# Updating the Bible App

The app updates itself from **a source you control** — the church's own Gitea server, a network
share, a folder on this PC, or any small web server. No GitHub, no app store, nothing leaves the
building.

---

## One-time setup (per installed machine)

1. Open the app → **menu (☰) → Settings → Updates**
2. Put the update source in **Update folder or address**. The church's is:

   ```
   http://chronicles-ab.waterschurch.org:3000/api/packages/christian/generic/bible-app/latest
   ```

   Anything else the app accepts also works: `\\WATERS-SERVER\builds\bible-app` (network share),
   `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.

> **Checking is automatic; installing is not.** With that box ticked the app asks the server at
> startup and remembers the answer, which Settings → Updates then shows. It never installs on its
> own — installing closes and reopens the app, so it stays a deliberate tap.

---

## 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 downloads (~750 MB, a couple of minutes over the 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.

---

## Publishing a new version (on the laptop)

```bash
npm run release -- "Faster laser, new popup cards"
git commit -am "Release <version>" && git push
```

That bumps the patch version, builds the Windows installer, uploads it and a `latest.json` manifest
to the update source, and clears out builds older than the previous one. The Windows installer builds
on the Mac — see BUILD-AND-DEPLOY.md.

To publish an existing build, or to publish somewhere other than the default:

```bash
npm run publish-update                                        # newest build -> default target
npm run publish-update -- "\\WATERS-SERVER\builds\bible-app" "Notes"
```

Publish destination is chosen in this order:

1. the path or URL you pass on the command line
2. the `BIBLEAPP_UPDATE_DIR` environment variable
3. `bibleApp.updateTarget` in `package.json` (the church's Gitea registry)
4. the source configured in the app on this machine
5. `dist-installer/publish` (fallback)

Uploading to Gitea needs a token — `GITEA_TOKEN`, or the macOS keychain item `gitea-mcp` that the
git tooling already uses. Downloading does not: the published installer is readable without a
login, which is what lets the TV fetch it. The source repository stays private.

---

## 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.35",
  "file": "Bible App Setup 1.4.35.exe",
  "size": 784268993,
  "sha256": "7a628d27…",
  "notes": "What changed in this version",
  "date": "2026-09-24"
}
```

Both the `.exe` and `latest.json` must sit in the same place. Version numbers are compared
numerically, so `1.4.10` correctly beats `1.4.9` — and the app only ever offers a HIGHER version,
so re-publishing the same version number is invisible to it.

---

## Setting up a brand-new machine — one file

Use **`Bible App Full Setup <version>.exe`** (about 2.7 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` (~750 MB) is what the in-app updater
> downloads. 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:

```powershell
Get-FileHash "Bible App Full Setup 1.4.35.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 source and nobody hand-carries files again. The Gitea URL
above works from anywhere on the church network; a network share or a web address works too.

## If something goes wrong

| Symptom | Fix |
|---|---|
| "Could not read update info" | The address is wrong, or `latest.json` isn't there. Check Settings → Updates, and that the machine can reach the Gitea server. |
| "Installer not found" | `latest.json`'s `file` name doesn't match the actual .exe. Re-run `npm run publish-update`. |
| 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 transfer didn't finish. Publish again and retry. |
| "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 is 0 KB, corrupt, or the wrong architecture — check its size and verify the hash. |
| Need to roll back | `git checkout v<older>` and `npm run release -- --no-bump "Rolling back"`, or run the previous installer (still in the update source) by hand — it installs over the top. |