SoundBlaster · SoundBlaster · Feb 14, 2026 · Feb 14, 2026 · Feb 14, 2026 · Feb 14, 2026
diff --git a/.agents/skills/gh-create-pr/SKILL.md b/.agents/skills/gh-create-pr/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: gh-create-pr
+description: Create or update GitHub pull requests with the GitHub CLI (`gh`) using the repository PR template. Use when asked to open a PR, fix PR description formatting, align description with `.github/PULL_REQUEST_TEMPLATE.md`, or prepare a merge-ready PR with validation results.
+---
+
+# GH Create PR
+
+## Workflow
+
+1. Confirm branch and working tree are ready.
+- Run `git status -sb`.
+- Ensure commits are complete and branch is pushed.
+
+2. Collect PR context.
+- Read `.github/PULL_REQUEST_TEMPLATE.md` when present.
+- Gather summary of changes and executed checks from commits and task artifacts.
+- Prefer factual check results and avoid claiming manual tests that were not run.
+
+3. Create or update PR with `gh`.
+- Create:
+```bash
+gh pr create --base main --head <branch> --title "<title>" --body-file <body.md>
+```
+- Update existing PR description:
+```bash
+gh pr edit <number-or-url> --body-file <body.md>
+```
+
+4. Use template-accurate checkboxes.
+- Mark only items that were actually completed.
+- Leave unchecked items for unperformed steps.
+- Keep wording from the template unchanged; only fill values/check states.
+
+5. Verify PR state.
+- Open or print PR URL from `gh` output.
+- Optionally run:
+```bash
+gh pr view <number-or-url> --json number,title,url,headRefName,baseRefName
+```
+
+## Body Authoring Rules
+
+- Keep description short and concrete.
+- Include changed areas, bug/task ID when available, and validation commands.
+- Mention warnings or non-blocking caveats if present.
+- Do not include markdown sections not in the template when template compliance is requested.
+
+## Fast Patterns
+
+Template-first PR update:
+1. Read template.
+2. Create `body.md` following the exact headings/order.
+3. Apply with `gh pr edit <pr> --body-file body.md`.
+
+New PR from current branch:
+1. Build `body.md` from template.
+2. Run `gh pr create --base main --head $(git branch --show-current) ...`.
diff --git a/.agents/skills/gh-create-pr/agents/openai.yaml b/.agents/skills/gh-create-pr/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "GitHub PR Creator"
+  short_description: "Create/update template-compliant GitHub PRs"
+  default_prompt: "Use $gh-create-pr to create or update a GitHub pull request with the repository template and accurate check results."
diff --git a/README.md b/README.md
@@ -266,7 +266,7 @@ claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge
 
 **Using uvx with Web UI (Optional):**
 ```bash
-claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 ```
 
 **Using manual installation:**
@@ -301,7 +301,7 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 
 **Using uvx with Web UI (Optional):**
 ```bash
-codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 ```
 
 **Using manual installation:**

diff --git a/...UG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_Validation_Report.md b/...UG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_Validation_Report.md
@@ -0,0 +1,40 @@
+# BUG-T2 Validation Report
+
+- **Task ID:** BUG-T2
+- **Task Name:** codex mcp add with Web UI extras fails in zsh
+- **Date:** 2026-02-14
+- **Verdict:** PASS
+
+## Scope Validated
+
+- Updated shell command examples using uvx Web UI extras to a zsh-safe quoted form:
+  - `uvx --from 'mcpbridge-wrapper[webui]' ...`
+- Added explicit troubleshooting guidance for:
+  - `zsh: no matches found: mcpbridge-wrapper[webui]`
+- Applied updates across user-facing docs and command template text files.
+
+## Acceptance Criteria Check
+
+1. No unquoted shell command examples remain for `uvx --from mcpbridge-wrapper[webui]` in active docs/config text examples.  
+   **Result:** PASS
+2. Codex setup examples with Web UI extras show a zsh-safe command form.  
+   **Result:** PASS
+3. Troubleshooting includes exact zsh symptom and fix.  
+   **Result:** PASS
+4. Required quality gates pass.  
+   **Result:** PASS
+
+## Quality Gate Results
+
+- `pytest`  
+  - Result: PASS (`345 passed, 5 skipped`)
+- `ruff check src/`  
+  - Result: PASS (`All checks passed!`)
+- `mypy src/`  
+  - Result: PASS (`Success: no issues found in 12 source files`)
+- `pytest --cov`  
+  - Result: PASS (`Total coverage: 96.62%`, required `>= 90%`)
+
+## Notes
+
+- Test runs emitted non-blocking warnings about local port collisions (`127.0.0.1:8080` / `9090`) from background Web UI thread startup in tests; suite still passed and coverage threshold was met.
diff --git a/..._mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_codex_mcp_add_webui_zsh_glob.md b/..._mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_codex_mcp_add_webui_zsh_glob.md
@@ -0,0 +1,67 @@
+# BUG-T2 PRD — codex mcp add with Web UI extras fails in zsh
+
+## 1. Context
+
+When users run Codex MCP setup with uvx extras using an unquoted package specifier, zsh treats `[...]` as a glob pattern and fails before executing `uvx`.
+
+Failing command observed:
+
+```zsh
+codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+# zsh: no matches found: mcpbridge-wrapper[webui]
+```
+
+## 2. Goal
+
+Make all user-facing shell command examples for uvx Web UI extras shell-safe in zsh and add explicit troubleshooting guidance.
+
+## 3. Scope
+
+In scope:
+- Documentation and setup snippets where users copy/paste shell commands
+- Troubleshooting updates for `zsh: no matches found`
+- Task tracking updates for BUG-T2 completion
+
+Out of scope:
+- Runtime code changes in wrapper core
+- MCP protocol behavior changes
+
+## 4. Deliverables
+
+- Updated docs and command snippets to use quoted extras form:
+  - `uvx --from 'mcpbridge-wrapper[webui]' ...`
+- Troubleshooting section with symptom/cause/fix for zsh globbing
+- Validation report at `SPECS/INPROGRESS/BUG-T2_Validation_Report.md`
+
+## 5. Acceptance Criteria
+
+1. No unquoted shell command examples remain for `uvx --from mcpbridge-wrapper[webui]` in active docs/config text examples.
+2. Codex setup examples with Web UI extras show a zsh-safe command form.
+3. Troubleshooting docs include the exact symptom `zsh: no matches found: mcpbridge-wrapper[webui]` and a fix.
+4. Quality gates pass:
+   - `pytest`
+   - `ruff check src/`
+   - `mypy src/`
+   - `pytest --cov` with project coverage >= 90%
+
+## 6. Dependencies
+
+- Existing bug record in `SPECS/Workplan.md` (`BUG-T2`)
+- Existing docs pages: README, codex setup, troubleshooting, AGENTS
+
+## 7. Implementation Plan
+
+1. Find all user-facing shell examples using unquoted extras.
+2. Update command snippets to quoted extras.
+3. Add troubleshooting guidance for zsh glob expansion.
+4. Run quality gates and capture results.
+5. Archive task artifacts according to FLOW.
+
+## 8. Risks and Mitigations
+
+- Risk: Over-editing machine-readable config examples where shell quoting is irrelevant.
+- Mitigation: Restrict quoting changes to shell command strings and explanatory text meant for terminal copy/paste.
+
+---
+**Archived:** 2026-02-14
+**Verdict:** PASS
diff --git a/...codex_mcp_add_with_Web_UI_extras_fails_in_zsh/REVIEW_BUG-T2_zsh_webui_extras.md b/...codex_mcp_add_with_Web_UI_extras_fails_in_zsh/REVIEW_BUG-T2_zsh_webui_extras.md
@@ -0,0 +1,29 @@
+## REVIEW REPORT — BUG-T2 zsh Web UI extras
+
+**Scope:** origin/main..HEAD
+**Files:** 15
+
+### Summary Verdict
+- [ ] Approve
+- [x] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- [Low] Test runs produced non-blocking warnings from local port conflicts (`127.0.0.1:8080`/`9090`) in background Web UI test threads; this does not affect pass/fail status but can add noise in CI/local logs.
+
+### Architectural Notes
+- The fix correctly targets shell command examples only and avoids changing JSON-based MCP config argument arrays, where shell glob expansion is not applicable.
+
+### Tests
+- Quality gates executed and passed:
+  - `pytest` passed (`345 passed, 5 skipped`)
+  - `ruff check src/` passed
+  - `mypy src/` passed
+  - `pytest --cov` passed with `96.62%` coverage (>= 90%)
+
+### Next Steps
+- FOLLOW-UP skipped: no actionable defects requiring additional backlog tasks.
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,6 +1,6 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-02-13
+**Last Updated:** 2026-02-14
 
 ## Archived Tasks
 
@@ -83,6 +83,7 @@
 | P9-T4 | [P9-T4_Create_the_publishing_helper/](P9-T4_Create_the_publishing_helper/) | 2026-02-13 | PASS |
 | FU-P9-T4-1 | [FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/](FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/) | 2026-02-13 | PASS |
 | FU-P9-T2-2 | [FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/](FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/) | 2026-02-13 | PASS |
+| BUG-T2 | [BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/](BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/) | 2026-02-14 | PASS |
 
 ## Historical Artifacts
 
@@ -131,6 +132,7 @@
 | [REVIEW_p9_t4_publishing_helper.md](P9-T4_Create_the_publishing_helper/REVIEW_p9_t4_publishing_helper.md) | Review report for P9-T4 |
 | [REVIEW_fu_p9_t4_1_publish_helper_protected_main.md](FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/REVIEW_fu_p9_t4_1_publish_helper_protected_main.md) | Review report for FU-P9-T4-1 |
 | [REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting.md](FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting.md) | Review report for FU-P9-T2-2 |
+| [REVIEW_BUG-T2_zsh_webui_extras.md](BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/REVIEW_BUG-T2_zsh_webui_extras.md) | Review report for BUG-T2 |
 
 ## Archive Log
 
@@ -216,3 +218,5 @@
 | 2026-02-13 | FU-P9-T2-2 | Archived Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions (PASS) |
 | 2026-02-13 | FU-P9-T2-2 | Archived REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting report |
 | 2026-02-13 | FU-P9-T4-1 | Archived REVIEW_fu_p9_t4_1_publish_helper_protected_main report |
+| 2026-02-14 | BUG-T2 | Archived codex_mcp_add_with_Web_UI_extras_fails_in_zsh (PASS) |
+| 2026-02-14 | BUG-T2 | Archived REVIEW_BUG-T2_zsh_webui_extras report |
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -4,6 +4,7 @@ The previously selected task has been archived.
 
 ## Recently Archived
 
+- 2026-02-14 — BUG-T2: codex mcp add with Web UI extras fails in zsh (PASS)
 - 2026-02-13 — FU-P9-T2-2: Add troubleshooting guidance for stale uvx cache/process versions (PASS)
 - 2026-02-13 — FU-P9-T4-1: Align publish_helper output with protected main branch workflow (PASS)
 - 2026-02-13 — P9-T4: Create the publishing helper (PASS)

diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -994,6 +994,41 @@ Use alternative MCP clients that work correctly:
 
 ---
 
+### BUG-T2: `codex mcp add` with Web UI extras fails in `zsh` ✅
+- **Type:** Bug / Documentation / CLI UX
+- **Status:** ✅ Complete
+- **Priority:** P1
+- **Discovered:** 2026-02-14
+- **Completed:** 2026-02-14
+- **Component:** Installation & Configuration Docs
+- **Affected Client:** Codex CLI (shell command setup)
+- **Affected Shell:** `zsh` (default macOS shell)
+
+#### Description
+The documented/pasted Web UI setup command for Codex using uvx extras fails in `zsh` because square brackets are treated as a glob pattern when unquoted.
+
+#### Symptoms
+```zsh
+egor@MacBook-Pro-Egor bin % codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+zsh: no matches found: mcpbridge-wrapper[webui]
+```
+
+#### Root Cause Analysis
+`zsh` performs filename globbing on unquoted bracket expressions like `[webui]`. The token `mcpbridge-wrapper[webui]` is parsed as a glob instead of a literal package specifier.
+
+#### Workaround
+Use any of the following forms so the extras spec is passed literally:
+- `uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080`
+- `uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080`
+
+#### Resolution Path
+- [x] Update README and setup docs to quote extras in all shell commands (`'mcpbridge-wrapper[webui]'`)
+- [x] Update configuration templates/examples that include extras to avoid raw unquoted bracket syntax
+- [x] Add a troubleshooting entry for `zsh: no matches found` with shell-safe examples
+- [x] Add a short note explaining why quotes are required in `zsh`
+
+---
+
 ### Phase 10: Web UI Control & Audit Dashboard
 
 **Intent:** Create a web-based dashboard for real-time monitoring, control, and audit logging of the XcodeMCPWrapper. Provides visibility into MCP tool usage, performance metrics, and operational control.

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md
@@ -19,7 +19,7 @@ That's it! uvx will automatically download and run the wrapper.
 Use this variant to enable the dashboard on port `8080`:
 
 ```bash
-claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 ```
 
 ### Option 2: Using Manual Installation

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md
@@ -19,7 +19,7 @@ That's it! uvx will automatically download and run the wrapper.
 Use this variant to enable the dashboard on port `8080`:
 
 ```bash
-codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 ```
 
 ### Option 2: Using Manual Installation

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md
@@ -130,7 +130,7 @@ chmod +x ~/bin/xcodemcpwrapper
 **Solution (uvx):**
 Use `[webui]` extras in the uvx package source when Web UI args are enabled:
 ```bash
-uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --help
+uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --help
 ```
 
 **Solution (manual install):**
@@ -143,6 +143,23 @@ Then restart your MCP client.
 
 If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args.
 
+## Error: `zsh: no matches found: mcpbridge-wrapper[webui]`
+
+**Symptom:** Setup commands fail immediately in `zsh` before `uvx` runs.
+
+**Cause:** `zsh` treats unquoted brackets as glob patterns.
+
+**Solution:**
+Quote (or escape) the extras package specifier:
+```bash
+codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
+```
+
+Alternative escaped form:
+```bash
+codex mcp add xcode -- uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080
+```
+
 ## Error: "Uptime still shows 1h 0m 0s" or behavior is unchanged after upgrade
 
 **Symptom:** You upgraded to a newer release, but dashboard behavior still matches an older version (for example uptime stays `1h 0m 0s`).

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md
@@ -187,7 +187,7 @@ claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge
 
 **Using uvx with Web UI (Optional):**
 ```bash
-claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 ```
 
 **Using manual installation:**
@@ -206,7 +206,7 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 
 **Using uvx with Web UI (Optional):**
 ```bash
-codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 ```
 
 **Using manual installation:**

diff --git a/config/claude-code.txt b/config/claude-code.txt
@@ -10,7 +10,7 @@
 # -------------------------------------------
 # Enable the Web UI dashboard on port 8080:
 #
-#   claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+#   claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 #
 # To install uv (which includes uvx):
 #   curl -LsSf https://astral.sh/uv/install.sh | sh

diff --git a/config/codex-cli.txt b/config/codex-cli.txt
@@ -10,7 +10,7 @@
 # -------------------------------------------
 # Enable the Web UI dashboard on port 8080:
 #
-#   codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+#   codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 #
 # To install uv (which includes uvx):
 #   curl -LsSf https://astral.sh/uv/install.sh | sh

diff --git a/docs/claude-setup.md b/docs/claude-setup.md
@@ -18,7 +18,7 @@ That's it! uvx will automatically download and run the wrapper.
 Use this variant to enable the dashboard on port `8080`:
 
 ```bash
-claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080
+claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
 ```
 
 ## Alternative: Using Manual Installation