learning_ai_clock/ios/README_TESTFLIGHT.md

ChronoMind — TestFlight Release Guide

One-Time Setup (Home Laptop)

1. Install prerequisites

# 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

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:

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
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)

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 release-testflight.sh --skip-build

Custom API key location

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

cd ios
xcodegen generate

Build (simulator, no signing)

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

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

Export + Upload

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