aiblueprint-cli 1.4.79 → 1.4.81

package/agents-config/skills/appstore-connect/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: appstore-connect
+description: Interact with App Store Connect via the asc CLI - apps, builds, TestFlight, beta testers, reviews, sales/analytics, metadata, IAP, signing, submissions. Use for "check my app", "App Store Connect", "TestFlight status", "app review", "my app sales", or "asc".
+---
+
+# App Store Connect (asc)
+
+Read, manage, and ship any of the user's App Store apps through the **`asc`** CLI (App Store Connect CLI by Rork). `asc` covers nearly the entire ASC surface; reach for the raw API only for the rare gap.
+
+<auth>
+`asc` is already authenticated on this machine (a default keychain profile). Verify before doing real work:
+
+```bash
+asc auth status            # shows stored credential profiles + which is default
+asc auth status --validate # confirms a credential actually works
+asc doctor                 # diagnose auth/config issues
+```
+
+- Multiple accounts/teams: `asc --profile <name> <command>` selects a profile.
+- A NEW account with no stored key: run the `appstore-connect-setup` skill (locates the `.p8`, key id, and issuer id, then `asc auth login`). Never print or commit `.p8` keys, key ids, or issuer ids.
+</auth>
+
+<how_to_drive>
+Do NOT guess flags. `asc` is large and self-documenting — discover, then act:
+
+```bash
+asc --help                 # the full command map (areas below)
+asc <area> --help          # subcommands + flags for an area, e.g. `asc builds --help`
+asc docs list              # embedded guides; `asc docs <topic>` to read one
+```
+
+- **Read before you write.** List/inspect/validate first; mutate second.
+- **Machine output:** most commands accept `--output json` (or `--output table` for humans) — use JSON when you need to parse ids.
+- Resolve an app id once and reuse it: `asc apps list --output json` → the numeric App Store app id.
+</how_to_drive>
+
+<command_map>
+| Goal | Area |
+| --- | --- |
+| List/inspect apps, app id | `asc apps`, `asc status --app <id>` |
+| Builds (processing, ids) | `asc builds` |
+| TestFlight: beta groups, testers, distribute a build | `asc testflight` |
+| Versions / release state | `asc versions`, `asc release`, `asc status` |
+| Metadata, localizations, keywords | `asc metadata`, `asc localizations` |
+| Screenshots / previews | `asc screenshots`, `asc video-previews` |
+| Pricing & availability | `asc pricing` |
+| In-app purchases / subscriptions | `asc iap`, `asc subscriptions` |
+| Age rating / privacy / encryption / EULA | `asc age-rating`, `asc encryption`, `asc eula` |
+| Submission readiness + submit | `asc validate`, `asc review`, `asc submit`, `asc publish` |
+| Customer reviews | `asc reviews` |
+| Sales / analytics / finance | `asc analytics`, `asc insights`, `asc finance`, `asc performance` |
+| Signing: certs, profiles, bundle ids | `asc signing`, `asc certificates`, `asc profiles`, `asc bundle-ids` |
+| Team / users / devices | `asc users`, `asc devices`, `asc account` |
+| Xcode Cloud, webhooks, workflows | `asc xcode-cloud`, `asc webhooks`, `asc workflow` |
+</command_map>
+
+<common_tasks>
+```bash
+# What apps do I have / what's an app's id?
+asc apps list --output table
+
+# Where is an app in the release pipeline?
+asc status --app <APP_ID> --output table
+
+# Latest builds and processing state
+asc builds list --app <APP_ID> --output json
+
+# TestFlight: see groups, add a tester, distribute a build
+asc testflight groups list --app <APP_ID>
+asc publish testflight --app <APP_ID> --ipa <path.ipa> --group "<GROUP_ID>" --wait
+
+# Is a version ready to submit? (fix every error it reports first)
+asc validate --app <APP_ID> --version <VERSION> --platform IOS --output table
+
+# Read customer reviews / respond
+asc reviews list --app <APP_ID> --output table
+
+# Sales & analytics
+asc analytics --help        # request/download reports
+asc insights --help         # weekly/daily insights
+```
+</common_tasks>
+
+<safety>
+- **Confirm before any mutation that is externally visible or hard to reverse:** `asc submit`, `asc publish ... --submit`, `asc review submit`, `asc pricing` changes, `asc iap`/`asc subscriptions` edits, `asc users` invites/removals, certificate/profile deletion. State the app id, version, and exact change, and get explicit user approval.
+- Prefer dry runs / validation first: many commands accept `--dry-run`; always run `asc validate` before submitting.
+- Never delete a signing certificate or provisioning profile without confirmation — it can break other apps signed with it.
+- Never print or commit `.p8` keys, key ids, issuer ids, app-specific passwords, or downloaded financial reports with PII.
+- This skill manages the store side only. Producing the build (.ipa/.aab) and project config belongs to the app's own deploy workflow.
+</safety>
+
+<raw_api_fallback>
+For the rare endpoint `asc` doesn't expose, call the App Store Connect API directly with the bundled helper (zero deps, ES256 JWT). Credentials come from env vars — never hardcode them:
+
+```bash
+export ASC_KEY_ID=...        # 10-char key id (from the AuthKey_<KEY_ID>.p8 filename)
+export ASC_ISSUER_ID=...     # team issuer UUID (App Store Connect > Users and Access > Integrations)
+export ASC_P8_PATH=/path/to/AuthKey_<KEY_ID>.p8
+node "$SKILL_DIR/scripts/asc-api.mjs" GET "/v1/apps?filter[bundleId]=com.example.app"
+node "$SKILL_DIR/scripts/asc-api.mjs" POST /v1/betaGroups body.json
+```
+
+`$SKILL_DIR` is this skill's directory. The helper prints `{"status", "body"}` and exits non-zero on HTTP >= 400.
+</raw_api_fallback>

package/agents-config/skills/appstore-connect/scripts/asc-api.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Minimal App Store Connect API client. Zero dependencies.
+ * Used by the setup-testflight / deploy-ios-app skills to manage certificates,
+ * provisioning profiles, beta groups, and testers without the web UI.
+ *
+ * Credentials come from env vars (never hardcode them):
+ *   ASC_KEY_ID     - 10-char API key ID (from the AuthKey_<KEY_ID>.p8 filename)
+ *   ASC_ISSUER_ID  - team issuer UUID (App Store Connect > Users and Access > Integrations)
+ *   ASC_P8_PATH    - absolute path to the AuthKey_*.p8 private key file
+ *
+ * Usage:
+ *   node scripts/asc-api.mjs GET "/v1/apps?filter[bundleId]=com.example.app"
+ *   node scripts/asc-api.mjs POST /v1/betaGroups body.json
+ *   node scripts/asc-api.mjs DELETE /v1/profiles/<id>
+ *
+ * Prints {"status": <http status>, "body": <json|null>} on stdout.
+ * Exits non-zero on HTTP >= 400 so shell scripts can chain safely.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+const KEY_ID = process.env.ASC_KEY_ID;
+const ISSUER_ID = process.env.ASC_ISSUER_ID;
+const P8_PATH = process.env.ASC_P8_PATH;
+
+if (!KEY_ID || !ISSUER_ID || !P8_PATH) {
+  console.error(
+    "Missing credentials. Set ASC_KEY_ID, ASC_ISSUER_ID, and ASC_P8_PATH env vars.\n" +
+      "Key ID is in the .p8 filename (AuthKey_<KEY_ID>.p8); issuer ID is in\n" +
+      "App Store Connect > Users and Access > Integrations > App Store Connect API.",
+  );
+  process.exit(2);
+}
+if (!fs.existsSync(P8_PATH)) {
+  console.error(`ASC_P8_PATH not found: ${P8_PATH}`);
+  process.exit(2);
+}
+
+const b64url = (buf) =>
+  Buffer.from(buf)
+    .toString("base64")
+    .replace(/=/g, "")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+
+function makeJwt() {
+  const header = { alg: "ES256", kid: KEY_ID, typ: "JWT" };
+  const now = Math.floor(Date.now() / 1000);
+  const payload = {
+    iss: ISSUER_ID,
+    iat: now,
+    exp: now + 900,
+    aud: "appstoreconnect-v1",
+  };
+  const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  const key = crypto.createPrivateKey(fs.readFileSync(P8_PATH, "utf8"));
+  const sig = crypto.sign("sha256", Buffer.from(signingInput), {
+    key,
+    dsaEncoding: "ieee-p1363",
+  });
+  return `${signingInput}.${b64url(sig)}`;
+}
+
+const [method, apiPath, bodyFile] = process.argv.slice(2);
+if (!method || !apiPath) {
+  console.error("usage: asc-api.mjs <GET|POST|PATCH|DELETE> </v1/...> [bodyFile.json]");
+  process.exit(2);
+}
+
+const res = await fetch(`https://api.appstoreconnect.apple.com${encodeURI(apiPath)}`, {
+  method: method.toUpperCase(),
+  headers: {
+    Authorization: `Bearer ${makeJwt()}`,
+    "Content-Type": "application/json",
+  },
+  body: bodyFile ? fs.readFileSync(bodyFile, "utf8") : undefined,
+});
+
+const text = await res.text();
+let body = null;
+try {
+  body = text ? JSON.parse(text) : null;
+} catch {
+  body = { raw: text.slice(0, 2000) };
+}
+console.log(JSON.stringify({ status: res.status, body }, null, 2));
+if (res.status >= 400) process.exit(1);

package/agents-config/skills/appstore-connect-setup/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: appstore-connect-setup
+description: Find and configure App Store Connect API credentials for asc auth. Use when asc auth is missing, credentials are unknown, the user says login to App Store Connect, or before TestFlight/App Store release work.
+---
+
+# App Store Connect Setup
+
+<objective>
+`asc auth login` needs three things: a **key ID**, an **issuer ID**, and a **.p8 private key file**. Users rarely remember where these are. This skill is a battle-tested workflow for finding all three without asking the user to dig through App Store Connect manually.
+
+Key insight from a real session: the `.p8` files and key IDs live on disk, but the **issuer ID is almost never stored locally** — it only exists in the App Store Connect web UI. The trick is to read it from the user's already-signed-in browser session via CDP, since Apple login requires 2FA and cannot be automated.
+</objective>
+
+<credentials_anatomy>
+| Credential | What it looks like | Where it lives |
+| --- | --- | --- |
+| Key ID | 10 chars, e.g. `T397KWC8K7` | In the `.p8` filename: `AuthKey_<KEY_ID>.p8` |
+| Issuer ID | UUID, e.g. `35b197bd-...` | App Store Connect → Users and Access → Integrations → App Store Connect API (top of Keys page). Team-level, same for all keys. |
+| Private key | `AuthKey_*.p8` file, ~257 bytes | User's disk — Downloads is the most common spot (Apple only lets you download it once) |
+
+Beware look-alikes that are NOT API auth keys:
+- `SubscriptionKey_*.p8` — in-app purchase key, won't work for `asc auth login`.
+- `.p8` files for APNs (push notifications).
+</credentials_anatomy>
+
+<step n="1" title="Check if already authenticated">
+
+```bash
+asc auth status --validate
+```
+
+If a credential validates as "works", stop — nothing to do.
+</step>
+
+<step n="2" title="Hunt for .p8 files on disk">
+
+```bash
+# Standard locations first
+ls ~/.asc ~/private_keys ~/.appstoreconnect/private_keys 2>/dev/null
+
+# Then the places people actually put them (Downloads wins in practice)
+find ~/Downloads ~/Documents ~/Desktop ~/Developer -maxdepth 5 -name "*.p8" 2>/dev/null
+```
+
+Real finding: keys were in `~/Downloads/AuthKey_X.p8` and `~/Downloads/Dev/AuthKey_Y.p8`, downloaded months earlier. The key ID is the filename suffix.
+</step>
+
+<step n="3" title="Try to find the issuer ID locally (usually fails)">
+
+Worth 30 seconds, but expect nothing:
+
+```bash
+grep -riE "issuer" ~/Developer --include="*.json" --include="*.env*" --include="*.rb" --include="*.yml" -l 2>/dev/null | grep -v node_modules
+grep -iE "issuer" ~/.zsh_history 2>/dev/null
+grep -ri "issuer" ~/.fastlane ~/.expo 2>/dev/null
+```
+
+Real finding: zero hits across the entire `~/Developer` tree, shell history, fastlane and expo config. Docs in repos only contain `ISSUER_ID` placeholders. **Do not burn time here — go to step 4.**
+</step>
+
+<step n="4" title="Read the issuer ID from the user's signed-in browser (the key move)">
+
+Apple login = password + 2FA, so never try to log in yourself. Instead, attach to the browser where the user is **already signed in** and read the page.
+
+**4a. Confirm with the user** which browser is signed in to App Store Connect (Chrome, Helium, etc.).
+
+**4b. Check if the browser exposes CDP:**
+
+```bash
+curl -s http://127.0.0.1:9222/json/version   # Chrome default
+curl -s http://127.0.0.1:9334/json/version   # custom port
+```
+
+**4c. If not (the usual case), quit and relaunch it with a debug port.** Session cookies survive a graceful quit, and `--restore-last-session` brings the tabs back:
+
+```bash
+osascript -e 'quit app "Helium"'   # or "Google Chrome"
+sleep 3
+nohup "/Applications/Helium.app/Contents/MacOS/Helium" --remote-debugging-port=9334 --restore-last-session >/dev/null 2>&1 &
+sleep 5
+curl -s http://127.0.0.1:9334/json/version | head -3   # must answer before continuing
+```
+
+**4d. Navigate to the API keys page and extract the issuer ID:**
+
+```bash
+dev-browser --browser helium --connect http://127.0.0.1:9334 --timeout 60 <<'EOF'
+const page = await browser.getPage("asc");
+await page.goto("https://appstoreconnect.apple.com/access/integrations/api", { waitUntil: "domcontentloaded" });
+await page.waitForTimeout(8000);
+const text = await page.evaluate(() => document.body.innerText);
+const m = text.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+console.log(JSON.stringify({ issuerId: m ? m[1] : null, loggedOut: page.url().includes("/login") }));
+EOF
+```
+
+If `loggedOut` is true, ask the user to sign in in that browser window, then re-run.
+
+**4e. Cross-check which keys are actually ACTIVE.** The same page lists active keys with their key IDs. A `.p8` found on disk may belong to a revoked key — match the filename key ID against the active list before using it:
+
+```bash
+dev-browser --browser helium --connect http://127.0.0.1:9334 --timeout 30 <<'EOF'
+const page = await browser.getPage("asc");
+const text = await page.evaluate(() => document.body.innerText);
+console.log(text);  // active keys table: NAME / KEY ID / LAST USED / ACCESS
+EOF
+```
+
+Real finding: the first `.p8` we picked (`AuthKey_6QD5RMPU9F.p8`) was NOT in the active list — login would have failed. The second one matched an active Admin key and worked.
+</step>
+
+<step n="5" title="Organize keys, then log in">
+
+Move keys to the canonical folder so the next agent finds them instantly:
+
+```bash
+mkdir -p ~/Developer/app-store
+mv ~/Downloads/AuthKey_*.p8 ~/Developer/app-store/ 2>/dev/null
+chmod 600 ~/Developer/app-store/*.p8
+```
+
+Then authenticate and verify end-to-end.
+
+**Naming the credential:** use a stable, descriptive name tied to the machine + user, not the app — the same ASC API key is team-level and works across every app, so naming it per-app is misleading. Convention: `asc-macos-<user>-key` (e.g. `asc-macos-melvynx-key`). **Prefer a key with Admin access** when several active keys exist (Admin can read/write everything the release flow needs); check the ACCESS column from step 4e and pick the Admin key.
+
+```bash
+asc auth login \
+  --name "asc-macos-melvynx-key" \
+  --key-id "KEY_ID" \
+  --issuer-id "ISSUER_ID" \
+  --private-key ~/Developer/app-store/AuthKey_KEY_ID.p8 \
+  --network
+
+asc auth status --validate   # must report "works"
+asc apps list                # must list the target app
+```
+</step>
+
+<step n="6" title="Persist the findings">
+
+Record in the agent memory / AGENTS.md so this hunt never happens twice:
+
+- The keys folder (`~/Developer/app-store/`), each key ID and whether it is active
+- The issuer ID (team-level, stable)
+- The `asc` credential name (convention `asc-macos-<user>-key`), its access level (prefer Admin), and that it is stored in the system keychain
+- The app's numeric App Store Connect ID and bundle ID from `asc apps list`
+</step>
+
+<critical_safety>
+- Never commit `.p8` files or paste their contents anywhere. `chmod 600` them.
+- Never attempt the Apple login form yourself — 2FA makes it pointless and looks like account takeover. Always reuse the user's signed-in session, with their explicit OK to attach to/restart their browser.
+- Restarting the browser closes the user's windows; warn them and rely on session restore.
+</critical_safety>
+
+<success_criteria>
+- `asc auth status --validate` reports the credential as "works".
+- `asc apps list` returns the expected app(s).
+- Keys live in `~/Developer/app-store/` and the findings are written to memory/AGENTS.md.
+</success_criteria>

package/agents-config/skills/ios-testflight/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: ios-testflight
+description: Build a NowStack Mobile iOS app and upload it to TestFlight. Defaults to local `eas build --local`; use `--expo` only when the user explicitly wants an EAS cloud build.
+---
+
+# iOS TestFlight - NowStack Mobile
+
+Take a working NowStack Mobile app from local dev to an installable TestFlight build. Run phases A-D for setup only (stop before the build, report readiness); run all phases end to end to build and upload. This is the iOS beta surface; for App Store review use `ns-ios-distribute`.
+
+Default build mode is **local Mac build** with `eas build --local`, so it does not consume Expo/EAS cloud build credits. If the user passes `--expo`, opt into the EAS cloud build path instead.
+
+<objective>
+Go from "the app works in the simulator" to "a build is installable from TestFlight" with maximum automation. Default to the local Mac build path to preserve Expo cloud credits; use `--expo` only when the user asks for a cloud build. Everything used here ships in this repo or is a public CLI (`eas-cli`, `asc`, `openssl`, `node`).
+
+The proven flow (battle-tested on a real app built from this boilerplate):
+
+1. Create the EAS project and wire `easProjectId` into `site-config.ts`.
+2. Deploy Convex to production and set prod env vars.
+3. Point `eas.json` production env at the prod Convex URLs.
+4. Create Apple signing credentials (distribution cert + App Store provisioning profile) through the **App Store Connect API** using `mobile-app/scripts/asc-api.mjs` — no browser, no Apple ID 2FA.
+5. Run a local signed App Store IPA build with `eas build --local`, `credentialsSource: "local"`, and an explicit `--output /tmp/{slug}.ipa`.
+6. Upload the `.ipa` to TestFlight with `asc publish testflight` into an internal beta group.
+
+The key insight: interactive `eas build` credential setup requires Apple ID 2FA and cannot be automated reliably. The ASC API key path avoids 2FA entirely, and local `eas build --local` avoids Expo cloud build credits while still using the same local signing files.
+</objective>
+
+<arguments>
+- Default / no flag: run setup, local build, upload, and verify.
+- `--expo`: use the EAS cloud build phase instead of local build. This consumes Expo/EAS build quota and requires explicit user confirmation.
+- Setup-only requests (`ios setup`, "prepare TestFlight", "credentials only"): run phases A-D, then stop before any build/upload.
+</arguments>
+
+<prerequisites>
+The user must have (ask once, as a group — these cannot be created by the agent):
+
+1. **Apple Developer Program membership** (paid, enrolled).
+2. **App Store Connect API key**: the `AuthKey_<KEY_ID>.p8` file, its key ID, and the team issuer ID. If unknown, run the `appstore-connect-setup` skill, or point the user to App Store Connect > Users and Access > Integrations > App Store Connect API (key must have Admin or App Manager role).
+3. **Expo account** logged in: `npx eas-cli@latest whoami` (else `npx eas-cli@latest login`).
+4. **App record in App Store Connect** for the bundle ID. The public API cannot create app records — if missing, the user creates it once at appstoreconnect.apple.com (My Apps > + > New App, selecting the bundle ID). Verify with Phase D step 1 and stop with clear instructions if absent.
+5. `asc` CLI installed (`brew install asc`) — used only for the final upload; everything else goes through `scripts/asc-api.mjs`.
+6. For the default local build: macOS with Xcode command line tools and CocoaPods (`xcodebuild -version`, `command -v pod`). If those are unavailable, stop and ask whether to use `--expo`.
+</prerequisites>
+
+<state_variables>
+| Variable | Source |
+| --- | --- |
+| `{bundle_id}` | `SiteConfig.bundleId` |
+| `{apple_team_id}` | `SiteConfig.appleTeamId` |
+| `{eas_project_id}` | output of `eas project:init`, then written to `site-config.ts` |
+| `{asc_key_id}` / `{asc_issuer_id}` / `{asc_p8_path}` | from the user / `appstore-connect-setup`. Never commit, never print. |
+| `{convex_prod_url}` / `{convex_prod_site_url}` | from `npx convex deploy` output / Convex dashboard |
+| `{asc_app_id}` | numeric app ID resolved from the bundle ID (Phase D) |
+| `{build_mode}` | default `local`; `expo` only when the user passes `--expo` |
+| `{ipa_path}` | `/tmp/{slug}.ipa` from local build, or downloaded cloud artifact |
+</state_variables>
+
+<critical_safety>
+- Never commit or print `.p8` keys, `.p12` files, p12 passwords, provisioning profiles, or `credentials.json`. The repo `.gitignore` already excludes them — verify before any commit.
+- Export ASC credentials as env vars for `scripts/asc-api.mjs`; do not write them into files inside the repo.
+- Get explicit user confirmation before: creating Apple certificates (accounts have a low cert limit), using `--expo` cloud EAS builds (consumes build credits), and the TestFlight upload.
+- Local builds do not consume Expo cloud credits, but they still sign a production App Store IPA and may increment the remote EAS build number when `appVersionSource` is `remote`.
+- Builds bake env vars in permanently: confirm `eas.json` points at the PROD Convex deployment before building, or testers ship with a dev backend.
+</critical_safety>
+
+<phase n="A" title="Preflight">
+From the repo root:
+
+```bash
+npm run check-setup          # must be free of errors (easProjectId warning is expected pre-init)
+cd mobile-app && npx tsc --noEmit && npm run lint
+npx eas-cli@latest whoami    # Expo account logged in?
+command -v asc && asc version
+xcodebuild -version && command -v pod   # required for default local builds
+```
+
+Read `site-config.ts` and confirm with the user: `title`, `bundleId`, `appleTeamId`, payment product IDs. The bundle ID is permanent once the app record exists — it must be final now.
+
+Export the ASC credentials for the rest of the session:
+
+```bash
+export ASC_KEY_ID="<10-char key id>"
+export ASC_ISSUER_ID="<issuer uuid>"
+export ASC_P8_PATH="/path/to/AuthKey_<KEY_ID>.p8"
+```
+</phase>
+
+<phase n="B" title="EAS project init">
+Skip if `easProjectId` in `site-config.ts` is already a real UUID.
+
+```bash
+cd mobile-app
+npx eas-cli@latest project:init --non-interactive --force
+npx eas-cli@latest project:info
+```
+
+Write the printed project ID into `site-config.ts > easProjectId`. Re-run `npm run check-setup` — the easProjectId warning must be gone.
+</phase>
+
+<phase n="C" title="Convex production + eas.json">
+Follow `docs/production-checklist.md` stage 1. Summary:
+
+```bash
+npx convex deploy -y
+# prod env starts EMPTY — set every required var:
+npx convex env set --prod SITE_URL "https://<the-app-domain>"
+npx convex env set --prod BETTER_AUTH_SECRET "$(openssl rand -hex 32)"   # fresh, never reuse dev
+npx convex env set --prod RESEND_API_KEY "$(npx convex env get RESEND_API_KEY)"
+npx convex env set --prod EMAIL_FROM "$(npx convex env get EMAIL_FROM)"
+# if Apple Sign In is enabled: APPLE_CLIENT_ID = {bundle_id}, APPLE_CLIENT_SECRET copied from dev
+# if Google Sign In is enabled: GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET copied from dev
+npx convex env list --prod
+```
+
+Then put the prod URLs into `mobile-app/eas.json > build.production`:
+
+```json
+"production": {
+  "autoIncrement": true,
+  "credentialsSource": "local",
+  "env": {
+    "EXPO_PUBLIC_CONVEX_URL": "https://<prod-deployment>.convex.cloud",
+    "EXPO_PUBLIC_CONVEX_SITE_URL": "https://<prod-deployment>.convex.site"
+  }
+}
+```
+
+`credentialsSource: "local"` is what makes the build fully non-interactive (Phase E).
+</phase>
+
+<phase n="D" title="Apple signing credentials via ASC API">
+All API calls use `node mobile-app/scripts/asc-api.mjs <METHOD> <path> [body.json]` with the env vars from Phase A. Work in a directory OUTSIDE the repo (e.g. `~/ios-credentials/<slug>/`) so nothing secret can be committed.
+
+**1. Resolve the app record (hard gate):**
+
+```bash
+node mobile-app/scripts/asc-api.mjs GET "/v1/apps?filter[bundleId]={bundle_id}"
+```
+
+Empty `data` → STOP. Tell the user to create the app record at appstoreconnect.apple.com (My Apps > + > New App) with this exact bundle ID, then resume. Otherwise save `{asc_app_id}` = `data[0].id`.
+
+**2. Bundle ID registration + capabilities:**
+
+```bash
+node mobile-app/scripts/asc-api.mjs GET "/v1/bundleIds?filter[identifier]={bundle_id}"
+# if missing, register it:
+# POST /v1/bundleIds  {"data":{"type":"bundleIds","attributes":{"identifier":"{bundle_id}","name":"{title}","platform":"IOS"}}}
+node mobile-app/scripts/asc-api.mjs GET "/v1/bundleIds/<BUNDLE_DB_ID>/bundleIdCapabilities"
+# enable missing capabilities the app uses (IN_APP_PURCHASE, APPLE_ID_AUTH, PUSH_NOTIFICATIONS):
+# POST /v1/bundleIdCapabilities {"data":{"type":"bundleIdCapabilities","attributes":{"capabilityType":"APPLE_ID_AUTH"},"relationships":{"bundleId":{"data":{"type":"bundleIds","id":"<BUNDLE_DB_ID>"}}}}}
+```
+
+**3. Distribution certificate.** First check for an existing one (Apple caps distribution certs at ~2-3 per account):
+
+```bash
+node mobile-app/scripts/asc-api.mjs GET "/v1/certificates?filter[certificateType]=DISTRIBUTION"
+```
+
+Reuse only if the user has its private key/.p12 locally. Otherwise create a new one (with user confirmation):
+
+```bash
+openssl req -new -newkey rsa:2048 -nodes -keyout dist.key -out dist.csr \
+  -subj "/emailAddress=<user-email>/CN={title} Distribution/C=US"
+node -e "const fs=require('fs');fs.writeFileSync('cert-req.json',JSON.stringify({data:{type:'certificates',attributes:{certificateType:'DISTRIBUTION',csrContent:fs.readFileSync('dist.csr','utf8')}}}))"
+node mobile-app/scripts/asc-api.mjs POST /v1/certificates cert-req.json
+# save body.data.id (cert id) and body.data.attributes.certificateContent (base64) -> dist.cer
+```
+
+**4. App Store provisioning profile:**
+
+```bash
+node -e "const fs=require('fs');fs.writeFileSync('profile-req.json',JSON.stringify({data:{type:'profiles',attributes:{name:'{title} AppStore',profileType:'IOS_APP_STORE'},relationships:{bundleId:{data:{type:'bundleIds',id:'<BUNDLE_DB_ID>'}},certificates:{data:[{type:'certificates',id:'<CERT_ID>'}]},devices:{data:[]}}}}))"
+node mobile-app/scripts/asc-api.mjs POST /v1/profiles profile-req.json
+# save body.data.attributes.profileContent (base64) -> profile.mobileprovision
+```
+
+**5. Build the .p12 (the `-legacy` flag is mandatory — Apple tooling rejects OpenSSL 3.x default ciphers):**
+
+```bash
+echo "<certificateContent-b64>" | base64 -d > dist.cer
+P12PASS=$(openssl rand -hex 12)
+openssl x509 -inform der -in dist.cer -out dist.pem 2>/dev/null || cp dist.cer dist.pem
+openssl pkcs12 -export -in dist.pem -inkey dist.key -out dist.p12 \
+  -name "{title} Distribution" -passout pass:"$P12PASS" -legacy
+echo "<profileContent-b64>" | base64 -d > appstore.mobileprovision
+```
+
+**6. Wire into the project (gitignored paths only):**
+
+```bash
+mkdir -p mobile-app/credentials
+cp dist.p12 mobile-app/credentials/dist.p12
+cp appstore.mobileprovision mobile-app/credentials/
+node -e "const fs=require('fs');fs.writeFileSync('mobile-app/credentials.json',JSON.stringify({ios:{provisioningProfilePath:'credentials/appstore.mobileprovision',distributionCertificate:{path:'credentials/dist.p12',password:process.argv[1]}}},null,2))" "$P12PASS"
+git check-ignore mobile-app/credentials.json mobile-app/credentials/dist.p12   # MUST print both paths
+```
+
+Setup-only mode STOPS here — report readiness (app record, cert, profile, credentials.json, eas.json) and the next command.
+</phase>
+
+<phase n="E" title="Local iOS build (default)">
+Default path. This uses the local Mac/Xcode toolchain and does **not** consume Expo cloud build credits. It still uses EAS CLI for config/versioning and local credentials for signing.
+
+```bash
+cd mobile-app
+npx eas-cli@latest build --platform ios --profile production \
+  --local --non-interactive --output /tmp/{slug}.ipa
+```
+
+If the build fails in `expo doctor` due to patch-version mismatches, inspect the exact error. Do not blindly upgrade dependencies during a release unless the build is blocked; if blocked, run `npx expo install --check`, apply the minimal Expo SDK patch updates, rerun `npx tsc --noEmit && npm run lint`, then rebuild.
+
+Local `autoIncrement` can skip build numbers if a canceled cloud build already reserved one. That is acceptable for App Store Connect.
+</phase>
+
+<phase n="E-expo" title="EAS cloud build (--expo only)">
+Run this phase only when the user passes `--expo`, and confirm once because it consumes Expo/EAS build credits:
+
+```bash
+cd mobile-app
+npx eas-cli@latest build --platform ios --profile production --non-interactive --no-wait
+```
+
+Poll until terminal state (FINISHED / ERRORED):
+
+```bash
+npx eas-cli@latest build:list --platform ios --limit 1 --json --non-interactive
+# or: npx eas-cli@latest build:view <BUILD_ID> --json
+```
+
+On FINISHED, download the artifact:
+
+```bash
+curl -sL -o /tmp/{slug}.ipa "<artifacts.buildUrl>"
+```
+</phase>
+
+<phase n="F" title="TestFlight upload">
+**1. Internal beta group** (TestFlight needs a group; `asc publish testflight` fails without `--group`):
+
+```bash
+node -e "const fs=require('fs');fs.writeFileSync('group-req.json',JSON.stringify({data:{type:'betaGroups',attributes:{name:'Internal',isInternalGroup:true,hasAccessToAllBuilds:true},relationships:{app:{data:{type:'apps',id:'{asc_app_id}'}}}}}))"
+node mobile-app/scripts/asc-api.mjs POST /v1/betaGroups group-req.json
+# 409 "already exists" is fine — fetch the id: GET "/v1/apps/{asc_app_id}/betaGroups"
+```
+
+**2. Upload and wait for processing** (asc must be authenticated — `asc auth status --validate`, else `asc auth login` with the same ASC key):
+
+```bash
+asc publish testflight --app "{asc_app_id}" --ipa /tmp/{slug}.ipa \
+  --group "<BETA_GROUP_ID>" --wait --timeout 45m
+```
+
+**3. Add testers** (internal testers must be App Store Connect team members; external emails work via groups):
+
+```bash
+node -e "const fs=require('fs');fs.writeFileSync('tester-req.json',JSON.stringify({data:{type:'betaTesters',attributes:{email:'<tester-email>'},relationships:{betaGroups:{data:[{type:'betaGroups',id:'<BETA_GROUP_ID>'}]}}}}))"
+node mobile-app/scripts/asc-api.mjs POST /v1/betaTesters tester-req.json
+```
+
+**4. Verify**: `asc status --app "{asc_app_id}" --output table` shows the build processed and attached to the group. Report build number, group, and tester list to the user.
+</phase>
+
+<failure_modes>
+- **`.p12` rejected during signing** → it was exported without `-legacy`. Re-export: `openssl pkcs12 -in dist.p12 -nodes -out tmp.pem -passin pass:"$P12PASS" && openssl pkcs12 -export -in tmp.pem -out dist.p12 -passout pass:"$P12PASS" -legacy`.
+- **Certificate creation returns 409 / limit reached** → list existing DISTRIBUTION certs; ask the user which to revoke (`DELETE /v1/certificates/<id>`) or whether they have its .p12 to reuse. Never revoke without confirmation — it breaks other apps signed with it.
+- **Local build fails before Xcode archive** → verify macOS/Xcode/CocoaPods: `xcodebuild -version`, `xcode-select -p`, `command -v pod`. If unavailable and the user accepts cloud quota usage, rerun with `--expo`.
+- **Local build fails asking for credentials** → `credentialsSource: "local"` is missing in `eas.json`, or `credentials.json` paths are wrong (they are relative to `mobile-app/`).
+- **`--expo` cloud build fails asking for credentials** → same credential checks as local, then rerun cloud build.
+- **`asc publish testflight` fails with "--group is required"** → create the beta group first (Phase F step 1).
+- **Upload rejected: missing export compliance** → answer the encryption question in App Store Connect once, or add `"ITSAppUsesNonExemptEncryption": false` to `infoPlist` in `mobile-app/app.config.ts` so future builds skip it.
+- **App opens but can't reach backend** → build was made before `eas.json` had prod URLs, or prod Convex env vars are missing (`npx convex env list --prod`). Rebuild after fixing — env is baked at build time.
+- **User insists on EAS-managed credentials (Apple ID login)** → that flow requires interactive 2FA and cannot run with `--non-interactive`. Run `npx eas-cli@latest credentials` in a real terminal with the user present, then build. Do not attempt to script the 2FA prompt.
+</failure_modes>
+
+<success_metrics>
+- `npm run check-setup` passes with a real `easProjectId`.
+- Default local build produces `/tmp/{slug}.ipa` without any interactive prompt; `--expo` cloud builds reach FINISHED.
+- The build shows as processed in TestFlight, attached to a beta group with at least one tester.
+- The TestFlight app signs in and talks to the PROD Convex deployment.
+- `git status` shows no credential files staged; nothing secret printed in the transcript.
+</success_metrics>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiblueprint-cli",
-  "version": "1.4.79",
+  "version": "1.4.81",
   "description": "AIBlueprint CLI for setting up AI coding configurations",
   "author": "AIBlueprint",
   "license": "MIT",