@bridge_gpt/mcp-server 0.2.68 → 0.2.69

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.69", "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.69", "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.69", "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.69", "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.69", "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).
@@ -1286,7 +1337,14 @@ The path from an epic to a finished run:
 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.
+   creates the run and starts its executor. In Claude Code, `/drive-epic-run` 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.
 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
@@ -1732,7 +1790,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`. |