# Phase 2 Implementation Guide

## Overview

This directory contains comprehensive specifications for implementing world-class UI/UX improvements, notifications, voice/chat hybrid mode, mobile connectivity, and enterprise features for the SOPHIAClaw macOS app.

## Table of Contents

1. [Design System](./01-design-system.md) - Brand colors, typography, spacing, components
2. [UI/UX Improvements](./02-ui-ux-improvements.md) - Chat window, visual polish, animations
3. [Notification System](./03-notifications.md) - Response notifications, permissions, settings
4. [Voice + Chat Hybrid](./04-voice-chat-hybrid.md) - Combined voice and text interaction
5. [Mobile Connectivity](./05-mobile-connectivity.md) - External access, security, Tailscale
6. [Enterprise Features](./06-enterprise-features.md) - Multi-window, shortcuts, accessibility
7. [Implementation Roadmap](./07-roadmap.md) - Priority order, dependencies, estimates
8. [Background Tasks Sidebar](./08-background-tasks-sidebar.md) - Hybrid mode for subagent task management
   - [Agent Instructions](./08a-agent-instructions.md) - Detailed implementation steps

## Quick Start for Coding Agents

### Files Modified in Phase 1 (Baseline)

- `/apps/macos/Sources/SOPHIAClaw/AboutSettings.swift` - Copyright and branding
- `/apps/macos/Sources/SOPHIAClaw/CommandResolver.swift` - Method naming fixes
- `/apps/macos/Sources/SOPHIAClaw/CritterStatusLabel+Behavior.swift` - Brain icon
- `/apps/macos/Sources/SOPHIAClaw/Onboarding.swift` - Welcome title
- `/apps/macos/Sources/SOPHIAClaw/SettingsRootView.swift` - Notification names
- `/apps/macos/Sources/SOPHIAClaw/PeekabooBridgeHostCoordinator.swift` - Socket paths
- `/apps/macos/Sources/SOPHIAClaw/AnthropicOAuth.swift` - Environment variables
- `/apps/macos/Sources/SOPHIAClaw/NodeServiceManager.swift` - Encoding fixes
- `/apps/macos/Sources/SOPHIAClaw/GatewayLaunchAgentManager.swift` - Type inference
- `/apps/macos/Sources/SOPHIAClawMacCLI/ConnectCommand.swift` - Client ID defaults
- `/apps/macos/Sources/SOPHIAClawMacCLI/WizardCommand.swift` - Client ID
- `/apps/macos/Sources/SOPHIAClaw/NodeMode/MacNodeModeCoordinator.swift` - Client ID
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatComposer.swift` - Placeholder text, abort button color
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawKit/GatewayChannel.swift` - Client ID, Origin header
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawKit/GatewayTLSPinning.swift` - Origin header
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatViewModel.swift` - Notification callback
- `/apps/macos/Sources/SOPHIAClaw/WebChatSwiftUI.swift` - Notification handler

### Key Resources

- App icon: `/apps/macos/SOPHIAClaw.app/Contents/Resources/sophiaclaw_logo.png`
- Mascot: `/apps/macos/SOPHIAClaw.app/Contents/Resources/sophia-mascot.png`
- Bundle ID: `ai.sophiaclaw.sophiaclaw`
- Target: macOS 15.0+

### Build Commands

```bash
cd apps/macos
swift build -c release --product SOPHIAClaw

# Create app bundle
mkdir -p SOPHIAClaw.app/Contents/MacOS
mkdir -p SOPHIAClaw.app/Contents/Resources
mkdir -p SOPHIAClaw.app/Contents/Frameworks
cp .build/arm64-apple-macosx/release/SOPHIAClaw SOPHIAClaw.app/Contents/MacOS/
cp sophiaclaw_logo.png SOPHIAClaw.app/Contents/Resources/
cp sophia-mascot.png SOPHIAClaw.app/Contents/Resources/
install_name_tool -add_rpath "@executable_path/../Frameworks" SOPHIAClaw.app/Contents/MacOS/SOPHIAClaw
```

### Testing Checklist

- [ ] App launches without crashes
- [ ] Brain icon appears in menu bar
- [ ] Chat window opens on click
- [ ] Placeholder shows "Message SOPHIAClaw…"
- [ ] Stop button is purple (not purple)
- [ ] Notifications appear when response arrives
- [ ] Gateway connects successfully
- [ ] About page shows Thalamus branding

## Design Principles

1. **Consistency** - Use design system throughout
2. **Clarity** - Users should never be confused about what's happening
3. **Performance** - 60fps animations, instant feedback
4. **Accessibility** - VoiceOver, keyboard nav, dynamic type
5. **Delight** - Micro-interactions, haptics, sound

## Getting Help

If you encounter issues:

1. Check the specific feature documentation file
2. Look for code examples in the "Implementation" sections
3. Verify you're using the correct file paths
4. Test on actual macOS hardware when possible

## Success Metrics

Phase 2 is complete when:

- [ ] Design system is fully implemented
- [ ] No "developer look" UI elements remain
- [ ] Notifications work reliably
- [ ] Voice + chat hybrid mode functional
- [ ] Mobile connectivity tested and working
- [ ] All accessibility requirements met
- [ ] User testing confirms enterprise-grade quality