Merge upstream/main (samwhosung/benilla b17be271) into the graphics programme

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/CONTRIBUTING.md

@@ -5,6 +5,13 @@ creative: a change is accepted when it makes benilla more like 1.12.1 or fixes a
 evidence from the reference, in one small piece, with the gates green. Everything else is a
 fork, and forks are welcome.
 
+## Where to start
+
+The [issues](https://github.com/samwhosung/benilla/issues) the maintainers file are checked
+against 1.12.1 first: each says what 1.12.1 does, what benilla does instead, and where in the
+code, and any of them is a place to start. Before you start one, look for an open pull request
+that already covers it, and say `Fixes #N` in yours.
+
 ## What gets in
 
 - A fix for a bug, with how to see it before and after.
@@ -26,7 +33,8 @@ fork, and forks are welcome.
 1. `scripts/gates.sh` is green: fmt, clippy with warnings denied, the workspace tests (once
    with the client data, once without, so a test that reads the install has to declare it), the
    doc-link and render-pass lints, the player build with its own tests, and the engine boot
-   checks.
+   checks. A pull request from a fork runs the ones that need neither the install nor a display
+   in CI, on Linux; the rest run on the maintainer's machine before it lands.
 2. The reference fact is stated: what 1.12.1 does, and where that is known from (the client's
    behaviour you observed, a DBC field, a FrameXML line, a packet capture). The names and shapes
    under `reference/` are the surface benilla tracks.
@@ -34,6 +42,15 @@ fork, and forks are welcome.
    No history.
 4. The commit message says what changed, for a player or a developer, in one line.
 
+## After you open it
+
+A maintainer reads it, checks it against the reference, runs it and finishes it here: a rebase
+onto main, a fix, a test or a comment, added as commits on top of yours on your branch, so leave
+"Allow edits by maintainers" ticked. It lands as one squash-merged commit with you as its author.
+When what would land is mostly ours, we land our own version with you as a co-author and close
+yours with a note, and when main already has the fix, we close yours and say where. One that is
+out of scope is closed with the reason.
+
 ## Setting up
 
 - **The toolchain.** Stable Rust (`rust-toolchain.toml` adds clippy and rustfmt) and a C
@@ -44,12 +61,12 @@ fork, and forks are welcome.
   root, which only a dev build sees: the player build looks for `Data/` or `WoW/Data/` beside
   the binary. benilla reads the install and never writes into it. `WOW_DATA=` (set, empty)
   means "no install", which is how the no-install boot is tested on a machine that has one.
-- **Without the install, green is hollow.** About a thousand tests read the install and skip
-  when it is absent; six more read a corpus of vanilla addons (`BENILLA_ADDON_CORPUS=<a folder
-  of addons>`, or a `wow-addons-vanilla` link at the root), third-party content that is not in
-  this repo. `scripts/gates.sh` and `scripts/check.sh` print how many tests skipped and why.
-  Where the data is, `BENILLA_REQUIRE_DATA=1` turns a skip into a failure, and the gates set it
-  themselves when the install and the corpus both resolve.
+- **Without the install, green is hollow.** Well over a thousand tests read the install and skip
+  when it is absent, and a few dozen more read a corpus of vanilla addons
+  (`BENILLA_ADDON_CORPUS=<a folder of addons>`, or a `wow-addons-vanilla` link at the root),
+  third-party content that is not in this repo. `scripts/gates.sh` and `scripts/check.sh` print
+  how many tests skipped and why. Where the data is, `BENILLA_REQUIRE_DATA=1` turns a skip into a
+  failure, and the gates set it themselves when the install and the corpus both resolve.
 - **A server to test against.** Any 1.12.1 server; `WOW_HOST` names it (default
   `localhost:3724`). A scripted run has no default account: `WOW_USER`, `WOW_PASS` and
   `WOW_CHAR` name a test account on your server whose login kicks nobody, all three, either in
@@ -78,8 +95,8 @@ fork, and forks are welcome.
 
 ## Reporting a bug
 
-Open an issue: what you did, what you saw and what 1.12.1 does instead, with the server and the
-platform you ran on. Questions and ideas are welcome there or on the Discord linked from the
-README.
+Open an issue: what you did, what you saw and what 1.12.1 does instead, with the `benilla build`
+line from the start of the terminal output, your platform and the server you ran on. Questions
+and ideas are welcome there or on the Discord linked from the README.
 
 Working with an AI agent is expected. The agent reads `AGENTS.md`, and the same rules bind it.

docs/MAP.md

@@ -378,7 +378,7 @@
 - `WOW_PARTICLE_FLAT` — benilla-world/src/particles/render.rs
 - `WOW_PARTICLE_NODEPTH` — benilla-world/src/particles/render.rs
 - `WOW_PART_CHURN` — benilla-app/src/perf/mod.rs
-- `WOW_PASS` — benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/run_mode.rs
+- `WOW_PASS` — benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/run_mode.rs, benilla-protocol/examples/login_refusal_probe.rs, benilla-protocol/examples/park_probe.rs
 - `WOW_PERF_HUD` — benilla-app/src/perf/hud.rs
 - `WOW_PHASE` — benilla-app/src/capture/phase_probe.rs, benilla-app/src/dev.rs, benilla-world/src/bgwin.rs
 - `WOW_PHASE_AT` — benilla-app/src/capture/phase_probe.rs
@@ -510,7 +510,9 @@
 - `WOW_UNIT_VISUALS` — benilla-app/src/capture/probes/visual_census.rs, benilla-app/src/dev.rs
 - `WOW_UNIT_VISUALS_RADIUS` — benilla-app/src/capture/probes/visual_census.rs
 - `WOW_UPLOAD_BUDGET` — benilla-world/src/world_plugins.rs
-- `WOW_USER` — benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/run_mode.rs
+- `WOW_USER` — benilla-app/src/login/mod.rs, benilla-app/src/net.rs, benilla-app/src/run_mode.rs, benilla-protocol/examples/login_refusal_probe.rs, benilla-protocol/examples/park_probe.rs
+- `WOW_VIS_DUMP` — benilla-app/src/capture/probes/live_fps.rs
+- `WOW_VIS_TRACE` — benilla-world/src/model_render/visibility.rs
 - `WOW_VISTA_AT` — benilla-app/src/capture/mod.rs
 - `WOW_VISTA_FACE` — benilla-app/src/capture/mod.rs
 - `WOW_VISTA_MIN` — benilla-app/src/capture/mod.rs

docs/METHOD.md

@@ -41,9 +41,9 @@ comment naming the reference fact and why we differ. Anything else is a fork.
   counterparts under `assets/ui` stay until they retire.
 - **The install is read-only.** benilla never writes into the WoW folder: no screenshot, log,
   cache or scratch file. `scripts/smoke.sh` fails a run that leaves the install changed.
-- **Local state lives in one folder**, `benilla-config/` beside the binary, and every path to
-  it resolves through `crate::local_state`. Player settings are CVars persisted as a diff in
-  `benilla-config/config.toml`.
+- **Local state lives in one folder**, `benilla-config/`, at the repo root in a dev build and
+  beside the binary in the player build; every path to it resolves through `crate::local_state`.
+  Player settings are CVars persisted as a diff in `benilla-config/config.toml`.
 - **UI is stock-first: a window is migrated, not authored.** The end state is the stock 1.12
   FrameXML executed off the player's own chain. `assets/ui` does not grow: a test names its
   files and fails on a new one. A window is built by pointing `benilla.toc` at the stock file,