Merge pull request 'docs(modules): phase 7b as built — configuration from the site, and the undo that makes it safe' (#260) from docs/rust-phase-7b into main

Reviewed-on: #260

README.md

@@ -10,6 +10,7 @@ so they live in one place, independent of either codebase.
 website/    docs from the website core (Node/Express + MariaDB + React/Vite)
 modules/    docs for installable game modules — one directory per module id
 link/       docs from the ServUO bridge (C# plugin + Rust sidecar + Node WS)
+rust-link/  docs from the Rust bridge (Oxide plugin + Rust sidecar)
 android/    docs from the native Android client (Kotlin + Jetpack Compose)
 installer/  docs for the installer that deploys a shard's bridge components
 ci/         cross-cutting CI/quality notes
@@ -76,6 +77,18 @@ particular game; a module is what makes it a site *for* one.
 | [link-README.md](link/link-README.md) | Snapshot of the link repo's README |
 | [PROJECT_TREE.md](link/PROJECT_TREE.md) | Auto-generated snapshot of the repo's tracked file layout |
 
+### `rust-link/`
+
+The same pair of contracts as `link/`, for Rust rather than Ultima Online: an Oxide plugin that
+dials out to a sidecar, and a sidecar the website reads. The two bridges are **independent** — they
+share a shape and nothing else, so neither document is a fallback for the other.
+
+| Doc | What it covers |
+|---|---|
+| [PROTOCOL.md](rust-link/PROTOCOL.md) | **Canonical** — the game link and the website API, the four declaration sites of the wire version, and what each protocol version defines: 1 the transport, 2 the read path |
+| [INTEGRATION.md](rust-link/INTEGRATION.md) | Standing the bridge up by hand, and which of the three components is wrong when it does not work |
+| [PLAYER_WALK.md](rust-link/PLAYER_WALK.md) | The half of the read path a console cannot reach: ten minutes on a rig with a player, step by step, with what each hook should produce |
+
 ### `android/`
 | Doc | What it covers |
 |---|---|

android/PLAN.md

@@ -1307,6 +1307,128 @@ push, and Play (M6–M8) follow the designed app.
     an inbox event link opening the app natively while a forum link still opened a Custom Tab; and
     participation history self-scoped, proved by two accounts rather than asserted.
 
+15. **M14 — the Rust module in the app** (post-v1; built 2026-09-17). The platform's **second game
+    module** reached its first public pages in `module-rust` phase 4
+    ([`../modules/rust/PLAN.md`](../modules/rust/PLAN.md) §17), and this is phase 5 — the app's leg.
+    R10 has each Android leg trail the website surface it consumes by exactly one phase, so every
+    route here existed and answered before a line of Kotlin was written.
+
+    **Design of record: [`../modules/rust/PLAN.md`](../modules/rust/PLAN.md)**, §17 for the surface
+    this mirrors and §18 for this phase as built. The contract is normative there; this entry records
+    what the app does about it.
+
+    **No backend work beyond one word.** The five public routes were live. The one change is
+    Module-Rust#5, which adds `rust` to the module's `capabilities` — see the gate below.
+
+    #### Why this is not the shard screens with a different name
+
+    The two games have genuinely different shapes, and collapsing them would have cost the app the
+    thing that makes each legible. **UO is one shard: a place**, five drawer rows, a live SSE stream.
+    **Rust is a fleet**: a list, and one page beneath it with four tabs. The app grows a second route
+    tree rather than a second meaning for `shard/`, and both can be installed on one backend — in
+    which case both trees exist at once and neither row appears on a site without its module.
+
+    | Screen | Route | Reads |
+    | --- | --- | --- |
+    | **Rust servers** (the list) | `rust` | `GET /public/rust/servers` |
+    | **One server** (four tabs) | `rust/servers/{serverId}` | `…/:id`, `…/:id/events`, `…/leaderboard`, `…/online`, `…/wipes` |
+
+    #### Four decisions, taken by the org lead on 2026-09-16
+
+    - **D16 — the gate is a new capability, `rust`.** `module-uo`'s five shard rows all hang on one
+      string, `shard`, because that is the only question a capability can answer: *is the module
+      there*. `module-rust` declared five and every one named a **surface** — `servers`, `killfeed`,
+      `leaderboard`, `presence`, `wipes`. Core flattens every started module's capabilities into a
+      single list, so gating on `servers` would let another module declaring that word silently reveal
+      these screens on a site that does not run Rust. Gating on the module **id** was considered and
+      rejected: `id` is a mount prefix (§2.1 requires it to equal the directory core loads from), and
+      `MODULE_API.md` §2.9 forbids a client inferring a route from a capability — making the two the
+      same thing would quietly end that separation. So the module declares its own name as a sixth
+      string, asserted in its suite against `module.json`'s own `id` so the two cannot drift.
+    - **D17 — poll every 20s while the screen is RESUMED**, the phone's version of D14's Page
+      Visibility gate. Immediate refresh on return to the foreground; nothing at all while away.
+    - **D18 — the Rust repositories move to `edge`** for the rest of the workstream, with releases at
+      the cutover rather than per phase. `pr-checks.yml` in all four repositories already triggers on
+      `[main, edge]`, so this costs no CI — the trap that made all nine M12 phase PRs land unchecked
+      was closed in engagement Phase 8.
+    - **D19 — the drawer row carries a live player count**, and NavPaths learns `/rust`.
+
+    #### A refresh is not a load, and the app had only ever done loads
+
+    The app has had exactly one shape for a read since M1: set `Loading`, ask, replace. That is right
+    for opening a screen and wrong for a poll — a twenty-second refresh built on it clears the
+    killfeed, renders a spinner in its place and re-fills it, three times a minute, for ever. **The
+    website hit the same wall one tier along**, which is why `module-rust` bundles its own `usePolled`
+    instead of using core's `useAsync` (§17.3). `ui/Polling.kt` is that hook's other half:
+
+    - `refreshInto` — **a refresh is invisible when it succeeds and keeps the rows when it fails.** A
+      failure with rows on screen keeps them and reports the failure beside them; a failure with
+      nothing on screen is an ordinary error with a retry, because there is nothing to protect.
+    - `PollWhileResumed` — `repeatOnLifecycle(RESUMED)`, which buys three behaviours from one line: no
+      requests at all while backgrounded, an immediate refresh on return, and a pause behind a dialog
+      or the recents switcher. `STARTED` would keep polling for a reader who is not reading.
+
+    Only the **visible** live panel is polled. The leaderboard and the wipe list never are: a
+    leaderboard that re-sorted itself under a finger every twenty seconds would be worse than a stale
+    one. Changing the filter, the sort or the wipe **is** a different question, so that panel blanks
+    and loads — leaving the old rows up would show last wipe's killfeed under this wipe's heading.
+
+    #### The drawer badge is D15 translated, not D15 copied
+
+    D15 put a live count in core's `site.footer.status` slot, which works because every page of the
+    website renders the same footer. The app has no footer and no slot. What it has is a drawer row
+    per surface and, since engagement Phase 8, a precedent for a number beside one — the inbox's
+    unread badge, in the `NavigationDrawerItem` badge slot, with a `contentDescription` so a screen
+    reader says "42 players online" rather than "42". The count rides there, and keeps the website
+    version's three rules: **zero renders nothing** (an empty fleet is not a notification), a failed
+    read keeps the last number, and it never polls. It is asked for only where the module is
+    installed, so a UO site makes no request at all.
+
+    #### Verified
+
+    The app suite (**644 tests, 0 failures**), `lintDebug`, `assembleDebug`, and an emulator walk
+    against the phase-4 rig — a core with the module installed, one live server and one seeded fixture
+    that has never reported.
+
+    **Both halves of the phase criterion, directly.** With its server unreachable and reading
+    *Offline*, the page still rendered its map, size, seed, wipe date, killfeed, per-wipe and all-time
+    leaderboards, its last known presence board and its wipe history. The same app pointed at the UO
+    core showed Shard / Rules / Atlas / Leaderboards / Market and **no Rust row**.
+
+    Also proven rather than asserted: `refreshInto` against a genuinely dead backend (the core was
+    stopped with the list on screen; a poll tick later the rows were unchanged under one quiet line);
+    R12's arithmetic on a phone (all-time 59 = 41 + 18, and a player who appears only in the older
+    wipe **drops out** of it rather than reading zero); every `describe` branch from real rows,
+    including the fall that must not read as a kill by nobody; the calendar-day rule, filtering to the
+    August wipe and getting three rows six weeks old, each unmistakably dated; and the badge.
+
+    #### The walk found three defects, and 644 green tests found none of them
+
+    - **The drawer's live count resolved once per process.** It was keyed on the capability answer
+      alone, so it was read at connect and never again — which is not what *live* means on a row
+      somebody opens the drawer to look at. It now refreshes on resume, beside the unread badge.
+    - **Every card's text sat flush against its edge.** `ShardCard` is the themed `Card` and carries
+      no padding of its own; each caller pads its own content, and these four did not. On a phone the
+      first glyph of each line read as clipped.
+    - **A name touched its own kill count.** Five numeric columns beside an equal-weight name column
+      left *Brannock* and *50* reading as one field. The name now takes a wider share and ellipsizes,
+      and the **active sort is marked on the header** rather than by tinting a column of numbers — the
+      header is the control, and tinting the values says *these are special* instead of *this is what
+      the table is ordered by*.
+
+    #### The rig note worth keeping
+
+    The debug `network_security_config.xml` permits cleartext to **`127.0.0.1` and `localhost` only**
+    — not `10.0.2.2`. An emulator walk against a local core therefore needs
+    `adb reverse tcp:<port> tcp:<port>` and the loopback address; typed as `10.0.2.2` every request
+    fails with `UnknownServiceException: CLEARTEXT communication to 10.0.2.2 not permitted`, which the
+    connect screen reports — correctly, and indistinguishably from a core that is not running.
+
+    - **Excluded**, in the same class as every earlier milestone's exclusions: the Rust **admin**
+      surface. Server configuration, the sidecar token and the connection test are admin
+      *configuration*, which the app consumes and does not edit. Identity and permissions are legs B
+      and C (phases 8 and 11), and the map is leg D.
+
 ### Deferred (not a milestone)
 
 - **Platform Teams in the app** — **deferred 2026-08-17, no app work scheduled.** The website is

modules/rust/CARBON.md

@@ -0,0 +1,378 @@
+# Carbon — the second modding framework, and where it differs from Oxide
+
+**Carbon** is the other framework modded Rust servers run. It is not a fork of Oxide and it does not
+load Oxide; it is a separate loader that ships an **Oxide compatibility layer** — the `Oxide.Core`,
+`Oxide.Plugins` and `Oxide.Game.Rust` namespaces, reimplemented — so that a plugin written for Oxide
+compiles and runs unchanged.
+
+This document exists because [`PLAN.md`](PLAN.md) **R19** commits `module-rust` to supporting both.
+It records the places the two frameworks are *not* the same, because those are the only places our
+code has to care. Everything not listed here is identical by construction.
+
+> **Provenance.** Facts below were taken on **2026-09-15** from Carbon's own published metadata —
+> `api.carbonmod.gg/meta/carbon/{hooks,commands,convars,switches}.json` — and from the
+> [`CarbonCommunity/Carbon`](https://github.com/CarbonCommunity/Carbon) source at `main`, with the
+> narrative pages at [carbonmod.gg](https://carbonmod.gg) as the prose source. Carbon is upstream
+> and wins any disagreement, exactly as uMod does for [`OXIDE_API.md`](OXIDE_API.md). Nothing here
+> is a Runic Gateway contract.
+>
+> **Verified on a live Carbon server on 2026-09-15** — Carbon **2.0.259.0** `[2026.09.03.0]` on
+> Linux, the `rust-carbon` rig (PLAN.md §14.5). Three of the four load-bearing claims held. **One was
+> wrong, and it was wrong about Oxide as well as Carbon** — see §4. Corrected in place; §10 is the
+> scorecard.
+
+---
+
+## 1. The one-sentence version
+
+**A plugin in the `Oxide.Plugins` namespace deriving from `RustPlugin` is Carbon's own documented
+first example**, so the bridge plugin is one `.cs` file that serves both frameworks. What diverges is
+not the plugin API but **the things around it**: where files live, how the permission store is
+persisted, what the console commands are called, and which extra hooks exist.
+
+```csharp
+// Carbon's own "first plugin" page shows this, unchanged from Oxide:
+namespace Oxide.Plugins;
+
+[Info("MyPlugin", "<author>", "1.0.0")]
+public class MyPlugin : RustPlugin
+{
+    private void OnServerInitialized() => Puts("Hello world!");
+}
+```
+
+Carbon also offers a native shape — `namespace Carbon.Plugins` / `CarbonPlugin` — which we do not
+use and should not: it is the one choice that would make the source Carbon-only.
+
+---
+
+## 2. Telling the two apart
+
+### At compile time — `#if CARBON`
+
+Carbon feeds the Roslyn compiler a set of conditional-compilation symbols. **Oxide defines no
+equivalent**, so `#if CARBON` / `#if !CARBON` is the portable framework branch, and an Oxide
+compiler simply evaluates the unknown symbol as false.
+
+| Symbol | Meaning |
+|---|---|
+| `CARBON` | The framework is Carbon |
+| `RUST` | The game is Rust |
+| `OXIDE_PUBLICIZED` | Compiled against publicised Oxide assemblies |
+| `WIN`, `UNIX` | Host operating system |
+| `STAGING`, `AUX01`, `AUX02` | Rust branch |
+| `RUST_ABV_<v>`, `RUST_BLW_<v>`, `RUST_IS_<v>` | Rust protocol above / below / exactly `<v>` |
+| `CARBON_ABV_<YYYY_MM_DD>` | Carbon protocol above a date |
+
+This works because the bridge plugin ships as **source** and is compiled by whichever framework
+loaded it. It would not work for a precompiled DLL — a reason, among others, not to ship one.
+
+**Confirmed on the live rig**: `carbon/config.json` reports
+`"ConditionalCompilationSymbols": ["CARBON", "RUST", "OXIDE_PUBLICIZED"]`, and the list is an
+operator-editable setting (`c.addconditional` adds to it), so treat the three above as the ones
+present by default rather than the ones guaranteed.
+
+### At run time
+
+`#if` is decided when the file is compiled, which is what we want for API differences. Where a
+*runtime* answer is needed — reporting which framework a server runs, in a `server.hello` say — ask
+for the type rather than the file layout: `Carbon.Community` exists only under Carbon.
+
+---
+
+## 3. Where the files live — **the divergence that reaches the most decisions**
+
+| Oxide | Carbon |
+|---|---|
+| `oxide/plugins/` | `carbon/plugins/` |
+| `oxide/config/` | `carbon/configs/` — **plural** |
+| `oxide/data/` | `carbon/data/` |
+| `oxide/lang/` | `carbon/lang/` |
+| `oxide/logs/` | `carbon/logs/` |
+| `oxide/extensions/`, plus `Oxide.Ext.*.dll` in `RustDedicated_Data/Managed` | `carbon/extensions/` only |
+| — | `carbon/modules/`, `carbon/harmony/`, `carbon/developer/` |
+
+**And none of those paths is fixed.** Carbon takes a command-line override for every single
+directory — `-carbon.rootdir`, `-carbon.configdir`, `-carbon.datadir`, `-carbon.scriptdir`,
+`-carbon.langdir`, `-carbon.logdir`, `-carbon.extdir`, `-carbon.moduledir`, `-carbon.modifierdir`,
+`-carbon.profiledir`, `-carbon.carbonconfigdir`, `-carbon.sqlpermsdb`, `-harmonydir`. An operator
+who has moved one is not doing anything unsupported.
+
+**So the rule is: never compose a config or data path.** Carbon reimplements Oxide's own directory
+accessors and populates them from its resolver:
+
+```csharp
+Interface.Oxide.ConfigDirectory   // oxide/config   or  carbon/configs  or wherever -carbon.configdir points
+Interface.Oxide.DataDirectory
+Interface.Oxide.PluginDirectory
+Interface.Oxide.LangDirectory
+Interface.Oxide.LogDirectory
+Interface.Oxide.ExtensionDirectory
+Interface.Oxide.RootDirectory
+Interface.Oxide.InstanceDirectory
+```
+
+(`Carbon.Common/src/Oxide/OxideMod.cs` assigns each from `Defines.Get*Folder()`; `Interface.cs`
+logs all eight at boot.) Asking the framework is both shorter and correct; hardcoding `oxide/config`
+is wrong on Carbon and wrong on an Oxide server whose operator moved things.
+
+**This is a direct amendment to R18.** The config editor's recursive walk is rooted at
+`ConfigDirectory`, not at a literal `oxide/config/`; the directory it must refuse to walk is
+`DataDirectory`, not a literal `oxide/data/`. The reasoning behind R18 is untouched — only the way
+the two roots are obtained.
+
+---
+
+## 4. Permissions — same API, same format, different directory
+
+Every member R2 depends on exists with the same name and the same argument shape
+(`Carbon.Common/src/Oxide/Libraries/Permissions.cs`): `RegisterPermission`, `PermissionExists`,
+`GrantUserPermission`, `RevokeUserPermission`, `GrantGroupPermission`, `RevokeGroupPermission`,
+`CreateGroup`, `RemoveGroup`, `AddUserGroup`, `RemoveUserGroup`, `UserHasPermission`,
+`GroupHasPermission`, `GetUserGroups`, `GetUserPermissions`, `GetGroupPermissions`,
+`GetPermissionUsers`, `GetPermissionGroups`, `GetGroups`, `GetUsersInGroup`, `SetGroupParent`.
+
+Two differences, and they pull in opposite directions.
+
+**All of the member names above were confirmed present on the live Carbon rig**, which loaded and ran
+our plugin against them unchanged.
+
+**The return type differs, and the portable answer is the one we already chose.** Carbon's
+`GrantUserPermission` returns `bool`; Oxide's returns `void` — which is
+[§12.2](PLAN.md#122-four-rules-the-r2-permission-push-must-obey)'s finding, that a grant naming an
+unregistered permission silently does nothing. Calling it as a statement compiles on both, so the
+source stays single. But **the bool cannot be read portably**, so the `PermissionExists` pre-check
+stays the mechanism on both frameworks rather than being replaced by a return value on one. Carbon
+is the framework that *would* have told us, and we still cannot listen.
+
+Carbon's signature also takes `BaseHookable` where Oxide's takes `Plugin`. Passing `this` is
+correct on both; a variable typed `Plugin` is not.
+
+### The store — **this section was wrong, and the truth is worse**
+
+> **Corrected 2026-09-15 against both live rigs.** This document previously said *"Oxide persists to
+> JSON; Carbon persists to Protobuf or SQLite"*, and offered that difference as the reason not to read
+> the file. **Both halves were wrong.** The real shape is more dangerous than the one that was
+> imagined, which is the only reason it is worth the space.
+
+Read off the two running servers, byte for byte:
+
+| | Oxide rig | Carbon rig |
+|---|---|---|
+| Path | `oxide/data/oxide.users.data`, `oxide.groups.data` | `carbon/data/oxide.users.data`, `oxide.groups.data` |
+| First bytes | `0a 16 0a 07 64 65 66 61 75 6c 74 …` | `0a 17 0a 07 64 65 66 61 75 6c 74 …` |
+| Format | **Protobuf** | **Protobuf** |
+| Default groups | `default`, `admin` | `default`, `admin`, **`moderator`** |
+
+**Neither framework writes JSON, and Carbon writes Carbon's data into files named after Oxide.** So
+the trap is not "two formats you must tell apart". It is:
+
+1. **The filename is identical and tells you nothing**, so a reader keyed on `oxide.users.data`
+   silently follows the wrong framework's file if it ever guesses the directory wrong.
+2. **The format is an undocumented binary**, not the JSON the name and the `.data` extension suggest.
+3. **Carbon can change it out from under you at run time** and Oxide cannot. `PermissionSerialization`
+   in `carbon/config.json` defaults to `0` (the Protobuf above); `c.migrate_perms_sql` moves the whole
+   store to SQLite at `server/identity/carbon.perms.db`, itself relocatable via `-carbon.sqlpermsdb`.
+   `Oxide Overrides/PermissionSql.cs` and `PermissionStoreless.cs` are those backends.
+
+**R2's conclusion is unchanged and the argument for it is now much stronger.** A file reader would
+have *worked* on both rigs today — same format, same names — and would break for the one operator
+who ran a migrate command, with no error and no version marker to notice. **Drift detection reads the
+API, or it does not work.**
+
+**One more thing R2 has to accommodate: Carbon creates a third default group.** `carbon/config.json`
+names `PlayerDefaultGroup`, `AdminDefaultGroup` and `ModeratorDefaultGroup`, all auto-granted by auth
+level (`AutoGrantPlayerGroup` / `AutoGrantAdminGroup` / `AutoGrantModeratorGroup`, all `true`). A
+site that pushes its *full* group set on connect must not treat `moderator` as drift to be reported,
+nor delete it — the framework will simply recreate it, and the site will report drift for ever.
+
+**Carbon does give R2 something Oxide's docs do not advertise: fourteen permission hooks**, a
+`Permissions` category of its own — `OnUserPermissionGranted`, `OnUserPermissionRevoked`,
+`OnUserGroupAdded`, `OnUserGroupRemoved`, `OnGroupCreated`, `OnGroupDeleted`, `OnGroupParentSet`,
+`OnGroupRankSet`, `OnGroupTitleSet`, `OnGroupPermissionGranted`, `OnGroupPermissionRevoked`,
+`OnPermissionRegistered`, `OnPermissionsUnregistered`, `OnUserNameUpdated`. Our uMod mirror carries
+most of these as universal hooks too, so drift may be **observable as it happens** on both rather
+than only diffable on connect. Phase 7 should test that rather than assume it; a hook that fires on
+our *own* push is a feedback loop to suppress, not a bonus.
+
+---
+
+## 5. Console commands — `c.` not `oxide.`
+
+Carbon's 129 published commands are `c.`-prefixed. The ones with Oxide counterparts:
+
+| Oxide | Carbon |
+|---|---|
+| `oxide.grant` / `oxide.revoke` | `c.grant` / `c.revoke` |
+| `oxide.group` | `c.group` |
+| `oxide.usergroup` | `c.usergroup` |
+| `oxide.load` / `oxide.unload` / `oxide.reload` | `c.load` / `c.unload` / `c.reload` |
+| `oxide.plugins` | `c.plugins` |
+
+Carbon can be configured to alias the old prefix, so an operator's muscle memory survives — but an
+alias is opt-in and **we must never depend on one**. **Confirmed on the live rig:** `c.version`,
+`c.plugins`, `c.grant` and `c.group` all answered; **`oxide.plugins` produced no output at all**. Note
+the shape of that failure — Pterodactyl's `command` endpoint returns `204` either way, and Carbon
+prints nothing for an unknown command, so *a wrong prefix looks exactly like a command that worked.*
+
+`c.plugins` is also worth knowing about for a reason unrelated to permissions: **it reports per-plugin
+`hook fires`, `hook time`, `hook memory`, `hook lag` and `hook exceptions`**, which is most of the
+"log which of its expected hooks have fired at least once" mechanism [`PLAN.md`](PLAN.md) §6 requires
+— for free, and only on Carbon. Useful when debugging *on* Carbon; **not a substitute for the
+plugin's own counter**, which has to work on both. Our plugin appears there as
+`Runic Gateway  RunicGateway  v0.1.0 … 2367ms [1077ms]`, under `Scripts`, with `failed plugins (0)`.
+
+**Where this reaches us is narrow but real.** R2 and R18 both act through the plugin API, not the
+console, so neither cares. The two that do care are **documentation** — every operator-facing
+instruction naming `oxide.grant` needs its Carbon line — and **any place we drive a reload by
+console string**, which R18's write path does. Resolve the reload through the framework rather than
+by composing a command, or branch it on `#if CARBON`.
+
+---
+
+## 6. Hooks — Carbon is a superset, with thirteen names it does not list
+
+Carbon publishes **894 hook entries, 774 unique names, in 42 categories**, against the **476** on
+uMod's Rust hooks page that [`HOOKS.md`](HOOKS.md) mirrors. The larger number is not more game
+coverage; Carbon documents patched methods our mirror's audience never sees.
+
+Carbon flags every entry for compatibility. **30 are Carbon-only. Zero are marked Oxide-only.**
+
+### The 30 Carbon-only hooks
+
+| Hook | Category | What it is |
+|---|---|---|
+| `CanAcceptBackpackItem` | Global | Whether to accept a backpack item |
+| `CanPatrolHeliSeePlayer` | Global | Patrol-helicopter line of sight to a player |
+| `CanPickupAllFromRack` | Global | Taking every weapon from a rack |
+| `CanPickupFromRack` | Global | Taking one weapon from a rack |
+| `CanPlaceOnRack` | Global | Placing on a rack |
+| `OnPickupFromRack` | Global | Controls taking items from a rack |
+| `CanPlayerInheritNetworkGroup` | Global | Network-group inheritance |
+| `OnChairComfort` | Global | Chair comfort |
+| `OnChickenScared` | Global | A chicken is scared |
+| `OnGrowableUpdate` | Global | A growable updates |
+| `OnConsoleCommand` | Global | A console command is executed |
+| `OnNativeCommandHasPermission` | Global | Permission check on a native console command |
+| `OnEntitySpawn` | Global | An entity spawns — **not** Oxide's `OnEntitySpawned`, which exists on both |
+| `OnJackieChan` | Global | Undescribed upstream |
+| `OnCarbonBanPlayer`, `OnCarbonUnbanPlayer`, `OnCarbonKickPlayer`, `OnCarbonMutePlayer` | Player | Carbon admin-module moderation actions |
+| `OnCarbonBlinded`, `OnCarbonUnblinded`, `OnCarbonSpectateStart`, `OnCarbonSpectateEnd` | Player | Carbon admin-module spectate and blind actions |
+| `OnCarbonPrivateMessage`, `OnCarbonEmpowerPlayerStats`, `OnCarbonLockPlayerContainer` | Player | Carbon admin-module player actions |
+| `OnCompilationFail`, `OnConstructorFail` | Engine | Plugin compile / constructor failure |
+| `OnPluginCompileFailure`, `OnPluginOutdated` | Plugin | Plugin lifecycle |
+| `OnMarketplaceTerminalPurchase` | Vending | Marketplace terminal purchase |
+
+**None of them is load-bearing for us and none should become so.** The `OnCarbon*` family is the
+Carbon admin module's own audit trail — tempting for a staff-actions feed, and exactly the kind of
+convenience that quietly makes Carbon the required framework. If we ever want that feed, it has to
+have an Oxide answer first.
+
+### The 13 uMod names Carbon's catalogue does not carry
+
+| Hook | Category | uMod's description |
+|---|---|---|
+| `CanNpcAttack` | Entity | An NPC attempts to attack another entity |
+| `CanPushBoat` | Player | Cancelling a boat push |
+| `CanUnlockTechTreeNode` | TechTree | Unlocking a blueprint in a tech tree |
+| `CanUnlockTechTreeNodePath` | TechTree | …after the path check |
+| `OnFrame` | Server | Each frame |
+| `OnHelicopterKilled` | Entity | A CH47 is going to be killed |
+| `OnNpcDestinationSet` | Entity | Cancelling an NPC destination change |
+| `OnNpcPlayerResume` | Entity | Cancelling `TryForceToNavmesh` |
+| `OnNpcStopMoving` | Entity | Denying an NPC move stop |
+| `OnPlayerCorpse` | Player | A non-null corpse has spawned |
+| `OnQuarryEnabled` | Resource | A mining quarry is turned on |
+| `OnTeamInvite` | Team | Cancelling a team invitation |
+| `OnTeamPromote` | Team | Cancelling a promotion |
+
+**Absent from a catalogue is not the same as absent from the framework**, and two of these look like
+renames rather than holes: Carbon lists `OnTeamMemberInvite` and `OnTeamMemberPromote` in its `Team`
+category, which is `OnTeamInvite` and `OnTeamPromote` under different names. Carbon's `Team`
+category also carries visible duplicates and both tenses of the same event (`OnTeamCreate` *and*
+`OnTeamCreated`, `OnTeamUpdate` *and* `OnTeamUpdated`, `OnTeamMemberInvite` twice), which says the
+catalogue is generated rather than curated.
+
+So this table is **a list of things to check on a live Carbon server**, not a list of losses. The
+practical protection is one we already committed to in [`PLAN.md`](PLAN.md) §6: *hooks bind by name
+and arity through reflection with no compile-time check*, so the plugin logs which of its expected
+hooks have fired at least once. That mechanism was written for Facepunch renaming a hook on wipe
+day; it answers this question too, on either framework, without us having to trust either catalogue.
+
+**None of the 13 is currently in a phase.** R5 settled Teams on Rust's **first-party clans**, not
+first-party Teams, so `OnTeamInvite`/`OnTeamPromote` are outside the plan as written.
+
+---
+
+## 7. Convars — a Carbon-only set exists, and leases must not reach for it
+
+Carbon publishes 23 convars of its own, several of them precisely the kind of live, gameplay-shaped
+value [`PLAN.md`](PLAN.md) §9 wants to lease — `c.recycletickmultiplier`,
+`c.safezonerecycletickmultiplier`, `c.researchdurationmultiplier` and so on, most flagged
+`ForceModded`.
+
+**A lease over one of those would work on Carbon and be undeclarable on Oxide.** Lease keys are
+advertised to the event authoring form, and a key that silently does not exist on half of installs
+is the failure `EVENTS.md` §H's *verify every key live* rule exists to prevent. So: **the lease
+catalogue is drawn from the game's own convars, which both frameworks expose identically.** If a
+Carbon-only key is ever worth the cost, it is advertised conditionally on the connected server's
+framework, and that is a deliberate decision rather than an oversight.
+
+---
+
+## 8. Operating differences that reach deployment
+
+- **They cannot coexist.** Oxide ships a patched `Assembly-CSharp.dll`; Carbon requires
+  Facepunch's vanilla one and patches in memory through Harmony. One install runs one framework, so
+  **one rig cannot prove both** — which is why [`PLAN.md`](PLAN.md) R21 moves the rigs to
+  Pterodactyl and runs two.
+- **Carbon migrates an Oxide install on first boot** — it copies config, data, lang, user and group
+  files across and relocates `Oxide.Ext.*.dll` out of `RustDedicated_Data/Managed`. Useful for an
+  operator; a hazard for a test rig, because a Carbon rig built by converting an Oxide one starts
+  with the Oxide one's state and proves less than a clean install.
+- **Carbon self-updates and its releases are rolling tags**, not versioned ones:
+  `production_build` (v2.0.259 at the time of writing, 2026-09-06), plus `edge_build`,
+  `experimental_build` and per-branch Rust builds. Oxide publishes an incrementing build number.
+  **So "which Carbon is this" is not answerable the way "which Oxide is this" is**, and R4's
+  `doctor` prerequisite check has to accept that — it can establish *that* Carbon is installed and
+  report the build it reports, but "current enough" is a weaker claim on Carbon than on Oxide.
+- **Carbon patches hooks only when a plugin subscribes**, so an unsubscribed hook costs nothing.
+  That rewards the selective subscription R17 already requires for ZoneManager's chatty zone
+  transitions, on Carbon more than on Oxide.
+
+---
+
+## 9. What this costs us, in one table
+
+| Decision | Change |
+|---|---|
+| **R2** permissions | None to the design. The store is API-only on Carbon *by construction* rather than by choice, and `PermissionExists` stays the check because the useful return value is Carbon-only |
+| **R4** installer | `doctor` detects *which* framework, not *whether Oxide*; the payload drops into `PluginDirectory`; "current enough" is weaker on Carbon (rolling tags) |
+| **R18** config editor | Roots come from `Interface.Oxide.ConfigDirectory` / `DataDirectory`, never literals; the reload is resolved through the framework, not by composing `oxide.reload` |
+| **R6/R17** base mods | Unchanged — Kits, Clans, PopupNotifications and ZoneManager are Oxide plugins and Oxide plugins run on Carbon |
+| **§9** event leases | Keys come from the game's convars; Carbon's own convars are out of the catalogue unless advertised conditionally |
+| Everything else | Unchanged |
+
+The honest summary: **Carbon costs three amendments and one extra rig, not a second codebase.**
+
+---
+
+## 10. Scorecard — what the live rig confirmed and what it corrected
+
+Run 2026-09-15 against `rust-carbon` (Carbon **2.0.259.0** `[2026.09.03.0]` `21063e8`, Linux,
+`production_build`, Rust 103/2633.288.1), with the Oxide rig alongside for comparison.
+
+| Claim | Verdict | Evidence |
+|---|---|---|
+| An `Oxide.Plugins` / `RustPlugin` source file loads unchanged | **CONFIRMED** | The byte-identical `RunicGateway.cs` that runs on the Oxide rig loaded as `Runic Gateway v0.1.0` in `2367ms`, printed the same startup line, and retried the absent sidecar the same way |
+| The framework root is `carbon/`, config dir is `configs` (plural) | **CONFIRMED** | `/carbon/{configs,data,lang,logs,plugins,extensions,modules,managed,native,modifiers,temp,tools}`; **no `/oxide` directory at all** |
+| `Interface.Oxide.ConfigDirectory` resolves there | **CONFIRMED, indirectly and decisively** | The plugin's own config was written to **`/carbon/configs/RunicGateway.json`** by the same code that writes `/oxide/config/RunicGateway.json` on the Oxide rig. A literal path in R18 would not have found it |
+| Console prefix is `c.`, `oxide.` is not aliased | **CONFIRMED** | `c.version` / `c.plugins` / `c.grant` / `c.group` answered; `oxide.plugins` produced nothing |
+| `#if CARBON` is defined | **CONFIRMED** | `carbon/config.json` → `ConditionalCompilationSymbols: ["CARBON", "RUST", "OXIDE_PUBLICIZED"]` — and two symbols this document had not known about |
+| Carbon self-updates | **CONFIRMED** | `SelfUpdating.Enabled: true`, plus the egg refetching `production_build` every boot |
+| *"Oxide stores JSON, Carbon stores Protobuf or SQLite"* | **WRONG — see §4** | **Both** store Protobuf, under **identical filenames**, differing only in directory. The refutation strengthens R2 rather than weakening it |
+| The 13 uMod hook names missing from Carbon's catalogue | **NOT YET TESTED** | None is in a phase; the plugin's own fired-hook log is the standing answer either way |
+
+**Two things this document did not know to claim**, both found by looking rather than reading:
+Carbon ships a **third default group** (`moderator`) that R2's push must tolerate, and `c.plugins`
+exposes per-plugin hook telemetry Oxide has no equivalent for.

modules/rust/README.md

@@ -1,10 +1,13 @@
-# Rust — the Oxide/uMod ecosystem reference
+# Rust — the modding-framework reference
 
-Reference material for the **upcoming `module-rust`**: a mirror of the uMod/Oxide documentation —
-the Rust game API *and* the game-independent plugin framework around it — captured here so the
-module can be designed and built against it without a round trip to umod.org on every question.
+Reference material for **`module-rust`**: a mirror of the uMod/Oxide documentation — the Rust game
+API *and* the game-independent plugin framework around it — captured here so the module can be
+designed and built against it without a round trip to umod.org on every question.
 
-Everything below was **scraped verbatim from uMod on 2026-09-15**.
+The mirrored material was **scraped verbatim from uMod on 2026-09-15**. One file,
+[`CARBON.md`](CARBON.md), covers the *other* framework modded Rust servers run: PLAN.md **R19**
+commits this module to supporting Oxide and Carbon both, and that file records only where the two
+differ.
 
 ## The mirror
 
@@ -15,6 +18,7 @@ Everything below was **scraped verbatim from uMod on 2026-09-15**.
 | [`DEFINITIONS.md`](DEFINITIONS.md) | **What things are called.** 678 items (short name, id, display name) and 2,590 workshop skin ids across 104 items. |
 | [`OPERATING.md`](OPERATING.md) | **How it gets run.** The 6 operator pages — installing Oxide on a server, then installing, configuring and permissioning plugins. |
 | [`agent/`](agent/README.md) | The same facts in **machine shape** — TSV and JSONL, ~46% of the tokens. Generated in the same pass, so it cannot drift. |
+| [`CARBON.md`](CARBON.md) | **The other framework.** Where Carbon diverges from Oxide and nowhere else — file layout, the permission store, the `c.` commands, 30 Carbon-only hooks and 13 uMod names its catalogue omits. Sourced from Carbon's own metadata and source, and **proven on a live Carbon 2.0.259.0 server** — R19 at phase 0, and the whole read path at phase 3. |
 
 **The one file here that is ours:** [`PLAN.md`](PLAN.md) — the schedule and the decisions of record
 for actually building `module-rust`. Everything else in this directory is copied from uMod; that one
@@ -40,8 +44,12 @@ The dry run's central structural fact is the thing this reference serves:
 
 > A ServUO shard is C# **source** the operator compiles into their own server, so our bridge plugin
 > can be anything we want. **A Rust server is a binary nobody outside Facepunch patches.** The only
-> way in is a mod — specifically an **Oxide plugin**, since Oxide/uMod is what modded Rust servers
-> run — hooking the game's own events.
+> way in is a mod — hooking the game's own events through a modding framework.
+
+The dry run named that framework as Oxide, and **R19 corrected it: there are two.** Carbon runs an
+Oxide compatibility layer, so one plugin serves both and the ceiling below is the same ceiling —
+but *which* framework an operator installed is their choice, not ours. [`CARBON.md`](CARBON.md) is
+the difference list.
 
 Two consequences, and they are the two halves of this directory:
 
@@ -50,8 +58,8 @@ Two consequences, and they are the two halves of this directory:
    those 477 hooks (or from a game type one of them hands you), the bridge cannot report it. That
    makes it the input to the Rust sidecar's event catalogue — the analogue of
    [`docs/link/PLAN.md`](../../link/PLAN.md) §5 on the UO side.
-2. **We are a guest in someone else's plugin framework.** Our plugin is compiled, loaded, permissioned
-   and configured by Oxide, on Oxide's terms. [`OXIDE_API.md`](OXIDE_API.md) is that rulebook, and
+2. **We are a guest in someone else's plugin framework** — and we do not get to pick which one. Our
+   plugin is compiled, loaded, permissioned and configured by Oxide or by Carbon, on its terms. [`OXIDE_API.md`](OXIDE_API.md) is that rulebook, and
    [`OPERATING.md`](OPERATING.md) is what the server owner has to do — which is the surface our
    deployment story has to sit on, the way
    [`installer/INSTALL.md`](../../installer/INSTALL.md) sits on top of ServUO.

rust-link/INTEGRATION.md

@@ -0,0 +1,301 @@
+# rust-link — standing the bridge up
+
+**Operator- and developer-facing.** How to get a Rust server, a sidecar and a website talking, and
+how to tell which of the three is wrong when they are not. The contract itself is
+[`PROTOCOL.md`](PROTOCOL.md).
+
+There is no installer support for Rust yet — that is a later phase — so everything here is done by
+hand. When the installer gains `--game rust`, this page becomes the fallback path rather than the
+only one.
+
+---
+
+## 1. What you need
+
+| Piece | Where it comes from |
+|---|---|
+| A Rust dedicated server with **Oxide** | umod.org |
+| `RunicGateway.cs` | [Rust-Plugins](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins), `overlay/oxide/plugins/` |
+| `rust-link-sidecar` | [Rust-Link](https://gitea.whitlocktech.com/RunicGateway/Rust-Link) |
+| A Runic Gateway website with `module-rust` installed | [Module-Rust](https://gitea.whitlocktech.com/RunicGateway/Module-Rust) |
+
+**One game server, one sidecar, on that server's own host.** Six servers means six of the first two
+pairs and six rows in the website's admin panel.
+
+The module also expects four third-party Oxide plugins to be present for the features that follow
+the bridge itself — `Clans`, `Kits`, `PopupNotifications` and `ZoneManager`, all from k1lly0u on
+umod.org. The bridge works without them; the features that read them do not.
+
+---
+
+## 2. The order that works
+
+Sidecar first, then plugin, then website. Any order eventually converges — the plugin retries for
+ever and the website polls — but this one gives you a readable log at each step instead of three
+components all reporting that something else is missing.
+
+### 2.1 The sidecar
+
+```bash
+rust-link-sidecar --print-config
+```
+
+This resolves the configuration exactly as a normal start would: it writes `sidecar.toml` if it is
+missing, generates and saves an auth token if there is none, and prints the whole thing as JSON —
+**including the token in clear text**, which is the point. Keep that token; the website needs it and
+there is no second way to read it back.
+
+```json
+{
+  "component": "rust-link-sidecar",
+  "protocol": 1,
+  "config_path": "/etc/runicgateway/rust-main.toml",
+  "game": { "bind": "127.0.0.1:7799", "server_id": "" },
+  "web":  { "bind": "127.0.0.1:8090", "auth_token": "…", "ws_path": "/ws" },
+  "store": { "path": "/var/lib/runicgateway/rust-link.db" }
+}
+```
+
+Then start it. On a host running more than one game server, give each sidecar its own
+`--config`, its own ports and its own database file.
+
+**`[game].bind` stays on loopback.** There is no token on the game link — the plugin and the sidecar
+share a host and `127.0.0.1` *is* the authentication. Moving that bind to a routable address puts an
+unauthenticated command channel on the network.
+
+**`[web].bind` is the one you may need to move**, because the website is usually on another host.
+Behind TLS and a firewall: the token is the only thing guarding it.
+
+Check it:
+
+```bash
+curl http://127.0.0.1:8090/health
+{"status":"degraded","protocol":1,"plugin_connected":false,"database":"ok","uptime":"0m","last_event":null}
+```
+
+`degraded` with `plugin_connected: false` is exactly right at this point — nothing is connected yet.
+
+### 2.2 The plugin
+
+```bash
+cp RunicGateway.cs /path/to/rust/oxide/plugins/
+```
+
+Oxide compiles and loads it on the write. Watch `oxide/logs/`:
+
+```
+[Info] RunicGateway was compiled successfully in 2295ms
+[Info] [Runic Gateway] protocol 1, serverId 'main', sidecar 127.0.0.1:7799
+[Info] [Runic Gateway] connected to 127.0.0.1:7799
+```
+
+The first load also writes `oxide/config/RunicGateway.json`. Set `ServerId` before you go further:
+
+```json
+{ "Host": "127.0.0.1", "Port": 7799, "QueueCap": 5000, "ServerId": "main" }
+```
+
+**`ServerId` is this server's identity as the website knows it, and it is permanent.** It is not
+derived from the hostname on purpose — an operator renames a server for a season, and the site must
+not lose its history for it. Changing it later orphans everything recorded under the old one.
+
+Now `/health` should read:
+
+```json
+{"status":"ok","protocol":1,"plugin_connected":true,"database":"ok","uptime":"2m","last_event":"…"}
+```
+
+If it does not, ask the game server:
+
+```
+rg.link
+protocol=1 serverId=main connected=True depth=0 sent=3 dropped=0 received=2
+connects=1 writeErrors=0 bootId=boot-20260915T194502Z
+```
+
+### 2.3 The website
+
+**Admin → Rust → add a server.** Four values:
+
+| Field | Value |
+|---|---|
+| Id | the slug every URL carries. Match `ServerId` in the plugin config |
+| Name | what visitors see |
+| Sidecar base URL | `http://<sidecar host>:8090` |
+| Sidecar token | the `auth_token` from `--print-config` |
+
+**The token is write-only.** It is stored encrypted and never returned to any client; the panel
+reports only whether one is set. A save that leaves the field blank keeps the stored one — so
+renaming a server does not mean re-pasting a credential.
+
+Then press **Test**, which probes the sidecar and reports what came back:
+
+```json
+{ "ok": true, "status": "ok",
+  "sidecar": { "status": "ok", "protocol": 1, "plugin_connected": true, … } }
+```
+
+Within a poll interval the server appears at `/rust/servers`.
+
+---
+
+## 3. When it does not work
+
+A wrong URL, a wrong token and a mismatched protocol version all present as *"the site says my
+server is offline"*. The **Test** button is what separates them, and its `status` is the whole
+diagnosis:
+
+| `status` | What is wrong | Where to look |
+|---|---|---|
+| `ok` | nothing | — |
+| `no-token` | the admin form was saved without one | Admin → Rust |
+| `unauthorized` | the token does not match | `--print-config` on the sidecar host |
+| `protocol-mismatch` | the sidecar and the module speak different versions | upgrade one of them; the body names both numbers |
+| `timeout` | the sidecar answered too slowly, or not at all | the sidecar's own log |
+| `transport-error` | nothing is listening at that address | the base URL, the firewall, whether the sidecar is running |
+| `http-<code>` | something answered, and it was not a sidecar | usually a reverse proxy in front of the wrong thing |
+
+Two failures that look alike and are not:
+
+- **`plugin_connected: false` with an otherwise healthy sidecar** — the bridge is fine and the game
+  is not talking to it. Check the plugin is loaded (`oxide.plugins`) and `rg.link` on the game
+  server.
+- **The server is listed but reads `stale`** — something reported once and has not since. The row
+  says what was true when it was written; nothing has written it since. Either the poll is failing
+  (the website's log) or the sidecar stopped (its own).
+
+### 3.0 `untyped_frames` on `/health` is not zero
+
+**The plugin and the sidecar are on different protocol versions.** The game link has no handshake
+to catch that at connect time (`PROTOCOL.md` §2), so it shows up here instead: the sidecar files a
+frame by its `type`, a frame from the wrong version does not carry one it recognises, and it is
+dropped and counted rather than guessed at.
+
+The symptom without this counter is the confusing one — a game server plainly up, a sidecar plainly
+healthy, and a website showing nothing. Check the plugin's `rg.link` (it prints its protocol) against
+the sidecar's `/health` (which prints its own) and upgrade whichever is behind.
+
+### 3.1 The failures that are supposed to happen
+
+Three things look like breakage and are the design:
+
+- **Killing the sidecar does not disturb the game.** The plugin logs `sidecar link lost;
+  reconnecting` and retries with backoff, buffering into a bounded queue that drops its oldest
+  entries rather than growing. The game does not stall, and `Emit` never touches a socket.
+- **Starting the plugin before the sidecar logs one line and then goes quiet.** `cannot reach the
+  sidecar: … — retrying quietly until it answers`, printed once per load rather than every few
+  seconds. A wrong `Host` or `Port` looks exactly like this, which is why it is printed at all.
+- **The website renders with every game server off.** The server list, the player counts and the
+  last-reported times all come from stored state. A page that 500s because a socket is closed would
+  be a module that made the site's availability depend on the game's.
+
+---
+
+## 4. Running more than one server
+
+Each pair is fully independent: its own ports, its own `sidecar.toml`, its own database file, its
+own token, its own row on the website.
+
+Set `[game].server_id` in each `sidecar.toml` to match that server's plugin config. It is a
+**cross-check**, not a second source of truth — the plugin's announcement wins — and it exists to
+catch exactly one mistake: two game servers pointed at one sidecar by a copied config, which is
+silent in every other design and produces one server's history under another's name. When it fires
+you get a warning naming both ids.
+
+---
+
+## 4.1 What the bridge sends, and how much of it is kept
+
+From protocol 2 the plugin sends the read path: connects and disconnects, deaths, chat, gathering,
+bans and reports, and the wipe. Two things about the volume are worth knowing before you size
+anything.
+
+**Gathering and NPC kills are counted, not forwarded.** `OnDispenserGather` fires on every swing at
+a tree; sending one frame per swing would make the bridge the most expensive thing on the server. The
+plugin keeps a per-player tally and flushes it once a minute as a single `player.tally` frame. So the
+leaderboard is exact and the wire is quiet.
+
+**The sidecar's history is bounded; the website's is not.** `[store].retain_days` (default 14) is
+how long the sidecar keeps raw events. The permanent record — per-wipe totals that survive a wipe —
+lives in the website's own tables, so shortening this loses recent detail and never loses a player's
+history. Set it to `0` to keep everything, if the host's disk is yours to spend.
+
+**From protocol 3 your players can link their Steam account.** In game they type `/link` and the
+server answers them privately with a six-character code; on the website they type that code in
+within five minutes and the two are joined. Nothing about the link is stored on the game host — the
+website owns the record, and `/unlink` in game asks it to let go.
+
+Two things an operator should know about it:
+
+- **The code is never in a frame.** It reaches the player and nobody else, which is what makes typing
+  it into a signed-in browser proof that they are the one who asked. What crosses the bridge is
+  `account.link.requested`, a staff-visible note that somebody asked.
+- **A Steam account can belong to one website account at a time, across your whole fleet.** A code
+  from any of your servers links for all of them. If somebody links the wrong account the site
+  refuses to move it — the player runs `/unlink` in game, or staff release it from the user's page in
+  the admin panel.
+
+**From protocol 4 the website owns your permissions.** Groups and grants are written in
+Admin → Rust permissions and pushed into this server's own Oxide/Carbon permission store, so every
+plugin you already run honours them — Kits, ZoneManager, anything that calls `UserHasPermission`.
+Nothing is required of those plugins and nothing is configured twice.
+
+Four things an operator should know about it, because each looks like something else from the game
+side:
+
+- **A wipe does not lose them.** The site re-pushes the whole set when the server comes back. If your
+  wipe script clears `oxide/data/`, the permissions the site authored are back within a minute of the
+  server being up; ones granted at the console are not, because nothing remembers those.
+- **Granting at the console still works, and the website notices.** A hand edit is reported as
+  drift on that screen and is **never** undone on its own — an operator is offered two answers to
+  it: adopt it, so the site maintains it from then on, or revoke it. That is deliberate: a console
+  grant during an incident must survive the next sync.
+- **A permission no loaded plugin has registered cannot be granted.** Oxide's own API silently does
+  nothing for an unknown name, so the site checks first and reports the name as unresolved instead
+  of claiming a privilege nobody has. Load the plugin and the grant lands by itself.
+- **A player who has never connected to that server can hold a grant but cannot be in a group.**
+  The store has no record of them to put in a group yet; the site says which memberships are waiting
+  and they land on that player's first connection.
+
+`rg.perms` at the server console prints what the last sync did, which is the fastest way to tell
+"that permission does not exist here" from "that player has never been seen here".
+
+**From protocol 5 you can edit your plugins' settings from the website**, in Admin → Rust mod
+config. It reads the configuration directory your framework actually uses — `oxide/config` or
+`carbon/configs`, or wherever you moved it — and generates a form from the values it finds, so it
+works for whatever you have installed. Four things worth knowing before you use it:
+
+- **A save reloads the plugin and watches the reload.** If the plugin does not come back within four
+  seconds, the old file is **restored automatically** and the site shows you the log line that says
+  why. A typo costs you a few seconds, not a plugin.
+- **Your data directory is not listed, deliberately.** `oxide/data` (or `carbon/data`) holds live
+  state — kit cooldowns, zone definitions, the permission store itself — not settings. Editing it
+  from a web form edits your players' cooldowns, and a running plugin overwrites the change on its
+  next save anyway.
+- **Which plugin gets reloaded is your choice, with a guess filled in.** A folder name is
+  convention, not contract, so the site suggests one and lets you change it. The suggestion is right
+  nearly always and wrong silently when it is wrong, which is why it is a field rather than an
+  assumption.
+- **This bridge's own `Host`, `Port` and `ServerId` are read-only there.** Changing them from the
+  website would cut the link carrying the change, or strand every row the site holds for this
+  server. Edit them on the host; everything else in that file is editable from the site.
+
+`rg.config` at the server console prints which directory the site is reading and what the last write
+from it did.
+
+**Every row carries its wipe.** The plugin derives a `wipeId` from the save's creation time and
+stamps it on every frame, so a wipe splits the history rather than ending it. That is also why
+**the sidecar's database must never be in a wipe script's delete list** — see the Pterodactyl egg's
+`REMOVE_FILES`.
+
+---
+
+## 5. Upgrading
+
+The four declaration sites in [`PROTOCOL.md` §2](PROTOCOL.md#2-versioning) must agree. In practice
+that means upgrading the sidecar and the plugin **together**, because the game link has no version
+check of its own and a mismatched plugin mis-parses rather than refusing.
+
+The website is the forgiving half: it sends its version on every request and a sidecar that
+disagrees answers `409` with both numbers, so a module ahead of or behind its sidecar reports a
+named fault rather than misbehaving.

rust-link/PLAYER_WALK.md

@@ -0,0 +1,217 @@
+# The player walk — proving the half of the read path a console cannot reach
+
+Protocol 2's catalogue divides cleanly in two, and the line is not about importance: it is about
+whether a hook can fire without somebody holding a mouse.
+
+Everything in the first half was proven from a console and a REST client while phase 3 was built —
+the boards, the wipe id, the envelope, bans, the server lifecycle. Everything below needs a **real
+player on a real server**, because the hooks carry a `BasePlayer`, a `HitInfo` or a chat line, and
+none of those three can be manufactured from a console without becoming a different test.
+
+This document is the walk that closes it. It takes about ten minutes, it is the same on Oxide and on
+Carbon, and it is written so that the answer is readable afterwards rather than watched live.
+
+---
+
+## Before you start
+
+1. A rig running, with `RunicGateway.cs` loaded — `oxide.plugins` (or `c.plugins`) lists *Runic
+   Gateway*, and `rg.link` answers `connected=True`.
+2. A sidecar the rig can reach, with its store **empty** — that is what makes the event list at the
+   end readable as a transcript of the walk and nothing else.
+3. The sidecar's token to hand, for the reads at the bottom.
+
+Run this once, before you join:
+
+```
+rg.hooks
+```
+
+Every player hook should read **silent**. That is the baseline: the point of the walk is to move
+them, and starting from a run where some already fired proves less.
+
+---
+
+## The walk
+
+Do these in order. The order matters only in two places, noted where it does.
+
+| # | Do this | Fires | The frame should carry |
+|---|---|---|---|
+| 1 | **Join the server** | `CanUserLogin`, `OnUserApproved`, `OnPlayerConnected` | Three frames, in that order. The first two carry your **IP address** — check it is a real address and not the string `0`. `player.connected` carries your steam id and name |
+| 2 | **Wake up / spawn in** (click Respawn if you are dead) | `OnPlayerRespawned` | `player.respawned`, steam id only. It does **not** fire if you simply wake from sleeping — that is the hook's own documented behaviour, so no frame here is a pass, not a failure |
+| 3 | **Say something in chat**, then **say something in team chat** if you have a team | `OnPlayerChat` | Two `player.chat` frames, with `channel` reading `Global` and `Team`. The message must arrive whole — if it is truncated or the frame is missing, the flattener ate it |
+| 4 | **Chop a tree for about twenty seconds**, then **mine a node** | `OnDispenserGather` | **Nothing immediately.** This is the aggregate: one `player.tally` frame within 60 seconds, carrying `gathered` with `wood` and `stones`, summed. Seeing a frame per swing would be the bug |
+| 5 | **Kill an animal or a scientist** | `OnEntityDeath` | Again nothing immediately — `npcKills` on the next `player.tally`. No `player.death`: a chicken is not a killfeed entry |
+| 6 | **Die to the environment** — fall damage is easiest | `OnPlayerDeath` | `player.death` with `attackerType: "environment"`, a `grid` like `H7`, and **no** `attackerId`. Check the grid against the map: a wrong sign in the row arithmetic mirrors the whole map, and only a human with the map open can see that |
+| 7 | **Kill yourself** — `kill` in the F1 console | `OnPlayerDeath` | `attackerType: "self"`, no `attackerId` |
+| 8 | **If a second player is available**: kill each other once | `OnPlayerDeath` | `attackerType: "player"`, with `attackerId`, `attackerName`, a `weapon` shortname and a `distance` in metres. This is the killfeed's whole shape, and it is the one row phase 4's page is built from |
+| 9 | **Build a foundation, then destroy it yourself** | `OnEntityDeath` | `entity.destroyed` with `ownerId` (yours), `prefab`, `grid` and `attackerId`. Decay must **not** produce one of these — only a player breaking it |
+| 10 | **Disconnect** | `OnPlayerDisconnected` | `player.disconnected` with a `reason` and a **`sessionSec`** roughly equal to how long you were on. It also flushes your tally first, so any gathering since the last minute arrives immediately before it |
+
+Two ordering notes: step 4 must come before step 10 by at least a minute if you want to see the
+cadence flush rather than the disconnect flush, and step 1's three frames are the only place the
+order between hooks is itself part of the answer.
+
+---
+
+## Reading the result
+
+From the machine running the sidecar:
+
+```bash
+TOKEN=…            # [web].auth_token from sidecar.toml, or `--print-config`
+BASE=http://127.0.0.1:8090
+
+# The whole walk, oldest first, as a transcript.
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/feed?since=0&limit=500" \
+  | python -m json.tool
+
+# Or one kind at a time.
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/events?kind=player.death&limit=20"
+```
+
+And from the game console:
+
+```
+rg.hooks
+```
+
+Every hook in the walk should now read **fired**, with a count. A hook still `silent` after the step
+that should have fired it is the finding — and on Carbon it is the specific question
+[`CARBON.md`](../modules/rust/CARBON.md) §6 asks, since Carbon's catalogue omits thirteen uMod names
+and nobody has yet checked whether they are renames or holes.
+
+---
+
+## What counts as a pass
+
+Not "frames arrived". Three things, and the third is the one worth slowing down for:
+
+1. **Every hook in the table fired**, on both frameworks, from the same plugin file.
+2. **Every frame carries the envelope** — `type`, `serverId` and `wipeId` on all of them
+   ([`PROTOCOL.md`](PROTOCOL.md) §8.1). A player frame without a `wipeId` cannot be attributed to a
+   wipe and its rollup is lost.
+3. **The aggregates are aggregates.** `player.tally` is a delta since the last flush, so two minutes
+   of chopping is two frames that sum to the total, not two frames each carrying the total. Getting
+   this backwards makes every leaderboard roughly double, and it looks correct until somebody counts.
+
+Anything that disagrees with the table is a finding about the game or the framework rather than a
+mistake in the table — record it, the same way phases 0, 1 and 2 recorded theirs.
+
+---
+
+## The identity walk (protocol 3, phase 6)
+
+Added 2026-09-21, and here for the same reason as everything above: **a link code reaches a player
+and nobody else**, so no console can read one. The site's own half was walked in a browser — the
+refusals, the admin panel, staff unlink, the rate limit — and what needs a person in game is the
+three steps below.
+
+It takes two minutes, and it wants **two website accounts** — one you will link, one you will try to
+link the same Steam account to.
+
+| # | Do this | You should see |
+|---|---|---|
+| 1 | **In game, type `/link`** | A private reply with a six-character code and a five-minute deadline. Check it is private: a second player on the server must not see it. The code has **no O, 0, I or 1** in it — those glyphs are not in the alphabet, so one in your code is a finding |
+| 2 | **Type `/link` again straight away** | *"Please wait a moment…"* — the thirty-second cooldown. The first code is now dead either way: a new request drops the old one, so only the newest ever works |
+| 3 | **On the website, sign in and open `/player/rust`. Type the code** | The account appears, named as the game knows you, with the server it came from. Try the same code again: *"That code is unknown or has expired"* — it works once |
+| 4 | **Sign in as the SECOND account and type a fresh code for the same Steam account** | Refused, naming the account that holds it: *"That Steam account is already linked to <name>. Run /unlink in game to release it."* The link must **not** move — it is what phase 7 grants permissions against |
+| 5 | **In game, type `/unlink`** | The site's row disappears within one ingest tick (five seconds by default). Reload `/player/rust` to confirm — this is the frame arriving over the feed, not the page asking |
+| 6 | **Type a code from a server whose sidecar you have just stopped** | *"One of the servers could not be reached… your code is still good — try again in a minute."* Distinct from step 3's refusal, and the distinction is the point: the code is fine and fetching another one would not help |
+
+Step 6 needs a fleet of two, one of them down; on a single-server rig it reads *"The game servers are
+unreachable right now"* instead, which is the same rule with nothing left to be unsure about.
+
+**What counts as a pass here:** the code never appears anywhere but in front of the player who asked
+for it (check the chat log and the sidecar's `/events?kind=account.link.requested` — the frame
+carries the steam id, the name and a TTL, and **no code**), a Steam account belongs to one website
+account at a time, and every refusal is a sentence that tells the player what to do next.
+
+---
+
+## The permission walk (protocol 4, phase 7)
+
+Added 2026-09-21. The website half was walked end to end against a stand-in plugin — the authoring
+screen, the report, drift and its two answers, and a restart that emptied the store and was fully
+re-pushed. **What is left is the sentence the phase exists for: a grant made on the website gates a
+third-party plugin in the game.**
+
+It cannot be walked from a console, and it cannot be walked on the owner's account:
+
+- **A console session bypasses every gate.** The standard idiom is
+  `return !player || permission.UserHasPermission(...)`, and an RCON command has no `BasePlayer` —
+  so the console is unconditionally allowed ([PLAN.md §12.5](../modules/rust/PLAN.md)).
+- **An admin account bypasses most plugins' gates too**, and not uniformly: Popup Notifications
+  (`player.IsAdmin ||`) and Zone Manager (`authLevel > 0 ||`) are hard bypasses. Kits is the
+  exception — its `IsAdmin` is the `kits.admin` **permission** and `AdminIgnoreRestrictions`
+  defaults to `false` — so a kit's `RequiredPermission` does apply to a server owner.
+
+So this walk wants a **second, non-admin Steam account** connected to the rig. Kits alone can be
+walked on the owner's account; steps 4 and 5 cannot.
+
+| # | Do this | You should see |
+|---|---|---|
+| 1 | **Link the second account** (the identity walk above), then on the website open Admin → Rust permissions and grant it a kit's `RequiredPermission` — pick the kit from `GetKitNames`, or read one out of `oxide/config/Kits.json` | The grant appears with the account beside it. Within a minute the server row reads **in sync** — or press *Sync now* and watch it happen |
+| 2 | **In game on that account, open the kit menu** | The kit is no longer locked. Before the grant it shows as locked; that difference is the whole phase |
+| 3 | **At the server console, `oxide.show user <steamid>`** | The permission is there, granted by this plugin rather than by hand |
+| 4 | **At the console, `oxide.grant user <steamid> zonemanager.admin`** (a permission the site manages but did not grant) | Within seconds the website's screen shows it under *Changed in game*. **Revoke** it there, and it is gone from `oxide.show user` on the next sync. **Adopt** a different one instead and it stays, now listed as the site's own |
+| 5 | **Put the second account in a group on the website, then wipe or restart the server** (a wipe script that clears `oxide/data/` is the interesting case) | After the server is back: the group exists again, the membership is back, and the grant is back — without anybody touching the website. This is R2's central promise and the one thing a stand-in cannot prove |
+| 6 | **Grant a permission whose plugin you have just unloaded** | The site reports it **unresolved** against that server and keeps the grant. Load the plugin again: it lands on the next sync, with nothing typed |
+| 7 | **Add a website account that has never connected to this server to a group** | The site reports the membership as *waiting on their first connection*. Have them connect: it lands. A **direct grant** to the same account, by contrast, is in `oxide.show user` immediately |
+
+**Run it on both frameworks.** From phase 3, done means done on Oxide and on Carbon (R19/R21), and
+this phase has two specific things to confirm there rather than assume:
+
+- **`GetPermissionUsers` / `GetUsersInGroup` entry format.** Both answer `id(name)`, and the spacing
+  differs between the calls and between the frameworks. The plugin takes everything before the first
+  bracket. If that parse is wrong, **every holder is reported as foreign** — which is visible
+  immediately: the drift list fills with grants the site itself made.
+- **`GetGroupPermissions(name, false)`** is called with both arguments. If Carbon's signature has no
+  second parameter, the plugin does not compile there at all — the one place in protocol 4 where
+  R19's byte-identical-plugin claim is at risk.
+
+**What counts as a pass:** a non-admin player's access in game changes because of something typed on
+the website and nothing else; a hand edit is reported rather than undone; and a wipe costs the
+operator nothing.
+
+## The configuration walk (protocol 5, phase 7b)
+
+Added 2026-09-22. The website half was walked end to end against a real sidecar and a stand-in
+plugin over a real directory of real config files — the recursive walk, a form save, a rollback, a
+refusal, a version conflict and the locked keys — and the plugin half **compiles and loads on the
+live Oxide rig**, where `rg.config` answers
+`protocol=5 framework=oxide root=/home/container/oxide/config`.
+
+**What is left is the sentence the phase exists for: a setting changed on the website takes effect
+in the running game.** It needs the sidecar and the game server on **one host**, because the game
+link is loopback by design (D2) — on the Pterodactyl rigs that is phase 18's egg, and on a
+development machine it is a firewall rule for the port the plugin dials.
+
+| # | Do this | You should see |
+|---|---|---|
+| 1 | **Open Admin → Rust mod config** and pick the server | The tree the framework actually uses — `oxide/config` on Oxide, `carbon/configs` on Carbon — grouped by plugin, with every loaded plugin's version beside it |
+| 2 | **Open `ZoneManager.json`, change a setting, leave the reload target on its guess, and save** | "Saved, and the plugin reloaded." At the console, `oxide.show`/`c.show` is irrelevant — the proof is the plugin behaving differently, so pick a setting you can see: `Auto Show Zones`, or an entry message |
+| 3 | **Check a float nobody touched**, e.g. a rate ending `.0`, in the file on the host | It is still `1.0`, not `1`. This is the trap the whole editor exists for, and a server whose configs are full of whole-numbered floats is where it bites |
+| 4 | **Break a config on purpose** — in Raw JSON, give a numeric field a string, or anything the plugin's own class cannot deserialize — and save with that plugin as the reload target | Within about four seconds: *"The plugin did not come back, so the old file was put back automatically"*, the compiler's own line underneath it, and the file on the host back as it was. `oxide.plugins` shows the plugin **loaded** — because the restore was reloaded too |
+| 5 | **Save a nested file** (`Kits/kits.json`, or any `config/<Mod>/x.json`) **and confirm the reload target** | The right plugin reloads. Reloading the wrong one is the failure this field exists to prevent, and it reports success — so check `oxide.plugins`' timestamps, not the website's word |
+| 6 | **Open the bridge's own config** | `Host`, `Port` and `ServerId` are read-only with the reason; `QueueCap` saves; the reload dropdown does not offer this plugin. The save says it was written and **not** reloaded, which is the honest answer — our settings apply on the next deliberate reload |
+| 7 | **Edit a file on the host over SSH while the website has it open, then save from the website** | A conflict, with the current file offered — never an overwrite |
+| 8 | **Ask for a file outside the tree** (`../data/oxide.users.data`, an absolute path) with `curl` against the sidecar, with a valid token | Refused by the **plugin**, with a reason. The sidecar forwards paths and judges none of them; the guard is where the directory is |
+
+**Run it on both frameworks.** From phase 3, done means done on Oxide and on Carbon (R19/R21), and
+this phase has two specific things to confirm rather than assume:
+
+- **The reload path.** The plugin asks `Interface.Oxide` for `ReloadPlugin` by reflection and falls
+  back to a console command — `c.reload` on Carbon, `oxide.reload` on Oxide, chosen by looking for a
+  Carbon assembly at runtime. A wrong prefix on Carbon prints **nothing at all**, which looks
+  exactly like a command that worked (`CARBON.md` §5), so the proof is `OnPluginLoaded` arriving,
+  not the command being accepted.
+- **`OnPluginLoaded` / `OnPluginUnloaded` firing at all.** They are the rollback's only evidence. If
+  either does not fire on a framework, every save there rolls itself back four seconds later and
+  reports a plugin that is in fact perfectly fine. `rg.hooks` at the console is the standing answer:
+  both names are in `ExpectedHooks`, so a framework that never raises one shows a zero.
+
+**What counts as a pass:** a setting typed on the website changes what the running game does; a
+deliberately broken config leaves the plugin loaded and the operator holding the reason; and no file
+the save did not touch differs by a single byte.