Fork setup: add MONKEY-FORK maintenance catalogue

Establish benilla-everwood as our fork of samwhosung/benilla.
Documents the vendor-branch update workflow, the benilla-monkey
plugin-crate design, the catalogue of upstream edits, the ~10
mapi functions to reimplement natively, and the staged de-risk plan.

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

MONKEY-FORK.md

@@ -0,0 +1,82 @@
+# MONKEY-FORK — benilla-everwood
+
+Our fork of **[samwhosung/benilla](https://github.com/samwhosung/benilla)** (a from-scratch Rust +
+Bevy reimplementation of the 1.12.1 / 5875 client). Goal: run the Everwood / "Monkey WoW" custom
+content — the features currently delivered on the stock Blizzard client via **injected `mapi.dll` /
+`phys.dll`** — as **native code in an open client** instead.
+
+Upstream is a solo project, published as **squashed snapshots from a private tree, with issues and
+PRs closed**. Nothing we do here can ever land upstream — we carry our changes forever. So this file
+is the contract that keeps re-applying them across upstream drops cheap.
+
+## Branch topology
+
+| branch | role | rule |
+|---|---|---|
+| `vendor` | pristine mirror of `upstream/main` | **never commit here** — only `reset --hard` |
+| `everwood` | our work (this fork's default) | the `benilla-monkey` crate + the catalogued edits below |
+
+Remotes: `upstream` = samwhosung/benilla · `origin` = pkuzic/benilla-everwood.
+
+## Updating to a new upstream drop
+
+```bash
+git fetch upstream
+git checkout vendor && git reset --hard upstream/main   # works even if upstream re-squashed / force-pushed
+git checkout everwood && git rebase vendor              # replays our small commit series on top
+```
+
+Conflicts can only occur in the few upstream files we edit (see catalogue). `Cargo.lock` conflict →
+`git checkout --theirs Cargo.lock` then `cargo build` to regenerate. After every rebase, re-run the
+addon harness as a regression gate (below).
+
+## Design rule: keep our surface tiny
+
+All custom logic lives in a **new crate `crates/benilla-monkey/`** (a Bevy plugin). The workspace is
+`members = ["crates/*"]`, so a new crate is auto-included and **cannot merge-conflict**. benilla
+already registers Lua globals from Bevy plugins (its `ProbeLuaPlugin` does
+`script.lua().create_function()` + `globals().set(...)`); `UiScript` exposes `.lua()` /
+`.register_bindings()`; rig/pose data is public (`RigPose`, `RigPalettes`, `RigSkin`, `PosePost`).
+When a refactor breaks us it surfaces as a **compile error in our crate** pointing at the renamed
+symbol — not a silent wipe of edits scattered through theirs.
+
+## Catalogue of edits to UPSTREAM files
+
+Every edit outside `crates/benilla-monkey/` goes here and is marked in-source with `// MONKEY:`.
+Keep this list short; prefer moving logic into the crate.
+
+| file | edit | why | status |
+|---|---|---|---|
+| `crates/benilla-app/src/lib.rs` (`run`) | `app.add_plugins(MonkeyPlugin)` | wire our plugin in (no public plugin-group entry yet) | **planned** |
+| `crates/benilla-ui` / `assets/ui` | publish `TargetLevelText` / `PlayerLevelText` regions | MonkeyCharsheet hooks these stock globals | **planned** |
+| (register `PlayerModel` frame type) | `CreateFrame("PlayerModel", …)` | BuildUI + ObjectBrowser 3D previews | **planned** |
+
+## The ~10 functions to reimplement natively
+
+Currently injected by `mapi.dll` (`custom/client/mapi/dllmain.cpp` `g_api[]`). Only 4 addons use
+them; the other 10 Monkey addons are pure FrameXML.
+
+- **Projection / camera** (easy): `WorldToScreen`, `MonkeyProj`, `MonkeyCamLive`
+- **Model spawn / transform** (cleaner than the DLL hacks — we own the loader): `MonkeyCreateModel`,
+  `MonkeySetModelTransform`, `MonkeyDestroyModel`; `MonkeyPathByte` becomes unnecessary
+- **GO model reuse** (obsolete — just spawn our own entity): `MonkeyHijackGO`, `MonkeyRestoreGO`,
+  `MonkeyDriveGO`
+- **Bone override** (deepest — via `RigPose` around `PosePost`): `MonkeySetScratchBone`, `MonkeyBendBone`
+
+## De-risk plan (staged)
+
+1. Plugin PoC — register `WorldToScreen` from `benilla-monkey`, confirm a Lua call returns real coords.
+2. FrameXML fixes — `PlayerModel` + `TargetLevelText`/`PlayerLevelText`; re-harness (10/14 → ~13/14).
+3. Live UI smoke test vs the Everwood server (real pixels + interaction).
+4. Native `MonkeySetScratchBone` via `RigPose` — unblocks MonkeyBodyShape end-to-end.
+
+## Regression harness
+
+benilla ships a headless addon corpus harness. Point it at a folder of our addons:
+
+```bash
+WOW_DATA=G:/twmoa_1181/Data cargo run -q -p benilla-app --example addon_harness -- <AddOns folder> --verbose
+```
+
+Baseline (2026-08-23, before any fix): **12/14 load, 10/14 survive a session**; read the custom
+MPQ/DBC patch chain without crashing.