@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/README.md

@@ -103,27 +103,41 @@ you run it in your home directory, your editor will not find any of it.
 npx -y @bridge_gpt/mcp-server install
 ```
 
-**3. Answer the sign-in question.** On a first run it asks whether you already have
-a token:
+**3. Answer the sign-in question.** On a first run it asks one question:
 
 ```
-1. I need a token
-2. I already have a token
+Email (or press Enter if you already have a token):
 ```
 
-- Choose **1** if you have nothing yet. It asks for your email address and a name
-  for your new Bridge project, then creates both for you.
-- Choose **2** if someone gave you a token — either a Bridge API key or an invite
+- Type your **email address** if you have nothing yet. The installer first shows
+  how your email is used, then sends you a verification code. Your new Bridge
+  project is named after your folder, with no question asked unless the folder
+  name cannot be used. Rename it later on the Setup page.
+- Press **Enter** if someone gave you a token — either a Bridge API key or an invite
   code. Paste it at the hidden prompt; you do not have to say which kind it is,
   because the installer recognizes it. Nothing is echoed as you type.
 
-There is no default answer, so pressing Enter alone selects nothing. If you would
-rather not be asked, pass the answer up front instead — see
+One mistyped answer gets a hint and a second try. If you would rather not be
+asked, pass the answer up front instead — see
 [Choosing how you sign in](#choosing-how-you-sign-in).
 
-**4. Pick which editors to configure.** The installer detects the MCP hosts on your
-machine and asks which ones to set up. Pick every editor you actually use for this
-project; you can re-run the command later to add another.
+**4. Confirm which editors to configure.** The installer detects the MCP hosts on
+your machine and ticks them for you (`[x]`). Press Enter to accept the ticked tools,
+or type the numbers you use (for example `1,3`) to replace them. You can re-run the
+command later to add another.
+
+**Optimization.** The installer then asks how Bridge should balance quality and
+cost: **Quality** (full-depth planning and review), **Speed** (one planning pass,
+one review), or **Token Efficiency** (Speed settings, with simpler tickets handed to
+smaller models, to stretch your Claude Code, Cursor, or Codex subscription). Press
+Enter to keep Quality (or your saved choice). Change it later by running
+`/teach-bridge` in your agent.
+
+When you are done answering, the installer writes Bridge's guidance for your agent
+between `<!-- BEGIN BRIDGE MCP GUIDANCE -->` and `<!-- END BRIDGE MCP GUIDANCE -->`
+without asking. It prints how to remove that region. Then it prints the defaults it
+chose — project name, ticket keys when your project uses local tickets,
+optimization, and guidance — just before offering to open the setup session.
 
 **5. Reload your MCP host.** Editors read their MCP configuration at startup, so a
 freshly written config is not live until you reload. Restart the editor, or use its
@@ -133,7 +147,9 @@ project's `.mcp.json` the first time.
 **6. Finish in the agent session the installer opens — when it opens one.** The
 last thing the installer does is offer to open a fresh agent session running
 `/install-bridge`, which reads your codebase, fills in the remaining project
-settings, and prints a short report of what Bridge can help with. Let it finish.
+settings, and prints a short report of what Bridge can help with. Let it finish. To
+invite teammates later, open the project's Security page from the Setup page and
+create a key.
 
 Three things all have to hold for that session to open: your selection has to
 include a host the installer can launch, the run has to be on an interactive
@@ -174,14 +190,15 @@ committing anything that can hold a credential.
 
 **Prompts you will see.** More than the sign-in question, in three groups:
 
-- *Always on a first bare interactive run:* the sign-in question, a hidden prompt
-  for a token (or a visible one for an email), a project name for a brand-new
-  project, a picker for which editors to configure, and an offer to connect GitHub
-  (`Connect GitHub? [y/N]:`).
+- *Always on a first bare interactive run:* the email-or-token question (a blank
+  answer opens a hidden prompt for a token), the verification code, a picker for
+  which editors to configure (detected ones are pre-ticked), the optimization
+  choice, and an offer to connect GitHub (`Connect GitHub? [y/N]:`).
 - *Conditional on your situation:* a confirmation when the directory has no `.git`
-  (default **No**, and declining aborts); a *"Which tool should open? [1-N]"*
-  chooser when your selection contains more than one launchable tool; and the
-  consent prompt before the final agent session.
+  (default **No**, and declining aborts); a project name when your folder name
+  cannot be used as one; and the consent prompt before the final agent session. With
+  more than one launchable tool selected, the first one is used and the installer
+  says so; pass `--agent` to choose another.
 - *Overwrite confirmations, each default **No** and each skippable with `--force`:*
   a saved key for this project already exists; a host config already contains a
   `BAPI_API_KEY`; a **git-tracked** config would receive your real key; a saved but
@@ -302,7 +319,7 @@ Creates a brand-new Bridge project for that address and your first admin key in
 command. No account, no key, and no invite needed beforehand. The address labels
 your new workspace and may receive a setup message; delivery is best-effort, so
 nothing waits on it. The email is visible as you type (it is not a secret) and is
-never written to a log. This is the same route as answering **1** at the prompt.
+never written to a log. This is the same route as typing an email at the prompt.
 
 **You were sent an invite code.**
 
@@ -393,7 +410,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -415,7 +432,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -437,7 +454,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -460,7 +477,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -479,7 +496,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.70", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -544,12 +561,46 @@ converge, and nothing is reported as complete in that case. The causes:
 - the upgrade finished but left an **unconfigured** MCP entry — one that would
   authenticate as nobody.
 
+#### Upgrade notices
+
 The server checks for updates on startup. The check is cached for a day and never
-blocks startup. When a newer version is known, it surfaces in two places you do
-not have to go looking for: a one-line warning on the server's **stderr**, and a
-short advisory attached to the ordinary `tools/list` response so the agent in the
-session can see that some tools may be missing or renamed in the older build.
-Neither requires calling `ping` or `doctor`.
+blocks startup or a tool call. When a newer version is known, you hear about it
+once, in a place you do not have to go looking for:
+
+- **The first completed tool result.** In an eligible session, the first tool call
+  that finishes carries one extra line naming both versions and `/upgrade-bridge`.
+  It tells the agent to mention the upgrade and to run it only if you say yes.
+  Failed tool calls count too.
+- **Startup instructions.** If the local cache already shows a newer version, the
+  server's instructions to the agent say so from the first message.
+- **A Claude Code `SessionStart` hook.** `install` and `upgrade` add one hook to
+  `.claude/settings.local.json`, pinned to the same version as your project's
+  launcher. It runs `check-update` and shows the notice at the start of a fresh
+  session. The hook is for Claude Code only and is per developer (that file is
+  gitignored). Bridge records the exact command in `.bridge/bridge-permissions.json`,
+  so a changed pin replaces it and removal deletes only that command. Cursor and
+  Codex have no hook; they get the startup instructions and the tool-result line.
+- **`doctor` and `start-tickets`.** `doctor` shows `Bridge MCP version` beside the
+  package version, from a fresh lookup that does not touch the cache. `start-tickets`
+  prints one reminder to stderr when the cache shows a newer version.
+
+The notice is decided without waiting for any lookup. While the latest version is
+unknown, or a result cannot safely carry the extra line, the session keeps its
+chance and tries again on a later call.
+
+It stays **silent** when you are current, when the latest version is unknown, in
+unattended worker sessions (`BAPI_WORKER_BRANCH` or `BAPI_EPIC_IMPLEMENTER_WORKER_ID`
+set), and when `BAPI_MCP_UPDATE_CHECK_ENABLED` is off.
+
+`BAPI_MCP_UPDATE_CHECK_FAKE_LATEST` is a manual-only override for trying the notice.
+It must be a plain `MAJOR.MINOR.PATCH` release; anything else is ignored. It never
+changes what `install` or `upgrade` pin to.
+
+Two limits to know. The startup instructions and the hook read the cache the server
+fills, so a machine that has never run the server may show no notice at session
+start. And a cold, pinned `npx` launch of the hook can take longer than its
+five-second timeout, in which case it stays silent; run `doctor`, or launch the
+pinned CLI once, to warm it.
 
 Re-running `install` on an already-configured project is safe: it refreshes the
 scaffolded files without overwriting your stored credential unless you pass
@@ -589,15 +640,15 @@ The tools worth knowing for most tickets.
 - **Flags:** `--auto` auto-accept findings and skip the approval gates · `--rounds=1` a cheaper single-pass review that still evaluates findings and captures decisions · `--rounds=2` force the full second-opinion review · omit `--rounds` to let the difficulty-adaptive review policy decide.
 
 **2. Start Tickets**
-- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
+- **What it does:** Builds several tickets at once, each in its own copy of the repo (a git worktree) with its own agent.
 - **When it's useful:** (Implementation | Automation) When you're ready to start building one or more refined tickets concurrently.
-- **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).
+- **How to use it:** `/start-tickets BAPI-248 BAPI-250`
 - **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default · `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs · `--rounds=1|2` forwarded to the review phase, valid only with `--workflow review-and-implement` · `--tier cheap|basic|premium` strict manual model-routing override · `--auto-tier cheap|basic|premium` machine-carried raw tier for chained automation (posture-adjusted; used internally by the `/review-and-implement` handoff), mutually exclusive with `--tier`.
 
 **3. Review and Start**
-- **What it does:** Spawns one worktree per ticket; each session reviews the ticket inline and, after a per-ticket proceed/halt gate, hands off to a **fresh implementation session** that reuses the same worktree — review and implementation run in two separate agent contexts, not one shared session.
+- **What it does:** Like Start Tickets, but each ticket is reviewed first and only built if it passes.
 - **When it's useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/idea-to-pr`, which only accepts an idea).
-- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).
+- **How to use it:** `/review-and-start BAPI-248 BAPI-250`
 - **Flags:** `--auto` auto-approves both the review and the implementation phase of every spawned session · `--rounds=1|2` forwarded to the review phase · `--agent`, `--base-branch`, `--max-parallel`, `--dry-run` mirror `/start-tickets`.
 
 **4. Define Tickets**
@@ -629,7 +680,7 @@ Good to know, but not needed every day.
 - **Flags:** Name the issue type (Bug / Story / Task / Epic) and, for a child ticket under an epic, the parent key.
 
 **2. Plan Ticket**
-- **What it does:** Generates a step-by-step implementation plan for a ticket that references real files in your codebase.
+- **What it does:** Writes a step-by-step plan for a ticket that points at the real files to change.
 - **When it's useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before — or instead of — auto-implementing it.
 - **How to use it:** `/plan-ticket BAPI-123`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check the plan with a second provider.
@@ -659,9 +710,9 @@ Good to know, but not needed every day.
 - **Flags:** None.
 
 **7. Drive Epic Run**
-- **What it does:** Launches an Epic Implementer run through `drive-epic` after a preview and an explicit yes — or attaches to the epic's live run — then drives it to a terminal state, applying one sanctioned recovery verb at a time and keeping a written tally.
+- **What it does:** Builds a whole epic for you. Bridge works through the child tickets in order, merges each one into the epic branch, and fixes routine problems along the way, so you only step in when it truly needs you. It shows you a preview and waits for your yes before it starts.
 - **When it's useful:** (Implementation | Automation) When an epic has an approved plan and you want its child tickets built and merged into the epic branch with one session watching the run.
-- **How to use it:** `/drive-epic-run <EPIC> [<plan path>]` — e.g. `/drive-epic-run BAPI-1145`; the plan is found automatically when the path is omitted.
+- **How to use it:** `/drive-epic-run BAPI-1145`
 - **Flags:** None — the epic key and an optional plan path are the only arguments.
 
 ### Now and then
@@ -752,7 +803,7 @@ Useful once in a while.
 Slash commands that drive several tools at once. Start Tickets, Review and Start, and Define Tickets are documented above under [Regularly useful](#regularly-useful); Create Decision Page is documented above under [Occasionally useful](#occasionally-useful); Regression Check and Scan Test Coverage are documented above under [Now and then](#now-and-then) — the rest live here.
 
 **1. Implement Ticket**
-- **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.
+- **What it does:** Builds one ticket end to end: plans it, writes the code, opens a pull request, and watches CI.
 - **When it's useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.
 - **How to use it:** `/implement-ticket BAPI-123` (command only — "implement X" as free text almost always triggers a freehand build instead of the Bridge plan→code→PR→CI pipeline).
 - **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).
@@ -1048,74 +1099,26 @@ Attribute-definition reads and writes can return an attribute's `default_value`
 
 ## Epic Implementer
 
-The Epic Implementer drives a whole epic, several related tickets, from an
-approved plan to merged pull requests. It hands each child ticket to an agent on
-your machine, waits for CI and code review, and merges each child PR into an
-`epic/<KEY>` branch. A person merges the final pull request into your default
-branch.
-
-By default a run with two or more tickets is **unattended**: it merges child
-PRs on its own. `--attended` opts out.
+The Epic Implementer drives a whole epic, several related tickets, from an approved plan to merged pull requests. It hands each child ticket to an agent on your machine, waits for CI and code review, and merges each child PR into an `epic/<KEY>` branch. A person merges the final pull request into your default branch.
 
-**What it requires**
+This is the one starting point. The same four steps work with Bridge's own ticket storage and with Jira:
 
-- macOS or Linux, with `git`, the GitHub CLI (`gh`, logged in), the Claude Code
-  CLI (`claude`, logged in), and Worktrunk (`wt`) on your `PATH`.
-- Bridge installed in the repository, and the Bridge GitHub App connected.
-- The repository's Epic Implementer defaults, including the CI check each
-  ticket must pass (`install conductor`). For unattended runs, that check must
-  be a job in one of the two workflow files below, for example
-  `epic-implementer-ci / gate`.
-- `.github/workflows/claude-review.yml` and
-  `.github/workflows/epic-implementer-ci.yml` on your default branch, then the
-  repository indexed (or re-indexed) after they merge. The epic branch is cut
-  from the indexed commit.
-- For unattended runs: an escalation channel (the account email, or a webhook)
-  and a merge credential in `BAPI_LOCAL_MERGE_TOKEN`.
+1. **Install.** `npx -y @bridge_gpt/mcp-server install` (skip it when Bridge is already installed).
+2. **Set up.** `npx -y @bridge_gpt/mcp-server install conductor` checks everything, fixes what is missing, checks again, and ends with one verdict: "Ready for your first epic" or "Not ready: N steps left".
+3. **Define the epic.** `/define-tickets` writes real child ticket keys, `epic-plan.dag.json`, and `epic-plan.meta.json`.
+4. **Launch.** `/drive-epic-run <EPIC> [<plan path>]` previews, asks you once, creates the run through `drive-epic`, and drives it. From a shell, run `npx -y @bridge_gpt/mcp-server drive-epic <EPIC>`.
 
-**How to set it up**
+**Read the guide: [Run your first epic](./docs/epic-implementer/getting-started.md).** It lists every prerequisite with its fix. `install` also copies it into your project at `docs/install/epic-implementer-install.md`, so you can ask your agent:
 
-The easy way is to ask your agent:
+> Set up the Epic Implementer by following `docs/install/epic-implementer-install.md`. Run `npx -y @bridge_gpt/mcp-server install` to write or refresh that file.
 
-> Set up the Epic Implementer by following `docs/install/epic-implementer-install.md`.
+Setup needs macOS or Linux, with `git`, the GitHub CLI (`gh`, signed in), the Claude Code CLI (`claude`, signed in), and Worktrunk (`wt`) on your `PATH`. By default a run with two or more tickets is **unattended**: it merges child PRs into the epic branch on its own. `--attended` opts out.
 
-`install` copies that guide into your project. It is also in this package as
-[EPIC-IMPLEMENTER-INSTALL.md](./docs/EPIC-IMPLEMENTER-INSTALL.md). It checks
-each step, asks before anything that writes, and tells you which commands you
-must run yourself.
-
-By hand, the outline is:
-
-```bash
-npx -y @bridge_gpt/mcp-server install                                   # if Bridge is not installed yet
-npx -y @bridge_gpt/mcp-server connect-github --repo <repo_name>         # connect the GitHub App
-npx -y @bridge_gpt/mcp-server install conductor --required-check "epic-implementer-ci / gate" \
-  --review-policy verdict_protocol \
-  --allowed-bot "<bot>" --secret-name <SECRET_NAME> --branches "<default branch>,epic/**"   # AI review is opt-in; omit all four to skip the claude-review workflow
-export BAPI_LOCAL_MERGE_TOKEN="$(gh auth token)"                        # in the shell that runs drive-epic
-npx -y @bridge_gpt/mcp-server epic-implementer readiness --json         # read-only check of every prerequisite
-```
+Merging child PRs needs a GitHub token. Setup can store one for this repository on your computer, under `github-merge:<host>/<owner>/<repo>` in your user credential store. `GITHUB_MERGE_TOKEN` still takes precedence when it is set.
 
-After `install conductor`, restart your MCP client so the Epic Implementer tools
-appear. Add `epic-implementer-ci.yml` (the guide has a template) and the
-`claude-review.yml` that `install conductor` wrote (only when you opted in to AI review with `--review-policy verdict_protocol`), through a pull request into
-your default branch. Once it merges, index the repository with
-`/parse-repository`.
+`/plan-epic` is the advanced planner. It writes placeholder `TBD-N` keys, so you create the child tickets and run `emit-epic-implementer-bundle finalize` before `/drive-epic-run`. It never creates or approves a run.
 
-**How to run an epic**
-
-1. `/plan-epic <EPIC>` splits an existing epic ticket into child tickets and
-   writes a plan (`epic-plan.dag.json`). Its last step creates and approves an
-   unattended run.
-2. `/drive-epic-run <EPIC> [<plan path>]` previews, asks you once, starts the
-   run, and watches it to the end. It takes no flags. For `--attended` or
-   `--policy-file <path>`, use the shell instead:
-   `npx -y @bridge_gpt/mcp-server drive-epic <EPIC> --plan-file <path> [--attended]`.
-3. Monitor with the `get_epic_snapshot` and `explain_run` MCP tools, or
-   `npx -y @bridge_gpt/mcp-server notifications --repo <repo_name> --run <EPIC> --follow`.
-
-See [The Epic Implementer](#the-epic-implementer) for every command, and
-[EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md) for the full reference.
+See [The Epic Implementer](#the-epic-implementer) for what each command is for, and [EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md) for the full reference.
 
 ## CLI Subcommands
 
@@ -1225,9 +1228,19 @@ onboarding/API setup, and Windsurf are outside packaged repair.
 The package also ships a strictly **read-only** `doctor` subcommand — titled **`bridge doctor — read-only diagnostics`** — that diagnoses your whole Bridge install without changing anything:
 
 ```
-npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
+npx -y @bridge_gpt/mcp-server doctor [--agent <name>] [--advanced]
 ```
 
+By default `doctor` works on a repository in any language: it makes **no `uv`,
+Alembic, or Python call**. `--advanced` adds the Python and self-host
+diagnostics — the `uv` check and the local plane credential section — for
+bridge-api and self-hosting owners.
+
+Right after `Install status`, a **Getting started** section shows the two
+sign-ins a first epic needs: your Claude sign-in (it reads only `~/.claude.json`)
+and your GitHub CLI sign-in (one `gh auth status`, ten seconds at most). Each one
+that is not ready names its one fix. It never changes the exit code.
+
 The report always leads with the advisory **`Install status`** section (repo identity, credential resolution, server connectivity, bootstrap-field completeness, integration credentials, indexing state) **before** the `start-tickets` prerequisite diagnostics; the launcher-cache and MCP tool-surface sections follow. `Install status` is read-only GETs only and never affects the exit code.
 
 The report also includes a **Claude login** advisory: whether the host's own
@@ -1236,7 +1249,7 @@ blocks the doctor run and cannot guarantee the next worker spawn will
 authenticate. See
 [Claude login for Epic Implementer workers](#claude-login-for-epic-implementer-workers).
 
-It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
+It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus the selected agent's command** (and **`uv`** with `--advanced`) (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
 
 **`claude-review` workflow lineage (advisory, read-only).** `doctor` also reports
 whether the current branch's `.github/workflows/claude-review.yml` matches the
@@ -1256,203 +1269,50 @@ worker**. Remedy and full diagnosis:
 
 ### The Epic Implementer
 
-The Epic Implementer drives a whole epic — several related tickets — from an
-approved plan to merged pull requests, with little help from you. It was called
-the "conductor" before BAPI-1077..1083 renamed it. A few command, flag, and path
-names still say `conductor`; each is noted where it appears.
+The Epic Implementer drives a whole epic — several related tickets — from an approved plan to merged pull requests, with little help from you. The getting-started guide in [the section above](#epic-implementer) is the one path; this section says what each command is for.
 
 It has two parts:
 
-- **The v2 engine.** A reconciler on the Bridge API server decides every step. An
-  executor on your machine runs the jobs it hands out, one agent session per child
-  ticket. This is what drives an epic.
-- **Observability** (`start-tickets --conductor`). An opt-in local event ledger,
-  supervisor tab, and git hooks. It is off by default, and driving an epic does not
-  need it.
-
-The path from an epic to a finished run:
-
-1. **Plan.** `/plan-epic` splits the epic into child tickets and a plan DAG
-   (`epic-plan.dag.json`). `emit-epic-implementer-bundle finalize` writes the DAG
-   and the meta file that `drive-epic` uses to find it.
-2. **Set up the repository, once.**
-   `npx -y @bridge_gpt/mcp-server install conductor --required-check <check>`
-   (also spelled `install-bridge conductor`; the name predates the rename). It runs
-   a read-only doctor and writes the done gate from your required CI check(s). It
-   can also scaffold the `claude-review` workflow (only with the explicit AI-review opt-in, `--review-policy verdict_protocol`; omitting the flag persists no repository review choice and scaffolds none), write an executor service unit,
-   and save a launch profile. With its own consent, it adds `epic_implementer` to
-   `BRIDGE_MCP_PROFILE` in your host MCP configs. Run `install conductor --help`
-   for every option.
-3. **Launch and drive.** In Claude Code, `/drive-epic-run <EPIC> [<plan path>]`
-   previews the launch, asks you once, creates the run through `drive-epic`, and
-   then watches and recovers it. From a shell, [`drive-epic <EPIC>`](#drive-epic)
-   creates the run and starts its executor.
-4. **Monitor.** The MCP tools `get_epic_snapshot` and `explain_run` (they need the
-   `epic_implementer` profile; see [Environment Variables](#environment-variables)),
-   `notifications <EPIC|run-id> [--follow]`, `epic-implementer epic-status`, and
-   `executor watch <job>`.
-5. **Recover.** `epic-implementer unpark`, `adopt-current-head-and-unpark`,
-   `continue-child`, `resume-run`, `stop-run`, and `abandon-run` (terminal and
-   irreversible). Run `npx -y @bridge_gpt/mcp-server epic-implementer --help` for
-   the full list.
-
-`epic-implementer readiness` is a read-only report of every prerequisite, the
-unattended ones included, each with its state and one named fix. The full
-reference — architecture, the CI gate, supervisor config, observability, and git
-hooks — is in [EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md).
-
-**Old variable names stop every command (BAPI-1190).** Every `BAPI_CONDUCTOR_*`
-variable was renamed to `BAPI_EPIC_IMPLEMENTER_*`, and the few old `CONDUCTOR_*`
-names without the `BAPI_` prefix (the node path, for one) now start with
-`EPIC_IMPLEMENTER_`. There are no aliases. If any old name is set, every
-entry point — the MCP server included — prints the old names and exits `1`.
-Rename or unset them.
+- **The engine.** A reconciler on the Bridge API server decides every step. An executor on your machine runs the jobs it hands out, one agent session per child ticket. This is what drives an epic.
+- **Observability** (`start-tickets --conductor`). An opt-in local event ledger, supervisor tab, and git hooks. It is off by default, and driving an epic does not need it.
+
+What each command is for:
+
+- **`install conductor`** sets up the repository, once. It checks, fixes what is missing, checks again, and ends with one verdict. It is also spelled `install-bridge conductor`, and `install conductor --help` lists every option.
+- **`/define-tickets`** writes the child tickets and the plan files. **`/plan-epic`** is the advanced planner; it needs `emit-epic-implementer-bundle finalize` and never creates a run.
+- **`/drive-epic-run <EPIC> [<plan path>]`** previews the launch, asks you once, creates the run through [`drive-epic`](#drive-epic), then watches and recovers it. In Claude Code it first checks whether Bridge's auto-mode sandbox description is in `~/.claude/settings.json`. Only when it is missing, it asks you once, in the session, and writes it only after an explicit yes. You can add it yourself with `npx -y @bridge_gpt/mcp-server bridge-permissions` (run from the project root; it asks first), inspect it with `bridge-permissions --check --json`, and remove it with `install --remove-bridge-permissions`. `install` itself never touches that file.
+- **Monitor** with the MCP tools `get_epic_snapshot` and `explain_run` (they need the `epic_implementer` profile; see [Environment Variables](#environment-variables)), `notifications <EPIC|run-id> [--follow]`, `epic-implementer epic-status`, and `executor watch <job>`.
+- **Recover** with `epic-implementer unpark`, `adopt-current-head-and-unpark`, `continue-child`, `resume-run`, `stop-run`, and `abandon-run` (terminal and irreversible). Run `npx -y @bridge_gpt/mcp-server epic-implementer --help` for the full list.
+
+`epic-implementer readiness` is a read-only report of every prerequisite, the unattended ones included, each with its state and one named fix.
+
+**Old variable names stop every command.** Every `BAPI_CONDUCTOR_*` variable was renamed to `BAPI_EPIC_IMPLEMENTER_*`, and the few old `CONDUCTOR_*` names without the `BAPI_` prefix (the node path, for one) now start with `EPIC_IMPLEMENTER_`. There are no aliases. If any old name is set, every entry point — the MCP server included — prints the old names and exits `1`. Rename or unset them.
 
 ### `drive-epic`
 
-The one Epic Implementer entry point every Bridge surface names. Give it an epic
-key and it reads Epic Implementer readiness for your repository and routes to the
-single path your project can actually run:
+The one launch command. Give it an epic key and it reads your repository's readiness and routes to the single path your project can run:
 
 ```
 npx -y @bridge_gpt/mcp-server drive-epic <EPIC>
 ```
 
-You are never asked to choose. `drive-epic` routes to exactly one engine, the
-v2 engine — one transition authority per epic is what keeps an epic from wedging.
-Readiness green routes to the v2 bootstrap below (pass `--plan-file`
-and `drive-epic` runs it for you); readiness not green reports that the v2 engine
-is not ready to drive this epic — there is no alternative engine to fall back
-to — and prints no run command. If readiness is **unknown** — unreachable,
-unauthorized, or malformed — it escalates and prints no run command at
-all, because an unknown owner is not the same as a not-ready one. No branch,
-including every error path, ever offers you two paths.
-
-`drive-epic` owns no branch behavior of its own — it forwards `--feature-branch
-<name>`, `--into-base`, and `--attended` verbatim to `setup-epic`, which decides
-the strategy and the posture (see below). With none of them, a multi-ticket epic
-runs on `epic/<KEY>`, unattended. It also forwards `--repo` and the policy flags:
-`--policy-file <path>` (the complete run policy), `--review-policy <src>` (a
-per-run review policy: `repository_policy`, `verdict_protocol`,
-`native_review_decision`, or `none`; omitted, the server stamps `repository_policy`
-at first approval for a new feature-branch run, and `verdict_protocol` is the
-explicit AI-review opt-in), and `--replace-policy` (allow replacing a live run's
-stored policy).
-
-**Every run gets an executor (BAPI-1279).** Once `drive-epic` creates a run, it
-starts an executor scoped to that run in the background, from this checkout's Git
-top level. The executor claims only that run's jobs, logs to
-`.bridge/executors/<run>.log`, and exits on its own when the run is done or
-abandoned. You do not start one by hand. Run `drive-epic` from a Git work tree
-inside the target repository — it checks this before creating anything. If the
-executor fails to start, the run is left intact and `drive-epic` prints the log
-path and the exact command to start it by hand.
-
-**Choosing the server.** With no flags, `drive-epic` targets production and uses
-the stored `bapi:<repo>` key when there is one. `--base-url <url>` (or
-`BAPI_BASE_URL`) names another server. `--launch-profile <name>` (or
-`BAPI_EPIC_LAUNCH_PROFILE`) selects a host-local profile saved by
-`install conductor --launch-profile <name>`; use one for a local server or a
-durable host. With a profile, `--base-url` must agree with it. A stored key
-approved for a different endpoint is never sent.
-
-**Finding the plan from the epic key (BAPI-1285).** `--plan-file` is optional.
-Without it, `drive-epic` searches `{docs_dir}/epic-plans/*/epic-plan.meta.json` for a
-file whose `epic_key` is exactly this epic (`docs_dir` is `BAPI_DOCS_DIR`, else
-`docs/tmp`, resolved against the Git top level; an absolute `BAPI_DOCS_DIR` is used
-as given). Exactly one match with a sibling `epic-plan.dag.json` is used as if you
-had passed `--plan-file`, and its path is printed before anything is created. Zero
-matches, two or more, or an unusable meta file **stop** with the paths found and
-create nothing, and a folder name, a child ticket key, or
-`sibling-ticket-manifest.json` is never used to guess. A supplied `--plan-file`
-always wins and discovery does not run.
-
-The meta file is `{"epic_key": "<KEY>"}`, written by `emit-epic-implementer-bundle
-finalize` beside the DAG (its own atomic write, reported as `meta_path` in
-`--json`). It is separate from `epic-plan.dag.json` on purpose: the DAG is sent to
-the server, which rejects unknown fields. A plan finalized before this change has no
-meta file, so it is reported as not found — pass its DAG with `--plan-file`.
-
-**A live run with no plan.** If the epic already has a live run and no plan was
-supplied or found, `drive-epic` creates nothing. It makes sure that run has an
-executor: it reuses a verified live one (never starting a second), starts one when
-the old one is gone, starts none for a durable launch profile with a confirmed
-repo-wide executor, and starts none when this checkout's plane is bound to that
-run. An epic with several active runs (`live-run-ambiguous`), or a run that cannot
-be read (`live-run-unknown`), is refused by name.
-
-**Preview with `--dry-run`.** `drive-epic <EPIC> --dry-run` is read-only. It reads
-the target, readiness, the live run, and the plan, runs the bootstrap's own dry-run
-validation when a plan is available, and reports the decision a real invocation
-would make — `create`, `attach`, `refuse`, or `stop` (exit `0` for the first two,
-`1` for the others). It never creates a run, cuts a branch, starts a plane,
-requests a lane, or starts or signals an executor. With `--json` (valid only with
-`--dry-run`) stdout carries exactly one JSON document with `epic_key`, `target`,
-`readiness`, `live_run`, `plan`, `summary`, `decision`, and `refusal`. The
-readiness `reason_id` and `remedy` are the strings the real refusal prints. The
-webhook URL, credentials, and policy contents are never included. The preview
-probes a local plane only when the target is a loopback plane, readiness failed on
-the network, and a plan is available. A refused port plus passing local preflight
-yields a conditional
-`create` with optional `cold_start` (`plane_endpoint`, `will_start_plane: true`,
-`live_run_checked: false`), `live_run: null`, and partial offline setup validation.
-The real launch attempts guarded startup, then rechecks run existence and server
-validation; the preview does not guarantee creation. Remote targets, non-refused
-port probes, and ordinary production previews keep their existing refusal or
-create behavior. `target.source` is optional and appears only for selected
-profiles (`profile` or `profile-env`).
-
-#### Running the server yourself (Bridge API source checkout only)
-
-The rest of this section, and [`plane up`](#plane-up--claim-scope-is-required)
-below, apply only when you run the Bridge API server on your own machine. That
-needs a Bridge API **source checkout**: `plane up` must run from its repository
-root (the directory holding `main.py`, `worker.py`, and `alembic.ini`), and its
-executor lanes run from that checkout's `mcp_server/build/index.js`, never from
-npx. If you target production, skip this part.
-
-**The composed bring-up is two-phase (BAPI-1102).** With `--plan-file` on a
-repository whose readiness is missing only the runtime facts, one invocation runs,
-in order: the **control plane** (Bridge API server + reconciler, each gated on its
-own readiness), then `setup-epic` to create and approve the run, then **executor
-lanes scoped to that run** with `--epic-run-id <run>`, then the **dead-man
-observer** last, then the ready banner. The order is forced: an executor lane must
-carry an explicit claim scope, and the run it is scoped to does not exist until the
-server is up and `setup-epic` has run.
-
-A plane's executor lanes serve **exactly one** run — the run it is bound to. A
-second epic does **not** start a second plane: it attaches to the running plane's
-reconciler and gets its own run-scoped executor. Two planes on one database are
-not supported. If `setup-epic` fails, the control plane is left running and **no
-executor lane is spawned**. If the lanes fail to become ready, the control plane
-and the committed run are both left intact and the observer is not started —
-nothing is rolled back, because a local process that failed to start says nothing
-about whether the run is valid.
-
-"Plane ready" reports **processes**, not dispatchability: if the run cuts an epic
-branch, the reconciler holds ticket dispatch until that branch's index scope
-finishes preparing.
-
-### `plane up` — claim scope is required
-
-`plane up` starts the runtime on its own, from a Bridge API source checkout, and
-every executor lane it starts needs an explicit claim scope:
+You are never asked to choose. If readiness is not green, it names each missing item with its fix and creates nothing. If readiness cannot be read (unreachable, unauthorized, or malformed), it stops and prints no run command, because an unknown state is not the same as a not-ready one.
 
-```
-npx -y @bridge_gpt/mcp-server plane up --epic-run-id <run-id>   # repeatable
-npx -y @bridge_gpt/mcp-server plane up --repo-wide              # or repository-wide
-```
+`drive-epic` owns no branch behavior of its own. It forwards `--feature-branch <name>`, `--into-base`, and `--attended` to `setup-epic`, which decides the strategy and the posture (see [`setup-epic`](#setup-epic)). With none of them, a multi-ticket epic runs on `epic/<KEY>`, unattended. It also forwards `--repo` and the policy flags: `--policy-file <path>` (the complete run policy), `--review-policy <src>` (a per-run review policy: `repository_policy`, `verdict_protocol`, `native_review_decision`, or `none`; omitted, the server stamps `repository_policy` at first approval for a new feature-branch run, and `verdict_protocol` is the explicit AI-review opt-in), and `--replace-policy` (allow replacing a live run's stored policy).
+
+**Every run gets an executor.** Once `drive-epic` creates a run, it starts an executor scoped to that run in the background, from this checkout's Git top level. The executor claims only that run's jobs, logs to `.bridge/executors/<run>.log`, and exits on its own when the run is done or abandoned. You do not start one by hand. Run `drive-epic` from a Git work tree inside the target repository; it checks this before creating anything. If the executor fails to start, the run is left intact and `drive-epic` prints the log path and the exact command to start it by hand.
+
+**Choosing the server.** With no flags, `drive-epic` targets production and uses the stored `bapi:<repo>` key when there is one. `--base-url <url>` (or `BAPI_BASE_URL`) names another server. A stored key approved for a different endpoint is never sent.
+
+**Finding the plan from the epic key.** `--plan-file` is optional. Without it, `drive-epic` searches `{docs_dir}/epic-plans/*/epic-plan.meta.json` for a file whose `epic_key` is exactly this epic (`docs_dir` is `BAPI_DOCS_DIR`, else `docs/tmp`, resolved against the Git top level; an absolute `BAPI_DOCS_DIR` is used as given). Exactly one match with a sibling `epic-plan.dag.json` is used as if you had passed `--plan-file`, and its path is printed before anything is created. Zero matches, two or more, or an unusable meta file **stop** with the paths found and create nothing. A folder name, a child ticket key, or `sibling-ticket-manifest.json` is never used to guess. A supplied `--plan-file` always wins and discovery does not run.
+
+The meta file is `{"epic_key": "<KEY>"}`, written beside the DAG by `/define-tickets` and by `emit-epic-implementer-bundle finalize` (reported as `meta_path` in `--json`). It is separate from `epic-plan.dag.json` on purpose: the DAG is sent to the server, which rejects unknown fields. A plan finalized before the meta file existed has none, so pass its DAG with `--plan-file`.
+
+**A live run with no plan.** If the epic already has a live run and no plan was supplied or found, `drive-epic` creates nothing. It makes sure that run has an executor: it reuses a verified live one (never starting a second) and starts one when the old one is gone. An epic with several active runs (`live-run-ambiguous`), or a run that cannot be read (`live-run-unknown`), is refused by name.
 
-The two are mutually exclusive. Asked to start lanes with neither, `plane up`
-**refuses before spawning anything**, in the executor's own words. That is not a
-new restriction — an executor started with no claim scope has refused to start
-since BAPI-1026 — it is that refusal moved to where it is actionable, instead of
-surfacing as a member crash and a full plane rollback.
+**Preview with `--dry-run`.** `drive-epic <EPIC> --dry-run` is read-only. It reads the target, readiness, the live run, and the plan, runs the bootstrap's own dry-run validation when a plan is available, and shows the decision a real invocation would make: `create`, `attach`, `refuse`, or `stop` (exit `0` for the first two, `1` for the others). It never creates a run, cuts a branch, requests a lane, or starts or signals an executor. With `--json` (valid only with `--dry-run`) stdout carries exactly one JSON document with `epic_key`, `target`, `readiness`, `live_run`, `plan`, `summary`, `decision`, and `refusal`. The readiness `reason_id` and `remedy` are the strings the real refusal prints. The webhook URL, credentials, and policy contents are never included.
 
-`plane status` reports the lifecycle phase (control plane starting/ready, lanes
-starting/ready, observer active, plane ready) and the epic run the plane is bound
-to. `plane down` handles every intermediate phase: it stops the bound run first,
-then signals the recorded process group.
+`drive-epic --help` lists every option. Owners who run their own Bridge server have extra steps: see `drive-epic --help-advanced`.
 
 ### `setup-epic`
 
@@ -1470,20 +1330,20 @@ branch, and one draft integration PR targets the repository base branch. This ho
 every path, CI and `--json` included. A single-node plan keeps the repository base
 branch, matching plain `start-tickets`.
 
-> **Behavior change (BAPI-1009).** The same no-flag command previously ran children
+> **Behavior change.** The same no-flag command previously ran children
 > directly into the repository base branch. **Pass `--into-base` to restore that**, if
 > your automation depends on it. Pass `--feature-branch <name>` to override the derived
 > name, or to force a branch for a single-node plan. Passing both is a parse error,
 > refused before any file read, credential resolution, or network call.
 
-**A run that selects an epic branch is created UNATTENDED (BAPI-1102).** Its
+**A run that selects an epic branch is created UNATTENDED.** Its
 `policy_json` carries `posture: "unattended"` and `v2_auto_merge_enabled: true`, so
 child PRs merge into the epic branch without parking for a human at every gate. The
 **integration PR into the repository base branch stays human-gated.** The run's CI
 gate is stamped **server-side at first approval** — from your repository's declared
 default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
 
-> **Behavior change (BAPI-1102).** Pass `--attended` to restore the previous
+> **Behavior change.** Pass `--attended` to restore the previous
 > composition: `base_branch` plus an explicitly requested `--review-policy`, with no
 > posture and no auto-merge authorization. `--into-base`, single-node plans, and
 > branch-silent invocations are **unchanged** — they send no `policy_json` at all,
@@ -1494,7 +1354,7 @@ default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
 An unattended run has two **repository** prerequisites — consent
 (`unattended_epic_implementer_allowed`, ON by default; the repository owner can switch
 "Allow unattended Epic Implementer runs" off and on in the Bridge admin panel's Setup
-page) and an **escalation channel** (BAPI-1274): a verified notify webhook, or,
+page) and an **escalation channel**: a verified notify webhook, or,
 when the policy declares no webhook, an email address on the account — plus
 confirmed default-branch review/CI workflows. Each is refused by name **before any
 run row is created** (`target_not_allowed`, `webhook_unverified`,
@@ -1504,33 +1364,52 @@ to email, and `notify.local_sink` does not count as a channel.
 `epic-implementer readiness` and `drive-epic` both list these prerequisites with
 their current state.
 
-Once the plan is approved, the **server-side reconciler** picks the run up within
-~30s. If you ran `setup-epic` directly, start an executor for the run yourself
-(`drive-epic` does this for you). An executor needs exactly one claim scope, or it
-refuses to start:
+**One switch decides a run's own merges.** A run's child merges into its
+epic branch follow the Setup-page switch "Allow unattended Epic Implementer runs".
+They do not read the legacy repository flags (`auto_merge_enabled`,
+`merge_approval_required`), which still govern merges made outside a run (the plain
+merge route, the approval route, and the `merge_pull_request` tool). The integration
+PR into the base branch is never eligible. If the switch is turned off mid-run, the
+reconciler **holds** each child that reaches merging: `explain_run` shows a pending
+`unattended_posture_off` observation, no job is created, and no attempt is spent.
+Turning the switch back on resumes merging on the next tick with no `unpark`. A hold
+longer than the merging gate's deadline parks through the normal watchdog. A local or
+machine-token merge already handed to the executor before the switch-off may still
+finish.
+
+**Launch capability summary.** An unattended `drive-epic` launch, and its
+`--dry-run`, check three rows before creating a run: the **unattended posture** (the
+Setup switch), **merge credential capability**, and **worktree preparation**. The
+server reports the resolved merge mode and the GitHub `owner/name`. In `local` mode the
+CLI probes `GITHUB_MERGE_TOKEN`, and in `machine_token` mode `BAPI_MACHINE_MERGE_TOKEN`,
+with `gh api --include repos/{owner}/{name}` and one pull-request read. Pass means the
+token has push permission and can read pull requests. `github_actions` mode shows one
+informational row and runs no local probe. The worktree row checks, without writing,
+that the executor clone's git `info/exclude` is present or writable.
+
+Each row carries a `blocking` flag. Only a **proven** problem blocks: the switch is off,
+the token is missing or invalid, a `404` or a `200` without push permission, or an
+exclude that is neither present nor writable. A `401`, `403`, `429`, `5xx`, a network
+error, a timeout, an unresolved repository, a non-local executor clone (a plane lane
+or a durable launch profile), or an older server that does not report the new fields
+is a **"capability not verified"** warning, not a refusal. `--attended` and
+`--into-base` make all three rows informational. The probe does not prove branch
+protection or rulesets; those are still checked at merge time. Upgrade the server
+before the MCP package: an older server simply yields the warning.
+
+Once the plan is approved, the **server-side reconciler** picks the run up within ~30s. If you ran `setup-epic` directly, start an executor for the run yourself (`drive-epic` does this for you). An executor needs exactly one claim scope, or it refuses to start, and it needs `--base-url` or `BAPI_BASE_URL`:
 
 ```
 npx -y @bridge_gpt/mcp-server executor --repo <name> --epic-run-id <run-id> --exit-when-run-terminal
-npx -y @bridge_gpt/mcp-server executor --repo <name> --repo-wide    # every run in the repo
 ```
 
-`executor install-service` generates a launchd/systemd user unit so a durable
-executor survives a reboot. `--base-url` or `BAPI_BASE_URL` is required: the
-executor has no production fallback.
+For durable hosts, see `drive-epic --help-advanced`.
 
 ### Epic Implementer reference
 
-The full reference — the v2 architecture (server-side reconciler + local
-executor), the CI gate, `epic-implementer install-git-hooks`, the supervisor
-`done_gate_config` / `auto_merge_enabled` settings, and the opt-in observability
-stream — lives in **[EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md)**.
-Auto-merge into the epic branch is **on by default** for unattended runs (see
-[`setup-epic`](#setup-epic)); only the `--conductor` observability layer is off by
-default.
+The full reference — how the engine works, the CI gate, `epic-implementer install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings (which govern merges outside a run; a run's own merges follow the Setup-page switch), and the opt-in observability stream — is in **[EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md)**. It is a reference, not a second walkthrough: start with the [Epic Implementer](#epic-implementer) section above.
 
-Two retired names remain as failing pointers. The event-ledger CLI was renamed
-from `conductor` to `epic-implementer`, and `emit-conductor-bundle` to
-`emit-epic-implementer-bundle`; the old names now print the new name and exit.
+Two retired names remain as failing pointers: the old event-ledger CLI name and `emit-conductor-bundle`. Both print the new name (`epic-implementer`, `emit-epic-implementer-bundle`) and exit.
 
 > The v1 `epic-implementer epic-tick` command is **frozen** — it throws on every invocation. There is nothing to schedule locally, and `epic-implementer doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.
 
@@ -1588,23 +1467,26 @@ Optionally set a repository Actions **variable** named `BAPI_BASE_URL` to point
 
 #### Merge credentials (`local` and `machine_token` modes)
 
-No merge path reads an ambient `gh` login. Each mode reads exactly one
-process-launch configuration key, with **no fallback** between them and none to
-an inherited `GH_TOKEN`, `GITHUB_TOKEN`, a `gh auth` session, or the Bridge
-credential store. Bridge never stores either value.
+No merge path reads an ambient `gh` login. The two modes are separate, with **no
+fallback** between them and none to an inherited `GH_TOKEN`, `GITHUB_TOKEN`, or a
+`gh auth` session.
 
 | Mode | Key | Provenance |
 |---|---|---|
-| `local` | `BAPI_LOCAL_MERGE_TOKEN` | A configured local scoped credential. |
-| `machine_token` | `BAPI_MACHINE_MERGE_TOKEN` | Your machine user's credential. |
+| `local` | `GITHUB_MERGE_TOKEN`, then `BAPI_LOCAL_MERGE_TOKEN`, then a stored entry | A scoped GitHub token for this repository. Setup can store one on your computer as `github-merge:<host>/<owner>/<repo>` in `~/.config/bridge/credentials.json`; either environment variable takes precedence over it. |
+| `machine_token` | `BAPI_MACHINE_MERGE_TOKEN` | Your machine user's credential, read from the environment only. A stored `github-merge:` entry does not configure this mode. |
 
-Supply them at process launch, or from an approved external secret manager.
+Supply environment keys at process launch, or from an approved external secret manager.
+
+A probe that passes shows the key has push permission and can read pull requests.
+It does not prove branch protection or repository rules; those are checked at merge time.
 
 | Preflight outcome | Remediation |
 |---|---|
-| `*_credential_missing` | Set the mode's key in the environment this MCP server is launched with. |
+| `*_credential_missing` | Set the mode's key in the environment this MCP server is launched with. For `local` mode, setup can instead store a token for this repository. |
 | `*_credential_invalid` | GitHub rejected the configured credential. Rotate it and relaunch. |
-| `*_credential_unpermitted` | It authenticates but cannot write to this repository. Grant it merge permission. |
+| `*_credential_unpermitted` | GitHub answered `404`, or `200` without push permission, for this repository. Grant it push access. |
+| capability probe unavailable | GitHub answered `401`, `403`, `429`, or `5xx`, or the probe timed out. At launch this is a "capability not verified" warning; at merge time the merge is refused. Retry, then check the token by hand. |
 | `local_gh_unavailable` | Install the GitHub CLI (`gh`) on the machine running this MCP server. |
 
 #### What the workflow does and does not do
@@ -1724,7 +1606,7 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `BAPI_PLANE_PYTHON` | No | `python` | Executable used for the Python members of `plane up` (Bridge API source checkout only). Point it at a venv interpreter when `python` on `PATH` is not the one you want |
 | `BAPI_PLANE_UVICORN` | No | `uvicorn` | Executable used for the server member of `plane up` |
 | `BAPI_PLANE_PORT` | No | `8000` | Port for the local plane server (`127.0.0.1`). Only for `plane up` and a local `drive-epic` target, from a Bridge API source checkout |
-| `BAPI_EPIC_LAUNCH_PROFILE` | No | _(none)_ | Selects a host-local launch profile (saved by `install conductor --launch-profile`) for `drive-epic`. `--launch-profile` takes precedence. See [`drive-epic`](#drive-epic) |
+| `BAPI_EPIC_LAUNCH_PROFILE` | No | _(none)_ | Selects a host-local launch profile (saved by `install conductor --launch-profile`) for `drive-epic`. `--launch-profile` takes precedence. See `drive-epic --help-advanced` |
 | `BAPI_DOCS_DIR` | No | `docs/tmp` | Local directory for saving plans, critiques, and research reports |
 | `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |
 | `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |
@@ -1732,7 +1614,7 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation — it only gates the recipe-preamble convention |
 | `BAPI_MCP_TOOL_SURFACE_GATING_ENABLED` | No | _(enabled)_ | MCP-local kill switch for **dynamic tool-surface capability gating** (see [Dynamic tool-surface gating](#dynamic-tool-surface-gating-capability-availability)). Default-on; set to `false`/`0`/`no`/`off`/`disabled` to skip the startup probe, the recurring poll, and the custom `tools/list` handler entirely, restoring the SDK's previous full profile-derived surface. Fail-open: any probe timeout, unreachable backend, non-2xx, malformed payload, incomplete evaluation, or unsupported schema advertises the full profile |
 | `BAPI_MCP_TOOL_SURFACE_POLL_ENABLED` | No | _(disabled)_ | Opt IN to the recurring tool-surface **poll**. Default-**off**: a session gates once via the startup probe and never re-probes. Set to `true`/`1`/`yes`/`on`/`enabled` to restore the jittered 12–18 s heartbeat that pushes `notifications/tools/list_changed` on mid-session capability changes. No effect when gating itself is disabled |
-| `BAPI_MCP_UPDATE_CHECK_ENABLED` | No | _(enabled)_ | MCP-local kill switch for the cached update check run at startup. Default-on; set to `false`/`0`/`no`/`off`/`disabled` to skip it entirely — no npm registry request, no update-cache read/write, no stderr advice, and no `tools/list` advisory decoration. Any other value is treated as enabled. Useful behind a firewall/registry-restricted network, and used by the payload-measurement harness so a stale local cache can never perturb a capture |
+| `BAPI_MCP_UPDATE_CHECK_ENABLED` | No | _(enabled)_ | MCP-local kill switch for the cached update check run at startup. Default-on; set to `false`/`0`/`no`/`off`/`disabled` to skip it entirely — no npm registry request, no update-cache read/write, and no upgrade notice on any surface (see [Upgrade notices](#upgrade-notices)). Any other value is treated as enabled. Useful behind a firewall/registry-restricted network, and used by the payload-measurement harness so a stale local cache can never perturb a capture |
 | `CURSOR_API_KEY` | No | _(none)_ | API key used to authenticate `cursor-agent` when launching `start-tickets`/scheduled runs with `--agent cursor-agent`. Not needed for the default Claude Code agent |
 | `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile — a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default — normal coding tools only), `epic_implementer` (+ the 2 Epic Implementer tools, `get_epic_snapshot` and `explain_run`), `pipeline-authoring` (adds **no** tools since BAPI-909; still accepted so old configs keep working — `get_pipeline_recipe` stays in `core` because the recipe-driven slash commands depend on it), `estimation` (+ `estimate_epic`, which is **hidden by default** — `/estimate-epic` needs this group), `sfcc` (+ the 8 heavy SFCC read tools, `sfcc_log_query`, and the `sfcc_setup_status`/`check_permissions` diagnostics — read-only, see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)), `sfcc-write` (+ the 9 destructive SFCC write tools — independent of `sfcc`, which does not enable them; see [Read and write profiles](#read-and-write-profiles)), and `full` (shortcut that expands to every group, **including `estimation` and `sfcc-write`**). Example: `sfcc,epic_implementer`; use `sfcc,sfcc-write` for reads plus writes. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported — groups are resolved once at process startup, so **changing this variable requires restarting the MCP server**. That is separate from the learn/onboarding tools, which are gated per session and can appear mid-session without a restart (see [Learn/onboarding tool availability](#learnonboarding-tool-availability)). Epic Implementer sessions launched via `start-tickets --conductor` **merge** `epic_implementer` into the parent process's already-resolved groups at the spawn boundary rather than replacing them — a project running on `sfcc` spawns workers on `core,sfcc,epic_implementer`. The retired token `conductor` is no longer valid and is dropped like any unknown token. A normal `start-tickets` run stays on `core`. |
 
@@ -1989,7 +1871,7 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The authoritative tool catalog covers **78 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the Epic Implementer (`epic_implementer`), estimation, and SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The authoritative tool catalog covers **80 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the Epic Implementer (`epic_implementer`), estimation, and SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping` (its JSON also carries `docs_dir`, `role`, and `customer_type`)
 - **Team & access** — `invite_member` (admin-only; mints a scoped access key for a teammate on an already-configured project — the plaintext key is shown exactly once)
@@ -1998,7 +1880,7 @@ The authoritative tool catalog covers **78 tools** (enumerated below). What's ac
 - **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/architecture/fsd/prd, where `architecture` is an alias of `tdd`), `request_ticket_review` (writes both `get_clarifying_questions` and `get_ticket_critique`), `request_reimplement_context`/`get_reimplement_context`, `request_council`/`get_council`, `request_deep_research`/`get_deep_research`
 - **Bounded waits** — `wait_for_ticket_review`, `wait_for_ci_checks`. Each returns `state: "ready" | "pending" | "error"`; review waits default to 20 s and CI waits default to 240 s (both accept up to 240 s explicitly). `pending` is a normal, resumable result you call again on, never a failure. They exist so an agent can wait without a foreground `sleep` and without binding a long server-side operation to the 900 s MCP client deadline. `wait_for_ci_checks` reports only that checks are **terminal** — deciding pass or fail stays with the caller.
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
-- **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`, `get_ticket_state_tree` (live repo-wide lifecycle + dependency tree; read-only, no mutation parameter)
+- **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`, `get_ticket_state_tree` (live repo-wide lifecycle + dependency tree; read-only, no mutation parameter), `get_epic_contract_context` (an epic child's parent requirements and sibling contracts, with explicit coverage; read-only)
 - **Jira status** — `update_jira_status` (pass `status: "auto"` to resolve the configured post-PR status server-side)
 - **Repository & CI** — `parse_repository` (`action`: `start`, `status`), `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `wait_for_ci_checks` (the last two are hidden until `ci_check_config` resolves, and share one visibility gate)
 - **Epics** — `assess_epic_implementer_eligibility` (core; read-only prediction, before a run, of which epic children change workflow files and so need hand review; the old `assess_epic_conductor_eligibility` name returns `tool_removed`), `estimate_epic` (`estimation` profile), and `get_epic_snapshot` / `explain_run` (`epic_implementer` profile; read-only run state and "why is it stuck"; an unknown run returns `status: "unknown"`)
@@ -2110,9 +1992,33 @@ outcome is unknown, a challenge cannot be recovered, or installation asks for su
 Never delete possibly redeemed proof to restart. Ordinary invite tokens and
 verification codes are not stored.
 
+### Didn't get the code?
+
+The code comes from noreply@bridgegpt-api.com and usually arrives within
+two minutes. Delivery is retried for about two hours, so it can come late.
+
+- Check your spam, junk, and quarantine folders. Search for
+  noreply@bridgegpt-api.com.
+- At the code prompt, type r to send a new code. Earlier codes keep
+  working. You can ask for up to two new codes, a minute apart.
+- Typed the wrong address? Press Ctrl-C and re-run install with the right
+  one. Install offers to start a new signup.
+- A code lasts four hours. If it expires, re-run install from the same
+  folder. Install offers to start a new signup.
+- A teammate on Bridge can send you an invite. Choose "I already have a
+  token", or pass --invite.
+- Still stuck? Email info@bridgegpt.ai.
+
+### Credential storage
+
 Credential storage uses bounded exclusive locking without timeout-based stealing.
-An abandoned lock needs installation support. POSIX systems sync the containing
+An abandoned lock needs help: contact Bridge support at info@bridgegpt.ai and keep
+the recovery proof. POSIX systems sync the containing
 directory; Windows uses file sync plus atomic replacement because portable Node
 directory handles are unavailable. A failure after rename is an uncertain durability
 outcome: the new bytes may already exist. Rerun reloads the actual store under lock;
 there is no guarantee that old pending bytes survive every failure.
+
+### Out of scope
+
+The CLI cannot diagnose non-delivery, a sender mismatch, or incompatible server behavior. It preserves saved attempts, uses the existing neutral guidance and server-enforced resend limits, and still permits the existing teammate-invite route; unresolved cases go to info@bridgegpt.ai, which does not promise a support-issued invite or a verification bypass.