SoundBlaster · SoundBlaster · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -6,6 +6,7 @@
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P7-T5 | [P7-T5_Document_broker_UX/](P7-T5_Document_broker_UX/) | 2026-03-07 | PASS |
 | P7-T4 | [P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/](P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/) | 2026-03-07 | PASS |
 | FU-P7-T3-2 | [FU-P7-T3-2_Exclude_broker-owned_dashboard_listeners_from_foreign_port-conflict_guidance/](FU-P7-T3-2_Exclude_broker-owned_dashboard_listeners_from_foreign_port-conflict_guidance/) | 2026-03-07 | PASS |
 | FU-P7-T3-1 | [FU-P7-T3-1_Prioritize_foreign_port-owner_guidance_in_mixed_broker-dashboard_conflicts/](FU-P7-T3-1_Prioritize_foreign_port-owner_guidance_in_mixed_broker-dashboard_conflicts/) | 2026-03-07 | PASS |
@@ -203,6 +204,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_broker_ux_docs.md](_Historical/REVIEW_broker_ux_docs.md) | Review report for P7-T5 |
 | [REVIEW_tui_local_status_fallback.md](P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/REVIEW_tui_local_status_fallback.md) | Review report for P7-T4 |
 | [REVIEW_broker_owned_listener_guidance.md](_Historical/REVIEW_broker_owned_listener_guidance.md) | Review report for FU-P7-T3-2 |
 | [REVIEW_mixed_dashboard_conflict_guidance.md](_Historical/REVIEW_mixed_dashboard_conflict_guidance.md) | Review report for FU-P7-T3-1 |
@@ -349,6 +351,8 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-03-07 | P7-T5 | Archived REVIEW_broker_ux_docs report |
+| 2026-03-07 | P7-T5 | Archived Document_broker_UX (PASS) |
 | 2026-03-07 | P7-T4 | Archived REVIEW_tui_local_status_fallback report |
 | 2026-03-07 | P7-T4 | Archived with verdict PASS |
 | 2026-03-07 | FU-P7-T3-2 | Archived REVIEW_broker_owned_listener_guidance report |

diff --git a/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Document_broker_UX.md b/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Document_broker_UX.md
@@ -0,0 +1,104 @@
+# P7-T5: Document the simplest supported broker UX and failure recovery flow
+
+**Status:** In Progress
+**Phase:** Phase 7 — Broker UX and Diagnostics
+**Priority:** P1
+**Dependencies:** P7-T1, P7-T2, P7-T3, P7-T4
+
+---
+
+## Problem Statement
+
+The broker UX surface has grown significantly through P7-T1 through P7-T4. Users now have:
+- `--broker-daemon --web-ui` for dedicated host startup
+- `--broker` for auto-detect/attach
+- `--broker-status` and `--broker-stop` for lifecycle management
+- `--broker-doctor` for diagnostics (P7-T2)
+- `--tui` for live operator monitoring (P7-T1)
+
+However, the user-facing documentation still presents these as a flat collection of options scattered
+across `broker-mode.md`, `troubleshooting.md`, and several client setup guides. New users must
+piece together the happy path from multiple documents, and the failure-recovery path is buried
+under long error reference sections.
+
+The goal of P7-T5 is to rewrite the broker UX documentation to:
+1. Present **one recommended path** first (the simplest supported workflow)
+2. Provide **one short failure-recovery path** using diagnostic surfaces (--broker-status, --broker-doctor, --tui)
+3. Not force users to read multiple guides to understand the common case
+
+---
+
+## Scope
+
+### In Scope
+- Rewrite `docs/broker-mode.md`:
+  - Lead with a single "quickstart" section: recommended one-command broker setup
+  - Follow with a concise failure-recovery section using `--broker-status` / `--broker-doctor`
+  - Move detailed/edge-case content to later sections (preserve existing detail, reorganize)
+- Add a `docs/quickstart.md` — a minimal end-to-end guide (install → enable Xcode Tools → add broker to one client → verify)
+- Update `docs/troubleshooting.md` to reference the new quickstart for initial setup failures
+
+### Out of Scope
+- No new CLI features
+- No changes to existing Python source code
+- No changes to test suite
+
+---
+
+## Deliverables
+
+1. **`docs/broker-mode.md`** — Reorganized with quickstart-first structure
+2. **`docs/quickstart.md`** — New minimal end-to-end guide (5–8 steps max)
+3. **`docs/troubleshooting.md`** — Updated reference to quickstart in first-time setup failure scenarios
+
+---
+
+## Acceptance Criteria
+
+- [ ] `docs/quickstart.md` exists with ≤8 numbered steps covering install → Xcode enable → broker start → client config → verify
+- [ ] `docs/broker-mode.md` opens with a "Quick setup" or "Recommended path" section that presents the simplest broker invocation before any detailed options
+- [ ] `docs/broker-mode.md` has a dedicated "Failure recovery" section (or similar) showing how to use `--broker-status`, `--broker-doctor`, and `--tui` to diagnose and recover
+- [ ] `docs/troubleshooting.md` references `docs/quickstart.md` in the initial setup / first-time connection section
+- [ ] No dead links (all `[text](file.md)` cross-references point to existing files)
+- [ ] No Python source code changes — docs only
+- [ ] All existing tests continue to pass (`make test`)
+
+---
+
+## Implementation Plan
+
+### Step 1 — Create `docs/quickstart.md`
+Write a minimal end-to-end guide:
+1. Prerequisites (Xcode 26.3+, uv/uvx)
+2. Enable Xcode Tools in Xcode Settings → Intelligence
+3. Start the broker daemon (one command)
+4. Add one MCP client config (show one example: Claude Code or Cursor)
+5. Verify: `--broker-status`, first tool call
+6. (Optional) Open dashboard: `open http://127.0.0.1:8080`
+
+### Step 2 — Rewrite `docs/broker-mode.md` structure
+New section order:
+1. **Quick setup** (2–3 commands, the recommended path)
+2. **Verify it's working** (`--broker-status`, broker log, dashboard)
+3. **Failure recovery** (`--broker-status`, `--broker-doctor`, `--tui`, recovery commands)
+4. *Existing detailed sections* (mode summary, topology, paths, operational flows, version management, client configs, security, etc.) — preserved but demoted
+
+### Step 3 — Update `docs/troubleshooting.md`
+- In the "0 tools" section, add a callout: "If this is first-time setup, see [Quickstart](quickstart.md) for the recommended initial flow."
+- In the "broker not starting" section, reference `--broker-doctor` as the first diagnostic step
+
+---
+
+## Quality Gates
+
+- `make test` — all tests pass (no source changes, but confirm no regressions)
+- `ruff check src/` — no regressions
+- Manual link check: all `[text](file.md)` in changed files point to real files
+
+---
+
+## Notes
+
+- The "dedicated host frontend workflow" section in `broker-mode.md` is currently detailed and accurate; preserve it as a later section, just move it after the quickstart and failure-recovery sections.
+- The `--broker-doctor` command (added in P7-T2) should be prominently featured in the failure-recovery path — this was its design intent.
+- `--tui` (added in P7-T1) should appear in the "monitoring" sub-section of failure recovery.
diff --git a/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Validation_Report.md b/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Validation_Report.md
@@ -0,0 +1,61 @@
+# P7-T5 Validation Report
+
+**Task:** P7-T5 — Document the simplest supported broker UX and failure recovery flow
+**Date:** 2026-03-07
+**Verdict:** PASS
+
+---
+
+## Deliverables
+
+| Deliverable | Status |
+|-------------|--------|
+| `docs/quickstart.md` — new minimal end-to-end guide | ✅ Created |
+| `docs/broker-mode.md` — reorganized with quickstart-first structure | ✅ Updated |
+| `docs/troubleshooting.md` — references quickstart + `--doctor` in recovery | ✅ Updated |
+
+---
+
+## Acceptance Criteria
+
+| Criterion | Result |
+|-----------|--------|
+| `docs/quickstart.md` exists with ≤8 numbered steps covering install → Xcode enable → broker start → client config → verify | ✅ 5 numbered steps |
+| `docs/broker-mode.md` opens with a "Quick setup" section presenting the simplest broker invocation first | ✅ New "Quick setup (recommended path)" section is first after the intro |
+| `docs/broker-mode.md` has a dedicated "Failure recovery" section with `--broker-status`, `--doctor`, `--tui` | ✅ Full "Failure recovery" section added |
+| `docs/troubleshooting.md` references `docs/quickstart.md` in initial setup section | ✅ Added callout at top of file |
+| No dead `.md` links in changed files | ✅ Link check passed (all targets exist) |
+| No Python source code changes — docs only | ✅ Confirmed |
+| All existing tests continue to pass | ✅ 898 passed, 5 skipped, 2 warnings |
+
+---
+
+## Quality Gates
+
+| Gate | Result |
+|------|--------|
+| `make test` — all tests pass | ✅ 898 passed, 5 skipped, 2 warnings (9.16s) |
+| `ruff check src/` — no linting errors | ✅ All checks passed |
+| `pytest --cov` — coverage ≥ 90% | ✅ 91.75% |
+| Manual link check — all `.md` cross-references valid | ✅ All .md links OK |
+
+---
+
+## Changes Summary
+
+### `docs/quickstart.md` (new)
+- 5-step guide: prerequisites → enable Xcode Tools → start broker daemon → configure one MCP client → verify
+- Includes a concise "Failure recovery" section with `--broker-status`, `--doctor`, `--tui`, and a recovery table
+- Cross-references `troubleshooting.md` for detailed error reference
+
+### `docs/broker-mode.md` (restructured)
+- Added intro callout linking to `quickstart.md`
+- New **"Quick setup (recommended path)"** section as the first major section — 2 commands, recommended path
+- New **"Verify it is working"** section — `--broker-status`, logs, dashboard, TUI
+- New **"Failure recovery"** section — `--broker-status`, `--doctor`, `--tui`, recovery table, restart steps
+- All existing detailed sections preserved and demoted below the new sections
+- Added `quickstart.md` to "Related docs"
+
+### `docs/troubleshooting.md` (updated)
+- Added first-time setup callout at top of file pointing to `quickstart.md`
+- Added `--doctor` as the first diagnostic step in the "Could not connect to broker socket" section
diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_broker_ux_docs.md b/SPECS/ARCHIVE/_Historical/REVIEW_broker_ux_docs.md
@@ -0,0 +1,71 @@
+## REVIEW REPORT — broker_ux_docs
+
+**Scope:** origin/main..HEAD (feature/P7-T5-broker-ux-docs)
+**Files:** 3 docs changed, 1 new doc created
+**Date:** 2026-03-07
+
+---
+
+### Summary Verdict
+
+- [ ] Approve
+- [x] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+**Overall:** The implementation is clean, docs-only, and correctly addresses the PRD. All quality gates pass. One low-priority nit about `--web-ui-config` defaulting noted below, but nothing blocking.
+
+---
+
+### Critical Issues
+
+None.
+
+---
+
+### Secondary Issues
+
+**[Low] `docs/quickstart.md` Step 2 omits `--web-ui-config` from the daemon start command**
+
+The quick setup daemon start command in `broker-mode.md` (Quick setup section) does not include
+`--web-ui-config`, while Step 4 client configs reference a config file path. This is technically
+correct — `--web-ui-config` is optional when using defaults — but it creates a slight inconsistency
+with the verification step that mentions "open http://127.0.0.1:8080". A user who configured a
+non-default port in their webui.json would be confused.
+
+*Suggestion:* Add a parenthetical note like "(uses default port 8080; add --web-ui-config if you have a custom config)" to the daemon start command in the Quick setup section. Low priority because default port 8080 covers the majority of users.
+
+**[Low] `quickstart.md` Step 3 verification uses `uvx --from mcpbridge-wrapper` while Step 2 uses `--from 'mcpbridge-wrapper[webui]'`**
+
+The two invocations use different package specifiers. `--broker-status` doesn't need webui extras,
+so the base package is correct — but visually inconsistent for users reading top-to-bottom.
+
+*Suggestion:* Add a brief note "(no [webui] extras needed for status checks)" or standardize the
+Step 3 example to use `mcpbridge-wrapper --broker-status` (assuming it was installed via the
+daemon setup) to avoid confusion. Not blocking.
+
+---
+
+### Architectural Notes
+
+- The three-section restructure (Quick setup → Verify → Failure recovery) correctly addresses the PRD's goal of presenting one path first before detailed options.
+- `--doctor` is now prominently surfaced in both `broker-mode.md` failure recovery and `troubleshooting.md` — this aligns with P7-T2's design intent.
+- The `quickstart.md` failure recovery table is a useful quick-reference; it duplicates some content from `broker-mode.md` but the duplication is intentional and appropriate for a standalone entry-point doc.
+- `---` horizontal rules now separate all major sections in `broker-mode.md`, improving scanability for a long reference page.
+- Cross-links between `quickstart.md`, `broker-mode.md`, and `troubleshooting.md` are all valid (link check passed).
+
+---
+
+### Tests
+
+- No source code changes — test suite unchanged.
+- `make test`: 898 passed, 5 skipped, 2 warnings — no regressions.
+- Coverage: 91.75% — remains above 90% threshold.
+- `ruff check src/`: all checks passed.
+
+---
+
+### Next Steps
+
+- The two Low findings above could be addressed in a follow-up polish pass, but neither is blocking.
+- No other actionable items identified. FOLLOW-UP can be skipped.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -1,26 +1,16 @@
-# Next Task: P7-T5 — Document the simplest supported broker UX and failure recovery flow
+# Next Task: (none pending)
 
-**Priority:** P1
-**Phase:** Phase 7: Broker UX and Diagnostics
-**Effort:** TBD
-**Dependencies:** P7-T1, P7-T2, P7-T3, P7-T4
-**Status:** Pending
-
-## Description
-
-After the orchestration and diagnostics improvements land, rewrite the user-facing docs around
-the simplest supported broker UX. The docs should present one recommended command path first,
-then one short failure-recovery path using the new diagnostic surfaces, instead of forcing users
-to piece together behavior from multiple guides.
+All current workplan tasks are complete.
 
 ## Recently Archived
 
+- `2026-03-07` — `P7-T5` archived with verdict `PASS`
 - `2026-03-07` — `P7-T4` archived with verdict `PASS`
 - `2026-03-07` — `FU-P7-T3-2` archived with verdict `PASS`
 - `2026-03-07` — `FU-P7-T3-1` archived with verdict `PASS`
 - `2026-03-07` — `FU-P7-T1-1` archived with verdict `PASS`
 
 ## Next Step
 
-Create the `P7-T5` PRD in `SPECS/INPROGRESS/`, then implement and validate the simplified
-broker UX documentation.
+All tasks in the current workplan cycle have been completed. Add new tasks to
+`SPECS/Workplan.md` to begin the next cycle.
diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -572,16 +572,17 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [x] The screen clearly distinguishes live dashboard-backed runtime data from local fallback data
   - [x] Users can tell from TUI alone whether they need to restart the broker, free a port, or just attach a client
 
-#### ⬜️ P7-T5: Document the simplest supported broker UX and failure recovery flow
+#### ✅ P7-T5: Document the simplest supported broker UX and failure recovery flow
+- **Status:** ✅ Completed (2026-03-07)
 - **Description:** After the orchestration and diagnostics improvements land, rewrite the user-facing docs around the simplest supported broker UX. The docs should present one recommended command path first, then one short failure-recovery path using the new diagnostic surfaces, instead of forcing users to piece together behavior from multiple guides.
 - **Priority:** P1
 - **Dependencies:** P7-T1, P7-T2, P7-T3, P7-T4
 - **Parallelizable:** yes
 - **Outputs/Artifacts:**
-  - `README.md` and broker troubleshooting docs updated to present the new primary UX
-  - client setup guides updated to reference the one-command startup and doctor flow
-  - DocC mirrors synced for all changed documentation
+  - `docs/quickstart.md` — new minimal end-to-end guide (5 steps)
+  - `docs/broker-mode.md` — restructured with quickstart-first and failure recovery sections
+  - `docs/troubleshooting.md` — updated to reference quickstart and `--doctor`
 - **Acceptance Criteria:**
-  - [ ] New users can find the recommended broker startup command and the recommended diagnostic command within one short reading path
-  - [ ] The docs no longer require users to infer the relationship between broker, dashboard, TUI, and Xcode approval prompts from multiple separate pages
-  - [ ] Failure recovery steps are written around the new UX primitives rather than raw manual shell debugging
+  - [x] New users can find the recommended broker startup command and the recommended diagnostic command within one short reading path
+  - [x] The docs no longer require users to infer the relationship between broker, dashboard, TUI, and Xcode approval prompts from multiple separate pages
+  - [x] Failure recovery steps are written around the new UX primitives rather than raw manual shell debugging
diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md
@@ -2,6 +2,8 @@
 
 Common issues and their solutions.
 
+**Setting up for the first time?** See the [Quickstart guide](https://github.com/SoundBlaster/XcodeMCPWrapper/blob/main/docs/quickstart.md) for the recommended initial flow before diving into this error reference.
+
 ## Error: "Found 0 tools, 0 prompts, and 0 resources"
 
 **Symptom:** MCP client connects successfully but reports 0 available tools
@@ -507,7 +509,13 @@ The second value should be larger.
 
 **Note:** When using `--broker`, stale socket/PID files are detected and removed automatically.
 
-**Solution:**
+**First step:** Run `--doctor` for a structured diagnostic report:
+
+```bash
+uvx --from mcpbridge-wrapper mcpbridge-wrapper --doctor
+```
+
+**Manual check:**
 
 ```bash
 PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then echo "broker running"; else echo "broker not running"; fi; ls -l "$SOCK" 2>/dev/null || echo "socket missing"