@bridge_gpt/mcp-server 0.2.34 → 0.2.36

package/README.md

@@ -2,13 +2,55 @@
 
 The Bridge MCP is an end-to-end accelerator for shipping code within SFCC, powered by [Bridge API](https://bridgegpt-api.com). Works with Claude Code, Github Copilot, Cursor, Windsurf, and OpenAI Codex.
 
+## Install
+
+From your **project root**, run:
+
+```bash
+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.
+
+**What it changes in your project**
+
+- 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
+  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.
+
+**Prerequisites**
+
+- **Node.js 18 or newer** (`node --version`), which is what provides `npx`.
+- **A project directory** — run the command from the folder your editor opens, the
+  one containing `package.json` or your repository root.
+- **An MCP-capable editor**: Claude Code, GitHub Copilot, Cursor, Windsurf, or
+  OpenAI Codex.
+- **No Bridge account needed.** The installer can create one for you from just an
+  email address.
+
 ## Contents
 
-- [Getting Started](#getting-started)
+- [Install](#install)
+- [Installing, step by step](#installing-step-by-step)
+- [What to expect](#what-to-expect)
+- [Troubleshooting](#troubleshooting)
+- [Quick start details](#quick-start-details)
 - [Usage Documentation](#usage-documentation)
-  - [Tier 1 — Regularly useful](#tier-1--regularly-useful)
-  - [Tier 2 — Occasionally useful](#tier-2--occasionally-useful)
-  - [Tier 3 — Now and then](#tier-3--now-and-then)
+  - [Regularly useful](#regularly-useful)
+  - [Occasionally useful](#occasionally-useful)
+  - [Now and then](#now-and-then)
+  - [Workflow commands](#workflow-commands)
   - [Operational commands](#operational-commands)
   - [Extra Capabilities](#extra-capabilities)
 - [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)
@@ -20,300 +62,232 @@ The Bridge MCP is an end-to-end accelerator for shipping code within SFCC, power
 
 For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./docs/CONDUCTOR.md).
 
-## Getting Started
+## Installing, step by step
 
-### Quick start
+**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
+you run it in your home directory, your editor will not find any of it.
 
-From your **project root**, install and connect in one command:
+**2. Run the command.**
 
 ```bash
-npx -y @bridge_gpt/mcp-server@latest install-bridge
+npx -y @bridge_gpt/mcp-server install
 ```
 
-Run bare like that in a terminal and it starts by asking
-**`How would you like to connect to Bridge API?`** with three numbered choices:
+**3. Answer the sign-in question.** On a first run it asks whether you already have
+a token:
 
 ```
-1. I have an invite token
-2. I'm new — set me up with just my email
-3. I have an API key for an existing project
+1. Yes, I have received a token
+2. No, I need one
 ```
 
-The two routes that **create** a project lead, because they are what a first-time
-user needs; the existing-project route is last and says so in its own label.
-
-- **1** — the **bootstrap-invite** flow. It asks for the invite token you were given,
-  with echo suppressed. Same as passing `--invite` (see below).
-- **2** — the **self-serve** flow, and the right answer if you have nothing yet. It
-  asks for an **email**, then a name for your new Bridge project, and creates the
-  workspace and your own admin API key for you. No account, no key, and no invite
-  needed beforehand. Same as passing `--email you@example.com` (see below).
-- **3** — the existing-project flow. It asks for your **API key** (generate one on the
-  Bridge API web UI **Security** page) and resolves your project from that key;
-  everything else is derived.
-
-There is **no default**: pressing Enter selects nothing. A blank or invalid answer
-re-prompts once with a hint, then exits with guidance naming all three routes.
-
-**Pasted the wrong kind of credential?** Both directions are detected from the value's
-**shape alone** — no probe request is ever sent — and neither switches routes silently:
-
-- A **`bapi_inv_…` invite entered as an API key** is announced, then confirmed before
-  it is redeemed to create a new project. A non-interactive run keeps the existing
-  automatic switch, but now prints the notice.
-- An **API-key-shaped value entered as an invite** is announced and can switch to the
-  existing-project route only after you confirm. A non-interactive run exits with
-  guidance instead of switching, so a script is never silently redirected. The check
-  happens **before** any project-name prompt, credential-store write, or network call,
-  so a declined switch leaves nothing behind.
-
-A value that is neither shape (a mistyped invite, say) is **not** reclassified — it
-stays on the route you picked.
-
-That question is asked only for a *bare interactive* run. Passing any flag, setting
-`BAPI_API_KEY`, or running without an interactive terminal skips it and keeps the
-existing deterministic behavior.
-
-From there `install-bridge` scaffolds the project, writes your editor's MCP config
-with real values, verifies connectivity, persists your API key to the user-scoped
-credential store, and opens a fresh agent session that runs `/install-bridge` to
-derive and apply the remaining config, presents a concise **capability report**
-("What Bridge can help with"), and recommends `/learn-repository` as your next step.
-It does **not** run `/learn-repository` itself — that stays your next explicit
-invocation. There is **no indexing question**: indexing starts automatically
-server-side once the repository reaches full parse readiness. Add `--dry-run` to
-preview every step without writing, pinging, or spawning anything.
-
-**Were you sent a bootstrap invite?** Then you don't need an API key or the web UI
-at all — run the command your operator gave you:
+- Choose **2** 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 **1** 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
+[Choosing how you sign in](#quick-start-details).
+
+**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.
+
+**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
+"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.
+
+**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
+one to show — most often `/learn-repository`, which it recommends when the project
+still needs its architecture, testing, review, and correctness standards documented
+and your key can run it. The installer deliberately does not run it for you. Those
+standards are what make every later plan, critique, and review match how your
+project actually works, and they only need to be gathered once per project — the
+result is shared with everyone on the team. If the session shows no next step,
+there is nothing for you to run.
+
+Want to see what would happen without changing anything? Add `--dry-run`.
+
+## What to expect
+
+**Files that appear in your project**
+
+| Path | What it is | Commit it? |
+|---|---|---|
+| `.claude/commands/`, `.cursor/commands/` | The slash commands your editor runs | Yes |
+| `.claude/agents/` and editor equivalents | Agent definitions used by those commands | Yes |
+| `.bridge/config` | Your project manifest — the repository name and which MCP targets to provision. Deliberately secret-free | Yes |
+| `.bridge/pipelines/`, `.bridge/instructions/` | Editable pipeline definitions | Yes |
+| `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json` | MCP registrations for your editor. These can carry your key, so the installer git-ignores them | No |
+
+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
+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.
+
+**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
+recommend. `/learn-repository` is the usual one: it is recommended when the project
+still needs its conventions documented and your key can run it. It is never
+automatic — until someone runs it, Bridge's agents work from your code alone rather
+than from your project's documented conventions.
+
+**Indexing happens on its own.** There is no "index my repository?" question. Once
+your project has the settings it needs, indexing starts server-side. You never have
+to ask for it.
+
+## Troubleshooting
+
+**"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
+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.
+
+**"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*,
+not the installer. It is waiting for an editor to connect over stdio, which is
+exactly what it should do when your editor launches it — but from a terminal it
+looks like a hang. It prints a line saying so. Press Ctrl-C and run
+`npx -y @bridge_gpt/mcp-server install` instead. The explicit spelling
+`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
+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.
+
+**"Which repository name should I use?"** The one registered with Bridge. If you
+have an existing key, the installer usually resolves it for you; when it cannot, it
+asks, and `--repo <name>` answers it up front.
+
+**Still stuck? Ask the installer to diagnose itself.**
 
 ```bash
-npx -y @bridge_gpt/mcp-server@latest install-bridge --invite
+npx -y @bridge_gpt/mcp-server doctor
 ```
 
-That one-liner is deliberately **secret-free**: the CLI prompts for the bootstrap
-invite token with **echo suppressed**, and sends it only in the request body. It
-creates your project and mints your own admin API key in a single command.
+`doctor` is strictly read-only. It reports what it found — configs, registrations,
+credential availability, prerequisites — and changes nothing.
+
+## Quick start details
 
-To upgrade later, run:
+<details>
+<summary><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.
+
+**No account yet — sign up with an email.**
 
 ```bash
-npx -y @bridge_gpt/mcp-server upgrade
+npx -y @bridge_gpt/mcp-server install --email you@example.com
 ```
 
-`upgrade` re-execs from `@latest`, refreshes all scaffolded artifacts (slash
-commands, agents, pipelines), rewrites the version pin, and reconnects — also
-available as the `/upgrade-bridge` slash command. (The legacy `--upgrade` flag still
-works as a fallback.)
+Creates a brand-new Bridge project for that address and your first admin key in one
+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 **2** at the prompt.
 
-<details>
-<summary><strong>Installation Instructions</strong></summary>
-
-#### What `install-bridge` does
-
-`install-bridge` collapses the whole setup into a single command. It:
-
-1. **Scaffolds** the project (the same artifacts `--init` writes: slash commands,
-   agents, `.bridge/pipelines/`, and secret-free MCP config placeholders).
-2. **Writes the per-host MCP config** (`.mcp.json` / `.cursor/mcp.json` /
-   `.vscode/mcp.json`) with your real `BAPI_REPO_NAME` / `BAPI_API_KEY` /
-   `BAPI_BASE_URL` / `BAPI_DOCS_DIR`, preserving any unrelated servers. The
-   launcher it writes is pinned to the exact installed version so `npx` never
-   silently reuses a stale local copy. (Windsurf and Codex are global configs it
-   can't safely write — it prints copy-paste instructions for those.)
-3. **Verifies connectivity** against the Bridge API before persisting anything.
-4. **Persists your key** to the user-scoped credential store
-   (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned
-   tooling (e.g. `start-tickets`) can resolve it.
-5. **Opens a fresh agent session** that runs `/install-bridge` to derive and apply
-   the remaining config fields from your codebase, presents a concise capability
-   report ("What Bridge can help with"), and recommends `/learn-repository` as the
-   next step. It does not chain into running `/learn-repository` itself — that's
-   your next explicit invocation. There is no indexing question anywhere: indexing
-   starts automatically once the repository reaches full parse readiness (VCS
-   credentials, the code index prerequisites, and project description), so you
-   never need to ask for it or run `/parse-repository` yourself as part of
-   onboarding.
-
-In this **existing-key** flow the only inputs are an **API key** and a **repo name**
-(everything else is derived). Resolution order:
-
-- **API key:** `--api-key <key>` → `BAPI_API_KEY` env → an interactive (no-echo)
-  prompt. Generate one first on the Bridge API web UI **Security** page (see
-  [Generate an API Key](#2-generate-an-api-key)); in this flow the command consumes
-  a key, it never mints one — **`--email` and `--invite` are the two exceptions**
-  (below), and each mints your first key. All three of `--api-key`, `BAPI_API_KEY`,
-  and the hidden prompt also accept a bootstrap-invite value (`bapi_inv_…`) —
-  detected automatically, **announced**, and (on a terminal) confirmed before it is
-  redeemed the same way `--invite` is, skipping repository lookup entirely.
-  `--invite` and `--email` remain the preferred, explicit entry points for a new
-  project. The key is **never printed or logged**.
-- **Repo name:** `--repo <name>` and `BAPI_REPO_NAME` remain the deterministic
-  short-circuits and compatibility fallbacks — when either is set it is used
-  directly, with no network round-trip. When **neither** is set, a compatible
-  server resolves the unique repository from your existing API key automatically
-  (a read-only lookup), so you don't have to supply it. What happens when that
-  lookup does not return a name is **tiered**, because the causes are not alike:
-  - **The key doesn't identify exactly one project** — the run **stops**. It never
-    guesses a name, because an accepted guess is just a `403` two steps later. Re-run
-    with `--repo <name>`, or rotate the key on the **Security** page so it maps to a
-    single project.
-  - **The server is older, or the lookup fails transiently** — still recoverable. You
-    are asked to type the registered name, with **no pre-filled default** (and
-    `--repo` is required when stdin is non-interactive).
-
-  Whatever name is used MUST match the server-side repository registration.
-
-#### Self-serve email onboarding (`--email`) — no account, no key, no invite
-
-The primary path for a **first-time user with nothing yet** — no Bridge account,
-no API key, and no pre-issued invite. Run:
+**You were sent an invite code.**
 
 ```bash
-npx -y @bridge_gpt/mcp-server@latest install-bridge --email you@example.com
+npx -y @bridge_gpt/mcp-server install --invite
 ```
 
-`install-bridge` requests a brand-new Bridge workspace for that email, receives an
-invite token, and then feeds it into the **exact same** persist-before-exchange
-bootstrap protocol as `--invite` below — so the project is created and your first
-admin key is minted in one command. The minted token is used internally and **never
-shown**.
-
-The email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a
-**visible** interactive prompt (email is not a secret, so it is echoed as you type —
-unlike the API key and the invite token, which use a hidden prompt). That prompt is
-what **option 2** of the bare-run chooser reaches, so
-`install-bridge --email you@example.com` and a bare `install-bridge` + `2` land in
-the same place. The email is still **never written to a log line**. No email
-verification is performed and no message is sent to the address — it only labels your
-new workspace. `--email` is mutually exclusive with `--api-key` and `--invite`.
-
-##### Self-serve retries resume automatically
-
-A self-serve run that fails part-way through — a network blip on the exchange, a
-failed connectivity check, an interrupted credential write — saves its signup state
-under `bootstrap-pending:<repo>` in the credential store (mode `0600`, fsync'd, the
-same record that already holds your `key_secret`).
-
-**Just re-run the self-serve flow.** It detects that saved attempt, prints
-`resuming your previous signup attempt for <repo>`, and re-drives the *same*
-exchange — it does **not** sign up again, so a retry never creates a second
-workspace. This is why the self-serve record stores the minted invite token: you
-were never shown that token, so nothing else could re-present it.
-
-Do **not** copy, display, or hand-remove that record. If the saved invite has
-genuinely expired, the CLI says so and **asks for confirmation** before discarding
-it and starting fresh — it never discards it silently, because a record whose
-exchange already succeeded is the only trace of a live admin key.
-
-Because this flow *creates* the project, it asks you to **name a new project**
-(`Name your new Bridge project [<inferred>]: `) rather than to match an existing
-server-side registration. The name must be globally unique; if it's taken, you're
-asked for another one and the invite is not consumed. The same applies to `--invite`.
-
-#### Bootstrap-invite onboarding (`--invite`)
-
-With a **bootstrap invite** you were already given, there is no pre-existing key and
-no web UI: like `--email` above, this mode **creates** the project and its first
-admin key instead of consuming one. Run `install-bridge --invite` and it:
-
-1. **Prompts for the bootstrap invite token** with echo suppressed (the default —
-   see below).
-2. **Generates your `key_secret`** (32 CSPRNG bytes) and **fsyncs it locally**
-   *before* contacting the server. If that write fails the run aborts and the
-   invite is **not** spent.
-3. **Redeems the invite** — `POST /setup/bootstrap` with the token, repo name, and
-   `key_secret` in the **body** — which creates the project and mints your admin
-   key. (This replaces the connectivity ping: there is no key to ping with yet.)
-4. **Verifies the newly-minted key**, then writes the per-host MCP config.
-5. **Promotes the credential** to `bapi:<repo>` and **opens the agent session** —
-   the same Steps 3–5 as the normal flow.
-
-Because the locally-saved `key_secret` is the only proof that can replay a
-redemption, a re-run after a network failure is safe: it re-sends the *same* secret
-and gets back the *same* project and key. If the repo name you chose is already
-taken (names are globally unique) the server rolls back — your invite is untouched —
-and the CLI asks for a different name and retries with the same token.
-
-**Pasted an API key here by mistake?** The invite input recognizes a Bridge API key
-by its shape and says so **before** it asks you to name a project, writes anything to
-the credential store, or contacts the server — so nothing is created and no invite is
-spent. On a terminal you're offered the existing-project route in place; a
-non-interactive run exits with guidance to re-run with `--api-key` instead. A value
-that is neither a `bapi_inv_…` invite nor a valid key shape is left alone and
-continues down this path.
-
-**The delivered one-liner is secret-free, by design.** "A copy/paste one-liner" and
-"the token never touches shell history" are contradictory, so the token is *not* in
-the command: the CLI asks for it, and it travels only in the request body.
-`--invite <token>`, `--invite=<token>`, and `BAPI_INVITE` still work for
-**scripting only** — and both forms **expose the token to your shell history and to
-the process list**. Prefer the prompt.
-
-Useful flags:
-
-- `--dry-run` — preview every step (scaffold targets, config files and keys with
-  the key value **redacted**, the ping target, the credential store target, and
-  the exact agent spawn command) without writing, pinging, or spawning anything.
-  With `--invite` it also never calls the exchange endpoint and never generates or
-  stores a secret.
-- `--force` — overwrite an existing real `BAPI_API_KEY` in a host config, or in the
-  credential store, without prompting (re-running is otherwise non-destructive).
-- `--agent claude|cursor-agent` — which agent to launch for the agentic remainder
-  (default `claude`).
-- `--email <addr>` — self-serve signup: create a new workspace from just an email
-  (mutually exclusive with `--api-key` and `--invite`). Falls back to
-  `BAPI_SIGNUP_EMAIL`, then a visible prompt. Visible input, not a secret; still
-  never logged.
-- `--invite [token]` — redeem a bootstrap invite (mutually exclusive with
-  `--api-key` and `--email`). Omit the value to get the hidden prompt.
-
-That's it — once `install-bridge` finishes you're connected. If you prefer to do
-it by hand (or just want to understand each step), the manual flow below does the
-same thing.
-
-#### Manual Setup (Alternative)
-
-##### 1. Install the Package
-
-From your **project root**, install the MCP server and scaffold slash commands:
+Redeems the invite, creates your project, and mints your first admin key. Run it
+*without* a value, as shown: the installer then asks for the code at a hidden
+prompt, so the code never lands in your shell history. `--invite <code>` and the
+`BAPI_INVITE` environment variable exist for scripting, but both expose the code to
+your shell history and to the process list.
+
+**Your team already has a project and gave you an API key.**
 
 ```bash
-npm i @bridge_gpt/mcp-server
-npx -y @bridge_gpt/mcp-server --init
+npx -y @bridge_gpt/mcp-server install --api-key <key>
 ```
 
-`--init` must be run from the directory containing your `package.json`. It:
+Or omit the flag and paste the key at the hidden prompt. Generate a key on the
+Bridge web UI's **Security** page (**Create New Key**, role **Admin**) and copy it
+immediately — it is shown once. `BAPI_API_KEY` works too.
 
-- Creates slash commands in `.claude/commands/` and `.cursor/commands/`
-- Detects existing MCP config files and sets `BAPI_PROJECT_ROOT` so local file output resolves correctly
-- Scaffolds `.bridge/pipelines/` for custom pipeline authoring
+If you paste an invite code where a key was expected, or a key where an invite was
+expected, the installer recognizes the mismatch and tells you before anything is
+created or spent.
 
-Re-run `--init` after upgrading the package to get updated commands.
+</details>
+
+<details>
+<summary><strong>Installer flags</strong></summary>
+
+| Flag | What it does |
+|---|---|
+| `--email <addr>` | Sign up for a new Bridge project with just an email address |
+| `--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`) |
+| `--dry-run` | Preview every step without writing, contacting Bridge, or opening anything |
+| `--force` | Overwrite an existing stored key without asking |
+| `-h`, `--help` | Full usage |
+
+`--email`, `--invite`, and `--api-key` are mutually exclusive — each names a
+different way to arrive, and the installer will not guess between them.
 
-##### 2. Generate an API Key
+</details>
 
-1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project's **Security** page
-2. Click **Create New Key**
-3. Enter your email, an optional label (e.g., "MCP Server"), and select the **Admin** role
-4. Click **Create Key**
-5. **Copy the key immediately** — it will not be shown again
+<details>
+<summary><strong>Setting up an MCP host by hand</strong></summary>
 
-##### 3. Configure the MCP Server
+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.
 
-Add the following to your editor's MCP configuration file, pasting in the API key from step 2:
+Scaffold the project files without configuring anything:
+
+```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."
 
 <details>
 <summary><strong>Claude Code (.mcp.json)</strong></summary>
 
-The `--init` command (step 1) detects Claude Code and creates a `.mcp.json` at your project root with placeholder values. Open it and replace `your-repo` and `your-api-key` with your actual values from step 2:
-
 ```json
 {
   "mcpServers": {
     "bridge-api": {
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server"],
+      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -334,7 +308,7 @@ The `--init` command (step 1) detects Claude Code and creates a `.mcp.json` at y
   "servers": {
     "bridge-api": {
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server"],
+      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -355,7 +329,7 @@ The `--init` command (step 1) detects Claude Code and creates a `.mcp.json` at y
   "mcpServers": {
     "bridge-api": {
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server"],
+      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -380,7 +354,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge-api": {
       "command": "npx",
-      "args": ["-y", "@bridge_gpt/mcp-server"],
+      "args": ["-y", "@bridge_gpt/mcp-server", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -399,7 +373,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge-api]
 command = "npx"
-args = ["-y", "@bridge_gpt/mcp-server"]
+args = ["-y", "@bridge_gpt/mcp-server", "serve"]
 
 [mcp_servers.bridge-api.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -408,193 +382,305 @@ BAPI_API_KEY = "your-api-key"
 BAPI_DOCS_DIR = "docs/tmp"
 ```
 
-> Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see Environment Variables below).
+> Codex users: set `BAPI_PROJECT_ROOT` manually in your config (see [Environment Variables](#environment-variables)).
 </details>
 
-After saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the `ping` tool.
+After saving, reload your editor and ask your assistant to call the `ping` tool to
+confirm the connection.
 
-##### 4. First-Time Setup: Teach Bridge Your Codebase
+An entry with no trailing `serve` still starts the server — bare invocation means
+"server" permanently, and nothing rewrites an existing config to add the token.
 
-If you're the first person to install Bridge API on your project, run the `/learn-repository` slash command after completing setup. This analyzes your codebase's architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project's actual architecture and conventions.
+</details>
 
-You only need to do this once per project — the learned standards persist for all team members.
+<details>
+<summary><strong>Upgrading Bridge</strong></summary>
 
-##### Upgrading (details)
+```bash
+npx -y @bridge_gpt/mcp-server upgrade
+```
+
+`upgrade` fetches the latest published version, refreshes your scaffolded slash
+commands, agents, and pipelines, updates the version pin in your MCP config, and
+opens a session so you can reconnect. It is also available as the
+`/upgrade-bridge` slash command.
 
-The one-command `npx -y @bridge_gpt/mcp-server upgrade` (shown above) is the
-recommended path. The legacy flag `npx -y @bridge_gpt/mcp-server --upgrade` still
-works: it runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version
-summary, then re-runs the full `--init` scaffolding flow to update your slash
-commands, agents, and pipeline definitions.
+The server checks for updates on startup and notes a newer version in your editor's
+MCP output log. That check is cached for a day and never blocks startup.
 
-The MCP server also checks for updates automatically on startup. If a newer version is available, you'll see a notice in your editor's MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.
+Re-running `install` on an already-configured project is safe: it refreshes the
+scaffolded files without overwriting your stored credential unless you pass
+`--force`.
 
 </details>
 
 ## Usage Documentation
 
-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** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).
+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).
 
 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.
 
-### Tier 1 — Regularly useful
+<!-- 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
+     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).
+     Everything outside the marker pair — including the sections below it — is hand-written. -->
 
-These features are useful for most tickets.
+<!-- BEGIN GENERATED: mcp-tool-documentation (managed by scripts/sync_mcp_server_readme.py — DO NOT EDIT BY HAND) -->
+### Regularly useful
+
+The tools worth knowing for most tickets.
 
 **1. Review Ticket**
-- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique plus an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The backend executor now owns all review round orchestration (including the second-opinion round) server-side; pass `--rounds=1` for a cheaper single-pass review, `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend's difficulty-adaptive review policy decide.
+- **What it does:** Runs a full quality review of a ticket: clarifying questions and a critique plus an alternate-model second opinion, then evaluates the findings and produces a decision page for accepting or rejecting them.
 - **When it's useful:** (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.
-- **How to use it:** `/review-ticket BAPI-123` (command only — "review" as free text is easily mistaken for a freehand agent review).
-- **Flags:** `--auto` auto-accept findings / skip the approval gates · `--rounds=1` request a cheaper single-pass review (no second-opinion round) while preserving downstream evaluation and decision-capture work · `--rounds=2` force the full second-opinion review · omit `--rounds` to let the backend's difficulty-adaptive review policy decide (it falls back to a full second-opinion review when adaptive routing is disabled or the ticket's difficulty cannot be resolved).
-- **Multi-ticket fan-out:** `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only — no `wt`/`git`). All `/review-ticket` flags apply; `--review KEY=auto,rounds=N` sets per-ticket overrides. Packaged CLI: `npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...]`.
+- **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. 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 (default `implement`, byte-identical to today; `review-and-implement` runs `/review-ticket` inline then, after a per-ticket halt gate, hands off to a **fresh** `/implement-ticket` session reusing the same worktree) · `--rounds=1|2` review-only, forwarded to the review phase, valid only with `--workflow review-and-implement` · `--tier cheap|basic|premium` coarse model-routing override (see [CLI Subcommands](#cli-subcommands)).
+**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"`.
 
-**3. Council**
-- **What it does:** Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of four modes, selected via `mode`: **`technical`** (default — implementation/architecture approaches), **`design`** (UI/UX and visual direction), **`discovery`** (stakeholder discovery questions for early/vague tasks, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`), or **`general`** (brief-driven ideation from your task description and concerns alone). `technical` and `discovery` are codebase-grounded — they retrieve from the repository index and need a successfully indexed repo. `general` needs no code index at all, so it works immediately after install, before `/parse-repository` has ever run. The legacy boolean `design=true` still works and maps to `mode: "design"`.
-- **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 we still need to figure out* before a real ticket exists, `general` for a quick brief-driven council 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; fan it out to multiple models."* 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"` — for this vague request so we can collect the questions stakeholders need to answer first."* For a fresh, unindexed repo: *"Run a general council — `request_council` with `mode: "general"` — on launch options for this idea."*
+**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.
+- **Flags:** None.
 
 **4. 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) you don't already have.
+- **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. 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.
+**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.
 
 **6. Upload Ticket**
-- **What it does:** Pushes a drafted ticket up to Jira as a real issue (the `create_ticket` capability); handles markdown and child tickets under an Epic.
-- **When it's useful:** (Refinement) The final step after drafting — to get the ticket into Jira so it can be tracked and worked.
-- **How to use it:** Ask your agent to create the ticket, and it should confirm before creating the live Jira issue.
-- **Options:** Describe the issue type (Bug / Story / Task / Epic) and, for a child under an Epic, the parent key.
+- **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.
 
-### Tier 2 — Occasionally useful
+### Occasionally useful
 
-These features are good to know, but you probably won't use them every day.
+Good to know, but not needed every day.
 
 **1. Plan Ticket**
-- **What it does:** Generates a step-by-step implementation plan for a ticket, with references to real code files, and saves it locally.
-- **When it's useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before (or instead of) auto-implementing.
+- **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. Clarify Ticket**
-- **What it does:** Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.
+**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` — *"Generate clarifying questions for BAPI-123"*
+- **How to use it:** `/clarify-ticket BAPI-123`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**3. Critique Ticket**
-- **What it does:** Critiques a ticket's quality against your project standards and lists deviations + improvements.
-- **When it's useful:** (Refinement) When you want a quality gate on a ticket before it's worked.
-- **How to use it:** `/critique-ticket BAPI-123` — *"Critique BAPI-123 against our project standards and list what's missing or deviating."*
+**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**
+- **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.
 
-**4. Create Doc**
-- **What it does:** Generates a design document for a ticket — a TDD (technical design, engineer audience), an FSD (functional spec, for product/design/QA), or a PRD (product requirements: problem, goals, success metrics) — and saves it locally.
+**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**
+- **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.
 
-**5. 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."*
+**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.
 
-**6. Second Opinion**
-- **What it does:** Gets an immediate critique of any text from a different model family — no artifact saved, just the reply.
+**9. 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 prod."*
-- **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).
+- **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).
 
-**7. Generate Image**
-- **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.
+**10. 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."*
-- **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen — adds an invisible SynthID watermark) · `quality` low (default, cheapest) / medium / high · `size` 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to `BAPI_DOCS_DIR/images/` and also returned inline.
+- **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.
 
-**8. 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).
+**11. 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.
 
-**9. Full Automation**
-- **What it does:** Drives the whole chain end-to-end: idea → ticket(s) → review each → spawn worktrees to implement.
+**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**
+- **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 — creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can't).
-- **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.
+- **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.
 
-**10. 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>`
+**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.
 
-### Tier 3 — Now and then
+### Now and then
 
-These features are useful once in a while, but you probably won't need them everyday.
+Useful once in a while.
 
 **1. Reimplement Ticket**
-- **What it does:** Pulls in new context/attachments since the last pass and implements small follow-up changes on an already-built ticket.
+- **What it does:** Gathers the context and attachments added since the last pass so a targeted follow-up change can be made.
 - **When it's useful:** (Implementation) After review feedback or new screenshots, when you need a targeted second pass rather than a fresh build.
 - **How to use it:** `/reimplement-ticket BAPI-123`
+- **Flags:** None.
 
-**2. 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` (`--unit-only`, `--skip-e2e`)
+**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. 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."*
-
-**4. Update Ticket**
-- **What it does:** Synthesizes a ticket's clarifying answers and critique into a rewritten description and pushes it to Jira.
+**3. 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 — does a full overwrite of the live Jira description; "update" as free text is both vague and hard to reverse).
+- **How to use it:** `/update-ticket BAPI-123` (command only — it fully overwrites the live description, which is hard to reverse).
+- **Flags:** None.
 
-**5. Get Ticket**
-- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).
+**4. 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."*
+- **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**
+- **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**
-- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).
+- **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's rotated."*
+- **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**
+- **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**
+- **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 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`
+- **Flags:** Pass an epic key, or an explicit list of ticket keys to estimate as one group.
+<!-- END GENERATED: mcp-tool-documentation -->
 
-**7. Download / Upload Attachment**
-- **What it does:** Pulls files off a Jira ticket to disk, or attaches a local file to a ticket.
-- **When it's useful:** (Refinement | Implementation) When a ticket has design files/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."* / *"Attach build-log.txt to BAPI-123."*
+### Workflow commands
 
-**8. Learn Repository**
+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.
+
+**2. 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**
+- **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.
+
+**5. 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**
+- **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**
+- **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**
 - **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.
 
-**9. Teach Bridge**
+**10. 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."*
-
-**10. Review and Start**
-- **What it does:** Spawns one worktree per ticket; each session reviews the ticket inline and, after a per-ticket human 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` a single chain-level flag that 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`.
-- Under the hood, this is a thin shim over `start-tickets --workflow review-and-implement <KEYS>` — the lower-level launcher seam documented above; the review→gate→fresh-implementation-handoff logic lives in the spawned `/review-and-implement` session, never in this command or the CLI. On approval, that session reuses its review-time model tier by passing it to the fresh implementation launcher via `--tier`.
+- **Flags:** None.
 
 ### Operational commands
 
@@ -964,7 +1050,7 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The server exposes **60 documented tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The authoritative tool catalog covers **92 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping`, `get_my_role`, `get_docs_dir`
 - **Team & access** — `invite_member` (admin-only; mints a scoped access key for a teammate on an already-configured project — the plaintext key is shown exactly once)
@@ -972,7 +1058,7 @@ The server exposes **60 documented tools** (enumerated below). What's actually r
 - **Attachments** — `attachment` (operations: `upload`, `download`, `list`)
 - **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_council`/`get_council`, `request_deep_research`/`get_deep_research`
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
-- **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`
+- **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`, `get_ticket_state_tree` (live repo-wide lifecycle + dependency tree; read-only, no mutation parameter)
 - **Jira status** — `get_jira_transitions`, `update_jira_status`, `resolve_target_status`
 - **Repository & CI** — `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
 - **Pipelines & automation** — `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`