SoundBlaster · SoundBlaster · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/README.md b/README.md
@@ -101,6 +101,7 @@ upstream bridge session.
 
 - Use `--broker-connect` to attach to an already-running broker.
 - Use `--broker-spawn` to auto-start the broker if needed.
+- Add `--web-ui` (plus optional `--web-ui-config`) when you want the spawned or daemon host to own one shared dashboard endpoint.
 
 Quick migration examples:
 
@@ -119,14 +120,11 @@ rollback to direct mode, see [Broker Mode Guide](docs/broker-mode.md).
 
 When you run multiple MCP client processes at the same time:
 
-- **For shared MCP upstream sessions:** run one broker daemon host and configure each client with `--broker-connect`.
-- **For Web UI dashboard hosting:** only one process can bind a given `host:port` (for example `127.0.0.1:8080`).
-- If multiple direct-mode processes start with the same `--web-ui-port`, one process serves the dashboard and other processes continue MCP without dashboard hosting.
-- This ownership rule is process-level and independent from Xcode window state.
-
-Current limitation:
-- Broker CLI modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the Web UI dashboard process.
-- If you need dashboard diagnostics, run a separate direct-mode/Web-UI process (for example `--web-ui-only`) in parallel.
+- **Unified single-config pattern:** configure each client with `--broker-spawn --web-ui --web-ui-config <shared-path>`.
+- **Runtime expectation:** the first client that must spawn the broker starts the broker host and dashboard; later clients reuse the same broker and dashboard endpoint.
+- **Ownership rule:** only one process can bind a given Web UI `host:port` (for example `127.0.0.1:8080`).
+- **Connect-only behavior:** `--broker-connect` clients never start the dashboard by themselves.
+- **Fallback behavior:** if dashboard bind fails (port already in use), broker MCP transport continues and only dashboard startup is skipped.
 
 See [Web UI Setup Guide](docs/webui-setup.md#multi-agent-web-ui-ownership-model) and [Troubleshooting](docs/troubleshooting.md#mcp-tools-are-green-but-dashboard-is-unreachable).
 

diff --git a/...cument_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md b/...cument_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md
@@ -0,0 +1,78 @@
+# PRD: FU-P13-T18 — Document unified single-config setup for broker + Web UI multi-agent workflows
+
+## 1. Objective
+
+Document one repeatable setup where multiple AI clients share the same broker and dashboard endpoint without per-client config drift. The goal is to let users keep a single MCP server definition in each client (Cursor, Zed, Claude Code, Codex) that points to a broker-aware command path, while only one broker host process owns `--web-ui` listener startup.
+
+This task builds directly on FU-P13-T17 behavior. Documentation must describe:
+- Which process starts and owns the dashboard listener.
+- How `--broker-spawn` and `--broker-connect` clients should be configured when using one shared broker host.
+- What users should expect when broker MCP transport stays healthy but dashboard endpoint is unavailable.
+- How DocC mirrors stay aligned with Markdown docs.
+
+## 2. Success Criteria and Acceptance Tests
+
+### Success Criteria
+- `README.md` contains a clear “single-config, shared broker host” quick path and links to detailed docs.
+- `docs/broker-mode.md` includes unified config examples for Cursor, Zed, Claude Code, and Codex with explicit host/client roles.
+- `docs/webui-setup.md` defines dashboard ownership rules and fallback behavior when the chosen listener is unavailable.
+- `docs/troubleshooting.md` adds broker-hosted Web UI diagnostics that distinguish broker health from dashboard reachability.
+- Mapped DocC documentation is updated to match user-facing guidance.
+
+### Acceptance Tests
+- Verify docs include one end-to-end flow where one process runs broker + Web UI and all other agents use broker connection mode without `--web-ui`.
+- Verify docs include explicit expectations for shared dashboard endpoint reuse and port conflict outcomes.
+- Verify troubleshooting steps include concrete commands (`lsof`, broker host start/restart checks, endpoint verification).
+
+## 3. Test-First Plan
+
+1. Review current behavior coverage to ensure docs claims are already validated by tests from FU-P13-T17 and prior broker-mode work.
+2. Add/adjust tests only if a new behavior statement lacks evidence in existing test suite.
+3. Run required quality gates after documentation updates:
+   - `pytest`
+   - `ruff check src/`
+   - `mypy src/`
+   - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing`
+
+## 4. Execution Plan (Hierarchical TODO)
+
+### Phase A — Behavior and config alignment
+- Inputs: runtime behavior from `src/mcpbridge_wrapper/__main__.py`, broker and Web UI docs.
+- Outputs: authoritative wording for broker host ownership and multi-agent shared endpoint semantics.
+- Verification: no docs claim behavior that code does not implement.
+
+### Phase B — Documentation and examples
+- Inputs: `README.md`, `docs/broker-mode.md`, `docs/webui-setup.md`, `docs/troubleshooting.md`.
+- Outputs: unified single-config examples, ownership matrix, fallback and diagnostics guidance.
+- Verification: examples are internally consistent and use current CLI flags.
+
+### Phase C — DocC synchronization
+- Inputs: mapped files under `Sources/XcodeMCPWrapper/Documentation.docc/`.
+- Outputs: mirrored guidance aligned with Markdown docs.
+- Verification: key sections and commands match without contradictions.
+
+### Phase D — Validation report
+- Inputs: edited docs and gate outputs.
+- Outputs: `SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md` with verdict and acceptance criteria checks.
+- Verification: report records all required gates and result status.
+
+## 5. Decision Points and Constraints
+
+- Preserve compatibility with existing single-agent quick start instructions.
+- Do not imply automatic dashboard failover or multi-owner listener support.
+- Keep commands copy/paste-ready and avoid introducing unsupported CLI flags.
+- Review subject for REPORT step: `fu_p13_t18_unified_config_docs`.
+
+## 6. Notes (Files likely touched)
+
+- `README.md`
+- `docs/broker-mode.md`
+- `docs/webui-setup.md`
+- `docs/troubleshooting.md`
+- `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md`
+- `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md`
+- `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`
+
+---
+**Archived:** 2026-02-28
+**Verdict:** PASS
diff --git a/...setup_for_broker_+_Web_UI_multi-agent_workflows/FU-P13-T18_Validation_Report.md b/...setup_for_broker_+_Web_UI_multi-agent_workflows/FU-P13-T18_Validation_Report.md
@@ -0,0 +1,41 @@
+# Validation Report: FU-P13-T18 — Document unified single-config setup for broker + Web UI multi-agent workflows
+
+**Date:** 2026-02-28
+**Task ID:** FU-P13-T18
+**Verdict:** PASS
+
+## Scope Implemented
+
+- Updated `README.md` multi-agent guidance to document unified broker + dashboard single-config behavior with `--broker-spawn --web-ui`.
+- Updated `docs/broker-mode.md` with:
+  - Unified single-config examples for Cursor, Zed, Claude Code, and Codex CLI.
+  - Runtime expectations for broker-hosted dashboard ownership and fallback behavior.
+  - Updated operational and migration guidance for broker-hosted Web UI flows.
+- Updated `docs/webui-setup.md` multi-agent ownership guidance to reflect broker-hosted dashboard behavior.
+- Updated `docs/troubleshooting.md` with broker-hosted dashboard diagnostics and decision paths for unified config vs dedicated host.
+- Synced mapped DocC pages:
+  - `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`
+
+## Quality Gates
+
+- `pytest` → FAIL in this environment (`ModuleNotFoundError: mcpbridge_wrapper` during collection; project uses `PYTHONPATH=src` for local gates)
+- `PYTHONPATH=src pytest` → PASS (`692 passed, 5 skipped`)
+- `ruff check src/` → PASS (`All checks passed!`)
+- `mypy src/` → PASS (`Success: no issues found in 18 source files`)
+- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` → PASS
+  - Total coverage: **91.72%** (required: >= 90%)
+
+## Acceptance Criteria Check
+
+- [x] Docs include one-config examples for Zed/Cursor/Claude/Codex with broker + dashboard expectations.
+- [x] Docs clearly define dashboard ownership and fallback behavior.
+- [x] Troubleshooting includes broker-hosted Web UI diagnostics.
+
+## Notes
+
+- Broker dashboard startup semantics documented here align with implemented runtime behavior from FU-P13-T17:
+  - Broker host (`--broker-daemon --web-ui`) can own dashboard startup.
+  - Auto-spawn path (`--broker-spawn --web-ui`) propagates Web UI args to spawned host.
+  - Connect-only clients (`--broker-connect`) do not host dashboards.
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-02-28 (FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry)
+**Last Updated:** 2026-02-28 (FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| FU-P13-T18 | [FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/](FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/) | 2026-02-28 | PASS |
 | FU-P13-T17 | [FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/](FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/) | 2026-02-28 | PASS |
 | FU-P13-T16 | [FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/](FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/) | 2026-02-28 | PASS |
 | FU-P11-T2-4 | [FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/](FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/) | 2026-02-28 | PASS |
@@ -164,6 +165,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_fu_p13_t18_unified_config_docs.md](_Historical/REVIEW_fu_p13_t18_unified_config_docs.md) | Review report for FU-P13-T18 |
 | [REVIEW_fu_p13_t17_broker_hosted_webui.md](_Historical/REVIEW_fu_p13_t17_broker_hosted_webui.md) | Review report for FU-P13-T17 |
 | [REVIEW_fu_p13_t16_multi_agent_mcp_docs.md](_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md) | Review report for FU-P13-T16 |
 | [REVIEW_P1-T1_project_structure.md](_Historical/REVIEW_P1-T1_project_structure.md) | Review report for P1-T1 |
@@ -277,6 +279,8 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-02-28 | FU-P13-T18 | Archived REVIEW_fu_p13_t18_unified_config_docs report |
+| 2026-02-28 | FU-P13-T18 | Archived Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows (PASS) |
 | 2026-02-28 | FU-P13-T17 | Archived REVIEW_fu_p13_t17_broker_hosted_webui report |
 | 2026-02-28 | FU-P13-T17 | Archived Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry (PASS) |
 | 2026-02-28 | FU-P13-T16 | Archived REVIEW_fu_p13_t16_multi_agent_mcp_docs report |

diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t18_unified_config_docs.md b/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t18_unified_config_docs.md
@@ -0,0 +1,32 @@
+## REVIEW REPORT — FU-P13-T18 Unified Config Docs
+
+**Scope:** origin/main..HEAD
+**Files:** 12
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None actionable.
+
+### Architectural Notes
+- Documentation now aligns with broker-hosted dashboard behavior delivered in FU-P13-T17 (`--broker-daemon --web-ui` and `--broker-spawn --web-ui` host-path semantics).
+- Multi-agent guidance is internally consistent across README, broker/web UI/troubleshooting docs, and mapped DocC pages.
+- Archive bookkeeping (`Workplan`, `next.md`, task artifacts, archive index/log) follows FLOW conventions and remains coherent.
+
+### Tests
+- `pytest` (without `PYTHONPATH`) fails in this repo environment due import resolution; gate path uses `PYTHONPATH=src`.
+- `PYTHONPATH=src pytest` passed (`692 passed, 5 skipped`).
+- `ruff check src/` passed.
+- `mypy src/` passed.
+- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` passed with 91.72% coverage (>=90%).
+
+### Next Steps
+- No follow-up tasks required from this review.
+- FOLLOW-UP step can be skipped per FLOW because there are no actionable findings.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -2,11 +2,10 @@
 
 ## Recently Archived
 
+- **FU-P13-T18** — Document unified single-config setup for broker + Web UI multi-agent workflows (2026-02-28, PASS)
 - **FU-P13-T17** — Enable broker-hosted Web UI with shared multi-client telemetry (2026-02-28, PASS)
 - **FU-P13-T16** — Document multi-agent MCP usage and single Web UI host (2026-02-28, PASS)
-- **FU-P11-T2-4** — Add one-command Web UI restart workflow (2026-02-28, PASS)
 
 ## Suggested Next Tasks
 
-- **FU-P13-T18** — Document unified single-config setup for broker + Web UI multi-agent workflows
 - **FU-P13-T19** — Add integration coverage for broker-hosted Web UI observability
diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -2626,7 +2626,8 @@ Phase 9 Follow-up Backlog
 
 ---
 
-#### ⬜️ FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows
+#### ✅ FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows — Completed (2026-02-28, PASS)
+- **Status:** ✅ Completed (2026-02-28, PASS)
 - **Description:** Update setup and troubleshooting docs so users can apply one MCP config across agents while reusing a shared broker host and one dashboard endpoint.
 - **Priority:** P1
 - **Dependencies:** FU-P13-T17
@@ -2635,9 +2636,9 @@ Phase 9 Follow-up Backlog
   - Updated `README.md`, `docs/broker-mode.md`, `docs/webui-setup.md`, and `docs/troubleshooting.md`
   - Updated mapped DocC files in `Sources/XcodeMCPWrapper/Documentation.docc/`
 - **Acceptance Criteria:**
-  - [ ] Docs include one-config examples for Zed/Cursor/Claude/Codex with broker + dashboard expectations
-  - [ ] Docs clearly define dashboard ownership and fallback behavior
-  - [ ] Troubleshooting includes broker-hosted Web UI diagnostics
+  - [x] Docs include one-config examples for Zed/Cursor/Claude/Codex with broker + dashboard expectations
+  - [x] Docs clearly define dashboard ownership and fallback behavior
+  - [x] Troubleshooting includes broker-hosted Web UI diagnostics
 
 ---
 

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md
@@ -271,7 +271,9 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex
 
 - MCP can stay healthy even if Web UI startup is skipped.
 - Only one process can own a given Web UI `host:port`.
-- In broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`), the dashboard server is not started.
+- Dashboard starts in a direct-mode owner (`--web-ui`) or a broker host (`--broker-daemon --web-ui`).
+- `--broker-connect` never starts a dashboard by itself; `--broker-spawn --web-ui` only starts one when it must spawn a host.
+- If dashboard bind fails (port already in use), wrapper logs a warning and continues MCP without dashboard hosting.
 - A healthy MCP status does not guarantee an active dashboard listener on the expected port.
 
 **Diagnosis:**
@@ -283,6 +285,10 @@ lsof -nP -iTCP:$PORT -sTCP:LISTEN
 
 # 2) Which wrapper processes are currently alive?
 pgrep -af "xcodemcpwrapper|mcpbridge-wrapper|mcpbridge_wrapper"
+
+# 3) If you expect broker-hosted dashboard, inspect broker host logs
+LOG="$HOME/.mcpbridge_wrapper/broker.log"
+test -f "$LOG" && rg -n "Web UI dashboard started|Skipping Web UI startup" "$LOG" | tail -n 10
 ```
 
 If step 1 returns no listener, no process currently owns the dashboard port.
@@ -291,7 +297,9 @@ If step 1 returns no listener, no process currently owns the dashboard port.
 
 1. **Single dashboard owner (direct mode):** keep `--web-ui` on one client config only.
 2. **Use separate dashboard ports:** assign unique `--web-ui-port` values per process.
-3. **Broker mode for multi-agent MCP:** use `--broker-daemon` + `--broker-connect` for clients, and run dashboard diagnostics separately with `--web-ui-only` when needed.
+3. **Unified broker single-config:** use `--broker-spawn --web-ui --web-ui-config <shared-path>` in all clients so one spawned host owns the dashboard.
+4. **Dedicated host pattern:** run one `--broker-daemon --web-ui` process, keep clients on `--broker-connect`, and monitor `~/.mcpbridge_wrapper/broker.log`.
+5. **Standalone diagnostics:** run `--web-ui-only` when you need dashboard-only debugging independent from MCP startup.
 
 ## Error: "Tool charts are fresh, but Audit Log / Session Timeline look stale"
 

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md b/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md
@@ -49,13 +49,15 @@ The Web UI dashboard is hosted by the wrapper process that successfully binds th
 Recommended patterns:
 
 1. **Single owner (recommended):** enable `--web-ui` for one designated client process only.
-2. **Separate ports per process:** if you truly need multiple dashboards, give each process its own port.
-3. **Shared config for consistency:** if multiple processes may start with Web UI args, use the same `--web-ui-config` so audit log paths stay aligned.
+2. **Unified broker config (multi-agent):** use `--broker-spawn --web-ui --web-ui-config <shared-path>` across Cursor/Zed/Claude/Codex so the first auto-spawn host owns one shared dashboard endpoint.
+3. **Separate ports per process:** if you truly need multiple dashboards, give each process its own port.
 
 Broker-mode note:
 
-- Broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the dashboard server.
-- Use direct mode with `--web-ui` (or `--web-ui-only` for diagnostics) when dashboard access is required.
+- `--broker-daemon --web-ui` starts the dashboard in the broker host process.
+- `--broker-spawn --web-ui` can start the dashboard when it has to spawn the broker host.
+- `--broker-connect` never starts the dashboard by itself.
+- If dashboard bind fails, broker MCP transport still runs and dashboard startup is skipped.
 
 ### Enabling via mcp.json
 

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md
@@ -94,6 +94,7 @@ Broker mode lets short-lived MCP sessions share one persistent upstream bridge.
 
 - `--broker-connect`: attach to an already-running broker.
 - `--broker-spawn`: best-effort auto-start, then connect.
+- Add `--web-ui` (plus optional `--web-ui-config`) when you want the spawned or daemon host to own one shared dashboard endpoint.
 
 Quick migration examples:
 
@@ -112,14 +113,11 @@ For troubleshooting and rollback details, see <doc:CursorSetup>,
 
 When you run multiple MCP client processes at the same time:
 
-- **For shared MCP upstream sessions:** run one broker daemon host and configure each client with `--broker-connect`.
-- **For Web UI dashboard hosting:** only one process can bind a given `host:port` (for example `127.0.0.1:8080`).
-- If multiple direct-mode processes start with the same `--web-ui-port`, one process serves the dashboard and other processes continue MCP without dashboard hosting.
-- This ownership rule is process-level and independent from Xcode window state.
-
-Current limitation:
-- Broker CLI modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the Web UI dashboard process.
-- If you need dashboard diagnostics, run a separate direct-mode/Web-UI process (for example `--web-ui-only`) in parallel.
+- **Unified single-config pattern:** configure each client with `--broker-spawn --web-ui --web-ui-config <shared-path>`.
+- **Runtime expectation:** the first client that must spawn the broker starts the broker host and dashboard; later clients reuse the same broker and dashboard endpoint.
+- **Ownership rule:** only one process can bind a given Web UI `host:port` (for example `127.0.0.1:8080`).
+- **Connect-only behavior:** `--broker-connect` clients never start the dashboard by themselves.
+- **Fallback behavior:** if dashboard bind fails (port already in use), broker MCP transport continues and only dashboard startup is skipped.
 
 See <doc:WebUIDashboard> and <doc:Troubleshooting>.