@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/install-bridge.js

@@ -1,7 +1,12 @@
 /**
  * install-bridge — the one-command Bridge API project bootstrap (BAPI-429).
  *
- *   npx -y @bridge_gpt/mcp-server@latest install-bridge [--repo <name>] [--api-key <key>] [--force] [--dry-run] [--agent <name>]
+ *   npx -y @bridge_gpt/mcp-server install [--repo <name>] [--api-key <key>] [--force] [--dry-run] [--agent <name>]
+ *
+ * The documented spelling is `install` (BAPI-714, Group E). The legacy
+ * `install-bridge` token remains a silent, permanent alias — every string this
+ * module prints names `install`, because that is the only spelling the README,
+ * the invite email, and the operator-provisioned command teach.
  *
  * Collapses the previously five-step manual setup into a single CLI subcommand.
  * It does the DETERMINISTIC work in the shell:
@@ -36,8 +41,9 @@
  *
  * then SPAWNS a fresh agent session (Step 5) for the CONFIGURE-ONLY agentic
  * remainder: `/install-bridge` config-field derivation → the read-after-write
- * concise capability report → a `/learn-repository` recommendation (BAPI-658).
- * It does NOT chain into running `/learn-repository` itself — that stays the
+ * concise capability report → whatever next step the manifest's `next_step.command`
+ * names, rendered only when it is non-empty (BAPI-658, BAPI-720).
+ * It does NOT chain into running that command itself — that stays the
  * human's next explicit invocation — and it never asks about, decides, or
  * claims anything about repository indexing: indexing is entirely automatic,
  * gated server-side by the existing readiness funnel, with no prompt on any
@@ -57,22 +63,41 @@
  * methods, differing only in how the first token is obtained: `bootstrap-invite`
  * (BAPI-606) redeems a pre-issued invite; `self-serve` (BAPI-618) mints one from an
  * email. Both then feed the SAME redemption protocol. Selection is pure and
- * deterministic from flags/env, except that a BARE interactive run is asked which
- * branch it wants (BAPI-626) — without that question a first-time user cannot
- * discover self-serve at all. Either need-key method NAMES a new project, so the
- * repository prompt asks for a new project name rather than an existing
- * registration (see `RepoNamePromptMode`).
- *
- * ORDINARY-ENTRY INVITE RECLASSIFICATION (BAPI-661) — the have-key branch's own
- * credential input (`--api-key`, `BAPI_API_KEY`, or its hidden prompt) is
- * CREDENTIAL-AGNOSTIC: it accepts a full API key OR a bootstrap-invite token,
- * because a user handed only an invite has no way to know it belongs in a
- * different flag. `classifyEnteredCredential` inspects the resolved value
- * immediately after input resolution (before repository-name resolution); a
- * `bapi_inv_…` value flips the branch's `bootstrapInviteMode`/`inviteToken` and
- * the run falls into the SAME bootstrap-invite protocol described below, verbatim.
- * Explicit `--invite`/`BAPI_INVITE` and `--email`/`BAPI_SIGNUP_EMAIL` are never
- * reclassified — they are already unambiguous and remain authoritative.
+ * deterministic from flags/env, except that a BARE interactive run is asked ONE
+ * question (BAPI-626/708): `Welcome to Bridge - do you have a token yet?`, answered
+ * `1` (yes) or `2` (no). Answering `2` is the self-serve route, which a first-time
+ * user could not otherwise discover. Answering `1` opens a single hidden,
+ * CREDENTIAL-AGNOSTIC token prompt and the route is then inferred from the pasted
+ * value's SHAPE — the user is never asked to pre-classify their own credential,
+ * because the shape checks below do that with no probe request. Either need-key
+ * method NAMES a new project, so the repository prompt asks for a new project name
+ * rather than an existing registration (see `RepoNamePromptMode`).
+ *
+ * SHAPE-BASED ROUTING, AND THE INFERRED/DECLARED SPLIT (BAPI-661/687/708) — the
+ * have-key branch's credential input (`--api-key`, `BAPI_API_KEY`, or its hidden
+ * prompt) is CREDENTIAL-AGNOSTIC: it accepts a full API key OR a bootstrap-invite
+ * token. `classifyEnteredCredential` (prefix) and `isHighEntropyApiKeyShape`
+ * (positive 43-char canonical base64url test) inspect the resolved value
+ * immediately after input resolution, before repository-name resolution; a
+ * `bapi_inv_…` value flips `bootstrapInviteMode`/`inviteToken` and the run falls
+ * into the SAME bootstrap-invite protocol described below, verbatim.
+ *
+ * What differs is whether the user DECLARED a route:
+ *
+ *   - INFERRED — the bare interactive question was answered. This is the PRIMARY
+ *     path, not mis-paste recovery: nothing was declared, so the detected type and
+ *     destination route are ANNOUNCED and the run proceeds. There is no
+ *     confirmation prompt and no decline exit, because there is no stated intent
+ *     for the value to contradict.
+ *   - DECLARED — `--api-key`/`BAPI_API_KEY`, `--invite`/`BAPI_INVITE`, or
+ *     `--email`/`BAPI_SIGNUP_EMAIL`. BAPI-687 behavior is unchanged, asymmetry
+ *     included: an invite-shaped value on the key path auto-switches on a non-TTY
+ *     (with a notice), while an API-key-shaped value on the invite path exits
+ *     non-zero rather than silently redirecting a script.
+ *
+ * A value matching NEITHER shape is never reclassified in either direction; it
+ * stays on its route and fails there. Because the question is reachable only on a
+ * bare interactive TTY run, every non-interactive run is declared by construction.
  *
  * BOOTSTRAP-INVITE MODE (BAPI-606) — one of the exceptions to "this command
  * consumes a key, it does not create one" (the ordinary-entry reclassification
@@ -118,15 +143,20 @@ import { randomBytes as cryptoRandomBytes, createHash } from "crypto";
 import os from "os";
 import path from "path";
 import readline from "readline";
-import { runInit, buildBridgeApiEntry } from "./init.js";
+import { runInit, buildBridgeApiEntry, resolveInitScaffoldAssets, refreshBridgeApiPackageSpec, currentBridgePackageSpec, } from "./init.js";
 import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.js";
 import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform, isHostPlatformId, detectDefaultPlatforms, } from "./mcp-host-targets.js";
 import { provisionHostTarget, createDefaultVendorProcessDeps, } from "./mcp-host-config.js";
-import { writeMcpInstallState } from "./mcp-install-state.js";
+import { recordInstalledProjectArtifact, writeMcpInstallState } from "./mcp-install-state.js";
+import { runInstallBridgeConductorCli, } from "./install-bridge-conductor.js";
+import { runConductorInstallDoctor, } from "./conductor/install-doctor.js";
+import { resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
+import { claudeReviewWorkflowPath, writeClaudeReviewWorkflow, } from "./claude-review-workflow.js";
+import { runSetupEpicCli } from "./setup-epic.js";
 import { ensureGitignored as ensureGitignoredShared, } from "./git-ignore-utils.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
-import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, lookupSelfServeBootstrapPendingCredential, discardBootstrapPendingCredential, getBootstrapPendingTarget, resolveBapiCredentials, } from "./credential-store.js";
+import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, lookupSelfServeBootstrapPendingCredential, prepareSelfServeBootstrapChallenge as prepareSelfServeBootstrapChallengeCredential, discardBootstrapPendingCredential, getBootstrapPendingTarget, resolveBapiCredentials, } from "./credential-store.js";
 // BAPI-631: the optional GitHub connect offer reuses the standalone command's flow and
 // API primitives verbatim — no duplicated polling, browser, or picker logic here.
 import { fetchGithubConfigurationState } from "./connect-github-api.js";
@@ -136,11 +166,17 @@ import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, d
 /** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
 export const REDACTED_API_KEY = "<REDACTED>";
 /**
- * Always-surfaced success-path note (BAPI-451 W3, E-3). The pinned launcher's
- * FIRST cold launch can resolve/download the package inline; if the MCP client's
- * connect deadline is very short it may time out before the handshake. Pre-warming
- * (below) makes this rare, but the note is surfaced unconditionally so the
- * fail-soft backstop is always discoverable.
+ * Fail-soft backstop note (BAPI-451 W3, E-3). The pinned launcher's FIRST cold
+ * launch can resolve/download the package inline; if the MCP client's connect
+ * deadline is very short it may time out before the handshake.
+ *
+ * BAPI-708 (Part B) narrowed WHERE this is surfaced. It is no longer printed after
+ * a SUCCESSFUL pre-warm — there, the cold install the note warns about has already
+ * been paid, so the remedy addressed a problem that did not occur. It is still
+ * emitted by the pre-warm FAILURE branch, where an incomplete warm makes the
+ * remedy real, and by both `--dry-run` previews, which describe the run rather
+ * than perform it. `mcp_server/src/doctor.ts` carries an independently-worded
+ * near-duplicate for the after-the-fact diagnosis case.
  */
 export const MCP_TIMEOUT_GUIDANCE = "Note: if your MCP client has a very short connect deadline, raise MCP_TIMEOUT for the first launch " +
     "(the initial npx package resolution/download can exceed a short connect timeout).";
@@ -159,8 +195,12 @@ export function buildPrewarmCommandPreview() {
 /**
  * The natural-language prompt handed to the spawned agent session. It is
  * CONFIGURE-ONLY: it derives and applies configuration, presents the concise
- * capability report, and closes with a `/learn-repository` recommendation
- * (BAPI-658). It never chains straight into running /learn-repository itself —
+ * capability report — the availability-framed 'Available now' / 'Needs setup'
+ * pair the server authors (BAPI-719), rendered verbatim with zero local
+ * curation — and closes with the server-provided `next_step.command`
+ * when the manifest returned a non-empty one — and with nothing at all when it
+ * did not (BAPI-658, BAPI-720). The eligibility decision is the server's, not
+ * this prompt's. It never chains straight into running that command itself —
  * that remains the human's next explicit invocation — and it never asks about,
  * decides, or claims anything about repository indexing: indexing is entirely
  * automatic, gated by the existing readiness funnel
@@ -171,13 +211,32 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "The command chooses its own mode from the install manifest's `configured` flag — do NOT force a " +
     "mode: when `configured` is false it runs its fresh-configuration flow, and when `configured` is " +
     "true it runs JOIN MODE. In JOIN MODE the command must NOT derive, approve, apply, or offer any " +
-    "configuration and applies zero fields for any caller; a joining member's only closing interaction " +
-    "is the welcome plus the concise capability report (no /learn-repository prompt for a member). " +
+    "configuration and applies zero fields for any caller; a joining member's closing interaction " +
+    "is the welcome plus the concise capability report. " +
     "Complete the command's concise capability report: the single 'What Bridge " +
-    "can help with' section, rendered exactly as the server's concise_tool_capabilities field gives it " +
-    "(Regularly useful, then Occasionally useful, each tool's display_name only, plus each tier's " +
-    "server-computed '+N more' where non-zero). Do not render the obsolete five-section report, and do " +
-    "not locally filter, count, or fall back to the complete tool_capabilities catalog. " +
+    "can help with' section, rendered exactly as the server's concise_tool_capabilities field gives it. " +
+    "That field is exactly two availability sections in server order — 'Available now' first, then " +
+    "'Needs setup' — and each item in them carries display_name, description, how_to_use, and (in the " +
+    "'Needs setup' section only) availability_text. Render each item's display_name, its description, " +
+    "and its how_to_use verbatim when that value is a non-empty string; render availability_text " +
+    "verbatim as the setup guidance for a 'Needs setup' item, and show NO availability caveat, " +
+    "asterisk, or footnote on an 'Available now' item. An item's `kind` ('tool' or 'workflow') is " +
+    "contract metadata only — render both kinds identically, with no label, icon, or separate list, " +
+    "and never branch on it. Keep an empty section visible with a short neutral line rather than " +
+    "dropping it, and after both sections close with a pointer to the Bridge MCP server README at " +
+    "https://www.npmjs.com/package/@bridge_gpt/mcp-server for the complete tool documentation, " +
+    "including when either or both sections are empty. Do not render the obsolete five-section report, " +
+    "and do not locally filter, count, sort, regroup, infer availability, fabricate an item, or fall " +
+    "back to the complete tool_capabilities catalog or the workflows collection. If " +
+    "concise_tool_capabilities is missing or malformed, take the command's single fallback line and " +
+    "render nothing else in its place. " +
+    "In the install-spawn context Stage 6 must STILL call persist_routing_credential, but must NOT " +
+    "print or summarize its SUCCESSFUL result anywhere — no 'Stored routing credential for …' line, " +
+    "and no restatement of that target or path in any later summary or Return section — because the " +
+    "install-bridge CLI has already reported where the credential landed and a second sentence is a " +
+    "duplicate. This silence applies ONLY to success and ONLY in the install-spawn context: a Stage 6 " +
+    "FAILURE is still reported loudly and in full, and in JOIN MODE or a direct/manual /install-bridge " +
+    "invocation Stage 6 reports its success exactly as it does today. " +
     "The install-spawn skip set is exactly Stage 8, Stage 9, and Stage 10. The command-owned Stage 11 " +
     "(invite teammates) is NOT in that skip set: it is independently gated and may run only when the " +
     "caller's role is admin AND customer_type is b2b AND an interactive response is available; " +
@@ -186,11 +245,19 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "Do NOT ask any indexing question, call parse_repository, mention /parse-repository, or claim " +
     "indexing has started or is pending — indexing is decided entirely by the server-side readiness " +
     "funnel with no visibility from this session, so say nothing about it at all. " +
-    "After the capability report on the fresh-configuration path, recommend /learn-repository as the " +
-    "next step: explain briefly that it " +
-    "learns repository-specific architecture, review, testing, correctness, and validation-manual " +
-    "configuration by researching the actual codebase. Do NOT run /learn-repository yourself — only " +
-    "recommend it; running it is the human's next explicit invocation. " +
+    "Close with the server's own next step, which you must read at runtime rather than assume. Inspect " +
+    "the `next_step` object on the manifest response the flow already used: on the fresh-configuration " +
+    "path that is the Stage 7 post-apply read-after-write manifest, and in JOIN MODE it is the Stage 2 " +
+    "manifest (JOIN MODE performs no read-after-write). Look at `next_step.command`: when it is a " +
+    "NON-EMPTY string, recommend exactly that command, verbatim, in inline code — do not rename it or " +
+    "substitute a command you happen to know. When it is an empty string, make NO next-command " +
+    "recommendation at all and say nothing in its place: no heading, no placeholder, no 'nothing to " +
+    "do' line. The server decides eligibility (repository state AND whether this caller can run the " +
+    "command), so do NOT apply a role rule or a learned-state rule of your own. Do NOT run the " +
+    "returned command yourself — only recommend it; running it is the human's next explicit " +
+    "invocation. For supporting context around a recommended command, use the manifest's own " +
+    "next_step.post_install_indexing and next_step.post_install_scheduler text rather than inventing " +
+    "an explanation for it. " +
     "Never request, echo, or transport any credential — 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 " +
@@ -227,16 +294,18 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
     const setupUrl = buildInstallBridgeSetupUrl(baseUrl);
     return [
         "Usage:",
-        "  npx -y @bridge_gpt/mcp-server@latest install-bridge [flags]",
+        "  npx -y @bridge_gpt/mcp-server install [flags]",
         "",
         "One-command Bridge API project bootstrap. Scaffolds the project, writes the",
         "per-host MCP config with your credentials, verifies connectivity, persists the",
         "routing credential, then — on a TTY, only after a Y/N consent prompt — opens a",
         "fresh session in your selected tool. If the project is not yet configured it",
-        "derives the remaining config, presents a concise capability report, and",
-        "recommends /learn-repository. If the project is already configured it instead",
+        "derives the remaining config, presents a concise capability report, and shows",
+        "the next step the server returned — when it returns one.",
+        "If the project is already configured it instead",
         "joins you to it without proposing or applying any changes and just shows the",
-        "concise capability report (a b2b admin is additionally offered a teammate-invite",
+        "concise capability report plus that same conditional next step (a b2b admin is",
+        "additionally offered a teammate-invite",
         "step). So not every run applies config fields. Indexing is never asked about —",
         "it starts automatically once the repository reaches full parse readiness.",
         "",
@@ -247,28 +316,37 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "resolves your key from the credential store at runtime. A config file that",
         "cannot be parsed is left untouched, with manual-merge instructions printed.",
         "",
-        "Run it bare — `install-bridge` with no flags — in a terminal and it asks",
-        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT}\` first, with three numbered choices:`,
+        "Run it bare — `install` with no flags — in a terminal and it asks",
+        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT}\` first, with two numbered choices:`,
         ...INSTALL_BRIDGE_ONBOARDING_CHOICES.map((choice) => `  ${choice}`),
-        "There is NO default — pressing Enter selects nothing; you must type 1, 2, or 3",
-        "(one blank or invalid answer re-prompts once, then exits with guidance). Option 1",
-        "is the bootstrap-invite flow, option 2 prompts for an email and creates a",
-        "brand-new Bridge workspace for you (the self-serve flow), and option 3 is the",
-        "existing-project API-key flow below. The project-CREATING routes lead",
-        "deliberately. 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.",
+        "There is NO default — pressing Enter selects nothing; you must type 1 or 2 (one",
+        "blank or invalid answer re-prompts once, then exits with guidance). Answering 1",
+        "opens a single hidden token prompt: paste whatever you were given and its SHAPE",
+        "picks the route — a bootstrap invite (bapi_inv_…) is redeemed to CREATE a new",
+        "project and mint your first admin key, while a Bridge API key connects to the",
+        "project that already exists. You are never asked which kind of token you hold.",
+        "Answering 2 prompts for an email and creates a brand-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.",
         "",
-        "Entered the wrong kind of credential? Both directions are detected by SHAPE",
-        "alone — no probe request is sent — and neither switches routes in silence:",
-        "  - a bootstrap invite (bapi_inv_…) entered as an API key is announced, then",
+        "On that bare run the route is INFERRED, so it is only announced — the detected",
+        "credential type and where it leads are printed and the run proceeds. There is no",
+        "confirmation question and no way to decline, because you never declared a route",
+        "for the value to contradict.",
+        "",
+        "When you DO declare a route with a flag or env var, the confirmations stay, and",
+        "the two directions are deliberately asymmetric. Both are detected by SHAPE alone",
+        "— no probe request is sent — BEFORE any project-name prompt, credential write,",
+        "or network call:",
+        "  - a bootstrap invite (bapi_inv_…) passed as an API key is announced, then",
         "    confirmed on a terminal before it is redeemed; a non-interactive run keeps",
         "    today's automatic switch but prints the notice.",
-        "  - an API-key-shaped value entered as an invite is announced and may switch in",
+        "  - an API-key-shaped value passed as an invite is announced and may switch in",
         "    place only after you confirm on a terminal — non-interactive runs exit with",
-        "    guidance instead, so a script is never silently redirected. The check runs",
-        "    BEFORE any project-name prompt, credential write, or network call.",
-        "A value that is neither shape is left on the route you chose.",
+        "    guidance instead, so a script is never silently redirected.",
+        "A value that is neither shape is left on the route you chose, and is not",
+        "announced.",
         "",
         "Inputs (the only two irreducible ones):",
         "  --api-key <key>   Bridge API key OR bootstrap invite. Falls back to the",
@@ -280,7 +358,10 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                    CREATE a new project and its first admin key — the same as",
         "                    --invite — so it skips repository lookup entirely (--email",
         "                    and --invite remain the explicit, preferred entry points for",
-        "                    a new project). NEVER printed or logged.",
+        "                    a new project). Passing the flag or setting the env var",
+        "                    DECLARES the key route, so that switch is confirmed on a",
+        "                    terminal; the bare run's hidden token prompt infers instead",
+        "                    and only announces. 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",
@@ -294,8 +375,8 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                    --repo is required when stdin is non-interactive). In the",
         "                    existing-project 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 chooser",
-        "                    option 1 or 2 above) it instead NAMES the project this run",
+        "                    In either new-project flow (--email, --invite, answering 2",
+        "                    above, or a token that turns out to be an invite) it NAMES",
         "                    creates, so you are asked to name a new project — with a",
         "                    suggested default — rather than match an existing one; the",
         "                    name must be globally unique.",
@@ -303,24 +384,34 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "Self-serve onboarding (no account, no API key, no pre-issued invite):",
         "  --email <addr>    Create a brand-new Bridge workspace from just an email —",
         "                    the primary path for a first-time user with nothing yet.",
-        "                    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 — which is also what chooser option 2 on a",
-        "                    bare run 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 — it only",
-        "                    labels the new workspace.",
+        "                    interactive prompt — which is also what answering 2 on a",
+        "                    bare run 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.",
         "",
-        "                    RESUMABLE: a self-serve run that fails mid-protocol saves its",
+        "                    VERIFIED: Bridge emails a 6-digit code to that address and",
+        "                    this command prompts you for it. Nothing is created until",
+        "                    the code is entered — no workspace, no project, no API key.",
+        "                    Delivery is asynchronous, so the message arrives shortly",
+        "                    after you are prompted rather than instantly. The code",
+        "                    expires 60 minutes after it is requested, and you can ask",
+        "                    for a new one if it does not arrive; earlier codes keep",
+        "                    working until one is accepted.",
+        "",
+        "                    REQUIRES A TERMINAL: there is no flag or environment",
+        "                    variable for the code — either would put a live credential",
+        "                    into your shell history and process list. For unattended",
+        "                    setup use --api-key <key> or --invite <token> instead.",
+        "",
+        "                    RESUMABLE: a self-serve run that is interrupted saves its",
         "                    signup state under bootstrap-pending:<repo> in the credential",
-        "                    store. Re-running the self-serve flow RESUMES that attempt —",
-        "                    it does not sign up again — so a retry never creates a second",
-        "                    workspace. Never copy, display, or hand-remove that record; if",
-        "                    the saved invite has genuinely expired the CLI asks before",
-        "                    discarding it.",
+        "                    store. Re-running RESUMES that attempt — at the code prompt",
+        "                    if the code has not been entered yet, or at the exchange if",
+        "                    it has — so a retry never sends a second code and never",
+        "                    creates a second workspace. The code itself is never saved.",
+        "                    Never copy, display, or hand-remove that record; if the saved",
+        "                    invite has genuinely expired the CLI asks before discarding it.",
         "",
         "Bootstrap-invite onboarding (no web UI, no pre-existing key):",
         "  --invite [token]  Redeem a bootstrap invite you were already given: creates",
@@ -328,7 +419,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                    Mutually exclusive with --api-key and --email (in this mode",
         "                    the key is created, not consumed).",
         "",
-        "                    Run it WITHOUT a value — `install-bridge --invite` — and the",
+        "                    Run it WITHOUT a value — `install --invite` — and the",
         "                    token is read from an interactive prompt with echo",
         "                    suppressed, then sent only in the request body. This is the",
         "                    default and the recommended path: 'a copy/paste one-liner'",
@@ -385,6 +476,35 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                --agent cursor-agent still force-spawns it.",
         "  -h, --help                    Show this help.",
         "",
+        "Subcommands:",
+        "  install conductor             Bootstrap Epic Conductor v2 for this repository",
+        "                                (BAPI-679). Runs a unified READ-ONLY doctor that",
+        "                                composes the conductor, executor-preflight,",
+        "                                install-status, and executor service-unit",
+        "                                diagnostics with server-side",
+        "                                readiness (supervisor defaults, empty required-",
+        "                                check detection, GitHub App credentials and the",
+        "                                `actions` permission, reconciler tick liveness).",
+        "                                The resolved BAPI_BASE_URL is confirmed BEFORE",
+        "                                any network call — the doctor's readiness GET",
+        "                                carries the repo API key, and the URL silently",
+        "                                defaults to production when unset. A fatal",
+        "                                finding aborts BEFORE any write. A separate",
+        "                                consent immediately precedes the bootstrap POST,",
+        "                                which writes the safe project-default supervisor",
+        "                                posture in one transaction; it optionally",
+        "                                scaffolds a parameterized claude-review workflow",
+        "                                (its own separate consent), prints the capability",
+        "                                matrix, and re-runs the doctor. `--dry-run`",
+        "                                performs NO write of any kind and no write-consent",
+        "                                prompt (the base-URL confirmation still applies).",
+        "                                Executor service units are generated by",
+        "                                `executor install-service`; starting one stays",
+        "                                operator-managed, so a run reports",
+        "                                `complete-with-manual-steps` until a live",
+        "                                executor is actually observed. See",
+        "                                `install conductor --help`.",
+        "",
         "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
         "(default docs/tmp) are read from the environment with the shown fallbacks.",
         "BAPI_SIGNUP_EMAIL supplies the self-serve signup email non-interactively (it is",
@@ -519,7 +639,7 @@ export function parseInstallBridgeArgs(argv) {
         }
         return {
             status: "error",
-            message: `Unexpected positional argument: '${arg}'. install-bridge does not accept positional arguments.`,
+            message: `Unexpected positional argument: '${arg}'. install does not accept positional arguments.`,
         };
     }
     // Mutually exclusive by construction: bootstrap-invite mode CREATES the key, so
@@ -651,7 +771,7 @@ export const INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND = "npx -y @bridge_gpt/mcp-ser
 export const INSTALL_BRIDGE_GITHUB_OFFER_CONTEXT = [
     "",
     "Step 4b — optional: connect GitHub.",
-    "  This installs the Bridge GitHub App so pull requests and code review work. It opens",
+    "  This installs the Bridge GitHub App so you can implement and review tickets with Bridge. It opens",
     "  github.com in your browser; no GitHub credential is shared with Bridge.",
     `  You can do this later instead: ${INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND}`,
 ];
@@ -841,6 +961,8 @@ export function createDefaultInstallBridgeDeps() {
         repointBootstrapPending: repointBootstrapPendingCredential,
         promoteBootstrapPending: promoteBootstrapPendingCredential,
         lookupSelfServeBootstrapPending: lookupSelfServeBootstrapPendingCredential,
+        prepareSelfServeBootstrapChallenge: prepareSelfServeBootstrapChallengeCredential,
+        now: () => Date.now(),
         discardBootstrapPending: discardBootstrapPendingCredential,
         buildShellCommand: buildGenericAgentShellCommand,
         spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
@@ -854,6 +976,55 @@ export function createDefaultInstallBridgeDeps() {
             if (process.env.BAPI_INSTALL_DEBUG)
                 console.error(m);
         },
+        // ---- Nested `install-bridge conductor` seams (BAPI-679) ----
+        conductorRunDoctor: (params) => runConductorInstallDoctor({
+            access: params.access,
+            accessError: params.accessError,
+            fetch: params.fetch,
+            reviewPolicySource: params.reviewPolicySource,
+            readWorkflowFile: () => params.readFile(claudeReviewWorkflowPath(params.cwd)),
+            installDoctorDeps: {
+                env: params.env,
+                cwd: params.cwd,
+                platform: process.platform,
+                homedir: os.homedir,
+                readFile: params.readFile,
+                stat: (p) => stat(p),
+                fetch: (...args) => fetch(...args),
+            },
+        }),
+        conductorResolveAccess: async (repoName, baseUrl, mergedDeps) => {
+            const result = await resolveConductorBridgeApiAccess({
+                env: { ...mergedDeps.env, BAPI_BASE_URL: baseUrl },
+                cwd: mergedDeps.cwd,
+                homedir: mergedDeps.homedir,
+                platform: mergedDeps.platform,
+                readFile: mergedDeps.readFile,
+                stat: (p) => mergedDeps.stat(p),
+                repoName,
+            });
+            // Never surface the resolver's secret-bearing internals — it already
+            // guarantees a secret-free `error`, which is forwarded verbatim.
+            return result.ok ? { ok: true, access: result.access } : { ok: false, error: result.error };
+        },
+        conductorWriteWorkflow: (cwd, content, options, mergedDeps) => writeClaudeReviewWorkflow(cwd, content, {
+            readFile: mergedDeps.readFile,
+            mkdir: (p, o) => mergedDeps.mkdir(p, o),
+            writeFile: (p, data) => mergedDeps.writeFile(p, data),
+        }, options),
+        conductorRecordArtifact: async (cwd, relPath, mergedDeps) => {
+            const result = await recordInstalledProjectArtifact(cwd, relPath, {
+                readFile: mergedDeps.readFile,
+                writeFile: (p, data) => mergedDeps.writeFile(p, data),
+                rename: mergedDeps.rename,
+                mkdir: (p, o) => mergedDeps.mkdir(p, o),
+                unlink: mergedDeps.unlink,
+            });
+            return result.ok ? { ok: true } : { ok: false, error: result.error };
+        },
+        conductorRunSetupEpicDryRun: async (argv) => ({
+            exitCode: await runSetupEpicCli(argv),
+        }),
     };
 }
 /**
@@ -881,7 +1052,11 @@ export async function resolveApiKey(options, deps) {
         return { ok: true, value: fromEnv.trim(), source: "env" };
     }
     if (deps.isTTY && deps.promptSecret) {
-        const entered = (await deps.promptSecret("Bridge API key or invite (input hidden): ")).trim();
+        // BAPI-708 (A-3): the prompt no longer asks the user to pre-classify their own
+        // credential ("Bridge API key or invite"). Classification is done from SHAPE
+        // downstream with no probe request, so the only thing worth asking for is the
+        // token itself.
+        const entered = (await deps.promptSecret("Paste your Bridge token (input hidden): ")).trim();
         if (entered.length > 0) {
             return { ok: true, value: entered, source: "prompt" };
         }
@@ -890,12 +1065,12 @@ export async function resolveApiKey(options, deps) {
         // and it named no route usable by someone who has no key at all.
         return {
             ok: false,
-            error: `No Bridge API key or invite entered. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
+            error: `No Bridge token entered. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
         };
     }
     return {
         ok: false,
-        error: "A Bridge API key or invite is required (no interactive terminal is available to prompt " +
+        error: "A Bridge token is required (no interactive terminal is available to prompt " +
             `for it). ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
     };
 }
@@ -935,7 +1110,7 @@ export async function resolveInviteToken(options, deps) {
         error: "A bootstrap invite token is required. Pass --invite <token> or set the BAPI_INVITE " +
             "environment variable (no interactive terminal is available to prompt for it). Note that " +
             "both forms expose the token to your shell history and process list — prefer running " +
-            "'install-bridge --invite' interactively.",
+            "'install --invite' interactively.",
     };
 }
 /**
@@ -955,6 +1130,16 @@ export async function resolveInviteToken(options, deps) {
  * back in an error message.
  */
 export async function resolveSignupEmail(options, deps) {
+    // BAPI-757 (R-3 / AC-9): self-serve signup now REQUIRES an interactive terminal,
+    // and the check runs FIRST — before `--email` and before `BAPI_SIGNUP_EMAIL` —
+    // so an unattended run fails before any request is made, no verification email
+    // is sent, and no challenge row is created. Supplying the address was never the
+    // hard part; entering a code that only arrives by email is, and there is
+    // deliberately no `--code` flag and no environment variable to supply it (a live
+    // code must never reach shell history or a process list).
+    if (!deps.isTTY || !deps.promptLine) {
+        return { ok: false, error: INSTALL_BRIDGE_SIGNUP_REQUIRES_TTY };
+    }
     if (typeof options.email === "string" && options.email.trim().length > 0) {
         return { ok: true, value: options.email.trim() };
     }
@@ -962,19 +1147,11 @@ export async function resolveSignupEmail(options, deps) {
     if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
         return { ok: true, value: fromEnv.trim() };
     }
-    if (deps.isTTY && deps.promptLine) {
-        const entered = (await deps.promptLine("Email for Bridge workspace setup: ")).trim();
-        if (entered.length > 0) {
-            return { ok: true, value: entered };
-        }
-        return { ok: false, error: "No email entered." };
+    const entered = (await deps.promptLine("Email for Bridge workspace setup: ")).trim();
+    if (entered.length > 0) {
+        return { ok: true, value: entered };
     }
-    return {
-        ok: false,
-        error: "An email is required to create a Bridge workspace. Pass --email <addr> or set the " +
-            "BAPI_SIGNUP_EMAIL environment variable (no interactive terminal is available to prompt " +
-            "for it).",
-    };
+    return { ok: false, error: "No email entered." };
 }
 /**
  * Select the onboarding branch as pure logic (deterministic, no I/O, no prompt):
@@ -1002,40 +1179,38 @@ export function resolveInstallBridgeOnboardingBranch(options, env) {
     return { kind: "have-key" };
 }
 /**
- * The bare-TTY onboarding chooser (BAPI-667), replacing the BAPI-626/661 Y/n
- * question. The old prompt defaulted a bare Enter to "yes" and dropped the newest
- * users — the ones with no key, no invite, and no account — into a hidden API-key
- * prompt they could not answer, then exited. The self-serve path built for exactly
- * that user was never named. The chooser names all three routes and has NO default,
- * so Enter can no longer route anyone into a prompt they cannot satisfy.
+ * The bare-TTY onboarding question (BAPI-708, Part A), replacing the BAPI-667/687
+ * three-option chooser.
  *
- * Interaction contract mirrors the BAPI-663 tool picker: render the heading and the
- * numbered options once, accept ONE strict line.
+ * The three-option form asked the user to make a distinction the CODE can already
+ * make for itself: whether the string in their clipboard is an invite or an API
+ * key. `classifyEnteredCredential` + `isHighEntropyApiKeyShape` decide that from
+ * SHAPE alone, with no probe request — so the only thing a first-time user
+ * genuinely knows, and the only thing worth asking, is whether they have a token
+ * at all. Hence a yes/no question, with the route inferred afterwards.
+ *
+ * Interaction contract is unchanged from BAPI-667/687 and remains load-bearing:
+ * render the heading and the numbered options exactly once, accept ONE strict
+ * line, no default (a bare Enter selects nothing), bounded to a single re-prompt
+ * after one hint, and EOF resolves as an empty answer so it can never hang.
  */
-export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "How would you like to connect to Bridge API?";
+export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Welcome to Bridge - do you have a token yet?";
 /**
- * The chooser's numbered options, in render order. Index + 1 is the accepted token.
- *
- * BAPI-687 (A-1) put the two PROJECT-CREATING routes first. The previous order led
- * with the existing-project key path, labelled only "I have a Bridge API key" — which
- * reads as the default for anyone holding any credential, so a user with a valid
- * invite picked it and dead-ended at a repo-not-registered 403 with no route to the
- * path that would have created their project. Position was doing the opposite of the
- * intended routing.
+ * The question's numbered options, in render order. Index + 1 is the accepted
+ * token, exactly as before — only the option SET narrowed from three to two.
  *
- * Option 3's label carries its own scope ("for an existing project") rather than
- * relying on position (A-3): a stale screenshot or a habituated user must still be
- * able to read the right choice off the label itself.
+ * "Token" is deliberately credential-agnostic: an invite and an API key are both
+ * tokens as far as this question is concerned, and answering "Yes" leads to ONE
+ * hidden prompt whose value selects the route by shape.
  */
 export const INSTALL_BRIDGE_ONBOARDING_CHOICES = [
-    "1. I have an invite token",
-    "2. I'm new — set me up with just my email",
-    "3. I have an API key for an existing project",
+    "1. Yes, I have received a token",
+    "2. No, I need one",
 ];
 /** The single-line answer prompt drawn after the options (no bracketed default). */
-export const INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT = "Enter 1, 2, or 3: ";
+export const INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT = "Enter 1 or 2: ";
 /** The one hint line printed after a blank/invalid answer, before the single re-prompt. */
-export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1, 2, or 3.";
+export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1 or 2.";
 /**
  * The one place the "no usable credential" copy lives (BAPI-667, U1-3).
  *
@@ -1044,10 +1219,10 @@ export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1, 2, or 3.";
  * advised "try the hidden prompt again" — false, because the process has already
  * exited by the time the user reads it. All three now name the SAME three routes.
  */
-export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install-bridge and choose an option: pass --api-key <key> if you have a Bridge API " +
-    "key (or set BAPI_API_KEY), --invite if you were sent an invite token, or --email <addr> " +
-    "to sign up with just an email — on a bare interactive run, re-run and choose option 2 to " +
-    "sign up with just an email.";
+export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install: on a bare interactive run answer 1 if you already have a token " +
+    "(an invite or an API key — either one is accepted at the hidden prompt) or 2 to sign up " +
+    "with just an email. Non-interactively, pass --api-key <key> (or set BAPI_API_KEY) for an " +
+    "existing project, --invite if you were sent an invite token, or --email <addr> to sign up.";
 /**
  * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
  *
@@ -1076,21 +1251,32 @@ export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install-bridge and cho
  * bounded to ONE re-prompt — an unanswerable prompt that loops is the same
  * dead-end in a different costume.
  *
- * BAPI-687 reordered the options so the project-CREATING routes lead (1 = invite,
- * 2 = self-serve email, 3 = existing-project API key). Only the labels and the
- * dispatch moved: the heading, the `Enter 1, 2, or 3: ` prompt, the accepted-token
- * set, the no-default rule, EOF handling, and every flag/env/non-TTY bypass are
- * byte-for-byte unchanged.
+ * BAPI-708 (Part A) narrowed those three options to a token yes/no question. The
+ * chooser was asking the user to pre-classify their own credential, which the
+ * shape checks downstream already do without a probe request. Every interaction
+ * property above survives verbatim — heading + options rendered once, one strict
+ * line, no default, one hint, one re-prompt, EOF-as-empty — and so does every
+ * bypass. Only the option SET and the dispatch changed.
+ *
+ * PROVENANCE. This function is the SOLE authority on `credentialIntent`, and that
+ * is deliberate: the route-switch arms downstream must not re-derive provenance
+ * from `argv`, because a second derivation is exactly the drift BAPI-708 exists to
+ * fix. `"inferred"` is returned ONLY when the question was actually answered — a
+ * state reachable on a bare interactive TTY run and nowhere else. Every other exit
+ * is `"declared"`, so 100% of non-interactive runs stay on declared paths and the
+ * documented directional asymmetry (invite-on-key auto-switches on a non-TTY;
+ * key-on-invite exits non-zero) is preserved BY CONSTRUCTION. Do not "unify" the
+ * two.
  */
 export async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv) {
     const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
     // An explicit need-key intent is already unambiguous — never re-ask it.
     if (branch.kind === "need-key")
-        return { ok: true, branch };
+        return { ok: true, branch, credentialIntent: "declared" };
     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 };
+        return { ok: true, branch, credentialIntent: "declared" };
     }
     const promptLine = deps.promptLine;
     try {
@@ -1105,18 +1291,20 @@ export async function resolveInstallBridgeOnboardingBranchForRun(options, deps,
         // it can never hang or silently select a branch.
         for (let attempt = 0; attempt < 2; attempt += 1) {
             const answer = (await promptLine(INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT)).trim();
-            // BAPI-687 (A-2): the dispatch moved WITH the labels — the accepted tokens are
-            // still exactly 1/2/3 (no letters, no aliases), so the one-strict-line input
-            // contract BAPI-667 established is unchanged. Either branch stays
-            // credential-agnostic: a value pasted onto the wrong path is detected and
-            // re-routed downstream rather than silently accepted (B-2 / B-3).
-            if (answer === "1") {
-                return { ok: true, branch: { kind: "need-key", method: "bootstrap-invite" } };
+            // BAPI-708 (A-1): the accepted tokens are now exactly 1/2 (no letters, no
+            // aliases), preserving the one-strict-line contract. "Yes" routes to the
+            // have-key branch's credential-agnostic prompt, whose value is classified by
+            // SHAPE — so a user holding an invite still lands in the redemption protocol
+            // without ever having been asked which kind of token they hold.
+            if (answer === "1")
+                return { ok: true, branch: { kind: "have-key" }, credentialIntent: "inferred" };
+            if (answer === "2") {
+                return {
+                    ok: true,
+                    branch: { kind: "need-key", method: "self-serve" },
+                    credentialIntent: "inferred",
+                };
             }
-            if (answer === "2")
-                return { ok: true, branch: { kind: "need-key", method: "self-serve" } };
-            if (answer === "3")
-                return { ok: true, branch: { kind: "have-key" } };
             if (attempt === 0)
                 deps.log(INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT);
         }
@@ -1465,13 +1653,21 @@ export function buildManualInstallBridgeContinuation(kind, toolLabels) {
     if (kind === "empty-selection") {
         return [
             "No AI coding tools were configured, so nothing was set up for this project.",
-            "Re-run install-bridge and select at least one tool to configure it.",
+            "Re-run install and select at least one tool to configure it.",
         ].join("\n");
     }
     const toolPhrase = formatToolLabelPhrase(toolLabels);
+    // BAPI-708 (B-c): the reload clause lives here so the requirement survives on
+    // every NO-SPAWN terminal path (declined consent, non-TTY suppression, no
+    // launchable tool, chooser failure, failed spawn). A written project MCP config
+    // is not a live connection until the host reloads and its trust prompt is
+    // approved — the single most common place a fresh install looks broken. The
+    // spawn path states the same requirement in its own handoff.
     return [
         `To finish configuring this project, open it in ${toolPhrase} that has the`,
         "Bridge MCP server configured, start a new session, and run /install-bridge.",
+        "Restart or reload the tool first if it is already running — the newly written",
+        "MCP server is not live until it reloads and you approve it if prompted.",
         "Until the project is configured, your Bridge MCP tools stay limited.",
     ].join("\n");
 }
@@ -1795,6 +1991,22 @@ async function requestTrackedConfigConsent(deps, relPath) {
     const normalized = (answer ?? "").trim().toLowerCase();
     return normalized === "y" || normalized === "yes";
 }
+/**
+ * Overlay a freshly built Bridge entry onto whatever is already registered,
+ * preserving the EXISTING launcher args composition (BAPI-714, Group C).
+ *
+ * Only the package-spec token is refreshed on an existing entry, so a legacy bare
+ * launcher stays bare and an already-`serve`-bearing launcher keeps `serve`
+ * exactly once. When there is no existing entry — or its args are a shape we
+ * cannot recognize — the new template args (which DO include `serve`) are used
+ * verbatim. `command` and `env` always come from the freshly built entry: this
+ * helper governs launcher-token migration only, never credentials.
+ */
+export function preserveExistingLauncherArgs(existing, entry) {
+    const existingArgs = asRecord(existing)?.args;
+    const preserved = refreshBridgeApiPackageSpec(existingArgs, currentBridgePackageSpec());
+    return preserved ? { ...entry, args: preserved } : entry;
+}
 /**
  * Write the `bridge-api` entry into each host config via read-merge-write,
  * preserving unrelated servers and top-level keys (BAPI-666). Per target:
@@ -1855,7 +2067,13 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
         // never initialized before its tracked-state consent is resolved.
         const config = read.state === "parsed" ? read.config : {};
         const topLevel = asRecord(config[target.topLevelKey]) ?? {};
-        topLevel["bridge-api"] = entry;
+        // BAPI-714 (Group C): a PRE-EXISTING Bridge entry keeps its own launcher args
+        // composition — only the package-spec token is refreshed — so the installer
+        // never migrates a legacy bare launcher to `serve`. A newly created entry gets
+        // the full template args, `serve` included. The rule is identical for the
+        // real-key and secret-free variants: credential safety must not decide whether
+        // a launcher is migrated.
+        topLevel["bridge-api"] = preserveExistingLauncherArgs(topLevel["bridge-api"], entry);
         config[target.topLevelKey] = topLevel;
         await deps.mkdir(path.dirname(fullPath), { recursive: true });
         await deps.writeFile(fullPath, JSON.stringify(config, null, 2) + "\n", {
@@ -2294,7 +2512,7 @@ export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_PROMPT = "Redeem it as an invite
 /** Non-TTY form: the switch still happens automatically, but it is announced (B-2). */
 export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_AUTO_NOTICE = "Redeeming it as a bootstrap invite (non-interactive — no confirmation is possible here).";
 /** Printed on decline. Names the other route rather than leaving the user stranded. */
-export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_DECLINED = "Error: cancelled — nothing was created. Re-run install-bridge with an API key for an " +
+export const INSTALL_BRIDGE_INVITE_ON_KEY_PATH_DECLINED = "Error: cancelled — nothing was created. Re-run install with an API key for an " +
     "existing project (--api-key <key>, or BAPI_API_KEY), or re-run and confirm to redeem the " +
     "invite and create a new project.";
 /**
@@ -2320,7 +2538,7 @@ export const INSTALL_BRIDGE_KEY_ON_INVITE_PATH_PROMPT = "Use it to connect to yo
  * direction would silently redirect a script away from the project-creating run it
  * asked for. A script gets a non-zero exit and the exact flag it should have passed.
  */
-export const INSTALL_BRIDGE_KEY_ON_INVITE_PATH_DECLINED = "Error: cancelled — nothing was created and no invite was spent. Re-run install-bridge with " +
+export const INSTALL_BRIDGE_KEY_ON_INVITE_PATH_DECLINED = "Error: cancelled — nothing was created and no invite was spent. Re-run install with " +
     "--api-key <key> (or BAPI_API_KEY) to connect to your existing project, or supply a bootstrap " +
     "invite token (bapi_inv_…) to create a new one.";
 /**
@@ -2347,23 +2565,234 @@ export async function requestCredentialRouteSwitchConfirmation(deps, promptText)
 export function buildSelfServeMintUrl(baseUrl) {
     return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve`;
 }
+// ===================================================================
+// BAPI-757 — the verification checkpoint's user-facing copy.
+//
+// Every string below is a module constant rather than an inline literal, for two
+// reasons: the static-contract suite pins several of them, and a uniform outcome
+// stated in one place cannot drift into four subtly different sentences that
+// together disclose which failure occurred.
+// ===================================================================
+/** Digits in a verification code. Mirrors the server's protocol constant. */
+export const SIGNUP_VERIFICATION_CODE_LENGTH = 6;
+/** The one prompt label. The E2E harness and the static contract both pin it. */
+export const INSTALL_BRIDGE_CODE_PROMPT = "Email verification code: ";
+/** Shown when a stored, unexpired challenge is picked up on a later run. */
+export const INSTALL_BRIDGE_RESUME_VERIFICATION_HEADING = "Resume email verification";
+/**
+ * The non-interactive refusal (AC-9 / R-3).
+ *
+ * Names BOTH unattended alternatives, because the whole point of the message is
+ * that the user is running in a context where no prompt can be answered — telling
+ * them only what does not work would leave them stuck.
+ */
+export const INSTALL_BRIDGE_SIGNUP_REQUIRES_TTY = [
+    "Creating a Bridge workspace requires verifying your email address, and that needs an",
+    "interactive terminal to enter the emailed code. There is deliberately no flag or",
+    "environment variable for the code — either would put a live credential into your shell",
+    "history and process list.",
+    "",
+    "Two onboarding paths still work unattended:",
+    "  • An existing API key:      install --api-key <key>   (or set BAPI_API_KEY)",
+    "  • A pre-issued invite:      install --invite <token>  (or set BAPI_INVITE)",
+    "",
+    "To sign up from scratch, re-run this command in an interactive terminal.",
+].join("\n");
+/**
+ * The UNIFORM recovery message for a rejected verification.
+ *
+ * The server answers a wrong code, an expired code, an unknown handle, and an
+ * exhausted challenge with one identical response — and this message is the client
+ * half of that property. It must never be specialized per case, and it must never
+ * speculate ("maybe it expired?"): a message that narrowed the possibilities would
+ * hand back exactly the signal the uniform response withholds.
+ */
+export const INSTALL_BRIDGE_VERIFICATION_REJECTED = [
+    "That code was not accepted.",
+    "",
+    "Check the most recent verification email and try again, or request a new code. If the",
+    "signup attempt is too old, re-run this command to start a fresh one.",
+].join("\n");
+/** Resend success. States plainly that earlier codes still work — see R-5. */
+export const INSTALL_BRIDGE_RESEND_SENT = "A new code is on its way. Any code from an earlier email for this signup still works too.";
+/** Cooldown. Non-accusatory, and silent about which limiter applied. */
+export const INSTALL_BRIDGE_RESEND_COOLDOWN = "A verification email was sent moments ago — give it a minute to arrive before requesting another.";
+/** Send ceiling. Names no bucket: not the address, not the source, not the global cap. */
+export const INSTALL_BRIDGE_RESEND_THROTTLED = "Bridge is not sending another verification email for this signup right now. Try again later, or use the code from an email you already received.";
+/**
+ * A throttle that arrives from the VERIFY call, i.e. after a code was submitted.
+ *
+ * Deliberately NOT {@link INSTALL_BRIDGE_RESEND_THROTTLED}. That message tells the
+ * user to fall back on a code they already have — which is backwards here: the
+ * server throttles verification at the invite-mint ceiling, so their code may have
+ * been perfectly correct and there is nothing to fall back to. Re-running is the
+ * remedy, and the code stays valid until it expires.
+ */
+export const INSTALL_BRIDGE_VERIFY_THROTTLED = "Bridge is at capacity and could not finish creating your workspace just now. Nothing was created — wait a few minutes and re-run this command; the code already emailed to you stays valid until it expires.";
+/**
+ * A transient server failure during verification.
+ *
+ * Separate from {@link INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED} because a 5xx means
+ * the server understood this CLI perfectly and simply failed. Telling the user to
+ * upgrade would send them to the one recovery step that cannot help, and would
+ * hide a real outage behind a version-skew story.
+ */
+export const INSTALL_BRIDGE_VERIFY_SERVER_ERROR = "Error: Bridge could not complete verification right now. Nothing was created — wait a few minutes and re-run this command; the code already emailed to you stays valid until it expires.";
+/**
+ * Local cap on rejected verification attempts before the CLI stops re-prompting.
+ *
+ * AC-4 makes "wrong code" and "this challenge is dead" byte-identical on purpose,
+ * so the CLI genuinely cannot tell them apart. Without a cap, a user who exhausts
+ * the server's attempt budget is re-prompted forever against a challenge that can
+ * never succeed, with Ctrl-C as the only exit.
+ *
+ * Set ABOVE the server's default attempt budget (5) so a legitimately mistyping
+ * user is never cut off before the server itself would refuse — the cap exists to
+ * end a hopeless loop, not to add a second, tighter budget the user cannot see.
+ */
+export const INSTALL_BRIDGE_MAX_CODE_REJECTIONS = 6;
+/** Printed when the rejection cap is reached. Still state-neutral (AC-4). */
+export const INSTALL_BRIDGE_VERIFICATION_GIVING_UP = [
+    "Error: that signup could not be verified.",
+    "",
+    "Nothing has been created. Re-run this command to start a fresh signup — it will email",
+    "a new code to the same address.",
+].join("\n");
+/** The fail-closed enqueue failure (R-4). No suggestion that verification is skippable. */
+export const INSTALL_BRIDGE_SIGNUP_UNAVAILABLE = "Error: Bridge could not send a verification email, so no workspace was created. Nothing has been set up — try again in a few minutes.";
+/**
+ * R-2's hard break, rendered for a server that no longer speaks this client's
+ * protocol — or a client that no longer speaks the server's.
+ *
+ * Deliberately NOT the old generic "Check connectivity and retry": connectivity is
+ * fine, and sending a user to debug their network for a protocol change is the
+ * failure mode this constant exists to prevent.
+ */
+export const INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED = [
+    "Error: this Bridge server's signup flow does not match this CLI.",
+    "",
+    "Signup now verifies your email address with a code before creating a workspace. Upgrade",
+    "and re-run:",
+    "",
+    "  npx -y @bridge_gpt/mcp-server@latest install --email <addr>",
+].join("\n");
+/**
+ * Mask an address for display: first character, then the domain.
+ *
+ * `ada@example.com` renders as `a***@example.com`. Enough for the user to confirm
+ * they typed the right mailbox, without putting a full address into a terminal
+ * transcript that may be pasted into an issue or captured by CI. Anything that
+ * does not look like a mailbox is reduced to a fixed placeholder rather than
+ * echoed — an unparseable value is exactly the one most likely to be a typo worth
+ * not repeating.
+ */
+export function maskSignupEmail(email) {
+    const trimmed = (email ?? "").trim();
+    const at = trimmed.lastIndexOf("@");
+    if (at <= 0 || at === trimmed.length - 1)
+        return "your email address";
+    return `${trimmed[0]}***${trimmed.slice(at)}`;
+}
 /**
- * POST the self-serve mint: an email in, an invite token out. Mirrors
- * {@link exchangeBootstrapInvite}'s fetch/timeout/secret-free-result discipline.
+ * Render a challenge's remaining lifetime in calm, approximate language.
+ *
+ * Whole minutes, rounded down, and never a countdown: the exact number does not
+ * change what the user does, and a precise timer turns a routine wait into a
+ * deadline. A challenge already past its expiry says so plainly rather than
+ * rendering a negative number.
+ */
+export function formatChallengeRemaining(expiresAtIso, nowMs) {
+    const expiresMs = Date.parse(expiresAtIso);
+    if (Number.isNaN(expiresMs))
+        return "";
+    const minutes = Math.floor((expiresMs - nowMs) / 60_000);
+    if (minutes <= 0)
+        return "This code has expired.";
+    if (minutes === 1)
+        return "This code is valid for about another minute.";
+    return `This code is valid for about another ${minutes} minutes.`;
+}
+/**
+ * Prompt for the verification code, validating its shape LOCALLY before any
+ * network call.
+ *
+ * Local validation is a courtesy, not a security control — the server re-validates
+ * everything — but it keeps a mistyped code from consuming one of the five attempts
+ * that permanently kill a challenge. The user gets the prompt back instead.
+ *
+ * Pasted input is trimmed: copying a code out of a mail client routinely brings
+ * whitespace with it, and refusing that would be an avoidable dead end.
+ *
+ * The entered value is returned and never echoed, never logged, and never written
+ * to disk. `null` means the user gave up (an empty line, or an unreadable prompt).
+ */
+export async function promptForVerificationCode(deps, log, maxAttempts = 3) {
+    if (!deps.promptLine)
+        return null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        let entered;
+        try {
+            entered = (await deps.promptLine(INSTALL_BRIDGE_CODE_PROMPT)).trim();
+        }
+        catch {
+            // Secret-free by construction: the caught value is never surfaced or
+            // inspected, because a readline failure can carry the partial input.
+            return null;
+        }
+        if (entered.length === 0)
+            return null;
+        if (new RegExp(`^[0-9]{${SIGNUP_VERIFICATION_CODE_LENGTH}}$`).test(entered)) {
+            return entered;
+        }
+        // Describes the SHAPE, never the value the user typed.
+        log(`  That does not look like a code — it is ${SIGNUP_VERIFICATION_CODE_LENGTH} digits.`);
+    }
+    return null;
+}
+/*
+ * `mintSelfServeInvite` and `SelfServeMintResult` were REMOVED in BAPI-757.
  *
- * The email travels ONLY in the JSON request body (never a query string, never a
- * header, never a log line). Bounded by the same 10s timeout as the exchange and
- * the connectivity ping. On any non-success status the failure body is NOT read —
- * the status alone decides the category — because an untrusted upstream body could
- * echo the email or carry internals. A caught fetch exception is likewise never
- * inspected or interpolated; some fetch impls embed the request (and thus the
- * email) in the message.
+ * They read `token` from the request phase's success body. Under R-2 that field
+ * no longer exists for any client version, and a helper that still looked for it
+ * would be a live path back to an unverified signup — so it is deleted rather than
+ * deprecated. The replacement is the three-phase client immediately below.
  */
-export async function mintSelfServeInvite(deps, baseUrl, email) {
-    const url = buildSelfServeMintUrl(baseUrl);
+// ===================================================================
+// BAPI-757 — the three-phase self-serve signup client.
+//
+// The server no longer returns a token from the request phase, for ANY client
+// version (R-2). These three helpers replace the single-shot mint above:
+//
+//   requestSelfServeChallenge  → POST /setup/bootstrap/self-serve
+//   verifySelfServeChallenge   → POST /setup/bootstrap/self-serve/verify
+//   resendSelfServeChallenge   → POST /setup/bootstrap/self-serve/resend
+//
+// All three keep the discipline the deleted single-shot mint established, and that
+// `exchangeBootstrapInvite` still follows: the same 10s timeout, a COARSE result
+// category on failure, and a failure body that is never read — an untrusted
+// upstream body could echo the email or the code, and some fetch implementations
+// embed the request (and therefore the code) in a thrown error's message, so caught
+// exceptions are never inspected either. The one exception is the resend 429, which
+// reads a FIXED server-controlled detail string carrying no request value.
+// ===================================================================
+/** The challenge REQUEST endpoint: `<base>/setup/bootstrap/self-serve`. */
+export function buildSelfServeVerifyUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve/verify`;
+}
+/** The challenge RESEND endpoint: `<base>/setup/bootstrap/self-serve/resend`. */
+export function buildSelfServeResendUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve/resend`;
+}
+/**
+ * POST the challenge REQUEST: an email in, a handle out. Never a token.
+ *
+ * The email travels ONLY in the JSON body — never a query string, never a header,
+ * never a log line.
+ */
+export async function requestSelfServeChallenge(deps, baseUrl, email) {
     let resp;
     try {
-        resp = await deps.fetch(url, {
+        resp = await deps.fetch(buildSelfServeMintUrl(baseUrl), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ invitee_email: email }),
@@ -2371,8 +2800,57 @@ export async function mintSelfServeInvite(deps, baseUrl, email) {
         });
     }
     catch (err) {
-        // The message may contain the request (some fetch impls echo it), so it is
-        // deliberately NOT inspected or interpolated here.
+        void err;
+        return { ok: false, category: "failed" };
+    }
+    if (resp.ok) {
+        let handle;
+        let expiresAt;
+        try {
+            const body = (await resp.json());
+            handle = body?.handle;
+            expiresAt = body?.expires_at;
+        }
+        catch {
+            return { ok: false, category: "failed" };
+        }
+        if (typeof handle !== "string" ||
+            handle.trim().length === 0 ||
+            typeof expiresAt !== "string" ||
+            expiresAt.trim().length === 0) {
+            // A success body without challenge metadata is not something this client can
+            // act on. It is also what an OLD server (pre-BAPI-757, still returning a
+            // token) looks like — and continuing from one would mean skipping
+            // verification entirely, so it is refused rather than tolerated.
+            return { ok: false, category: "failed" };
+        }
+        return { ok: true, handle: handle.trim(), expiresAt: expiresAt.trim() };
+    }
+    if (resp.status === 429)
+        return { ok: false, category: "rate-limited" };
+    if (resp.status === 503)
+        return { ok: false, category: "unavailable" };
+    if (resp.status === 400 || resp.status === 422)
+        return { ok: false, category: "invalid" };
+    return { ok: false, category: "failed" };
+}
+/**
+ * POST the VERIFY phase: a handle and a code in, the invite token out.
+ *
+ * The code is sent once, in the body, and is never echoed back into terminal
+ * output or into any error this returns.
+ */
+export async function verifySelfServeChallenge(deps, baseUrl, handle, code) {
+    let resp;
+    try {
+        resp = await deps.fetch(buildSelfServeVerifyUrl(baseUrl), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ handle, code }),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (err) {
         void err;
         return { ok: false, category: "failed" };
     }
@@ -2383,7 +2861,6 @@ export async function mintSelfServeInvite(deps, baseUrl, email) {
             token = body?.token;
         }
         catch {
-            // An unreadable success body is not actionable and must not be exposed.
             return { ok: false, category: "failed" };
         }
         if (typeof token !== "string" ||
@@ -2393,14 +2870,83 @@ export async function mintSelfServeInvite(deps, baseUrl, email) {
         }
         return { ok: true, token };
     }
-    // Non-success: the status alone decides the category. The failure body is NEVER
-    // read — it is untrusted and could echo the email or leak internals.
-    if (resp.status === 429) {
+    // 401 is the server's uniform invalid-challenge outcome. It covers a wrong code,
+    // an expired code, an unknown handle, and an exhausted challenge, and the client
+    // deliberately cannot tell them apart — so neither can a caller watching the
+    // client's output.
+    if (resp.status === 401)
+        return { ok: false, category: "rejected" };
+    if (resp.status === 429)
         return { ok: false, category: "rate-limited" };
+    // A 5xx is the server failing, not the protocol disagreeing. Kept distinct so the
+    // caller can say "try again" instead of "upgrade the CLI".
+    if (resp.status >= 500)
+        return { ok: false, category: "server-error" };
+    return { ok: false, category: "failed" };
+}
+/**
+ * POST the RESEND phase: the handle alone, timing metadata out.
+ *
+ * No email field — accepting one would let a caller request mail for an address
+ * they hold no challenge for, which is the abuse the per-email budget bounds.
+ */
+export async function resendSelfServeChallenge(deps, baseUrl, handle) {
+    let resp;
+    try {
+        resp = await deps.fetch(buildSelfServeResendUrl(baseUrl), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ handle }),
+            signal: AbortSignal.timeout(10_000),
+        });
     }
-    if (resp.status === 400 || resp.status === 422) {
-        return { ok: false, category: "invalid" };
+    catch (err) {
+        void err;
+        return { ok: false, category: "failed" };
     }
+    if (resp.ok) {
+        let expiresAt;
+        let resendsRemaining;
+        try {
+            const body = (await resp.json());
+            expiresAt = body?.expires_at;
+            resendsRemaining = body?.resends_remaining;
+        }
+        catch {
+            return { ok: false, category: "failed" };
+        }
+        if (typeof expiresAt !== "string" || expiresAt.trim().length === 0) {
+            return { ok: false, category: "failed" };
+        }
+        return {
+            ok: true,
+            expiresAt: expiresAt.trim(),
+            resendsRemaining: typeof resendsRemaining === "number" && Number.isFinite(resendsRemaining)
+                ? resendsRemaining
+                : 0,
+        };
+    }
+    // Cooldown and the send ceilings are BOTH 429 and are distinguished only by the
+    // fixed detail string. Reading it is safe here precisely because it is fixed and
+    // server-controlled — it carries no request value — and the distinction lets the
+    // CLI say "wait a moment" instead of "try again later". Any parse problem falls
+    // through to the more conservative `rate-limited`.
+    if (resp.status === 429) {
+        let detail = "";
+        try {
+            const body = (await resp.json());
+            detail = typeof body?.detail === "string" ? body.detail : "";
+        }
+        catch {
+            detail = "";
+        }
+        return {
+            ok: false,
+            category: detail.toLowerCase().includes("very recently") ? "cooldown" : "rate-limited",
+        };
+    }
+    if (resp.status === 401)
+        return { ok: false, category: "rejected" };
     return { ok: false, category: "failed" };
 }
 /**
@@ -2430,7 +2976,7 @@ export const BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE = [
     "",
     "Ask your Bridge API operator to recover it for you: they revoke the orphaned key",
     "(DELETE /setup/keys/{id}) and issue a replacement key for the EXISTING project",
-    "(POST /setup/keys), then send you that key. Run install-bridge with --api-key <that key>.",
+    "(POST /setup/keys), then send you that key. Run install with --api-key <that key>.",
 ].join("\n");
 /**
  * The 401 message for a run that REUSED an existing pending secret — the replay
@@ -2459,8 +3005,8 @@ export const BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE = "The Bridge API rejected the
  */
 export function buildBootstrapRetryAdvice(selfServeSignupMode) {
     return selfServeSignupMode
-        ? "Re-run install-bridge and choose the email option — your previous attempt will resume."
-        : "Re-run install-bridge with the same bootstrap invite — the redemption will replay and " +
+        ? "Re-run install and choose the email option — your previous attempt will resume."
+        : "Re-run install with the same bootstrap invite — the redemption will replay and " +
             "return the same key.";
 }
 /**
@@ -2509,6 +3055,69 @@ export async function resolveCredentialConflictConsent(prepared, ctx) {
     ctx.grantConsent();
     return ctx.retry();
 }
+/**
+ * The secret-free install-state file. Gitignored before it is written, so it is
+ * named here once and fed to BOTH the gitignore call and the commit-notice
+ * exclusion set — a single definition site keeps the two from drifting apart.
+ */
+export const INSTALL_BRIDGE_INSTALL_STATE_PATH = ".bridge/install-state.json";
+/** Heading printed above the commit-your-assets list. Shared with the tests. */
+export const INSTALL_BRIDGE_COMMIT_ASSETS_HEADING = "Commit these generated files so your team inherits the same Bridge setup:";
+/**
+ * Format the commit-your-assets notice (BAPI-708, Part C).
+ *
+ * THIS IS A CORRECTNESS BOUNDARY, NOT COPY. Several files this install writes are
+ * deliberately gitignored because they can carry a real `BAPI_API_KEY` — the
+ * per-host MCP configs above all — and `.bridge/install-state.json` is gitignored
+ * too. A generic "commit your Bridge assets" is exactly how a live key reaches a
+ * public remote. So the notice is built by SUBTRACTION as well as selection: every
+ * path this run handed to `ensureGitignoredShared` is removed from the candidate
+ * list, which means the safe set cannot silently acquire a gitignored target if
+ * the host-target registry grows a new entry later.
+ *
+ * SECRET DISCIPLINE: parameters are project-relative scaffold paths only. The
+ * credential-store path is never passed in — it lives outside the repository and
+ * holds the key, so it is excluded by never being a candidate at all, not by
+ * filtering.
+ *
+ * Returns `""` when nothing survives, so a caller can skip an empty notice.
+ */
+export function buildCommitGeneratedAssetsNotice(safePaths, gitignoredPaths) {
+    // POSIX-normalized, trailing slash preserved (it marks a directory), so
+    // "./a/b" and "a//b" compare equal to "a/b" on both sides of the exclusion.
+    const normalize = (value) => {
+        const trailingSlash = /\/+$/.test(value.trim());
+        const collapsed = value.trim().replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+        return trailingSlash ? `${collapsed}/` : collapsed;
+    };
+    const excluded = new Set();
+    for (const raw of gitignoredPaths) {
+        const normalized = normalize(raw);
+        if (normalized.length === 0)
+            continue;
+        // Match a gitignored file whether the candidate names it with or without a
+        // trailing slash, so a registry entry can never slip through on formatting.
+        excluded.add(normalized);
+        excluded.add(normalized.replace(/\/+$/, ""));
+        excluded.add(`${normalized.replace(/\/+$/, "")}/`);
+    }
+    const seen = new Set();
+    const lines = [];
+    for (const raw of safePaths) {
+        const normalized = normalize(raw);
+        if (normalized.length === 0)
+            continue;
+        if (excluded.has(normalized))
+            continue;
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        lines.push(`  ${normalized}`);
+    }
+    if (lines.length === 0)
+        return "";
+    return [INSTALL_BRIDGE_COMMIT_ASSETS_HEADING, ...lines].join("\n");
+}
 /**
  * Render the --dry-run preview lines. Every secret is ALWAYS redacted — the
  * spawnCommand, config preview, and (in bootstrap-invite mode) the exchange body
@@ -2525,8 +3134,8 @@ export function buildDryRunPreview(plan) {
         // truthful for every outcome — but ONLY `resolved` may claim the name came back
         // from the server (BAPI-687, C-4).
         plan.serverRepoResolutionStatus !== undefined
-            ? "install-bridge --dry-run (one read-only repository-resolution GET may already have occurred; no writes, no state-changing requests, no spawns)"
-            : "install-bridge --dry-run (no writes, no network, no spawns)",
+            ? "install --dry-run (one read-only repository-resolution GET may already have occurred; no writes, no state-changing requests, no spawns)"
+            : "install --dry-run (no writes, no network, no spawns)",
         `Repo name:        ${plan.repoName}${plan.serverRepoResolutionStatus === "resolved"
             ? " (resolved server-side from your API key)"
             : ""}`,
@@ -2546,9 +3155,25 @@ export function buildDryRunPreview(plan) {
         `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY removed): ${plan.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
         `Step 4 — persist routing credential: target ${plan.credentialTarget} at ${plan.credentialStorePath}`,
+        ...buildCommitAssetsPreviewLines(plan),
         ...buildLaunchStepPreview(plan),
     ];
 }
+/**
+ * The commit-assets notice as preview lines (BAPI-708, Part C). A `--dry-run`
+ * returns before the live emission point, and this module's convention is that a
+ * preview never advertises different behavior — so the same notice, built from the
+ * same resolved manifest, appears here too. The gitignored exclusion set is the
+ * plan's own `configTargets` plus the install-state file, exactly as the live path
+ * computes it.
+ */
+function buildCommitAssetsPreviewLines(plan) {
+    const notice = buildCommitGeneratedAssetsNotice(plan.commitSafeAssets ?? [], [
+        ...plan.configTargets,
+        INSTALL_BRIDGE_INSTALL_STATE_PATH,
+    ]);
+    return notice.length > 0 ? ["", notice] : [];
+}
 /**
  * One-line description of the planned launch agent for the dry-run header (BAPI-657).
  * Never claims an unconditional Claude spawn: it reflects the discriminated launch
@@ -2589,8 +3214,10 @@ function buildLaunchStepPreview(plan) {
         "Step 4b — 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 '${INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT.replace(/:\s*$/, "")}' before the agent session starts.`,
-        "          It installs the Bridge GitHub App so pull requests and code review work, opens",
-        "          github.com in your browser, and shares no GitHub credential with Bridge; it",
+        // BAPI-708: the purpose sentence is kept on ONE line in both copies so the
+        // no-drift test can compare the whole phrase rather than a wrapped fragment.
+        "          It installs the Bridge GitHub App so you can implement and review tickets with Bridge.",
+        "          It opens github.com in your browser, and shares no GitHub credential with Bridge; it",
         `          defaults to No and can be run later instead: ${INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND}`,
     ];
     if (plan.launch.kind === "spawn") {
@@ -2634,8 +3261,8 @@ function buildBootstrapDryRunPreview(plan) {
     // created, no mint request is sent, no email leaves the machine. The email and
     // any synthetic token are deliberately absent from this output.
     const header = plan.selfServeSignup
-        ? "install-bridge --email --dry-run (no writes, no network, no spawns, no account created, no secret generated)"
-        : "install-bridge --invite --dry-run (no writes, no network, no spawns, no secret generated)";
+        ? "install --email --dry-run (no writes, no network, no spawns, no account created, no secret generated)"
+        : "install --invite --dry-run (no writes, no network, no spawns, no secret generated)";
     const repoLine = plan.selfServeSignup
         ? `Repo name:        ${plan.repoName} (created by the self-serve exchange; globally unique)`
         : `Repo name:        ${plan.repoName} (created by the exchange; globally unique)`;
@@ -2675,6 +3302,7 @@ function buildBootstrapDryRunPreview(plan) {
         `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY / BAPI_INVITE removed): ${plan.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
         `Step 4 — promote ${pendingTarget} → ${plan.credentialTarget} at ${plan.credentialStorePath} (only after the exchange succeeds)`,
+        ...buildCommitAssetsPreviewLines(plan),
         ...buildLaunchStepPreview(plan),
     ];
 }
@@ -2724,6 +3352,28 @@ export function manualEditorNames(editors) {
 export function formatNeedKeyCredentialStoreLine(repoName, credentialStorePath) {
     return `Your API key is stored at ${credentialStorePath} under "bapi:${repoName}" — copy BAPI_API_KEY from there.`;
 }
+/**
+ * Where THIS run's routing credential landed (BAPI-708, B-b) — the single Step 4
+ * result line, printed on the have-key and need-key arms alike.
+ *
+ * It replaces both `stored routing credential for … at …` lines, and it is also
+ * what makes Part B-a honest: `.mcp.json` is an MCP SERVER REGISTRATION, not a
+ * credentials file, so the one place a credential is reported must name the
+ * credential store instead.
+ *
+ * Distinct from {@link formatNeedKeyCredentialStoreLine}, which stays for the
+ * MANUAL-EDITOR context — its "copy BAPI_API_KEY from there" instruction only
+ * makes sense when the user has a global config to paste into.
+ *
+ * SECRET DISCIPLINE (hard constraint, same as its sibling): this formatter accepts
+ * NO key material. Its parameters are a repo name and a filesystem path, both
+ * printable; it must never be handed `apiKey`, `inviteToken`, `keySecret`, a signup
+ * email, or a credential record. The arity is pinned by test precisely so a third
+ * parameter cannot be added without that test failing.
+ */
+export function formatProjectCredentialStoreLine(repoName, credentialStorePath) {
+    return `We wrote your project credentials to: ${credentialStorePath} (target "bapi:${repoName}")`;
+}
 /**
  * Build the manual-instruction block for the DETECTED global-config editors only
  * (key always redacted). Returns `null` when neither Windsurf nor Codex is
@@ -2868,7 +3518,7 @@ function readInstallBridgeDebugValue(read) {
  */
 export function buildInstallBridgeFailureLines(error, context) {
     const lines = [
-        `Error: install-bridge failed at: ${context.step}`,
+        `Error: install failed at: ${context.step}`,
         `  cause: ${classifyInstallBridgeFailure(error)}`,
         `  ${INSTALL_BRIDGE_DOCTOR_POINTER}`,
     ];
@@ -2935,6 +3585,14 @@ export function resolveInstallBridgeBaseUrl(env) {
  * Every printed Step 1–5 label, defined once. `runInstallBridgeCli` uses each
  * constant BOTH when logging the step AND when recording the current step, so a
  * failure can never be attributed to a label the user did not just see.
+ *
+ * BAPI-708 (Part D) removed the separate `promoteCredential` entry: promotion is
+ * not a step the user does anything about, and printing it as its own numbered
+ * step told them the bootstrap two-phase commit exists without giving them a way
+ * to act on it. Both credential arms now log `persistCredential`. Attribution is
+ * NOT lost — the promotion-failure fatal is highly specific about what failed and
+ * what state the user is left in. The step COUNT is unchanged at 5; nothing is
+ * renumbered.
  */
 export const INSTALL_BRIDGE_STEP_LABELS = {
     scaffold: "Step 1/5 — scaffolding project (commands, agents, pipelines, config placeholders)…",
@@ -2942,7 +3600,6 @@ export const INSTALL_BRIDGE_STEP_LABELS = {
     inviteRedeem: "Step 2/5 — redeeming the bootstrap invite…",
     verifyConnectivity: "Step 2/5 — verifying connectivity…",
     writeHostConfigs: "Step 3/5 — writing per-host MCP config…",
-    promoteCredential: "Step 4/5 — promoting the bootstrap credential…",
     persistCredential: "Step 4/5 — persisting routing credential…",
 };
 /**
@@ -2974,7 +3631,7 @@ export const INSTALL_BRIDGE_NO_GIT_WARNING = "This doesn't look like a project r
 /** Default-No confirmation shown only on a TTY when `.git` is absent. */
 export const INSTALL_BRIDGE_NO_GIT_PROMPT = `${INSTALL_BRIDGE_NO_GIT_WARNING} — continue? [y/N]: `;
 /** Printed on decline. Paired with exit code 0 — a cancel is not an error. */
-export const INSTALL_BRIDGE_NO_GIT_ABORT = "Aborted — run install-bridge from your project root, or re-run and confirm to continue.";
+export const INSTALL_BRIDGE_NO_GIT_ABORT = "Aborted — run install from your project root, or re-run and confirm to continue.";
 /** The non-TTY form: same finding, stated as a warning, then the run continues. */
 export const INSTALL_BRIDGE_NO_GIT_NONINTERACTIVE_WARNING = `Warning: ${INSTALL_BRIDGE_NO_GIT_WARNING} — continuing (non-interactive).`;
 /**
@@ -3040,6 +3697,63 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // A rejected value cannot be interpolated into guidance, so usage falls back to
     // the documented default — the run is about to fail on it anyway.
     const usageBaseUrl = baseUrlResult.ok ? baseUrlResult.value : DEFAULT_BAPI_BASE_URL;
+    // ---- BAPI-679: nested `install-bridge conductor` -----------------------
+    // Intercepted HERE, before `parseInstallBridgeArgs`, because that parser
+    // rejects ALL positional arguments — a bare `conductor` token would otherwise
+    // be an argument error. Deliberately after the deps merge and the base-URL
+    // resolution above, so the nested command inherits the same final merged deps
+    // (including a test's `fetch` override) and the same normalized base URL.
+    // Note this is `install-bridge conductor`; the bare top-level `conductor`
+    // subcommand still routes to `runConductorCli` (the local event ledger) and is
+    // untouched.
+    if (argv[0] === "conductor") {
+        if (!baseUrlResult.ok) {
+            errorLog(baseUrlResult.error);
+            return 1;
+        }
+        const conductorBaseUrl = baseUrlResult.value;
+        const conductorDeps = {
+            env: deps.env,
+            cwd: deps.cwd,
+            log: deps.log,
+            errorLog: deps.errorLog,
+            promptLine: deps.promptLine,
+            resolveBaseUrl: () => ({ ok: true, value: conductorBaseUrl }),
+            resolveAccess: (repoName, resolvedBaseUrl) => (deps.conductorResolveAccess ??
+                (async () => ({ ok: false, error: "conductor access seam unavailable" })))(repoName, resolvedBaseUrl, deps),
+            fetchJson: deps.fetch,
+            postJson: deps.fetch,
+            runDoctor: (params) => (deps.conductorRunDoctor ??
+                (async () => ({
+                    legacyConductor: null,
+                    legacyExecutorPreflight: null,
+                    legacyInstallChecks: null,
+                    executorService: null,
+                    readiness: null,
+                    sections: [
+                        {
+                            id: "conductor-doctor",
+                            label: "Conductor install doctor",
+                            status: "fatal",
+                            detail: "the unified doctor seam is unavailable",
+                        },
+                    ],
+                })))({
+                ...params,
+                fetch: deps.fetch,
+                cwd: deps.cwd,
+                env: deps.env,
+                readFile: deps.readFile,
+            }),
+            writeWorkflow: (cwd, content, options) => (deps.conductorWriteWorkflow ??
+                (async () => ({ ok: false, error: "workflow seam unavailable" })))(cwd, content, options, deps),
+            recordArtifact: (cwd, relPath) => (deps.conductorRecordArtifact ??
+                (async () => ({ ok: false, error: "install-state seam unavailable" })))(cwd, relPath, deps),
+            runSetupEpicDryRun: (setupArgv) => (deps.conductorRunSetupEpicDryRun ??
+                (async () => ({ exitCode: 1 })))(setupArgv),
+        };
+        return runInstallBridgeConductorCli(argv.slice(1), conductorDeps);
+    }
     const parsed = parseInstallBridgeArgs(argv);
     if (parsed.status === "help") {
         log(getInstallBridgeUsage(usageBaseUrl));
@@ -3109,6 +3823,10 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const branch = branchResult.branch;
+    // BAPI-708 (A-5): provenance comes from the branch resolver and NOWHERE else. It
+    // is deliberately NOT re-derived from `argv`/`env` here — the resolver owns that
+    // logic, and a second derivation is exactly the drift this ticket removes.
+    const credentialIntent = branchResult.credentialIntent;
     // Mutable (BAPI-661): an ordinary have-key credential that classifies as a
     // bootstrap invite (see the have-key arm below) flips `bootstrapInviteMode` to
     // true AFTER branch selection, before repository-name resolution — everything
@@ -3170,13 +3888,23 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         if (classifyEnteredCredential(inviteToken) !== "invite" &&
             isHighEntropyApiKeyShape(inviteToken)) {
             log(INSTALL_BRIDGE_KEY_ON_INVITE_PATH_NOTICE);
-            const switchToKeyPath = await requestCredentialRouteSwitchConfirmation(deps, INSTALL_BRIDGE_KEY_ON_INVITE_PATH_PROMPT);
-            if (!switchToKeyPath) {
-                // Decline, an unreadable prompt, and a non-TTY run all land here — nothing
-                // has been prompted for, written, or sent, so the exit costs the user only
-                // the re-run named in the guidance.
-                errorLog(INSTALL_BRIDGE_KEY_ON_INVITE_PATH_DECLINED);
-                return 1;
+            // BAPI-708 (A-4): DO NOT UNIFY THESE TWO BRANCHES. On an INFERRED route the
+            // announcement above is purely informational — the user never declared the
+            // invite path, so there is no stated intent for the value to contradict and a
+            // confirmation would ask them to ratify a decision they never made. On a
+            // DECLARED route the confirmation is byte-for-byte BAPI-687 behavior,
+            // including the intentional non-TTY asymmetry: an API-key-shaped value on the
+            // declared invite path exits non-zero rather than silently redirecting a
+            // script away from the project-creating run it asked for.
+            if (credentialIntent === "declared") {
+                const switchToKeyPath = await requestCredentialRouteSwitchConfirmation(deps, INSTALL_BRIDGE_KEY_ON_INVITE_PATH_PROMPT);
+                if (!switchToKeyPath) {
+                    // Decline, an unreadable prompt, and a non-TTY run all land here — nothing
+                    // has been prompted for, written, or sent, so the exit costs the user only
+                    // the re-run named in the guidance.
+                    errorLog(INSTALL_BRIDGE_KEY_ON_INVITE_PATH_DECLINED);
+                    return 1;
+                }
             }
             apiKey = inviteToken;
             inviteToken = "";
@@ -3200,20 +3928,26 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // bootstrap-invite protocol verbatim.
         if (classifyEnteredCredential(keyResult.value) === "invite") {
             // BAPI-687 (B-2): the switch survives, the SILENCE does not. The user is told
-            // which credential type was detected and what it will do, and on a TTY is
-            // asked to confirm before the branch changes. A non-TTY run keeps today's
-            // automatic switch — a script must not gain a prompt — but still prints the
-            // notice, so the transcript explains itself.
+            // which credential type was detected and what it will do.
             log(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_NOTICE);
-            if (deps.isTTY && deps.promptLine) {
-                const switchToInvite = await requestCredentialRouteSwitchConfirmation(deps, INSTALL_BRIDGE_INVITE_ON_KEY_PATH_PROMPT);
-                if (!switchToInvite) {
-                    errorLog(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_DECLINED);
-                    return 1;
+            // BAPI-708 (A-4): DO NOT UNIFY THESE TWO BRANCHES — see the matching comment
+            // on the invite-path arm above. INFERRED means the user answered "yes, I have
+            // a token" and pasted it; they never claimed it was an API key, so the notice
+            // is an announcement and the run simply proceeds. DECLARED keeps BAPI-687
+            // verbatim, asymmetry included: a TTY gets the default-No confirmation, while
+            // a non-TTY still auto-switches (a script that worked yesterday must not gain
+            // a prompt) and prints the notice so the transcript explains itself.
+            if (credentialIntent === "declared") {
+                if (deps.isTTY && deps.promptLine) {
+                    const switchToInvite = await requestCredentialRouteSwitchConfirmation(deps, INSTALL_BRIDGE_INVITE_ON_KEY_PATH_PROMPT);
+                    if (!switchToInvite) {
+                        errorLog(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_DECLINED);
+                        return 1;
+                    }
+                }
+                else {
+                    log(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_AUTO_NOTICE);
                 }
-            }
-            else {
-                log(INSTALL_BRIDGE_INVITE_ON_KEY_PATH_AUTO_NOTICE);
             }
             inviteToken = keyResult.value.trim();
             apiKey = "";
@@ -3224,6 +3958,16 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             apiKeySource = undefined;
         }
         else {
+            // BAPI-708 (A-4): on the INFERRED path the route decision is announced even
+            // when nothing switches, so a bare run always says which credential type it
+            // detected and where that leads. Reuses the existing notice because it names
+            // only the credential TYPE and the destination ROUTE — never the value.
+            // Guarded on the POSITIVE shape test: a value matching neither shape is not
+            // reclassified AND not announced; it stays on this route and fails here
+            // exactly as it does today. Declared paths announce nothing new.
+            if (credentialIntent === "inferred" && isHighEntropyApiKeyShape(keyResult.value.trim())) {
+                log(INSTALL_BRIDGE_KEY_ON_INVITE_PATH_NOTICE);
+            }
             apiKey = keyResult.value;
             apiKeySource = keyResult.source;
         }
@@ -3343,12 +4087,24 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     else {
         planLaunch = { kind: "manual", reason: launchDecision.reason };
     }
+    // BAPI-708 (Part C): resolved from THIS invocation's cwd + env, so the notice
+    // names only what this run actually scaffolds — `.cursor/commands/` only when
+    // Cursor was detected, `.github/agents/` only when VS Code was, and the pipelines
+    // / instructions entries under whatever `BAPI_PIPELINES_DIR` resolved to. It is
+    // deliberately independent of which MCP HOSTS were selected: a scaffolded command
+    // directory is committed whether or not its editor got an MCP registration.
+    const scaffoldAssets = await resolveInitScaffoldAssets({
+        cwd: deps.cwd,
+        env: deps.env,
+        stat: deps.stat,
+    });
     const plan = {
         repoName,
         baseUrl,
         docsDir,
         launch: planLaunch,
         configTargets: targets.map((t) => t.relPath),
+        commitSafeAssets: scaffoldAssets.commitSafePaths,
         manualEditors: manualEditorNames(manualEditors),
         credentialTarget: `bapi:${repoName}`,
         credentialStorePath,
@@ -3486,7 +4242,14 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // ---- Step 1 — scaffold (secret-free placeholders only) ----
         currentStep = INSTALL_BRIDGE_STEP_LABELS.scaffold;
         log(currentStep);
-        await deps.runInit(deps.cwd);
+        // BAPI-728: hand init the identity this run already resolved and validated.
+        // `credentialAvailable: true` is a statement about THIS flow, not a lookup:
+        // Step 2 mints/verifies the key and Step 4 persists it, so a placeholder
+        // warning here would be a false alarm about a config the installer is
+        // actively configuring. The key value itself never crosses this boundary.
+        await deps.runInit(deps.cwd, {
+            creationContext: { repoName, baseUrl, credentialAvailable: true },
+        });
         // ---- Step 2 — mint (invite mode) or verify (normal mode) the credential ----
         let inviteFingerprint = "";
         if (bootstrapInviteMode) {
@@ -3504,13 +4267,18 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             let resumedSelfServeReplay = false;
             let keySecret = "";
             let reusedPendingSecret = false;
+            // BAPI-757: a LIVE challenge found by the lookup below. When set, the run
+            // resumes at the code prompt and MUST NOT request or resend — the emailed
+            // code is still valid, and asking again would spend one of the user's own
+            // per-address sends for nothing.
+            let liveChallenge = null;
             if (selfServeSignupMode) {
-                const lookup = await deps.lookupSelfServeBootstrapPending({ repoName }, credentialWriteDeps);
+                const lookup = await deps.lookupSelfServeBootstrapPending({ repoName, now: deps.now() }, credentialWriteDeps);
                 if (!lookup.ok) {
-                    // Fail BEFORE the mint endpoint is called and leave the stored record
-                    // untouched — an ordinary-invite record, a malformed record, and an
-                    // unreadable store are all states where minting again would compound the
-                    // problem rather than recover from it.
+                    // Fail BEFORE any endpoint is called and leave the stored record
+                    // untouched — an ordinary-invite record, a malformed record, a partial
+                    // challenge record, and an unreadable store are all states where
+                    // starting over would compound the problem rather than recover from it.
                     return fatal(`Error: ${lookup.error}`);
                 }
                 if (lookup.state === "resumable") {
@@ -3524,37 +4292,176 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     reusedPendingSecret = true;
                     log(`  resuming your previous signup attempt for ${repoName}`);
                 }
+                else if (lookup.state === "challenge") {
+                    liveChallenge = {
+                        handle: lookup.challengeHandle,
+                        expiresAt: lookup.challengeExpiresAt,
+                        email: lookup.signupEmail,
+                    };
+                }
+                // `challenge-expired` and `none` both fall through to a fresh request.
             }
             /**
-             * Mint a self-serve invite and durably store it WITH a fresh `key_secret`.
+             * Run the self-serve signup through request → verify, then durably store the
+             * resulting invite token WITH a fresh `key_secret` (BAPI-757).
+             *
+             * Three phases, in this order, and the order is the protocol:
+             *
+             *   1. **Request** (skipped when resuming a live challenge). The server
+             *      creates a challenge and queues an email. No tenant, no invitation, and
+             *      nothing billable exists yet.
+             *   2. **Persist the challenge, THEN prompt.** The email has already been
+             *      sent and the user's per-address send budget already charged by this
+             *      point, so the handle reaches disk before anything can interrupt the
+             *      run. A terminal closed at the prompt resumes the SAME challenge with
+             *      the SAME code.
+             *   3. **Verify**, which is what actually mints — and hands back the very
+             *      `inviteToken` the untouched persist-before-exchange region below
+             *      already expected.
+             *
+             * The verification code is prompted for, submitted once, and never written to
+             * disk, never logged, and never echoed.
              *
-             * Shared by the initial signup and the consented refresh below — the only two
-             * places a self-serve token is ever created. The ordering inside is the same
-             * load-bearing protocol described below: mint the token, durably store the
-             * token plus the `key_secret`, and only THEN exchange. Logs its own
-             * (secret-free) failure and returns false; the caller exits non-zero.
+             * Logs its own (secret-free) failure and returns false; the caller exits
+             * non-zero.
              */
             const mintAndPrepareSelfServe = async () => {
-                const mint = await mintSelfServeInvite(deps, baseUrl, signupEmail);
-                if (!mint.ok) {
-                    if (mint.category === "rate-limited") {
-                        // BAPI-668 (R12-1): the limiter is a single GLOBAL per-hour signup bucket,
-                        // not a per-IP/per-email one — so "temporarily rate limited" read as "you
-                        // did something wrong" when nothing on the user's machine is at fault.
-                        // Message-only: the return value and the caller's exit code are unchanged.
-                        reportFatal("Error: Bridge's self-serve signup capacity for this hour is exhausted (this is a " +
-                            "global service limit, not a problem with your machine). Try again in about an hour.");
+                let challengeHandle;
+                let challengeExpiresAt;
+                let challengeEmail;
+                if (liveChallenge) {
+                    // Phase 1 SKIPPED. Resuming an unexpired challenge: no request call, no
+                    // resend call, and no second email.
+                    challengeHandle = liveChallenge.handle;
+                    challengeExpiresAt = liveChallenge.expiresAt;
+                    challengeEmail = liveChallenge.email;
+                    log(`  ${INSTALL_BRIDGE_RESUME_VERIFICATION_HEADING}`);
+                    log(`  We already emailed a code to ${maskSignupEmail(challengeEmail)}.`);
+                }
+                else {
+                    const requested = await requestSelfServeChallenge(deps, baseUrl, signupEmail);
+                    if (!requested.ok) {
+                        if (requested.category === "rate-limited") {
+                            // Deliberately does NOT name a limiter bucket. The server refuses to
+                            // say which ceiling was reached, and repeating a guess here would
+                            // undo that.
+                            reportFatal(`Error: ${INSTALL_BRIDGE_RESEND_THROTTLED}`);
+                        }
+                        else if (requested.category === "unavailable") {
+                            // R-4's fail-closed branch: nothing was created, and there is no
+                            // suggestion anywhere that verification can be skipped.
+                            reportFatal(INSTALL_BRIDGE_SIGNUP_UNAVAILABLE);
+                        }
+                        else if (requested.category === "invalid") {
+                            reportFatal("Error: Self-serve setup could not be requested. Check the email value and try again.");
+                        }
+                        else {
+                            // R-2: a malformed or tokenless-unexpected response is a PROTOCOL
+                            // mismatch, not a network problem. Saying "check connectivity" here
+                            // was the old behavior and is exactly what this ticket replaces.
+                            reportFatal(INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED);
+                        }
+                        return false;
                     }
-                    else if (mint.category === "invalid") {
-                        reportFatal("Error: Self-serve setup could not be requested. Check the email value and try again.");
+                    challengeHandle = requested.handle;
+                    challengeExpiresAt = requested.expiresAt;
+                    challengeEmail = signupEmail;
+                    // Phase 2, first half — durable BEFORE the prompt. A failure here stops
+                    // the run: continuing would prompt for a code whose challenge could not
+                    // be resumed if anything interrupted the terminal.
+                    const recorded = await deps.prepareSelfServeBootstrapChallenge({
+                        repoName,
+                        signupEmail: challengeEmail,
+                        challengeHandle,
+                        challengeExpiresAt,
+                    }, credentialWriteDeps);
+                    if (!recorded.ok) {
+                        reportFatal(`Error: could not record the signup attempt (${recorded.kind}). ${recorded.error} ` +
+                            "No workspace has been set up — fix the problem and re-run.");
+                        return false;
                     }
-                    else {
-                        reportFatal("Error: Unable to complete self-serve setup. Check connectivity and retry.");
+                    log(`  We emailed a code to ${maskSignupEmail(challengeEmail)}.`);
+                }
+                log(`  Enter the ${SIGNUP_VERIFICATION_CODE_LENGTH}-digit code to finish setting up your workspace.`);
+                const remaining = formatChallengeRemaining(challengeExpiresAt, deps.now());
+                if (remaining)
+                    log(`  ${remaining}`);
+                // Phase 2, second half, and phase 3. One resend is offered on the recovery
+                // path only — never proactively — so the budget is spent on the user's
+                // explicit request rather than by the CLI's own retry logic.
+                let resendOffered = false;
+                // BOUNDED, not `for (;;)`. AC-4 makes a wrong code and a dead challenge
+                // byte-identical, so the CLI cannot detect that a challenge has been killed
+                // — an unbounded loop would re-prompt forever against something that can
+                // never succeed, with Ctrl-C as the only way out.
+                let rejections = 0;
+                for (;;) {
+                    const code = await promptForVerificationCode(deps, log);
+                    if (code === null) {
+                        reportFatal("Error: No verification code entered — nothing has been set up. Re-run this command " +
+                            "to continue; the code already emailed to you stays valid until it expires.");
+                        return false;
+                    }
+                    const verified = await verifySelfServeChallenge(deps, baseUrl, challengeHandle, code);
+                    if (verified.ok) {
+                        inviteToken = verified.token;
+                        break;
+                    }
+                    if (verified.category === "rate-limited") {
+                        // NOT the resend wording: a throttle here comes from the invite-mint
+                        // ceiling and can fire AFTER a perfectly correct code, so telling the
+                        // user to fall back on an email they already have is backwards.
+                        reportFatal(`Error: ${INSTALL_BRIDGE_VERIFY_THROTTLED}`);
+                        return false;
+                    }
+                    if (verified.category === "server-error") {
+                        reportFatal(INSTALL_BRIDGE_VERIFY_SERVER_ERROR);
+                        return false;
+                    }
+                    if (verified.category === "failed") {
+                        // Only a genuine protocol mismatch reaches here now: a malformed body,
+                        // a missing token, a network error, or a 4xx this client does not
+                        // expect. R-2's upgrade instruction is the right answer for those.
+                        reportFatal(INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED);
+                        return false;
+                    }
+                    // `rejected` — the server's UNIFORM outcome. One message, no speculation
+                    // about which of the four states it was.
+                    rejections += 1;
+                    if (rejections >= INSTALL_BRIDGE_MAX_CODE_REJECTIONS) {
+                        // Still state-neutral: this says the attempt is over, never WHY.
+                        reportFatal(INSTALL_BRIDGE_VERIFICATION_GIVING_UP);
+                        return false;
+                    }
+                    errorLog(INSTALL_BRIDGE_VERIFICATION_REJECTED);
+                    if (!resendOffered && deps.isTTY && deps.promptLine) {
+                        resendOffered = true;
+                        const answer = await requestCredentialRouteSwitchConfirmation(deps, "Send a new code? [y/N]: ");
+                        if (answer) {
+                            const resent = await resendSelfServeChallenge(deps, baseUrl, challengeHandle);
+                            if (resent.ok) {
+                                log(`  ${INSTALL_BRIDGE_RESEND_SENT}`);
+                            }
+                            else if (resent.category === "cooldown") {
+                                log(`  ${INSTALL_BRIDGE_RESEND_COOLDOWN}`);
+                            }
+                            else if (resent.category === "rate-limited") {
+                                log(`  ${INSTALL_BRIDGE_RESEND_THROTTLED}`);
+                            }
+                            else if (resent.category === "rejected") {
+                                // The challenge is no longer eligible — the same uniform outcome
+                                // verification reports. Stop rather than loop on a dead challenge.
+                                reportFatal(`Error: ${INSTALL_BRIDGE_VERIFICATION_REJECTED}`);
+                                return false;
+                            }
+                            else {
+                                log(`  ${INSTALL_BRIDGE_RESEND_THROTTLED}`);
+                            }
+                        }
                     }
-                    return false;
                 }
-                // Treated identically to a manually supplied invite token from here on.
-                inviteToken = mint.token;
+                // From here on the token is treated identically to a manually supplied
+                // invite — the load-bearing region below is completely unchanged.
                 inviteFingerprint = fingerprintBootstrapInvite(inviteToken);
                 const prepareSelfServePending = (allowOverwrite) => deps.prepareBootstrapPending({
                     repoName,
@@ -3585,7 +4492,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 }
                 keySecret = prep.keySecret;
                 reusedPendingSecret = prep.reused;
-                log(`  saved the pending credential for ${prep.target} (fsynced before the exchange)`);
+                // BAPI-708 (Part D): the pending write is NOT narrated on the happy path.
+                // The target name and the fsync ordering are implementation detail the user
+                // cannot act on; they remain fully described in --dry-run and in the failure
+                // messages, which name the pending record and what it means for a retry. The
+                // MECHANISM above is untouched — see the LOAD-BEARING ORDERING block below.
                 return true;
             };
             // ---- Self-serve signup (BAPI-618): mint the invite token from the email ----
@@ -3670,7 +4581,8 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 }
                 keySecret = prepared.keySecret;
                 reusedPendingSecret = prepared.reused;
-                log(`  saved the pending credential for ${prepared.target} (fsynced before the exchange)`);
+                // BAPI-708 (Part D): happy-path narration removed; the mechanism above is
+                // unchanged. See the matching comment on the self-serve arm.
             }
             // The exchange REPLACES the pre-flight ping: in invite mode there is no key to
             // ping with — this call is what mints it.
@@ -3727,7 +4639,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     !selfServeRefreshed) {
                     if (!deps.isTTY || !deps.promptLine) {
                         return fatal(BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE, `The saved attempt at ${getBootstrapPendingTarget(repoName)} in ${credentialStorePath} ` +
-                            "has been left untouched. Re-run install-bridge on an interactive terminal to " +
+                            "has been left untouched. Re-run install on an interactive terminal to " +
                             "discard it and start a fresh signup.");
                     }
                     errorLog(BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE);
@@ -3860,8 +4772,14 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             trackedState.set(target.relPath, await isTrackedProjectConfig(deps, target.relPath));
         }
         const writeResult = await writeHostConfigs(deps, targets, { real: entry, secretFree: secretFreeEntry }, trackedState, { repoName, credentialStorePath });
+        // BAPI-708 (B-a): these files are the MCP SERVER REGISTRATION (BAPI_REPO_NAME,
+        // BAPI_BASE_URL, BAPI_DOCS_DIR, BAPI_PROJECT_ROOT, and the version-pinned npx
+        // launcher) — calling them a credentials file was simply inaccurate. Where the
+        // credential actually landed is reported once, at Step 4.
         for (const { relPath, mode } of writeResult.written) {
-            log(mode === "secret-free" ? `  wrote ${relPath} (secret-free — key resolved at runtime)` : `  wrote ${relPath}`);
+            log(mode === "secret-free"
+                ? `  registered the Bridge MCP server in ${relPath} (secret-free — key resolved at runtime)`
+                : `  registered the Bridge MCP server in ${relPath}`);
         }
         for (const { relPath } of writeResult.skipped) {
             log(`  skipped ${relPath} — existing config could not be parsed safely; left untouched`);
@@ -3897,16 +4815,16 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             log("  Note: Claude Code uses the project .mcp.json while GitHub Copilot CLI uses only its " +
                 "global ~/.copilot/mcp-config.json — the two are configured separately.");
         }
-        // BAPI-635 (Step 7): Claude trust reminder — a written project MCP config is
-        // not a live connection until approved in Claude Code's trust dialog.
-        if (selectedPlatforms.includes("claude-code")) {
-            log("  Claude Code: the project MCP server is pending approval in Claude Code's trust dialog; " +
-                "restart or reload an already-running session for it to take effect.");
-        }
+        // BAPI-708 (B-c): the Claude trust reminder that used to print here was
+        // RELOCATED, not dropped — the reload requirement is genuinely actionable (the
+        // server does not work until the host reloads), but at Step 3 it duplicated the
+        // spawn handoff. It now survives on EVERY terminal path: the spawn handoff
+        // already carries it, and `buildManualInstallBridgeContinuation("configured")`
+        // carries it for the declined, non-TTY, and failed-spawn paths.
         // BAPI-635 (Step 8 + Step 3): persist the secret-free install state, ignoring
         // it before the write. Project-local paths only; global paths are never in it.
         try {
-            await ensureGitignoredShared(deps.cwd, ".bridge/install-state.json", gitignoreDeps);
+            await ensureGitignoredShared(deps.cwd, INSTALL_BRIDGE_INSTALL_STATE_PATH, gitignoreDeps);
             // writeMcpInstallState catches its own I/O errors and returns { ok: false }
             // (it does NOT throw), so the failure warning must inspect the return value —
             // a try/catch alone would silently swallow a real persistence failure.
@@ -3939,7 +4857,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             // resolve. Promotion removes the pending record and writes the credential in one
             // durable replacement; on failure the pending record survives so a re-run replays
             // the same redemption. The agent session is NOT spawned until this succeeds.
-            currentStep = INSTALL_BRIDGE_STEP_LABELS.promoteCredential;
+            // BAPI-708 (Part D): the SHARED Step 4 label — identical on both arms, so a
+            // successful run prints exactly one Step 4 line and never narrates promotion
+            // as a step of its own. Still assigned before the log, preserving the
+            // log == record invariant the failure attribution depends on.
+            currentStep = INSTALL_BRIDGE_STEP_LABELS.persistCredential;
             log(currentStep);
             const promoted = await deps.promoteBootstrapPending({ repoName, inviteFingerprint, allowOverwriteExistingCredential: overwriteConsent }, credentialWriteDeps);
             if (!promoted.ok) {
@@ -3949,7 +4871,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     `(${promoted.kind}). ${promoted.error} Your key is still saved locally as a pending ` +
                     `record. ${buildBootstrapRetryAdvice(selfServeSignupMode)}`);
             }
-            log(`  stored routing credential for ${promoted.target} at ${promoted.path}`);
+            log(formatProjectCredentialStoreLine(repoName, promoted.path));
         }
         else {
             // ---- persist routing credential (non-blocking / fail-open) ----
@@ -3958,13 +4880,13 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             try {
                 const result = await deps.upsertCredential(repoName, apiKey, credentialWriteDeps);
                 if (result.ok) {
-                    log(`  stored routing credential for ${result.target} at ${result.path}`);
+                    log(formatProjectCredentialStoreLine(repoName, result.path));
                 }
                 else {
                     log(`  warning: could not persist the routing credential (${result.kind}). ` +
                         `start-tickets model routing may not resolve the key for bapi:${repoName} ` +
                         "and will fail open to the premium/Opus tier (the most expensive) — " +
-                        "set BAPI_API_KEY in the shell or re-run install-bridge, then verify with " +
+                        "set BAPI_API_KEY in the shell or re-run install, then verify with " +
                         "'npx -y @bridge_gpt/mcp-server doctor'.");
                 }
             }
@@ -3977,6 +4899,21 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     "'npx -y @bridge_gpt/mcp-server doctor'.");
             }
         }
+        // ---- commit-your-assets notice (BAPI-708, Part C) ----
+        // Emitted AFTER the credential step and BEFORE the GitHub offer and the Step 5
+        // consent/spawn block, so every terminal path — spawn, decline, non-TTY, and
+        // spawn-failure alike — receives it exactly once. The exclusion set is computed
+        // from what this run actually gitignored (the selected project host targets and
+        // the install-state file), not a hand-copied literal, so a future host-registry
+        // entry is excluded automatically. `credentialStorePath` is never a candidate.
+        const commitAssetsNotice = buildCommitGeneratedAssetsNotice(scaffoldAssets.commitSafePaths, [
+            ...targets.map((t) => t.relPath),
+            INSTALL_BRIDGE_INSTALL_STATE_PATH,
+        ]);
+        if (commitAssetsNotice.length > 0) {
+            log("");
+            log(commitAssetsNotice);
+        }
         // ---- optional GitHub connect offer (BAPI-631) ----
         // Placed AFTER the credential is durable (the flow needs a resolvable key) and BEFORE
         // the agent spawn, for two reasons: the spawned session's capability report should
@@ -3992,8 +4929,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         if (prewarmPromise) {
             const prewarm = await prewarmPromise;
             if (prewarm.ok) {
-                log("  launcher bucket warmed (the first MCP launch will not pay a cold install).");
-                log(`  ${MCP_TIMEOUT_GUIDANCE}`);
+                // BAPI-708 (Part B): a SUCCESSFUL pre-warm is silent. Both lines described
+                // an internal optimization that worked and a remedy for a problem that did
+                // not occur. The failure branch below — where the remedy is real — keeps
+                // the MCP_TIMEOUT guidance verbatim, and both dry-run previews still carry
+                // it, so it stays discoverable exactly where it is actionable.
             }
             else {
                 // Escalate to a stronger, still secret-free warning when pre-warm didn't
@@ -4035,8 +4975,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 // raw agent binary name — computed once so all three sentences agree.
                 const handoffToolLabel = toolLabelForLaunchAgent(finalAgentName);
                 log("");
-                log(`install-bridge setup steps complete. A fresh ${handoffToolLabel} session is now applying ` +
-                    "configuration, presenting the concise capability report, and recommending /learn-repository.");
+                log(`install setup steps complete. A fresh ${handoffToolLabel} session is now applying ` +
+                    "configuration, presenting the concise capability report, and showing any next step the " +
+                    "server provides.");
                 // The trust dialog is the single most common place a spawned session stalls:
                 // the tab opens, nothing is approved, and the install looks hung.
                 log(`In the new tab: approve the workspace and the 'bridge-api' MCP server if ${handoffToolLabel} ` +