SoundBlaster · SoundBlaster · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-03-01 (P2-T6 archived)
+**Last Updated:** 2026-03-01 (P1-T8 archived)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P1-T8 | [P1-T8_Update_config_examples_for_broker_setup_first/](P1-T8_Update_config_examples_for_broker_setup_first/) | 2026-03-01 | PASS |
 | P2-T6 | [P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/](P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/) | 2026-03-01 | PASS |
 | P1-T7 | [P1-T7_Hide_README_version_badge_maintenance_note/](P1-T7_Hide_README_version_badge_maintenance_note/) | 2026-03-01 | PASS |
 | P1-T4 | [P1-T4_Update_docs_broker_robustness/](P1-T4_Update_docs_broker_robustness/) | 2026-03-01 | PASS |
@@ -180,6 +181,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_p1_t8_config_broker_setup_first.md](_Historical/REVIEW_p1_t8_config_broker_setup_first.md) | Review report for P1-T8 |
 | [REVIEW_P2-T5_webui_mismatch_warning.md](_Historical/REVIEW_P2-T5_webui_mismatch_warning.md) | Review report for P2-T5 |
 | [REVIEW_P2-T4_broker_unavailable_error.md](_Historical/REVIEW_P2-T4_broker_unavailable_error.md) | Review report for P2-T4 |
 | [REVIEW_P2-T3_spawn_lock.md](_Historical/REVIEW_P2-T3_spawn_lock.md) | Review report for P2-T3 |
@@ -305,6 +307,8 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-03-01 | P1-T8 | Archived REVIEW_p1_t8_config_broker_setup_first report |
+| 2026-03-01 | P1-T8 | Archived Update /config examples for broker setup first (PASS) |
 | 2026-03-01 | P2-T6 | Archived REVIEW_p2_t6_remove_legacy_broker_flags report |
 | 2026-03-01 | P2-T6 | Archived Remove legacy --broker-connect and --broker-spawn flags (PASS) |
 | 2026-03-01 | P1-T7 | Archived REVIEW_P1-T7_readme_badge_note report |

diff --git a/...s_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md b/...s_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md
@@ -0,0 +1,65 @@
+# PRD: P1-T8 — Update /config examples for broker setup first
+
+## Overview
+
+`README.md` already presents broker setup first, but several standalone templates in
+`config/` still lead with non-broker examples. This task aligns those templates
+with current guidance by presenting broker-mode setup first for supported MCP
+clients.
+
+## Problem Statement
+
+Users often copy from `config/` files directly. When non-broker examples appear
+first, the docs and templates send mixed signals about the preferred setup path.
+With `--broker` now the primary mode, templates should reflect that ordering.
+
+## Scope
+
+In scope:
+- Reorder options in `config/cursor-mcp.json` and `config/zed-agent.json` so a
+  broker-mode configuration is listed first.
+- Update `config/claude-code.txt` and `config/codex-cli.txt` so broker setup
+  commands are shown before non-broker alternatives.
+- Keep command syntax compatible with current `--broker` guidance.
+
+Out of scope:
+- Runtime behavior changes in Python source code.
+- Changes to broker-specific template files that already lead with broker mode.
+
+## Deliverables
+
+| File(s) | Change |
+|---|---|
+| `config/cursor-mcp.json` | Broker option block moved to first position and labeled as recommended |
+| `config/zed-agent.json` | Broker option block moved to first position and labeled as recommended |
+| `config/claude-code.txt` | Broker command block added as first option |
+| `config/codex-cli.txt` | Broker command block added as first option |
+
+## Acceptance Criteria
+
+- [ ] `config/cursor-mcp.json` presents a broker-mode option first in `xcode-tools` options.
+- [ ] `config/zed-agent.json` presents a broker-mode option first in `xcode-tools` options.
+- [ ] `config/claude-code.txt` lists a broker setup command before non-broker options.
+- [ ] `config/codex-cli.txt` lists a broker setup command before non-broker options.
+- [ ] Full quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (>= 90%).
+
+## Validation Plan
+
+1. Inspect option ordering in each updated config template.
+2. Run `pytest`.
+3. Run `ruff check src/`.
+4. Run `mypy src/`.
+5. Run `pytest --cov` and confirm coverage remains >= 90%.
+
+## Dependencies
+
+- P2-T6
+
+## Risks
+
+Low. This is a documentation/template ordering change and does not alter runtime
+logic.
+
+---
+**Archived:** 2026-03-01
+**Verdict:** PASS
diff --git a/.../P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md b/.../P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md
@@ -0,0 +1,54 @@
+# Validation Report: P1-T8 — Update /config examples for broker setup first
+
+**Date:** 2026-03-01  
+**Verdict:** PASS
+
+## Summary
+
+Updated client configuration templates under `config/` so broker-mode setup appears first for Cursor, Zed, Claude Code, and Codex CLI examples.
+
+## Delivered Changes
+
+- `config/cursor-mcp.json`
+  - Added broker-first option blocks (`_option1_uvx_broker`, `_option1b_uvx_broker_web_ui`).
+  - Shifted non-broker options to `_option2*` and below.
+- `config/zed-agent.json`
+  - Added broker-first option blocks (`_option1_uvx_broker`, `_option1b_uvx_broker_web_ui`).
+  - Shifted non-broker options to `_option2*` and below.
+- `config/claude-code.txt`
+  - Added broker-mode command as `OPTION 1` and broker + Web UI as `OPTION 1B`.
+  - Moved non-broker alternatives to `OPTION 2` and below.
+- `config/codex-cli.txt`
+  - Added broker-mode command as `OPTION 1` and broker + Web UI as `OPTION 1B`.
+  - Moved non-broker alternatives to `OPTION 2` and below.
+
+## Acceptance Criteria Check
+
+- [x] `config/cursor-mcp.json` presents a broker-mode option first in `xcode-tools` options.
+- [x] `config/zed-agent.json` presents a broker-mode option first in `xcode-tools` options.
+- [x] `config/claude-code.txt` lists a broker setup command before non-broker options.
+- [x] `config/codex-cli.txt` lists a broker setup command before non-broker options.
+- [x] Full quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (>= 90%).
+
+## Quality Gates
+
+1. `pytest`
+- Result: PASS
+- Evidence: `735 passed, 5 skipped`
+
+2. `ruff check src/`
+- Result: PASS
+- Evidence: `All checks passed!`
+
+3. `mypy src/`
+- Result: PASS
+- Evidence: `Success: no issues found in 18 source files`
+
+4. `pytest --cov`
+- Result: PASS
+- Evidence: `Required test coverage of 90.0% reached. Total coverage: 91.26%`
+
+## Notes
+
+- Initial `pytest` run failed due to environment import setup (`ModuleNotFoundError: mcpbridge_wrapper`).
+- Resolved by installing the package in editable mode with `python3 -m pip install -e .`, then re-running quality gates successfully.
diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p1_t8_config_broker_setup_first.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t8_config_broker_setup_first.md
@@ -0,0 +1,31 @@
+## REVIEW REPORT — P1-T8 Config Broker Setup First
+
+**Scope:** `origin/main..HEAD`  
+**Files:** 9
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- Config templates now align with broker-first guidance already reflected in README/docs, reducing mismatch between direct template copy paths and documented recommendations.
+- JSON template option ordering is explicit and keeps non-broker alternatives available for users that still need per-session mode.
+
+### Tests
+- Quality gates were run and passed:
+  - `pytest` → `735 passed, 5 skipped`
+  - `ruff check src/` → pass
+  - `mypy src/` → pass
+  - `pytest --cov` → `91.26%` (>= 90%)
+
+### Next Steps
+- No actionable follow-up items from this review.
+- FOLLOW-UP step is skipped per FLOW rules.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -1,9 +1,10 @@
 # No Active Task
 
-**Status:** Idle — P2-T6 archived. Select the next task from `SPECS/Workplan.md`.
+**Status:** Idle — P1-T8 archived. Select the next task from `SPECS/Workplan.md`.
 
 ## Recently Archived
 
+- **P1-T8** — Update /config examples for broker setup first (2026-03-01, PASS)
 - **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS)
 - **P1-T7** — Hide README version badge maintenance note (2026-03-01, PASS)
 - **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS)

diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -112,6 +112,20 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [x] `README.md` no longer contains the exact string `Version badge maintenance: run make badge-version (or make badge-version-check in CI).`
   - [x] Version badge remains visible and functional after removing the maintenance note
 
+#### ✅ P1-T8: Update /config examples for broker setup first
+- **Status:** ✅ Completed (2026-03-01)
+- **Description:** Update MCP client templates under `config/` so broker-mode setup is presented first and consistently framed as the recommended path.
+- **Priority:** P1
+- **Dependencies:** P2-T6
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - `config/cursor-mcp.json` and `config/zed-agent.json` reordered to show broker-mode options before non-broker alternatives
+  - `config/claude-code.txt` and `config/codex-cli.txt` updated so broker commands appear before non-broker commands
+- **Acceptance Criteria:**
+  - [x] Cursor and Zed config templates present a broker-mode option first
+  - [x] Claude Code and Codex CLI config templates present a broker command first
+  - [x] Broker-first guidance is consistent with existing `*-broker` templates and `--broker` usage
+
 ### Phase 2: Broker Robustness
 
 #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag

diff --git a/config/claude-code.txt b/config/claude-code.txt
@@ -1,14 +1,25 @@
 # Claude Code MCP Configuration for xcodemcpwrapper
 #
-# OPTION 1: Using uvx (Recommended - Easiest)
-# -------------------------------------------
-# No manual installation needed. uvx automatically downloads and runs the wrapper.
+# OPTION 1: Using uvx with broker mode (Recommended)
+# ---------------------------------------------------
+# Shares a single broker daemon across MCP clients and auto-starts it if needed.
+#
+#   claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
+#
+# OPTION 1B: Using uvx with broker mode + Web UI (Optional)
+# ----------------------------------------------------------
+# Enable broker mode and host the dashboard on port 8080:
+#
+#   claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-port 8080
+#
+# OPTION 2: Using uvx (Non-broker Alternative)
+# ---------------------------------------------
+# Starts an independent wrapper process per client session.
 #
 #   claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 #
-# OPTION 1B: Using uvx with Web UI (Optional)
-# -------------------------------------------
-# Enable the Web UI dashboard on port 8080:
+# OPTION 2B: Using uvx with Web UI (Non-broker, Optional)
+# --------------------------------------------------------
 #
 #   claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 #
@@ -17,26 +28,26 @@
 #   or: brew install uv
 #
 #
-# OPTION 2: Manual Installation
+# OPTION 3: Manual Installation
 # -----------------------------
 # If you installed manually to ~/bin/xcodemcpwrapper:
 #
 #   claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper
 #
-# OPTION 2B: Manual Installation with Web UI (Optional)
+# OPTION 3B: Manual Installation with Web UI (Optional)
 # -----------------------------------------------------
 # Enable the Web UI dashboard on port 8080:
 #
 #   claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
 #
 #
-# OPTION 3: Local Development (from cloned repo with venv)
+# OPTION 4: Local Development (from cloned repo with venv)
 # --------------------------------------------------------
 # If you cloned the repo and installed via `make install` in a virtual environment:
 #
 #   claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
 #
-# OPTION 3B: Local Development with Web UI (Optional)
+# OPTION 4B: Local Development with Web UI (Optional)
 # ----------------------------------------------------
 # Enable the Web UI dashboard on port 8080:
 #
@@ -48,5 +59,5 @@
 # Verification:
 #   claude mcp list
 #
-# Note: Replace USERNAME with your actual username for option 2.
-# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 3.
+# Note: Replace USERNAME with your actual username for option 3.
+# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 4.
diff --git a/config/codex-cli.txt b/config/codex-cli.txt
@@ -1,14 +1,25 @@
 # Codex CLI MCP Configuration for xcodemcpwrapper
 #
-# OPTION 1: Using uvx (Recommended - Easiest)
-# -------------------------------------------
-# No manual installation needed. uvx automatically downloads and runs the wrapper.
+# OPTION 1: Using uvx with broker mode (Recommended)
+# ---------------------------------------------------
+# Shares a single broker daemon across MCP clients and auto-starts it if needed.
+#
+#   codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
+#
+# OPTION 1B: Using uvx with broker mode + Web UI (Optional)
+# ----------------------------------------------------------
+# Enable broker mode and host the dashboard on port 8080:
+#
+#   codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-port 8080
+#
+# OPTION 2: Using uvx (Non-broker Alternative)
+# ---------------------------------------------
+# Starts an independent wrapper process per client session.
 #
 #   codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 #
-# OPTION 1B: Using uvx with Web UI (Optional)
-# -------------------------------------------
-# Enable the Web UI dashboard on port 8080:
+# OPTION 2B: Using uvx with Web UI (Non-broker, Optional)
+# --------------------------------------------------------
 #
 #   codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 #
@@ -17,26 +28,26 @@
 #   or: brew install uv
 #
 #
-# OPTION 2: Manual Installation
+# OPTION 3: Manual Installation
 # -----------------------------
 # If you installed manually to ~/bin/xcodemcpwrapper:
 #
 #   codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper
 #
-# OPTION 2B: Manual Installation with Web UI (Optional)
+# OPTION 3B: Manual Installation with Web UI (Optional)
 # -----------------------------------------------------
 # Enable the Web UI dashboard on port 8080:
 #
 #   codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
 #
 #
-# OPTION 3: Local Development (from cloned repo with venv)
+# OPTION 4: Local Development (from cloned repo with venv)
 # --------------------------------------------------------
 # If you cloned the repo and installed via `make install` in a virtual environment:
 #
 #   codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
 #
-# OPTION 3B: Local Development with Web UI (Optional)
+# OPTION 4B: Local Development with Web UI (Optional)
 # ----------------------------------------------------
 # Enable the Web UI dashboard on port 8080:
 #
@@ -48,5 +59,5 @@
 # Verification:
 #   codex mcp list
 #
-# Note: Replace USERNAME with your actual username for option 2.
-# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 3.
+# Note: Replace USERNAME with your actual username for option 3.
+# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 4.