@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/README.md

@@ -10,16 +10,35 @@ From your **project root**, run:
 npx -y @bridge_gpt/mcp-server install
 ```
 
-That is the whole setup command. It works whether or not you already have a Bridge
-account — it will ask.
+That command starts guided setup. It works whether or not you already have a Bridge
+account — it will ask; follow the remaining onboarding instructions afterward.
+
+### Already ran `npm i @bridge_gpt/mcp-server`?
+
+> The package and its executable aliases are installed, but your intended project
+> and MCP host still need setup. From your intended project root, run:
+>
+> ```bash
+> npx -y @bridge_gpt/mcp-server install
+> ```
+>
+> You do not need to uninstall the package first. [Continue with the step-by-step
+> setup instructions](#installing-step-by-step) for sign-in, host selection,
+> reload/trust, and agent handoff.
+
+> Package installation is passive: Bridge cannot detect or notify someone who only
+> installs the package and does nothing else. Successful lifecycle output is not a
+> reliable default-install notification because `foreground-scripts` normally
+> defaults to false, and `ignore-scripts` can disable hooks entirely.
 
 > We recommend **the command above** instead of the `npm i @bridge_gpt/mcp-server`
 > one in npm's sidebar, because it **will make set up much easier**.
 
 **What it will do**
 
-- **Bootstraps the Bridge MCP for you** — one command and your editor's agent can
-  use Bridge's tools and slash commands on this project.
+- **Starts guided Bridge MCP setup** — after completing the remaining onboarding
+  instructions, your editor's agent can use Bridge's tools and slash commands on
+  this project.
 - Registers a `bridge` MCP server in your editor's MCP config, leaving any
   other servers you have configured untouched.
 - Creates and updates the files it needs inside your project root: slash commands
@@ -60,6 +79,7 @@ account — it will ask.
   - [Operational commands](#operational-commands)
   - [Extra Capabilities](#extra-capabilities)
 - [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)
+- [Epic Implementer](#epic-implementer)
 - [CLI Subcommands](#cli-subcommands)
 - [Custom Pipelines](#custom-pipelines)
 - [Environment Variables](#environment-variables)
@@ -67,7 +87,7 @@ account — it will ask.
 - [Personal model routing preferences](#personal-model-routing-preferences)
 - [Reference](#reference)
 
-For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./docs/CONDUCTOR.md).
+To drive a whole epic of tickets automatically, start with [Epic Implementer](#epic-implementer) below. The command details are in [The Epic Implementer](#the-epic-implementer), and the full reference is [EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md).
 
 ## Installation details
 
@@ -216,8 +236,8 @@ re-run the command from the right directory — if you already had a `.vscode/`,
 (`npx -y @bridge_gpt/mcp-server`) with no subcommand, you started the MCP *server*,
 not the installer. It is waiting for an editor to connect over stdio, which is
 exactly what it should do when your editor launches it — but from a terminal it
-looks like a hang. It prints a line saying so. Press Ctrl-C and run
-`npx -y @bridge_gpt/mcp-server install` instead. The explicit spelling
+looks like a hang. It prints a stderr guidance block explaining this. Press Ctrl-C
+and run `npx -y @bridge_gpt/mcp-server install` instead. The explicit spelling
 `npx -y @bridge_gpt/mcp-server serve` starts the server on purpose.
 
 **"It can't reach Bridge" or "my key was rejected."** The installer checks
@@ -373,7 +393,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -395,7 +415,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -417,7 +437,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -440,7 +460,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -459,7 +479,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.68", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -584,7 +604,7 @@ The tools worth knowing for most tickets.
 - **What it does:** Analyzes a single task or feature specification to define, refine, and structure one or more actionable Jira tickets. It maps the code paths, dependencies, and project conventions the task would touch, settles acceptance criteria with you on a decision page, then compares the viable implementation approaches and their trade-offs so the ticket work is grounded in the real codebase. Along the way it surfaces the ambiguities that still need deciding and can pull in optional web or deep research where the answer is not in the code.
 - **When it's useful:** (Architecture | Refinement) Before writing a ticket or a plan, when you're unsure how a change would fit the existing code and want the open questions and the realistic options laid out first.
 - **How to use it:** `/define-tickets <task>` — *"Define the tickets we'd need to add a Mistral LLM provider."*
-- **Flags:** None.
+- **Flags:** `--auto` runs unattended, `--allow-duplicate` proceeds past a known duplicate, and `--max-children=N` caps the ticket count (default 10). `--allow-duplicate` and `--max-children=N` take effect only with `--auto`.
 
 **5. AI Council**
 - **What it does:** Fans your problem out to two different models and returns their approaches, in technical, design, discovery, or general mode.
@@ -638,6 +658,12 @@ Good to know, but not needed every day.
 - **How to use it:** `/create-decision-page <topic or open questions>` — e.g. *"how we handle rate limiting"* — or leave it empty to frame the open choices already raised earlier in the conversation.
 - **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.
+- **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.
+- **Flags:** None — the epic key and an optional plan path are the only arguments.
+
 ### Now and then
 
 Useful once in a while.
@@ -738,10 +764,10 @@ Slash commands that drive several tools at once. Start Tickets, Review and Start
 - **Flags:** None — name a specific standards file in your request to have it applied when drafting.
 
 **3. Idea to Ticket**
-- **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.
-- **When it's useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.
+- **What it does:** A deprecation alias for `/define-tickets`, kept for one release. It prints a one-line notice and forwards your idea and flags unchanged to `/define-tickets`.
+- **When it's useful:** (Refinement | Automation) Only while you migrate; use `/define-tickets` for new work.
 - **How to use it:** `/idea-to-ticket <idea>`
-- **Flags:** None.
+- **Flags:** `--auto`, `--allow-duplicate`, and `--max-children=N`, all forwarded to `/define-tickets`. Without `--auto` you get the attended `define-tickets` flow; `--allow-duplicate` and `--max-children=N` take effect only with `--auto`.
 
 **4. Plan Epic**
 - **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.
@@ -751,7 +777,8 @@ Slash commands that drive several tools at once. Start Tickets, Review and Start
 
 #### Ticket-authoring posture
 
-`/define-tickets`, `/idea-to-ticket`, and `/plan-epic` all decide ticket shape
+`/define-tickets` is the single ticket-creation entry point. It, the deprecated
+`/idea-to-ticket` alias, and `/plan-epic` all decide ticket shape
 the same way, as does the `jira-ticket-writer` agent they draft through. A fresh install inherits this with no configuration
 step and no server call; the full rationale and the closed exception list ship as
 `docs/bridge-ticket-authoring.md`.
@@ -774,7 +801,7 @@ step and no server call; the full rationale and the closed exception list ship a
   then fans out one writer invocation per entry against that frozen manifest. A
   rendering invocation never re-splits, merges, reorders, or rescopes.
 - **Handed off once.** An epic handoff names exactly one entry point,
-  [`drive-epic`](#drive-epic) — never a choice between conductors.
+  [`drive-epic`](#drive-epic) — never a choice between two ways to run it.
 
 **5. Run Tests**
 - **What it does:** Runs the unit and E2E suites and autonomously triages/fixes failures (via the test-correction agent).
@@ -883,13 +910,13 @@ Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `
 
 Credentials resolve in **three tiers, highest first** — the environment wins over `dw.json`, not the other way round:
 
-1. An explicit dotted `instance` argument on the call, **plus** `SFCC_CLIENT_ID` and `SFCC_CLIENT_SECRET` in the environment. Secrets are never read from `dw.json` on this tier, so an explicit instance without those two env values is an error.
+1. An explicit dotted `instance` argument on the call. An unapproved host is refused with `403` `TARGET_NOT_SANDBOX` **before** any credential lookup. An approved host is matched against the configs in `dw.json` (single or `configs[]`); a config for that exact host supplies the credentials. Otherwise `SFCC_CLIENT_ID` and `SFCC_CLIENT_SECRET` in the environment are the fallback, and with neither the call fails as `CREDENTIAL_RESOLUTION_FAILED` (`400`).
 2. `SFCC_HOSTNAME` **and** `SFCC_CLIENT_ID` **and** `SFCC_CLIENT_SECRET`, all three set.
 3. `dw.json`.
 
 Because tier 2 outranks tier 3, a stale `SFCC_HOSTNAME` left in the environment silently wins over the `dw.json` you are looking at. Check both when a tool reports an unexpected host.
 
-**Use a single-config `dw.json`, or set all three `SFCC_*` variables.** A multi-entry `configs[]` array is **rejected outright** — it is not a working setup that merely requires an explicit `instance` on every call. Two things make that workaround unavailable: an explicit `instance` takes tier 1, which needs the client id and secret in the environment anyway, and most tools cannot accept a hostname at all — the value must contain a dot, and the site-preference tools constrain `instance` to `staging | development | sandbox | production`, none of which is a hostname.
+**With a multi-entry `configs[]` array, name the sandbox on each call.** Pass one of the listed hostnames as `instance` and that config's credentials are used. Without an `instance`, a multi-config `dw.json` fails as `multi-sandbox`, listing the full hostnames. Most tools cannot accept a hostname at all — the value must contain a dot, and the site-preference tools constrain `instance` to `staging | development | sandbox | production`, none of which is a hostname — so a single-config `dw.json` (or all three `SFCC_*` variables) remains the simplest setup.
 
 **3. Enable the tools you want.** Add the groups to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated), then **restart the MCP client**:
 
@@ -904,9 +931,9 @@ Because tier 2 outranks tier 3, a stale `SFCC_HOSTNAME` left in the environment
 Read what it prints before pasting it. The output is **two labelled blocks**, and they are not equivalent:
 
 - **READ/SEARCH TOOL GRANTS** — what the `sfcc` read tools need: `get` on `/system_object_definitions`, and `get` + `post` on `/system_object_definitions/**`, `/site_preferences/**`, and `/custom_object_definitions/**`. The `post` is OCAPI's convention for its `*_search` endpoints, not a mutation — but it is a grant you are pasting, so it is labelled for what it is rather than as "read-only".
-- **MUTATION GRANTS** — required by the nine `sfcc-write` tools and by nothing else: `put`/`patch` on `/system_object_definitions/**` and `/custom_object_definitions/**`, and `patch` on `/site_preferences/**`. Paste this block only if you intend to enable `sfcc-write`.
+- **MUTATION GRANTS** — required by the nine `sfcc-write` tools and by nothing else: `put`/`patch` on `/system_object_definitions/**` and `/custom_object_definitions/**`, and `patch` on `/sites/*/site_preferences/**` (value writes are site-scoped; the read/search grant keeps the org-level `/site_preferences/**`). Paste this block only if you intend to enable `sfcc-write`. **If you pasted an earlier mutation grant, it lacks the site-scoped resource:** replace `<YOUR_CLIENT_ID>` with your client id in the newly printed grant and paste it again before running value writes.
 
-Neither block grants `delete`, and neither pastes the global `resource_id: "/**"` that would cover every Data API resource. Each entry names one resource family — `/system_object_definitions`, `/custom_object_definitions/**`, `/site_preferences/**` — so the wildcard is scoped to the family, not to the API. Within a family it is still broad, and `write_attributes` is `(**)`, so a throwaway sandbox is the right place for these.
+Neither block grants `delete`, and neither pastes the global `resource_id: "/**"` that would cover every Data API resource. Each entry names one resource family — `/system_object_definitions`, `/custom_object_definitions/**`, `/site_preferences/**` (read/search), `/sites/*/site_preferences/**` (mutation) — so the wildcard is scoped to the family, not to the API. Within a family it is still broad, and `write_attributes` is `(**)`, so a throwaway sandbox is the right place for these.
 
 </details>
 
@@ -982,7 +1009,7 @@ Attribute-definition reads and writes can return an attribute's `default_value`
 
 **Diagnostics** (registered by the `sfcc` profile)
 - `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.
-- `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (read/search grants for the `sfcc` tools, mutation grants for the `sfcc-write` tools). An explicit `instance` hostname is still subject to the sandbox check below.
+- `check_permissions` — probe OCAPI **read** access via `GET /system_object_definitions` (it does not probe write access); on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (read/search grants for the `sfcc` tools, mutation grants for the `sfcc-write` tools). An explicit `instance` hostname is still subject to the sandbox check below.
 
 **System object model — reads** (needs the `sfcc` profile)
 - `system_object_list` — list system object types (Product, Order, Customer, …).
@@ -1007,7 +1034,7 @@ Attribute-definition reads and writes can return an attribute's `default_value`
 - `site_preference_group_list` — list the preference groups on a site. This is the discovery tool the other two reads depend on: both take a group, and this is how you find one.
 - `site_preference_get` — list the preference **identifiers** in a group.
 - `site_preference_search` — search/filter preference identifiers within a group.
-- `site_preference_values_set` — **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.
+- `site_preference_values_set` — **write** (sandbox only): set custom preference values for one required `site_id` via `PATCH /sites/{site_id}/site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.
 
 > **Site preference values are write-only through this surface.** `site_preference_get` and `site_preference_search` return **ids only, never values** — an unset preference and one set to the empty string are indistinguishable. So you can *set* a value with `site_preference_values_set` and have no way to read it back through an MCP tool. Business Manager is the supported path to read a preference value.
 
@@ -1019,6 +1046,77 @@ Attribute-definition reads and writes can return an attribute's `default_value`
   - **Auth is separate from OCAPI.** Log retrieval uses **HTTP Basic auth** — a Business Manager username + a **40-character WebDAV access key** — *not* the OCAPI Account Manager OAuth token the other SFCC tools use. A valid AM bearer token 401s on `/Logs`. `sfcc_setup_status` step 5 (AM/OCAPI token) and step 6 (WebDAV log access) are independent: one can be green while the other is not.
   - **Local / air-gapped fallback.** The primary path above is the only path this tool takes. For air-gapped development, the documented fallback is Salesforce's own **`@salesforce/b2c-cli`**, shelled out to directly: `b2c logs get --since <window> --search <q> --json`. There is no MCP alternative to reach for — `@salesforce/b2c-dx-mcp` ships **no `logs_*` tool** as of 1.1.2, and every log workflow in the vendor toolkit goes through the CLI anyway (see the [vendor manual](../docs/mcp/b2c-commerce-developer.md)). It is **not** the primary path because its credentials live client-side and its output has **not** passed Bridge's redaction/filter. If you use it, its output must be treated as raw: route it back through the same server-side Python `LogSource` composition and `RedactionPort`/T3 filter workflow — never paste or relay unredacted CLI output to an LLM.
 
+## 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.
+
+**What it requires**
+
+- 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`.
+
+**How to set it up**
+
+The easy way is to ask your agent:
+
+> Set up the Epic Implementer by following `docs/install/epic-implementer-install.md`.
+
+`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
+```
+
+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`.
+
+**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.
+
 ## CLI Subcommands
 
 Beyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) — so they travel with the package to every consumer. See [Usage Documentation → Start Tickets](#regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.
@@ -1044,7 +1142,7 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |
 | `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever `--base-branch` resolves to. |
 | `--max-parallel N` | `3` | Max worktrees created concurrently |
-| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_EPIC_IMPLEMENTER_*` env + Claude hook injection, lifecycle ledger events, and a supervisor peer tab). **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
+| `--conductor` | off | Opt into Epic Implementer observability (per-worker `BAPI_EPIC_IMPLEMENTER_*` env + Claude hook injection, lifecycle ledger events, and a supervisor peer tab). The flag keeps its name from before the Epic Implementer rename. **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
 | `-h`, `--help` | — | Show usage |
 
 Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent. Claude is the default. Cursor with `--auto` runs headlessly after a bounded authentication/readiness check; manual Cursor runs remain interactive for human review gates. To launch Cursor Agent instead of Claude Code:
@@ -1063,7 +1161,7 @@ For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-mod
 
 **Machine-carried `--auto-tier` handoff (BAPI-1236).** Passing `--auto-tier cheap|basic|premium` also bypasses the per-ticket difficulty lookup, but — unlike `--tier` — the carried tier IS routed through the launching session's own `maximize_subscription` downshift, exactly once. A malformed, empty, or repeated `--auto-tier` value is a hard parser error (no fail-open sentinel), and `--tier`/`--auto-tier` are mutually exclusive regardless of order. `/review-and-implement` uses this flag, never `--tier`, to hand its review-time raw tier snapshot to the fresh implementation session — so a `maximize_subscription` repo still gets the downshift on the chained handoff instead of silently skipping it.
 
-**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./docs/CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
+**Epic Implementer observability (opt-in via `--conductor`, BAPI-394).** The flag keeps its name from before the Epic Implementer rename. Observability is **off by default**. With `--conductor`, a run mints a `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree. It also **merges** `epic_implementer` into the workers' `BRIDGE_MCP_PROFILE`, so workers get the Epic Implementer MCP tools. Observability is best-effort — a failure here never blocks a spawn, and `--dry-run` performs no observability side effects. See **[EPIC-IMPLEMENTER.md](./docs/EPIC-IMPLEMENTER.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
 
 **Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.
 
@@ -1073,6 +1171,55 @@ For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-mod
 
 Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` — Worktrunk's `pre-start` hook runs `uv`, but live preflight does not check it — and the selected agent's command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).
 
+### Missing packaged workflow files
+
+Run read-only `doctor` to distinguish absent, unreadable, unsafe, and uncertain
+workflow files. Healthy discovery adds no recovery prose. Confirmed loss in a
+root-bound initialized installation adds bounded recovery metadata and guidance;
+unknown hosts, fallback roots, legacy inventories, and newer bundle additions do
+not establish historical loss. Readable customized or uncommitted files count as
+present; committing generated files is unnecessary.
+
+```sh
+npx -y '@bridge_gpt/mcp-server@<running-version>' repair-assets --project-root '/path/to/project' --host claude
+```
+
+Replace `<running-version>` with the running package version. Both explicit root and host
+options authorize fill-only provisioning without inventory. Otherwise repair
+requires a matching inventory at the exact selected root; callers in a project
+subdirectory must supply `--project-root`. The canonical selected root is printed
+before writes. Unpinned `npx -y @bridge_gpt/mcp-server repair-assets` intentionally
+selects the latest package, which may introduce new assets.
+
+| Host | Packaged destinations |
+| --- | --- |
+| `claude` | `.claude/commands/`, `.claude/agents/`, shipped documentation |
+| `cursor` | `.cursor/commands/`, shipped documentation; no native agent definitions |
+| `codex` | `.agents/skills/bridge-*/SKILL.md`, shipped documentation |
+| `copilot` | Independent `.github/prompts/`, `.github/skills/`, `.github/agents/`, shipped documentation |
+
+Repair preserves existing bytes and concurrent creation winners. It prepares
+complete temporary files, flushes/closes them, and publishes with exclusive hard
+links. A confined Linux procfs adapter supports writes; macOS/Windows currently
+refuse missing-file writes because a qualified descriptor-relative adapter is
+unavailable. Non-files, permissions, unsafe ancestry, unsupported publication, or
+cleanup failures produce a nonzero exit and distinct diagnostics. Repair does not
+refresh or upgrade existing content.
+
+When a missing host command prevents Bridge invocation, run the terminal command
+from the established root, then refresh/reconnect and run doctor. Hosts may cache
+lists or ignore notifications; healthy files do not guarantee host presentation.
+If the mismatch persists, consult host support.
+
+Plans/reviews/research reports are generated outputs: retrieve identified existing
+results using `get_plan`, `wait_for_ticket_review` for eligible canonical legs,
+`get_deep_research(task_id)`, or `get_council(council_id)`. Never silently rerun paid
+generation. Agent-reviewed rewrites must be recreated and reviewed before
+publication; neither retrieval nor installer repair reconstructs them.
+
+Custom pipelines/instructions, MCP registration/configuration, credentials,
+onboarding/API setup, and Windsurf are outside packaged repair.
+
 ### `doctor`
 
 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:
@@ -1087,7 +1234,7 @@ The report also includes a **Claude login** advisory: whether the host's own
 `~/.claude.json` carries a login marker. This is informational only — it never
 blocks the doctor run and cannot guarantee the next worker spawn will
 authenticate. See
-[Claude login for conductor workers](#claude-login-for-conductor-workers).
+[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.
 
@@ -1107,30 +1254,107 @@ worker against a stale base prints the same advisory and **still spawns the
 worker**. Remedy and full diagnosis:
 `docs/claude/runbooks/claude-review-base-branch-drift.md`.
 
+### 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.
+
+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.
+
 ### `drive-epic`
 
-The one conductor entry point every Bridge surface names. Give it an epic key and
-it reads conductor readiness for your repository and routes to the single path
-your project can actually run:
+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:
 
 ```
 npx -y @bridge_gpt/mcp-server drive-epic <EPIC>
 ```
 
-You are never asked to choose. `drive-epic` routes to exactly one conductor, the
+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 conductor to fall back
-to — and prints no conductor invocation. If readiness is **unknown** — unreachable,
-unauthorized, or malformed — it escalates and prints no conductor invocation at
+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.
+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
@@ -1166,9 +1390,10 @@ requests a lane, or starts or signals an executor. With `--json` (valid only wit
 `--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 does
-probes only a selected loopback plane after a network readiness failure and an
-available plan. A refused port plus passing local preflight yields a conditional
+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
@@ -1177,6 +1402,15 @@ 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
@@ -1186,24 +1420,23 @@ observer** last, then the ready banner. The order is forced: an executor lane mu
 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 composed plane serves **exactly one** run; start a second plane for a second
-epic. 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.
+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.
 
-Two conductors is a transitional state. When one is eliminated, `drive-epic` is
-the only thing that changes.
-
 ### `plane up` — claim scope is required
 
-`plane up` starts the runtime on its own, and every executor lane it starts needs
-an explicit claim scope:
+`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:
 
 ```
 npx -y @bridge_gpt/mcp-server plane up --epic-run-id <run-id>   # repeatable
@@ -1223,13 +1456,13 @@ then signals the recorded process group.
 
 ### `setup-epic`
 
-Bootstraps an Epic Conductor v2 run in one command — creates the epic run, stores the plan DAG, and approves it:
+Bootstraps an Epic Implementer v2 run in one command — creates the epic run, stores the plan DAG, and approves it. `drive-epic` runs it for you; call it directly only when you want the bootstrap on its own:
 
 ```
 npx -y @bridge_gpt/mcp-server setup-epic --epic-key <KEY> --plan-file <path-to-epic-plan.dag.json>
 ```
 
-The plan sidecar is produced by the `decompose-epic` pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable dependency references, acyclicity) before sending anything, so a malformed plan fails legibly instead of as a bare HTTP 400. It is **idempotent**: re-running it on an epic that already has a live run reuses that run rather than minting a second one. `--dry-run` validates and previews the calls without mutating anything; `--json` emits a single machine-readable result object.
+The plan sidecar is produced by the `decompose-epic` pipeline step (the `/plan-epic` flow). `setup-epic` validates it locally (unique ticket keys, resolvable dependency references, acyclicity) before sending anything, so a malformed plan fails legibly instead of as a bare HTTP 400. It is **idempotent**: re-running it on an epic that already has a live run reuses that run rather than minting a second one. `--dry-run` validates and previews the calls without mutating anything; `--json` emits a single machine-readable result object. It takes the same policy flags as `drive-epic` (`--policy-file`, `--review-policy`, `--replace-policy`), plus `--plan-version` and `--local-only`; see `setup-epic --help`.
 
 **The command above uses an epic branch.** For a plan with **two or more** nodes and
 no branch flag, `setup-epic` derives `epic/<KEY>`: every child-ticket PR targets that
@@ -1261,49 +1494,61 @@ 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 a verified notify webhook default — plus
+page) and an **escalation channel** (BAPI-1274): 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`,
-`repository_readiness_unconfirmed`), and `drive-epic` readiness and `doctor` both
-list them with their current state. `notify.local_sink` does not satisfy the webhook
-prerequisite.
-
-> **Rollout note.** The client-side default and the server-side admission,
-> stamping, and readiness changes must be released as **one compatible unit**. The
-> new default's shape (`v2_auto_merge_enabled: true` with no `required_checks`) is
-> exactly what the create route refused before BAPI-1102, so shipping the client
-> half alone would 422 every unattended run at `POST /jira/epic-runs/runs`.
-> Deploying only the server half is safe and inert: it narrows two refusals and adds
-> a first-approval stamp, and **rewrites no existing run**. No database migration and
-> no new environment variable is introduced — `config_projects.unattended_epic_implementer_allowed`
-> and `epic_supervisor_setup.done_gate_config` already exist and are read as-is.
-
-Once the plan is approved, the **server-side reconciler** picks the run up within ~30s. To execute claimed jobs on your machine, run `executor`:
+`repository_readiness_unconfirmed`). A missing channel is still refused as
+`webhook_unverified`. A declared webhook that fails verification never falls back
+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:
 
 ```
-npx -y @bridge_gpt/mcp-server executor --repo <name>
+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
 ```
 
-### Conductor (epic & multi-agent orchestration)
+`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.
 
-Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `epic-implementer install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**. (The event-ledger CLI was renamed from `conductor` to `epic-implementer`; the retained `conductor` bin name is now a fixed migration pointer.)
+### 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.
+
+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.
 
 > 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.
 
 <!-- BEGIN GENERATED: merge-workflow-install (managed by mcp_server/scripts/sync-readme-merge-workflow.js — DO NOT EDIT BY HAND) -->
-### `install-bridge conductor --merge-workflow`
+### `install conductor --merge-workflow`
 
 Generates the Epic Implementer **merge workflow** plus its CODEOWNERS fragment
 and repository-rule guidance, commits them on a managed branch, pushes with
 **your own git identity**, and opens a pull request with **your own `gh`**.
 
 ```
-npx -y @bridge_gpt/mcp-server install-bridge conductor --merge-workflow --codeowner <@org/team|@user>
+npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team|@user>
 ```
 
-`--codeowner` is **required** and takes exactly one `@user` or `@org/team`. It is
-never inferred from repository metadata, and a documentation placeholder is
-rejected. `--dry-run` prints the plan and performs **no** write: no branch, no
+`--codeowner` is **required** and takes exactly one `@user` or `@org/team`. Bridge
+cannot infer the code owner, so replace `<@org/team|@user>` with the one `@user` or
+`@org/team` who should review the workflow file before running; the placeholder
+itself is rejected. `--dry-run` prints the plan and performs **no** write: no branch, no
 file, no install-state write, no commit, no push, and no pull request.
 
 **Bridge performs no repository write, and the pull request is never merged for
@@ -1472,12 +1717,14 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `SFCC_HOSTNAME` | No | _(none)_ | SFCC sandbox hostname. Part of the environment credential tier — `SFCC_HOSTNAME`, `SFCC_CLIENT_ID`, and `SFCC_CLIENT_SECRET` must **all three** be set for that tier to apply, and a complete tier takes precedence over `dw.json` |
 | `SFCC_CLIENT_ID` | No | _(none)_ | Account Manager API client id. See `SFCC_HOSTNAME` — all three are needed together. Also required on its own when a tool is called with an explicit dotted `instance` |
 | `SFCC_CLIENT_SECRET` | No | _(none)_ | Account Manager API client secret. See `SFCC_HOSTNAME` — all three are needed together. Never sent to Bridge; it goes only to the Account Manager token endpoint |
-| `CLAUDE_CODE_OAUTH_TOKEN` | No | _(none)_ | The supported headless authentication input for conductor workers. Export it into the **executor process's own** environment; Bridge forwards it unchanged into the worker and stores it nowhere — no credential-store entry, no disk, never sent to Bridge. See [Claude login for conductor workers](#claude-login-for-conductor-workers) |
+| `CLAUDE_CODE_OAUTH_TOKEN` | No | _(none)_ | The supported headless authentication input for Epic Implementer workers. Export it into the **executor process's own** environment; Bridge forwards it unchanged into the worker and stores it nowhere — no credential-store entry, no disk, never sent to Bridge. See [Claude login for Epic Implementer workers](#claude-login-for-epic-implementer-workers) |
 | `BAPI_INSTALL_DEBUG` | No | _(unset)_ | Set to any non-empty value to unlock raw diagnostics in `install` and the `apply_install_manifest` path — the underlying error message and stack behind an `unexpected error` summary. The installer's own failure text tells you to set it |
 | `BAPI_SIGNUP_EMAIL` | No | _(none)_ | Selects the self-serve signup route without `--email`. Precedence: `--email` first, then this variable, then the visible interactive prompt |
 | `BAPI_INVITE` | No | _(none)_ | Invite code for `install`, for scripting. Like `--invite <code>`, it exposes the code to your shell history and the process list — prefer bare `--invite` and the hidden prompt |
-| `BAPI_PLANE_PYTHON` | No | `python` | Executable used for the Python members of `plane up`. Point it at a venv interpreter when `python` on `PATH` is not the one you want |
+| `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_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 |
@@ -1487,7 +1734,7 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `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 |
 | `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), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it 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,conductor`; 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)). Conductor/epic sessions launched via `start-tickets --conductor` **merge** `conductor` 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,conductor`. A normal `start-tickets` run stays on `core`. |
+| `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`. |
 
 Environment values are **trimmed**, and only a non-empty result wins. A
 whitespace-only `BAPI_API_KEY` therefore does not override anything: it falls
@@ -1657,9 +1904,9 @@ work. Two supported paths write it for you:
 
   Run it without `--write-credentials` to preview; add the flag to write the store.
 
-### Claude login for conductor workers
+### Claude login for Epic Implementer workers
 
-Conductor workers are **not** isolated into a private Claude configuration
+Epic Implementer workers are **not** isolated into a private Claude configuration
 directory — they run with the executor host's own `HOME`, so a worker
 authenticates the same way any interactive `claude` invocation on that host
 does. The prerequisite is simple: run
@@ -1742,7 +1989,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 conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+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).
 
 - **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)
@@ -1754,6 +2001,7 @@ The authoritative tool catalog covers **78 tools** (enumerated below). What's ac
 - **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)
 - **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"`)
 - **Pipelines & automation** — `get_pipeline_recipe` (returns a fully resolved recipe the agent executes step-by-step)
 - **Config** — `get_project_standards`, `config_field` (operations: `get`, `update`, `list`), `model_thresholds` (actions: `get`, `set`, `clear`; the only way to set personal thresholds)
 
@@ -1765,9 +2013,8 @@ Pipelines are declarative, multi-step workflows your AI agent executes step-by-s
 |---|---|---|
 | `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |
 | `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. Internal atomic pipeline invoked by `/review-tickets` (inline for one key, spawned per tab for several) and by `/review-and-implement`, `/review-and-start`, and `/start-tickets`. | `/review-tickets PROJ-123` |
-| `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |
+| `idea-to-ticket` | Deprecated, superseded by `/define-tickets`; still resolvable through `get_pipeline_recipe` for one release, with no new consumers | `/define-tickets "<idea>"` |
 | `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |
-| `full-automation` | Client-side wrapper: runs the `idea-to-ticket` recipe, then hands the created keys to `/review-and-start --auto` | `/idea-to-pr "<idea>"` |
 | `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |
 
 ### Pipeline response envelope
@@ -1778,3 +2025,94 @@ plus `total_steps`, `auto_approve`, and `execution_mode`. Each step is either an
 text). `execution_mode` is `inline` — the calling agent executes every step
 itself and keeps its own durable record through `record_phase_result` /
 `record_checkpoint`. There is no server-side orchestrator and no run to resume.
+
+
+## Start Tickets troubleshooting
+
+`start-tickets` reports actual worktree paths and branches in its stable summary,
+then explains successfully spawned sessions. Work from each reported folder: its
+branch is already checked out there and normally cannot also be checked out in
+the original folder. Folder names and locations come from Worktrunk configuration;
+do not infer them from the original checkout.
+
+Monitor the selected agent in the reported Terminal/iTerm tab, Windows Terminal
+tab, PowerShell fallback window, or detached tmux session. Linux output prints
+the exact `tmux attach -t ...` commands. When a destination is not reported, treat
+it as unknown. A spawned session has started; it has not completed implementation
+or review. Review workflows review independently before opening a fresh
+implementation session. Coordinate ownership across multiple independent
+sessions and pause affected work when overlapping changes cause conflicts.
+
+For mixed failures, only `spawned` rows describe running sessions. Retain failed
+row warnings and the CLI exit status. Dry-run and all-failed results open no
+successful sessions. After a failure, read-only diagnostics are allowed:
+
+```bash
+npx -y @bridge_gpt/mcp-server doctor --agent codex
+```
+
+The interactive installer separates **Required for launcher** tools from
+**Recommended diagnostics** (`uv`, selected agent, ast-grep, ripgrep, lizard).
+Missing recommendations and the **Git compatibility advisory** add no install or
+launcher admission gate. Doctor performs no automatic repair, installation, PATH
+mutation, authentication, or terminal launch. The existing launcher still checks
+Git presence and repository work-tree context at launch.
+
+### Worktrunk and Git compatibility evidence
+
+The documented comparison baseline is **Worktrunk v0.80.0**, whose
+[tagged Git-version source](https://github.com/max-sixty/worktrunk/blob/v0.80.0/src/git/version.rs)
+sets the minimum to **Git 2.43.0**. This is the release-specific baseline Bridge
+recommends for this advisory, not a universal rule for every Worktrunk release or
+a requirement to install the latest Git. The onboarding report observed Git
+**2.39.5** being rejected with a **2.43.0** minimum; it did not identify the
+Worktrunk release, so that observation alone is not release verification.
+
+Doctor and the installer report the resolved Git executable and numeric version
+when available, with compatible, incompatible, and unknown advisory states.
+An arbitrary nonempty `BAPI_WORKTRUNK_BIN` override has an unconfirmed release
+requirement and is not assumed compatible with this baseline. On macOS,
+installing another Git does not ensure the launcher resolves it. Verify the
+executable and version selected on PATH before changing your installation:
+
+```bash
+which git
+git --version
+```
+
+### Saved planning work and launch readiness
+
+Successful ticket/plan creation does not establish executor, policy, VCS, or
+indexing readiness. A finalized epic completion may show one bounded read-only
+`drive-epic '<EPIC>' --dry-run --json` preview. Ready means **ready at preview
+time**; a conditional cold start still needs guarded startup/live validation.
+Returned target, refusal reasons, remedies, and `availability_text` remain
+authoritative. An unavailable preview leaves readiness unconfirmed while saved
+work remains successful. Free-form plans or unresolved child keys must be
+finalized first. Actual launch retains its consent and admission checks.
+
+## Backend-owned bootstrap identity (BAPI-1438)
+
+Ordinary new creation uses a friendly display label. Labels may repeat and never
+select credentials. For a scripted operator invite use `install --invite --display-name "My project"`
+and supply the invitation through the existing private input mechanism. In an
+interactive terminal the folder basename is a suggested label. Self-serve signup
+still requires emailed-code verification in an interactive terminal.
+
+Use `--repo <canonical-name>` or `BAPI_REPO_NAME` for existing-key registration
+or explicit legacy creation. Existing keys cannot use `--display-name`; creation
+cannot combine that flag with a canonical selector.
+
+Rerun from the original folder with the same invitation or signup method after
+an interrupted install. The original proof and label are reused; another entered
+label does not rename the recovered project. Preserve recovery storage when an
+outcome is unknown, a challenge cannot be recovered, or installation asks for support.
+Never delete possibly redeemed proof to restart. Ordinary invite tokens and
+verification codes are not stored.
+
+Credential storage uses bounded exclusive locking without timeout-based stealing.
+An abandoned lock needs installation support. 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.