@bridge_gpt/mcp-server 0.2.24 → 0.2.25

package/build/index.js

@@ -19,7 +19,7 @@ var VERSION;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    VERSION = "0.2.24";
+    VERSION = "0.2.25";
   }
 });
 
@@ -1584,14 +1584,14 @@ function credentialResolutionDescriptor() {
     label: "Bridge API credential resolution",
     installHint: CREDENTIAL_RESOLUTION_INSTALL_HINTS,
     probe: async (deps) => {
-      const { readFile: readFile14, stat: stat10, homedir } = deps;
-      if (!readFile14 || !stat10 || !homedir) {
+      const { readFile: readFile15, stat: stat11, homedir } = deps;
+      if (!readFile15 || !stat11 || !homedir) {
         return { found: false, detail: "credential probe unavailable (no read-only filesystem access)" };
       }
       const repoName = await resolveStartTicketsRepoName({
         env: deps.env,
         cwd: deps.cwd,
-        readFile: readFile14
+        readFile: readFile15
       });
       if (!repoName) {
         return {
@@ -1604,8 +1604,8 @@ function credentialResolutionDescriptor() {
         env: deps.env,
         homedir,
         platform: deps.platform,
-        readFile: readFile14,
-        stat: stat10
+        readFile: readFile15,
+        stat: stat11
       });
       if (result.ok) {
         const detail = result.credentials.source === "env" ? `credentials resolvable via env for repo ${repoName}` : `credentials resolvable via store target bapi:${repoName} at ${storePath}`;
@@ -1624,11 +1624,11 @@ function worktreeMcpReachabilityDescriptor() {
     label: "Worktree MCP registration reachability",
     installHint: WORKTREE_MCP_INSTALL_HINTS,
     probe: async (deps) => {
-      const { readFile: readFile14 } = deps;
-      if (!readFile14) {
+      const { readFile: readFile15 } = deps;
+      if (!readFile15) {
         return { found: false, detail: "registration probe unavailable (no read-only filesystem access)" };
       }
-      const result = await probeWorktreeMcpRegistration(deps.cwd, { readFile: readFile14 });
+      const result = await probeWorktreeMcpRegistration(deps.cwd, { readFile: readFile15 });
       return { found: result.found, detail: result.detail };
     }
   };
@@ -2098,10 +2098,10 @@ function parseDeclaredTouchedFilesFromEnv(env = process.env) {
 }
 function collectBranchChangedFiles(opts = {}) {
   const baseRef = opts.baseRef ?? FILE_SCOPE_GUARD_BASE_REF;
-  const spawn8 = opts.spawnSyncFn ?? defaultSpawnSync;
+  const spawn9 = opts.spawnSyncFn ?? defaultSpawnSync;
   let result;
   try {
-    result = spawn8("git", ["diff", "--name-only", `${baseRef}...HEAD`], {
+    result = spawn9("git", ["diff", "--name-only", `${baseRef}...HEAD`], {
       cwd: opts.cwd,
       encoding: "utf-8",
       shell: false
@@ -4373,8 +4373,8 @@ async function fetchPrReviewStatus(access2, prNumber, fetchImpl = globalThis.fet
 }
 function buildConductorVcsUrl(baseUrl, apiPath) {
   const trimmed = baseUrl.replace(/\/+$/, "");
-  const path34 = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
-  return new URL(`${trimmed}${path34}`).toString();
+  const path35 = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
+  return new URL(`${trimmed}${path35}`).toString();
 }
 function conductorPostHeaders(access2) {
   return { "X-API-Key": access2.apiKey, "Content-Type": "application/json" };
@@ -4780,8 +4780,8 @@ async function transitionEpicDispatch(access2, request, fetchImpl = globalThis.f
   if (request.nextStatus === "run_spawned") {
     requireNonEmptyString(request.runId);
   }
-  const path34 = epicDispatchTransitionApiPath(request.dispatchKey, request.nextStatus);
-  const url = buildConductorJiraUrl(access2.baseUrl, path34);
+  const path35 = epicDispatchTransitionApiPath(request.dispatchKey, request.nextStatus);
+  const url = buildConductorJiraUrl(access2.baseUrl, path35);
   const body = request.nextStatus === "run_spawned" ? JSON.stringify({ repo_name: access2.repoName, run_id: request.runId }) : JSON.stringify({ repo_name: access2.repoName });
   const parsed = await fetchConductorJsonPostWithTimeout(
     url,
@@ -6159,16 +6159,23 @@ async function pruneStaleLaunchScripts(deps = defaultPruneStaleLaunchScriptsDeps
   }
 }
 async function materializeWorkerLaunchCommand(deps, key, fullCommand) {
-  if (!deps.writeWorkerLaunchScript) return fullCommand;
+  if (!deps.writeWorkerLaunchScript) return { ok: true, command: fullCommand };
   try {
     const scriptPath = await deps.writeWorkerLaunchScript({
       platform: deps.platform,
       key,
       content: buildLaunchScriptContent(deps.platform, fullCommand)
     });
-    return buildLaunchScriptRunnerCommand(deps.platform, scriptPath);
+    return { ok: true, command: buildLaunchScriptRunnerCommand(deps.platform, scriptPath) };
   } catch {
-    return fullCommand;
+    if (Buffer.byteLength(fullCommand, "utf8") <= MAX_TERMINAL_COMMAND_BYTES) {
+      return { ok: true, command: fullCommand };
+    }
+    return {
+      ok: false,
+      reason: "launch-script-write-failed-oversized-command",
+      error: "Could not write the temporary launch script, and the full command is too long to send to the terminal directly. Check that the system temporary directory is writable."
+    };
   }
 }
 async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildShellCommand) {
@@ -6184,8 +6191,12 @@ async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildShellComm
       baseShellCommand,
       row.conductorEnv
     );
-    const runnableCommand = await materializeWorkerLaunchCommand(deps, row.key, shellCommand);
-    const result = await deps.spawnTerminalTab(deps, terminal, runnableCommand, {
+    const materialized = await materializeWorkerLaunchCommand(deps, row.key, shellCommand);
+    if (!materialized.ok) {
+      out.push({ ...row, status: "spawn-failed", error: materialized.error });
+      continue;
+    }
+    const result = await deps.spawnTerminalTab(deps, terminal, materialized.command, {
       key: row.key,
       worktreePath: row.path
     });
@@ -7131,7 +7142,7 @@ async function runStartTicketsCli(argv, overrides = {}) {
   }
   return 0;
 }
-var TICKET_KEY_PATTERN, DEFAULT_MAX_PARALLEL, DEFAULT_TMUX_SESSION_PREFIX, TMUX_SESSION_OVERRIDE_ENV, STALE_LAUNCH_SCRIPT_MAX_AGE_MS, defaultPruneStaleLaunchScriptsDeps, defaultWriteWorkerLaunchScript, START_TICKETS_DEFAULT_BASE_URL, TICKET_MODEL_TIER_FETCH_TIMEOUT_MS, CONFIG_FIELD_FETCH_TIMEOUT_MS, CURSOR_MODEL_LIST_TIMEOUT_MS, StartTicketsHttpError, isCreatedRoutingEligible, isDryRunRoutingEligible;
+var TICKET_KEY_PATTERN, DEFAULT_MAX_PARALLEL, DEFAULT_TMUX_SESSION_PREFIX, TMUX_SESSION_OVERRIDE_ENV, STALE_LAUNCH_SCRIPT_MAX_AGE_MS, defaultPruneStaleLaunchScriptsDeps, defaultWriteWorkerLaunchScript, MAX_TERMINAL_COMMAND_BYTES, START_TICKETS_DEFAULT_BASE_URL, TICKET_MODEL_TIER_FETCH_TIMEOUT_MS, CONFIG_FIELD_FETCH_TIMEOUT_MS, CURSOR_MODEL_LIST_TIMEOUT_MS, StartTicketsHttpError, isCreatedRoutingEligible, isDryRunRoutingEligible;
 var init_start_tickets = __esm({
   "src/start-tickets.ts"() {
     "use strict";
@@ -7171,6 +7182,7 @@ var init_start_tickets = __esm({
       await writeFile3(file, content, { mode: 384 });
       return file;
     };
+    MAX_TERMINAL_COMMAND_BYTES = 1024;
     START_TICKETS_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
     TICKET_MODEL_TIER_FETCH_TIMEOUT_MS = 75e3;
     CONFIG_FIELD_FETCH_TIMEOUT_MS = 3e4;
@@ -14390,9 +14402,9 @@ var init_supervisor_runtime = __esm({
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z16 } from "zod";
-import { writeFile as writeFile12, mkdir as mkdir12, readFile as readFile13, stat as stat9, rename as rename3, chmod as chmod3, unlink as unlink3, mkdtemp as mkdtemp3, rm as rm3, readdir as readdir3, open as open2 } from "fs/promises";
-import path33 from "path";
-import os15 from "os";
+import { writeFile as writeFile12, mkdir as mkdir12, readFile as readFile14, stat as stat10, rename as rename3, chmod as chmod3, unlink as unlink3, mkdtemp as mkdtemp3, rm as rm3, readdir as readdir3, open as open2 } from "fs/promises";
+import path34 from "path";
+import os16 from "os";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/pipelines.generated.ts
@@ -14591,7 +14603,7 @@ var PIPELINES = {
   },
   "learn-repository": {
     "name": "learn-repository",
-    "description": "Learn and document all configuration fields for the repository by running sequential research agents.",
+    "description": "Learn and document the repository's configuration fields. Researches every unlearned field in parallel by reading the local codebase, skips fields that are already populated, applies ordinary learned fields automatically with no mid-run approval prompts, and closes with a single confirmation round for the fields the server requires a human to confirm.",
     "variables": [
       "docs_dir"
     ],
@@ -14609,6 +14621,7 @@ var PIPELINES = {
       },
       {
         "type": "mcp_call",
+        "id": "fetch_architecture_instructions",
         "tool": "config_field",
         "params": {
           "field_name": "architecture_instructions",
@@ -14617,255 +14630,246 @@ var PIPELINES = {
         "description": "Fetch current architecture_instructions value",
         "on_error": "warn_and_continue"
       },
-      {
-        "type": "agent_task",
-        "instruction_file": "learn-architecture.md",
-        "description": "Learn and document architecture instructions"
-      },
       {
         "type": "mcp_call",
+        "id": "fetch_review_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "architecture_instructions",
-          "file_path": "{docs_dir}/standards/architecture_instructions.md",
-          "operation": "update"
+          "field_name": "review_instructions",
+          "operation": "get"
         },
-        "description": "Upload architecture_instructions to config",
-        "requires_approval": true
+        "description": "Fetch current review_instructions value",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "fetch_documentation_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "review_instructions",
+          "field_name": "documentation_instructions",
           "operation": "get"
         },
-        "description": "Fetch current review_instructions value",
+        "description": "Fetch current documentation_instructions value",
         "on_error": "warn_and_continue"
       },
-      {
-        "type": "agent_task",
-        "instruction_file": "learn-review-instructions.md",
-        "description": "Learn and document review instructions"
-      },
       {
         "type": "mcp_call",
+        "id": "fetch_unit_testing_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "review_instructions",
-          "file_path": "{docs_dir}/standards/review_instructions.md",
-          "operation": "update"
+          "field_name": "unit_testing_instructions",
+          "operation": "get"
         },
-        "description": "Upload review_instructions to config",
-        "requires_approval": true
+        "description": "Fetch current unit_testing_instructions value",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "fetch_e2e_testing_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "documentation_instructions",
+          "field_name": "e2e_testing_instructions",
           "operation": "get"
         },
-        "description": "Fetch current documentation_instructions value",
+        "description": "Fetch current e2e_testing_instructions value",
         "on_error": "warn_and_continue"
       },
-      {
-        "type": "agent_task",
-        "instruction_file": "learn-documentation-instructions.md",
-        "description": "Learn and document documentation instructions"
-      },
       {
         "type": "mcp_call",
+        "id": "fetch_frontend_correctness_standards",
         "tool": "config_field",
         "params": {
-          "field_name": "documentation_instructions",
-          "file_path": "{docs_dir}/standards/documentation_instructions.md",
-          "operation": "update"
+          "field_name": "frontend_correctness_standards",
+          "operation": "get"
         },
-        "description": "Upload documentation_instructions to config",
-        "requires_approval": true
+        "description": "Fetch current frontend_correctness_standards value",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "fetch_backend_correctness_standards",
         "tool": "config_field",
         "params": {
-          "field_name": "unit_testing_instructions",
+          "field_name": "backend_correctness_standards",
           "operation": "get"
         },
-        "description": "Fetch current unit_testing_instructions value",
+        "description": "Fetch current backend_correctness_standards value",
         "on_error": "warn_and_continue"
       },
       {
-        "type": "agent_task",
-        "instruction_file": "learn-unit-testing.md",
-        "description": "Learn and document unit testing instructions"
+        "type": "mcp_call",
+        "id": "fetch_template_correctness_standards",
+        "tool": "config_field",
+        "params": {
+          "field_name": "template_correctness_standards",
+          "operation": "get"
+        },
+        "description": "Fetch current template_correctness_standards value",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "fetch_style_correctness_standards",
         "tool": "config_field",
         "params": {
-          "field_name": "unit_testing_instructions",
-          "file_path": "{docs_dir}/standards/unit_testing_instructions.md",
-          "operation": "update"
+          "field_name": "style_correctness_standards",
+          "operation": "get"
         },
-        "description": "Upload unit_testing_instructions to config",
-        "requires_approval": true
+        "description": "Fetch current style_correctness_standards value",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "fetch_design_principles",
         "tool": "config_field",
         "params": {
-          "field_name": "e2e_testing_instructions",
+          "field_name": "design_principles",
           "operation": "get"
         },
-        "description": "Fetch current e2e_testing_instructions value",
+        "description": "Fetch current design_principles value",
         "on_error": "warn_and_continue"
       },
       {
         "type": "agent_task",
-        "instruction_file": "learn-e2e-testing.md",
-        "description": "Learn and document E2E testing instructions"
+        "id": "research_fan_out",
+        "instruction_file": "learn-repository-fan-out.md",
+        "description": "Research all learned fields in parallel (one subagent per field)"
       },
       {
         "type": "mcp_call",
+        "id": "upload_architecture_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "e2e_testing_instructions",
-          "file_path": "{docs_dir}/standards/e2e_testing_instructions.md",
-          "operation": "update"
+          "field_name": "architecture_instructions",
+          "file_path": "{docs_dir}/standards/architecture_instructions.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Upload e2e_testing_instructions to config",
-        "requires_approval": true
+        "description": "Upload architecture_instructions to config",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "upload_review_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "frontend_correctness_standards",
-          "operation": "get"
+          "field_name": "review_instructions",
+          "file_path": "{docs_dir}/standards/review_instructions.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Fetch current frontend_correctness_standards value",
+        "description": "Upload review_instructions to config",
         "on_error": "warn_and_continue"
       },
-      {
-        "type": "agent_task",
-        "instruction_file": "learn-frontend-correctness.md",
-        "description": "Learn and document frontend_correctness standards"
-      },
       {
         "type": "mcp_call",
+        "id": "upload_documentation_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "frontend_correctness_standards",
-          "file_path": "{docs_dir}/standards/frontend_correctness_standards.md",
-          "operation": "update"
+          "field_name": "documentation_instructions",
+          "file_path": "{docs_dir}/standards/documentation_instructions.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Upload frontend_correctness_standards to config",
-        "requires_approval": true
+        "description": "Upload documentation_instructions to config",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "upload_unit_testing_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "backend_correctness_standards",
-          "operation": "get"
+          "field_name": "unit_testing_instructions",
+          "file_path": "{docs_dir}/standards/unit_testing_instructions.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Fetch current backend_correctness_standards value",
+        "description": "Upload unit_testing_instructions to config",
         "on_error": "warn_and_continue"
       },
-      {
-        "type": "agent_task",
-        "instruction_file": "learn-backend-correctness.md",
-        "description": "Learn and document backend_correctness standards"
-      },
       {
         "type": "mcp_call",
+        "id": "upload_e2e_testing_instructions",
         "tool": "config_field",
         "params": {
-          "field_name": "backend_correctness_standards",
-          "file_path": "{docs_dir}/standards/backend_correctness_standards.md",
-          "operation": "update"
+          "field_name": "e2e_testing_instructions",
+          "file_path": "{docs_dir}/standards/e2e_testing_instructions.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Upload backend_correctness_standards to config",
-        "requires_approval": true
+        "description": "Upload e2e_testing_instructions to config",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "upload_frontend_correctness_standards",
         "tool": "config_field",
         "params": {
-          "field_name": "template_correctness_standards",
-          "operation": "get"
+          "field_name": "frontend_correctness_standards",
+          "file_path": "{docs_dir}/standards/frontend_correctness_standards.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Fetch current template_correctness_standards value",
+        "description": "Upload frontend_correctness_standards to config",
         "on_error": "warn_and_continue"
       },
-      {
-        "type": "agent_task",
-        "instruction_file": "learn-template-correctness.md",
-        "description": "Learn and document template_correctness standards"
-      },
       {
         "type": "mcp_call",
+        "id": "upload_backend_correctness_standards",
         "tool": "config_field",
         "params": {
-          "field_name": "template_correctness_standards",
-          "file_path": "{docs_dir}/standards/template_correctness_standards.md",
-          "operation": "update"
+          "field_name": "backend_correctness_standards",
+          "file_path": "{docs_dir}/standards/backend_correctness_standards.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Upload template_correctness_standards to config",
-        "requires_approval": true
+        "description": "Upload backend_correctness_standards to config",
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "upload_template_correctness_standards",
         "tool": "config_field",
         "params": {
-          "field_name": "style_correctness_standards",
-          "operation": "get"
+          "field_name": "template_correctness_standards",
+          "file_path": "{docs_dir}/standards/template_correctness_standards.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Fetch current style_correctness_standards value",
+        "description": "Upload template_correctness_standards to config",
         "on_error": "warn_and_continue"
       },
-      {
-        "type": "agent_task",
-        "instruction_file": "learn-style-correctness.md",
-        "description": "Learn and document style_correctness standards"
-      },
       {
         "type": "mcp_call",
+        "id": "upload_style_correctness_standards",
         "tool": "config_field",
         "params": {
           "field_name": "style_correctness_standards",
           "file_path": "{docs_dir}/standards/style_correctness_standards.md",
-          "operation": "update"
+          "operation": "update",
+          "only_if_null": true
         },
         "description": "Upload style_correctness_standards to config",
-        "requires_approval": true
+        "on_error": "warn_and_continue"
       },
       {
         "type": "mcp_call",
+        "id": "upload_design_principles",
         "tool": "config_field",
         "params": {
           "field_name": "design_principles",
-          "operation": "get"
+          "file_path": "{docs_dir}/standards/design_principles.md",
+          "operation": "update",
+          "only_if_null": true
         },
-        "description": "Fetch current design_principles value",
+        "description": "Upload design_principles to config",
         "on_error": "warn_and_continue"
       },
       {
         "type": "agent_task",
-        "instruction_file": "learn-design-principles.md",
-        "description": "Learn and document design principles"
-      },
-      {
-        "type": "mcp_call",
-        "tool": "config_field",
-        "params": {
-          "field_name": "design_principles",
-          "file_path": "{docs_dir}/standards/design_principles.md",
-          "operation": "update"
-        },
-        "description": "Upload design_principles to config",
-        "requires_approval": true
+        "id": "batched_confirmations",
+        "instruction_file": "learn-repository-confirmations.md",
+        "description": "Confirm and apply confirmation-required fields in one batched round"
       }
     ]
   },
@@ -15096,16 +15100,18 @@ var INSTRUCTIONS = {
   "frame-goals-and-nfrs.md": 'Frame the business goals, desired end-state, and non-functional requirements (NFRs) for this work before any functional decomposition or drafting. When the goals and the desired end-state of the system are clear, the functional requirements become much easier to design accurately. This step is documentary: it records the framing and classifies what is unclear. It does NOT pause and does NOT generate a decision page (interactive surfaces handle that separately).\n\n## Inputs\n\n- The idea or epic description for this run, plus any prior planning artifacts the earlier steps wrote into this run\'s working directory under `{docs_dir}` (for example: research findings, codebase exploration, resolved uncertainties, duplicate assessment). Read whichever of these exist; proceed without the ones that do not.\n\n## Instructions\n\n1. From the inputs, derive and state plainly:\n   - **Business goal** \u2014 the business value this work delivers and why it matters.\n   - **Desired end-state** \u2014 the concrete state the system should reach once this work is done.\n   - **System behavior** \u2014 how the system must behave to complete its task (the quality attributes in prose, not a feature list).\n\n2. Identify the non-functional requirements. Consider every one of these canonical NFR categories and include the ones that genuinely apply (omit categories that do not):\n   - security/privacy\n   - performance/latency\n   - reliability/failure-modes\n   - observability/auditability\n   - accessibility/UX\n   - data-integrity/migration\n   - compatibility\n   - operability/config\n   - compliance/SOC2\n   - rollout/reversibility\n\n   For each NFR you include, write three things: the `requirement`, its `implication` (what this requirement changes about the implementation), and a `status`. **An NFR with no concrete implication is boilerplate \u2014 drop it rather than record it.**\n\n3. Classify each NFR\'s `status` with this rubric:\n   - `confirmed` \u2014 only if it is explicitly stated in the idea/description/standards or is directly observable in the codebase.\n   - `assumed` \u2014 only if it is a low-risk, conventional, and reversible default.\n   - `open` \u2014 if it touches architecture, the data model, security, user-visible behavior, migration, or irreversible Jira creation and is not settled. Be willing to mark things `open`: surfacing an unclear NFR is the point of this step.\n\n4. If this work is an epic (it will be decomposed into multiple sub-tasks or child tickets), draft a provisional **recommended implementation order**. For each slice, record a short title, its hard prerequisites (`depends_on` \u2014 what must land first), any soft sequencing preferences (`recommended_after` \u2014 not hard blockers), and a one-line rationale. Keep hard prerequisites separate from soft sequencing. Do not create Jira dependency links \u2014 the order is delivered into the epic downstream.\n\n5. Write the framing to a file named `goals-and-nfrs.md` in this run\'s working directory \u2014 the **same directory the earlier exploration/research steps in this pipeline wrote to** under `{docs_dir}`. Getting this path right matters: downstream steps read `goals-and-nfrs.md` from that exact directory and silently degrade (they see no framing) if it lands elsewhere. The directory differs by pipeline:\n   - **plan-epic**: the epic plan directory, `docs/epic-plans/<epic-slug>/` (alongside `codebase-exploration.md` and `epic-plan.md`).\n   - **idea-to-ticket**: the run directory, `docs/idea-to-ticket/<slug>-<run-id>/` (alongside `research-pack.md` and `resolved-uncertainties.md`).\n\n   Use this structure (no markdown tables, no `- [ ]` checkboxes \u2014 BAPI-320 hygiene):\n\n```markdown\n# Goals & Non-Functional Requirements\n\n## Business Goal\n{business goal}\n\n## Desired End-State\n{desired end-state}\n\n## System Behavior\n{how the system must behave to complete its task}\n\n## Non-Functional Requirements\n- **{nfr category}** ({confirmed, assumed, or open}): {the requirement}. Implication: {what it changes about the implementation}.\n- ...\n\n## Recommended Implementation Order\n(Epics only; omit this section for a single task or spike.)\n1. {slice title} \u2014 depends on: {hard prerequisites or "none"}; recommended after: {soft preferences or "none"}. Rationale: {one line}.\n2. ...\n```\n\n## Return\n\nConfirm `goals-and-nfrs.md` was written, report the counts of `confirmed` / `assumed` / `open` NFRs, and state whether a recommended implementation order was produced (epics) or skipped (single task/spike).\n',
   "gather-and-attach-materials.md": 'Post-create materials-completeness step. Gather the reachable local text materials and eligible local design/UI comp images a freshly-created ticket references and attach them via `attachment` (operation: `"upload"`), while recording everything that is record-only. This is the POST-CREATE half of the upload-time materials-completeness pass (BAPI-423); the PRE-CREATE half \u2014 inventorying and writing the `## Materials & Access` section into the draft \u2014 already ran in the `jira-ticket-writer` agent.\n\n## Inputs\n\n- `{ticket_number}` \u2014 the real Jira key of the already-created ticket (e.g. `BAPI-423`). Attachment is a POST-CREATE step; never attempt to attach before the key exists.\n- `{draft_file_path}` \u2014 path to the draft markdown that carries the trailing `## Materials & Access` section.\n- `{auto_approve_external}` \u2014 the unattended-vs-interactive signal (named for consistency with `upload-and-track.md`). **Polarity is counter-intuitive: `"true"` means UNATTENDED, which is the MORE restrictive mode here** \u2014 skip all prompts AND keep external/auth-gated materials record-only (never auto-attach them). It does NOT grant permission to attach external materials. Any other value (including `"false"`, missing, or empty) means an interactive invocation that MAY prompt for external/auth-gated materials. Invocations from `write-ticket` and `full-automation` are always unattended (`"true"`) for this step.\n\n## Instructions\n\n> **Orchestrator-directed step.** This agent task is authorized to call `attachment` (operations: `list`, `upload`) and `update_ticket_description` as directed below.\n\n1. **Read the record.** Read `{draft_file_path}` and parse its trailing `## Materials & Access` section. Collect the inventoried items grouped under *Reachable Local Files*, *External/Auth-Gated Links*, *Design/UI Comps (Fetchable)* (when present), and *Binary/Image Materials (Record-Only)*. If there is no `## Materials & Access` section, there is nothing to gather \u2014 return a no-op success.\n\n2. **Deduplicate first.** Call the `attachment` MCP tool with `operation` set to `"list"` and `ticket_number` set to `{ticket_number}` BEFORE uploading anything, so a resumed or re-run invocation does not re-attach a material that is already present. Compare against the deterministic filenames computed in step 4 (for both text materials and design comp image uploads) and skip any that already exist.\n\n3. **Source classification (scheme-based, no network probe).** Honor the classification already recorded in the draft:\n   - **Reachable Local Files** (local filesystem paths that are **NOT tracked in version control**) are **low-risk** materials eligible for auto-attach \u2014 proceed to step 4. The pre-create inventory already excluded version-controlled files (source code and in-repo docs are already available in the repository and are never attached \u2014 they are cited inline as *Relevant code*). As a safety net, this step must **never attach a file that is available in version control**: if any item listed under *Reachable Local Files* is a code file or otherwise clearly version-controlled, skip it and treat it as record-only.\n   - **External/Auth-Gated Links** (every `http(s)` URI, even if explicitly linked) are **record-only** on unattended paths. If `{auto_approve_external}` is `"true"` (or the invocation is from `write-ticket` / `full-automation`), leave them record-only and never auto-attach. (Mind the polarity: `auto_approve_external = "true"` means we are in unattended mode, so external materials must stay record-only \u2014 `"true"` is NOT permission to attach them.) Only an explicitly interactive invocation (`auto_approve_external` is any non-`"true"` value) may prompt the user to confirm before attaching.\n   - **Binary/Image Materials (Record-Only)** \u2014 ordinary/unrelated binaries (arbitrary screenshots, PDFs, ZIPs, and other binaries not design-relevant) stay **record-only** in this step; never attempt to upload them.\n   - **Design/UI Comps (Fetchable)** \u2014 split by whether the comp is a *local* file or a reference to something already remote:\n     - A **local design/UI comp image** (a reachable local file whose extension maps to an allowlisted image MIME type \u2014 `image/png`, `image/jpeg`, `image/webp`, `image/gif`) is eligible for auto-attach via the (now allowlist-guarded) binary upload path \u2014 proceed to step 4.\n     - A **non-local design reference** \u2014 a Jira `attachment_id` reference on another ticket, or an external/auth-gated design link \u2014 is **not** uploaded by this step; it is a reference to a comp that already lives on Jira (or is fetched at implementation time). This gather step neither re-uploads it nor re-encodes its bytes. Leave each such reference recorded with its `attachment_id`/path in the `## Materials & Access` record so a later implementation agent can download it into its worktree via the Jira attachment download capability.\n\n4. **Gather and size-tier each reachable local text material; compute deterministic filenames for local design comp images.**\n   - For each low-risk local **text** material:\n     - Read the local file from disk.\n     - If the content exceeds **200,000 characters**, SKIP the upload and RECORD it (note the path and that it was skipped for size) \u2014 do not attach it.\n     - If the content is **<= 200,000 characters**, upload it RAW via `attachment` (operation: `"upload"`). Do NOT summarize locally: the backend already summarizes attached text at plan time, so the size tiers are backend behavior this step defers to. The agent performs NO local summarization.\n     - Use a deterministic, sanitized filename of the form `{ticket_number}-material-{hash}.md` (using the `{ticket_number}` input from the Inputs section), where `{hash}` is the first 8 hex characters of the SHA-256 digest of the sanitized absolute source path.\n   - For each eligible local **design/UI comp image** identified in step 3:\n     - Use a deterministic filename of the form `{ticket_number}-material-{hash}{ext}`, where `{hash}` is computed the same way (first 8 hex characters of the SHA-256 digest of the sanitized absolute source path) and `{ext}` is the lowercased allowlisted source extension (`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`).\n   - Pin the hash algorithm exactly (SHA-256, first 8 hex chars, of the sanitized absolute path) \u2014 do NOT substitute another hash \u2014 so the same source always maps to the same filename and the dedup in step 2 works across separate sessions and re-runs. Compute comp filenames before the step 2 dedup comparison is applied. Keep the sanitized source provenance inside the text attachment body (not applicable to binary comp uploads), not only in the filename.\n\n5. **`attachment` upload parameter discipline (Zod).**\n   - For text materials, call `attachment` with `operation: "upload"`, `ticket_number`, the deterministic attachment filename, and the text `content`.\n   - For design comp image uploads, call `attachment` with `operation: "upload"`, `ticket_number`, `file_path` (the local source path), and `file_name` set to the deterministic comp filename from step 4 \u2014 pass `file_path` rather than reading and UTF-8-encoding the bytes yourself, so `resolveUploadAttachment()` performs binary detection, the MIME allowlist check, and base64 encoding. Never UTF-8-encode image bytes locally.\n   - In both cases, OMIT the optional parameters `link_type` and `replace_existing` entirely when they are unused \u2014 do NOT pass `null` or empty strings for them. The Zod schemas reject `null`/empty values, so an unused optional parameter must be omitted rather than nulled.\n\n6. **Redact secrets everywhere.** Before writing any URL or access note ANYWHERE \u2014 the Jira `## Materials & Access` record, any warning or final-report output, and any local intermediate file \u2014 sanitize and redact embedded credentials, SAS tokens, API keys, and basic-auth secrets using a high-visibility placeholder such as `[REDACTED_TOKEN]`. Mirror the backend `_redact_forge_fields()` / `_sanitize_jira_error_message()` patterns. A location/access note must never expose a plaintext secret.\n\n7. **Warn, never halt (error handling).** This step must NEVER halt, prompt-to-fail, or fail the overarching command because a material could not be gathered or attached. Follow the warn-not-halt convention:\n   - If an `attachment` upload call fails (or a file disappeared between inventory and upload), warn gracefully and continue with the next material.\n   - This includes design comp image uploads: an unsupported/disallowed MIME type, an oversize image (`> 10 MB`), a missing local file, a malformed upload payload, or a Jira upload failure must all be warned and skipped, never halting the run.\n   - On such a post-create attach failure, call `update_ticket_description` to record the failure in the issue\'s `## Materials & Access` record (the material became unavailable only after the issue existed). `update_ticket_description` is an existing MCP tool, not a backend change.\n   - Everything knowable PRE-CREATE was already written into the description at create time, so `update_ticket_description` is reserved for these rarer post-create attach failures. This complements the existing `partial_success` recording convention in `upload-and-track.md`.\n   - Apply the step 6 redaction to every warning and recorded note.\n\n## Return\n\nConfirm the outcome, reporting each category separately: which local text materials were attached (with their deterministic filenames), which design/UI comp images were attached (with their deterministic filenames), which materials were skipped/recorded as record-only (over-size text, external/auth-gated links, ordinary/unrelated binaries, or non-local design references), any attach failures recorded via `update_ticket_description`, and that no failure halted the run.\n',
   "get-prd.md": "# get_prd\n\nRetrieve an already-generated **Product Requirements Document (PRD)** for a Jira\nticket.\n\nThis tool only **fetches** an existing PRD \u2014 it does **not** start or trigger\ngeneration. If no PRD exists yet (or you need a fresh one), call `request_prd`\nfirst; it starts the async generation and `get_prd` retrieves the result once\nprocessing completes.\n\nThe PRD is product/stakeholder-facing: problem framing, goals, non-goals, target\nusers, success metrics, product requirements, scope, and risks. Present the\nreturned markdown verbatim without summarizing.\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `ticket_number` | string | \u2014 | Jira ticket key in `PROJECT-NUMBER` format (e.g. `BAPI-123`). |\n| `save_locally` | boolean | `true` | Save the retrieved PRD to a local file. Set to `false` to skip saving. |\n\nLocal saves go to `BAPI_DOCS_DIR/prd/{ticket}-prd-plan.md`.\n\n## Return\n\n- The full PRD as markdown text when one exists.\n- A `404` / not-found response when no PRD is ready yet \u2014 that means generation\n  has not run, not that the tool failed. Call `request_prd` to generate one.\n",
-  "learn-architecture.md": "## Objective\n\nExplore the codebase to identify architectural principles, directory conventions, design patterns, and data flow, then draft `architecture_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Principles Research\n\nResearch the codebase to identify architectural principles and conventions. For each area below, examine at least 5 representative files. Cite file paths for every pattern. Include code examples (5-15 lines) showing correct usage. Where relevant, include a WRONG example showing the common mistake.\n\nFor each pattern, classify its evidence level:\n- `ENFORCED` \u2014 consistently followed across the codebase, violations would be bugs\n- `CONVENTION` \u2014 commonly observed, occasional deviations exist\n- `ASPIRATIONAL` \u2014 intended direction, not yet consistently applied\n\nResearch areas:\n1. **Architectural coding patterns**: Search `api/routes/` and `api/library/` for separation of concerns, layer boundaries, function-vs-class decisions. Read files matching `*_lib.py`, `*_utils.py`, `*_helpers.py` to document module naming suffix conventions.\n2. **Design patterns**: Search for factory functions, strategy patterns, middleware chains, registry patterns, and dependency injection in `api/` and `src/python/`. Cite concrete usage with file path and function name.\n3. **Dependency management**: Read `requirements.in`, `requirements-dev.in`, and `package.json` files to document how dependencies are declared and organized.\n4. **Error handling architecture**: Search for `log_exception_to_sentry` and `HTTPException` usage patterns across `api/routes/` to document the system-wide error propagation strategy.\n5. **Configuration management**: Search for `os.environ` and `get_config_field` usage to document the two-tier system (env vars vs. database config).\n6. **Tech stack detection**: Read `requirements.in`, `package.json`, and `main.py` to identify primary languages, frameworks, and key libraries.\n7. **Security architecture**: Read `api/routes/setup/auth.py` and search for `require_api_key`, `require_api_session`, and `verify_repo_access` to document authentication and authorization design.\n8. **Agent prompting conventions**: Read files in `src/python/llms/agents/` to document prompt construction, section headers, dynamic content delimiters, and role-based personas.\n\nScope exclusion: Do NOT document testing patterns. Skip the `tests/` directory entirely.\n\nWrite findings to `{docs_dir}/tmp/architecture-principles.md`.\n\n### Phase 2 \u2014 Structure & Data Flow Research\n\n1. Call the `regenerate_directory_map` MCP tool to get a fresh directory map.\n2. Read the principles document from Phase 1.\n3. Research and document:\n   - **Directory conventions**: For each major directory, document purpose, file naming, internal structure, and an example file.\n   - **Module boundaries and import patterns**: Which directories are distinct modules and how they interact. Document import restrictions.\n   - **Data flow patterns**: Trace 2-3 complete request paths (synchronous, async background task, agent orchestration).\n   - **Integration patterns**: How external services (Jira, GitHub/Bitbucket, LLMs, Pinecone, PostgreSQL) are integrated.\n   - **Background task patterns**: The async task lifecycle with `asyncio.create_task`, semaphores, and error reporting.\n\nWrite findings to `{docs_dir}/tmp/architecture-structure.md`.\n\n### Phase 3 \u2014 Draft\n\n1. Read both research documents.\n2. Combine into a single `architecture_instructions` draft with these required sections:\n   - **1. Core Principles** \u2014 Each principle with evidence level and explanation.\n   - **2. Layered Architecture** \u2014 Layer separation, dependency rule, agent vs orchestration logic.\n   - **3. Directory Conventions** \u2014 Purpose, naming, structure for each major directory.\n   - **4. Data Flow Patterns** \u2014 Complete request path traces with file paths.\n   - **5. Technical Standards** \u2014 Coding style, async patterns, database, schema, LLM integration, config, dependencies.\n   - **6. Error Handling & Monitoring** \u2014 Error propagation strategy, Sentry integration, Langfuse tracing.\n   - **7. Security & Authentication** \u2014 Auth architecture, session model, permission model.\n   - **8. Agent Prompting Conventions** \u2014 Prompt construction, section headers, content delimiters.\n   - **9. Integration Points** \u2014 External service clients and their calling patterns.\n   - **10. AI Code Generation Guidelines** \u2014 Anti-patterns, duplication avoidance, pattern compliance checklist.\n\n3. Write the draft to `{docs_dir}/standards/architecture_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's architecture (core principles, directory conventions, data flow), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/architecture_instructions.md`.\n",
-  "learn-backend-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for backend code, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `backend_correctness`\n- **Field name**: `backend_correctness_standards`\n- **Scope**: Server-side code: Python, Ruby, Go, Java, C#, Node.js server code, API routes, business logic.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.py` in `api/` and `src/python/`. If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative files in `api/routes/` and `api/library/` to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n   Also read files to document:\n   - Error handling implementation (try/except ordering, Sentry calls) with CORRECT/WRONG examples\n   - Authentication implementation (auth check sequence) with code examples\n   - Database call patterns (`postgres_helpers` (bool, result) tuple handling) with CORRECT/WRONG examples\n   - Input validation patterns (Pydantic models, naming conventions)\n   - HTTP client patterns (error handling, JiraError sanitization)\n   - Async implementation patterns (`asyncio.to_thread()` for blocking code)\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nAlso include:\n- Route handler boilerplate (auth -> validation -> business logic -> error handling)\n- Database interaction patterns with CORRECT/WRONG examples\n- Exception handling pattern (specific first, HTTPException re-raise, generic with Sentry)\n- Sentry reporting patterns and common mistakes\n- Input sanitization rules (JiraError headers, raw exception messages)\n\nWrite the draft to `{docs_dir}/standards/backend_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about backend correctness conventions (structure, naming, error handling, auth, DB patterns), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/backend_correctness_standards.md`.\n",
-  "learn-design-principles.md": "## Objective\n\nExplore the codebase to identify frontend design principles, then draft a structured design principles document.\n\n## Target Type\n\n- **Type**: `design_principles`\n- **Field name**: `design_principles`\n- **Scope**: Visual identity, design tokens, component inventory, layout patterns, composition rules, interaction patterns, and anti-patterns.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Design Patterns\n\nSearch the codebase by filename pattern, search file contents by text pattern, and read relevant files to explore the codebase for design patterns. **Exclude `node_modules/`, `dist/`, `build/`, `.next/`, and `__pycache__/` from filename-pattern searches** to avoid token bloat.\n\nCall the `get_project_standards` MCP tool to check if `working_in` and `version` context is available. If available, use them to prioritize relevant file types. If unavailable or the call fails, read dependency files (`package.json`, `tailwind.config.js`, `postcss.config.js`) to infer the framework and styling approach.\n\n1. **Design Token Detection**: Search for CSS custom properties, SCSS/LESS variables, theme configs, Tailwind config, and design token definitions. Document naming conventions, token hierarchy, and value scales (spacing, colors, typography).\n\n2. **Component Inventory**: Search by filename pattern for component files (JSX/TSX/Vue/Svelte/ISML/template files). Read 5-10 representative components to identify composition patterns, prop interfaces, naming conventions, and component categories.\n\n3. **Style Architecture**: Find and analyze stylesheets (CSS/SCSS/LESS/styled-components/Tailwind). Document methodology (BEM, CSS Modules, utility-first), responsive breakpoints, and media query patterns.\n\n4. **Layout Patterns**: Identify grid systems, page templates, container components, and responsive layout strategies.\n\n5. **Interaction Patterns**: Search for animations, transitions, hover states, loading states, and error states.\n\n6. **Visual Consistency Audit**: Compare patterns across files. Note inconsistencies in spacing, color usage, component structure, or naming.\n\n### Phase 2 \u2014 Draft\n\nSynthesize findings into a structured document with exactly these 7 sections:\n\n1. **Visual Identity** \u2014 Colors, typography, spacing scales, iconography, visual tone\n2. **Design Token Reference** \u2014 Token naming conventions, hierarchy, value definitions\n3. **Component Inventory** \u2014 What components exist, their responsibilities, naming patterns\n4. **Page Layout Patterns** \u2014 Grid systems, page templates, responsive strategies, container patterns\n5. **Composition Rules** \u2014 How components combine, nesting patterns, slot/children conventions\n6. **Interaction Patterns** \u2014 Animations, transitions, states, hover/focus/active behaviors\n7. **Anti-patterns** \u2014 Inconsistencies found, patterns to avoid, deprecated approaches\n\nWrite the draft to `{docs_dir}/standards/design_principles.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's design principles (visual identity, tokens, components, layout, interactions), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/design_principles.md`.\n",
-  "learn-documentation-instructions.md": "## Objective\n\nExplore the codebase to identify implementation documentation patterns \u2014 the markdown records that document what was built, why, and when \u2014 then draft `documentation_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Implementation Record Patterns\n\nFocus on how the project records what was built, why, and when. These records serve as persistent project memory. Code-level documentation (docstrings, inline comments) is handled by correctness standards, not here.\n\n1. **Implementation Record Discovery**: Search for:\n   - Ticket-numbered documents matching `BAPI-*.md` or `PROJ-*.md` in `docs/` and subdirectories\n   - Feature/migration documents in `docs/`, `documentation/`, or similar directories\n   - Architecture Decision Records (ADRs) in `adr/`, `decisions/`, or similar\n   - Changelogs (`CHANGELOG.md`, release notes)\n\n   Count how many records exist and identify the naming convention.\n\n2. **Record Structure Analysis**: Read 3-5 representative implementation records (mix of early and recent). Document:\n   - Sections present (Summary, Architecture, Database Changes, API Reference, etc.)\n   - Level of detail provided\n   - Types of information captured (motivation, design decisions, schema changes, file paths, API contracts)\n   - How code examples and diagrams are used\n\n3. **Documentation Location and Organization**: Read the directory structure of `docs/` to identify where records are stored, the file naming convention, whether there is a table of contents or index, and whether subdirectories serve different purposes.\n\n### Phase 2 \u2014 Draft\n\nDraft `documentation_instructions` as **exactly one concise prose paragraph** that an AI agent will follow when writing implementation documentation after completing a feature. The drafted value is inlined verbatim into a generated plan step, so it has hard formatting constraints:\n\n- The output MUST be **one prose paragraph under 1,500 characters**.\n- The output MUST avoid **markdown headings, bullets, numbered lists, and intentional blank lines**. Write flowing prose (semicolon-separated clauses are fine), not a document outline or multi-section manual.\n- The paragraph MUST cover, in prose: the discovered **file naming convention** (or a sensible default), the **file location** where implementation records live, and the **key content to include** (what changed and why, important files and design decisions, any API/configuration/database impacts, and brief usage or validation examples).\n- The paragraph SHOULD include **skip guidance**: skip implementation documentation for trivial, test-only, or docs-only changes where appropriate.\n\nKeep the scope to implementation records only; code-level documentation (docstrings, inline comments) belongs in correctness standards.\n\nWrite the draft to `{docs_dir}/standards/documentation_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's implementation-record conventions (naming, location, required sections), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/documentation_instructions.md`.\n",
-  "learn-e2e-testing.md": '## Objective\n\nDetect whether an E2E testing framework exists in the codebase, document how to run and write E2E tests, then draft `e2e_testing_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Detect E2E Framework\n\nSearch for config files and indicators:\n- **Playwright**: Search for `playwright.config.ts`, `playwright.config.js`, `@playwright/test` in `package.json`\n- **Cypress**: Search for `cypress.json`, `cypress.config.*`, `cypress/` directory\n- **Selenium/WebDriver**: Search for `selenium` in `requirements.in` or `package.json`\n- **Puppeteer**: Search for `puppeteer` in `package.json`\n- **TestCafe**: Search for `.testcaferc.json`\n\nAlso read `package.json` for E2E-related scripts and search for test directories containing E2E tests.\n\nIf NO E2E testing framework is detected, write "No E2E testing framework detected in this repository." to `{docs_dir}/standards/e2e_testing_instructions.md` and stop.\n\n### Phase 2 \u2014 Explore E2E Testing Conventions\n\n1. **Test Execution**: Read the E2E config file and `package.json` scripts to determine exact commands (all tests, single file, headed/headless), prerequisites (server running, database seeded), and environment requirements.\n\n2. **Test Patterns**: Read 2-3 representative E2E test files in `tests/playwright/` to identify structure (page objects, fixtures, helpers), login/auth flows, test data setup/teardown, async waiting strategies, and selector patterns.\n\n3. **Common Pitfalls**: Search for hard-coded waits (`setTimeout`, `page.waitForTimeout`), test isolation issues, and browser state management patterns across E2E test files.\n\n### Phase 3 \u2014 Draft\n\nDraft `e2e_testing_instructions` as clear, actionable instructions for an AI agent writing E2E tests. Cover:\n- How to run tests (exact commands, prerequisites)\n- Test structure and organization\n- Authentication and setup patterns\n- How to wait for async operations (never hard-coded sleeps)\n- Common pitfalls with browser automation\n- Guards against common AI weaknesses: flaky tests, brittle selectors, hard-coded waits\n\nWrite the draft to `{docs_dir}/standards/e2e_testing_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project\'s E2E testing setup (framework detected, run commands, test patterns) \u2014 or state that no framework was detected \u2014 citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/e2e_testing_instructions.md`.\n',
-  "learn-frontend-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for frontend code, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `frontend_correctness`\n- **Field name**: `frontend_correctness_standards`\n- **Scope**: JS, TS, JSX, TSX files: React/Vue/Angular/Svelte components, client-side logic, state management.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.js`, `**/*.ts`, `**/*.jsx`, `**/*.tsx` (excluding `node_modules/` and `build/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative frontend files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/frontend_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about frontend correctness conventions (structure, naming, framework idioms), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/frontend_correctness_standards.md`.\n",
-  "learn-review-instructions.md": "## Objective\n\nExplore the codebase to identify self-verification patterns, downstream impact analysis techniques, and local validation tooling, then draft `review_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Self-Verification Patterns\n\nFocus on how an AI agent working in a code editor (with capabilities to search file contents by text pattern, search by filename pattern, read files, and call MCP tools) can verify its own code changes before requesting human review. Do NOT document test runners or CI/CD \u2014 focus on static analysis by reading code and searching for patterns.\n\n1. **Code Correctness Patterns**: Read 3-5 representative modules in `api/routes/` and `api/library/` to identify:\n   - Function signature conventions (return types, parameter patterns)\n   - Import conventions and layer boundaries (deprecated modules, import restrictions)\n   - Return value handling (structured results, tuple unpacking)\n   - Auth pattern compliance (required decorators, dependency injections, call order)\n   - Naming conventions (files, functions, classes, variables)\n   - Error handling patterns (try/except structure, ordering, logging)\n\n2. **Downstream Impact Analysis**: For each technique, demonstrate with a concrete codebase example:\n   - Caller discovery (text-pattern search for finding all callers of utility functions)\n   - Import graph analysis (finding all files importing from a module)\n   - Route registration verification (checking new routes are properly included)\n   - Database schema impact (finding queries referencing a given table/column)\n   - Model/schema usage (verifying model changes don't break dependents)\n\n3. **Local Validation Tooling**: Discover available MCP tools and validation capabilities:\n   - Database MCP tools (schema verification, query validation)\n   - Project API MCP tools (config verification, health checks)\n   - Hooks and guards (pre-commit hooks, pre-tool hooks)\n   - Safety model (read-only vs. mutating operations)\n   - Runtime smoke verification capability: Document which tools the executor can use to _run_ code safely (test runners, dbhub MCP, local dev servers, fixture loaders) and whether mutations are permitted against local/ephemeral state. The per-repo `allow_mutating_smoke_ops` flag (on `config_code_repositories`) controls whether the final reviewer is allowed to plan mutating verification steps.\n\n4. **Correctness Standards Integration**: Read files in `{docs_dir}/standards/` matching `*_correctness_standards.md`. Extract key verification checkpoints that can be statically verified.\n\n### Phase 2 \u2014 Draft\n\nDraft `review_instructions` with these required sections:\n1. **Self-Verification Checklist** \u2014 Concise, scannable checklist with concrete actions and tools.\n2. **Local Code Verification** \u2014 Detailed static analysis instructions (function calls, imports, auth, error handling, naming).\n3. **Downstream Effect Analysis** \u2014 Finding callers, checking signature compatibility, import tracking, schema impact, route registration.\n4. **Validation Using Local Tooling** \u2014 Database validation, project API validation, hooks and guards.\n5. **Correctness Standards Reference** \u2014 Distilled checkpoints from loaded standards, or placeholder paths.\n6. **Common AI Agent Mistakes** \u2014 Verification-framed guards against duplication, unnecessary abstraction, data leaks, edge cases.\n\nWrite the draft to `{docs_dir}/standards/review_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's self-review and downstream-impact analysis patterns (verification checkpoints, local validation tooling), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/review_instructions.md`.\n",
-  "learn-style-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for style files, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `style_correctness`\n- **Field name**: `style_correctness_standards`\n- **Scope**: Style files: CSS, SCSS, SASS, LESS, Styled Components, Tailwind configs.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.css`, `**/*.scss`, `**/*.sass`, `**/*.less` (excluding `node_modules/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative style files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/style_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about style-file correctness conventions (structure, naming, methodology), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/style_correctness_standards.md`.\n",
-  "learn-template-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for template files, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `template_correctness`\n- **Field name**: `template_correctness_standards`\n- **Scope**: Template files: HTML, Jinja2, Handlebars, EJS, ERB, Blade, Pug, Twig.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.html`, `**/*.jinja2`, `**/*.j2` in `templates/` and similar directories (excluding `node_modules/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative template files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/template_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about template-file correctness conventions (structure, naming, framework idioms), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/template_correctness_standards.md`.\n",
-  "learn-unit-testing.md": "## Objective\n\nExplore the codebase to identify the test runner, assertion library, mocking framework, and testing patterns, then draft `unit_testing_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Testing Infrastructure\n\n1. **Test Runner and Framework Detection**: Search for test runner configs (`pytest.ini`, `pyproject.toml` `[tool.pytest]` section, `jest.config.*`) and read `package.json` test scripts. Read the `tests/` directory structure.\n\n2. **Testing Patterns**: Read 3-5 representative test files in `tests/pytest/` to identify:\n   - Assertion library and style (`assert`, `expect`, custom matchers)\n   - Mocking framework (`unittest.mock`, `jest.mock`, `sinon`, etc.)\n   - Fixture patterns (setup/teardown)\n   - Test organization (by module, feature, layer)\n   - Exemplary tests vs. weak tests\n\n3. **How to Run Tests**: Read `pyproject.toml`, `package.json`, and `Makefile` (if present) to determine exact commands for: full suite, single file, by name pattern, with verbose output.\n\n4. **Mocking vs. Fidelity**: Read test helper files in `tests/pytest/helpers/` to document how external APIs are mocked, whether integration tests exist alongside unit tests, and patterns for avoiding third-party calls in tests.\n\n### Phase 2 \u2014 Draft\n\nDraft `unit_testing_instructions` as clear, actionable instructions for an AI agent writing unit tests. Cover:\n- How to run tests (exact commands)\n- Which test framework and assertion library to use\n- How to mock external dependencies without calling third parties\n- How to structure test files and test functions\n- What constitutes a thorough test (not just happy path)\n- How to avoid shallow tests that pass but don't verify meaningful behavior\n- Guards against common AI weaknesses: tests that mock the thing being tested, trivially passing assertions, overly complex setup\n\nWrite the draft to `{docs_dir}/standards/unit_testing_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's unit testing setup (test runner, assertion library, mocking framework, run commands), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/unit_testing_instructions.md`.\n",
+  "learn-architecture.md": "## Objective\n\nExplore the codebase to identify architectural principles, directory conventions, design patterns, and data flow, then draft `architecture_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Principles Research\n\nResearch the codebase to identify architectural principles and conventions. For each area below, examine at least 5 representative files. Cite file paths for every pattern. Include code examples (5-15 lines) showing correct usage. Where relevant, include a WRONG example showing the common mistake.\n\nFor each pattern, classify its evidence level:\n- `ENFORCED` \u2014 consistently followed across the codebase, violations would be bugs\n- `CONVENTION` \u2014 commonly observed, occasional deviations exist\n- `ASPIRATIONAL` \u2014 intended direction, not yet consistently applied\n\nResearch areas:\n1. **Architectural coding patterns**: Search `api/routes/` and `api/library/` for separation of concerns, layer boundaries, function-vs-class decisions. Read files matching `*_lib.py`, `*_utils.py`, `*_helpers.py` to document module naming suffix conventions.\n2. **Design patterns**: Search for factory functions, strategy patterns, middleware chains, registry patterns, and dependency injection in `api/` and `src/python/`. Cite concrete usage with file path and function name.\n3. **Dependency management**: Read `requirements.in`, `requirements-dev.in`, and `package.json` files to document how dependencies are declared and organized.\n4. **Error handling architecture**: Search for `log_exception_to_sentry` and `HTTPException` usage patterns across `api/routes/` to document the system-wide error propagation strategy.\n5. **Configuration management**: Search for `os.environ` and `get_config_field` usage to document the two-tier system (env vars vs. database config).\n6. **Tech stack detection**: Read `requirements.in`, `package.json`, and `main.py` to identify primary languages, frameworks, and key libraries.\n7. **Security architecture**: Read `api/routes/setup/auth.py` and search for `require_api_key`, `require_api_session`, and `verify_repo_access` to document authentication and authorization design.\n8. **Agent prompting conventions**: Read files in `src/python/llms/agents/` to document prompt construction, section headers, dynamic content delimiters, and role-based personas.\n\nScope exclusion: Do NOT document testing patterns. Skip the `tests/` directory entirely.\n\nWrite findings to `{docs_dir}/tmp/architecture-principles.md`.\n\n### Phase 2 \u2014 Structure & Data Flow Research\n\n1. Call the `regenerate_directory_map` MCP tool to get a fresh directory map.\n2. Read the principles document from Phase 1.\n3. Research and document:\n   - **Directory conventions**: For each major directory, document purpose, file naming, internal structure, and an example file.\n   - **Module boundaries and import patterns**: Which directories are distinct modules and how they interact. Document import restrictions.\n   - **Data flow patterns**: Trace 2-3 complete request paths (synchronous, async background task, agent orchestration).\n   - **Integration patterns**: How external services (Jira, GitHub/Bitbucket, LLMs, Pinecone, PostgreSQL) are integrated.\n   - **Background task patterns**: The async task lifecycle with `asyncio.create_task`, semaphores, and error reporting.\n\nWrite findings to `{docs_dir}/tmp/architecture-structure.md`.\n\n### Phase 3 \u2014 Draft\n\n1. Read both research documents.\n2. Combine into a single `architecture_instructions` draft with these required sections:\n   - **1. Core Principles** \u2014 Each principle with evidence level and explanation.\n   - **2. Layered Architecture** \u2014 Layer separation, dependency rule, agent vs orchestration logic.\n   - **3. Directory Conventions** \u2014 Purpose, naming, structure for each major directory.\n   - **4. Data Flow Patterns** \u2014 Complete request path traces with file paths.\n   - **5. Technical Standards** \u2014 Coding style, async patterns, database, schema, LLM integration, config, dependencies.\n   - **6. Error Handling & Monitoring** \u2014 Error propagation strategy, Sentry integration, Langfuse tracing.\n   - **7. Security & Authentication** \u2014 Auth architecture, session model, permission model.\n   - **8. Agent Prompting Conventions** \u2014 Prompt construction, section headers, content delimiters.\n   - **9. Integration Points** \u2014 External service clients and their calling patterns.\n   - **10. AI Code Generation Guidelines** \u2014 Anti-patterns, duplication avoidance, pattern compliance checklist.\n\n3. Write the draft to `{docs_dir}/standards/architecture_instructions.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``architecture_instructions`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about the project's architecture (core principles, directory conventions, data flow), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/architecture_instructions.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-backend-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for backend code, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `backend_correctness`\n- **Field name**: `backend_correctness_standards`\n- **Scope**: Server-side code: Python, Ruby, Go, Java, C#, Node.js server code, API routes, business logic.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.py` in `api/` and `src/python/`. If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative files in `api/routes/` and `api/library/` to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n   Also read files to document:\n   - Error handling implementation (try/except ordering, Sentry calls) with CORRECT/WRONG examples\n   - Authentication implementation (auth check sequence) with code examples\n   - Database call patterns (`postgres_helpers` (bool, result) tuple handling) with CORRECT/WRONG examples\n   - Input validation patterns (Pydantic models, naming conventions)\n   - HTTP client patterns (error handling, JiraError sanitization)\n   - Async implementation patterns (`asyncio.to_thread()` for blocking code)\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nAlso include:\n- Route handler boilerplate (auth -> validation -> business logic -> error handling)\n- Database interaction patterns with CORRECT/WRONG examples\n- Exception handling pattern (specific first, HTTPException re-raise, generic with Sentry)\n- Sentry reporting patterns and common mistakes\n- Input sanitization rules (JiraError headers, raw exception messages)\n\nWrite the draft to `{docs_dir}/standards/backend_correctness_standards.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``backend_correctness_standards`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about backend correctness conventions (structure, naming, error handling, auth, DB patterns), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/backend_correctness_standards.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-design-principles.md": "## Objective\n\nExplore the codebase to identify frontend design principles, then draft a structured design principles document.\n\n## Target Type\n\n- **Type**: `design_principles`\n- **Field name**: `design_principles`\n- **Scope**: Visual identity, design tokens, component inventory, layout patterns, composition rules, interaction patterns, and anti-patterns.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Design Patterns\n\nSearch the codebase by filename pattern, search file contents by text pattern, and read relevant files to explore the codebase for design patterns. **Exclude `node_modules/`, `dist/`, `build/`, `.next/`, and `__pycache__/` from filename-pattern searches** to avoid token bloat.\n\nCall the `get_project_standards` MCP tool to check if `working_in` and `version` context is available. If available, use them to prioritize relevant file types. If unavailable or the call fails, read dependency files (`package.json`, `tailwind.config.js`, `postcss.config.js`) to infer the framework and styling approach.\n\n1. **Design Token Detection**: Search for CSS custom properties, SCSS/LESS variables, theme configs, Tailwind config, and design token definitions. Document naming conventions, token hierarchy, and value scales (spacing, colors, typography).\n\n2. **Component Inventory**: Search by filename pattern for component files (JSX/TSX/Vue/Svelte/ISML/template files). Read 5-10 representative components to identify composition patterns, prop interfaces, naming conventions, and component categories.\n\n3. **Style Architecture**: Find and analyze stylesheets (CSS/SCSS/LESS/styled-components/Tailwind). Document methodology (BEM, CSS Modules, utility-first), responsive breakpoints, and media query patterns.\n\n4. **Layout Patterns**: Identify grid systems, page templates, container components, and responsive layout strategies.\n\n5. **Interaction Patterns**: Search for animations, transitions, hover states, loading states, and error states.\n\n6. **Visual Consistency Audit**: Compare patterns across files. Note inconsistencies in spacing, color usage, component structure, or naming.\n\n### Phase 2 \u2014 Draft\n\nSynthesize findings into a structured document with exactly these 7 sections:\n\n1. **Visual Identity** \u2014 Colors, typography, spacing scales, iconography, visual tone\n2. **Design Token Reference** \u2014 Token naming conventions, hierarchy, value definitions\n3. **Component Inventory** \u2014 What components exist, their responsibilities, naming patterns\n4. **Page Layout Patterns** \u2014 Grid systems, page templates, responsive strategies, container patterns\n5. **Composition Rules** \u2014 How components combine, nesting patterns, slot/children conventions\n6. **Interaction Patterns** \u2014 Animations, transitions, states, hover/focus/active behaviors\n7. **Anti-patterns** \u2014 Inconsistencies found, patterns to avoid, deprecated approaches\n\nWrite the draft to `{docs_dir}/standards/design_principles.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``design_principles`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about the project's design principles (visual identity, tokens, components, layout, interactions), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/design_principles.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-documentation-instructions.md": "## Objective\n\nExplore the codebase to identify implementation documentation patterns \u2014 the markdown records that document what was built, why, and when \u2014 then draft `documentation_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Implementation Record Patterns\n\nFocus on how the project records what was built, why, and when. These records serve as persistent project memory. Code-level documentation (docstrings, inline comments) is handled by correctness standards, not here.\n\n1. **Implementation Record Discovery**: Search for:\n   - Ticket-numbered documents matching `BAPI-*.md` or `PROJ-*.md` in `docs/` and subdirectories\n   - Feature/migration documents in `docs/`, `documentation/`, or similar directories\n   - Architecture Decision Records (ADRs) in `adr/`, `decisions/`, or similar\n   - Changelogs (`CHANGELOG.md`, release notes)\n\n   Count how many records exist and identify the naming convention.\n\n2. **Record Structure Analysis**: Read 3-5 representative implementation records (mix of early and recent). Document:\n   - Sections present (Summary, Architecture, Database Changes, API Reference, etc.)\n   - Level of detail provided\n   - Types of information captured (motivation, design decisions, schema changes, file paths, API contracts)\n   - How code examples and diagrams are used\n\n3. **Documentation Location and Organization**: Read the directory structure of `docs/` to identify where records are stored, the file naming convention, whether there is a table of contents or index, and whether subdirectories serve different purposes.\n\n### Phase 2 \u2014 Draft\n\nDraft `documentation_instructions` as **exactly one concise prose paragraph** that an AI agent will follow when writing implementation documentation after completing a feature. The drafted value is inlined verbatim into a generated plan step, so it has hard formatting constraints:\n\n- The output MUST be **one prose paragraph under 1,500 characters**.\n- The output MUST avoid **markdown headings, bullets, numbered lists, and intentional blank lines**. Write flowing prose (semicolon-separated clauses are fine), not a document outline or multi-section manual.\n- The paragraph MUST cover, in prose: the discovered **file naming convention** (or a sensible default), the **file location** where implementation records live, and the **key content to include** (what changed and why, important files and design decisions, any API/configuration/database impacts, and brief usage or validation examples).\n- The paragraph SHOULD include **skip guidance**: skip implementation documentation for trivial, test-only, or docs-only changes where appropriate.\n\nKeep the scope to implementation records only; code-level documentation (docstrings, inline comments) belongs in correctness standards.\n\nWrite the draft to `{docs_dir}/standards/documentation_instructions.md`.\n\n## Length Budget\n\nThe general platform ceiling for a configuration field is **40,000 characters**, but\n`documentation_instructions` has a stricter **effective limit of 1,500 characters** enforced by the\nserver for this field specifically, because the value is inlined verbatim into a generated plan step.\nThe uploaded draft must satisfy the 1,500-character limit \u2014 the 40,000-character ceiling is not the\nconstraint that applies here.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 1,500 characters, condense it: remove redundancy, tighten the prose, and drop\n   examples before anything else.\n3. Keep all four required topics (naming convention, location, key content, skip guidance) and the\n   single-paragraph form. Never meet the budget by dropping a required topic, and never truncate the\n   paragraph mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 1,500 characters.\n\n## Return\n\nReturn a brief summary of what was learned about the project's implementation-record conventions (naming, location, required sections), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/documentation_instructions.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (1,500 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-e2e-testing.md": "## Objective\n\nDetect whether an E2E testing framework exists in the codebase, document how to run and write E2E tests, then draft `e2e_testing_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Detect E2E Framework\n\nSearch for config files and indicators:\n- **Playwright**: Search for `playwright.config.ts`, `playwright.config.js`, `@playwright/test` in `package.json`\n- **Cypress**: Search for `cypress.json`, `cypress.config.*`, `cypress/` directory\n- **Selenium/WebDriver**: Search for `selenium` in `requirements.in` or `package.json`\n- **Puppeteer**: Search for `puppeteer` in `package.json`\n- **TestCafe**: Search for `.testcaferc.json`\n\nAlso read `package.json` for E2E-related scripts and search for test directories containing E2E tests.\n\nIf NO E2E testing framework is detected, write \"No E2E testing framework detected in this repository.\" to `{docs_dir}/standards/e2e_testing_instructions.md` and stop.\n\n### Phase 2 \u2014 Explore E2E Testing Conventions\n\n1. **Test Execution**: Read the E2E config file and `package.json` scripts to determine exact commands (all tests, single file, headed/headless), prerequisites (server running, database seeded), and environment requirements.\n\n2. **Test Patterns**: Read 2-3 representative E2E test files in `tests/playwright/` to identify structure (page objects, fixtures, helpers), login/auth flows, test data setup/teardown, async waiting strategies, and selector patterns.\n\n3. **Common Pitfalls**: Search for hard-coded waits (`setTimeout`, `page.waitForTimeout`), test isolation issues, and browser state management patterns across E2E test files.\n\n### Phase 3 \u2014 Draft\n\nDraft `e2e_testing_instructions` as clear, actionable instructions for an AI agent writing E2E tests. Cover:\n- How to run tests (exact commands, prerequisites)\n- Test structure and organization\n- Authentication and setup patterns\n- How to wait for async operations (never hard-coded sleeps)\n- Common pitfalls with browser automation\n- Guards against common AI weaknesses: flaky tests, brittle selectors, hard-coded waits\n\nWrite the draft to `{docs_dir}/standards/e2e_testing_instructions.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``e2e_testing_instructions`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about the project's E2E testing setup (framework detected, run commands, test patterns) \u2014 or state that no framework was detected \u2014 citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/e2e_testing_instructions.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-frontend-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for frontend code, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `frontend_correctness`\n- **Field name**: `frontend_correctness_standards`\n- **Scope**: JS, TS, JSX, TSX files: React/Vue/Angular/Svelte components, client-side logic, state management.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.js`, `**/*.ts`, `**/*.jsx`, `**/*.tsx` (excluding `node_modules/` and `build/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative frontend files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/frontend_correctness_standards.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``frontend_correctness_standards`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about frontend correctness conventions (structure, naming, framework idioms), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/frontend_correctness_standards.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-repository-confirmations.md": '## Objective\n\nApply the configuration fields that the server requires a human to confirm \u2014 in **one** batched round\nat the very end of the run, after everything that could be applied unattended already has been.\n\nFields carrying `requires_confirmation: true` can never be written on derivation alone: the\nrequirement is a server-side registry property, not a client-side courtesy. This task is where the\nhuman is asked, exactly once, with the full run behind them.\n\n## Operating rules\n\n1. **One question, not one per field.** Every candidate is presented together in a single round.\n2. **Only explicitly approved values are applied.** Silence is not approval.\n3. **Never stall.** If no human response can be obtained, omit the unconfirmed fields, report them,\n   and finish successfully.\n4. **This step never invalidates the run.** The learned fields were already uploaded by earlier\n   steps. A decline, a rejection, or a conflict here is a reportable outcome for that one field \u2014 it\n   never undoes or discards anything already applied.\n\n## Step 1 \u2014 Read the manifest once\n\n1. Call the `get_install_manifest` MCP tool **exactly once**, with `save_locally: false` \u2014 this is a\n   confirmation round, not an install artifact worth writing to disk.\n2. Keep the returned `snapshot_token` **verbatim**. The apply call in Step 4 must present that same\n   token. Do not re-read the manifest before applying; a fresh read invalidates the token you are\n   about to use.\n3. Select candidates from the manifest\'s field groups using the manifest\'s own metadata:\n   - the field\'s `requires_confirmation` is `true`, **and**\n   - the field\'s `is_set` is `false`.\n\n   A confirmation-required field that is already set is **not** a candidate: record it as\n   `skipped_existing` and leave it alone. Do not maintain your own list of which fields require\n   confirmation \u2014 the manifest is the authority, so a field the server adds later is picked up here\n   with no change to this instruction.\n\n## Step 2 \u2014 Derive a proposed value for each candidate\n\n### `selected_mcp_slugs`\n\nMCP validation manuals are supplied to the final plan reviewer. Propose them **only** from clear\nrepository markers, and record the evidence you used for each:\n\n| Evidence in the repository | Proposed slug |\n| --- | --- |\n| SFCC cartridges, or Salesforce Commerce Cloud markers | `b2c-commerce-developer` |\n| A Playwright configuration file | `playwright-mcp` |\n| PWA Kit markers | `pwa-kit-mcp` |\n\nRules:\n\n- Every proposed slug must come from the manifest\'s supported values for the field. Never propose a\n  slug that is not in the catalog \u2014 the server rejects unknown slugs outright.\n- Every proposed slug needs concrete evidence, named in the question. Cite the file or marker.\n- **No clear marker means the field is `not_applicable`** \u2014 report it as such and omit it from the\n  question. Do not guess, and do not propose a manual on weak evidence: a wrong manual degrades the\n  reviewer\'s behavior.\n\n### `project_description`\n\nIf `project_description` is still unset after install, derive a concise candidate description from the\nlocal codebase, following the field\'s manifest `guidance`. If it is already set, it is\n`skipped_existing`.\n\n### Any other confirmation-required candidate\n\nFor a candidate this instruction does not name explicitly, follow the field\'s manifest `guidance` to\nderive a value, and apply the same rule: no clear evidence means omit it rather than guess.\n\n## Step 3 \u2014 Ask once\n\nPresent **all** candidates in a **single** batched question. Separate per-field confirmation rounds\nare prohibited \u2014 the entire point of this step is that the human is interrupted exactly once.\n\nFor each candidate include:\n\n- the **field name**,\n- the **proposed value**,\n- the **evidence** behind the proposal, and\n- the **impact** of setting it \u2014 what changes about Bridge\'s behavior once the value is applied.\n\nLet the human approve or decline each field individually within that one round.\n\n## Step 4 \u2014 Apply the approved fields (one call)\n\n1. Make **at most one** `apply_install_manifest` call, passing the exact `snapshot_token` from Step 1.\n2. Submit every approved field in the `fields` map as `{ "value": <approved value>, "confirmed": true }`.\n   The `confirmed: true` metadata is what satisfies the server\'s confirmation requirement.\n3. **Omit** declined fields and unanswered fields entirely \u2014 do not send them with `confirmed: false`,\n   and do not send a placeholder value.\n4. If no field was approved, make no apply call at all.\n5. The apply is partial-tolerant. A field returned in the `rejected` bucket, or in the `conflict`\n   bucket because it changed since the manifest was read, is reported as that field\'s outcome \u2014 the\n   other approved fields still commit, and the learned fields uploaded earlier are untouched. Do not\n   retry the whole apply because one field failed.\n\n## Step 5 \u2014 Headless safety\n\nIf interaction is unavailable, or no response can be obtained (a non-interactive or headless\nsession):\n\n- Do **not** wait indefinitely and do **not** abandon the run.\n- Omit **every** unconfirmed field from the apply.\n- Report each candidate as `pending human input`, using that exact phrase.\n- Finish successfully. Everything else the run applied stays applied \u2014 an unconfirmed field never\n  blocks a confirmed or already-uploaded one.\n\n## Return\n\nReturn a single JSON object listing each field name in its outcome bucket:\n\n```json\n{\n  "approved": [],\n  "applied": [],\n  "declined": [],\n  "pending_human_input": [],\n  "not_applicable": [],\n  "skipped_existing": [],\n  "conflict": [],\n  "rejected": []\n}\n```\n\n- `approved` \u2014 the human approved the proposed value this round.\n- `applied` \u2014 the server committed the value.\n- `declined` \u2014 the human explicitly rejected the proposal.\n- `pending_human_input` \u2014 presented but unanswered, or never presentable (headless).\n- `not_applicable` \u2014 no clear evidence supported a proposal, so none was made.\n- `skipped_existing` \u2014 already set; never re-proposed.\n- `conflict` \u2014 changed since the manifest snapshot was read.\n- `rejected` \u2014 failed server-side validation.\n',
+  "learn-repository-fan-out.md": '## Objective\n\nResearch all ten learned configuration fields for this repository **in parallel**, one isolated\nsubagent per field, and leave a bounded, upload-ready draft on disk for each field that needs one.\n\nThis step performs research only. It never uploads: the ten declarative `config_field` update steps\nthat follow this task own every write.\n\n## Operating rules (apply to the whole task)\n\n1. **Local research only.** Every field is learned by reading *this checkout* on local disk. Do not\n   delegate research to the Bridge API backend or any server-side index \u2014 the backend has a vector\n   index of the code, not the working tree in front of you.\n2. **One isolated subagent per missing field.** Use the host coding agent\'s own subagent/task\n   mechanism. Each subagent gets exactly one field and does not see the others\' work.\n3. **Launch before you await.** Start every missing-field subagent first, then collect results. Never\n   spawn a subagent, wait for it to finish, and only then spawn the next one \u2014 a sequential\n   spawn-and-wait loop defeats the entire purpose of this step.\n4. **Subagents never upload and never talk to the human.** A subagent\'s only outputs are its draft\n   file and its structured result. All human interaction is deferred to the final confirmation step.\n5. **A failed field is not a failed run.** Isolate each failure to its own field, let the other\n   subagents finish, and return a successful aggregate result naming the gap.\n\n## Step 1 \u2014 Classify each field from the ten preceding fetch results\n\nThe ten `config_field` steps immediately before this task already read the current value of every\nlearned field. Use **those results** \u2014 do not re-read the fields and do not infer state from whether\na draft file happens to exist on disk from an earlier run.\n\nFor each field, read the fetch response\'s `value` property. That property is the authoritative\nsignal:\n\n- `value` is `null`, absent, or contains only whitespace \u2192 the field is **missing** (needs research).\n- `value` holds any other content \u2192 the field is **populated** (already learned).\n\nIf a fetch step warned and returned no usable response at all, treat that field as **missing**.\n\nRecord every populated field as `skipped_existing` and do not spawn a subagent for it. This is what\nmakes a rerun after a partial failure cheap: only the fields that are still empty are researched\nagain.\n\n## Step 2 \u2014 Prepare the artifact targets (before any subagent starts)\n\nThe upload steps that follow this task read a fixed file path per field. Stale content at one of\nthose paths would be uploaded as if it were this run\'s work, so:\n\n1. For every **missing** field, delete any existing file at its draft path. A field whose subagent\n   later fails must leave *no* file behind, so the declarative upload has nothing to send.\n2. For every **skipped_existing** field, write the value you just fetched to that field\'s draft path,\n   so the unchanged upload step has a readable file. The upload carries `only_if_null: true`, so the\n   server skips the write and the stored value is never overwritten by its own copy.\n\n## Step 3 \u2014 Fan out\n\nLaunch one subagent for every missing field, all of them, before awaiting any result. Then await all\nof them and collect each result.\n\nGive each subagent the prompt block for its field from the matrix below. Every prompt block already\ncarries the field name, the draft path, the research responsibilities, the evidence expectations, and\nthe character budget. Pass each block through verbatim, substituting `{docs_dir}` with the resolved\ndocs directory.\n\n### Shared subagent contract\n\nInclude this contract in every subagent prompt, in addition to the field-specific block:\n\n"""\nYou are researching exactly one configuration field for this repository. Read the local checkout on\ndisk \u2014 the actual files, not a summary of them. Cite concrete file paths as evidence for every claim\nyou make; a pattern you cannot point at a file for does not belong in the draft.\n\nWrite your finished draft to the draft path given below, and nothing else. Do not call any\nconfiguration-update tool, do not upload your draft anywhere, and do not ask the human any question:\nanother step owns writing and another step owns asking.\n\n**Length budget \u2014 this is a hard limit, measured in characters.**\n\n- Your draft must be at most the maximum character count stated in your field block below, measured\n  in **characters** (not tokens, not words, not bytes).\n- When your draft is complete, measure its length in characters.\n- If it exceeds the budget, condense it: remove redundancy, collapse repetitive passages, and shorten\n  or drop verbose code examples. Keep every required section \u2014 never meet the budget by deleting a\n  required section, and never truncate mid-sentence.\n- Re-measure after condensing, and repeat until the draft is within budget.\n- The budget is enforced by the server at upload time, so a draft over the limit is rejected outright\n  and the field is simply not learned. Condensing is how the field gets learned at all.\n\nReturn a JSON object:\n`{"field_name": "...", "draft_path": "...", "character_count": <int>, "max_character_count": <int>,\n"condensed": <bool>, "condensation_reason": "<why you condensed, or empty>"}`\n"""\n\n### Field matrix\n\nTen fields. Each row names the field, its draft path, its character budget, and the research\nresponsibilities to expand into that subagent\'s prompt block. The responsibilities mirror the\nmatching standalone `learn-*.md` instruction, which remains the fuller reference for that field.\n\n| Field | Draft path | Max characters | Mirrors |\n| --- | --- | --- | --- |\n| `architecture_instructions` | `{docs_dir}/standards/architecture_instructions.md` | 40000 | `learn-architecture.md` |\n| `review_instructions` | `{docs_dir}/standards/review_instructions.md` | 40000 | `learn-review-instructions.md` |\n| `documentation_instructions` | `{docs_dir}/standards/documentation_instructions.md` | 1500 | `learn-documentation-instructions.md` |\n| `unit_testing_instructions` | `{docs_dir}/standards/unit_testing_instructions.md` | 40000 | `learn-unit-testing.md` |\n| `e2e_testing_instructions` | `{docs_dir}/standards/e2e_testing_instructions.md` | 40000 | `learn-e2e-testing.md` |\n| `frontend_correctness_standards` | `{docs_dir}/standards/frontend_correctness_standards.md` | 40000 | `learn-frontend-correctness.md` |\n| `backend_correctness_standards` | `{docs_dir}/standards/backend_correctness_standards.md` | 40000 | `learn-backend-correctness.md` |\n| `template_correctness_standards` | `{docs_dir}/standards/template_correctness_standards.md` | 40000 | `learn-template-correctness.md` |\n| `style_correctness_standards` | `{docs_dir}/standards/style_correctness_standards.md` | 40000 | `learn-style-correctness.md` |\n| `design_principles` | `{docs_dir}/standards/design_principles.md` | 40000 | `learn-design-principles.md` |\n\n#### `architecture_instructions` \u2014 max 40000 characters\n\n"""\nDraft `architecture_instructions` to `{docs_dir}/standards/architecture_instructions.md`, at most\n40000 characters.\n\nExplore the codebase for architectural principles, directory conventions, design patterns, and data\nflow. Examine at least 5 representative files per area and cite file paths for every pattern.\nClassify each pattern\'s evidence level as `ENFORCED` (violations would be bugs), `CONVENTION`\n(commonly observed, deviations exist), or `ASPIRATIONAL` (intended, not yet consistent).\n\nCover: architectural coding patterns and layer boundaries; design patterns (factories, strategies,\nmiddleware, registries, dependency injection); dependency management; error-handling architecture;\nconfiguration management; tech-stack detection; security/auth architecture; and agent prompting\nconventions. Trace 2-3 complete request paths end to end. Do NOT document testing patterns \u2014 skip the\ntests directory entirely.\n\nRequired sections: 1. Core Principles; 2. Layered Architecture; 3. Directory Conventions; 4. Data\nFlow Patterns; 5. Technical Standards; 6. Error Handling & Monitoring; 7. Security & Authentication;\n8. Agent Prompting Conventions; 9. Integration Points; 10. AI Code Generation Guidelines.\n"""\n\n#### `review_instructions` \u2014 max 40000 characters\n\n"""\nDraft `review_instructions` to `{docs_dir}/standards/review_instructions.md`, at most 40000\ncharacters.\n\nFollow the responsibilities in `learn-review-instructions.md`: research what this repository\'s code\nreviewers actually enforce, and turn it into instructions the AI code reviewer can apply. Cite file\npaths as evidence for every rule, and preserve that instruction\'s required sections.\n"""\n\n#### `documentation_instructions` \u2014 max 1500 characters\n\n"""\nDraft `documentation_instructions` to `{docs_dir}/standards/documentation_instructions.md`, at most\n**1500 characters**.\n\nThis field\'s limit is far stricter than the platform\'s general 40000-character ceiling, because the\nserver enforces 1500 characters for this field specifically and the value is inlined verbatim into a\ngenerated plan step.\n\nProduce **a single concise prose paragraph**: no markdown headings, no bullets, no numbered lists, no\nintentional blank lines. The paragraph must cover the implementation-document file naming convention,\nwhere documentation lives, the key content to capture, and when to skip documentation.\n\nBecause 1500 characters is tight, expect to condense. Cut redundancy and examples first; keep all\nfour required topics.\n"""\n\n#### `unit_testing_instructions` \u2014 max 40000 characters\n\n"""\nDraft `unit_testing_instructions` to `{docs_dir}/standards/unit_testing_instructions.md`, at most\n40000 characters.\n\nFollow the responsibilities in `learn-unit-testing.md`: research this repository\'s unit-testing\nconventions \u2014 framework, layout, fixtures, mocking boundaries, and assertion style \u2014 and cite file\npaths for every convention. Preserve that instruction\'s required sections.\n"""\n\n#### `e2e_testing_instructions` \u2014 max 40000 characters\n\n"""\nDraft `e2e_testing_instructions` to `{docs_dir}/standards/e2e_testing_instructions.md`, at most 40000\ncharacters.\n\nFollow the responsibilities in `learn-e2e-testing.md`: research this repository\'s end-to-end testing\nconventions \u2014 runner, prerequisites, page/selector patterns, and how tests are executed \u2014 and cite\nfile paths for every convention. Preserve that instruction\'s required sections.\n"""\n\n#### `frontend_correctness_standards` \u2014 max 40000 characters\n\n"""\nDraft `frontend_correctness_standards` to\n`{docs_dir}/standards/frontend_correctness_standards.md`, at most 40000 characters.\n\nFollow the responsibilities in `learn-frontend-correctness.md`: research the correctness rules that\napply to this repository\'s frontend code and cite file paths as evidence. Preserve that\ninstruction\'s required sections. If the repository has no frontend code, say so explicitly rather\nthan inventing standards.\n"""\n\n#### `backend_correctness_standards` \u2014 max 40000 characters\n\n"""\nDraft `backend_correctness_standards` to `{docs_dir}/standards/backend_correctness_standards.md`, at\nmost 40000 characters.\n\nFollow the responsibilities in `learn-backend-correctness.md`: research the correctness rules that\napply to this repository\'s backend code and cite file paths as evidence. Preserve that instruction\'s\nrequired sections.\n"""\n\n#### `template_correctness_standards` \u2014 max 40000 characters\n\n"""\nDraft `template_correctness_standards` to `{docs_dir}/standards/template_correctness_standards.md`,\nat most 40000 characters.\n\nFollow the responsibilities in `learn-template-correctness.md`: research the correctness rules that\napply to this repository\'s template files and cite file paths as evidence. Preserve that\ninstruction\'s required sections. If the repository has no templates, say so explicitly rather than\ninventing standards.\n"""\n\n#### `style_correctness_standards` \u2014 max 40000 characters\n\n"""\nDraft `style_correctness_standards` to `{docs_dir}/standards/style_correctness_standards.md`, at most\n40000 characters.\n\nFollow the responsibilities in `learn-style-correctness.md`: research the style and formatting rules\nthat apply to this repository\'s styling files and cite file paths as evidence. Preserve that\ninstruction\'s required sections. If the repository has no styling files, say so explicitly rather\nthan inventing standards.\n"""\n\n#### `design_principles` \u2014 max 40000 characters\n\n"""\nDraft `design_principles` to `{docs_dir}/standards/design_principles.md`, at most 40000 characters.\n\nFollow the responsibilities in `learn-design-principles.md`: research this repository\'s design\ntokens, component inventory, layout patterns, and composition rules, and cite file paths as evidence.\nPreserve that instruction\'s required sections. If the repository has no user interface, say so\nexplicitly rather than inventing principles.\n"""\n\n## Step 4 \u2014 Verify each result before marking it upload-ready\n\nFor every subagent that returned successfully:\n\n1. Confirm the draft file exists at the field\'s draft path.\n2. Measure the file\'s length in characters **yourself**. Do not trust the subagent\'s reported count \u2014\n   an oversized draft handed to the declarative upload is rejected by the server, and the field is\n   silently not learned.\n3. If the file is within the field\'s budget, mark the field `drafted`.\n4. If the file is still over budget, condense it yourself to fit \u2014 preserving its required sections \u2014\n   then re-measure. If you cannot bring it within budget, delete the draft file and record the field\n   as `failed` with the reason, so the upload sends nothing rather than something the server rejects.\n\nFor every subagent that failed, errored, or returned nothing usable: leave the draft path absent,\nrecord the field as `failed` with a short sanitized reason (no credentials, tokens, URLs, or raw\nstack traces), and continue. Do not abandon the other fields and do not fail this task.\n\n## Return\n\nReturn a single JSON object. This task succeeds even when some fields failed \u2014 the summary is how a\ngap gets reported, not an exception.\n\n```json\n{\n  "fields": [\n    {\n      "field_name": "architecture_instructions",\n      "status": "drafted",\n      "draft_path": "{docs_dir}/standards/architecture_instructions.md",\n      "character_count": 18240,\n      "max_character_count": 40000,\n      "condensed": false,\n      "condensation_reason": "",\n      "failure_reason": ""\n    }\n  ],\n  "drafted": ["architecture_instructions"],\n  "skipped_existing": [],\n  "condensed": [],\n  "failed": []\n}\n```\n\nRules for the return value:\n\n- `status` is exactly one of `drafted`, `skipped_existing`, or `failed`.\n- Every one of the ten fields appears exactly once in `fields`.\n- `condensed` is `true` only when the draft was shortened to meet the budget; `condensation_reason`\n  explains why whenever `condensed` is `true`.\n- `failure_reason` is populated only for `failed` fields and is sanitized.\n- The four aggregate arrays list the field names in each outcome, so the command\'s closing summary\n  can report them without re-deriving them from prose.\n',
+  "learn-review-instructions.md": "## Objective\n\nExplore the codebase to identify self-verification patterns, downstream impact analysis techniques, and local validation tooling, then draft `review_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Self-Verification Patterns\n\nFocus on how an AI agent working in a code editor (with capabilities to search file contents by text pattern, search by filename pattern, read files, and call MCP tools) can verify its own code changes before requesting human review. Do NOT document test runners or CI/CD \u2014 focus on static analysis by reading code and searching for patterns.\n\n1. **Code Correctness Patterns**: Read 3-5 representative modules in `api/routes/` and `api/library/` to identify:\n   - Function signature conventions (return types, parameter patterns)\n   - Import conventions and layer boundaries (deprecated modules, import restrictions)\n   - Return value handling (structured results, tuple unpacking)\n   - Auth pattern compliance (required decorators, dependency injections, call order)\n   - Naming conventions (files, functions, classes, variables)\n   - Error handling patterns (try/except structure, ordering, logging)\n\n2. **Downstream Impact Analysis**: For each technique, demonstrate with a concrete codebase example:\n   - Caller discovery (text-pattern search for finding all callers of utility functions)\n   - Import graph analysis (finding all files importing from a module)\n   - Route registration verification (checking new routes are properly included)\n   - Database schema impact (finding queries referencing a given table/column)\n   - Model/schema usage (verifying model changes don't break dependents)\n\n3. **Local Validation Tooling**: Discover available MCP tools and validation capabilities:\n   - Database MCP tools (schema verification, query validation)\n   - Project API MCP tools (config verification, health checks)\n   - Hooks and guards (pre-commit hooks, pre-tool hooks)\n   - Safety model (read-only vs. mutating operations)\n   - Runtime smoke verification capability: Document which tools the executor can use to _run_ code safely (test runners, dbhub MCP, local dev servers, fixture loaders) and whether mutations are permitted against local/ephemeral state. The per-repo `allow_mutating_smoke_ops` flag (on `config_code_repositories`) controls whether the final reviewer is allowed to plan mutating verification steps.\n\n4. **Correctness Standards Integration**: Read files in `{docs_dir}/standards/` matching `*_correctness_standards.md`. Extract key verification checkpoints that can be statically verified.\n\n### Phase 2 \u2014 Draft\n\nDraft `review_instructions` with these required sections:\n1. **Self-Verification Checklist** \u2014 Concise, scannable checklist with concrete actions and tools.\n2. **Local Code Verification** \u2014 Detailed static analysis instructions (function calls, imports, auth, error handling, naming).\n3. **Downstream Effect Analysis** \u2014 Finding callers, checking signature compatibility, import tracking, schema impact, route registration.\n4. **Validation Using Local Tooling** \u2014 Database validation, project API validation, hooks and guards.\n5. **Correctness Standards Reference** \u2014 Distilled checkpoints from loaded standards, or placeholder paths.\n6. **Common AI Agent Mistakes** \u2014 Verification-framed guards against duplication, unnecessary abstraction, data leaks, edge cases.\n\nWrite the draft to `{docs_dir}/standards/review_instructions.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``review_instructions`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about the project's self-review and downstream-impact analysis patterns (verification checkpoints, local validation tooling), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/review_instructions.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-style-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for style files, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `style_correctness`\n- **Field name**: `style_correctness_standards`\n- **Scope**: Style files: CSS, SCSS, SASS, LESS, Styled Components, Tailwind configs.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.css`, `**/*.scss`, `**/*.sass`, `**/*.less` (excluding `node_modules/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative style files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/style_correctness_standards.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``style_correctness_standards`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about style-file correctness conventions (structure, naming, methodology), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/style_correctness_standards.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-template-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for template files, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `template_correctness`\n- **Field name**: `template_correctness_standards`\n- **Scope**: Template files: HTML, Jinja2, Handlebars, EJS, ERB, Blade, Pug, Twig.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.html`, `**/*.jinja2`, `**/*.j2` in `templates/` and similar directories (excluding `node_modules/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative template files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 \u2014 Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/template_correctness_standards.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``template_correctness_standards`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about template-file correctness conventions (structure, naming, framework idioms), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/template_correctness_standards.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
+  "learn-unit-testing.md": "## Objective\n\nExplore the codebase to identify the test runner, assertion library, mocking framework, and testing patterns, then draft `unit_testing_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 \u2014 Explore Testing Infrastructure\n\n1. **Test Runner and Framework Detection**: Search for test runner configs (`pytest.ini`, `pyproject.toml` `[tool.pytest]` section, `jest.config.*`) and read `package.json` test scripts. Read the `tests/` directory structure.\n\n2. **Testing Patterns**: Read 3-5 representative test files in `tests/pytest/` to identify:\n   - Assertion library and style (`assert`, `expect`, custom matchers)\n   - Mocking framework (`unittest.mock`, `jest.mock`, `sinon`, etc.)\n   - Fixture patterns (setup/teardown)\n   - Test organization (by module, feature, layer)\n   - Exemplary tests vs. weak tests\n\n3. **How to Run Tests**: Read `pyproject.toml`, `package.json`, and `Makefile` (if present) to determine exact commands for: full suite, single file, by name pattern, with verbose output.\n\n4. **Mocking vs. Fidelity**: Read test helper files in `tests/pytest/helpers/` to document how external APIs are mocked, whether integration tests exist alongside unit tests, and patterns for avoiding third-party calls in tests.\n\n### Phase 2 \u2014 Draft\n\nDraft `unit_testing_instructions` as clear, actionable instructions for an AI agent writing unit tests. Cover:\n- How to run tests (exact commands)\n- Which test framework and assertion library to use\n- How to mock external dependencies without calling third parties\n- How to structure test files and test functions\n- What constitutes a thorough test (not just happy path)\n- How to avoid shallow tests that pass but don't verify meaningful behavior\n- Guards against common AI weaknesses: tests that mock the thing being tested, trivially passing assertions, overly complex setup\n\nWrite the draft to `{docs_dir}/standards/unit_testing_instructions.md`.\n\n## Length Budget\n\nThe platform ceiling for a configuration field is **40,000 characters**, and the server enforces it\nat upload time: a draft over the limit is rejected outright and ``unit_testing_instructions`` is simply not learned. Bound\nthe draft here, at write time, rather than discovering the limit through a failed upload.\n\n1. When the draft is complete, measure its length in **characters** \u2014 not tokens, not words, not\n   bytes.\n2. If it exceeds 40,000 characters, condense it: remove redundancy, collapse repetitive passages, and\n   shorten or drop verbose code examples.\n3. Keep every required section listed above. Never meet the budget by deleting a required section,\n   and never truncate the draft mid-sentence.\n4. Re-measure after condensing and repeat until the draft is at most 40,000 characters.\n\n## Return\n\nReturn a brief summary of what was learned about the project's unit testing setup (test runner, assertion library, mocking framework, run commands), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/unit_testing_instructions.md`.\n\nAlso report the draft's final length in characters, the applicable maximum (40,000 characters),\nwhether the draft was condensed to meet that maximum (`condensed`: true/false), and \u2014 when it was\ncondensed \u2014 the reason it needed condensing.\n",
   "monitor-ci-checks.md": 'Monitor CI checks for the most recent commit. The behavior is dispatched on the repo-specific `ci_followup_config` JSON value: `poll_only`, `fix_and_iterate`, or `custom`. Read this entire file once before doing anything, then follow only the matching branch.\n\n> **Warning**: Keep this file behaviorally in sync with `commands/src/check-ci.md` (and its scaffolded copies) to prevent drift (BAPI-462).\n\n**Required-check source**: Both the `poll_only` (Step 5) and `fix_and_iterate` (Step 6) branches gate progression on the *required* check subset, not the aggregate `all_passed` flag. Each check returned by `resolve_ci_checks`/`poll_ci_checks` carries a `required` field (from GitHub Branch Protection, or an LLM classification fallback) \u2014 treat `required: false` as non-required (e.g. `pip-audit`) and a missing field or `required: true` as required. This is the tool-provided proxy for the Conductor done-gate\'s authoritative required-checks set (`mcp_server/src/conductor/done-gate.ts`); do not re-derive required/non-required status in prose.\n\n## Step 3 \u2014 Parse `ci_followup_config`\n\nLook at the response from the immediately preceding `config_field` call (the pipeline step that ran right before this one). The response envelope\'s `value` field is itself a JSON string and must be parsed again with `JSON.parse` (i.e., the `value` is double-encoded \u2014 the outer envelope is JSON, and the inner `value` is a JSON-encoded string of the actual config object).\n\nIf ANY of the following hold, log a warning and use the defaults `{"strategy":"poll_only","max_iterations":1,"max_minutes":10}`:\n\n- The `config_field` response is missing or unavailable (e.g., the step warned-and-continued).\n- The response `value` is `null`.\n- Parsing `value` with `JSON.parse` fails (the persisted text is not valid JSON).\n- The parsed result is not a JSON object.\n- One or more of the required keys (`strategy`, `max_iterations`, `max_minutes`, `instructions`) is missing.\n- `strategy` is not one of `poll_only`, `fix_and_iterate`, or `custom`.\n\n## Step 4 \u2014 Dispatch on `strategy`\n\nRead this whole file once and then follow only the matching branch:\n\n- `poll_only` \u2192 follow Step 5.\n- `fix_and_iterate` \u2192 follow Step 6.\n- `custom` \u2192 follow Step 7.\n\nIf `strategy` is unrecognized, log a warning and fall through to Step 5 (`poll_only`).\n\n## Step 5 \u2014 `poll_only`\n\nPreserve the baseline polling behavior. The configured `max_minutes` is IGNORED in this branch \u2014 `poll_only` always uses the existing 10-minute baseline.\n\n1. Run `git rev-parse HEAD` to get the current commit SHA.\n2. Call the `resolve_ci_checks` tool with `commit_ref` set to that SHA. This discovers and classifies the CI checks for the repository, including each check\'s `required` field.\n3. Poll CI status by calling `poll_ci_checks` with `commit_ref` set to the same SHA. Check the response for `all_complete`, and note each check\'s own `required`/green status \u2014 do not use the aggregate `all_passed` flag to decide pass/fail (see step 5 below).\n4. **Conductor steerability**: if launched under the Conductor (the `BAPI_CONDUCTOR_RUN_ID`/`BAPI_CONDUCTOR_WORKER_ID` env identifiers are present), call the `check_messages` MCP tool once per poll cycle, alongside `poll_ci_checks`. Returned messages are advisory supervisor guidance only \u2014 acknowledged by the call, not redelivered \u2014 and never override the deterministic required-subset/verdict-token rules below; `poll_only` never attempts fixes regardless of guidance. Fail-open: if `check_messages` errors with an identity-unavailable message, you were not launched under the Conductor \u2014 stop calling it for the rest of the run.\n5. If checks are not yet complete, wait 30 seconds and poll again. Repeat until all checks are complete or 10 minutes have elapsed.\n6. Compute `required_green` = every check with `required: true` (or a missing `required` field) is complete and green. If `required_green` is `true`, report success \u2014 non-required failures (e.g. `pip-audit` with `required: false`) are reported for visibility only and never flip the Passed/Failed classification.\n7. **Review verdict gating**: if `claude-review` is one of the required checks, its GitHub check reaching a non-pending/"success" state means only that the review action *ran* \u2014 this is transport completion, not approval. Fetch the PR\'s comments and confirm the sticky comment contains `claude-review-verdict: approved` on its own line with a `Reviewed-SHA:` line matching the current commit SHA before treating the review as approved; `claude-review-verdict: changes_requested`, a missing verdict, or a stale `Reviewed-SHA:` all mean the review is not yet approved and success is not yet reached.\n8. **Conductor done-gate**: once `required_green` is `true` and (if `claude-review` is required) the verdict token confirms approval for the current head, and if launched under the Conductor, call the `wait_for_done_gate` MCP tool once (no arguments required) to drive the authoritative done-gate evaluation server-side against the Conductor\'s `required_checks` config. This tool applies its own short internal poll cap \u2014 if it times out without observing `gate_met`, exit cleanly and still report success rather than treating the timeout as a failure: the Conductor\'s own reconciliation pass is the correctness backstop. Fail-open: if the tool errors with an identity-unavailable message, skip it.\n9. If any required checks fail, report which required checks failed (and any non-required failures for visibility) and include any available annotations or log details from the poll response. Do NOT attempt to fix failures \u2014 just report them clearly.\n10. If CI status is unavailable (resolver/poll returns `available: false`), report unavailable status and exit; do not attempt fixes.\n11. If the 10-minute timeout is reached, report timeout and exit.\n\n### Polling Directive\n\nDuring the polling loop, execute `sleep 30` silently. Do NOT output any inline commentary, reasoning, or partial status updates between polls. Only output a status message when:\n- All checks are complete (pass or fail), OR\n- The 10-minute timeout is reached.\n\nThis minimizes context window consumption during long-running CI waits.\n\n## Step 6 \u2014 `fix_and_iterate`\n\nThis is a self-contained loop where `iteration` is the number of correction rounds already pushed and `start_time` is captured before the first iteration. `max_minutes` is the TOTAL wall-clock cap across all iterations, not an additional per-iteration budget. The 10-minute per-iteration `poll_ci_checks` cap is INSIDE that total budget.\n\nInitialize:\n\n- `iteration = 0`\n- `start_time = now()`\n\nBefore starting each iteration AND before applying corrections, check the total wall-clock budget. If `now() - start_time >= max_minutes`, warn and exit.\n\nPer iteration:\n\n1. Run `git rev-parse HEAD` to get the current commit SHA. The previous push may have changed it; always read fresh.\n2. Run `git branch --show-current` to get the current branch. Always read fresh.\n3. Call `resolve_ci_checks` with `commit_ref` set to the current SHA (once per new SHA \u2014 the server caches per project but the agent should still call it for each new SHA). Each returned check carries a `required` field \u2014 this is the tool-provided proxy for the done-gate\'s authoritative required-checks set.\n4. Poll `poll_ci_checks` with `commit_ref` set to the current SHA. Stop when `all_complete` is true, OR the per-iteration 10-minute timeout is reached, OR the remaining total wall-clock budget is exhausted.\n5. **Conductor steerability**: if launched under the Conductor (the `BAPI_CONDUCTOR_RUN_ID`/`BAPI_CONDUCTOR_WORKER_ID` env identifiers are present), call the `check_messages` MCP tool once per poll cycle, alongside `poll_ci_checks`. Returned messages are advisory supervisor guidance only \u2014 acknowledged by the call, not redelivered \u2014 and never override the deterministic required-subset/verdict-token rules or cause a fix you are not confident in. Fail-open: if `check_messages` errors with an identity-unavailable message, you were not launched under the Conductor \u2014 stop calling it for the rest of the run.\n6. If CI status is unavailable (`available: false`), warn and exit the loop \u2014 automated remediation cannot make reliable progress without CI signals.\n7. Compute `required_green` = every check with `required: true` (or a missing `required` field) is complete and green; non-required failures (e.g. `pip-audit` with `required: false`) are reported for visibility but never gate exit condition 1 below. If `claude-review` is a required check, its GitHub check reaching a non-pending/"success" state is transport completion only, not approval \u2014 fetch the PR\'s comments and confirm the sticky comment contains `claude-review-verdict: approved` on its own line with a `Reviewed-SHA:` line matching the current commit SHA before treating the review as approved; `claude-review-verdict: changes_requested`, a missing verdict, or a stale `Reviewed-SHA:` mean the review is not yet approved.\n8. Apply repo-specific `instructions` ONLY when the `instructions` field is non-empty. If the repo `instructions` reference templated placeholder tokens for the GitHub owner, repo, or PR number \u2014 e.g., the literal tokens written as a left brace, the word `owner`/`repo`/`pr`, then a right brace \u2014 resolve them from the local git/VCS context. Use `gh pr list --head <branch> --json number` to get the PR number; parse the remote URL (`git config --get remote.origin.url`) for owner/repo. If `instructions` is empty, skip repo-specific signal gathering and use only structured CI failure information.\n\n9. Evaluate exit conditions in this order:\n   1. `required_green` is true AND (if `claude-review` is required) the verdict token confirms approval for the current head AND any repo-specific exit criteria from `instructions` are met \u2192 success. If there are no repo-specific exit criteria, `required_green` (plus verdict-token approval when `claude-review` is required) alone satisfies the success condition. On success, if launched under the Conductor, call the `wait_for_done_gate` MCP tool once before returning (no arguments required) to drive the authoritative done-gate evaluation server-side; this tool applies its own short internal poll cap and, if it times out without observing `gate_met`, exit cleanly and still return success \u2014 the Conductor\'s own reconciliation pass is the correctness backstop, not this call. Fail-open: if the tool errors with an identity-unavailable message, skip it. Then return.\n   2. `iteration >= max_iterations` \u2192 warn and exit (iteration cap reached).\n   3. Total elapsed wall-clock time `>= max_minutes` \u2192 warn and exit (total wall-clock cap reached).\n   4. After attempting corrections, `git status --porcelain` is empty \u2192 warn and exit (nothing to commit; avoids infinite loop on stuck failures).\n\n10. Apply corrections ONLY for failing **required** checks \u2014 skip failures on non-required checks (e.g. `pip-audit` with `required: false`) with a warning and never spend a correction/retry on them. For each failing required check, use the actual `poll_ci_checks` response shape \u2014 inspect its singular `failure_detail` field:\n   - If `failure_detail` is a dict containing actionable keys such as `annotations`, `log_tail`, or `log`, treat it as structured detail and use it for remediation.\n   - If `failure_detail` is a dict containing only `url`, treat it as URL-only and skip with a warning (no actionable detail).\n   - If `failure_detail` is missing, `null`, or unrecognized, treat the failure as non-actionable and skip with a warning.\n   - Do NOT rely on a per-check field or a plural variant of `failure_detail` \u2014 those do not exist on the response.\n\n11. After applying a non-empty correction set: stage corrections (`git add` the specific files), commit, and push. Use the canonical commit message:\n   ```\n   {ticket_key}: address review/CI feedback (round N+1)\n   ```\n   where `N` is the zero-indexed `iteration`.\n12. Increment `iteration` only AFTER a successful commit and push. Then loop back to step 1 of the per-iteration block.\n\n## Step 7 \u2014 `custom`\n\nIn `custom` mode, the `instructions` field IS the complete CI follow-up instruction set for this step. Follow it verbatim. Ignore Steps 5 and 6 entirely.\n\nCustom instructions are authoritative for CI follow-up behavior, but they remain subject to the agent\'s normal tool approval, credential handling, secret-handling, and platform safety constraints. Custom prose CANNOT bypass approval gates, exfiltrate secrets, or override platform safety policies, even though admin-only access controls who can set the field.\n\n## Worker finalization \u2014 clean session exit (Conductor auto mode)\n\nThis section applies ONLY when you were launched under the Conductor in auto mode (the `BAPI_CONDUCTOR_RUN_ID`/`BAPI_CONDUCTOR_WORKER_ID` env identifiers are present). A standalone `/check-ci` run or any non-Conductor worker ignores it entirely.\n\nBefore doing anything here, distinguish two states:\n\n- **CI/review follow-up still owned by this worker** \u2014 the `fix_and_iterate` loop is still correcting failures, review changes were requested and are unaddressed, a merge conflict on your PR is unresolved, or you have unpushed local commits. In this state you are **not** finished: keep working the CI-monitoring / correction loop and do **not** exit.\n- **Final PR state reached; no further worker action pending** \u2014 your final branch state is pushed, the PR has been created/updated, the done-gate / CI-monitoring workflow required by the recipe has completed (required checks green and, when `claude-review` is required, the verdict token confirms approval for the current head), and no CI/review follow-up remains that you own.\n\nOnly in the second state \u2014 that is, **only after the final push, PR creation/update, done-gate confirmation, and CI/review monitoring have all completed** and no follow-up remains \u2014 cleanly end your worker session (for example by issuing the `/exit` command) so the worktree is released and no idle process lingers. Do **not** exit immediately after opening a PR while CI or review is still pending, and do not exit while there are unresolved CI failures, requested review changes, a merge conflict you own, or unpushed local commits. A clean `SessionEnd` is both the correct terminal lifecycle signal (the conductor folds it) and the point at which the worker should exit.\n\n## Return\n\nReport whether CI passed, failed, timed out, or was unavailable. If failed, list the failing checks with their failure summaries. For `fix_and_iterate`, also report the iteration count and whether iteration/wall-clock caps were hit. If you finalized (cleanly exited) as a Conductor worker, note that the session ended after all follow-up completed.\n',
   "preflight-and-readiness.md": "Initialize the idea-to-ticket run directory and classify the idea's readiness and scope.\n\n## Inputs\n\n- Idea: `{idea}`\n- Slug: `{slug}`\n- Run ID: `{run_id}`\n- Docs directory: `{docs_dir}`\n- Project standards: response from the immediately preceding `get_project_standards` step. If that step returned an error envelope or a 404, treat the project standards as unavailable and proceed; do not halt.\n\n## Instructions\n\n1. Create the run directory:\n   ```\n   mkdir -p {docs_dir}/idea-to-ticket/{slug}-{run_id}\n   ```\n   Every artifact produced by this pipeline run lives under this run directory. No Jira mutation may occur in any later step until `run-manifest.json` has been written to this directory.\n\n2. Classify the idea on two independent axes:\n\n   **Readiness** (one of):\n   - `ready_to_draft` \u2014 the idea is concrete enough that a clear ticket draft can be produced.\n   - `needs_clarification` \u2014 the idea is reasonable but missing key answers; clarifying questions must be raised in `open-questions.md` later.\n   - `research_first` \u2014 drafting is blocked on external/codebase research; deep or narrow research must come first.\n   - `too_vague_to_ticket` \u2014 the idea is not actionable yet; do not produce a ticket.\n\n   **Scope** (one of):\n   - `task` \u2014 a single Jira Task (default when ambiguous).\n   - `spike` \u2014 a single Jira Spike for primarily discovery/research work.\n   - `epic_candidate` \u2014 the idea decomposes into a Jira Epic plus multiple child tickets.\n\n3. Halt locally if readiness is `too_vague_to_ticket`. Write the manifest anyway (see step 4) so the local artifacts record the halt; then stop without continuing the rest of the pipeline. Do not attempt any Jira mutation.\n\n4. Write `run-manifest.json` to `{docs_dir}/idea-to-ticket/{slug}-{run_id}/run-manifest.json`. Required fields:\n   - `idea` \u2014 the original `{idea}` text.\n   - `slug` \u2014 `{slug}`.\n   - `run_id` \u2014 `{run_id}`.\n   - `run_dir` \u2014 `{docs_dir}/idea-to-ticket/{slug}-{run_id}/`.\n   - `readiness` \u2014 one of the four readiness values above.\n   - `scope` \u2014 one of the three scope values above.\n   - `project_standards_available` \u2014 `true` if `get_project_standards` returned a usable result, `false` otherwise.\n   - `idempotency_label` \u2014 `bapi-idea-to-ticket-{run_id}` (per-run label; lets downstream steps resume THIS run by label).\n   - `stable_label` \u2014 `bapi-idea-hash-{idea_hash}` (stable across runs of the same idea; lets the duplicate-detection step catch a PRIOR run of the same idea by label, not just fuzzy text).\n   - `created_at` \u2014 ISO 8601 timestamp.\n\n5. The manifest is the resumability artifact for the whole run. Do not include secrets or raw credentials. Keep the file under a few KB.\n\n## Return\n\nConfirm the run directory and `run-manifest.json` were created, and report the classified `readiness` and `scope`. If readiness is `too_vague_to_ticket`, also report that the pipeline must stop without Jira mutation.\n",
   "request-prd.md": "# request_prd\n\nStart (or refresh) asynchronous generation of a **Product Requirements Document\n(PRD)** for a Jira ticket.\n\nA PRD is the most product/stakeholder-facing document in the design-document\nfamily. It frames product intent \u2014 the problem, goals, non-goals, target users,\nsuccess metrics, product requirements, scope, and risks \u2014 rather than the\ndetailed functional flows and acceptance behavior an FSD covers, or the\narchitecture/implementation guidance a TDD covers.\n\n## Async request/retrieve pattern\n\n`request_prd` only **starts** generation; it does not return the PRD directly\nunless you set `wait_for_result`. PRD generation typically takes **2\u20134 minutes**.\n\n1. Call `request_prd` with the `ticket_number`.\n2. Wait for processing to complete (2\u20134 minutes).\n3. Call `get_prd` with the same `ticket_number` to retrieve the result.\n\nSet `wait_for_result: true` to block and return the PRD content directly instead\nof polling separately.\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `ticket_number` | string | \u2014 | Jira ticket key in `PROJECT-NUMBER` format (e.g. `BAPI-123`). |\n| `wait_for_result` | boolean | `false` | When `true`, block and poll until the PRD is ready, then return it directly. |\n| `save_locally` | boolean | `true` | When `wait_for_result` is `true`, save the PRD to `BAPI_DOCS_DIR/prd/{ticket}-prd-plan.md`. |\n| `second_opinion` | string | \u2014 | Provider routing override for **this** generation request (e.g. `anthropic`, `openai`, `gemini`). This is **not** the standalone `second_opinion` tool \u2014 it only changes which provider produces this request's artifact, and takes precedence over `provider`. |\n| `provider` | string | \u2014 | Pure provider switch without second-opinion semantics. If both `provider` and `second_opinion` are set, `second_opinion` wins. |\n\n## Return\n\n- `202` when the request is accepted (async dispatch).\n- `404` if the ticket does not exist in Jira.\n- `403` if the API key is unauthorized.\n",
@@ -15122,7 +15128,7 @@ var INSTRUCTIONS = {
 init_version_generated();
 
 // src/readme.generated.ts
-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](./docs/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 that runs `/install-bridge` to derive and\napply the remaining config, presents a **capability report** (what you can use now\nand what you\'ll unlock), and closes by asking whether to index the repository. It\ndoes **not** automatically run `/learn-repository` or index without your consent \u2014\nboth remain available as separate steps. The only inputs are an **API key**\n(generate one on the Bridge API web UI **Security** page) and a **repo name** \u2014\neverything else is derived. Add `--dry-run` to preview every step without writing,\npinging, or spawning anything.\n\n**Were you sent a bootstrap invite?** Then you don\'t need an API key or the web UI\nat all \u2014 run the command your operator gave you:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge --invite\n```\n\nThat one-liner is deliberately **secret-free**: the CLI prompts for the bootstrap\ninvite token with **echo suppressed**, and sends it only in the request body. It\ncreates your project and mints your own admin API key in a single command.\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 and apply\n   the remaining config fields from your codebase, presents the capability report\n   (Connected / Not yet connected / Tools you can use now / Tools you\'ll unlock /\n   Recommended next step), and closes with one optional `[Y/n] Index repository\n   now?` question. It does not chain `/learn-repository` and never indexes without\n   consent; run `/learn-repository` and `/parse-repository` yourself when you want\n   them.\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 \u2014 **`--invite` is the one exception** (below). The key is\n  **never printed or logged**.\n- **Repo name:** `--repo <name>` and `BAPI_REPO_NAME` remain the deterministic\n  short-circuits and compatibility fallbacks \u2014 when either is set it is used\n  directly, with no network round-trip. When **neither** is set, a compatible\n  server resolves the unique repository from your existing API key automatically\n  (a read-only lookup), so you don\'t have to supply it. If the server is older,\n  the key can\'t be uniquely resolved, or the lookup fails, `install-bridge` falls\n  back to an inferred default you confirm interactively (and requires `--repo`\n  when stdin is non-interactive). Whatever name is used MUST match the\n  server-side repository registration.\n\n#### Self-serve email onboarding (`--email`) \u2014 no account, no key, no invite\n\nThe primary path for a **first-time user with nothing yet** \u2014 no Bridge account,\nno API key, and no pre-issued invite. Run:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge --email you@example.com\n```\n\n`install-bridge` requests a brand-new Bridge workspace for that email, receives an\ninvite token, and then feeds it into the **exact same** persist-before-exchange\nbootstrap protocol as `--invite` below \u2014 so the project is created and your first\nadmin key is minted in one command. The minted token is used internally and **never\nshown**.\n\nThe email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a\n**visible** interactive prompt (email is not a secret, so it is echoed as you type \u2014\nunlike the API key and the invite token, which use a hidden prompt). It is still\n**never written to a log line**. No email verification is performed and no message\nis sent to the address \u2014 it only labels your new workspace. `--email` is mutually\nexclusive with `--api-key` and `--invite`.\n\n#### Bootstrap-invite onboarding (`--invite`)\n\nWith a **bootstrap invite** you were already given, there is no pre-existing key and\nno web UI: like `--email` above, this mode **creates** the project and its first\nadmin key instead of consuming one. Run `install-bridge --invite` and it:\n\n1. **Prompts for the bootstrap invite token** with echo suppressed (the default \u2014\n   see below).\n2. **Generates your `key_secret`** (32 CSPRNG bytes) and **fsyncs it locally**\n   *before* contacting the server. If that write fails the run aborts and the\n   invite is **not** spent.\n3. **Redeems the invite** \u2014 `POST /setup/bootstrap` with the token, repo name, and\n   `key_secret` in the **body** \u2014 which creates the project and mints your admin\n   key. (This replaces the connectivity ping: there is no key to ping with yet.)\n4. **Verifies the newly-minted key**, then writes the per-host MCP config.\n5. **Promotes the credential** to `bapi:<repo>` and **opens the agent session** \u2014\n   the same Steps 3\u20135 as the normal flow.\n\nBecause the locally-saved `key_secret` is the only proof that can replay a\nredemption, a re-run after a network failure is safe: it re-sends the *same* secret\nand gets back the *same* project and key. If the repo name you chose is already\ntaken (names are globally unique) the server rolls back \u2014 your invite is untouched \u2014\nand the CLI asks for a different name and retries with the same token.\n\n**The delivered one-liner is secret-free, by design.** "A copy/paste one-liner" and\n"the token never touches shell history" are contradictory, so the token is *not* in\nthe command: the CLI asks for it, and it travels only in the request body.\n`--invite <token>`, `--invite=<token>`, and `BAPI_INVITE` still work for\n**scripting only** \u2014 and both forms **expose the token to your shell history and to\nthe process list**. Prefer the prompt.\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  With `--invite` it also never calls the exchange endpoint and never generates or\n  stores a secret.\n- `--force` \u2014 overwrite an existing real `BAPI_API_KEY` in a host config, or in the\n  credential store, without 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- `--email <addr>` \u2014 self-serve signup: create a new workspace from just an email\n  (mutually exclusive with `--api-key` and `--invite`). Falls back to\n  `BAPI_SIGNUP_EMAIL`, then a visible prompt. Visible input, not a secret; still\n  never logged.\n- `--invite [token]` \u2014 redeem a bootstrap invite (mutually exclusive with\n  `--api-key` and `--email`). Omit the value to get the hidden prompt.\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 plus an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The backend executor now owns all review round orchestration (including the second-opinion round) server-side; pass `--rounds=1` for a cheaper single-pass review, `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide.\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` request a cheaper single-pass review (no second-opinion round) while preserving downstream evaluation and decision-capture work \xB7 `--rounds=2` force the full second-opinion review \xB7 omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide (it falls back to a full second-opinion review when adaptive routing is disabled or the ticket\'s difficulty cannot be resolved).\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 \xB7 `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs (default `implement`, byte-identical to today; `review-and-implement` runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session) \xB7 `--rounds=1|2` review-only, forwarded to the review phase, valid only with `--workflow review-and-implement`.\n\n**2b. Review and Start**\n- **What it does:** Spawns one worktree per ticket, each running review then (after a per-ticket human proceed/halt gate) implementation \u2014 the chained `review \u2192 gate \u2192 implement` composition.\n- **When it\'s useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/full-automation`, which only accepts an idea).\n- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).\n- **Flags:** `--auto` a single chain-level flag that auto-approves both the review and the implementation phase of every spawned session \xB7 `--rounds=1|2` forwarded to the review phase \xB7 `--agent`, `--base-branch`, `--max-parallel`, `--dry-run` mirror `/start-tickets`.\n- Under the hood, this is a thin shim over `start-tickets --workflow review-and-implement <KEYS>` \u2014 the lower-level launcher seam documented above; the halt-gate decision logic lives in the spawned `/review-and-implement` session, never in this command or the CLI.\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\nFor a step-by-step OCAPI client setup guide (including the Business Manager permissions grant), see [docs/install/sfcc-integration.md](./docs/install/sfcc-integration.md).\n\n<details>\n<summary><strong>Setup</strong></summary>\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The read tools, the write tools, and `sfcc_log_query` must be enabled with a profile (step 3). Changing `BRIDGE_MCP_PROFILE` requires an MCP client restart.\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, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.\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_attributes_get` \u2014 fetch attribute definitions for a known custom object type. OCAPI cannot enumerate custom object types, so `object_type` must already be known.\n- `custom_object_definition_attribute_search` \u2014 search attribute definitions within a known custom object type. Read-only \u2014 creating a custom object *type* isn\'t possible via OCAPI; that\'s a future v2 metadata-import capability.\n- `custom_object_definition_attribute_create` \u2014 **write** (sandbox only): create an attribute definition on a known custom object type via `PUT /custom_object_definitions/{type}/attribute_definitions/{id}`. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.\n- `custom_object_definition_attribute_update` \u2014 **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH \u2026/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.\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- `site_preference_values_set` \u2014 **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.\n\n**On-demand log query** (needs the `sfcc` profile)\n- `sfcc_log_query` \u2014 query redacted, filtered SFCC logs on demand. `environment` and `time_range` (`start`/`end`) are **required** \u2014 production, "all environments", and an open-ended period are never inferred. The tool calls a Bridge backend endpoint that runs the pull \u2192 redaction \u2192 filter pipeline server-side and returns scoped, redacted findings; **WebDAV credentials, retrieval, redaction, and filtering all stay server-side and single-sourced.** It holds no credentials of its own.\n  - **Guardrails.** Selection is bounded by log-file `prefixes` (max 5), the time range, a scanned-entry cap (`max_entries`, \u2264 2000), a finding cap, and a per-snippet length cap. High-volume prefix classes (`info`, `jobs`, `debug`, `customdebug`) impose a **stricter 6-hour** max range (vs. 24h for the error class) because `info-*` runs ~1 MB/day versus `error-*` at ~13 KB median \u2014 a wide window over a high-volume prefix is **rejected**, never silently narrowed.\n  - **Response order.** Resolved scope (`environment`, `time_range`, `applied_prefixes`) and cap `status` first, redacted `findings` second, retrieval/truncation `metadata` last.\n  - **Statuses & errors.** `ready`, `no_matching_findings`, `results_truncated`; plus `VALIDATION_ERROR` (bad/oversized scope, caught before any network call), `NOT_CONFIGURED` (503 \u2014 the log capability isn\'t set up; run `sfcc_setup_status`, whose step 6 reports it), and `BAD_GATEWAY`/`SERVICE_UNAVAILABLE` on a retrieval/backend failure.\n  - **Auth is separate from OCAPI.** Log retrieval uses **HTTP Basic auth** \u2014 a Business Manager username + a **40-character WebDAV access key** \u2014 *not* the OCAPI Account Manager OAuth token the other SFCC tools use. A valid AM bearer token 401s on `/Logs`. `sfcc_setup_status` step 5 (AM/OCAPI token) and step 6 (WebDAV log access) are independent: one can be green while the other is not.\n  - **Local / air-gapped fallback.** The primary path above is the only path this tool takes. For air-gapped development, the documented fallback is Salesforce\'s own **`@salesforce/b2c-dx-mcp`** (`logs_list_files`, configured from `dw.json`) \u2014 it is vendor-maintained and reads log files over WebDAV, so it is strictly less work than shelling the B2C CLI (`b2c logs get --since <window> --search <q> --json`). It is **not** the primary path because its credentials live client-side and its output has **not** passed Bridge\'s redaction/filter. If you use it, its output must be treated as raw: route it back through the same server-side Python `LogSource` composition and `RedactionPort`/T3 filter workflow \u2014 never paste or relay unredacted `b2c-dx-mcp` or CLI output to an LLM.\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`. For existing ticket keys, `/review-and-start` (see [Usage Documentation \u2192 Review and Start](#tier-1--regularly-useful)) is the recommended enriched front door over this CLI\'s `--workflow review-and-implement` seam; using the CLI directly (below) remains the advanced/lower-level path.\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| `--workflow implement\\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `implement` is byte-identical to today\'s `/implement-ticket <KEY> [--auto]`. `review-and-implement` spawns `/review-and-implement <KEY> [--auto] [--rounds=<n>]`, which runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session. `--auto` applies to the selected workflow as a whole. |\n| `--rounds 1\\|2` | unset | Review round count forwarded to the review phase. Review-only \u2014 valid only with `--workflow review-and-implement`. |\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](./docs/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### `setup-epic`\n\nBootstraps an Epic Conductor v2 run in one command \u2014 creates the epic run, stores the plan DAG, and approves it:\n\n```\nnpx -y @bridge_gpt/mcp-server setup-epic --epic-key <KEY> --plan-file <path-to-epic-plan.dag.json>\n```\n\nThe plan sidecar is produced by the `decompose-epic` pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable dependency references, acyclicity) before sending anything, so a malformed plan fails legibly instead of as a bare HTTP 400. It is **idempotent**: re-running it on an epic that already has a live run reuses that run rather than minting a second one. `--dry-run` validates and previews the calls without mutating anything; `--json` emits a single machine-readable result object.\n\nOnce the plan is approved, the **server-side reconciler** picks the run up within ~30s. To execute claimed jobs on your machine, run `executor`:\n\n```\nnpx -y @bridge_gpt/mcp-server executor --repo <name>\n```\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 the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream \u2014 lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**.\n\n> The v1 `conductor epic-tick` command is **frozen** \u2014 it throws on every invocation. There is nothing to schedule locally, and `conductor doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.\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 **59 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`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)\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: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. | `/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](./docs/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\nRun bare like that in a terminal and it starts by asking\n**`Do you have a Bridge API key? [Y/n]`**:\n\n- **Yes** (or just press Enter) \u2014 the existing-key flow. It asks for your **API key**\n  (generate one on the Bridge API web UI **Security** page) and a **repo name**\n  matching your server-side registration; everything else is derived.\n- **No** \u2014 the **self-serve** flow. It asks for an **email**, then a name for your new\n  Bridge project, and creates the workspace and your own admin API key for you. No\n  account, no key, and no invite needed beforehand. Same as passing\n  `--email you@example.com` (see below).\n\nThat question is asked only for a *bare interactive* run. Passing any flag, setting\n`BAPI_API_KEY`, or running without an interactive terminal skips it and keeps the\nexisting deterministic behavior.\n\nFrom there `install-bridge` scaffolds the project, writes your editor\'s MCP config\nwith real values, verifies connectivity, persists your API key to the user-scoped\ncredential store, and opens a fresh agent session that runs `/install-bridge` to\nderive and apply the remaining config, presents a **capability report** (what you can\nuse now and what you\'ll unlock), and closes by asking whether to index the\nrepository. It does **not** automatically run `/learn-repository` or index without\nyour consent \u2014 both remain available as separate steps. Add `--dry-run` to preview\nevery step without writing, pinging, or spawning anything.\n\n**Were you sent a bootstrap invite?** Then you don\'t need an API key or the web UI\nat all \u2014 run the command your operator gave you:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge --invite\n```\n\nThat one-liner is deliberately **secret-free**: the CLI prompts for the bootstrap\ninvite token with **echo suppressed**, and sends it only in the request body. It\ncreates your project and mints your own admin API key in a single command.\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 and apply\n   the remaining config fields from your codebase, presents the capability report\n   (Connected / Not yet connected / Tools you can use now / Tools you\'ll unlock /\n   Recommended next step), and closes with one optional `[Y/n] Index repository\n   now?` question. It does not chain `/learn-repository` and never indexes without\n   consent; run `/learn-repository` and `/parse-repository` yourself when you want\n   them.\n\nIn this **existing-key** flow the only inputs are an **API key** and a **repo name**\n(everything else is derived). 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)); in this flow the command consumes\n  a key, it never mints one \u2014 **`--email` and `--invite` are the two exceptions**\n  (below), and each mints your first key. The key is **never printed or logged**.\n- **Repo name:** `--repo <name>` and `BAPI_REPO_NAME` remain the deterministic\n  short-circuits and compatibility fallbacks \u2014 when either is set it is used\n  directly, with no network round-trip. When **neither** is set, a compatible\n  server resolves the unique repository from your existing API key automatically\n  (a read-only lookup), so you don\'t have to supply it. If the server is older,\n  the key can\'t be uniquely resolved, or the lookup fails, `install-bridge` falls\n  back to an inferred default you confirm interactively (and requires `--repo`\n  when stdin is non-interactive). Whatever name is used MUST match the\n  server-side repository registration.\n\n#### Self-serve email onboarding (`--email`) \u2014 no account, no key, no invite\n\nThe primary path for a **first-time user with nothing yet** \u2014 no Bridge account,\nno API key, and no pre-issued invite. Run:\n\n```bash\nnpx -y @bridge_gpt/mcp-server@latest install-bridge --email you@example.com\n```\n\n`install-bridge` requests a brand-new Bridge workspace for that email, receives an\ninvite token, and then feeds it into the **exact same** persist-before-exchange\nbootstrap protocol as `--invite` below \u2014 so the project is created and your first\nadmin key is minted in one command. The minted token is used internally and **never\nshown**.\n\nThe email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a\n**visible** interactive prompt (email is not a secret, so it is echoed as you type \u2014\nunlike the API key and the invite token, which use a hidden prompt). That prompt is\nwhat answering **no** to `Do you have a Bridge API key? [Y/n]` on a bare run reaches,\nso `install-bridge --email you@example.com` and a bare `install-bridge` + "no" land\nin the same place. The email is still **never written to a log line**. No email\nverification is performed and no message is sent to the address \u2014 it only labels your\nnew workspace. `--email` is mutually exclusive with `--api-key` and `--invite`.\n\nBecause this flow *creates* the project, it asks you to **name a new project**\n(`Name your new Bridge project [<inferred>]: `) rather than to match an existing\nserver-side registration. The name must be globally unique; if it\'s taken, you\'re\nasked for another one and the invite is not consumed. The same applies to `--invite`.\n\n#### Bootstrap-invite onboarding (`--invite`)\n\nWith a **bootstrap invite** you were already given, there is no pre-existing key and\nno web UI: like `--email` above, this mode **creates** the project and its first\nadmin key instead of consuming one. Run `install-bridge --invite` and it:\n\n1. **Prompts for the bootstrap invite token** with echo suppressed (the default \u2014\n   see below).\n2. **Generates your `key_secret`** (32 CSPRNG bytes) and **fsyncs it locally**\n   *before* contacting the server. If that write fails the run aborts and the\n   invite is **not** spent.\n3. **Redeems the invite** \u2014 `POST /setup/bootstrap` with the token, repo name, and\n   `key_secret` in the **body** \u2014 which creates the project and mints your admin\n   key. (This replaces the connectivity ping: there is no key to ping with yet.)\n4. **Verifies the newly-minted key**, then writes the per-host MCP config.\n5. **Promotes the credential** to `bapi:<repo>` and **opens the agent session** \u2014\n   the same Steps 3\u20135 as the normal flow.\n\nBecause the locally-saved `key_secret` is the only proof that can replay a\nredemption, a re-run after a network failure is safe: it re-sends the *same* secret\nand gets back the *same* project and key. If the repo name you chose is already\ntaken (names are globally unique) the server rolls back \u2014 your invite is untouched \u2014\nand the CLI asks for a different name and retries with the same token.\n\n**The delivered one-liner is secret-free, by design.** "A copy/paste one-liner" and\n"the token never touches shell history" are contradictory, so the token is *not* in\nthe command: the CLI asks for it, and it travels only in the request body.\n`--invite <token>`, `--invite=<token>`, and `BAPI_INVITE` still work for\n**scripting only** \u2014 and both forms **expose the token to your shell history and to\nthe process list**. Prefer the prompt.\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  With `--invite` it also never calls the exchange endpoint and never generates or\n  stores a secret.\n- `--force` \u2014 overwrite an existing real `BAPI_API_KEY` in a host config, or in the\n  credential store, without 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- `--email <addr>` \u2014 self-serve signup: create a new workspace from just an email\n  (mutually exclusive with `--api-key` and `--invite`). Falls back to\n  `BAPI_SIGNUP_EMAIL`, then a visible prompt. Visible input, not a secret; still\n  never logged.\n- `--invite [token]` \u2014 redeem a bootstrap invite (mutually exclusive with\n  `--api-key` and `--email`). Omit the value to get the hidden prompt.\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 plus an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The backend executor now owns all review round orchestration (including the second-opinion round) server-side; pass `--rounds=1` for a cheaper single-pass review, `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide.\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` request a cheaper single-pass review (no second-opinion round) while preserving downstream evaluation and decision-capture work \xB7 `--rounds=2` force the full second-opinion review \xB7 omit `--rounds` to let the backend\'s difficulty-adaptive review policy decide (it falls back to a full second-opinion review when adaptive routing is disabled or the ticket\'s difficulty cannot be resolved).\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 \xB7 `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs (default `implement`, byte-identical to today; `review-and-implement` runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session) \xB7 `--rounds=1|2` review-only, forwarded to the review phase, valid only with `--workflow review-and-implement`.\n\n**2b. Review and Start**\n- **What it does:** Spawns one worktree per ticket, each running review then (after a per-ticket human proceed/halt gate) implementation \u2014 the chained `review \u2192 gate \u2192 implement` composition.\n- **When it\'s useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/full-automation`, which only accepts an idea).\n- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).\n- **Flags:** `--auto` a single chain-level flag that auto-approves both the review and the implementation phase of every spawned session \xB7 `--rounds=1|2` forwarded to the review phase \xB7 `--agent`, `--base-branch`, `--max-parallel`, `--dry-run` mirror `/start-tickets`.\n- Under the hood, this is a thin shim over `start-tickets --workflow review-and-implement <KEYS>` \u2014 the lower-level launcher seam documented above; the halt-gate decision logic lives in the spawned `/review-and-implement` session, never in this command or the CLI.\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\nFor a step-by-step OCAPI client setup guide (including the Business Manager permissions grant), see [docs/install/sfcc-integration.md](./docs/install/sfcc-integration.md).\n\n<details>\n<summary><strong>Setup</strong></summary>\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The read tools, the write tools, and `sfcc_log_query` must be enabled with a profile (step 3). Changing `BRIDGE_MCP_PROFILE` requires an MCP client restart.\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, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.\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_attributes_get` \u2014 fetch attribute definitions for a known custom object type. OCAPI cannot enumerate custom object types, so `object_type` must already be known.\n- `custom_object_definition_attribute_search` \u2014 search attribute definitions within a known custom object type. Read-only \u2014 creating a custom object *type* isn\'t possible via OCAPI; that\'s a future v2 metadata-import capability.\n- `custom_object_definition_attribute_create` \u2014 **write** (sandbox only): create an attribute definition on a known custom object type via `PUT /custom_object_definitions/{type}/attribute_definitions/{id}`. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.\n- `custom_object_definition_attribute_update` \u2014 **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH \u2026/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.\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- `site_preference_values_set` \u2014 **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.\n\n**On-demand log query** (needs the `sfcc` profile)\n- `sfcc_log_query` \u2014 query redacted, filtered SFCC logs on demand. `environment` and `time_range` (`start`/`end`) are **required** \u2014 production, "all environments", and an open-ended period are never inferred. The tool calls a Bridge backend endpoint that runs the pull \u2192 redaction \u2192 filter pipeline server-side and returns scoped, redacted findings; **WebDAV credentials, retrieval, redaction, and filtering all stay server-side and single-sourced.** It holds no credentials of its own.\n  - **Guardrails.** Selection is bounded by log-file `prefixes` (max 5), the time range, a scanned-entry cap (`max_entries`, \u2264 2000), a finding cap, and a per-snippet length cap. High-volume prefix classes (`info`, `jobs`, `debug`, `customdebug`) impose a **stricter 6-hour** max range (vs. 24h for the error class) because `info-*` runs ~1 MB/day versus `error-*` at ~13 KB median \u2014 a wide window over a high-volume prefix is **rejected**, never silently narrowed.\n  - **Response order.** Resolved scope (`environment`, `time_range`, `applied_prefixes`) and cap `status` first, redacted `findings` second, retrieval/truncation `metadata` last.\n  - **Statuses & errors.** `ready`, `no_matching_findings`, `results_truncated`; plus `VALIDATION_ERROR` (bad/oversized scope, caught before any network call), `NOT_CONFIGURED` (503 \u2014 the log capability isn\'t set up; run `sfcc_setup_status`, whose step 6 reports it), and `BAD_GATEWAY`/`SERVICE_UNAVAILABLE` on a retrieval/backend failure.\n  - **Auth is separate from OCAPI.** Log retrieval uses **HTTP Basic auth** \u2014 a Business Manager username + a **40-character WebDAV access key** \u2014 *not* the OCAPI Account Manager OAuth token the other SFCC tools use. A valid AM bearer token 401s on `/Logs`. `sfcc_setup_status` step 5 (AM/OCAPI token) and step 6 (WebDAV log access) are independent: one can be green while the other is not.\n  - **Local / air-gapped fallback.** The primary path above is the only path this tool takes. For air-gapped development, the documented fallback is Salesforce\'s own **`@salesforce/b2c-dx-mcp`** (`logs_list_files`, configured from `dw.json`) \u2014 it is vendor-maintained and reads log files over WebDAV, so it is strictly less work than shelling the B2C CLI (`b2c logs get --since <window> --search <q> --json`). It is **not** the primary path because its credentials live client-side and its output has **not** passed Bridge\'s redaction/filter. If you use it, its output must be treated as raw: route it back through the same server-side Python `LogSource` composition and `RedactionPort`/T3 filter workflow \u2014 never paste or relay unredacted `b2c-dx-mcp` or CLI output to an LLM.\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`. For existing ticket keys, `/review-and-start` (see [Usage Documentation \u2192 Review and Start](#tier-1--regularly-useful)) is the recommended enriched front door over this CLI\'s `--workflow review-and-implement` seam; using the CLI directly (below) remains the advanced/lower-level path.\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| `--workflow implement\\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `implement` is byte-identical to today\'s `/implement-ticket <KEY> [--auto]`. `review-and-implement` spawns `/review-and-implement <KEY> [--auto] [--rounds=<n>]`, which runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session. `--auto` applies to the selected workflow as a whole. |\n| `--rounds 1\\|2` | unset | Review round count forwarded to the review phase. Review-only \u2014 valid only with `--workflow review-and-implement`. |\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](./docs/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### `setup-epic`\n\nBootstraps an Epic Conductor v2 run in one command \u2014 creates the epic run, stores the plan DAG, and approves it:\n\n```\nnpx -y @bridge_gpt/mcp-server setup-epic --epic-key <KEY> --plan-file <path-to-epic-plan.dag.json>\n```\n\nThe plan sidecar is produced by the `decompose-epic` pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable dependency references, acyclicity) before sending anything, so a malformed plan fails legibly instead of as a bare HTTP 400. It is **idempotent**: re-running it on an epic that already has a live run reuses that run rather than minting a second one. `--dry-run` validates and previews the calls without mutating anything; `--json` emits a single machine-readable result object.\n\nOnce the plan is approved, the **server-side reconciler** picks the run up within ~30s. To execute claimed jobs on your machine, run `executor`:\n\n```\nnpx -y @bridge_gpt/mcp-server executor --repo <name>\n```\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 the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream \u2014 lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**.\n\n> The v1 `conductor epic-tick` command is **frozen** \u2014 it throws on every invocation. There is nothing to schedule locally, and `conductor doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.\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 **59 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`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)\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: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. | `/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();
@@ -15464,12 +15470,12 @@ var COMMANDS = {
   "create-pr.md": '# Create PR: $ARGUMENTS\n\n$ARGUMENTS\n\nThis command takes a Jira ticket key (e.g., `BAPI-150`), fetches the ticket summary, determines the base branch, and creates a pull request on the configured VCS provider. It is designed to run after `/commit-ticket` completes.\n\nIf any critical stage fails (Stage 0), stop immediately and report which stage failed and why. Non-critical stages (Stage 1 and Stage 2) should log a warning but not stop the pipeline.\n\n---\n\n# Instructions\n\nYou are executing a 3-stage pipeline to create a pull request for a Jira ticket. Execute all stages in sequence.\n\n## Stage 0 \u2014 Setup and Argument Parsing\n\n1. **Parse `$ARGUMENTS`**: Extract a single required `ticket_key` argument. The expected format is a Jira ticket key such as `BAPI-150` or `PROJ-123` \u2014 one or more uppercase letters, a hyphen, and one or more digits (regex: `[A-Z]+-\\d+`). If `$ARGUMENTS` is empty or the value does not match the expected format, stop immediately and display:\n\n   ```\n   Invalid ticket key format: \'<value>\'. Expected format: PROJ-123 (uppercase letters, hyphen, digits).\n   Usage: /create-pr <ticket_key> (e.g., /create-pr BAPI-150)\n   ```\n\n2. **Connectivity check**: Call the `ping` MCP tool (no parameters). If the ping fails or does not return `"status": "ok"`, stop immediately and display:\n\n   ```\n   Connectivity check failed. Please verify:\n   - Check that the Bridge API MCP server is configured in your editor\'s MCP settings\n   - Check that BAPI_BASE_URL is set and the server is reachable\n   - Check that BAPI_API_KEY is valid\n   - Check that BAPI_REPO_NAME matches a configured repository\n   ```\n\n3. **Get current branch**: Run `git branch --show-current` in the terminal. Store the result as `head_branch`. Verify that `head_branch` contains the `ticket_key` (case-insensitive comparison). If the branch does not contain the ticket key, stop immediately and display:\n\n   ```\n   Current branch \'<head_branch>\' does not contain ticket key <ticket_key>.\n   Please switch to the correct feature branch before running /create-pr.\n   ```\n\n4. **Resolve base branch**: Call the `config_field` MCP tool with `operation` set to `"get"` and `field_name` set to `base_branch`. If the tool returns null, or an HTTP 400 Validation Error / Invalid field name, treat it as not set and fallback to `main`. Store the resolved value as `base_branch`.\n\n5. **Fetch ticket summary**: Call the `get_ticket` MCP tool with `ticket_number` set to the parsed `ticket_key`. Extract the ticket summary from the response. If the tool returns an error, log a warning and use a generic summary based on the ticket key.\n\n6. **Resolve docs directory**: Call the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\nThis stage is **critical** \u2014 stop immediately on failure. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Create Pull Request\n\n1. **Compose PR title**: Format the title as `<ticket_key>: <ticket_summary>`. Truncate to 72 characters if needed.\n\n2. **Compose PR body**: Build a PR body that includes:\n   - A brief description derived from the ticket summary\n   - A plain text reference to the local implementation plan: `Implementation Plan available locally at {docs_dir}/plans/{ticket_key}-plan.md` (do not use markdown hyperlink syntax \u2014 the local path is sufficient for team members pulling the branch)\n\n3. **Create the pull request**: Call the `create_pull_request` MCP tool with:\n   - `head_branch`: the current branch from Stage 0\n   - `base_branch`: the resolved base branch from Stage 0\n   - `title`: the composed PR title\n   - `body`: the composed PR body\n\n4. **Handle the response with graceful degradation**:\n   - If the response contains `available: false`: Report the reason to the user and skip to Stage 2. Do not halt the pipeline.\n   - If the response contains `created: false`: Log "PR already exists" and store the returned PR URL. Continue to Stage 2.\n   - If the response contains `created: true`: Store the PR URL. Continue to Stage 2.\n   - If an HTTP error occurs: Warn the user with the error details and continue to Stage 2. Do not halt the pipeline.\n\nThis stage is **non-critical** \u2014 warn on failure, continue to Stage 2 regardless.\n\n## Stage 2 \u2014 Summary Report\n\nDisplay a structured report after all stages complete:\n\n```\n## Pull Request Report\n\n**Ticket**: <ticket_key>\n**Branch**: <head_branch>\n**Base Branch**: <base_branch>\n**PR URL**: <pr_url or "N/A \u2014 see warnings">\n\n**Warnings**:\n<If any non-critical stages had warnings (Stage 1: PR creation failed or unavailable),\nlist them here. If no warnings, omit this section.>\n```\n\nThis stage is **non-critical** \u2014 display the report regardless.\n\n## Final Report\n\nOn success, display the structured report from Stage 2 confirming that the pull request was created (or already existed), including the branch name, base branch, PR URL, and any warnings from earlier stages.\n\nOn failure at any critical stage (Stage 0), display which stage failed and the error details.\n',
   "critique-ticket.md": 'Generate a ticket quality critique and save it locally.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command triggers an AI-powered critique of a Jira ticket and saves the result locally. **No human confirmation gates** \u2014 the command runs end-to-end without pausing. `$ARGUMENTS` should contain a single Jira ticket key in `PROJECT-NUMBER` format (e.g., `BAPI-123`).\n\nIf any step fails, stop immediately and report which step failed and why.\n\n## Step 1 \u2014 Parse Arguments\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = "auto"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: "Usage error: --provider requires a provider name (openai, anthropic, or gemini)."\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n\n2. **Validate the ticket key format**: Validate that `ticket_key` matches the regex pattern `^[A-Za-z][A-Za-z0-9]+-\\d+$`. If validation fails, stop immediately and report: "The argument does not match the expected `PROJECT-NUMBER` format. Example: `BAPI-123`."\n\n## Step 2 \u2014 Resolve Docs Directory\n\nCall the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n## Step 3 \u2014 Generate Critique\n\nCall the `request_ticket_critique` MCP tool with:\n- `ticket_number`: the validated `ticket_key`\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if non-null; omit entirely if null\n- `provider`: set to `provider_value` if non-null; omit entirely if null\n\nIf the tool returns an error, stop immediately and report: "Critique generation failed." Include the error details.\n\n## Final Report\n\n**On success**, display a summary including:\n\n- Path to the saved critique document: `{docs_dir}/ticket-critiques/{ticket_key}-ticket-quality-critique.md`\n\nNote: The critique was NOT pushed to Jira. To incorporate the critique findings into the Jira ticket description, run: `/update-ticket {ticket_key}`\n\n**On failure at any step**, stop immediately and display the step that failed and the error details.\n',
   "estimate-epic.md": "Estimate an entire Jira Epic or an explicit ticket-key group via the shared epic estimation orchestrator.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\n`$ARGUMENTS` is either a Jira Epic key (e.g. `BAPI-518`) or an explicit `--tickets` key list \u2014 never both. This command calls the `estimate_epic` MCP tool, which delegates to the Bridge API epic estimation orchestrator, and renders the structured result.\n\nIf any step fails, stop immediately and report which step failed and why, preserving the user's originally entered epic key or ticket list in the report.\n\n## Step 1 \u2014 Parse Arguments\n\n1. **Parse `$ARGUMENTS`**: Extract exactly one key-source input, plus an optional `--allow-partial` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--tickets` appears, every token after it (up to the next flag or end of input) is the explicit ticket-key list \u2014 this is the `ticket_keys` mode.\n   - Otherwise, the first token matching the Jira key pattern (`[A-Z][A-Z0-9]+-\\d+`) is the `epic_key` \u2014 this is the epic mode.\n   - `--allow-partial` may appear anywhere; if present, set `allow_partial_value = true`. If absent, omit `allow_partial` entirely (do not pass `false`).\n   - Never resolve both an `epic_key` and a `ticket_keys` list from the same invocation \u2014 usage is one mode or the other.\n\n2. **Validate input**:\n   - Usage forms: `/estimate-epic EPIC-KEY` or `/estimate-epic --tickets KEY-1 KEY-2 ...`, plus optional `--allow-partial`.\n   - If neither an `epic_key` nor a `--tickets` list can be resolved, stop immediately and report:\n     ```\n     Usage: /estimate-epic EPIC-KEY [--allow-partial]\n            /estimate-epic --tickets KEY-1 KEY-2 ... [--allow-partial]\n     ```\n   - If `--tickets` is present but followed by zero keys, stop immediately and report: \"`--tickets` requires at least one ticket key.\"\n   - Do not invent or pass a `mode` parameter \u2014 there isn't one; the tool infers the source from whichever of `epic_key`/`ticket_keys` is supplied.\n\n## Step 2 \u2014 Call the Tool\n\nCall the `estimate_epic` MCP tool with:\n- `epic_key`: the resolved epic key \u2014 **only** when in epic mode. Omit entirely in ticket-key mode.\n- `ticket_keys`: the resolved ticket-key list \u2014 **only** when in ticket-key mode. Omit entirely in epic mode.\n- `allow_partial`: `allow_partial_value` if `--allow-partial` was passed; omit entirely otherwise (never pass `null`, an empty string, or an empty array for any absent field).\n\nNever pass both `epic_key` and `ticket_keys` in the same call.\n\nIf the tool returns an error envelope (a JSON object with an `error` field), stop and report the error message, preserving the epic key or ticket list the user originally entered.\n\n## Step 3 \u2014 Render the Result\n\nRender the successful result as a structured report \u2014 do not dump raw JSON by default:\n\n1. **Top**: the final estimate and its scale label (`estimate_label`) as the primary heading \u2014 this is the strongest element of the report.\n2. **Immediately after the summary**: `math_source`.\n3. **Next**: resolved child ticket keys (`child_ticket_keys`) and the per-child breakdown, presented compactly.\n4. **Only if non-empty**: a compact warning section listing `failed_child_keys` and `skipped_child_keys`.\n\nKeep the happy-path report concise and scannable. Use backticks for Jira keys and technical identifiers (e.g. `BAPI-518`).\n\n> Note: this tool does not accept a `recreate` parameter \u2014 the underlying epic estimation orchestrator (BAPI-522) always reuses cached child estimates and has no recreate knob to forward to.\n\n## Final Report\n\nOn successful completion, display a structured summary per Step 3 above. On failure, display the error message returned by the tool (or the usage error from Step 1), preserving the user's originally entered epic key or ticket list.\n",
-  "explore-ticket.md": 'Explore the codebase for a task and recommend implementation options or surface clarifying questions.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\n`$ARGUMENTS` is a free-form prompt describing a task you want to accomplish and your goals for it. This is **not** a Jira ticket key \u2014 it is plain text describing the work.\n\nExecute all exploration and analysis directly in the main conversation. The user should see exploration progress as it happens.\n\nIf any critical stage fails, stop immediately and report which stage failed and why.\n\n## Stage 0 \u2014 Setup\n\n1. **Parse prompt**: Extract the prompt text from `$ARGUMENTS`. Trim any surrounding whitespace. If the prompt is empty or whitespace-only, stop immediately and display: `Usage: /explore-ticket <prompt describing your task and goals>`\n\n2. **Resolve docs directory**: Call the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n3. **Generate output slug**: Create a kebab-case slug from the prompt \u2014 take the first 6-8 meaningful words, strip non-alphanumeric characters, lowercase, and truncate to 60 characters. The slug **must start with a letter** so it is a valid decision-page `ticket_key` in Stage 5 (`/^[A-Za-z][A-Za-z0-9_-]*$/`); if it would start with a digit or hyphen, prefix it with `exploration-`. If `{docs_dir}/explorations/{slug}.md` already exists, append a short timestamp suffix (e.g., `-1710000000`) \u2014 and fold that suffix **into the `slug` variable itself**, not just the filename, so that Stage 5 (`ticket_key`, `output_filename`) and Stage 6 (the `{docs_dir}/explorations/{slug}.md` rewrite) all reference the same slug. The output file path is `{docs_dir}/explorations/{slug}.md`.\n\n4. **Initialize tracking**: Prepare to track `key_files_examined` (list of files read during exploration), `web_searches` (list of topics searched), and `research_queries` (list of deep research queries).\n\nIf this stage fails, stop immediately and report the error. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Codebase Exploration\n\nThis is the core discovery stage. Take your time \u2014 thorough exploration is more valuable than speed.\n\n1. **Analyze the prompt** to identify which areas of the codebase are relevant: route files, agent flows, database models, library utilities, LLM integration, MCP server, tests, etc.\n\n2. **Search for files** matching patterns related to the task (e.g., `api/routes/**/*.py`, `src/python/llms/agents/**/*.py`, `db/models/*.py`).\n\n3. **Search for content** \u2014 relevant function names, class names, patterns, and keywords across the codebase.\n\n4. **Read the most relevant files** in detail \u2014 understand existing implementations, conventions, and patterns that relate to the task.\n\n5. **Build a mental model** of:\n   - What exists today that relates to the task\n   - What patterns and conventions are used in similar features\n   - What dependencies, data flows, and integration points are involved\n   - What gaps or unknowns remain that need external research\n\n6. **Track all significant files** examined in `key_files_examined`.\n\nDo not rush this stage. When in doubt, read more code rather than less. Continue exploring until you have a solid understanding of the relevant code.\n\nThis stage is non-blocking \u2014 always proceed to Stage 2 regardless of what you find, since the exploration informs what research is needed.\n\n## Stage 2 \u2014 Research Unknowns\n\nBased on gaps identified in Stage 1, decide what research is needed. Apply these decision rules:\n\n- **No research needed**: The codebase exploration answered all questions. Skip directly to Stage 3.\n- **Web search**: For quick factual lookups \u2014 library API signatures, configuration syntax, small "how to" questions. Examples: "FastAPI dependency injection with custom headers", "Alembic batch migration syntax". Do web searches inline and capture relevant findings.\n- **Deep research** (via `request_deep_research` MCP tool): For large, multi-faceted unknowns that require synthesizing information from multiple sources. Examples: "Best practices for implementing WebSocket connection pooling in Python asyncio", "Tradeoffs between different approaches to real-time notification delivery in FastAPI applications". Only use deep research when the question genuinely needs a multi-source investigation.\n\n**If deep research is needed:**\n\n1. Call `request_deep_research` with `wait_for_result` set to `true`, `save_locally` set to `true`, a descriptive `query`, and `context` describing the Bridge API tech stack and the specific task.\n2. If deep research fails, note the failure and fall back to web searches for the same topic. Do NOT halt the pipeline.\n\nTrack all research performed in `research_queries` and `web_searches`.\n\nThis stage is non-blocking \u2014 failures degrade the quality of analysis but do not stop the command. Log a warning for any failed research and continue.\n\n## Stage 3 \u2014 Analysis and Recommendation\n\nSynthesize everything from Stages 1 and 2 into a structured analysis:\n\n1. **Frame the goals and non-functional requirements first (required).** Before weighing implementation options, state plainly:\n   - **Business goal** \u2014 the value this work delivers and why it matters.\n   - **Desired end-state** \u2014 the concrete state the system should reach once this work is done.\n   - **System behavior** \u2014 how the system must behave to complete its task (the quality attributes in prose).\n\n   Then identify the non-functional requirements. Consider every one of these canonical NFR categories and include the ones that genuinely apply (omit the rest): security/privacy, performance/latency, reliability/failure-modes, observability/auditability, accessibility/UX, data-integrity/migration, compatibility, operability/config, compliance/SOC2, rollout/reversibility. For each NFR you include, write its `requirement` and its `implication` (what it changes about the implementation) \u2014 an NFR with no concrete implication is boilerplate; drop it. Classify each NFR\'s status with this rubric: `confirmed` only if explicitly stated or observable in code; `assumed` only if a low-risk, reversible default; `open` if it touches architecture, the data model, security, user-visible behavior, migration, or irreversible creation and is not settled. When the goals or an NFR are genuinely unclear, prefer marking them `open` and asking \u2014 clear goals make the functional choices far more accurate.\n\n2. **Identify viable implementation options** \u2014 at least 2 when multiple approaches exist, or 1 if there is genuinely only one reasonable path.\n\n3. **For each option, evaluate:**\n   - Implementation complexity and estimated effort\n   - How well it follows existing codebase patterns and conventions\n   - Risks, tradeoffs, and potential pitfalls\n   - Files that would need to be created or modified\n\n4. **Decide whether to recommend or ask questions:**\n   - **Recommend** if one option is clearly superior, or if the tradeoffs are well-understood and the choice is primarily technical.\n   - **Ask clarifying questions** if there are significant unknowns about goals, business requirements, or constraints that would change the recommendation. For each question, explain why the answer matters and how it would affect the choice between options.\n   - **When in doubt, ask rather than guess** \u2014 this command prioritizes thorough discovery over premature commitment.\n\n5. **Frame the open decisions so they are decision-page-ready.** Stage 5 renders these as cards on an interactive decision page, so each decision \u2014 the primary implementation-direction choice, any `open` NFR from step 1, plus any clarifying question that has discrete candidate answers \u2014 must be expressed with:\n   - A short decision **question** (e.g. "Which storage approach for the cache?").\n   - **2\u20134 concrete option labels.** Do **not** include a "None of these" or "Ask about this" option \u2014 the page auto-appends both. When there is genuinely a single reasonable path, still provide a second option: frame it as the recommended approach **plus the strongest alternative you considered** (a minimal/conservative variant, the rejected approach, or "defer until X is known").\n   - A one-line **consequence per option**, parallel to the options (what choosing that branch actually means for the implementation).\n   - A `why_it_matters` line (the concrete impact of the decision) and a `recommendation_explanation` (why the recommended branch is best).\n   - The 0-based index of the recommended option.\n   - Optional supporting evidence: an Assessment paragraph plus `file:line` citations from Stage 1.\n\n   Genuinely open-ended clarifying questions with no discrete answers do not need to become cards \u2014 capture them in the doc\'s Recommendation section as written. Aim to surface the real choices as cards; do not invent decisions just to fill the page.\n\nThis stage is inline analysis \u2014 no tool calls required. This stage is non-blocking \u2014 always proceed to Stage 4.\n\n## Stage 4 \u2014 Write Output\n\n1. Create the `explorations/` directory under `docs_dir` if it does not exist.\n\n2. Write the exploration document to the slug-based path determined in Stage 0 (`{docs_dir}/explorations/{slug}.md`) with this structure:\n\n```markdown\n# Exploration: {concise summary of the prompt}\n\n**Date**: {current date}\n**Prompt**: {original prompt text}\n\n## Context\n\n{Brief description of the task and what areas of the codebase are relevant.}\n\n## Goals & NFRs\n\n{The business goal, desired end-state, and required system behavior from Stage 3. Then the non-functional requirements: each with its category, requirement, implication, and status (confirmed / assumed / open). Open NFRs should also appear as decision cards on the Stage 5 page.}\n\n## Codebase Findings\n\n{Key discoveries from Stage 1. What exists today, what patterns are used, what the relevant code paths look like. Reference specific files and functions with file_path:line_number format.}\n\n## Research Findings\n\n{Findings from web searches and deep research, if any. If no research was performed, state "No external research was needed."}\n\n## Implementation Options\n\n### Option A: {name}\n\n{Description, approach, affected files, pros, cons.}\n\n### Option B: {name}\n\n{Description, approach, affected files, pros, cons.}\n\n## Recommendation\n\n{If recommending: State which option and why. Mention any caveats or risks.}\n\n{If asking questions: State "The following questions need to be answered before a confident recommendation can be made:" followed by numbered questions. For each question, explain why it matters and how the answer would affect the recommendation.}\n\n## Key Files\n\n{Bulleted list of the most important files examined, with one-line descriptions of their relevance.}\n```\n\nIf the file cannot be written, stop immediately and report the failure.\n\n## Stage 5 \u2014 Generate Decision Page\n\nTurn the decisions framed in Stage 3 into an interactive HTML decision page so the user can record their choices by clicking, instead of hand-editing the markdown doc.\n\n1. **Map each Stage 3 decision to an actionable item.** Build an `actionable_items` array where each entry has:\n   - `id`: a short stable id, e.g. `D-1`, `D-2`.\n   - `question`: the decision question.\n   - `options`: the 2\u20134 option labels (string array). Do **not** include "None of these" or "Ask about this" \u2014 the renderer auto-appends both.\n   - `option_consequences`: the per-option consequence lines, **parallel to and the same length as** `options`.\n   - `why_it_matters`: the concrete impact line.\n   - `recommendation_explanation`: why the recommended branch is best.\n   - `recommendation_index`: the 0-based index of the recommended option (must be within `options`).\n   - `codebase_evidence` (optional): the Assessment paragraph plus `file:line` citations, shown collapsed.\n   - `original_question` (optional): include only when the item maps to a verbatim clarifying question.\n\n   Optionally include `clear_improvements` for low-risk findings you are confident about that do not need a choice (each with `id`, `title`, `action`, `confidence`, `source`) \u2014 these render as an informational list and are not submitted.\n\n2. **Call `generate_decision_page`** with routing fields at the root and all heavy arrays nested under `content`:\n   - `artifact_type`: `pre_ticket_planning` (renders the read-only System Goals & NFRs panel above the decision cards).\n   - `ticket_key`: the Stage 0 `slug` (a non-Jira slug is fine \u2014 it must start with a letter and contain only letters, digits, hyphens, or underscores).\n   - `output_subdir`: `explorations` (so the page lands beside the markdown doc).\n   - `output_filename`: `{slug}-decisions.html`.\n   - `labels`: exploration-flavored overrides, e.g. `title` = "Exploration Decisions", `section_heading` = "Implementation Decisions", and an `intro` that frames the page as choosing the direction for the explored task.\n   - `content`: an object containing `system_goals`, `actionable_items`, and optionally `clear_improvements` from step 1. **`system_goals` MUST ALWAYS be passed** inside `content` so the backend always writes a page. Never omit it, even if all NFRs are confirmed. Open NFRs must ALSO appear in `actionable_items`. (Do not pass `implementation_order` inside `content` \u2014 that is for epic surfaces, not a single explored task.)\n\n   ```typescript\n   interface ExploreTicketContent {\n     system_goals?: {\n       business_goal: string;\n       desired_end_state: string;\n       system_behavior: string;\n       nfrs?: Array<{\n         category: string;\n         requirement: string;\n         implication: string;\n         status: "confirmed" | "assumed" | "open";\n       }>;\n     };\n     actionable_items?: Array<{\n       id: string;                      // e.g. "D-1", "D-2"\n       question: string;\n       why_it_matters: string;\n       recommendation_explanation: string;\n       options: string[];               // 2-4 option labels (no "None of these" or "Ask about this")\n       option_consequences: string[];   // same length as options\n       recommendation_index: number;   // 0-based within options\n       codebase_evidence?: string;      // optional: assessment + file:line citations\n       original_question?: string;      // optional: only when item maps to a clarifying question\n     }>;\n     clear_improvements?: Array<{\n       id: string;\n       title: string;\n       action: string;\n       confidence: string;\n       source: string;\n     }>;\n     // implementation_order: for epic surfaces only \u2014 do NOT include for single task explorations\n     // depends_on: hard prerequisites (titles/keys that must land first)\n     // recommended_after: soft sequencing preferences, not hard blockers\n   }\n   ```\n\n   Example call:\n   ```json\n   {\n     "ticket_key": "my-task-slug",\n     "artifact_type": "pre_ticket_planning",\n     "output_subdir": "explorations",\n     "output_filename": "my-task-slug-decisions.html",\n     "labels": { "title": "Exploration Decisions", "section_heading": "Implementation Decisions" },\n     "content": {\n       "system_goals": {\n         "business_goal": "Improve token efficiency for MCP sessions.",\n         "desired_end_state": "Core profile under 15k tokens.",\n         "system_behavior": "Schema delivered on demand, not in every session.",\n         "nfrs": [\n           { "category": "security/privacy", "requirement": "Errors in JSON envelope only", "implication": "Never render validation errors into HTML", "status": "confirmed" }\n         ]\n       },\n       "actionable_items": [\n         {\n           "id": "D-1",\n           "question": "Which approach?",\n           "why_it_matters": "Determines whether schema stays lean in production.",\n           "recommendation_explanation": "Option A saves ~1.8k tokens per session.",\n           "options": ["Lean schema + in-handler validation", "Keep full schema"],\n           "option_consequences": ["~1.8k token saving per session.", "No change from today."],\n           "recommendation_index": 0\n         }\n       ]\n     }\n   }\n   ```\n\n3. **Handle the response `status`:**\n   - `no_decisions_needed`: no page was written (no open decisions, no `system_goals`, and no `implementation_order`). This should not occur when `system_goals` is always passed. Skip Stage 6\'s capture loop entirely, tell the user there were no open decisions, and go straight to Stage 6\'s "Suggest next steps" guidance.\n   - `decision_page_generated`: surface the returned `file_path` and proceed to Stage 6\'s capture loop. **Always proceed to Stage 6\'s capture loop when `decision_page_generated` is returned**, regardless of `actionable_items_count`. A goals-only page (zero actionable items) still has NFR stance controls that must be submitted.\n\nThis stage is non-blocking: if `generate_decision_page` fails, do not halt. **You MUST output a highly visible warning** (e.g. **\u26A0 WARNING: The decision page could not be generated** in bold) explaining that generation failed and that the user should work from the markdown doc written in Stage 4 instead. Do not silently continue \u2014 the failure must be diagnosable from your output. Then skip to Stage 6\'s "Suggest next steps" guidance.\n\n## Stage 6 \u2014 Capture Decisions and Finalize\n\nCapture the user\'s choices, fold them into the exploration doc as resolved decisions, and recommend what to do next.\n\n1. **Direct the user to the page.** Provide the `file_path` from Stage 5 and tell them to open it in their browser. Explain that for any item they are unsure about they can choose "Ask about this" and you will talk it through, and that they can also ask questions in chat before submitting.\n\n2. **Q&A loop and commit signal.** Engage with each user message as either a commit or a discussion turn:\n   - **Commit:** trim the full message and attempt to parse the entire trimmed message as JSON. Treat it as a commit only when the parsed value is an object with all three top-level fields: `ticket_key` (string), `decisions` (object), and `general_comment` (string). The first valid commit-shaped paste commits \u2014 do not over-validate the per-card fields.\n   - **Discussion:** anything that is not commit-shaped JSON. Answer from the exploration doc written in Stage 4 and from codebase lookups. If a JSON-shaped paste is missing one of the three required fields, say which field is missing rather than treating it as a freeform question.\n   - **In-flight overrides:** when the user clearly changes a choice in chat ("go with option B for D-2", "change D-3 to None of these") or gives new overarching guidance, record it as a working-memory override. On commit, the submitted JSON is the baseline and recorded overrides take precedence; post a one-line acknowledgement naming each overridden item before you rewrite the doc.\n\n3. **Resolve "Ask about this" items (hard rule).** After accepting a commit, scan `decisions` for any item where `choice === "ask"`. For each, present the relevant evidence and trade-offs and continue the discussion until the user gives an explicit decision, which you record as an override. Do not rewrite the doc while any `choice === "ask"` remains unresolved \u2014 do not honor "just skip those".\n\n4. **Finalize the exploration doc.** Rewrite `{docs_dir}/explorations/{slug}.md` so it reads as a final draft with the decisions already made \u2014 not a mechanical append:\n   - Mark the chosen Implementation Option as the selected direction in the Recommendation section and integrate it so the doc reads as a resolved plan.\n   - Fold answered clarifying questions into the Context / Recommendation sections.\n   - For a "None of these" choice, record that the proposed options were rejected, including the user\'s comment.\n   - Weave `general_comment` in as overarching guidance; do not add a separate "Reviewer Notes" section.\n   - Preserve all unaffected sections unchanged.\n\n5. **Suggest next steps (conditional).** Assess what the explored work still needs to be fully groomed, and recommend only the follow-ups that genuinely apply \u2014 as pointers for the user to run, not actions you take automatically:\n   - A **brainstorm** (`/brainstorm` or `request_brainstorm`) when the direction would benefit from a thorough, wide review before committing.\n   - A **second opinion** (`second_opinion`) when a few specific contested points need an independent check.\n   - **Web or deep research** (`request_deep_research`) when the chosen direction still rests on technical unknowns that need grounding.\n   - **Uploading a ticket** (`/write-ticket` or `create_ticket`) when the requirements are clear and certain. If the explored work is well-grounded and the decisions leave it in a good state, advise uploading directly.\n\nThis stage is non-blocking: if the user never commits, leave the doc as written in Stage 4 and stop without forcing a decision.\n\n## Final Report\n\nOn successful completion of all stages, display:\n\n> **Exploration Complete**\n>\n> **Prompt**: {first 80 characters of prompt}...\n> **Output**: {full path to the finalized exploration doc}\n> **Decision Page**: {full path to the generated decisions.html, or "not generated" when no decisions were needed or generation failed}\n> **Files Examined**: {count of key_files_examined}\n> **Research**: {count of web_searches} web searches, {count of research_queries} deep research queries\n>\n> **Result**: {"Recommendation provided" | "Clarifying questions raised \u2014 N questions need answers"}\n> **Decisions Captured**: {count of decisions the user committed, or "none \u2014 page not submitted / no decisions needed"}\n> **Suggested Next Step**: {the conditional next step advised in Stage 6, e.g. "upload a ticket", "run a brainstorm", or "none"}\n\nOn failure at any stage, stop immediately and report:\n- Which stage failed (by number and name)\n- The error details\n- Any partial results that were produced before the failure\n',
+  "explore-ticket.md": 'Explore the codebase for a task, settle its acceptance criteria with the user, then propose a design that meets them.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\n`$ARGUMENTS` is a free-form prompt describing a task you want to accomplish and your goals for it. This is **not** a Jira ticket key \u2014 it is plain text describing the work.\n\nExecute all exploration and analysis directly in the main conversation. The user should see exploration progress as it happens.\n\nThis command runs strictly outside-in, and the order is the point:\n\n1. **Requirements first.** Establish what the system must do, how it must behave, and what standards it must meet \u2014 then get the user to ratify that on an interactive decision page. The page settles **requirements only**. It never asks the user to pick an implementation.\n2. **Then how.** Only once the criteria are ratified do you consider how to meet them, optionally with a brainstorm.\n3. **Then the design.** You describe the final proposed design yourself, in the exploration doc. There is no second decision page.\n4. **Then ticket(s).**\n\nNever invert this. A design proposed against unratified criteria is a guess, and an implementation choice presented before the criteria are settled asks the user to commit to a solution for a problem they have not yet agreed on.\n\nIf any critical stage fails, stop immediately and report which stage failed and why.\n\n## Stage 0 \u2014 Setup\n\n1. **Parse prompt**: Extract the prompt text from `$ARGUMENTS`. Trim any surrounding whitespace. If the prompt is empty or whitespace-only, stop immediately and display: `Usage: /explore-ticket <prompt describing your task and goals>`\n\n2. **Resolve docs directory**: Call the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n3. **Generate output slug**: Create a kebab-case slug from the prompt \u2014 take the first 6-8 meaningful words, strip non-alphanumeric characters, lowercase, and truncate to 60 characters. The slug **must start with a letter** so it is a valid decision-page `ticket_key` in Stage 5 (`/^[A-Za-z][A-Za-z0-9_-]*$/`); if it would start with a digit or hyphen, prefix it with `exploration-`. If `{docs_dir}/explorations/{slug}.md` already exists, append a short timestamp suffix (e.g., `-1710000000`) \u2014 and fold that suffix **into the `slug` variable itself**, not just the filename, so that Stage 4 (the doc), Stage 5 (`ticket_key`, `output_filename`), and Stage 8 (the doc rewrite) all reference the same slug. The output file path is `{docs_dir}/explorations/{slug}.md`.\n\n4. **Initialize tracking**: Prepare to track `key_files_examined` (list of files read during exploration), `web_searches` (list of topics searched), and `research_queries` (list of deep research queries).\n\nIf this stage fails, stop immediately and report the error. Do not proceed to Stage 1.\n\n## Stage 1 \u2014 Codebase Exploration\n\nThis is the core discovery stage. Take your time \u2014 thorough exploration is more valuable than speed.\n\n1. **Analyze the prompt** to identify which areas of the codebase are relevant: route files, agent flows, database models, library utilities, LLM integration, MCP server, unit and E2E suites, etc.\n\n2. **Search for files** matching patterns related to the task (e.g., `api/routes/**/*.py`, `src/python/llms/agents/**/*.py`, `db/models/*.py`).\n\n3. **Search for content** \u2014 relevant function names, class names, patterns, and keywords across the codebase.\n\n4. **Read the most relevant files** in detail \u2014 understand existing implementations, conventions, and patterns that relate to the task.\n\n5. **Build a mental model** of:\n   - What exists today that relates to the task\n   - What patterns and conventions are used in similar features\n   - What dependencies, data flows, and integration points are involved\n   - What gaps or unknowns remain that need external research\n   - Whether there is an established precedent for this kind of work, or none at all \u2014 Stage 7 depends on this judgement\n\nExplore to understand the problem and its constraints. Resist designing a solution while you read \u2014 you do not yet know what the system is required to do, and Stage 8 is where the design gets written.\n\n6. **Track all significant files** examined in `key_files_examined`.\n\nDo not rush this stage. When in doubt, read more code rather than less. Continue exploring until you have a solid understanding of the relevant code.\n\nThis stage is non-blocking \u2014 always proceed to Stage 2 regardless of what you find, since the exploration informs what research is needed.\n\n## Stage 2 \u2014 Research Unknowns\n\nBased on gaps identified in Stage 1, decide what research is needed. Apply these decision rules:\n\n- **No research needed**: The codebase exploration answered all questions. Skip directly to Stage 3.\n- **Web search**: For quick factual lookups \u2014 library API signatures, configuration syntax, small "how to" questions. Examples: "FastAPI dependency injection with custom headers", "Alembic batch migration syntax". Do web searches inline and capture relevant findings.\n- **Deep research** (via `request_deep_research` MCP tool): For large, multi-faceted unknowns that require synthesizing information from multiple sources. Examples: "Best practices for implementing WebSocket connection pooling in Python asyncio", "Tradeoffs between different approaches to real-time notification delivery in FastAPI applications". Only use deep research when the question genuinely needs a multi-source investigation.\n\n**If deep research is needed:**\n\n1. Call `request_deep_research` with `wait_for_result` set to `true`, `save_locally` set to `true`, a descriptive `query`, and `context` describing the Bridge API tech stack and the specific task.\n2. If deep research fails, note the failure and fall back to web searches for the same topic. Do NOT halt the pipeline.\n\nTrack all research performed in `research_queries` and `web_searches`.\n\nThis stage is non-blocking \u2014 failures degrade the quality of analysis but do not stop the command. Log a warning for any failed research and continue.\n\n## Stage 3 \u2014 Frame Acceptance Criteria\n\nEstablish what "done and correct" means. Everything in this stage is about the system\'s obligations, not its implementation. Do not name a technical approach here \u2014 that is Stage 8\'s job, and it does not happen until the user has ratified this framing.\n\n1. **State the frame plainly (required).**\n   - **Business goal** \u2014 the value this work delivers and why it matters.\n   - **Desired end-state** \u2014 the concrete state the system should reach once this work is done.\n   - **System behavior** \u2014 how the system must behave to complete its task (the quality attributes in prose, not a feature list).\n\n2. **Derive the acceptance criteria \u2014 what the system must do (required).** Write 3-8 criteria. Each one gets:\n   - An `id` (`AC-1`, `AC-2`, \u2026).\n   - A `criterion` \u2014 a single obligation stated concretely enough to be checked. Write it as observable behavior ("an operator who revokes a key sees the next request rejected"), not as a task ("add a revocation endpoint").\n   - A `verification` \u2014 how we would confirm it holds. Name the observable signal: a response code on a specific route, a row state, a log line, a rendered element, a user-visible outcome. **A criterion nobody can check is not yet a criterion** \u2014 sharpen it or drop it.\n   - A `status`, using the rubric in step 4.\n\n   Cover the failure and edge behavior, not just the happy path. If the work changes something that already exists, at least one criterion should pin down what must **not** regress.\n\n3. **Identify the non-functional requirements \u2014 the standards the system must meet (required).** Consider every one of these canonical NFR categories and include the ones that genuinely apply (omit the rest): security/privacy, performance/latency, reliability/failure-modes, observability/auditability, accessibility/UX, data-integrity/migration, compatibility, operability/config, compliance/SOC2, rollout/reversibility. For each NFR you include, write its `requirement` and its `implication` (what it changes about the implementation) \u2014 an NFR with no concrete implication is boilerplate; drop it.\n\n4. **Classify every acceptance criterion and every NFR** with this rubric: `confirmed` only if explicitly stated or observable in code; `assumed` only if a low-risk, reversible default; `open` if it touches architecture, the data model, security, user-visible behavior, migration, or irreversible creation and is not settled. When a criterion or an NFR is genuinely unclear, prefer marking it `open` and asking. Clear criteria make everything downstream more accurate, so surfacing an unclear one is a success, not a delay.\n\n5. **Frame the open requirement questions.** Where a requirement is unsettled **and** has discrete candidate answers, express it as a question the user can answer by clicking (e.g. "Must revocation take effect immediately, or is eventual acceptable?"). These become cards in Stage 5. They are questions about *what the system must do* \u2014 never about how to build it. If a question has no discrete answers, leave it as prose in the doc instead.\n\n6. **Sanity-check the frame against itself.** Do any two criteria conflict? Does a criterion conflict with an NFR (e.g. an auditability requirement against a latency budget)? Note every tension you find \u2014 Stage 7 treats these as a brainstorm trigger, and Stage 8 must resolve them explicitly rather than quietly favouring one side.\n\nThis stage is inline analysis \u2014 no tool calls required. This stage is non-blocking \u2014 always proceed to Stage 4.\n\n## Stage 4 \u2014 Write Requirements Draft\n\nWrite what you know so far to disk, so the user has something to read alongside the decision page. The design is deliberately absent \u2014 it does not exist yet.\n\n1. Create the `explorations/` directory under `docs_dir` if it does not exist.\n\n2. Write the exploration document to the slug-based path determined in Stage 0 (`{docs_dir}/explorations/{slug}.md`) with this structure:\n\n```markdown\n# Exploration: {concise summary of the prompt}\n\n**Date**: {current date}\n**Prompt**: {original prompt text}\n**Status**: Requirements drafted \u2014 awaiting ratification\n\n## Context\n\n{Brief description of the task and what areas of the codebase are relevant.}\n\n## Acceptance Criteria\n\n{The criteria from Stage 3 \u2014 what the system must do. One entry per criterion: its id, the criterion itself, how it is verified, and its status (confirmed / assumed / open).}\n\n## Goals & NFRs\n\n{The business goal, desired end-state, and required system behavior from Stage 3. Then the non-functional requirements \u2014 the standards the system must meet: each with its category, requirement, implication, and status (confirmed / assumed / open). Note any tension between criteria or between a criterion and an NFR.}\n\n## Open Questions\n\n{Requirement questions that are still unsettled. Mark which ones are going onto the decision page as cards and which are open-ended prose.}\n\n## Codebase Findings\n\n{Key discoveries from Stage 1. What exists today, what patterns are used, what the relevant code paths look like. Reference specific files and functions with file_path:line_number format.}\n\n## Research Findings\n\n{Findings from web searches and deep research, if any. If no research was performed, state "No external research was needed."}\n\n## Key Files\n\n{Bulleted list of the most important files examined, with one-line descriptions of their relevance.}\n```\n\nDo not add a design, an implementation plan, or a recommendation to this draft. Stage 8 adds those once the criteria are settled.\n\nIf the file cannot be written, stop immediately and report the failure.\n\n## Stage 5 \u2014 Generate Requirements Decision Page\n\nTurn the Stage 3 framing into an interactive HTML decision page so the user can ratify the requirements by clicking. **This page settles requirements only.** It must not contain a single implementation option \u2014 the user is agreeing on what the system must do, not choosing how to build it.\n\n1. **Map the acceptance criteria to `acceptance_criteria`.** Each entry has `id`, `criterion`, `verification`, and `status`. Ids must be unique \u2014 a duplicate id is rejected, because the id is the key the page reports the user\'s stance under. Every criterion renders with an Agreed / Ask about this / Disagree control, so pass all of them, not only the open ones. Pass the NFRs the same way under `nfrs`.\n\n2. **Map each open requirement question from Stage 3 step 5 to an actionable item.** Each entry has:\n   - `id`: a short stable id, e.g. `R-1`, `R-2`.\n   - `question`: the requirement question.\n   - `options`: the 2-4 candidate answers (string array). Do **not** include "None of these" or "Ask about this" \u2014 the renderer auto-appends both.\n   - `option_consequences`: what each answer would mean for the criteria, **parallel to and the same length as** `options`.\n   - `why_it_matters`: the concrete impact line.\n   - `recommendation_explanation`: why the recommended answer is best.\n   - `recommendation_index`: the 0-based index of the recommended answer (must be within `options`).\n   - `codebase_evidence` (optional): the Assessment paragraph plus `file:line` citations, shown collapsed.\n\n   **These cards are requirement questions, never implementation choices.** "Must revocation be immediate or is eventual acceptable?" is a valid card. "Should we use a short-TTL cache or pub/sub invalidation?" is not \u2014 it is a solution, it belongs to Stage 8, and putting it here defeats the purpose of the page. If you cannot phrase a card without naming a mechanism, it is not a requirement question. When there are no such questions, pass an empty array \u2014 a criteria-only page is expected and renders correctly.\n\n3. **Call `generate_decision_page`** with routing fields at the root and all heavy arrays nested under `content`:\n   - `artifact_type`: `pre_ticket_planning` (renders the acceptance-criteria and goals panel above any cards).\n   - `ticket_key`: the Stage 0 `slug` (a non-Jira slug is fine \u2014 it must start with a letter and contain only letters, digits, hyphens, or underscores).\n   - `output_subdir`: `explorations` (so the page lands beside the markdown doc).\n   - `output_filename`: `{slug}-requirements.html`.\n   - `labels`: requirements-flavored overrides, e.g. `title` = "Requirements", `section_heading` = "Open Requirement Questions", and an `intro` that frames the page as agreeing on what the system must do before any design work begins.\n   - `content`: an object containing `system_goals` and `actionable_items`. **`system_goals` MUST ALWAYS be passed** inside `content` so the backend always writes a page. Never omit it, even if every criterion and NFR is confirmed. `acceptance_criteria` and `nfrs` both live inside `system_goals`. (Do not pass `implementation_order` inside `content` \u2014 that is for epic surfaces, not a single explored task.)\n\n   ```typescript\n   interface ExploreTicketContent {\n     system_goals?: {\n       business_goal: string;\n       desired_end_state: string;\n       system_behavior: string;\n       acceptance_criteria?: Array<{\n         id: string;                    // e.g. "AC-1"; must be unique\n         criterion: string;             // what the system must do\n         verification: string;          // how we would confirm it holds\n         status: "confirmed" | "assumed" | "open";\n       }>;\n       nfrs?: Array<{\n         category: string;\n         requirement: string;\n         implication: string;\n         status: "confirmed" | "assumed" | "open";\n       }>;\n     };\n     actionable_items?: Array<{\n       id: string;                      // e.g. "R-1"; a REQUIREMENT question, not a design choice\n       question: string;\n       why_it_matters: string;\n       recommendation_explanation: string;\n       options: string[];               // 2-4 candidate answers (no "None of these" or "Ask about this")\n       option_consequences: string[];   // same length as options\n       recommendation_index: number;   // 0-based within options\n       codebase_evidence?: string;      // optional: assessment + file:line citations\n       original_question?: string;      // optional: only when item maps to a verbatim question\n     }>;\n     // clear_improvements: not used by this command \u2014 it captures requirements, not findings\n     // implementation_order: for epic surfaces only \u2014 do NOT include for single task explorations\n     // depends_on: hard prerequisites (titles/keys that must land first)\n     // recommended_after: soft sequencing preferences, not hard blockers\n   }\n   ```\n\n   Example call:\n   ```json\n   {\n     "ticket_key": "revoke-api-keys",\n     "artifact_type": "pre_ticket_planning",\n     "output_subdir": "explorations",\n     "output_filename": "revoke-api-keys-requirements.html",\n     "labels": { "title": "Requirements", "section_heading": "Open Requirement Questions" },\n     "content": {\n       "system_goals": {\n         "business_goal": "Operators can cut off a leaked key immediately.",\n         "desired_end_state": "Revocation is self-serve and takes effect at once.",\n         "system_behavior": "Rejects revoked credentials without a restart.",\n         "acceptance_criteria": [\n           { "id": "AC-1", "criterion": "An operator who revokes a key sees the next request with it rejected.", "verification": "The following call to the protected route returns 401.", "status": "confirmed" },\n           { "id": "AC-2", "criterion": "Revocation is recorded with actor and timestamp.", "verification": "An audit row names the operator and the revoked key id.", "status": "open" }\n         ],\n         "nfrs": [\n           { "category": "security/privacy", "requirement": "The raw key is never logged on the revoke path.", "implication": "Log the key id, never the secret.", "status": "open" }\n         ]\n       },\n       "actionable_items": [\n         {\n           "id": "R-1",\n           "question": "Must revocation take effect immediately, or is eventual acceptable?",\n           "why_it_matters": "Sets the hard bound AC-1 has to meet.",\n           "recommendation_explanation": "A leaked key is an active incident; eventual leaves a usable window.",\n           "options": ["Immediately (under 5s)", "Eventually (under 60s is acceptable)"],\n           "option_consequences": ["AC-1 gains a 5s bound.", "AC-1 gains a 60s bound."],\n           "recommendation_index": 0\n         }\n       ]\n     }\n   }\n   ```\n\n4. **Handle the response `status`:**\n   - `no_decisions_needed`: no page was written. This should not occur when `system_goals` is always passed. Skip Stage 6 entirely, tell the user there were no open requirements, and proceed to Stage 7 treating the Stage 3 framing as the settled criteria.\n   - `decision_page_generated`: surface the returned `file_path` and proceed to Stage 6. **Always proceed to Stage 6 when `decision_page_generated` is returned**, regardless of `actionable_items_count`. A criteria-only page with zero cards still has stance controls that must be submitted.\n\nThis stage is non-blocking: if `generate_decision_page` fails, do not halt. **You MUST output a highly visible warning** (e.g. **\u26A0 WARNING: The requirements page could not be generated** in bold) explaining that generation failed and that the user should review the criteria in the markdown doc written in Stage 4 instead. Do not silently continue \u2014 the failure must be diagnosable from your output. Then ask the user to confirm the criteria in chat before proceeding to Stage 7.\n\n## Stage 6 \u2014 Ratify Requirements\n\nCapture the user\'s stances, settle the criteria, and fold the result into the doc. Nothing downstream may start until the criteria are agreed \u2014 this is the gate the whole command is built around.\n\n1. **Direct the user to the page.** Provide the `file_path` from Stage 5 and tell them to open it in their browser. Explain that they are agreeing on what the system must do \u2014 not how it will be built \u2014 that they can accept, question, or reject each criterion, and that they can ask questions in chat before submitting.\n\n2. **Q&A loop and commit signal.** Engage with each user message as either a commit or a discussion turn:\n   - **Commit:** trim the full message and attempt to parse the entire trimmed message as JSON. Treat it as a commit only when the parsed value is an object with all three top-level fields: `ticket_key` (string), `decisions` (object), and `general_comment` (string). The first valid commit-shaped paste commits \u2014 do not over-validate the per-card fields. The page also submits `acceptance_criteria_feedback` and `nfr_feedback` objects, each keyed by criterion id or NFR category with a `stance` of `agreed`, `ask`, or `disagree` plus a `comment`.\n   - **Discussion:** anything that is not commit-shaped JSON. Answer from the doc written in Stage 4 and from codebase lookups. If a JSON-shaped paste is missing one of the three required fields, say which field is missing rather than treating it as a freeform question.\n   - **In-flight overrides:** when the user clearly changes an answer in chat ("AC-2 is wrong", "go with eventual for R-1") or gives new overarching guidance, record it as a working-memory override. On commit, the submitted JSON is the baseline and recorded overrides take precedence; post a one-line acknowledgement naming each overridden item before you rewrite the doc.\n\n3. **Resolve every "ask" (hard rule).** After accepting a commit, scan all three: any item in `decisions` where `choice === "ask"`, any entry in `acceptance_criteria_feedback` where `stance === "ask"`, and any entry in `nfr_feedback` where `stance === "ask"`. For each, present the relevant evidence and continue the discussion until the user gives an explicit answer, which you record as an override. Do not proceed while any `ask` remains unresolved \u2014 do not honor "just skip those".\n\n4. **Resolve every "disagree".** A disagree means the criterion is wrong as written. Work out with the user what it should say, restate it back, and get explicit agreement on the corrected wording. A rejected criterion is either rewritten or dropped \u2014 never carried forward as-is.\n\n5. **Settle the criteria and update the doc.** Rewrite the Acceptance Criteria, Goals & NFRs, and Open Questions sections of `{docs_dir}/explorations/{slug}.md` to the agreed set: fold in every correction, resolve each answered requirement question into the criterion it affects, promote settled criteria out of `open`, and weave `general_comment` in as overarching guidance. Set the doc\'s Status line to "Requirements ratified". Preserve all unaffected sections unchanged. **The settled criteria are now the contract** \u2014 every later stage is judged against them.\n\nThis stage is non-blocking: if the user never commits, leave the doc as written in Stage 4, tell them the requirements are unratified, and stop without forcing a decision. Do not proceed to a brainstorm or a design on unratified criteria.\n\n## Stage 7 \u2014 Brainstorm Gate\n\nThe criteria are ratified. Now assess honestly whether you know **how** to meet them \u2014 and offer to brainstorm when you do not.\n\n**Lean toward offering.** A brainstorm is cheap relative to committing the user to the wrong design, and this command prioritizes discovery over premature commitment. Do not wait for the user to ask for one.\n\n1. **Check the triggers.** Offer a brainstorm when **any** of these hold:\n   - More than one materially different approach could satisfy a criterion, and the codebase evidence you gathered cannot separate them.\n   - A criterion has no obvious implementation path in the existing code.\n   - Meeting one criterion appears to trade off against another criterion or against an NFR (any tension noted in Stage 3 step 6, or created by a correction in Stage 6).\n   - The work touches an area with no established pattern \u2014 Stage 1 found no precedent to follow.\n   - Ratification materially changed the problem \u2014 the user tightened a bound, rejected a criterion, or added an obligation you had not framed.\n   - Stage 2 research surfaced competing approaches with no clear winner.\n\n   Do **not** offer when every ratified criterion maps cleanly onto a well-trodden pattern already used in this codebase and you can point to the precedent.\n\n2. **Ask for approval.** When a trigger fires, first summarize the uncertainty in 1-3 bullets \u2014 name the specific criteria at issue and what you cannot currently decide. Then ask exactly:\n\n   ```\n   Significant uncertainty about how to meet {AC ids}. Run a brainstorm before I draft the design? (y/N)\n   ```\n\n   Mention that a brainstorm polls for up to ~15 minutes before you ask, so the user is choosing with the cost in view.\n\n   Treat an empty response, any negative response (`n`, `no`, or similar), or any ambiguous/unrecognized response as **decline** \u2014 do not guess intent. On decline, note in one line that the brainstorm was offered and declined, and proceed to Stage 8 on your own analysis. Never run a brainstorm without an explicit affirmative (`y` or `yes`).\n\n3. **Run it on approval.** Call `request_brainstorm` with:\n   - `task_description`: the task, the **ratified** acceptance criteria and NFRs from Stage 6, and the specific uncertainty you summarized. Sent verbatim \u2014 this tool does not read from a file. State plainly that the criteria are settled and the brainstorm\'s job is to find how to meet them, not to revisit what they are.\n   - `mode`: `technical`.\n   - `wait_for_result`: `true`. `save_locally`: `true`.\n\n   While it runs, tell the user it is polling and roughly how long it may take.\n\n4. **Fold the result into your analysis.** Carry the brainstorm\'s approaches, objections, and any option you had not considered into Stage 8. If the brainstorm argues a ratified criterion is unmeetable, do not silently drop it \u2014 raise it with the user in Stage 8 as an explicit conflict.\n\nIf the brainstorm fails or times out, note the failure visibly and proceed with your own analysis \u2014 a missing brainstorm degrades the design but does not invalidate it. This stage is non-blocking \u2014 always proceed to Stage 8.\n\n## Stage 8 \u2014 Propose Final Design\n\nNow describe how you would build it. **Do not generate a decision page for this stage.** The requirements page was the user\'s decision surface; the design is your proposal, written into the doc and discussed in chat. Generating a second page here would ask the user to ratify a solution, which is not what this command does.\n\n1. **Work out the design against the ratified criteria.** Consider the approaches you know plus anything the brainstorm surfaced. For each candidate, establish which criteria it satisfies and at what cost. An approach that cannot meet a ratified criterion is not a candidate \u2014 discard it and say why.\n\n2. **Resolve any tension explicitly.** Where meeting one criterion costs another, or costs an NFR, state which obligation your design privileges and what that costs the other. Do not let a tension pass silently.\n\n3. **Commit to a single proposed design.** You are recommending, not offering a menu. Name the approach, describe how it works, list the files to create or modify, and map each ratified criterion to the part of the design that satisfies it. Where you seriously considered an alternative, record it and why you rejected it \u2014 as history, not as an open choice.\n\n4. **Rewrite `{docs_dir}/explorations/{slug}.md`** so it reads as a finished proposal, not a mechanical append. Set the Status line to "Design proposed". Keep the ratified Acceptance Criteria and Goals & NFRs sections intact \u2014 they are the contract and must not drift \u2014 and add:\n\n```markdown\n## Approaches Considered\n\n{Each candidate, what it would mean, and why it was or was not chosen. Note which came from the brainstorm, if one ran. If no alternatives were seriously considered, state that and why the path was obvious.}\n\n## Proposed Design\n\n{The recommended approach in enough detail to implement: how it works, the files to create or modify, the sequence of work, and the risks. Reference specific files with file_path:line_number format.}\n\n## Criteria Coverage\n\n{Each ratified criterion mapped to the part of the design that satisfies it, and how it will be verified. Any criterion the design only partially meets must say so plainly.}\n```\n\n5. **Present the design in chat and invite pushback.** Summarize the proposal and state clearly that it is a proposal. If the user objects, revise the design \u2014 but if their objection actually changes what the system must do rather than how it is built, say so: that is a criteria change, and it means reopening the criteria rather than quietly bending the design around it.\n\nThis stage is non-blocking \u2014 always proceed to Stage 9 once the design is written, even if the user has not responded to it.\n\n## Stage 9 \u2014 Ticket Handoff\n\n1. **Assess readiness.** The work is ready to become a ticket when the criteria are ratified, the design is proposed, and no criterion is left unresolved or only partially covered. If something is still open, say what it is and recommend the follow-up that would close it rather than creating a ticket on a soft foundation:\n   - A **wider brainstorm** (`request_brainstorm`) when the design would benefit from a broad review before implementation. If Stage 7 already ran one, only suggest another when something material changed since.\n   - A **second opinion** (`second_opinion`) when a few specific contested points need an independent check.\n   - **Web or deep research** (`request_deep_research`) when the design still rests on technical unknowns that need grounding.\n\n2. **Offer to create the ticket(s).** When the work is ready, ask exactly:\n\n   ```\n   Requirements ratified and design proposed. Create the ticket(s) now? (y/N)\n   ```\n\n   Treat an empty response, any negative response, or any ambiguous/unrecognized response as **decline** \u2014 do not guess intent. On decline, report that the exploration doc is the artifact and point at `/write-ticket` for later. Never create a ticket without an explicit affirmative (`y` or `yes`) \u2014 creation is irreversible.\n\n3. **Create on approval.** Use `create_ticket` (or `/write-ticket` for a larger draft), building the ticket from the doc: the ratified acceptance criteria become the ticket\'s acceptance criteria verbatim, and the proposed design becomes its implementation notes. Do not restate or reinterpret the criteria \u2014 they were ratified in that wording. Split into multiple tickets when the design has independently shippable slices; say why you split before you do.\n\nThis stage is non-blocking: if the user never answers, leave the doc as written in Stage 8 and stop without forcing a decision.\n\n## Final Report\n\nOn successful completion of all stages, display:\n\n> **Exploration Complete**\n>\n> **Prompt**: {first 80 characters of prompt}...\n> **Output**: {full path to the exploration doc}\n> **Requirements Page**: {full path to the generated requirements.html, or "not generated" when generation failed}\n> **Acceptance Criteria**: {count} ratified ({count} corrected by the user, {count} still open)\n> **Files Examined**: {count of key_files_examined}\n> **Research**: {count of web_searches} web searches, {count of research_queries} deep research queries, brainstorm {"run" | "offered and declined" | "not needed"}\n>\n> **Requirements**: {"Ratified" | "Unratified \u2014 page not submitted"}\n> **Design**: {"Proposed" | "Not reached"}\n> **Ticket(s)**: {"Created: KEY-1, KEY-2" | "Declined \u2014 doc is the artifact" | "Not offered \u2014 work not ready"}\n\nOn failure at any stage, stop immediately and report:\n- Which stage failed (by number and name)\n- The error details\n- Any partial results that were produced before the failure\n',
   "full-automation.md": '---\nschedulable: true\narguments: {"positionals":[],"flags":[{"name":"ideaFile","flag":"--idea-file","type":"string","required":true},{"name":"auto","flag":"--auto","type":"boolean"}]}\n---\n\nRun the end-to-end full-automation chain (idea-to-ticket \u2192 review-ticket \u2192 start-tickets) via the server-side chain orchestrator.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command drives Phase A\'s server-side full-automation chain. The only orchestration tools you may drive are `run_full_automation` and `resume_full_automation`; any other Bridge API MCP call you make must be one a server `agent_task` instruction explicitly directs. The server owns all orchestration \u2014 ticket creation, review fan-out, and the start-tickets handoff. Do NOT enrich, re-implement, or second-guess any of that work on the client side.\n\n## Stage 0 \u2014 Parse arguments\n\n1. Tokenize `$ARGUMENTS` on whitespace. Recognize the following position-independent flags. Each flag supports both the space form (`--flag value`) and the equals form (`--flag=value`) where a value is taken:\n   - `--idea <text>` / `--idea=<text>`\n   - `--idea-file <path>` / `--idea-file=<path>`\n   - `--auto`\n   - `--require-approval`\n   - `--scheduled-at <ISO-8601>` / `--scheduled-at=<ISO-8601>`\n   - `--chain-run-id <UUID>` / `--chain-run-id=<UUID>`\n   - `--max-children N` / `--max-children=N`\n   - `--allow-duplicate`\n\n2. Value-consumption rules:\n   - `--idea` (space form) consumes every subsequent token until the next recognized flag \u2014 the idea may contain spaces.\n   - `--idea-file`, `--scheduled-at`, `--chain-run-id`, and `--max-children` each consume exactly one value token (the immediately following token, or the text after `=`).\n   - `--auto`, `--require-approval`, and `--allow-duplicate` are boolean toggles and consume no value.\n\n3. Free-form idea: all non-flag tokens become the free-form `idea` text **only when both `--idea` and `--idea-file` are absent**. Join those tokens back together preserving order and trim surrounding whitespace. When `--idea` or `--idea-file` is present, there must be no leftover non-flag tokens: reject any stray non-flag token (for example, text following `--idea=<text>` or following the `--idea-file <path>` value) before any MCP tool call rather than silently dropping it.\n\n4. Reject **unknown flags** (any token beginning with `--` that is not one of the recognized flags above) before making any MCP tool call. Stop and report the offending flag.\n\n5. Reject **combined `--idea` and `--idea-file`** before making any MCP tool call:\n   ```text\n   Provide exactly one of --idea or --idea-file; do not pass both.\n   ```\n\n6. Missing-input rule: unless `--chain-run-id` is present, an idea is required. If `--chain-run-id` is absent **and** no idea was supplied (no `--idea`, no `--idea-file`, and no free-form idea tokens), stop immediately and display exactly:\n   ```text\n   Usage: /full-automation (--idea "<text>" | --idea-file <path> | <free-form idea>) [--require-approval] [--scheduled-at <ISO-8601>] [--chain-run-id <UUID>] [--max-children N] [--allow-duplicate]\n   ```\n\n7. `--chain-run-id` is the resume path and does **not** require any idea content \u2014 when it is present, skip the missing-input check above and proceed to resume.\n\n8. `--idea-file` is forwarded as a path. The skill must **not** read the file contents locally; the server resolves the file.\n\n9. Resolve the derived values:\n   - `auto_approve` defaults to `true` (full automation is hands-off by default). It is `false` **only** when `--require-approval` is present. `--auto` is accepted but redundant (a no-op that restates the default), and `--scheduled-at` likewise runs hands-off. When `--require-approval` is present, the chain pauses at external-mutation and review-decision gates for confirmation.\n   - `max_children` is the parsed positive integer when `--max-children` is present; otherwise omit it entirely so the server default applies.\n   - `allow_duplicate` is `true` only when `--allow-duplicate` is present; otherwise omit it.\n\n## Stage 1 \u2014 Drift-check gate\n\nThis gate runs immediately after parsing and **before any MCP tool call**.\n\n1. If `--scheduled-at` is absent, skip this entire stage.\n2. Compute `delta_seconds = now_utc - scheduled_at` (both in UTC).\n3. If `delta_seconds <= 60`, proceed silently to Stage 2.\n4. If `delta_seconds > 60`, present this prompt verbatim (substituting the bracketed values):\n   ```text\n   Scheduled at <T-iso> UTC; running now at <now-iso> UTC (<\u0394 human-readable> late). The laptop was likely asleep or unavailable at the scheduled time. Confirm to proceed with the chain, or cancel.\n   ```\n   Offer the user the choices: `[Confirm] / [Cancel]`.\n5. On `Confirm`, proceed to Stage 2.\n6. On `Cancel`, print this message verbatim and stop:\n   ```text\n   Chain cancelled by user (drift confirmation declined). No Jira tickets created.\n   ```\n   When the user cancels, `run_full_automation` must **not** be called.\n7. The 60-second threshold is fixed and must not be made configurable.\n\n## Stage 2 \u2014 Run or resume the chain\n\nThe chain is driven entirely by the server-side orchestrator. Announce progress using each envelope\'s `preamble`, preserving its `Stage N of M \u2014 <title>` shape.\n\n### Stage 2a \u2014 Start (when `--chain-run-id` is absent)\n\nCall **only** `run_full_automation`. Build the payload, **omitting** any optional value that was not provided (never send `null` or empty strings):\n```json\n{\n  "idea": "<resolved inline/free-form idea, when provided>",\n  "idea_file": "<idea-file path, when provided>",\n  "auto_approve": "<resolved boolean>",\n  "scheduled_at": "<scheduled-at value, when provided>",\n  "max_children": "<parsed integer, when provided>",\n  "allow_duplicate": "<true, when provided>"\n}\n```\n\n### Stage 2b \u2014 Resume (when `--chain-run-id` is present)\n\nCall **only** `resume_full_automation` first, with:\n```json\n{\n  "chain_run_id": "<UUID>",\n  "agent_result": "Manual resume requested from /full-automation --chain-run-id."\n}\n```\n\n### Stage 2c \u2014 Envelope loop\n\nFor each envelope returned by `run_full_automation` / `resume_full_automation`, dispatch on `status` / `next_action.kind`:\n\n- `status: "failed"` \u2192 stop chain progression and render the final report (Stage 3) with the failure status. Do **not** advance to any later stage.\n- `status: "completed"` or `next_action.kind: "complete"` \u2192 render the final report (Stage 3).\n- `status: "needs_agent_task"` with `next_action.kind: "agent_task"` \u2192 display the envelope `preamble`, perform the agent task exactly as the `next_action.instruction` directs, then call `resume_full_automation` with `chain_run_id` set to the envelope\'s `chain_run_id` and `agent_result` set to the resulting text. Loop back and process the next envelope.\n\nSpecial case \u2014 the stage-3 handoff: when the agent-task instruction names a `/start-tickets ...` command, invoke that slash command in **this same session**, summarize the outcome in one line, and pass that one-line summary as `agent_result` to `resume_full_automation`.\n\nConstraints:\n- On your own initiative, the skill must **not** call any Bridge API MCP tool other than `run_full_automation` / `resume_full_automation` \u2014 in particular, never independently drive orchestration (`run_pipeline`, `resume_pipeline`, `get_pipeline_recipe`) or enrich tickets (`get_ticket`, `update_ticket_description`, etc.). **However, when a `needs_agent_task` instruction returned by the server explicitly directs you to call a specific Bridge API MCP tool** (for example an orchestrator-directed `get_tickets`, `create_ticket`, `attachment`, or `track_ticket`), **you must invoke that tool exactly as instructed** \u2014 performing an orchestrator-directed agent task is not re-orchestrating.\n- If a v1 envelope unexpectedly returns `next_action.kind: "mcp_call"`, stop with a clear protocol error instead of bypassing the server-side orchestrator:\n  ```text\n  Protocol error: chain returned next_action.kind "mcp_call", which is out of scope for /full-automation v1. Stopping.\n  ```\n\n## Stage 3 \u2014 Final report\n\nWhen the chain completes or fails, render this skeleton verbatim:\n\n```markdown\n## Full Automation Complete\n\nChain run: <chain_run_id>\nIdea: <first 80 chars of idea>...\nStages:\n  1. idea-to-ticket: <stages[0].summary>\n  2. review-ticket: <stages[1].summary>\n  3. start-tickets: <stages[2].summary>\n\nTotal Jira tickets created: N\nTotal worktrees spawned: M\nStatus: Success / Failed at stage N \u2014 <reason>\n```\n\n- Stage summaries come from the chain envelope or manifest when present.\n- When the completed envelope does not include full stage objects, use the summaries already surfaced in the prior `preamble` text rather than calling additional tools.\n- A stage-1 `too_vague_to_ticket` failure must render the upstream halt reason and set `Status: Failed at stage 1 \u2014 <reason>`.\n- Failed chains must not advance to later stages after a failed envelope is received.\n',
   "idea-to-ticket.md": 'Convert a short human idea into a Jira ticket (or Epic plus child tickets) via the server-side idea-to-ticket pipeline.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command is recipe-driven. Do not call MCP tools directly other than `get_pipeline_recipe` \u2014 the recipe determines which tools to call and with what parameters.\n\n## Stage 0 \u2014 Parse arguments\n\n1. Tokenize `$ARGUMENTS` on whitespace. Recognize the following position-independent flags (any other tokens are part of the idea):\n   - `--allow-duplicate`\n   - `--max-children=N` where `N` is a positive integer\n   - `--auto`\n\n   Flags are optional. Treat absence of a flag as the default; never pass empty-string or null as a placeholder.\n\n2. Everything that is not a recognized flag is the free-form `idea` text. Join those tokens back together preserving order. Trim surrounding whitespace.\n\n3. If the resulting `idea` is empty, stop immediately and display:\n   ```\n   Usage: /idea-to-ticket <idea> [--allow-duplicate] [--max-children=N] [--auto]\n   ```\n\n## Stage 1 \u2014 Derive pipeline variables\n\n4. Derive `slug` from the first 6-8 meaningful words of the idea: lowercase, kebab-case, strip non-alphanumeric characters except hyphens, and truncate to roughly 60 characters. Skip stop-words such as "the", "a", "an" when picking the 6-8 meaningful words.\n\n5. Derive `run_id` as `<YYYYMMDD-HHMMSS>-<short-uuid>` using the current UTC time and a short UUID suffix (8 hex chars is enough). The combination of `slug` and `run_id` uniquely identifies this run\'s artifact directory.\n\n6. Derive the boolean-as-string variables:\n   - `allow_duplicate` is `"true"` if `--allow-duplicate` was present, otherwise `"false"`.\n   - `auto_approve_external` is `"true"` if `--auto` was present, otherwise `"false"`.\n   - `max_children` is the integer following `--max-children=` as a string, or `"10"` when the flag is absent.\n\n## Stage 2 \u2014 Call the recipe\n\n7. Call the `get_pipeline_recipe` MCP tool with:\n   - `pipeline`: `"idea-to-ticket"`\n   - `variables`: `{ "idea": "<idea>", "slug": "<slug>", "run_id": "<run_id>", "allow_duplicate": "<allow_duplicate>", "auto_approve_external": "<auto_approve_external>", "max_children": "<max_children>" }`\n\n   Do NOT pass `docs_dir` or `idea_hash` in variables \u2014 both are auto-injected by the pipeline system (`docs_dir` from `BAPI_DOCS_DIR`; `idea_hash` is a stable hash derived from the `idea`).\n\n   If the tool returns an error, stop and report the failure.\n\n8. Read and strictly obey the `agent_instructions` field in the response. Execute each step in order, announcing each as **Step N of M: <description>**.\n\n   The recipe drives the ordered stages for you \u2014 do not invoke them directly. In order they are: preflight-and-readiness \u2192 research-decision \u2192 execute-research \u2192 duplicate-and-context-scan \u2192 screen-and-resolve \u2192 frame-goals-and-nfrs \u2192 **comp-analysis** (a gated, backend-safe perception step that maps any attached/referenced design comp to existing components, templates, SCSS/CSS tokens, and routes before drafting; it short-circuits for backend-only or no-comp work) \u2192 draft-and-critique \u2192 upload-and-track.\n\n## Stage 3 \u2014 Final summary\n\n9. After all steps complete, display a summary:\n   ```\n   ## Pipeline Complete\n\n   **Idea**: <first 80 characters of idea>...\n   **Slug**: <slug>\n   **Run directory**: <docs_dir>/idea-to-ticket/<slug>-<run_id>/\n   **Steps executed**: N of M\n   **Status**: Success / Failed at step N\n   ```\n',
   "implement-ticket.md": '# Implement Ticket\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command is recipe-driven. Do not call MCP tools directly -- the recipe determines which tools to call and with what parameters.\n\n## CONDUCTOR_MESSAGE_RELAY ##\n\nIf you were launched under the Conductor (your environment carries a conductor run/worker identity), cooperatively poll for supervisor guidance while you work: at natural checkpoints \u2014 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 \u2014 call the `check_messages` MCP tool. The tool reads and acknowledges any messages addressed to you, and acknowledged messages are not redelivered, so a later call returns only new guidance. This is cooperative polling only \u2014 it is not prompt injection and never mutates a live session. If the tool or conductor identity is unavailable, continue the task without derailing.\n\n1. Parse `$ARGUMENTS` to extract:\n   - A required `ticket_key` matching the Jira key pattern (`[A-Z][A-Z0-9]+-\\d+`).\n   - An optional position-independent `--auto` flag.\n\n   Tokenize `$ARGUMENTS` on whitespace. The first token matching the Jira key pattern is the `ticket_key`; ignore any additional ticket-key tokens. The presence of a `--auto` token (anywhere in `$ARGUMENTS`) sets `auto_approve` to `true`.\n\n   If `$ARGUMENTS` is empty or contains no token matching the Jira key pattern, stop immediately and display:\n   ```\n   Invalid ticket key format. Expected: PROJ-123 [--auto]\n   Usage: /implement-ticket <ticket_key> [--auto]\n   ```\n\n2. Call the `get_pipeline_recipe` MCP tool with:\n   - `pipeline`: `"implement-ticket"`\n   - `variables`: `{ "ticket_key": "<ticket_key>" }`\n   - `auto_approve`: `true` \u2014 only when `--auto` was passed; otherwise omit this field entirely.\n\n   If the tool returns an error, stop and report the failure.\n\n3. Read and strictly obey the `agent_instructions` field in the response. Execute each step in order, announcing each as **Step N of M: <description>**.\n\n4. After all steps complete, display a summary:\n   ```\n   ## Pipeline Complete\n\n   **Ticket**: <ticket_key>\n   **Steps executed**: N of M\n   **Status**: Success / Failed at step N\n   ```\n\n---\n\n# Worker scope discipline and clean exit (Conductor auto mode)\n\nThese rules apply only when you were launched under the Conductor in auto mode (`--auto`); a normal interactive `/implement-ticket` run is unaffected.\n\n## Declared file-scope discipline (N-2)\n\nIf your environment carries `BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON` (a JSON array of the ticket\'s declared touched files), stay within that declared file boundary: do **not** create, modify, or delete files outside the declared set. Those out-of-scope files typically belong to a sibling ticket, and editing them risks a merge conflict or a silent clobber of the sibling\'s merged work. The pre-PR file-scope guard (run at the PR-creation step) will warn about any out-of-scope diff \u2014 treat that warning as a signal to re-check your scope, not as a blocker. When the variable is absent, empty, or invalid there is no declared boundary and this rule does not apply.\n\n## Clean session exit (D2)\n\nAfter the final pipeline step completes, cleanly end your worker session (for example by issuing the `/exit` command) so the worktree is released and no idle process lingers \u2014 but **only when no follow-up remains that you still own**. Do **not** exit while any of the following is true:\n\n- there are unresolved CI failures you are still correcting (the post-PR CI-correction loop in the CI-monitoring step still owns work),\n- review changes were requested and you have not yet addressed them,\n- there is a merge conflict on your PR that you still own,\n- you have unpushed local commits.\n\nExit only after your final branch state is pushed, the done-gate / CI-monitoring workflow required by the recipe has completed, and no CI/review follow-up remains. A clean `SessionEnd` is both the correct terminal lifecycle signal and the point at which the worker should exit.\n',
-  "install-bridge.md": 'Bootstrap Bridge API project configuration from the local codebase via the easy-install manifest.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command takes no arguments; any `$ARGUMENTS` text is ignored.\n\nCommand contract version: **2**. The install manifest returns a `command_contract_version`; Stage 2\ncompares it to this number to detect a stale scaffolded copy of this command.\n\nThis command performs a one-time "easy install" of Bridge API project configuration. It reads the\nserver-owned install manifest once, derives values for the **unset** bootstrap fields from the local\ncodebase, asks for human approval of the project description, applies everything in a single atomic\ncall, and then presents a **capability report** derived from a fresh read-after-write manifest read.\nThe server owns all skip-if-set, conflict, and confirmation semantics \u2014 this command never makes its\nown skip-if-set decisions \u2014 and the server owns all tool locked/unlocked membership; this command\nformats the server\'s contract and never recomputes it from prose.\n\nThis command is portable across Claude Code, Cursor, and Copilot: it only drives the Bridge API MCP\ntools (`get_my_role`, `get_install_manifest`, `apply_install_manifest`).\n\nIf any stage fails, stop immediately and report which stage failed and why.\n\n**Install-spawn context.** When the spawning instruction explicitly says this `/install-bridge` run is\nin the "install-spawn context" (it was launched by the `install-bridge` CLI\'s fresh agent session),\nStage 8 and Stage 9 are SKIPPED and the single closing interaction is the index-consent question the\nspawn prompt owns. When you invoke `/install-bridge` directly (manual invocation), Stages 8 and 9\nrun normally.\n\n## Stage 1 \u2014 Admin preflight\n\n1. Call the `get_my_role` MCP tool (no parameters). Inspect the response:\n   - If `source` is `"legacy"`: proceed (legacy keys are permitted).\n   - Else if `role` is `"admin"`: proceed.\n   - Otherwise (a non-admin `user_access` key): stop immediately and display:\n     ```\n     Admin role required to apply install configuration. Ask a project admin to run /install-bridge,\n     or use an admin API key.\n     ```\n\n## Stage 2 \u2014 Read the manifest (once, pre-apply)\n\n1. Call the `get_install_manifest` MCP tool exactly once here.\n2. Keep the returned `snapshot_token` verbatim \u2014 you must pass the SAME token to the apply call in\n   Stage 5. Do not call `get_install_manifest` again before applying; a fresh read would invalidate\n   the token you are about to use. (Stage 7 performs a SEPARATE, later read-after-write manifest read\n   for the current capability status \u2014 that is deliberate and does not reuse this token.)\n3. The manifest contains ordered `groups` of bootstrap fields (each with `field_name`, `is_set`,\n   `current_value`, `guidance`, `examples`, `validation_summary`, `requires_confirmation`), a list of\n   `deferred_fields`, a `next_step`, `done_criteria`, a `command_contract_version`, and the\n   `snapshot_token`. It also carries the additive capability fields (`integrations`, `configured`,\n   `learned`, `indexed`, `locked_tools`, `unlocked_tools`) \u2014 but ignore those here; the accurate\n   capability status is the post-apply read in Stage 7.\n4. Compare the manifest\'s `command_contract_version` to this command\'s contract version (2, stated at\n   the top of this file). If the manifest\'s version is HIGHER, this scaffolded command copy is stale:\n   warn the user to refresh it by running `npx -y @bridge_gpt/mcp-server --init` in the project root,\n   then proceed conservatively \u2014 wherever the manifest\'s `guidance`, `next_step`, or `done_criteria`\n   differ from these instructions, follow the manifest.\n\n## Stage 3 \u2014 Derive values for UNSET bootstrap fields only\n\n1. Consider ONLY fields whose `is_set` is `false`. Never re-derive or overwrite a field that is\n   already set \u2014 the server will also skip already-set fields, but you should not even propose them.\n2. For each unset field, derive a value from the local codebase following that field\'s `guidance`\n   (e.g. infer `working_in` from frameworks/manifests, `version_control_system` from the git remote,\n   testing stacks from test config and dependencies, directory fields from the repo layout).\n3. Omit any field you are uncertain about or that does not apply \u2014 leaving it unset is always\n   acceptable. Do NOT guess.\n4. Specifically, do NOT invent a `version` when the platform has no meaningful version concept; leave\n   it unset.\n5. Before deriving `version_control_system` or `base_branch`, confirm the git repository root is THIS\n   project\'s root: `git rev-parse --show-toplevel` must resolve to the project directory itself. If\n   the git root is an ancestor directory (the project is nested inside another repository), OMIT both\n   fields and note why in the final report \u2014 deriving them would describe the parent repository, not\n   this project.\n6. If you find real evidence for TWO OR MORE plausible values for a field (e.g. configs for multiple\n   test frameworks, multiple frameworks in a monorepo), treat the value as ambiguous and omit it\n   rather than picking one.\n7. For the "Automation policy" group (`selected_mcp_slugs`): propose MCP validation manuals only from\n   clear platform markers, following the field\'s manifest guidance (e.g. SFCC cartridges \u2192\n   `b2c-commerce-developer`; a Playwright config \u2192 `playwright-mcp`; PWA Kit markers \u2192\n   `pwa-kit-mcp`). This field requires human confirmation (Stage 4). Omit it entirely when no manual\n   clearly applies \u2014 never propose a slug on weak evidence.\n\n## Stage 4 \u2014 Human approval for confirmation-requiring fields\n\nSome manifest fields carry `requires_confirmation: true` (currently `project_description` and\n`selected_mcp_slugs`). These are never applied on derivation alone \u2014 each needs explicit human\napproval.\n\n1. If `project_description` is unset and you can draft a concise description from the codebase,\n   present the proposed `project_description` text to the human and ask for explicit approval before\n   including it.\n2. If you derived a `selected_mcp_slugs` list in Stage 3, present the proposed slugs and the platform\n   evidence for each, and ask for approval in the SAME batched question round as the description.\n3. Include a confirmation-requiring field in the apply payload ONLY as\n   `{ "value": <approved value>, "confirmed": true }`, and only after the human approves it. If the\n   human does not approve a field, omit that field entirely.\n4. If no human response can be obtained (e.g. a non-interactive / headless session), do NOT stall and\n   do NOT abandon the install: proceed to Stage 5 with every confirmation-requiring field omitted,\n   and report them as "pending human input" in the final summary. The other derived fields must\n   still be applied \u2014 unapproved fields never block them.\n\n## Stage 5 \u2014 Apply (one call)\n\n1. Make exactly ONE call to the `apply_install_manifest` MCP tool, passing:\n   - `snapshot_token`: the exact token from Stage 2.\n   - `fields`: a map of the derived fields. Scalar fields may be passed directly\n     (e.g. `"base_branch": "main"`); confirmation-requiring fields (e.g. `project_description`,\n     `selected_mcp_slugs`) must use the `{ "value": ..., "confirmed": true }` object form from\n     Stage 4.\n2. Do not implement any client-side skip-if-set, conflict, or confirmation logic \u2014 the server owns\n   all of that and returns the outcome buckets.\n3. The apply is partial-tolerant: fields that fail server-side validation are returned in the\n   `rejected` bucket while the valid fields still commit. A rejected field is therefore reported,\n   not fatal \u2014 do NOT retry the whole apply just because one field was rejected.\n\n## Stage 6 \u2014 Persist the routing credential\n\nThe Bash-spawned `start-tickets` CLI runs in a DIFFERENT runtime surface than this MCP server, so a\nkey that lives only in `.mcp.json` / `.cursor/mcp.json` is invisible to it and difficulty\u2192model\nrouting silently degrades. This final stage persists the already-validated key into the user-scoped\ncredential store (`~/.config/bridge/credentials.json`) so shell-spawned CLI commands can resolve it.\n\n1. Call the `persist_routing_credential` MCP tool with `repo_name` set to the repository name for\n   this install (the configured `BAPI_REPO_NAME`). Pass `repo_name` ONLY \u2014 this tool resolves the\n   API key inside the MCP server process. NEVER pass or display `BAPI_API_KEY` (nor `api_key`,\n   `apiKey`, `secret`, or `token`); the key value must not appear in the tool call or in any output.\n2. On success, tell the user the credential was stored, echoing the returned `target` and `path`,\n   e.g. `Stored routing credential for bapi:<repo_name> at <path>`.\n3. On failure, do NOT block the install \u2014 show the rest of the install summary anyway, then tell the\n   user the routing credential could not be stored. They can rerun `/install-bridge` after setting\n   `BAPI_API_KEY` in the environment, or run\n   `npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials` to migrate an\n   existing key. Until then, `start-tickets` model routing fails open (assumes a hard ticket and\n   defaults to premium/Opus when available) \u2014 this is the MOST EXPENSIVE model tier, so unexplained\n   cost is the symptom of leaving this unfixed. Recommend verifying credential resolution afterwards\n   with `npx -y @bridge_gpt/mcp-server doctor`.\n\n## Stage 7 \u2014 Summarize the outcome, then present the capability report\n\nFirst, begin with an explicit applied count: "Applied N of M derivable fields" (M = the unset\nbootstrap fields you derived values for). An install that applied 0 fields must say so loudly \u2014 the\ninstall is NOT complete until the apply call reports applied fields.\n\nThen summarize the six buckets from the apply response for the user:\n- `applied` \u2014 fields written this run.\n- `skipped` \u2014 fields already set (left untouched).\n- `conflict` \u2014 fields that changed since the manifest was read (re-run /install-bridge to retry).\n- `needs_confirmation` \u2014 fields awaiting explicit confirmation (e.g. project_description).\n- `rejected` \u2014 fields that failed validation or were not bootstrap-eligible (the other fields still\n  applied; fix or drop the rejected values before any retry).\n- `deferred` \u2014 fields intentionally not auto-written by install (owned by /learn-repository or set\n  deliberately).\n\n### Read-after-write: fetch current capability status\n\nAfter the bucket summary, call the `get_install_manifest` MCP tool ONCE MORE. This post-apply read\nreflects the configuration you just wrote, so its capability fields are current (the Stage-2 read was\npre-apply and is stale for this purpose). This read does not need the snapshot token. Use ONLY this\npost-write response for the capability report below.\n\nThe response carries: the `integrations` checklist (each item `label`, `is_configured`,\n`required_for`, `configure_in`), the separate `configured` / `learned` / `indexed` readiness values,\nand the server-computed `locked_tools` / `unlocked_tools` arrays. Each tool entry is exactly\n`{tool, effect, missing, semantics}`: `effect` is `BLOCK` (unavailable) or `DEGRADE` (usable now,\nbut without codebase context); `missing` lists the server-computed dependency identifiers (integration\nids such as `github_app` / `vcs_access_token`, and `code_index`); `semantics` is `all_of` or `any_of`\nand you MUST preserve it verbatim \u2014 never recompute membership yourself, and cite\n`docs/mcp-tool-integrations.md` only for the human explanation of a gate, never to recalculate it.\n\nIf the post-write response has no capability fields at all (no `integrations` / `locked_tools` /\n`unlocked_tools` keys, e.g. the additive enrichment was omitted), print exactly:\n`No capability status is available yet; configuration can still continue.` and skip the five sections.\n\nOtherwise render exactly these five sections, in this order, with these exact headings:\n\n**Connected \u2713**\n\n- List each configured integration\'s `label` from the post-write `integrations` checklist, with a\n  restrained `\u2713` marker. (Do not let the `\u2713` markers dominate the report.)\n\n**Not yet connected \u2717**\n\n- List each unconfigured integration: its `label`, its `required_for` items, and the exact\n  `configure_in` pointer. Do NOT include `setup_instructions` content \u2014 the pointer is the only\n  configuration direction you emit. STRICT INVARIANT: you DIRECT the human to the setup UI; you never\n  ask for, accept, echo, or transport an integration credential (API token, access token, webhook\n  secret) in any form.\n\n**Tools you can use now**\n\n- Render each `unlocked_tools` entry with an explicit `BLOCK` or `DEGRADE` text label (do not rely on\n  color). Describe a `DEGRADE` tool as "available with reduced/no codebase context" \u2014 never as failed\n  or unavailable. Entries here with a non-empty `missing` list are still usable; state the caveat.\n\n**Tools you\'ll unlock**\n\n- Group `locked_tools` by each missing gating integration so the human can scan by "what would I\n  configure to unlock these". Preserve the server\'s `all_of` / `any_of` semantics in plain text, e.g.\n  "requires VCS and a successful code index" (`all_of` with `code_index`) or "requires GitHub App or\n  VCS access token" (`any_of`). A tool with multiple missing integrations may appear under more than\n  one group, but keep its complete server-provided relationship intact. Cite\n  `docs/mcp-tool-integrations.md` briefly for each gate\'s human "why" \u2014 but do not recompute membership\n  from it.\n\n**Recommended next step + why**\n\n- Make this section visually strongest through ordering and concise wording. Choose the single most\n  valuable next action using this deterministic priority based only on the server output:\n  1. If any `locked_tools` entry is missing a VCS integration (`github_app` / `vcs_access_token`),\n     recommend connecting VCS in the setup UI first (via `configure_in`).\n  2. Else if any `locked_tools` entry is missing `code_index`, recommend running repository indexing\n     (`/parse-repository`) next.\n  3. Else if `learned` is false, recommend running `/learn-repository` to populate the deeper\n     instruction-tier configuration.\n- If `indexed` is `null` (unknown), include this exact warning:\n  `Index status could not be confirmed\u2014check again before relying on codebase-grounded tools.`\n\n## Stage 8 \u2014 Offer the next steps\n\n**Skip this entire stage in the install-spawn context** (the spawning instruction identifies it); the\nspawn prompt owns the single closing index-consent question there. On direct manual `/install-bridge`\ninvocation, run it normally:\n\n1. Offer to continue with `/learn-repository` to populate the deeper instruction-tier configuration\n   (architecture, review, testing, and correctness standards), matching the manifest\'s `next_step`.\n2. After `/learn-repository` completes (or if the human declines it), offer to start **repository\n   indexing**: ask ONE consent question ("Start repository indexing now? It runs as a background job\n   and makes the codebase searchable for Bridge API\'s agents."). On yes, call the `parse_repository`\n   MCP tool once. Report that the job was QUEUED and that progress can be checked with\n   `get_parse_status` (or `/check-parse-status`) \u2014 do NOT poll it to completion in this session.\n   Indexing is deliberately last so the applied `exclude_directories` / `custom_directories` values\n   scope it correctly. If no human response can be obtained (non-interactive session), skip indexing\n   and list it as a pending next step in the final report \u2014 never start it without consent.\n\n## Stage 9 \u2014 Offer CI follow-up configuration (only when CI is detected)\n\n**Skip this entire stage in the install-spawn context** (the spawning instruction identifies it), so\nthe index-consent question the spawn prompt owns remains the sole closing interaction. On direct\nmanual `/install-bridge` invocation, run it normally.\n\nThis stage is separate from the single apply call: it writes at most ONE field via the\n`config_field` MCP tool. `ci_followup_config` is REPLACE-NOT-AUGMENT \u2014 leaving it NULL already means\nsafe poll-only defaults, so "skip" is always a correct answer.\n\n1. Gate: only offer this when Stage 3 found real CI evidence (e.g. `.github/workflows/*.yml`,\n   `bitbucket-pipelines.yml`). With no CI detected, skip this stage and note "no CI detected \u2014 CI\n   follow-up not offered" in the final report.\n2. Ask ONE question, referencing the discovered CI by name, with exactly these preset profiles\n   (default: skip):\n   - **observe** \u2014 poll CI results only, never attempt fixes:\n     `{"strategy": "poll_only", "max_iterations": 1, "max_minutes": 10, "instructions": ""}`\n   - **self-heal** \u2014 bounded fix-and-iterate loop on the automation\'s own PRs:\n     `{"strategy": "fix_and_iterate", "max_iterations": 3, "max_minutes": 45, "instructions": ""}`\n   - **skip** (default) \u2014 leave `ci_followup_config` unset (NULL = baseline poll-only behavior).\n3. Do NOT offer or compose a `custom` strategy during install \u2014 free-form CI follow-up instructions\n   are a deliberate later act (setup UI or a direct `config_field` update).\n4. When the human picks a profile, call the `config_field` MCP tool once (operation `"update"`,\n   `field_name: "ci_followup_config"`, `value`: the profile\'s JSON object). If the server rejects the\n   value, retry ONCE with a corrected payload; if it is rejected again, stop, show the proposed JSON\n   to the human, and leave the field unset.\n5. Never select a profile in a non-interactive session \u2014 skip and list it as a pending next step. An\n   unattended install must never enable fix-and-iterate behavior.\n\n## Return\n\nReport the admin check result, the "Applied N of M" count, the\napplied/skipped/conflict/needs_confirmation/rejected field names, any fields omitted for\nnested-repository or ambiguity reasons, the approval outcome for each confirmation-requiring field\n(approved / declined / pending human input), whether a stale-command warning was raised (manifest\n`command_contract_version` higher than this command\'s), whether the routing credential was persisted\n(the returned `target` and `path`, or the non-blocking failure remediation), the five-section\ncapability report (Connected \u2713 / Not yet connected \u2717 / Tools you can use now / Tools you\'ll unlock /\nRecommended next step + why) from the post-apply read-after-write manifest read, the CI follow-up\noutcome (profile written / skipped / no CI detected / pending / skipped in install-spawn context), and\nthe recommended next step.\n',
-  "learn-repository.md": 'Learn and document all configuration fields for the repository by running parallel research agents.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command is recipe-driven. Do not call MCP tools directly -- the recipe determines which tools to call and with what parameters.\n\n1. This command takes no arguments.\n\n2. Call the `get_pipeline_recipe` MCP tool with:\n   - `pipeline`: `"learn-repository"`\n\n   If the tool returns an error, stop and report the failure.\n\n3. Read and strictly obey the `agent_instructions` field in the response. Execute each step in order, announcing each as **Step N of M: <description>**.\n\n4. After all steps complete, display a summary:\n   ```\n   ## Pipeline Complete\n\n   **Steps executed**: N of M\n   **Status**: Success / Failed at step N\n   ```\n',
+  "install-bridge.md": 'Bootstrap Bridge API project configuration from the local codebase via the easy-install manifest.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command takes no arguments; any `$ARGUMENTS` text is ignored.\n\nCommand contract version: **2**. The install manifest returns a `command_contract_version`; Stage 2\ncompares it to this number to detect a stale scaffolded copy of this command.\n\nThis command performs a one-time "easy install" of Bridge API project configuration. It reads the\nserver-owned install manifest once, derives values for the **unset** bootstrap fields from the local\ncodebase, asks for human approval of the project description, applies everything in a single atomic\ncall, and then presents a **capability report** derived from a fresh read-after-write manifest read.\nThe server owns all skip-if-set, conflict, and confirmation semantics \u2014 this command never makes its\nown skip-if-set decisions \u2014 and the server owns all tool locked/unlocked membership; this command\nformats the server\'s contract and never recomputes it from prose.\n\nThis command is portable across Claude Code, Cursor, and Copilot: it only drives the Bridge API MCP\ntools (`get_my_role`, `get_install_manifest`, `apply_install_manifest`).\n\nIf any stage fails, stop immediately and report which stage failed and why.\n\n**Install-spawn context.** When the spawning instruction explicitly says this `/install-bridge` run is\nin the "install-spawn context" (it was launched by the `install-bridge` CLI\'s fresh agent session),\nStage 8 and Stage 9 are SKIPPED and the single closing interaction is the index-consent question the\nspawn prompt owns. When you invoke `/install-bridge` directly (manual invocation), Stages 8 and 9\nrun normally.\n\n## Stage 1 \u2014 Admin preflight\n\n1. Call the `get_my_role` MCP tool (no parameters). Inspect the response:\n   - If `source` is `"legacy"`: proceed (legacy keys are permitted).\n   - Else if `role` is `"admin"`: proceed.\n   - Otherwise (a non-admin `user_access` key): stop immediately and display:\n     ```\n     Admin role required to apply install configuration. Ask a project admin to run /install-bridge,\n     or use an admin API key.\n     ```\n\n## Stage 2 \u2014 Read the manifest (once, pre-apply)\n\n1. Call the `get_install_manifest` MCP tool exactly once here.\n2. Keep the returned `snapshot_token` verbatim \u2014 you must pass the SAME token to the apply call in\n   Stage 5. Do not call `get_install_manifest` again before applying; a fresh read would invalidate\n   the token you are about to use. (Stage 7 performs a SEPARATE, later read-after-write manifest read\n   for the current capability status \u2014 that is deliberate and does not reuse this token.)\n3. The manifest contains ordered `groups` of bootstrap fields (each with `field_name`, `is_set`,\n   `current_value`, `guidance`, `examples`, `validation_summary`, `requires_confirmation`), a list of\n   `deferred_fields`, a `next_step`, `done_criteria`, a `command_contract_version`, and the\n   `snapshot_token`. It also carries the additive capability fields (`integrations`, `configured`,\n   `learned`, `indexed`, `locked_tools`, `unlocked_tools`) \u2014 but ignore those here; the accurate\n   capability status is the post-apply read in Stage 7.\n4. Compare the manifest\'s `command_contract_version` to this command\'s contract version (2, stated at\n   the top of this file). If the manifest\'s version is HIGHER, this scaffolded command copy is stale:\n   warn the user to refresh it by running `npx -y @bridge_gpt/mcp-server --init` in the project root,\n   then proceed conservatively \u2014 wherever the manifest\'s `guidance`, `next_step`, or `done_criteria`\n   differ from these instructions, follow the manifest.\n\n## Stage 3 \u2014 Derive values for UNSET bootstrap fields only\n\n1. Consider ONLY fields whose `is_set` is `false`. Never re-derive or overwrite a field that is\n   already set \u2014 the server will also skip already-set fields, but you should not even propose them.\n2. For each unset field, derive a value from the local codebase following that field\'s `guidance`\n   (e.g. infer `working_in` from frameworks/manifests, `version_control_system` from the git remote,\n   testing stacks from test config and dependencies, directory fields from the repo layout).\n3. Omit any field you are uncertain about or that does not apply \u2014 leaving it unset is always\n   acceptable. Do NOT guess.\n4. Specifically, do NOT invent a `version` when the platform has no meaningful version concept; leave\n   it unset.\n5. Before deriving `version_control_system` or `base_branch`, confirm the git repository root is THIS\n   project\'s root: `git rev-parse --show-toplevel` must resolve to the project directory itself. If\n   the git root is an ancestor directory (the project is nested inside another repository), OMIT both\n   fields and note why in the final report \u2014 deriving them would describe the parent repository, not\n   this project.\n6. If you find real evidence for TWO OR MORE plausible values for a field (e.g. configs for multiple\n   test frameworks, multiple frameworks in a monorepo), treat the value as ambiguous and omit it\n   rather than picking one.\n7. Do NOT derive `selected_mcp_slugs`, even though it appears as an unset bootstrap-eligible field in\n   the manifest. MCP validation manual selection is deferred to `/learn-repository`, which derives and\n   confirms it with the codebase already researched. Install neither proposes nor applies this field.\n\n## Stage 4 \u2014 Human approval for confirmation-requiring fields\n\n`project_description` is the ONLY confirmation-requiring field install proposes. It carries\n`requires_confirmation: true` in the manifest, so it is never applied on derivation alone \u2014 it needs\nexplicit human approval. (`selected_mcp_slugs` also requires confirmation, but install does not\nderive it at all; `/learn-repository` asks for it. See Stage 3 step 7.)\n\n1. If `project_description` is unset and you can draft a concise description from the codebase,\n   present the proposed `project_description` text to the human and ask for explicit approval before\n   including it.\n2. Include `project_description` in the apply payload ONLY as\n   `{ "value": <approved value>, "confirmed": true }`, and only after the human approves it. If the\n   human does not approve it, omit the field entirely.\n3. If no human response can be obtained (e.g. a non-interactive / headless session), do NOT stall and\n   do NOT abandon the install: proceed to Stage 5 with `project_description` omitted, and report it\n   as "pending human input" in the final summary. The other derived fields must still be applied \u2014 an\n   unapproved description never blocks them.\n\n## Stage 5 \u2014 Apply (one call)\n\n1. Make exactly ONE call to the `apply_install_manifest` MCP tool, passing:\n   - `snapshot_token`: the exact token from Stage 2.\n   - `fields`: a map of the derived fields. Scalar fields may be passed directly\n     (e.g. `"base_branch": "main"`); an approved `project_description` must use the\n     `{ "value": ..., "confirmed": true }` object form from Stage 4. Never include\n     `selected_mcp_slugs` in this payload \u2014 install does not derive or apply it (Stage 3 step 7).\n2. Do not implement any client-side skip-if-set, conflict, or confirmation logic \u2014 the server owns\n   all of that and returns the outcome buckets.\n3. The apply is partial-tolerant: fields that fail server-side validation are returned in the\n   `rejected` bucket while the valid fields still commit. A rejected field is therefore reported,\n   not fatal \u2014 do NOT retry the whole apply just because one field was rejected.\n\n## Stage 6 \u2014 Persist the routing credential\n\nThe Bash-spawned `start-tickets` CLI runs in a DIFFERENT runtime surface than this MCP server, so a\nkey that lives only in `.mcp.json` / `.cursor/mcp.json` is invisible to it and difficulty\u2192model\nrouting silently degrades. This final stage persists the already-validated key into the user-scoped\ncredential store (`~/.config/bridge/credentials.json`) so shell-spawned CLI commands can resolve it.\n\n1. Call the `persist_routing_credential` MCP tool with `repo_name` set to the repository name for\n   this install (the configured `BAPI_REPO_NAME`). Pass `repo_name` ONLY \u2014 this tool resolves the\n   API key inside the MCP server process. NEVER pass or display `BAPI_API_KEY` (nor `api_key`,\n   `apiKey`, `secret`, or `token`); the key value must not appear in the tool call or in any output.\n2. On success, tell the user the credential was stored, echoing the returned `target` and `path`,\n   e.g. `Stored routing credential for bapi:<repo_name> at <path>`.\n3. On failure, do NOT block the install \u2014 show the rest of the install summary anyway, then tell the\n   user the routing credential could not be stored. They can rerun `/install-bridge` after setting\n   `BAPI_API_KEY` in the environment, or run\n   `npx -y @bridge_gpt/mcp-server credentials migrate-agent-config --write-credentials` to migrate an\n   existing key. Until then, `start-tickets` model routing fails open (assumes a hard ticket and\n   defaults to premium/Opus when available) \u2014 this is the MOST EXPENSIVE model tier, so unexplained\n   cost is the symptom of leaving this unfixed. Recommend verifying credential resolution afterwards\n   with `npx -y @bridge_gpt/mcp-server doctor`.\n\n## Stage 7 \u2014 Summarize the outcome, then present the capability report\n\nFirst, begin with an explicit applied count: "Applied N of M derivable fields" (M = the unset\nbootstrap fields you derived values for). An install that applied 0 fields must say so loudly \u2014 the\ninstall is NOT complete until the apply call reports applied fields.\n\nThen summarize the six buckets from the apply response for the user:\n- `applied` \u2014 fields written this run.\n- `skipped` \u2014 fields already set (left untouched).\n- `conflict` \u2014 fields that changed since the manifest was read (re-run /install-bridge to retry).\n- `needs_confirmation` \u2014 fields awaiting explicit confirmation (e.g. project_description).\n- `rejected` \u2014 fields that failed validation or were not bootstrap-eligible (the other fields still\n  applied; fix or drop the rejected values before any retry).\n- `deferred` \u2014 fields intentionally not auto-written by install (owned by /learn-repository or set\n  deliberately). `selected_mcp_slugs` belongs here: report it as deferred to `/learn-repository`,\n  never as approved, declined, or pending an install-time decision.\n\n### Read-after-write: fetch current capability status\n\nAfter the bucket summary, call the `get_install_manifest` MCP tool ONCE MORE. This post-apply read\nreflects the configuration you just wrote, so its capability fields are current (the Stage-2 read was\npre-apply and is stale for this purpose). This read does not need the snapshot token. Use ONLY this\npost-write response for the capability report below.\n\nThe response carries: the `integrations` checklist (each item `label`, `is_configured`,\n`required_for`, `configure_in`), the separate `configured` / `learned` / `indexed` readiness values,\nand the server-computed `locked_tools` / `unlocked_tools` arrays. Each tool entry is exactly\n`{tool, effect, missing, semantics}`: `effect` is `BLOCK` (unavailable) or `DEGRADE` (usable now,\nbut without codebase context); `missing` lists the server-computed dependency identifiers (integration\nids such as `github_app` / `vcs_access_token`, and `code_index`); `semantics` is `all_of` or `any_of`\nand you MUST preserve it verbatim \u2014 never recompute membership yourself, and cite\n`docs/mcp-tool-integrations.md` only for the human explanation of a gate, never to recalculate it.\n\nIf the post-write response has no capability fields at all (no `integrations` / `locked_tools` /\n`unlocked_tools` keys, e.g. the additive enrichment was omitted), print exactly:\n`No capability status is available yet; configuration can still continue.` and skip the five sections.\n\nOtherwise render exactly these five sections, in this order, with these exact headings:\n\n**Connected \u2713**\n\n- List each configured integration\'s `label` from the post-write `integrations` checklist, with a\n  restrained `\u2713` marker. (Do not let the `\u2713` markers dominate the report.)\n\n**Not yet connected \u2717**\n\n- List each unconfigured integration: its `label`, its `required_for` items, and the exact\n  `configure_in` pointer. Do NOT include `setup_instructions` content \u2014 the pointer is the only\n  configuration direction you emit. The pointer is per-integration and is NOT always the setup UI:\n  `github_app` points at the terminal command `npx -y @bridge_gpt/mcp-server@latest connect-github\n  --repo <repo_name>`, while Jira, `vcs_access_token`, `vcs_webhook`, and SFCC point at the setup UI.\n  Emit whatever the server sent, verbatim \u2014 never rewrite a command pointer into "the setup UI".\n  STRICT INVARIANT: you DIRECT the human to that pointer; you never ask for, accept, echo, or\n  transport an integration credential (API token, access token, webhook secret) in any form. This is\n  unchanged for GitHub: the connect-github command authenticates the human to GitHub in their own\n  browser, and no GitHub credential ever reaches Bridge or an agent.\n\n**Tools you can use now**\n\n- Render each `unlocked_tools` entry with an explicit `BLOCK` or `DEGRADE` text label (do not rely on\n  color). Describe a `DEGRADE` tool as "available with reduced/no codebase context" \u2014 never as failed\n  or unavailable. Entries here with a non-empty `missing` list are still usable; state the caveat.\n\n**Tools you\'ll unlock**\n\n- Group `locked_tools` by each missing gating integration so the human can scan by "what would I\n  configure to unlock these". Preserve the server\'s `all_of` / `any_of` semantics in plain text, e.g.\n  "requires VCS and a successful code index" (`all_of` with `code_index`) or "requires GitHub App or\n  VCS access token" (`any_of`). A tool with multiple missing integrations may appear under more than\n  one group, but keep its complete server-provided relationship intact. Cite\n  `docs/mcp-tool-integrations.md` briefly for each gate\'s human "why" \u2014 but do not recompute membership\n  from it.\n\n**Recommended next step + why**\n\n- Make this section visually strongest through ordering and concise wording. Choose the single most\n  valuable next action using this deterministic priority based only on the server output:\n  1. If any `locked_tools` entry is missing a VCS integration (`github_app` / `vcs_access_token`),\n     recommend connecting VCS first, using that integration\'s own `configure_in` pointer verbatim\n     (for `github_app` that is the `connect-github` terminal command, not the setup UI).\n  2. Else if any `locked_tools` entry is missing `code_index`, recommend running repository indexing\n     (`/parse-repository`) next.\n  3. Else if `learned` is false, recommend running `/learn-repository` to populate the deeper\n     instruction-tier configuration.\n- If `indexed` is `null` (unknown), include this exact warning:\n  `Index status could not be confirmed\u2014check again before relying on codebase-grounded tools.`\n\n## Stage 8 \u2014 Offer the next steps\n\n**Skip this entire stage in the install-spawn context** (the spawning instruction identifies it); the\nspawn prompt owns the single closing index-consent question there. On direct manual `/install-bridge`\ninvocation, run it normally:\n\n1. Offer to continue with `/learn-repository` to populate the deeper instruction-tier configuration\n   (architecture, review, testing, and correctness standards), matching the manifest\'s `next_step`.\n   Mention that it also derives and confirms the applicable MCP validation manuals\n   (`selected_mcp_slugs`) \u2014 it researches the codebase first, so it can propose them with evidence\n   and explain what they do, which is why install leaves that field alone.\n2. After `/learn-repository` completes (or if the human declines it), offer to start **repository\n   indexing**: ask ONE consent question ("Start repository indexing now? It runs as a background job\n   and makes the codebase searchable for Bridge API\'s agents."). On yes, call the `parse_repository`\n   MCP tool once. Report that the job was QUEUED and that progress can be checked with\n   `get_parse_status` (or `/check-parse-status`) \u2014 do NOT poll it to completion in this session.\n   Indexing is deliberately last so the applied `exclude_directories` / `custom_directories` values\n   scope it correctly. If no human response can be obtained (non-interactive session), skip indexing\n   and list it as a pending next step in the final report \u2014 never start it without consent.\n\n## Stage 9 \u2014 Offer CI follow-up configuration (only when CI is detected)\n\n**Skip this entire stage in the install-spawn context** (the spawning instruction identifies it), so\nthe index-consent question the spawn prompt owns remains the sole closing interaction. On direct\nmanual `/install-bridge` invocation, run it normally.\n\nThis stage is separate from the single apply call: it writes at most ONE field via the\n`config_field` MCP tool. `ci_followup_config` is REPLACE-NOT-AUGMENT \u2014 leaving it NULL already means\nsafe poll-only defaults, so "skip" is always a correct answer.\n\n1. Gate: only offer this when Stage 3 found real CI evidence (e.g. `.github/workflows/*.yml`,\n   `bitbucket-pipelines.yml`). With no CI detected, skip this stage and note "no CI detected \u2014 CI\n   follow-up not offered" in the final report.\n2. Ask ONE question, referencing the discovered CI by name, with exactly these preset profiles\n   (default: skip):\n   - **observe** \u2014 poll CI results only, never attempt fixes:\n     `{"strategy": "poll_only", "max_iterations": 1, "max_minutes": 10, "instructions": ""}`\n   - **self-heal** \u2014 bounded fix-and-iterate loop on the automation\'s own PRs:\n     `{"strategy": "fix_and_iterate", "max_iterations": 3, "max_minutes": 45, "instructions": ""}`\n   - **skip** (default) \u2014 leave `ci_followup_config` unset (NULL = baseline poll-only behavior).\n3. Do NOT offer or compose a `custom` strategy during install \u2014 free-form CI follow-up instructions\n   are a deliberate later act (setup UI or a direct `config_field` update).\n4. When the human picks a profile, call the `config_field` MCP tool once (operation `"update"`,\n   `field_name: "ci_followup_config"`, `value`: the profile\'s JSON object). If the server rejects the\n   value, retry ONCE with a corrected payload; if it is rejected again, stop, show the proposed JSON\n   to the human, and leave the field unset.\n5. Never select a profile in a non-interactive session \u2014 skip and list it as a pending next step. An\n   unattended install must never enable fix-and-iterate behavior.\n\n## Return\n\nReport the admin check result, the "Applied N of M" count, the\napplied/skipped/conflict/needs_confirmation/rejected field names, any fields omitted for\nnested-repository or ambiguity reasons, the approval outcome for `project_description` \u2014 install\'s\nonly confirmation-requiring field \u2014 (approved / declined / pending human input), the fact that\n`selected_mcp_slugs` is deferred to `/learn-repository` rather than decided here, whether a\nstale-command warning was raised (manifest\n`command_contract_version` higher than this command\'s), whether the routing credential was persisted\n(the returned `target` and `path`, or the non-blocking failure remediation), the five-section\ncapability report (Connected \u2713 / Not yet connected \u2717 / Tools you can use now / Tools you\'ll unlock /\nRecommended next step + why) from the post-apply read-after-write manifest read, the CI follow-up\noutcome (profile written / skipped / no CI detected / pending / skipped in install-spawn context), and\nthe recommended next step.\n',
+  "learn-repository.md": "Learn and document all configuration fields for the repository by running parallel research agents.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command is recipe-driven. Do not call MCP tools directly -- the recipe determines which tools to call and with what parameters.\n\n1. This command takes no arguments.\n\n2. **Before executing any recipe step**, tell the user what they are about to sit through and why it\n   is worth it:\n\n   ```\n   Learning this repository. This takes a while \u2014 the research agents read the actual codebase, and\n   all the unlearned fields are researched in parallel, so the wait is roughly the slowest single\n   field rather than the sum of all of them. Fields that are already populated are skipped entirely.\n\n   What this buys you: these fields are what ground Bridge's agents in THIS codebase. Planning,\n   reviewing, and code generation all read them, so they follow your repository's actual\n   architecture, testing, documentation, and correctness conventions instead of generic defaults.\n\n   It runs unattended \u2014 there are no approval prompts during the run. You may be asked one batched\n   question at the very end.\n   ```\n\n   Do not invent a specific number of minutes; the honest statement is the parallel-wait shape above.\n\n3. Call the `get_pipeline_recipe` MCP tool with:\n   - `pipeline`: `\"learn-repository\"`\n\n   If the tool returns an error, stop and report the failure.\n\n4. Read and strictly obey the `agent_instructions` field in the response. Execute each step in order, announcing each as **Step N of M: <description>**.\n\n   Retain, for the closing summary: the consolidated research task's structured result (its per-field\n   `status`, `character_count`, `condensed`, and `condensation_reason`), each upload step's result,\n   and the final confirmation task's structured result. You will need all three \u2014 do not discard them\n   as you go.\n\n5. After all steps complete, display a summary built from the results you retained:\n\n   ```\n   ## Learn Complete\n\n   **Status**: Success / Completed with gaps / Failed at step N\n\n   **Learned and applied**: <fields drafted this run and written to config>\n   **Already populated (skipped)**: <fields skipped because they already had a value>\n   **Condensed to fit the field limit**: <field \u2014 reason it was condensed, per field>\n   **Gaps**: <fields whose research or upload failed, each named with its reason>\n   **Confirmation**: <approved / applied / declined / pending human input / not applicable, per field>\n\n   Review or edit any of these on the **Project Configuration** page, under **Code Writer Settings**\n   for the learned instructions and **MCP Validation Manuals** for the manual selection. Bridge's\n   agents read whatever is stored there, so correcting a wrong conclusion there changes their\n   behavior.\n   ```\n\n   Rules for the summary:\n\n   - A run where some fields failed but others applied is **`Completed with gaps`**, not `Failed`.\n     Name every gap explicitly \u2014 an unnamed gap is worse than a failed run, because the user believes\n     the field was learned.\n   - Report confirmation candidates that could not be presented in a headless session with the exact\n     phrase `pending human input`.\n   - Every field that was condensed must appear with the reason it was condensed.\n",
   "parse-repository.md": "Queue a background job to parse and index the repository for Bridge API's AI agents.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nExecute all steps in this command as a simple linear sequence of MCP tool calls.\n\n## Step 1 \u2014 Parse Arguments\n\nParse `$ARGUMENTS` for an optional `directory_path` argument (a subdirectory path to scope the parse to, e.g., `src/python`). If no argument is provided, the entire repository will be parsed. If `$ARGUMENTS` is provided but invalid (e.g., contains special characters that suggest it's not a path), report an error.\n\n## Step 2 \u2014 Queue Parse Job\n\nCall the `parse_repository` MCP tool with:\n- `directory_path`: set to the parsed `directory_path` from Step 1 if provided, otherwise omit the parameter\n\nIf the response indicates parsing is already in progress, display:\n\n```\nRepository parsing is already in progress. A previous parse job has not yet completed.\n\nRun `/check-parse-status` to monitor progress, or wait a few minutes and try again.\n```\n\nStop and do not proceed to the summary.\n\nIf the call fails or returns an error, stop immediately and display:\n\n```\nFailed to queue parse job: <error message from the tool>\n```\n\n## Summary\n\nOn successful queuing, display:\n\n```\nRepository parse job queued successfully.\n\nScope: <entire repository or directory_path if provided>\n\nProcessing typically takes several minutes for large repositories.\nRun `/check-parse-status` to monitor progress.\n```\n\nAfter the parse completes, AI-generated plans and clarifying questions will reflect the latest code changes.\n",
   "plan-epic.md": 'Plan an epic by decomposing it into sub-tasks with structured exploration documents.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nThis command is recipe-driven. Do not call MCP tools directly -- the recipe determines which tools to call and with what parameters.\n\n## Stage 0 \u2014 Setup\n\n1. **Parse arguments**: Extract the input from `$ARGUMENTS`. Trim any surrounding whitespace. If the input is empty or whitespace-only, stop immediately and display:\n   ```\n   Usage: /plan-epic <description of the epic or Jira key>\n   ```\n\n2. **Jira key detection**: If the input matches a Jira key pattern (`[A-Z]+-\\d+`), call the `get_ticket` MCP tool with that key to fetch the epic description. Use the ticket\'s description as the `epic_description`, and set `epic_key` to that Jira key. If the input does not match a Jira key, use the free-form text directly as the `epic_description` and set `epic_key` to an empty string `""` (there is no Jira epic to update). The recipe uses `epic_key` to decide whether to post the goals/NFRs + recommended implementation order as a comment on the epic.\n\n3. **Generate slug**: Create a kebab-case slug from the epic description \u2014 take the first 6-8 meaningful words, strip non-alphanumeric characters (except hyphens), lowercase, and truncate to 60 characters. This becomes the `epic_slug`.\n\n4. **Directory existence check**: Call the `get_docs_dir` MCP tool (no parameters) to get the docs directory path. Then run a terminal command to check if the directory `{docs_dir}/epic-plans/{epic_slug}` already exists:\n   ```\n   test -d {docs_dir}/epic-plans/{epic_slug} && echo "exists" || echo "not_found"\n   ```\n   If the directory exists, append `-{unix_timestamp}` to the `epic_slug` (e.g., `add-auth-provider-support-1710000000`).\n\n## Stage 1 \u2014 Execution\n\n5. Call the `get_pipeline_recipe` MCP tool with:\n   - `pipeline`: `"plan-epic"`\n   - `variables`: `{ "epic_description": "<resolved_description>", "epic_slug": "<slug>", "epic_key": "<jira_key_or_empty_string>" }`\n\n   Note: Do NOT pass `docs_dir` in variables \u2014 it is auto-injected by the pipeline system.\n\n   If the tool returns an error, stop and report the failure.\n\n6. Read and strictly obey the `agent_instructions` field in the response. Execute each step in order, announcing each as **Step N of M: <description>**.\n\n7. After all steps complete, display a summary:\n   ```\n   ## Pipeline Complete\n\n   **Epic**: <first 80 characters of epic_description>...\n   **Slug**: <epic_slug>\n   **Output**: <docs_dir>/epic-plans/<epic_slug>/overview.md\n   **Steps executed**: N of M\n   **Status**: Success / Failed at step N\n   ```\n',
   "plan-ticket.md": 'Generate an implementation plan for a Jira ticket, wait for the result, and save it locally.\n\n$ARGUMENTS\n\n---\n\n# Instructions\n\nExecute all steps in this command as a simple linear sequence of MCP tool calls.\n\n## Step 1 \u2014 Parse Arguments\n\n1. **Parse `$ARGUMENTS`**: Extract a required `ticket_key`, an optional `--second-opinion` flag, and an optional `--provider` flag.\n   - Split `$ARGUMENTS` on whitespace.\n   - If `--second-opinion` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `second_opinion_value`.\n   - If `--second-opinion` appears without a provider name following it (or is the last token), set `second_opinion_value = "auto"`.\n   - If `--second-opinion` is absent, set `second_opinion_value = null`.\n   - If `--provider` appears followed by a provider name (one of `openai`, `anthropic`, `gemini`), capture that provider as `provider_value`.\n   - If `--provider` appears without a valid provider name following it (or is the last token), stop immediately and report: "Usage error: --provider requires a provider name (openai, anthropic, or gemini)."\n   - If `--provider` is absent, set `provider_value = null`.\n   - If both `--second-opinion` and `--provider` are present, `--second-opinion` takes precedence (set `provider_value = null`).\n   - The remaining token (after removing flags and their arguments) is the `ticket_key`.\n   - If `ticket_key` is empty or missing, stop immediately and display:\n\n   ```\n   Usage: /plan-ticket <ticket_key> [--second-opinion [provider]] [--provider <name>] (e.g., /plan-ticket BAPI-150)\n   ```\n\n## Step 2 \u2014 Resolve Docs Directory\n\nCall the `get_docs_dir` MCP tool (no parameters). Store the returned path as `docs_dir`.\n\n## Step 3 \u2014 Generate Plan\n\nCall the `request_plan_generation` MCP tool with:\n- `ticket_number`: the parsed `ticket_key`\n- `wait_for_result`: `true`\n- `save_locally`: `true`\n- `second_opinion`: set to `second_opinion_value` if non-null; omit entirely if null\n- `provider`: set to `provider_value` if non-null; omit entirely if null\n\nThis step may take 1-5 minutes while the backend processes the plan.\n\nIf the tool returns an error, stop immediately and display:\n\n```\nPlan generation failed: <error message from the tool>\n```\n\n## Step 4 \u2014 Confirm Success\n\nDisplay a confirmation message:\n\n```\nPlan generated successfully for <ticket_key>\nSaved to: {docs_dir}/plans/<ticket_key>-plan.md\n```\n\n## Final Summary\n\nDisplay a summary block:\n\n```\n## Plan Generation Report\n\n- **Ticket**: <ticket_key>\n- **Plan Status**: Generated successfully\n- **Local File**: {docs_dir}/plans/<ticket_key>-plan.md\n```\n\nOn failure at any step, stop immediately, display which step failed and the error details, and do not proceed.\n',
@@ -16300,6 +16306,17 @@ function summarizeIntegrations(body) {
   }
   return { total, unconfigured };
 }
+function readGithubConfiguredFlag(body) {
+  if (!body || typeof body !== "object") return null;
+  const integrations = body.integrations;
+  if (!Array.isArray(integrations)) return null;
+  for (const item of integrations) {
+    if (item?.id !== "github_app") continue;
+    const configured = item.is_configured;
+    return typeof configured === "boolean" ? configured : null;
+  }
+  return null;
+}
 async function collectInstallStatusChecks(deps) {
   const checks = [];
   const target = await resolveInstallDoctorTarget(deps);
@@ -16475,6 +16492,39 @@ async function collectInstallStatusChecks(deps) {
       detail: "manifest unavailable"
     });
   }
+  if (manifest.ok && manifest.status === 200) {
+    const github = readGithubConfiguredFlag(manifest.body);
+    if (github === null) {
+      checks.push({
+        id: "github",
+        label: "GitHub connection",
+        status: "SKIP",
+        detail: "the manifest response carried no GitHub integration entry"
+      });
+    } else if (github) {
+      checks.push({
+        id: "github",
+        label: "GitHub connection",
+        status: "PASS",
+        detail: "a GitHub repository is connected to this project"
+      });
+    } else {
+      checks.push({
+        id: "github",
+        label: "GitHub connection",
+        status: "WARN",
+        detail: "no GitHub repository is connected to this project",
+        remediation: `run 'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${target.repoName}'.`
+      });
+    }
+  } else {
+    checks.push({
+      id: "github",
+      label: "GitHub connection",
+      status: "SKIP",
+      detail: "manifest unavailable"
+    });
+  }
   const parse = await probeGet(deps, `${target.baseUrl}/jira/parse-status?${repoQuery}`, apiKey);
   if (!parse.ok || parse.status !== 200) {
     checks.push({
@@ -17501,8 +17551,8 @@ function createDefaultExecutorDeps() {
     mkdir: (dirPath, opts) => mkdir5(dirPath, opts),
     stat: (filePath) => stat6(filePath).then((s) => ({ mode: s.mode })),
     statMtimeMs: (filePath) => stat6(filePath).then((s) => s.mtimeMs).catch(() => null),
-    statfs: async (path34) => {
-      const s = await statfs(path34);
+    statfs: async (path35) => {
+      const s = await statfs(path35);
       return { bavail: Number(s.bavail), bsize: Number(s.bsize) };
     },
     sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
@@ -20658,13 +20708,13 @@ function findCycle(keys, adjacency) {
     if (color.get(start) !== WHITE) continue;
     const stack = [{ node: start, path: [start] }];
     while (stack.length > 0) {
-      const { node, path: path34 } = stack[stack.length - 1];
+      const { node, path: path35 } = stack[stack.length - 1];
       if (color.get(node) === WHITE) {
         color.set(node, GREY);
         for (const next of adjacency.get(node) ?? []) {
-          if (color.get(next) === GREY) return [...path34, next];
+          if (color.get(next) === GREY) return [...path35, next];
           if (color.get(next) === WHITE) {
-            stack.push({ node: next, path: [...path34, next] });
+            stack.push({ node: next, path: [...path35, next] });
           }
         }
       } else {
@@ -21039,8 +21089,8 @@ function extractChangedSymbolsFromDiff(diffText) {
   let newLineNo = 0;
   for (const rawLine of diffText.split("\n")) {
     if (rawLine.startsWith("+++ ")) {
-      const path34 = rawLine.slice(4).trim();
-      currentFile = path34 === "/dev/null" ? null : path34.replace(/^b\//, "");
+      const path35 = rawLine.slice(4).trim();
+      currentFile = path35 === "/dev/null" ? null : path35.replace(/^b\//, "");
       continue;
     }
     if (rawLine.startsWith("--- ") || rawLine.startsWith("diff --git") || rawLine.startsWith("index ")) {
@@ -21599,16 +21649,573 @@ async function runRegressionCheckCli(argv, overrides = {}) {
 }
 
 // src/install-bridge.ts
-import { readFile as readFile10, writeFile as writeFile7, mkdir as mkdir7, stat as stat7, rename, chmod, unlink, open } from "fs/promises";
-import { spawn as spawn6 } from "child_process";
+import { readFile as readFile11, writeFile as writeFile7, mkdir as mkdir7, stat as stat8, rename, chmod, unlink, open } from "fs/promises";
+import { spawn as spawn7 } from "child_process";
 import { randomBytes as cryptoRandomBytes, createHash as createHash3 } from "crypto";
+import os14 from "os";
+import path24 from "path";
+import readline2 from "readline";
+init_version_generated();
+init_bridge_config();
+init_start_tickets_repo();
+init_credential_store();
+
+// src/connect-github-api.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "staged",
+  "awaiting-organization-approval",
+  "connected",
+  "expired",
+  "invalid",
+  "verification-failed",
+  "no-repositories",
+  "conflict",
+  "failed"
+]);
+var ALL_STATUSES = /* @__PURE__ */ new Set([
+  "waiting",
+  ...TERMINAL_STATUSES
+]);
+var REQUEST_TIMEOUT_MS = 15e3;
+async function postJson(deps, path35, payload) {
+  let resp;
+  try {
+    resp = await deps.fetch(`${deps.baseUrl}${path35}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": deps.apiKey
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+  } catch (e) {
+    const isTimeout = e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+    return { ok: false, kind: isTimeout ? "timeout" : "network" };
+  }
+  let body = null;
+  try {
+    body = await resp.json();
+  } catch {
+  }
+  return {
+    ok: true,
+    value: { status: resp.status, body, retryAfter: resp.headers.get("Retry-After") }
+  };
+}
+function classifyStatus(status) {
+  if (status === 401 || status === 403) return "unauthorized";
+  if (status === 404) return "not-found";
+  return "server";
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function asString3(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function asNullableString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function parseRetryAfterMs(header, remainingMs, nowMs) {
+  if (!header) return null;
+  const trimmed = header.trim();
+  if (!trimmed) return null;
+  const clamp = (ms) => {
+    if (!Number.isFinite(ms) || ms < 0) return null;
+    return Math.min(ms, Math.max(0, remainingMs));
+  };
+  if (/^\d+$/.test(trimmed)) {
+    return clamp(Number(trimmed) * 1e3);
+  }
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) return null;
+  return clamp(parsed - nowMs);
+}
+async function mintGithubConnection(deps, repoName) {
+  const res = await postJson(deps, "/setup/github/cli/connection-code", {
+    repo_name: repoName
+  });
+  if (!res.ok) return res;
+  if (res.value.status !== 200) {
+    return { ok: false, kind: classifyStatus(res.value.status) };
+  }
+  const body = asRecord(res.value.body);
+  const state = asString3(body?.state);
+  const installUrl = asString3(body?.install_url);
+  const ttlSeconds = body?.ttl_seconds;
+  if (!body || !state || !installUrl || typeof ttlSeconds !== "number") {
+    return { ok: false, kind: "malformed" };
+  }
+  return { ok: true, value: { state, installUrl, ttlSeconds } };
+}
+function parseCandidates(value) {
+  if (!Array.isArray(value)) return null;
+  const out = [];
+  for (const raw of value) {
+    const rec = asRecord(raw);
+    const id = asString3(rec?.github_repository_id);
+    const name = asString3(rec?.github_repo_name);
+    if (!rec || !id || !name) return null;
+    out.push({
+      github_repository_id: id,
+      github_repo_name: name,
+      github_repo_full_name: asNullableString(rec.github_repo_full_name),
+      owner: asNullableString(rec.owner)
+    });
+  }
+  return out;
+}
+async function confirmGithubConnection(deps, repoName, state, githubRepositoryId) {
+  const res = await postJson(deps, "/setup/github/cli/confirm", {
+    repo_name: repoName,
+    state,
+    github_repository_id: githubRepositoryId
+  });
+  if (!res.ok) return res;
+  if (res.value.status !== 200) {
+    return { ok: false, kind: classifyStatus(res.value.status) };
+  }
+  const body = asRecord(res.value.body);
+  const name = asString3(body?.github_repo_name);
+  if (!body || body.status !== "connected" || !name) {
+    return { ok: false, kind: "malformed" };
+  }
+  return {
+    ok: true,
+    value: {
+      githubRepoName: name,
+      githubRepoFullName: asNullableString(body.github_repo_full_name)
+    }
+  };
+}
+async function fetchGithubConfigurationState(deps, repoName) {
+  let resp;
+  try {
+    resp = await deps.fetch(
+      `${deps.baseUrl}/jira/config/install-manifest?repo_name=${encodeURIComponent(repoName)}`,
+      {
+        headers: { "X-API-Key": deps.apiKey },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      }
+    );
+  } catch {
+    return "unavailable";
+  }
+  if (resp.status !== 200) return "unavailable";
+  let body;
+  try {
+    body = await resp.json();
+  } catch {
+    return "unavailable";
+  }
+  const integrations = asRecord(body)?.integrations;
+  if (!Array.isArray(integrations)) return "unavailable";
+  for (const raw of integrations) {
+    const rec = asRecord(raw);
+    if (rec?.id !== "github_app") continue;
+    if (typeof rec.is_configured !== "boolean") return "unavailable";
+    return rec.is_configured ? "configured" : "unconfigured";
+  }
+  return "unavailable";
+}
+var POLL_DEADLINE_MS = 15.5 * 60 * 1e3;
+var POLL_DELAYS_MS = [2e3, 3e3, 5e3];
+var MAX_JITTER_MS = 400;
+var RETRYABLE_TRANSPORT = /* @__PURE__ */ new Set([
+  "network",
+  "timeout"
+]);
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500;
+}
+async function pollGithubConnection(deps, poll, repoName, state) {
+  const started = poll.now();
+  let attempt = 0;
+  for (; ; ) {
+    const elapsed = poll.now() - started;
+    const remaining = POLL_DEADLINE_MS - elapsed;
+    if (remaining <= 0) return { ok: false, kind: "deadline" };
+    const res = await postJson(deps, "/setup/github/cli/status", {
+      repo_name: repoName,
+      state
+    });
+    let waitMs = null;
+    if (!res.ok) {
+      if (!RETRYABLE_TRANSPORT.has(res.kind)) return { ok: false, kind: res.kind };
+    } else if (res.value.status === 200) {
+      const body = asRecord(res.value.body);
+      const status = asString3(body?.status);
+      if (!body || !status || !ALL_STATUSES.has(status)) {
+        return { ok: false, kind: "malformed" };
+      }
+      const candidates = parseCandidates(body.candidates ?? []);
+      if (candidates === null) return { ok: false, kind: "malformed" };
+      const typed = status;
+      if (TERMINAL_STATUSES.has(typed)) {
+        return {
+          ok: true,
+          value: {
+            status: typed,
+            candidates,
+            githubRepoName: asNullableString(body.github_repo_name),
+            retryAfterMs: null
+          }
+        };
+      }
+      waitMs = parseRetryAfterMs(res.value.retryAfter, remaining, poll.now());
+    } else if (isRetryableStatus(res.value.status)) {
+      waitMs = parseRetryAfterMs(res.value.retryAfter, remaining, poll.now());
+    } else {
+      return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    if (waitMs === null) {
+      const base = POLL_DELAYS_MS[Math.min(attempt, POLL_DELAYS_MS.length - 1)];
+      waitMs = base + Math.floor(poll.jitter() * MAX_JITTER_MS);
+    }
+    attempt += 1;
+    const capped = Math.min(waitMs, Math.max(0, POLL_DEADLINE_MS - (poll.now() - started)));
+    if (capped <= 0) return { ok: false, kind: "deadline" };
+    await poll.sleep(capped);
+  }
+}
+
+// src/connect-github.ts
+import { readFile as readFile10, stat as stat7 } from "fs/promises";
+import { spawn as spawn6 } from "child_process";
 import os13 from "os";
 import path23 from "path";
 import readline from "readline";
-init_version_generated();
 init_bridge_config();
 init_start_tickets_repo();
 init_credential_store();
+var USAGE = `Usage: connect-github [--repo <repo_name>]
+
+Connect a GitHub repository to a Bridge project from your terminal.
+
+Opens the GitHub App install page in your browser, waits for you to install it,
+then asks which repository to connect. You are never asked for a GitHub token or
+password \u2014 you authenticate to GitHub in the browser.
+
+Options:
+  --repo <repo_name>   Bridge project to connect (inferred from this directory
+                       when omitted; you will be asked to confirm).
+  --help               Show this message.`;
+function parseConnectGithubArgs(argv) {
+  const out = { help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (arg === "--repo") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        return { ok: false, error: "--repo requires a value (e.g. --repo my-project)." };
+      }
+      out.repo = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--repo=")) {
+      const value = arg.slice("--repo=".length);
+      if (!value) {
+        return { ok: false, error: "--repo requires a value (e.g. --repo my-project)." };
+      }
+      out.repo = value;
+      continue;
+    }
+    if (arg === "--yes" || arg === "-y") {
+      return {
+        ok: false,
+        error: "connect-github does not support --yes: connecting a repository always requires an explicit confirmation."
+      };
+    }
+    if (arg === "--installation-id" || arg.startsWith("--installation-id=")) {
+      return {
+        ok: false,
+        error: "connect-github does not accept --installation-id: the installation is verified by Bridge from your browser install, not supplied by the caller."
+      };
+    }
+    if (arg.startsWith("-")) {
+      return { ok: false, error: `Unknown option: ${arg}` };
+    }
+    return { ok: false, error: `Unexpected argument: ${arg}` };
+  }
+  return { ok: true, value: out };
+}
+function defaultPromptLine(promptText) {
+  return new Promise((resolve2) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    let answered = false;
+    rl.on("close", () => {
+      if (!answered) resolve2("");
+    });
+    rl.question(promptText, (answer) => {
+      answered = true;
+      rl.close();
+      resolve2(answer.trim());
+    });
+  });
+}
+function defaultOpenBrowser(platform, url) {
+  const [command, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? (
+    // `start` is a cmd builtin; the empty string is its window-title argument,
+    // without which a quoted URL would be swallowed as the title.
+    ["cmd", ["/c", "start", "", url]]
+  ) : ["xdg-open", [url]];
+  return new Promise((resolve2) => {
+    try {
+      const child = spawn6(command, args, {
+        stdio: "ignore",
+        detached: false,
+        shell: false
+      });
+      child.on("error", () => resolve2(false));
+      child.on("spawn", () => resolve2(true));
+    } catch {
+      resolve2(false);
+    }
+  });
+}
+function createDefaultConnectGithubDeps() {
+  return {
+    env: process.env,
+    cwd: process.cwd(),
+    platform: process.platform,
+    homedir: os13.homedir,
+    isTTY: Boolean(process.stdin.isTTY),
+    readFile: (filePath) => readFile10(filePath, "utf-8"),
+    stat: async (filePath) => {
+      const s = await stat7(filePath);
+      return { mode: s.mode };
+    },
+    fetch: globalThis.fetch,
+    sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
+    now: () => Date.now(),
+    jitter: () => Math.random(),
+    promptLine: defaultPromptLine,
+    openBrowser: (url) => defaultOpenBrowser(process.platform, url),
+    stdout: (message) => process.stdout.write(`${message}
+`),
+    stderr: (message) => process.stderr.write(`${message}
+`)
+  };
+}
+async function resolveConnectGithubRepoName(args, deps) {
+  if (args.repo) {
+    const validated2 = validateRepoName(args.repo);
+    return validated2.ok ? { ok: true, value: validated2.value } : { ok: false, error: validated2.error };
+  }
+  let inferred = await resolveStartTicketsRepoName({
+    env: deps.env,
+    cwd: deps.cwd,
+    readFile: deps.readFile
+  });
+  if (!inferred) {
+    const validated2 = validateRepoName(path23.basename(deps.cwd));
+    if (validated2.ok) inferred = validated2.value;
+  }
+  if (!inferred) {
+    return {
+      ok: false,
+      error: "Could not determine the Bridge project. Pass --repo <repo_name>."
+    };
+  }
+  const answer = (await deps.promptLine(`Bridge project [${inferred}]: `)).trim();
+  const chosen = answer.length > 0 ? answer : inferred;
+  const validated = validateRepoName(chosen);
+  return validated.ok ? { ok: true, value: validated.value } : { ok: false, error: validated.error };
+}
+async function openGithubInstallPage(deps, installUrl) {
+  const opened = await deps.openBrowser(installUrl);
+  if (opened) return { ok: true };
+  return {
+    ok: false,
+    error: "Could not open your browser automatically. Re-run this command from a desktop session with a browser available."
+  };
+}
+var STEPS = [
+  "Connect GitHub",
+  "Complete GitHub in browser",
+  "Verify connection",
+  "Choose repository",
+  "Confirm connection"
+];
+function renderStep(deps, index) {
+  deps.stderr(`[${index + 1}/${STEPS.length}] ${STEPS[index]}`);
+}
+function candidateLabel(c) {
+  if (c.github_repo_full_name) return c.github_repo_full_name;
+  return c.owner ? `${c.owner}/${c.github_repo_name}` : c.github_repo_name;
+}
+var OUTCOME_MESSAGES = {
+  expired: "The connection request expired before GitHub reported back. Run connect-github again.",
+  invalid: "This connection request is no longer valid. Run connect-github again.",
+  "verification-failed": "Bridge could not verify the GitHub installation. Run connect-github again.",
+  "no-repositories": "The GitHub App installation did not include any repositories Bridge can access. Re-run connect-github and grant access to at least one repository.",
+  conflict: "This GitHub installation or project is already connected to a different Bridge account or repository. Contact support if that is unexpected.",
+  failed: "The GitHub connection did not complete. Run connect-github again."
+};
+var FAILURE_MESSAGES = {
+  network: "Could not reach Bridge API. Check your network, then run connect-github again.",
+  timeout: "Bridge API did not respond in time. Run connect-github again.",
+  unauthorized: "Bridge rejected your API key for this project. Re-run install-bridge with a current key.",
+  "not-found": "Bridge does not recognize this project. Check --repo matches your Bridge project name.",
+  server: "Bridge API returned an error. Run connect-github again shortly.",
+  malformed: "Bridge API returned an unexpected response. Run connect-github again shortly.",
+  deadline: "Timed out waiting for GitHub. If you completed the install, run connect-github again to pick up the connection."
+};
+function reportNoConnection(deps, detail) {
+  deps.stderr("");
+  deps.stderr("No GitHub connection was made.");
+  deps.stderr(detail);
+  return 1;
+}
+async function runGithubConnectionFlow(deps, api, repoName) {
+  renderStep(deps, 0);
+  const minted = await mintGithubConnection(api, repoName);
+  if (!minted.ok) {
+    return reportNoConnection(deps, FAILURE_MESSAGES[minted.kind]);
+  }
+  renderStep(deps, 1);
+  deps.stderr("Opening GitHub\u2026");
+  const opened = await openGithubInstallPage(deps, minted.value.installUrl);
+  if (!opened.ok) {
+    return reportNoConnection(deps, opened.error);
+  }
+  renderStep(deps, 2);
+  const minutes = Math.floor(POLL_DEADLINE_MS / 6e4);
+  deps.stderr(`Waiting for GitHub installation\u2026 (up to ~${minutes} minutes)`);
+  const pollDeps = { sleep: deps.sleep, now: deps.now, jitter: deps.jitter };
+  const started = deps.now();
+  const polled = await pollGithubConnection(api, pollDeps, repoName, minted.value.state);
+  if (!polled.ok) {
+    return reportNoConnection(deps, FAILURE_MESSAGES[polled.kind]);
+  }
+  const elapsedSec = Math.max(0, Math.round((deps.now() - started) / 1e3));
+  deps.stderr(`Waited ${elapsedSec}s.`);
+  const result = polled.value;
+  if (result.status === "awaiting-organization-approval") {
+    deps.stderr("");
+    deps.stderr("No GitHub connection was made.");
+    deps.stderr(
+      "Your request to install the GitHub App was sent to an organization owner for approval."
+    );
+    deps.stderr(
+      "That approval happens on GitHub and does not return here, so this command cannot wait for it."
+    );
+    deps.stderr(
+      "Once an owner approves the install, finish the connection with the manual steps in the GitHub App setup guide (docs/install/github-app.md)."
+    );
+    return 1;
+  }
+  if (result.status === "connected") {
+    deps.stdout(`Connected ${result.githubRepoName ?? repoName}.`);
+    return 0;
+  }
+  if (result.status !== "staged") {
+    return reportNoConnection(deps, OUTCOME_MESSAGES[result.status] ?? OUTCOME_MESSAGES.failed);
+  }
+  const candidates = result.candidates;
+  if (candidates.length === 0) {
+    return reportNoConnection(deps, OUTCOME_MESSAGES["no-repositories"]);
+  }
+  renderStep(deps, 3);
+  let selected = null;
+  if (candidates.length === 1) {
+    const only = candidates[0];
+    const answer = (await deps.promptLine(`Connect ${candidateLabel(only)}? [y/N]: `)).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      deps.stderr("");
+      deps.stderr("No GitHub connection was made. Nothing was changed.");
+      return 1;
+    }
+    selected = only;
+  } else {
+    deps.stderr("");
+    deps.stderr("Your GitHub installation includes multiple repositories:");
+    candidates.forEach((c, i) => {
+      deps.stderr(`  ${String(i + 1).padStart(2, " ")}. ${candidateLabel(c)}`);
+    });
+    deps.stderr("");
+    const answer = (await deps.promptLine(`Choose a repository [1-${candidates.length}]: `)).trim();
+    const index = Number(answer);
+    if (!/^\d+$/.test(answer) || !Number.isInteger(index) || index < 1 || index > candidates.length) {
+      deps.stderr("");
+      deps.stderr("No GitHub connection was made. No repository was selected.");
+      return 1;
+    }
+    selected = candidates[index - 1];
+    deps.stderr(`Selected ${candidateLabel(selected)}.`);
+  }
+  renderStep(deps, 4);
+  const confirmed = await confirmGithubConnection(
+    api,
+    repoName,
+    minted.value.state,
+    selected.github_repository_id
+  );
+  if (!confirmed.ok) {
+    return reportNoConnection(deps, FAILURE_MESSAGES[confirmed.kind]);
+  }
+  deps.stdout(
+    `Connected ${confirmed.value.githubRepoFullName ?? confirmed.value.githubRepoName}.`
+  );
+  return 0;
+}
+async function runConnectGithubCli(argv, injected) {
+  const deps = injected ?? createDefaultConnectGithubDeps();
+  try {
+    const parsed = parseConnectGithubArgs(argv);
+    if (!parsed.ok) {
+      deps.stderr(parsed.error);
+      deps.stderr("");
+      deps.stderr(USAGE);
+      return 1;
+    }
+    if (parsed.value.help) {
+      deps.stdout(USAGE);
+      return 0;
+    }
+    if (!deps.isTTY) {
+      deps.stderr(
+        "connect-github needs an interactive terminal: it asks you to confirm which repository to connect. Run it directly in your terminal."
+      );
+      return 1;
+    }
+    const repo = await resolveConnectGithubRepoName(parsed.value, deps);
+    if (!repo.ok) {
+      deps.stderr(repo.error);
+      return 1;
+    }
+    const cred = await resolveBapiCredentials(repo.value, {
+      env: deps.env,
+      homedir: deps.homedir,
+      platform: deps.platform,
+      readFile: deps.readFile,
+      stat: deps.stat,
+      stderr: () => {
+      }
+    });
+    if (!cred.ok) {
+      deps.stderr(cred.error);
+      return 1;
+    }
+    const api = {
+      fetch: deps.fetch,
+      baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL2,
+      apiKey: cred.credentials.apiKey
+    };
+    return await runGithubConnectionFlow(deps, api, repo.value);
+  } catch {
+    deps.stderr("No GitHub connection was made. An unexpected error occurred.");
+    return 1;
+  }
+}
+
+// src/install-bridge.ts
 init_agent_registry();
 init_start_tickets();
 var REDACTED_API_KEY = "<REDACTED>";
@@ -21619,7 +22226,7 @@ function buildPrewarmArgs() {
 function buildPrewarmCommandPreview() {
   return `npx ${buildPrewarmArgs().join(" ")}`;
 }
-var INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command in the install-spawn context (tell the command it is running in the install-spawn context so it SKIPS its Stage 8 and Stage 9 offers \u2014 this session's only closing interaction is the single indexing question below). Do NOT run /learn-repository. Do NOT call parse_repository (or otherwise start indexing) before the capability report and explicit consent below. Complete the command's read-after-write five-section capability report first: 'Connected \u2713', 'Not yet connected \u2717', 'Tools you can use now', 'Tools you'll unlock', and 'Recommended next step + why'. Only AFTER that report is fully presented, ask exactly one question using this visible prompt: '[Y/n] Index repository now?'. Only an explicit affirmative answer (e.g. 'y'/'yes') starts indexing; a blank answer, a negative answer, EOF, an unavailable interaction, and any non-interactive/headless run all resolve to NO. On an affirmative answer: call the parse_repository MCP tool exactly once, describe the accepted job as QUEUED, and direct later progress checks to get_parse_status or /check-parse-status (do NOT poll it to completion). If parse_repository returns a blocking refusal or error, do NOT claim the job was queued \u2014 report the sanitized result and leave indexing pending. On NO (or any unavailable/non-interactive resolution): do not index; print the exact copy-paste continuation command '/parse-repository' on its own line and state that indexing remains pending. Never request, echo, or transport any credential \u2014 only ever direct the human to the setup UI via the command's configure_in pointer. End with an explicit summary line stating how many config fields the apply_install_manifest call applied (e.g. 'Applied 8 of 9 derived fields') and whether indexing was queued or left pending \u2014 if 0 fields were applied, say so loudly and explain what is still pending.";
+var INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command in the install-spawn context (tell the command it is running in the install-spawn context so it SKIPS its Stage 8 and Stage 9 offers \u2014 this session's only closing interaction is the single indexing question below). Do NOT run /learn-repository. Do NOT call parse_repository (or otherwise start indexing) before the capability report and explicit consent below. Complete the command's read-after-write five-section capability report first: 'Connected \u2713', 'Not yet connected \u2717', 'Tools you can use now', 'Tools you'll unlock', and 'Recommended next step + why'. Only AFTER that report is fully presented, ask exactly one question using this visible prompt: '[Y/n] Index repository now?'. Only an explicit affirmative answer (e.g. 'y'/'yes') starts indexing; a blank answer, a negative answer, EOF, an unavailable interaction, and any non-interactive/headless run all resolve to NO. On an affirmative answer: call the parse_repository MCP tool exactly once, describe the accepted job as QUEUED, and direct later progress checks to get_parse_status or /check-parse-status (do NOT poll it to completion). If parse_repository returns a blocking refusal or error, do NOT claim the job was queued \u2014 report the sanitized result and leave indexing pending. On NO (or any unavailable/non-interactive resolution): do not index; print the exact copy-paste continuation command '/parse-repository' on its own line and state that indexing remains pending. Never request, echo, or transport any credential \u2014 only ever direct the human to that integration's own configure_in pointer, verbatim. The pointer is per-integration and is NOT always the setup UI: GitHub's is a terminal command (connect-github), while Jira, SFCC, and Bitbucket point at the setup UI. Follow whatever the report says rather than assuming. End with an explicit summary line stating how many config fields the apply_install_manifest call applied (e.g. 'Applied 8 of 9 derived fields') and whether indexing was queued or left pending \u2014 if 0 fields were applied, say so loudly and explain what is still pending.";
 var DEFAULT_BAPI_BASE_URL2 = "https://bridgegpt-api.com";
 var DEFAULT_BAPI_DOCS_DIR = "docs/tmp";
 function getInstallBridgeUsage() {
@@ -21632,13 +22239,20 @@ function getInstallBridgeUsage() {
     "routing credential, then opens a fresh agent session to derive the remaining",
     "config, present a capability report, and offer optional repository indexing.",
     "",
+    "Run it bare \u2014 `install-bridge` with no flags \u2014 in a terminal and it asks",
+    `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT.trim()}\` first. Answer yes (or press Enter) for the`,
+    "existing-key flow below; answer no and it asks for an email and creates a new",
+    "Bridge workspace for you (the self-serve flow). That question is asked ONLY for a",
+    "bare interactive run: passing ANY flag, setting BAPI_API_KEY, or running without",
+    "an interactive terminal keeps the existing deterministic behavior and no prompt.",
+    "",
     "Inputs (the only two irreducible ones):",
     "  --api-key <key>   Bridge API key. Falls back to the BAPI_API_KEY env var,",
     "                    then an interactive (no-echo) prompt. Generate one in the",
     "                    Bridge API web UI Security page \u2014 this command consumes a",
-    "                    key, it does not create one (--invite is the one exception:",
-    "                    it CREATES the project and its first admin key). NEVER",
-    "                    printed or logged.",
+    "                    key, it does not create one (--email and --invite are the",
+    "                    exceptions: they CREATE the project and its first admin key).",
+    "                    NEVER printed or logged.",
     "  --repo <name>     Repository name. --repo and BAPI_REPO_NAME still take",
     "                    priority and short-circuit before any network call. When",
     "                    neither is set, a compatible server resolves the unique",
@@ -21646,10 +22260,13 @@ function getInstallBridgeUsage() {
     "                    server is older, the key is unresolvable, or resolution",
     "                    fails, it falls back to an inferred default you confirm",
     "                    interactively (and to a required --repo when stdin is",
-    "                    non-interactive). MUST match the server-side repo",
-    "                    registration (it keys the credential store as bapi:<repo>).",
-    "                    With --invite it is the name your NEW project is created",
-    "                    under (globally unique).",
+    "                    non-interactive). In the existing-key flow it MUST match the",
+    "                    server-side repo registration (it keys the credential store",
+    "                    as bapi:<repo>). In either new-project flow (--email,",
+    "                    --invite, or a negative answer to the key question above) it",
+    "                    instead NAMES the project this run creates, so you are asked",
+    "                    to name a new project rather than match an existing one; the",
+    "                    name must be globally unique.",
     "",
     "Self-serve onboarding (no account, no API key, no pre-issued invite):",
     "  --email <addr>    Create a brand-new Bridge workspace from just an email \u2014",
@@ -21657,8 +22274,10 @@ function getInstallBridgeUsage() {
     "                    It requests a fresh workspace for that email, then creates",
     "                    the project and mints your own admin API key in one command.",
     "                    Falls back to the BAPI_SIGNUP_EMAIL env var, then a visible",
-    "                    interactive prompt. The email is NOT a secret (it is shown",
-    "                    as you type), but it is never printed to a log. Mutually",
+    "                    interactive prompt \u2014 which is also what a negative answer to",
+    "                    the bare-run key question above reaches. The email is NOT a",
+    "                    secret (it is shown as you type), but it is never printed to",
+    "                    a log. Mutually",
     "                    exclusive with --api-key and --invite. No email verification",
     "                    is performed and no message is sent to the address \u2014 it only",
     "                    labels the new workspace.",
@@ -21821,7 +22440,7 @@ function parseInstallBridgeArgs(argv) {
 }
 function promptSecretViaReadline(promptText, input = process.stdin, output = process.stderr) {
   return new Promise((resolve2) => {
-    const rl = readline.createInterface({
+    const rl = readline2.createInterface({
       input,
       output,
       terminal: true
@@ -21848,9 +22467,49 @@ function promptSecretViaReadline(promptText, input = process.stdin, output = pro
     muted = true;
   });
 }
+async function offerGithubConnection(repoName, deps, log) {
+  if (!deps.isTTY || !deps.promptLine) return;
+  try {
+    const credDeps = {
+      env: deps.env,
+      homedir: deps.homedir,
+      platform: deps.platform,
+      readFile: deps.readFile,
+      stat: deps.stat,
+      stderr: () => {
+      }
+    };
+    const cred = await resolveBapiCredentials(repoName, credDeps);
+    if (!cred.ok) return;
+    const api = {
+      fetch: deps.fetch,
+      baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL2,
+      apiKey: cred.credentials.apiKey
+    };
+    const state = await fetchGithubConfigurationState(api, repoName);
+    if (state === "configured") return;
+    if (state === "unavailable") {
+      log("  note: could not read GitHub configuration status; skipping the GitHub offer.");
+      return;
+    }
+    const answer = (await deps.promptLine("Connect GitHub? (Y/n): ")).trim().toLowerCase();
+    if (answer === "n" || answer === "no") return;
+    const connectDeps = createDefaultConnectGithubDeps();
+    const code = await runGithubConnectionFlow(connectDeps, api, repoName);
+    if (code !== 0) {
+      log(
+        `  note: GitHub was not connected. Your install is complete \u2014 connect GitHub later with 'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${repoName}'.`
+      );
+    }
+  } catch {
+    log(
+      `  note: the GitHub connection offer could not run. Your install is complete \u2014 connect GitHub later with 'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${repoName}'.`
+    );
+  }
+}
 function promptLineViaReadline(promptText) {
   return new Promise((resolve2) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    const rl = readline2.createInterface({ input: process.stdin, output: process.stderr });
     let answered = false;
     rl.on("close", () => {
       if (!answered) resolve2("");
@@ -21873,7 +22532,7 @@ function spawnPrewarmDefault(command, args, env) {
   return new Promise((resolve2) => {
     const sanitizedEnv = sanitizePrewarmEnv(env);
     try {
-      const child = spawn6(command, args, {
+      const child = spawn7(command, args, {
         shell: false,
         stdio: "ignore",
         timeout: 6e4,
@@ -21901,12 +22560,12 @@ function createDefaultInstallBridgeDeps() {
     env: process.env,
     cwd: process.cwd(),
     platform: process.platform,
-    homedir: os13.homedir,
+    homedir: os14.homedir,
     isTTY,
-    readFile: (p) => readFile10(p, "utf-8"),
+    readFile: (p) => readFile11(p, "utf-8"),
     writeFile: (p, data, options) => writeFile7(p, data, options),
     mkdir: (p, options) => mkdir7(p, options),
-    stat: (p) => stat7(p),
+    stat: (p) => stat8(p),
     rename: (a, b) => rename(a, b),
     chmod: (p, m) => chmod(p, m),
     unlink: (p) => unlink(p),
@@ -22003,6 +22662,38 @@ function resolveInstallBridgeOnboardingBranch(options, env) {
   if (emailMode) return { kind: "need-key", method: "self-serve" };
   return { kind: "have-key" };
 }
+var INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Do you have a Bridge API key? [Y/n] ";
+async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv) {
+  const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
+  if (branch.kind === "need-key") return { ok: true, branch };
+  const hasEnvApiKey = (deps.env.BAPI_API_KEY ?? "").trim().length > 0;
+  const isBareInvocation = argv.length === 0;
+  if (!deps.isTTY || !deps.promptLine || !isBareInvocation || hasEnvApiKey) {
+    return { ok: true, branch };
+  }
+  const promptLine = deps.promptLine;
+  try {
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const answer = (await promptLine(INSTALL_BRIDGE_KEY_SELECTOR_PROMPT)).trim().toLowerCase();
+      if (answer.length === 0 || answer === "y" || answer === "yes") {
+        return { ok: true, branch: { kind: "have-key" } };
+      }
+      if (answer === "n" || answer === "no") {
+        return { ok: true, branch: { kind: "need-key", method: "self-serve" } };
+      }
+      deps.log("Please answer y or n (press Enter for yes).");
+    }
+    return {
+      ok: false,
+      error: "No valid answer to the Bridge API key question. Re-run and answer y or n."
+    };
+  } catch {
+    return {
+      ok: false,
+      error: "Could not read your answer from the terminal. Re-run with --api-key <key> if you have a Bridge API key, or --email <addr> to create a new Bridge workspace."
+    };
+  }
+}
 function resolveConfiguredRepoName(options, env) {
   if (typeof options.repo === "string" && options.repo.trim().length > 0) {
     return options.repo.trim();
@@ -22013,7 +22704,7 @@ function resolveConfiguredRepoName(options, env) {
   }
   return void 0;
 }
-async function resolveRepoName(options, deps) {
+async function resolveRepoName(options, deps, mode = "existing-registration") {
   const configured = resolveConfiguredRepoName(options, deps.env);
   if (configured !== void 0) {
     return { ok: true, value: configured };
@@ -22021,7 +22712,7 @@ async function resolveRepoName(options, deps) {
   if (!deps.isTTY || !deps.promptLine) {
     return {
       ok: false,
-      error: "A repo name is required. Pass --repo or set the BAPI_REPO_NAME environment variable (no interactive terminal is available to confirm an inferred name). It must match the server-side repository registration."
+      error: mode === "new-project" ? "A project name is required. Pass --repo or set the BAPI_REPO_NAME environment variable (no interactive terminal is available to confirm an inferred name). It names the new Bridge project this run creates and must be globally unique." : "A repo name is required. Pass --repo or set the BAPI_REPO_NAME environment variable (no interactive terminal is available to confirm an inferred name). It must match the server-side repository registration."
     };
   }
   let inferred = await resolveStartTicketsRepoName({
@@ -22030,15 +22721,17 @@ async function resolveRepoName(options, deps) {
     readFile: deps.readFile
   });
   if (!inferred) {
-    const validated = validateRepoName(path23.basename(deps.cwd));
+    const validated = validateRepoName(path24.basename(deps.cwd));
     if (validated.ok) inferred = validated.value;
   }
   if (inferred) {
-    const answer = (await deps.promptLine(`Repo name [${inferred}] (must match server-side registration): `)).trim();
+    const promptText = mode === "new-project" ? `Name your new Bridge project [${inferred}]: ` : `Repo name [${inferred}] (must match server-side registration): `;
+    const answer = (await deps.promptLine(promptText)).trim();
     const chosen = answer.length > 0 ? answer : inferred;
     if (chosen.length > 0) return { ok: true, value: chosen };
   } else {
-    const answer = (await deps.promptLine("Repo name (must match server-side registration): ")).trim();
+    const promptText = mode === "new-project" ? "Name your new Bridge project: " : "Repo name (must match server-side registration): ";
+    const answer = (await deps.promptLine(promptText)).trim();
     if (answer.length > 0) return { ok: true, value: answer };
   }
   return { ok: false, error: "No repo name provided." };
@@ -22049,7 +22742,7 @@ async function resolveHostConfigTargets(deps) {
   ];
   const dirExists = async (rel) => {
     try {
-      await deps.stat(path23.join(deps.cwd, rel));
+      await deps.stat(path24.join(deps.cwd, rel));
       return true;
     } catch {
       return false;
@@ -22096,7 +22789,7 @@ async function readHostConfig(deps, fullPath) {
 }
 async function detectExistingRealKey(deps, targets) {
   for (const target of targets) {
-    const parsed = await readHostConfig(deps, path23.join(deps.cwd, target.relPath));
+    const parsed = await readHostConfig(deps, path24.join(deps.cwd, target.relPath));
     const entry = parsed?.[target.topLevelKey]?.["bridge-api"];
     if (entry?.env && !isPlaceholderApiKey(entry.env.BAPI_API_KEY)) {
       return true;
@@ -22107,13 +22800,13 @@ async function detectExistingRealKey(deps, targets) {
 async function writeHostConfigs(deps, targets, entry) {
   const written = [];
   for (const target of targets) {
-    const fullPath = path23.join(deps.cwd, target.relPath);
+    const fullPath = path24.join(deps.cwd, target.relPath);
     const parsed = await readHostConfig(deps, fullPath) ?? {};
     if (!parsed[target.topLevelKey] || typeof parsed[target.topLevelKey] !== "object") {
       parsed[target.topLevelKey] = {};
     }
     parsed[target.topLevelKey]["bridge-api"] = entry;
-    await deps.mkdir(path23.dirname(fullPath), { recursive: true });
+    await deps.mkdir(path24.dirname(fullPath), { recursive: true });
     await deps.writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", {
       encoding: "utf-8"
     });
@@ -22327,7 +23020,21 @@ function buildDryRunPreview(plan) {
     `Step 3b \u2014 pre-warm the version-pinned launcher bucket (fail-open, env sanitized \u2014 BAPI_API_KEY removed): ${plan.prewarmCommand}`,
     MCP_TIMEOUT_GUIDANCE,
     `Step 4 \u2014 persist routing credential: target ${plan.credentialTarget} at ${plan.credentialStorePath}`,
-    `Step 5 \u2014 spawn agent session: ${plan.spawnCommand}`
+    ...buildLaunchStepPreview(plan)
+  ];
+}
+function buildLaunchStepPreview(plan) {
+  return [
+    // BAPI-631: described, never performed in --dry-run — a preview must not open a
+    // browser or reach the network. It is also strictly optional, so it carries no step
+    // number of its own and never changes the 5-step count.
+    "Step 4b \u2014 optional GitHub connect (SKIPPED in --dry-run): read GitHub's configured state",
+    "          via the install manifest and, only when it is unconfigured and the terminal is",
+    "          interactive, offer 'Connect GitHub? (Y/n)' before the agent session starts.",
+    "Step 5 \u2014 spawn agent session: the full command below is stored in a restricted launch script",
+    "          (mode 0600, under the system temp dir) and only a short sourced runner is spawned",
+    "          (the script itself is NOT written in --dry-run):",
+    `          ${plan.spawnCommand}`
   ];
 }
 function buildBootstrapDryRunPreview(plan) {
@@ -22363,7 +23070,7 @@ function buildBootstrapDryRunPreview(plan) {
     `Step 3b \u2014 pre-warm the version-pinned launcher bucket (fail-open, env sanitized \u2014 BAPI_API_KEY / BAPI_INVITE removed): ${plan.prewarmCommand}`,
     MCP_TIMEOUT_GUIDANCE,
     `Step 4 \u2014 promote ${pendingTarget} \u2192 ${plan.credentialTarget} at ${plan.credentialStorePath} (only after the exchange succeeds)`,
-    `Step 5 \u2014 spawn agent session: ${plan.spawnCommand}`
+    ...buildLaunchStepPreview(plan)
   ];
 }
 async function detectManualEditors(deps) {
@@ -22375,8 +23082,8 @@ async function detectManualEditors(deps) {
       return false;
     }
   };
-  const windsurf = await exists(path23.join(deps.cwd, ".windsurf")) || await exists(path23.join(deps.cwd, ".windsurfrules"));
-  const codex = await exists(path23.join(deps.homedir(), ".codex"));
+  const windsurf = await exists(path24.join(deps.cwd, ".windsurf")) || await exists(path24.join(deps.cwd, ".windsurfrules"));
+  const codex = await exists(path24.join(deps.homedir(), ".codex"));
   return { windsurf, codex };
 }
 function manualEditorNames(editors) {
@@ -22428,7 +23135,12 @@ async function runInstallBridgeCli(argv, overrides = {}) {
     return 1;
   }
   const options = parsed.options;
-  const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
+  const branchResult = await resolveInstallBridgeOnboardingBranchForRun(options, deps, argv);
+  if (!branchResult.ok) {
+    errorLog(`Error: ${branchResult.error}`);
+    return 1;
+  }
+  const branch = branchResult.branch;
   const bootstrapInviteMode = branch.kind === "need-key";
   const selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
   let apiKey = "";
@@ -22461,7 +23173,7 @@ async function runInstallBridgeCli(argv, overrides = {}) {
   let repoName;
   let attemptedServerResolution = false;
   if (bootstrapInviteMode) {
-    const repoResult = await resolveRepoName(options, deps);
+    const repoResult = await resolveRepoName(options, deps, "new-project");
     if (!repoResult.ok) {
       errorLog(`Error: ${repoResult.error}`);
       return 1;
@@ -22483,7 +23195,7 @@ async function runInstallBridgeCli(argv, overrides = {}) {
       if (resolution.status === "resolved") {
         repoName = resolution.repoName;
       } else {
-        const repoResult = await resolveRepoName(options, deps);
+        const repoResult = await resolveRepoName(options, deps, "existing-registration");
         if (!repoResult.ok) {
           errorLog(`Error: ${repoResult.error}`);
           return 1;
@@ -22525,6 +23237,22 @@ async function runInstallBridgeCli(argv, overrides = {}) {
     for (const line of buildDryRunPreview(plan)) log(line);
     return 0;
   }
+  const materialized = await materializeWorkerLaunchCommand(
+    deps.startTicketsDeps,
+    "install",
+    spawnCommand
+  );
+  if (!materialized.ok) {
+    errorLog(`Error: ${materialized.error}`);
+    return 1;
+  }
+  const launchCommand = materialized.command;
+  if (Buffer.byteLength(launchCommand, "utf8") >= MAX_TERMINAL_COMMAND_BYTES) {
+    errorLog(
+      "Error: the agent session command is too long to send to the terminal safely. Check that the system temporary directory is writable so the launch script can be used."
+    );
+    return 1;
+  }
   const credentialWriteDeps = {
     env: deps.env,
     homedir: deps.homedir,
@@ -22747,9 +23475,10 @@ async function runInstallBridgeCli(argv, overrides = {}) {
       );
     }
   }
+  await offerGithubConnection(repoName, deps, log);
   log(`Step 5/5 \u2014 opening a ${agent.name} session for /install-bridge configuration + capability report\u2026`);
   const terminal = detectTerminal(void 0, deps.env);
-  const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, spawnCommand, {
+  const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, launchCommand, {
     key: "install",
     worktreePath: deps.cwd
   });
@@ -22771,9 +23500,9 @@ async function runInstallBridgeCli(argv, overrides = {}) {
 
 // src/upgrade-cli.ts
 init_version_generated();
-import { spawn as spawn7 } from "child_process";
-import { stat as stat8 } from "fs/promises";
-import path24 from "path";
+import { spawn as spawn8 } from "child_process";
+import { stat as stat9 } from "fs/promises";
+import path25 from "path";
 init_start_tickets();
 init_agent_registry();
 async function fetchLatestVersion() {
@@ -22813,7 +23542,7 @@ async function runUpgradeCli(argv) {
           "--old-version",
           VERSION
         ];
-        const child = spawn7(npxCmd, childArgs, { stdio: "inherit", cwd });
+        const child = spawn8(npxCmd, childArgs, { stdio: "inherit", cwd });
         child.on("close", (code) => resolve2(code ?? 0));
         child.on("error", (err) => {
           console.error(`Bridge API upgrade failed: could not re-exec npx: ${err.message}`);
@@ -22840,7 +23569,7 @@ async function runUpgradeCli(argv) {
     );
     for (const target of configTargets) {
       try {
-        await stat8(path24.join(cwd, target));
+        await stat9(path25.join(cwd, target));
         console.log(`    - ${target}`);
       } catch {
       }
@@ -22859,14 +23588,14 @@ async function runUpgradeCli(argv) {
     return 0;
   }
   try {
-    const localModulePath = path24.join(cwd, "node_modules", "@bridge_gpt", "mcp-server");
-    await stat8(localModulePath);
+    const localModulePath = path25.join(cwd, "node_modules", "@bridge_gpt", "mcp-server");
+    await stat9(localModulePath);
     console.log(
       "Found stale local installation in node_modules. Removing to converge on pinned-npx..."
     );
     const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
     await new Promise((resolve2) => {
-      const child = spawn7(npmCmd, ["uninstall", "@bridge_gpt/mcp-server"], {
+      const child = spawn8(npmCmd, ["uninstall", "@bridge_gpt/mcp-server"], {
         stdio: "inherit",
         cwd
       });
@@ -22926,18 +23655,18 @@ ${spawnCommand}
 init_credential_store();
 
 // src/credentials-cli.ts
-import { readFile as readFile11, mkdir as mkdir8, writeFile as writeFile8, rename as rename2, chmod as chmod2, unlink as unlink2 } from "fs/promises";
-import os14 from "os";
-import readline2 from "readline";
+import { readFile as readFile12, mkdir as mkdir8, writeFile as writeFile8, rename as rename2, chmod as chmod2, unlink as unlink2 } from "fs/promises";
+import os15 from "os";
+import readline3 from "readline";
 
 // src/agent-config-credential-migration.ts
 init_credential_store();
 init_start_tickets_repo();
-import path25 from "path";
-async function readAgentMcpConfigIfPresent(filePath, readFile14) {
+import path26 from "path";
+async function readAgentMcpConfigIfPresent(filePath, readFile15) {
   let raw;
   try {
-    raw = await readFile14(filePath);
+    raw = await readFile15(filePath);
   } catch (err) {
     const code = err && typeof err === "object" ? err.code : void 0;
     if (code === "ENOENT") {
@@ -22995,7 +23724,7 @@ function resolveAgentConfigScanTargets(cwd, sources) {
   const selected = sources && sources.length > 0 ? AGENT_CONFIG_SOURCE_NAMES.filter((name) => sources.includes(name)) : AGENT_CONFIG_SOURCE_NAMES;
   return selected.map((name) => ({
     name,
-    filePath: name === ".mcp.json" ? path25.join(cwd, ".mcp.json") : path25.join(cwd, ".cursor", "mcp.json")
+    filePath: name === ".mcp.json" ? path26.join(cwd, ".mcp.json") : path26.join(cwd, ".cursor", "mcp.json")
   }));
 }
 async function scanAgentMcpConfigsForBapiApiKey(deps) {
@@ -23185,7 +23914,7 @@ function parseCredentialsArgs(argv) {
 }
 function promptChoiceViaReadline(candidates) {
   return new Promise((resolve2) => {
-    const rl = readline2.createInterface({ input: process.stdin, output: process.stderr });
+    const rl = readline3.createInterface({ input: process.stdin, output: process.stderr });
     process.stderr.write(
       "Multiple, conflicting BAPI_API_KEY values were found. Choose a source:\n"
     );
@@ -23214,8 +23943,8 @@ function createDefaultCredentialsDeps(writeCredentials) {
     env: process.env,
     cwd: process.cwd(),
     platform: process.platform,
-    homedir: os14.homedir,
-    readFile: (p) => readFile11(p, "utf-8"),
+    homedir: os15.homedir,
+    readFile: (p) => readFile12(p, "utf-8"),
     mkdir: (p, o) => mkdir8(p, o),
     writeFile: (p, d, o) => writeFile8(p, d, o),
     rename: (a, b) => rename2(a, b),
@@ -23774,8 +24503,8 @@ async function getSfccVersionConfig(buildGetUrl2, getGetHeaders2, repoName) {
 }
 
 // src/sfcc/credentials.ts
-import { readFile as readFile12, writeFile as writeFile9, mkdir as mkdir9 } from "fs/promises";
-import path26 from "path";
+import { readFile as readFile13, writeFile as writeFile9, mkdir as mkdir9 } from "fs/promises";
+import path27 from "path";
 var ENV_HOSTNAME = "SFCC_HOSTNAME";
 var ENV_CLIENT_ID = "SFCC_CLIENT_ID";
 var ENV_CLIENT_SECRET = "SFCC_CLIENT_SECRET";
@@ -23818,14 +24547,14 @@ async function resolveSfccCredentials(explicitHostname, env = process.env, deps
     };
   }
   const cwd = deps.cwd ?? process.cwd();
-  const rf = deps.readFile ?? ((p) => readFile12(p, "utf-8"));
+  const rf = deps.readFile ?? ((p) => readFile13(p, "utf-8"));
   const wf = deps.writeFile ?? ((p, data) => writeFile9(p, data, "utf-8"));
   const mk = deps.mkdir ?? ((p, opts) => mkdir9(p, opts));
   try {
     await ensureGitInfoExcluded(cwd, DW_JSON, { readFile: rf, writeFile: wf, mkdir: mk });
   } catch {
   }
-  const dwJsonPath = path26.join(cwd, DW_JSON);
+  const dwJsonPath = path27.join(cwd, DW_JSON);
   let dwJson;
   try {
     const raw = await rf(dwJsonPath);
@@ -23898,11 +24627,11 @@ function mapOcapiWriteFault(status, body) {
     errorCode: known ? expected : "OCAPI_WRITE_FAULT"
   };
 }
-function buildSyntheticIfMatchRequiredBody(path34) {
+function buildSyntheticIfMatchRequiredBody(path35) {
   return {
     fault: {
       type: "IfMatchRequiredException",
-      message: `PATCH ${path34} requires an ETag (If-Match) captured from the GET round trip, but the GET response returned no ETag header. Cannot safely issue a conditional PATCH.`
+      message: `PATCH ${path35} requires an ETag (If-Match) captured from the GET round trip, but the GET response returned no ETag header. Cannot safely issue a conditional PATCH.`
     }
   };
 }
@@ -23952,9 +24681,9 @@ async function getAmToken(credentials) {
 function invalidateAmToken(credentials) {
   tokenCache.delete(credentials.hostname);
 }
-function buildOcapiUrl(hostname, ocapiVersion, path34) {
+function buildOcapiUrl(hostname, ocapiVersion, path35) {
   const baseUrl = `https://${hostname}/s/-/dw/data/${ocapiVersion}`;
-  return `${baseUrl}${path34.startsWith("/") ? path34 : "/" + path34}`;
+  return `${baseUrl}${path35.startsWith("/") ? path35 : "/" + path35}`;
 }
 async function parseOcapiResponse(resp) {
   try {
@@ -23978,7 +24707,7 @@ function sleep2(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 var MAX_RETRY_AFTER_MS = 5e3;
-function parseRetryAfterMs(headerValue) {
+function parseRetryAfterMs2(headerValue) {
   if (!headerValue) return void 0;
   const trimmed = headerValue.trim();
   if (trimmed === "") return void 0;
@@ -23998,17 +24727,17 @@ async function fetchWith429Backoff(url, init) {
   for (let attempt = 0; attempt < BACKOFF_SCHEDULE_MS.length; attempt++) {
     if (resp.status !== 429) return resp;
     const retryAfterHeader = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("retry-after") : null;
-    const retryAfter = parseRetryAfterMs(retryAfterHeader);
+    const retryAfter = parseRetryAfterMs2(retryAfterHeader);
     const backoff = retryAfter !== void 0 ? Math.min(retryAfter, MAX_RETRY_AFTER_MS) : BACKOFF_SCHEDULE_MS[attempt];
     await sleep2(backoff);
     resp = await fetch(url, init);
   }
   return resp;
 }
-async function ocapiRequest(method, path34, body, credentials, ocapiVersion, extraHeaders) {
+async function ocapiRequest(method, path35, body, credentials, ocapiVersion, extraHeaders) {
   const doRequest = async () => {
     const token = await getAmToken(credentials);
-    const url = buildOcapiUrl(credentials.hostname, ocapiVersion, path34);
+    const url = buildOcapiUrl(credentials.hostname, ocapiVersion, path35);
     const init = {
       method,
       headers: {
@@ -24041,23 +24770,23 @@ async function ocapiRequest(method, path34, body, credentials, ocapiVersion, ext
   }
   return first;
 }
-async function ocapiGet(path34, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("GET", path34, void 0, credentials, ocapiVersion);
+async function ocapiGet(path35, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("GET", path35, void 0, credentials, ocapiVersion);
 }
-async function ocapiPost(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("POST", path34, body, credentials, ocapiVersion);
+async function ocapiPost(path35, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("POST", path35, body, credentials, ocapiVersion);
 }
-async function ocapiPut(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("PUT", path34, body, credentials, ocapiVersion);
+async function ocapiPut(path35, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("PUT", path35, body, credentials, ocapiVersion);
 }
-async function ocapiPatch(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  const getResult = await ocapiGet(path34, credentials, ocapiVersion);
+async function ocapiPatch(path35, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  const getResult = await ocapiGet(path35, credentials, ocapiVersion);
   if (!getResult.ok) {
     return getResult;
   }
   const etag = getResult.etag;
   if (etag === null || etag === void 0 || etag.trim() === "") {
-    const syntheticBody = buildSyntheticIfMatchRequiredBody(path34);
+    const syntheticBody = buildSyntheticIfMatchRequiredBody(path35);
     return {
       ok: false,
       status: 409,
@@ -24065,10 +24794,10 @@ async function ocapiPatch(path34, body, credentials, ocapiVersion = DEFAULT_OCAP
       fault: mapOcapiWriteFault(409, syntheticBody)
     };
   }
-  return ocapiRequest("PATCH", path34, body, credentials, ocapiVersion, { "If-Match": etag });
+  return ocapiRequest("PATCH", path35, body, credentials, ocapiVersion, { "If-Match": etag });
 }
-async function ocapiPatchDirect(path34, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
-  return ocapiRequest("PATCH", path34, body, credentials, ocapiVersion);
+async function ocapiPatchDirect(path35, body, credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+  return ocapiRequest("PATCH", path35, body, credentials, ocapiVersion);
 }
 
 // src/sfcc/setup-status.ts
@@ -24277,12 +25006,12 @@ function formatOcapiWriteGrantJson(ocapiVersion, clientIdPlaceholder = "<YOUR_CL
   return JSON.stringify(buildOcapiWriteGrantSettings(ocapiVersion, clientIdPlaceholder), null, 2);
 }
 function buildOcapiWriteGrant403Text(params) {
-  const { operation, path: path34, ocapiVersion, body } = params;
+  const { operation, path: path35, ocapiVersion, body } = params;
   const bodyLine = body === void 0 ? "" : `
 Response body:
 ${JSON.stringify(body, null, 2)}
 `;
-  return `HTTP 403: OCAPI write access denied for ${operation} ${path34}.
+  return `HTTP 403: OCAPI write access denied for ${operation} ${path35}.
 ` + bodyLine + `
 To grant write access, paste the JSON below in Business Manager:
   Administration > Site Development > Open Commerce API Settings \u2192 Data API tab
@@ -24405,11 +25134,11 @@ Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`;
 }
 
 // src/sfcc/reads-system-object.ts
-import path28 from "path";
+import path29 from "path";
 import { z as z3 } from "zod";
 
 // src/sfcc/output.ts
-import path27 from "path";
+import path28 from "path";
 import { mkdir as mkdir10, writeFile as writeFile10 } from "fs/promises";
 var SFCC_MAX_INLINE = 5e4;
 function truncationNote(savedPath) {
@@ -24423,7 +25152,7 @@ async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
   }
   const mk = deps.mkdir ?? mkdir10;
   const wf = deps.writeFile ?? writeFile10;
-  const filePath = path27.join(dir, filename);
+  const filePath = path28.join(dir, filename);
   try {
     await mk(dir, { recursive: true });
     await wf(filePath, text, "utf-8");
@@ -24491,7 +25220,7 @@ function buildSystemObjectListHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path28.join(await getDocsDir2(), "sfcc");
+      const dir = path29.join(await getDocsDir2(), "sfcc");
       return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`);
     }
   );
@@ -24514,7 +25243,7 @@ function buildSystemObjectGetHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path28.join(await getDocsDir2(), "sfcc");
+      const dir = path29.join(await getDocsDir2(), "sfcc");
       return saveAndReturn(
         text,
         dir,
@@ -24546,7 +25275,7 @@ function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path28.join(await getDocsDir2(), "sfcc");
+      const dir = path29.join(await getDocsDir2(), "sfcc");
       return saveAndReturn(
         text,
         dir,
@@ -24587,7 +25316,7 @@ function registerSystemObjectReadTools(registerTool2, deps) {
 }
 
 // src/sfcc/reads-custom-object-def.ts
-import path29 from "path";
+import path30 from "path";
 import { z as z4 } from "zod";
 var READ_ANNOTATIONS2 = {
   readOnlyHint: true,
@@ -24641,7 +25370,7 @@ function buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path29.join(await getDocsDir2(), "sfcc");
+      const dir = path30.join(await getDocsDir2(), "sfcc");
       return saveAndReturn2(
         text,
         dir,
@@ -24673,7 +25402,7 @@ function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path29.join(await getDocsDir2(), "sfcc");
+      const dir = path30.join(await getDocsDir2(), "sfcc");
       return saveAndReturn2(
         text,
         dir,
@@ -24705,7 +25434,7 @@ function registerSfccCustomObjectDefReadTools(registerTool2, deps) {
 }
 
 // src/sfcc/reads-site-preference.ts
-import path30 from "path";
+import path31 from "path";
 import { z as z5 } from "zod";
 var READ_ANNOTATIONS3 = {
   readOnlyHint: true,
@@ -24785,7 +25514,7 @@ function buildSitePreferenceGetHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path30.join(await getDocsDir2(), "sfcc");
+      const dir = path31.join(await getDocsDir2(), "sfcc");
       return saveAndReturn3(
         text,
         dir,
@@ -24819,7 +25548,7 @@ function buildSitePreferenceSearchHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path30.join(await getDocsDir2(), "sfcc");
+      const dir = path31.join(await getDocsDir2(), "sfcc");
       return saveAndReturn3(
         text,
         dir,
@@ -24848,7 +25577,7 @@ function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir2) {
       }
       const normalized = normalizeOcapiBody(result.body);
       const text = JSON.stringify(normalized, null, 2);
-      const dir = path30.join(await getDocsDir2(), "sfcc");
+      const dir = path31.join(await getDocsDir2(), "sfcc");
       return saveAndReturn3(
         text,
         dir,
@@ -24911,11 +25640,11 @@ function rejectIfNotSandboxForWrite(instance) {
 function textResult5(text) {
   return { content: [{ type: "text", text }] };
 }
-function formatOcapiWriteToolResult(result, operation, path34, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+function formatOcapiWriteToolResult(result, operation, path35, ocapiVersion = DEFAULT_OCAPI_VERSION) {
   if (result.status === 403) {
     return writeGrantForbiddenResult({
       operation,
-      path: path34,
+      path: path35,
       ocapiVersion,
       body: result.body
     });
@@ -25173,20 +25902,20 @@ function buildCreateAttributeDefinitionHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path34;
+      let path35;
       let body;
       try {
         const parsed = createAttributeDefinitionInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path34 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+        path35 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
         body = buildObjectAttributeDefinitionCreatePayload(parsed.attribute_id, parsed.definition);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path34);
+        const result = await ocapiPut(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path35);
       } catch {
         return unexpectedEnvelope();
       }
@@ -25197,20 +25926,20 @@ function buildUpdateAttributeDefinitionHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path34;
+      let path35;
       let body;
       try {
         const parsed = updateAttributeDefinitionInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path34 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+        path35 = attributeDefinitionPath(parsed.object_type, parsed.attribute_id);
         body = buildObjectAttributeDefinitionPatchPayload(parsed.attribute_id, parsed.patch);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPatch(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path34);
+        const result = await ocapiPatch(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path35);
       } catch {
         return unexpectedEnvelope();
       }
@@ -25221,13 +25950,13 @@ function buildCreateAttributeGroupHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path34;
+      let path35;
       let body;
       try {
         const parsed = createAttributeGroupInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path34 = attributeGroupPath(parsed.object_type, parsed.group_id);
+        path35 = attributeGroupPath(parsed.object_type, parsed.group_id);
         body = buildAttributeGroupPutPayload({
           display_name: parsed.display_name,
           internal: parsed.internal
@@ -25236,8 +25965,8 @@ function buildCreateAttributeGroupHandler(gateDeps) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path34);
+        const result = await ocapiPut(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path35);
       } catch {
         return unexpectedEnvelope();
       }
@@ -25248,20 +25977,20 @@ function buildUpdateAttributeGroupHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path34;
+      let path35;
       let body;
       try {
         const parsed = updateAttributeGroupInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path34 = attributeGroupPath(parsed.object_type, parsed.group_id);
+        path35 = attributeGroupPath(parsed.object_type, parsed.group_id);
         body = buildAttributeGroupPatchPayload(parsed.patch);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPatch(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path34);
+        const result = await ocapiPatch(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path35);
       } catch {
         return unexpectedEnvelope();
       }
@@ -25272,12 +26001,12 @@ function buildAssignAttributeToGroupHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path34;
+      let path35;
       try {
         const parsed = assignAttributeToGroupInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
-        path34 = attributeGroupAssignmentPath(
+        path35 = attributeGroupAssignmentPath(
           parsed.object_type,
           parsed.group_id,
           parsed.attribute_id
@@ -25286,8 +26015,8 @@ function buildAssignAttributeToGroupHandler(gateDeps) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path34, buildEmptyRelationPayload(), credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path34);
+        const result = await ocapiPut(path35, buildEmptyRelationPayload(), credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path35);
       } catch {
         return unexpectedEnvelope();
       }
@@ -25298,21 +26027,21 @@ function buildCreateCustomPreferenceDefinitionHandler(gateDeps) {
   return withSfccGate(
     gateDeps,
     async (args, credentials) => {
-      let path34;
+      let path35;
       let body;
       try {
         const parsed = createCustomPreferenceDefinitionInput.parse(args);
         const guard = rejectIfNotSandboxForWrite(parsed.instance);
         if (guard) return guard;
         const objectType = preferenceObjectTypeForScope(parsed.preference_scope);
-        path34 = attributeDefinitionPath(objectType, parsed.preference_id);
+        path35 = attributeDefinitionPath(objectType, parsed.preference_id);
         body = buildObjectAttributeDefinitionCreatePayload(parsed.preference_id, parsed.definition);
       } catch (err) {
         return preTransportErrorEnvelope(err);
       }
       try {
-        const result = await ocapiPut(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path34);
+        const result = await ocapiPut(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path35);
       } catch {
         return unexpectedEnvelope();
       }
@@ -25527,11 +26256,11 @@ function buildCreateCustomObjectAttributeDefinitionHandler(gateDeps) {
           `Body id '${parsed.definition.id}' does not match URL attribute_id '${parsed.attribute_id}'.`
         );
       }
-      const path34 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+      const path35 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
       const body = buildObjectAttributeDefinitionCreatePayload2(parsed.attribute_id, parsed.definition);
       try {
-        const result = await ocapiPut(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PUT", path34);
+        const result = await ocapiPut(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PUT", path35);
       } catch {
         return unexpectedEnvelope2();
       }
@@ -25550,11 +26279,11 @@ function buildUpdateCustomObjectAttributeDefinitionHandler(gateDeps) {
       }
       const guard = rejectIfNotSandboxForWrite(parsed.instance);
       if (guard) return guard;
-      const path34 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
+      const path35 = customObjectAttributeDefinitionPath(parsed.object_type, parsed.attribute_id);
       const body = buildObjectAttributeDefinitionPatchPayload2(parsed.patch);
       try {
-        const result = await ocapiPatch(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path34);
+        const result = await ocapiPatch(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path35);
       } catch {
         return unexpectedEnvelope2();
       }
@@ -25645,11 +26374,11 @@ function buildSitePreferenceValuesSetHandler(gateDeps) {
       }
       const guard = rejectIfNotSandboxForWrite(parsed.instance);
       if (guard) return guard;
-      const path34 = sitePreferenceGroupPath(parsed.group);
+      const path35 = sitePreferenceGroupPath(parsed.group);
       const body = buildSitePreferenceValuesPatchPayload(parsed.values);
       try {
-        const result = await ocapiPatchDirect(path34, body, credentials);
-        return formatOcapiWriteToolResult(result, "PATCH", path34);
+        const result = await ocapiPatchDirect(path35, body, credentials);
+        return formatOcapiWriteToolResult(result, "PATCH", path35);
       } catch {
         return unexpectedEnvelope2();
       }
@@ -27418,10 +28147,26 @@ var SystemGoalNfrSchema = z15.object({
     "confirmed = explicitly stated or observable in code; assumed = low-risk and reversible default; open = unresolved (also surface as an actionable_items card)."
   )
 });
+var AcceptanceCriterionSchema = z15.object({
+  id: z15.string().min(1).regex(
+    /^[A-Za-z0-9_-]+$/,
+    "id must contain only letters, digits, hyphens, or underscores"
+  ).describe("Stable per-criterion id, e.g. AC-1. Becomes the captured-feedback JSON key."),
+  criterion: z15.string().min(1).describe("What the system must do, stated concretely enough to be verified."),
+  verification: z15.string().min(1).describe(
+    "How we would confirm this criterion is met. Required \u2014 a criterion with no way to check it is not yet a criterion."
+  ),
+  status: z15.enum(["confirmed", "assumed", "open"]).describe(
+    "confirmed = explicitly stated or observable in code; assumed = low-risk and reversible default; open = unresolved."
+  )
+});
 var SystemGoalsSchema = z15.object({
   business_goal: z15.string().min(1).describe("The business goal this work serves."),
   desired_end_state: z15.string().min(1).describe("The end-state the system should reach."),
   system_behavior: z15.string().min(1).describe("How the system must behave / complete its task (quality attributes in prose)."),
+  acceptance_criteria: z15.array(AcceptanceCriterionSchema).optional().default([]).describe(
+    "What the system must do, as verifiable criteria. Implementation options should be derived from these rather than the reverse."
+  ),
   nfrs: z15.array(SystemGoalNfrSchema).optional().default([])
 });
 var ImplementationOrderItemSchema = z15.object({
@@ -27436,7 +28181,7 @@ var DecisionPageInputShape = {
     '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."
+    "pre_ticket_planning only: business goal, desired end-state, system behavior, acceptance criteria (what the system must do), and classified NFRs (the standards it must meet). Acceptance criteria and NFRs render with per-item stance controls. Unresolved (open) NFRs should ALSO be passed as actionable_items so the human can decide them."
   ),
   implementation_order: z15.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."
@@ -27489,7 +28234,7 @@ var DecisionPageLeanInputShape = {
 
 // src/brainstorm-files.ts
 import { writeFile as writeFile11, mkdir as mkdir11 } from "fs/promises";
-import path31 from "path";
+import path32 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(/-$/, "");
 }
@@ -27514,7 +28259,7 @@ async function saveBrainstormResultsToDir(envelope, dir, subject) {
       continue;
     }
     const filename = buildBrainstormResultFilename(envelope, row, subject);
-    const filePath = path31.join(dir, filename);
+    const filePath = path32.join(dir, filename);
     try {
       await mkdir11(dir, { recursive: true });
       await writeFile11(filePath, markdown, "utf-8");
@@ -29263,7 +30008,7 @@ async function resumeFullAutomation(deps, input) {
 }
 
 // src/visual-diff.ts
-import path32 from "path";
+import path33 from "path";
 import { Worker } from "worker_threads";
 
 // src/visual-diff-worker.ts
@@ -29635,12 +30380,12 @@ function toUint8(bytes) {
 }
 async function resolveCompRef(compRef, deps) {
   const candidates = [];
-  if (path32.isAbsolute(compRef)) {
+  if (path33.isAbsolute(compRef)) {
     candidates.push(compRef);
   } else {
     const root = await deps.getProjectRoot();
-    candidates.push(path32.resolve(root, compRef));
-    const cwdCandidate = path32.resolve(process.cwd(), compRef);
+    candidates.push(path33.resolve(root, compRef));
+    const cwdCandidate = path33.resolve(process.cwd(), compRef);
     if (!candidates.includes(cwdCandidate)) candidates.push(cwdCandidate);
   }
   for (const candidate of candidates) {
@@ -29664,9 +30409,9 @@ async function resolveCompRef(compRef, deps) {
   try {
     const dir = await deps.getDocsPath("visual-diffs");
     const rawName = fetched.filename || (lookup.kind === "attachment_id" ? `attachment-${lookup.attachment_id}` : lookup.filename);
-    const base = path32.basename(rawName);
-    const target = path32.resolve(dir, `comp-${deps.safeTimestampForFilename()}-${base}`);
-    if (!target.startsWith(path32.resolve(dir) + path32.sep)) {
+    const base = path33.basename(rawName);
+    const target = path33.resolve(dir, `comp-${deps.safeTimestampForFilename()}-${base}`);
+    if (!target.startsWith(path33.resolve(dir) + path33.sep)) {
       warnings.push("Skipped saving attachment comp copy: resolved path escaped the visual-diffs directory.");
     } else {
       await deps.mkdir(dir, { recursive: true });
@@ -29909,8 +30654,8 @@ function runInWorker(args) {
 async function saveHeatmap(heatmapBase64, deps) {
   try {
     const dir = await deps.getDocsPath("visual-diffs");
-    const target = path32.resolve(dir, `visual-diff-${deps.safeTimestampForFilename()}.png`);
-    if (!target.startsWith(path32.resolve(dir) + path32.sep)) {
+    const target = path33.resolve(dir, `visual-diff-${deps.safeTimestampForFilename()}.png`);
+    if (!target.startsWith(path33.resolve(dir) + path33.sep)) {
       return { ok: false, warning: "Heatmap not saved: resolved path escaped the visual-diffs directory." };
     }
     await deps.mkdir(dir, { recursive: true });
@@ -30111,10 +30856,10 @@ async function getResolvedApiKey() {
       try {
         const result = await resolveBapiCredentials(REPO_NAME, {
           env: process.env,
-          homedir: os15.homedir,
+          homedir: os16.homedir,
           platform: process.platform,
-          readFile: (p) => readFile13(p, "utf-8"),
-          stat: (p) => stat9(p)
+          readFile: (p) => readFile14(p, "utf-8"),
+          stat: (p) => stat10(p)
         });
         return result.ok ? result.credentials.apiKey : "";
       } catch {
@@ -30128,10 +30873,10 @@ async function getResolvedApiKeyForRepo(repoName) {
   try {
     const result = await resolveBapiCredentials(repoName, {
       env: process.env,
-      homedir: os15.homedir,
+      homedir: os16.homedir,
       platform: process.platform,
-      readFile: (p) => readFile13(p, "utf-8"),
-      stat: (p) => stat9(p)
+      readFile: (p) => readFile14(p, "utf-8"),
+      stat: (p) => stat10(p)
     });
     return result.ok ? result.credentials.apiKey : "";
   } catch {
@@ -30141,9 +30886,9 @@ async function getResolvedApiKeyForRepo(repoName) {
 function buildCredentialStoreWriteDeps() {
   return {
     env: process.env,
-    homedir: os15.homedir,
+    homedir: os16.homedir,
     platform: process.platform,
-    readFile: (p) => readFile13(p, "utf-8"),
+    readFile: (p) => readFile14(p, "utf-8"),
     mkdir: (p, options) => mkdir12(p, options),
     writeFile: (p, data, options) => writeFile12(p, data, options),
     rename: (oldPath, newPath) => rename3(oldPath, newPath),
@@ -30212,39 +30957,39 @@ async function getProjectRoot() {
 var docsDirPromise;
 async function getDocsDir() {
   if (!docsDirPromise) {
-    docsDirPromise = (async () => path33.resolve(await getProjectRoot(), process.env.BAPI_DOCS_DIR ?? "docs/tmp"))();
+    docsDirPromise = (async () => path34.resolve(await getProjectRoot(), process.env.BAPI_DOCS_DIR ?? "docs/tmp"))();
   }
   return docsDirPromise;
 }
 var pipelinesDirPromise;
 async function getPipelinesDir() {
   if (!pipelinesDirPromise) {
-    pipelinesDirPromise = (async () => path33.resolve(await getProjectRoot(), process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines"))();
+    pipelinesDirPromise = (async () => path34.resolve(await getProjectRoot(), process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines"))();
   }
   return pipelinesDirPromise;
 }
-function buildUrl(path34) {
-  return `${BASE_URL.replace(/\/+$/, "")}/jira${path34}`;
+function buildUrl(path35) {
+  return `${BASE_URL.replace(/\/+$/, "")}/jira${path35}`;
 }
-function buildApiUrl(path34) {
-  return `${BASE_URL.replace(/\/+$/, "")}${path34}`;
+function buildApiUrl(path35) {
+  return `${BASE_URL.replace(/\/+$/, "")}${path35}`;
 }
-function buildGetUrl(path34, params) {
-  const url = new URL(buildUrl(path34));
+function buildGetUrl(path35, params) {
+  const url = new URL(buildUrl(path35));
   for (const [key, value] of Object.entries(params)) {
     url.searchParams.set(key, value);
   }
   return url.toString();
 }
 async function getDocsPath(subdir) {
-  return path33.join(await getDocsDir(), subdir);
+  return path34.join(await getDocsDir(), subdir);
 }
 var customPipelinesPromise;
 async function ensureCustomPipelinesLoaded() {
   if (!customPipelinesPromise) {
     customPipelinesPromise = (async () => {
       const pipelinesDir = await getPipelinesDir();
-      const instructionsDir = path33.join(path33.dirname(pipelinesDir), "instructions");
+      const instructionsDir = path34.join(path34.dirname(pipelinesDir), "instructions");
       const customResult = await loadCustomPipelines(
         pipelinesDir,
         instructionsDir,
@@ -30329,7 +31074,7 @@ async function createTicketRequest(params) {
   return handleResponse(resp);
 }
 async function saveLocally(dir, filename, content) {
-  const filePath = path33.join(dir, filename);
+  const filePath = path34.join(dir, filename);
   try {
     await mkdir12(dir, { recursive: true });
     await writeFile12(filePath, content, "utf-8");
@@ -30349,14 +31094,14 @@ function safeTimestampForFilename() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 }
 function safeTicketFileSegment(ticketNumber) {
-  const base = path33.basename(ticketNumber.trim());
+  const base = path34.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 = path33.resolve(dir);
-  const target = path33.resolve(resolvedDir, filename);
-  return target.startsWith(resolvedDir + path33.sep);
+  const resolvedDir = path34.resolve(dir);
+  const target = path34.resolve(resolvedDir, filename);
+  return target.startsWith(resolvedDir + path34.sep);
 }
 function saveLocallySucceeded(note) {
   return note.includes("Saved to ");
@@ -30406,7 +31151,7 @@ async function resolveTextOrFile(textValue, filePath, textLabel) {
   let note = "";
   if (filePath) {
     try {
-      const fileStat = await stat9(filePath);
+      const fileStat = await stat10(filePath);
       if (fileStat.size > 1048576) {
         return {
           ok: false,
@@ -30418,7 +31163,7 @@ async function resolveTextOrFile(textValue, filePath, textLabel) {
           }
         };
       }
-      resolvedText = await readFile13(filePath, "utf-8");
+      resolvedText = await readFile14(filePath, "utf-8");
       if (textValue) {
         note = `
 
@@ -30465,7 +31210,7 @@ var ALLOWED_BINARY_UPLOAD_MIME_TYPES = Array.from(
   new Set(Object.values(ALLOWED_BINARY_UPLOAD_MIME_BY_EXTENSION))
 ).sort();
 function deriveAllowedBinaryUploadMimeType(effectiveFileName) {
-  const ext = path33.extname(effectiveFileName).toLowerCase();
+  const ext = path34.extname(effectiveFileName).toLowerCase();
   return ALLOWED_BINARY_UPLOAD_MIME_BY_EXTENSION[ext];
 }
 async function resolveUploadAttachment(textValue, filePath, textLabel, effectiveFileName) {
@@ -30484,7 +31229,7 @@ async function resolveUploadAttachment(textValue, filePath, textLabel, effective
     return { ok: true, text: textValue, encoding: void 0, note: "" };
   }
   try {
-    const fileStat = await stat9(filePath);
+    const fileStat = await stat10(filePath);
     if (fileStat.size > 10 * 1024 * 1024) {
       return {
         ok: false,
@@ -30496,8 +31241,8 @@ async function resolveUploadAttachment(textValue, filePath, textLabel, effective
         }
       };
     }
-    const ext = path33.extname(filePath).toLowerCase();
-    const buf = await readFile13(filePath);
+    const ext = path34.extname(filePath).toLowerCase();
+    const buf = await readFile14(filePath);
     let isBinary = BINARY_EXTENSIONS.has(ext);
     if (!isBinary) {
       try {
@@ -30881,7 +31626,7 @@ Raw body: ${result.text}`
 }
 async function ensurePackageJsonForCliCommand(flagName, cwd) {
   try {
-    await stat9(path33.join(cwd, "package.json"));
+    await stat10(path34.join(cwd, "package.json"));
     return null;
   } catch {
     return `Error: No package.json found in current directory.
@@ -30944,6 +31689,9 @@ async function dispatchCliSubcommand(argv) {
   if (argv[0] === "install-bridge") {
     return runInstallBridgeCli(argv.slice(1));
   }
+  if (argv[0] === "connect-github") {
+    return runConnectGithubCli(argv.slice(1));
+  }
   if (argv[0] === "upgrade") {
     return runUpgradeCli(argv.slice(1));
   }
@@ -31345,8 +32093,8 @@ registerTool(
       getProjectRoot,
       getDocsPath,
       safeTimestampForFilename,
-      readFile: (p) => readFile13(p),
-      stat: (p) => stat9(p),
+      readFile: (p) => readFile14(p),
+      stat: (p) => stat10(p),
       mkdir: (p, opts) => mkdir12(p, opts),
       writeFile: (p, data) => writeFile12(p, data),
       fetchAttachmentBytes: fetchVisualDiffAttachmentBytes,
@@ -31846,7 +32594,7 @@ registerTool(
     switch (args.operation) {
       case "upload": {
         const { ticket_number, file_path, content, file_name, link_type, replace_existing } = args;
-        const derivedFileName = file_name || (file_path ? path33.basename(file_path) : `${ticket_number}-attachment.md`);
+        const derivedFileName = file_name || (file_path ? path34.basename(file_path) : `${ticket_number}-attachment.md`);
         const resolved = await resolveUploadAttachment(content, file_path, "content", derivedFileName);
         if (!resolved.ok) return resolved.errorResponse;
         const payload = {
@@ -31906,12 +32654,12 @@ registerTool(
         const isText = body.is_text;
         const mimeType = body.mime_type;
         const size = body.size;
-        const safeFileName = path33.basename(serverFilename);
-        const safeTicket = path33.basename(ticket_number);
-        const savePath = file_path ? file_path : path33.join(await getDocsDir(), "attachments", safeTicket, safeFileName);
-        const resolvedSave = path33.resolve(savePath);
-        const resolvedRoot = path33.resolve(await getProjectRoot());
-        if (!resolvedSave.startsWith(resolvedRoot + path33.sep) && resolvedSave !== resolvedRoot) {
+        const safeFileName = path34.basename(serverFilename);
+        const safeTicket = path34.basename(ticket_number);
+        const savePath = file_path ? file_path : path34.join(await getDocsDir(), "attachments", safeTicket, safeFileName);
+        const resolvedSave = path34.resolve(savePath);
+        const resolvedRoot = path34.resolve(await getProjectRoot());
+        if (!resolvedSave.startsWith(resolvedRoot + path34.sep) && resolvedSave !== resolvedRoot) {
           return {
             content: [{
               type: "text",
@@ -31922,7 +32670,7 @@ registerTool(
             }]
           };
         }
-        await mkdir12(path33.dirname(resolvedSave), { recursive: true });
+        await mkdir12(path34.dirname(resolvedSave), { recursive: true });
         if (isText) {
           await writeFile12(resolvedSave, content, "utf-8");
         } else {
@@ -33586,7 +34334,7 @@ registerTool(
 var REVIEW_WORKSPACE_PREFIX = "bridge-review-";
 var REVIEW_WORKSPACE_TTL_MS = 24 * 60 * 60 * 1e3;
 async function pruneStaleReviewWorkspaces() {
-  const tmpDir = os15.tmpdir();
+  const tmpDir = os16.tmpdir();
   let entries;
   try {
     entries = await readdir3(tmpDir);
@@ -33596,9 +34344,9 @@ async function pruneStaleReviewWorkspaces() {
   const now = Date.now();
   for (const entry of entries) {
     if (!entry.startsWith(REVIEW_WORKSPACE_PREFIX)) continue;
-    const fullPath = path33.join(tmpDir, entry);
+    const fullPath = path34.join(tmpDir, entry);
     try {
-      const info = await stat9(fullPath);
+      const info = await stat10(fullPath);
       if (now - info.mtimeMs > REVIEW_WORKSPACE_TTL_MS) {
         await rm3(fullPath, { recursive: true, force: true });
       }
@@ -33701,7 +34449,7 @@ registerTool(
     }
     let tempDir;
     try {
-      tempDir = await mkdtemp3(path33.join(os15.tmpdir(), REVIEW_WORKSPACE_PREFIX));
+      tempDir = await mkdtemp3(path34.join(os16.tmpdir(), REVIEW_WORKSPACE_PREFIX));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       return {
@@ -33715,7 +34463,7 @@ registerTool(
         }]
       };
     }
-    const archivePath = path33.join(tempDir, "archive.tar");
+    const archivePath = path34.join(tempDir, "archive.tar");
     const archiveResult = await startTicketsDeps.runCommand(
       "git",
       ["archive", "--format=tar", resolvedBaseSha, "-o", archivePath],
@@ -33787,11 +34535,11 @@ registerTool(
     }
   },
   async ({ fresh_base_root }) => {
-    const allowedPrefix = path33.join(os15.tmpdir(), REVIEW_WORKSPACE_PREFIX);
-    const resolvedTarget = path33.resolve(fresh_base_root);
-    const resolvedTmpDir = path33.resolve(os15.tmpdir());
-    const isDirectChildOfTmpDir = path33.dirname(resolvedTarget) === resolvedTmpDir;
-    const hasReviewPrefix = path33.basename(resolvedTarget).startsWith(REVIEW_WORKSPACE_PREFIX);
+    const allowedPrefix = path34.join(os16.tmpdir(), REVIEW_WORKSPACE_PREFIX);
+    const resolvedTarget = path34.resolve(fresh_base_root);
+    const resolvedTmpDir = path34.resolve(os16.tmpdir());
+    const isDirectChildOfTmpDir = path34.dirname(resolvedTarget) === resolvedTmpDir;
+    const hasReviewPrefix = path34.basename(resolvedTarget).startsWith(REVIEW_WORKSPACE_PREFIX);
     if (!isDirectChildOfTmpDir || !hasReviewPrefix) {
       return {
         content: [{
@@ -34039,7 +34787,7 @@ function containsUnsafeEncodedPathToken(value) {
   return /%2e/i.test(value) || /%2f/i.test(value) || /%5c/i.test(value);
 }
 function isPlatformAbsolutePath(value) {
-  return path33.posix.isAbsolute(value) || path33.win32.isAbsolute(value) || path33.isAbsolute(value);
+  return path34.posix.isAbsolute(value) || path34.win32.isAbsolute(value) || path34.isAbsolute(value);
 }
 function validateDecisionPageOutputSubdir(value) {
   if (value.trim().length === 0) {
@@ -34089,9 +34837,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 = path33.resolve(await getDocsDir());
-  const resolvedTarget = path33.resolve(docsBase, outputSubdir, outputFilename);
-  if (!resolvedTarget.startsWith(docsBase + path33.sep)) {
+  const docsBase = path34.resolve(await getDocsDir());
+  const resolvedTarget = path34.resolve(docsBase, outputSubdir, outputFilename);
+  if (!resolvedTarget.startsWith(docsBase + path34.sep)) {
     return {
       ok: false,
       message: `Invalid output target: the resolved output path must stay under the docs directory.`
@@ -34099,7 +34847,7 @@ async function resolveDecisionPageOutputTarget(outputSubdir, outputFilename) {
   }
   return {
     ok: true,
-    docsPath: path33.dirname(resolvedTarget),
+    docsPath: path34.dirname(resolvedTarget),
     filePath: resolvedTarget
   };
 }
@@ -34187,6 +34935,13 @@ registerTool(
       }
       seenNfrCategories.add(nfr.category);
     }
+    const seenAcIds = /* @__PURE__ */ new Set();
+    for (const ac of parsed.system_goals?.acceptance_criteria ?? []) {
+      if (seenAcIds.has(ac.id)) {
+        return validationError2(`Duplicate system_goals.acceptance_criteria id: "${ac.id}"`);
+      }
+      seenAcIds.add(ac.id);
+    }
     const outputSubdir = parsed.output_subdir ?? "review";
     const outputFilename = parsed.output_filename ?? `${parsed.ticket_key}-decisions.html`;
     const outputTarget = await resolveDecisionPageOutputTarget(outputSubdir, outputFilename);
@@ -34194,36 +34949,36 @@ registerTool(
       return validationError2(outputTarget.message);
     }
     const projectRootForAssets = await getProjectRoot();
-    const pkgRoot = path33.resolve(path33.dirname(fileURLToPath3(import.meta.url)), "../");
+    const pkgRoot = path34.resolve(path34.dirname(fileURLToPath3(import.meta.url)), "../");
     let assetsDir;
     try {
-      await stat9(path33.join(projectRootForAssets, "design-assets"));
-      assetsDir = path33.join(projectRootForAssets, "design-assets");
+      await stat10(path34.join(projectRootForAssets, "design-assets"));
+      assetsDir = path34.join(projectRootForAssets, "design-assets");
     } catch {
-      assetsDir = path33.join(pkgRoot, "design-assets");
+      assetsDir = path34.join(pkgRoot, "design-assets");
     }
     let fontsDir;
     try {
-      await stat9(path33.join(projectRootForAssets, "public", "fonts"));
-      fontsDir = path33.join(projectRootForAssets, "public", "fonts");
+      await stat10(path34.join(projectRootForAssets, "public", "fonts"));
+      fontsDir = path34.join(projectRootForAssets, "public", "fonts");
     } catch {
-      fontsDir = path33.join(pkgRoot, "public", "fonts");
+      fontsDir = path34.join(pkgRoot, "public", "fonts");
     }
     let faviconBase64 = "";
     let logoBase64 = "";
     try {
-      const faviconBuf = await readFile13(path33.join(assetsDir, "favicon", "favicon-32x32.png"));
+      const faviconBuf = await readFile14(path34.join(assetsDir, "favicon", "favicon-32x32.png"));
       faviconBase64 = faviconBuf.toString("base64");
     } catch {
     }
     try {
-      const logoBuf = await readFile13(path33.join(assetsDir, "just-logo-rough-draft.png"));
+      const logoBuf = await readFile14(path34.join(assetsDir, "just-logo-rough-draft.png"));
       logoBase64 = logoBuf.toString("base64");
     } catch {
     }
     const docsPath = outputTarget.docsPath;
     const filePath = outputTarget.filePath;
-    const fontsRelPath = path33.relative(docsPath, fontsDir);
+    const fontsRelPath = path34.relative(docsPath, fontsDir);
     const html = generateDecisionPageHtml(parsed, {
       faviconBase64,
       logoBase64,
@@ -34241,6 +34996,7 @@ registerTool(
           actionable_items_count: parsed.actionable_items.length,
           clear_improvements_count: parsed.clear_improvements.length,
           system_goals_nfr_count: parsed.system_goals?.nfrs?.length ?? 0,
+          system_goals_acceptance_criteria_count: parsed.system_goals?.acceptance_criteria?.length ?? 0,
           implementation_order_count: parsed.implementation_order?.length ?? 0
         })
       }]