bible-app/UPDATES.md

Updating the Bible App

The app updates itself from a folder you control — a network share, a folder on this PC, a USB drive, or a small web server. No GitHub, no app store, no internet required (a network share is enough).

---

One-time setup (per installed machine)

1. Open the app → menu (☰) → Settings → Updates
2. Put your update location in Update folder or address, for example:
   • \\WATERS-SERVER\builds\bible-app (network share — recommended)
   • D:\BibleAppBuilds (folder on this PC)
   • http://server.local/bible-app (web server)
3. Leave “Check for updates automatically when the app starts” ticked.
4. Click Save.

That's it. From now on the stage PC never needs a hand-carried .exe.

---

Publishing a new version (on the dev machine)

# 1. bump the version in package.json  (e.g. 1.4.0 -> 1.4.1)
# 2. build + publish in one step:
npm run release

That produces the regular ~300 MB installer and publishes it — this is what existing machines download. To also make the one-file installer for a new machine (app + AI model in a single 2.2 GB .exe), run this afterwards:

node tools/build-full-installer.cjs

It lands in dist-installer/Bible App Full Setup <version>.exe. You only need it when setting up a PC that has never had the app.

npm run release builds the installer and copies it, plus a latest.json manifest, into the update folder. To publish somewhere specific, or to add release notes the operator will see:

npm run publish-update -- "\\WATERS-SERVER\builds\bible-app" "Faster laser, new popup cards"

Publish destination is chosen in this order:

1. the path you pass on the command line
2. the BIBLEAPP_UPDATE_DIR environment variable
3. the folder configured in the app on this machine
4. dist-installer/publish (fallback)

The script keeps the 3 most recent installers in that folder and deletes older ones.

---

Installing an update (on the stage PC)

1. Settings → Updates → Check for Updates
2. If a new version exists it shows the version number and notes → Download & Install
3. A progress bar runs while the installer copies (~1.4 GB, fast over a LAN)
4. The app closes, the installer runs, and the app reopens

Everything is kept: notes, graphics, announcements, maps, annotations, service profiles, OSC settings, phone-remote PIN, and all popup/tool preferences. Those live in your user-content folder, which the installer never touches.

Do this before a service, not during one — the app restarts as part of installing.

---

What latest.json looks like

The publish script writes it for you; you only need this if you're placing a build by hand:

{
  "version": "1.4.1",
  "file": "Bible App Setup 1.4.1.exe",
  "notes": "What changed in this version",
  "date": "2026-08-12"
}

Both the .exe and latest.json must sit in the same folder. Version numbers are compared numerically, so 1.4.10 correctly beats 1.4.9.

---

Setting up a brand-new machine — one file

Use Bible App Full Setup <version>.exe (about 2.2 GB). It is a single self-extracting file containing the app and the offline AI model. Copy it to the new PC any way you like (USB stick, network, cloud) and double-click it.

1. Windows asks for permission (it is an installer) → Yes
2. It asks "Install Bible App with the offline AI model?" → Yes
3. It installs the app and places the AI model. Nothing else to copy, no second file, no internet.

The AI model is written to C:\ProgramData\Bible App\llama-cache\model.gguf. That folder belongs to the machine, not to one user account, and no installer or update ever touches it — so the AI survives every future update. Settings → Updates will show "AI model installed for all users on this PC".

Why two different installers? A Windows installer cannot exceed 2 GB, and the app plus the model is over that. The regular Bible App Setup <version>.exe (~300 MB) is what the in-app updater downloads, which keeps ordinary updates fast. The Full one exists for new machines.

Always check the file after copying it. An interrupted copy or a cloud placeholder leaves a 0 KB file, and Windows then says "This app can't run on your PC" — which looks like an app problem but isn't:

Get-FileHash "Bible App Full Setup 1.4.1.exe" -Algorithm SHA256

Compare that to the .sha256 file next to the installer. If they match, install it. If not (or the file is 0 KB), copy it again.

After that first install, updates verify themselves — the app checks size and checksum before it runs anything, and refuses a damaged download instead of installing it.

Keeping several machines in step

Point every machine at the same update location so nobody hand-carries files again:

• Same building: a network share, e.g. \\WATERS-SERVER\builds\bible-app
• Different site: any web address the app can reach (http://...), or a synced cloud folder that lands on that PC's disk

If something goes wrong

Symptom	Fix
“Could not read update info”	The folder path is wrong, or latest.json isn't in it. Check Settings → Updates.
“Installer not found”	latest.json's file name doesn't match the actual .exe in the folder.
Network share not reachable	Confirm the stage PC can open that share in File Explorer.
Update seems stuck	The installer is large; watch the progress bar. It resumes fine if you retry.
“came across empty (0 bytes)” / “is incomplete”	The copy into the update folder didn't finish. Re-copy the installer there and try again.
“was damaged in transfer (checksum mismatch)”	The file arrived corrupted. Publish or copy it again.
Windows: “This app can't run on your PC”	The .exe you're double-clicking is 0 KB or corrupt — check its size, verify the hash, and re-copy.
Need to roll back	Run an older installer from the update folder by hand — it installs over the top.