Context

SkyTwin's desktop app (#13) initially targets macOS. For HN launch and broad adoption, it needs to run on Windows and Linux too. Mobile access (#15) starts as a responsive web dashboard over local network — but native iOS and Android apps provide a better experience for approvals on the go.

Claude Code estimate: ~5-8h

Current State (verified 2026-04-04)

• Desktop: Electron app at `apps/desktop/` — macOS-only packaging planned in Desktop Electron app: native install, tray, process management #13
• Mobile: responsive web dashboard + QR pairing planned in Mobile local access: QR pairing, mDNS, responsive dashboard #15
• No platform-specific native code (pure TypeScript + Electron)
• electron-builder supports macOS, Windows, Linux from same codebase

Proposed Change

1. Windows build

MSI/NSIS installer via electron-builder. System tray, native notifications, auto-launch all handled by Electron cross-platform APIs. First-launch detects CockroachDB, guides install via Chocolatey or Scoop.

2. Linux build

AppImage (universal) + .deb (Debian/Ubuntu) + .rpm (Fedora/RHEL). Desktop entry file for app menu. Notifications via libnotify (Electron handles). Auto-launch via XDG autostart.

3. Native iOS app

React Native (recommended) or Swift. Connects to desktop via mDNS (Bonjour native on iOS). Same session token auth as #15 web mobile. Push notifications bridged from SSE. Swipe-to-approve UX. Background refresh for new approvals.

4. Native Android app

React Native (shared with iOS) or Kotlin. mDNS via Android NSD. Material Design approval cards. Notification channels per urgency level.

Framework recommendation: React Native with Expo

~80% code sharing, one codebase, ~3d total vs ~5d for native. Adequate for an approval-focused app.

Acceptance Criteria

1. Windows: MSI installer downloads → double-click → install wizard completes → SkyTwin appears in Start menu → launches to onboarding wizard
2. Windows: system tray icon with green/yellow/red status (same behavior as macOS — criteria from Desktop Electron app: native install, tray, process management #13 apply)
3. Windows: native Windows notification (toast) appears for new approval request within 5 seconds
4. Windows: `taskkill /F /IM skytwin-api.exe` → process restarts automatically (same supervision as macOS)
5. Windows: CockroachDB not found → dialog with Chocolatey install command + "Check Again" button
6. Linux AppImage: download → `chmod +x` → run → onboarding wizard loads (no root required)
7. Linux .deb: `sudo dpkg -i skytwin.deb` → installs → `skytwin` command available → launches from app menu
8. Linux: desktop notifications work on GNOME 42+ (Ubuntu 22.04) and KDE Plasma 5.27+
9. Linux: CockroachDB not found → dialog with apt/snap install command for detected distro
10. iOS: app opens → discovers `skytwin.local` via Bonjour within 5 seconds on same WiFi → shows "Found SkyTwin on your network" with connect button
11. iOS: QR scan from app camera → session paired → approval list loads → swipe right on card to approve → action confirmed on desktop within 2 seconds
12. iOS: app backgrounded → new approval created on desktop → push notification appears on phone within 10 seconds → tap opens app to approval
13. iOS: no network / desktop off → app shows "SkyTwin not found on your network" with retry button (not crash or blank screen)
14. Android: same feature parity as iOS (criteria 10-13 apply with Android equivalents)
15. Android: notification channels created: "Urgent Approvals" (heads-up), "Approvals" (standard), "Updates" (silent)
16. All platforms: session token auth matches Mobile local access: QR pairing, mDNS, responsive dashboard #15 specification — same token works in web mobile and native app
17. All 432 existing tests pass on macOS, Windows, and Linux
18. PR passes `/review` before merge

Testing Plan

Effort Estimate

• Windows electron-builder + platform adjustments: ~1h
• Linux electron-builder + .desktop + packages: ~1h
• React Native mobile app (shared core): ~3h
• iOS-specific (Bonjour, notifications, TestFlight prep): ~0.5h
• Android-specific (NSD, notification channels, APK): ~0.5h
• Cross-platform testing: ~1-2h

Total: ~5-8h Claude Code time

Files Reference

Out of Scope

• App Store / Google Play distribution (sideload + TestFlight for v0.4)
• Off-network mobile access
• Running the twin on the phone
• Tablet-optimized layout

Related

• Desktop Electron app: native install, tray, process management #13 — Desktop app (macOS, this extends to Windows/Linux)
• Mobile local access: QR pairing, mDNS, responsive dashboard #15 — Mobile local access (web mobile, this adds native apps)
• Part of v0.4 epic (Epic: SkyTwin v0.4 — Local-First Product Completion (HN Launch Ready) #12)

Working Context Protocol

During implementation, maintain two sources of truth to survive context compaction:

1. Local context file: Write progress, decisions, and blockers to .context/issue-16-cross-platform.md (gitignored). Update this file after each meaningful step. On compaction, re-read this file to restore state.
2. GitHub issue: Post progress comments on #16 at key milestones (subtask complete, blocker hit, design decision made). Reference the issue URL in your conversation so it persists across compaction: Cross-platform builds: Windows, Linux, native mobile apps #16

This ensures no quality loss across compaction events — the local file has granular state, the GitHub issue has durable history.