Merge pull request 'docs(installer): add release orchestration and the bundle manifest' (#81 ) from docs/installer-release-orchestration into main

Reviewed-on: #81
docs(installer): add release orchestration and the bundle manifest
2026-08-01 21:42:33 +00:00 · 2026-08-01 06:11:08 -05:00 · 2026-08-01 10:46:13 +00:00 · 2026-08-01 05:44:44 -05:00 · 2026-08-01 07:50:46 +00:00 · 2026-08-01 07:22:23 +00:00
12 changed files with 1065 additions and 45 deletions
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ ci/        cross-cutting CI/quality notes
 | [SHARD_VISIBILITY.md](website/SHARD_VISIBILITY.md) | Who sees which shard data — the admin-configurable audience framework |
 | [SPAWN_ATLAS.md](website/SPAWN_ATLAS.md) | The bestiary / spawn atlas: what the shard contains, parsed from its own ServUO tree |
 | [CLILOCS.md](website/CLILOCS.md) | UO's id → name table: converting one from your client so items have names |
 | [UOFIDDLER.md](website/UOFIDDLER.md) | **Operator runbook** — step-by-step extraction from your own UO client (cliloc table, creature art) |
 | [MARKETPLACE.md](website/MARKETPLACE.md) | The player-vendor index: how it is gathered, what it costs, how to tune it |
 | [website-README.md](website/website-README.md) | Snapshot of the website repo's README (setup/run reference) |
 | [PROJECT_TREE.md](website/PROJECT_TREE.md) | Auto-generated snapshot of the repo's tracked file layout |
--- a/android/PLAN.md
+++ b/android/PLAN.md
@@ -1,6 +1,6 @@
 # Android App — Plan
-Status: **M0–M7 landed; M7 (push notifications) both parts done — Part 1 backend (website#78) and Part 2 app (Android-app#15) plus a small `push.ntfyUrl` settings addition (website#79). Remaining: set the shard's `NTFY_*` deploy config so push lights up, and cut the v1 tag. M9 (native SSO login) is now underway backend-first — the Mobile SSO Authorization Bridge is being built in `website/` + `docs/` ahead of the app-side client (§4.2, §9 M9); custom-scheme callback only for now, App Links deferred (see [`APP_LINKS.md`](./APP_LINKS.md)).** This document is the
+Status: **M0–M7 landed; M7 (push notifications) both parts done — Part 1 backend (website#78) and Part 2 app (Android-app#15) plus a small `push.ntfyUrl` settings addition (website#79). Remaining: set the shard's `NTFY_*` deploy config so push lights up, and cut the v1 tag. M9 (native SSO login) is now underway backend-first — the Mobile SSO Authorization Bridge is being built in `website/` + `docs/` ahead of the app-side client (§4.2, §9 M9); custom-scheme callback only for now, App Links deferred (see [`APP_LINKS.md`](./APP_LINKS.md)). **M11 (Protocol 3.0 shard parity)** is scoped and next: the app sees none of the four shard features v3 added (`ruleset`, `leaderboards`, `market`, `atlas`) and does not consult `GET /public/shard/features`, so it gates shard nav on session role alone while an admin can switch any of those surfaces off or raise its audience — the v3 `edge` → `main` cutover is held until it lands (§9 M11).** This document is the
 design contract for the `RunicGateway/Android-app` repo. It was written before implementation so the
 API changes it depends on could be landed in `website/` and `docs/` first. The authoritative API
 reference is the committed OpenAPI spec at `website/server/swagger/swagger-output.json` (regenerated
@@ -631,6 +631,8 @@ not rank).
 | News & content | everyone | `/public/posts/:category`, `/public/pages/:slug` |
 | Wiki | everyone | `/public/wiki`, `/public/wiki/categories`, `/public/wiki/tags`, `/public/wiki/:slug` |
 | Shard (live) | everyone | `/public/shard/*` + `/public/shard/stream` (SSE) |
 | **Rules / Leaderboards / Market** | everyone, *if the shard publishes them* | `/public/shard/{ruleset,points,market}` (M11) |
 | **Atlas** (bestiary) | everyone, *if the shard publishes it* | `/public/atlas/*` (M11) |
 | Contact | everyone | `/public/contact` |
 | **My Account** | signed-in | `/player/account/*` (or `/admin/account/*` for staff — see §6.4) |
 | **My Characters / Vendors / Houses** | `player` (linked) | `/player/shard/*` |
@@ -639,6 +641,12 @@ not rank).
 Guidelines:
 - The menu is **declarative + data-driven**, not a pile of `if role ==` checks — one list of entries
  with a `minAccess`/`requiredCapability` field, filtered by the session.
 - **Session role is not the only gate on shard surfaces (M11).** Every shard-derived feature is
  *admin-configurable* — it can be switched off or raised to a higher audience rung — so a shard entry
  is filtered by the session role **and** by `GET /public/shard/features`, which reports the features
  the caller may actually reach. While that answer is unknown (in flight, or the lookup failed) the app
  shows everything: the server gates regardless, and a nav that flickers in on every load is worse than
  a link that briefly `403`s.
 - Never hide the fact that more exists behind auth in a way that misleads; anonymous users see public
  groups and a "Sign in" affordance.
 - The server is the source of truth: a hidden/greyed item is a UX convenience; every gated call still
@@ -663,9 +671,15 @@ Guidelines:
 ### 6.2 Public shard (live)
 - Status/online/feed/economy/champs/guilds/governors(+history)/presence/houses/idoc — the
  `/public/shard/*` GETs.
- **Live updates** — subscribe to `GET /public/shard/stream` (SSE, safe kinds only) and patch the
+- **Live updates** — subscribe to `GET /public/shard/stream` (SSE) and patch the in-memory boards in
-  in-memory boards in place (champ/guild/city/house/presence update+remove frames). Reconnect with
+  place (champ/guild/city/house/presence update+remove frames). Reconnect with backoff; fall back to
-  backoff; fall back to poll if SSE drops.
+  poll if SSE drops. What arrives on the stream is **resolved from the caller's audience rung at
  subscribe time**, not from a fixed allowlist (Protocol 3.0 §3.6) — the stream request carries the
  bearer like every other call, so a signed-in app session sees exactly what the same account sees on
  the web.
 - **Visibility + the Protocol 3.0 surfaces (M11)** — `GET /public/shard/features` drives which of these
  the menu offers; `GET /public/shard/{ruleset,points,points/:system,market,market/meta,market/vendors/:serial}`
  and `GET /public/atlas/*` are the new reads. Full contract and traps in §9 M11.
 ### 6.3 Player self-service & game data (bearer)
 - **Account** — `GET /player/account`; `PATCH /player/account/username`;
@@ -675,6 +689,11 @@ Guidelines:
 - **My game data** — `GET /player/shard/roster/:account`, `/char/:serial`, `/vendors/:account`,
  `/sales`, `/houses`. All ownership-checked server-side; a `503` means shard/sidecar down → show an
  "offline, retry" state (see §7).
 - **The character sheet carries two things the app does not yet read (M11):** the `points` block
  (per-character loyalty/points standings, Protocol 3.0 §7.3) and the server-resolved cliloc names on
  `equipment[].clilocName` / `titles.rewardResolved` (§8.6). Both are served **ungated** on this route —
  a character's own standings are self-service data and do not depend on the public `leaderboards`
  feature being visible, which is the behavior the app must mirror rather than re-gate.
 - **Presentation is text-only for v1.** Character sheets and vendor listings render as data/text — no
  item icons or paperdoll art. A richer "pretty paperdoll" view is a **future** enhancement (pending the
  art/asset work on the platform side) and is explicitly out of the first release.
@@ -883,10 +902,98 @@ push, and Play (M6–M8) follow the designed app.
      shard-write actions degrade gracefully when the sidecar is offline. Excluded: hero/CMS block
      editor, Discord-bot config, uo-link config, OAuth-provider setup.
 12. **M11 — Protocol 3.0 shard parity** (post-v1; scoped 2026-07-30). The website's Protocol 3.0 work
    added four shard features and, with them, an **admin-configurable visibility framework** the app
    knows nothing about. `link/v3.md` §10 deferred the app side as a follow-up; it is now scoped
    deliberately, and **the v3 `edge` → `main` cutover is held until both parts land** so web and app
    surface the same shard on the same day (decided 2026-07-30).
    Neither part is coupled to the cutover *merge order*, which is what makes holding it a schedule
    decision rather than a technical one: against a pre-v3 website every new route and
    `/public/shard/features` simply `404`s, and each consumer below falls back to exactly today's
    behavior. The app declares no protocol version and never talks to the sidecar.
    - **Part 1 — the visibility rules + the read-model adds.** The security-shaped half, reviewed on
      its own:
      - `GET /public/shard/features` → `{ level, features[] }`: the features **this caller** may reach.
        A new singleton cache mirrors the web client's (`lib/useShardFeatures.js`): per-viewer but
        stable for a session, invalidated on sign-in/out and on a server switch.
      - `MenuEntry` gains `feature: String?` beside its existing `access`, so the one declarative menu
        (§5) filters on the session role **and** the shard's live feature config. While the lookup is
        in flight or has failed, **show everything** — the same deliberate fail-open the web client
        takes, because the server gates regardless and a nav that flickers in on every load is worse
        than a link that briefly `403`s. The gate is server-side; hiding is presentation.
      - **`404` and `403` mean different things here** and neither is a generic error:
        `requireFeature` `404`s a *disabled* feature (deliberately not disclosing that it exists) and
        `403`s a viewer *below its audience*. Both render "not available on this shard", alongside the
        existing `503` = shard offline (§7).
      - **The `level` from `/features` is authoritative — do not re-derive the rung from the role.**
        The server's ladder is `anonymous → logged_in → player → staff → admin`, where `player` means
        *a linked game account* and staff always satisfy `player` (the same superset rule `Menu.kt`
        already encodes as `isPlayer || isStaff`).
      - **`char.profile.points`** → the "Loyalty & Points" block the web character sheet gained:
        `CharProfileDto.points[{system, nameString, points, maxPoints, rank?}]`. Three traps, all of
        them things a real shard does and a fake one does not (`v3.md` §7.5): `maxPoints == 0` means
        **uncapped** and is the *common* case, so nothing may divide by it; `nameString` is usually
        `null` because most systems name themselves with a cliloc, making the humanise-the-`system`-key
        path the **primary** one rather than a fallback; and `rank` is absent unless the shard runs
        `PointsProfileRank=true` — absent and "unranked" are different answers.
      - **Cliloc-resolved names** (`v3.md` §8.6, already live on the website): `EquipmentDto` gains
        `name` + `clilocName` and `TitlesDto` gains `rewardResolved`, so equipment stops rendering as a
        layer or a bare id. Precedence is `name → clilocName → layer`: a player-given name outranks the
        resolved type name, and the server applies the same order. A shard with no cliloc table
        configured sends neither field and the sheet renders exactly as it does today.
      - `ActorDto` keeps its `acct` / `webId` fields (nullable, so nothing breaks) but its KDoc stops
        describing them as available: they are **locked to the admin rung**, always, and stripped from
        every response below it.
    - **Part 2 — the four new screens**, each hidden by its feature name in the menu:
      - **Rules** — `GET /public/shard/ruleset` (`ruleset`). A `null` body means "the shard has not
        published its ruleset yet", which is a different state from the feature being disabled. Every
        block is optional and omitted when its system is off. **`caps.skill` / `caps.totalSkill` are in
        tenths** (1000 = 100.0) and must be converted — the raw number is actively misleading, not
        merely unhelpful. Live via the `world.ruleset` frame, which is on the public stream by default.
      - **Leaderboards** — `GET /public/shard/points`, `/points/:system` (`leaderboards`). The same
        `maxPoints`/`nameString` traps as the profile block. Live via `points.board`.
      - **Market** — `GET /public/shard/market` (`q`, `minPrice`, `maxPrice`, `itemId`, `map`, `region`,
        `sort`, `limit`, `offset`), `/market/meta` for the filter options + staleness, and
        `/market/vendors/:serial` (`market`). Four things this screen must get right: it is the site's
        first **rate-limited** public endpoint, so handle `429` the way the contact form does; the
        *"prices last refreshed N minutes ago"* banner is **required, not decoration** — the shard
        sweeps vendors round-robin, so a listing can legitimately be a full cycle stale and a page
        implying live prices sends people to an item that sold twenty minutes ago; a `truncated` shop
        must say so; and `location` is a **nested object** that an admin may gate away entirely, which
        the vendor screen renders as "hidden by the shard" (a real answer) rather than as blank
        coordinates — same for `ownerName` / `ownerSerial`. **The `market` SSE fan-out is off by
        default** (a live firehose of vendor inventories would be the site's biggest bandwidth
        consumer), so the screen is a plain paginated read and must never depend on live frames.
      - **Atlas** — `GET /public/atlas/{creatures,creatures/:slug,regions,landmarks,champions,meta}`
        (`atlas`). Note the path: `/public/atlas`, **not** `/public/shard` — the atlas is static shard
        *content*, not live shard *state*, and unlike `/shard/*` it **is** `siteMode`-gated like
        `/posts` and `/wiki`, so a site in maintenance mode withholds it independently of the sidecar.
        Three traps. Two are units/naming, from `v3.md` §6.3: respawn delays are **seconds**
        throughout, and `points` is a *count* on the search route while `spawners` is the *list* on
        the detail route. The third is a **shape**: `places` is a list of
        `{facet, label, spawners, maxAlive}` **objects**, not of place-name strings — it is the
        aggregate the screen exists to show ("Shrines, Isamu-Jima, Yew"), it arrives only on the
        detail route, and typing it `List<String>` makes that whole route fail to decode while the
        request itself returns `200`.
    - **Verification** — the five-rung walk (`anonymous`, `logged_in`, `player`, `staff`, `admin`)
      against a local website on the cutover branch, per
      [`../link/v3.md`](../link/v3.md) §11 and the shard-visibility smoke harness; plus one pass with
      **every feature disabled** in Admin → Shard Visibility, confirming the app *hides* each surface
      instead of erroring on it. Unit tests cover the menu filter (role × feature set), the
      `404`/`403`/`503` mapping, and DTO decode for each new shape. **Decode tests must feed real
      captured JSON**, not DTOs built in Kotlin: the fakes under `data/api/fake/` construct objects
      directly, so they can never catch a wire/type mismatch — which is how the `places` shape above
      shipped past a green suite.
    - **Excluded**, in the same class as M10's exclusions: the admin *configuration* panels — Shard
      Visibility, Spawn Atlas and Cliloc import — alongside the hero/CMS block editor, Discord-bot
      config, uo-link config and OAuth-provider setup.
 ### Deferred (not a milestone)
- **`/api/mobile` facade migration + app-version floor** — briefly planned as M11 (2026-07-22), now
+- **`/api/mobile` facade migration + app-version floor** — briefly planned as its own milestone
-  **deferred with no app work scheduled**. The website's router refactor is being done in place with
+  (2026-07-22), now **deferred with no app work scheduled**. The website's router refactor is being done in place with
  every URL byte-identical and `/api/v1` is not being retired, so the app's ~70 hardcoded `api/v1/…`
  endpoints, its SSE path, and its SSO URLs keep working untouched. If the mobile contract ever needs
  to diverge from web, the migration comes back — starting from a one-line alias mount on the server,
--- a/android/PROJECT_TREE.md
+++ b/android/PROJECT_TREE.md
@@ -85,6 +85,7 @@ android-app/
 │   │   │   │               │   │   │   ├── PlayerShardDto.kt
 │   │   │   │               │   │   │   ├── PostDto.kt
 │   │   │   │               │   │   │   ├── PublicDto.kt
 │   │   │   │               │   │   │   ├── ShardContentDto.kt
 │   │   │   │               │   │   │   ├── ShardDto.kt
 │   │   │   │               │   │   │   ├── SsoDto.kt
 │   │   │   │               │   │   │   └── WikiDto.kt
@@ -106,6 +107,7 @@ android-app/
 │   │   │   │               │       ├── NotificationsRepository.kt
 │   │   │   │               │       ├── PlayerShardRepository.kt
 │   │   │   │               │       ├── SettingsRepository.kt
 │   │   │   │               │       ├── ShardFeaturesRepository.kt
 │   │   │   │               │       ├── ShardRepository.kt
 │   │   │   │               │       └── WikiRepository.kt
 │   │   │   │               ├── di/
@@ -171,6 +173,8 @@ android-app/
 │   │   │   │               │   ├── session/
 │   │   │   │               │   │   └── SessionViewModel.kt
 │   │   │   │               │   ├── shard/
 │   │   │   │               │   │   ├── AtlasScreen.kt
 │   │   │   │               │   │   ├── AtlasViewModel.kt
 │   │   │   │               │   │   ├── ChampsScreen.kt
 │   │   │   │               │   │   ├── ChampsViewModel.kt
 │   │   │   │               │   │   ├── FrameFields.kt
@@ -180,7 +184,13 @@ android-app/
 │   │   │   │               │   │   ├── GuildsViewModel.kt
 │   │   │   │               │   │   ├── HousesScreen.kt
 │   │   │   │               │   │   ├── HousesViewModel.kt
 │   │   │   │               │   │   ├── LeaderboardsScreen.kt
 │   │   │   │               │   │   ├── LeaderboardsViewModel.kt
 │   │   │   │               │   │   ├── LiveBoard.kt
 │   │   │   │               │   │   ├── MarketScreen.kt
 │   │   │   │               │   │   ├── MarketViewModel.kt
 │   │   │   │               │   │   ├── RulesScreen.kt
 │   │   │   │               │   │   ├── RulesViewModel.kt
 │   │   │   │               │   │   ├── ShardComponents.kt
 │   │   │   │               │   │   ├── ShardEventText.kt
 │   │   │   │               │   │   ├── ShardScreen.kt
@@ -284,6 +294,7 @@ android-app/
 │   │                       │   │   │   ├── PlayerShardDtoTest.kt
 │   │                       │   │   │   ├── PublicDtoTest.kt
 │   │                       │   │   │   ├── ShardBoardDtoTest.kt
 │   │                       │   │   │   ├── ShardContentDtoTest.kt
 │   │                       │   │   │   ├── ShardDtoTest.kt
 │   │                       │   │   │   ├── SsoDtoTest.kt
 │   │                       │   │   │   └── WikiDtoTest.kt
@@ -294,7 +305,8 @@ android-app/
 │   │                       │   │       └── FakeShardStream.kt
 │   │                       │   └── repository/
 │   │                       │       ├── AccountTrustedDevicesTest.kt
-│   │                       │       └── ConnectionVersionGuardTest.kt
+│   │                       │       ├── ConnectionVersionGuardTest.kt
 │   │                       │       └── ShardFeaturesRepositoryTest.kt
 │   │                       ├── ui/
 │   │                       │   ├── admin/
 │   │                       │   │   ├── AdminContentViewModelTest.kt
@@ -304,7 +316,8 @@ android-app/
 │   │                       │   ├── contact/
 │   │                       │   │   └── ContactViewModelTest.kt
 │   │                       │   ├── navigation/
-│   │                       │   │   └── MenuAccessTest.kt
+│   │                       │   │   ├── MenuAccessTest.kt
 │   │                       │   │   └── MenuFeatureGatingTest.kt
 │   │                       │   ├── notifications/
 │   │                       │   │   └── NotificationRoutingTest.kt
 │   │                       │   ├── player/
@@ -315,6 +328,8 @@ android-app/
 │   │                       │   │   ├── FrameFieldsTest.kt
 │   │                       │   │   ├── LiveBoardTest.kt
 │   │                       │   │   ├── ShardBoardViewModelTest.kt
 │   │                       │   │   ├── ShardContentHelpersTest.kt
 │   │                       │   │   ├── ShardContentViewModelTest.kt
 │   │                       │   │   └── ShardEventTextTest.kt
 │   │                       │   ├── theme/
 │   │                       │   │   └── BrandColorTest.kt
--- a/installer/PLAN.md
+++ b/installer/PLAN.md
@@ -0,0 +1,446 @@
 # Runic Gateway Installer — plan
 Status: **planning**. No installer code exists yet. This document is the design of record; it
 supersedes the informal overview it grew out of, which described a ServUO integration that does not
 match how `servuo-plugins` actually ships (see [Corrections](#corrections-to-the-original-overview)).
 ---
 ## 1. Purpose
 Take a stock ServUO installation and configure it for Runic Gateway with minimal manual steps, while
 keeping the components separated and independently maintainable.
 The installer handles environment detection, ServUO overlay deployment, the optional stock-file
 patch tier, uo-link installation and service registration, version tracking, diagnostics, and
 updates from Gitea releases.
 **It is a deployment tool, not a hosted bootstrapper.** There is no `curl | bash`, no installer
 service, and no hosted bootstrap script. Artifacts are downloaded from a Gitea release page and run.
 **It does not replace ServUO startup behavior.** ServUO keeps running through its existing
 release/start scripts. The installer never writes a launcher.
 ### Decisions locked
 | Question | Decision |
 |---|---|
 | Audience | **Public** — any ServUO operator, not just shards we run |
 | Code signing | **Unsigned.** `SHA256SUMS` is the trust anchor; SmartScreen/Gatekeeper warnings are expected and documented, as with most self-hosted tooling |
 | Language | **Rust** — single static binary per OS, reuses the cross-compile pattern already proven in `link/.gitea/workflows/release.yml` |
 | Plugin source | **Release tarball artifact** — no git and no Gitea credentials on the shard host |
 | Composition | **Published bundle manifest** (§7.1). CI names an exact, protocol-checked combination of component versions; the installer fetches it at run time and `--bundle <tag>` pins one. Component releases regenerate JSON, not the installer binary |
 | Token handoff | **Print token + prefilled admin URL** at the end of the run |
 | Repo | **New repo**, `RunicGateway/installer`. It deploys *both* other components, so living inside `link/` would invert the dependency |
 | ServUO version | **Warn and skip.** Patches are verified against stock 57.4 only; on anything else the base install proceeds and the patch tier is skipped with a warning. Forks are the norm in a public audience — refusing outright would block most operators |
 | Uninstall | **Never touches the ServUO tree.** Removes uo-link and its service entry, then *prints* the overlay files to delete and the patch hunks to revert. Reverting is the operator's call |
 ---
 ## 2. Corrections to the original overview
 These are not wording nits — each one changes what the installer has to do.
 ### 2.1 There is no `RunicGateway.dll` and no `Plugins/` directory
 The plugin ships as **C# source** and ServUO compiles it at boot. The real deployable is
 `servuo-plugins/overlay/`, which mirrors the server root:
 ```
 overlay/
 ├── Config/Bridge.cfg
 └── Scripts/
    ├── Scripts.csproj                 # Phase 0 — whole-file overwrite of a stock file
    └── Custom/Bridge/*.cs             # 22 files
 ```
 So the plugin step is a hash-compare file sync, not a DLL drop — mechanically easier than the
 overview assumed. The sting is that **a successful copy does not mean a working bridge.** Per
 `link/SHARD_PREREQS.md`, `ScriptCompiler.Compile()` shells out to `dotnet build`, prints the output,
 **ignores the exit code**, and reloads the existing `Scripts.dll`. A broken script build is
 invisible: the shard boots clean on stale code. Diagnostics must therefore verify *post-boot* state,
 never treat "files copied" as success.
 ### 2.2 Stock ServUO files *are* modified — by an optional tier
 `servuo-plugins/patches/` holds unified diffs against stock ServUO 57.4, plus two `.cs` files that
 can only be copied *after* their patch lands (they reference symbols the patch introduces):
 | Patch | Target | Companion file | Rebuild required |
 |---|---|---|---|
 | `playervendor-sale-eventsink.patch` | `Server/EventSink.cs` | `BridgeVendorSale.cs` | **Core** — `dotnet build ServUO.sln`; the dynamic script build is not enough |
 | `playervendor-sale-gump.patch` | `Scripts/Gumps/PlayerVendorGumps.cs` | (same unit as above) | script build |
 | `commandlogging-event.patch` | `Scripts/Commands/Logging.cs` | `BridgeModerationAudit.cs` | script build |
 Plus `overlay/Scripts/Scripts.csproj`, which overwrites a stock file (Phase 0 — it fixes the silent
 ServUO build bug above).
 This is the hardest part of the installer. `git apply` against a hand-modified shard will fail, and
 most real shards are hand-modified. Therefore:
 - The patch tier is **opt-in and skippable**. The base install must complete without it.
 - Always dry-run (`git apply --check`) before applying, and report per-patch.
 - When skipped or failed, say plainly what is lost: **no `vendor.sale` events, no in-game moderation
  audit forwarding**.
 - The `EventSink.cs` patch must warn loudly that a **core solution rebuild** is required, not just a
  shard restart.
 - On any ServUO version other than stock **57.4**, skip the whole tier with a warning and continue
  with the base install. Do not attempt to apply unverified diffs to an unknown tree.
 - Record applied patches in `install.json`, **and cache the applied `.patch` files** next to it
  (`/etc/runicgateway/patches/`, `%ProgramData%\RunicGateway\patches\`). Re-runs stay idempotent,
  and uninstall can print the exact hunks offline long after the release tarball is gone (§5,
  Phase 4).
 ### 2.3 Config paths collide with what the sidecar actually reads
 The sidecar reads `$UOLINK_CONFIG`, else `sidecar.toml` in the **working directory**
 (`link/sidecar/src/config.rs`), with keys `[shard].bind`, `[web].bind`, `[web].auth_token`,
 `[store].path`. The overview proposed a `config.toml` with `[updates]`, `[link]`, `[servuo]` — keys
 the sidecar cannot read.
 Two files, two owners:
 | File | Owner | Contents |
 |---|---|---|
 | `/etc/runicgateway/sidecar.toml` | uo-link | The sidecar's own schema, unchanged. Service sets `UOLINK_CONFIG` to this path |
 | `/etc/runicgateway/install.json` | installer | Deployed versions, file hashes, applied patches, ServUO path, timestamps |
 **Working-directory trap:** the sidecar writes both `sidecar.toml` and `uo-link.db` relative to CWD.
 Under `C:\Program Files\` that fails or silently lands in VirtualStore. The service definitions must
 pin `UOLINK_CONFIG` and `UOLINK_DB_PATH` explicitly:
 - Linux: config `/etc/runicgateway/sidecar.toml`, db `/var/lib/runicgateway/uo-link.db`, dedicated
  service user
 - Windows: binary under `%ProgramFiles%\RunicGateway\`, **data under `%ProgramData%\RunicGateway\`**
 ### 2.4 The token handoff was missing entirely
 The whole point is the website reaching the sidecar, and today that is manual and undocumented in
 the install flow: the sidecar generates a token on first run and logs it, then a human pastes base
 URL, WS URL, token, and protocol version into Admin → Shard, where it is AES-GCM encrypted and
 becomes write-only. This is the largest "I installed it and nothing happened" failure mode.
 The installer closes it by printing a copy-paste block at the end of a successful run — see §6.
 ### 2.5 `deploy.ps1` cannot be the cross-platform deployer
 It is PowerShell-only; a Linux ServUO host running .NET typically has no `pwsh`. It also hard-throws
 when the ServUO process is running — correct behavior, and the installer must inherit it (detect and
 refuse, rather than corrupt a live `Scripts.dll`). The installer reimplements the sync natively; it
 is a short hash-compare-and-copy that never deletes.
 `deploy.ps1` **stays** in `servuo-plugins` as the developer-facing tool. The installer is for
 operators.
 ### 2.6 Prerequisites the overview assumed away
 - **`servuo-plugins` has no release workflow.** Only `link` does. "Pull latest repository" is
  replaced by a release tarball, which has to be built first (Phase 0).
 - **arm64 is not buildable today.** `link/release.yml` cross-compiles only
  `x86_64-unknown-linux-gnu` and `x86_64-pc-windows-gnu`. An arm64 `.deb` needs another cross
  toolchain.
 - **The compat matrix has no home.** `PROTOCOL_VERSION` currently lives only in
  `link/sidecar/src/main.rs`. The sidecar publishes it via `X-UOLink-Version` and `/health`, and the
  website stores an expected value — but the *plugin's* protocol version is not queryable before
  boot. See §7.
 ---
 ## 3. Distribution model
 Components are published as Gitea release artifacts. Operators download from the release page
 (browser, `curl`/`wget`, or `scp` to the server) and run the binary.
 ```
 Runic Gateway Installer v1.0.0
 ├── runicgateway-installer-windows-x86_64.exe
 ├── runicgateway-installer-linux-x86_64
 └── SHA256SUMS
 uo-link v3.x.y                        (existing release, extended)
 ├── uo-link-sidecar-windows-x86_64.exe
 ├── uo-link-sidecar-linux-x86_64
 ├── runicgateway-link_<ver>_amd64.deb        (Phase 5)
 └── SHA256SUMS
 servuo-plugins v<ver>                 (new release, Phase 0)
 ├── runicgateway-overlay-<ver>.tar.gz         # overlay/ + patches/ + manifest.json
 └── SHA256SUMS
 ```
 Binding those together is the **bundle manifest** (§7.1) — published by the installer repo's CI, not
 by any component, and the thing the installer actually resolves against.
 ```bash
 scp runicgateway-installer-linux-x86_64 user@server:/tmp/
 chmod +x runicgateway-installer-linux-x86_64
 sudo ./runicgateway-installer-linux-x86_64
 ```
 ### Unsigned-binary posture
 Because releases are unsigned, trust is anchored on checksums and the operator's own verification.
 The docs must state this up front rather than let users discover it as a scary dialog:
 - Every release publishes `SHA256SUMS`; the install docs lead with the verification command for both
  OSes.
 - Windows will show a SmartScreen "unrecognized app" prompt. Documented, with the exact click path.
 - The installer verifies the SHA256 of everything **it** downloads (overlay tarball, sidecar binary)
  against the release's `SHA256SUMS` and refuses on mismatch. Self-verification is not optional just
  because the installer itself is unsigned.
 - Revisit signing if it ever becomes affordable; the release layout should not have to change.
 ---
 ## 4. Component architecture
 ```
                 Runic Gateway Installer  (Rust, one binary per OS)
                                │
                ┌───────────────┴────────────────┐
                ▼                                ▼
      ServUO integration                      uo-link
                │                                │
       ┌────────┴────────┐              ┌────────┴────────┐
       ▼                 ▼              ▼                 ▼
  overlay sync    patch tier (opt-in)  binary install   service registration
  (never deletes) (git apply + guard)  + config + data  (systemd / Windows SCM)
 ```
 Each component keeps its own lifecycle. ServUO's existing startup process is untouched.
 ---
 ## 5. Phases
 ### Phase 0 — prerequisites (no installer code)
 Repo work that must land before an installer can exist.
 1. **`servuo-plugins`: add `.gitea/workflows/release.yml`.** Retarget the release *engine* half of
   `link/release.yml` (its header comment explicitly anticipates this — the plan/release steps
   consume only `{version, changelog, artifacts}`). The adapter half produces
   `runicgateway-overlay-<ver>.tar.gz` containing `overlay/`, `patches/`, and a `manifest.json`
   (version, commit, per-file SHA256, declared protocol version, minimum ServUO version).
 2. **`link`: make the sidecar installable.** Confirm/settle default data paths, and add a way to
   read back config non-interactively (e.g. `--print-config` emitting JSON: bind addresses, token,
   protocol version, db path) so the installer does not have to scrape logs for the token.
 3. **Bundle CI in the installer repo** (§7). Compose job (read both repos' latest releases → run the
   two gates → publish `bundle.json`), the nightly cron, and the dispatch step appended to each
   component's release workflow. This must exist before Phase 1 is useful, since the installer
   resolves what to install *from* the bundle.
 4. **`docs`: this file, plus `docs/installer/INSTALL.md`** (the operator-facing guide) once the
   shape is settled.
 ### Phase 1 — installer core
 - ServUO root detection and validation (`ServUO.exe`, `Scripts/`, `Config/`), with version detection
  and an explicit refusal when the ServUO process is running.
 - Overlay sync: fetch tarball → verify SHA256 → hash-compare against the server tree → add/change,
  **never delete**. Port of `deploy.ps1` semantics including its `-Verify` dry run (`--verify`).
 - Write `install.json`: component, version, source commit, per-file hashes, applied patches,
  timestamp.
 - Idempotent re-runs; a second run with no upstream change reports "unchanged" and writes nothing.
 ### Phase 2 — uo-link install and service
 - Linux: binary → `/usr/bin/runicgateway-link`, config → `/etc/runicgateway/sidecar.toml`, db →
  `/var/lib/runicgateway/`, systemd unit with a dedicated user, `enable` + `start`.
 - Windows: `%ProgramFiles%\RunicGateway\`, data in `%ProgramData%\RunicGateway\`, service
  registration with automatic start and restart-on-failure.
 - Both: `UOLINK_CONFIG` and `UOLINK_DB_PATH` pinned in the service definition (§2.3).
 - Token surfacing (§6).
 ### Phase 3 — patch tier (opt-in)
 Everything in §2.2. Detect applicability, dry-run, apply, record, warn about the core rebuild, and
 degrade loudly rather than silently.
 ### Phase 4 — diagnostics and updates
 `runicgateway doctor` — the command that makes the whole thing supportable:
 ```
 ✓ ServUO found            /opt/ServUO  (57.4)
 ✓ Overlay in sync         23 files, all hashes match install.json
 ⚠ Patch tier              1 of 3 applied — vendor.sale unavailable
 ✓ uo-link installed       3.0.1
 ✓ Service                 running, enabled
 ✓ Sidecar reachable       127.0.0.1:8080  /health ok
 ✓ Protocol                sidecar 3 = overlay manifest 3
 ✗ Shard connected         no shard has dialed in since boot
 ```
 The last check matters most: it is the only thing that distinguishes "files copied" from "the bridge
 actually works" (§2.1).
 `runicgateway update` — resolves the current bundle (§7.1), then acts asymmetrically by component,
 deliberately:
 - **uo-link**: compare the bundle's version against what is installed → download → verify checksum →
  replace binary → restart service.
 - **plugin overlay**: download the bundle's overlay tarball → verify → re-sync → record commit →
  tell the operator ServUO must restart (the installer does not restart the shard).
 Because both come from one bundle, an update always moves to a combination whose protocol versions
 were checked together, rather than to two independently-latest artifacts that may disagree.
 `runicgateway uninstall` — **removes only what it exclusively owns, and never edits the ServUO
 tree.** The installer cannot know what the operator has changed in those files since deployment, so
 a clever automatic revert risks silently eating their work. It removes and it reports:
 | Action | Scope |
 |---|---|
 | Removed | uo-link binary, its service entry (systemd unit / Windows service), `install.json` and the cached patch set |
 | Kept | `sidecar.toml` and `uo-link.db` (config and history survive; `--purge` to drop them) |
 | **Printed, not done** | Every overlay file deployed into the ServUO tree, listed by path, for the operator to delete |
 | **Printed, not done** | The exact hunks each applied patch added to `EventSink.cs`, `PlayerVendorGumps.cs`, `Logging.cs`, rendered from the cached `.patch` files, for the operator to revert by hand |
 The printed report is also written to a file, so it survives the terminal scrollback of a long
 uninstall.
 ### Phase 5 — packaging polish
 `.deb` packaging, Windows MSI, arm64 cross build, and optional automated backup before upgrade.
 Deliberately last: v1 can register services directly (`sc create` / a written systemd unit) and ship
 plain binaries. Nothing in Phases 1–4 should have to change to add these.
 ---
 ## 6. Token handoff (the end of a successful run)
 ```
 Runic Gateway is installed.
 One manual step remains — connect the website to this sidecar:
  Base URL          http://<this-host>:8080
  WebSocket URL     ws://<this-host>:8080/ws
  Protocol version  3
  Auth token        4f9c...   (also in /etc/runicgateway/sidecar.toml)
 Paste these into  Admin → Shard  on your Runic Gateway site:
  https://<your-site>/admin/shard
 The token is write-only once saved — the site will never show it back to you.
 ```
 The installer prompts for the site URL only to build that link; it never contacts the website. A
 future "installer registers itself with the website" flow (claim code + authenticated endpoint) is
 explicitly **out of scope** — it is real backend work in a security-sensitive area and can be added
 later without changing anything here.
 ---
 ## 7. Version tracking, the bundle, and release orchestration
 Three components version independently, bound by a protocol contract:
 - **sidecar** — `PROTOCOL_VERSION` in `link/sidecar/src/main.rs`, exposed on `/health` and as
  `X-UOLink-Version` on every response; a mismatch is rejected `409`.
 - **website** — stores an expected protocol version in `uoLinkConfig` (admin-managed).
 - **plugin overlay** — has no queryable version before ServUO boots. The overlay release
  `manifest.json` declares it, and `install.json` records what was deployed.
 ### 7.1 The bundle manifest
 **The bundle is the compat matrix.** Rather than the installer hardcoding versions or blindly
 resolving "latest", CI publishes a small manifest naming an exact, checked combination:
 ```json
 {
  "bundle": "2026.08.01",
  "protocol": 3,
  "link":    { "version": "3.0.1", "sha256": "a91f..." },
  "overlay": { "version": "2.4.0", "commit": "a81f42c", "sha256": "7c3e..." }
 }
 ```
 The installer fetches the current bundle at run time; `--bundle <tag>` pins an older one for a
 reproducible install. Because the bundle is data, **a new `link` release regenerates ~20 lines of
 JSON and leaves the installer binary untouched** — operators do not re-download the installer to
 pick up a sidecar patch, and the installer does not accumulate releases whose code is byte-identical.
 Two gates run at compose time, both cheap and both worth it:
 1. The sidecar's `PROTOCOL_VERSION` must equal the overlay manifest's declared protocol version.
   This is the check that catches an `edge`/`main` protocol mismatch before it reaches an operator.
 2. Every referenced asset must exist and its SHA256 must match the publishing repo's `SHA256SUMS`.
 ### 7.2 What triggers a bundle
 | Trigger | Why |
 |---|---|
 | `link` publishes a release | Its release job `POST`s to the installer repo's workflow-dispatch endpoint as its final step. `link/.gitea/workflows/release.yml` already declares `workflow_dispatch: {}` and already holds a `write:repository` token |
 | `servuo-plugins` publishes a release | Same, once Phase 0 gives it a release workflow |
 | Nightly cron on the installer repo | Recomputes from whatever the latest releases actually are, so a missed or failed dispatch self-heals instead of silently pinning operators to a stale sidecar |
 `repository_dispatch` is deliberately avoided — support for it is uncertain on this Gitea version,
 whereas dispatching an existing `workflow_dispatch` workflow via the API works today.
 ### 7.3 Stale-overlay handling: dispatch, don't wait
 Each component **self-releases on merge to its own `main`**, using the same conventional-commit
 engine. Note that "updated since the last release" must mean *releasable* commits — the engine sets
 `RELEASE=false` when nothing but `docs:`/`chore:` has landed, so a docs typo correctly does **not**
 cut an overlay release, and the bundle keeps using the existing one.
 So by the time the installer's CI looks, the release normally already exists. If it finds
 `servuo-plugins` main ahead of its latest release *with* releasable commits, it:
 1. fires that repo's release workflow via workflow-dispatch and **does not wait for it**,
 2. composes this bundle from the assets that exist right now,
 3. writes a loud warning into the job summary.
 The new overlay release lands minutes later on its own and the nightly cron folds it into the next
 bundle. This gets the automation without the flaky part: dispatching another repo's workflow is
 fine — that workflow still runs its own gates — but *polling* it is not, because Gitea's dispatch
 endpoint returns no run handle, so the job would have to guess which run is its own and hold a
 runner idle meanwhile. The warning exists so a genuinely broken release workflow surfaces once
 rather than being silently retriggered every night forever.
 ### 7.4 Open risk
 The v3 cutover is mid-flight — protocol work landed on `edge` branches with the `edge → main`
 cutover still open across four repos. Until that lands, `main` and `edge` disagree about
 `PROTOCOL_VERSION`, so the installer must not hardcode a version anywhere; it reads what the
 artifacts declare, and §7.1's gate 1 is what stops a mismatched pair from being published as a
 bundle. See `docs/link/v3.md`.
 ---
 ## 8. Open questions
 1. **Windows service mechanism** — `sc create` against the plain console binary (simplest, works
   today), a bundled WinSW/NSSM shim, or a native `--service` mode in the sidecar using the
   `windows-service` crate (cleanest, but changes `link`). Recommendation: `sc create` for v1,
   revisit if restart semantics prove inadequate.
 2. **Does the installer manage ServUO stop/start?** Currently it refuses while ServUO runs and tells
   the operator to restart afterward. Offering to stop/start would be friendlier but means owning
   another shard's process lifecycle, and the shard's own start scripts vary.
 3. **Co-location assumption** — the shard dials out to the sidecar on loopback `127.0.0.1:7788`, so
   sidecar and ServUO must share a host. Should the installer support installing only uo-link on a
   different host, or hard-assume co-location?
 4. **Branch targeting for the new repo** — `link`, `website`, `servuo-plugins` and `docs` are
   mid-cutover between `edge` and `main`. The installer repo starts clean on `main`; the Phase 0
   `servuo-plugins` release workflow needs a target branch decision.
 Resolved and moved into §1 / §2.2 / §5: uninstall scope, and minimum ServUO version.
 ---
 ## 9. Administrator experience
 Before:
 ```
 find plugins → copy files → edit ServUO → download bridge → start bridge
 → configure startup → find the token → troubleshoot paths
 ```
 After:
 ```
 download artifact → verify checksum → run installer → select ServUO directory
 → install components → paste 4 values into Admin → Shard → start ServUO normally
 ```
--- a/link/INTEGRATION.md
+++ b/link/INTEGRATION.md
@@ -31,31 +31,31 @@ Missing or wrong token → **401** `{"error":"missing or invalid auth token"}`.
 The wire protocol is versioned so a mismatch is caught immediately instead of failing weirdly.
- Every response carries an **`X-UOLink-Version: 2`** header.
+- Every response carries an **`X-UOLink-Version: 3`** header.
- `GET /health` and the WebSocket `ws.hello` frame include `"protocol": 2`.
+- `GET /health` and the WebSocket `ws.hello` frame include `"protocol": 3`.
- **Optionally**, send `X-UOLink-Version: 2` on your requests. If it disagrees with the sidecar, the request is rejected **409 Conflict**:
+- **Optionally**, send `X-UOLink-Version: 3` on your requests. If it disagrees with the sidecar, the request is rejected **409 Conflict**:
  ```json
-  { "error": "protocol version mismatch", "sidecar_protocol": 2, "client_protocol": "1" }
+  { "error": "protocol version mismatch", "sidecar_protocol": 3, "client_protocol": "2" }
  ```
 Pin the version you built against and compare it to the header (or `/health.protocol`) at startup.
 **v2 (Protocol 2.0)** added the account-provisioning surface (§6.x: `POST /accounts/create`, `DELETE /link/{account}`) and the `account.*` events. Outbound event kinds are **additive** — a v1 client that ignores unknown kinds keeps working against the live feed — but the new *endpoints* require a v2 sidecar. If you send `X-UOLink-Version: 1`, calls to the new endpoints are refused with the 409 above.
-**v3 (Protocol 3.0) is being built and the version has not been bumped yet.** It is defined as *adds
+**v3 (Protocol 3.0)** adds `world.ruleset`, `points.board` and `vendor.listing` /
-`world.ruleset`, `points.board`, `vendor.listing` / `vendor.listing.remove`*, and the bump to
+`vendor.listing.remove`, with the `GET /ruleset`, `/points` and `/market` reads that serve them from
-`X-UOLink-Version: 3` happens **exactly once**, at the end, when [`v3.md`](v3.md) §4's `edge` → `main`
+the sidecar's store. Same shape as the v2 bump: the event kinds are additive, so a v2 client that
-cutover lands — because a bump is an operator-visible hard break (409 on every protected route, and
+ignores unknown kinds keeps working against the live feed, but the three new endpoints require a v3
-the website's WS closes on the `ws.hello` mismatch), so doing it per phase would break the site
+sidecar. There is deliberately **no feature-negotiation array** — v3 implies all three kinds, so the
-repeatedly.
+version number alone tells you what is available.
-Until then, sidecars on `edge` still report `2` while already carrying some v3 kinds and endpoints.
+**Upgrading a v2 integration.** The bump is an operator-visible hard break in one direction only: a
-That is safe in the direction that matters: event kinds are additive, and a client that ignores
+client still declaring `2` gets a 409 on every protected route and, on the WebSocket, a closed
-unknown kinds and tolerates a `404` on a not-yet-present endpoint keeps working. What you must **not**
+connection on the `ws.hello` mismatch. So update the pinned version at the same time you deploy the
-do is infer feature availability from the version number during this window — probe the endpoint, or
+v3 sidecar. Nothing that existed in v2 changed shape, so that is the whole migration — the website
-treat a missing `world.ruleset` as "this shard hasn't published one". There is deliberately **no
+does it with a one-shot boot migration of its `uo_link_config.protocol` row ([`v3.md`](v3.md) §4.1);
-feature-negotiation array**: v3 implies all three kinds.
+a third-party client changes the constant it sends.
 ---
@@ -68,7 +68,7 @@ GET /health          (no auth)
 ```json
 {
  "status": "ok",                      // "ok" when plugin connected AND db reachable, else "degraded"
-  "protocol": 1,
+  "protocol": 3,
  "plugin_connected": true,            // is the shard link up right now?
  "database": "ok",                    // "ok" | "error"
  "uptime": "3d 12h",
@@ -91,7 +91,7 @@ A push-only stream of game events as they happen. You do **not** send commands o
 **On connect**, the first frame is:
 ```json
-{ "kind": "ws.hello", "protocol": 1 }
+{ "kind": "ws.hello", "protocol": 3 }
 ```
 **Then** a continuous stream of event frames, each with at least `t` (epoch ms) and `kind`. Route on `kind`.
@@ -955,7 +955,7 @@ sidecar defines no audiences. Deciding who may see what is the consuming site's
 A typical character page:
 ```js
-const H = { "Authorization": `Bearer ${TOKEN}`, "X-UOLink-Version": "2" };
+const H = { "Authorization": `Bearer ${TOKEN}`, "X-UOLink-Version": "3" };
 // 1. render the roster
 const roster = await fetch(`${BASE}/roster/${account}`, { headers: H }).then(r => r.json());
--- a/link/PLAN.md
+++ b/link/PLAN.md
@@ -347,6 +347,12 @@ of 25 vendors x 40 listings and **0.3 ms** in steady state (the per-vendor diff)
 items / 43k mobiles. It is also the first stream to honour a per-player privacy toggle: ServUO's own
 `PlayerVendor.VendorSearch` flag, so a shop hidden in game is hidden on the site.
 That completes 3.0's feature work, so the last step is the version itself: `PROTOCOL_VERSION` **2 →
 3** and the coordinated `edge` → `main` merge across all four repos ([`v3.md`](v3.md) §4 and §4.1).
 The bump is deliberately the *only* thing that happens at that moment — v3 adds kinds and endpoints
 but changes nothing that already existed in v2 — so the operator-visible break is limited to
 re-pinning the version, which the website does for itself in a one-shot boot migration.
 ### Config keys (`Config/Bridge.cfg`)
 ```ini
--- a/link/PROJECT_TREE.md
+++ b/link/PROJECT_TREE.md
@@ -18,6 +18,7 @@ link/
 │   ├── scripts/
 │   │   └── gen_tree.py
 │   ├── workflows/
 │   │   ├── pr-checks.yml
 │   │   ├── release.yml
 │   │   ├── sonarqube.yml
 │   │   └── sync-project-tree.yml
--- a/link/v3.md
+++ b/link/v3.md
@@ -1,6 +1,6 @@
 # Protocol 3.0 — Shard content, standings & the visibility framework
-**Status:** In progress. All work lands on an `edge` branch in each repo; `edge` → `main` is the v3 cutover.
+**Status:** Feature-complete on `edge`; the cutover (order 6) is in review. All work lands on an `edge` branch in each repo; `edge` → `main` is the v3 cutover.
 **Date:** 2026-07-28
 **Codebase:** ServUO 57.4, `<servuo>`, net48 / x64, Expansion **EJ**.
 **Companion to** [`PLAN.md`](PLAN.md) (1.0 read/event plane), [`PROTOCOL_2.md`](PROTOCOL_2.md) (2.0 provisioning + world-state streams), [`ADMIN_CONTROLS.md`](ADMIN_CONTROLS.md) (staff write plane), [`INTEGRATION.md`](INTEGRATION.md) (website API).
@@ -16,13 +16,18 @@ Each part is marked off here as it lands on `edge`. §9 carries the same state p
 | 3 | **C** — spawn atlas (§6) | ✅ **Done** | website [#112](https://gitea.whitlocktech.com/RunicGateway/website/pulls/112) (parsers + CLI + tables) + [#113](https://gitea.whitlocktech.com/RunicGateway/website/pulls/113) (API + pages + admin panel), docs [#67](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/67) + [#68](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/68) |
 | 4 | **B/2** — `points.board` (§7) | ✅ **Done** | servuo-plugins [#4](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/4), link [#18](https://gitea.whitlocktech.com/RunicGateway/link/pulls/18), website [#114](https://gitea.whitlocktech.com/RunicGateway/website/pulls/114), docs [#69](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/69) |
 | 5a | **B/3 dependency** — cliloc table (§8.6) | ✅ **Done** | website [#115](https://gitea.whitlocktech.com/RunicGateway/website/pulls/115), docs [#70](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/70) |
-| 5b | **B/3** — `vendor.listing` (§8) | 🟨 In review | servuo-plugins [#5](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/5), link [#19](https://gitea.whitlocktech.com/RunicGateway/link/pulls/19), website [#116](https://gitea.whitlocktech.com/RunicGateway/website/pulls/116), docs [#71](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/71) |
+| 5b | **B/3** — `vendor.listing` (§8) | ✅ **Done** | servuo-plugins [#5](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/5), link [#19](https://gitea.whitlocktech.com/RunicGateway/link/pulls/19), website [#116](https://gitea.whitlocktech.com/RunicGateway/website/pulls/116), docs [#71](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/71) |
-| 6 | **Cutover** — `PROTOCOL_VERSION` 2→3 (§4) | ⬜ Not started | — |
+| 6 | **Cutover** — `PROTOCOL_VERSION` 2→3 (§4) | 🟨 In review | the bump: link [#20](https://gitea.whitlocktech.com/RunicGateway/link/pulls/20), website [#117](https://gitea.whitlocktech.com/RunicGateway/website/pulls/117), docs [#72](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/72) — then `edge` → `main`: servuo-plugins [#6](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/6), link [#21](https://gitea.whitlocktech.com/RunicGateway/link/pulls/21), website [#118](https://gitea.whitlocktech.com/RunicGateway/website/pulls/118), docs [#73](https://gitea.whitlocktech.com/RunicGateway/docs/pulls/73) |
 Order 5 split in two once §8.6's cliloc dependency turned out to be a client-format problem rather
 than a parser (see §8.6). 5a is website-only and lands first so the marketplace ships with real item
 names; 5b is the four-repo wire change.
 **The `edge` → `main` half of order 6 is held for Android parity** (decided 2026-07-30, see §10): the
 app sees none of the four new features and gates shard nav on session role alone, so merging the
 cutover first would ship a shard whose app client silently disagrees with the web client about what is
 public. The **bump** PRs into `edge` are unaffected and merge normally.
 ---
 ## 1. Why 3.0
@@ -242,6 +247,39 @@ admin-set `uo_link_config.protocol` column — so it happens **exactly once**, a
  from 2 to 3, so the cutover doesn't require a manual admin edit. `UOLINK_PROTOCOL` still overrides.
 - No feature-negotiation array anywhere — v3 implies all three kinds.
 ### 4.1 What the bump actually touches
 The version lives in five places, and all five move together:
 | Where | Change |
 |---|---|
 | `link/sidecar/src/main.rs` | `PROTOCOL_VERSION` 2 → 3 (with the v3 note beside the v2 one), plus the sidecar README's worked example |
 | `website/server/db/schema.sql` | `uo_link_config.protocol` column default 1 → 3, plus the boot migration below |
 | `website/server/src/model/uoLinkConfig/uoLinkConfig.model.js` | `DEFAULT_PROTOCOL` — what a site with nothing saved yet declares |
 | `website/server/src/utils/uoLinkClient.js` + `uoLinkSocket.js` | the `config.protocol || …` fallbacks, so an unset value can never quietly send `1` and 409 with a confusing message |
 | `website/client/.../ShardAdmin.jsx`, `website/.env.example` | the admin form's initial value and the documented env default |
 **The migration has to be one-shot, and that is the only subtle part.** `schema.sql` is re-run on
 *every* boot (`utils/db.js::ensureSchema`), and every other statement in its migration block is an
 idempotent `ADD COLUMN IF NOT EXISTS` / `MODIFY`. A bare `UPDATE uo_link_config SET protocol = 3`
 would not be idempotent in the sense that matters: `protocol` is **admin-editable**, so an operator
 who deliberately pins an older sidecar in Admin → Shard would silently be un-pinned on the next
 restart. It is therefore gated on a marker row in `settings`:
 ```sql
 ALTER TABLE uo_link_config MODIFY COLUMN protocol INT NOT NULL DEFAULT 3;
 UPDATE uo_link_config SET protocol = 3
  WHERE id = 1 AND protocol < 3
    AND NOT EXISTS (SELECT 1 FROM settings WHERE `key` = 'uo_link_protocol_3_migrated');
 INSERT IGNORE INTO settings (`key`, value) VALUES ('uo_link_protocol_3_migrated', '1');
 ```
 The marker is written *after* the `UPDATE`, so the first boot on the new build migrates and every
 later boot is a no-op. A fresh install has no `uo_link_config` row to update and simply gets the
 marker plus the new column default. `protocol < 3` rather than `= 2` so an install that never left
 the old default of `1` is carried across too — it could not have been talking to a v2 sidecar
 anyway.
 ---
 ## 5. Part B/1 — `world.ruleset` ✅ Done
@@ -312,8 +350,11 @@ Sidecar — `store.rs`: singleton `ruleset(id CHECK(id=1), rev, json, updated_t)
 `main.rs`: new arm in the board-projection match; `web.rs`: `GET /ruleset` served from the store, so
 it answers during a shard outage (`PROTOCOL_2.md` §12.2).
-Website — `uoLinkClient.getRuleset()`; `uoLinkSocket.backfill()` (object-shaped, so follow the
+Website — `uoLinkClient.getRuleset()`; `uoLinkSocket.backfill()` (object-shaped, so it cannot use the
-`getPresence()` block's explicit form, not the array-only `snapshot()` helper); `shardIngest.js` →
+array-only `snapshot()` helper — but it **must still go through `shardIngest.ingest()`**, as
 `ingestEach` does, rather than calling `shardState.setRuleset` directly: the two arrival orders have
 to produce the same stored frame, and a direct call quietly made backfill a second writer that
 skipped the normalization below); `shardIngest.js` →
 `shardState.setRuleset`, **not** in `LOGGED_KINDS` (it re-arrives every reconnect and `server.hello`
 already marks those); `KIND_FEATURE['world.ruleset'] = 'ruleset'`; `shard_ruleset` singleton table
 (`rev`, `expansion`, `payload JSON`, `t`); `GET /public/shard/ruleset` behind
@@ -322,6 +363,17 @@ already marks those); `KIND_FEATURE['world.ruleset'] = 'ruleset'`; `shard_rulese
 Client — NEW `routes/public/Rules.jsx` at `/site/rules`, alongside
 `/site/champs|guilds|governors|houses`; live via `useShardFeed({ filter: new Set(['world.ruleset']) })`.
 **The `shard` field falls back to the instance's own name.** ServUO ships `Server.cfg` with
 `Name=My Shard`, so an operator who never edited it publishes that verbatim — which is the shard
 saying *unnamed*, not naming anything, and the rules page then reads "My Shard" under a header
 carrying the real one. `shardIngest` substitutes `settings.getInstanceName()` (the admin-editable
 site title, else `BRAND_NAME` — the same resolution `getPublic().brand.name` uses, so one install
 never shows two names) when `shard` is absent, blank, or exactly the stock default, matched
 case-insensitively and trim-tolerantly but only as a **whole** value: a shard genuinely called
 *"My Shard Reborn"* has named itself and keeps it. Applied at **ingest**, not on read, because the
 ruleset is also broadcast live — the same object goes to the SSE fan-out, so a read-time
 substitution would be undone by the next reconnect's frame.
 ### 5.4 Risk
 Perf is nil (~3 KB per connect). The only real risk is publishing a secret, mitigated by the explicit
@@ -600,6 +652,15 @@ Client — NEW `routes/public/Leaderboards.jsx` at `/site/leaderboards`; a "Loya
 added to `components/CharacterSheet.jsx`, one edit serving both `PlayerCharacter.jsx` and
 `AdminCharacter.jsx`.
 **An unscored board still renders a row.** Most systems on a young shard have `top: []`, and a page
 of blank cards reads as broken rather than as new — so a board with no entries shows a single
 placeholder bearing the **instance's own name** with an em dash where a score goes, above the
 existing "nobody has earned points here yet" line. It is deliberately **not** shaped like an entry —
 no rank, no medal, no bar, muted — because a placeholder that looked like a real standing would be a
 fabricated one; the first real entry replaces it outright. Purely presentational: the API keeps
 sending an empty `top`, so no consumer ever receives an invented row. Web and app render it the same
 way (`Leaderboards.jsx`, `LeaderboardsScreen.kt`).
 ### 7.5 What the run against a real shard changed
 The plan above was written from reading `PointsSystem.cs`. Booting the actual shard (ServUO 57.4, a
@@ -887,8 +948,8 @@ not a blocker here.)
 | 3 | **C** — spawn atlas (§6) | website, docs | none | ✅ Done |
 | 4 | **B/2** — `points.board` (§7) | all four | new kind + `char.profile` field | ✅ Done |
 | 5a | **B/3 dependency** — cliloc table (§8.6) | website, docs | none | ✅ Done |
-| 5b | **B/3** — `vendor.listing` (§8) | all four | new kinds | 🟨 In review |
+| 5b | **B/3** — `vendor.listing` (§8) | all four | new kinds | ✅ Done |
-| 6 | **Cutover** — `PROTOCOL_VERSION` 2→3, `edge` → `main` | all four | the bump | ⬜ |
+| 6 | **Cutover** — `PROTOCOL_VERSION` 2→3, `edge` → `main` | all four | the bump | 🟨 In review — `edge` → `main` held for Android parity (§10) |
 ---
@@ -910,8 +971,24 @@ not a blocker here.)
 - `npm run swagger` **and** `npm run routes:manifest` on every route-touching PR — both are committed
  artifacts, and `test/routeManifest.test.js` fails on drift.
-**Follow-up, not scoped for 3.0:** the Android app consumes the same public/player shard API and will
+**Android parity — now scoped, and it gates the cutover (decided 2026-07-30).** This was written as a
-need `/public/shard/features` to hide its own nav. Track separately against `android-app/`.
+"track separately" follow-up. It was re-examined before the cutover and the gap is wider than nav
 hiding: the app consumes the same public/player shard API but has **no consumer for any of the four new
 features** (`ruleset`, `leaderboards`, `market`, `atlas`), no `points` block on its character sheet, no
 cliloc-resolved item names (§8.6), and — the part that matters for §3 — **it gates shard navigation on
 session role alone**, so an admin who disables a feature or raises its audience leaves the app
 rendering entries that `404`/`403` into a generic error where the web client hides them.
 Two things were verified as already correct and are recorded so they are not re-derived: the app's SSE
 request rides the same authenticated OkHttp client as every other call, so an app session resolves to
 the same audience rung as the same account on the web; and every shard DTO in the app is
 nullable-with-defaults, so field projection strips fields without a deserialization failure.
 Scoped as **M11 in [`../android/PLAN.md`](../android/PLAN.md) §9**, two PRs (the visibility rules +
 read-model adds, then the four screens). `edge` → `main` is held until both land, so web and app
 surface the same shard on the same day. Neither PR is coupled to the merge order — on a pre-v3 website
 every new route and `/public/shard/features` `404`s and the app falls back to today's behavior — so
 holding the cutover is a schedule decision, not a technical dependency.
 ---
--- a/website/CLILOCS.md
+++ b/website/CLILOCS.md
@@ -44,6 +44,11 @@ they did before the table existed.
 ## Converting
 > **Step-by-step operator instructions — where to get UOFiddler, where your
 > client files are, and how to verify the import — are in
 > [`UOFIDDLER.md`](UOFIDDLER.md).** This section covers the formats and the
 > reasoning behind them.
 Either format below is accepted; the site sniffs which one it was handed.
 | Format | Fidelity | Notes |
@@ -77,8 +82,16 @@ dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/cli
 dotnet run -- "<UOFiddler>/Ultima.dll" "<UO client>/Cliloc.enu" /srv/uo-data/clilocs.tsv --tsv
 ```
-A UOFiddler GUI export works equally well — anything producing one of the two
+A UOFiddler GUI export works too, but **not unmodified**: its Cliloc tab writes
-shapes above is fine.
+`Number;Text;Flag` — three columns, the flag *last* — and the parser reads
 `number<separator>text`, so the trailing field is absorbed into the name and
 every item renders as `quarter staff;0`. Stripping it is one `sed`, given in
 [`UOFIDDLER.md`](UOFIDDLER.md) §Route B.
 The parser already tolerates `number,flag,text`, with the flag in the *middle*.
 It is not extended to cover the trailing form because a final `;0` is
 indistinguishable from a name that genuinely ends that way — a heuristic there
 would corrupt real names to save the operator one command.
 ## Shard-added and shard-edited items
--- a/website/PROJECT_TREE.md
+++ b/website/PROJECT_TREE.md
@@ -164,6 +164,7 @@ website/
 │   │   │   ├── heroLayout.js
 │   │   │   ├── shardEvents.js
 │   │   │   ├── useAsync.js
 │   │   │   ├── useShardFeatures.js
 │   │   │   └── useShardFeed.js
 │   │   ├── routes/
 │   │   │   ├── admin/
@@ -190,6 +191,8 @@ website/
 │   │   │   │   │   ├── SettingsAdmin.jsx
 │   │   │   │   │   ├── ShardAdmin.jsx
 │   │   │   │   │   ├── ShardOps.jsx
 │   │   │   │   │   ├── ShardVisibility.jsx
 │   │   │   │   │   ├── SpawnAtlas.jsx
 │   │   │   │   │   ├── UserDetail.jsx
 │   │   │   │   │   ├── UserEditor.jsx
 │   │   │   │   │   ├── UsersAdmin.jsx
@@ -213,17 +216,23 @@ website/
 │   │   │   │   └── ResetPassword.jsx
 │   │   │   ├── public/
 │   │   │   │   ├── About.jsx
 │   │   │   │   ├── Atlas.jsx
 │   │   │   │   ├── AtlasCreature.jsx
 │   │   │   │   ├── ChampSpawns.jsx
 │   │   │   │   ├── CmsPage.jsx
 │   │   │   │   ├── FiveOnFriday.jsx
 │   │   │   │   ├── Governors.jsx
 │   │   │   │   ├── Guilds.jsx
 │   │   │   │   ├── Houses.jsx
 │   │   │   │   ├── Leaderboards.jsx
 │   │   │   │   ├── Maintenance.jsx
 │   │   │   │   ├── Market.jsx
 │   │   │   │   ├── MarketVendor.jsx
 │   │   │   │   ├── News.jsx
 │   │   │   │   ├── Newsletter.jsx
 │   │   │   │   ├── NewsletterIssue.jsx
 │   │   │   │   ├── Portal.jsx
 │   │   │   │   ├── Rules.jsx
 │   │   │   │   ├── Screenshots.jsx
 │   │   │   │   ├── Shard.jsx
 │   │   │   │   ├── ShardActivity.jsx
@@ -257,9 +266,12 @@ website/
 │   └── sonar-test-reporter.mjs
 ├── server/
 │   ├── db/
 │   │   ├── data/
 │   │   │   └── spawnAtlas.art.example.json
 │   │   ├── schema.sql
 │   │   └── seed.js
 │   ├── scripts/
 │   │   ├── importSpawnAtlas.js
 │   │   └── routeManifest.js
 │   ├── src/
 │   │   ├── auth/
@@ -365,15 +377,27 @@ website/
 │   │   │   ├── settings/
 │   │   │   │   ├── settings.db.js
 │   │   │   │   └── settings.model.js
 │   │   │   ├── shardAtlas/
 │   │   │   │   ├── shardAtlas.db.js
 │   │   │   │   └── shardAtlas.model.js
 │   │   │   ├── shardClilocs/
 │   │   │   │   ├── shardClilocs.db.js
 │   │   │   │   └── shardClilocs.model.js
 │   │   │   ├── shardEvents/
 │   │   │   │   ├── shardEvents.db.js
 │   │   │   │   └── shardEvents.model.js
 │   │   │   ├── shardLinks/
 │   │   │   │   ├── shardLinks.db.js
 │   │   │   │   └── shardLinks.model.js
 │   │   │   ├── shardMarket/
 │   │   │   │   ├── shardMarket.db.js
 │   │   │   │   └── shardMarket.model.js
 │   │   │   ├── shardState/
 │   │   │   │   ├── shardState.db.js
 │   │   │   │   └── shardState.model.js
 │   │   │   ├── shardVisibility/
 │   │   │   │   ├── shardVisibility.db.js
 │   │   │   │   └── shardVisibility.model.js
 │   │   │   ├── trustedDevices/
 │   │   │   │   ├── trustedDevices.db.js
 │   │   │   │   └── trustedDevices.model.js
@@ -398,12 +422,14 @@ website/
 │   │   │   │   │   ├── account.router.js
 │   │   │   │   │   ├── activity.router.js
 │   │   │   │   │   ├── admin.controller.js
 │   │   │   │   │   ├── admin.routes.js
 │   │   │   │   │   ├── authProviders.controller.js
 │   │   │   │   │   ├── authProviders.router.js
 │   │   │   │   │   ├── botActivity.controller.js
 │   │   │   │   │   ├── botActivity.router.js
 │   │   │   │   │   ├── dashboard.router.js
 │   │   │   │   │   ├── discordBot.controller.js
 │   │   │   │   │   ├── discordBot.router.js
 │   │   │   │   │   ├── email.router.js
 │   │   │   │   │   ├── emailConfig.controller.js
 │   │   │   │   │   ├── imageUpload.js
 │   │   │   │   │   ├── index.js
@@ -414,16 +440,25 @@ website/
 │   │   │   │   │   ├── pages.controller.js
 │   │   │   │   │   ├── pages.router.js
 │   │   │   │   │   ├── posts.router.js
 │   │   │   │   │   ├── settings.router.js
 │   │   │   │   │   ├── shard.router.js
 │   │   │   │   │   ├── shardAtlas.controller.js
 │   │   │   │   │   ├── shardClilocs.controller.js
 │   │   │   │   │   ├── shardOps.controller.js
 │   │   │   │   │   ├── shardVisibility.controller.js
 │   │   │   │   │   ├── uoLink.controller.js
 │   │   │   │   │   ├── uoLink.router.js
 │   │   │   │   │   ├── uploads.router.js
 │   │   │   │   │   ├── users.router.js
 │   │   │   │   │   ├── usersShard.controller.js
 │   │   │   │   │   └── wiki.router.js
 │   │   │   │   ├── auth/
 │   │   │   │   │   ├── auth.controller.js
-│   │   │   │   │   ├── auth.routes.js
+│   │   │   │   │   ├── index.js
 │   │   │   │   │   ├── invite.controller.js
 │   │   │   │   │   ├── invite.router.js
 │   │   │   │   │   ├── login.router.js
 │   │   │   │   │   ├── loginGuards.js
 │   │   │   │   │   ├── me.routes.js
 │   │   │   │   │   ├── mobile.controller.js
 │   │   │   │   │   ├── mobile.routes.js
@@ -431,7 +466,10 @@ website/
 │   │   │   │   │   ├── mobileSso.routes.js
 │   │   │   │   │   ├── notifications.controller.js
 │   │   │   │   │   ├── notifications.routes.js
 │   │   │   │   │   ├── password.router.js
 │   │   │   │   │   ├── passwordReset.controller.js
 │   │   │   │   │   ├── register.router.js
 │   │   │   │   │   ├── session.router.js
 │   │   │   │   │   ├── sso.controller.js
 │   │   │   │   │   ├── sso.routes.js
 │   │   │   │   │   └── trustDevice.helper.js
@@ -439,13 +477,23 @@ website/
 │   │   │   │   │   ├── internal.controller.js
 │   │   │   │   │   └── internal.routes.js
 │   │   │   │   ├── player/
 │   │   │   │   │   ├── account.router.js
 │   │   │   │   │   ├── appeals.controller.js
-│   │   │   │   │   ├── player.routes.js
+│   │   │   │   │   ├── appeals.router.js
-│   │   │   │   │   └── shard.controller.js
+│   │   │   │   │   ├── index.js
 │   │   │   │   │   ├── shard.controller.js
 │   │   │   │   │   └── shard.router.js
 │   │   │   │   ├── public/
 │   │   │   │   │   ├── atlas.controller.js
 │   │   │   │   │   ├── atlas.router.js
 │   │   │   │   │   ├── index.js
 │   │   │   │   │   ├── pages.router.js
 │   │   │   │   │   ├── posts.router.js
 │   │   │   │   │   ├── public.controller.js
-│   │   │   │   │   ├── public.routes.js
+│   │   │   │   │   ├── shard.controller.js
-│   │   │   │   │   └── shard.controller.js
+│   │   │   │   │   ├── shard.router.js
 │   │   │   │   │   ├── site.router.js
 │   │   │   │   │   └── wiki.router.js
 │   │   │   │   └── v1.router.js
 │   │   │   ├── api.router.js
 │   │   │   ├── cspReport.controller.js
@@ -455,6 +503,8 @@ website/
 │   │   │   ├── auth.js
 │   │   │   ├── botInternalClient.js
 │   │   │   ├── botInternalKey.js
 │   │   │   ├── clilocParse.js
 │   │   │   ├── clilocSource.js
 │   │   │   ├── db.js
 │   │   │   ├── logger.js
 │   │   │   ├── mailer.js
@@ -465,6 +515,9 @@ website/
 │   │   │   ├── shardBroadcast.js
 │   │   │   ├── shardIngest.js
 │   │   │   ├── shardSales.js
 │   │   │   ├── shardVisibility.js
 │   │   │   ├── spawnAtlasParse.js
 │   │   │   ├── spawnAtlasSource.js
 │   │   │   ├── totp.js
 │   │   │   ├── trustProxy.js
 │   │   │   ├── uoLinkClient.js
@@ -483,11 +536,14 @@ website/
 │   │   ├── appeals.pure.test.js
 │   │   ├── appeals.test.js
 │   │   ├── appLinks.test.js
 │   │   ├── atlasController.test.js
 │   │   ├── authController.test.js
 │   │   ├── authMe.test.js
 │   │   ├── authTrustedDevice.test.js
 │   │   ├── botInternalKey.test.js
 │   │   ├── botScore.test.js
 │   │   ├── clilocParse.test.js
 │   │   ├── clilocSource.test.js
 │   │   ├── csp.test.js
 │   │   ├── emailConfig.model.test.js
 │   │   ├── honeypot.test.js
@@ -521,17 +577,32 @@ website/
 │   │   ├── secretBox.test.js
 │   │   ├── selfTrustedDevices.test.js
 │   │   ├── session.test.js
 │   │   ├── shardBroadcast.visibility.test.js
 │   │   ├── shardControllerPublic.test.js
 │   │   ├── shardIngest.champsPages.test.js
 │   │   ├── shardIngest.market.test.js
 │   │   ├── shardIngest.points.test.js
 │   │   ├── shardIngest.protocol2.test.js
 │   │   ├── shardIngest.ruleset.test.js
 │   │   ├── shardMarket.model.test.js
 │   │   ├── shardState.governorTerms.test.js
 │   │   ├── shardState.model.test.js
 │   │   ├── shardVisibility.test.js
 │   │   ├── spawnAtlas.parse.test.js
 │   │   ├── spawnAtlas.source.test.js
 │   │   ├── ssoCallback.test.js
 │   │   ├── ssoState.test.js
 │   │   ├── ssoTrustedDevice.test.js
 │   │   ├── totp.test.js
 │   │   ├── trustedDevices.test.js
 │   │   ├── trustProxy.test.js
 │   │   ├── uoLinkClient.test.js
 │   │   └── usernamePolicy.test.js
 │   ├── tools/
 │   │   └── cliloc-export/
 │   │       ├── clilocexport.csproj
 │   │       ├── Program.cs
 │   │       └── README.md
 │   ├── .env.example
 │   ├── package-lock.json
 │   ├── package.json
--- a/website/SPAWN_ATLAS.md
+++ b/website/SPAWN_ATLAS.md
@@ -223,7 +223,8 @@ The atlas is fully functional as text. `shard_spawn_creatures.art` is nullable
 and is NULL on every fresh import; pages render without images, which is the
 normal and supported state, not a degraded one.
-An operator who wants art:
+An operator who wants art — step-by-step, with the UOFiddler side spelled out, in
 [`UOFIDDLER.md`](UOFIDDLER.md) §Part 2:
 1. Extracts it from **their own** client files (UOFiddler, ClassicUO tooling, or
   any art extractor).
--- a/website/UOFIDDLER.md
+++ b/website/UOFIDDLER.md
@@ -0,0 +1,282 @@
 # Extracting from your own UO client (UOFiddler)
 **Audience:** the shard operator, once, at setup time.
 **Related:** [`CLILOCS.md`](CLILOCS.md) (why the cliloc conversion is unavoidable),
 [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md) (where creature art fits).
 Two features read data that **only exists inside a UO client**, and a UO client's
 files are EA's, not ours to redistribute. So neither this repo nor any image we
 publish can ship them — the operator extracts from **their own** client, once,
 and points the site at the result.
 | Feature | What it needs | Required? | Without it |
 |---|---|---|---|
 | **Item / title names** ([`CLILOCS.md`](CLILOCS.md)) | `Cliloc.enu`, converted | No | Names render as raw ids — `id 1023721` instead of *quarter staff* |
 | **Creature art** ([`SPAWN_ATLAS.md`](SPAWN_ATLAS.md)) | Sprites from `.mul`/`.uop` | No | Atlas pages render as text, which is the normal state |
 **Both are optional and neither is load-bearing.** A shard that never does any of
 this is fully supported. Do part one and skip part two if art is not worth your
 time — they share only the tool.
 Everything you extract stays **outside the repository**: the converted cliloc
 file lives at a path you choose, and `spawnAtlas.art.json` plus `server/uploads/`
 are gitignored, so none of it can be committed by accident.
 ---
 ## Part 0 — Get UOFiddler
 [UOFiddler](https://github.com/polserver/UOFiddler) is the community client-file
 editor. We use it because its `Ultima.dll` already contains the cliloc
 decompressor, maintained by people who do this for a living.
 1. Download the latest release zip from
   <https://github.com/polserver/UOFiddler/releases/latest> — one asset, named
   `UOFiddler-<version>.zip` (4.22.2 is ~2 MB).
 2. Extract it. The zip contains a single top-level folder, and the two files that
   matter are at **its root**:
   ```
   UOFiddler-4.22.2/
     Ultima.dll        ← the decompressor (Part 1 needs this path)
     UoFiddler.exe     ← the GUI (Part 2 needs this)
     plugins/
     …
   ```
 3. **Runtime:** UOFiddler 4.22.2 is built for **.NET 10**. Running `UoFiddler.exe`
   needs the .NET 10 **Desktop** Runtime (Windows only); loading `Ultima.dll` from
   the converter in Part 1 needs the .NET 10 runtime. Install from
   <https://dotnet.microsoft.com/download/dotnet/10.0>.
 ### Finding your client files
 The cliloc file is in your **UO client installation directory**, not in your
 ServUO tree — the shard server has no copy of it. Look for `Cliloc.enu` (English;
 the other seven are `chs`, `cht`, `deu`, `esp`, `fra`, `jpn`, `kor`) beside
 `art.mul` / `artLegacyMUL.uop`. The EA Classic Client's default location is:
 ```
 C:\Program Files (x86)\Electronic Arts\Ultima Online Classic\
 ```
 **If your shard distributes its own patched client to players, use that copy.**
 Any cliloc edits you shipped to players are then already in the base table and
 you need no overlay for them (see [`CLILOCS.md`](CLILOCS.md) §Shard-added and
 shard-edited items).
 ---
 ## Part 1 — Convert the cliloc table
 **Goal:** turn the client's compressed `Cliloc.enu` into a file the site can
 read, and point the site at it.
 The site cannot read `Cliloc.enu` directly. Every modern client compresses it
 (the "Mythic" container), and so does ServUO's own bundled `Ultima.StringList` —
 which is why the shard cannot supply names on our behalf either. The full
 reasoning is in [`CLILOCS.md`](CLILOCS.md) §Why the operator has to convert the
 file; this section is just the procedure.
 Two routes. **The bundled tool is the recommended one** — the GUI export needs a
 fixup step, described below.
 ### Route A — the bundled converter (recommended)
 Needs a .NET SDK (any version 8 or newer — the project targets `net8.0` and rolls
 forward, so whatever you have works) **plus** the .NET 10 runtime from Part 0,
 which is what actually loads `Ultima.dll`.
 ```bash
 cd website/server/tools/cliloc-export
 dotnet build -c Release
 # plain binary — recommended, exact
 dotnet run -c Release -- \
  "/path/to/UOFiddler-4.22.2/Ultima.dll" \
  "/path/to/UO client/Cliloc.enu" \
  /srv/uo-data/clilocs.plain
 # or tab-delimited text, if you want to eyeball or hand-edit it
 dotnet run -c Release -- \
  "/path/to/UOFiddler-4.22.2/Ultima.dll" \
  "/path/to/UO client/Cliloc.enu" \
  /srv/uo-data/clilocs.tsv --tsv
 ```
 Expected output for a stock English client:
 ```
 wrote 123490 entries to /srv/uo-data/clilocs.plain (maxTextBytes=12150, skippedOversize=0)
 ```
 **Sanity-check that number.** A stock `Cliloc.enu` is ~123,000 entries. A few
 hundred means it read something else and you should not ship the result. The
 tool exits non-zero and says `no entries were written — is that a cliloc file?`
 when it gets nothing at all.
 The conversion runs on whatever machine has the client (usually Windows), and the
 site reads the output wherever it runs — so **copy the output file to the server**
 if those are different machines. It is a single self-contained file (~5 MB); the
 `--tsv` form is larger but diff-able.
 <details>
 <summary>Errors you may hit</summary>
 | Message | Cause |
 |---|---|
 | `Ultima.StringList not found — is that really UOFiddler's Ultima.dll?` | First argument points at some other `Ultima.dll` (ServUO ships one too — it is **not** the same assembly and cannot do this) |
 | `You must install .NET to run this application` | Missing the .NET 10 runtime from Part 0 step 3 |
 | `Unexpected Ultima.StringList API` | UOFiddler older than 4.21 |
 | `usage: clilocexport …` | Fewer than three arguments |
 </details>
 ### Route B — the UOFiddler GUI
 Use this if you would rather not install a .NET SDK. **It needs one extra step**,
 so do not skip the fixup.
 1. Launch `UoFiddler.exe` and point it at your client directory when it asks
   (or **Options → Path Settings**).
 2. Open the **Cliloc** tab and use its **export to CSV** action.
 3. It writes `CliLoc.csv` to UOFiddler's configured output path, in **three**
   columns with a header row:
   ```
   Number;Text;Flag
   1023721;quarter staff;0
   ```
 4. **Strip the trailing flag column.** The site's text parser reads
   `number<TAB|,|;>text`, so that third field is otherwise absorbed into the name
   and every item on the site renders as `quarter staff;0`.
   ```bash
   sed -E 's/;[0-9]+$//' CliLoc.csv > clilocs.csv
   ```
   ```powershell
   Get-Content CliLoc.csv |
     ForEach-Object { $_ -replace ';\d+$','' } |
     Set-Content -Encoding utf8 clilocs.csv
   ```
   The header row needs no removal — a line whose first field is not an integer
   is skipped. Blank entries (`1005008;`) survive the fixup correctly and are
   dropped at import, as intended.
 5. Copy `clilocs.csv` to the server.
 **Why the fixup is not just done for us:** the parser already handles
 `number,flag,text` — the flag in the *middle*, which is what several exports
 emit. UOFiddler puts it at the *end*, where it is indistinguishable from a name
 that genuinely ends in `;0`. One `sed` on the operator's side beats a parser
 heuristic that would corrupt real names.
 ### Point the site at it
 Two ways, the setting winning over the environment:
 | Where | How |
 |---|---|
 | **Admin → Shard → cliloc path** | Takes effect on the next refresh, no redeploy |
 | `UO_CLIENT_PATH` env var | The deploy-time default |
 The value may be **the file itself or a directory to search** — both are natural
 answers to "where is it", and overlays are picked up either way.
 Setting the path deliberately does **not** import as a side effect. Click
 **Import** (or `POST /api/v1/admin/shard/clilocs/import`) to load it.
 ### Verify
 `GET /api/v1/admin/shard/clilocs`, or the Admin → Shard panel, reports what each
 source contributed:
 ```json
 "sources": [
  { "label": "clilocs.plain", "kind": "base", "entries": 123490, "added": 123490, "overrode": 0 }
 ]
 ```
 Roughly **67,500 rows stored** from a stock table is correct — about half a
 cliloc table is empty strings for ids the client reserves and never uses.
 Then load any character sheet with equipment: items should show names rather than
 `id 1023721`.
 <details>
 <summary>What a refusal means</summary>
 A bad file answers `200` with a `status` and a named reason, not a `500` — you
 need to be told *which file* to fix.
 | `code` | Meaning |
 |---|---|
 | `COMPRESSED` | You pointed at the raw client `Cliloc.enu`. Convert it — this whole page. |
 | `TRUNCATED` | Half-copied file. Re-copy; the loaded table is untouched. |
 | `EMPTY` | A text source with no parseable rows — the file is named in the reason. |
 | `status: needsReview` + `missingSources` | A previously-loaded source has vanished (unmounted volume? deliberate deletion?). Nothing changes until you re-import with `{ "approve": true }`. |
 </details>
 ### Custom items — do *not* re-export for these
 Shard-added items carry ids no client table has. Drop a small delimited file in a
 `custom/` directory beside the base file and re-import:
 ```
 /srv/uo-data/
  clilocs.plain            ← base, from this guide
  custom/
    01-uomysticmoon.tsv    ← your additions and overrides
 ```
 Files are read in sorted order and **later sources win**, so an overlay both adds
 new ids and overrides stock ones you have re-purposed. **Adding one item never
 means re-exporting a 5 MB client file.** Details in [`CLILOCS.md`](CLILOCS.md).
 ---
 ## Part 2 — Creature art for the spawn atlas (optional)
 **Goal:** put sprites on atlas pages. Purely cosmetic — the atlas is fully
 functional as text, and `art` is NULL on every fresh import.
 **This project ships no art and no art-extraction tooling, and never will.**
 1. In `UoFiddler.exe` (paths configured as in Route B step 1), open the
   **Animations** tab for creature sprites — or **Items** for object art — find
   the creature, and export as PNG. Right-click an entry for its export options,
   or use the tab's *Export All* action for a batch. (4.22.2 added an export
   option to the Animation tab's thumbnail list, which is the convenient one
   here.)
 2. Put the images under `server/uploads/atlas/`.
 3. Copy `server/db/data/spawnAtlas.art.example.json` to `spawnAtlas.art.json` in
   the same directory and map creature slugs to file names:
   ```json
   {
     "lizardman": "lizardman.png",
     "orc": "orc.png"
   }
   ```
   **Keys are the slugs the atlas API reports**, derived from the type names in
   your own shard's `Spawns/*.xml` — read them off the atlas rather than guessing.
   A creature with no entry renders without art, which is the default.
 4. Restart, or `npm run atlas:import -- --force`.
 The art map is re-read on every atlas refresh, so adding one image is an edit plus
 a refresh. Both `spawnAtlas.art.json` and `server/uploads/` are gitignored.
 ---
 ## Licensing, briefly
 UO's strings and sprites are EA's. Extracting from **your own** client for
 **your own** shard is the arrangement here; redistributing the extracted files is
 not something this project does or can advise on. That is the whole reason this
 page exists instead of a download link.
Author	SHA1	Message	Date
Colby Whitlock	8322e8318c	Merge pull request 'docs(installer): add release orchestration and the bundle manifest' (#81 ) from docs/installer-release-orchestration into main Reviewed-on: #81	2026-08-01 21:42:33 +00:00
wtclaude	25a5734107	docs(installer): add release orchestration and the bundle manifest The installer needs CI that reacts when a component publishes a release. Adds that as section 7, folded into version tracking because the bundle IS the compat matrix -- which closes the "where does the compat matrix live" gap section 7 previously left open. - 7.1 Bundle manifest: CI publishes an exact, protocol-checked combination of component versions; the installer resolves against it at run time and --bundle <tag> pins one. A link release regenerates JSON and leaves the installer binary untouched, so operators don't re-download the installer for a sidecar patch and the repo doesn't accumulate releases with identical code. Two compose-time gates: sidecar PROTOCOL_VERSION must equal the overlay manifest's declared version, and every asset's SHA256 must match. - 7.2 Triggers: each component's release job POSTs to the installer's workflow-dispatch endpoint (link's release.yml already declares workflow_dispatch and already holds a write:repository token), plus a nightly cron so a missed dispatch self-heals. repository_dispatch avoided -- support is uncertain on this Gitea version. - 7.3 Stale overlay: dispatch, don't wait. Components self-release on merge to their own main, so the release normally already exists. If main is ahead with releasable commits (docs:/chore: correctly cut nothing), fire that repo's workflow, compose from what exists now, warn loudly, and let the nightly fold in the result. Dispatching another repo's workflow is fine -- it still runs its own gates -- but polling it is not, since Gitea's dispatch endpoint returns no run handle. Bundle CI becomes a Phase 0 deliverable, since Phase 1 resolves what to install from the bundle. `update` now moves between checked combinations rather than two independently-latest artifacts. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-01 06:11:08 -05:00
Colby Whitlock	c583ddb77f	Merge pull request 'docs(installer): plan the Runic Gateway installer' (#80 ) from docs/installer-plan into main Reviewed-on: #80	2026-08-01 10:46:13 +00:00
wtclaude	29056ba996	docs(installer): plan the Runic Gateway installer Design of record for a deployment tool that takes a stock ServUO install and configures it for Runic Gateway. Supersedes the informal overview it grew from, which described a ServUO integration that does not match how servuo-plugins actually ships. Corrections that change the design: - There is no RunicGateway.dll and no Plugins/ dir. The plugin ships as C# source compiled by ServUO at boot, so the step is a hash-compare sync of overlay/ -- but a successful copy does not mean a working bridge, because ScriptCompiler.Compile() ignores dotnet build's exit code and reloads the stale Scripts.dll. - Stock ServUO files ARE modified, by three diffs in patches/. Made an opt-in, skippable tier: git apply against a hand-modified shard will fail, and the EventSink.cs patch needs a full core solution rebuild. - Config paths collided with what the sidecar actually reads. Split ownership: sidecar.toml stays the sidecar's schema, install.json is the installer's. Service definitions pin UOLINK_CONFIG and UOLINK_DB_PATH, since the sidecar writes relative to CWD and would land in VirtualStore under Program Files. - The token handoff was missing entirely -- the largest "installed it and nothing happened" failure mode. - deploy.ps1 cannot be the cross-platform deployer; it stays the developer tool. Decisions: public audience, unsigned binaries anchored on SHA256SUMS, Rust, release-tarball plugin distribution, printed token handoff, new installer repo, warn-and-skip on non-57.4 ServUO, and an uninstall that never edits the shard tree -- it prints the files to delete and the hunks to revert. Phases 0-5, with Phase 0 (a release workflow for servuo-plugins, which has none today) gating everything else. Two open questions remain in section 8. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-01 05:44:44 -05:00
Colby Whitlock	186f057bc0	Merge pull request 'docs(tree): sync android/PROJECT_TREE.md' (#79 ) from chore/sync-android-tree into main Reviewed-on: #79	2026-08-01 07:50:46 +00:00
runic-docs-bot	33a013ca98	docs(tree): sync android/PROJECT_TREE.md from RunicGateway/Android-app@5eaf5d2 [skip ci]	2026-08-01 07:22:23 +00:00
Colby Whitlock	5e2bc22a94	Merge pull request 'docs(tree): sync link/PROJECT_TREE.md' (#77 ) from chore/sync-link-tree into main Reviewed-on: #77	2026-08-01 07:21:29 +00:00
Colby Whitlock	04cd64b838	Merge branch 'main' into chore/sync-link-tree	2026-08-01 07:21:09 +00:00
Colby Whitlock	916c11ee92	Merge pull request 'docs(tree): sync website/PROJECT_TREE.md' (#78 ) from chore/sync-website-tree into main Reviewed-on: #78	2026-08-01 07:20:49 +00:00
runic-docs-bot	ea3755760d	docs(tree): sync website/PROJECT_TREE.md from RunicGateway/website@5103b74 [skip ci]	2026-08-01 07:19:52 +00:00
runic-docs-bot	54b3002701	docs(tree): sync link/PROJECT_TREE.md from RunicGateway/link@295defb [skip ci]	2026-08-01 06:50:30 +00:00
Colby Whitlock	9d98109628	Merge pull request 'docs!: Protocol 3.0 cutover — the 3.0 documentation set' (#73 ) from edge into main Reviewed-on: #73 Reviewed-by: Colby Whitlock <whitlocktech@gmail.com>	2026-08-01 06:29:36 +00:00
Colby Whitlock	d0808b766b	Merge branch 'main' into edge	2026-08-01 06:28:21 +00:00
Colby Whitlock	eab0a83f26	Merge pull request 'docs(link): the shard-name fallback, the atlas `places` shape, and two traps' (#76 ) from docs/protocol-3-smoke-findings into edge Reviewed-on: #76	2026-08-01 06:02:59 +00:00
wtclaude	1444c77413	docs(link): the shard-name fallback, the atlas places shape, and two traps Records what the live Protocol 3.0 smoke test (ServUO + sidecar + website + AVD) turned up, so none of it has to be rediscovered. v3.md §5.3 — the ruleset `shard` field now falls back to the instance's own name when the shard publishes ServUO's stock "My Shard", why that is done at ingest rather than on read (the frame is also broadcast live), and why the backfill snapshot must go through the dispatcher instead of writing state directly: a direct call made it a second writer that skipped the normalization. v3.md §7.4 — an unscored board renders a placeholder row rather than a blank card, and why it is deliberately not shaped like a real entry. PLAN.md §9 M11 — `places` is a list of {facet,label,spawners,maxAlive} OBJECTS, not of place-name strings, and typing it `List<String>` makes the whole detail route fail to decode while the request itself returns 200. Adds the rule that came out of it: decode tests must feed real captured JSON, because the fakes build DTOs in Kotlin and can never catch a wire mismatch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP	2026-08-01 00:58:53 -05:00
Colby Whitlock	2e24427032	Merge pull request 'docs(website): an operator runbook for extracting from your own UO client' (#75 ) from docs/operator-uofiddler-guide into edge Reviewed-on: #75	2026-07-30 09:51:31 +00:00
wtclaude	afcdb373ec	docs(website): an operator runbook for extracting from your own UO client CLILOCS.md and SPAWN_ATLAS.md each explain WHY the operator has to supply something out of their own client, but neither says how. UOFIDDLER.md is the missing procedure: where to get UOFiddler, which two files in the zip matter, which runtime it needs, where Cliloc.enu actually lives, the conversion, how to point the site at the result, and how to confirm it took. Verified end to end on a stock Windows box: UOFiddler 4.22.2 (Ultima.dll is net10.0), .NET SDK 9.0.312 building the net8.0 converter, RollForward carrying it onto runtime 10.0.8, and the site's own parser reading the output back. Corrects one claim while doing it. CLILOCS.md said a UOFiddler GUI export "works equally well"; it does not. Its Cliloc tab writes `Number;Text;Flag` -- three columns, flag LAST -- and parseClilocText splits on the first separator only, so the flag is absorbed into the name and every item renders as `quarter staff;0`. The parser already handles `number,flag,text` with the flag in the middle, but a trailing `;0` is indistinguishable from a name that genuinely ends that way, so this stays a documented `sed` on the operator's side rather than a heuristic that would corrupt real names. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-30 03:34:29 -05:00
Colby Whitlock	45fb4a3f15	Merge pull request 'docs(android): scope M11 — Protocol 3.0 shard parity for the app' (#74 ) from docs/android-v3-parity into edge Reviewed-on: #74	2026-07-30 07:23:00 +00:00
wtclaude	5a091157d6	docs(android): scope M11 — Protocol 3.0 shard parity for the app The v3 work added four shard features and an admin-configurable visibility framework the Android client knows nothing about. v3.md §10 deferred the app side as a follow-up; re-examining it before the cutover found the gap is wider than nav hiding: - no consumer for any of ruleset / leaderboards / market / atlas, - no `points` block on the character sheet (§7.3), - no cliloc-resolved item names (§8.6), and - shard nav gated on session role alone, so an admin who disables a feature or raises its audience leaves the app rendering entries that 404/403 into a generic error where the web client hides them. Scoped as PLAN.md §9 M11 in two PRs (the visibility rules + read-model adds, then the four screens), with the traps a real shard exposes recorded inline: uncapped `maxPoints: 0`, cliloc-named boards with a null `nameString`, skill caps in tenths, the required market staleness banner, the market stream being off by default, atlas delays in seconds, and `points`-count vs `spawners`-list. edge → main is held until both land so web and app surface the same shard on the same day. Neither PR is coupled to the merge order — on a pre-v3 website every new route and /public/shard/features 404s and the app falls back to today's behavior — so holding the cutover is a schedule decision, not a technical dependency. Also records two things verified as already correct, so they are not re-derived: the app's SSE request rides the authenticated client (same audience rung as the same account on web), and every shard DTO is nullable-with-defaults (field projection cannot cause a decode failure). Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-30 00:46:16 -05:00
Colby Whitlock	3a1bbdd165	Merge pull request 'docs(link): the Protocol 3.0 cutover (v3.md order 6)' (#72 ) from docs/protocol-3-cutover into edge Reviewed-on: #72	2026-07-30 03:03:10 +00:00
wtclaude	32def88c4e	docs(link): fill in the cutover PR numbers The order-6 row was written before the seven PRs existed. Same follow-up as the cliloc row got. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 18:09:50 -05:00
wtclaude	71207cef16	docs(link): the Protocol 3.0 cutover (v3.md order 6) INTEGRATION.md was written for the window that just closed -- it told integrators the version had NOT been bumped yet and that a sidecar on `edge` reports 2 while already carrying v3 kinds. That guidance is now wrong in the direction that matters, so the version section states 3 (header, /health, ws.hello, the 409 example and the §8 worked example) and replaces the "until then" paragraph with what a v2 integration actually has to do to upgrade: change the constant it sends, and nothing else, because nothing that existed in v2 changed shape. v3.md gains §4.1 for what the bump touches and, more importantly, WHY the website's boot migration is gated on a marker row: schema.sql is re-run on every boot and uo_link_config.protocol is admin-editable, so an ungated UPDATE would silently un-pin an operator running an older sidecar. That is the one piece of the cutover a reader could not infer from the code being one constant. Progress tables: 5b done, 6 in review. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 18:04:00 -05:00
Colby Whitlock	06b4a06baa	Merge pull request 'docs(tree): sync website/PROJECT_TREE.md' (#59 ) from chore/sync-website-tree into main Reviewed-on: #59	2026-07-28 15:02:41 +00:00
runic-docs-bot	f2fa6abff7	docs(tree): sync website/PROJECT_TREE.md from RunicGateway/website@a3407ae [skip ci]	2026-07-28 06:12:43 +00:00