@bridge_gpt/mcp-server 0.1.17 → 0.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 MCP server for [Bridge API](https://bridgegpt-api.com) — exposes Jira integration endpoints as MCP tools for AI coding agents. Works with Claude Code, VS Code/Copilot, Cursor, Windsurf, and OpenAI Codex.
 
+> **New here?** Jump to [Usage Documentation](#usage-documentation) for what you can actually do with Bridge, grouped by how often you'll reach for it.
+
 ## Getting Started
 
 ### 1. Install the Package
@@ -21,61 +23,6 @@ npx -y @bridge_gpt/mcp-server --init
 
 Re-run `--init` after upgrading the package to get updated commands.
 
-### Upgrading
-
-To upgrade to the latest version and refresh all scaffolded artifacts in one step:
-
-```bash
-npx -y @bridge_gpt/mcp-server --upgrade
-```
-
-This 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 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.
-
-### CLI subcommand: `start-tickets`
-
-Beyond `--init` / `--upgrade`, the package ships a `start-tickets` subcommand that spawns one Worktrunk worktree + selected-agent session per Jira ticket. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`. It is part of the **existing `bridge-api-mcp-server` bin** — not a separate binary — so it travels with the package to every consumer. It also backs the `/start-tickets` slash command.
-
-```
-npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
-```
-
-| Flag | Default | Meaning |
-|---|---|---|
-| `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
-| `--terminal terminal\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |
-| `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |
-| `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |
-| `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |
-| `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever `--base-branch` resolves to. |
-| `--max-parallel N` | `3` | Max worktrees created concurrently |
-| `-h`, `--help` | — | Show usage |
-
-Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent's `'/implement-ticket <KEY>'` — `claude '/implement-ticket <KEY>'` by default, or `cursor-agent '/implement-ticket <KEY>'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:
-
-```
-npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
-```
-
-**Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.
-
-- **macOS** — opens a Terminal.app or iTerm tab via `osascript`.
-- **Windows** — creates worktrees with **`git-wt`** (Worktrunk's winget alias) and opens a tab via **Windows Terminal (`wt.exe new-tab`)**, falling back to **`Start-Process powershell.exe`** when Windows Terminal is absent. Requires **Git for Windows / Git Bash** (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash). The Worktrunk binary (`git-wt`) and the tab launcher (`wt.exe`) are resolved independently and never conflated.
-- **Linux** — creates one detached **tmux** session per ticket (pane kept open after the agent exits); attach with `tmux attach -t <session>`. A missing `tmux` produces a clear, actionable error.
-
-Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` — Worktrunk's `pre-start` hook runs `uv`, but live preflight does not check it — and the selected agent's command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).
-
-### CLI subcommand: `doctor`
-
-The package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:
-
-```
-npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
-```
-
-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.
-
 ### 2. Generate an API Key
 
 1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project's **Security** page
@@ -198,184 +145,250 @@ BAPI_DOCS_DIR = "docs/tmp"
 
 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.
 
-### First-Time Setup: Teach Bridge Your Codebase
+### 4. First-Time Setup: Teach Bridge Your Codebase
 
 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.
 
 You only need to do this once per project — the learned standards persist for all team members.
 
-## Pipelines
+### Upgrading
 
-Pipelines are declarative, multi-step workflows that your AI agent executes step-by-step. Each pipeline is a JSON recipe that chains MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. Bridge ships with built-in pipelines; you can also write your own (see [Custom Pipelines](#custom-pipelines)).
+To upgrade to the latest version and refresh all scaffolded artifacts in one step:
 
-| Pipeline | Description | Invoke with |
-|---|---|---|
-| `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |
-| `review-ticket` | Two-round ticket quality review: clarifying questions and critique from multiple providers | `/review-ticket PROJ-123` |
-| `learn-repository` | Analyze codebase architecture, testing patterns, review standards, and documentation conventions, then upload to Bridge | `/learn-repository` |
-| `pr-ticket` | Commit changes and open a pull request | `/create-pr PROJ-123` |
-| `check-ci-ticket` | Commit, open a PR, then monitor CI checks until they pass or fail | `/check-ci PROJ-123` |
+```bash
+npx -y @bridge_gpt/mcp-server --upgrade
+```
 
-## Commands
+This 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.
 
-Commands are slash commands you invoke from your AI assistant's chat. Most orchestrate multi-step workflows; some are simple single-action utilities. Run `--init` to scaffold them into your project.
+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.
 
-| Command | Description |
+## 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).
+
+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
+
+These features are useful for most tickets.
+
+**1. Review Ticket**
+- **What it does:** Runs a two-round quality review of a ticket (clarifying questions + critique, plus an alternate-model second opinion) and produces a decision page to accept/reject findings.
+- **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.
+
+**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.
+
+**3. Brainstorm**
+- **What it does:** Fans your problem out to two different LLMs and synthesizes their approaches into one set of options. Runs in one of two modes: a **standard** brainstorm (implementation/architecture approaches) or a **design** brainstorm (UI/UX and visual direction).
+- **When it's useful:** (Architecture | Refinement) Early, when you want a spread of approaches — standard for *how to build it*, design for *how it should look*.
+- **How to use it:** ask your agent to brainstorm — *"Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models and synthesize."* For a design pass: *"Run a design brainstorm for the evidence-freshness dashboard UI."*
+
+**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.
+- **How to use it:** `/deep-research <question>`
+
+**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.
+
+**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.
+
+### Tier 2 — Occasionally useful
+
+These features are good to know, but you probably won't use them every day.
+
+**1. Second Opinion**
+- **What it does:** Gets an immediate critique of any text from a different model family — no artifact saved, just the reply.
+- **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).
+
+**2. 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>`
+
+**3. 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."*
+
+**4. 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.
+- **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.
+
+**5. Clarify Ticket**
+- **What it does:** Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.
+- **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"*
+- **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
+
+**6. 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."*
+- **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
+
+**7. Full Automation**
+- **What it does:** Drives the whole chain end-to-end: idea → ticket(s) → review each → spawn worktrees to implement.
+- **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.
+
+**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).
+
+**9. 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.
+- **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 · `save_locally` write the image to `docs/images`.
+
+### Tier 3 — Now and then
+
+These features are useful once in a while, but you probably won't need them everyday.
+
+**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.
+- **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`
+
+**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`)
+
+**3. 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`
+
+**4. 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."*
+
+**5. Update Ticket**
+- **What it does:** Synthesizes a ticket's clarifying answers and critique into a rewritten description and pushes it to Jira.
+- **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).
+
+**6. 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."*
+
+**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."*
+
+**8. Write Comment**
+- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).
+- **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."*
+
+**9. Get Ticket**
+- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).
+- **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."*
+
+### Operational commands
+
+Workflow commands you'll reach for during implementation and CI, beyond the tiers above:
+
+| Command | What it does |
 |---|---|
-| `/check-ci [PROJ-123]` | Monitor CI checks for the current branch, triage failures, apply fixes, and report results |
-| `/check-parse-status` | Check whether a background repository parse job is still running |
-| `/clarify-ticket PROJ-123` | Generate clarifying questions for a ticket and save them locally |
 | `/code-ticket PROJ-123` | Download the implementation plan and questions, then execute the plan inline |
 | `/commit-ticket PROJ-123` | Stage, commit, and push changes; transition Jira status; post a smoke-test comment |
 | `/create-pr PROJ-123` | Commit staged changes and open a pull request |
-| `/critique-ticket PROJ-123` | Generate a ticket quality critique and save it locally |
-| `/explore-ticket [PROJ-123]` | Free-form codebase exploration — searches code, surfaces implementation options and questions |
-| `/implement-ticket PROJ-123` | Full end-to-end implementation: plan → code → commit → PR → CI |
-| `/learn-repository` | Teach Bridge API about your codebase (architecture, testing, review patterns) |
+| `/check-ci [PROJ-123]` | Monitor CI checks for the current branch, triage failures, apply fixes, and report results |
 | `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |
-| `/plan-ticket PROJ-123` | Generate an AI implementation plan and save it locally |
-| `/reimplement-ticket PROJ-123` | Follow-up implementation pass using previous implementation context |
-| `/review-ticket PROJ-123` | Two-round ticket quality review with critiques from multiple LLM providers |
-| `/run-tests` | Run the full test suite, triage failures, and classify issues as test bugs vs. implementation bugs |
+| `/check-parse-status` | Check whether a background repository parse job is still running |
 | `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |
-| `/start-tickets KEY [KEY ...]` | Spawn one Worktrunk worktree + selected-agent session per ticket via the packaged `start-tickets` CLI (Claude Code by default, `--agent cursor-agent` for Cursor; macOS Terminal/iTerm, Windows Terminal/PowerShell, or Linux tmux) |
-| `/teach-bridge` | Update a Bridge API configuration field via natural-language instructions |
-| `/update-ticket PROJ-123` | Fetch clarifying questions and critique, then rewrite the ticket description and push to Jira |
-| `/write-ticket` | Draft a new Jira ticket from a prompt and upload it |
 
 > Commands are designed for Claude Code. Other editors may support slash commands differently — check your editor's documentation for how to invoke prompt files.
 
-## Smoke testing
-
-The package ships a canonical, **opt-in** in-host smoke-test runbook at
-`smoke-test/SMOKE-TEST.md`. An AI agent running inside your host (Claude Code,
-Cursor, Codex, Windsurf, or VS Code/Copilot) executes it to verify that the MCP
-server actually works end-to-end *inside that host* — it calls the real tools and
-records a PASS/FAIL verdict for each one in a markdown report.
-
-- `smoke-test/SMOKE-TEST.md` **ships with the npm package** and is the
-  **canonical** source of truth for the smoke test.
-- The smoke test **adds no MCP tool** and **does not change the registered
-  tool surface** (the server still registers its existing 51 tools).
-- It is **opt-in**: default `--init` **does not scaffold `/smoke-test-mcp`**, so
-  consumer command palettes are not polluted.
-
-### Running it
-
-You have two options:
-
-1. **Copy the opt-in command manually.** Copy the packaged command stub into your
-   host's command directory, then invoke `/smoke-test-mcp`:
-
-   ```bash
-   # Claude Code
-   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .claude/commands/smoke-test-mcp.md
-   # Cursor
-   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .cursor/commands/smoke-test-mcp.md
-   ```
-
-2. **Open the runbook directly.** Alternatively, open
-   `smoke-test/SMOKE-TEST.md` and ask the host agent to execute it.
-
-Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`.
-
-## Available Tools
-
-MCP tools are the low-level primitives Bridge exposes to your AI assistant. You don't call them directly — ask your AI assistant to perform the task you need, or compose them into a custom pipeline.
-
-### Connectivity
+### Extra Capabilities
 
-| Tool | Description |
-|---|---|
-| `ping` | Verify connectivity and confirm your API key is valid |
+Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invoked automatically by the commands above, rarely requested by name:
 
-### Jira Tickets
+- **Ship a PR end-to-end:** commit & push, open a pull request, transition the Jira status, and discover/poll CI checks (powers `commit-ticket`, `create-pr`, `check-ci`, `implement-ticket`).
+- **Architecture plan** for a ticket (design-level guidance, separate from the implementation plan).
+- **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).
+- **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, brainstorms, research, architecture) without regenerating it.
+- **Tiered-section execution telemetry** recording (internal measurement).
 
-| Tool | Description |
-|---|---|
-| `get_tickets` | Search and list Jira tickets by query, status, or date |
-| `get_ticket` | Get full details for a single ticket |
-| `create_ticket` | Create a new Jira ticket |
-| `add_comment` | Post a comment on a ticket |
-| `update_ticket_description` | Replace a ticket's description |
-| `upload_attachment` | Upload a file as a ticket attachment |
+## CLI Subcommands
 
-### AI Generation
+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.
 
-Async tools follow a request/get pattern: call the `request_*` tool to kick off generation, then call the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+### `start-tickets`
 
-| Tool | Description |
-|---|---|
-| `request_plan_generation` | Request an AI-generated implementation plan |
-| `get_plan` | Retrieve a generated implementation plan |
-| `request_architecture` | Request an AI-generated architecture plan |
-| `get_architecture` | Retrieve a generated architecture plan |
-| `request_clarifying_questions` | Request clarifying questions for a ticket |
-| `get_clarifying_questions` | Retrieve generated clarifying questions |
-| `request_ticket_critique` | Request a ticket quality critique |
-| `get_ticket_critique` | Retrieve a generated ticket critique |
-| `request_reimplement_context` | Request context assembly for a follow-up implementation |
-| `get_reimplement_context` | Retrieve assembled reimplementation context |
-| `request_deep_research` | Submit a deep research query |
-| `get_deep_research` | Retrieve deep research results |
-
-### Ticket Lifecycle
-
-| Tool | Description |
-|---|---|
-| `track_ticket` | Register a ticket for lifecycle tracking |
-| `update_ticket_state` | Update workflow timestamps for a tracked ticket |
-| `get_ticket_state` | Get workflow state and timestamps for a tracked ticket |
+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`.
 
-### Jira Status
-
-| Tool | Description |
-|---|---|
-| `get_jira_transitions` | List available status transitions for a ticket |
-| `update_jira_status` | Transition a ticket to a new Jira status |
-| `resolve_target_status` | Resolve the post-PR target status for a project |
+```
+npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
+```
 
-### Configuration
+| Flag | Default | Meaning |
+|---|---|---|
+| `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
+| `--terminal terminal\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |
+| `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |
+| `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |
+| `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |
+| `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever `--base-branch` resolves to. |
+| `--max-parallel N` | `3` | Max worktrees created concurrently |
+| `-h`, `--help` | — | Show usage |
 
-| Tool | Description |
-|---|---|
-| `get_project_standards` | Retrieve configured coding standards and architecture guidelines |
-| `list_config_fields` | List all available configuration fields |
-| `get_config_field` | Read the current value of a configuration field |
-| `update_config_field` | Update a configuration field |
-| `get_my_role` | Check the role and permissions for the current API key |
+Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent's `'/implement-ticket <KEY>'` — `claude '/implement-ticket <KEY>'` by default, or `cursor-agent '/implement-ticket <KEY>'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:
 
-### Repository & CI
+```
+npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
+```
 
-| Tool | Description |
-|---|---|
-| `parse_repository` | Queue a background job to parse and index the repository |
-| `get_parse_status` | Check whether a repository parse is in progress |
-| `regenerate_directory_map` | Regenerate the repository directory map |
-| `create_pull_request` | Create a pull request on GitHub or Bitbucket |
-| `resolve_ci_checks` | Discover and classify CI checks for a commit |
-| `poll_ci_checks` | Poll the current status of CI checks |
+**Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.
 
-### Pipelines
+- **macOS** — opens a Terminal.app or iTerm tab via `osascript`.
+- **Windows** — creates worktrees with **`git-wt`** (Worktrunk's winget alias) and opens a tab via **Windows Terminal (`wt.exe new-tab`)**, falling back to **`Start-Process powershell.exe`** when Windows Terminal is absent. Requires **Git for Windows / Git Bash** (Worktrunk runs its `pre-start` / `post-start` hooks via Git Bash). The Worktrunk binary (`git-wt`) and the tab launcher (`wt.exe`) are resolved independently and never conflated.
+- **Linux** — creates one detached **tmux** session per ticket (pane kept open after the agent exits); attach with `tmux attach -t <session>`. A missing `tmux` produces a clear, actionable error.
 
-| Tool | Description |
-|---|---|
-| `get_docs_dir` | Return the configured local docs directory path |
-| `list_pipelines` | List available pipeline recipes with names and descriptions |
-| `get_pipeline_recipe` | Retrieve a fully resolved pipeline recipe with variables substituted |
-| `run_pipeline` | Execute a pipeline end-to-end; pauses on `agent_task` steps with a `needs_agent_task` envelope |
-| `resume_pipeline` | Resume a paused run with the agent's result string |
-| `list_pipeline_runs` | List recent pipeline runs (metadata only) — useful for recovering a `pipeline_run_id` after compaction |
+Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for Windows / Git Bash, Windows Terminal or PowerShell; Linux `wt`, `git`, `tmux`. Set `BAPI_WORKTRUNK_BIN` to override the Worktrunk executable name/path for nonstandard installs (`doctor` honors it too). The read-only `doctor` subcommand (below) additionally surfaces a missing `uv` — Worktrunk's `pre-start` hook runs `uv`, but live preflight does not check it — and the selected agent's command; run `doctor --agent cursor-agent` to also check `cursor-agent` (it prints `cursor-agent login` as an informational auth reminder).
 
-### Pipeline Response Envelope
+### `doctor`
 
-`run_pipeline`, `resume_pipeline`, and `list_pipeline_runs` share a unified envelope keyed on `status`:
+The package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:
 
-- `completed` — terminal success; `results` holds per-step output.
-- `needs_agent_task` — the orchestrator paused. Read `instruction`, perform the task, then call `resume_pipeline` with `pipeline_run_id` and a string `agent_result`.
-- `failed` — terminal failure. `error_code` is one of `VALIDATION`, `NOT_FOUND`, `EXPIRED`, `REPO_MISMATCH`, `TOOL_ERROR`.
+```
+npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
+```
 
-Paused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition. List output is metadata-only — it never includes resolved recipes, params, instructions, results, or agent outputs.
+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.
 
 ## Custom Pipelines
 
@@ -418,6 +431,40 @@ See `.bridge/pipelines/README.md` for the full schema reference.
 
 If a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).
 
+## Smoke testing
+
+The package ships a canonical, **opt-in** in-host smoke-test runbook at
+`smoke-test/SMOKE-TEST.md`. An AI agent running inside your host (Claude Code,
+Cursor, Codex, Windsurf, or VS Code/Copilot) executes it to verify that the MCP
+server actually works end-to-end *inside that host* — it calls the real tools and
+records a PASS/FAIL verdict for each one in a markdown report.
+
+- `smoke-test/SMOKE-TEST.md` **ships with the npm package** and is the
+  **canonical** source of truth for the smoke test.
+- The smoke test **adds no MCP tool** and **does not change the registered
+  tool surface** (the server still registers its existing 55 tools).
+- It is **opt-in**: default `--init` **does not scaffold `/smoke-test-mcp`**, so
+  consumer command palettes are not polluted.
+
+### Running it
+
+You have two options:
+
+1. **Copy the opt-in command manually.** Copy the packaged command stub into your
+   host's command directory, then invoke `/smoke-test-mcp`:
+
+   ```bash
+   # Claude Code
+   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .claude/commands/smoke-test-mcp.md
+   # Cursor
+   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .cursor/commands/smoke-test-mcp.md
+   ```
+
+2. **Open the runbook directly.** Alternatively, open
+   `smoke-test/SMOKE-TEST.md` and ask the host agent to execute it.
+
+Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`.
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |
@@ -430,3 +477,92 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `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 |
 | `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |
+
+## Worktree credentials and the `mcp-invoke` shim
+
+When `start-tickets` creates a git worktree, it provisions a Bridge API MCP
+registration into that worktree so Claude Code (`.mcp.json`) and Cursor
+(`.cursor/mcp.json`) can reach the server immediately. These registrations are
+**secret-free**: they contain no `env` block and no API key. Instead they point
+at an internal subcommand of the published single CLI bin, `mcp-invoke`:
+
+```bash
+npx -y @bridge_gpt/mcp-server@<VERSION> mcp-invoke --target bapi --project-root <ABS_WORKTREE_PATH>
+```
+
+`mcp-invoke` is not a separate binary — it is a positional subcommand of
+`bridge-api-mcp-server`. It resolves the repo identity from the absolute
+`--project-root` (the committed `.bridge/config` manifest, falling back to the
+git common dir), resolves credentials from the home-directory credential store,
+and then spawns the real MCP server with that environment.
+
+### Credential store
+
+Credentials live outside the repository, keyed by `bapi:<repo_name>`:
+
+```json
+{
+  "bapi:<repo_name>": {
+    "BAPI_API_KEY": "..."
+  }
+}
+```
+
+Resolution order:
+
+1. `BAPI_API_KEY` in the parent environment (overrides the file entirely).
+2. `$XDG_CONFIG_HOME/bridge/credentials.json`, else `~/.config/bridge/credentials.json`.
+3. `~/.bridge/credentials.json` (only when the primary path is absent).
+
+On POSIX systems, lock the file down so only you can read it:
+
+```bash
+chmod 600 ~/.config/bridge/credentials.json
+```
+
+`mcp-invoke` warns (but continues) if the file is group/world-readable, and it
+never creates or initializes the credential file for you.
+
+## Reference
+
+The full surface, for when you need the complete enumeration. Day-to-day, use [Usage Documentation](#usage-documentation) instead — you don't call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.
+
+### MCP tools
+
+The server registers **55 tools**. 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`
+- **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
+- **Attachments** — `list_attachments`, `upload_attachment`, `download_attachment`
+- **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`
+- **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`
+- **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`
+- **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`
+- **Config & telemetry** — `get_project_standards`, `list_config_fields`, `get_config_field`, `update_config_field`, `record_tiered_section_metric`
+
+### Bundled pipelines
+
+Pipelines are declarative, multi-step workflows your AI agent executes step-by-step — each a JSON recipe chaining MCP tool calls and free-form agent tasks, with variable substitution, per-step error handling, and optional approval gates. You can also write your own (see [Custom Pipelines](#custom-pipelines)).
+
+| Pipeline | Description | Invoke with |
+|---|---|---|
+| `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |
+| `review-ticket` | Two-round ticket quality review: clarifying questions and critique from multiple providers | `/review-ticket PROJ-123` |
+| `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |
+| `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |
+| `full-automation` | Chain: idea → ticket(s) → review each → spawn worktrees to implement | `/full-automation "<idea>"` |
+| `pr-ticket` | Commit changes and open a pull request | `/create-pr PROJ-123` |
+| `check-ci-ticket` | Commit, open a PR, then monitor CI checks until they pass or fail | `/check-ci PROJ-123` |
+| `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |
+
+### Pipeline response envelope
+
+`run_pipeline`, `resume_pipeline`, and `list_pipeline_runs` share a unified envelope keyed on `status`:
+
+- `completed` — terminal success; `results` holds per-step output.
+- `needs_agent_task` — the orchestrator paused. Read `instruction`, perform the task, then call `resume_pipeline` with `pipeline_run_id` and a string `agent_result`.
+- `failed` — terminal failure. `error_code` is one of `VALIDATION`, `NOT_FOUND`, `EXPIRED`, `REPO_MISMATCH`, `TOOL_ERROR`.
+
+Paused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition. List output is metadata-only — it never includes resolved recipes, params, instructions, results, or agent outputs.