### Start Metro Server

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/CONTRIBUTING.md

Run the Metro server to prepare for app development. Use `yarn start:reset` to ensure a clean start.

```bash
yarn start:reset
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Install project dependencies using Yarn. Ensure Node.js (v18+) and Yarn are installed.

```bash
yarn install
```

--------------------------------

### Clone PocketPal AI Repository

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Clone the repository to start development. Ensure you have Git installed.

```bash
git clone https://github.com/a-ghorbani/pocketpal-ai
cd pocketpal-ai
```

--------------------------------

### Install Dependencies

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Install project dependencies for end-to-end testing.

```bash
cd e2e
yarn install
```

--------------------------------

### Setup Multi-Device Inventory

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Instructions for setting up the `devices.json` file required for the `--each-device` flag. This involves copying a template and editing it with actual device information.

```bash
cp devices.template.json devices.json
```

--------------------------------

### Start Metro Bundler

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Start the Metro bundler, which is necessary for running React Native applications.

```bash
yarn start
```

--------------------------------

### List Available Device Pools

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/DEVICE-POOLS.md

Command to display all configured device pools. Useful for debugging and verifying pool setup.

```bash
yarn crash-repro --list-pools
```

--------------------------------

### Install iOS Pod Dependencies

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Install CocoaPods dependencies for iOS development. Run this command after installing Node.js dependencies.

```bash
cd ios
pod install
cd ..
```

--------------------------------

### Include React Native Application Setup

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/android/app/src/main/jni/CMakeLists.txt

Includes the React Native CMake utility script to enable autolinking, TurboModule registration, and prefab linkage to libreactnative.so. This is crucial for the application to boot correctly.

```cmake
include(${REACT_ANDROID_DIR}/cmake-utils/ReactNative-application.cmake)
```

--------------------------------

### Build and Install E2E Android Flavor

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Commands to build the E2E flavor of the Android app and install it on a device. This flavor is debuggable and required for the preseed workflow.

```bash
yarn android:build:e2e
adb install -r android/app/build/outputs/apk/e2e/releaseE2e/app-e2e-releaseE2e.apk
```

--------------------------------

### Filter Benchmark Matrix Configuration

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Narrow down the benchmark tier by specifying models and quantizations. This command assumes the E2E-flavor APK is installed.

```bash
BENCH_TIER=full BENCH_MODELS=qwen3.5-2b BENCH_QUANTS=q4_0,q6_k yarn build:bench-config
```

--------------------------------

### E2E Benchmark Runner Screen Activation

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/__automation__/README.md

This example shows how the `BenchmarkRunnerScreen` is activated via a deep link. It highlights the URL format `pocketpal://e2e/benchmark` used for navigation and mentions its registration in the Android manifest.

```typescript
case 'e2e/benchmark':
  return navigation.navigate('BenchmarkRunnerScreen');
```

--------------------------------

### Find Device UDIDs for Multi-Device Setup

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Commands to find device UDIDs for both iOS and Android, which are necessary for configuring `devices.json` for multi-device testing.

```bash
# iOS
xcrun xctrace list devices
```

```bash
# Android
adb devices -l
```

--------------------------------

### Expected Validation for Memory Residency Hazard Sweep

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/baselines/benchmark/SWEEP-PLAN.md

This example illustrates the expected memory behavior (PSS_post_load) for different combinations of mmap and repack settings on the Android CPU path. It highlights the hazard scenario where mmap=true and repack=ON can lead to approximately double the memory usage compared to weights_mib, and safe scenarios where memory usage is around 1x.

```text
qwen3-1.7b q4_0  cpu  mmap=true  repack=ON   → PSS_post_load ≈ 2× weights_mib  (HAZARD)
                      mmap=true  repack=OFF  → PSS_post_load ≈ 1× weights_mib  (SAFE)
                      mmap=false repack=ON   → PSS_post_load ≈ 1× weights_mib  (slow load, safe)
                      mmap=false repack=OFF  → PSS_post_load ≈ 1× weights_mib  (slow load, safe)
```

--------------------------------

### Build Android E2E APK

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Builds the E2E flavor of the Android application. This APK includes the automation bridge and installs side-by-side with the production app.

```bash
# Android E2E APK (required — prod APK has no automation bridge)
yarn android:build:e2e
# Installs as com.pocketpalai.e2e and coexists side-by-side with the
# prod install (com.pocketpalai). E2E_BUILD=true is set automatically
# so the automation bridge (src/__automation__/) ships in this APK.
```

--------------------------------

### Add Custom Source Files

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/android/app/src/main/jni/CMakeLists.txt

Explicitly adds custom C++ source files to the target. This is done after including the React Native setup to avoid conflicts with the default template's file globbing.

```cmake
target_sources(${CMAKE_PROJECT_NAME} PRIVATE src/hardware_info.cpp)
```

--------------------------------

### Run Benchmark Matrix Config

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Generate configuration for the benchmark matrix and push it to the device. Supports specifying a tier and a specific device UDID.

```bash
# 1. Generate config + adb push to device
BENCH_TIER=smoke yarn build:bench-config --push           # default device
BENCH_TIER=full  yarn build:bench-config --push <udid>    # specific device
```

--------------------------------

### Run Benchmark with Preseeded Models

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute the benchmark matrix while skipping model downloads by setting the `MODELS_PRESEEDED` environment variable to `1`. This assumes models are already available on the device.

```bash
# Preseeded mode (see "Preseed workflow" below)
MODELS_PRESEEDED=1 yarn e2e --platform android --spec benchmark-matrix --skip-build
```

--------------------------------

### List Available E2E Models

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

List all available models that can be used for end-to-end testing and then exit. This is useful for understanding the testing scope.

```bash
yarn e2e --list-models
```

--------------------------------

### Run App on iOS

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/CONTRIBUTING.md

Execute the command to run the application on an iOS simulator or device.

```bash
yarn ios
```

--------------------------------

### Run Full Benchmark Matrix on Android

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute the complete benchmark matrix on a connected Android device. This command may take 25-45 minutes. `--skip-build` is recommended if the project is already built.

```bash
# Full matrix on the currently connected Android device (~25-45 min)
yarn e2e --platform android --spec benchmark-matrix --skip-build
```

--------------------------------

### Run App on Android

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/CONTRIBUTING.md

Execute the command to run the application on an Android emulator or device.

```bash
yarn android
```

--------------------------------

### Initialize CMake and Project

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/android/app/src/main/jni/CMakeLists.txt

Sets the minimum CMake version required and defines the project name, which is expected by React Native's SoLoader for library mapping.

```cmake
cmake_minimum_required(VERSION 3.13)

project(appmodules)
```

--------------------------------

### Launch Benchmark Runner via Deep Link

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Cold-launch the benchmark runner application using a deep link. This command is for Android devices.

```bash
# 2. Cold-launch the runner via deep link
adb shell am start -a android.intent.action.VIEW \
  -d 'pocketpal://e2e/benchmark' -p com.pocketpalai.e2e
```

--------------------------------

### Memory Adapter Commands

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/__automation__/README.md

This table lists the commands supported by the `MemoryAdapter` for memory profiling. These commands are used by the `memory-profile` spec to interact with the E2E automation bridge.

```markdown
| Adapter | Purpose |
|---|---|
| `MemoryAdapter` | Memory profile snapshots for the `memory-profile` spec | `snap::<label>`, `clear::snapshots`, `read::snapshots` |
```

--------------------------------

### Run Single Benchmark Cell with Environment Variables

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute a specific benchmark cell by setting environment variables for models, quantizations, and backends. This is useful for targeted testing or debugging.

```bash
# Single cell (smoke)
BENCH_MODELS=qwen3-1.7b BENCH_QUANTS=q4_0 BENCH_BACKENDS=cpu \
  yarn e2e --platform android --spec benchmark-matrix --skip-build
```

--------------------------------

### Push Branch and Open Pull Request

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Push your feature branch to the remote repository and open a pull request for review.

```bash
git push origin feature/your-feature-name
```

--------------------------------

### Run E2E Tests on AWS Device Farm

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute end-to-end tests using AWS Device Farm. This requires AWS credentials and a Device Farm project ARN to be set up.

```bash
yarn e2e:aws --platform android --app path/to/app.apk
```

--------------------------------

### Backend Selection Rule

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/baselines/benchmark/SWEEP-PLAN.md

This rule defines a decision tree for selecting the optimal backend based on device capabilities (Hexagon, OpenCL) and workload type (pp_workload, tg-dominant chat). It prioritizes Hexagon for specific quantizations and workloads, falls back to GPU (OpenCL) if available, and defaults to CPU.

```plaintext
RULE — Backend selection (decision tree, top-down):
  if has_hexagon AND quant ∈ {q4_0, q8_0, MXFP4}:
    if pp_workload_dominant: backend = hexagon
    else (tg-dominant chat):  backend = gpu (Adreno OpenCL) — usually wins tg
  elif has_working_opencl:
    backend = gpu
  else:
    backend = cpu
```

--------------------------------

### Execute Multi-Device E2E Tests on iOS

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Run end-to-end tests on iOS, iterating through devices defined in `devices.json`. Use `--skip-build` to avoid rebuilding the app if it's already built.

```bash
yarn e2e:ios --each-device
```

```bash
yarn e2e:ios --devices virtual-only --skip-build
```

--------------------------------

### Run E2E Tests on Connected Android Devices

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute end-to-end tests on Android devices that are currently connected via USB. `--skip-build` is used to reuse existing builds.

```bash
yarn e2e:android --devices connected --skip-build
```

--------------------------------

### Build iOS E2E App

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Builds the E2E version of the iOS application for the simulator.

```bash
# iOS simulator
yarn ios:build:e2e
```

--------------------------------

### Pass Device Pool ARN via Command Line

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/DEVICE-POOLS.md

Specify the device pool ARN directly on the command line when running the crash reproduction test. This allows for ad-hoc testing with specific pools.

```bash
yarn crash-repro --model gemma-2-2b --device-pool "arn:aws:devicefarm:us-west-2:123456789:devicepool:abc123..."
```

--------------------------------

### Compare Benchmark Reports

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Command to compare two benchmark JSON reports using the provided TypeScript script. It highlights regressions in performance metrics and backend usage.

```bash
npx tsx e2e/scripts/benchmark-compare.ts \
  path/to/baseline.json path/to/current.json
```

--------------------------------

### Run Unit Tests with Jest

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/CONTRIBUTING.md

Execute unit tests using Jest. Ensure all new features and changes are adequately tested.

```bash
yarn test
```

--------------------------------

### Run Crash Reproduction with Environment Variable

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/DEVICE-POOLS.md

Execute the crash reproduction test using the device pool ARN set in the environment variable. This command targets a specific model.

```bash
yarn crash-repro --model gemma-2-2b
```

--------------------------------

### Run Crash Reproduction Locally

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/DEVICE-POOLS.md

Execute the crash reproduction test in a local environment. This is recommended for initial debugging and faster iteration cycles.

```bash
yarn crash-repro --model gemma-2-2b --local
```

--------------------------------

### Deep Link Dispatcher for E2E

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/__automation__/README.md

This code illustrates the `dispatchAutomationDeepLink` function used to handle E2E-specific deep links. It shows how different hosts like 'memory' and 'e2e/benchmark' are routed to their respective functionalities.

```typescript
export const dispatchAutomationDeepLink = (
  url: string,
  navigation: NavigationContainerRef<ReactNavigation.RootParamList>
) => {
  const { host, path, queryParams } = parse(url);

  switch (host) {
    case 'memory':
      return handleMemoryDeepLink(path, queryParams, navigation);
    case 'e2e/benchmark':
      return navigation.navigate('BenchmarkRunnerScreen');
    default:
      return false;
  }
};
```

--------------------------------

### Run Local E2E Tests

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute end-to-end tests locally using the unified runner command. Specify the platform (iOS or Android) and the test spec to run.

```bash
# Simple smoke test on default device
yarn e2e:ios --spec quick-smoke
yarn e2e:android --spec quick-smoke
```

--------------------------------

### Build iOS E2E IPA

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Builds the E2E version of the iOS application as an IPA file, suitable for real devices. Requires code signing.

```bash
# iOS real device (IPA, requires code signing)
yarn ios:build:ipa
```

--------------------------------

### Push GGUF Model via ADB

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Steps to push a GGUF model file to the device's app-private storage using ADB. This is part of the preseed workflow to avoid HuggingFace downloads.

```bash
adb shell run-as com.pocketpalai.e2e mkdir -p \
  files/models/hf/bartowski/Qwen_Qwen3-1.7B-GGUF

# copy via /data/local/tmp to avoid run-as's stdin limitations:
adb push Qwen_Qwen3-1.7B-Q4_0.gguf /data/local/tmp/
adb shell run-as com.pocketpalai.e2e sh -c \
  'cat /data/local/tmp/Qwen_Qwen3-1.7B-Q4_0.gguf > \
   files/models/hf/bartowski/Qwen_Qwen3-1.7B-GGUF/Qwen_Qwen3-1.7B-Q4_0.gguf'
```

--------------------------------

### Lint Code with ESLint

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/CONTRIBUTING.md

Apply ESLint to check for code style and potential errors. Ensure your code adheres to project standards.

```bash
yarn lint
```

--------------------------------

### Top-Level Benchmark Report Schema

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Defines the overall structure for benchmark reports, including device information, commit hash, and a list of benchmark runs.

```json
{
  "version": "1.0",
  "device": "SM-S948U",
  "soc": "Snapdragon 8 Elite Gen 2",   // or null
  "commit": "abc1234",
  "llama_rn_version": "0.12.0-rc.8",
  "platform": "android",
  "os_version": "16",
  "timestamp": "2026-04-21T…",
  "preseeded": false,
  "runs": [ /* BenchmarkRun[] */ ]
}
```

--------------------------------

### Direct WDIO Command Execution

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute WDIO tests directly, allowing for custom configurations and spec file targeting. This is useful for ad-hoc runs or when specific WDIO flags are needed.

```bash
npx wdio run wdio.ios.local.conf.ts --spec specs/quick-smoke.spec.ts
```

```bash
npx wdio run wdio.android.local.conf.ts --spec specs/load-stress.spec.ts
```

--------------------------------

### Quantization Selection Rule per RAM

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/baselines/benchmark/SWEEP-PLAN.md

This rule dynamically selects the maximum allowed quantization type based on available free RAM. It restricts quantization to `q4_K_M` for less than 4GB, `q5_K_M` for less than 6GB, and allows `q8_0` (if supported by the backend) for 8GB or more.

```plaintext
RULE — Quant selection per RAM:
  if ram_free < 4 GB:  quant ≤ q4_K_M
  if ram_free < 6 GB:  quant ≤ q5_K_M
  if ram_free >= 8 GB: quant ≤ q8_0 if backend supports it
```

--------------------------------

### Per-Run Benchmark Data Schema

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Details the schema for individual benchmark runs, including model information, performance metrics, memory usage, and backend details.

```json
{
  "model_id": "qwen3-1.7b",
  "quant": "q4_0",                      // canonical lowercase rung label
  "requested_backend": "cpu",           // "cpu" | "gpu"
  "effective_backend": "cpu",           // see below
  "pp_avg": 123.4,                      // tokens/s, nullable
  "tg_avg": 18.2,                       // tokens/s, nullable
  "wall_ms": 24571,
  "peak_memory_mb": 812.3,              // nullable
  "log_signals": {                      // structured — see src/__automation__/logSignals.ts
    "opencl_init": true,
    "opencl_device_name": "QUALCOMM Adreno(TM) 840",
    "adreno_gen": "A8X",
    "large_buffer_enabled": true,
    "large_buffer_unsupported": false,
    "offloaded_layers": 29,
    "total_layers": 29,
    "raw_matches": [ /* up to 200 matched native-log lines, debug only */ ]
  },
  "init_settings": { /* modelStore.contextInitParams snapshot */ },
  "status": "ok",                       // "ok" | "skipped" | "failed"
  "reason": "…",                        // set on skipped
  "error": "…",                         // set on failed (first 500 chars)
  "timestamp": "2026-04-21T…"
}
```

--------------------------------

### Run E2E Tests on iOS with Each Model

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Execute end-to-end tests on iOS, running each specified model in isolation. This is useful for testing individual model performance and behavior.

```bash
yarn e2e:ios --each-model
```

```bash
yarn e2e:ios --each-model --models smollm2-135m,qwen3-0.6b
```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Clean the project's build artifacts. Useful for resolving build issues.

```bash
yarn clean
```

--------------------------------

### Lint and Type Check Code

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Run ESLint for linting and TypeScript for type checking to maintain code quality.

```bash
yarn lint
yarn typecheck
```

--------------------------------

### Full Matrix E2E Test Run on iOS

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Perform a comprehensive end-to-end test run on iOS, executing every model on every available device. This provides maximum test coverage.

```bash
yarn e2e:ios --each-device --each-model
```

--------------------------------

### Benchmark Runner Screen Purpose

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/__automation__/README.md

This table describes the `BenchmarkRunnerScreen` and its purpose in driving the benchmark matrix for the `benchmark-matrix` spec. It also details its activation method via deep link.

```markdown
| Screen | Purpose |
|---|---|
| `BenchmarkRunnerScreen` | Drives the benchmark matrix in-app for the `benchmark-matrix` spec | Deep link `pocketpal://e2e/benchmark` (registered in `android/app/src/e2e/AndroidManifest.xml`); manual button tap to start |
```

--------------------------------

### Validate Localization Files

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/CONTRIBUTING.md

Check the validity of JSON localization files and ensure placeholders are consistent. This command is crucial for maintaining translation integrity.

```bash
yarn l10n:validate
```

--------------------------------

### Run Crash Reproduction on Target Device Pool

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/DEVICE-POOLS.md

Execute the load-stress test on a specific device pool in AWS Device Farm. This command is used for verifying fixes on problematic devices.

```bash
yarn crash-repro --model gemma-2-2b --device-pool arn:aws:...
```

--------------------------------

### Adding a New E2E Adapter

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/__automation__/README.md

This code snippet shows how to render a new E2E adapter component within the `AutomationBridge.tsx` file. This is part of the process for adding new automation surfaces that instrument the regular UX flow.

```typescript
<>
  <MemoryAdapter />
  <FooAdapter />
</>
```

--------------------------------

### Find and Link Log Library

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/android/app/src/main/jni/CMakeLists.txt

Locates the Android logging library and links it to the project. This is necessary for any logging operations performed in the native code.

```cmake
find_library(log-lib log)
target_link_libraries(${CMAKE_PROJECT_NAME} ${log-lib})
```

--------------------------------

### Create New Git Branch

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Use this command to create a new branch for your feature or bug fix.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Dry Run E2E Tests

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Perform a dry run of end-to-end tests across both iOS and Android platforms, iterating through all devices and models. This command previews the test execution without actually running the tests.

```bash
yarn e2e --platform both --each-device --each-model --dry-run
```

--------------------------------

### Set Device Pool ARN via Environment Variable

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/DEVICE-POOLS.md

Configure the AWS Device Pool ARN in your .env file for automated testing. This is useful for persistent configurations.

```bash
# e2e/.env
AWS_DEVICE_POOL_ARN_ANDROID="arn:aws:devicefarm:us-west-2:123456789:devicepool:abc123..."
```

--------------------------------

### Include Crash-Reproduction Models in E2E Tests

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Run end-to-end tests on iOS, ensuring that models known to cause crashes are included in the test pool along with all other models.

```bash
yarn e2e:ios --each-model --all-models
```

--------------------------------

### Memory Hazard Guard Rule (Android CPU)

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/baselines/benchmark/SWEEP-PLAN.md

This rule implements a memory hazard guard for Android devices using the CPU backend, specifically when using repacking quantization types. It enforces `no_extra_bufts=true` if free RAM is insufficient to prevent duplicate residency, and allows `no_extra_bufts=false` for faster steady-state performance when ample RAM is available, with a warning for approaching peak usage.

```plaintext
RULE — Memory hazard guard (Android CPU):
  if backend == 'cpu' AND quant ∈ REPACK_TYPES:
    if ram_free < model_size * 2 + KV_estimate + 500MB:
      MUST: no_extra_bufts=true   (avoid duplicate residency)
    else:
      MAY: no_extra_bufts=false   (faster steady-state; warn UI when peak approaches jetsam)
```

--------------------------------

### Reproduce Crashes with Load Stress on a Specific Model

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Run end-to-end tests on iOS with a load-stress spec to reproduce crashes, focusing on a specific model. This helps in debugging stability issues.

```bash
yarn e2e --platform ios --spec load-stress --models gemma-2-2b
```

--------------------------------

### KV Cache Quantization Rule

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/baselines/benchmark/SWEEP-PLAN.md

This rule optimizes KV cache memory usage by selecting quantization based on context length (`n_ctx`) and Flash Attention (FA) support. For contexts of 4096 or greater with FA support, it recommends `q8_0/q8_0` for significant memory savings with minimal quality loss. Otherwise, it defaults to `f16/f16`.

```plaintext
RULE — KV quant:
  if n_ctx >= 4096 AND backend supports FA:
    KV = q8_0/q8_0  (~50% KV memory savings, minimal quality loss reported)
  else:
    KV = f16/f16
```

--------------------------------

### Merge Benchmark Reports

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Merge multiple raw benchmark reports into a single baseline JSON file. This script dedupes entries, drops stale models, sorts deterministically, and strips debug logs.

```bash
npx ts-node scripts/merge-bench-reports.ts \
  --input '/path/to/benchmark-report-*.json' \
  --out baselines/benchmark/<device-slug>.json \
  --device 'POCO X9 Pro Myron' \
  --soc 'Snapdragon 8 Elite Gen 5 / Adreno 840' \
  --commit "$(git rev-parse --short HEAD)" \
  --llama-rn-version "$(node -p 'require(\"../package.json\").dependencies[\"llama.rn\"]')" \
  --drop-models lfm2-1.2b
```

--------------------------------

### Conditional E2E Code Execution

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/__automation__/README.md

This code demonstrates how to conditionally include E2E automation code based on the `__E2E__` global variable, which is set at build time. This ensures automation code is only included in E2E builds and stripped from production bundles.

```javascript
if (__E2E__) {
  // E2E-specific code here
  console.log('Running E2E automation code...');
}
```

--------------------------------

### Commit Changes with Conventional Commits

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/README.md

Commit your changes following the Conventional Commits specification for clear commit messages.

```bash
git commit -m "feat: add new model support"
```

--------------------------------

### Cross-Platform Selectors for UI Elements

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Utilize `testID` and `accessibilityLabel` for robust cross-platform element selection. Supports exact text matches and partial text matches.

```typescript
import {Selectors} from '../helpers/selectors';

// By testID
await $(Selectors.byTestId('send-button')).click();

// By text (exact match)
await $(Selectors.byText('Models')).click();

// By partial text
await $(Selectors.byPartialText('Download')).click();

// By accessibility label
await $(Selectors.byAccessibilityLabel('Chat input')).click();
```

--------------------------------

### Type Check Code with TypeScript

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/CONTRIBUTING.md

Use TypeScript to perform static type checking on your code. This helps catch type-related errors before runtime.

```bash
yarn typecheck
```

--------------------------------

### Page Object Pattern for Common Interactions

Source: https://github.com/a-ghorbani/pocketpal-ai/blob/main/e2e/README.md

Employ page objects to encapsulate common UI interactions, promoting code reusability and maintainability.

```typescript
import {ChatPage, DrawerPage, ModelsPage} from '../pages';

await ChatPage.openDrawer();
await DrawerPage.navigateToModels();
await ModelsPage.openHuggingFaceSearch();
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.