# Ticket 11.9 — iOS PWA Guided Install Flow

**Phase**: 11 — UI/UX Polish
**Priority**: Low
**Depends on**: None

## Description

claude-relay detects Safari on iOS and shows guided "Add to Home Screen" instructions with step-by-step visuals. conduit has full PWA support (manifest, service worker, icons) but no guidance for iOS users who need to manually install via Safari's Share → Add to Home Screen flow. Most users don't know this is possible.

Show a dismissible banner or prompt for iOS Safari users who haven't installed the PWA:
- Detect iOS Safari + not-standalone mode
- Show a one-time instructional prompt with the steps
- Include the Safari share icon and step numbers
- Persist dismissal in localStorage

## Acceptance Criteria

### AC1: iOS Safari users see the install prompt
```gherkin
Given the user is on iOS Safari and not in standalone (PWA) mode
And they have not previously dismissed the install prompt
When the page loads
Then a dismissible banner or prompt appears with "Add to Home Screen" instructions
```

### AC2: The prompt shows step-by-step instructions
```gherkin
Given the install prompt is visible
When the user reads the prompt
Then it displays numbered steps: (1) Tap the Share icon, (2) Scroll down, (3) Tap "Add to Home Screen"
And the Safari share icon is visually included
```

### AC3: Dismissal persists in localStorage
```gherkin
Given the install prompt is visible
When the user dismisses the prompt (close button or "Don't show again")
Then the prompt disappears
And a flag is written to localStorage
And on subsequent page loads the prompt does not appear
```

### AC4: PWA standalone users never see the prompt
```gherkin
Given the user has already installed the PWA and is in standalone mode
When the page loads
Then the install prompt is never rendered
```

### AC5: Non-iOS users never see the prompt
```gherkin
Given the user is on Android, Windows, macOS Chrome, or any non-iOS-Safari browser
When the page loads
Then the install prompt is never rendered
```

## Testable Components

| Component | Test Type | What to Assert |
|-----------|-----------|----------------|
| iOS Safari detection | Unit | User agent parsing correctly identifies iOS Safari vs other browsers |
| Standalone mode detection | Unit | `matchMedia('(display-mode: standalone)')` check returns correct boolean |
| Prompt rendering on iOS Safari | E2E | With iOS Safari user agent override, the install prompt appears |
| Dismissal persistence | Unit | Dismissing sets localStorage flag; subsequent checks return dismissed=true |
| Prompt hidden for non-iOS | E2E | With Chrome desktop user agent, the install prompt is not rendered |

## Reference

- claude-relay iOS PWA: `../claude-relay/lib/public/modules/notifications.js` (iOS Safari detection, Add to Home Screen instructions)
- PWA manifest: `conduit/src/lib/public/manifest.json`
- Service worker: `conduit/src/lib/public/sw.ts`
- DashboardPage standalone check: `conduit/src/lib/public/pages/DashboardPage.svelte`
