update docs

abueide · abueide · commit 3ec85f2a39d8 · 2026-02-18T17:16:28.000-06:00
diff --git a/wiki/guides/android-guide.md b/wiki/guides/android-guide.md
@@ -33,14 +33,11 @@ Create or modify your `devbox.json` to include the Android plugin:
   "packages": {
     "jdk17": "latest",
     "gradle": "latest"
-  },
-  "env": {
-    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk"
   }
 }
 ```
 
-The `include` line adds the plugin. The `packages` section adds your build tooling. Set `ANDROID_APP_APK` to where your build outputs the APK.
+The `include` line adds the plugin. The `packages` section adds your build tooling. APK paths are auto-detected at runtime when you deploy.
 
 ### Initial Setup
 
@@ -228,12 +225,9 @@ The plugin provides emulator and device management. Build and deploy commands ar
     "jdk17": "latest",
     "gradle": "latest"
   },
-  "env": {
-    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk"
-  },
   "shell": {
     "scripts": {
-      "build": [
+      "build:android": [
         "gradle assembleDebug --info"
       ],
       "start:app": [
@@ -250,7 +244,7 @@ With these scripts defined, you can:
 
 ```bash
 # Build the APK
-devbox run build
+devbox run build:android
 
 # Build, install, and launch on the emulator
 devbox run start:app
@@ -259,7 +253,23 @@ devbox run start:app
 devbox run start:app min
 ```
 
-The `android.sh run` command waits for the emulator to boot, installs the APK, and launches the app. The app's package name is auto-detected from the APK.
+**How APK auto-detection works:** The `android.sh run` command waits for the emulator to boot, then auto-detects the APK using this precedence chain:
+
+1. `ANDROID_APP_APK` env var — if set, resolves the path/glob relative to project root
+2. Recursive search of the project directory for `.apk` files, skipping `.gradle/`, `build/intermediates/`, `node_modules/`, and `.devbox/`
+3. Recursive search of the current working directory (if different from project root)
+
+The app's package name and launch activity are extracted from the APK automatically.
+
+In most projects, step 2 finds the right APK with no configuration. If auto-detection picks the wrong APK (e.g., multiple build variants), set `ANDROID_APP_APK` explicitly:
+
+```json
+{
+  "env": {
+    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk"
+  }
+}
+```
 
 See the [Android example project](../../examples/android/) for a complete working setup.
 
@@ -360,7 +370,6 @@ Configure the plugin by setting environment variables in `devbox.json`:
 {
   "env": {
     "ANDROID_DEFAULT_DEVICE": "max",
-    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk",
     "ANDROID_BUILD_TOOLS_VERSION": "36.1.0",
     "ANDROID_COMPILE_SDK": "36",
     "ANDROID_TARGET_SDK": "36"
@@ -370,7 +379,7 @@ Configure the plugin by setting environment variables in `devbox.json`:
 
 Key variables:
 - `ANDROID_DEFAULT_DEVICE` - Default device when none specified
-- `ANDROID_APP_APK` - Path or glob pattern for APK
+- `ANDROID_APP_APK` - Path or glob pattern for APK (empty = auto-detect)
 - `ANDROID_BUILD_TOOLS_VERSION` - Build tools version
 - `ANDROID_COMPILE_SDK` - Compile SDK version
 - `ANDROID_TARGET_SDK` - Target SDK version
@@ -482,10 +491,9 @@ Run `devbox shell` after changing `devbox.json` to apply the new values. To rese
 
 **Solutions**:
 
-1. Verify APK path is correct:
+1. Verify the APK exists (check your build output directory):
    ```bash
-   echo $ANDROID_APP_APK
-   ls -l $ANDROID_APP_APK
+   find . -name '*.apk' -not -path '*/.gradle/*' -not -path '*/intermediates/*'
    ```
 
 2. Check if app is already installed:
diff --git a/wiki/guides/ios-guide.md b/wiki/guides/ios-guide.md
@@ -10,8 +10,9 @@ The iOS plugin enables reproducible iOS development by automatically discovering
 - **Automatic Xcode discovery**: Multi-strategy detection with caching for fast shell initialization
 - **Device management**: JSON-based device definitions with CLI commands for creating, updating, and managing simulators
 - **Simulator control**: Scripts for starting and stopping simulators
+- **App deployment**: `ios.sh run` auto-detects your `.app` bundle, extracts the bundle ID, and deploys to the simulator
 
-The plugin does **not** provide build or deploy commands. Every project has different Xcode configurations (project vs. workspace, different schemes, different derived data paths), so you define those in your own `devbox.json`. See [Adding Build Scripts](#adding-build-and-deploy-scripts) for patterns.
+The plugin auto-detects your Xcode project, `.app` path, and bundle ID at runtime. You define a `build:ios` script in your `devbox.json` to handle the actual Xcode build, then `ios.sh run` handles everything else. See [Adding Build Scripts](#adding-build-and-deploy-scripts) for patterns.
 
 Pure shells with `devbox run --pure` create test-specific simulators and clean up after execution, ensuring isolated, reproducible testing.
 
@@ -34,7 +35,7 @@ Create or modify your `devbox.json` to include the iOS plugin:
 }
 ```
 
-The Xcode project, build scheme, bundle ID, and app path are all auto-detected at runtime. Use `-derivedDataPath DerivedData` in your xcodebuild command to keep build output project-local.
+Use `-derivedDataPath DerivedData` in your xcodebuild command to keep build output project-local.
 
 ### Initial Setup
 
@@ -250,9 +251,26 @@ The plugin provides simulator and device management. Build and deploy commands a
 }
 ```
 
-The `ios.sh run` command starts the simulator, builds (via `build:ios`), auto-detects the .app bundle, extracts the bundle ID, installs, and launches. The `${1:-}` syntax passes an optional device nickname through.
+The `ios.sh run` command handles the full deployment pipeline: starts the simulator, runs your `build:ios` script, auto-detects the `.app` bundle, extracts the bundle ID from `Info.plist`, installs, and launches. The `${1:-}` syntax passes an optional device nickname through.
 
-With these scripts defined, you can:
+**How app auto-detection works:** After building, `ios.sh run` finds your `.app` bundle using this precedence chain:
+
+1. `IOS_APP_ARTIFACT` env var — if set, resolves the path/glob relative to project root
+2. `xcodebuild -showBuildSettings` — queries your Xcode project for BUILT_PRODUCTS_DIR + FULL_PRODUCT_NAME
+3. Recursive search of the project directory for `.app` bundles, skipping `Pods/`, `.build/`, `node_modules/`, `.devbox/`, and similar directories
+4. Recursive search of the current working directory (if different from project root)
+
+In most projects, step 2 or 3 finds the right `.app` automatically with no configuration needed. If auto-detection doesn't work (e.g., multiple `.app` bundles, non-standard project layout), set `IOS_APP_ARTIFACT` explicitly:
+
+```json
+{
+  "env": {
+    "IOS_APP_ARTIFACT": "DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app"
+  }
+}
+```
+
+With the scripts defined above, you can:
 
 ```bash
 # Build the app
@@ -275,16 +293,11 @@ Typical development session:
 # 1. Enter devbox shell
 devbox shell
 
-# 2. Start simulator
-devbox run start:sim max
-
-# 3. Build and deploy app (using your custom scripts)
-devbox run build
-devbox run start:app max
+# 2. Build and deploy (starts simulator, builds, installs, and launches)
+devbox run start:app
 
-# 4. Make code changes, rebuild, and redeploy
-devbox run build
-devbox run start:app max
+# 3. Make code changes, rebuild, and redeploy
+devbox run start:app
 
 # 5. Stop simulator when done
 devbox run stop:sim
diff --git a/wiki/guides/quick-start.md b/wiki/guides/quick-start.md
@@ -38,14 +38,11 @@ Replace the contents of your `devbox.json` with:
   "packages": {
     "jdk17": "latest",
     "gradle": "latest"
-  },
-  "env": {
-    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk"
   }
 }
 ```
 
-The `include` line adds the Android plugin from GitHub. Devbox downloads the Android SDK, emulator, and device management tools automatically. The `packages` section adds JDK and Gradle for building your app. Set `ANDROID_APP_APK` to the path where your build outputs the APK.
+The `include` line adds the Android plugin from GitHub. Devbox downloads the Android SDK, emulator, and device management tools automatically. The `packages` section adds JDK and Gradle for building your app.
 
 > **Note:** Plugins are included via URL in `devbox.json`, not with `devbox add`. You cannot use `devbox add plugin:android`.
 
@@ -97,12 +94,9 @@ The plugin provides emulator and device management. Build and deploy commands ar
     "jdk17": "latest",
     "gradle": "latest"
   },
-  "env": {
-    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk"
-  },
   "shell": {
     "scripts": {
-      "build": [
+      "build:android": [
         "gradle assembleDebug --info"
       ],
       "start:app": [
@@ -119,7 +113,7 @@ Now you can build and deploy:
 
 ```sh
 # Build the APK
-devbox run build
+devbox run build:android
 
 # Build, install, and launch on the default device
 devbox run start:app
@@ -128,7 +122,19 @@ devbox run start:app
 devbox run start:app min
 ```
 
-The `android.sh run` command waits for the emulator to boot, installs the APK, and launches the app. The app's package name is auto-detected from the APK.
+The `android.sh run` command waits for the emulator to boot, then auto-detects, installs, and launches the APK. The app's package name is extracted from the APK automatically.
+
+**How APK auto-detection works:** The `run` command searches your project for `.apk` files, skipping build caches like `.gradle/`, `build/intermediates/`, `node_modules/`, and `.devbox/`. If your build outputs the APK to a standard location (e.g., `app/build/outputs/apk/`), it will be found automatically.
+
+If auto-detection picks the wrong APK or you want to be explicit, set `ANDROID_APP_APK` in your `devbox.json` env. This accepts a path or glob pattern relative to your project root:
+
+```json
+{
+  "env": {
+    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk"
+  }
+}
+```
 
 ### 6. Stop the Emulator
 
@@ -165,7 +171,7 @@ Replace the contents of your `devbox.json` with:
 }
 ```
 
-The `include` line adds the iOS plugin from GitHub. The plugin discovers your Xcode installation and provides simulator management tools. The Xcode project, build scheme, bundle ID, and app path are all auto-detected at runtime.
+The `include` line adds the iOS plugin from GitHub. The plugin discovers your Xcode installation, manages simulators, and auto-detects your Xcode project, `.app` bundle, and bundle ID when deploying.
 
 > **Note:** Plugins are included via URL in `devbox.json`, not with `devbox add`.
 
@@ -226,8 +232,6 @@ The plugin provides simulator and device management. Build and deploy commands a
 
 As with the Android example, `${1:-}` passes an optional device nickname through (e.g., `devbox run start:app min`). If omitted, the default device is used.
 
-The `ios.sh run` command starts the simulator, builds (via `build:ios`), auto-detects the .app bundle (via xcodebuild settings or recursive search), extracts the bundle ID from `Info.plist`, installs, and launches.
-
 Now you can build and deploy:
 
 ```sh
@@ -238,6 +242,23 @@ devbox run build:ios
 devbox run start:app
 ```
 
+**How app auto-detection works:** The `ios.sh run` command starts the simulator, runs your `build:ios` script, then auto-detects the `.app` bundle. It uses this precedence chain:
+
+1. Query `xcodebuild -showBuildSettings` for the built products path (works when your project has an `.xcodeproj` or `.xcworkspace` in the project root)
+2. Recursive search of the project directory for `.app` bundles, skipping `Pods/`, `.build/`, `node_modules/`, `.devbox/`, and similar directories
+
+The bundle ID is extracted automatically from the `.app`'s `Info.plist`.
+
+If auto-detection picks the wrong `.app` or your project structure is non-standard, set `IOS_APP_ARTIFACT` in your `devbox.json` env. This accepts a path or glob pattern relative to your project root:
+
+```json
+{
+  "env": {
+    "IOS_APP_ARTIFACT": "DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app"
+  }
+}
+```
+
 Use `-derivedDataPath DerivedData` in your xcodebuild command to keep build output project-local.
 
 ### 6. Stop the Simulator
@@ -277,14 +298,11 @@ Replace the contents of your `devbox.json` with:
     "watchman@latest",
     "jdk17@latest",
     "gradle@latest"
-  ],
-  "env": {
-    "ANDROID_APP_APK": "android/app/build/outputs/apk/debug/app-debug.apk"
-  }
+  ]
 }
 ```
 
-The React Native plugin automatically includes both the Android and iOS plugins. The iOS app project, scheme, bundle ID, and artifact path are all auto-detected at runtime.
+The React Native plugin automatically includes both the Android and iOS plugins. APK and `.app` paths are auto-detected at runtime.
 
 > **Note:** Plugins are included via URL in `devbox.json`, not with `devbox add`.
 
@@ -309,9 +327,6 @@ The plugin provides emulator/simulator control, device management, and Metro bun
     "jdk17@latest",
     "gradle@latest"
   ],
-  "env": {
-    "ANDROID_APP_APK": "android/app/build/outputs/apk/debug/app-debug.apk"
-  },
   "shell": {
     "scripts": {
       "build:android": [
