Mobile v3 docs: simplify versioning guidance around NATIVEPHP_APP_VERSION

- Remove NATIVEPHP_APP_VERSION/_CODE from the pre-install .env block; they default to DEBUG and aren't required up front.
- Reframe the configuration page section: lead with what these vars actually are (public version string vs. internal build number, with iOS/Android mappings), note DEBUG is the default, and point at `native:release`. Move the bundled-Laravel extraction mechanics into an aside.
- Update the deployment Releasing section to drive readers to `native:release` instead of editing .env by hand, recommend semver for version numbers, and clarify that the build number is auto-incremented and persisted by the command.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: simonhamp

package-lock.json

@@ -34,27 +34,37 @@ So it's not something you want to be changing very often.
 
 ## `NATIVEPHP_APP_VERSION`
 
-The `NATIVEPHP_APP_VERSION` environment variable controls your app's versioning behavior.
+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.
 
-When your app is compiling, NativePHP first copies the relevant Laravel files into a temporary directory, zips them up,
-and embeds the archive into the native application.
+Its companion, `NATIVEPHP_APP_VERSION_CODE`, sets the **internal 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.
 
-When your app boots, it checks the embedded version against the previously installed version to see if it needs to
-extract the bundled Laravel application.
+`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.
 
-If the versions match, the app uses the existing files without re-extracting the archive.
+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](/docs/mobile/3/getting-started/commands#nativerelease), which bumps the version (and build
+number) for you.
 
-To force your application to always install the latest version of your code - especially useful during development -
-set this to `DEBUG`:
+<aside>
 
-```dotenv
-NATIVEPHP_APP_VERSION=DEBUG
-```
+#### How NativePHP uses these values internally
 
-Note that this will make your application's boot up slightly slower as it must unpack the zip every time it loads.
+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.
 
-But this ensures that you can iterate quickly during development, while providing a faster, more stable experience for
-end users once an app is published.
+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.
+
+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>
 
 ## Persistent Runtime
 

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

@@ -58,29 +58,32 @@ If you want more hands-on support, we happily work with our [Partners](/partners
 
 ## Releasing
 
-To prepare your app for release, you should set the version number to a new version number that you have not used
-before and increment the build number:
+To prepare your app for release, bump the version number using the
+[`native:release` command](/docs/mobile/3/getting-started/commands#nativerelease):
 
-```dotenv
-NATIVEPHP_APP_VERSION=1.2.3
-NATIVEPHP_APP_VERSION_CODE=48
+```shell
+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.
+
 ### Versioning
 
-You have complete freedom in how you version your applications. You may use semantic versioning, codenames,
-date-based versions, or any scheme that works for your project, team or business.
+App version numbers should follow [semantic versioning](https://semver.org) (e.g. `1.2.3`). The `native:release` command
+relies on this format to determine how to bump your version.
 
 Remember that your app versions are usually public-facing (e.g. in store listings and on-device settings and update
 screens) and can be useful for customers to reference if they need to contact you for help and support.
 
-The build number is managed via the `NATIVEPHP_APP_VERSION` key in your `.env`.
+The app version is managed via the `NATIVEPHP_APP_VERSION` key in your `.env`.
 
 ### Build numbers
 
 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`.
+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`.
 
 ### Run a `release` build
 

resources/views/docs/mobile/3/getting-started/deployment.md

@@ -35,11 +35,9 @@ NativePHP does not work in WSL (Windows Subsystem for Linux). You must install a
 
 ```dotenv
 NATIVEPHP_APP_ID=com.yourcompany.yourapp
-NATIVEPHP_APP_VERSION="DEBUG"
-NATIVEPHP_APP_VERSION_CODE="1"
 ```
 
-Find out more about these options in
+Find out more about this option in
 [Configuration](/docs/getting-started/configuration#codenativephp-app-idcode).
 
 <aside>