P1-T10: Document Xcode first-approval timing race in Troubleshooting & Known Issues

[SoundBlaster]

Description

Documents the Xcode first-approval timing race in broker mode — a usability trap where MCP clients show a green "connected" indicator with 0 tools and no error, caused by Xcode's per-process approval dialog racing with the client's tools/list request.

Changes:

• docs/troubleshooting.md — new section "MCP client shows 0 tools (green dot) after first broker connection": symptom, root cause, per-process identity note (direct wrapper vs broker daemon trigger separate dialogs), broker log signature, correct first-time setup sequence, client-specific recovery steps (Zed, Cursor, Claude Code), diagnostic command
• README.md — Known Issues entry for broker cold-start expanded: now includes client-caching consequence, green-dot symptom, per-process identity note, and a deep link to the new troubleshooting section
• Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md — mirrored section added

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactoring
• CI/CD improvement

Quality Gates

• make test - All tests pass with ≥90% coverage
• make lint - No linting errors
• make format - Code is properly formatted
• make typecheck - Type checking passes
• make doccheck - Documentation is synced with DocC (if docs changed)

Documentation-only change — no Python source modified. make test, make lint, make format, make typecheck are N/A. DocC mirror updated in the same commit as docs/troubleshooting.md.

Documentation Sync

• Documentation changes are synced with DocC catalog (or N/A)

docs/troubleshooting.md → Documentation.docc/Troubleshooting.md ✅ (new section mirrored)
README.md → mcpbridge-wrapper.docc/mcpbridge-wrapper.md — N/A (DocC root does not mirror README Known Issues section)

Testing

• Added/updated tests for new functionality
• All tests pass locally
• Manually tested the changes

Verified against live multi-client broker test (Zed + Claude Code): the symptom, root cause, log signature, and recovery sequence documented here match actual observed behaviour.

Checklist

• Code follows the project's style guidelines
• Self-review completed
• Comments added for complex code
• Documentation updated (if needed)
• No new warnings generated
• PR title is descriptive