@allstak/react-native 0.3.0 → 0.3.2

package/README.md

@@ -1,223 +1,457 @@
 # @allstak/react-native
 
-**Native crash + JS error capture for React Native. iOS and Android auto-wired.**
+AllStak's React Native SDK captures JS errors, render errors, unhandled promises, logs, HTTP breadcrumbs/events, navigation breadcrumbs, device tags, and source maps from React Native apps.
+
+Use one wrapper, keep privacy-first defaults, support Hermes, and upload React Native source maps through build hooks instead of manual release chores.
 
 [![npm version](https://img.shields.io/npm/v/@allstak/react-native.svg)](https://www.npmjs.com/package/@allstak/react-native)
 [![CI](https://github.com/allstak-io/allstak-react-native/actions/workflows/ci.yml/badge.svg)](https://github.com/allstak-io/allstak-react-native/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Official AllStak SDK for React Native — hooks `ErrorUtils`, Hermes rejection tracking, and native crash capture on iOS and Android.
+## 1. Overview
 
-## Dashboard
+Use `@allstak/react-native` when you want production mobile error context without wiring several separate tools: a provider-first setup, automatic JS/runtime capture, privacy-safe breadcrumbs, Hermes-aware tags, and source-map upload through EAS, Gradle, Xcode, or custom CI build hooks.
 
-View captured events live at [app.allstak.sa](https://app.allstak.sa).
+## 2. Installation
 
-![AllStak dashboard](https://app.allstak.sa/images/dashboard-preview.png)
+```bash
+npm install @allstak/react-native
+```
 
-## Features
+Peer expectations:
 
-- `ErrorUtils.setGlobalHandler` integration for JS crash capture
-- Hermes unhandled promise rejection tracking
-- `Platform.OS` / `Platform.Version` auto-tags on every event
-- Native layers (Obj-C/Swift, Java/Kotlin) ship under `native/` for fatal crash capture
-- Breadcrumbs and user/tag context via the shared core API
-- Works with RN 0.70+
+| Peer | Supported |
+| --- | --- |
+| React | `>=16.8.0` |
+| React Native | `>=0.70` |
+| Expo | Supported in Expo apps. Expo Go can use the JS SDK paths; native crash capture requires native modules in a dev client or native build. |
 
-## What You Get
+The published package is standalone: no browser DOM, Node runtime, or `@allstak/js` dependency is required.
 
-Once integrated, every event flows to your AllStak dashboard:
+## 3. Quick Start — Provider-first
 
-- **JS errors** — stack traces, component names, Hermes rejections
-- **Native crashes** — iOS (Obj-C/Swift) and Android (Java/Kotlin) fatals
-- **Logs** — structured logs with search and filters
-- **HTTP** — outbound request timing, status codes, failed calls
-- **Device tags** — `Platform.OS`, `Platform.Version`, release channel
-- **Alerts** — email and webhook notifications on regressions
+Provider-first setup is the recommended path.
 
-## Installation
+```tsx
+import { AllStakProvider } from "@allstak/react-native";
 
-```bash
-npm install @allstak/react-native
+export default function App() {
+  return (
+    <AllStakProvider
+      apiKey="ask_live_..."
+      environment="production"
+      release="mobile@1.0.0+1"
+      dist="ios-hermes"
+      debug
+    >
+      <AppRoot />
+    </AllStakProvider>
+  );
+}
 ```
 
-## Quick Start
+`AllStakProvider` automatically:
 
-> Create a project at [app.allstak.sa](https://app.allstak.sa) to get your API key.
+- initializes the SDK
+- installs React Native integrations
+- wraps children with an error boundary
+- captures render errors
+- captures global JS errors through `ErrorUtils`
+- captures unhandled promise rejections, including Hermes-native promise rejections
+- attaches platform, device, architecture, Hermes, release, dist, and environment tags
+- installs console, HTTP, XHR, fetch, and AppState breadcrumbs according to config
+- attempts navigation auto-instrumentation when possible
 
-```ts
-import { Platform } from 'react-native';
-import { AllStak, installReactNative } from '@allstak/react-native';
+Navigation note: Metro/React Native static bundling currently prevents the SDK from guaranteeing automatic React Navigation patching in normal native Metro builds. The provider logs the status when `debug` is enabled. Use `instrumentReactNavigation(navigationRef)` when you need guaranteed navigation breadcrumbs.
 
-AllStak.init({
-  apiKey: process.env.ALLSTAK_API_KEY!,
-  environment: 'production',
-  release: 'com.app@1.0.3+5',
-  dist: Platform.OS,            // 'ios' | 'android' — used as the dashboard filter for binary builds
-  enableHttpTracking: true,     // auto-instrument fetch + XHR + axios — see "HTTP tracking" below
-});
-installReactNative();           // ErrorUtils + Hermes promise rejections + Platform tags
+## 4. Verify It Works
+
+Add a temporary test button or run these snippets after the provider has mounted:
+
+```tsx
+import { AllStak } from "@allstak/react-native";
 
-AllStak.captureException(new Error('test: hello from allstak-react-native'));
+AllStak.captureException(new Error("AllStak test error"));
+AllStak.captureMessage("AllStak test log");
+console.warn("AllStak warning breadcrumb");
+Promise.reject(new Error("AllStak unhandled rejection test"));
 ```
 
-Run the app — the test error appears in your dashboard within seconds.
+Expected result:
+
+- with `debug`, Metro shows `[AllStak] Initialized — session <id>`
+- the manual error appears in the AllStak dashboard
+- the message appears as a log event
+- the warning is attached as a breadcrumb to the next captured error
+- the unhandled rejection is captured with `metadata.source = "unhandledRejection"`
+
+## 5. Automatic Capture Matrix
+
+| Feature | Default | Config | Status | Notes |
+| --- | --- | --- | --- | --- |
+| Render errors | On with provider | `fallback`, `onError`; manual setup skips the boundary | Verified on iOS simulator | Captured with `metadata.source = "AllStakProvider.ErrorBoundary"` and component stack. |
+| Global JS errors | On | `autoErrorHandler` | Verified on iOS simulator; unit-tested elsewhere | Uses `ErrorUtils.setGlobalHandler`. |
+| Unhandled promises | On | `autoPromiseRejections` | Verified on iOS simulator | Uses Hermes rejection tracker plus polyfill/browser fallbacks. |
+| Manual `captureException` | Manual | `AllStak.captureException(error)` | Verified on iOS simulator and backend contract tests | Posts to `/ingest/v1/errors`. |
+| Manual `captureMessage` | Manual | `AllStak.captureMessage(message, level?)` | Verified on iOS simulator and backend contract tests | Info/warn go to logs; error/fatal also create error events. |
+| `console.warn` / `console.error` | On | `autoConsoleBreadcrumbs`, `captureConsole` | Verified on iOS simulator | Breadcrumbs only; original console methods still run. |
+| `console.log` / `console.info` | Off | `captureConsole={{ log: true, info: true }}` | Verified on iOS simulator | Opt-in only to avoid noisy dashboards. |
+| Fetch breadcrumbs | On | `autoFetchBreadcrumbs` | Verified on iOS simulator | Query strings are stripped from breadcrumb URLs. |
+| XHR breadcrumbs | On | `autoNetworkCapture` | Unit-tested; RN fetch is XHR-based in many setups | Skips AllStak ingest host to avoid recursion. |
+| HTTP 4xx/5xx | On for breadcrumbs | `autoFetchBreadcrumbs`, `autoNetworkCapture` | Verified on iOS simulator | Error-level breadcrumb for status `>=400`. |
+| Network failures | On for breadcrumbs | `autoFetchBreadcrumbs`, `autoNetworkCapture` | Verified on iOS simulator | Records failed request breadcrumb and rethrows original error. |
+| Full HTTP request events | Off | `enableHttpTracking`, `httpTracking` | Verified on iOS simulator | Posts to `/ingest/v1/http_requests`; headers/bodies off by default. |
+| AppState breadcrumbs | On | `autoAppStateBreadcrumbs` | Listener verified; OS transitions not fully scripted | Foreground/background transition testing is environment-dependent. |
+| Navigation breadcrumbs | Best effort automatic, manual fallback guaranteed | `autoNavigationBreadcrumbs`, `instrumentReactNavigation(ref)` | Manual path verified on iOS simulator; auto path unit-tested under Node; Metro native auto-patch intentionally falls back | Use manual ref instrumentation for guaranteed React Navigation breadcrumbs. |
+| Device/platform tags | On | `autoDeviceTags` | Verified on iOS simulator | Adds `device.os`, `device.osVersion`, `device.model` where available. |
+| Hermes detection | On | automatic | Verified on iOS simulator | Adds `rn.hermes` and selects `ios-hermes` / `android-hermes` dist when possible. |
+| Release/dist/environment tags | Environment defaults to `production`; release is caller-supplied; dist auto-detected unless overridden | `environment`, `release`, `dist` | Verified on iOS simulator | `release` and `dist` must match uploaded source maps for symbolication. |
+| Native iOS crashes | Manual drain API; native module must be linked | `drainPendingNativeCrashes(release?)` | Verified on iOS simulator | Crash is stored by native handler and sent on next launch. Provider does not call this automatically. |
+| Native Android crashes | Manual drain API; native module must be linked | `drainPendingNativeCrashes(release?)` | Implemented, not emulator/device verified | Android native module and dev crash trigger exist; emulator verification was blocked by disk in latest report. |
+| Offline queue | On, in-memory only | transport internal | Backend-contract verified | Buffered retry works while process lives; events are lost after app restart. |
+| Source maps | Build-time hook | EAS, Gradle, Xcode, or custom CI hooks | Build hooks implemented; backend upload path exists | Hooks inject `debugId` and upload maps. End-to-end Hermes symbolication still depends on matching release/dist/debugId. |
+
+## 6. Configuration Reference
+
+`AllStakProvider` accepts the SDK config and React Native integration flags:
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | required | Runtime project API key such as `ask_live_...`. Not the source-map upload token. |
+| `environment` | `string` | `"production"` | Attached to errors, logs, spans, and HTTP events. |
+| `release` | `string` | unset | App release, for example `mobile@1.2.3+45`. Required for source-map matching. |
+| `dist` | `string` | auto-detected | Override build flavor, for example `android-hermes`. |
+| `debug` | `boolean` | `false` | Prints SDK init and selected integration status logs. |
+| `fallback` | `ReactNode` or function | `null` on render error | Error boundary fallback UI. |
+| `onError` | function | unset | Called after render error capture. |
+| `destroyOnUnmount` | `boolean` | `false` | Keep `false` for app roots, Fast Refresh, and Strict Mode. |
+| `captureConsole` | object | `{ warn: true, error: true, log: false, info: false }` | Per-method console breadcrumb flags. |
+| `autoConsoleBreadcrumbs` | `boolean` | `true` | Kill switch for console wrapping. |
+| `autoFetchBreadcrumbs` | `boolean` | `true` | Wraps `fetch` for HTTP breadcrumbs. |
+| `autoNetworkCapture` | `boolean` | `true` | Wraps `XMLHttpRequest` for network breadcrumbs. |
+| `enableHttpTracking` | `boolean` | `false` | Enables full HTTP request events. |
+| `httpTracking` | `HttpTrackingOptions` | privacy-first defaults | Controls body/header capture, redaction, ignore lists, and byte limits. |
+| `autoAppStateBreadcrumbs` | `boolean` | `true` | Captures AppState changes as breadcrumbs. |
+| `autoDeviceTags` | `boolean` | `true` | Captures platform/device tags. |
+| `autoNavigationBreadcrumbs` | `boolean` | `true` | Best-effort auto navigation patch; manual fallback is recommended for Metro-native builds. |
+
+Common optional props also supported by the underlying client include `host`, `user`, `tags`, `sampleRate`, `beforeSend`, `tracesSampleRate`, `service`, and `replay`.
+
+```tsx
+<AllStakProvider
+  apiKey="ask_live_..."
+  environment="production"
+  release="mobile@1.2.3+45"
+  dist="android-hermes"
+  captureConsole={{ log: true, info: true }}
+  enableHttpTracking
+>
+  <AppRoot />
+</AllStakProvider>
+```
 
-## HTTP tracking
+HTTP tracking defaults are intentionally conservative. Request bodies, response bodies, and headers are not captured unless explicitly enabled. Sensitive headers and query parameters are still redacted even when header/body capture is enabled.
 
-Setting `enableHttpTracking: true` (off by default) auto-wraps `fetch`,
-`XMLHttpRequest`, and `axios` (when the latter is installed) so every
-outbound HTTP call is recorded as an `http_request` event.
+## 7. Manual / Advanced API
 
-**Privacy defaults are aggressive — `enableHttpTracking: true` is safe
-to ship to production:**
+```ts
+import {
+  AllStak,
+  instrumentReactNavigation,
+  drainPendingNativeCrashes,
+} from "@allstak/react-native";
+
+AllStak.captureException(error);
+AllStak.captureMessage("message");
+AllStak.addBreadcrumb("ui", "Tapped checkout", "info", { screen: "Checkout" });
+AllStak.setUser({ id: "user_123", email: "user@example.com" });
+AllStak.setTag("key", "value");
+AllStak.setContext("device", { model: "simulator" });
+await AllStak.flush();
+AllStak.destroy();
+```
 
-- request bodies are **not** captured
-- response bodies are **not** captured
-- headers are **not** captured
-- `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token`,
-  `Proxy-Authorization` are **always** redacted
-- query params named `token`, `password`, `api_key`, `apikey`,
-  `authorization`, `auth`, `secret`, `access_token`, `refresh_token`,
-  `session`, `sessionid`, `jwt` are **always** redacted in the URL
-- own-ingest URLs (your AllStak host) are skipped to avoid recursion
+Other advanced APIs include `setTags`, `setExtra`, `setExtras`, `setLevel`, `setFingerprint`, `withScope`, tracing helpers, `getReplay`, and manual `instrumentAxios`.
 
-Enable richer capture only on routes you control:
+Manual setup is available when you need full initialization control:
 
 ```ts
+import { AllStak, installReactNative } from "@allstak/react-native";
+
 AllStak.init({
-  apiKey: '...',
-  enableHttpTracking: true,
-  httpTracking: {
-    captureRequestBody: true,           // off by default
-    captureResponseBody: true,          // off by default
-    captureHeaders: true,               // off by default — auth headers still hard-redacted
-    redactHeaders: ['x-tenant'],        // additional names on top of the always-redact list
-    redactQueryParams: ['custom_id'],
-    ignoredUrls: [/health/i, '/metrics'],
-    allowedUrls: [],                    // if non-empty, ONLY these URLs are captured
-    maxBodyBytes: 4096,                 // bodies truncated past this with `…[truncated]`
-  },
+  apiKey: "ask_live_...",
+  environment: "production",
+  release: "mobile@1.2.3+45",
 });
+
+installReactNative();
 ```
 
-### axios
+Manual navigation fallback:
 
-If the project uses axios with a non-XHR adapter (rare on RN), explicitly
-instrument the instance — idempotent, so safe to call twice:
+```tsx
+import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
+import { instrumentReactNavigation } from "@allstak/react-native";
 
-```ts
-import axios from 'axios';
-const api = AllStak.instrumentAxios(axios.create({ baseURL: 'https://api.example.com' }));
+export function AppNavigation() {
+  const navigationRef = useNavigationContainerRef();
+
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      onReady={() => instrumentReactNavigation(navigationRef)}
+    >
+      {/* navigators */}
+    </NavigationContainer>
+  );
+}
 ```
 
-### Errors auto-link to recent failed requests
+Auto navigation works only where the SDK can safely patch `@react-navigation/native`. In normal Metro-native builds, manual ref instrumentation is the guaranteed path.
+
+## 8. Source Maps — automatic via build hooks
+
+React Native source maps become hands-off after adding one build hook for your build system. The hook injects a `debugId` into both the JS bundle and source map, then uploads the map to AllStak.
+
+### EAS / Expo
 
-When `enableHttpTracking: true` is on, the most recent failed HTTP
-requests (status >= 400 or network error, last 10) are automatically
-attached to the next `captureException` under
-`metadata['http.recentFailed']`. Bodies are NOT included in this
-snapshot unless body capture is enabled — only `method`, `url`,
-`statusCode`, `durationMs`, `error`.
+Add the AllStak config plugin to your `app.json` (or `app.config.js`):
 
-### `dist`
+```json
+{
+  "expo": {
+    "plugins": ["@allstak/react-native"]
+  }
+}
+```
 
-`dist: Platform.OS` is the recommended pattern — it labels every event
-with the binary build (`ios` / `android`) so the dashboard can filter
-to a single platform when triaging.
+Then add the EAS post-build hook:
 
-## Get Your API Key
+```json
+{
+  "scripts": {
+    "eas-build-on-success": "node ./node_modules/@allstak/react-native/build-hooks/eas-post-bundle.js"
+  }
+}
+```
 
-1. Sign up at [app.allstak.sa](https://app.allstak.sa)
-2. Create a project
-3. Copy your API key from **Project Settings → API Keys**
-4. Export it as `ALLSTAK_API_KEY` or pass it to `installReactNative(...)`
+Required environment:
 
-## Configuration
+- `ALLSTAK_UPLOAD_TOKEN`
+- `ALLSTAK_RELEASE`
+- `ALLSTAK_API_URL` optional, defaults to AllStak production API
 
-| Option | Type | Required | Default | Description |
-|---|---|---|---|---|
-| `apiKey` | `string` | yes | — | Project API key (`ask_live_…`) |
-| `environment` | `string` | no | — | Deployment env |
-| `release` | `string` | no | — | App version |
-| `host` | `string` | no | `https://api.allstak.sa` | Ingest host override |
-| `user` | `{ id?, email? }` | no | — | Default user context |
-| `tags` | `Record<string,string>` | no | — | Default tags |
+`ALLSTAK_UPLOAD_TOKEN` is a project-scoped upload token from Project Settings. It is not the runtime `apiKey`.
 
-## Example Usage
+### Android Gradle
 
-Capture a caught exception:
+Add this to `android/app/build.gradle` after the React Native Gradle plugin setup:
 
-```ts
-try {
-  await api.fetchFeed();
-} catch (e) {
-  AllStak.captureException(e as Error, { screen: 'Feed' });
-}
+```groovy
+apply from: "../../node_modules/@allstak/react-native/build-hooks/allstak-sourcemaps.gradle"
 ```
 
-Send a log from a screen:
+Supported Gradle properties / environment:
 
-```ts
-AllStak.captureMessage('User opened Settings', 'info');
-```
+- `ALLSTAK_UPLOAD_TOKEN` or `allstakUploadToken`
+- `ALLSTAK_RELEASE` or `allstakRelease`
+- optional API URL override when self-hosting
 
-Tag the current build channel:
+Then run your normal release task, for example:
 
-```ts
-AllStak.setTag('release-channel', 'beta');
-AllStak.setUser({ id: userId });
+```bash
+cd android
+./gradlew :app:bundleRelease
 ```
 
-## Production Endpoint
+### iOS Xcode Build Phase
 
-Production endpoint: `https://api.allstak.sa`. Override via `host` for self-hosted installs:
+Add a Run Script build phase after "Bundle React Native code and images":
 
-```ts
-installReactNative({ apiKey: '...', host: 'https://allstak.mycorp.com' });
+```sh
+"${SRCROOT}/../node_modules/@allstak/react-native/build-hooks/xcode-build-phase.sh"
 ```
 
-## Source maps (Hermes / Metro)
+Set these in the build phase, `.xcconfig`, or CI shell:
 
-JS bundles produced by Metro (with or without Hermes) are minified in
-release builds — without source-map upload, your dashboard stacks will
-read like `at e (index.bundle:1:42031)`. Wire it up once during release
-build via `@allstak/js/sourcemaps` (devDependency only):
+```sh
+ALLSTAK_UPLOAD_TOKEN=aspk_...
+ALLSTAK_RELEASE=mobile@1.2.3+45
+```
+
+The script is designed for release builds; debug builds should not upload source maps.
+
+### Custom CI
 
 ```bash
-npm install -D @allstak/js
+node ./node_modules/@allstak/react-native/build-hooks/upload-sourcemaps.js \
+  --platform ios \
+  --bundle path/to/main.jsbundle \
+  --sourcemap path/to/main.jsbundle.map \
+  --release mobile@1.2.3+45 \
+  --dist ios-hermes
 ```
 
-```sh
-# Build the release bundle as you normally would
-npx react-native bundle \
-  --platform android --dev false --entry-file index.js \
-  --bundle-output android-release.bundle \
-  --sourcemap-output android-release.bundle.map
+Programmatic API:
 
-# Hermes-compile (if Hermes is enabled — the default on RN 0.70+)
-hermes-compiler --emit-binary --output-source-map \
-  -out android-release.hbc android-release.bundle
+```js
+const { uploadReactNativeSourcemap } = require("@allstak/react-native/sourcemaps");
 
-# Upload to AllStak — debugId injection + map upload
-node -e "import('@allstak/js/sourcemaps').then(({ processBuildOutput }) => \
-  processBuildOutput({ dir: '.', release: process.env.RELEASE, \
-    token: process.env.ALLSTAK_UPLOAD_TOKEN }))"
+await uploadReactNativeSourcemap({
+  platform: "ios",
+  bundle: "path/to/main.jsbundle",
+  sourcemap: "path/to/main.jsbundle.map",
+  release: "mobile@1.2.3+45",
+  dist: "ios-hermes",
+  token: process.env.ALLSTAK_UPLOAD_TOKEN,
+});
 ```
 
-For iOS (`react-native bundle --platform ios`) the same flow applies.
-Add this as a release-only step in your CI; the runtime SDK reads the
-`debugId` from each frame and resolves the matching map server-side.
+How matching works:
 
-> **Status:** the upload pipeline is the same one used by the web SDK
-> and is unit-tested in `@allstak/js/tests/sourcemaps-*.test.ts`. Native
-> Hermes-bytecode mapping has not yet been integration-tested end-to-end
-> against the AllStak symbolicator on a real device build — flag any
-> off-by-one source maps in [issues](https://github.com/AllStak/allstak-react-native/issues).
+- `debugId` is injected into the bundle and the source map.
+- The backend matches stack frames using `debugId`, `release`, and `dist`.
+- Maps are uploaded to `/api/v1/artifacts/upload`.
+- Upload auth uses `X-AllStak-Upload-Token`; do not use the runtime `ask_live_...` API key.
+
+If no upload token is present, the hook can run in inject-only mode so CI can still produce bundles with debug IDs without uploading artifacts.
+
+## 9. Native Crashes
+
+JS errors are verified. Native crash files exist for iOS and Android, and the SDK exports a drain API:
+
+```ts
+import { drainPendingNativeCrashes } from "@allstak/react-native";
+
+await drainPendingNativeCrashes("mobile@1.2.3+45");
+```
+
+The provider does not call `drainPendingNativeCrashes()` automatically. Call it once early after SDK initialization, before user flows start:
+
+```tsx
+import { AllStakProvider, drainPendingNativeCrashes } from "@allstak/react-native";
+import { useEffect } from "react";
+
+function AppRoot() {
+  useEffect(() => {
+    drainPendingNativeCrashes("mobile@1.2.3+45");
+  }, []);
+
+  return <Routes />;
+}
+```
+
+Current verification status:
+
+- iOS native crash capture and drain were verified end-to-end on an iOS simulator.
+- Android native crash capture code exists and has parity with iOS, but emulator/device verification was not completed in the latest report.
+- Do not mark Android native crash capture production-ready until an Android emulator or device run proves crash -> relaunch -> drain -> backend ingest.
+
+Native modules are not available in Expo Go. Use a dev client or native build for native crash verification.
+
+## 10. Privacy Defaults
+
+- Headers are off by default.
+- Request bodies are off by default.
+- Response bodies are off by default.
+- `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token`, and `Proxy-Authorization` are always redacted.
+- Sensitive query parameters such as `token`, `password`, `api_key`, `authorization`, `secret`, `access_token`, `refresh_token`, and `jwt` are redacted.
+- `console.log` and `console.info` are off by default.
+- `console.warn` and `console.error` are captured as breadcrumbs by default.
+- Source maps containing `sourcesContent` may be rejected when organization privacy mode requires stripped sources. Use `stripSources: true` or configure your build hook accordingly.
+
+## 11. Troubleshooting
+
+### Events not appearing
+
+- Confirm `apiKey` is the runtime project key and starts with `ask_live_...`.
+- Enable `debug` and check for `[AllStak] Initialized — session <id>`.
+- Confirm the app can reach `https://api.allstak.sa`.
+- For self-hosted installs, pass `host="https://your-api.example.com"`.
+- Check the project/environment you are viewing in the dashboard.
+
+### Wrong `apiKey`
+
+Runtime ingestion uses the project API key. Source-map upload uses `ALLSTAK_UPLOAD_TOKEN`. They are different credentials and are not interchangeable.
+
+### Upload token vs runtime API key confusion
+
+- `apiKey="ask_live_..."`: ships runtime errors/logs/breadcrumbs.
+- `ALLSTAK_UPLOAD_TOKEN=aspk_...`: uploads source maps and artifacts in CI.
+- Never put the upload token in app code.
+
+### Source maps uploaded but stack is not symbolicated
+
+- Ensure the runtime `release` matches `ALLSTAK_RELEASE`.
+- Ensure runtime `dist` matches the uploaded map's `dist`.
+- Confirm the event contains a matching `debugId` or release/dist combination.
+- Confirm the map was uploaded to the same project as the runtime API key.
+
+### Release/dist mismatch
+
+Use stable release names such as `mobile@1.2.3+45` and platform dists such as `ios-hermes`, `android-hermes`, `ios-jsc`, or `android-jsc`. Mismatched values prevent backend joining between event and source map.
+
+### Hermes stacks not resolving
+
+Hermes stack traces need the correct Metro/Hermes source-map chain. Use the provided build hooks instead of uploading a random map file from an intermediate build step.
+
+### Navigation breadcrumbs not appearing
+
+- In Metro-native builds, use `instrumentReactNavigation(navigationRef)`.
+- Confirm `NavigationContainer` has mounted and `onReady` fires.
+- Avoid deep imports that bypass `@react-navigation/native`.
+- Enable `debug` to see whether auto navigation instrumentation was applied or skipped.
+
+### Metro / Expo issues
+
+- Rebuild after adding native modules or source-map hooks.
+- Expo Go cannot load custom native crash modules.
+- For native crash testing, use an Expo dev client, simulator build, or physical device build.
+
+### Android Gradle hook not running
+
+- Confirm the `apply from` path is relative to `android/app/build.gradle`.
+- Confirm `ALLSTAK_RELEASE` and `ALLSTAK_UPLOAD_TOKEN` are visible to Gradle.
+- Run with `--info` to verify the AllStak source-map task executes.
+
+### Xcode build phase path wrong
+
+- The recommended path is `"${SRCROOT}/../node_modules/@allstak/react-native/build-hooks/xcode-build-phase.sh"`.
+- Place the phase after React Native bundles JS.
+- Confirm the script has executable permissions after install.
+
+### AppState breadcrumbs not easy to test
+
+The listener registers at startup, but actual foreground/background transitions depend on simulator/device behavior. Verify by backgrounding and foregrounding the app, then capturing an error so breadcrumbs attach.
+
+### Docker/backend local issue is not an SDK issue
+
+If local backend testing returns `401 INVALID_API_KEY` or nothing reaches ClickHouse, verify the API key exists in the same database used by the running backend. The latest backend verification report found that using the wrong local Postgres instance caused false SDK failures.
+
+## 12. Verification Status
+
+Latest verification reports are in `docs/reports/`:
+
+- `react-native-provider-verification.md`
+- `react-native-backend-ingestion-verification.md`
+- `react-native-production-readiness.md`
+- `console-and-navigation-auto.md`
+
+Current status from those reports:
+
+| Area | Status |
+| --- | --- |
+| Unit tests | Latest production-readiness report: 132 passing total, including 126 unit tests and 6 live backend-contract tests. Earlier provider report recorded 98/98 before later additions. |
+| iOS simulator verified paths | Provider init, render errors, global JS errors, unhandled promises, manual exception/message, console warn/error defaults, console log/info opt-in behavior, fetch breadcrumbs, HTTP 4xx/5xx/network failure, full HTTP request events, device/platform/Hermes/dist tags, manual React Navigation breadcrumbs, iOS native crash drain. |
+| Android emulator verified paths | Not completed in latest production-readiness pass; emulator boot was blocked by disk. Android native crash and JS paths remain implemented but not device-verified. |
+| Backend ingestion verified paths | `/ingest/v1/errors`, `/ingest/v1/logs`, `/ingest/v1/http_requests`; 8 canonical curl payload shapes accepted; live SDK events landed in ClickHouse; backend-contract tests cover buffering and invalid-key resilience. |
+| Source-map backend status | `/api/v1/artifacts/upload` upload path exists and build hooks inject/upload debug-ID source maps. Full Hermes symbolication remains dependent on matching release/dist/debugId and should be validated per app release pipeline. |
+| Remaining gaps | Android device/emulator verification, persistent offline queue, full AppState transition verification, and per-project source-map symbolication verification in release CI. |
 
 ## Links
 
-- Documentation: https://docs.allstak.sa
 - Dashboard: https://app.allstak.sa
+- Documentation: https://docs.allstak.sa
 - Source: https://github.com/allstak-io/allstak-react-native
 
 ## License