Update engage-native docs for v1.10.5

repositories/d-sports-engage-native.mdx

@@ -1,14 +1,15 @@
 ---
 title: "d-sports-engage-native"
 description: "Native iOS and Android app for D-Sports Engage. Expo 54, React Native, Clerk, RevenueCat, Thirdweb."
 icon: "smartphone"
 ---
 
 ## Overview
 
 **d-sports-engage-native** (package name: `engage-native`) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.
 
 - **Run:** `bunx expo start` or `bun run start` — then press `a` for Android or `i` for iOS, or scan the QR code with Expo Go.
+- **Current version:** 1.10.5
 
 ## Tech stack
 
@@ -17,31 +18,115 @@
 | Framework  | Expo 54, React Native 0.81, React 19 |
 | Auth       | Clerk (Expo)              |
 | Payments   | RevenueCat (react-native-purchases) |
 | Web3       | Thirdweb                  |
 | State      | Zustand                   |
 | Storage    | MMKV                      |
 | UI         | Lucide React Native       |
-| Navigation | Expo Router               |
+| Navigation | Expo Router 6             |
 | Package    | Bun                       |
 
 ## Features
 
 - **Wallet** — Tokens, holdings, pack opening, crypto checkout (via PWA backend)
 - **Shop** — Collectibles, cart, coin bundles, checkout
 - **Leaderboard** — Rankings and filters
-- **Locker room** — Social feed and engagement
+- **Locker room** — Social feed, quests, daily games, and engagement
 - **Profile** — User profile and settings
 - **Theme** — Dark/light mode (default dark)
 
+## Project structure
+
+```text
+app/
+├── (auth)/              # Login, signup, SSO callback
+├── (onboarding)/        # New-user onboarding flow
+├── (tabs)/              # Main tab navigation (wallet, shop, leaderboard, locker room, profile)
+├── settings/            # Settings pages with nested modals/tabs
+└── _layout.tsx          # Root layout with providers and auth protection
+
+components/
+├── wallet/              # Wallet sub-components (TokenRow, CardDetailModal, PackOpeningModal, …)
+├── shop/                # Shop sub-components (CartModal, CryptoCheckoutModal, …)
+├── locker-room/         # Locker room components (quests, daily games, feed, teams)
+├── leaderboard/         # Leaderboard components
+├── settings/            # Settings modals and tabs
+├── ui/                  # Reusable primitives (Button, TextField, TutorialOverlay, …)
+└── Icon/                # Icon wrapper using lucide-react-native
+
+hooks/                   # Screen-level hooks (use-wallet-screen, use-shop-screen, …)
+lib/api/                 # API client modules (wallet, shop, user, quests, checkout, …)
+context/                 # React contexts (user, collectibles, navbar visibility)
+services/                # Zustand store, MMKV storage, RevenueCat
+theme/                   # Brand colors, spacing, typography tokens
+types/                   # Shared TypeScript types (wallet, shop, checkout, API)
+constants/               # Shared constants (tokens, coin bundles, locker room)
+```
+
+<Info>
+Screen files contain only JSX. All state, effects, and handlers live in dedicated hooks (e.g., `use-wallet-screen.ts`). Sub-components are grouped by feature under `components/`.
+</Info>
+
+## Environment variables
+
+All runtime variables use the `EXPO_PUBLIC_` prefix. Create a `.env` file in the repo root:
+
+| Variable | Purpose |
+| -------- | ------- |
+| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk authentication key |
+| `EXPO_PUBLIC_API_URL` | Backend API base URL (defaults to `https://api.d-sports.org`) |
+| `EXPO_PUBLIC_TW_CLIENT_ID` | Thirdweb client ID for Web3 features |
+| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat API key for in-app purchases |
+| `EXPO_PUBLIC_REVENUECAT_APPSTORE_ID` | RevenueCat App Store app ID |
+| `EXPO_PUBLIC_REVENUECAT_ENTITLEMENT` | RevenueCat entitlement identifier |
+| `EXPO_PUBLIC_SUPABASE_URL` | Supabase project URL |
+| `EXPO_PUBLIC_SUPABASE_KEY` | Supabase publishable (anon) key |
+
 ## Getting started
 
-1. Clone the repository and run `bun install`.
-2. Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README.
-3. Run `bunx expo start`.
-4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.
+<Steps>
+  <Step title="Install dependencies">
+    Clone the repository and run `bun install`.
+  </Step>
+  <Step title="Configure environment">
+    Copy the `.env` example and fill in your Clerk, RevenueCat, Thirdweb, Supabase, and API URL values.
+  </Step>
+  <Step title="Start the dev server">
+    Run `bunx expo start`, then press **a** for Android, **i** for iOS, or scan the QR code with Expo Go.
+  </Step>
+  <Step title="Development builds (optional)">
+    Use EAS for device builds. The project includes profiles for `development`, `preview`, `staging`, and `production` in `eas.json`.
+  </Step>
+</Steps>
+
+The app targets both native and web (responsive) and uses the same backend (`d-sports-api`) as the PWA for API and checkout flows.
+
+## API client layer
+
+The API client in `lib/api/client.ts` automatically attaches Clerk auth tokens and handles the normalized response envelope:
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  code?: string;
+}
+```
+
+All migrated backend routes return `{ success, data }` or `{ success: false, error, code }` envelopes via shared helpers (`apiSuccess`, `apiError`, `apiUnauthorized`, `apiNotFound`). The client transparently supports both the new envelope and legacy responses for routes that have not yet been migrated.
+
+## EAS build profiles
+
+| Profile | Channel | Use case |
+| ------- | ------- | -------- |
+| `development` | `development` | Simulator builds with dev client |
+| `development-device` | `development` | Physical device builds with dev client |
+| `preview` | `preview` | Internal APK distribution |
+| `staging` | `staging` | Pre-release testing (auto-increment) |
+| `production` | `production` | App Store / Play Store release (auto-increment) |
 
-The app targets both native and web (responsive) and uses the same backend (d-sports-api) as the PWA for API and checkout flows.
+Run builds with `bunx eas build --profile <profile>`.
 
 <Card title="Ecosystem overview" icon="map" href="/repositories/ecosystem-overview">
   See how the native app fits with the PWA, site, and Mic'd Up.
 </Card>