feat(gastown): Premier mobile experience — PWA, push notifications, and potential standalone mobile client

[jrf0110]

Vision

Gastown should be an absolutely premier mobile experience. Users should be able to manage their towns, chat with the Mayor, monitor agent progress, and receive real-time updates — all from their phone with a native-app feel.

Requirements

Phase 1: PWA Foundation

• Add a web app manifest (manifest.json) with proper icons, theme color, display mode (standalone)
• Add "Add to Home Screen" prompt/banner for iOS and Android
• Service worker for offline shell caching (the app shell loads instantly, data streams in)
• Splash screens for iOS and Android
• Viewport and touch optimizations across all gastown pages

Phase 2: Push Notifications

• Web Push API integration (service worker + push subscription)
• Notification triggers:
  • Convoy completed / landed
  • Bead failed (with failure reason)
  • Escalation created (medium+ severity)
  • Review ready (PR created, awaiting human review)
  • Budget threshold reached
  • Mayor @-mention or direct message
• Notification preferences page (per-notification-type toggle)
• Server-side: store push subscriptions per user, send via Web Push protocol from the worker
• Badge count on the PWA icon (unread notifications / active escalations)

Phase 3: Mobile-Optimized UI

• Audit and optimize all gastown pages for mobile viewports
• Touch-friendly interactions: swipe to dismiss drawers, pull-to-refresh, long-press context menus
• Mobile-specific navigation: bottom tab bar (Towns / Activity / Mayor Chat / Settings)
• Mayor chat optimized for mobile keyboards (input stays above keyboard, smooth scroll)
• Terminal view adapted for small screens (full-screen modal with pinch-to-zoom)
• Compact town cards for the overview page (feat(gastown): Redesign Overview page — town cards with sparklines, aggregate stats sidebar #1421)

Phase 4 (Evaluate): Standalone Mobile Client

• Evaluate whether a dedicated mobile web app (separate route tree, mobile-only layouts) provides a meaningfully better experience than responsive web
• If yes: create /m/ route prefix with mobile-specific page components, shared data layer
• Consider React Native / Capacitor wrapper if app store distribution becomes important
• Evaluate native gesture libraries (react-native-gesture-handler equivalent for web)

Non-Goals (for now)

• Native iOS/Android apps (too much overhead for the team size)
• Offline agent interaction (agents need server-side infrastructure)
• Mobile terminal input (watching is useful, typing commands from phone is not)

Design Principles

• Information density over chrome — mobile screens are small, every pixel matters. Show bead counts, agent status, and sparklines without requiring taps to drill in.
• Mayor chat is the primary mobile interaction — most mobile usage will be checking status via the Mayor, not editing settings or managing beads directly.
• Notifications are the killer feature — the phone buzzes when your convoy lands or an agent needs help. That's the value prop over just checking a dashboard.

References

• feat(gastown): Redesign Overview page — town cards with sparklines, aggregate stats sidebar #1421 — Overview page redesign (town cards with sparklines — mobile layout applies here)
• Real-time throughput gauges and timeseries — tokens/sec, cost/sec, gas tank #1297 — Real-time throughput gauges (mobile-friendly gauge variants)
• [Gastown] Onboarding Flow — Zero to Agent in Under 2 Minutes #229 — Onboarding flow (must work on mobile too)