Last verified: June 2026 (based on actual screenshots from Randy's submissions)

This guide reflects the EXACT click paths in App Store Connect, Google Play Console, and Emergent — based on what we've actually seen on your screen. No guessing.

🎯 The Big Picture (do this in order every release)

1. Bump version & versionCode in app.json (Emergent code)
2. Click Publish in Emergent → pick platform → wait for build
3. Download the build file (.ipa for iOS / .aab for Android)
4. Upload to the appropriate store console
5. Fill in release notes + submit for review

🍎 PART 1: APPLE / iOS RELEASE

Step 1: Trigger the iOS build in Emergent

1. Click "Publish" (top-right of Emergent)
2. Choose "iOS"
3. The "Confirm details" dialog opens
4. Verify:

• App name: The Getting Ahead Guidebook
• Version name: auto-increments (e.g., 1.1.6 → 1.1.7)
• Bundle ID: com.thegettingaheadguidebook.app (should be auto-filled)

1. Click Continue → wait ~15–20 min for build
2. Emergent uploads the .ipa directly to App Store Connect → Build appears in TestFlight

Step 2: Wait for the build to process in App Store Connect

• Go to appstoreconnect.apple.com → Apps → The Getting Ahead Guidebook
• Click TestFlight tab → wait for the new build to finish "Processing" (~10–20 min)
• Email arrives when ready

Step 3: Create a new version (if you're going from 1.1.5 → 1.1.6)

1. Click the Distribution tab (top blue bar)
2. Left sidebar → click "+ iOS App" OR if "1.1.5" already exists in left sidebar, click "Add Platform" OR the "+" at the top of the version list
3. Enter the version number (e.g., 1.1.6) → click Create

Step 4: Fill in the new version page

On the iOS App Version page, scroll down and fill:

• "What's New in This Version" — type your release notes (e.g., "Bug fixes and performance improvements")
• Build section — click "+" or "Add Build" → select the build you just uploaded
• In-App Purchases section (if subscriptions changed) — click "+" → check both ☑️ GAG Monthly and ☑️ GAG Annual
• All other fields (screenshots, description, keywords) — leave as-is unless you're changing them

Step 5: Submit for review

1. Scroll to the top of the version page
2. Click the blue "Add for Review" or "Submit to App Review" button (top right)
3. Answer the export compliance questions (No encryption changes = answer "No")
4. Confirm → Status changes to 🟡 "Waiting for Review"

Step 6: Wait for Apple

• 24–48 hours typical (sometimes a few hours)
• You'll get an email when status changes
• If 🟢 Approved → app auto-releases (or "Pending Developer Release" if you set manual release)
• If 🔴 Rejected → check Resolution Center in App Store Connect for the reason

🚨 IAP (Subscription) Setup — Only do this ONCE per new subscription product

This is needed only when CREATING new IAP products (gag_monthly_v1, gag_annual_v1, etc.), not on every release. Skip this section if you're not adding/changing IAPs.

A. Go to your IAP product page:

1. App Store Connect → Apps → The Getting Ahead Guidebook
2. Left sidebar under MONETIZATION → Subscriptions
3. Click on your subscription group (e.g., GAG Premium)
4. Click on the product name (e.g., GAG Annual)

B. Set the price (THIS IS THE TRICKY PART):

1. On the product page, find "Set Up Availability" link (LEFT side, near top — NOT the "+" next to "Subscription Prices")
2. Click it → "Confirm Upfront Billing" dialog opens
3. Select United States + your price (e.g., $89.99 for Annual, $9.99 for Monthly)
4. Click Confirm → price is locked in worldwide

⚠️ The "+" next to "Subscription Prices" only shows Introductory/Promotional Offer options — DO NOT use that for the base price.

C. Add Localization (display name + description):

1. Scroll down to "Localization" section → click "Add Localization"
2. Select English (U.S.)
3. Display Name: GAG Annual (or whatever)
4. Description: Full annual access to The Getting Ahead Guidebook — budgeting, ledger, AI receipt scanning, and printable resources.
5. Click Save

D. Upload Review Screenshot:

1. Scroll to "Review Information" → Screenshot box
2. ⚠️ MUST be a tall rectangle (e.g., 1170×2532 — a normal iPhone screenshot). NOT 1024×1024 (Apple rejects squares — they're reserved for App Icons).
3. Easy way: Take a screenshot on your iPhone of the in-app paywall → AirDrop it to your Mac → upload here.

E. Verify status is "Ready to Submit":

• Status circle in the product list should now show 🟡 Ready to Submit

F. Attach to your app version (every release that includes new IAPs):

1. Go to Distribution → click your version (e.g., 1.1.6)
2. Scroll down to "In-App Purchases" section
3. Click "+" or "Edit" → check ☑️ the products you want included
4. Save → submit for review

🤖 PART 2: ANDROID / GOOGLE PLAY RELEASE

Step 1: Trigger the Android build in Emergent

1. Click "Publish" (top-right of Emergent)
2. Choose "Android"
3. The "Confirm details for your Android build" dialog opens
4. ⚠️ CRITICAL — Verify Android Package Name field:

• It should say: com.personalsolutionsnw.gettingaheadguidebook
• If it shows app.emergent.budgetplanner352d3f530e5 (Emergent's default placeholder) → STOP and email support@emergent.sh to unlock the field. Do NOT proceed — the build will be rejected by Google Play.

1. Other fields:

• App name: The Getting Ahead Guidebook
• Version name: auto-increments (e.g., 1.1.6, 1.1.7)

1. Click Continue → wait ~15–20 min for build
2. Download the .aab file when complete

Step 2: Open Google Play Console

1. Go to play.google.com/console
2. Click your app: The Getting Ahead Guidebook (package com.personalsolutionsnw.gettingaheadguidebook)
3. Click "View app →" on the right of the row

Step 3: Create a new Production release

1. Left sidebar → click "Test and release" (🚀 rocket icon)
2. The menu expands → click "Production"
3. Top right → click the blue "Create new release" button

Step 4: Upload the .aab

1. In the "App bundles" section, click the blue "Upload" link
2. Select your downloaded .aab file
3. Wait ~30 seconds for validation
4. ⚠️ If you see red error: "Your APK or Android App Bundle needs to have the package name com.personalsolutionsnw.gettingaheadguidebook" — the build came out with the wrong package name. Click the X to remove it, contact support@emergent.sh, and rebuild.

Step 5: Fill in release notes

Scroll down to "Release details" → in the "Release notes" box, paste (KEEP the XML language tags):

<en-US>
Subscription upgrades and improved checkout flow. Better support for tablets and foldable devices. Android compatibility improvements. Performance and stability fixes.
</en-US>

Step 6: Submit

1. Click the blue "Next" at the bottom
2. Step 2 shows "Preview and confirm"
3. Click the blue "Save and publish" or "Start rollout to Production"
4. Confirm the popup → Status changes to 🟡 "In review"

Step 7: Wait for Google

• A few hours to 7 days typical (usually <24 hrs after the first manual review)
• You'll get an email when reviewed
• If 🟢 Approved → rolls out automatically
• If 🔴 Rejected → check the email for the reason

📋 PART 3: VERSION NUMBERING RULES (don't break these)

⚠️ Google Play rejects uploads if versionCode is the same or lower than a previous release. ⚠️ Apple rejects uploads if buildNumber is the same as a previous build for the same version.

🛟 PART 4: WHEN THINGS GO WRONG — Who to Contact

🔗 PART 5: WEBHOOKS & PRODUCTION URLs (critical — read once, save forever)

⚠️ THE GOLDEN RULE

ALWAYS use app.thegettingaheadguidebook.com for any URL configured in a third-party dashboard (Stripe, Resend, Apple, etc.).

NEVER use the Emergent preview URL (budget-planner-352.preview.emergentagent.com) — it goes down whenever the dev container restarts and will cause silent failures + angry emails from Stripe.

Stripe Webhook URL (production)

https://app.thegettingaheadguidebook.com/api/subscriptions/webhook

To verify/update in Stripe:

1. Go to https://dashboard.stripe.com/webhooks
2. Check both Test mode and Live mode (toggle at top of dashboard)
3. Your webhook endpoint URL MUST be the production URL above (NOT a preview URL)
4. If it's wrong, click the webhook → "…" menu → Update details → fix URL → Save

Apple Server-to-Server Notifications V2

In App Store Connect → Apps → The Getting Ahead Guidebook → App Information → App Store Server Notifications:

Production Server URL:   https://app.thegettingaheadguidebook.com/api/iap/webhook
Sandbox Server URL:      https://app.thegettingaheadguidebook.com/api/iap/webhook
Notifications Version:   Version 2

Backend .env APP_URL (used for email links)

The backend has defensive code that auto-rewrites any preview/legacy URL to app.thegettingaheadguidebook.com at runtime — so even if your .env file is wrong, password reset emails and verification emails will still build correct links. But for cleanliness, the APP_URL should be:

APP_URL=https://app.thegettingaheadguidebook.com

Signs of a webhook problem

Watch for these — they're your warning signs:

• 📧 Email from support@stripe.com titled "We're having trouble…" about webhook failures
• 🔴 Stripe Dashboard → Webhooks → endpoint shows red "Failing" badge
• 📉 Backend logs show no incoming POST /api/subscriptions/webhook after a subscription event
• ⚠️ Users complete checkout but their subscription doesn't activate in your app
• 🆘 IAP receipts not auto-renewing in your DB after Apple sandbox tests

Quick check (paste in Terminal/browser):

To verify the webhook is reachable, run this from anywhere:

curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST https://app.thegettingaheadguidebook.com/api/subscriptions/webhook \
  -H "Content-Type: application/json" -d '{}'

You want to see 200 (or 400 if missing signature — both mean the endpoint is alive). A 404 means something is misconfigured.

🔐 PART 6: CRITICAL FACTS ABOUT THIS APP (memorize/print)

📅 PART 7: CHECKLIST BEFORE EVERY RELEASE

Before clicking Publish, verify:

• [ ] app.json → version is bumped (e.g., 1.1.5 → 1.1.6)
• [ ] app.json → android.versionCode is bumped (e.g., 16 → 17)
• [ ] No console errors when running the app in dev mode
• [ ] Tested the main user flow (sign in → view ledger → subscribe)
• [ ] Release notes drafted (paste-ready text)

After release:

• [ ] iOS submitted to App Review
• [ ] Android submitted to Play Production
• [ ] Both versions show 🟡 "In Review" or 🟡 "Waiting for Review"
• [ ] Email Randy at randywinsall@gmail.com when both are approved

End of Playbook. Keep this file open in a tab during releases. Print it if needed.