@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/error-handling/scripts/verify.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — error-handling anti-pattern scanner
+#
+# USAGE
+#   ./verify.sh [PATH]            # default PATH = .
+#   ./verify.sh --strict [PATH]   # exit non-zero if anything is flagged
+#
+# WHAT IT DOES
+#   Greps the working tree for the highest-signal anti-patterns this skill
+#   teaches and prints file:line for each hit:
+#     - empty `catch {}` / `catch (e) {}`            (swallowed failure)
+#     - Python `except: pass` and bare `except:`     (swallowed / over-broad)
+#     - `alert(` as a handler, lone `console.log(err)` / `console.error(e)`
+#     - retry loops with no cap: `while (true)`/`while True` near "retry"
+#
+# POSTURE
+#   - READ-ONLY. Never writes, never auto-fixes.
+#   - HEURISTIC and ADVISORY. It flags candidates; a human judges each one.
+#   - Exits 0 by default even with findings (warnings only). Pass --strict to
+#     make any finding exit non-zero (for CI). Exits 0 cleanly on an empty or
+#     clean target — no false failure.
+#   - Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+#
+# EXIT CODES
+#   0  no findings, OR findings in advisory (default) mode
+#   1  findings AND --strict was passed
+# ============================================================================
+
+RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
+if [ -n "${NO_COLOR:-}" ]; then RED=""; YEL=""; GRN=""; RST=""; fi
+
+STRICT=0
+TARGET="."
+for arg in "$@"; do
+  case "$arg" in
+    --strict) STRICT=1 ;;
+    *) TARGET="$arg" ;;
+  esac
+done
+
+if [ ! -e "$TARGET" ]; then
+  printf '%s[skip]%s target not found: %s\n' "$YEL" "$RST" "$TARGET" >&2
+  exit 0
+fi
+
+HITS=0
+
+# Prefer ripgrep (respects .gitignore, fast); fall back to grep -r.
+if command -v rg >/dev/null 2>&1; then
+  search() { rg --line-number --no-heading --color=never -e "$1" "$TARGET" 2>/dev/null || true; }
+  searchP() { rg --line-number --no-heading --color=never -P -e "$1" "$TARGET" 2>/dev/null || true; }
+else
+  search() { grep -rEn --exclude-dir=.git --exclude-dir=node_modules -- "$1" "$TARGET" 2>/dev/null || true; }
+  searchP() { grep -rEn --exclude-dir=.git --exclude-dir=node_modules -- "$1" "$TARGET" 2>/dev/null || true; }
+fi
+
+# report <label> <matches> : print a section if there are matches, bump HITS.
+report() {
+  label="$1"; matches="$2"
+  if [ -n "$matches" ]; then
+    count=$(printf '%s\n' "$matches" | grep -c . || true)
+    printf '\n%s[flag]%s %s (%s)\n' "$YEL" "$RST" "$label" "$count"
+    printf '%s\n' "$matches"
+    HITS=$((HITS + count))
+  fi
+}
+
+# 1. Empty catch blocks: `catch {}`, `catch (e) {}`, `catch(err){ }`
+report "empty catch block — swallows the failure" \
+  "$(searchP 'catch\s*(\([^)]*\))?\s*\{\s*\}')"
+
+# 2. Python `except: pass`  (allow whitespace / one-liners)
+report "Python 'except ...: pass' — swallows the failure" \
+  "$(searchP 'except[^\n:]*:\s*pass\b')"
+
+# 3. Python bare `except:`  (over-broad; catches SystemExit/KeyboardInterrupt)
+report "Python bare 'except:' — over-broad, catch the specific type" \
+  "$(searchP 'except\s*:')"
+
+# 4. alert() used as an error handler (leaks internals, blocks UI)
+report "alert() as a handler — leaks internals, no recovery" \
+  "$(searchP 'alert\s*\(\s*(e|err|error)(\.message)?\s*\)')"
+
+# 5. console.log/error of the error as the ONLY handling (log-and-forget)
+report "lone console.log/error(err) — log without classify/surface" \
+  "$(searchP 'console\.(log|error)\s*\(\s*(e|err|error)\s*\)\s*;?\s*$')"
+
+# 6. Uncapped retry loops: while(true)/while True within a couple lines of 'retry'
+report "possible uncapped retry loop — needs an attempt cap + jitter" \
+  "$(searchP 'while\s*\(\s*true\s*\)|while\s+True\s*:' | grep -iE 'retry|attempt|backoff' || true)"
+
+# ----------------------------------------------------------------------------
+printf '\n=== Summary ===\n'
+if [ "$HITS" -eq 0 ]; then
+  printf '%s[ok]%s no anti-patterns flagged under %s\n' "$GRN" "$RST" "$TARGET"
+  exit 0
+fi
+
+printf '%s%s candidate(s) flagged%s — heuristic; review each against ../SKILL.md.\n' \
+  "$YEL" "$HITS" "$RST"
+if [ "$STRICT" -eq 1 ]; then
+  printf '%s--strict: failing.%s\n' "$RED" "$RST" >&2
+  exit 1
+fi
+printf 'advisory mode (exit 0); pass --strict to gate.\n'
+exit 0

package/skills/shared/expo/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: expo
+description: "Use when shipping a React Native app with Expo — EAS Build/Submit/Update, eas.json profiles and channels, config plugins, prebuild/CNG, runtime-version policy, OTA updates that never land, SDK upgrades, the New Architecture. NOT RN UI, navigation or native-module authoring (that is `react-native`), NOT a Dart app (that is `flutter`)."
+tags: [expo, eas, react-native, mobile, ota-updates, app-store]
+recommends: [react-native, github-actions, ship, deployment, secure-coding]
+origin: ai-hub
+---
+
+# Expo & EAS: shipping React Native
+
+**Scope.** This skill owns the Expo platform: router, config plugins, EAS, native modules, store
+builds. Animation and gestures (Reanimated worklets, sheets, press feedback, haptics) follow
+`../react-native/SKILL.md`. Visual design of web pages and screens is `../design/SKILL.md`'s.
+
+
+## What this skill owns
+
+Expo is the toolchain and **EAS cloud platform** layered on React Native: cloud
+builds, store submission, over-the-air JS updates, and **native configuration
+declared in JavaScript** instead of hand-edited Xcode/Gradle projects. This skill
+owns the *shipping pipeline* and *native-config-via-JS*.
+
+The verb rule of thumb: if the verb is **build / submit / update / prebuild /
+plugin / EAS / channel / runtime-version**, you are in `expo`. If it is **render /
+navigate / animate / bridge / write a native module**, route to `react-native`.
+Other exits: web React/hooks/state → `react`, a Dart app → `flutter`, native-only
+Swift/Kotlin → `swift-ios`/`kotlin-android`, a desktop wrapper → `tauri`/`electron`,
+CI unrelated to EAS → `github-actions`.
+
+Current stable as of 2026-06-02: **Expo SDK 55** — React Native 0.83.1, React
+19.2.0, shipped 2026-02-25. **SDK 56 is in beta** (beta opened 2026-05-06, ~2-week
+window; RN 0.85.2, React 19.2.3) — upcoming, not yet shipped stable. Both run
+exclusively on the New Architecture; the Legacy Architecture was removed in SDK 55.
+
+## Decision rules
+
+| Situation | Do this | Why / not that |
+|---|---|---|
+| New app, want config-as-JS | **managed + prebuild (CNG)** — no committed `ios/`/`android/` | native dirs are regenerable artifacts; hand-edits get blown away |
+| You truly need to hand-edit native code long-term | **bare** (commit `ios/`/`android/`) | last resort; you lose `prebuild --clean` upgrades |
+| Quick demo, only Expo-SDK modules | **Expo Go** | zero build, but custom native deps will crash |
+| Any custom native dependency or plugin | **dev build** (`developmentClient: true`) | Expo Go cannot load arbitrary native code |
+| Runtime version, picking a policy | **`fingerprint`** (auto-bumps on native change) | safest default; prevents serving JS to an incompatible binary |
+| Runtime tied to your release version | `appVersion` | simpler, but you must remember to bump it on native changes |
+
+## The shipping pipeline (core)
+
+Four EAS verbs, in this order: **prebuild → build → submit → update**.
+
+```bash
+npx expo prebuild --clean      # regenerate native dirs from app config + plugins (CNG)
+eas build -p ios --profile production       # cloud-build the binary (.ipa/.aab)
+eas submit -p ios --profile production      # upload to App Store / Play Store
+eas update --branch production --message "fix typo"   # ship JS-only over the air
+```
+
+`prebuild` is only needed for managed/CNG apps and runs automatically inside
+`eas build`; run it locally to inspect or to verify a plugin. **Build/submit ship a
+new binary; update ships JS only** — anything touching native code needs a new build.
+
+Minimal `eas.json` with the three default profiles plus channels. Each build is
+stamped with a `channel`; a channel maps to a same-named EAS Update branch by default
+(SDK 55 stable builders: RN 0.83.1, Xcode 26 on iOS, Android 16 target):
+
+```jsonc
+{
+  "cli": { "version": ">= 16.0.0" },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal",
+      "channel": "development"
+    },
+    "preview": {
+      "distribution": "internal",
+      "channel": "preview"
+    },
+    "production": {
+      "channel": "production",
+      "autoIncrement": true
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}
+```
+
+Run `scripts/verify.sh` inside an Expo project to gate `eas.json`, the runtime
+policy, committed secrets, and New-Arch readiness.
+
+## EAS Update mental model
+
+Runtime version is the **compatibility gate**. An update applies to a build only
+when **BOTH the platform AND the `runtimeVersion` match exactly** — there is no
+"close enough". The chain is: build stamped with a **channel** → channel points at a
+**branch** → you publish updates to a branch. Updates flow only down a matching
+runtime within the linked branch.
+
+The #1 footgun: a hardcoded `runtimeVersion` that drifts from the binary, so the
+update silently never installs and you stare at unchanged devices.
+
+```jsonc
+// BAD — hardcoded string in app.json; bump a native dep and every old build
+// silently stops matching, so your "shipped" OTA never reaches users.
+{ "expo": { "runtimeVersion": "1.0.0" } }
+```
+
+```jsonc
+// GOOD — fingerprint policy: EAS hashes the native runtime and auto-bumps the
+// runtime version whenever native code/config changes, so updates only ever
+// reach binaries that can actually run them.
+{ "expo": { "runtimeVersion": { "policy": "fingerprint" } } }
+```
+
+Inspect, branch ops, rollouts/rollbacks, republish, and the full "update not
+applying" decision flow → `references/eas-update.md`.
+
+## Config plugins / CNG
+
+**Never hand-edit `ios/` or `android/`** — they are ephemeral, regenerated by
+`npx expo prebuild --clean` from `app.config` + plugins + autolinking. To change
+native config, write a config plugin (a function in the `plugins` array) or use a
+mod like `withInfoPlist` / `withAndroidManifest`.
+
+```ts
+// app.plugin.ts — add an iOS Info.plist key during prebuild, the CNG way.
+import { ConfigPlugin, withInfoPlist } from "expo/config-plugins";
+
+const withCameraUsage: ConfigPlugin<{ reason: string }> = (config, { reason }) =>
+  withInfoPlist(config, (cfg) => {
+    cfg.modResults.NSCameraUsageDescription = reason;
+    return cfg;
+  });
+
+export default withCameraUsage;
+```
+
+```ts
+// app.config.ts — dynamic config; reference the plugin with its options.
+export default {
+  expo: {
+    name: "MyApp",
+    runtimeVersion: { policy: "fingerprint" },
+    plugins: [["./app.plugin.ts", { reason: "Scan receipts" }]],
+  },
+};
+```
+
+Plugin anatomy, dangerous mods, mod ordering, and prebuild troubleshooting →
+`references/config-plugins.md`.
+
+## New Architecture & SDK upgrade
+
+**The Legacy Architecture is gone.** SDK 54 was the last release to ship it; SDK 55
+(2026-02-25, current stable) removed it entirely, and the SDK 56 beta builds on that.
+On any supported SDK you are **already** on the New Architecture — it is always
+enabled and cannot be turned off. The `newArchEnabled` flag was deleted from
+`app.json` in SDK 55; if you still carry one, it is dead config — remove it. There is no legacy
+fallback to lean on, so a dependency that only works on the old architecture is now a
+hard blocker, not a "flip the flag back" escape hatch.
+
+Upgrade checklist:
+
+1. `npx expo install expo@latest --fix` — bump SDK and align every dependency.
+2. `npx expo-doctor@latest` — catch deps that never made the New-Arch jump before you build.
+3. `npx expo prebuild --clean` — regenerate native dirs (managed/CNG apps).
+4. Build a `development`/`preview` binary on a device before promoting to production.
+
+Two upgrade tripwires: every Android app is **edge-to-edge** (on since SDK 54,
+non-negotiable) — audit manual inset/status-bar code. And SDK 55+ ships **Hermes
+bytecode diffing** for EAS Update (~75% smaller OTA downloads) automatically; you get
+it for free once both the build and the update are on SDK 55+.
+
+## Credentials & secrets
+
+- Let **EAS manage credentials** (signing keys, provisioning profiles) by default —
+  it stores and rotates them server-side so they never touch the repo.
+- Supply per-profile config through **EAS environment variables** / `.env` files
+  scoped by profile, not committed plaintext.
+- **Never commit** a keystore (`*.jks`/`*.keystore`), `*.p12`, or
+  `*.mobileprovision`, and never put API keys in `app.config`/`app.json` — anything
+  in app config ships inside the public bundle. See `../secure-coding/SKILL.md`.
+
+## EAS Workflows
+
+EAS Workflows are Expo's own CI: YAML in `.eas/workflows/`. Jobs use pre-packaged
+`type`s (`build`, `submit`, `update`) and chain via `needs:` + outputs. Route to the
+`github-actions` skill **only** when the user explicitly wants GH Actions or
+non-Expo CI.
+
+```yaml
+# .eas/workflows/release-android.yml — build then submit, chained by needs.
+name: Release Android
+on:
+  push:
+    branches: [main]
+jobs:
+  build:
+    type: build
+    params:
+      platform: android
+      profile: production
+  submit:
+    needs: [build]
+    type: submit
+    params:
+      platform: android
+      build_id: ${{ needs.build.outputs.build_id }}
+```
+
+## Plan limits (set expectations)
+
+EAS **Free**: 15 Android + 15 iOS builds/month on the **low-priority queue only**
+(peak waits can exceed an hour). High-priority queue needs a paid plan; the
+Production plan includes 2 build concurrencies, with extra concurrency at
+$50/concurrency/month, up to 5 extra. If a user complains about build queue waits,
+the fix is usually the plan, not the config. (Pricing per expo.dev/pricing, verified
+2026-06-02; re-check before quoting — Expo adjusts tiers and dollar figures.)
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+|---|---|
+| Editing `ios/Info.plist` directly | `prebuild --clean` overwrites it; write a config plugin / `withInfoPlist`. |
+| Hardcoding `runtimeVersion: '1.0.0'` because it is simpler | it drifts from the binary; updates silently stop matching. Use the `fingerprint` policy. |
+| Expecting an OTA update to deliver a bumped native dep | EAS Update is JS-only; native changes need a new `eas build`. |
+| Telling users to "just refresh" when a published update does not land | check the channel→branch and exact runtime match first — wrong channel = no delivery. |
+| Testing a custom native module in Expo Go | Expo Go can't load arbitrary native code; build a dev client. |
+| Upgrading the SDK and building straight to production | run `expo-doctor` + a preview build first; there is no Legacy-Arch fallback to catch a New-Arch-incompatible dep. |
+| Setting `newArchEnabled: false` to dodge a broken native dep | the flag was removed in SDK 55 and the Legacy Architecture is gone; fix or replace the dep. |
+| Committing the keystore so CI can sign | never; let EAS manage credentials or use EAS secrets. |
+| Putting the API key in `app.config` extra | app config ships in the public bundle; use EAS env vars / a backend. |
+| Reaching for GitHub Actions to call `eas build` | EAS Workflows is the native CI; only reach for github-actions if explicitly required. |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki),
+read `02-DOCS/wiki/stack/expo.md` first and record this app's shipping decisions
+there — managed-vs-bare, runtime-version policy, channel/branch map, SDK/New-Arch
+status — linked from the root `CLAUDE.md` `## Knowledge map`, bumping its `Updated`
+date when a convention changes. No `02-DOCS/`? Skip silently. Conventions are
+*recorded, not gated* — never block the task on this.

package/skills/shared/expo/evals/README.md

@@ -0,0 +1,13 @@
+# expo evals
+
+These cases are a routing + capability rubric, not an automated test harness. To run
+them, feed each `should_trigger` / `should_not_trigger` prompt to the skill router and
+confirm it (a) selects `expo` for the triggers — paying attention to the non-obvious
+("update isn't showing up", the New-Arch-mandatory blocker) and the Catalan/Spanish ones — and
+(b) routes each non-trigger to the stated sibling (`react-native`, `github-actions`,
+`flutter`, `swift-ios`, `react`). For `capability`, give the scenario to the skill and
+score the answer against the `must_include` rubric, either by hand or with an LLM judge:
+every bullet should be present and correct (eas.json profiles + channel, fingerprint
+runtime policy with the exact-match rule, the build/submit/update commands, the
+hand-editing/keystore warnings, and the New-Arch-already-mandatory note). The config artifacts the
+skill emits can be additionally gated with `scripts/verify.sh`.

package/skills/shared/expo/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: expo
+
+should_trigger:
+  - prompt: "Set up eas.json with dev, preview, and production profiles and push an iOS build to TestFlight."
+    why: "Core EAS Build + Submit + build-profile configuration — the heart of this skill."
+  - prompt: "My EAS Update published fine but none of the devices ever get the new JS bundle."
+    why: "Non-obvious; the runtime-version exact-match footgun, the #1 reason updates silently never apply."
+  - prompt: "How do I add a custom AndroidManifest permission without ejecting or editing native code?"
+    why: "Config plugin / CNG — declaring native config in JS instead of hand-editing android/."
+  - prompt: "com configuro EAS Update amb branques i canals per a staging i producció?"
+    why: "Catalan; channel/branch model for staged OTA rollouts."
+  - prompt: "expo-doctor says a dependency isn't New-Architecture compatible and newArchEnabled is gone from app.json — how do I ship?"
+    why: "Non-obvious; New Arch is mandatory since SDK 55 with no legacy fallback, so a non-compliant dep is a hard blocker, not a flag flip."
+  - prompt: "Write an EAS Workflow that builds Android then submits to the Play Store."
+    why: "EAS Workflows YAML with build->submit chaining via needs/outputs."
+  - prompt: "subir la app a la Play Store con EAS y configurar el runtimeVersion con fingerprint"
+    why: "Spanish; EAS Submit plus runtime-version policy choice."
+
+should_not_trigger:
+  - prompt: "Build a custom swipeable card list with React Native Reanimated."
+    route_to: "react-native"
+    why: "Pure RN UI/animation, no EAS/Expo toolchain or shipping concern."
+  - prompt: "Set up a GitHub Actions workflow to run my Jest tests on every push."
+    route_to: "github-actions"
+    why: "Generic CI unrelated to EAS Workflows; only route here if the user explicitly wants EAS CI."
+  - prompt: "How do I structure a Flutter app with Riverpod and go_router?"
+    route_to: "flutter"
+    why: "Different ecosystem (Dart), not React Native / Expo."
+  - prompt: "Write a native Swift widget extension for iOS."
+    route_to: "swift-ios"
+    why: "Native-Swift-only work with no Expo/CNG angle."
+  - prompt: "Memoize this React component so it stops re-rendering on every parent update."
+    route_to: "react"
+    why: "Web/component performance, no mobile shipping or native config."
+
+capability:
+  - scenario: "I have an Expo SDK 55 app. Configure eas.json for preview and production, set up EAS Update so I can ship JS fixes safely, and give me the build and submit commands."
+    must_include:
+      - "eas.json with a build.production profile + channel mapping and a preview profile with distribution internal"
+      - "runtimeVersion fingerprint policy recommended (or appVersion), with the exact-match rule explained: an update applies only when BOTH platform AND runtimeVersion match exactly"
+      - "explicit commands: eas build -p ios --profile production and eas submit -p ios --profile production"
+      - "eas update --branch production --message <msg> for JS-only OTA, noting native changes need a new build"
+      - "warning never to hand-edit ios/ or android/ (use a config plugin / prebuild --clean) and never to commit a keystore/.p12/.mobileprovision"
+      - "note that the New Architecture is mandatory since SDK 55 (Legacy Architecture removed, newArchEnabled deleted from app.json) so the app is already on New Arch"

package/skills/shared/expo/references/config-plugins.md

@@ -0,0 +1,117 @@
+# Config plugins & CNG (Continuous Native Generation)
+
+Deep dive for the native-config-via-JS half of the pipeline. With CNG the `ios/` and
+`android/` directories are **ephemeral build artifacts**, regenerated by
+`npx expo prebuild` from `app.config` + the `plugins` array + autolinking. The
+golden rule: **never hand-edit generated native dirs — write a plugin instead.**
+
+## When you need a plugin
+
+You need a config plugin whenever a native change must survive `prebuild --clean`:
+an Info.plist key, an AndroidManifest permission/intent-filter, an entitlement, a
+Gradle/Podfile tweak, an extra resource file. Most popular native libraries ship
+their own plugin — you just add the package name (and options) to `plugins`.
+
+## Anatomy: mods
+
+A config plugin is a function `(config, props) => config`. It usually delegates to a
+**mod** — a hook that runs during a specific prebuild phase and receives the parsed
+native file in `config.modResults`:
+
+| Mod | Edits |
+|---|---|
+| `withInfoPlist` | iOS `Info.plist` |
+| `withEntitlementsPlist` | iOS entitlements |
+| `withAndroidManifest` | `AndroidManifest.xml` |
+| `withStringsXml` / `withAndroidColors` | Android resources |
+| `withAppBuildGradle` / `withProjectBuildGradle` | Gradle |
+| `withPodfile` (dangerous) | iOS Podfile |
+| `withDangerousMod` | raw filesystem access — last resort |
+
+```ts
+// withMicPermission.ts — typed plugin with options, editing both platforms.
+import {
+  ConfigPlugin,
+  withInfoPlist,
+  withAndroidManifest,
+  AndroidConfig,
+} from "expo/config-plugins";
+
+const withMicPermission: ConfigPlugin<{ reason: string }> = (config, { reason }) => {
+  config = withInfoPlist(config, (cfg) => {
+    cfg.modResults.NSMicrophoneUsageDescription = reason;
+    return cfg;
+  });
+  config = withAndroidManifest(config, (cfg) => {
+    AndroidConfig.Permissions.addPermission(
+      cfg.modResults,
+      "android.permission.RECORD_AUDIO",
+    );
+    return cfg;
+  });
+  return config;
+};
+
+export default withMicPermission;
+```
+
+```ts
+// app.config.ts — wire it with options.
+export default {
+  expo: {
+    name: "MyApp",
+    runtimeVersion: { policy: "fingerprint" },
+    plugins: [["./withMicPermission.ts", { reason: "Record voice memos" }]],
+  },
+};
+```
+
+## Mod ordering
+
+Plugins run **top to bottom** in the `plugins` array. Order matters when one plugin
+depends on a file/key another created — put the producer before the consumer.
+Within a single config, base mods run before the platform mods they feed. If a key
+seems to vanish, a later plugin is overwriting it; reorder or merge instead of
+assigning the whole object.
+
+## Dangerous mods
+
+`withDangerousMod` and `withPodfile` give raw filesystem/string access and run
+*outside* the structured merge, so two dangerous mods touching the same file can
+clobber each other silently. Use them only when no structured mod exists, keep the
+edit idempotent (check before you append), and prefer string-anchored insertion over
+full-file rewrites.
+
+## Dynamic app config
+
+`app.config.{js,ts,mjs,cjs,mts,cts}` lets you compute config at evaluation time —
+read environment variables, switch bundle ids per profile, gate plugins by env.
+Keep secrets *out*: anything returned here ships in the public bundle.
+
+```ts
+export default ({ config }) => ({
+  ...config,
+  ios: { bundleIdentifier: process.env.APP_VARIANT === "preview" ? "com.app.pre" : "com.app" },
+});
+```
+
+## Common community plugins
+
+Most are added by package name; many auto-register so you don't even list them.
+Examples: `expo-build-properties` (set iOS deployment target / Android `compileSdk`,
+enable specific build flags), `expo-camera`/`expo-location` (permission strings via
+plugin props), `@react-native-firebase/app` (config files + native setup),
+`react-native-ble-plx` (Bluetooth permission/usage). Always read the library's
+README for its plugin props rather than editing native files by hand.
+
+## Prebuild troubleshooting
+
+- **Change didn't appear** → you edited a generated file; move it into a plugin and
+  rerun `npx expo prebuild --clean`.
+- **Plugin error during prebuild** → run `npx expo prebuild --clean --platform ios`
+  (or `android`) to isolate which platform's mod throws.
+- **Stale native state after an upgrade** → always `prebuild --clean` (not plain
+  `prebuild`) after bumping the SDK or native deps; plain prebuild merges and can
+  keep stale config.
+- **Verify before building** → run `expo-doctor` after editing plugins to catch
+  incompatible versions before paying for a cloud build.

package/skills/shared/expo/references/eas-update.md

@@ -0,0 +1,118 @@
+# EAS Update: runtime versions, channels, rollouts
+
+Deep dive for the OTA-JS half of the pipeline. EAS Update ships **JavaScript and
+asset** changes over the air; anything touching native code needs a new `eas build`.
+
+## The exact-match rule (read this first)
+
+An update is delivered to a build only when **BOTH** of these match **exactly**:
+
+1. the **platform** (`ios` / `android`), and
+2. the **`runtimeVersion`** of the build and the update.
+
+There is no fuzzy/semver matching. A build with runtime `42` will never receive an
+update published under runtime `43`, even if "43 is newer". This single rule
+explains the vast majority of "my update isn't showing up" reports.
+
+## Runtime version policies
+
+Set `runtimeVersion` in `app.config`/`app.json`. Pick a *policy* object, not a
+literal string, so it tracks the native runtime automatically.
+
+| Policy | Behaviour | Use when |
+|---|---|---|
+| `{ "policy": "fingerprint" }` | EAS hashes everything affecting the native runtime (deps, config, plugins) and derives the runtime version; auto-bumps on any native change | **default** — safest; impossible to serve JS to an incompatible binary |
+| `{ "policy": "appVersion" }` | runtime tied to `version` | you already discipline yourself to bump `version` on every native change |
+| `"1.0.0"` (literal) | frozen; you bump by hand | almost never — drifts silently from the binary |
+
+```jsonc
+// GOOD default
+{ "expo": { "runtimeVersion": { "policy": "fingerprint" } } }
+```
+
+`expo-updates` reads this at build time and stamps the binary; the same value is
+computed when you `eas update`, and the two are compared by the exact-match rule.
+
+## Channel → branch → update
+
+- **Channel**: stamped onto each build via the `eas.json` profile's `"channel"`.
+  It is baked into the binary and cannot be changed without a new build.
+- **Branch**: where updates are published. A channel maps to a same-named branch by
+  default; you can repoint a channel to a different branch (e.g. promote `staging`'s
+  branch to the `production` channel) without rebuilding.
+- **Update**: one publish to a branch.
+
+```bash
+eas update --branch production --message "fix checkout copy"
+eas channel:view production          # see which branch a channel points at
+eas channel:edit production --branch release-2025-06   # repoint without rebuilding
+eas branch:list
+eas update:list --branch production
+```
+
+Promotion pattern: build once with the `preview`/`production` channel, publish to
+the `staging` branch, validate, then repoint the `production` channel at that same
+branch — the binary never changes, only which JS it pulls.
+
+## Rollouts and rollbacks
+
+There are two distinct rollout mechanisms; pick by what you are ramping.
+
+**Per-update rollout** (ramp one new update against the branch's prior update):
+publish with `--rollout-percentage <1-100>`, then adjust with `eas update:edit`.
+
+```bash
+# Publish to 10% of the channel's devices, then ramp.
+eas update --branch production --message "v2 flow" --rollout-percentage 10
+eas update:edit --branch production --rollout-percentage 50   # ramp (then 100)
+```
+
+**Branch-based rollout** (gradually switch a channel's traffic to a different
+branch — e.g. a hotfix branch): managed with `eas channel:rollout`.
+
+```bash
+# Start a rollout sending 10% of the production channel to the hotfix branch.
+eas channel:rollout production --action=create --percent=10 --branch=hotfix-123
+eas channel:rollout production --action=edit --percent=50    # ramp
+eas channel:rollout production --action=view                 # inspect state
+eas channel:rollout production --action=end                  # commit / finish
+```
+
+Roll back by republishing the previous good update as the *newest* one (optionally
+itself rolled out gradually), or by repointing the channel:
+
+```bash
+# Republish a known-good update group as the newest update; can itself be staged.
+eas update:republish --branch production --group <previous-update-group-id> --rollout-percentage 100
+
+# Or point a channel back at a known-good branch.
+eas channel:edit production --branch release-last-good
+```
+
+`republish` is preferred over deleting: it makes the older bundle the *newest*
+update on the branch, so devices move forward (clients only ever roll forward to a
+newer update id), not into an undefined state.
+
+## Embedded vs downloaded updates
+
+Every build embeds the JS bundle it was compiled with — that is the fallback shown
+on first launch and offline. Downloaded updates are fetched on the *next* launch
+after the current one (default check-on-launch), not mid-session, unless you call
+the `expo-updates` API to fetch and reload explicitly.
+
+## "Update not applying" — debug flow
+
+Work top to bottom; stop at the first mismatch:
+
+1. **Runtime mismatch?** Compare the build's runtime version with the update's
+   (`eas update:list`). Different → the binary can never see it. Rebuild or
+   republish under the matching runtime.
+2. **Wrong channel/branch?** `eas channel:view <channel>` — is it pointing at the
+   branch you published to? Repoint or republish to the right branch.
+3. **Native change shipped as JS?** If you bumped a native dependency or changed
+   native config, an OTA update cannot deliver it — `eas build` a new binary.
+4. **Rollout < 100%?** A gradual rollout only reaches a fraction of devices; ramp it.
+5. **Launch timing?** The update installs on the *next* cold start; a device that
+   hasn't relaunched still runs the old bundle.
+6. **`expo-updates` disabled / dev build?** Updates are off in development mode and
+   when `expo-updates` isn't installed/configured.