installer/INSTALL.md

@@ -83,10 +83,16 @@ Download the installer for your OS, plus `SHA256SUMS`, from the
 
 ```
 runicgateway-installer-linux-x86_64
+runicgateway-installer-linux-aarch64
 runicgateway-installer-windows-x86_64.exe
 SHA256SUMS
 ```
 
+`linux-aarch64` is for arm64 hosts — Ampere/Graviton instances, Pi-class boxes. `uname -m` says
+`aarch64` on those and `x86_64` otherwise. There is no macOS build and no Windows-on-arm build: the
+shard dials the sidecar out on loopback, so the two have to share a host, and no ServUO host is
+either of those.
+
 **Linux**
 
 ```bash
@@ -218,7 +224,8 @@ reports "unchanged" and writes nothing.
 | `--host <name>` | `install` | The hostname to print in the website URLs. |
 | `--site-url <url>` | `install` | Your site's base URL, for the Admin → Shard link. |
 | `--yes` | all | Assume the default answer to every prompt. Combine with the flags above for an unattended run. **On `uninstall` it means yes** — that prompt defaults to no, and typing `uninstall --yes` is not an accident. |
-| `--purge` | `uninstall` | Also delete `sidecar.toml`, `uo-link.db` and the cached patch set, all of which are otherwise kept. |
+| `--no-backup` | `install`, `update` | Do not copy the files this run is about to overwrite. They are otherwise saved under the state directory — see [§7](#7-day-two). |
+| `--purge` | `uninstall` | Also delete `sidecar.toml`, `uo-link.db`, the cached patch set and every backup, all of which are otherwise kept. |
 
 Exit codes are `0` success, `1` the run failed, `2` the arguments were unusable. Two commands also
 use `1` for a run that *completed* and found something wrong, so they can be read from a script:
@@ -238,6 +245,7 @@ else still was).
 | `/etc/runicgateway/install.json` | What the installer deployed: versions, commit, per-file hashes, applied patches, timestamps |
 | `/etc/runicgateway/patches/` | Copies of the patches the tier evaluated, so `uninstall` can print the exact hunks long after the release tarball is gone, and a refused one is still on hand to apply yourself |
 | `/etc/runicgateway/patches/originals/` | Each file the patch tier edited, exactly as it was beforehand — a revert you can verify rather than reconstruct |
+| `/etc/runicgateway/backups/<timestamp>/` | Copies of the files a run replaced, with a `manifest.json` naming each. Newest three kept; skip with `--no-backup` |
 | `/var/lib/runicgateway/uo-link.db` | The sidecar's SQLite store (event history, cached profiles, link map) |
 | `/etc/systemd/system/runicgateway-link.service` | The service unit, running as a dedicated user |
 
@@ -250,6 +258,7 @@ else still was).
 | `%ProgramData%\RunicGateway\install.json` | As above |
 | `%ProgramData%\RunicGateway\patches\` | As above |
 | `%ProgramData%\RunicGateway\patches\originals\` | As above |
+| `%ProgramData%\RunicGatewayackups\<timestamp>\` | As above |
 | `%ProgramData%\RunicGateway\uo-link.db` | The sidecar's SQLite store |
 | Service `RunicGatewayLink` | Automatic start, restart on failure, running as `NT SERVICE\RunicGatewayLink` |
 
@@ -520,6 +529,8 @@ first thing a maintainer will want.
 ✓ Protocol                sidecar 3 = overlay manifest 3
 ✗ Shard connected         no — the shard is running (pid 8123) but has not dialed in
 ✓ Bundle                  2026.08.04 — up to date
+✓ Backups                 2026-08-04T09:12:44Z — 3 file(s) replaced by update to bundle 2026.08.04
+    3 kept in /etc/runicgateway/backups
 ```
 
 Rows come from asking the installed sidecar (`--version`, `--print-config`) rather than from reading
@@ -557,6 +568,16 @@ together — never to two independently-latest artifacts that may disagree.
 Your `sidecar.toml`, your `Bridge.cfg` edits and your database are not touched. `Bridge.cfg` is
 overwritten only if you have not changed it; a modified copy is reported, not clobbered.
 
+**Anything it does overwrite is copied first.** Every `.cs` file the overlay owns is replaced
+unconditionally — that is deliberate, they are code — so if you have edited one, the run saves your
+copy under `backups/<timestamp>/` in the state directory before writing, alongside `sidecar.toml`
+and any stock ServUO file the patch tier is about to touch. Each backup carries a `manifest.json`
+saying where every file came from. The newest three are kept; `--no-backup` skips taking one.
+
+Putting a file back is yours to do — the installer will not restore an old file over a newer
+release, because it cannot know what has changed since. A run that overwrites nothing takes no
+backup, so a no-op `update` leaves nothing behind.
+
 It updates the ServUO tree `install.json` names — not a tree it detects — and it needs the shard
 stopped, exactly as `install` does. There is nothing to update on a host that was never installed;
 it says so rather than performing a first install under a verb that promises to preserve.
@@ -581,7 +602,7 @@ your work.
 | | |
 |---|---|
 | **Removed** | The sidecar binary, its service entry, `install.json` |
-| **Kept** | `sidecar.toml`, `uo-link.db`, and the cached patch set with its pre-patch originals (`--purge` drops all of them) |
+| **Kept** | `sidecar.toml`, `uo-link.db`, the cached patch set with its pre-patch originals, and every backup an upgrade took (`--purge` drops all of them) |
 | **Printed, not done** | Every overlay file deployed into your ServUO tree, by path, for you to delete — with any file you have edited since deployment flagged, so you do not delete your own work by mistake |
 | **Printed, not done** | The exact hunks each applied patch added to `EventSink.cs`, `PlayerVendorGumps.cs` and `Logging.cs`, for you to revert — with how each landed, since one placed into a file you had already modified is worth a closer look. The pre-patch copy kept under `patches/originals/` is there to diff against. |
 
@@ -679,6 +700,10 @@ for the *comparison* while writing back your file's own endings, which is why it
 
 ### A3. Install the sidecar
 
+On an arm64 host substitute `uo-link-sidecar-linux-aarch64` for the asset name below (`uname -m`
+says `aarch64`); releases from v1.2.0 carry both. Take the version from the bundle you fetched in
+A1 rather than the one written here.
+
 ```bash
 curl -LO https://gitea.whitlocktech.com/RunicGateway/link/releases/download/v1.1.0/uo-link-sidecar-linux-x86_64
 curl -LO https://gitea.whitlocktech.com/RunicGateway/link/releases/download/v1.1.0/SHA256SUMS