Merge pull request 'docs: make the installer the documented way to deploy the overlay' (#11) from docs/installer-first-setup into main

Reviewed-on: #11
Reviewed-by: Colby Whitlock <whitlocktech@gmail.com>

CONTRIBUTING.md

@@ -33,6 +33,13 @@ under `overlay/` (or `patches/` for changes to stock ServUO files) and deploy:
 .\deploy.ps1 -ServerPath C:\path\to\servuo
 ```
 
+`deploy.ps1` deploys from *this working tree*, which is what you want while
+developing. It is not how a shard is set up: operators run the
+[Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer),
+which syncs the released overlay tarball and installs the sidecar alongside it.
+Changes here reach shards through a [release](README.md#releases), so a change
+that only works when `deploy.ps1` copies it is a change that does not ship.
+
 - `overlay/` — copied over an install (the only thing `deploy.ps1` deploys).
 - `patches/` — unified diffs against stock ServUO for files we must modify.
 - `tools/` — never deployed: test scaffolding and stub sidecars.

README.md

@@ -26,7 +26,7 @@ integration guide, protocol spec, research — with full history preserved).
 | `overlay/` | Mirrors the ServUO server root. Everything here — and **only** this — copies over an install. |
 | `patches/` | Unified diffs against stock ServUO for files we must modify rather than add. |
 | `tools/` | Never deployed. Test scaffolding (C# probes + PowerShell stub sidecars) and anything else that must not reach a server. |
-| `deploy.ps1` | Copies `overlay/` into a server root. `-Verify` diffs instead of writing. |
+| `deploy.ps1` | **Developer tool** — copies `overlay/` from this working tree into a server root. `-Verify` diffs instead of writing. Operators use the [installer](https://gitea.whitlocktech.com/RunicGateway/installer); see [Deploy](#deploy). |
 | `overlay.toml` | Release metadata: the wire-protocol version this overlay speaks, and its ServUO compatibility. Read by CI into the release manifest — see [Releases](#releases). |
 | `.gitea/workflows/release.yml` | Publishes `runicgateway-overlay-<ver>.tar.gz` on every merge to `main`. |
 | [INTEGRATION.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md) | **Website integration guide** — the WebSocket feed, REST endpoints, auth, event catalog, and examples. |
@@ -39,14 +39,17 @@ Anything under `overlay/` is authoritative. Do not edit files in the server tree
 ## Sidecar & deployment
 
 The Rust sidecar is the other half of the bridge and lives in **[RunicGateway/link](https://gitea.whitlocktech.com/RunicGateway/link)**.
-The two are deployed **together** but built **independently**:
+The two are deployed **together** — by the
+[installer](https://gitea.whitlocktech.com/RunicGateway/installer), in one run — but built
+**independently**:
 
-- **This plugin** is deployed as *source* — `deploy.ps1` copies `overlay/` into the ServUO server
-  root, and ServUO compiles it at boot (`Scripts.csproj`; see [Phase 0](#phase-0--what-it-fixes)).
-  There is **no CI build** — it cannot be compiled standalone without the ServUO reference
-  assemblies. CI does publish a *source* tarball for the installer to fetch; see
+- **This plugin** is deployed as *source*: `overlay/` is copied into the ServUO server root and
+  ServUO compiles it at boot (`Scripts.csproj`; see [Phase 0](#phase-0--what-it-fixes)). There is
+  **no CI build** — it cannot be compiled standalone without the ServUO reference assemblies. CI
+  publishes a *source* tarball, which is what the installer fetches and syncs; see
   [Releases](#releases).
-- **The sidecar** is a standalone Rust binary, released from its own repo.
+- **The sidecar** is a standalone Rust binary, released from its own repo and installed from that
+  release.
 
 The **only** coupling is the loopback JSON protocol (the shard dials out to the sidecar on
 `127.0.0.1`). Compatibility is a **protocol** concern, not a build-order one: keep the event/command
@@ -57,14 +60,32 @@ without the sidecar running.
 
 ## Deploy
 
+**On a shard, use the [Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer).**
+One binary syncs this overlay from the release tarball below, offers the patch tier, installs the
+uo-link sidecar as a service, and prints the values your website needs — cross-platform, with a
+`doctor` afterwards to tell a copied file from a working bridge:
+
+```bash
+sudo ./runicgateway-installer-linux-x86_64 install
+```
+
+Guide: [installer/INSTALL.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md).
+To place the overlay yourself instead — a host that cannot run the binary, or you want to see every
+file land — [Appendix A2](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md#a2-deploy-the-plugin-overlay)
+is the same copy done by hand, and stays supported.
+
+### `deploy.ps1` — the developer path
+
+`deploy.ps1` deploys from a **working tree**, which is what you want while writing plugin code and
+is the one thing the installer cannot do (it deploys from a release):
+
 ```powershell
 .\deploy.ps1 -ServerPath <servuo> -Verify   # show what would change
 .\deploy.ps1 -ServerPath <servuo>           # write
 ```
 
-`deploy.ps1` is the **developer-facing** tool and stays that way. Operators get the
-[Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer), which does the
-same sync cross-platform from the release tarball below.
+It is Windows-only and stays developer-facing; it never installs the sidecar, registers a service,
+or checks the protocol pairing. Nothing shipped to an operator depends on it.
 
 ## Releases