scarf/scarf/scarf-ios/SETUP.md

# scarf-ios — Xcode target setup

This folder contains the source tree for the iOS app (`scarf-ios`), but
**not** the Xcode project file. Creating the `.xcodeproj` is a one-time
step you do in Xcode's UI — it's about 5 minutes, and doing it by hand
produces a project file that's definitely correct for whichever Xcode
version you're running, rather than a hand-edited pbxproj that might
drift from Xcode's expectations.

Everything the app needs — SSH key generation, Keychain storage,
onboarding state machine, Citadel-backed connection testing — already
lives in the shared SPM packages (`Packages/ScarfCore`,
`Packages/ScarfIOS`) and is exercised by 88 passing unit tests on
Linux CI. The Xcode target is mostly just a wrapper that assembles
those packages behind a `@main` SwiftUI app.

## One-time: create the Xcode target

1. Open **Xcode** → **File → New → Project…**
2. Choose **iOS → App**. Click Next.
3. Fill in:
   - **Product Name**: `scarf-ios`
   - **Team**: `3Q6X2L86C4` (the same team the Mac app uses for notarization)
   - **Organization Identifier**: `com.scarf`
   - **Interface**: **SwiftUI**
   - **Language**: **Swift**
   - **Storage**: **None** (no Core Data, no CloudKit)
   - **Include Tests**: unchecked (SPM covers them)
4. On the save-location sheet, navigate to `<repo>/scarf/` (the same
   level as `scarf.xcodeproj`) and hit **Create**.
5. Xcode produces `<repo>/scarf/scarf-ios/scarf-ios.xcodeproj` and a
   default source tree you'll immediately throw away.

## One-time: set project settings

In the **scarf-ios** project (target of the same name):

1. **General → Minimum Deployments → iPhone**: `iOS 18.0`.
2. **General → Supported Destinations**: keep **iPhone** only. Remove
   iPad + Mac Catalyst + Vision.
3. **Info → Bundle Identifier**: `com.scarf.scarf-ios`.
4. **Signing & Capabilities → Team**: `3Q6X2L86C4` (same as Mac).
5. **Build Settings → Swift Language Version**: `Swift 5` (matches
   the Mac app and both SPM packages).

## One-time: wire the SPM packages

1. **File → Add Package Dependencies…**
2. **Add Local…** button in the lower-left of the dialog.
3. Select `<repo>/scarf/Packages/ScarfCore`. Click **Add Package**.
4. Target to attach it to: **scarf-ios**. Click **Add Package**.
5. Repeat steps 1–4 for `<repo>/scarf/Packages/ScarfIOS`.
   - `ScarfIOS` already declares `Citadel` as a dependency — Xcode
     will resolve it automatically when you add the local package.
   - On first resolution expect a ~30s wait while Citadel +
     SwiftNIO-SSH fetch from GitHub.

## One-time: replace the default source tree

1. In Xcode's Project Navigator, delete the auto-generated files
   Xcode created for you:
   - `scarf_iosApp.swift` (or `scarf-iosApp.swift`)
   - `ContentView.swift`
   - **`Assets.xcassets`** — yes, delete this one too. We ship a
     pre-built `Assets.xcassets/` with the app icon + accent
     color inside `<repo>/scarf/scarf-ios/` that we'll add in the
     next step.
2. In Finder, open `<repo>/scarf/scarf-ios/`. Drag **App/**,
   **Onboarding/**, **Dashboard/**, and **`Assets.xcassets/`** onto
   the `scarf-ios` target in Xcode's navigator.
   - In the import sheet: **Create groups**, **Add to target:
     scarf-ios**.
3. Build (`⌘B`). It should compile cleanly against Citadel 0.12.1
   — every API call in `CitadelSSHService` was cross-checked
   against the 0.12.1 tag in April 2026. If you've bumped the pin
   to 0.13+ and something fails here, the likeliest culprit is
   `SSHAuthenticationMethod.ed25519(username:privateKey:)` being
   renamed or refactored; check the current
   `Sources/Citadel/SSHAuthenticationMethod.swift` in the new
   release.

## App icon + accent color

The `Assets.xcassets/` inside `<repo>/scarf/scarf-ios/` ships with:

- **`AppIcon.appiconset/AppIcon-1024.png`** — the 1024×1024 Scarf
  icon from the Mac app's icon set. iOS 14+ renders all smaller
  sizes automatically from the single 1024 image.
- **`AccentColor.colorset`** — a custom Scarf teal (`RGB
  0.227 / 0.525 / 0.722` in light mode; lighter `0.400 / 0.690
  / 0.902` in dark mode). If you want a different accent, swap
  the sRGB components in `Contents.json` or edit in Xcode's
  color picker.

## Info.plist additions for M2

None required. Citadel uses SwiftNIO, which doesn't need the
network-usage `Info.plist` key unless you hit local-network
discovery — which onboarding doesn't.

If you want to publish to TestFlight in M2, add these under
**Info → Custom iOS Target Properties**:

- `LSRequiresIPhoneOS = YES` (defaults to YES, usually already set)
- `UIApplicationSceneManifest → UIApplicationSupportsMultipleScenes = NO`
  (single-window for iPhone)
- `UILaunchScreen` — empty dictionary is fine.

## Smoke test the target

1. Pick an iPhone simulator (any iPhone running iOS 18+) and hit ⌘R.
2. You should see the onboarding flow: **Remote host** form → **SSH
   key** choice → **Generate** → **Show public key** → …
3. On **Show public key**, the OpenSSH line is selectable and
   copy-able. The text renders as `ssh-ed25519 AAAA… scarf-iphone-XXXX`.
4. Tap **I've added this key**. Onboarding calls `CitadelSSHService`
   to connect. With no real server, this will fail with
   `.hostUnreachable` — that's expected. You should land on the
   **Connection failed** screen with a "Retry" button.
5. Real end-to-end test: use a host you actually own, copy the shown
   public key into its `~/.ssh/authorized_keys`, tap Retry. You
   should reach the **Connected** state and then the placeholder
   **Dashboard** with a Disconnect button.

## TestFlight (still M2 — optional)

1. **Product → Archive** (select a physical iPhone or "Any iOS
   Device (arm64)" as the target).
2. **Window → Organizer → Archives → Distribute App → App Store
   Connect → Upload**. Uses your existing team signing setup.
3. First upload will trigger App Store Connect to create the app
   record if it doesn't exist. Give it `com.scarf.scarf-ios` and
   the same team.
4. After processing, invite testers from App Store Connect.

## What's *not* in M2

- Dashboard data (sessions, messages, stats) — **M3** adds a
  Citadel-backed `ServerTransport` so `HermesDataService` and friends
  work over SSH from iOS.
- Chat — **M4** adds an `SSHExecACPChannel` (the iOS counterpart to
  `ProcessACPChannel`) so `ACPClient` runs over a Citadel exec
  session.
- Memory editing, Cron, Skills, Settings — **M5**.
- Polish, App Store submission — **M6**.

## Troubleshooting

**Citadel fails to resolve.** Delete derived data (`~/Library/Developer/Xcode/DerivedData/scarf-ios-*`)
and `File → Packages → Reset Package Caches`, then rebuild.

**`SSHAuthenticationMethod` has no member `ed25519`.** Shouldn't
happen against Citadel 0.12.1 (verified), but historically the
private-key variant names have changed between minor versions
(0.7 → 0.9 → 0.12). See `CitadelSSHService.buildClientSettings(...)`
— there's one line to
update. Keep the protocol conformance intact.

**Keychain reads empty after relaunch.** Check that you haven't
accidentally set `kSecAttrAccessible` to a value that requires
biometric unlock — M2 uses `AfterFirstUnlockThisDeviceOnly` which
should always be readable.

**The shown public-key line doesn't match what OpenSSH generates
from the private key.** It won't — `scarf-ios` uses a compact
internal PEM shape for the private key (see `Ed25519KeyGenerator`
for the format). The **public** key is standard OpenSSH wire format
and is interop-safe with `authorized_keys`. If you want to export
the private key for use with `ssh`, that export flow is deferred
to a future phase.