Release Healer Man 0.1.3

RELEASE_RUNBOOK.md

@@ -3,7 +3,42 @@
 Use this checklist whenever game changes need to be pushed to Gitea, deployed
 to the TrueNAS server, and released as an Obtainium-compatible APK.
 
-The examples below use Android version `0.1.1` and `versionCode` `2`. Replace
+## Visual release manager
+
+On the development PC, double-click `scripts\release-manager.cmd` or run:
+
+```powershell
+npm run release:gui
+```
+
+The release manager suggests the next semantic patch version and a strictly
+increasing Android `versionCode`, runs the complete validation suite, and
+stages the release. It then shows the exact staged paths and diff summary for
+approval before it commits, pushes `main`, builds the signed APK, and publishes
+the Gitea release. Signing passwords and the Gitea token are passed to the
+child process in memory rather than on its command line.
+
+The local release key is `F:\secure\healer-man-release.jks`. When the companion
+`healer-man-release-password.dpapi` file is present, blank signing-password
+fields are filled from that Windows user-encrypted credential in memory. The
+encrypted credential is usable only by the Windows account that created it;
+back up the keystore and preserve its password separately for disaster recovery.
+The **Remember Gitea token on this PC** option stores the token the same way at
+`F:\secure\healer-man-gitea-token.dpapi`, loads it on later launches, and keeps
+it outside the repository. Use **Forget saved token** to remove it.
+
+After the push, the GUI's **Deploy** tab contains the backup and fast-forward
+pull block for the TrueNAS shell, pinned to the new commit. Stop the app in the
+TrueNAS Apps UI before running it. Start the app afterward, watch its startup
+log, and use the **Verify** tab for the health checks.
+
+The canonical Android version is stored in `release-version.json`. The initial
+`1002` code is intentionally above the historical codes in this runbook; the
+GUI will suggest `1003` for version `0.1.3`. If APK publication fails after the
+Git push, fix the release-side problem and use **Publish Current APK Only** so
+the source version is not bumped a second time.
+
+The examples below use Android version `0.1.3` and `versionCode` `1003`. Replace
 both with the next values for the release you are making. Every APK must use a
 larger `versionCode` than every APK previously released.
 
@@ -150,8 +185,8 @@ other secrets.
 Choose both values before building:
 
 ```powershell
-$VersionName = '0.1.1'
-$VersionCode = 2
+$VersionName = '0.1.3'
+$VersionCode = 1003
 ```
 
 - `VersionName` is the player-facing semantic version.
@@ -159,10 +194,20 @@ $VersionCode = 2
 - Record the last used `versionCode` in the Gitea release notes or your release
   records so it is never accidentally reused.
 
-Update `package.json` and `package-lock.json` to the same version:
+Update `package.json`, `package-lock.json`, and the canonical Android release
+metadata to the same version:
 
 ```powershell
 npm version $VersionName --no-git-tag-version
+$ReleaseVersion = [ordered]@{
+  versionName = $VersionName
+  versionCode = $VersionCode
+} | ConvertTo-Json
+[IO.File]::WriteAllText(
+  (Join-Path $PWD 'release-version.json'),
+  "$ReleaseVersion`n",
+  [Text.UTF8Encoding]::new($false)
+)
 ```
 
 Do not create a local Git tag with `npm version`; the release script creates the
@@ -544,6 +589,11 @@ An already-installed Android APK cannot be rolled back in place to a lower
 
 ## Common failures
 
+- **Android Vite build reports `JavaScript heap out of memory`:** the checked-in
+  `build:android:web` command gives Vite an 8 GB Node heap. Make sure the current
+  `package.json` contains that command and close other memory-heavy applications
+  before retrying. A failed GUI preparation restores the version files when no
+  release commit was created, so retry the same suggested version.
 - **TrueNAS says the bare repository is not a Git repository:** run the pull
   with `sudo`. The normal `truenas_admin` account cannot read Gitea's repository
   storage.