Tunnel share UX: QR code + Add-to-Home-Screen + URL persistence

[kovtcharov]

Goal

Polish the tunnel share flow so getting GAIA on a phone is a 30-second flow ending with the app icon on the home screen — not a "copy this URL into Safari" flow. Builds on the diagnostics + cookie auth work in #872.

Why this matters for consumer adoption

The tunnel (#872) and the PWA (M1) only matter if a consumer can actually get from "GAIA is running on my laptop" to "GAIA is on my phone home screen" without friction. Today the flow is roughly: enable tunnel → copy URL → text to self → open on phone → bookmark or Add-to-Home-Screen. That's at least 5 manual steps with potential ngrok URL volatility.

Scope (single PR or two, v0.18.2)

A. Stable URL story

• Document the ngrok URL persistence story:
  • Free tier rotates URLs on every tunnel restart — bad for bookmarks
  • Paid tier supports reserved subdomains — recommended for consumers
• In the tunnel UX, surface a clear "Get a stable URL" CTA pointing to ngrok upgrade docs
• If user has a reserved subdomain configured, prefer it
• Alternative: support self-hosted reverse tunnel (Cloudflare Tunnel, FRP) as a power-user option

B. QR code share

• In Agent UI, when tunnel is enabled, surface a "Share to phone" button
• Generates a QR code containing the tunnel URL + a one-time auth token
• Phone scans QR → opens URL → cookie auth (feat(ui): friendly ngrok tunnel diagnostics + cookie auth for mobile #872) auto-applies via the token → user is in the app, authenticated, in <10 seconds
• Token expires after first use OR after 5 minutes (whichever first)

C. Add-to-Home-Screen guidance

• On first mobile visit (after QR or direct URL), show a one-time mobile-only banner: "Install GAIA on your home screen for the best experience"
• Platform-specific instructions: iOS (Safari Share → Add to Home Screen), Android Chrome (auto-prompt via M1's beforeinstallprompt)
• Dismissable

D. Tunnel state visibility on phone

• If the user opens the PWA on phone and the tunnel is offline (laptop asleep, ngrok down), show the friendly error from feat(ui): friendly ngrok tunnel diagnostics + cookie auth for mobile #872 plus "Wake up your laptop" instructions
• If known last-tunnel-URL no longer resolves, surface "Your tunnel URL changed; re-share from your laptop" with a clear path

E. Tunnel + cookie auth hardening

• Confirm the cookie auth from feat(ui): friendly ngrok tunnel diagnostics + cookie auth for mobile #872 works in PWA standalone mode (some service workers strip third-party cookies — needs first-party cookie strategy)
• Confirm cookie persists across PWA closes / reopens
• Test that the auth doesn't lock the user out when ngrok URL rotates (tie the cookie to the GAIA backend identity, not the ngrok hostname)

What this is NOT

• ❌ Not the tunnel itself (feat(ui): friendly ngrok tunnel diagnostics + cookie auth for mobile #872 owns that)
• ❌ Not the PWA shell (M1 owns that)
• ❌ Not native iOS / Android apps

Acceptance criteria

• A user with GAIA running on their laptop can get the app on their phone home screen, authenticated, in under 30 seconds via the QR flow
• Tunnel URL changes don't lock the user out of the existing PWA install
• Friendly error appears on phone when laptop is asleep / tunnel is down
• Cookie auth survives PWA close + reopen

Attribution / prior art

• ngrok (ngrok.com) — primary tunnel provider
• Cloudflare Tunnel — power-user alternative

Dependencies

• Blocked by: feat(ui): friendly ngrok tunnel diagnostics + cookie auth for mobile #872 (tunnel diagnostics + cookie auth — must land first), M1 (PWA shell)
• Adjacent: M2 (mobile-responsive UI), M4 (push notifications layer on top)