Explain how the version and build number decide when code updates

resources/views/docs/mobile/4/getting-started/configuration.md

@@ -34,21 +34,20 @@ So it's not something you want to be changing very often.
 
 ## `NATIVEPHP_APP_VERSION`
 
-The `NATIVEPHP_APP_VERSION` environment variable sets your app's **public version string** - what shows up in App Store
-and Play Store listings, and on-device under "Settings → Apps" (or equivalent). It maps to `CFBundleShortVersionString`
-on iOS and `versionName` on Android.
+The `NATIVEPHP_APP_VERSION` environment variable sets your app's **version number** - the public version string that
+shows up in App Store and Play Store listings, and on-device under "Settings → Apps" (or equivalent). It maps to
+`CFBundleShortVersionString` on iOS and `versionName` on Android.
 
-Its companion, `NATIVEPHP_APP_VERSION_CODE`, sets the **internal build number** the stores use to distinguish uploads
+Its companion, `NATIVEPHP_APP_VERSION_CODE`, sets the **build number** the stores use to distinguish uploads
 (`CFBundleVersion` on iOS, `versionCode` on Android). Users don't normally see this one, but the stores require it to
 increase with every upload.
 
 `NATIVEPHP_APP_VERSION` defaults to `DEBUG`, which is what you want during development - every boot picks up your
 latest code without needing to bump a version number by hand.
 
 You only need to change this when you're cutting a release build for distribution. Rather than editing your `.env`
-manually, use the
-[`native:release` command](commands#nativerelease), which bumps the version (and build
-number) for you.
+manually, use the [`native:release` command](commands#nativerelease) to bump the version number.
+[`native:package`](commands#nativepackage) increments the build number each time it packages your app.
 
 <aside>
 
@@ -57,15 +56,20 @@ number) for you.
 When your app is compiling, NativePHP copies the relevant Laravel files into a temporary directory, zips them up, and
 embeds the archive into the native application.
 
-On boot, the app compares the embedded `NATIVEPHP_APP_VERSION` and `NATIVEPHP_APP_VERSION_CODE` against the values from
-the previously installed version. If they match, it skips extracting the archive and reuses the already-unpacked files.
+On boot, the app compares the embedded version number and build number with the pair it extracted last time. If either
+one is different, it extracts the archive. If both match, it skips extraction and reuses the already-unpacked files.
 
 This means the first boot after an install or update unpacks the bundled Laravel app, and every subsequent boot is
 significantly faster. It's also why `DEBUG` makes development boots a bit slower - the archive is always extracted so
 you see your latest changes.
 
 </aside>
 
+Because of this, two builds with the same version number and build number count as the same build. If you set a version
+and then rebuild and install over an existing copy of your app without changing either number, the app keeps running
+the code it extracted before. Bump `NATIVEPHP_APP_VERSION_CODE` before each build you install. `native:run` doesn't
+change it for you.
+
 ## Persistent Runtime
 
 NativePHP uses a persistent PHP runtime that boots Laravel once and reuses the kernel across all subsequent requests.

resources/views/docs/mobile/4/getting-started/development.md

@@ -107,6 +107,10 @@ Your app will boot a little slower, but you will find that everything looks as y
 
 It's better than scratching your head for an hour trying to figure out why your changes aren't showing!
 
+If you do set a version, the app only refreshes when the version number or the build number changes, so bump
+`NATIVEPHP_APP_VERSION_CODE` before each build. See
+[how NativePHP uses these values](configuration#codenativephp-app-versioncode).
+
 </aside>
 
 ## Working with Xcode or Android Studio

resources/views/docs/mobile/4/publishing/introduction.md

@@ -66,7 +66,7 @@ php artisan native:release patch
 ```
 
 You can pass `patch`, `minor`, or `major` depending on the type of release you're cutting. This updates
-`NATIVEPHP_APP_VERSION` in your `.env` and increments the build number for you.
+`NATIVEPHP_APP_VERSION` in your `.env`.
 
 ### Versioning
 
@@ -83,7 +83,13 @@ The app version is managed via the `NATIVEPHP_APP_VERSION` key in your `.env`.
 Both the Google Play Store and Apple App Store require your app's build number to increase for each release you submit.
 
 The build number is managed via the `NATIVEPHP_APP_VERSION_CODE` key in your `.env`. You don't need to manage this
-yourself — running `native:release` automatically increments the build number and persists it back to your `.env`.
+yourself for store builds: `native:package` increments the build number and persists it back to your `.env`.
+
+The build number also decides whether a device picks up your new code. Together with the version number, it identifies
+a build, and the app only unpacks its bundled Laravel code when that pair changes. A release build installed over a
+previous one with the same version and build number keeps running the previous code. `native:run --build=release`
+doesn't increment the build number, so bump `NATIVEPHP_APP_VERSION_CODE` yourself before testing a new release build
+on a device that already has one installed.
 
 ### Run a `release` build
 

resources/views/docs/mobile/4/publishing/ios.md

@@ -196,8 +196,8 @@ php artisan native:package ios \
 php artisan native:release patch
 ```
 
-Build numbers (`NATIVEPHP_APP_VERSION_CODE`) are incremented automatically based on your `.env`, so you don't have to
-manage them by hand.
+Build numbers (`NATIVEPHP_APP_VERSION_CODE`) are incremented automatically by `native:package`, so you don't have to
+manage them by hand for App Store builds.
 
 ## Artifact Locations