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)

```bash
# 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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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. |