> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mobile Quickstart
> From zero to your first TestFlight + Google Play upload in one session
This walkthrough takes you from a blank Hiveku account to a working iOS + Android app on TestFlight and Google Play Internal track. Plan \~60 minutes if you already have Apple Developer + Google Play accounts. Plan +24 hours if you're enrolling in Apple Developer Program for the first time (Apple's verification step).
## Before you start
You'll need:
* An Hiveku account (sign up at [app.hiveku.com](https://app.hiveku.com))
* An [Apple Developer Program](https://developer.apple.com/programs/enroll/) membership (\$99/year, paid to Apple)
* A [Google Play Developer](https://play.google.com/console/signup) account (\$25 one-time, paid to Google)
* A real phone with [Expo Go](https://expo.dev/go) installed (optional but recommended for testing OTA updates)
You can create the project and iterate in the phone-frame preview without these — they're only required when you want to actually ship to the app stores.
## Step 1 — Create the project
From the Hiveku dashboard, click **New Site**.
Pick the **Native Mobile** card (the cyan one with the smartphone icon). Enter a name — this becomes the slug in your Hiveku URL and shows up in the App Store listing as your initial app name.
Hiveku scaffolds the Expo project (\~30 files), provisions a per-project Supabase database, applies the seed schema (an `items` table with row-level security), and injects the Supabase keys into the project's `.env`. When the editor opens, you have a working Expo Router app with sign-in / sign-up / items CRUD already wired.
The **Getting Started** tab is selected by default. It shows a 7-step checklist that's the rest of this quickstart in compressed form.
## Step 2 — Run the preview
The phone-frame preview boots automatically. First-time boot takes 20-40 seconds (the Fly machine pulls the Expo Docker image and runs `expo start --web`). You'll see a "Starting your project..." splash, then the sign-in screen rendered inside an iPhone 15 Pro frame.
Try it out:
1. Tap **Sign up** in the preview, create a test user
2. Land on the empty items list
3. Tap **+ New** to create an item
4. Refresh — your item persists (proves Supabase auth + RLS are working end-to-end)
This is a real database. The user you just created and the item you just added are stored in the Supabase project Hiveku provisioned for you.
## Step 3 — Connect your Apple Developer account
On the **Mobile Credentials** tab, click into the iOS section. The inline 5-step guide walks the App Store Connect setup:
Open [appstoreconnect.apple.com/access/api](https://appstoreconnect.apple.com/access/api) → **Users and Access** → **Integrations** → **App Store Connect API**.
Click **Generate API Key**. Name it `Hiveku`. Set the role to **Admin** (recommended for first-time apps; can downgrade to App Manager after Hiveku registers your app record). Click Generate.
Apple gives you the `.p8` file as a one-time download. **Save it now** — Apple will not show it again. If you lose it, you have to revoke and regenerate.
The Issuer ID is at the top of the API Keys page (a UUID). The Key ID is shown in the row of the key you just created (10 characters).
At [developer.apple.com/account](https://developer.apple.com/account), under **Membership Details**. 10 characters.
Back in Hiveku, paste the .p8 file, Apple ID email, Apple Team ID, ASC API Key ID, and ASC Issuer ID. Click **Connect Apple Developer**.
Hiveku immediately runs preflight validation — it signs an ES256 JWT with your .p8 and hits Apple's `/v1/users` endpoint to confirm everything works. You should see a green "Credentials verified successfully" banner within 5 seconds. If you see red, the error message names exactly what's wrong (wrong role, malformed file, expired key) — fix and reconnect.
## Step 4 — Connect your Google Play account
Same Mobile Credentials page, Android section. The 5-step inline guide walks the Google Cloud + Play Console setup:
[console.cloud.google.com/iam-admin/serviceaccounts](https://console.cloud.google.com/iam-admin/serviceaccounts) → **Create Service Account**. Name it `hiveku-publisher`. No project roles needed at this step.
Open the service account → **Keys** → **Add Key** → **Create new key** → **JSON**. Save the JSON file.
[play.google.com/console](https://play.google.com/console) → **Setup** → **API Access** → link your Google Cloud project → grant the service account **Release Manager** role (must include "Release apps to production", "Manage releases", and "Manage testing tracks").
Play Console → **All apps** → **Create app**. Set the package name to the exact `com.hiveku.` value shown on the Mobile Credentials page in Hiveku. Google Play API can't create the very first version of an app — only updates, so this manual step is required once.
Back on Mobile Credentials, upload the JSON file, pick the initial Play track (default: **Internal testing**, safest), confirm auto-submit is on, click **Connect Google Play**.
Hiveku runs the same preflight validation: signs a JWT with the service account's private key, exchanges for a Google OAuth2 access token, and confirms it has Play Console access to the app you just created. Green banner = ready to build. Amber banner means the credentials are good but the app entry isn't in Play Console yet (loop back to step 4).
## Step 5 — Trigger your first build
Click the **Builds** tab. You'll see two cards:
* **Publish OTA Update** — for JS-only changes. We'll come back to this.
* **Native Build & Submit** — what we use for the first build.
In the Native Build card, pick **iOS + Android**, click **Build & Ship**.
Hiveku synthesizes an `eas.json` on the fly with your encrypted credentials, runs `eas init` to register the EAS project (if it's the first build), creates the iOS App Store record via the ASC API (saves you a manual step), and enqueues two builds (one per platform) at EAS.
You see the build IDs immediately. Status is "in-queue", then "in-progress". The `eas build` command exits as soon as EAS accepts the build — actual building happens on EAS infrastructure (\~20-30 minutes).
## Step 6 — Wait, and watch the email
Two ways to monitor:
* **Email** — when each build finishes (success, failure, or canceled), you get an email with the build status, link to the build artifact (if successful), and decoded error message (if failed). Subject line: `✓ iOS build finished — TaskWise` or `✗ iOS build failed — TaskWise`.
* **Builds page** — auto-refreshes every 15 seconds while a build is in progress. Status flips through `in-progress` → `success` → `submitted` (if auto-submit was on). Cancel button is available on in-progress rows if you change your mind.
When the build is done, the row also shows the **artifact size** (e.g. "📦 12.4 MB"). If your bundle exceeds 75 MB it shows in amber as a hint to audit native dependencies.
If something fails, see the next section.
## Step 7 — If a build fails
Open the failed row on the Builds page. The error message has been decoded from cryptic Apple/Google output (`ITMS-90013`, `PERMISSION_DENIED`, etc.) into something actionable. Often there's a **Fix with AI** button — click it.
This deeplinks to the AI chat with the error pre-loaded as your first message. The AI reads the relevant code files, proposes a fix, and applies it. You confirm, then click **Build & Ship** again. Subsequent builds reuse the existing EAS project, so kickoff is faster (\~10s instead of 60s for first-build init).
## Step 8 — See your app in the stores
When the build status flips to **submitted**:
* **iOS** — open [App Store Connect](https://appstoreconnect.apple.com) → **My Apps** → your app → **TestFlight** tab. The build appears within 5-15 minutes after submission (Apple processing time). Add yourself to the Internal Testing group → install via TestFlight on your phone.
* **Android** — open [Google Play Console](https://play.google.com/console) → your app → **Testing** → **Internal testing**. The release should be ready immediately. Add yourself as a tester → opt in via the link → install via Play Store.
You're now running your Hiveku-built app on a real phone, signed with your Apple Developer account and your Google Play account. The app is yours, in your store accounts, with you as the publisher of record.
## Step 9 — Iterate with OTA updates
Most subsequent changes don't need a 25-minute rebuild. JS-only changes (new screen, style change, Supabase query update, anything that doesn't add a native module) ship via OTA Update in \~30 seconds:
1. Edit code in the editor (or ask the AI to edit it)
2. Open Builds page → **Publish OTA Update** card
3. Pick channel: **Preview** (your testers only) or **Production** (live for everyone on production builds)
4. Click **Publish to preview**
Within \~30 seconds, the new bundle is on EAS. Open your Expo Go app on a real phone, refresh — you're running the new code.
When you're ready to promote a tested preview build to production, click the **Promote to production** button. Same code, different channel.
## What's next
Detailed reference for Apple + Google credential setup, with troubleshooting for common errors.
OTA channel deep-dive, the full Build & Ship lifecycle, and Fix-with-AI workflows.
All 11 devices, landscape mode, device colors — and which to test on.
AI-generate your app icon and listing copy in one form.