SoundBlaster · SoundBlaster · Feb 12, 2026 · Feb 12, 2026 · Feb 12, 2026 · Feb 12, 2026
diff --git a/README.md b/README.md
@@ -142,6 +142,12 @@ cd XcodeMCPWrapper
 
 The install script creates a virtual environment, installs the package, and places a wrapper at `~/bin/xcodemcpwrapper`.
 
+If you plan to use `--web-ui` MCP args, install Web UI extras explicitly:
+
+```bash
+./scripts/install.sh --webui
+```
+
 Add the following to your `~/.bashrc` or `~/.zshrc`:
 ```bash
 export PATH="$HOME/bin:$PATH"
@@ -200,6 +206,7 @@ For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) a
 ```
 
 **Using manual installation with Web UI (Optional):**
+> Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies).
 ```json
 {
   "mcpServers": {
@@ -254,6 +261,7 @@ claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper
 ```
 
 **Using manual installation with Web UI (Optional):**
+Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies).
 ```bash
 claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
 ```
@@ -288,6 +296,7 @@ codex mcp add xcode -- ~/bin/xcodemcpwrapper
 ```
 
 **Using manual installation with Web UI (Optional):**
+Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies).
 ```bash
 codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
 ```
@@ -349,6 +358,7 @@ Edit `~/.zed/settings.json`:
 ```
 
 **Using manual installation with Web UI (Optional):**
+Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies).
 ```json
 {
   "xcode-tools": {

diff --git a/...eb_UI_configuration_expectations/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md b/...eb_UI_configuration_expectations/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md
@@ -0,0 +1,13 @@
+# FOLLOW-UP — FU-P6-T10-1 Install/Web UI Alignment
+
+**Parent Task:** FU-P6-T10-1  
+**Review File:** REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md  
+**Date:** 2026-02-12
+
+## Actionable Findings
+
+No actionable follow-up tasks were identified.
+
+## Decision
+
+FOLLOW-UP step completed with no new workplan tasks added.
diff --git a/...-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md b/...-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md
@@ -0,0 +1,32 @@
+# FU-P6-T10-1 — Align manual install script with Web UI configuration expectations
+
+**Priority:** P1  
+**Dependencies:** P6-T3, P10-T1  
+**Phase:** Follow-up Backlog
+
+## Objective
+Eliminate the installation mismatch where `scripts/install.sh` installs only base dependencies while users can copy configs that enable `--web-ui`, causing runtime ImportError for missing Web UI packages.
+
+## Deliverables
+1. `scripts/install.sh` supports explicit Web UI install mode via `--webui`.
+2. `README.md` and `docs/installation.md` clearly map:
+   - base install => no `--web-ui` args
+   - webui install => `--web-ui` args supported
+3. `docs/troubleshooting.md` includes symptom/cause/fix for this mismatch.
+4. Validation report records command-level verification.
+
+## Acceptance Criteria
+1. `./scripts/install.sh` keeps base install behavior by default.
+2. `./scripts/install.sh --webui` installs `-e ".[webui]"` dependencies.
+3. `xcodemcpwrapper --web-ui --web-ui-port 8080 --help` does not fail after Web UI install mode.
+4. Documentation no longer implies Web UI works on base-only install.
+
+## Execution Plan
+1. Extend installer argument parsing and install command selection.
+2. Update docs in focused sections only (no broad restructuring).
+3. Run quality gates plus targeted runtime checks.
+4. Produce `SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md`.
+
+---
+**Archived:** 2026-02-12
+**Verdict:** PASS
diff --git a/..._script_with_Web_UI_configuration_expectations/FU-P6-T10-1_Validation_Report.md b/..._script_with_Web_UI_configuration_expectations/FU-P6-T10-1_Validation_Report.md
@@ -0,0 +1,48 @@
+# FU-P6-T10-1 Validation Report
+
+**Task:** Align manual install script with Web UI configuration expectations  
+**Date:** 2026-02-12  
+**Verdict:** PASS
+
+## Changes Implemented
+
+1. Added Web UI install mode to `scripts/install.sh`:
+   - `--webui` flag support
+   - `--help` output and unknown-arg validation
+   - Base install remains default (`pip install -e .`)
+   - Web UI mode installs extras (`pip install -e ".[webui]"`)
+   - Post-install guidance now states whether Web UI extras are present
+
+2. Updated docs to prevent base/Web UI ambiguity:
+   - `README.md`: manual install section now documents `./scripts/install.sh --webui`
+   - `README.md`: manual Web UI config snippets now explicitly require Web UI extras
+   - `docs/installation.md`: Option D now documents base vs `--webui` mode
+   - `docs/troubleshooting.md`: added dedicated symptom/cause/fix for missing Web UI deps (`uvicorn` import error)
+
+## Acceptance Criteria Check
+
+| Criteria | Status | Evidence |
+|---|---|---|
+| Default `./scripts/install.sh` keeps base behavior | PASS | Installer runs successfully and prints base-only note |
+| `./scripts/install.sh --webui` installs Web UI extras | PASS | Installer runs in Web UI mode and prints Web UI deps installed message |
+| `xcodemcpwrapper --web-ui --web-ui-port 8080 --help` works in Web UI install mode | PASS | Command exits successfully after `--webui` install |
+| Docs no longer imply Web UI works on base-only install | PASS | README/installation/troubleshooting updated with explicit dependency mapping |
+
+## Quality Gates
+
+Environment note:
+- Initial `pytest` run with global interpreter failed (`ModuleNotFoundError: mcpbridge_wrapper`).
+- Quality gates were rerun in project venv after installing dev/webui extras.
+
+Results in `.venv`:
+- `python -m pytest` → **324 passed, 5 skipped**
+- `python -m ruff check src/` → **All checks passed**
+- `python -m mypy src/` → **Success: no issues found**
+- `python -m pytest --cov` → **Coverage 96.62%** (>= 90% requirement)
+
+## Files Modified
+
+- `scripts/install.sh`
+- `README.md`
+- `docs/installation.md`
+- `docs/troubleshooting.md`
diff --git a/..._Web_UI_configuration_expectations/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md b/..._Web_UI_configuration_expectations/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md
@@ -0,0 +1,28 @@
+## REVIEW REPORT — FU-P6-T10-1 Install/Web UI Alignment
+
+**Scope:** origin/main..HEAD  
+**Files:** 8
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- [Low] `scripts/install.sh` now has argument parsing in shell; future flags should preserve backward-compatible default mode and avoid changing current no-arg behavior.
+
+### Architectural Notes
+- Root cause (base install + Web UI args) is now addressed in both installer behavior and docs, reducing client-specific confusion (Zed/Cursor/Claude/Codex).
+
+### Tests
+- `./.venv/bin/python -m pytest` passed
+- `./.venv/bin/python -m ruff check src/` passed
+- `./.venv/bin/python -m mypy src/` passed
+- `./.venv/bin/python -m pytest --cov` passed (96.62%)
+
+### Next Steps
+- No actionable follow-up tasks required from this review.
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -74,6 +74,7 @@
 | FU-REBUILD-P10-T1-5 | [FU-REBUILD-P10-T1-5_Validate_Documentation_Paths/](FU-REBUILD-P10-T1-5_Validate_Documentation_Paths/) | 2026-02-11 | PASS |
 | FU-REBUILD-P10-T1-6 | [FU-REBUILD-P10-T1-6_Fix_Uninstall_Asymmetry/](FU-REBUILD-P10-T1-6_Fix_Uninstall_Asymmetry/) | 2026-02-12 | PASS |
 | P7-T12 | [P7-T12_Move_Cursor_UVX_Before_Installation/](P7-T12_Move_Cursor_UVX_Before_Installation/) | 2026-02-12 | PASS |
+| FU-P6-T10-1 | [FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/](FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/) | 2026-02-12 | PASS |
 
 ## Historical Artifacts
 
@@ -112,6 +113,8 @@
 | [REVIEW_FU-REBUILD-P10-T1-5_Documentation_Paths.md](FU-REBUILD-P10-T1-5_Validate_Documentation_Paths/REVIEW_FU-REBUILD-P10-T1-5_Documentation_Paths.md) | Review report for FU-REBUILD-P10-T1-5 |
 | [REVIEW_FU-REBUILD-P10-T1-6_Uninstall_Asymmetry.md](FU-REBUILD-P10-T1-6_Fix_Uninstall_Asymmetry/REVIEW_FU-REBUILD-P10-T1-6_Uninstall_Asymmetry.md) | Review report for FU-REBUILD-P10-T1-6 |
 | [REVIEW_P7-T12_Cursor_Quick_Setup.md](P7-T12_Move_Cursor_UVX_Before_Installation/REVIEW_P7-T12_Cursor_Quick_Setup.md) | Review report for P7-T12 |
+| [REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md](FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md) | Review report for FU-P6-T10-1 |
+| [FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md](FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md) | Follow-up report for FU-P6-T10-1 |
 
 ## Archive Log
 
@@ -178,3 +181,6 @@
 | 2026-02-12 | FU-REBUILD-P10-T1-6 | Archived REVIEW_FU-REBUILD-P10-T1-6_Uninstall_Asymmetry report |
 | 2026-02-12 | P7-T12 | Archived Move_Cursor_UVX_Before_Installation (PASS) |
 | 2026-02-12 | P7-T12 | Archived REVIEW_P7-T12_Cursor_Quick_Setup report |
+| 2026-02-12 | FU-P6-T10-1 | Archived Align_manual_install_script_with_Web_UI_configuration_expectations (PASS) |
+| 2026-02-12 | FU-P6-T10-1 | Archived REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch report |
+| 2026-02-12 | FU-P6-T10-1 | Archived FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch report |
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -4,11 +4,12 @@ The previously selected task has been archived.
 
 ## Recently Archived
 
+- 2026-02-12 — FU-P6-T10-1: Align manual install script with Web UI configuration expectations (PASS)
 - 2026-02-12 — P7-T12: Move Cursor IDE uvx settings before installation instructions in README (PASS)
 - 2026-02-12 — FU-REBUILD-P10-T1-6: Fix uninstall.sh package detection/removal asymmetry and venv cleanup (PASS)
 - 2026-02-11 — FU-REBUILD-P10-T1-5: Validate and fix documentation paths for local-running MCP server with Web UI (PASS)
 
 ## Suggested Next Tasks
 
 - FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (P2)
-- Run SELECT after adding new tasks to the workplan.
+- Run SELECT after choosing the next task.
diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -866,6 +866,7 @@ Create a Python-based protocol compatibility wrapper that intercepts MCP respons
 
 Phase 8 Follow-up Backlog
 - [ ] FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (P2)
+- [x] FU-P6-T10-1: Align manual install script with Web UI configuration expectations (P1)
 
 #### FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings
 - **Description:** Review follow-up to align Phase 8 tracking artifacts with the live documentation URL `soundblaster.github.io/XcodeMCPWrapper/` and remove remaining DocC ambiguity warnings in the Phase 8 documentation index.
@@ -879,7 +880,25 @@ Phase 8 Follow-up Backlog
 - **Acceptance Criteria:**
   - Workplan Phase 8 no longer references the legacy `/mcpbridge-wrapper` GitHub Pages URL as the active deployment URL
   - Phase 8 review/validation artifacts clearly document that the active URL is `soundblaster.github.io/XcodeMCPWrapper/`
-  - `swift package generate-documentation --target XcodeMCPWrapper` completes without `Architecture` ambiguity warnings
+- `swift package generate-documentation --target XcodeMCPWrapper` completes without `Architecture` ambiguity warnings
+
+#### ✅ FU-P6-T10-1: Align manual install script with Web UI configuration expectations
+- **Description:** Fix the mismatch where `scripts/install.sh` installs only the base package (`pip install -e .`) while docs/config examples allow `--web-ui` usage from `~/bin/xcodemcpwrapper`. This causes runtime failure when users enable Web UI without optional dependencies. Add an explicit installer mode for Web UI extras and update documentation to make the dependency requirement unambiguous.
+- **Priority:** P1
+- **Dependencies:** P6-T3, P10-T1
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - Updated `scripts/install.sh` with Web UI-aware install option (e.g., `--webui`) that installs `-e ".[webui]"`
+  - Updated `README.md` and `docs/installation.md` with clear mapping:
+    - base install => no `--web-ui` args
+    - webui install => `--web-ui` args supported
+  - Updated `docs/troubleshooting.md` to include this specific symptom/cause/fix path
+- **Acceptance Criteria:**
+  - Running `./scripts/install.sh` (default) keeps current base behavior and works with no Web UI args
+  - Running `./scripts/install.sh --webui` installs required Web UI dependencies (`fastapi`, `uvicorn`, etc.)
+  - `~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 --help` no longer fails after Web UI install mode
+  - Zed/Cursor configs that include `--web-ui` work when installer is run with Web UI mode
+  - Documentation examples do not imply Web UI works on base-only install
 
 ---
 

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md b/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md
@@ -62,12 +62,20 @@ This installs the package and creates the `mcpbridge-wrapper` or `xcodemcpwrappe
 ./scripts/install.sh
 ```
 
+If you need Web UI support for `--web-ui` args, install with:
+
+```bash
+./scripts/install.sh --webui
+```
+
 This script will:
 1. Create a virtual environment (`.venv`) if not already active
 2. Install the package into the venv
 3. Create `~/bin/xcodemcpwrapper` wrapper with the correct Python interpreter
 4. Make it executable
 
+Default `./scripts/install.sh` is base-only (no Web UI extras).
+
 ### Method 4: Local Development (venv)
 
 For development or running directly from the cloned repository:

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md
@@ -121,6 +121,20 @@ source bin/activate
 chmod +x ~/bin/xcodemcpwrapper
 ```
 
+## Error: "Web UI dependencies not installed" / `ModuleNotFoundError: uvicorn`
+
+**Symptom:** Wrapper exits when MCP client config includes `--web-ui` args.
+
+**Cause:** Manual install used base mode (`./scripts/install.sh`), but Web UI args require optional `.[webui]` dependencies.
+
+**Solution:**
+```bash
+cd /path/to/XcodeMCPWrapper
+./scripts/install.sh --webui
+```
+
+Then restart your MCP client. If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args.
+
 ## Tool Returns Empty Results
 
 **Symptom:** Tools execute but return no data.

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md
@@ -109,6 +109,11 @@ cd XcodeMCPWrapper
 ./scripts/install.sh
 ```
 
+If you plan to use `--web-ui` MCP args with manual install:
+```bash
+./scripts/install.sh --webui
+```
+
 For local development from a clone:
 ```bash
 git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
@@ -144,6 +149,19 @@ For **uvx** setup (recommended), see **Cursor Quick Setup** above.
 }
 ```
 
+**Using manual installation with Web UI (Optional):**
+> Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies).
+```json
+{
+  "mcpServers": {
+    "xcode-tools": {
+      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
+      "args": ["--web-ui", "--web-ui-port", "8080"]
+    }
+  }
+}
+```
+
 #### Claude Code
 
 **Using uvx (Recommended):**

diff --git a/docs/installation.md b/docs/installation.md
@@ -97,12 +97,20 @@ cd XcodeMCPWrapper
 ./scripts/install.sh
 ```
 
+If you need Web UI support for `--web-ui` args, install with:
+
+```bash
+./scripts/install.sh --webui
+```
+
 This will:
 - Create a virtual environment (`.venv`) if not already active
 - Install the package into the venv
 - Create `~/bin/xcodemcpwrapper` wrapper with the correct Python interpreter
 - Make `xcodemcpwrapper` available in your PATH
 
+Default `./scripts/install.sh` is base-only (no Web UI extras).
+
 Add the following to your `~/.bashrc` or `~/.zshrc`:
 ```bash
 export PATH="$HOME/bin:$PATH"

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -150,6 +150,21 @@ Then reload:
 source ~/.zshrc  # or ~/.bashrc
 ```
 
+### "Web UI dependencies not installed" / `ModuleNotFoundError: uvicorn`
+
+**Symptom:** Wrapper exits when client config includes `--web-ui` args.
+
+**Cause:** Manual install used base mode (`./scripts/install.sh`), but Web UI args require optional `.[webui]` dependencies.
+
+**Solution:**
+```bash
+cd /path/to/XcodeMCPWrapper
+./scripts/install.sh --webui
+```
+
+Then restart your MCP client.  
+If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args.
+
 ## Debug Mode
 
 For verbose output, check the stderr stream: