@bridge-ds/mcp 0.2.0 → 0.3.1

package/dist/{chunk-6JO2AG6X.js → chunk-I3TL76GK.js}

@@ -1,11 +1,14 @@
 import {
   CONFIG_FILE,
   DEFAULT_PROTECTED_BRANCHES,
+  DEFAULT_RIGHTS,
   LayeredTokenSet,
   ProtectedBranchError,
   RISK_LABELS,
+  TeamDirectory,
   __export,
   aliasOf,
+  approverEntries,
   assertSafeBranch,
   baseBranchOf,
   branchExists,
@@ -21,10 +24,12 @@ import {
   contrastPair,
   currentBranch,
   diffLayered,
+  entryLabel,
+  expandOwners,
+  findPreviewComment,
   git,
   globToRegExp,
   hexToRgba,
-  installCommand,
   isGitRepo,
   layeredImpact,
   layeredParityIssues,
@@ -33,19 +38,23 @@ import {
   originRepo,
   parseContrastChecks,
   previewLinks,
+  previewsSettled,
   protectedBranchesOf,
+  readPreviewComment,
   renderedColor,
+  resolveBranchPreviews,
   rgbaToDtcg,
   rgbaToHex,
   runLayeredContrast,
   selectTokenFiles,
+  shipPolicy,
   showFile,
-  snapshotUrl,
-  tarballUrl,
   toConfigJson,
   tokensPath,
-  validateLayered
-} from "./chunk-FJL6UTZG.js";
+  unreadableTeams,
+  validateLayered,
+  whoCanShipSentence
+} from "./chunk-X455XY4E.js";
 
 // src/lib.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -704,15 +713,67 @@ function applyTokenEdits(base, edits) {
 
 // ../core/src/github-client.ts
 var GitHubError = class extends Error {
-  constructor(status, message, detail) {
+  constructor(status, message, detail, info = {}) {
     super(message);
     this.status = status;
     this.detail = detail;
     this.name = "GitHubError";
+    this.auth = info.auth;
+    this.permission = info.permission;
   }
   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;
 };
+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 first = acceptedHeader.split(";")[0].split(",").map((p2) => p2.trim().split("=")[0].trim()).filter((p2) => p2 && p2 !== "metadata");
+    if (first.length) return first[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 {};
+}
 var DEFAULT_RETRY = { attempts: 3, baseDelayMs: 600, sleep: (ms) => new Promise((r) => setTimeout(r, ms)) };
 var isTransient = (status, detail) => status === 0 || status >= 500 || status === 429 || status === 403 && /secondary rate limit/i.test(detail);
 var API = "https://api.github.com";
@@ -774,7 +835,7 @@ var GitHubClient = class _GitHubClient {
     }
   }
   assertToken(what) {
-    if (!this.token) throw new GitHubError(401, `${what} needs a GitHub token (contents and pull requests, read and write, on this repository only). Without one Bridge is read-only.`);
+    if (!this.token) throw new GitHubError(401, `${what} needs a GitHub token (contents and pull requests, read and write, on this repository only). Without one Bridge is read-only.`, "no-token");
   }
   get repoPath() {
     return `/repos/${this.owner}/${this.name}`;
@@ -823,7 +884,12 @@ var GitHubClient = class _GitHubClient {
           detail
         );
       }
-      throw new GitHubError(res.status, friendlyMessage(res.status, detail), detail);
+      const info = classifyAuth(res.status, detail, {
+        path,
+        acceptedPermissions: res.headers?.get("x-accepted-github-permissions"),
+        withToken: Boolean(this.token)
+      });
+      throw new GitHubError(res.status, friendlyMessage(res.status, detail, info), detail, info);
     }
     return await res.json();
   }
@@ -973,6 +1039,25 @@ var GitHubClient = class _GitHubClient {
       throw new GitHubError(422, `GitHub refused to mark #${n} ready for review${detail ? `: ${detail}` : "."} Use "Ready for review" on GitHub instead.`, detail);
     }
   }
+  /**
+   * Turns an open pull request back into a draft: the GraphQL mutation convertPullRequestToDraft (REST cannot set
+   * `draft` either), same token. No-op when it is already a draft.
+   */
+  async convertToDraft(n) {
+    this.assertToken("Turning a pull request back into a draft");
+    const pr = await this.request("GET", `${this.repoPath}/pulls/${n}`);
+    if (pr.draft === true) return;
+    if (pr.state && pr.state !== "open") throw new GitHubError(422, `Pull request #${n} is ${pr.state}: only an open one can go back to draft.`);
+    if (!pr.node_id) throw new GitHubError(422, `Pull request #${n} has no node id: convert it to draft on GitHub.`);
+    const r = await this.request("POST", "/graphql", {
+      query: "mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { number isDraft } } }",
+      variables: { id: pr.node_id }
+    });
+    if (r?.errors?.length) {
+      const detail = r.errors.map((e) => e.message).filter(Boolean).join(" ");
+      throw new GitHubError(422, `GitHub refused to turn #${n} back into a draft${detail ? `: ${detail}` : "."} Use "Convert to draft" on GitHub instead.`, detail);
+    }
+  }
   async createPullRequest(input) {
     this.assertWritableBranch(input.head, input.base);
     const r = await this.request(
@@ -1002,6 +1087,11 @@ var GitHubClient = class _GitHubClient {
   async addComment(issueNumber, body) {
     await this.request("POST", `${this.repoPath}/issues/${issueNumber}/comments`, { body });
   }
+  /** Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early). */
+  async listIssueComments(issueNumber) {
+    const r = await this.request("GET", `${this.repoPath}/issues/${issueNumber}/comments?per_page=100`);
+    return r.map((c) => ({ id: c.id, body: c.body ?? "", author: c.user?.login ?? "unknown", updatedAt: c.updated_at }));
+  }
   // --- Issues (component change requests) ---------------------------------------------------
   async createIssue(input) {
     const r = await this.request("POST", `${this.repoPath}/issues`, {
@@ -1022,6 +1112,67 @@ var GitHubClient = class _GitHubClient {
   async getIssue(n) {
     return toIssue(await this.request("GET", `${this.repoPath}/issues/${n}`));
   }
+  /** Edits an issue: its body, or closes it with a reason ("not_planned" for a declined request). */
+  async updateIssue(n, patch) {
+    this.assertToken("Editing an issue");
+    return toIssue(await this.request("PATCH", `${this.repoPath}/issues/${n}`, patch));
+  }
+  /** Adds people to an issue's assignees (GitHub ignores logins that cannot be assigned: the result says who is). */
+  async addAssignees(n, logins) {
+    this.assertToken("Assigning an issue");
+    const r = await this.request("POST", `${this.repoPath}/issues/${n}/assignees`, { assignees: logins });
+    return (r.assignees ?? []).map((a) => a.login);
+  }
+  /** People with at least `permission` on the repository (reading the list needs push access). First 100. */
+  async listCollaborators(permission = "push") {
+    const r = await this.request("GET", `${this.repoPath}/collaborators?permission=${permission}&per_page=100`);
+    return r.map((c) => ({ login: c.login, avatarUrl: c.avatar_url ?? "" }));
+  }
+  /** Whether a token is sent with each request (TeamReader). */
+  get hasToken() {
+    return Boolean(this.token);
+  }
+  /** Every page of a list endpoint (per_page 100), up to `maxPages`. */
+  async paginate(path, maxPages = 20) {
+    const out = [];
+    const sep2 = path.includes("?") ? "&" : "?";
+    for (let page = 1; page <= maxPages; page++) {
+      const r = await this.request("GET", `${path}${sep2}per_page=100&page=${page}`);
+      out.push(...r);
+      if (r.length < 100) break;
+    }
+    return out;
+  }
+  /** Every member login of an organization team (needs read:org, or Members: Read on a fine-grained token). */
+  async listTeamMembers(org, slug2) {
+    const r = await this.paginate(`/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(slug2)}/members`);
+    return r.map((m) => m.login);
+  }
+  /** A user's membership of a team: "active", "pending", or null when GitHub says they are not a member (404). */
+  async getTeamMembership(org, slug2, login) {
+    try {
+      const r = await this.request("GET", `/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(slug2)}/memberships/${encodeURIComponent(login)}`);
+      return r.state === "active" ? "active" : "pending";
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /** "User" or "Organization" for a login, null when GitHub does not know it. */
+  async getAccountType(login) {
+    try {
+      const r = await this.request("GET", `/users/${encodeURIComponent(login)}`);
+      return r.type === "Organization" ? "Organization" : r.type === "User" ? "User" : null;
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /** The organization's teams this token can see. */
+  async listOrgTeams(org) {
+    const r = await this.paginate(`/orgs/${encodeURIComponent(org)}/teams`);
+    return r.map((t) => ({ slug: t.slug, name: t.name }));
+  }
   /** Create or update a binary file (base64 content) on a branch, e.g. a Figma export attached to a request. */
   async putBase64File(input) {
     this.assertWritableBranch(input.branch);
@@ -1157,6 +1308,27 @@ var GitHubClient = class _GitHubClient {
     const pending = checks.some((c) => c.status !== "completed");
     return { state: !checks.length ? "none" : failing ? "failure" : pending ? "pending" : "success", checks };
   }
+  /** Commit statuses of a commit, newest first (Vercel reports each project as "Vercel – <project>"). */
+  async listCommitStatuses(sha) {
+    const r = await this.request("GET", `${this.repoPath}/commits/${encodeRef(sha)}/statuses?per_page=100`);
+    return r.map((s) => ({ context: s.context, state: s.state, target_url: s.target_url ?? null, description: s.description ?? null }));
+  }
+  /**
+   * GitHub deployments of a commit with their latest status (environment "Preview – <project>", environment_url the
+   * preview). Latest per environment only, so it costs one read plus one per environment.
+   */
+  async listDeployments(sha) {
+    const list = await this.request("GET", `${this.repoPath}/deployments?sha=${encodeURIComponent(sha)}&per_page=30`);
+    const latest = /* @__PURE__ */ new Map();
+    for (const d of list) if (!latest.has(d.environment)) latest.set(d.environment, d);
+    return Promise.all(
+      [...latest.values()].map(async (d) => {
+        const st = await this.request("GET", `${this.repoPath}/deployments/${d.id}/statuses?per_page=1`).catch(() => []);
+        const s = st[0];
+        return { id: d.id, environment: d.environment, state: s?.state ?? null, environmentUrl: s?.environment_url || null };
+      })
+    );
+  }
   async getPullRequest(n) {
     const r = await this.request("GET", `${this.repoPath}/pulls/${n}`);
     return { ...toSummary(r), body: r.body ?? "", mergeable: r.mergeable ?? null };
@@ -1183,7 +1355,44 @@ var GitHubClient = class _GitHubClient {
       "GET",
       `${this.repoPath}/commits/${encodeRef(ref)}/check-runs`
     );
-    return r.check_runs.map((c) => ({ id: c.id, name: c.name, status: c.status, conclusion: c.conclusion, url: c.html_url }));
+    return r.check_runs.map((c) => ({ id: c.id, name: c.name, status: c.status, conclusion: c.conclusion, url: c.html_url, ...c.app?.slug ? { app: c.app.slug } : {} }));
+  }
+  /** Rulesets that apply to the repository, without their rules (GET /rulesets; read access is enough). */
+  async listRulesets() {
+    const r = await this.request("GET", `${this.repoPath}/rulesets?includes_parents=true&per_page=100`);
+    return r.map(withRulesetUrl);
+  }
+  /** One ruleset with its rules. */
+  async getRuleset(id) {
+    return withRulesetUrl(await this.request("GET", `${this.repoPath}/rulesets/${id}`));
+  }
+  /** Creates a repository ruleset. Needs admin on the repo (fine-grained token: Administration read and write). */
+  async createRuleset(payload) {
+    this.assertToken("Protecting the library");
+    return withRulesetUrl(await this.request("POST", `${this.repoPath}/rulesets`, payload));
+  }
+  /** Replaces a repository ruleset (same permissions as createRuleset). */
+  async updateRuleset(id, payload) {
+    this.assertToken("Protecting the library");
+    return withRulesetUrl(await this.request("PUT", `${this.repoPath}/rulesets/${id}`, payload));
+  }
+  /**
+   * Classic branch protection of `branch`: the settings, null when the branch has none (404), undefined when this
+   * token cannot read them (403: the endpoint needs admin). On a 403 the public branch summary still tells
+   * whether the branch is protected at all: `protected: false` means there is nothing to read, so null.
+   */
+  async getBranchProtection(branch) {
+    try {
+      return await this.request("GET", `${this.repoPath}/branches/${encodeRef(branch)}/protection`);
+    } catch (err) {
+      if (!(err instanceof GitHubError)) throw err;
+      if (err.status === 404) return null;
+      if (err.status === 403 || err.status === 401) {
+        const b = await this.request("GET", `${this.repoPath}/branches/${encodeRef(branch)}`).catch(() => void 0);
+        return b?.protected === false ? null : void 0;
+      }
+      throw err;
+    }
   }
   /** Create a check run (needs a GitHub App token; personal tokens are refused by GitHub). */
   async createCheckRun(input) {
@@ -1225,7 +1434,9 @@ function toSummary(r) {
     ...typeof r.body === "string" ? { body: r.body } : {}
   };
 }
-function friendlyMessage(status, detail) {
+function friendlyMessage(status, detail, info = {}) {
+  if (info.auth === "rejected") return TOKEN_REJECTED_MESSAGE;
+  if (info.auth === "missing-permission") return missingPermissionMessage(info.permission);
   switch (status) {
     case 401:
       return "GitHub rejected the token. It may be expired or mistyped: create a new one and save it in Settings.";
@@ -1245,6 +1456,10 @@ function friendlyMessage(status, detail) {
       return `GitHub error ${status}${detail ? `: ${detail}` : ""}`;
   }
 }
+function withRulesetUrl(r) {
+  const href = r._links?.html?.href;
+  return href && !r.html_url ? { ...r, html_url: href } : r;
+}
 function toIssue(r) {
   return {
     number: r.number,
@@ -1850,6 +2065,38 @@ async function loadGitHubHistory(client2, config, opts = {}) {
   return buildReport({ source: "github", label: `${client2.fullName}@${ref}`, ref, entries, releases, ...currentVersion ? { currentVersion } : {}, truncated: listed >= limit });
 }
 
+// ../core/src/previews-github.ts
+async function branchPreviewUrls(gh, ref, config, opts = {}) {
+  const apps = config?.previews?.apps ?? {};
+  if (!Object.values(apps).some(Boolean)) return [];
+  let pr;
+  let branch = opts.branch;
+  let sha = opts.sha;
+  if (typeof ref === "number") {
+    pr = ref;
+    if (!branch || !sha) {
+      const p = await gh.getPullRequest(ref);
+      branch ??= p.headRef;
+      sha ??= p.headSha;
+    }
+  } else {
+    sha = ref;
+    if (!branch || !opts.comments) {
+      const open = (await gh.listPullRequestsForCommit(ref).catch(() => [])).find((p) => p.state === "open");
+      if (open) {
+        pr = open.number;
+        branch ??= open.headRef;
+      }
+    }
+  }
+  const [comments, statuses, deployments] = await Promise.all([
+    opts.comments ? Promise.resolve(opts.comments) : pr !== void 0 ? gh.listIssueComments(pr).catch(() => []) : Promise.resolve([]),
+    sha ? gh.listCommitStatuses(sha).catch(() => []) : Promise.resolve([]),
+    sha ? gh.listDeployments(sha).catch(() => []) : Promise.resolve([])
+  ]);
+  return resolveBranchPreviews(apps, { branch: branch ?? "", ...pr !== void 0 ? { pr } : {}, ...sha ? { sha } : {} }, { comments, statuses, deployments });
+}
+
 // ../core/src/ramps.js
 var STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
 var LIGHTNESS = { 50: 0.975, 100: 0.952, 200: 0.912, 300: 0.85, 400: 0.735, 500: 0.63, 600: 0.53, 700: 0.445, 800: 0.36, 900: 0.27, 950: 0.205 };
@@ -2378,6 +2625,7 @@ function composeNewBrandBody(plan, opts) {
 }
 
 // ../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) {
@@ -2430,6 +2678,7 @@ function prefillDocs(input) {
     contentGuidelines: existing?.contentGuidelines ?? [],
     anatomy,
     ...existing?.draftedBy ? { draftedBy: existing.draftedBy } : {},
+    ...existing?.draftedSections?.length ? { draftedSections: existing.draftedSections } : {},
     ...existing?.needsReview !== void 0 ? { needsReview: existing.needsReview } : {}
   };
   return {
@@ -2444,7 +2693,17 @@ function prefillDocs(input) {
     draft
   };
 }
-function docsPrompt(prefill, conventions = {}) {
+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):
@@ -2459,15 +2718,33 @@ ${prefill.propsTable}` : "Props: none of its own.",
   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 shape = 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 [
-    `Write the missing prose of ${prefill.component}.docs.json for the Bridge design system.`,
+    ...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.',
-    `- 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.",
+    ...shape,
     "",
     "Facts computed from the code:",
     facts.join("\n\n"),
@@ -2476,11 +2753,179 @@ ${text.trim()}
 ${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)}
+`;
+}
+
+// ../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 capital = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+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,;:(]+$/, "");
+}
+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 fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+  const body = fenced ? fenced[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";
@@ -2535,16 +2980,6 @@ function explorationNote(e) {
     ""
   ].join("\n");
 }
-function explorationInstall(input) {
-  const packages = input.packages.map((name) => ({ name, url: snapshotUrl(input.owner, input.repo, name, input.pr) }));
-  const named = (list) => installCommand(list.map((p) => `${p.name}@${p.url}`));
-  const out = { command: named(packages), packages };
-  if (input.sha) {
-    const tarballs = input.packages.map((name) => ({ name, url: tarballUrl(input.owner, input.repo, input.pr, name, input.sha) }));
-    out.fallback = { command: named(tarballs), packages: tarballs, release: `https://github.com/${input.owner}/${input.repo}/releases/tag/preview-pr-${input.pr}` };
-  }
-  return out;
-}
 function explorationPrTitle(e) {
   const n = e.name.trim().replace(/\.$/, "");
   return `Exploration: ${n.charAt(0).toLowerCase()}${n.slice(1)}`;
@@ -2570,20 +3005,9 @@ function explorationPrBody(e, ctx) {
     "### Try it in a product staging branch",
     ""
   ];
-  if (ctx.pr) {
-    const install = explorationInstall({ owner: ctx.owner, repo: ctx.repo, pr: ctx.pr, packages: ctx.packages });
-    lines.push(
-      "In the product repo, on a branch that deploys to staging (production keeps the released version):",
-      "",
-      "```sh",
-      install.command,
-      "```",
-      "",
-      `The snapshots follow the latest commit of this pull request. The "Try this DS branch in your product" comment lists the exact commit, and the tarball URLs from the [\`preview-pr-${ctx.pr}\` prerelease](https://github.com/${ctx.owner}/${ctx.repo}/releases/tag/preview-pr-${ctx.pr}) when pkg.pr.new is not set up.`
-    );
-  } else {
-    lines.push('The install command appears here and in the "Try this DS branch in your product" comment once the first snapshot is published.');
-  }
+  lines.push(
+    'In the product repo, on a branch that deploys to staging (production keeps the released version), install the snapshot with the command in the "Try this exploration in your product" comment below. It appears a few minutes after each push and always matches the latest commit.'
+  );
   lines.push("", "### Previews", "");
   const links = previewLinks(ctx.apps, { branch, ...ctx.pr ? { pr: ctx.pr } : {} });
   if (links.length) lines.push("| App | Preview |", "| --- | --- |", ...links.map((l) => `| ${l.label} | ${l.url} |`));
@@ -2595,7 +3019,7 @@ function explorationPrBody(e, ctx) {
     `- **Promote:** in Bridge Studio (Changes, Explorations, Promote to review) or \`bridge explore promote ${slug2}\`. Bridge marks the pull request ready for review, removes the \`${EXPLORATION_LABEL}\` label and the exploration note, and adds the tier labels. Then it goes through the usual review.`,
     "- **Close:** close this pull request. The branch stays for reference; the preview prerelease is removed.",
     "",
-    `<!-- ${MARK} ${JSON.stringify({ name: e.name.trim(), purpose: e.purpose.trim(), slug: slug2, ...e.useCase ? { useCase: e.useCase } : {}, ...experimental.length ? { experimental } : {}, ...e.author ? { author: e.author } : {}, ...e.startedAt ? { startedAt: e.startedAt } : {} }).replace(/-->/g, "--\\u003e")} -->`
+    `<!-- ${MARK} ${JSON.stringify({ name: e.name.trim(), purpose: e.purpose.trim(), slug: slug2, ...e.useCase ? { useCase: e.useCase } : {}, ...experimental.length ? { experimental } : {}, ...e.author ? { author: e.author } : {}, ...e.startedAt ? { startedAt: e.startedAt } : {}, ...e.source ? { source: e.source } : {}, ...e.agent ? { agent: e.agent } : {} }).replace(/-->/g, "--\\u003e")} -->`
   );
   return lines.join("\n");
 }
@@ -2652,6 +3076,13 @@ function promotionPlan(input) {
     markReady: true
   };
 }
+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.`,
@@ -2664,7 +3095,8 @@ function explorationRules(branch) {
 var REQUEST_KINDS = [
   { value: "new-component", label: "New component", hint: "A component the design system does not have yet." },
   { value: "new-variant", label: "New variant", hint: "A size, tone or state the component does not have yet." },
-  { value: "prop-change", label: "Prop change", hint: "Add, rename or change a prop or its default." },
+  { value: "prop-change", label: "Option change (prop)", hint: "Add, rename or change an option (a prop in code) or its default." },
+  { value: "structure", label: "Structure change", hint: "A part was added, removed or moved." },
   { value: "visual", label: "Visual change", hint: "Spacing, radius, layout or icon placement." },
   { value: "token-binding", label: "Token change", hint: "The component should paint with another token." },
   { value: "bug", label: "Bug", hint: "It looks or behaves differently from the guidance." },
@@ -2686,6 +3118,7 @@ function composeRequestIssue(r, opts = {}) {
     "",
     r.summary.trim(),
     "",
+    ...r.line?.trim() ? [`**What changes:** ${r.line.trim()}`, ""] : [],
     ...rows.length ? [...rows, ""] : [],
     ...r.images?.length ? [...r.images.map((u, i) => `![${r.component} design ${i + 1}](${u})`), ""] : [],
     ...figma ? [`**Design:** ${figma}`, ""] : [],
@@ -2733,6 +3166,7 @@ function requestBrief(r, ctx) {
     `Component: ${r.component}`,
     `Kind: ${kindLabel(r.kind)}`,
     `Request: ${r.title}`,
+    ...r.line?.trim() ? [`What changes: ${r.line.trim()}`] : [],
     "",
     r.summary.trim(),
     "",
@@ -2750,11 +3184,6 @@ function requestBrief(r, ctx) {
 var cell2 = (s) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
 var sourceLabel = (s) => s === "figma" ? "Figma" : s === "studio" ? "Bridge Studio" : s === "cli" ? "the CLI" : "Claude (MCP)";
 
-// ../core/src/change-drafts.ts
-function cleanDraftText(text) {
-  return text.replace(/\s*\u2014\s*/g, ", ").replace(/,\s*,/g, ",").replace(/^,\s*/, "").replace(/[ \t]+/g, " ").trim();
-}
-
 // ../core/src/draft-exchange.ts
 var DRAFT_EXCHANGE_VERSION = 1;
 var DRAFTS_DIR = ".bridge/drafts";
@@ -2768,12 +3197,16 @@ var DRAFT_VOICE_RULES = [
   "Use only facts from the changes, the images and the designer's notes. Never invent numbers, names, usage or reasons. If the reason is unknown, say what changes and leave the reason out.",
   "Keep the designer's intent from their notes.",
   "Never use an em dash: use a colon, a comma or parentheses. No exclamation marks, no emoji, no Markdown.",
-  "A request title never repeats the component name: the issue title already starts with it."
+  "A request title never repeats the component name: the issue title already starts with it.",
+  `For each change line, write one short sentence (at most ${DRAFT_LINE_MAX} characters, no trailing period) of what changed for developers, read from the before and after images: the part, the variant and the values when you can see them, for example "Icon added after the label in primary sm: Pencil, 16px". Never guess a value you cannot read.`,
+  `For each change line, also write the title of the request it becomes: short, sentence case, starts with a verb, at most ${DRAFT_TITLE_MAX} characters, no trailing period, never the component name, for example "Add an icon after the label".`
 ];
 var DRAFT_OUTPUT_CONTRACT = [
-  `Call bridge_write_drafts once per session with {"sessionId": "...", "results": [{"id": "<item id>", "title": "...", "summary": "..."}]}, one result per item.`,
+  `Call bridge_write_drafts once per session with {"sessionId": "...", "results": [{"id": "<item id>", "title": "...", "summary": "...", "lines": [{"id": "<line id>", "line": "...", "title": "..."}]}]}, one result per item.`,
   `title: one line, at most ${DRAFT_TITLE_MAX} characters, no trailing period.`,
   `summary: at most ${DRAFT_SUMMARY_SENTENCES} sentences, plain text.`,
+  `lines: one per change line the item lists (its "lines"), by line id: line is one sentence, at most ${DRAFT_LINE_MAX} characters, no trailing period; title is the request title for that component change, at most ${DRAFT_TITLE_MAX} characters, no trailing period. Leave lines out when the item lists none.`,
+  `Docs items (scope "docs", from Bridge Studio): follow the item's prompt and send {"id": "<item id>", "docs": {<only the sections it asks for>}} for a sections task (a section to check goes in only when something in it is no longer true for the code: leave accurate ones out, {"docs": {}} when all are), or {"id": "<item id>", "replacement": "..."} for a selection task. No title or summary. The designer reviews them on the Library page.`,
   "The designer reviews the text in Figma before anything is sent."
 ];
 var SESSION_RE = /^[a-z0-9-]{6,64}$/;
@@ -2793,7 +3226,7 @@ function validatePendingDrafts(x) {
   if (!isDraftSessionId(p.sessionId)) out.push("The session id is missing or invalid.");
   if (!str(p.createdAt) || Number.isNaN(Date.parse(p.createdAt))) out.push("createdAt must be an ISO date.");
   if (p.status !== "pending" && p.status !== "drafted") out.push('status must be "pending" or "drafted".');
-  if (p.source !== "figma") out.push('source must be "figma".');
+  if (p.source !== "figma" && p.source !== "studio") out.push('source must be "figma" or "studio".');
   if (!Array.isArray(p.items) || !p.items.length) out.push("A draft session needs at least one item.");
   const ids = /* @__PURE__ */ new Set();
   for (const [n, i] of (Array.isArray(p.items) ? p.items : []).entries()) {
@@ -2805,7 +3238,12 @@ function validatePendingDrafts(x) {
     if (!str(i.id) || !i.id) out.push(`${at} has no id.`);
     else if (ids.has(i.id)) out.push(`${at} repeats the id "${i.id}".`);
     else ids.add(i.id);
-    if (i.scope !== "request" && i.scope !== "push") out.push(`${at}: scope must be "request" or "push".`);
+    if (i.scope !== "request" && i.scope !== "push" && i.scope !== "docs") out.push(`${at}: scope must be "request", "push" or "docs".`);
+    if (i.scope === "docs") {
+      const d = i.docs;
+      if (!d || typeof d !== "object" || !str(d.slug) || !d.slug || !str(d.prompt) || !d.prompt || !optStr(d.path)) out.push(`${at}: a docs item needs docs {slug, task, prompt}.`);
+      else out.push(...validateDocsTask(d.task).map((m) => `${at}: ${m}`));
+    } else if (i.docs !== void 0) out.push(`${at}: only a docs item has docs.`);
     if (!optStr(i.component)) out.push(`${at}: component must be text.`);
     if (i.kind !== void 0 && !KINDS.has(i.kind)) out.push(`${at}: unknown kind "${String(i.kind)}".`);
     if (!Array.isArray(i.changes) || i.changes.some((c) => !c || !str(c.field) || !optStr(c.before) || !optStr(c.after))) out.push(`${at}: changes must be a list of {field, before, after}.`);
@@ -2813,10 +3251,17 @@ function validatePendingDrafts(x) {
     if (i.variables !== void 0 && i.scope !== "push") out.push(`${at}: only a push item has variables.`);
     if (i.images !== void 0 && (!Array.isArray(i.images) || i.images.some((m) => !m || m.label !== "before" && m.label !== "after" || !str(m.url)))) out.push(`${at}: images must be a list of {label: before or after, url}.`);
     if (!i.draft || !str(i.draft.title) || !str(i.draft.summary)) out.push(`${at}: draft must hold a title and a summary.`);
+    if (i.lines !== void 0 && (!Array.isArray(i.lines) || i.lines.some((l) => !l || !str(l.id) || !l.id || !str(l.line) || !optStr(l.title) || !Array.isArray(l.changes)))) out.push(`${at}: lines must be a list of {id, changes, line, title}.`);
   }
   if (p.results !== void 0) {
     if (!Array.isArray(p.results)) out.push("results must be a list.");
-    else for (const r of p.results) if (!r || !str(r.id) || !str(r.title) || !str(r.summary)) out.push("Each result needs an id, a title and a summary.");
+    else
+      for (const r of p.results) {
+        if (!r || !str(r.id) || !str(r.title) || !str(r.summary)) out.push("Each result needs an id, a title and a summary.");
+        else if (r.docs !== void 0 && (!r.docs || typeof r.docs !== "object" || Array.isArray(r.docs))) out.push("Result docs must be an object of sections.");
+        else if (!optStr(r.replacement)) out.push("A result replacement must be text.");
+        else if (r.lines !== void 0 && (!Array.isArray(r.lines) || r.lines.some((l) => !l || !str(l.id) || !str(l.line) || !optStr(l.title)))) out.push("Result lines must be a list of {id, line, title}.");
+      }
   }
   return out;
 }
@@ -2853,19 +3298,69 @@ function sanitizeDraftText(raw) {
   const summary2 = typeof raw.summary === "string" ? sentences(cleanDraftText(raw.summary)) : "";
   return { title, summary: summary2 };
 }
+function sanitizeDocsResult(item, r) {
+  const task = item.docs.task;
+  if (task.kind === "selection") {
+    const raw = r.replacement ?? (r.docs && typeof r.docs === "object" ? r.docs[task.key] : void 0);
+    const replacement = sanitizeDocsReplacement(raw);
+    if (!replacement) throw new Error(`Item "${item.id}" asks to rewrite a passage of ${task.key}: send {"id": "${item.id}", "replacement": "..."}.`);
+    return { replacement };
+  }
+  try {
+    const { sections: sections2, checked } = docsSectionsAnswer(task, r.docs ?? {});
+    return { docs: sections2, checked };
+  } catch {
+    throw new Error(`Item "${item.id}" asks for the sections ${docsTaskKeys(task).join(", ")}: send {"id": "${item.id}", "docs": {${task.keys.map((k) => `"${k}": ...`).join(", ")}}} in the shapes of its prompt.`);
+  }
+}
+function sanitizeResultLines(item, raw) {
+  if (raw === void 0 || raw === null) return [];
+  if (!Array.isArray(raw)) throw new Error(`lines for "${item.id}" must be a list of {"id", "line", "title"}.`);
+  const known = new Set((item.lines ?? []).map((l) => l.id));
+  const out = /* @__PURE__ */ new Map();
+  for (const l of raw) {
+    const id = typeof l?.id === "string" ? l.id : "";
+    if (!known.has(id)) throw new Error(`Item "${item.id}" has no change line "${id}".${known.size ? ` Use the line ids from bridge_pending_drafts: ${[...known].join(", ")}.` : " It lists no lines: leave lines out."}`);
+    const line = sanitizeDraftLine(l.line);
+    const title = sanitizeDraftTitle(l.title);
+    if (line || title) out.set(id, { id, line, ...title ? { title } : {} });
+  }
+  return [...out.values()];
+}
+function sanitizeDraftTitle(raw) {
+  if (typeof raw !== "string") return "";
+  const t = clip(cleanDraftText(raw.replace(/[\r\n]+/g, " ")), DRAFT_TITLE_MAX);
+  return t.charAt(0).toUpperCase() + t.slice(1);
+}
 function mergeDraftResults(p, results, at = /* @__PURE__ */ new Date()) {
   const ids = new Set(p.items.map((i) => i.id));
   const next = new Map((p.results ?? []).map((r) => [r.id, r]));
   for (const r of results) {
     if (!ids.has(r.id)) throw new Error(`Session ${p.sessionId} has no item "${r.id}". Use the ids from bridge_pending_drafts: ${[...ids].join(", ")}.`);
+    const item = p.items.find((i) => i.id === r.id);
+    if (item.scope === "docs") {
+      next.set(r.id, { id: r.id, title: "", summary: "", ...sanitizeDocsResult(item, r), by: "claude", at: at.toISOString() });
+      continue;
+    }
     const clean = sanitizeDraftText(r);
-    if (!clean.title && !clean.summary) throw new Error(`The result for "${r.id}" has no title and no summary.`);
-    next.set(r.id, { id: r.id, title: clean.title, summary: clean.summary, by: "claude", at: at.toISOString() });
+    const lines = sanitizeResultLines(item, r.lines);
+    if (!clean.title && !clean.summary && !lines.length) throw new Error(`The result for "${r.id}" has no title and no summary, and no line.`);
+    next.set(r.id, { id: r.id, title: clean.title, summary: clean.summary, ...lines.length ? { lines } : {}, by: "claude", at: at.toISOString() });
   }
   const merged = p.items.map((i) => next.get(i.id)).filter((r) => !!r);
   return { ...p, results: merged, status: merged.length === p.items.length ? "drafted" : "pending" };
 }
 function draftItemBrief(i) {
+  if (i.scope === "docs" && i.docs) {
+    const t = i.docs.task;
+    const check = t.kind === "sections" ? (t.check ?? []).filter((k) => t.keys.includes(k)) : [];
+    const write = t.kind === "sections" ? t.keys.filter((k) => !check.includes(k)) : [];
+    const what = t.kind === "selection" ? `rewrite one passage of the ${t.key} section (${t.mode}), answer with "replacement"` : [
+      write.length ? `${t.rewrite ? "rewrite" : "write"} the sections ${write.join(", ")}` : "",
+      check.length ? `check the sections ${check.join(", ")} against the code and return one only when something in it is no longer true (leave accurate ones out)` : ""
+    ].filter(Boolean).join("; ") + ', answer with "docs"';
+    return [`Item ${i.id}: component docs${i.component ? ` of ${i.component}` : ""} from Bridge Studio (${i.docs.path ?? i.docs.slug}): ${what}.`, "", i.docs.prompt].join("\n");
+  }
   const kind = i.kind ? REQUEST_KINDS.find((k) => k.value === i.kind)?.label : void 0;
   const cell3 = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
   const lines = [`Item ${i.id}: ${i.scope === "request" ? "a component change request (a GitHub issue developers implement)" : "the description of a pull request with design token (variable) edits from Figma"}.`];
@@ -2874,10 +3369,17 @@ function draftItemBrief(i) {
   if (i.components?.length) lines.push(`Components with a change request: ${i.components.join(", ")}`);
   if (i.changes.length) lines.push("", "| What | Now | In Figma |", "| --- | --- | --- |", ...i.changes.map((c) => `| ${cell3(c.field)} | ${cell3(c.before) || "none"} | ${cell3(c.after) || "removed"} |`));
   if (i.variables?.length) lines.push("", "| Token | Now | In Figma |", "| --- | --- | --- |", ...i.variables.map((v) => `| ${cell3(v.path)} | ${cell3(v.before) || "none"} | ${cell3(v.after) || "removed"} |`));
-  if (!i.changes.length && !i.variables?.length) lines.push("", "No change detected: rely on the notes and the images.");
+  if (!i.changes.length && !i.variables?.length && !i.lines?.length) lines.push("", "No change detected: rely on the notes and the images.");
   if (i.draft.title || i.draft.summary) lines.push("", "Starting draft, written from the changes only:", `Title: ${i.draft.title}`, `Summary: ${i.draft.summary}`);
   if (i.notes?.trim()) lines.push("", "The designer's notes (keep their intent):", i.notes.trim());
-  if (i.images?.length) lines.push("", `Images: ${i.images.map((m) => `${m.label} ${m.url}`).join(", ")}`);
+  if (i.lines?.length) {
+    lines.push("", `Change lines to write (one sentence each, at most ${DRAFT_LINE_MAX} characters, from the before and after images), each with the title of its request (at most ${DRAFT_TITLE_MAX} characters):`);
+    for (const l of i.lines) {
+      lines.push(`- Line ${l.id}${l.component ? `, ${l.component}` : ""}${l.kind ? ` (${REQUEST_KINDS.find((k) => k.value === l.kind)?.label ?? l.kind})` : ""}. Starting line: ${l.line || "(none)"}${l.title ? `. Starting title: ${l.title}` : ""}`);
+      for (const c of l.changes) lines.push(`  - ${c.field}: ${c.before || "none"} -> ${c.after || "removed"}`);
+    }
+  }
+  if (i.images?.length) lines.push("", `Images: ${i.images.map((m) => `${m.label}${m.line ? ` (line ${m.line})` : ""} ${m.url}`).join(", ")}`);
   return lines.join("\n");
 }
 var isConflict = (err) => err instanceof GitHubError ? err.status === 409 || err.status === 422 && /sha/i.test(`${err.detail ?? ""} ${err.message}`) : err?.status === 409;
@@ -2920,9 +3422,10 @@ function writeDraftResults(client2, sessionId, results, opts = {}) {
     message: `Bridge drafts: ${results.length === 1 ? "1 text" : `${results.length} texts`} drafted by Claude`
   });
 }
+var DRAFT_POLL_TIMEOUT_MS = 10 * 6e4;
 
 // ../core/src/explorations-github.ts
-function explorationSummary(p, owner, repo, s) {
+function explorationSummary(p, _owner, _repo, s) {
   const e = parseExplorationBody(p.body);
   const slug2 = p.headRef?.startsWith(EXPLORATION_PREFIX) ? p.headRef.slice(EXPLORATION_PREFIX.length) : e?.slug ?? explorationSlug(p.title);
   return {
@@ -2936,9 +3439,11 @@ function explorationSummary(p, owner, repo, s) {
     status: explorationStatus({ state: p.state, labels: p.labels, headRef: p.headRef, body: p.body }),
     draft: p.draft,
     author: e?.author ?? p.author,
+    ...e?.source ? { source: e.source } : {},
+    ...e?.agent ? { agent: e.agent } : {},
     updatedAt: p.updatedAt,
-    previews: previewLinks(s.apps, { branch: p.headRef, pr: p.number, sha: p.headSha }),
-    install: explorationInstall({ owner, repo, pr: p.number, packages: s.packages, sha: p.headSha })
+    headSha: p.headSha,
+    previews: previewLinks(s.apps, { branch: p.headRef, pr: p.number, sha: p.headSha })
   };
 }
 async function listExplorationsOnGitHub(gh, s, opts = {}) {
@@ -2964,7 +3469,7 @@ ${full.purpose.trim()}
 Exploration: never merged as is. Promote it to review or close it.`,
     files: [{ path: explorationNotePath(slug2), content: explorationNote(full) }]
   });
-  const ctx = { owner: gh.owner, repo: gh.name, packages: s.packages, apps: s.apps };
+  const ctx = { owner: gh.owner, repo: gh.name, packages: s.packages, apps: s.apps, ...s.requests?.length ? { requests: s.requests } : {} };
   const pr = await x.createPullRequest({ title: explorationPrTitle(full), head: branch, base: s.base, body: explorationPrBody(full, ctx), draft: true });
   await x.addLabels(pr.number, [EXPLORATION_LABEL]);
   await x.updatePullRequest(pr.number, { body: explorationPrBody(full, { ...ctx, pr: pr.number }) }).catch(() => void 0);
@@ -2974,10 +3479,16 @@ Exploration: never merged as is. Promote it to review or close it.`,
     pr: pr.number,
     url: pr.url,
     commit: commit.sha,
-    install: explorationInstall({ owner: gh.owner, repo: gh.name, pr: pr.number, packages: s.packages, sha: commit.sha }),
+    tryIt: { state: "building" },
     previews: previewLinks(s.apps, { branch, pr: pr.number, sha: commit.sha })
   };
 }
+async function explorationTestBuildOnGitHub(gh, e, config) {
+  const [comments, head] = await Promise.all([gh.listIssueComments(e.number), gh.getBranchSha(e.branch).catch(() => void 0)]);
+  const tryIt = explorationTryIt({ comment: findPreviewComment(comments)?.body, headSha: head });
+  const previews = await branchPreviewUrls(gh, e.number, config, { branch: e.branch, sha: head, comments }).catch(() => []);
+  return { tryIt, previews, settled: tryIt.state !== "building" && previewsSettled(previews) };
+}
 async function findExplorationOnGitHub(gh, ref) {
   if (typeof ref === "number" || /^#?\d+$/.test(String(ref))) {
     const p = await gh.getPullRequest(Number(String(ref).replace(/^#/, "")));
@@ -3001,6 +3512,7 @@ async function promoteExplorationOnGitHub(gh, ref, opts = {}) {
   const x = gh.withBranchPrefix(EXPLORATION_PREFIX);
   if (plan.removeFiles.length) {
     await x.commitToBranch({ branch: p.headRef, message: "chore(explore): promote to review, remove the exploration note", files: plan.removeFiles.map((path) => ({ path, content: null })) }).catch((e) => {
+      if (e instanceof GitHubError && e.auth === "rejected") throw e;
       out.warnings.push(`The exploration note stays on the branch (${e.message}). Delete ${plan.removeFiles.join(", ")} before merging.`);
     });
   }
@@ -4632,7 +5144,9 @@ async function detectConfig(files, read, extra = {}) {
       branchPrefix: "bridge/",
       labels: ["source: mcp"],
       guardrails: [guidelines, "CLAUDE.md", ".github/", governance, contrast, CONFIG_FILE].filter(Boolean),
-      owners: { design: [], tech: [] }
+      owners: { design: [], tech: [] },
+      // New configs start from the default roles: design owners approve design, tech owners approve tech and ship.
+      rights: DEFAULT_RIGHTS
     }
   });
 }
@@ -5187,6 +5701,7 @@ __export(ops_exports, {
   normalizeTokenPath: () => normalizeTokenPath,
   proposeTokenChange: () => proposeTokenChange,
   reviewPr: () => reviewPr,
+  reviewRoles: () => reviewRoles,
   scaffoldComponentOp: () => scaffoldComponentOp,
   searchTokens: () => searchTokens,
   validateTokens: () => validateTokens,
@@ -5324,6 +5839,7 @@ __export(explorations_exports, {
   closeExploration: () => closeExploration,
   explorationContext: () => explorationContext,
   explorationRules: () => explorationRules,
+  installOf: () => installOf,
   listExplorations: () => listExplorations,
   promoteExploration: () => promoteExploration,
   startExploration: () => startExploration,
@@ -5361,6 +5877,8 @@ async function startExploration(ctx, a) {
     ...a.useCase ? { useCase: a.useCase } : {},
     ...a.experimental?.length ? { experimental: a.experimental } : {},
     ...a.author ? { author: a.author } : {},
+    ...a.source ? { source: a.source } : {},
+    ...a.agent ? { agent: a.agent } : {},
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   const gh = await ctx.github().catch(() => null);
@@ -5377,7 +5895,16 @@ async function startExploration(ctx, a) {
   const work = `Work on it: \`git fetch origin && git switch ${branch}\`. Token edits: bridge_propose_token_change with "branch": "${branch}". Requests: bridge_create_request with "exploration": "${branch}", then bridge_get_request with "branch": "${branch}". It is never merged as is: promote it (\`bridge explore promote ${slug2}\`) or close it.`;
   if (gh && ctx.canWriteRemote) {
     const r = await startExplorationOnGitHub(gh, e, s);
-    return { status: "started", ...preview, pr: r.pr, url: r.url, commit: r.commit, install: r.install, previews: r.previews, next: work };
+    return {
+      status: "started",
+      ...preview,
+      pr: r.pr,
+      url: r.url,
+      commit: r.commit,
+      install: installOf(r.tryIt),
+      previews: r.previews,
+      next: `${work} The install command and the preview links appear on the pull request a few minutes after each push: \`bridge explore list\` reads them.`
+    };
   }
   if (ctx.mode === "local" && ctx.isGit) {
     if (await branchExists(ctx.root, branch)) throw new Error(`Branch ${branch} already exists here. Pick another name, or continue it with \`git switch ${branch}\`.`);
@@ -5404,6 +5931,11 @@ Exploration: never merged as is. Promote it to review or close it.`,
   }
   throw new Error("Starting an exploration needs GITHUB_TOKEN (contents and pull requests: write), or a local git repo. Without them Bridge is read-only. Use dryRun to preview it.");
 }
+function installOf(t) {
+  if (t.state === "ready") return { state: "ready", command: t.command, note: `Snapshot of ${t.sha7 ?? "the latest commit"}, ${t.source === "release" ? "tarballs from the preview prerelease" : t.source === "pkg.pr.new" ? "pkg.pr.new" : "from the preview comment"}. Install it in a product branch that deploys to staging.` };
+  if (t.state === "failed") return { state: "failed", command: null, note: "The test build did not finish for the latest commit. The Preview packages run on the pull request says why." };
+  return { state: "building", command: null, note: 'The test build is being prepared, a few minutes after each push. The command then appears in the "Try this exploration in your product" comment.' };
+}
 async function requestsByExploration(gh) {
   const out = /* @__PURE__ */ new Map();
   try {
@@ -5420,7 +5952,15 @@ async function listExplorations(ctx, a = {}) {
   const { config } = await ctx.config();
   const gh = await requireGitHub(ctx);
   const [list, linked] = await Promise.all([listExplorationsOnGitHub(gh, settingsOf(config), { state: a.state ?? "open" }), requestsByExploration(gh)]);
-  const explorations = list.map((x) => ({ ...x, requests: linked.get(x.branch) ?? [] }));
+  const explorations = await Promise.all(
+    list.map(async (x) => {
+      const requests = linked.get(x.branch) ?? [];
+      if (x.status !== "active") return { ...x, install: null, requests };
+      const t = await explorationTestBuildOnGitHub(gh, { number: x.number, branch: x.branch }, config).catch(() => null);
+      if (!t) return { ...x, install: installOf({ state: "building" }), requests };
+      return { ...x, previews: t.previews.map((p) => ({ app: p.app, label: p.label, url: p.url, state: p.state })), install: installOf(t.tryIt), requests };
+    })
+  );
   let localBranches = [];
   if (ctx.mode === "local" && ctx.isGit) {
     const refs = (await git(ctx.root, ["for-each-ref", "--format=%(refname:short)", `refs/heads/${EXPLORATION_PREFIX}`]).catch(() => "")).split("\n").filter(Boolean);
@@ -5962,6 +6502,7 @@ async function getReview(ctx, a) {
       approvals: [...latest.entries()].filter(([, s]) => s === "APPROVED").map(([u]) => u),
       changesRequested: [...latest.entries()].filter(([, s]) => s === "CHANGES_REQUESTED").map(([u]) => u)
     };
+    meta.roles = await reviewRoles(gh, config, meta.approvals);
   }
   const [before, after] = await Promise.all([setAt2(baseSrc, config), setAt2(headSrc, config)]);
   const changes = core.diff(before, after);
@@ -5989,6 +6530,25 @@ async function getReview(ctx, a) {
     impact: imp
   };
 }
+var sameLogin = (a, b) => a.trim().toLowerCase().replace(/^@/, "") === b.trim().toLowerCase().replace(/^@/, "");
+async function reviewRoles(gh, config, approvers) {
+  const { owners, rights } = config.governance;
+  const teams = await new TeamDirectory(gh).resolve(owners);
+  const entries = approverEntries(owners, rights);
+  const lists = expandOwners(entries, teams);
+  const role = (k) => ({
+    owners: entries[k].map((e) => entryLabel(e, teams)),
+    approvedBy: approvers.filter((a) => lists[k].some((x) => sameLogin(x, a)))
+  });
+  const ship = shipPolicy(owners, rights, teams);
+  const unreadable = unreadableTeams(teams);
+  return {
+    design: role("design"),
+    tech: role("tech"),
+    ship: ship ? whoCanShipSentence(ship) : "Anyone with write access can ship.",
+    ...unreadable.length ? { unreadableTeams: unreadable.map((t) => t.message) } : {}
+  };
+}
 async function reviewPr(ctx, a) {
   const gh = await ctx.github();
   if (!gh) throw new Error('No GitHub repo known: set "repo" in bridge.config.json.');
@@ -6025,7 +6585,7 @@ 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-ABJPOTKE.js")).runImpact;
+  const runImpact = run2 ?? (await import("./src-XSBCZV4W.js")).runImpact;
   const r = await runImpact({
     root: ctx.root,
     base: a.base ?? "main",
@@ -6620,7 +7180,7 @@ async function pendingDrafts(ctx, a) {
         for (const img of item.images ?? []) {
           if (images.length >= IMAGES_PER_CALL || !img.path) continue;
           const f = await gh.getFileBase64(img.path, REQUESTS_BRANCH).catch(() => void 0);
-          if (f && f.size <= IMAGE_INLINE_MAX) images.push({ sessionId: s.sessionId, itemId: item.id, label: img.label, base64: f.base64 });
+          if (f && f.size <= IMAGE_INLINE_MAX) images.push({ sessionId: s.sessionId, itemId: item.id, label: img.label, ...img.line ? { line: img.line } : {}, base64: f.base64 });
         }
       }
     }
@@ -6632,12 +7192,12 @@ async function pendingDrafts(ctx, a) {
     sessions: sessions.map((s) => ({ sessionId: s.sessionId, createdAt: s.createdAt, status: s.status, items: s.items, briefs: s.items.map(draftItemBrief) })),
     voice: DRAFT_VOICE_RULES,
     contract: DRAFT_OUTPUT_CONTRACT,
-    next: sessions.length ? `Write a title and a summary for each item, then call bridge_write_drafts with the sessionId and one result per item id. The designer reviews them in Figma.` : `Nothing is waiting. In the DS Bridge Figma plugin, click "Draft with my Claude" on a request or on the Push description, then say "${DRAFT_PHRASE}" again.`
+    next: sessions.length ? sessions.some((s) => s.items.some((i) => i.scope === "docs")) ? `For each change item write a title, a summary and one line per change line; for each docs item follow its brief and send "docs" (the sections it asks for) or "replacement" (a selected passage). Then call bridge_write_drafts with the sessionId and one result per item id. The designer reviews them in Figma or on the Library page.` : `Write a title and a summary for each item, and one line per change line it lists, then call bridge_write_drafts with the sessionId and one result per item id. The designer reviews them in Figma.` : `Nothing is waiting. In the DS Bridge Figma plugin, click "Draft with my Claude" on a request or on the Push description, or pick "My Claude" when drafting docs on a Library page, then say "${DRAFT_PHRASE}" again.`
   };
   return { answer, images };
 }
 async function writeDrafts(ctx, a) {
-  if (!a.results.length) throw new Error('Send at least one result: {"id", "title", "summary"} per item.');
+  if (!a.results.length) throw new Error('Send at least one result: {"id", "title", "summary"} per change item, {"id", "docs"} or {"id", "replacement"} per docs item.');
   const gh = await requireGitHub3(ctx);
   if (!ctx.canWriteRemote) throw new Error("Writing drafts needs GITHUB_TOKEN (contents: read and write on this repository), the same token as the Figma plugin. Without it Bridge is read-only.");
   const out = await writeDraftResults(gh, a.sessionId, a.results);
@@ -6647,12 +7207,12 @@ async function writeDrafts(ctx, a) {
     status: out.status,
     results: out.results ?? [],
     ...waiting.length ? { waiting } : {},
-    next: waiting.length ? `Still waiting for ${waiting.join(", ")}: call bridge_write_drafts again with those ids.` : 'Done. The text shows up in the Figma plugin within a few seconds, marked "Drafted by Claude, review before sending". Tell the designer to review it there.'
+    next: waiting.length ? `Still waiting for ${waiting.join(", ")}: call bridge_write_drafts again with those ids.` : out.source === "studio" ? 'Done. The docs show up on the Library page within a few seconds, marked "Drafted by Claude". Tell the designer to review them there before proposing.' : 'Done. The text shows up in the Figma plugin within a few seconds, marked "Drafted by Claude, review before sending". Tell the designer to review it there.'
   };
 }
 
 // src/server.ts
-var VERSION = "0.1.0";
+var VERSION = true ? "0.3.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 run = (fn) => async (a) => {
@@ -6680,6 +7240,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.",
         "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.",
@@ -6688,7 +7249,7 @@ function createServer(ctx) {
         "New brands: bridge_plan_brand first (dry run with ramps and the contrast gate for every theme), then bridge_propose_brand. A new brand is Tier 3.",
         "To undo a merged token change use bridge_plan_revert first (it shows conflicts with later changes), then bridge_propose_revert; never revert by hand-editing files.",
         'Component changes (new component, variant, prop, structure, visual, token binding) are requests: GitHub issues labeled component-change. bridge_list_requests finds them, bridge_get_request returns a brief to implement one in a pull request that says "Closes #n", bridge_create_request files a new one.',
-        `Change texts from Figma: when the user says "${DRAFT_PHRASE}" (or asks you to draft their Bridge changes), call bridge_pending_drafts, look at the before and after images, write each title and summary in the Bridge voice, then call bridge_write_drafts. The designer reviews them in the DS Bridge Figma plugin.`,
+        `Change texts from Figma and docs from Bridge Studio: when the user says "${DRAFT_PHRASE}" (or asks you to draft their Bridge changes or docs), call bridge_pending_drafts. For change items, look at the before and after images and write each title, summary and change line in the Bridge voice. For docs items (scope "docs"), follow the brief: write only the sections it asks for, grounded in the props, CSS module classes and source it quotes, never an invented prop or behavior, never anatomy. Then call bridge_write_drafts. The designer reviews them in the DS Bridge Figma plugin or on the Library page.`,
         'Explorations try experimental variables and components in a product staging branch without touching main: an explore/<slug> branch with a draft pull request labeled exploration, previews and a snapshot package. bridge_start_exploration starts one, bridge_list_explorations lists them. To work on one, pass "branch": "explore/<slug>" to bridge_propose_token_change, bridge_draft_docs and bridge_get_request, and never open a pull request to main from it: a person promotes it to review or closes it.'
       ].join(" ")
     }
@@ -6881,7 +7442,7 @@ function createServer(ctx) {
     "bridge_get_review",
     {
       title: "Get review",
-      description: "Review a token change: designer-readable diff table, contrast before -> after, new validation errors, downstream impact, computed risk tier (and a warning if labelled lower), and for PRs the CI status and approvals. Pass `pr` (GitHub) or `branch` (local proposal branch).",
+      description: "Review a token change: designer-readable diff table, contrast before -> after, new validation errors, downstream impact, computed risk tier (and a warning if labelled lower), and for PRs the CI status, approvals and roles: who may approve design, approve tech and ship, with GitHub teams named and their size, and any team that cannot be read with the fix. Pass `pr` (GitHub) or `branch` (local proposal branch).",
       inputSchema: { pr: z.number().int().positive().optional(), branch: z.string().optional() },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -7074,9 +7635,11 @@ function createServer(ctx) {
       title: "Pending change texts from Figma",
       description: [
         `Change texts a designer asked their own Claude to write from the DS Bridge Figma plugin ("Draft with my Claude"), waiting on the bridge-requests branch. Call it when the user says "${DRAFT_PHRASE}".`,
-        "Returns the pending sessions (newest first) with each item: scope (request: a component change request; push: a pull request description of token edits), component, kind, the change table, token edits, the designer's notes, the deterministic starting draft, a brief, and the before and after image links; the images themselves follow as image content when small enough.",
+        "Returns the pending sessions (newest first) with each item: scope (request: a component change request; push: a pull request description of token edits; docs: component docs sections from Bridge Studio, with a brief holding the full prompt), component, kind, the change table, token edits, the designer's notes, the deterministic starting draft, the change lines to write (one per component change, with an id, its changes and a starting line), a brief, and the before and after image links; the images themselves follow as image content when small enough.",
         "Look at the before and after images, then write what changes for developers and why it matters for people who use the component. Sentence case, start the title with a verb, no em dash, no invented numbers, names or reasons: if the reason is unknown, leave it out.",
-        `Then call bridge_write_drafts with one result per item id: title at most ${DRAFT_TITLE_MAX} characters, summary at most 3 sentences.`
+        `Write one short sentence per change line from the images: what changed for developers (the part, the variant, the values you can read), for example "Icon added after the label in primary sm: Pencil, 16px", and the title of the request it becomes, for example "Add an icon after the label".`,
+        `Then call bridge_write_drafts with one result per item id: title at most ${DRAFT_TITLE_MAX} characters, summary at most 3 sentences, lines (one per change line id) with a line of at most ${DRAFT_LINE_MAX} characters and a title of at most ${DRAFT_TITLE_MAX}.`,
+        `Docs items: read the brief. Sections to check (the code changed after they were written) go in the answer ONLY when something in them is no longer true for the code (a wrong or removed prop, a removed state, changed behavior), fixed with the writer's wording kept elsewhere; leave accurate ones out (a missing key means unchanged, "docs": {} when all are accurate). Otherwise write only the sections its task names (summary a string; whenToUse, whenNotToUse, accessibility, contentGuidelines lists of strings; dos and donts lists of {"title", "text"}) from the facts it quotes, never a prop, variant or keyboard behavior that is not in the code, never anatomy; answer with "docs": {sections}. A selection task rewrites one passage: answer with "replacement": "the passage". No title or summary for docs items.`
       ].join(" "),
       inputSchema: {
         sessionId: z.string().optional().describe("One session only. Default: every pending session."),
@@ -7091,7 +7654,7 @@ function createServer(ctx) {
           content: [
             { type: "text", text: JSON.stringify(answer, null, 2) },
             ...images.flatMap((img) => [
-              { type: "text", text: `${img.label === "before" ? "Before (baseline)" : "After (now in Figma)"}: session ${img.sessionId}, item ${img.itemId}` },
+              { type: "text", text: `${img.label === "before" ? "Before (baseline)" : "After (now in Figma)"}: session ${img.sessionId}, item ${img.itemId}${img.line ? `, line ${img.line}` : ""}` },
               { type: "image", data: img.base64, mimeType: "image/png" }
             ])
           ]
@@ -7105,14 +7668,23 @@ function createServer(ctx) {
     "bridge_write_drafts",
     {
       title: "Write change texts for Figma",
-      description: 'Write the titles and summaries you drafted for a session from bridge_pending_drafts. The DS Bridge Figma plugin fills them in within seconds, marked "Drafted by Claude, review before sending"; it never overwrites text the designer typed meanwhile. Texts are cleaned to the contract (no em dash, title at most 70 characters without a trailing period, summary at most 3 sentences). Needs GITHUB_TOKEN with contents write. Writes only the session file on the bridge-requests branch, never main.',
+      description: `Write the titles, summaries and change lines (or, for docs items, the docs sections or the rewritten passage) you drafted for a session from bridge_pending_drafts. Docs results show up on the Library page marked "Drafted by Claude" for review, cleaned to the docs.json shapes (no em dash; only the sections the item asks for). The DS Bridge Figma plugin fills change texts in within seconds, marked "Drafted by Claude, review before sending"; it never overwrites text the designer typed meanwhile. Each change line becomes the main line of its component row and the first line of its request; its title becomes that request's title. Texts are cleaned to the contract (no em dash, titles at most ${DRAFT_TITLE_MAX} characters without a trailing period, summary at most 3 sentences, each line at most ${DRAFT_LINE_MAX} characters). Results without lines, or lines without a title, still work. Needs GITHUB_TOKEN with contents write. Writes only the session file on the bridge-requests branch, never main.`,
       inputSchema: {
         sessionId: z.string().min(1).describe("The sessionId from bridge_pending_drafts."),
         results: z.array(
           z.object({
             id: z.string().min(1).describe("The item id from bridge_pending_drafts."),
-            title: z.string().describe(`One line, sentence case, starts with a verb, at most ${DRAFT_TITLE_MAX} characters, no trailing period. A request title never repeats the component name.`),
-            summary: z.string().describe("At most 3 sentences: what changes for developers and why it matters. No em dash, no invented numbers.")
+            title: z.string().optional().describe(`Change items: one line, sentence case, starts with a verb, at most ${DRAFT_TITLE_MAX} characters, no trailing period. A request title never repeats the component name. Leave it out for docs items.`),
+            summary: z.string().optional().describe("Change items: at most 3 sentences, what changes for developers and why it matters. No em dash, no invented numbers. Leave it out for docs items."),
+            docs: z.record(z.string(), z.unknown()).optional().describe('Docs items with a sections task: only the sections the brief asks for (a section to check only when it is no longer true for the code; leave accurate ones out), in docs.json shapes: summary a string; whenToUse, whenNotToUse, accessibility, contentGuidelines lists of strings; dos and donts lists of {"title", "text"}.'),
+            replacement: z.string().optional().describe("Docs items with a selection task: the rewritten passage only, plain text, Bridge voice, no em dash."),
+            lines: z.array(
+              z.object({
+                id: z.string().min(1).describe(`A change line id from the item's "lines" in bridge_pending_drafts.`),
+                line: z.string().describe(`One sentence, at most ${DRAFT_LINE_MAX} characters, no trailing period: what changed for developers, read from the before and after images ("Icon added after the label in primary sm: Pencil, 16px").`),
+                title: z.string().optional().describe(`The title of the request this component change becomes: short, sentence case, starts with a verb, at most ${DRAFT_TITLE_MAX} characters, no trailing period, never the component name ("Add an icon after the label").`)
+              })
+            ).optional().describe("One per change line the item lists. Leave it out when the item lists none.")
           })
         ).min(1).describe("One result per item.")
       },
@@ -7134,13 +7706,13 @@ function createServer(ctx) {
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
-    run((a) => startExploration(ctx, a))
+    run((a) => startExploration(ctx, { ...a, source: "mcp" }))
   );
   server.registerTool(
     "bridge_list_explorations",
     {
       title: "List explorations",
-      description: "Explorations of the repo (draft pull requests labeled exploration on explore/* branches): name, purpose, status (active: running; promoted: ready for review; closed), author, last update, preview links, the snapshot install command for a product staging branch (and the tarball fallback), and the component requests implemented on each. Locally, also explore/* branches without a pull request.",
+      description: "Explorations of the repo (draft pull requests labeled exploration on explore/* branches): name, purpose, status (active: running; promoted: ready for review; closed), author, last update, for running ones the preview links Vercel reports (url null while it has not reported one yet) and the install command a product staging branch uses, read from the preview comment on the pull request (state building until the snapshot of the latest commit is published, never a guessed command), and the component requests implemented on each. Locally, also explore/* branches without a pull request.",
       inputSchema: { state: z.enum(["open", "closed", "all"]).optional().describe("Pull request state. Default open: running and promoted ones.") },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -7345,6 +7917,13 @@ function optionsFromArgv(argv, env = process.env) {
 }
 
 export {
+  missingProse,
+  formatDocsJson,
+  DOCS_DRAFT_MODEL,
+  parseDocsReply,
+  mergeDocsDraft,
+  anthropicRequest,
+  anthropicReplyText,
   detectConfig,
   core,
   LocalSource,