scarf/releases/v2.5.0/TESTFLIGHT_CHECKLIST.md

# v2.5 TestFlight submission checklist

Pre-flight steps to take ScarfGo to public TestFlight. Order matters — Apple review wants the privacy URL to resolve at submission time, and the build needs to upload before review can start.

## 0. Apple Developer Program prerequisites

- Apple Developer Program enrollment active (team `3Q6X2L86C4`).
- iOS Distribution certificate in login Keychain (`Apple Distribution: Alan Wizemann`).
- App Store provisioning profile for the iOS bundle ID (auto-managed in Xcode is fine).
- App Store Connect access for the team.

## 1. Privacy policy live

- [ ] Copy `scarf/docs/PRIVACY_POLICY.md` content into `.gh-pages-worktree/privacy/index.html` (wrap in minimal HTML, or leave as Markdown if GitHub Pages renders Markdown — GitHub Pages with Jekyll does).
- [ ] `cd .gh-pages-worktree && git add privacy/index.html && git commit -m "docs(privacy): publish v2.5 policy" && git push`
- [ ] Verify https://awizemann.github.io/scarf/privacy/ resolves (give it ~1 min after push).

The privacy URL is required by App Store Connect before submitting for Beta App Review. Without it the submission button is disabled.

## 2. Xcode target configuration

Open `scarf/scarf.xcodeproj`, select the `scarf mobile` target.

- [ ] Signing & Capabilities → "Automatically manage signing" ON, team set to `3Q6X2L86C4`.
- [ ] Capabilities present: Keychain Sharing only. **Push Notifications stays OFF** — `NotificationRouter.apnsEnabled = false` and the entitlement is absent. Match the two: enable both later together.
- [ ] Info.plist sanity:
  - Bundle Identifier matches App Store Connect record.
  - `LSApplicationCategoryType = public.app-category.developer-tools`.
  - `NSAppTransportSecurity` allows the SSH ports the app dials? — N/A for SSH (raw TCP); ATS only governs HTTPS. Skip.

## 3. Version bump

The version bump runs automatically via `./scripts/release.sh 2.5.0` in Phase G. Do NOT bump `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION` manually before that — the script writes the version commit and reads `CURRENT_PROJECT_VERSION` to compute the next build number.

## 4. Archive + upload

- [ ] Xcode → Product → Scheme → `scarf mobile`.
- [ ] Destination → "Any iOS Device (arm64)".
- [ ] Product → Archive. Wait for build (~3-5 min).
- [ ] Organizer opens automatically. Select the archive → Distribute App.
- [ ] Distribution method: **App Store Connect**.
- [ ] Destination: **Upload**.
- [ ] Distribution options: leave defaults (manage versioning automatically; include bitcode if offered = N/A on Xcode 14+; strip Swift symbols ON).
- [ ] Re-sign: automatic.
- [ ] Upload. Apple processes the binary (~5-15 min); App Store Connect emails when ready.

## 5. App Store Connect metadata (TestFlight tab)

Once the binary is processed:

- [ ] **App information** (one-time, persists across builds):
  - Subtitle: "On-the-go Hermes companion"
  - Privacy policy URL: https://awizemann.github.io/scarf/privacy/
  - Category: Developer Tools
  - Age rating: 4+ (no restricted content)
- [ ] **Test information** (per-build is fine, persists if not changed):
  - Beta App Description (paragraph): see "Beta description copy" below.
  - Email: alan@wizemann.com
  - Beta App Review information: account credentials only if the app required them — N/A (BYO Hermes host).
  - Marketing URL (optional): https://github.com/awizemann/scarf
- [ ] **What to test** (per-build):
  ```
  v2.5.0 — first public TestFlight build of ScarfGo. Try connecting to a
  Hermes host (you'll need an SSH-reachable Hermes install). Test:
  - Onboarding + Add a second server
  - Project-scoped chat
  - Session resume from Dashboard
  - Sessions tab project filter
  - Forget a server / re-onboard
  Known limitations: no push, no in-app Settings editor, English only.
  Report issues via TestFlight feedback.
  ```

### Beta description copy

> ScarfGo is the iOS companion to Scarf, the Mac client for the Hermes AI agent. Connect to a Hermes server you operate (Mac, Linux, or any SSH-reachable host) and run sessions, browse memory, manage cron jobs, and resume conversations from your phone. All data stays between your device and your Hermes host — no developer servers in between.

## 6. Submit for Beta App Review

- [ ] TestFlight tab → External Testers → Add a public group called "Public Beta".
- [ ] Add the new build to the group.
- [ ] Click **Submit for Review**.
- [ ] Apple's Beta Review queue is typically 24-48h.

## 7. After approval

- [ ] Apple issues a public TestFlight URL (`https://testflight.apple.com/join/XXXXXX`).
- [ ] Record the URL — needed in Phases E (wiki ScarfGo page) and F (README v2.5 section).
- [ ] **DO NOT** publicize it yet. Update wiki + README in branches first; the user (Alan) decides when to push live.

## Rollback

If a build breaks on TestFlight:

- [ ] Disable the build in App Store Connect → TestFlight → Builds → Expire.
- [ ] Fix the bug, archive a new build with the same `MARKETING_VERSION` (Apple requires the build number — `CURRENT_PROJECT_VERSION` — to monotonically increase).
- [ ] Upload + add to Public Beta group + submit if Apple flagged the prior build for re-review.

## Open items / future TestFlight builds

- **Push notifications** — flip `NotificationRouter.apnsEnabled = true` simultaneously with: enabling the Push Notifications capability, generating an APNs auth key, deploying the Hermes-side push sender. Stops being a no-op only when all three exist.
- **iPad support** — `.tabViewStyle(.sidebarAdaptable)` is wired but iPad layout hasn't been smoke-tested. Probably free, but verify before flipping the iPad flag in the target.
- **Localization** — English only for v1. Mac ships 7 languages; iOS strings are extracted but no translations.