@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/README.md

@@ -13,21 +13,27 @@ 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.
 
-> **npm shows a different command in its sidebar. Ignore it.** The
-> `npm i @bridge_gpt/mcp-server` box on this page is generated by npm from the
-> package name; it is not the setup command, and no packaging option lets the
-> publisher change or remove it. Installing the package that way does not connect
-> anything. Use the command above.
+> 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 changes in your project**
+**What it will do**
 
-- Adds slash commands and agent definitions for your editor (`.claude/commands/`,
-  `.cursor/commands/`, and the equivalents your editor uses).
-- Registers a `bridge-api` MCP server in your editor's MCP config, leaving any
+- **Bootstraps the Bridge MCP for you** — one command and 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 `.bridge/` for your project manifest and pipeline definitions.
-- Writes nothing outside your project root except your Bridge credential, which is
-  stored for you so you never have to paste it again.
+- Creates and updates the files it needs inside your project root: slash commands
+  and agent definitions for your editor (`.claude/commands/`, `.cursor/commands/`,
+  and the equivalents your editor uses), your editor's MCP config, and `.bridge/`
+  for your project manifest and pipeline definitions.
+- Stores your Bridge credential outside the project, so the MCP server and the
+  tooling that spawns its own shells can find it without you configuring anything.
+  Re-running `install` still asks for the credential unless you supply it through
+  `--api-key` or `BAPI_API_KEY` — the installer writes that store, it does not read
+  it back.
+- Writes outside your project root only when you pick a host whose configuration is
+  global: OpenAI Codex (`~/.codex/config.toml`) and GitHub Copilot CLI
+  (`~/.copilot/mcp-config.json`).
 
 **Prerequisites**
 
@@ -35,18 +41,18 @@ account — it will ask.
 - **A project directory** — run the command from the folder your editor opens: your
   repository root, the one containing `.git`. No `package.json` is required — SFCC
   cartridge repos, Python, Go, Rust, and other non-Node projects work the same way.
-- **An MCP-capable editor**: Claude Code, GitHub Copilot, Cursor, Windsurf, or
-  OpenAI Codex.
+- **An MCP-capable editor or CLI**: Claude Code, GitHub Copilot in VS Code, GitHub
+  Copilot CLI, Cursor, Windsurf, or OpenAI Codex.
 - **No Bridge account needed.** The installer can create one for you from just an
   email address.
 
 ## Contents
 
 - [Install](#install)
-- [Installing, step by step](#installing-step-by-step)
-- [What to expect](#what-to-expect)
-- [Troubleshooting](#troubleshooting)
-- [Quick start details](#quick-start-details)
+- [Installation details](#installation-details)
+  - [Installing, step by step](#installing-step-by-step)
+  - [What to expect](#what-to-expect)
+  - [Troubleshooting](#troubleshooting)
 - [Usage Documentation](#usage-documentation)
   - [Regularly useful](#regularly-useful)
   - [Occasionally useful](#occasionally-useful)
@@ -63,7 +69,9 @@ account — it will ask.
 
 For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./docs/CONDUCTOR.md).
 
-## Installing, step by step
+## Installation details
+
+### Installing, step by step
 
 **1. Open a terminal in your project root.** This matters: the installer writes
 your slash commands and MCP config relative to the directory you run it from. If
@@ -91,7 +99,7 @@ a token:
 
 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
-[Choosing how you sign in](#quick-start-details).
+[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
@@ -102,10 +110,19 @@ freshly written config is not live until you reload. Restart the editor, or use
 "reload MCP servers" action. In Claude Code you will also be asked to trust the
 project's `.mcp.json` the first time.
 
-**6. Finish in the agent session the installer opens.** The last thing the
-installer does is 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.
+**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.
+
+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
+terminal, and you have to accept the consent prompt (*"Bridge can configure and set
+up this project for you automatically. Open a `<tool>` session to do that now?
+(Y/n)"*). Claude Code is the only selection that launches on its own. A
+Cursor-only, Copilot, Copilot CLI, Codex, or Windsurf selection, a non-interactive
+run, or a declined prompt all print the command to continue by hand instead. Pass
+`--agent claude` or `--agent cursor-agent` to override the decision outright.
 
 **7. Follow the next step the session shows you, if it shows one.** The installer
 asks the server what should happen next and shows that command only when there is
@@ -119,7 +136,8 @@ there is nothing for you to run.
 
 Want to see what would happen without changing anything? Add `--dry-run`.
 
-## What to expect
+<details>
+<summary id="what-to-expect"><strong>What to expect</strong></summary>
 
 **Files that appear in your project**
 
@@ -134,16 +152,35 @@ Want to see what would happen without changing anything? Add `--dry-run`.
 The installer tells you which of these are safe to commit and never recommends
 committing anything that can hold a credential.
 
-**Prompts you will see.** A sign-in question on a first bare run, a hidden prompt
-for a token (or a visible one for an email), a project name for a brand-new
-project, and a picker for which editors to configure. Nothing else prompts.
-
-**A fresh agent session opens at the end.** This is expected — it is how the
-installer finishes configuring the project. Use `--agent cursor-agent` if you want
+**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]:`).
+- *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.
+- *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
+  expired self-serve signup would be discarded.
+
+**A fresh agent session opens at the end — if your selection can launch one.** See
+step 6 above for the three conditions. Use `--agent cursor-agent` if you want
 Cursor's agent instead of Claude Code.
 
-**Your key is remembered.** You paste a credential at most once. Later runs, and
-the tooling that spawns its own shells, find it on their own.
+**Selecting Windsurf prints instructions instead of writing config.** Windsurf's
+global `mcp_config.json` is never modified automatically; the installer reports the
+entry for you to paste yourself. Codex and Copilot CLI *are* written automatically,
+even though their files are global too.
+
+**Your key is stored for the tools that read the store.** The MCP server and the
+shell-spawned tooling (`start-tickets` and its model routing) resolve it from
+`~/.config/bridge/credentials.json` on their own. The **installer** does not: a
+repeat `install` prompts for the credential again unless you pass `--api-key` or
+set `BAPI_API_KEY` in the environment.
 
 **A next step, when the project needs one.** The session closes with whatever
 command the server says comes next, and stays quiet when there is nothing to
@@ -156,18 +193,24 @@ than from your project's documented conventions.
 your project has the settings it needs, indexing starts server-side. You never have
 to ask for it.
 
-## Troubleshooting
+</details>
+
+<details>
+<summary id="troubleshooting"><strong>Troubleshooting</strong></summary>
 
 **"My editor doesn't see any Bridge tools."** Two usual causes. First, the config
 was written somewhere your editor is not looking — re-run the installer from the
-directory your editor actually opens, and check that a `bridge-api` entry exists in
+directory your editor actually opens, and check that a `bridge` entry exists in
 that project's MCP config. Second, the editor has not been reloaded since the file
 was written; restart it. In Claude Code, also confirm you accepted the trust prompt
 for the project's `.mcp.json`.
 
-**"I ran it in the wrong folder."** Nothing is broken. Delete the `.bridge/`,
-`.claude/`, and `.mcp.json` entries that were created there and re-run the command
-from the right directory.
+**"I ran it in the wrong folder."** Nothing is broken. Depending on which editors
+were detected, a run can leave `.bridge/`, `.bridge/install-state.json`, `.claude/`,
+`.cursor/commands/`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.github/agents/`,
+`.mcp.json`, and appended `.gitignore` lines. Remove only what that run created and
+re-run the command from the right directory — if you already had a `.vscode/`,
+`.cursor/`, or `.gitignore` there, keep the parts you had before.
 
 **"It seems to hang with no output."** If you ran the bare command
 (`npx -y @bridge_gpt/mcp-server`) with no subcommand, you started the MCP *server*,
@@ -178,7 +221,11 @@ looks like a hang. It prints a line saying so. Press Ctrl-C and run
 `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
-connectivity before it saves anything, so a failure here has changed nothing. A
+connectivity before it saves your **credential** anywhere, so a failure here has not
+written your key into a config or stored it for later. It has already
+scaffolded the project files by then — slash commands, agents, pipelines,
+`.bridge/config`, and secret-free per-host MCP placeholders — so expect those to
+exist; re-running is safe and refreshes them. A
 rejected key means the credential is not valid for that project — check the project
 name you gave, and generate a fresh key on the Bridge web UI's **Security** page if
 needed. A network failure usually means a proxy or VPN is in the way.
@@ -196,10 +243,10 @@ npx -y @bridge_gpt/mcp-server doctor
 `doctor` is strictly read-only. It reports what it found — configs, registrations,
 credential availability, prerequisites — and changes nothing.
 
-## Quick start details
+</details>
 
 <details>
-<summary><strong>Choosing how you sign in</strong></summary>
+<summary id="choosing-how-you-sign-in"><strong>Choosing how you sign in</strong></summary>
 
 Three routes lead to the same place. The interactive question above picks one for
 you; these flags pick it up front and skip the question entirely.
@@ -253,8 +300,8 @@ created or spent.
 | `--invite [code]` | Redeem an invite code. Omit the value for the hidden prompt (recommended) |
 | `--api-key <key>` | Use an existing Bridge API key |
 | `--repo <name>` | Name the registered repository instead of resolving or asking for it |
-| `--tools <list>` | Configure specific MCP hosts without the picker (e.g. `claude-code,cursor`) |
-| `--agent claude\|cursor-agent` | Which agent to open for the final configuration step (default `claude`) |
+| `--tools <list>` | Configure specific MCP hosts without the picker. Accepted IDs are exactly `claude-code`, `cursor`, `copilot-vscode`, `copilot-cli`, `codex`, and `windsurf` (e.g. `claude-code,cursor`); any other value is a parse error |
+| `--agent claude\|cursor-agent` | Which agent to open for the final configuration step. **No default** — without this flag the agent is derived from the hosts you selected, and an explicit value always wins, including for a host you did not select |
 | `--dry-run` | Preview every step without writing, contacting Bridge, resolving or prompting for a credential, or opening anything. Genuinely inert: it returns before the project-root prompt, before the repository is resolved, and before any tool-selection prompt, so a value it cannot know locally (an unresolved repository name, an unselected tool) is shown as **not yet known** rather than guessed |
 | `--force` | Overwrite an existing stored key without asking |
 | `-h`, `--help` | Full usage |
@@ -270,17 +317,31 @@ different way to arrive, and the installer will not guess between them.
 The installer configures your editors for you. Do this only if you would rather
 write the config yourself, or if you use a host it cannot write automatically.
 
-Scaffold the project files without configuring anything. Run it from the same
-project root `install` uses — your repository root, the one containing `.git`.
-No `package.json` is required:
+Scaffold the project files and write a secret-free MCP registration. Run it from
+the same project root `install` uses — your repository root, the one containing
+`.git`. No `package.json` is required:
 
 ```bash
 npx -y @bridge_gpt/mcp-server --init
 ```
 
-Then add a `bridge-api` entry to your host's MCP config, filling in your repository
-name and API key. Add `"serve"` as the last launcher argument, as shown — it is the
-explicit way to say "start the MCP server."
+`--init` always creates `.mcp.json`, and adds `.vscode/mcp.json` or
+`.cursor/mcp.json` when it detects those editors. Each generated entry carries
+`BAPI_BASE_URL`, `BAPI_REPO_NAME`, `BAPI_DOCS_DIR`, and `BAPI_PROJECT_ROOT`, and
+**never** `BAPI_API_KEY` — the server resolves the credential itself at runtime.
+
+So the manual work left after `--init` is narrower than writing an entry from
+scratch: correct `BAPI_REPO_NAME` if it was written as the `YOUR_REPO_NAME`
+placeholder, and supply your credential through a supported source (`BAPI_API_KEY`
+in the entry's `env` block, `BAPI_API_KEY` in the server's environment, or the
+`~/.config/bridge/credentials.json` store).
+
+Write the entry yourself instead — for a host `--init` does not touch, or because
+you would rather — using the shapes below. Add `"serve"` as the last launcher
+argument, as shown: it is the explicit way to say "start the MCP server." Pin the
+package to an exact version and pass `--prefer-offline`, which is what the
+generated entries do and what keeps npx from resolving a different build on some
+later boot.
 
 <details>
 <summary><strong>Claude Code (.mcp.json)</strong></summary>
@@ -288,9 +349,9 @@ explicit way to say "start the MCP server."
 ```json
 {
   "mcpServers": {
-    "bridge-api": {
+    "bridge": {
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.42", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -309,9 +370,10 @@ explicit way to say "start the MCP server."
 ```json
 {
   "servers": {
-    "bridge-api": {
+    "bridge": {
+      "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.42", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -330,9 +392,10 @@ explicit way to say "start the MCP server."
 ```json
 {
   "mcpServers": {
-    "bridge-api": {
+    "bridge": {
+      "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.42", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -343,8 +406,32 @@ explicit way to say "start the MCP server."
   }
 }
 ```
+</details>
 
-> If project-local config is not supported in your Cursor version, use `~/.cursor/config/mcp.json` instead.
+<details>
+<summary><strong>GitHub Copilot CLI (~/.copilot/mcp-config.json)</strong></summary>
+
+Copilot CLI reads a single global file. The installer writes this one for you when
+you select `copilot-cli`; the shape below is what it produces.
+
+```json
+{
+  "mcpServers": {
+    "bridge": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.42", "serve"],
+      "tools": ["*"],
+      "env": {
+        "BAPI_BASE_URL": "https://bridgegpt-api.com",
+        "BAPI_REPO_NAME": "your-repo",
+        "BAPI_API_KEY": "your-api-key",
+        "BAPI_DOCS_DIR": "docs/tmp"
+      }
+    }
+  }
+}
+```
 </details>
 
 <details>
@@ -355,9 +442,9 @@ Windsurf only supports global MCP configuration.
 ```json
 {
   "mcpServers": {
-    "bridge-api": {
+    "bridge": {
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.42", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -374,11 +461,11 @@ Windsurf only supports global MCP configuration.
 <summary><strong>OpenAI Codex (~/.codex/config.toml)</strong></summary>
 
 ```toml
-[mcp_servers.bridge-api]
+[mcp_servers.bridge]
 command = "npx"
-args = ["-y", "@bridge_gpt/mcp-server", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.42", "serve"]
 
-[mcp_servers.bridge-api.env]
+[mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
 BAPI_REPO_NAME = "your-repo"
 BAPI_API_KEY = "your-api-key"
@@ -426,9 +513,19 @@ Launcher pins:
 When every applicable launcher pin was already at the target, it prints
 `Already up-to-date.` — that status comes from comparing your configs, not from
 the version of the CLI process. A non-zero exit means the upgrade did **not**
-converge (an unreadable config, a launcher carrying a version range the upgrader
-must not rewrite, a competing local install it could not remove, or a pin that
-failed post-write verification); nothing is reported as complete in that case.
+converge, and nothing is reported as complete in that case. The causes:
+
+- the npm registry lookup failed **and** this process was not started from
+  `@latest`, so the target version could not be confirmed — the likeliest one
+  offline, and why the canonical command uses `@latest`;
+- a launcher pin is already **newer** than the target, which an automated repin
+  must never downgrade;
+- an unreadable or unparseable config, a launcher carrying a version range or a
+  dist-tag rather than an exact release, or two Bridge registrations in one file;
+- a competing local install it could not remove, or a pin that failed post-write
+  verification;
+- the upgrade finished but left an **unconfigured** MCP entry — one that would
+  authenticate as nobody.
 
 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
@@ -447,16 +544,20 @@ scaffolded files without overwriting your stored credential unless you pass
 
 This is the Bridge API tooling worth knowing about as a software engineer — the things you'd ask an agent to do — grouped by how often you would use them. Each entry covers **what it does**, **when it's useful**, **how to use it**, and its **flags**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).
 
-Working in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).
+Working in a Salesforce B2C Commerce codebase? Bridge also ships SFCC platform tools — read-only introspection under the `sfcc` profile, and nine destructive writes under the separate `sfcc-write` opt-in. See [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).
 
 For invocation, prefer the slash command — it's deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.
 
-<!-- The three tier sections below are GENERATED from api/library/config/mcp_tool_catalog.json,
-     the authoritative tool catalog, by scripts/sync_mcp_server_readme.py. Edit the curated
-     metadata in scripts/sync_mcp_tool_catalog.py — never the JSON artifact and never the
-     text between the markers. Generation order is: sync_mcp_tool_catalog.py, then
+<!-- The three tier sections below are GENERATED from TWO catalogs by
+     scripts/sync_mcp_server_readme.py: api/library/config/mcp_tool_catalog.json,
+     the authoritative MCP tool catalog, and api/library/config/workflow_catalog_lib.py,
+     the immutable catalog of slash-command workflows (which have no MCP registration
+     and therefore cannot live in the JSON artifact). Edit the curated tool metadata in
+     scripts/sync_mcp_tool_catalog.py and the workflow definitions in
+     workflow_catalog_lib.py — never the JSON artifact and never the text between the
+     markers. Generation order is: sync_mcp_tool_catalog.py, then
      sync_mcp_server_readme.py, then `cd mcp_server && npm run build` (which bundles this
-     file into readme.generated.ts, served as the MCP resource bridge-api://readme).
+     file into readme.generated.ts, served as the MCP resource bridge://readme).
      Everything outside the marker pair — including the sections below it — is hand-written. -->
 
 <!-- BEGIN GENERATED: mcp-tool-documentation (managed by scripts/sync_mcp_server_readme.py — DO NOT EDIT BY HAND) -->
@@ -470,125 +571,95 @@ The tools worth knowing for most tickets.
 - **How to use it:** `/review-ticket BAPI-123` (command only — "review" as free text is easily mistaken for a freehand agent review). For several tickets at once, `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket and reviews them in parallel with no worktrees; every `/review-ticket` flag applies, and `--review KEY=auto,rounds=N` sets per-ticket overrides.
 - **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. Council**
-- **What it does:** Fans your problem out to two different models and returns their approaches, in technical, design, discovery, or general mode.
-- **When it's useful:** (Architecture | Refinement) Early, when you want a spread of approaches — technical for how to build it, design for how it should look, discovery for what still needs figuring out before a real ticket exists, general for a quick brief-driven pass before the repository is indexed.
-- **How to use it:** Ask your agent to convene a council — "Convene a council on approaches for adding rate limiting to the LLM client." For a design pass: "Run a design council for the evidence-freshness dashboard UI." For early discovery: "Run a discovery council — `request_council` with `mode: "discovery"` — so we can collect the questions stakeholders need to answer first."
-- **Flags:** `mode` selects one of four modes: `technical` (the default — implementation/architecture approaches), `design` (UI/UX and visual direction), `discovery` (stakeholder discovery questions, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`), and `general` (brief-driven ideation from your task description alone). `technical` and `discovery` are codebase-grounded and need an indexed repository; `general` needs no code index at all, so it works immediately after install. The legacy boolean `design=true` still works and maps to `mode: "design"`.
+**2. Start Tickets**
+- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
+- **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).
+- **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` coarse model-routing override.
+
+**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.
+- **When it's useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/full-automation`, which only accepts an idea).
+- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).
+- **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`.
 
-**3. Get Council**
-- **What it does:** Retrieves a council that was already generated for a ticket.
-- **When it's useful:** (Architecture | Refinement) When a council was already run and you want to reread it without paying to regenerate it.
-- **How to use it:** Ask your agent to pull up the council already generated for the ticket.
+**4. Explore Ticket**
+- **What it does:** Maps the code paths, dependencies, and project conventions a task would touch, settles its acceptance criteria with you on a decision page, then compares the viable implementation approaches and their trade-offs and writes up a proposed design. 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:** `/explore-ticket <task>` — *"Explore the codebase for how we'd add a Mistral LLM provider and recommend 2–3 implementation options."*
 - **Flags:** None.
 
-**4. Deep Research**
+**5. Council**
+- **What it does:** Fans your problem out to two different models and returns their approaches, in technical, design, discovery, or general mode.
+- **When it's useful:** (Architecture | Refinement) Early, when you want a spread of approaches — technical for how to build it, design for how it should look, discovery for what still needs figuring out before a real ticket exists, general for a quick brief-driven pass before the repository is indexed.
+- **How to use it:** `/council <question>`
+- **Flags:** `--mode` selects one of four modes, passed to the underlying `request_council` tool as e.g. `mode: "discovery"`: `technical` (the default — implementation/architecture approaches), `design` (UI/UX and visual direction), `discovery` (stakeholder discovery questions, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`), and `general` (brief-driven ideation from your task description alone). `technical` and `discovery` are codebase-grounded and need an indexed repository; `general` needs no code index at all, so it works immediately after install. The legacy boolean `design=true` still works and maps to `mode: "design"`.
+
+**6. Deep Research**
 - **What it does:** Runs multi-source, fact-checked web research on a technical topic and returns a cited report.
 - **When it's useful:** (Architecture | Refinement) When a decision hinges on outside knowledge — libraries, best practices, standards — that you do not already have.
 - **How to use it:** `/bridge-research <question>`
 - **Flags:** None.
 
-**5. Get Deep Research**
-- **What it does:** Retrieves a research report that was already generated.
-- **When it's useful:** (Architecture | Refinement) When the report already exists and you want to reread it without re-running the research.
-- **How to use it:** Ask your agent to retrieve the research report already generated.
-- **Flags:** None.
+### Occasionally useful
+
+Good to know, but not needed every day.
 
-**6. Upload Ticket**
+**1. Upload Ticket**
 - **What it does:** Creates a real Jira issue from a drafted ticket, including child tickets under an epic; your agent should confirm with you before creating it.
 - **When it's useful:** (Refinement) The final step after drafting — to get the ticket into your tracker so it can be tracked and worked.
 - **How to use it:** Ask your agent to create the ticket; it should confirm with you before creating the live issue.
 - **Flags:** Name the issue type (Bug / Story / Task / Epic) and, for a child ticket under an epic, the parent key.
 
-### Occasionally useful
-
-Good to know, but not needed every day.
-
-**1. Plan Ticket**
+**2. Plan Ticket**
 - **What it does:** Generates a step-by-step implementation plan for a ticket that references real files in your codebase.
 - **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.
 
-**2. Get Plan**
-- **What it does:** Retrieves an implementation plan that was already generated for a ticket.
-- **When it's useful:** (Implementation) When the plan already exists and you want to read it without regenerating it.
-- **How to use it:** Ask your agent to fetch the implementation plan already generated for the ticket.
-- **Flags:** None.
-
 **3. Clarify Ticket**
 - **What it does:** Generates clarifying questions for a ticket, or debugging guidance when the ticket is a bug.
 - **When it's useful:** (Refinement) When a ticket feels under-specified and you want the open questions made explicit.
 - **How to use it:** `/clarify-ticket BAPI-123`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**4. Get Clarifying Questions**
-- **What it does:** Retrieves clarifying questions that were already generated for a ticket.
-- **When it's useful:** (Refinement) When the questions were already generated and you want to reread them rather than pay to regenerate them.
-- **How to use it:** Ask your agent for the clarifying questions already generated for the ticket.
-- **Flags:** None.
-
-**5. Critique Ticket**
+**4. Critique Ticket**
 - **What it does:** Critiques a ticket against your project's standards and lists the deviations and improvements it found.
 - **When it's useful:** (Refinement) When you want a quality gate on a ticket before anyone works it.
 - **How to use it:** `/critique-ticket BAPI-123`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**6. Get Ticket Critique**
-- **What it does:** Retrieves a ticket critique that was already generated.
-- **When it's useful:** (Refinement) When the critique already exists and you want to reread its findings without regenerating it.
-- **How to use it:** Ask your agent for the critique already generated for the ticket.
-- **Flags:** None.
-
-**7. Create Doc**
+**5. Create Doc**
 - **What it does:** Generates a design document for a ticket — a technical design document, a functional spec, or a product requirements document.
 - **When it's useful:** (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.
 - **How to use it:** `/create-doc BAPI-123 --doc-type tdd` (or `fsd` / `prd`)
 - **Flags:** `--doc-type tdd|fsd|prd` which document to generate (required) · `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**8. Get Doc**
-- **What it does:** Retrieves a design document that was already generated for a ticket.
-- **When it's useful:** (Architecture | Refinement) When the document already exists and you want to reread it without regenerating it.
-- **How to use it:** Ask your agent for the ticket's design document, naming which type you want.
-- **Flags:** None.
-
-**9. Second Opinion**
+**6. Second Opinion**
 - **What it does:** Gets an immediate critique of any text from a different model family, without saving an artifact.
 - **When it's useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.
 - **How to use it:** Ask your agent — "Get a second opinion from Gemini on whether the BAPI-123 plan's migration step is safe to run against production."
 - **Flags:** Pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).
 
-**10. Generate Image**
+**7. Generate Image**
 - **What it does:** Generates an image from a text prompt using a provider image model, spending provider credits on every call.
 - **When it's useful:** (Architecture | Refinement) When you want a quick visual — a UI mockup, diagram, or illustration — to anchor a design discussion or attach to a ticket.
 - **How to use it:** Ask your agent — "Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."
 - **Flags:** `provider` openai (`gpt-image-2`) / gemini (Imagen, which adds an invisible SynthID watermark) · `quality` low (default, cheapest) / medium / high · `size` 1024x1024 / 1024x1536 / 1536x1024. The image is saved to `BAPI_DOCS_DIR/images/` and also returned inline.
 
-**11. Request PRD**
+**8. Request PRD**
 - **What it does:** Generates a product requirements document for a ticket covering the problem, the goals, and the success metrics.
 - **When it's useful:** (Architecture | Refinement) When a piece of work needs its problem, goals, and success metrics written down before anyone designs a solution.
 - **How to use it:** `/create-doc BAPI-123 --doc-type prd`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**12. Get PRD**
-- **What it does:** Retrieves a product requirements document that was already generated for a ticket.
-- **When it's useful:** (Architecture | Refinement) When the requirements document already exists and you want to reread it without regenerating it.
-- **How to use it:** Ask your agent to retrieve the ticket's product requirements document.
-- **Flags:** None.
-
-**13. Full Automation**
+**9. Full Automation**
 - **What it does:** Drives the whole chain from a raw idea through tickets and reviews to implementation sessions.
 - **When it's useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.
 - **How to use it:** `/full-automation <idea>` (command only — it creates tickets, spawns worktrees, and carries scheduling flags free text cannot).
 - **Flags:** `--require-approval` re-enable the approval gates; the chain runs end to end by default · `--max-children <n>` cap how many child tickets an epic decomposes into.
 
-**14. Resume Full Automation**
-- **What it does:** Resumes a full-automation chain that was started earlier.
-- **When it's useful:** (Automation) When an earlier chain stopped at an approval gate or was interrupted, and you want it continued rather than restarted.
-- **How to use it:** Ask your agent to resume the full-automation chain, naming the run to continue.
-- **Flags:** None.
-
-**15. Update Ticket Description**
+**10. Update Ticket Description**
 - **What it does:** Rewrites a ticket's description with AI, using the ticket's own content and its reference material. A rewrite that changes more than 60% of the description is held for review instead of applied.
 - **When it's useful:** (Refinement) When a ticket has accumulated comments, attachments, or links and its description no longer reflects them.
 - **How to use it:** Ask your agent — "Update the description for BAPI-123."
@@ -604,55 +675,49 @@ Useful once in a while.
 - **How to use it:** `/reimplement-ticket BAPI-123`
 - **Flags:** None.
 
-**2. Get Reimplement Context**
-- **What it does:** Retrieves the follow-up context that was already gathered for a ticket.
-- **When it's useful:** (Implementation) When the follow-up context was already gathered and you want to read it without gathering it again.
-- **How to use it:** Ask your agent for the follow-up context already gathered for the ticket.
-- **Flags:** None.
-
-**3. Update Ticket**
+**2. Update Ticket**
 - **What it does:** Rewrites a ticket's description, fully replacing what is there today.
 - **When it's useful:** (Refinement) After review, to fold the resolved questions and fixes back into the ticket itself.
 - **How to use it:** `/update-ticket BAPI-123` (command only — it fully overwrites the live description, which is hard to reverse).
 - **Flags:** None.
 
-**4. Get Ticket**
+**3. Get Ticket**
 - **What it does:** Retrieves the full details of a ticket, including its summary, status, and description.
 - **When it's useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.
 - **How to use it:** Ask your agent — "Pull up BAPI-123 and show me its description, status, and acceptance criteria."
 - **Flags:** None.
 
-**5. Search Tickets**
+**4. Search Tickets**
 - **What it does:** Searches across the tickets in your project.
 - **When it's useful:** (Refinement) When you need to find tickets by project, status, or wording rather than by key.
 - **How to use it:** Ask your agent — "Search our project for open tickets mentioning rate limiting."
 - **Flags:** Narrow the search by project, status, issue type, or free text.
 
-**6. Write Comment**
+**5. Write Comment**
 - **What it does:** Posts a comment on a ticket.
 - **When it's useful:** (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.
 - **How to use it:** Ask your agent — "Post a comment on BAPI-123: blocked on the expired Atlassian token — will retry after it is rotated."
 - **Flags:** A long comment can be attached as a file instead of inlined.
 
-**7. Read Comments**
+**6. Read Comments**
 - **What it does:** Reads the comment thread on a ticket.
 - **When it's useful:** (Refinement | Implementation) When the discussion on a ticket matters and you want the agent to read it before acting.
 - **How to use it:** Ask your agent — "Read the comments on BAPI-123 and summarize what was decided."
 - **Flags:** None.
 
-**8. Ticket Attachments**
+**7. Ticket Attachments**
 - **What it does:** Downloads files from a ticket to your disk, or attaches a local file to a ticket.
 - **When it's useful:** (Refinement | Implementation) When a ticket has design files or logs you need locally, or you want to attach output back to it.
 - **How to use it:** Ask your agent — "Download the design mockups attached to BAPI-123 into my docs folder," or "Attach build-log.txt to BAPI-123."
 - **Flags:** Choose the direction (download from the ticket, or upload to it) and, for a download, where the files should land.
 
-**9. Estimate Ticket**
+**8. Estimate Ticket**
 - **What it does:** Estimates the development effort for one ticket. Use Estimate Epic instead for a whole epic or a named group of tickets.
 - **When it's useful:** (Refinement) When you need a size for a single ticket before committing to it.
 - **How to use it:** Ask your agent — "Estimate BAPI-123."
 - **Flags:** Ask for a fresh estimate to regenerate rather than reuse a stored one.
 
-**10. Estimate Epic**
+**9. Estimate Epic**
 - **What it does:** Estimates an epic, or an explicit group of tickets you name.
 - **When it's useful:** (Architecture | Refinement) When you need a sizing pass across an epic, or across a set of tickets you name explicitly.
 - **How to use it:** `/estimate-epic BAPI-123`
@@ -661,63 +726,72 @@ Useful once in a while.
 
 ### Workflow commands
 
-Slash commands that drive several tools at once. They are agent workflows rather than single MCP tools, so they are documented here by hand.
-
-**1. Start Tickets**
-- **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
-- **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).
-- **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` coarse model-routing override.
+Slash commands that drive several tools at once. Start Tickets, Review and Start, and Explore Ticket are documented above under [Regularly useful](#regularly-useful) — the rest live here.
 
-**2. Implement Ticket**
+**1. Implement Ticket**
 - **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor 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).
 
-**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.
-- **When it's useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/full-automation`, which only accepts an idea).
-- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).
-- **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. Jira Ticket Writer**
+**2. Jira Ticket Writer**
 - **What it does:** An agent that drafts a well-structured Jira ticket from a plain description, applying your project's standards.
 - **When it's useful:** (Refinement) When you have an idea in your head and want a properly-formatted ticket draft without writing it by hand.
-- **How to use it:** `/write-ticket <description>` — or ask your agent, *"Use the jira ticket writer to turn our conversation into a ticket."*
-- **Flags:** `--standards <path>` apply a specific standards file when drafting.
+- **How to use it:** Ask your agent, *"Use the jira ticket writer to turn our conversation into a ticket."* The other ticket commands draft through it automatically.
+- **Flags:** None — name a specific standards file in your request to have it applied when drafting.
 
-**5. Idea to Ticket**
+**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.
 - **How to use it:** `/idea-to-ticket <idea>`
 - **Flags:** None.
 
-**6. Explore Ticket**
-- **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.
-- **When it's useful:** (Architecture | Refinement) Before writing a ticket or plan, when you're unsure how a change would fit the existing code.
-- **How to use it:** `/explore-ticket <task>` — *"Explore the codebase for how we'd add a Mistral LLM provider and recommend 2–3 implementation options."*
-- **Flags:** None.
-
-**7. Plan Epic**
+**4. Plan Epic**
 - **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.
 - **When it's useful:** (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.
 - **How to use it:** `/plan-epic <epic>` — *"Decompose the epic 'migrate PayPal token storage off Custom Objects' into sub-tasks with an exploration doc for each."*
 - **Flags:** None.
 
-**8. Run Tests**
+#### Ticket-authoring posture
+
+`/explore-ticket`, `/idea-to-ticket`, 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`.
+
+- **Drafted by the writer.** Every ticket body — epic parent, epic child, and
+  ordinary sibling alike — goes through the `jira-ticket-writer` agent. Nothing
+  composes a ticket description inline.
+- **Sized toward L, overflowing upward.** `L` (target) → `XL` (when the work
+  does not fit in `L`) → `M` (third choice) → `S` (only when unavoidable). A
+  slice that outgrows `L` becomes one `XL` ticket rather than two `L` ones —
+  splitting a coherent slice to fit a band buys another worktree, another PR, and
+  another rebase for nothing. This binds a standalone ticket and an epic child
+  alike. Past roughly 40 files or ~3000 LOC it splits anyway, into the largest
+  coherent pieces available.
+- **Grouped at three.** Three or more tickets is an epic: an epic parent plus an
+  ordered child manifest, shown in full at an approval gate before anything is
+  created. One or two are ordinary siblings — no epic parent, no manifest. The
+  threshold is exactly three.
+- **Decomposed once, rendered many.** One pass freezes the split; body drafting
+  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.
+
+**5. Run Tests**
 - **What it does:** Runs the unit and E2E suites and autonomously triages/fixes failures (via the test-correction agent).
 - **When it's useful:** (Implementation) After making changes, to confirm everything passes and auto-fix straightforward breakages.
 - **How to use it:** `/run-tests`
 - **Flags:** `--unit-only` skip the E2E suite · `--skip-e2e` same, phrased the other way.
 
-**9. Learn Repository**
+**6. Learn Repository**
 - **What it does:** Researches and documents the repo's architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.
 - **When it's useful:** (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge's agents follow your conventions.
 - **How to use it:** `/learn-repository`
 - **Flags:** None.
 
-**10. Teach Bridge**
+**7. Teach Bridge**
 - **What it does:** Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).
 - **When it's useful:** (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.
 - **How to use it:** `/teach-bridge <teaching>` — *"Teach Bridge: always use data-testid selectors in E2E tests."*
@@ -748,7 +822,7 @@ Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invo
 - **Index the codebase** so Bridge's agents can reason about it: queue/parse the repo, check parse status, regenerate the directory map.
 - **Read & tune project config/standards:** list/read/update config fields, fetch project standards, and the per-topic `learn-*` commands that populate them.
 - **Ticket lifecycle bookkeeping:** track tickets and backfill workflow-state timestamps (`scan-tickets`), search across tickets, read comments, list attachments.
-- **Pipeline machinery:** list/inspect pipeline recipes and run/resume/list/delete pipeline runs (the engine under the orchestration commands).
+- **Pipeline machinery:** list/inspect pipeline recipes, run/resume/list/delete pipeline runs (the engine under the orchestration commands), and resume a full-automation chain that stopped at an approval gate or was interrupted.
 - **Decision page** generation for capturing human review decisions as structured data.
 - **Connectivity & identity checks:** ping Bridge, check your role, resolve the local docs directory.
 - **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, councils, research, architecture) without regenerating it.
@@ -756,7 +830,7 @@ Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invo
 
 ## Salesforce B2C Commerce (SFCC) Tools
 
-Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks — cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform's object model, custom objects, or site configuration — exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge's SFCC tools install side-by-side with `b2c-dx-mcp` (they don't duplicate its surface) and close that gap with **OCAPI Data API introspection** of system objects, custom object definitions, and site preferences — plus, behind a separate opt-in, a small set of sandbox-bounded writes.
+Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks — cartridge deploy, step debugging, MRT bundle push, and SCAPI Custom API scaffolding. **As of `@salesforce/b2c-dx-mcp` 1.1.2 (published 2026-05-20)** it has no way to *read* the platform's object model, custom objects, or site configuration — exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. That comparison is dated on purpose: its basis is this repository's hand-maintained [vendor manual](../docs/mcp/b2c-commerce-developer.md), pinned to the same version, so a new Salesforce toolset ages the claim visibly instead of rotting silently. Bridge's SFCC tools install side-by-side with `b2c-dx-mcp` (they don't duplicate its surface) and close that gap with **OCAPI Data API introspection** of system objects, custom object definitions, and site preferences — plus, behind a separate opt-in, a set of sandbox-bounded writes.
 
 **Every SFCC tool is restricted to a developer sandbox, and the restriction is checked at invocation time against the hostname your credentials actually resolve to** — not against anything the caller passes in. If `dw.json` or `SFCC_HOSTNAME` names a host Bridge does not recognize as a developer sandbox, every SFCC tool refuses with a `403` before contacting it. See [Sandbox enforcement](#sandbox-enforcement).
 
@@ -771,7 +845,7 @@ The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always a
 
 **Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).
 
-**1. Set the repo `version` config field** to your SFCC project type — one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.
+**1. Set the repo `version` config field** to your SFCC project type — one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks the OCAPI tools — the eight reads, the nine writes, and `check_permissions`. It does **not** block `sfcc_setup_status`, and it does not block `sfcc_log_query`: log query runs on its own gate, which reads neither the `version` field nor `dw.json` and instead probes the backend log capability (log access is WebDAV Basic auth, a different boundary from OCAPI's OAuth). Set the field via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.
 
 **2. Provide SFCC credentials.** Create a `dw.json` in your project root:
 
@@ -783,7 +857,17 @@ The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always a
 }
 ```
 
-Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.
+Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. `dw.json` is auto-added to git exclude and must never be committed.
+
+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.
+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.
 
 **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**:
 
@@ -795,6 +879,13 @@ Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `
 
 **4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
 
+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`.
+
+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.
+
 </details>
 
 ### Sandbox enforcement
@@ -848,7 +939,7 @@ Users of `BRIDGE_MCP_PROFILE=full` keep write access and need no change.
 
 ### Tools
 
-The `sfcc` profile registers **read-only** tools: eight OCAPI reads plus `sfcc_log_query`. The **nine destructive write tools** are registered only by the separate `sfcc-write` profile — see [Read and write profiles](#read-and-write-profiles). Both surfaces are bounded to a developer sandbox by the same invocation-time check.
+Twenty tools in total: two always-on diagnostics, the `sfcc` profile's **read-only** surface (eight OCAPI reads plus `sfcc_log_query`), and the nine destructive writes that only the separate `sfcc-write` profile registers — see [Read and write profiles](#read-and-write-profiles). Every one of them is bounded to a developer sandbox by the same invocation-time check. All twenty are enumerated below.
 
 An oversized response is saved in full to `BAPI_DOCS_DIR/sfcc/` and replaced by a parseable JSON descriptor — `truncated: true`, the `saved_path` it was written to, and the `page` metadata (`returned`, `total` when OCAPI supplied one, `has_more`) — so the collection metadata survives even though the data itself is on disk. If that save fails, the complete payload is returned inline instead, still as parseable JSON.
 
@@ -858,11 +949,19 @@ Attribute-definition reads and writes can return an attribute's `default_value`
 - `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.
 
-**System object model** (needs the `sfcc` profile)
+**System object model — reads** (needs the `sfcc` profile)
 - `system_object_list` — list system object types (Product, Order, Customer, …).
 - `system_object_get` — fetch one system object type's definition.
 - `system_object_attribute_search` — search a type's attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.
 
+**System object model — writes** (needs the `sfcc-write` profile; every one is a destructive write, sandbox only)
+- `system_object_attribute_definition_create` — create an attribute definition via `PUT /system_object_definitions/{type}/attribute_definitions/{id}`.
+- `system_object_attribute_definition_update` — update one via `PATCH` on the same path.
+- `system_object_attribute_group_create` — create an attribute group via `PUT /system_object_definitions/{type}/attribute_groups/{id}`.
+- `system_object_attribute_group_update` — update one via `PATCH` on the same path.
+- `system_object_attribute_assign_to_group` — assign an existing attribute definition into a group via `PUT …/attribute_groups/{group}/attribute_definitions/{def}`.
+- `custom_preference_definition_create` — define a custom site or organization preference via `PUT /system_object_definitions/{SitePreferences|OrganizationPreferences}/attribute_definitions/{id}`.
+
 **Custom object definitions** (reads need `sfcc`; the two writes need `sfcc-write`)
 - `custom_object_definition_attributes_get` — fetch attribute definitions for a known custom object type (`default_value` withheld). OCAPI cannot enumerate custom object type *IDs* directly, so `object_type` must be known — but it is discoverable: call `system_object_list` at `projection: "full"` for each custom type's `display_name` and `attribute_definition_count`, derive a candidate id (e.g. strip spaces from `"Product Quality Result"` → `ProductQualityResult`), and confirm it by checking that this tool's returned attribute count matches that row's `attribute_definition_count`.
 - `custom_object_definition_attribute_search` — search attribute definitions within a known custom object type (`default_value` withheld). Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability. Same discovery path as above applies to `object_type`.
@@ -870,25 +969,28 @@ Attribute-definition reads and writes can return an attribute's `default_value`
 - `custom_object_definition_attribute_update` — **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH …/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.
 
 **Site preferences** (reads need `sfcc`; the write needs `sfcc-write`; sandbox only)
-- `site_preference_get` — read a preference group's effective preferences.
-- `site_preference_search` — search/filter preferences within a group.
+- `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 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.
+
 **On-demand log query** (needs the `sfcc` profile)
 - `sfcc_log_query` — query redacted, filtered SFCC logs on demand. `environment` and `time_range` (`start`/`end`) are **required** — production, "all environments", and an open-ended period are never inferred. The tool calls a Bridge backend endpoint that runs the pull → redaction → filter pipeline server-side and returns scoped, redacted findings; **WebDAV credentials, retrieval, redaction, and filtering all stay server-side and single-sourced.** It holds no credentials of its own.
   - **Guardrails.** Selection is bounded by log-file `prefixes` (max 5), the time range, a scanned-entry cap (`max_entries`, ≤ 2000), a finding cap, and a per-snippet length cap. High-volume prefix classes (`info`, `jobs`, `debug`, `customdebug`) impose a **stricter 6-hour** max range (vs. 24h for the error class) because `info-*` runs ~1 MB/day versus `error-*` at ~13 KB median — a wide window over a high-volume prefix is **rejected**, never silently narrowed.
   - **Response order.** Resolved scope (`environment`, `time_range`, `applied_prefixes`) and cap `status` first, redacted `findings` second, retrieval/truncation `metadata` last.
   - **Statuses & errors.** `ready`, `no_matching_findings`, `results_truncated`; plus `VALIDATION_ERROR` (bad/oversized scope, caught before any network call), `NOT_CONFIGURED` (503 — the log capability isn't set up; run `sfcc_setup_status`, whose step 6 reports it), and `BAD_GATEWAY`/`SERVICE_UNAVAILABLE` on a retrieval/backend failure.
   - **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-dx-mcp`** (`logs_list_files`, configured from `dw.json`) — it is vendor-maintained and reads log files over WebDAV, so it is strictly less work than shelling the B2C CLI (`b2c logs get --since <window> --search <q> --json`). It is **not** the primary path because its credentials live client-side and its output has **not** passed Bridge's redaction/filter. If you use it, its output must be treated as raw: route it back through the same server-side Python `LogSource` composition and `RedactionPort`/T3 filter workflow — never paste or relay unredacted `b2c-dx-mcp` or CLI output to an LLM.
+  - **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.
 
 ## 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](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.
+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.
 
 ### `start-tickets`
 
-Spawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`. For existing ticket keys, `/review-and-start` (see [Usage Documentation → Review and Start](#tier-3--now-and-then)) is the recommended enriched front door over this CLI's `--workflow review-and-implement` seam; using the CLI directly (below) remains the advanced/lower-level path.
+Spawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`. For existing ticket keys, `/review-and-start` (see [Usage Documentation → Review and Start](#regularly-useful)) is the recommended enriched front door over this CLI's `--workflow review-and-implement` seam; using the CLI directly (below) remains the advanced/lower-level path.
 
 ```
 npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
@@ -947,6 +1049,29 @@ authenticate. See
 
 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.
 
+### `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:
+
+```
+npx -y @bridge_gpt/mcp-server drive-epic <EPIC>
+```
+
+You are never asked to choose. Bridge currently has two conductors and a standing
+rule that they must never operate on the same epic — two transition authorities on
+one epic wedge it permanently — so the choice is made structurally rather than by
+judgement. Readiness green routes to the v2 bootstrap below (pass `--plan-file`
+and `drive-epic` runs it for you); readiness not green prints the interactive
+pilot instruction instead. If readiness is **unknown** — unreachable,
+unauthorized, or malformed — it escalates and prints no conductor invocation 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.
+
+Two conductors is a transitional state. When one is eliminated, `drive-epic` is
+the only thing that changes.
+
 ### `setup-epic`
 
 Bootstraps an Epic Conductor v2 run in one command — creates the epic run, stores the plan DAG, and approves it:
@@ -1086,10 +1211,20 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `BAPI_BASE_URL` | Yes | `https://bridgegpt-api.com` | Bridge API base URL |
+| `BAPI_BASE_URL` (server, installer) | No | `https://bridgegpt-api.com` | Bridge API base URL. The MCP server and the `install` CLI both fall back to the production default |
+| `BAPI_BASE_URL` (`executor` subcommand) | **Yes** | _(none)_ | The `executor` deliberately has **no** production fallback — it refuses to start rather than guess a target |
 | `BAPI_REPO_NAME` | Yes | _(none)_ | Jira project/repository identifier configured in Bridge API |
-| `BAPI_API_KEY` | Yes | _(none)_ | API key obtained from the Bridge API setup UI |
-| `BAPI_PROJECT_ROOT` | No | _(auto-set by --init)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution |
+| `BAPI_API_KEY` | No | _(none)_ | A Bridge credential **is** required; this environment variable is only the first place the server looks for it. When it is unset the server resolves the credential from the user-scoped store (`~/.config/bridge/credentials.json`, target `bapi:<repo>`), which is why generated MCP registrations are secret-free |
+| `BAPI_PROJECT_ROOT` | No | _(see fallback order)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution. Resolved once, in order: `BAPI_PROJECT_ROOT` → the connected client's MCP `roots/list` → `CLAUDE_PROJECT_DIR` → `process.cwd()`. Several paths *write* it into a generated registration (`--init`, host-config provisioning, the worktree `mcp-invoke` shim) — that is provenance, not a runtime default |
+| `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) |
+| `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_UVICORN` | No | `uvicorn` | Executable used for the server member of `plane up` |
 | `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 |
@@ -1098,7 +1233,11 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `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 |
 | `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), `sfcc` (+ the 8 heavy SFCC read tools and `sfcc_log_query` — read-only, see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), `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 `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. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |
+| `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), `sfcc` (+ the 8 heavy SFCC read tools and `sfcc_log_query` — read-only, see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), `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 `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. 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`. |
+
+Environment values are **trimmed**, and only a non-empty result wins. A
+whitespace-only `BAPI_API_KEY` therefore does not override anything: it falls
+through to credential-store resolution exactly as an unset variable would.
 
 ## Dynamic tool-surface gating (capability availability)