# ChronoMind — TestFlight Release Guide

## One-Time Setup (Home Laptop)

### 1. Install prerequisites

```bash
# Xcode (from App Store or xcodereleases.com)
xcode-select --install

# XcodeGen
brew install xcodegen
```

### 2. Clone sibling repos

The iOS app depends on `ByteLystPlatformSDK` from the common platform repo. Both repos must be siblings:

```
~/code/mygh/
├── learning_ai_clock/           # This repo
└── learning_ai_common_plat/     # ByteLystPlatformSDK lives here
```

```bash
cd ~/code/mygh
git clone https://github.com/saravanakumardb1/learning_ai_common_plat.git
```

### 3. App Store Connect API Key

The key is already created. Copy it from your work machine:

```bash
mkdir -p ~/.appstoreconnect/private_keys
# Copy AuthKey_PPATU9GL73.p8 to ~/.appstoreconnect/private_keys/
chmod 600 ~/.appstoreconnect/private_keys/AuthKey_PPATU9GL73.p8
```

| Field | Value |
|-------|-------|
| Key ID | `PPATU9GL73` |
| Issuer ID | `1dbc2980-1621-4fb9-940b-e28257e6322c` |

### 4. Create app in App Store Connect (one-time)

1. Go to [App Store Connect → My Apps](https://appstoreconnect.apple.com/apps)
2. Click **"+"** → **"New App"**
3. Fill in:
   - **Platform:** iOS
   - **Name:** `ChronoMind`
   - **Primary Language:** English (U.S.)
   - **Bundle ID:** `com.saravana.chronomind` (already registered)
   - **SKU:** `chronomind`
4. Click **Create**

---

## Release to TestFlight

### Quick release (one command)

```bash
cd ios
bash release-testflight.sh
```

This will:
1. Bump the build number in `project.yml`
2. Regenerate the Xcode project via `xcodegen`
3. Verify the debug build compiles
4. Archive a Release build
5. Export and upload to App Store Connect
6. Update `BUILD_STATE.md`
7. Commit and push

### Re-upload a failed upload

If the archive succeeded but upload failed:

```bash
bash release-testflight.sh --skip-build
```

### Custom API key location

```bash
ASC_KEY_ID=XXXX ASC_ISSUER_ID=yyyy ASC_KEY_PATH=/path/to/key.p8 bash release-testflight.sh
```

---

## Manual Steps (if script fails)

### Generate Xcode project

```bash
cd ios
xcodegen generate
```

### Build (simulator, no signing)

```bash
xcodebuild build \
  -project ChronoMind.xcodeproj \
  -scheme ChronoMind \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  CODE_SIGN_IDENTITY=- CODE_SIGNING_ALLOWED=NO
```

### Archive

```bash
xcodebuild archive \
  -project ChronoMind.xcodeproj \
  -scheme ChronoMind \
  -configuration Release \
  -archivePath /tmp/ChronoMind_1.xcarchive \
  -destination 'generic/platform=iOS'
```

### Export + Upload

```bash
xcodebuild -exportArchive \
  -archivePath /tmp/ChronoMind_1.xcarchive \
  -exportPath /tmp/ChronoMind_export1 \
  -exportOptionsPlist ExportOptions.plist \
  -allowProvisioningUpdates \
  -authenticationKeyPath ~/.appstoreconnect/private_keys/AuthKey_PPATU9GL73.p8 \
  -authenticationKeyID PPATU9GL73 \
  -authenticationKeyIssuerID 1dbc2980-1621-4fb9-940b-e28257e6322c
```

---

## Troubleshooting

| Error | Fix |
|-------|-----|
| `xcodegen not found` | `brew install xcodegen` |
| `ByteLystPlatformSDK not found` | Clone `learning_ai_common_plat` as sibling directory |
| `Authentication failed` | Check API key path, Key ID, and Issuer ID |
| `Error Downloading App Information` | Create the app record in App Store Connect first (see Setup §4) |
| `No signing certificate "iOS Distribution"` | Use `-allowProvisioningUpdates` with API key (script does this) |
| `App Groups capability` | Register App Group in developer portal, or remove entitlement for initial release |
| `duplicate 'init(hex:alpha:)'` | Remove duplicate `Color.init(hex:)` from `ChronoMindTheme.generated.swift` |

---

## Project Info

| Field | Value |
|-------|-------|
| Bundle ID | `com.saravana.chronomind` |
| Team ID | `748N7QPX7J` |
| Min iOS | 17.0 |
| Xcode | 16.0+ |
| Swift | 5.9 |