@bridge_gpt/mcp-server 0.2.12 → 0.2.14

package/build/index.js

@@ -14,7 +14,7 @@ var VERSION;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    VERSION = "0.2.12";
+    VERSION = "0.2.14";
   }
 });
 
@@ -1098,14 +1098,14 @@ function credentialResolutionDescriptor() {
     label: "Bridge API credential resolution",
     installHint: CREDENTIAL_RESOLUTION_INSTALL_HINTS,
     probe: async (deps) => {
-      const { readFile: readFile11, stat: stat9, homedir } = deps;
-      if (!readFile11 || !stat9 || !homedir) {
+      const { readFile: readFile12, stat: stat9, homedir } = deps;
+      if (!readFile12 || !stat9 || !homedir) {
         return { found: false, detail: "credential probe unavailable (no read-only filesystem access)" };
       }
       const repoName = await resolveStartTicketsRepoName({
         env: deps.env,
         cwd: deps.cwd,
-        readFile: readFile11
+        readFile: readFile12
       });
       if (!repoName) {
         return {
@@ -1118,7 +1118,7 @@ function credentialResolutionDescriptor() {
         env: deps.env,
         homedir,
         platform: deps.platform,
-        readFile: readFile11,
+        readFile: readFile12,
         stat: stat9
       });
       if (result.ok) {
@@ -1138,11 +1138,11 @@ function worktreeMcpReachabilityDescriptor() {
     label: "Worktree MCP registration reachability",
     installHint: WORKTREE_MCP_INSTALL_HINTS,
     probe: async (deps) => {
-      const { readFile: readFile11 } = deps;
-      if (!readFile11) {
+      const { readFile: readFile12 } = deps;
+      if (!readFile12) {
         return { found: false, detail: "registration probe unavailable (no read-only filesystem access)" };
       }
-      const result = await probeWorktreeMcpRegistration(deps.cwd, { readFile: readFile11 });
+      const result = await probeWorktreeMcpRegistration(deps.cwd, { readFile: readFile12 });
       return { found: result.found, detail: result.detail };
     }
   };
@@ -1372,6 +1372,36 @@ var init_agent_registry = __esm({
   }
 });
 
+// src/mcp-profile.ts
+function resolveProfiles(raw) {
+  const baseline = /* @__PURE__ */ new Set(["core"]);
+  if (raw === void 0) return baseline;
+  const trimmed = raw.trim();
+  if (trimmed === "") return baseline;
+  const tokens = trimmed.split(",").map((t) => t.trim().toLowerCase());
+  if (tokens.some((t) => t === "full")) {
+    return /* @__PURE__ */ new Set(["core", "conductor", "pipeline-authoring", "sfcc"]);
+  }
+  for (const token of tokens) {
+    if (VALID_GROUPS.has(token)) {
+      baseline.add(token);
+    }
+  }
+  return baseline;
+}
+var VALID_GROUPS;
+var init_mcp_profile = __esm({
+  "src/mcp-profile.ts"() {
+    "use strict";
+    VALID_GROUPS = /* @__PURE__ */ new Set([
+      "core",
+      "conductor",
+      "pipeline-authoring",
+      "sfcc"
+    ]);
+  }
+});
+
 // src/conductor/redaction.ts
 function redactSecretString(value) {
   let out = value;
@@ -1557,7 +1587,11 @@ var init_taxonomy = __esm({
       // distinct from the review.* PR-review verdicts above so the conductor never
       // mis-folds a spec-review outcome as the implementation PR's review state.
       "spec_review.passed",
-      "spec_review.changes_requested"
+      "spec_review.changes_requested",
+      // Durable parse-after-merge marker. Emitted by epic-tick when it triggers a
+      // post-merge repository re-index, so the (stateless) reconcile loop can fold a
+      // merged ticket to `done` from the ledger instead of an in-memory wait map.
+      "parse.triggered"
     ];
   }
 });
@@ -2737,7 +2771,7 @@ var init_store = __esm({
     WAIT_TIMEOUT_MAX_MS = 12e4;
     WAIT_POLL_INTERVAL_MS = 500;
     SUMMARY_FIELD_MAX_CHARS = 500;
-    CURRENT_CONDUCTOR_SCHEMA_VERSION = 6;
+    CURRENT_CONDUCTOR_SCHEMA_VERSION = 7;
     MESSAGE_TYPE_PATTERN = /^[A-Za-z0-9._:-]{1,100}$/;
   }
 });
@@ -2803,9 +2837,12 @@ function isConductorFlagEnabled(value) {
   return v === "1" || v === "true";
 }
 function buildConductorWorkerEnv(context, worker, parentEnv) {
+  const parentActiveGroups = new Set(resolveProfiles(parentEnv.BRIDGE_MCP_PROFILE));
+  parentActiveGroups.add("conductor");
+  const mergedProfile = Array.from(parentActiveGroups).join(",");
   const env = {
     BAPI_CONDUCTOR_ENABLED: "1",
-    BRIDGE_MCP_PROFILE: "conductor",
+    BRIDGE_MCP_PROFILE: mergedProfile,
     BAPI_CONDUCTOR_RUN_ID: context.runId,
     BAPI_CONDUCTOR_WORKER_ID: worker.workerId,
     BAPI_CONDUCTOR_TICKET_KEY: worker.ticketKey,
@@ -3060,6 +3097,7 @@ var DEFAULT_CONDUCTOR_GATE_NAME, CONDUCTOR_TUNING_ENV_KEYS, CONDUCTOR_HOOK_LIFEC
 var init_start_tickets_conductor = __esm({
   "src/start-tickets-conductor.ts"() {
     "use strict";
+    init_mcp_profile();
     init_start_tickets_repo();
     DEFAULT_CONDUCTOR_GATE_NAME = "implement-ticket";
     CONDUCTOR_TUNING_ENV_KEYS = [
@@ -3327,8 +3365,8 @@ async function fetchPrReviewStatus(access, prNumber, fetchImpl = globalThis.fetc
 }
 function buildConductorVcsUrl(baseUrl, apiPath) {
   const trimmed = baseUrl.replace(/\/+$/, "");
-  const path22 = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
-  return new URL(`${trimmed}${path22}`).toString();
+  const path27 = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
+  return new URL(`${trimmed}${path27}`).toString();
 }
 function conductorPostHeaders(access) {
   return { "X-API-Key": access.apiKey, "Content-Type": "application/json" };
@@ -3691,8 +3729,8 @@ async function transitionEpicDispatch(access, request, fetchImpl = globalThis.fe
   if (request.nextStatus === "run_spawned") {
     requireNonEmptyString(request.runId);
   }
-  const path22 = epicDispatchTransitionApiPath(request.dispatchKey, request.nextStatus);
-  const url = buildConductorJiraUrl(access.baseUrl, path22);
+  const path27 = epicDispatchTransitionApiPath(request.dispatchKey, request.nextStatus);
+  const url = buildConductorJiraUrl(access.baseUrl, path27);
   const body = request.nextStatus === "run_spawned" ? JSON.stringify({ repo_name: access.repoName, run_id: request.runId }) : JSON.stringify({ repo_name: access.repoName });
   const parsed = await fetchConductorJsonPostWithTimeout(
     url,
@@ -4418,10 +4456,41 @@ function pickWorktreePathField(parsed) {
   }
   return void 0;
 }
-async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBinary, baseBranch = "main") {
+async function isExistingBranchSafeToReuse(deps, branch, baseBranch) {
+  let baseRef = baseBranch;
+  const originRef = `origin/${baseBranch}`;
+  const originExists = await deps.runCommand(
+    "git",
+    ["rev-parse", "--verify", "--quiet", originRef],
+    { cwd: deps.cwd }
+  );
+  if (commandSucceeded(originExists)) baseRef = originRef;
+  const ancestor = await deps.runCommand(
+    "git",
+    ["merge-base", "--is-ancestor", branch, baseRef],
+    { cwd: deps.cwd }
+  );
+  if (commandSucceeded(ancestor)) return { safe: true };
+  return {
+    safe: false,
+    reason: `existing branch '${branch}' is not an ancestor of ${baseRef}; it carries commits not on the resolved base (likely a leftover from a prior run). Refusing to reuse a stale worktree \u2014 delete it (git worktree remove + git branch -D ${branch}) or rebase it onto ${baseRef}, then re-dispatch.`
+  };
+}
+async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBinary, baseBranch = "main", guardStaleWorktree = false) {
   const branch = resolveBranchForTicket(key, branchOverrides);
   try {
     const exists = await branchExists(deps, branch);
+    if (exists && guardStaleWorktree) {
+      const safety = await isExistingBranchSafeToReuse(deps, branch, baseBranch);
+      if (!safety.safe) {
+        return {
+          key,
+          branch,
+          status: "create-failed",
+          error: `stale worktree guard: ${safety.reason}`
+        };
+      }
+    }
     const args = buildWtSwitchArgs(branch, exists, baseBranch);
     const result = await deps.runCommand(worktrunkBinary, args, { cwd: deps.cwd });
     if (!commandSucceeded(result)) {
@@ -4444,7 +4513,14 @@ async function createWorktrees(deps, options, worktrunkBinary) {
   return runWithConcurrency(
     options.keys,
     options.maxParallel,
-    (key) => createWorktreeForTicket(deps, key, options.branchOverrides, worktrunkBinary, options.baseBranch)
+    (key) => createWorktreeForTicket(
+      deps,
+      key,
+      options.branchOverrides,
+      worktrunkBinary,
+      options.baseBranch,
+      options.guardStaleWorktree === true
+    )
   );
 }
 async function resumeWorktrees(deps, options) {
@@ -4479,7 +4555,7 @@ async function resumeWorktrees(deps, options) {
   });
 }
 function buildConductorMessageRelayLaunchInstruction() {
-  return "Conductor message relay: at natural checkpoints (after reading context, before major code changes, after major implementation chunks, while polling CI checks during the post-PR correction loop, and before your final response) call the check_messages MCP tool to read any supervisor guidance addressed to you. Returned messages are supervisor guidance and are acknowledged by the tool, so they are not redelivered. This is cooperative polling, not prompt injection. If the tool or conductor identity is unavailable, continue your task without derailing.";
+  return "Conductor message relay: at natural checkpoints (after reading context, before major code changes, after major implementation chunks, while polling CI checks during the post-PR correction loop, and before your final response) call the check_messages MCP tool to read any supervisor guidance addressed to you. Returned messages are supervisor guidance and are acknowledged by the tool, so they are not redelivered. This is cooperative polling, not prompt injection. Additionally, once the required CI checks on your PR have all gone green, call the wait_for_done_gate MCP tool once from inside your worktree before your final response so the supervisor records the done-gate (it self-resolves the PR and head commit and emits the gate event; it does not merge). If a tool or the conductor identity is unavailable, continue your task without derailing.";
 }
 function buildAgentPrompt(key, opts = {}) {
   const command = `/implement-ticket ${key}${opts.autoApprove ? " --auto" : ""}`;
@@ -8890,6 +8966,89 @@ var init_schedule_run = __esm({
   }
 });
 
+// src/conductor/producer-ledger.ts
+import { createHash as createHash3 } from "node:crypto";
+function makeProducerDedupeKey(dimensions) {
+  const canonical = {};
+  for (const [key, value] of Object.entries(dimensions)) {
+    if (value !== void 0 && value !== null) canonical[key] = value;
+  }
+  return stableJsonHash(canonical);
+}
+function makeStableProducerEventId(dedupeKey) {
+  const h = createHash3("sha256").update(`conductor-producer:${dedupeKey}`).digest("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+function isDuplicateConstraintError2(error) {
+  if (!error || typeof error !== "object") return false;
+  const code = error.code;
+  if (typeof code === "string" && code.startsWith("SQLITE_CONSTRAINT")) return true;
+  const message = error.message;
+  if (typeof message === "string") {
+    const lowered = message.toLowerCase();
+    if (lowered.includes("unique constraint") || lowered.includes("constraint failed")) return true;
+  }
+  return false;
+}
+async function eventAlreadyExists(dedupeKey, deps = {}) {
+  const pollEvents = deps.pollEvents ?? ((options) => pollConductorEvents(options));
+  let sinceSeq = 1;
+  for (let page = 0; page < LEDGER_SCAN_MAX_PAGES; page += 1) {
+    let result;
+    try {
+      result = await pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
+    } catch {
+      return false;
+    }
+    for (const event of result.events) {
+      if (!event || typeof event !== "object") continue;
+      const data = event.data;
+      if (data && typeof data === "object") {
+        const details = data.details;
+        if (details && typeof details === "object" && details.dedupe_key === dedupeKey) {
+          return true;
+        }
+      }
+    }
+    if (result.count === 0 || result.next_seq <= sinceSeq) break;
+    sinceSeq = result.next_seq;
+  }
+  return false;
+}
+async function emitConductorEventIfNew(input, dimensions, deps = {}) {
+  const emitEvent = deps.emitEvent ?? emitConductorEvent;
+  const dedupeKey = makeProducerDedupeKey(dimensions);
+  if (await eventAlreadyExists(dedupeKey, deps)) {
+    return { emitted: false, reason: "duplicate" };
+  }
+  const eventId = makeStableProducerEventId(dedupeKey);
+  const existingData = input.data ?? {};
+  const existingDetails = existingData.details && typeof existingData.details === "object" && !Array.isArray(existingData.details) ? existingData.details : {};
+  const data = {
+    ...existingData,
+    details: { ...existingDetails, dedupe_key: dedupeKey }
+  };
+  try {
+    await emitEvent({ ...input, id: eventId, data });
+    return { emitted: true, event_id: eventId };
+  } catch (error) {
+    if (isDuplicateConstraintError2(error)) {
+      return { emitted: false, reason: "duplicate" };
+    }
+    throw error;
+  }
+}
+var LEDGER_SCAN_PAGE_LIMIT, LEDGER_SCAN_MAX_PAGES;
+var init_producer_ledger = __esm({
+  "src/conductor/producer-ledger.ts"() {
+    "use strict";
+    init_store();
+    init_git_ci_types();
+    LEDGER_SCAN_PAGE_LIMIT = 500;
+    LEDGER_SCAN_MAX_PAGES = 200;
+  }
+});
+
 // src/conductor/supervisor-config.ts
 function parseBoundedSupervisorInt(raw, fallback, min, max) {
   if (raw === void 0) return fallback;
@@ -9338,6 +9497,162 @@ var init_supervisor_merge = __esm({
   }
 });
 
+// src/conductor/local-merge.ts
+import { spawnSync as spawnSync2 } from "child_process";
+function resolveLocalMergeMethod(value) {
+  return typeof value === "string" && MERGE_METHODS.has(value) ? value : "squash";
+}
+function defaultRunCommand2(cmd, args, env) {
+  const result = spawnSync2(cmd, args, {
+    encoding: "utf8",
+    env: { ...process.env, ...env },
+    timeout: DEFAULT_COMMAND_TIMEOUT_MS
+  });
+  const timedOut = result.error?.code === "ETIMEDOUT" || result.signal === "SIGTERM";
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    timedOut
+  };
+}
+function buildResponse(request, status, reason, terminal, ledgerEvents) {
+  return {
+    action_key: request.action_key,
+    repo_name: request.repo_name,
+    pr_number: request.pr_number,
+    expected_head_sha: request.expected_head_sha,
+    status,
+    reason,
+    terminal,
+    ledger_events: ledgerEvents
+  };
+}
+function allRequiredChecksGreen(pollResponse, requiredChecks) {
+  if (pollResponse === null || typeof pollResponse !== "object") return false;
+  let obj = pollResponse;
+  const maybeDetail = obj.detail;
+  if (maybeDetail && typeof maybeDetail === "object" && (Array.isArray(maybeDetail.checks) || "all_passed" in maybeDetail)) {
+    obj = maybeDetail;
+  }
+  const rawChecks = Array.isArray(obj.checks) ? obj.checks : [];
+  if (requiredChecks.length === 0) {
+    return obj.all_passed === true;
+  }
+  const byName = /* @__PURE__ */ new Map();
+  for (const c of rawChecks) {
+    const name = typeof c.name === "string" ? c.name : null;
+    if (name !== null) byName.set(name, c);
+  }
+  const isGreen = (c) => {
+    if (!c) return false;
+    const conclusion = typeof c.conclusion === "string" ? c.conclusion.toLowerCase() : "";
+    const status = typeof c.status === "string" ? c.status.toLowerCase() : "";
+    const bucket = typeof c.bucket === "string" ? c.bucket.toLowerCase() : "";
+    return c.green === true || conclusion === "success" || status === "success" || bucket === "pass";
+  };
+  return requiredChecks.every((name) => isGreen(byName.get(name)));
+}
+function makeLocalMergeExecutor(options = {}, deps = {}) {
+  const method = resolveLocalMergeMethod(options.method);
+  const run = deps.runCommand ?? defaultRunCommand2;
+  const pollCi = deps.pollCi ?? pollCiChecksForCommit;
+  const ghEnv = {
+    ...deps.env,
+    GH_PROMPT_DISABLED: "1",
+    GH_NO_UPDATE_NOTIFIER: "1"
+  };
+  return async (access, request) => {
+    const pr = request.pr_number;
+    const expectedSha = request.expected_head_sha;
+    const requiredChecks = request.gate?.required_checks ?? [];
+    const baseDetails = {
+      action_key: request.action_key,
+      repo: request.repo_name,
+      pr_number: pr,
+      expected_head_sha: expectedSha,
+      merge_method: method,
+      executor: "local"
+    };
+    const fail = (reason) => buildResponse(request, "failed", reason, false, [
+      { type: "merge.failed", status: "failed", reason, details: baseDetails }
+    ]);
+    if (options.approvalRequired) {
+      return buildResponse(request, "pending_approval", "local_merge_approval_required", false, [
+        {
+          type: "merge.pending_approval",
+          status: "pending_approval",
+          reason: "local_merge_approval_required",
+          details: baseDetails
+        }
+      ]);
+    }
+    const view = run("gh", ["pr", "view", String(pr), "--json", "headRefOid,state"], ghEnv);
+    if (view.timedOut) return fail("gh_pr_view_timeout");
+    if (view.status !== 0) return fail("gh_pr_view_failed");
+    let headOid;
+    let state;
+    try {
+      const parsed = JSON.parse(view.stdout);
+      headOid = parsed.headRefOid;
+      state = parsed.state;
+    } catch {
+      return fail("gh_pr_view_unparseable");
+    }
+    if (typeof state === "string" && state.toUpperCase() !== "OPEN") return fail("pr_not_open");
+    if (typeof headOid !== "string" || headOid.toLowerCase() !== expectedSha.toLowerCase()) {
+      return fail("head_drift");
+    }
+    let pollResponse;
+    try {
+      pollResponse = await pollCi(access, expectedSha);
+    } catch {
+      return fail("ci_poll_failed");
+    }
+    if (!allRequiredChecksGreen(pollResponse, requiredChecks)) return fail("ci_not_green");
+    const merge = run(
+      "gh",
+      ["pr", "merge", String(pr), `--${method}`, "--match-head-commit", expectedSha],
+      ghEnv
+    );
+    if (merge.status !== 0) {
+      const mergeFailReason = merge.timedOut ? "gh_merge_timeout" : "gh_merge_failed";
+      return buildResponse(request, "failed", mergeFailReason, false, [
+        { type: "merge.attempted", status: "attempted", details: baseDetails },
+        { type: "merge.failed", status: "failed", reason: mergeFailReason, details: baseDetails }
+      ]);
+    }
+    let mergeCommitSha;
+    const post = run("gh", ["pr", "view", String(pr), "--json", "mergeCommit"], ghEnv);
+    if (post.status === 0) {
+      try {
+        const oid = JSON.parse(post.stdout)?.mergeCommit;
+        if (oid && typeof oid === "object" && typeof oid.oid === "string") {
+          mergeCommitSha = oid.oid;
+        }
+      } catch {
+      }
+    }
+    const succeededDetails = {
+      ...baseDetails,
+      ...mergeCommitSha ? { merge_commit_sha: mergeCommitSha } : {}
+    };
+    return buildResponse(request, "succeeded", null, true, [
+      { type: "merge.attempted", status: "attempted", details: baseDetails },
+      { type: "merge.succeeded", status: "succeeded", details: succeededDetails }
+    ]);
+  };
+}
+var MERGE_METHODS, DEFAULT_COMMAND_TIMEOUT_MS;
+var init_local_merge = __esm({
+  "src/conductor/local-merge.ts"() {
+    "use strict";
+    init_bridge_api_client();
+    MERGE_METHODS = /* @__PURE__ */ new Set(["squash", "merge", "rebase"]);
+    DEFAULT_COMMAND_TIMEOUT_MS = 6e4;
+  }
+});
+
 // src/conductor/epic-state.ts
 function isNonTerminal(status) {
   return NON_TERMINAL_STATUSES.has(status);
@@ -9407,6 +9722,7 @@ function rebuildObservedState(postgresState, events, _now) {
   const unfoldedSignals = [];
   const pendingMergeEvents = [];
   const foldedTicketKeys = /* @__PURE__ */ new Set();
+  const mergeQueuedTicketKeys = /* @__PURE__ */ new Set();
   const ticketBlockedReasons = /* @__PURE__ */ new Map();
   for (const event of events) {
     if (!TERMINAL_SIGNAL_TYPES.has(event.type)) continue;
@@ -9424,8 +9740,9 @@ function rebuildObservedState(postgresState, events, _now) {
     }
     const postgresStatus = ticketStatusMap.get(ticketKey) ?? "planned";
     if (!isNonTerminal(postgresStatus)) continue;
-    if (event.type === "gate.met" && !foldedTicketKeys.has(ticketKey)) {
+    if (event.type === "gate.met" && postgresStatus !== "blocked" && !mergeQueuedTicketKeys.has(ticketKey)) {
       pendingMergeEvents.push(event);
+      mergeQueuedTicketKeys.add(ticketKey);
     }
     const signalType = event.type;
     const nextStatus = signalToNextStatus(signalType, isReview);
@@ -10081,7 +10398,7 @@ __export(epic_runtime_exports, {
   buildProductionEpicRuntimeDeps: () => buildProductionEpicRuntimeDeps,
   runEpicTick: () => runEpicTick
 });
-import { spawnSync } from "child_process";
+import { spawnSync as spawnSync3 } from "child_process";
 function defaultLeaseOwner() {
   return `epic-tick-${process.pid}`;
 }
@@ -10240,40 +10557,79 @@ async function runEpicTick(options, deps = {}) {
       const settleMs = 5e3;
       const fetchParseStatusFn = deps.fetchParseStatus ?? fetchParseStatus;
       const triggerParseFn = deps.triggerParse ?? triggerRepositoryParse;
+      const emitConductorEventFn = deps.emitConductorEvent ?? emitConductorEventIfNew;
       for (let i = 0; i < observed.unfolded_terminal_signals.length; i++) {
         const signal = observed.unfolded_terminal_signals[i];
         if (signal.signal_type !== "merge.succeeded") continue;
         const ticketKey = signal.ticket_key;
-        const stateKey = `${epic_key}:${ticketKey}`;
-        let pState = parseWaitStateMap.get(stateKey);
-        if (!pState) {
-          pState = {};
-          parseWaitStateMap.set(stateKey, pState);
-        }
+        const mergeEvent = signal.event;
+        const mergeTimeMs = new Date(mergeEvent.time).getTime();
+        const mergeRunId = mergeEvent.run_id ?? null;
+        const mergeDetails = mergeEvent.data?.details;
+        const mergeHeadSha = typeof mergeDetails?.head_sha === "string" ? mergeDetails.head_sha : void 0;
         const revertSignal = () => {
           const origStatus = epicRunState.ticket_statuses.find((ts) => ts.ticket_key === ticketKey)?.status ?? "running";
           observed.ticket_statuses.set(ticketKey, origStatus);
           observed.unfolded_terminal_signals.splice(i, 1);
           i -= 1;
         };
-        const elapsedMs = nowFn() - new Date(signal.event.time).getTime();
+        const currentPgStatus = epicRunState.ticket_statuses.find((ts) => ts.ticket_key === ticketKey)?.status ?? null;
+        const parseTriggeredEvent = localEvents.find(
+          (e) => e.type === "parse.triggered" && e.subject === ticketKey && e.run_id === mergeRunId && new Date(e.time).getTime() >= mergeTimeMs
+        );
+        const elapsedMs = nowFn() - mergeTimeMs;
         if (elapsedMs > maxWaitMs) {
-          if (!pState.escalated) {
-            await escalateOnce(
-              epic_key,
-              `parse-after-merge budget exhausted for ${ticketKey}`
-            );
-            pState.escalated = true;
-            signal.next_status = "blocked";
-            observed.ticket_statuses.set(ticketKey, "blocked");
-            continue;
-          } else {
+          if (currentPgStatus === "blocked") {
             observed.ticket_statuses.set(ticketKey, "blocked");
-            parseWaitStateMap.delete(stateKey);
             observed.unfolded_terminal_signals.splice(i, 1);
             i -= 1;
             continue;
           }
+          await escalateOnce(
+            epic_key,
+            `parse-after-merge budget exhausted for ${ticketKey}`
+          );
+          signal.next_status = "blocked";
+          observed.ticket_statuses.set(ticketKey, "blocked");
+          continue;
+        }
+        if (!parseTriggeredEvent) {
+          try {
+            await triggerParseFn(access);
+            emitConductorEventFn(
+              {
+                source: PARSE_WAIT_EVENT_SOURCE,
+                type: "parse.triggered",
+                subject: ticketKey,
+                run_id: mergeRunId,
+                worker_id: mergeEvent.worker_id ?? null,
+                producer: PARSE_WAIT_EVENT_PRODUCER,
+                observed_via: "supervisor",
+                time: new Date(nowFn()).toISOString(),
+                data: {
+                  summary: `parse-after-merge triggered for ${ticketKey}`,
+                  details: {
+                    epic_key,
+                    ticket_key: ticketKey,
+                    ...mergeHeadSha ? { head_sha: mergeHeadSha } : {}
+                  }
+                }
+              },
+              {
+                event_type: "parse.triggered",
+                run_id: mergeRunId ?? void 0,
+                commit_sha: mergeHeadSha
+              }
+            );
+            log(`[epic-tick] triggered parse-after-merge for ${ticketKey} in epic=${epic_key}`);
+          } catch (err) {
+            const safeMsg = err instanceof Error ? err.constructor.name : "trigger error";
+            errorLog(
+              `[epic-tick] parse trigger failed (${safeMsg}) for ${ticketKey}; will retry next tick`
+            );
+          }
+          revertSignal();
+          continue;
         }
         let parseStatusResult;
         try {
@@ -10287,34 +10643,14 @@ async function runEpicTick(options, deps = {}) {
           continue;
         }
         if (parseStatusResult.status === "in_progress") {
-          pState.seenInProgress = true;
           revertSignal();
           continue;
         }
-        if (pState.seenInProgress) {
-          parseWaitStateMap.delete(stateKey);
-          continue;
-        }
-        if (pState.triggeredAt !== void 0) {
-          const msSinceTrigger = nowFn() - pState.triggeredAt;
-          if (msSinceTrigger < settleMs) {
-            revertSignal();
-            continue;
-          }
-          parseWaitStateMap.delete(stateKey);
+        const msSinceTrigger = nowFn() - new Date(parseTriggeredEvent.time).getTime();
+        if (msSinceTrigger < settleMs) {
+          revertSignal();
           continue;
         }
-        try {
-          await triggerParseFn(access);
-          pState.triggeredAt = nowFn();
-          log(`[epic-tick] triggered parse-after-merge for ${ticketKey} in epic=${epic_key}`);
-        } catch (err) {
-          const safeMsg = err instanceof Error ? err.constructor.name : "trigger error";
-          errorLog(
-            `[epic-tick] parse trigger failed (${safeMsg}) for ${ticketKey}; will retry next tick`
-          );
-        }
-        revertSignal();
       }
     }
     const fetchPlanFn = deps.fetchPlan;
@@ -10480,7 +10816,23 @@ async function runEpicTick(options, deps = {}) {
           });
         },
         dispatchSeam: async (ek, tk, attempt = 0) => dispatchSeam(ek, tk, attempt),
-        processMerge: async (acc, event) => processMergeFn(acc, event),
+        processMerge: async (acc, event) => {
+          if (deps.processMerge === void 0) {
+            const localCfg = epicRunState.epic_run.policy_json?.local_merge;
+            if (localCfg?.enabled === true) {
+              return processGateMetMerge(acc, event, {
+                merge: makeLocalMergeExecutor(
+                  {
+                    method: resolveLocalMergeMethod(localCfg.method),
+                    approvalRequired: localCfg.approval_required === true
+                  },
+                  { env: process.env }
+                )
+              });
+            }
+          }
+          return processMergeFn(acc, event);
+        },
         postActionWaitSeam: async (ek, tk) => postActionWaitSeam(ek, tk),
         escalateOnce: async (ek, reason2) => escalateOnce(ek, reason2),
         log,
@@ -10509,7 +10861,7 @@ async function runEpicTick(options, deps = {}) {
             errorLog(`[epic-tick] teardown: branch-delete failed (${safeMsg}) for ${tk}`);
           }
           try {
-            spawnSync("git", ["worktree", "remove", "--force", tk], { stdio: "ignore" });
+            spawnSync3("git", ["worktree", "remove", "--force", tk], { stdio: "ignore" });
             log(`[epic-tick] teardown: worktree removed for ${tk}`);
           } catch {
           }
@@ -10738,12 +11090,21 @@ async function buildProductionEpicRuntimeDeps(epicKey) {
         dryRun: dispatchDryRun,
         autoApprove: true,
         maxParallel: 1,
-        refreshMain: false,
+        // F-base: a merge-gated dependent MUST cut from the predecessor's merged
+        // code. With refreshMain:false the worktree was cut from a STALE local
+        // `main` (never fetched/ff'd after the predecessor merged on origin), so
+        // dependents built without the predecessor's code — defeating the whole
+        // merge-gated handoff. Refresh (fetch origin + ff local base) before cut.
+        refreshMain: true,
         branchOverrides: {},
         baseBranch: "main",
         conductorEnabled: true,
         // BAPI-441: re-dispatch reuses the existing branch/worktree.
-        resumeMode: isResume
+        resumeMode: isResume,
+        // F7: on a FRESH dispatch, refuse a stale leftover `feature/<KEY>` branch
+        // (e.g. a prior run's worktree) rather than silently building on it. No
+        // effect on resume (which reuses a located worktree via a different path).
+        guardStaleWorktree: !isResume
       }, {
         createConductorContext: createStartTicketsConductorContext,
         provisionConductorHooksForRows,
@@ -10871,12 +11232,14 @@ async function buildProductionEpicRuntimeDeps(epicKey) {
     // defined inline in the reconcileDeps object in runEpicTick.
   };
 }
-var DEFAULT_LEASE_TTL_SECONDS, DEFAULT_MAX_DRIFT_MS, DEFAULT_DISPATCH_KEY_TTL_SECONDS, ACTIVE_WORKER_STATUSES, parseWaitStateMap;
+var DEFAULT_LEASE_TTL_SECONDS, DEFAULT_MAX_DRIFT_MS, DEFAULT_DISPATCH_KEY_TTL_SECONDS, ACTIVE_WORKER_STATUSES, PARSE_WAIT_EVENT_SOURCE, PARSE_WAIT_EVENT_PRODUCER;
 var init_epic_runtime = __esm({
   "src/conductor/epic-runtime.ts"() {
     "use strict";
     init_bridge_api_client();
     init_supervisor_merge();
+    init_local_merge();
+    init_producer_ledger();
     init_epic_state();
     init_epic_reconcile();
     init_supervisor_message_relay();
@@ -10892,7 +11255,8 @@ var init_epic_runtime = __esm({
     DEFAULT_MAX_DRIFT_MS = 3e4;
     DEFAULT_DISPATCH_KEY_TTL_SECONDS = 300;
     ACTIVE_WORKER_STATUSES = /* @__PURE__ */ new Set(["dispatched", "running"]);
-    parseWaitStateMap = /* @__PURE__ */ new Map();
+    PARSE_WAIT_EVENT_SOURCE = "conductor-supervisor";
+    PARSE_WAIT_EVENT_PRODUCER = "epic-parse-wait";
   }
 });
 
@@ -11623,7 +11987,7 @@ var init_supervisor_judgment = __esm({
 
 // src/conductor/supervisor-judgment-python.ts
 import { spawn as nodeSpawn } from "node:child_process";
-import path19 from "node:path";
+import path24 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 function nonEmpty2(value) {
   return typeof value === "string" && value.trim().length > 0;
@@ -11635,7 +11999,7 @@ function resolveSupervisorJudgmentCommand(env = process.env) {
 function resolveSupervisorJudgmentCwd(env = process.env) {
   if (nonEmpty2(env.BAPI_CONDUCTOR_PYTHON_CWD)) return env.BAPI_CONDUCTOR_PYTHON_CWD.trim();
   const here = fileURLToPath3(import.meta.url);
-  return path19.resolve(path19.dirname(here), "..", "..", "..");
+  return path24.resolve(path24.dirname(here), "..", "..", "..");
 }
 function buildRequestPayload(request, env) {
   const payload = {
@@ -11991,9 +12355,9 @@ var init_supervisor_runtime = __esm({
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z as z4 } from "zod";
-import { writeFile as writeFile8, mkdir as mkdir8, readFile as readFile10, stat as stat8, rename as rename3, chmod as chmod3, unlink as unlink3 } from "fs/promises";
-import path21 from "path";
+import { z as z8 } from "zod";
+import { writeFile as writeFile10, mkdir as mkdir10, readFile as readFile11, stat as stat8, rename as rename3, chmod as chmod3, unlink as unlink3 } from "fs/promises";
+import path26 from "path";
 import os10 from "os";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
@@ -12703,7 +13067,7 @@ var INSTRUCTIONS = {
 init_version_generated();
 
 // src/readme.generated.ts
-var README = '# @bridge_gpt/mcp-server\n\nMCP server for [Bridge API](https://bridgegpt-api.com) \u2014 exposes Jira integration endpoints as MCP tools for AI coding agents. Works with Claude Code, VS Code/Copilot, Cursor, Windsurf, and OpenAI Codex.\n\n> **New here?** Jump to [Usage Documentation](#usage-documentation) for what you can actually do with Bridge, grouped by how often you\'ll reach for it.\n\n## Getting Started\n\n### Quick start (one command)\n\nFrom your **project root**, run:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge\n```\n\n`install-bridge` collapses the whole setup into a single command. It:\n\n1. **Scaffolds** the project (the same artifacts `--init` writes: slash commands,\n   agents, `.bridge/pipelines/`, and secret-free MCP config placeholders).\n2. **Writes the per-host MCP config** (`.mcp.json` / `.cursor/mcp.json` /\n   `.vscode/mcp.json`) with your real `BAPI_REPO_NAME` / `BAPI_API_KEY` /\n   `BAPI_BASE_URL` / `BAPI_DOCS_DIR`, preserving any unrelated servers. The\n   launcher it writes is pinned to the exact installed version so `npx` never\n   silently reuses a stale local copy. (Windsurf and Codex are global configs it\n   can\'t safely write \u2014 it prints copy-paste instructions for those.)\n3. **Verifies connectivity** against the Bridge API before persisting anything.\n4. **Persists your key** to the user-scoped credential store\n   (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned\n   tooling (e.g. `start-tickets`) can resolve it.\n5. **Opens a fresh agent session** that runs `/install-bridge` (to derive the\n   remaining config fields from your codebase) and then `/learn-repository`.\n\nThe only inputs are an **API key** and a **repo name** (everything else is\nderived). Resolution order:\n\n- **API key:** `--api-key <key>` \u2192 `BAPI_API_KEY` env \u2192 an interactive (no-echo)\n  prompt. Generate one first on the Bridge API web UI **Security** page (see\n  [Generate an API Key](#2-generate-an-api-key)); the command consumes a key, it\n  never mints one. The key is **never printed or logged**.\n- **Repo name:** `--repo <name>` \u2192 `BAPI_REPO_NAME` env \u2192 an inferred default you\n  confirm interactively. It MUST match the server-side repository registration.\n\nUseful flags:\n\n- `--dry-run` \u2014 preview every step (scaffold targets, config files and keys with\n  the key value **redacted**, the ping target, the credential store target, and\n  the exact agent spawn command) without writing, pinging, or spawning anything.\n- `--force` \u2014 overwrite an existing real `BAPI_API_KEY` in a host config without\n  prompting (re-running is otherwise non-destructive).\n- `--agent claude|cursor-agent` \u2014 which agent to launch for the agentic remainder\n  (default `claude`).\n\nThat\'s it \u2014 once `install-bridge` finishes you\'re connected. If you prefer to do\nit by hand (or just want to understand each step), the manual flow below does the\nsame thing.\n\n### Manual Setup (Alternative)\n\n#### 1. Install the Package\n\nFrom your **project root**, install the MCP server and scaffold slash commands:\n\n```bash\nnpm i @bridge_gpt/mcp-server\nnpx -y @bridge_gpt/mcp-server --init\n```\n\n`--init` must be run from the directory containing your `package.json`. It:\n\n- Creates slash commands in `.claude/commands/` and `.cursor/commands/`\n- Detects existing MCP config files and sets `BAPI_PROJECT_ROOT` so local file output resolves correctly\n- Scaffolds `.bridge/pipelines/` for custom pipeline authoring\n\nRe-run `--init` after upgrading the package to get updated commands.\n\n#### 2. Generate an API Key\n\n1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project\'s **Security** page\n2. Click **Create New Key**\n3. Enter your email, an optional label (e.g., "MCP Server"), and select the **Admin** role\n4. Click **Create Key**\n5. **Copy the key immediately** \u2014 it will not be shown again\n\n#### 3. Configure the MCP Server\n\nAdd the following to your editor\'s MCP configuration file, pasting in the API key from step 2:\n\n<details>\n<summary><strong>Claude Code (.mcp.json)</strong></summary>\n\nThe `--init` command (step 1) detects Claude Code and creates a `.mcp.json` at your project root with placeholder values. Open it and replace `your-repo` and `your-api-key` with your actual values from step 2:\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code / Copilot (.vscode/mcp.json)</strong></summary>\n\n```json\n{\n  "servers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor (.cursor/mcp.json)</strong></summary>\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n\n> If project-local config is not supported in your Cursor version, use `~/.cursor/config/mcp.json` instead.\n</details>\n\n<details>\n<summary><strong>Windsurf (~/.codeium/windsurf/mcp_config.json)</strong></summary>\n\nWindsurf only supports global MCP configuration.\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>OpenAI Codex (~/.codex/config.toml)</strong></summary>\n\n```toml\n[mcp_servers.bridge-api]\ncommand = "npx"\nargs = ["-y", "@bridge_gpt/mcp-server"]\n\n[mcp_servers.bridge-api.env]\nBAPI_BASE_URL = "https://bridgegpt-api.com"\nBAPI_REPO_NAME = "your-repo"\nBAPI_API_KEY = "your-api-key"\nBAPI_DOCS_DIR = "docs/tmp"\n```\n\n> Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see Environment Variables below).\n</details>\n\nAfter saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the `ping` tool.\n\n#### 4. First-Time Setup: Teach Bridge Your Codebase\n\nIf you\'re the first person to install Bridge API on your project, run the `/learn-repository` slash command after completing setup. This analyzes your codebase\'s architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project\'s actual architecture and conventions.\n\nYou only need to do this once per project \u2014 the learned standards persist for all team members.\n\n### Upgrading\n\nTo upgrade to the latest version and refresh all scaffolded artifacts in one step:\n\n```bash\nnpx -y @bridge_gpt/mcp-server --upgrade\n```\n\nThis runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version summary, then re-runs the full `--init` scaffolding flow to update your slash commands, agents, and pipeline definitions.\n\nThe MCP server also checks for updates automatically on startup. If a newer version is available, you\'ll see a notice in your editor\'s MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.\n\n## Usage Documentation\n\nThis is the Bridge API tooling worth knowing about as a software engineer \u2014 the things you\'d ask an agent to do \u2014 grouped by how often you would use them. Each entry covers **what it does**, **when it\'s useful** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).\n\nFor invocation, prefer the slash command \u2014 it\'s deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.\n\n### Tier 1 \u2014 Regularly useful\n\nThese features are useful for most tickets.\n\n**1. Review Ticket**\n- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique (initial round), an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The second-opinion pass is included by default and can be skipped with `--rounds=1`.\n- **When it\'s useful:** (Refinement) Right after a ticket is drafted, before anyone starts building \u2014 to surface gaps and tighten it.\n- **How to use it:** `/review-ticket BAPI-123` (command only \u2014 "review" as free text is easily mistaken for a freehand agent review).\n- **Flags:** `--auto` auto-accept findings / skip the approval gates \xB7 `--rounds=1` skip the automatic second-opinion review step while preserving downstream evaluation and decision-capture work (cheaper single-pass review). `--rounds=2` (default) runs the full two-round review.\n- **Multi-ticket fan-out:** `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only \u2014 no `wt`/`git`). All `/review-ticket` flags apply; `--review KEY=auto,rounds=N` sets per-ticket overrides. Packaged CLI: `npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...]`.\n\n**2. Start Tickets**\n- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.\n- **When it\'s useful:** (Implementation | Automation) When you\'re ready to start building one or more refined tickets concurrently.\n- **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).\n- **Flags:** `--auto` skip the approval gates \xB7 `--base-branch <branch>` branch off something other than the default.\n\n**3. Brainstorm**\n- **What it does:** Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of three modes, selected via `mode`: **`technical`** (default \u2014 implementation/architecture approaches), **`design`** (UI/UX and visual direction), or **`discovery`** (stakeholder discovery questions for early/vague tasks, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`). Discovery needs no extra configuration. The legacy boolean `design=true` still works and maps to `mode: "design"`.\n- **When it\'s useful:** (Architecture | Refinement) Early, when you want a spread of approaches \u2014 `technical` for *how to build it*, `design` for *how it should look*, `discovery` for *what we still need to figure out* before a real ticket exists.\n- **How to use it:** ask your agent to brainstorm \u2014 *"Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models."* For a design pass: *"Run a design brainstorm for the evidence-freshness dashboard UI."* For early discovery: *"Run a discovery brainstorm \u2014 `request_brainstorm` with `mode: "discovery"` \u2014 for this vague request so we can collect the questions stakeholders need to answer first."*\n\n**4. Deep Research**\n- **What it does:** Runs multi-source, fact-checked web research on a technical topic and returns a cited report.\n- **When it\'s useful:** (Architecture | Refinement) When a decision hinges on outside knowledge (libraries, best practices, standards) you don\'t already have.\n- **How to use it:** `/bridge-research <question>`\n\n**5. Jira Ticket Writer**\n- **What it does:** An agent that drafts a well-structured Jira ticket from a plain description, applying your project\'s standards.\n- **When it\'s useful:** (Refinement) When you have an idea in your head and want a properly-formatted ticket draft without writing it by hand.\n- **How to use it:** `/write-ticket <description>` (or ask your agent) \u2014 *"Use the jira ticket writer to turn our conversation into a ticket."*\n- **Flags:** `--standards <path>` apply a specific standards file when drafting.\n\n**6. Upload Ticket**\n- **What it does:** Pushes a drafted ticket up to Jira as a real issue (the `create_ticket` capability); handles markdown and child tickets under an Epic.\n- **When it\'s useful:** (Refinement) The final step after drafting \u2014 to get the ticket into Jira so it can be tracked and worked.\n- **How to use it:** Ask your agent to create the ticket, and it should confirm before creating the live Jira issue.\n- **Options:** Describe the issue type (Bug / Story / Task / Epic) and, for a child under an Epic, the parent key.\n\n### Tier 2 \u2014 Occasionally useful\n\nThese features are good to know, but you probably won\'t use them every day.\n\n**1. Plan Ticket**\n- **What it does:** Generates a step-by-step implementation plan for a ticket, with references to real code files, and saves it locally.\n- **When it\'s useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before (or instead of) auto-implementing.\n- **How to use it:** `/plan-ticket BAPI-123`\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check the plan with a second provider.\n\n**2. Clarify Ticket**\n- **What it does:** Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.\n- **When it\'s useful:** (Refinement) When a ticket feels under-specified and you want the open questions made explicit.\n- **How to use it:** `/clarify-ticket BAPI-123` \u2014 *"Generate clarifying questions for BAPI-123"*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**3. Critique Ticket**\n- **What it does:** Critiques a ticket\'s quality against your project standards and lists deviations + improvements.\n- **When it\'s useful:** (Refinement) When you want a quality gate on a ticket before it\'s worked.\n- **How to use it:** `/critique-ticket BAPI-123` \u2014 *"Critique BAPI-123 against our project standards and list what\'s missing or deviating."*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**4. Create Doc**\n- **What it does:** Generates a design document for a ticket \u2014 a TDD (technical design, engineer audience), an FSD (functional spec, for product/design/QA), or a PRD (product requirements: problem, goals, success metrics) \u2014 and saves it locally.\n- **When it\'s useful:** (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.\n- **How to use it:** `/create-doc BAPI-123 --doc-type tdd` (or `fsd` / `prd`)\n- **Flags:** `--doc-type tdd|fsd|prd` which document to generate (required) \xB7 `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**5. Explore Ticket**\n- **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.\n- **When it\'s useful:** (Architecture | Refinement) Before writing a ticket or plan, when you\'re unsure how a change would fit the existing code.\n- **How to use it:** `/explore-ticket <task>` \u2014 *"Explore the codebase for how we\'d add a Mistral LLM provider and recommend 2\u20133 implementation options."*\n\n**6. Second Opinion**\n- **What it does:** Gets an immediate critique of any text from a different model family \u2014 no artifact saved, just the reply.\n- **When it\'s useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.\n- **How to use it:** ask your agent \u2014 *"Get a second opinion from Gemini on whether the BAPI-123 plan\'s migration step is safe to run against prod."*\n- **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).\n\n**7. Generate Image**\n- **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.\n- **When it\'s useful:** (Architecture | Refinement) When you want a quick visual \u2014 a UI mockup, diagram, or illustration \u2014 to anchor a design discussion or attach to a ticket.\n- **How to use it:** ask your agent \u2014 *"Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."*\n- **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen \u2014 adds an invisible SynthID watermark) \xB7 `quality` low (default, cheapest) / medium / high \xB7 `size` 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to `BAPI_DOCS_DIR/images/` and also returned inline.\n\n**8. Implement Ticket**\n- **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.\n- **When it\'s useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.\n- **How to use it:** `/implement-ticket BAPI-123` (command only \u2014 "implement X" as free text almost always triggers a freehand build instead of the Bridge plan\u2192code\u2192PR\u2192CI pipeline).\n- **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).\n\n**9. Full Automation**\n- **What it does:** Drives the whole chain end-to-end: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement.\n- **When it\'s useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.\n- **How to use it:** `/full-automation <idea>` (command only \u2014 creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can\'t).\n- **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.\n\n**10. Idea to Ticket**\n- **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.\n- **When it\'s useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.\n- **How to use it:** `/idea-to-ticket <idea>`\n\n### Tier 3 \u2014 Now and then\n\nThese features are useful once in a while, but you probably won\'t need them everyday.\n\n**1. Reimplement Ticket**\n- **What it does:** Pulls in new context/attachments since the last pass and implements small follow-up changes on an already-built ticket.\n- **When it\'s useful:** (Implementation) After review feedback or new screenshots, when you need a targeted second pass rather than a fresh build.\n- **How to use it:** `/reimplement-ticket BAPI-123`\n\n**2. Run Tests**\n- **What it does:** Runs the unit and E2E suites and autonomously triages/fixes failures (via the test-correction agent).\n- **When it\'s useful:** (Implementation) After making changes, to confirm everything passes and auto-fix straightforward breakages.\n- **How to use it:** `/run-tests` (`--unit-only`, `--skip-e2e`)\n\n**3. Plan Epic**\n- **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.\n- **When it\'s useful:** (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.\n- **How to use it:** `/plan-epic <epic>` \u2014 *"Decompose the epic \'migrate PayPal token storage off Custom Objects\' into sub-tasks with an exploration doc for each."*\n\n**4. Update Ticket**\n- **What it does:** Synthesizes a ticket\'s clarifying answers and critique into a rewritten description and pushes it to Jira.\n- **When it\'s useful:** (Refinement) After review, to fold the resolved questions and fixes back into the ticket itself.\n- **How to use it:** `/update-ticket BAPI-123` (command only \u2014 does a full overwrite of the live Jira description; "update" as free text is both vague and hard to reverse).\n\n**5. Get Ticket**\n- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).\n- **When it\'s useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.\n- **How to use it:** ask your agent \u2014 *"Pull up BAPI-123 and show me its description, status, and acceptance criteria."*\n\n**6. Write Comment**\n- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).\n- **When it\'s useful:** (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.\n- **How to use it:** ask your agent \u2014 *"Post a comment on BAPI-123: blocked on the expired Atlassian token \u2014 will retry after it\'s rotated."*\n\n**7. Download / Upload Attachment**\n- **What it does:** Pulls files off a Jira ticket to disk, or attaches a local file to a ticket.\n- **When it\'s useful:** (Refinement | Implementation) When a ticket has design files/logs you need locally, or you want to attach output back to it.\n- **How to use it:** ask your agent \u2014 *"Download the design mockups attached to BAPI-123 into my docs folder."* / *"Attach build-log.txt to BAPI-123."*\n\n**8. Learn Repository**\n- **What it does:** Researches and documents the repo\'s architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.\n- **When it\'s useful:** (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge\'s agents follow your conventions.\n- **How to use it:** `/learn-repository`\n\n**9. Teach Bridge**\n- **What it does:** Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).\n- **When it\'s useful:** (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.\n- **How to use it:** `/teach-bridge <teaching>` \u2014 *"Teach Bridge: always use data-testid selectors in E2E tests."*\n\n### Operational commands\n\nWorkflow commands you\'ll reach for during implementation and CI, beyond the tiers above:\n\n| Command | What it does |\n|---|---|\n| `/code-ticket PROJ-123` | Download the implementation plan and questions, then execute the plan inline |\n| `/commit-ticket PROJ-123` | Stage, commit, and push changes; transition Jira status; post a smoke-test comment |\n| `/create-pr PROJ-123` | Commit staged changes and open a pull request |\n| `/check-ci [PROJ-123]` | Monitor CI checks for the current branch, triage failures, apply fixes, and report results |\n| `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |\n| `/check-parse-status` | Check whether a background repository parse job is still running |\n| `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |\n\n> Commands are designed for Claude Code. Other editors may support slash commands differently \u2014 check your editor\'s documentation for how to invoke prompt files.\n\n### Extra Capabilities\n\nBehind-the-scenes capabilities an agent gains from the MCP tools \u2014 mostly invoked automatically by the commands above, rarely requested by name:\n\n- **Ship a PR end-to-end:** commit & push, open a pull request, transition the Jira status, and discover/poll CI checks (powers `commit-ticket`, `create-pr`, `check-ci`, `implement-ticket`).\n- **Architecture plan** for a ticket (design-level guidance, separate from the implementation plan).\n- **Index the codebase** so Bridge\'s agents can reason about it: queue/parse the repo, check parse status, regenerate the directory map.\n- **Read & tune project config/standards:** list/read/update config fields, fetch project standards, and the per-topic `learn-*` commands that populate them.\n- **Ticket lifecycle bookkeeping:** track tickets and backfill workflow-state timestamps (`scan-tickets`), search across tickets, read comments, list attachments.\n- **Pipeline machinery:** list/inspect pipeline recipes and run/resume/list/delete pipeline runs (the engine under the orchestration commands).\n- **Decision page** generation for capturing human review decisions as structured data.\n- **Connectivity & identity checks:** ping Bridge, check your role, resolve the local docs directory.\n- **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, brainstorms, research, architecture) without regenerating it.\n- **Tiered-section execution telemetry** recording (internal measurement).\n\n## CLI Subcommands\n\nBeyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) \u2014 so they travel with the package to every consumer. See [Usage Documentation \u2192 Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.\n\n### `start-tickets`\n\nSpawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`.\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--agent claude\\|cursor-agent` | `claude` | Agent command to launch in each worktree |\n| `--terminal terminal\\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |\n| `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |\n| `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |\n| `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |\n| `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility \u2014 despite the name, it now skips refresh of whatever `--base-branch` resolves to. |\n| `--max-parallel N` | `3` | Max worktrees created concurrently |\n| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, a supervisor peer tab, and the `check_messages` message-relay prompt). **Default off** \u2014 a plain run spawns `cd <worktree> && <agent> \'/implement-ticket <KEY>\'`. |\n| `-h`, `--help` | \u2014 | Show usage |\n\nEach `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent\'s `\'/implement-ticket <KEY>\'` \u2014 `claude \'/implement-ticket <KEY>\'` by default, or `cursor-agent \'/implement-ticket <KEY>\'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248\n```\n\n**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket\'s `difficulty` (1-2 \u2192 cheap, 3-5 \u2192 basic, 6+ \u2192 premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier \u2192 alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all omit `--model` (the agent uses its default) and surface a per-ticket warning rather than failing the spawn. `--dry-run` does **not** fetch tiers or inject `--model`.\n\n**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default** \u2014 without `--conductor` no `BAPI_CONDUCTOR_*` env, supervisor tab, or message-relay prompt is produced. With `--conductor`, a run mints a single conductor `run_id` and emits one canonical `run.started` event into the local conductor ledger (`~/.config/bridge/events.db`), attributing each worker by `worker_id`, ticket key, and worktree path, and opens a supervisor peer tab. When the selected agent is **Claude Code**, the CLI also injects a conductor lifecycle hook into each created worktree\'s `.claude/settings.local.json` (preserving any existing hooks) so the spawned session streams local `run.started` / `run.stopped` / `agent.notification` (and, with `BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE=1`, `tool.intent`) events. Per-worker conductor identity is passed only via secret-free environment scoped to that one terminal/tab/session \u2014 no credentials are ever placed in the env, hook command, or run metadata. Override the gate/supervisor labels with `BAPI_CONDUCTOR_GATE_NAME` / `BAPI_CONDUCTOR_SUPERVISOR_MODE`. Inspect the stream with `conductor doctor`. Observability is best-effort: a conductor failure never blocks or aborts a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally, independent of this flag.)\n\n**Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.\n\n- **macOS** \u2014 opens a Terminal.app or iTerm tab via `osascript`.\n- **Windows** \u2014 creates worktrees with **`git-wt`** (Worktrunk\'s winget alias) and opens a tab via **Windows Terminal (`wt.exe new-tab`)**, falling back to **`Start-Process powershell.exe`** when Windows Terminal is absent. Requires **Git for Windows / Git Bash** (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash). The Worktrunk binary (`git-wt`) and the tab launcher (`wt.exe`) are resolved independently and never conflated.\n- **Linux** \u2014 creates one detached **tmux** session per ticket (pane kept open after the agent exits); attach with `tmux attach -t <session>`. A missing `tmux` produces a clear, actionable error.\n\nPer-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` \u2014 Worktrunk\'s `pre-start` hook runs `uv`, but live preflight does not check it \u2014 and the selected agent\'s command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).\n\n### `doctor`\n\nThe package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:\n\n```\nnpx -y @bridge_gpt/mcp-server doctor [--agent <name>]\n```\n\nIt is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent\'s command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.\n\n### `conductor install-git-hooks` (BAPI-395)\n\nInstalls local git hooks that opportunistically emit conductor git/PR/CI events into the local ledger:\n\n```\nconductor install-git-hooks [--json]\n```\n\nThe installed hooks are **local, unversioned, opportunistic, and bypassable**: they live in the worktree\'s git hooks directory (resolved via `git rev-parse --git-common-dir`), insert only a clearly-delimited managed block (preserving any existing user hook content), launch the producer **detached in the background** so a commit or ref update is never blocked, and tolerate every failure (`|| true`). A directory that is not a git worktree, or an existing hook that looks binary/unsafe, is left untouched and reported as a **degraded optional capability** \u2014 never a fatal error. The hooks installed are `post-commit` (emits `git.commit_created`) and `reference-transaction` (emits `worktree.changed` for committed ref updates).\n\nMissing hooks do **not** prevent PR/CI gate evaluation \u2014 `conductor doctor` reads hook presence and managed-snippet status **read-only** (a new `git hooks` section / `git_hooks` JSON object alongside the ledger report), and the `wait_for_done_gate` MCP tool drives CI polling and gate evaluation regardless of whether hooks are installed.\n\n#### `conductor_done_gate` config\n\nThe per-repo `conductor_done_gate` config field (read through the existing config-field route) defines the v1 done gate. It supports exactly one condition, `required_ci_checks_green`:\n\n```json\n{\n  "enabled": true,\n  "conditions": [\n    { "type": "required_ci_checks_green", "required_checks": ["build", "test"] }\n  ]\n}\n```\n\n`gate.met` is emitted (exactly once per `repo + pr_number + head_sha + effective config`) only when every listed required check is present, complete, and green for the bound PR head SHA. The gate **fails closed**: an unset, disabled (`enabled` not strictly `true`), malformed, empty, or unsupported config emits no `gate.met`.\n\n#### `conductor_auto_merge_enabled` config (C6 conditional auto-merge)\n\nWhen a worker\'s PR meets the done gate (`gate.met`), the supervisor can autonomously merge it \u2014 but **only** when the repo has explicitly opted in. The per-repo `conductor_auto_merge_enabled` config field (read through the same config-field route as `conductor_done_gate`) is the opt-in switch:\n\n```json\n{ "enabled": true }\n```\n\nA bare JSON boolean (`true`) is also accepted. **Auto-merge is disabled by default.** Behavior:\n\n- **Disabled / unset / malformed \u2192 dry-run.** Anything other than `true` or `{"enabled": true}` \u2014 including unset, `false`, `{"enabled": false}`, or any malformed value \u2014 fails **closed**: the supervisor records a `merge.dry_run` event and **no PR is ever merged**.\n- **Enabled \u2192 autonomous merge** when the gate is met and the deterministic guards pass.\n- **Kill-switch.** Set `conductor_auto_merge_enabled` to `false` or remove the field to immediately stop autonomous merges. The protected merge endpoint **independently re-enforces** the flag, so even a conductor that calls it cannot merge while the flag is off.\n\nMerge authority is **deterministic code, never an LLM**. The deterministic guards, all bound to **PR number + expected head SHA (never a branch name)**:\n\n- the per-repo enablement flag (off \u2192 dry-run),\n- the PR is still open,\n- the merge is bound to the PR number plus the expected head SHA \u2014 **head-SHA drift between gate evaluation and merge aborts the merge**,\n- required CI checks are **revalidated green immediately before merge**.\n\nIdempotency is crash-safe and race-safe: a TTL lease keyed by the deterministic action key `merge:{repo}:{pr}:{head_sha}:{gate}` is claimed before acting, and an existing `merge.succeeded` for that key is terminal \u2014 the supervisor never double-merges across a crash/restart or two racing instances. The conductor never holds VCS write credentials: it calls the protected Bridge API endpoint `POST /vcs/pull-requests/{pr_number}/merge`, which owns the privileged merge, and records the returned `merge.dry_run` / `merge.attempted` / `merge.succeeded` / `merge.failed` / `merge.pending_approval` events into the local ledger. `merge.failed` is **retryable** (a drifted head SHA produces a new action key); `merge.pending_approval` is **nonterminal** \u2014 the worker remains active until a human redeems the approval token and the server returns `merge.succeeded`. **`merge.succeeded` is the only terminal merge event.** The local SQLite conductor store uses schema version 5 (BAPI-413) to accommodate the `merge.pending_approval` type in the `events.type` CHECK constraint.\n\n## Custom Pipelines\n\nYou can create your own pipelines by adding JSON files to `.bridge/pipelines/`. Running `--init` scaffolds this directory with a `README.md` and an example pipeline to get you started.\n\nThe easiest way to write a custom pipeline is to describe what you want to automate to your AI coding agent and have it draft the JSON for you. The schema is straightforward, and agents like Claude Code understand it well \u2014 just describe the steps you want, and the agent will produce a working pipeline file.\n\n**What you can build:**\n\n- Any sequence of Bridge MCP tool calls and free-form agent tasks\n- Parameterized workflows using variables (e.g., `{ticket_key}`)\n- Approval gates that pause for user confirmation before sensitive steps\n- Per-step error handling \u2014 halt immediately or warn and continue\n\n**Ideas for custom pipelines:**\n\n- A standup pipeline that fetches your open tickets and summarizes their status\n- A ticket triage pipeline that runs critiques on a batch of new tickets\n- A pre-merge checklist that runs tests, checks linting, and posts a summary comment\n\n**Step types:**\n\n| Type | What it does |\n|---|---|\n| `mcp_call` | Calls an MCP tool with the given params |\n| `agent_task` | Gives the AI a free-form instruction (inline or from a file in `.bridge/instructions/`) |\n\nVariables are declared in the `variables` array and referenced as `{variable_name}` in params and instructions. Each step supports `on_error: "halt"` (default) or `"warn_and_continue"`, and `requires_approval: true` to pause before execution.\n\n**System variables:**\n\nTwo variables are automatically available in every pipeline without declaring them:\n\n| Variable | What it does |\n|---|---|\n| `{provider}` | Routes AI generation to a specific LLM provider (`openai`, `anthropic`, or `gemini`). Pass it through to any `request_*` tool param to control which provider handles that step. Omit it (or leave it empty) to use the project default. |\n| `{second_opinion}` | Runs AI generation through a different provider than the default, acting as a cross-check. Set to `"auto"` to let Bridge pick the second provider automatically. When set, it takes precedence over `{provider}`. Use this when you want two independent AI perspectives on the same task \u2014 for example, running clarifying questions and a critique twice (once with each provider) produces better results than a single pass. |\n\nSee `.bridge/pipelines/README.md` for the full schema reference.\n\nIf a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).\n\n## Smoke testing\n\nThe package ships a canonical, **opt-in** in-host smoke-test runbook at\n`smoke-test/SMOKE-TEST.md`. An AI agent running inside your host (Claude Code,\nCursor, Codex, Windsurf, or VS Code/Copilot) executes it to verify that the MCP\nserver actually works end-to-end *inside that host* \u2014 it calls the real tools and\nrecords a PASS/FAIL verdict for each one in a markdown report.\n\n- `smoke-test/SMOKE-TEST.md` **ships with the npm package** and is the\n  **canonical** source of truth for the smoke test.\n- The smoke test **adds no MCP tool** and **does not change the registered\n  tool surface** (the server still registers its existing 62 tools).\n- It is **opt-in**: default `--init` **does not scaffold `/smoke-test-mcp`**, so\n  consumer command palettes are not polluted.\n\n### Running it\n\nYou have two options:\n\n1. **Copy the opt-in command manually.** Copy the packaged command stub into your\n   host\'s command directory, then invoke `/smoke-test-mcp`:\n\n   ```bash\n   # Claude Code\n   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .claude/commands/smoke-test-mcp.md\n   # Cursor\n   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .cursor/commands/smoke-test-mcp.md\n   ```\n\n2. **Open the runbook directly.** Alternatively, open\n   `smoke-test/SMOKE-TEST.md` and ask the host agent to execute it.\n\nReports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`.\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `BAPI_BASE_URL` | Yes | `https://bridgegpt-api.com` | Bridge API base URL |\n| `BAPI_REPO_NAME` | Yes | _(none)_ | Jira project/repository identifier configured in Bridge API |\n| `BAPI_API_KEY` | Yes | _(none)_ | API key obtained from the Bridge API setup UI |\n| `BAPI_PROJECT_ROOT` | No | _(auto-set by --init)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution |\n| `BAPI_DOCS_DIR` | No | `docs/tmp` | Local directory for saving plans, critiques, and research reports |\n| `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |\n| `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |\n| `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |\n| `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation \u2014 it only gates the recipe-preamble convention |\n| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile. Controls which tool groups are registered when the server starts. Valid values: `core` (default \u2014 normal coding tools only), `conductor` (core + 8 conductor/event/supervisor tools), `pipeline-authoring` (core + 5 pipeline run/admin tools \u2014 `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `full` (all tools, equivalent to the legacy unconditional registration). Unknown, blank, or malformed values fail safe to `core`. Dynamic mid-session switching via `tools/list_changed` is unsupported \u2014 the profile is resolved once at process startup. **Phase 2b note:** epic/conductor sessions launched via `start-tickets` will automatically inject `BRIDGE_MCP_PROFILE=conductor`; that injection is handled at the spawn boundary and is out of scope for this phase. |\n\n## Worktree credentials and the `mcp-invoke` shim\n\nWhen `start-tickets` creates a git worktree, it provisions a Bridge API MCP\nregistration into that worktree so Claude Code (`.mcp.json`) and Cursor\n(`.cursor/mcp.json`) can reach the server immediately. These registrations are\n**secret-free**: they contain no `env` block and no API key. Instead they point\nat an internal subcommand of the published single CLI bin, `mcp-invoke`:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@<VERSION> mcp-invoke --target bapi --project-root <ABS_WORKTREE_PATH>\n```\n\n`mcp-invoke` is not a separate binary \u2014 it is a positional subcommand of\n`bridge-api-mcp-server`. It resolves the repo identity from the absolute\n`--project-root` (the committed `.bridge/config` manifest, falling back to the\ngit common dir), resolves credentials from the home-directory credential store,\nand then spawns the real MCP server with that environment.\n\n### Credential store\n\nCredentials live outside the repository, keyed by `bapi:<repo_name>`:\n\n```json\n{\n  "bapi:<repo_name>": {\n    "BAPI_API_KEY": "..."\n  }\n}\n```\n\nResolution order:\n\n1. `BAPI_API_KEY` in the parent environment (overrides the file entirely).\n2. `$XDG_CONFIG_HOME/bridge/credentials.json`, else `~/.config/bridge/credentials.json`.\n3. `~/.bridge/credentials.json` (only when the primary path is absent).\n\nOn POSIX systems, lock the file down so only you can read it:\n\n```bash\nchmod 600 ~/.config/bridge/credentials.json\n```\n\n`mcp-invoke` warns (but continues) if the file is group/world-readable, and it\nnever creates or initializes the credential file for you.\n\n### Populating the credential store\n\nThe same store also backs the shell-spawned `start-tickets` CLI (its\ndifficulty\u2192model routing runs in a Bash process that cannot see an `env` block in\n`.mcp.json` / `.cursor/mcp.json`), so the store must hold the key for routing to\nwork. Two supported paths write it for you:\n\n- **Install-time upsert.** `/install-bridge`\'s final stage persists the validated\n  routing credential into `~/.config/bridge/credentials.json` (target\n  `bapi:<repo>`) via the `persist_routing_credential` MCP tool \u2014 the tool resolves\n  the key inside the MCP process and writes the store, so no secret crosses the\n  wire.\n- **One-shot migration.** If a key currently lives only in `.mcp.json` /\n  `.cursor/mcp.json`, migrate it into the user-scoped store with the consent-gated\n  command (a compatibility aid, not a live fallback):\n\n  ```bash\n  npx -y @bridge_gpt/mcp-server credentials migrate-agent-config [--write-credentials]\n  ```\n\n  Run it without `--write-credentials` to preview; add the flag to write the store.\n\n## Reference\n\nThe full surface, for when you need the complete enumeration. Day-to-day, use [Usage Documentation](#usage-documentation) instead \u2014 you don\'t call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.\n\n### MCP tools\n\nThe server registers **58 tools**. Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).\n\n- **Connectivity & identity** \u2014 `ping`, `get_my_role`, `get_docs_dir`\n- **Jira tickets** \u2014 `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`\n- **Attachments** \u2014 `attachment` (operations: `upload`, `download`, `list`)\n- **AI generation (request/get)** \u2014 `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`\n- **Other AI** \u2014 `second_opinion`, `generate_image`, `generate_decision_page`\n- **Ticket lifecycle** \u2014 `track_ticket`, `update_ticket_state`, `get_ticket_state`\n- **Jira status** \u2014 `get_jira_transitions`, `update_jira_status`, `resolve_target_status`\n- **Repository & CI** \u2014 `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`\n- **Pipelines & automation** \u2014 `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`\n- **Config** \u2014 `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)\n\n### Bundled pipelines\n\nPipelines are declarative, multi-step workflows your AI agent executes step-by-step \u2014 each a JSON recipe chaining MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. You can also write your own (see [Custom Pipelines](#custom-pipelines)).\n\n| Pipeline | Description | Invoke with |\n|---|---|---|\n| `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |\n| `review-ticket` | Full ticket quality review: initial clarifying questions + critique, automatic second-opinion pass (default), then evaluation and decision capture. Pass `--rounds=1` to skip the second-opinion step (`--rounds=2` is the default). | `/review-ticket PROJ-123` |\n| `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |\n| `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |\n| `full-automation` | Chain: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement | `/full-automation "<idea>"` |\n| `pr-ticket` | Commit changes and open a pull request | `/create-pr PROJ-123` |\n| `check-ci-ticket` | Commit, open a PR, then monitor CI checks until they pass or fail | `/check-ci PROJ-123` |\n| `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |\n\n### Pipeline response envelope\n\n`run_pipeline`, `resume_pipeline`, and `list_pipeline_runs` share a unified envelope keyed on `status`:\n\n- `completed` \u2014 terminal success; `results` holds per-step output.\n- `needs_agent_task` \u2014 the orchestrator paused. Read `instruction`, perform the task, then call `resume_pipeline` with `pipeline_run_id` and a string `agent_result`.\n- `failed` \u2014 terminal failure. `error_code` is one of `VALIDATION`, `NOT_FOUND`, `EXPIRED`, `REPO_MISMATCH`, `TOOL_ERROR`.\n\nPaused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition. List output is metadata-only \u2014 it never includes resolved recipes, params, instructions, results, or agent outputs.\n';
+var README = '# @bridge_gpt/mcp-server\n\nThe Bridge MCP is an end-to-end accelerator for shipping code within SFCC, powered by [Bridge API](https://bridgegpt-api.com). Works with Claude Code, Github Copilot, Cursor, Windsurf, and OpenAI Codex.\n\n## Contents\n\n- [Getting Started](#getting-started)\n- [Usage Documentation](#usage-documentation)\n  - [Tier 1 \u2014 Regularly useful](#tier-1--regularly-useful)\n  - [Tier 2 \u2014 Occasionally useful](#tier-2--occasionally-useful)\n  - [Tier 3 \u2014 Now and then](#tier-3--now-and-then)\n  - [Operational commands](#operational-commands)\n  - [Extra Capabilities](#extra-capabilities)\n- [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)\n- [CLI Subcommands](#cli-subcommands)\n- [Custom Pipelines](#custom-pipelines)\n- [Environment Variables](#environment-variables)\n- [Worktree credentials and the `mcp-invoke` shim](#worktree-credentials-and-the-mcp-invoke-shim)\n- [Reference](#reference)\n\nFor advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./CONDUCTOR.md).\n\n## Getting Started\n\n### Quick start\n\nFrom your **project root**, install and connect in one command:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge\n```\n\n`install-bridge` scaffolds the project, writes your editor\'s MCP config with real\nvalues, verifies connectivity, persists your API key to the user-scoped credential\nstore, and opens a fresh agent session to finish setup (`/install-bridge` then\n`/learn-repository`). The only inputs are an **API key** (generate one on the Bridge\nAPI web UI **Security** page) and a **repo name** \u2014 everything else is derived. Add\n`--dry-run` to preview every step without writing, pinging, or spawning anything.\n\nTo upgrade later, run:\n\n```bash\nnpx -y @bridge_gpt/mcp-server upgrade\n```\n\n`upgrade` re-execs from `@latest`, refreshes all scaffolded artifacts (slash\ncommands, agents, pipelines), rewrites the version pin, and reconnects \u2014 also\navailable as the `/upgrade-bridge` slash command. (The legacy `--upgrade` flag still\nworks as a fallback.)\n\n<details>\n<summary><strong>Installation Instructions</strong></summary>\n\n#### What `install-bridge` does\n\n`install-bridge` collapses the whole setup into a single command. It:\n\n1. **Scaffolds** the project (the same artifacts `--init` writes: slash commands,\n   agents, `.bridge/pipelines/`, and secret-free MCP config placeholders).\n2. **Writes the per-host MCP config** (`.mcp.json` / `.cursor/mcp.json` /\n   `.vscode/mcp.json`) with your real `BAPI_REPO_NAME` / `BAPI_API_KEY` /\n   `BAPI_BASE_URL` / `BAPI_DOCS_DIR`, preserving any unrelated servers. The\n   launcher it writes is pinned to the exact installed version so `npx` never\n   silently reuses a stale local copy. (Windsurf and Codex are global configs it\n   can\'t safely write \u2014 it prints copy-paste instructions for those.)\n3. **Verifies connectivity** against the Bridge API before persisting anything.\n4. **Persists your key** to the user-scoped credential store\n   (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned\n   tooling (e.g. `start-tickets`) can resolve it.\n5. **Opens a fresh agent session** that runs `/install-bridge` (to derive the\n   remaining config fields from your codebase) and then `/learn-repository`.\n\nThe only inputs are an **API key** and a **repo name** (everything else is\nderived). Resolution order:\n\n- **API key:** `--api-key <key>` \u2192 `BAPI_API_KEY` env \u2192 an interactive (no-echo)\n  prompt. Generate one first on the Bridge API web UI **Security** page (see\n  [Generate an API Key](#2-generate-an-api-key)); the command consumes a key, it\n  never mints one. The key is **never printed or logged**.\n- **Repo name:** `--repo <name>` \u2192 `BAPI_REPO_NAME` env \u2192 an inferred default you\n  confirm interactively. It MUST match the server-side repository registration.\n\nUseful flags:\n\n- `--dry-run` \u2014 preview every step (scaffold targets, config files and keys with\n  the key value **redacted**, the ping target, the credential store target, and\n  the exact agent spawn command) without writing, pinging, or spawning anything.\n- `--force` \u2014 overwrite an existing real `BAPI_API_KEY` in a host config without\n  prompting (re-running is otherwise non-destructive).\n- `--agent claude|cursor-agent` \u2014 which agent to launch for the agentic remainder\n  (default `claude`).\n\nThat\'s it \u2014 once `install-bridge` finishes you\'re connected. If you prefer to do\nit by hand (or just want to understand each step), the manual flow below does the\nsame thing.\n\n#### Manual Setup (Alternative)\n\n##### 1. Install the Package\n\nFrom your **project root**, install the MCP server and scaffold slash commands:\n\n```bash\nnpm i @bridge_gpt/mcp-server\nnpx -y @bridge_gpt/mcp-server --init\n```\n\n`--init` must be run from the directory containing your `package.json`. It:\n\n- Creates slash commands in `.claude/commands/` and `.cursor/commands/`\n- Detects existing MCP config files and sets `BAPI_PROJECT_ROOT` so local file output resolves correctly\n- Scaffolds `.bridge/pipelines/` for custom pipeline authoring\n\nRe-run `--init` after upgrading the package to get updated commands.\n\n##### 2. Generate an API Key\n\n1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project\'s **Security** page\n2. Click **Create New Key**\n3. Enter your email, an optional label (e.g., "MCP Server"), and select the **Admin** role\n4. Click **Create Key**\n5. **Copy the key immediately** \u2014 it will not be shown again\n\n##### 3. Configure the MCP Server\n\nAdd the following to your editor\'s MCP configuration file, pasting in the API key from step 2:\n\n<details>\n<summary><strong>Claude Code (.mcp.json)</strong></summary>\n\nThe `--init` command (step 1) detects Claude Code and creates a `.mcp.json` at your project root with placeholder values. Open it and replace `your-repo` and `your-api-key` with your actual values from step 2:\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code / Copilot (.vscode/mcp.json)</strong></summary>\n\n```json\n{\n  "servers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor (.cursor/mcp.json)</strong></summary>\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n\n> If project-local config is not supported in your Cursor version, use `~/.cursor/config/mcp.json` instead.\n</details>\n\n<details>\n<summary><strong>Windsurf (~/.codeium/windsurf/mcp_config.json)</strong></summary>\n\nWindsurf only supports global MCP configuration.\n\n```json\n{\n  "mcpServers": {\n    "bridge-api": {\n      "command": "npx",\n      "args": ["-y", "@bridge_gpt/mcp-server"],\n      "env": {\n        "BAPI_BASE_URL": "https://bridgegpt-api.com",\n        "BAPI_REPO_NAME": "your-repo",\n        "BAPI_API_KEY": "your-api-key",\n        "BAPI_DOCS_DIR": "docs/tmp"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>OpenAI Codex (~/.codex/config.toml)</strong></summary>\n\n```toml\n[mcp_servers.bridge-api]\ncommand = "npx"\nargs = ["-y", "@bridge_gpt/mcp-server"]\n\n[mcp_servers.bridge-api.env]\nBAPI_BASE_URL = "https://bridgegpt-api.com"\nBAPI_REPO_NAME = "your-repo"\nBAPI_API_KEY = "your-api-key"\nBAPI_DOCS_DIR = "docs/tmp"\n```\n\n> Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see Environment Variables below).\n</details>\n\nAfter saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the `ping` tool.\n\n##### 4. First-Time Setup: Teach Bridge Your Codebase\n\nIf you\'re the first person to install Bridge API on your project, run the `/learn-repository` slash command after completing setup. This analyzes your codebase\'s architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project\'s actual architecture and conventions.\n\nYou only need to do this once per project \u2014 the learned standards persist for all team members.\n\n##### Upgrading (details)\n\nThe one-command `npx -y @bridge_gpt/mcp-server upgrade` (shown above) is the\nrecommended path. The legacy flag `npx -y @bridge_gpt/mcp-server --upgrade` still\nworks: it runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version\nsummary, then re-runs the full `--init` scaffolding flow to update your slash\ncommands, agents, and pipeline definitions.\n\nThe MCP server also checks for updates automatically on startup. If a newer version is available, you\'ll see a notice in your editor\'s MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.\n\n</details>\n\n## Usage Documentation\n\nThis is the Bridge API tooling worth knowing about as a software engineer \u2014 the things you\'d ask an agent to do \u2014 grouped by how often you would use them. Each entry covers **what it does**, **when it\'s useful** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).\n\nWorking in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools \u2014 see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).\n\nFor invocation, prefer the slash command \u2014 it\'s deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.\n\n### Tier 1 \u2014 Regularly useful\n\nThese features are useful for most tickets.\n\n**1. Review Ticket**\n- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique (initial round), an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The second-opinion pass is included by default and can be skipped with `--rounds=1`.\n- **When it\'s useful:** (Refinement) Right after a ticket is drafted, before anyone starts building \u2014 to surface gaps and tighten it.\n- **How to use it:** `/review-ticket BAPI-123` (command only \u2014 "review" as free text is easily mistaken for a freehand agent review).\n- **Flags:** `--auto` auto-accept findings / skip the approval gates \xB7 `--rounds=1` skip the automatic second-opinion review step while preserving downstream evaluation and decision-capture work (cheaper single-pass review). `--rounds=2` (default) runs the full two-round review.\n- **Multi-ticket fan-out:** `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only \u2014 no `wt`/`git`). All `/review-ticket` flags apply; `--review KEY=auto,rounds=N` sets per-ticket overrides. Packaged CLI: `npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...]`.\n\n**2. Start Tickets**\n- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.\n- **When it\'s useful:** (Implementation | Automation) When you\'re ready to start building one or more refined tickets concurrently.\n- **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).\n- **Flags:** `--auto` skip the approval gates \xB7 `--base-branch <branch>` branch off something other than the default.\n\n**3. Brainstorm**\n- **What it does:** Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of three modes, selected via `mode`: **`technical`** (default \u2014 implementation/architecture approaches), **`design`** (UI/UX and visual direction), or **`discovery`** (stakeholder discovery questions for early/vague tasks, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`). Discovery needs no extra configuration. The legacy boolean `design=true` still works and maps to `mode: "design"`.\n- **When it\'s useful:** (Architecture | Refinement) Early, when you want a spread of approaches \u2014 `technical` for *how to build it*, `design` for *how it should look*, `discovery` for *what we still need to figure out* before a real ticket exists.\n- **How to use it:** ask your agent to brainstorm \u2014 *"Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models."* For a design pass: *"Run a design brainstorm for the evidence-freshness dashboard UI."* For early discovery: *"Run a discovery brainstorm \u2014 `request_brainstorm` with `mode: "discovery"` \u2014 for this vague request so we can collect the questions stakeholders need to answer first."*\n\n**4. Deep Research**\n- **What it does:** Runs multi-source, fact-checked web research on a technical topic and returns a cited report.\n- **When it\'s useful:** (Architecture | Refinement) When a decision hinges on outside knowledge (libraries, best practices, standards) you don\'t already have.\n- **How to use it:** `/bridge-research <question>`\n\n**5. Jira Ticket Writer**\n- **What it does:** An agent that drafts a well-structured Jira ticket from a plain description, applying your project\'s standards.\n- **When it\'s useful:** (Refinement) When you have an idea in your head and want a properly-formatted ticket draft without writing it by hand.\n- **How to use it:** `/write-ticket <description>` (or ask your agent) \u2014 *"Use the jira ticket writer to turn our conversation into a ticket."*\n- **Flags:** `--standards <path>` apply a specific standards file when drafting.\n\n**6. Upload Ticket**\n- **What it does:** Pushes a drafted ticket up to Jira as a real issue (the `create_ticket` capability); handles markdown and child tickets under an Epic.\n- **When it\'s useful:** (Refinement) The final step after drafting \u2014 to get the ticket into Jira so it can be tracked and worked.\n- **How to use it:** Ask your agent to create the ticket, and it should confirm before creating the live Jira issue.\n- **Options:** Describe the issue type (Bug / Story / Task / Epic) and, for a child under an Epic, the parent key.\n\n### Tier 2 \u2014 Occasionally useful\n\nThese features are good to know, but you probably won\'t use them every day.\n\n**1. Plan Ticket**\n- **What it does:** Generates a step-by-step implementation plan for a ticket, with references to real code files, and saves it locally.\n- **When it\'s useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before (or instead of) auto-implementing.\n- **How to use it:** `/plan-ticket BAPI-123`\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check the plan with a second provider.\n\n**2. Clarify Ticket**\n- **What it does:** Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.\n- **When it\'s useful:** (Refinement) When a ticket feels under-specified and you want the open questions made explicit.\n- **How to use it:** `/clarify-ticket BAPI-123` \u2014 *"Generate clarifying questions for BAPI-123"*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**3. Critique Ticket**\n- **What it does:** Critiques a ticket\'s quality against your project standards and lists deviations + improvements.\n- **When it\'s useful:** (Refinement) When you want a quality gate on a ticket before it\'s worked.\n- **How to use it:** `/critique-ticket BAPI-123` \u2014 *"Critique BAPI-123 against our project standards and list what\'s missing or deviating."*\n- **Flags:** `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**4. Create Doc**\n- **What it does:** Generates a design document for a ticket \u2014 a TDD (technical design, engineer audience), an FSD (functional spec, for product/design/QA), or a PRD (product requirements: problem, goals, success metrics) \u2014 and saves it locally.\n- **When it\'s useful:** (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.\n- **How to use it:** `/create-doc BAPI-123 --doc-type tdd` (or `fsd` / `prd`)\n- **Flags:** `--doc-type tdd|fsd|prd` which document to generate (required) \xB7 `--provider <name>` choose the model provider \xB7 `--second-opinion <provider>` cross-check with a second provider.\n\n**5. Explore Ticket**\n- **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.\n- **When it\'s useful:** (Architecture | Refinement) Before writing a ticket or plan, when you\'re unsure how a change would fit the existing code.\n- **How to use it:** `/explore-ticket <task>` \u2014 *"Explore the codebase for how we\'d add a Mistral LLM provider and recommend 2\u20133 implementation options."*\n\n**6. Second Opinion**\n- **What it does:** Gets an immediate critique of any text from a different model family \u2014 no artifact saved, just the reply.\n- **When it\'s useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.\n- **How to use it:** ask your agent \u2014 *"Get a second opinion from Gemini on whether the BAPI-123 plan\'s migration step is safe to run against prod."*\n- **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).\n\n**7. Generate Image**\n- **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.\n- **When it\'s useful:** (Architecture | Refinement) When you want a quick visual \u2014 a UI mockup, diagram, or illustration \u2014 to anchor a design discussion or attach to a ticket.\n- **How to use it:** ask your agent \u2014 *"Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."*\n- **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen \u2014 adds an invisible SynthID watermark) \xB7 `quality` low (default, cheapest) / medium / high \xB7 `size` 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to `BAPI_DOCS_DIR/images/` and also returned inline.\n\n**8. Implement Ticket**\n- **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.\n- **When it\'s useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.\n- **How to use it:** `/implement-ticket BAPI-123` (command only \u2014 "implement X" as free text almost always triggers a freehand build instead of the Bridge plan\u2192code\u2192PR\u2192CI pipeline).\n- **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).\n\n**9. Full Automation**\n- **What it does:** Drives the whole chain end-to-end: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement.\n- **When it\'s useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.\n- **How to use it:** `/full-automation <idea>` (command only \u2014 creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can\'t).\n- **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.\n\n**10. Idea to Ticket**\n- **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.\n- **When it\'s useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.\n- **How to use it:** `/idea-to-ticket <idea>`\n\n### Tier 3 \u2014 Now and then\n\nThese features are useful once in a while, but you probably won\'t need them everyday.\n\n**1. Reimplement Ticket**\n- **What it does:** Pulls in new context/attachments since the last pass and implements small follow-up changes on an already-built ticket.\n- **When it\'s useful:** (Implementation) After review feedback or new screenshots, when you need a targeted second pass rather than a fresh build.\n- **How to use it:** `/reimplement-ticket BAPI-123`\n\n**2. Run Tests**\n- **What it does:** Runs the unit and E2E suites and autonomously triages/fixes failures (via the test-correction agent).\n- **When it\'s useful:** (Implementation) After making changes, to confirm everything passes and auto-fix straightforward breakages.\n- **How to use it:** `/run-tests` (`--unit-only`, `--skip-e2e`)\n\n**3. Plan Epic**\n- **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.\n- **When it\'s useful:** (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.\n- **How to use it:** `/plan-epic <epic>` \u2014 *"Decompose the epic \'migrate PayPal token storage off Custom Objects\' into sub-tasks with an exploration doc for each."*\n\n**4. Update Ticket**\n- **What it does:** Synthesizes a ticket\'s clarifying answers and critique into a rewritten description and pushes it to Jira.\n- **When it\'s useful:** (Refinement) After review, to fold the resolved questions and fixes back into the ticket itself.\n- **How to use it:** `/update-ticket BAPI-123` (command only \u2014 does a full overwrite of the live Jira description; "update" as free text is both vague and hard to reverse).\n\n**5. Get Ticket**\n- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).\n- **When it\'s useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.\n- **How to use it:** ask your agent \u2014 *"Pull up BAPI-123 and show me its description, status, and acceptance criteria."*\n\n**6. Write Comment**\n- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).\n- **When it\'s useful:** (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.\n- **How to use it:** ask your agent \u2014 *"Post a comment on BAPI-123: blocked on the expired Atlassian token \u2014 will retry after it\'s rotated."*\n\n**7. Download / Upload Attachment**\n- **What it does:** Pulls files off a Jira ticket to disk, or attaches a local file to a ticket.\n- **When it\'s useful:** (Refinement | Implementation) When a ticket has design files/logs you need locally, or you want to attach output back to it.\n- **How to use it:** ask your agent \u2014 *"Download the design mockups attached to BAPI-123 into my docs folder."* / *"Attach build-log.txt to BAPI-123."*\n\n**8. Learn Repository**\n- **What it does:** Researches and documents the repo\'s architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.\n- **When it\'s useful:** (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge\'s agents follow your conventions.\n- **How to use it:** `/learn-repository`\n\n**9. Teach Bridge**\n- **What it does:** Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).\n- **When it\'s useful:** (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.\n- **How to use it:** `/teach-bridge <teaching>` \u2014 *"Teach Bridge: always use data-testid selectors in E2E tests."*\n\n### Operational commands\n\nWorkflow commands you\'ll reach for during implementation and CI, beyond the tiers above:\n\n| Command | What it does |\n|---|---|\n| `/code-ticket PROJ-123` | Download the implementation plan and questions, then execute the plan inline |\n| `/commit-ticket PROJ-123` | Stage, commit, and push changes; transition Jira status; post a smoke-test comment |\n| `/create-pr PROJ-123` | Commit staged changes and open a pull request |\n| `/check-ci [PROJ-123]` | Monitor CI checks for the current branch, triage failures, apply fixes, and report results |\n| `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |\n| `/check-parse-status` | Check whether a background repository parse job is still running |\n| `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |\n\n> Commands are designed for Claude Code. Other editors may support slash commands differently \u2014 check your editor\'s documentation for how to invoke prompt files.\n\n### Extra Capabilities\n\nBehind-the-scenes capabilities an agent gains from the MCP tools \u2014 mostly invoked automatically by the commands above, rarely requested by name:\n\n- **Ship a PR end-to-end:** commit & push, open a pull request, transition the Jira status, and discover/poll CI checks (powers `commit-ticket`, `create-pr`, `check-ci`, `implement-ticket`).\n- **Architecture plan** for a ticket (design-level guidance, separate from the implementation plan).\n- **Index the codebase** so Bridge\'s agents can reason about it: queue/parse the repo, check parse status, regenerate the directory map.\n- **Read & tune project config/standards:** list/read/update config fields, fetch project standards, and the per-topic `learn-*` commands that populate them.\n- **Ticket lifecycle bookkeeping:** track tickets and backfill workflow-state timestamps (`scan-tickets`), search across tickets, read comments, list attachments.\n- **Pipeline machinery:** list/inspect pipeline recipes and run/resume/list/delete pipeline runs (the engine under the orchestration commands).\n- **Decision page** generation for capturing human review decisions as structured data.\n- **Connectivity & identity checks:** ping Bridge, check your role, resolve the local docs directory.\n- **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, brainstorms, research, architecture) without regenerating it.\n- **Tiered-section execution telemetry** recording (internal measurement).\n\n## Salesforce B2C Commerce (SFCC) Tools\n\nSalesforce\'s official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks \u2014 cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform\'s object model, custom objects, or site configuration \u2014 exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge\'s SFCC tools install side-by-side with `b2c-dx-mcp` (they don\'t duplicate its surface) and close that gap with **read-only OCAPI Data API introspection** of system objects, custom object definitions, and site preferences.\n\n**v1 is read-only and developer-sandbox-only** \u2014 no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.\n\n<details>\n<summary><strong>Setup</strong></summary>\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The seven read tools must be enabled with a profile (step 3).\n\n**Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).\n\n**1. Set the repo `version` config field** to your SFCC project type \u2014 one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.\n\n**2. Provide SFCC credentials.** Create a `dw.json` in your project root:\n\n```json\n{\n  "hostname": "zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com",\n  "client-id": "<account-manager-client-id>",\n  "client-secret": "<account-manager-client-secret>"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config \u2014 a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n**3. Enable the read tools.** Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated; `full` also works), then **restart the MCP client**:\n\n```json\n"env": { "BRIDGE_MCP_PROFILE": "sfcc" }\n```\n\nWithout this, only the diagnostic tools are registered.\n\n**4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks \u2713), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration \u2192 Site Development \u2192 Open Commerce API Settings \u2192 Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change \u2014 a running session does not pick them up.\n\n</details>\n\n### Tools\n\nAll SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.\n\n**Diagnostics** (always available, no profile needed)\n- `sfcc_setup_status` \u2014 report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, and AM token acquisition.\n- `check_permissions` \u2014 probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).\n\n**System object model** (needs the `sfcc` profile)\n- `system_object_list` \u2014 list system object types (Product, Order, Customer, \u2026).\n- `system_object_get` \u2014 fetch one type\'s definition, optionally with its full attribute definitions (`expand_attribute_definitions`).\n- `system_object_attribute_search` \u2014 search a type\'s attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.\n\n**Custom object definitions** (needs the `sfcc` profile)\n- `custom_object_definition_list` \u2014 list custom object type definitions.\n- `custom_object_definition_get` \u2014 fetch an existing custom type with its key definition and attribute definitions/groups. Read-only \u2014 creating a custom object *type* isn\'t possible via OCAPI; that\'s a future v2 metadata-import capability.\n\n**Site preferences** (needs the `sfcc` profile; sandbox only)\n- `site_preference_get` \u2014 read a preference group\'s effective preferences.\n- `site_preference_search` \u2014 search/filter preferences within a group.\n\n## CLI Subcommands\n\nBeyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) \u2014 so they travel with the package to every consumer. See [Usage Documentation \u2192 Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.\n\n### `start-tickets`\n\nSpawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`.\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--agent claude\\|cursor-agent` | `claude` | Agent command to launch in each worktree |\n| `--terminal terminal\\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |\n| `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |\n| `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |\n| `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |\n| `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility \u2014 despite the name, it now skips refresh of whatever `--base-branch` resolves to. |\n| `--max-parallel N` | `3` | Max worktrees created concurrently |\n| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, a supervisor peer tab, and the `check_messages` message-relay prompt). **Default off** \u2014 a plain run spawns `cd <worktree> && <agent> \'/implement-ticket <KEY>\'`. |\n| `-h`, `--help` | \u2014 | Show usage |\n\nEach `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent\'s `\'/implement-ticket <KEY>\'` \u2014 `claude \'/implement-ticket <KEY>\'` by default, or `cursor-agent \'/implement-ticket <KEY>\'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:\n\n```\nnpx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248\n```\n\n**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket\'s `difficulty` (1-2 \u2192 cheap, 3-5 \u2192 basic, 6+ \u2192 premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier \u2192 alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all omit `--model` (the agent uses its default) and surface a per-ticket warning rather than failing the spawn. `--dry-run` does **not** fetch tiers or inject `--model`.\n\n**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort \u2014 a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.\n\n**Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.\n\n- **macOS** \u2014 opens a Terminal.app or iTerm tab via `osascript`.\n- **Windows** \u2014 creates worktrees with **`git-wt`** (Worktrunk\'s winget alias) and opens a tab via **Windows Terminal (`wt.exe new-tab`)**, falling back to **`Start-Process powershell.exe`** when Windows Terminal is absent. Requires **Git for Windows / Git Bash** (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash). The Worktrunk binary (`git-wt`) and the tab launcher (`wt.exe`) are resolved independently and never conflated.\n- **Linux** \u2014 creates one detached **tmux** session per ticket (pane kept open after the agent exits); attach with `tmux attach -t <session>`. A missing `tmux` produces a clear, actionable error.\n\nPer-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` \u2014 Worktrunk\'s `pre-start` hook runs `uv`, but live preflight does not check it \u2014 and the selected agent\'s command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).\n\n### `doctor`\n\nThe package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:\n\n```\nnpx -y @bridge_gpt/mcp-server doctor [--agent <name>]\n```\n\nIt is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent\'s command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.\n\n### Conductor (epic & multi-agent orchestration)\n\nConductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference \u2014 `conductor install-git-hooks`, the `conductor_done_gate` and `conductor_auto_merge_enabled` config fields, and the observability stream \u2014 lives in **[CONDUCTOR.md](./CONDUCTOR.md)**.\n\n## Custom Pipelines\n\nYou can create your own pipelines by adding JSON files to `.bridge/pipelines/`. Running `--init` scaffolds this directory with a `README.md` and an example pipeline to get you started.\n\nThe easiest way to write a custom pipeline is to describe what you want to automate to your AI coding agent and have it draft the JSON for you. The schema is straightforward, and agents like Claude Code understand it well \u2014 just describe the steps you want, and the agent will produce a working pipeline file.\n\n**What you can build:**\n\n- Any sequence of Bridge MCP tool calls and free-form agent tasks\n- Parameterized workflows using variables (e.g., `{ticket_key}`)\n- Approval gates that pause for user confirmation before sensitive steps\n- Per-step error handling \u2014 halt immediately or warn and continue\n\n**Ideas for custom pipelines:**\n\n- A standup pipeline that fetches your open tickets and summarizes their status\n- A ticket triage pipeline that runs critiques on a batch of new tickets\n- A pre-merge checklist that runs tests, checks linting, and posts a summary comment\n\n**Step types:**\n\n| Type | What it does |\n|---|---|\n| `mcp_call` | Calls an MCP tool with the given params |\n| `agent_task` | Gives the AI a free-form instruction (inline or from a file in `.bridge/instructions/`) |\n\nVariables are declared in the `variables` array and referenced as `{variable_name}` in params and instructions. Each step supports `on_error: "halt"` (default) or `"warn_and_continue"`, and `requires_approval: true` to pause before execution.\n\n**System variables:**\n\nTwo variables are automatically available in every pipeline without declaring them:\n\n| Variable | What it does |\n|---|---|\n| `{provider}` | Routes AI generation to a specific LLM provider (`openai`, `anthropic`, or `gemini`). Pass it through to any `request_*` tool param to control which provider handles that step. Omit it (or leave it empty) to use the project default. |\n| `{second_opinion}` | Runs AI generation through a different provider than the default, acting as a cross-check. Set to `"auto"` to let Bridge pick the second provider automatically. When set, it takes precedence over `{provider}`. Use this when you want two independent AI perspectives on the same task \u2014 for example, running clarifying questions and a critique twice (once with each provider) produces better results than a single pass. |\n\nSee `.bridge/pipelines/README.md` for the full schema reference.\n\nIf a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `BAPI_BASE_URL` | Yes | `https://bridgegpt-api.com` | Bridge API base URL |\n| `BAPI_REPO_NAME` | Yes | _(none)_ | Jira project/repository identifier configured in Bridge API |\n| `BAPI_API_KEY` | Yes | _(none)_ | API key obtained from the Bridge API setup UI |\n| `BAPI_PROJECT_ROOT` | No | _(auto-set by --init)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution |\n| `BAPI_DOCS_DIR` | No | `docs/tmp` | Local directory for saving plans, critiques, and research reports |\n| `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |\n| `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |\n| `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |\n| `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation \u2014 it only gates the recipe-preamble convention |\n| `CURSOR_API_KEY` | No | _(none)_ | API key used to authenticate `cursor-agent` when launching `start-tickets`/scheduled runs with `--agent cursor-agent`. Not needed for the default Claude Code agent |\n| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile \u2014 a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default \u2014 normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools \u2014 `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 7 heavy SFCC read tools \u2014 see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), and `full` (shortcut that expands to every group). Example: `sfcc,conductor`. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported \u2014 groups are resolved once at process startup. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |\n\n## Worktree credentials and the `mcp-invoke` shim\n\nWhen `start-tickets` creates a git worktree, it provisions a Bridge API MCP\nregistration into that worktree so Claude Code (`.mcp.json`) and Cursor\n(`.cursor/mcp.json`) can reach the server immediately. These registrations are\n**secret-free**: they contain no `env` block and no API key. Instead they point\nat an internal subcommand of the published single CLI bin, `mcp-invoke`:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@<VERSION> mcp-invoke --target bapi --project-root <ABS_WORKTREE_PATH>\n```\n\n`mcp-invoke` is not a separate binary \u2014 it is a positional subcommand of\n`bridge-api-mcp-server`. It resolves the repo identity from the absolute\n`--project-root` (the committed `.bridge/config` manifest, falling back to the\ngit common dir), resolves credentials from the home-directory credential store,\nand then spawns the real MCP server with that environment.\n\n### Credential store\n\nCredentials live outside the repository, keyed by `bapi:<repo_name>`:\n\n```json\n{\n  "bapi:<repo_name>": {\n    "BAPI_API_KEY": "..."\n  }\n}\n```\n\nResolution order:\n\n1. `BAPI_API_KEY` in the parent environment (overrides the file entirely).\n2. `$XDG_CONFIG_HOME/bridge/credentials.json`, else `~/.config/bridge/credentials.json`.\n3. `~/.bridge/credentials.json` (only when the primary path is absent).\n\nOn POSIX systems, lock the file down so only you can read it:\n\n```bash\nchmod 600 ~/.config/bridge/credentials.json\n```\n\n`mcp-invoke` warns (but continues) if the file is group/world-readable, and it\nnever creates or initializes the credential file for you.\n\n### Populating the credential store\n\nThe same store also backs the shell-spawned `start-tickets` CLI (its\ndifficulty\u2192model routing runs in a Bash process that cannot see an `env` block in\n`.mcp.json` / `.cursor/mcp.json`), so the store must hold the key for routing to\nwork. Two supported paths write it for you:\n\n- **Install-time upsert.** `/install-bridge`\'s final stage persists the validated\n  routing credential into `~/.config/bridge/credentials.json` (target\n  `bapi:<repo>`) via the `persist_routing_credential` MCP tool \u2014 the tool resolves\n  the key inside the MCP process and writes the store, so no secret crosses the\n  wire.\n- **One-shot migration.** If a key currently lives only in `.mcp.json` /\n  `.cursor/mcp.json`, migrate it into the user-scoped store with the consent-gated\n  command (a compatibility aid, not a live fallback):\n\n  ```bash\n  npx -y @bridge_gpt/mcp-server credentials migrate-agent-config [--write-credentials]\n  ```\n\n  Run it without `--write-credentials` to preview; add the flag to write the store.\n\n## Reference\n\nThe full surface, for when you need the complete enumeration. Day-to-day, use [Usage Documentation](#usage-documentation) instead \u2014 you don\'t call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.\n\n### MCP tools\n\nThe server exposes **58 documented tools** (enumerated below). What\'s actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).\n\n- **Connectivity & identity** \u2014 `ping`, `get_my_role`, `get_docs_dir`\n- **Jira tickets** \u2014 `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`\n- **Attachments** \u2014 `attachment` (operations: `upload`, `download`, `list`)\n- **AI generation (request/get)** \u2014 `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`\n- **Other AI** \u2014 `second_opinion`, `generate_image`, `generate_decision_page`\n- **Ticket lifecycle** \u2014 `track_ticket`, `update_ticket_state`, `get_ticket_state`\n- **Jira status** \u2014 `get_jira_transitions`, `update_jira_status`, `resolve_target_status`\n- **Repository & CI** \u2014 `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`\n- **Pipelines & automation** \u2014 `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`\n- **Config** \u2014 `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)\n\n### Bundled pipelines\n\nPipelines are declarative, multi-step workflows your AI agent executes step-by-step \u2014 each a JSON recipe chaining MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. You can also write your own (see [Custom Pipelines](#custom-pipelines)).\n\n| Pipeline | Description | Invoke with |\n|---|---|---|\n| `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |\n| `review-ticket` | Full ticket quality review: initial clarifying questions + critique, automatic second-opinion pass (default), then evaluation and decision capture. Pass `--rounds=1` to skip the second-opinion step (`--rounds=2` is the default). | `/review-ticket PROJ-123` |\n| `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |\n| `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |\n| `full-automation` | Chain: idea \u2192 ticket(s) \u2192 review each \u2192 spawn worktrees to implement | `/full-automation "<idea>"` |\n| `pr-ticket` | Commit changes and open a pull request | `/create-pr PROJ-123` |\n| `check-ci-ticket` | Commit, open a PR, then monitor CI checks until they pass or fail | `/check-ci PROJ-123` |\n| `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |\n\n### Pipeline response envelope\n\n`run_pipeline`, `resume_pipeline`, and `list_pipeline_runs` share a unified envelope keyed on `status`:\n\n- `completed` \u2014 terminal success; `results` holds per-step output.\n- `needs_agent_task` \u2014 the orchestrator paused. Read `instruction`, perform the task, then call `resume_pipeline` with `pipeline_run_id` and a string `agent_result`.\n- `failed` \u2014 terminal failure. `error_code` is one of `VALIDATION`, `NOT_FOUND`, `EXPIRED`, `REPO_MISMATCH`, `TOOL_ERROR`.\n\nPaused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition. List output is metadata-only \u2014 it never includes resolved recipes, params, instructions, results, or agent outputs.\n';
 
 // src/update-check.ts
 init_version_generated();
@@ -13193,6 +13557,18 @@ async function ensureGitignored(cwd, filePath, deps) {
   if (hasExactLine(content, entry)) return;
   await deps.writeFile(gitignorePath, appendLine(content, entry));
 }
+async function ensureGitInfoExcluded(worktreeRoot, relativePath, deps) {
+  const infoDir = path4.join(worktreeRoot, ".git", "info");
+  const excludePath = path4.join(infoDir, "exclude");
+  let content = "";
+  try {
+    content = await deps.readFile(excludePath);
+  } catch {
+  }
+  if (hasExactLine(content, relativePath)) return;
+  await deps.mkdir(infoDir, { recursive: true });
+  await deps.writeFile(excludePath, appendLine(content, relativePath));
+}
 
 // src/init.ts
 function buildBridgeApiEntry(cwd) {
@@ -13236,6 +13612,44 @@ function buildBridgeConfigManifest(repoName) {
     ""
   ].join("\n");
 }
+async function mergeBridgeApiProfileToken(cwd, token) {
+  const targets = [
+    { path: ".mcp.json", topLevelKey: "mcpServers" },
+    { path: ".vscode/mcp.json", topLevelKey: "servers" },
+    { path: ".cursor/mcp.json", topLevelKey: "mcpServers" }
+  ];
+  let lastProfile = "";
+  for (const target of targets) {
+    const fullPath = path5.join(cwd, target.path);
+    let raw;
+    try {
+      raw = await readFile3(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    const topLevel = parsed[target.topLevelKey];
+    if (!topLevel || !topLevel["bridge-api"]) {
+      continue;
+    }
+    const entry = topLevel["bridge-api"];
+    if (!entry.env) entry.env = {};
+    const existing = entry.env.BRIDGE_MCP_PROFILE;
+    const existingTokens = existing ? existing.split(",").map((t) => t.trim()).filter((t) => t.length > 0) : [];
+    const tokenSet = new Set(existingTokens);
+    tokenSet.add(token);
+    const merged = Array.from(tokenSet).join(",");
+    entry.env.BRIDGE_MCP_PROFILE = merged;
+    await writeFile2(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+    lastProfile = merged;
+  }
+  return lastProfile;
+}
 async function ensureGitignored2(cwd, filePath) {
   await ensureGitignored(cwd, filePath, {
     readFile: (p) => readFile3(p, "utf-8"),
@@ -13621,6 +14035,7 @@ init_start_tickets();
 init_version_generated();
 init_agent_registry();
 init_start_tickets_prereqs();
+init_mcp_profile();
 import { readFile as readFile6, stat as stat4 } from "fs/promises";
 import { spawn } from "child_process";
 import os5 from "os";
@@ -13712,10 +14127,12 @@ async function collectDoctorResults(deps, agentName) {
   return { ok: true, results };
 }
 function formatDoctorReport(platform, agent, collection) {
+  const activeGroups = Array.from(resolveProfiles(process.env.BRIDGE_MCP_PROFILE)).join(", ");
   const lines = [
     "start-tickets doctor (read-only diagnostics)",
     `Platform: ${platform}`,
     `Selected agent: ${agent.name} (command: ${agent.command})`,
+    `Active MCP Groups: \`${activeGroups}\``,
     ""
   ];
   if (!collection.ok) {
@@ -14590,8 +15007,8 @@ var outputFormat = {
       cwd: dir,
       outputFormat: "text"
     });
-    const textResult = assertMarkers(textRun, [marker], "text output-format did not emit the marker");
-    if (textResult.status !== "pass") return textResult;
+    const textResult4 = assertMarkers(textRun, [marker], "text output-format did not emit the marker");
+    if (textResult4.status !== "pass") return textResult4;
     const jsonRun = await ctx.runHeadless({
       prompt: `Do not use any tools. Output exactly the token ${marker}.`,
       cwd: dir,
@@ -15587,10 +16004,10 @@ import readline2 from "readline";
 init_credential_store();
 init_start_tickets_repo();
 import path18 from "path";
-async function readAgentMcpConfigIfPresent(filePath, readFile11) {
+async function readAgentMcpConfigIfPresent(filePath, readFile12) {
   let raw;
   try {
-    raw = await readFile11(filePath);
+    raw = await readFile12(filePath);
   } catch (err) {
     const code = err && typeof err === "object" ? err.code : void 0;
     if (code === "ENOENT") {
@@ -16341,110 +16758,32 @@ function evaluateDoneGate(config, binding, snapshot, evaluatedAtIso, reviewSnaps
 // src/conductor/pr-review-producer.ts
 init_git_ci_types();
 init_bridge_api_client();
-
-// src/conductor/producer-ledger.ts
-init_store();
-init_git_ci_types();
-import { createHash as createHash3 } from "node:crypto";
-function makeProducerDedupeKey(dimensions) {
-  const canonical = {};
-  for (const [key, value] of Object.entries(dimensions)) {
-    if (value !== void 0 && value !== null) canonical[key] = value;
-  }
-  return stableJsonHash(canonical);
-}
-function makeStableProducerEventId(dedupeKey) {
-  const h = createHash3("sha256").update(`conductor-producer:${dedupeKey}`).digest("hex");
-  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
-}
-function isDuplicateConstraintError2(error) {
-  if (!error || typeof error !== "object") return false;
-  const code = error.code;
-  if (typeof code === "string" && code.startsWith("SQLITE_CONSTRAINT")) return true;
-  const message = error.message;
-  if (typeof message === "string") {
-    const lowered = message.toLowerCase();
-    if (lowered.includes("unique constraint") || lowered.includes("constraint failed")) return true;
-  }
-  return false;
-}
-var LEDGER_SCAN_PAGE_LIMIT = 500;
-var LEDGER_SCAN_MAX_PAGES = 200;
-async function eventAlreadyExists(dedupeKey, deps = {}) {
-  const pollEvents = deps.pollEvents ?? ((options) => pollConductorEvents(options));
-  let sinceSeq = 1;
-  for (let page = 0; page < LEDGER_SCAN_MAX_PAGES; page += 1) {
-    let result;
-    try {
-      result = await pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
-    } catch {
-      return false;
-    }
-    for (const event of result.events) {
-      if (!event || typeof event !== "object") continue;
-      const data = event.data;
-      if (data && typeof data === "object") {
-        const details = data.details;
-        if (details && typeof details === "object" && details.dedupe_key === dedupeKey) {
-          return true;
-        }
-      }
-    }
-    if (result.count === 0 || result.next_seq <= sinceSeq) break;
-    sinceSeq = result.next_seq;
-  }
-  return false;
-}
-async function emitConductorEventIfNew(input, dimensions, deps = {}) {
-  const emitEvent = deps.emitEvent ?? emitConductorEvent;
-  const dedupeKey = makeProducerDedupeKey(dimensions);
-  if (await eventAlreadyExists(dedupeKey, deps)) {
-    return { emitted: false, reason: "duplicate" };
-  }
-  const eventId = makeStableProducerEventId(dedupeKey);
-  const existingData = input.data ?? {};
-  const existingDetails = existingData.details && typeof existingData.details === "object" && !Array.isArray(existingData.details) ? existingData.details : {};
-  const data = {
-    ...existingData,
-    details: { ...existingDetails, dedupe_key: dedupeKey }
-  };
-  try {
-    await emitEvent({ ...input, id: eventId, data });
-    return { emitted: true, event_id: eventId };
-  } catch (error) {
-    if (isDuplicateConstraintError2(error)) {
-      return { emitted: false, reason: "duplicate" };
-    }
-    throw error;
-  }
-}
-
-// src/conductor/pr-review-producer.ts
-var REVIEW_PRODUCER_OBSERVED_VIA = "pr-review-producer";
-function buildReviewObservationEventInput(binding, snapshot, eventType, reason, runId = null, workerId = null) {
-  return {
-    source: "review",
-    type: eventType,
-    subject: binding.subject,
-    run_id: runId,
-    worker_id: workerId,
-    producer: GIT_CI_PRODUCER,
-    observed_via: REVIEW_PRODUCER_OBSERVED_VIA,
-    data: {
-      summary: eventType === REVIEW_PASSED ? `Review passed for ${binding.subject}` : `Review changes requested for ${binding.subject}`,
-      status: eventType === REVIEW_PASSED ? "passed" : "changes_requested",
-      details: {
-        repo: binding.repo,
-        pr_number: binding.pr_number,
-        head_sha: binding.head_sha,
-        review_decision: snapshot.review_decision,
-        approvals: snapshot.approvals,
-        sticky_verdict: snapshot.sticky_verdict,
-        review_state_hash: snapshot.review_state_hash,
-        reason
-      }
-    }
-  };
+init_producer_ledger();
+var REVIEW_PRODUCER_OBSERVED_VIA = "pr-review-producer";
+function buildReviewObservationEventInput(binding, snapshot, eventType, reason, runId = null, workerId = null) {
+  return {
+    source: "review",
+    type: eventType,
+    subject: binding.subject,
+    run_id: runId,
+    worker_id: workerId,
+    producer: GIT_CI_PRODUCER,
+    observed_via: REVIEW_PRODUCER_OBSERVED_VIA,
+    data: {
+      summary: eventType === REVIEW_PASSED ? `Review passed for ${binding.subject}` : `Review changes requested for ${binding.subject}`,
+      status: eventType === REVIEW_PASSED ? "passed" : "changes_requested",
+      details: {
+        repo: binding.repo,
+        pr_number: binding.pr_number,
+        head_sha: binding.head_sha,
+        review_decision: snapshot.review_decision,
+        approvals: snapshot.approvals,
+        sticky_verdict: snapshot.sticky_verdict,
+        review_state_hash: snapshot.review_state_hash,
+        reason
+      }
+    }
+  };
 }
 async function observeReviewWithResolved(binding, access, gateConfig, deps = {}) {
   const fetchStatus = deps.fetchReviewStatus ?? fetchPrReviewStatus;
@@ -16745,6 +17084,7 @@ function resolvePrHeadBinding(input = {}, deps = {}) {
 }
 
 // src/conductor/pr-ci-producer.ts
+init_producer_ledger();
 async function _fetchGateConfigDefault(access) {
   const setup = await fetchEffectiveSupervisorSetup(access);
   if (setup.source === "none") return void 0;
@@ -17081,7 +17421,11 @@ async function observePrCiFromPollResponse(commitRef, pollResponse, deps = {}) {
         rawConfig = void 0;
       }
       const gateConfig = parseDoneGateConfig(rawConfig);
-      if (gateConfig.enabled && gateConfig.valid) {
+      const requiresReview = gateConfig.conditions.some((c) => c.type === REVIEW_STATE);
+      if (gateConfig.enabled && gateConfig.valid && requiresReview) {
+        result.reason = "review-gated config: gate.met deferred to wait_for_done_gate (poll path is CI-only)";
+      }
+      if (gateConfig.enabled && gateConfig.valid && !requiresReview) {
         const evaluation = evaluateDoneGate(gateConfig, binding, snapshot, now());
         if (evaluation.met) {
           result.gate_met = true;
@@ -17457,24 +17801,977 @@ function registerConductorTools(registerTool2) {
   registerCheckMessagesTool(reg);
 }
 
-// src/mcp-profile.ts
-var VALID_PROFILES = /* @__PURE__ */ new Set([
-  "core",
-  "conductor",
-  "pipeline-authoring",
-  "full"
-]);
-function resolveProfile(raw) {
-  if (raw === void 0) return "core";
-  const normalized = raw.trim().toLowerCase();
-  if (normalized === "") return "core";
-  if (VALID_PROFILES.has(normalized)) return normalized;
-  return "core";
+// src/sfcc/register.ts
+import { z as z6 } from "zod";
+
+// src/sfcc/config.ts
+var SFCC_VERSIONS = ["sfra", "pwakit", "sitegenesis", "storefrontnext", "hybrid"];
+var DEFAULT_OCAPI_VERSION = "v25_6";
+var AM_HOST = "account.demandware.com";
+var AM_TOKEN_URL = `https://${AM_HOST}/dwsso/oauth2/access_token`;
+async function getSfccVersionConfig(buildGetUrl2, getGetHeaders2, repoName) {
+  try {
+    const url = buildGetUrl2("/config-field/version", { repo_name: repoName });
+    const resp = await fetch(url, { headers: await getGetHeaders2() });
+    if (!resp.ok) return null;
+    const body = await resp.json();
+    const value = body.value;
+    if (value === null || value === void 0 || typeof value !== "string") return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+// src/sfcc/credentials.ts
+import { readFile as readFile10, writeFile as writeFile7, mkdir as mkdir7 } from "fs/promises";
+import path19 from "path";
+var ENV_HOSTNAME = "SFCC_HOSTNAME";
+var ENV_CLIENT_ID = "SFCC_CLIENT_ID";
+var ENV_CLIENT_SECRET = "SFCC_CLIENT_SECRET";
+var DW_JSON = "dw.json";
+function safeHostLabel(hostname) {
+  return hostname.split(".")[0] ?? hostname;
+}
+async function resolveSfccCredentials(explicitHostname, env = process.env, deps = {}) {
+  if (explicitHostname) {
+    const clientId2 = env[ENV_CLIENT_ID];
+    const clientSecret2 = env[ENV_CLIENT_SECRET];
+    if (!clientId2 || !clientSecret2) {
+      return {
+        ok: false,
+        error: `Explicit instance '${safeHostLabel(explicitHostname)}' provided but ${ENV_CLIENT_ID} and/or ${ENV_CLIENT_SECRET} are not set in environment. Set them and retry.`
+      };
+    }
+    return {
+      ok: true,
+      credentials: {
+        hostname: explicitHostname,
+        clientId: clientId2,
+        clientSecret: clientSecret2,
+        source: `explicit arg + env (${ENV_CLIENT_ID}/${ENV_CLIENT_SECRET})`
+      }
+    };
+  }
+  const envHostname = env[ENV_HOSTNAME];
+  const envClientId = env[ENV_CLIENT_ID];
+  const envClientSecret = env[ENV_CLIENT_SECRET];
+  if (envHostname && envClientId && envClientSecret) {
+    return {
+      ok: true,
+      credentials: {
+        hostname: envHostname,
+        clientId: envClientId,
+        clientSecret: envClientSecret,
+        source: `env (${ENV_HOSTNAME}/${ENV_CLIENT_ID}/${ENV_CLIENT_SECRET})`
+      }
+    };
+  }
+  const cwd = deps.cwd ?? process.cwd();
+  const rf = deps.readFile ?? ((p) => readFile10(p, "utf-8"));
+  const wf = deps.writeFile ?? ((p, data) => writeFile7(p, data, "utf-8"));
+  const mk = deps.mkdir ?? ((p, opts) => mkdir7(p, opts));
+  try {
+    await ensureGitInfoExcluded(cwd, DW_JSON, { readFile: rf, writeFile: wf, mkdir: mk });
+  } catch {
+  }
+  const dwJsonPath = path19.join(cwd, DW_JSON);
+  let dwJson;
+  try {
+    const raw = await rf(dwJsonPath);
+    dwJson = JSON.parse(raw);
+  } catch {
+    return {
+      ok: false,
+      error: "Could not read dw.json. Create a dw.json file in your project root with your SFCC sandbox credentials (hostname, client-id, client-secret)."
+    };
+  }
+  const configs = Array.isArray(dwJson.configs) ? dwJson.configs : null;
+  if (configs && configs.length > 1) {
+    const instances = configs.map((c) => safeHostLabel(String(c.hostname ?? c.host ?? "unknown"))).join(", ");
+    return {
+      ok: false,
+      error: `dw.json contains multiple sandboxes (${instances}). Pass an explicit 'instance' argument to select one: ${instances}.`
+    };
+  }
+  const cfg = configs && configs.length === 1 ? configs[0] : dwJson;
+  const hostname = String(cfg.hostname ?? cfg.host ?? "");
+  const clientId = String(cfg["client-id"] ?? cfg.clientId ?? cfg.client_id ?? "");
+  const clientSecret = String(
+    cfg["client-secret"] ?? cfg.clientSecret ?? cfg.client_secret ?? ""
+  );
+  if (!hostname || !clientId || !clientSecret) {
+    return {
+      ok: false,
+      error: "dw.json is present but missing required fields (hostname, client-id, client-secret). Ensure all three fields are set."
+    };
+  }
+  return {
+    ok: true,
+    credentials: {
+      hostname,
+      clientId,
+      clientSecret,
+      source: `dw.json (instance: ${safeHostLabel(hostname)})`
+    }
+  };
 }
-function profileIncludes(profile, group) {
-  return profile === "full" || profile === group;
+
+// src/sfcc/client.ts
+var tokenMutex = /* @__PURE__ */ new Map();
+var tokenCache = /* @__PURE__ */ new Map();
+async function getAmToken(credentials) {
+  const instanceKey = credentials.hostname;
+  const cached = tokenCache.get(instanceKey);
+  if (cached) return cached;
+  const existing = tokenMutex.get(instanceKey);
+  if (existing) return existing;
+  const promise = (async () => {
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: credentials.clientId,
+      client_secret: credentials.clientSecret
+    });
+    const resp = await fetch(AM_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    });
+    if (!resp.ok) {
+      throw new Error(
+        `AM token acquisition failed: HTTP ${resp.status} for instance ${instanceKey.split(".")[0]}`
+      );
+    }
+    const data = await resp.json();
+    const token = typeof data.access_token === "string" ? data.access_token : "";
+    if (!token) {
+      throw new Error(
+        `AM token acquisition returned no access_token for instance ${instanceKey.split(".")[0]}`
+      );
+    }
+    tokenCache.set(instanceKey, token);
+    return token;
+  })();
+  tokenMutex.set(instanceKey, promise);
+  try {
+    return await promise;
+  } finally {
+    tokenMutex.delete(instanceKey);
+  }
+}
+function invalidateAmToken(credentials) {
+  tokenCache.delete(credentials.hostname);
+}
+async function ocapiGet(path27, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  const doRequest = async () => {
+    const token = await getAmToken(credentials);
+    const baseUrl = `https://${credentials.hostname}/s/-/dw/data/${ocapiVersion}`;
+    const url = `${baseUrl}${path27.startsWith("/") ? path27 : "/" + path27}`;
+    const resp = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      }
+    });
+    const status = resp.status;
+    let body = null;
+    try {
+      body = await resp.json();
+    } catch {
+      body = null;
+    }
+    return { ok: resp.ok, status, body };
+  };
+  const first = await doRequest();
+  if (first.status === 401) {
+    invalidateAmToken(credentials);
+    return doRequest();
+  }
+  return first;
+}
+async function ocapiPost(path27, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  const doRequest = async () => {
+    const token = await getAmToken(credentials);
+    const baseUrl = `https://${credentials.hostname}/s/-/dw/data/${ocapiVersion}`;
+    const url = `${baseUrl}${path27.startsWith("/") ? path27 : "/" + path27}`;
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    const status = resp.status;
+    let respBody = null;
+    try {
+      respBody = await resp.json();
+    } catch {
+      respBody = null;
+    }
+    return { ok: resp.ok, status, body: respBody };
+  };
+  const first = await doRequest();
+  if (first.status === 401) {
+    invalidateAmToken(credentials);
+    return doRequest();
+  }
+  return first;
 }
 
+// src/sfcc/setup-status.ts
+async function sfccSetupStatusTool(deps) {
+  const lines = ["## SFCC Setup Status\n"];
+  const apiKeyOk = Boolean(deps.apiKey);
+  lines.push(`1. Bridge API Key: ${apiKeyOk ? "\u2713 Resolved" : "\u2717 Missing (set BAPI_API_KEY)"}`);
+  const repoOk = Boolean(deps.repoName);
+  lines.push(`2. Repo Name: ${repoOk ? `\u2713 Set (${deps.repoName})` : "\u2717 Not set (set BAPI_REPO_NAME)"}`);
+  let versionStatus = "\u2717 Not set";
+  let resolvedVersion = null;
+  if (apiKeyOk && repoOk) {
+    try {
+      resolvedVersion = await getSfccVersionConfig(
+        deps.buildGetUrl,
+        deps.getGetHeaders,
+        deps.repoName
+      );
+      if (resolvedVersion === null) {
+        versionStatus = "\u2717 Not set (configure the 'version' field in Bridge API project settings)";
+      } else if (!SFCC_VERSIONS.includes(resolvedVersion)) {
+        versionStatus = `\u2717 '${resolvedVersion}' is not an SFCC version (expected: ${SFCC_VERSIONS.join(", ")})`;
+      } else {
+        versionStatus = `\u2713 '${resolvedVersion}'`;
+      }
+    } catch {
+      versionStatus = "\u2717 Could not read (Bridge API error)";
+    }
+  } else {
+    versionStatus = "\u2014 Skipped (Bridge API not configured)";
+  }
+  lines.push(`3. SFCC Version: ${versionStatus}`);
+  let credStatus = "\u2717 Missing";
+  let resolvedCredentials = null;
+  try {
+    const result = await resolveSfccCredentials();
+    if (result.ok) {
+      resolvedCredentials = {
+        hostname: result.credentials.hostname.split(".")[0] ?? result.credentials.hostname,
+        source: result.credentials.source
+      };
+      credStatus = `\u2713 Found (${resolvedCredentials.source})`;
+    } else {
+      credStatus = `\u2717 ${result.error}`;
+    }
+  } catch (err) {
+    credStatus = `\u2717 Resolution error: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  lines.push(`4. dw.json / Credentials: ${credStatus}`);
+  let tokenStatus = "\u2014 Skipped (credentials not available)";
+  if (resolvedCredentials) {
+    try {
+      const credResult = await resolveSfccCredentials();
+      if (credResult.ok) {
+        await getAmToken(credResult.credentials);
+        tokenStatus = `\u2713 Token acquired for instance ${resolvedCredentials.hostname}`;
+      } else {
+        tokenStatus = "\u2717 Credentials not resolved";
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      tokenStatus = `\u2717 ${msg}`;
+    }
+  }
+  lines.push(`5. AM Token: ${tokenStatus}`);
+  lines.push(
+    "\nRun `check_permissions` to probe OCAPI access once steps 1\u20135 are all green."
+  );
+  return {
+    content: [{ type: "text", text: lines.join("\n") }]
+  };
+}
+function buildSfccSetupStatusHandler(buildGetUrl2, getGetHeaders2, repoName, getApiKey) {
+  return async (_args) => {
+    const apiKey = await getApiKey();
+    return sfccSetupStatusTool({ buildGetUrl: buildGetUrl2, getGetHeaders: getGetHeaders2, repoName, apiKey });
+  };
+}
+
+// src/sfcc/tool-wrapper.ts
+function notConfigured(failureClass, message) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          error: "NOT_CONFIGURED",
+          status: 503,
+          failure_class: failureClass,
+          message
+        })
+      }
+    ]
+  };
+}
+function withSfccGate(deps, handler) {
+  return async (args) => {
+    const version = await getSfccVersionConfig(
+      deps.buildGetUrl,
+      deps.getGetHeaders,
+      deps.repoName
+    );
+    if (version === null) {
+      return notConfigured(
+        "bridge-auth",
+        "Could not read the SFCC version from Bridge API (/config-field/version). Ensure your Bridge API key is set and the repo is configured. Run sfcc_setup_status for a full diagnostic."
+      );
+    }
+    if (!SFCC_VERSIONS.includes(version)) {
+      return notConfigured(
+        "version-not-sfcc",
+        `Repo version '${version}' is not an SFCC version. Expected one of: ${SFCC_VERSIONS.join(", ")}. Update the version field in your Bridge API project settings.`
+      );
+    }
+    const explicitHostname = typeof args.instance === "string" ? args.instance : void 0;
+    const credResult = await resolveSfccCredentials(explicitHostname);
+    if (!credResult.ok) {
+      return notConfigured(
+        "missing-dw-json",
+        `SFCC credential resolution failed: ${credResult.error} Ensure a dw.json file exists in your project root with hostname, client-id, and client-secret fields.`
+      );
+    }
+    return handler(args, credResult.credentials);
+  };
+}
+
+// src/sfcc/ocapi-shape.ts
+function normalizeOcapiPage(body) {
+  if (body === null || typeof body !== "object" || !Array.isArray(body.data) || typeof body.count !== "number") {
+    return null;
+  }
+  const envelope = body;
+  return {
+    items: envelope.data,
+    count: envelope.count,
+    total: envelope.total,
+    hasMore: envelope.next != null
+  };
+}
+function normalizeOcapiBody(body) {
+  if (Array.isArray(body)) {
+    return { items: body, count: body.length, total: void 0, hasMore: false };
+  }
+  if (body !== null && typeof body === "object") {
+    const obj = body;
+    if (Array.isArray(obj.data)) {
+      const items = obj.data;
+      return {
+        items,
+        count: typeof obj.count === "number" ? obj.count : items.length,
+        total: typeof obj.total === "number" ? obj.total : void 0,
+        hasMore: obj.next != null
+      };
+    }
+    return { items: [body], count: 1, total: void 0, hasMore: false };
+  }
+  return { items: [], count: 0, total: void 0, hasMore: false };
+}
+
+// src/sfcc/permissions.ts
+var OCAPI_SETTINGS_READ_ONLY = (ocapiVersion) => JSON.stringify(
+  {
+    _v: ocapiVersion,
+    clients: [
+      {
+        client_id: "<YOUR_CLIENT_ID>",
+        resources: [
+          {
+            resource_id: "/system_object_definitions",
+            methods: ["get"],
+            read_attributes: "(**)",
+            write_attributes: "(**)"
+          },
+          {
+            resource_id: "/system_object_definitions/**",
+            methods: ["get"],
+            read_attributes: "(**)",
+            write_attributes: "(**)"
+          }
+        ]
+      }
+    ]
+  },
+  null,
+  2
+);
+var OCAPI_SETTINGS_WRITE_IMPORT = (ocapiVersion) => JSON.stringify(
+  {
+    _v: ocapiVersion,
+    clients: [
+      {
+        client_id: "<YOUR_CLIENT_ID>",
+        resources: [
+          {
+            resource_id: "/system_object_definitions",
+            methods: ["get", "put", "patch", "delete"],
+            read_attributes: "(**)",
+            write_attributes: "(**)"
+          },
+          {
+            resource_id: "/system_object_definitions/**",
+            methods: ["get", "put", "patch", "delete"],
+            read_attributes: "(**)",
+            write_attributes: "(**)"
+          }
+        ]
+      }
+    ]
+  },
+  null,
+  2
+);
+async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  let result;
+  try {
+    result = await ocapiGet("/system_object_definitions", credentials, ocapiVersion);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `OCAPI probe failed: ${msg}
+
+` + ocapiSettingsInstructions(ocapiVersion)
+        }
+      ]
+    };
+  }
+  if (result.ok) {
+    const normalized = normalizeOcapiPage(result.body);
+    const itemCount = normalized ? normalized.count : "unknown";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `\u2713 OCAPI access confirmed.
+  Instance: ${credentials.hostname.split(".")[0]}
+  OCAPI version: ${ocapiVersion}
+  GET /system_object_definitions: ${itemCount} items returned`
+        }
+      ]
+    };
+  }
+  if (result.status === 401 || result.status === 403) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `HTTP ${result.status}: OCAPI access denied for instance ${credentials.hostname.split(".")[0]}.
+
+` + ocapiSettingsInstructions(ocapiVersion)
+        }
+      ]
+    };
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Unexpected OCAPI response: HTTP ${result.status}.
+Ensure your sandbox is running and the hostname in dw.json is correct.`
+      }
+    ]
+  };
+}
+function ocapiSettingsInstructions(ocapiVersion) {
+  return `To grant OCAPI access, paste the JSON below in Business Manager:
+  Administration > Site Development > Open Commerce API Settings \u2192 Data API tab
+
+--- READ-ONLY GRANTS (v1 \u2014 required now) ---
+${OCAPI_SETTINGS_READ_ONLY(ocapiVersion)}
+
+--- WRITE/IMPORT GRANTS (v2 \u2014 forward-looking, paste once) ---
+${OCAPI_SETTINGS_WRITE_IMPORT(ocapiVersion)}
+
+Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`;
+}
+
+// src/sfcc/reads-system-object.ts
+import path21 from "path";
+import { z as z3 } from "zod";
+
+// src/sfcc/output.ts
+import path20 from "path";
+import { mkdir as mkdir8, writeFile as writeFile8 } from "fs/promises";
+var SFCC_MAX_INLINE = 5e4;
+function truncationNote(savedPath) {
+  return `
+
+[Response truncated \u2014 full payload saved to ${savedPath}]`;
+}
+async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
+  if (text.length <= SFCC_MAX_INLINE) {
+    return text;
+  }
+  const mk = deps.mkdir ?? mkdir8;
+  const wf = deps.writeFile ?? writeFile8;
+  const filePath = path20.join(dir, filename);
+  try {
+    await mk(dir, { recursive: true });
+    await wf(filePath, text, "utf-8");
+  } catch (err) {
+    return text + `
+
+Warning: response was NOT truncated because local save failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  return text.slice(0, SFCC_MAX_INLINE) + truncationNote(filePath);
+}
+
+// src/sfcc/reads-system-object.ts
+var READ_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var systemObjectListInput = z3.object({
+  count: z3.number().optional().describe("Maximum number of system object types to return."),
+  start: z3.number().optional().describe("Zero-based offset for paging.")
+});
+var systemObjectGetInput = z3.object({
+  object_type: z3.string().describe('System object type identifier, e.g. "Product" or "Order".'),
+  expand_attribute_definitions: z3.boolean().optional().describe(
+    "When true, include the full attribute definition list in the response. May produce a large payload \u2014 auto-saved locally when oversized."
+  )
+});
+var systemObjectAttributeSearchInput = z3.object({
+  object_type: z3.string().describe('System object type to search within, e.g. "Order".'),
+  query: z3.union([z3.string(), z3.record(z3.string(), z3.any())]).describe(
+    "Search query. Pass a plain string for a text search across id and display_name, or a structured OCAPI query object (term_query, filtered_query, etc.)."
+  ),
+  start: z3.number().optional().describe("Zero-based offset for paging."),
+  count: z3.number().optional().describe("Maximum number of results to return."),
+  sorts: z3.array(z3.any()).optional().describe("Array of OCAPI sort descriptors.")
+});
+function safeTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function safeType(objectType) {
+  return encodeURIComponent(objectType).replace(/%/g, "_");
+}
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+async function saveAndReturn(text, dir, filename) {
+  const output = await truncateAndSaveIfNeeded(text, dir, filename);
+  return textResult(output);
+}
+function buildSystemObjectListHandler(gateDeps, getDocsDir2) {
+  return withSfccGate(
+    gateDeps,
+    async (args, credentials) => {
+      const { count, start } = systemObjectListInput.parse(args);
+      const queryParams = {};
+      if (count !== void 0) queryParams.count = String(count);
+      if (start !== void 0) queryParams.start = String(start);
+      const queryStr = Object.keys(queryParams).length > 0 ? "?" + new URLSearchParams(queryParams).toString() : "";
+      const result = await ocapiGet(`/system_object_definitions${queryStr}`, credentials);
+      if (!result.ok) {
+        return textResult(
+          JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2)
+        );
+      }
+      const normalized = normalizeOcapiBody(result.body);
+      const text = JSON.stringify(normalized, null, 2);
+      const dir = path21.join(await getDocsDir2(), "sfcc");
+      return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`);
+    }
+  );
+}
+function buildSystemObjectGetHandler(gateDeps, getDocsDir2) {
+  return withSfccGate(
+    gateDeps,
+    async (args, credentials) => {
+      const { object_type, expand_attribute_definitions } = systemObjectGetInput.parse(args);
+      const encodedType = encodeURIComponent(object_type);
+      const expandParam = expand_attribute_definitions === true ? "?expand=attribute_definitions" : "";
+      const result = await ocapiGet(
+        `/system_object_definitions/${encodedType}${expandParam}`,
+        credentials
+      );
+      if (!result.ok) {
+        return textResult(
+          JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2)
+        );
+      }
+      const normalized = normalizeOcapiBody(result.body);
+      const text = JSON.stringify(normalized, null, 2);
+      const dir = path21.join(await getDocsDir2(), "sfcc");
+      return saveAndReturn(
+        text,
+        dir,
+        `system-object-get-${safeType(object_type)}-${safeTimestamp()}.json`
+      );
+    }
+  );
+}
+function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir2) {
+  return withSfccGate(
+    gateDeps,
+    async (args, credentials) => {
+      const { object_type, query, start, count, sorts } = systemObjectAttributeSearchInput.parse(args);
+      const encodedType = encodeURIComponent(object_type);
+      const resolvedQuery = typeof query === "string" ? { text_query: { fields: ["id", "display_name"], search_phrase: query } } : query;
+      const postBody = { query: resolvedQuery };
+      if (start !== void 0) postBody.start = start;
+      if (count !== void 0) postBody.count = count;
+      if (sorts !== void 0) postBody.sorts = sorts;
+      const result = await ocapiPost(
+        `/system_object_definitions/${encodedType}/attribute_definition_search`,
+        postBody,
+        credentials
+      );
+      if (!result.ok) {
+        return textResult(
+          JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2)
+        );
+      }
+      const normalized = normalizeOcapiBody(result.body);
+      const text = JSON.stringify(normalized, null, 2);
+      const dir = path21.join(await getDocsDir2(), "sfcc");
+      return saveAndReturn(
+        text,
+        dir,
+        `system-object-search-${safeType(object_type)}-${safeTimestamp()}.json`
+      );
+    }
+  );
+}
+function registerSystemObjectReadTools(registerTool2, deps) {
+  const { gateDeps, getDocsDir: getDocsDir2 } = deps;
+  registerTool2(
+    "system_object_list",
+    {
+      description: "List all system object types from the developer sandbox via GET /system_object_definitions. Read-only. Accepts optional `count` and `start` for paging (OCAPI default pagination applies when omitted). Oversized outputs are auto-saved locally and previewed inline.",
+      inputSchema: systemObjectListInput,
+      annotations: READ_ANNOTATIONS
+    },
+    buildSystemObjectListHandler(gateDeps, getDocsDir2)
+  );
+  registerTool2(
+    "system_object_get",
+    {
+      description: "Retrieve a system object type from the developer sandbox. Read-only. GET /system_object_definitions/{type}. Prefer system_object_attribute_search for targeted attribute lookups \u2014 use this for a full type dump or expanded attribute list (expand_attribute_definitions=true). Oversized payloads are auto-saved locally.",
+      inputSchema: systemObjectGetInput,
+      annotations: READ_ANNOTATIONS
+    },
+    buildSystemObjectGetHandler(gateDeps, getDocsDir2)
+  );
+  registerTool2(
+    "system_object_attribute_search",
+    {
+      description: "Search attribute definitions for a system object type. Read-only. POST /system_object_definitions/{type}/attribute_definition_search. Prefer over system_object_get+expand for targeted c_ attribute lookups. Pass a plain string for text search or a structured OCAPI query object. Oversized results are auto-saved locally.",
+      inputSchema: systemObjectAttributeSearchInput,
+      annotations: READ_ANNOTATIONS
+    },
+    buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir2)
+  );
+}
+
+// src/sfcc/reads-custom-object-def.ts
+import path22 from "path";
+import { z as z4 } from "zod";
+var READ_ANNOTATIONS2 = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var customObjectListInput = z4.object({
+  count: z4.number().optional().describe("Maximum number of custom object types to return."),
+  start: z4.number().optional().describe("Zero-based offset for paging.")
+});
+var customObjectGetInput = z4.object({
+  object_type: z4.string().describe(
+    'Custom object type identifier, e.g. "GiftCertificate" or a custom type id starting with "c_".'
+  )
+});
+function safeTimestamp2() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function safeType2(objectType) {
+  return encodeURIComponent(objectType).replace(/%/g, "_");
+}
+function textResult2(text) {
+  return { content: [{ type: "text", text }] };
+}
+async function saveAndReturn2(text, dir, filename) {
+  const output = await truncateAndSaveIfNeeded(text, dir, filename);
+  return textResult2(output);
+}
+function buildCustomObjectListHandler(gateDeps, getDocsDir2) {
+  return withSfccGate(
+    gateDeps,
+    async (args, credentials) => {
+      const { count, start } = customObjectListInput.parse(args);
+      const queryParams = {};
+      if (count !== void 0) queryParams.count = String(count);
+      if (start !== void 0) queryParams.start = String(start);
+      const queryStr = Object.keys(queryParams).length > 0 ? "?" + new URLSearchParams(queryParams).toString() : "";
+      const result = await ocapiGet(`/custom_object_definitions${queryStr}`, credentials);
+      if (!result.ok) {
+        return textResult2(
+          JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2)
+        );
+      }
+      const normalized = normalizeOcapiBody(result.body);
+      const text = JSON.stringify(normalized, null, 2);
+      const dir = path22.join(await getDocsDir2(), "sfcc");
+      return saveAndReturn2(text, dir, `custom-object-def-list-${safeTimestamp2()}.json`);
+    }
+  );
+}
+function buildCustomObjectGetHandler(gateDeps, getDocsDir2) {
+  return withSfccGate(
+    gateDeps,
+    async (args, credentials) => {
+      const { object_type } = customObjectGetInput.parse(args);
+      const encodedType = encodeURIComponent(object_type);
+      const result = await ocapiGet(`/custom_object_definitions/${encodedType}`, credentials);
+      if (!result.ok) {
+        return textResult2(
+          JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2)
+        );
+      }
+      const normalized = normalizeOcapiBody(result.body);
+      const text = JSON.stringify(normalized, null, 2);
+      const dir = path22.join(await getDocsDir2(), "sfcc");
+      return saveAndReturn2(
+        text,
+        dir,
+        `custom-object-def-${safeType2(object_type)}-${safeTimestamp2()}.json`
+      );
+    }
+  );
+}
+function registerSfccCustomObjectDefReadTools(registerTool2, deps) {
+  const { gateDeps, getDocsDir: getDocsDir2 } = deps;
+  registerTool2(
+    "custom_object_definition_list",
+    {
+      description: "List all custom object type definitions from the developer sandbox via GET /custom_object_definitions. Read-only introspection; type definitions cannot be created or updated via OCAPI (v2 metadata-import only). Optional `count` and `start` for paging. Oversized outputs auto-saved locally.",
+      inputSchema: customObjectListInput,
+      annotations: READ_ANNOTATIONS2
+    },
+    buildCustomObjectListHandler(gateDeps, getDocsDir2)
+  );
+  registerTool2(
+    "custom_object_definition_get",
+    {
+      description: "Retrieve an EXISTING custom object type from the developer sandbox via GET /custom_object_definitions/{type}. Returns the type with key_definition and attribute_definitions/attribute_groups. Read-only introspection; type definitions cannot be created or updated via OCAPI (v2 metadata-import only). Oversized payloads auto-saved locally.",
+      inputSchema: customObjectGetInput,
+      annotations: READ_ANNOTATIONS2
+    },
+    buildCustomObjectGetHandler(gateDeps, getDocsDir2)
+  );
+}
+
+// src/sfcc/reads-site-preference.ts
+import path23 from "path";
+import { z as z5 } from "zod";
+var READ_ANNOTATIONS3 = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var INSTANCE_ENUM = z5.enum(["staging", "development", "sandbox", "production"]);
+var INSTANCE_DESCRIBE = "OCAPI instance context. v1 supports the 'sandbox' context only; any other value is rejected with a validation error. Defaults to 'sandbox'.";
+var sitePreferenceGetInput = z5.object({
+  group: z5.string().describe("Preference group ID, e.g. 'Account' or 'General'."),
+  instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
+  start: z5.number().optional().describe("Zero-based offset for paging."),
+  count: z5.number().optional().describe("Maximum number of preferences to return.")
+});
+var sitePreferenceSearchInput = z5.object({
+  group: z5.string().describe("Preference group ID to search within."),
+  instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
+  query: z5.union([z5.string(), z5.record(z5.string(), z5.any())]).describe(
+    "Search query. Pass a plain string for text search across preference ids and values, or a structured OCAPI query object (term_query, filtered_query, etc.)."
+  ),
+  start: z5.number().optional().describe("Zero-based offset for paging."),
+  count: z5.number().optional().describe("Maximum number of results to return."),
+  sorts: z5.array(z5.any()).optional().describe("Array of OCAPI sort descriptors.")
+});
+function safeTimestamp3() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function safeGroup(group) {
+  return encodeURIComponent(group).replace(/%/g, "_");
+}
+function textResult3(text) {
+  return { content: [{ type: "text", text }] };
+}
+async function saveAndReturn3(text, dir, filename) {
+  const output = await truncateAndSaveIfNeeded(text, dir, filename);
+  return textResult3(output);
+}
+function rejectIfNotSandbox(instance) {
+  if (instance !== "sandbox") {
+    return textResult3(
+      JSON.stringify({
+        error: "VALIDATION_ERROR",
+        status: 400,
+        message: `v1 only supports the 'sandbox' instance context. Received: '${instance}'.`
+      }, null, 2)
+    );
+  }
+  return null;
+}
+function buildSitePreferenceGetHandler(gateDeps, getDocsDir2) {
+  return withSfccGate(
+    gateDeps,
+    async (args, credentials) => {
+      const { group, instance, start, count } = sitePreferenceGetInput.parse(args);
+      const guard = rejectIfNotSandbox(instance);
+      if (guard) return guard;
+      const encodedGroup = encodeURIComponent(group);
+      const queryParams = {};
+      if (start !== void 0) queryParams.start = String(start);
+      if (count !== void 0) queryParams.count = String(count);
+      const queryStr = Object.keys(queryParams).length > 0 ? "?" + new URLSearchParams(queryParams).toString() : "";
+      const result = await ocapiGet(
+        `/site_preferences/preference_groups/${encodedGroup}/${instance}${queryStr}`,
+        credentials
+      );
+      if (!result.ok) {
+        return textResult3(
+          JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2)
+        );
+      }
+      const normalized = normalizeOcapiBody(result.body);
+      const text = JSON.stringify(normalized, null, 2);
+      const dir = path23.join(await getDocsDir2(), "sfcc");
+      return saveAndReturn3(
+        text,
+        dir,
+        `site-preference-get-${safeGroup(group)}-${safeTimestamp3()}.json`
+      );
+    }
+  );
+}
+function buildSitePreferenceSearchHandler(gateDeps, getDocsDir2) {
+  return withSfccGate(
+    gateDeps,
+    async (args, credentials) => {
+      const { group, instance, query, start, count, sorts } = sitePreferenceSearchInput.parse(args);
+      const guard = rejectIfNotSandbox(instance);
+      if (guard) return guard;
+      const encodedGroup = encodeURIComponent(group);
+      const resolvedQuery = typeof query === "string" ? { text_query: { fields: ["id", "value"], search_phrase: query } } : query;
+      const postBody = { query: resolvedQuery };
+      if (start !== void 0) postBody.start = start;
+      if (count !== void 0) postBody.count = count;
+      if (sorts !== void 0) postBody.sorts = sorts;
+      const result = await ocapiPost(
+        `/site_preferences/preference_groups/${encodedGroup}/${instance}/preference_search`,
+        postBody,
+        credentials
+      );
+      if (!result.ok) {
+        return textResult3(
+          JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2)
+        );
+      }
+      const normalized = normalizeOcapiBody(result.body);
+      const text = JSON.stringify(normalized, null, 2);
+      const dir = path23.join(await getDocsDir2(), "sfcc");
+      return saveAndReturn3(
+        text,
+        dir,
+        `site-preference-search-${safeGroup(group)}-${safeTimestamp3()}.json`
+      );
+    }
+  );
+}
+function registerSitePreferenceTools(registerTool2, deps) {
+  const { gateDeps, getDocsDir: getDocsDir2 } = deps;
+  registerTool2(
+    "site_preference_get",
+    {
+      description: "Read effective preferences for a site preference group from the developer sandbox via GET /site_preferences/preference_groups/{group}/sandbox. Read-only; v1 supports sandboxes only (non-sandbox instances are rejected). Accepts optional `start` and `count` for paging. Oversized payloads are auto-saved locally and previewed inline.",
+      inputSchema: sitePreferenceGetInput,
+      annotations: READ_ANNOTATIONS3
+    },
+    buildSitePreferenceGetHandler(gateDeps, getDocsDir2)
+  );
+  registerTool2(
+    "site_preference_search",
+    {
+      description: "Search/filter preferences within a site preference group from the developer sandbox via POST /site_preferences/preference_groups/{group}/sandbox/preference_search. Read-only; v1 sandbox only. Pass a plain string for text search or a structured OCAPI query object. Oversized results are auto-saved locally.",
+      inputSchema: sitePreferenceSearchInput,
+      annotations: READ_ANNOTATIONS3
+    },
+    buildSitePreferenceSearchHandler(gateDeps, getDocsDir2)
+  );
+}
+
+// src/sfcc/register.ts
+function registerSfccTools(registerTool2, deps) {
+  const gateDeps = {
+    buildGetUrl: deps.buildGetUrl,
+    getGetHeaders: deps.getGetHeaders,
+    repoName: deps.repoName
+  };
+  registerTool2(
+    "sfcc_setup_status",
+    {
+      description: "Report on every SFCC prerequisite: Bridge API key, repo name, version config, dw.json presence/uniqueness, and AM token acquisition. Always-registered; returns status without requiring full SFCC configuration to be complete.",
+      inputSchema: z6.object({}),
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    buildSfccSetupStatusHandler(
+      deps.buildGetUrl,
+      deps.getGetHeaders,
+      deps.repoName,
+      deps.getResolvedApiKey
+    )
+  );
+  const gatedCheckPermissions = withSfccGate(
+    gateDeps,
+    async (_args, credentials) => checkPermissionsTool(credentials)
+  );
+  registerTool2(
+    "check_permissions",
+    {
+      description: "Probe SFCC OCAPI access via GET /system_object_definitions. On 200: reports OK and the detected OCAPI version. On 401/403: prints the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).",
+      inputSchema: z6.object({
+        instance: z6.string().optional().describe("Explicit sandbox hostname to use instead of dw.json auto-detection.")
+      }),
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    gatedCheckPermissions
+  );
+  if (deps.includeReadTools) {
+    registerSystemObjectReadTools(registerTool2, {
+      gateDeps,
+      getDocsDir: deps.getDocsDir
+    });
+    registerSfccCustomObjectDefReadTools(registerTool2, {
+      gateDeps,
+      getDocsDir: deps.getDocsDir
+    });
+    registerSitePreferenceTools(registerTool2, {
+      gateDeps,
+      getDocsDir: deps.getDocsDir
+    });
+  }
+}
+
+// src/index.ts
+init_mcp_profile();
+
 // src/conductor/cli.ts
 init_errors();
 init_store();
@@ -17648,6 +18945,7 @@ function inspectConductorGitHooks(deps = {}) {
 
 // src/conductor/git-producer.ts
 init_git_ci_types();
+init_producer_ledger();
 var COMMITTED_REF_PHASE = "committed";
 function buildCommitCreatedEventInput(context, metadata) {
   const details = {
@@ -17749,6 +19047,7 @@ async function runReferenceTransactionHookProducer(args, deps = {}) {
 
 // src/conductor/doctor.ts
 init_store();
+import { spawnSync } from "node:child_process";
 async function inspectEpicTickSchedule(deps, orchestrateListOverride) {
   try {
     const schedRun = orchestrateListOverride ? null : await Promise.resolve().then(() => (init_schedule_run(), schedule_run_exports));
@@ -17815,6 +19114,46 @@ function inspectMcpProfile(env, epicTick) {
   }
   return { resolved_profile, conductor_context_detected, degraded, warnings };
 }
+function inspectLocalMerge(runCommand) {
+  const run = runCommand ?? ((cmd, args) => {
+    try {
+      const r = spawnSync(cmd, args, {
+        encoding: "utf8",
+        timeout: 1e4,
+        env: { ...process.env, GH_PROMPT_DISABLED: "1" }
+      });
+      return { status: r.status };
+    } catch {
+      return { status: null };
+    }
+  });
+  let gh_available = false;
+  let gh_authed = false;
+  try {
+    gh_available = run("gh", ["--version"]).status === 0;
+  } catch {
+    gh_available = false;
+  }
+  if (gh_available) {
+    try {
+      gh_authed = run("gh", ["auth", "status"]).status === 0;
+    } catch {
+      gh_authed = false;
+    }
+  }
+  const warnings = [];
+  if (!gh_available) {
+    warnings.push(
+      "`gh` is not installed or not on PATH. Local merge (policy_json.local_merge.enabled) cannot run; install the GitHub CLI to enable conductor-driven merges."
+    );
+  } else if (!gh_authed) {
+    warnings.push(
+      "`gh` is installed but not authenticated (`gh auth status` failed). Run `gh auth login` to grant the conductor merge permission; otherwise local merge will emit merge.failed/skip."
+    );
+  }
+  const degraded = !gh_available || !gh_authed;
+  return { gh_available, gh_authed, degraded, warnings };
+}
 async function buildConductorDoctorReport(deps = {}) {
   const doctorLedger = deps.doctorLedger ?? doctorConductorLedger;
   const inspectHooks = deps.inspectHooks ?? inspectConductorGitHooks;
@@ -17824,11 +19163,12 @@ async function buildConductorDoctorReport(deps = {}) {
     ledger: await doctorLedger(),
     git_hooks: inspectHooks(deps.hooksDeps),
     epic_tick: epicTick,
-    mcp_profile
+    mcp_profile,
+    local_merge: inspectLocalMerge(deps.runCommand)
   };
 }
 function formatConductorDoctorReport(report) {
-  const { ledger, git_hooks, epic_tick, mcp_profile } = report;
+  const { ledger, git_hooks, epic_tick, mcp_profile, local_merge } = report;
   const lines = [
     "Conductor ledger doctor",
     "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
@@ -17891,6 +19231,17 @@ function formatConductorDoctorReport(report) {
     lines.push("mcp profile warnings:");
     for (const w of mcp_profile.warnings) lines.push(`  - ${w}`);
   }
+  lines.push("");
+  lines.push("Local merge capability (optional, opt-in)");
+  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  const ghTag = local_merge.gh_available ? local_merge.gh_authed ? "[OK]" : "[WARNING] not authenticated" : "[WARNING] not installed";
+  lines.push(`gh available:          ${local_merge.gh_available} ${ghTag}`);
+  lines.push(`gh authenticated:      ${local_merge.gh_authed}`);
+  lines.push(`degraded:              ${local_merge.degraded}`);
+  if (local_merge.warnings.length > 0) {
+    lines.push("local merge warnings:");
+    for (const w of local_merge.warnings) lines.push(`  - ${w}`);
+  }
   return lines.join("\n");
 }
 
@@ -18746,135 +20097,135 @@ async function runConductorCli(argv) {
 import { generateDecisionPageHtml } from "./decision-page-template.js";
 
 // src/decision-page-schema.ts
-import { z as z3 } from "zod";
-var ActionableItemSchema = z3.object({
-  id: z3.string().min(1).regex(
+import { z as z7 } from "zod";
+var ActionableItemSchema = z7.object({
+  id: z7.string().min(1).regex(
     /^[A-Za-z0-9_-]+$/,
     "id must contain only letters, digits, hyphens, or underscores"
   ),
-  question: z3.string().min(1),
-  original_question: z3.string().optional().describe(
+  question: z7.string().min(1),
+  original_question: z7.string().optional().describe(
     "Optional display-only field: the clarifying question or critique point as originally raised; soft cap ~30 words. Omit it (or pass an empty string) for non-review callers \u2014 the renderer omits the section when it is absent or blank."
   ),
-  why_it_matters: z3.string().min(1).describe("Concrete one-sentence impact of this decision; soft cap ~40 words."),
-  recommendation_explanation: z3.string().min(1).describe("Why the recommended branch is the best choice; soft cap ~60 words."),
-  codebase_evidence: z3.string().optional().describe(
+  why_it_matters: z7.string().min(1).describe("Concrete one-sentence impact of this decision; soft cap ~40 words."),
+  recommendation_explanation: z7.string().min(1).describe("Why the recommended branch is the best choice; soft cap ~60 words."),
+  codebase_evidence: z7.string().optional().describe(
     "Optional display-only field: combined Assessment paragraph and Codebase Evidence bullet list. Rendered as escaped plain text inside a closed-by-default <details> block, which is omitted when this field is absent or blank."
   ),
-  source: z3.string().optional().describe(
+  source: z7.string().optional().describe(
     `Optional source reference from the combined review-and-resolution doc, e.g. 'Clarifying Q3 (prior round, weak concurrence)'. When absent the rendered card emits data-source="".`
   ),
-  recommendation_index: z3.number().int().min(0).describe("0-based index of the recommended option in the options array"),
-  options: z3.array(z3.string().min(1)).min(2).max(4).describe("Option labels from the decision tree branches. Values are auto-generated. Must have 2\u20134 entries."),
-  option_consequences: z3.array(z3.string().min(1)).min(2).max(4).describe(
+  recommendation_index: z7.number().int().min(0).describe("0-based index of the recommended option in the options array"),
+  options: z7.array(z7.string().min(1)).min(2).max(4).describe("Option labels from the decision tree branches. Values are auto-generated. Must have 2\u20134 entries."),
+  option_consequences: z7.array(z7.string().min(1)).min(2).max(4).describe(
     "Behavioral consequence per branch, parallel to options. Must have 2\u20134 entries; length must equal options.length."
   )
 }).superRefine((item, ctx) => {
   if (item.option_consequences.length !== item.options.length) {
     ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
+      code: z7.ZodIssueCode.custom,
       path: ["option_consequences"],
       message: `option_consequences length (${item.option_consequences.length}) must match options length (${item.options.length}).`
     });
   }
   if (item.recommendation_index >= item.options.length) {
     ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
+      code: z7.ZodIssueCode.custom,
       path: ["recommendation_index"],
       message: `recommendation_index (${item.recommendation_index}) is out of bounds (${item.options.length} options).`
     });
   }
 });
-var DecisionPageLabelsSchema = z3.object({
-  title: z3.string().optional().describe('Overrides the page <title>/<h1> lead text (default "Review Decisions").'),
-  intro: z3.string().optional().describe("Overrides the actionable-page intro copy shown when there are decisions."),
-  section_heading: z3.string().optional().describe('Overrides the decision cards <h2> (default "Review Decisions").'),
-  improvements_heading: z3.string().optional().describe('Overrides the confirmed-improvements <h2> (default "Confirmed Improvements").')
+var DecisionPageLabelsSchema = z7.object({
+  title: z7.string().optional().describe('Overrides the page <title>/<h1> lead text (default "Review Decisions").'),
+  intro: z7.string().optional().describe("Overrides the actionable-page intro copy shown when there are decisions."),
+  section_heading: z7.string().optional().describe('Overrides the decision cards <h2> (default "Review Decisions").'),
+  improvements_heading: z7.string().optional().describe('Overrides the confirmed-improvements <h2> (default "Confirmed Improvements").')
 });
-var SystemGoalNfrSchema = z3.object({
-  category: z3.string().min(1).describe(
+var SystemGoalNfrSchema = z7.object({
+  category: z7.string().min(1).describe(
     "Canonical NFR category, e.g. security/privacy, performance/latency, reliability/failure-modes, observability/auditability, accessibility/UX, data-integrity/migration, compatibility, operability/config, compliance/SOC2, rollout/reversibility."
   ),
-  requirement: z3.string().min(1).describe("The non-functional requirement itself."),
-  implication: z3.string().min(1).describe(
+  requirement: z7.string().min(1).describe("The non-functional requirement itself."),
+  implication: z7.string().min(1).describe(
     "What this requirement changes about the implementation. Required \u2014 drop the NFR rather than emit boilerplate without an implication."
   ),
-  status: z3.enum(["confirmed", "assumed", "open"]).describe(
+  status: z7.enum(["confirmed", "assumed", "open"]).describe(
     "confirmed = explicitly stated or observable in code; assumed = low-risk and reversible default; open = unresolved (also surface as an actionable_items card)."
   )
 });
-var SystemGoalsSchema = z3.object({
-  business_goal: z3.string().min(1).describe("The business goal this work serves."),
-  desired_end_state: z3.string().min(1).describe("The end-state the system should reach."),
-  system_behavior: z3.string().min(1).describe("How the system must behave / complete its task (quality attributes in prose)."),
-  nfrs: z3.array(SystemGoalNfrSchema).optional().default([])
+var SystemGoalsSchema = z7.object({
+  business_goal: z7.string().min(1).describe("The business goal this work serves."),
+  desired_end_state: z7.string().min(1).describe("The end-state the system should reach."),
+  system_behavior: z7.string().min(1).describe("How the system must behave / complete its task (quality attributes in prose)."),
+  nfrs: z7.array(SystemGoalNfrSchema).optional().default([])
 });
-var ImplementationOrderItemSchema = z3.object({
-  title: z3.string().min(1).describe("Short title of the slice / child ticket."),
-  depends_on: z3.array(z3.string().min(1)).optional().default([]).describe("Hard prerequisites (titles or keys) that must land first."),
-  recommended_after: z3.array(z3.string().min(1)).optional().default([]).describe("Soft sequencing preferences \u2014 not hard blockers."),
-  rationale: z3.string().min(1).describe("Why this slice sits at this point in the order.")
+var ImplementationOrderItemSchema = z7.object({
+  title: z7.string().min(1).describe("Short title of the slice / child ticket."),
+  depends_on: z7.array(z7.string().min(1)).optional().default([]).describe("Hard prerequisites (titles or keys) that must land first."),
+  recommended_after: z7.array(z7.string().min(1)).optional().default([]).describe("Soft sequencing preferences \u2014 not hard blockers."),
+  rationale: z7.string().min(1).describe("Why this slice sits at this point in the order.")
 });
 var DecisionPageInputShape = {
-  ticket_key: z3.string().describe("Jira ticket key, e.g. BAPI-123"),
-  artifact_type: z3.enum(["review_decisions", "pre_ticket_planning"]).optional().default("review_decisions").describe(
+  ticket_key: z7.string().describe("Jira ticket key, e.g. BAPI-123"),
+  artifact_type: z7.enum(["review_decisions", "pre_ticket_planning"]).optional().default("review_decisions").describe(
     'Which flavor of page to render. "review_decisions" (default) is the ticket-review decision-capture page and is unaffected by the planning fields. "pre_ticket_planning" additionally renders the read-only system_goals and implementation_order sections for pre-ticket epic/task framing.'
   ),
   system_goals: SystemGoalsSchema.optional().describe(
     "pre_ticket_planning only: read-only business goal, desired end-state, system behavior, and classified NFRs. Unresolved (open) NFRs should ALSO be passed as actionable_items so the human can decide them."
   ),
-  implementation_order: z3.array(ImplementationOrderItemSchema).optional().describe(
+  implementation_order: z7.array(ImplementationOrderItemSchema).optional().describe(
     "pre_ticket_planning epic surfaces only: read-only recommended implementation order (hard depends_on vs soft recommended_after). No Jira links are created from this."
   ),
-  output_subdir: z3.string().optional().default("review").describe(
+  output_subdir: z7.string().optional().default("review").describe(
     'Optional docs-relative subdirectory to write the page under (default "review"). Validated strictly: no absolute paths, backslashes, ".." segments, null bytes, or encoded path tokens.'
   ),
-  output_filename: z3.string().optional().describe(
+  output_filename: z7.string().optional().describe(
     'Optional output filename (default "${ticket_key}-decisions.html"). Must end with .html and contain no path separators; the .html suffix is required and never auto-appended.'
   ),
   labels: DecisionPageLabelsSchema.optional().describe(
     "Optional presentation-label overrides (title, intro, section_heading, improvements_heading). Presentation-only; does not change data-testid hooks or the submitted JSON shape."
   ),
-  actionable_items: z3.array(ActionableItemSchema).optional().default([]).describe(
+  actionable_items: z7.array(ActionableItemSchema).optional().default([]).describe(
     "Actionable review decisions sourced from the combined review-and-resolution document. 'None of these' is auto-appended by the renderer and must not appear in options."
   ),
-  clear_improvements: z3.array(
-    z3.object({
-      id: z3.string().min(1).describe(
+  clear_improvements: z7.array(
+    z7.object({
+      id: z7.string().min(1).describe(
         "Stable identifier for the improvement. Stored for the rewrite/capture step but intentionally not rendered to the user."
       ),
-      title: z3.string().min(1),
-      action: z3.string().min(1),
-      confidence: z3.string().min(1),
-      source: z3.string().min(1).describe(
+      title: z7.string().min(1),
+      action: z7.string().min(1),
+      confidence: z7.string().min(1),
+      source: z7.string().min(1).describe(
         "Source reference from the evaluation. Stored for the rewrite/capture step but intentionally not rendered to the user \u2014 the confirmed-improvements list shows title/confidence/action only."
       )
     })
   ).optional().default([]).describe("Confirmed improvements displayed as informational list, not submitted.")
 };
-var DecisionPageInputSchema = z3.object(DecisionPageInputShape);
+var DecisionPageInputSchema = z7.object(DecisionPageInputShape);
 var DecisionPageLeanInputShape = {
-  ticket_key: z3.string().describe("Jira ticket key, e.g. BAPI-123"),
-  artifact_type: z3.enum(["review_decisions", "pre_ticket_planning"]).optional().default("review_decisions").describe(
+  ticket_key: z7.string().describe("Jira ticket key, e.g. BAPI-123"),
+  artifact_type: z7.enum(["review_decisions", "pre_ticket_planning"]).optional().default("review_decisions").describe(
     'Which flavor of page to render. "review_decisions" (default) or "pre_ticket_planning" (adds system_goals and implementation_order sections).'
   ),
-  output_subdir: z3.string().optional().default("review").describe(
+  output_subdir: z7.string().optional().default("review").describe(
     'Optional docs-relative subdirectory to write the page under (default "review"). No absolute paths, backslashes, ".." segments, null bytes, or encoded path tokens.'
   ),
-  output_filename: z3.string().optional().describe(
+  output_filename: z7.string().optional().describe(
     'Optional output filename (default "${ticket_key}-decisions.html"). Must end with .html; no path separators.'
   ),
   labels: DecisionPageLabelsSchema.optional().describe(
     "Optional presentation-label overrides (title, intro, section_heading, improvements_heading)."
   ),
-  content: z3.record(z3.string(), z3.unknown()).optional().describe(
+  content: z7.record(z7.string(), z7.unknown()).optional().describe(
     "Contains deferred heavy payloads like actionable_items or system_goals."
   )
 };
 
 // src/brainstorm-files.ts
-import { writeFile as writeFile7, mkdir as mkdir7 } from "fs/promises";
-import path20 from "path";
+import { writeFile as writeFile9, mkdir as mkdir9 } from "fs/promises";
+import path25 from "path";
 function slugify(text, maxLength = 60) {
   return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").slice(0, maxLength).replace(/-$/, "");
 }
@@ -18899,10 +20250,10 @@ async function saveBrainstormResultsToDir(envelope, dir, subject) {
       continue;
     }
     const filename = buildBrainstormResultFilename(envelope, row, subject);
-    const filePath = path20.join(dir, filename);
+    const filePath = path25.join(dir, filename);
     try {
-      await mkdir7(dir, { recursive: true });
-      await writeFile7(filePath, markdown, "utf-8");
+      await mkdir9(dir, { recursive: true });
+      await writeFile9(filePath, markdown, "utf-8");
       savedPaths.push(filePath);
     } catch {
     }
@@ -20662,7 +22013,7 @@ function parseDefaultOnEnvFlag(value) {
 var UPGRADE_ADVICE_SURFACING_ENABLED = parseDefaultOnEnvFlag(
   process.env.BAPI_MCP_UPGRADE_ADVICE_ENABLED
 );
-var BRIDGE_MCP_PROFILE = resolveProfile(process.env.BRIDGE_MCP_PROFILE);
+var ACTIVE_GROUPS = resolveProfiles(process.env.BRIDGE_MCP_PROFILE);
 var resolvedApiKeyPromise;
 async function getResolvedApiKey() {
   if (!resolvedApiKeyPromise) {
@@ -20672,7 +22023,7 @@ async function getResolvedApiKey() {
           env: process.env,
           homedir: os10.homedir,
           platform: process.platform,
-          readFile: (p) => readFile10(p, "utf-8"),
+          readFile: (p) => readFile11(p, "utf-8"),
           stat: (p) => stat8(p)
         });
         return result.ok ? result.credentials.apiKey : "";
@@ -20689,7 +22040,7 @@ async function getResolvedApiKeyForRepo(repoName) {
       env: process.env,
       homedir: os10.homedir,
       platform: process.platform,
-      readFile: (p) => readFile10(p, "utf-8"),
+      readFile: (p) => readFile11(p, "utf-8"),
       stat: (p) => stat8(p)
     });
     return result.ok ? result.credentials.apiKey : "";
@@ -20702,9 +22053,9 @@ function buildCredentialStoreWriteDeps() {
     env: process.env,
     homedir: os10.homedir,
     platform: process.platform,
-    readFile: (p) => readFile10(p, "utf-8"),
-    mkdir: (p, options) => mkdir8(p, options),
-    writeFile: (p, data, options) => writeFile8(p, data, options),
+    readFile: (p) => readFile11(p, "utf-8"),
+    mkdir: (p, options) => mkdir10(p, options),
+    writeFile: (p, data, options) => writeFile10(p, data, options),
     rename: (oldPath, newPath) => rename3(oldPath, newPath),
     chmod: (p, mode) => chmod3(p, mode),
     unlink: (p) => unlink3(p)
@@ -20761,39 +22112,39 @@ async function getProjectRoot() {
 var docsDirPromise;
 async function getDocsDir() {
   if (!docsDirPromise) {
-    docsDirPromise = (async () => path21.resolve(await getProjectRoot(), process.env.BAPI_DOCS_DIR ?? "docs/tmp"))();
+    docsDirPromise = (async () => path26.resolve(await getProjectRoot(), process.env.BAPI_DOCS_DIR ?? "docs/tmp"))();
   }
   return docsDirPromise;
 }
 var pipelinesDirPromise;
 async function getPipelinesDir() {
   if (!pipelinesDirPromise) {
-    pipelinesDirPromise = (async () => path21.resolve(await getProjectRoot(), process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines"))();
+    pipelinesDirPromise = (async () => path26.resolve(await getProjectRoot(), process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines"))();
   }
   return pipelinesDirPromise;
 }
-function buildUrl(path22) {
-  return `${BASE_URL.replace(/\/+$/, "")}/jira${path22}`;
+function buildUrl(path27) {
+  return `${BASE_URL.replace(/\/+$/, "")}/jira${path27}`;
 }
-function buildApiUrl(path22) {
-  return `${BASE_URL.replace(/\/+$/, "")}${path22}`;
+function buildApiUrl(path27) {
+  return `${BASE_URL.replace(/\/+$/, "")}${path27}`;
 }
-function buildGetUrl(path22, params) {
-  const url = new URL(buildUrl(path22));
+function buildGetUrl(path27, params) {
+  const url = new URL(buildUrl(path27));
   for (const [key, value] of Object.entries(params)) {
     url.searchParams.set(key, value);
   }
   return url.toString();
 }
 async function getDocsPath(subdir) {
-  return path21.join(await getDocsDir(), subdir);
+  return path26.join(await getDocsDir(), subdir);
 }
 var customPipelinesPromise;
 async function ensureCustomPipelinesLoaded() {
   if (!customPipelinesPromise) {
     customPipelinesPromise = (async () => {
       const pipelinesDir = await getPipelinesDir();
-      const instructionsDir = path21.join(path21.dirname(pipelinesDir), "instructions");
+      const instructionsDir = path26.join(path26.dirname(pipelinesDir), "instructions");
       const customResult = await loadCustomPipelines(
         pipelinesDir,
         instructionsDir,
@@ -20878,10 +22229,10 @@ async function createTicketRequest(params) {
   return handleResponse(resp);
 }
 async function saveLocally(dir, filename, content) {
-  const filePath = path21.join(dir, filename);
+  const filePath = path26.join(dir, filename);
   try {
-    await mkdir8(dir, { recursive: true });
-    await writeFile8(filePath, content, "utf-8");
+    await mkdir10(dir, { recursive: true });
+    await writeFile10(filePath, content, "utf-8");
     return `
 
 ---
@@ -20898,19 +22249,19 @@ function safeTimestampForFilename() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 }
 function safeTicketFileSegment(ticketNumber) {
-  const base = path21.basename(ticketNumber.trim());
+  const base = path26.basename(ticketNumber.trim());
   const cleaned = base.replace(/[^A-Za-z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
   return cleaned || "ticket";
 }
 function isContainedSaveTarget(dir, filename) {
-  const resolvedDir = path21.resolve(dir);
-  const target = path21.resolve(resolvedDir, filename);
-  return target.startsWith(resolvedDir + path21.sep);
+  const resolvedDir = path26.resolve(dir);
+  const target = path26.resolve(resolvedDir, filename);
+  return target.startsWith(resolvedDir + path26.sep);
 }
 function saveLocallySucceeded(note) {
   return note.includes("Saved to ");
 }
-async function truncateAndSaveIfNeeded(text, dir, filename) {
+async function truncateAndSaveIfNeeded2(text, dir, filename) {
   if (text.length <= MAX_INLINE_TEXT_LENGTH) {
     return text;
   }
@@ -20967,7 +22318,7 @@ async function resolveTextOrFile(textValue, filePath, textLabel) {
           }
         };
       }
-      resolvedText = await readFile10(filePath, "utf-8");
+      resolvedText = await readFile11(filePath, "utf-8");
       if (textValue) {
         note = `
 
@@ -21031,8 +22382,8 @@ async function resolveUploadAttachment(textValue, filePath, textLabel) {
         }
       };
     }
-    const ext = path21.extname(filePath).toLowerCase();
-    const buf = await readFile10(filePath);
+    const ext = path26.extname(filePath).toLowerCase();
+    const buf = await readFile11(filePath);
     let isBinary = BINARY_EXTENSIONS.has(ext);
     if (!isBinary) {
       try {
@@ -21365,7 +22716,7 @@ Raw body: ${result.text}`
 }
 async function ensurePackageJsonForCliCommand(flagName, cwd) {
   try {
-    await stat8(path21.join(cwd, "package.json"));
+    await stat8(path26.join(cwd, "package.json"));
     return null;
   } catch {
     return `Error: No package.json found in current directory.
@@ -21509,22 +22860,30 @@ var registerTool = ((name, config, handler) => {
   return toolHandle;
 });
 var commonFields = {
-  ticket_number: z4.string(),
-  repo_name: z4.string().optional(),
-  save_locally: z4.boolean().optional().default(true),
-  wait_for_result: z4.boolean().optional().default(false).describe(
+  ticket_number: z8.string(),
+  repo_name: z8.string().optional(),
+  save_locally: z8.boolean().optional().default(true),
+  wait_for_result: z8.boolean().optional().default(false).describe(
     "When true, blocks and polls until ready, returning full content directly. When false (default), returns immediately with confirmation/handle. Use the corresponding get_* tool to retrieve results."
   ),
-  second_opinion: z4.string().optional().describe(
+  second_opinion: z8.string().optional().describe(
     "Provider routing override for THIS request. NOT the standalone second_opinion tool. Takes precedence over provider."
   ),
-  provider: z4.string().optional().describe(
+  provider: z8.string().optional().describe(
     "Use a specific LLM provider (openai, anthropic, gemini) without triggering second-opinion semantics."
   )
 };
-if (profileIncludes(BRIDGE_MCP_PROFILE, "conductor")) {
+if (ACTIVE_GROUPS.has("conductor")) {
   registerConductorTools(registerTool);
 }
+registerSfccTools(registerTool, {
+  buildGetUrl,
+  getGetHeaders,
+  repoName: REPO_NAME,
+  getResolvedApiKey,
+  getDocsDir,
+  includeReadTools: ACTIVE_GROUPS.has("sfcc")
+});
 registerTool(
   "ping",
   {
@@ -21573,13 +22932,13 @@ registerTool(
     },
     description: "Use to get an immediate, ad hoc independent critique on a plan or analysis you already have. Returns the responding model's reply text plus the resolved provider. This does NOT create or retrieve a Bridge artifact (use request_* tools for that).",
     inputSchema: {
-      prompt: z4.string().describe(
+      prompt: z8.string().describe(
         "The complete, self-contained brief to send to the second-opinion model. Include the full plan, recommendation, analysis, or question you want challenged, plus enough context for the responder to evaluate it independently. This is sent as the user message; the server constructs the system prompt."
       ),
-      provider: z4.enum(["anthropic", "openai", "gemini"]).describe(
+      provider: z8.enum(["anthropic", "openai", "gemini"]).describe(
         "LLM provider family for the second opinion. Choose a family DIFFERENT from the one you are running on so the response is genuinely independent."
       ),
-      model: z4.enum(["CHEAP_MODEL", "BASIC_MODEL", "PREMIUM_MODEL"]).describe(
+      model: z8.enum(["CHEAP_MODEL", "BASIC_MODEL", "PREMIUM_MODEL"]).describe(
         "Model tier within the chosen provider. CHEAP_MODEL for quick sanity checks, BASIC_MODEL for focused reviews, PREMIUM_MODEL for serious architectural pushback."
       )
     }
@@ -21660,10 +23019,10 @@ registerTool(
     },
     description: "Generate an image from a text prompt using a provider image model. This tool spends provider credits on every call \u2014 cost scales with quality (low/medium/high). Defaults to low quality to minimize provider spend; increase quality only when fidelity matters. Returns native MCP image content (type: 'image') so the caller receives the image directly. The image is always also saved to the local BAPI_DOCS_DIR/images/ directory. Google Imagen outputs (provider='gemini') include an invisible SynthID watermark applied server-side by Google.",
     inputSchema: {
-      prompt: z4.string().min(1).max(8e3).describe("Text prompt sent to the image provider."),
-      provider: z4.enum(["openai", "gemini"]).optional().default("openai").describe("Image provider. Defaults to 'openai' (gpt-image-2)."),
-      quality: z4.enum(["low", "medium", "high"]).optional().default("low").describe("Image quality. Defaults to 'low' for cost control."),
-      size: z4.enum(["1024x1024", "1024x1536", "1536x1024"]).optional().default("1024x1024").describe("Image dimensions. Defaults to '1024x1024'.")
+      prompt: z8.string().min(1).max(8e3).describe("Text prompt sent to the image provider."),
+      provider: z8.enum(["openai", "gemini"]).optional().default("openai").describe("Image provider. Defaults to 'openai' (gpt-image-2)."),
+      quality: z8.enum(["low", "medium", "high"]).optional().default("low").describe("Image quality. Defaults to 'low' for cost control."),
+      size: z8.enum(["1024x1024", "1024x1536", "1536x1024"]).optional().default("1024x1024").describe("Image dimensions. Defaults to '1024x1024'.")
     }
   },
   async ({ prompt, provider, quality, size }) => {
@@ -21757,8 +23116,8 @@ registerTool(
       const imagesDir = await getDocsPath("images");
       const filename = `generated-image-${safeTimestampForFilename()}.png`;
       const filePath = `${imagesDir}/${filename}`;
-      await mkdir8(imagesDir, { recursive: true });
-      await writeFile8(filePath, Buffer.from(imageBase64, "base64"));
+      await mkdir10(imagesDir, { recursive: true });
+      await writeFile10(filePath, Buffer.from(imageBase64, "base64"));
       content.push({ type: "text", text: `Saved to ${filePath}` });
     } catch (saveErr) {
       content.push({
@@ -21789,7 +23148,7 @@ registerTool(
     if (ok) {
       const safeRepo = safeTicketFileSegment(REPO_NAME || "repo");
       const filename = `${safeRepo}-project-standards.md`;
-      text = await truncateAndSaveIfNeeded(
+      text = await truncateAndSaveIfNeeded2(
         text,
         await getDocsPath("project-standards"),
         filename
@@ -21809,16 +23168,16 @@ registerTool(
     },
     description: "Search for and list Jira tickets from the configured project. Filters by query text, status name, label, or date. Returns up to 'limit' tickets ordered by most recently updated. All data is fetched live from Jira. Use get_ticket to retrieve full details for a specific ticket.",
     inputSchema: {
-      query: z4.string().optional().describe(
+      query: z8.string().optional().describe(
         `Free-text search string. Filters tickets via JQL text ~ '...' (searches summary, description, comments). Examples: "authentication error", "login page crash", "payment timeout"`
       ),
-      status: z4.string().optional().describe("Filter by Jira status name (e.g. 'To Do', 'In Progress', 'Done')"),
-      labels: z4.string().optional().describe(
+      status: z8.string().optional().describe("Filter by Jira status name (e.g. 'To Do', 'In Progress', 'Done')"),
+      labels: z8.string().optional().describe(
         'Comma-separated Jira labels. Filters tickets via JQL labels in (...) (matches tickets carrying any of the given labels). Labels cannot contain spaces. Example: "bapi-idea-to-ticket-fa-1a2b3c"'
       ),
-      limit: z4.number().optional().default(20).describe("Maximum number of tickets to return (1-100, default 20)"),
-      offset: z4.number().optional().default(0).describe("Number of results to skip for pagination (default 0)"),
-      updated_since: z4.string().optional().describe("ISO date string (YYYY-MM-DD). Only return tickets updated on or after this date")
+      limit: z8.number().optional().default(20).describe("Maximum number of tickets to return (1-100, default 20)"),
+      offset: z8.number().optional().default(0).describe("Number of results to skip for pagination (default 0)"),
+      updated_since: z8.string().optional().describe("ISO date string (YYYY-MM-DD). Only return tickets updated on or after this date")
     }
   },
   async ({ query, status, labels, limit, offset, updated_since }) => {
@@ -21842,7 +23201,7 @@ registerTool(
         limit,
         offset
       });
-      text = await truncateAndSaveIfNeeded(
+      text = await truncateAndSaveIfNeeded2(
         text,
         await getDocsPath("tickets-search"),
         filename
@@ -21876,7 +23235,7 @@ registerTool(
     if (ok) {
       const safeTicket = safeTicketFileSegment(ticket_number);
       const filename = `${safeTicket}.json`;
-      text = await truncateAndSaveIfNeeded(
+      text = await truncateAndSaveIfNeeded2(
         text,
         await getDocsPath("tickets"),
         filename
@@ -21934,7 +23293,7 @@ registerTool(
     if (ok) {
       const safeTicket = safeTicketFileSegment(ticket_number);
       const filename = `${safeTicket}-comments.json`;
-      text = await truncateAndSaveIfNeeded(
+      text = await truncateAndSaveIfNeeded2(
         text,
         await getDocsPath("comments"),
         filename
@@ -21954,18 +23313,18 @@ registerTool(
     },
     description: "Create a new Jira ticket in the configured project. Requires either description or file_path (or both \u2014 file_path takes precedence). Returns JSON with {ticket_key: 'PROJ-123', url: 'https://...'}. The ticket is created immediately in Jira \u2014 confirm details with the user before calling. The description field supports Jira markdown formatting. Pass parent_key ONLY when creating a child ticket under an existing Jira Epic; omit it for standalone tickets and for Epic parent creation itself.",
     inputSchema: {
-      summary: z4.string().describe("Ticket title \u2014 keep under 100 characters"),
-      description: z4.string().optional().describe(
+      summary: z8.string().describe("Ticket title \u2014 keep under 100 characters"),
+      description: z8.string().optional().describe(
         "Required unless file_path is provided. Detailed description in markdown. Recommended structure: Summary (2-4 sentences), Requirements (bullet list with code file references), Acceptance Criteria (testable 'Done when...' statements)"
       ),
-      file_path: z4.string().optional().describe(
+      file_path: z8.string().optional().describe(
         "Path to a local markdown file whose contents will be used as the ticket description. If both file_path and description are provided, file_path takes precedence. The file must be UTF-8 encoded and under 1MB."
       ),
-      issue_type: z4.string().describe("One of: 'Bug' (defect), 'Story' (user-facing feature), 'Task' (technical/infrastructure work)"),
-      priority: z4.string().optional().describe("One of: 'Highest', 'High', 'Medium', 'Low', 'Lowest'. Omit to use Jira project default"),
-      labels: z4.array(z4.string()).optional().describe("List of Jira labels to apply (e.g. ['frontend', 'tech-debt'])"),
-      assignee: z4.string().optional().describe("Jira username or account ID of the assignee. Omit to leave unassigned"),
-      parent_key: z4.string().optional().describe(
+      issue_type: z8.string().describe("One of: 'Bug' (defect), 'Story' (user-facing feature), 'Task' (technical/infrastructure work)"),
+      priority: z8.string().optional().describe("One of: 'Highest', 'High', 'Medium', 'Low', 'Lowest'. Omit to use Jira project default"),
+      labels: z8.array(z8.string()).optional().describe("List of Jira labels to apply (e.g. ['frontend', 'tech-debt'])"),
+      assignee: z8.string().optional().describe("Jira username or account ID of the assignee. Omit to leave unassigned"),
+      parent_key: z8.string().optional().describe(
         "Optional Jira Epic key to set as the parent of the newly created child issue. Omit for standalone tickets and Epic parent creation."
       )
     }
@@ -22064,7 +23423,7 @@ registerTool(
     },
     description: "Queue a background job to parse and index the repository for Bridge API's AI agents. This should be run after major codebase changes so that plans and questions reflect the latest code. Returns 202 with {message: 'Repository parsing queued'} on success, or {message: 'Repository parsing already in progress'} if a job is already running. The job runs asynchronously \u2014 there is no completion callback. For large repositories this may take several minutes. Confirm with the user before triggering.",
     inputSchema: {
-      directory_path: z4.string().optional().describe(
+      directory_path: z8.string().optional().describe(
         "Subdirectory to scope the parse to (e.g. 'src/python'). Omit to parse the entire repository"
       )
     }
@@ -22141,14 +23500,14 @@ registerTool(
     description: "Post a comment on a Jira ticket. The comment appears immediately in Jira. Supports markdown formatting. For long comments (over ~2000 characters), set attach_as_file to true \u2014 this attaches the comment as a .md file instead of posting inline, which avoids Jira's comment length limitations.\n\nTip: To generate plans, clarifying questions, or ticket critiques, use the dedicated request_plan_generation, request_clarifying_questions, or request_ticket_critique tools.",
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      comment: z4.string().optional().describe("Comment text in markdown format. Can include code blocks, lists, headings, etc. Optional if file_path is provided."),
-      file_path: z4.string().optional().describe(
+      comment: z8.string().optional().describe("Comment text in markdown format. Can include code blocks, lists, headings, etc. Optional if file_path is provided."),
+      file_path: z8.string().optional().describe(
         "Path to a local markdown file whose contents will be used as the comment. If both file_path and comment are provided, file_path takes precedence. The file must be UTF-8 encoded and under 1MB."
       ),
-      attach_as_file: z4.boolean().optional().default(false).describe(
+      attach_as_file: z8.boolean().optional().default(false).describe(
         "Set to true to attach the comment as a .md file instead of posting inline. Recommended for comments over 2000 characters"
       ),
-      file_name: z4.string().optional().describe(
+      file_name: z8.string().optional().describe(
         "Custom filename for the attached .md file (only used when attach_as_file is true). Defaults to {ticket_number}-comment.md if not provided. Example: 'PROJ-123-clarifying-questions.md'"
       )
     }
@@ -22188,8 +23547,8 @@ registerTool(
     description: "Update the description of an existing Jira ticket. This is a direct, synchronous update that overwrites the existing description with the provided text. The description should be in markdown format \u2014 it will be automatically converted to Jira wiki markup. This does NOT create a new ticket. Use create_ticket for that. Returns a success message with the ticket number, or an error if the update fails.",
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      description: z4.string().optional().describe("New description text in markdown format. Optional if file_path is provided. This will completely replace the existing description."),
-      file_path: z4.string().optional().describe(
+      description: z8.string().optional().describe("New description text in markdown format. Optional if file_path is provided. This will completely replace the existing description."),
+      file_path: z8.string().optional().describe(
         "Path to a local markdown file whose contents will be used as the new description. If both file_path and description are provided, file_path takes precedence. The file must be UTF-8 encoded and under 1MB."
       )
     }
@@ -22219,35 +23578,35 @@ registerTool(
       openWorldHint: true
     },
     description: "Manages Jira attachments. Operations: upload, download, list.",
-    inputSchema: z4.discriminatedUnion("operation", [
-      z4.object({
-        operation: z4.literal("upload"),
+    inputSchema: z8.discriminatedUnion("operation", [
+      z8.object({
+        operation: z8.literal("upload"),
         ticket_number: commonFields.ticket_number,
-        file_path: z4.string().optional().describe(
+        file_path: z8.string().optional().describe(
           "Path to a local file to upload. Binary files up to `10 MB`; text up to `1 MB`. If both file_path and content are provided, file_path takes precedence."
         ),
-        content: z4.string().max(1048576).optional().describe("Inline text content to upload (max `1 MB`). Optional if file_path is provided."),
-        file_name: z4.string().optional().describe(
+        content: z8.string().max(1048576).optional().describe("Inline text content to upload (max `1 MB`). Optional if file_path is provided."),
+        file_name: z8.string().optional().describe(
           "Filename for the attachment in Jira. Defaults to the basename of file_path if provided, or {ticket_number}-attachment.md otherwise."
         ),
-        link_type: z4.string().optional().describe(
+        link_type: z8.string().optional().describe(
           "When provided, also syncs the content to Bridge API's tickets_links table. Known values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md, fsd-plan.md, prd-plan.md. Cannot be used with binary file uploads."
         ),
-        replace_existing: z4.boolean().optional().default(true).describe(
+        replace_existing: z8.boolean().optional().default(true).describe(
           "When true (default), deletes any existing attachment with the same filename before uploading."
         )
       }).strict(),
-      z4.object({
-        operation: z4.literal("download"),
+      z8.object({
+        operation: z8.literal("download"),
         ticket_number: commonFields.ticket_number,
-        attachment_id: z4.string().optional().describe("Jira attachment ID. Mutually exclusive with filename."),
-        filename: z4.string().optional().describe("Attachment filename. If multiple exist, returns the most recent. Mutually exclusive with attachment_id."),
-        file_path: z4.string().optional().describe("Override the default save location. If omitted, saves to {BAPI_DOCS_DIR}/attachments/{ticket_number}/{filename}.")
+        attachment_id: z8.string().optional().describe("Jira attachment ID. Mutually exclusive with filename."),
+        filename: z8.string().optional().describe("Attachment filename. If multiple exist, returns the most recent. Mutually exclusive with attachment_id."),
+        file_path: z8.string().optional().describe("Override the default save location. If omitted, saves to {BAPI_DOCS_DIR}/attachments/{ticket_number}/{filename}.")
       }).strict(),
-      z4.object({
-        operation: z4.literal("list"),
+      z8.object({
+        operation: z8.literal("list"),
         ticket_number: commonFields.ticket_number,
-        include_ai_generated: z4.boolean().optional().describe("Include AI-generated attachments in the list (default: false)")
+        include_ai_generated: z8.boolean().optional().describe("Include AI-generated attachments in the list (default: false)")
       }).strict()
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ])
@@ -22259,7 +23618,7 @@ registerTool(
         const { ticket_number, file_path, content, file_name, link_type, replace_existing } = args;
         const resolved = await resolveUploadAttachment(content, file_path, "content");
         if (!resolved.ok) return resolved.errorResponse;
-        const derivedFileName = file_name || (file_path ? path21.basename(file_path) : `${ticket_number}-attachment.md`);
+        const derivedFileName = file_name || (file_path ? path26.basename(file_path) : `${ticket_number}-attachment.md`);
         const payload = {
           repo_name: REPO_NAME,
           content: resolved.text,
@@ -22314,12 +23673,12 @@ registerTool(
         const isText = body.is_text;
         const mimeType = body.mime_type;
         const size = body.size;
-        const safeFileName = path21.basename(serverFilename);
-        const safeTicket = path21.basename(ticket_number);
-        const savePath = file_path ? file_path : path21.join(await getDocsDir(), "attachments", safeTicket, safeFileName);
-        const resolvedSave = path21.resolve(savePath);
-        const resolvedRoot = path21.resolve(await getProjectRoot());
-        if (!resolvedSave.startsWith(resolvedRoot + path21.sep) && resolvedSave !== resolvedRoot) {
+        const safeFileName = path26.basename(serverFilename);
+        const safeTicket = path26.basename(ticket_number);
+        const savePath = file_path ? file_path : path26.join(await getDocsDir(), "attachments", safeTicket, safeFileName);
+        const resolvedSave = path26.resolve(savePath);
+        const resolvedRoot = path26.resolve(await getProjectRoot());
+        if (!resolvedSave.startsWith(resolvedRoot + path26.sep) && resolvedSave !== resolvedRoot) {
           return {
             content: [{
               type: "text",
@@ -22330,11 +23689,11 @@ registerTool(
             }]
           };
         }
-        await mkdir8(path21.dirname(resolvedSave), { recursive: true });
+        await mkdir10(path26.dirname(resolvedSave), { recursive: true });
         if (isText) {
-          await writeFile8(resolvedSave, content, "utf-8");
+          await writeFile10(resolvedSave, content, "utf-8");
         } else {
-          await writeFile8(resolvedSave, Buffer.from(content, "base64"));
+          await writeFile10(resolvedSave, Buffer.from(content, "base64"));
         }
         let resultText = `File saved to: ${resolvedSave}
 Filename: ${safeFileName}
@@ -22371,7 +23730,7 @@ ${content}`;
         if (ok) {
           const safeTicket = safeTicketFileSegment(ticket_number);
           const fname = `${safeTicket}-attachment-list.json`;
-          text = await truncateAndSaveIfNeeded(
+          text = await truncateAndSaveIfNeeded2(
             text,
             await getDocsPath("attachments"),
             fname
@@ -22464,15 +23823,15 @@ registerTool(
     description: "Use to start async generation of a design document (tdd, fsd, or prd) for a Jira ticket. Returns confirmation immediately (or the full document if wait_for_result is true). Use get_doc to retrieve. Generates and persists a retrievable artifact.",
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      doc_type: z4.enum(["tdd", "fsd", "prd"]).describe(
+      doc_type: z8.enum(["tdd", "fsd", "prd"]).describe(
         "Which design document to generate: 'tdd' (Technical Design Document, engineer audience), 'fsd' (Functional Specification Document, product/functional audience), or 'prd' (Product Requirements Document, product-requirements focused: problem, goals, success metrics)."
       ),
       wait_for_result: commonFields.wait_for_result,
       save_locally: commonFields.save_locally,
-      second_opinion: z4.string().optional().describe(
+      second_opinion: z8.string().optional().describe(
         "Provider routing override for THIS artifact-generation request (e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is generated by the named provider and, where supported, a cross-provider second-opinion pass is applied to this request only. Takes precedence over `provider` when both are set."
       ),
-      provider: z4.string().optional().describe(
+      provider: z8.string().optional().describe(
         "Pure provider switch \u2014 use a specific LLM provider (openai, anthropic, gemini) without triggering second-opinion semantics. If both provider and second_opinion are set, second_opinion takes precedence."
       )
     }
@@ -22493,7 +23852,7 @@ registerTool(
     description: "RETRIEVE an already-generated design document for a Jira ticket, routed by doc_type. Use doc_type 'tdd' for the Technical Design Document, 'fsd' for the Functional Specification Document, or 'prd' for the Product Requirements Document. This tool only fetches an existing document \u2014 it does NOT start or trigger generation. If no document exists yet (or you need a fresh one), call `create_doc` first with the same doc_type. Returns the full document as markdown text \u2014 present it verbatim without summarizing. Returns a 404 / not-found response when no document is ready yet \u2014 that means generation has not run, not that this tool failed.",
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      doc_type: z4.enum(["tdd", "fsd", "prd"]).describe(
+      doc_type: z8.enum(["tdd", "fsd", "prd"]).describe(
         "Which design document to retrieve: 'tdd' (Technical Design Document), 'fsd' (Functional Specification Document), or 'prd' (Product Requirements Document)."
       ),
       save_locally: commonFields.save_locally
@@ -22641,7 +24000,7 @@ registerTool(
     description: "Write/update Bridge API's DATABASE lifecycle-tracking record for a ticket ONLY. This registers the ticket in Bridge's own database so workflow state timestamps (critique, clarify, plan, implement) can be tracked. It does NOT edit anything in Jira: it does not change the Jira summary, description, comments, attachments, or status. If the ticket is already tracked, this is a safe no-op \u2014 it upserts the description and repo_name without error. After create_ticket, this is the correct next step when you want Bridge to track that ticket's workflow timestamps / artifact state. For Jira mutations use a different tool instead: `update_ticket_description` to replace the Jira description, `add_comment` to post a Jira comment, and `update_jira_status` to move the Jira workflow status. The repo_name is automatically injected from the configured environment.",
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      description: z4.string().optional().describe("Ticket description text. Optional \u2014 used to store a local copy of the description for reference.")
+      description: z8.string().optional().describe("Ticket description text. Optional \u2014 used to store a local copy of the description for reference.")
     }
   },
   async ({ ticket_number, description }) => {
@@ -22671,7 +24030,7 @@ registerTool(
     description: "Update workflow state timestamps on a tracked ticket. Each specified field is set to the current UTC timestamp on the server. Valid field names: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'. The ticket must already be tracked (via track_ticket) or a 404 error is returned. Returns 400 if any field name is invalid. The repo_name is automatically injected from the configured environment.",
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      fields: z4.array(z4.string()).describe("List of state field names to set to the current UTC timestamp. Valid values: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'")
+      fields: z8.array(z8.string()).describe("List of state field names to set to the current UTC timestamp. Valid values: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'")
     }
   },
   async ({ ticket_number, fields }) => {
@@ -22748,8 +24107,8 @@ registerTool(
     description: 'Transition a Jira ticket to a specified target status by executing a workflow transition. Provide either target_status (matched case-insensitively against available transitions) or transition_id (used directly). If transition_id is provided, it takes precedence over target_status. Pass target_status as "auto" to trigger server-side status resolution via LLM \u2014 the server determines the correct post-PR status automatically. If auto-resolve finds no match, returns status: skipped (not an error). Returns the from/to status on success, or an error listing available transitions if no match is found. The repo_name is automatically injected from the configured environment.',
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      target_status: z4.string().optional().describe('Target status name to transition to (case-insensitive match). Pass "auto" to resolve the target status server-side via LLM agent.'),
-      transition_id: z4.string().optional().describe("Specific transition ID to execute (takes precedence over target_status)")
+      target_status: z8.string().optional().describe('Target status name to transition to (case-insensitive match). Pass "auto" to resolve the target status server-side via LLM agent.'),
+      transition_id: z8.string().optional().describe("Specific transition ID to execute (takes precedence over target_status)")
     }
   },
   async ({ ticket_number, target_status, transition_id }) => {
@@ -22780,7 +24139,7 @@ registerTool(
     description: "Ask an LLM agent to CHOOSE the project's post-PR target Jira status, and cache that choice per project. The agent selects the single workflow status that best represents 'code committed via PR but not yet tested.' Results are cached per-project \u2014 subsequent calls return the cached value unless force_rerun is true. This does NOT list all available transitions \u2014 use `get_jira_transitions` for the full transition list. This also does NOT move the ticket \u2014 use `update_jira_status` to actually perform the status transition. Requires a ticket_number to fetch available transitions from Jira. The repo_name is automatically injected from the configured environment.",
     inputSchema: {
       ticket_number: commonFields.ticket_number,
-      force_rerun: z4.boolean().optional().describe("Set to true to bypass the cache and re-resolve the target status via LLM")
+      force_rerun: z8.boolean().optional().describe("Set to true to bypass the cache and re-resolve the target status via LLM")
     }
   },
   async ({ ticket_number, force_rerun }) => {
@@ -22845,35 +24204,35 @@ registerTool(
       openWorldHint: true
     },
     description: "Manages Bridge API configuration fields. Operations: get, update, list.",
-    inputSchema: z4.discriminatedUnion("operation", [
-      z4.object({
-        operation: z4.literal("get"),
-        field_name: z4.string().describe(
+    inputSchema: z8.discriminatedUnion("operation", [
+      z8.object({
+        operation: z8.literal("get"),
+        field_name: z8.string().describe(
           `Read the current value and metadata for a config field. For install bootstrap, prefer get_install_manifest over many individual reads. Valid options: ${VALID_CONFIG_FIELDS}`
         )
       }).strict(),
-      z4.object({
-        operation: z4.literal("update"),
-        field_name: z4.string().describe(
+      z8.object({
+        operation: z8.literal("update"),
+        field_name: z8.string().describe(
           `The configuration field to update. Valid options: ${VALID_CONFIG_FIELDS}. Always call with operation: "get" first to read the current value. For install bootstrap, prefer apply_install_manifest over many individual updates. Returns 400 if the field name is invalid, 404 if no configuration row exists.`
         ),
-        value: z4.union([
-          z4.string(),
-          z4.boolean(),
-          z4.array(z4.string()),
-          z4.record(z4.string(), z4.union([z4.string(), z4.null()]))
+        value: z8.union([
+          z8.string(),
+          z8.boolean(),
+          z8.array(z8.string()),
+          z8.record(z8.string(), z8.union([z8.string(), z8.null()]))
         ]).optional().describe(
           `The new value for the configuration field. Provide either value or file_path, not both. Most fields take a string; scalar boolean fields (e.g. allow_mutating_smoke_ops, difficulty_model_routing_enabled) take true/false. The selected_mcp_slugs field takes a JSON array of supported MCP validation manual slug strings (e.g. ["b2c-commerce-developer", "playwright-mcp", "pwa-kit-mcp"]) \u2014 pass an array of strings, not a comma-delimited string; an empty array clears the selection. The difficulty_model_tier_overrides field takes a JSON object mapping tier names ("cheap"/"basic"/"premium") to per-repo model aliases (e.g. {"premium": "opus"}) \u2014 pass an object, not a string; an empty object clears all overrides. The difficulty_model_routing_enabled field enables difficulty-based /start-tickets model routing (default ON); pass true/false. The base_branch field is a string/null field controlling the development base branch used by PR creation (/create-pr) and start-tickets worktree creation; an empty/null value clears it and automations fall back to 'main'. For string fields, omit both value and file_path to set the field to NULL (clearing it). Scalar boolean fields are NOT NULL and have no clear/null state: omitting the value writes false (matching the API-layer coercion), so pass true/false explicitly.`
         ),
-        file_path: z4.string().optional().describe(
+        file_path: z8.string().optional().describe(
           "Path to a local file whose contents will be used as the new value. Useful for large configuration values like detailed review instructions. The file must be UTF-8 encoded and under 1MB. Not supported for scalar boolean fields like allow_mutating_smoke_ops."
         ),
-        only_if_null: z4.boolean().optional().describe(
+        only_if_null: z8.boolean().optional().describe(
           "Secondary conditional-write guard: when true, the field is updated only if its column is currently NULL (returns status 'skipped'/reason 'already_set' otherwise). Legal only for nullable columns (HTTP 422 otherwise). For easy install, prefer apply_install_manifest."
         )
       }).strict(),
-      z4.object({
-        operation: z4.literal("list")
+      z8.object({
+        operation: z8.literal("list")
       }).strict()
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ])
@@ -23083,10 +24442,10 @@ registerTool(
     },
     description: 'Apply easy-install configuration in one atomic call. Pass the snapshot_token returned by get_install_manifest plus a fields object. Each field value is either a scalar (e.g. "base_branch": "main") or an object (e.g. "project_description": {"value": "...", "confirmed": true}). project_description MUST be passed as {value, confirmed: true} and only after explicit human approval. The server owns skip-if-set, conflict detection, and confirmation semantics and returns six buckets: applied, skipped, conflict, rejected, deferred, needs_confirmation. Only bootstrap-eligible fields are accepted (others are rejected).',
     inputSchema: {
-      snapshot_token: z4.string().describe(
+      snapshot_token: z8.string().describe(
         "The exact snapshot_token returned by get_install_manifest for this repository."
       ),
-      fields: z4.record(z4.string(), z4.any()).describe(
+      fields: z8.record(z8.string(), z8.any()).describe(
         'Map of field_name to value. A value is either a scalar or an object {value, confirmed}. Pass project_description only as {value: "...", confirmed: true} after human approval.'
       )
     }
@@ -23100,7 +24459,25 @@ registerTool(
         body: JSON.stringify({ repo_name: REPO_NAME, snapshot_token, fields })
       }
     );
-    const text = await handleResponse(resp);
+    let text = await handleResponse(resp);
+    try {
+      const wiResp = await fetch(
+        buildGetUrl("/config-field/working_in", { repo_name: REPO_NAME }),
+        { headers: await getGetHeaders() }
+      );
+      if (wiResp.ok) {
+        const wiBody = await wiResp.json();
+        if (wiBody.value === "Salesforce Commerce Cloud") {
+          const newProfile = await mergeBridgeApiProfileToken(await getProjectRoot(), "sfcc");
+          if (newProfile) {
+            text += `
+
+\u26A0\uFE0F  SFCC profile updated: BRIDGE_MCP_PROFILE is now set to \`${newProfile}\` in your local MCP config file(s). This activates on the next MCP server launch \u2014 restart your MCP client to gain access to the SFCC read tools.`;
+          }
+        }
+      }
+    } catch {
+    }
     return { content: [{ type: "text", text }] };
   }
 );
@@ -23115,7 +24492,7 @@ registerTool(
     },
     description: "Persist the ALREADY-VALIDATED Bridge API key for this repo into the user-scoped credential store (`~/.config/bridge/credentials.json`) under the target `bapi:<repo_name>`, so that Bash-spawned CLI features such as `start-tickets` (a different runtime surface than the MCP server) can resolve it for difficulty\u2192model routing. This is the final stage of `/install-bridge`. The key is resolved INSIDE the MCP server process (env-first, then the existing store) using the provided `repo_name` as the store identity \u2014 it is NEVER passed as a tool argument. Existing credentials are preserved; only `BAPI_API_KEY` for this repo is upserted. The response is secret-free (it reports ok/action/target/path only) and never echoes the key value.",
     inputSchema: {
-      repo_name: z4.string().describe(
+      repo_name: z8.string().describe(
         "The repository name to store the routing credential under (target `bapi:<repo_name>`). This is the ONLY input \u2014 do not pass the API key, a secret, or a token; the key is resolved inside the MCP server process."
       )
     }
@@ -23250,10 +24627,10 @@ registerTool(
     },
     description: "Use to start async deep research on a technical topic using AI-powered web search. Returns a task_id immediately (or the full report if wait_for_result is true). Use get_deep_research to retrieve. Generates and persists a retrievable artifact.",
     inputSchema: {
-      query: z4.string().describe(
+      query: z8.string().describe(
         "The research query. Be specific and detailed about what you need to learn. Good: 'What are the tradeoffs between Redis, Memcached, and DynamoDB DAX for caching in a Python FastAPI application serving 10k RPM, including connection pooling, serialization overhead, and failure modes?' Bad: 'caching options' (too vague \u2014 use a web search instead)"
       ),
-      context: z4.string().optional().describe(
+      context: z8.string().optional().describe(
         "Optional context to focus the research scope. Describe your current task, tech stack, and constraints. Example: 'I am building a FastAPI application that uses PostgreSQL and needs to implement real-time notifications. Focus on Python-specific solutions compatible with async frameworks.'"
       ),
       ticket_number: commonFields.ticket_number.optional(),
@@ -23348,10 +24725,10 @@ registerTool(
     },
     description: "RETRIEVE the result of a previously submitted deep research request. This tool only fetches an existing/in-progress result \u2014 it does NOT start or trigger new research. If you have not submitted a research request yet (or you need a new one), call `request_deep_research` first; it starts the async research and this `get_deep_research` tool retrieves the result. Returns the full markdown research report if the task is completed, or a structured status response (still processing / failed / not-found) if the report is not ready yet \u2014 that means research has not finished, not that this tool failed. Use this after calling request_deep_research with wait_for_result=false.",
     inputSchema: {
-      task_id: z4.number().describe(
+      task_id: z8.number().describe(
         "The task ID returned by request_deep_research."
       ),
-      query_slug: z4.string().optional().describe(
+      query_slug: z8.string().optional().describe(
         "Optional slug derived from the original query, used for the saved filename. If omitted, the file is saved as 'research-{task_id}.md'."
       ),
       save_locally: commonFields.save_locally
@@ -23473,26 +24850,26 @@ registerTool(
     },
     description: "Use to start an async brainstorm that fans out a task to opinion-provider LLMs. Returns a brainstorm_id immediately (or the full result envelope if wait_for_result is true). Use get_brainstorm to retrieve. Generates and persists a retrievable artifact.",
     inputSchema: {
-      task_description: z4.string().describe(
+      task_description: z8.string().describe(
         "Free-form description of the task to brainstorm about. Sent verbatim \u2014 this tool does NOT read task_description from a file."
       ),
       repo_name: commonFields.repo_name,
       ticket_number: commonFields.ticket_number.optional(),
-      providers: z4.array(z4.string()).optional().describe(
+      providers: z8.array(z8.string()).optional().describe(
         "Opinion-provider LLMs. Defaults to ['openai', 'gemini']. A single-provider request runs one opinion provider and returns that provider's markdown directly."
       ),
-      concerns: z4.string().optional().describe(
+      concerns: z8.string().optional().describe(
         "Optional caller-supplied concerns to surface to the brainstorm agents."
       ),
       wait_for_result: commonFields.wait_for_result,
       save_locally: commonFields.save_locally,
-      prior_brainstorm_id: z4.string().optional().describe(
+      prior_brainstorm_id: z8.string().optional().describe(
         "Optional brainstorm_id from an earlier brainstorm to refine. When provided, the prior brainstorm's completed opinion-provider markdowns are concatenated and supplied as prior context."
       ),
-      mode: z4.enum(["technical", "design", "discovery"]).optional().describe(
+      mode: z8.enum(["technical", "design", "discovery"]).optional().describe(
         "Preferred brainstorm-mode selector for new callers. 'technical' (default) is the implementation/architecture brainstorm; 'design' is web-page/UI visual-direction ideation; 'discovery' generates grouped technical and business/stakeholder discovery questions for early/vague tasks. Takes precedence over the legacy boolean design field."
       ),
-      design: z4.boolean().optional().describe(
+      design: z8.boolean().optional().describe(
         'Legacy compatibility flag: set to true for web-page/UI design ideation focused on visual appeal and conversion. New callers should use mode: "design" instead. Omit this field when not requesting design mode; absent is treated as false.'
       )
     }
@@ -23584,7 +24961,7 @@ registerTool(
     },
     description: "Use to retrieve the result envelope for a previously submitted brainstorm by brainstorm_id. Returns opinion-provider rows only (including error_kind for each row). Does NOT start a new brainstorm \u2014 use request_brainstorm first if none exists. Returns not-found when still processing.",
     inputSchema: {
-      brainstorm_id: z4.string().describe(
+      brainstorm_id: z8.string().describe(
         "The brainstorm_id (UUID) returned by request_brainstorm."
       ),
       repo_name: commonFields.repo_name,
@@ -23627,10 +25004,10 @@ registerTool(
     },
     description: "Create a pull request on the configured VCS provider (GitHub or Bitbucket). Returns a structured response with {available, reason, action, detail}. If a PR already exists for the head branch, returns it with created=false. Capability issues (missing VCS config, API errors) return available=false, not errors. The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-      head_branch: z4.string().describe("The source branch name for the pull request"),
-      base_branch: z4.string().describe("The target/destination branch name for the pull request"),
-      title: z4.string().describe("The title of the pull request"),
-      body: z4.string().optional().describe("The description/body of the pull request")
+      head_branch: z8.string().describe("The source branch name for the pull request"),
+      base_branch: z8.string().describe("The target/destination branch name for the pull request"),
+      title: z8.string().describe("The title of the pull request"),
+      body: z8.string().optional().describe("The description/body of the pull request")
     }
   },
   async ({ head_branch, base_branch, title, body }) => {
@@ -23664,8 +25041,8 @@ var resolveCiChecksTool = registerTool(
     },
     description: "Discover and classify CI checks for the configured repository. Queries GitHub Check Runs + Commit Statuses APIs (or Bitbucket Build Statuses), then uses Branch Protection API or LLM to determine which checks are required for merging. Results are cached per-project \u2014 subsequent calls return cached config unless force_rerun is true. Returns {available, reason, action, detail} envelope. The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-      commit_ref: z4.string().describe("Git commit SHA to discover checks for"),
-      force_rerun: z4.boolean().optional().describe("Set to true to bypass cache and re-resolve CI checks")
+      commit_ref: z8.string().describe("Git commit SHA to discover checks for"),
+      force_rerun: z8.boolean().optional().describe("Set to true to bypass cache and re-resolve CI checks")
     }
   },
   async ({ commit_ref, force_rerun }) => {
@@ -23704,7 +25081,7 @@ var pollCiChecksTool = registerTool(
     },
     description: "Poll the current status of CI checks for a specific commit. Requires that resolve_ci_checks has been called first to populate the check configuration. Returns per-check status, all_complete, all_passed, and unknown_checks fields. For failed checks with detail_level 'full', includes annotations and/or log tails. Returns {available, reason, action, detail} envelope. The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-      commit_ref: z4.string().describe("Git commit SHA to poll CI checks for")
+      commit_ref: z8.string().describe("Git commit SHA to poll CI checks for")
     }
   },
   async ({ commit_ref }) => {
@@ -23801,14 +25178,14 @@ registerTool(
     },
     description: "Retrieve a fully resolved pipeline recipe by name. Substitutes variables, resolves instruction file references to inline content, and returns an ordered array of executable steps. Each step is either an mcp_call (with tool name and params) or an agent_task (with instruction text). Use list_pipelines to discover available pipeline names first. Note: the 'docs_dir' variable is automatically set from BAPI_DOCS_DIR \u2014 callers should omit it.",
     inputSchema: {
-      pipeline: z4.string().describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
-      variables: z4.record(z4.string(), z4.string()).optional().describe(
+      pipeline: z8.string().describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
+      variables: z8.record(z8.string(), z8.string()).optional().describe(
         "Key-value pairs for variable substitution (e.g. { ticket_key: 'BAPI-123' })"
       ),
-      skip_steps: z4.array(z4.string()).optional().describe(
+      skip_steps: z8.array(z8.string()).optional().describe(
         "Step tool names or descriptions to omit from the recipe"
       ),
-      auto_approve: z4.boolean().optional().describe(
+      auto_approve: z8.boolean().optional().describe(
         "When true, automatically approve all approval-gated steps. For implement-ticket this skips the commit/push approval pause; for review-ticket this skips the HTML decision page and selects each item's recommended option. Pass via this top-level parameter, not via the variables map."
       )
     }
@@ -23880,7 +25257,7 @@ registerTool(
     }
   }
 );
-if (profileIncludes(BRIDGE_MCP_PROFILE, "pipeline-authoring")) {
+if (ACTIVE_GROUPS.has("pipeline-authoring")) {
   registerTool(
     "list_pipelines",
     {
@@ -23919,14 +25296,14 @@ if (profileIncludes(BRIDGE_MCP_PROFILE, "pipeline-authoring")) {
       },
       description: "Execute a Bridge API pipeline by name. The orchestrator runs steps sequentially, dispatching mcp_call steps in-process and pausing on agent_task steps with a needs_agent_task envelope. Returns a unified envelope keyed on `status`: `completed` (terminal success with `results`), `needs_agent_task` (pause \u2014 read `instruction`, perform the task, then call `resume_pipeline` with the resulting string as `agent_result`), or `failed` (terminal error \u2014 check `error_code`: VALIDATION | NOT_FOUND | EXPIRED | REPO_MISMATCH | TOOL_ERROR). Paused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition.\n\nCall list_pipelines for the current resolved catalog of available pipeline names (bundled plus any custom user pipelines).",
       inputSchema: {
-        pipeline: z4.string().describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
-        variables: z4.record(z4.string(), z4.string()).optional().describe(
+        pipeline: z8.string().describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
+        variables: z8.record(z8.string(), z8.string()).optional().describe(
           "Key-value pairs for variable substitution (e.g. { ticket_key: 'BAPI-123' }). Do NOT pass `auto_approve` here \u2014 use the top-level parameter."
         ),
-        auto_approve: z4.union([z4.boolean(), z4.literal("true"), z4.literal("false")]).optional().describe(
+        auto_approve: z8.union([z8.boolean(), z8.literal("true"), z8.literal("false")]).optional().describe(
           "When true, approval-gated mcp_call steps execute directly. When false or omitted, the orchestrator synthesises a needs_agent_task pause so the agent can confirm with the user before resuming. Accepts boolean or 'true'/'false' strings for MCP clients that serialize booleans as strings."
         ),
-        ttl_seconds: z4.number().int().positive().optional().describe(
+        ttl_seconds: z8.number().int().positive().optional().describe(
           "Override the default 24-hour idle TTL for this run. Must be a positive integer."
         )
       }
@@ -23954,8 +25331,8 @@ if (profileIncludes(BRIDGE_MCP_PROFILE, "pipeline-authoring")) {
       },
       description: "Resume a paused pipeline run with the result of the agent_task. Provide the `pipeline_run_id` returned by the prior needs_agent_task envelope, and the string the instruction's `## Return` section asked you to produce as `agent_result`. `agent_result` is always a string \u2014 do not wrap it in JSON unless the instruction explicitly asked you to serialize structured output. Returns the same unified envelope shape as `run_pipeline`.",
       inputSchema: {
-        pipeline_run_id: z4.string().describe("The pipeline_run_id returned by a prior needs_agent_task envelope"),
-        agent_result: z4.string().describe(
+        pipeline_run_id: z8.string().describe("The pipeline_run_id returned by a prior needs_agent_task envelope"),
+        agent_result: z8.string().describe(
           "The string the paused instruction's ## Return section asked you to produce"
         )
       }
@@ -23983,7 +25360,7 @@ if (profileIncludes(BRIDGE_MCP_PROFILE, "pipeline-authoring")) {
       },
       description: "List recent pipeline runs for the configured repository, newest first. Returns metadata only \u2014 `resolved_recipe`, resolved params, instruction text, results, and agent outputs are intentionally excluded. Use this to recover a `pipeline_run_id` when an earlier needs_agent_task envelope is no longer in scope (e.g. after compaction or a client restart). Optionally filter by `status`: running | paused | completed | failed | expired.",
       inputSchema: {
-        status: z4.enum(["running", "paused", "completed", "failed", "expired"]).optional().describe("Optional status filter")
+        status: z8.enum(["running", "paused", "completed", "failed", "expired"]).optional().describe("Optional status filter")
       }
     },
     async (input) => {
@@ -24009,7 +25386,7 @@ if (profileIncludes(BRIDGE_MCP_PROFILE, "pipeline-authoring")) {
       },
       description: "Delete a pipeline run row (any status). Use this to discard orphaned `running` rows from a previous session that can't be resumed (resume_pipeline only accepts `paused`), to clean up after a failed run, or to remove a no-longer-needed paused session. Returns `{ status: 'completed', deleted: true, pipeline_run_id }` on success, or a `failed` envelope with error_code in (VALIDATION | NOT_FOUND | REPO_MISMATCH | TOOL_ERROR). Repo-scoped: the row's stored repo_name must match the caller's repo.",
       inputSchema: {
-        pipeline_run_id: z4.string().describe("UUID of the pipeline run to delete.")
+        pipeline_run_id: z8.string().describe("UUID of the pipeline run to delete.")
       }
     },
     async (input) => {
@@ -24036,14 +25413,14 @@ registerTool(
     },
     description: "Run the full-automation chain for an idea: create ticket(s) (idea-to-ticket), review each created ticket (review-ticket fan-out), then emit the exact `/start-tickets ...` command for you to invoke in this same session. Returns the chain envelope keyed on `status`: `needs_agent_task` (perform the `next_action.instruction`, then call `resume_full_automation` with the result as `agent_result`), `completed`, or `failed` (check `error_code`: VALIDATION | NOT_FOUND | EXPIRED | REPO_MISMATCH | TOOL_ERROR). Provide the idea via `idea` or `idea_file` (mutually exclusive).",
     inputSchema: {
-      idea: z4.string().optional(),
-      idea_file: z4.string().optional(),
-      auto_approve: z4.union([z4.boolean(), z4.literal("true"), z4.literal("false")]).optional(),
-      scheduled_at: z4.string().optional(),
-      max_children: z4.number().int().positive().optional(),
-      allow_duplicate: z4.boolean().optional(),
-      agent: z4.enum(["claude"]).optional(),
-      ttl_seconds: z4.number().int().positive().optional()
+      idea: z8.string().optional(),
+      idea_file: z8.string().optional(),
+      auto_approve: z8.union([z8.boolean(), z8.literal("true"), z8.literal("false")]).optional(),
+      scheduled_at: z8.string().optional(),
+      max_children: z8.number().int().positive().optional(),
+      allow_duplicate: z8.boolean().optional(),
+      agent: z8.enum(["claude"]).optional(),
+      ttl_seconds: z8.number().int().positive().optional()
     }
   },
   async (input) => {
@@ -24086,8 +25463,8 @@ registerTool(
     },
     description: "Resume a paused full-automation chain run. Provide the `chain_run_id` returned by the prior needs_agent_task envelope and the string the instruction asked you to produce as `agent_result`. Returns the same chain envelope shape as `run_full_automation`.",
     inputSchema: {
-      chain_run_id: z4.string(),
-      agent_result: z4.string()
+      chain_run_id: z8.string(),
+      agent_result: z8.string()
     }
   },
   async (input) => {
@@ -24106,7 +25483,7 @@ function containsUnsafeEncodedPathToken(value) {
   return /%2e/i.test(value) || /%2f/i.test(value) || /%5c/i.test(value);
 }
 function isPlatformAbsolutePath(value) {
-  return path21.posix.isAbsolute(value) || path21.win32.isAbsolute(value) || path21.isAbsolute(value);
+  return path26.posix.isAbsolute(value) || path26.win32.isAbsolute(value) || path26.isAbsolute(value);
 }
 function validateDecisionPageOutputSubdir(value) {
   if (value.trim().length === 0) {
@@ -24156,9 +25533,9 @@ async function resolveDecisionPageOutputTarget(outputSubdir, outputFilename) {
   if (subdirError) return { ok: false, message: subdirError };
   const filenameError = validateDecisionPageOutputFilename(outputFilename);
   if (filenameError) return { ok: false, message: filenameError };
-  const docsBase = path21.resolve(await getDocsDir());
-  const resolvedTarget = path21.resolve(docsBase, outputSubdir, outputFilename);
-  if (!resolvedTarget.startsWith(docsBase + path21.sep)) {
+  const docsBase = path26.resolve(await getDocsDir());
+  const resolvedTarget = path26.resolve(docsBase, outputSubdir, outputFilename);
+  if (!resolvedTarget.startsWith(docsBase + path26.sep)) {
     return {
       ok: false,
       message: `Invalid output target: the resolved output path must stay under the docs directory.`
@@ -24166,7 +25543,7 @@ async function resolveDecisionPageOutputTarget(outputSubdir, outputFilename) {
   }
   return {
     ok: true,
-    docsPath: path21.dirname(resolvedTarget),
+    docsPath: path26.dirname(resolvedTarget),
     filePath: resolvedTarget
   };
 }
@@ -24211,7 +25588,7 @@ registerTool(
     try {
       parsed = DecisionPageInputSchema.parse(rawPayload);
     } catch (err) {
-      if (err instanceof z4.ZodError) {
+      if (err instanceof z8.ZodError) {
         return validationError(formatDecisionPageValidationError(err));
       }
       throw err;
@@ -24254,43 +25631,43 @@ registerTool(
       return validationError(outputTarget.message);
     }
     const projectRootForAssets = await getProjectRoot();
-    const pkgRoot = path21.resolve(path21.dirname(fileURLToPath4(import.meta.url)), "../");
+    const pkgRoot = path26.resolve(path26.dirname(fileURLToPath4(import.meta.url)), "../");
     let assetsDir;
     try {
-      await stat8(path21.join(projectRootForAssets, "design-assets"));
-      assetsDir = path21.join(projectRootForAssets, "design-assets");
+      await stat8(path26.join(projectRootForAssets, "design-assets"));
+      assetsDir = path26.join(projectRootForAssets, "design-assets");
     } catch {
-      assetsDir = path21.join(pkgRoot, "design-assets");
+      assetsDir = path26.join(pkgRoot, "design-assets");
     }
     let fontsDir;
     try {
-      await stat8(path21.join(projectRootForAssets, "public", "fonts"));
-      fontsDir = path21.join(projectRootForAssets, "public", "fonts");
+      await stat8(path26.join(projectRootForAssets, "public", "fonts"));
+      fontsDir = path26.join(projectRootForAssets, "public", "fonts");
     } catch {
-      fontsDir = path21.join(pkgRoot, "public", "fonts");
+      fontsDir = path26.join(pkgRoot, "public", "fonts");
     }
     let faviconBase64 = "";
     let logoBase64 = "";
     try {
-      const faviconBuf = await readFile10(path21.join(assetsDir, "favicon", "favicon-32x32.png"));
+      const faviconBuf = await readFile11(path26.join(assetsDir, "favicon", "favicon-32x32.png"));
       faviconBase64 = faviconBuf.toString("base64");
     } catch {
     }
     try {
-      const logoBuf = await readFile10(path21.join(assetsDir, "just-logo-rough-draft.png"));
+      const logoBuf = await readFile11(path26.join(assetsDir, "just-logo-rough-draft.png"));
       logoBase64 = logoBuf.toString("base64");
     } catch {
     }
     const docsPath = outputTarget.docsPath;
     const filePath = outputTarget.filePath;
-    const fontsRelPath = path21.relative(docsPath, fontsDir);
+    const fontsRelPath = path26.relative(docsPath, fontsDir);
     const html = generateDecisionPageHtml(parsed, {
       faviconBase64,
       logoBase64,
       fontsRelPath
     });
-    await mkdir8(docsPath, { recursive: true });
-    await writeFile8(filePath, html, "utf-8");
+    await mkdir10(docsPath, { recursive: true });
+    await writeFile10(filePath, html, "utf-8");
     return {
       content: [{
         type: "text",