Reorganize docs

2026-07-22 11:39:41 -07:00
parent 696b0b777f
commit 70920f2167
11 changed files with 83 additions and 80 deletions
@@ -1,80 +1,3 @@
 # AGENTS.md

-EverQuest client config and a **minimal classic UI skin** (`UISkin=isuldor`) maintained as unified diffs against `uifiles/default/`.
-
-## Docs
-
-* Install paths and INI layout: [docs/steam-linux-paths.md](docs/steam-linux-paths.md)
-* 2026 theme refresh (what broke, what we changed): [docs/ui-theme-2026-refresh.md](docs/ui-theme-2026-refresh.md)
-
-## Patch-set model (advice)
-
-We patch **six** `EQUI_*.xml` files plus two `dark_tile_*.tga` textures — not a full skin fork. That is intentional.
-
-| Do | Avoid |
-|----|--------|
-| Keep the patch set small (persistent on-screen windows only) | Copying all of `uifiles/default/` into git |
-| Patch `uifiles/default/` → install to `uifiles/isuldor/` | Patching `uiresources/` / `AtlasSkin` (HTML/Cohtml panels) |
-| Run `bash ui/verify.sh` before every commit and after every game patch | Relying on `patch --fuzz 3` without a dry-run |
-| Regenerate diffs with `bash ui/install.sh --update` (CRLF-aware) | Hand-editing diffs or `diff -u` from LF-only XML |
-| Budget **manual re-merge** for `EQUI_PlayerWindow` after major client updates | Expecting every patch to apply for years unchanged |
-
-**Highest-churn files:** `EQUI_PlayerWindow.xml` (roles, aggro, meters), then `EQUI_HotButtonWnd.xml` (many slot animations). Everything else has been stable across years.
-
-**Pin the client you verified against:** `ui/.verified-build` (eqgame mtime, patch list). Refresh with `bash ui/verify.sh --record` after a successful in-game check.
-
-## Non-obvious details
-
-* **Two UI trees:** `UISkin` → `uifiles/<name>/` (XML we patch). `AtlasSkin` → `uiresources/<name>/` (modern panels; **out of scope** — stay stock Default).
-* **Stock XML is CRLF.** `uifiles/default/*.xml` use Windows line endings. LF-only merged files produce giant whole-file diffs; `install.sh --update` normalizes to CRLF when the default file is CRLF.
-* **`patch --fuzz 3`** helps when line numbers drift (e.g. `EQUI_Animations`) but can apply the wrong hunk if context is ambiguous. Verify always uses dry-run; treat any future `FAILED` on PlayerWindow as a hand-merge, not a fuzz tweak.
-* **Textures:** Register new `.tga` only in `EQUI_Animations.diff`; reference by filename elsewhere. `install.sh` copies `ui/*.tga` into `uifiles/isuldor/`.
-* **Theme vs layout:** XML = chrome/templates. Window positions and fade % live in `UI_<Char>_<Server>_<Class>.ini` (`UISkin`, fades). Chat colors in `eqclient.ini` `[TextColors]`. Client updates can stomp INIs — keep canonical copies in this repo.
-* **`EQType` on labels:** The player-window theme uses shadow labels and specific EQTypes (e.g. HP `17`, mana `124`) so text overlays gauges; stock uses different types — do not “fix” to match default without checking in-game.
-* **Required stub labels:** `HPPerLabel` / `ManPercLabel` / `FatiguePercLabel` must exist as minimal `<Label>` pieces (ScreenID only) or the client breaks.
-* **Install script:** Use `bash ui/install.sh` (shebang can fail on some mounts). `EQ_GAME_PATH` overrides auto-detect (Steam Linux path is tried first).
-* **Game path detection:** Looks for `eqgame.exe` in install root (including Proton/Steam Linux `.exe` name).
-
-## Lint / verify (run before commit)
-
-From repo root:
-
-```bash
-# 1. Patches apply cleanly against live uifiles/default/
-bash ui/verify.sh
-
-# 2. Optional: fail if eqgame.exe changed since ui/.verified-build
-bash ui/verify.sh --strict
-
-# 3. After game patch + in-game smoke test — update pin file
-bash ui/verify.sh --record
-```
-
-**Install + verify together:**
-
-```bash
-bash ui/install.sh && bash ui/verify.sh
-```
-
-**After editing `uifiles/isuldor/` in-game or by hand:**
-
-```bash
-bash ui/install.sh --update   # regenerate *.diff (CRLF-safe)
-bash ui/verify.sh --record
-```
-
-**Manual checks** (no automated linter for EQ UI XML):
-
-* No duplicate `<Pieces>` entries in `EQUI_PlayerWindow` (easy to introduce when merging).
-* `grep -c Player_HPLabelShadow` in built XML — should appear twice (element + one Pieces line), not three.
-* Diff size sanity: `EQUI_PlayerWindow.diff` should be hundreds of lines, not 1500+ (signals CRLF/LF mismatch).
-
-**In-game smoke test** (after client update): player window (HP/mana/XP/AA, group roles, aggro), hotbars, chat, spell window; inventory/AA should still look like **Default**.
-
-## Workflow summary
-
-```
-game patch → bash ui/install.sh → bash ui/verify.sh
-          → fix failed hunks (usually EQUI_PlayerWindow) → install.sh --update → verify.sh --record
-          → set UISkin=isuldor in UI INI → login smoke test
-```
+* [EverQuest Legends spell data](/docs/eql-spell-data.md)
@@ -0,0 +1,80 @@
+# AGENTS.md
+
+EverQuest client config and a **minimal classic UI skin** (`UISkin=isuldor`) maintained as unified diffs against `uifiles/default/`.
+
+## Docs
+
+* Install paths and INI layout: [docs/steam-linux-paths.md](docs/steam-linux-paths.md)
+* 2026 theme refresh (what broke, what we changed): [docs/ui-theme-2026-refresh.md](docs/ui-theme-2026-refresh.md)
+
+## Patch-set model (advice)
+
+We patch **six** `EQUI_*.xml` files plus two `dark_tile_*.tga` textures — not a full skin fork. That is intentional.
+
+| Do | Avoid |
+|----|--------|
+| Keep the patch set small (persistent on-screen windows only) | Copying all of `uifiles/default/` into git |
+| Patch `uifiles/default/` → install to `uifiles/isuldor/` | Patching `uiresources/` / `AtlasSkin` (HTML/Cohtml panels) |
+| Run `bash ui/verify.sh` before every commit and after every game patch | Relying on `patch --fuzz 3` without a dry-run |
+| Regenerate diffs with `bash ui/install.sh --update` (CRLF-aware) | Hand-editing diffs or `diff -u` from LF-only XML |
+| Budget **manual re-merge** for `EQUI_PlayerWindow` after major client updates | Expecting every patch to apply for years unchanged |
+
+**Highest-churn files:** `EQUI_PlayerWindow.xml` (roles, aggro, meters), then `EQUI_HotButtonWnd.xml` (many slot animations). Everything else has been stable across years.
+
+**Pin the client you verified against:** `ui/.verified-build` (eqgame mtime, patch list). Refresh with `bash ui/verify.sh --record` after a successful in-game check.
+
+## Non-obvious details
+
+* **Two UI trees:** `UISkin` → `uifiles/<name>/` (XML we patch). `AtlasSkin` → `uiresources/<name>/` (modern panels; **out of scope** — stay stock Default).
+* **Stock XML is CRLF.** `uifiles/default/*.xml` use Windows line endings. LF-only merged files produce giant whole-file diffs; `install.sh --update` normalizes to CRLF when the default file is CRLF.
+* **`patch --fuzz 3`** helps when line numbers drift (e.g. `EQUI_Animations`) but can apply the wrong hunk if context is ambiguous. Verify always uses dry-run; treat any future `FAILED` on PlayerWindow as a hand-merge, not a fuzz tweak.
+* **Textures:** Register new `.tga` only in `EQUI_Animations.diff`; reference by filename elsewhere. `install.sh` copies `ui/*.tga` into `uifiles/isuldor/`.
+* **Theme vs layout:** XML = chrome/templates. Window positions and fade % live in `UI_<Char>_<Server>_<Class>.ini` (`UISkin`, fades). Chat colors in `eqclient.ini` `[TextColors]`. Client updates can stomp INIs — keep canonical copies in this repo.
+* **`EQType` on labels:** The player-window theme uses shadow labels and specific EQTypes (e.g. HP `17`, mana `124`) so text overlays gauges; stock uses different types — do not “fix” to match default without checking in-game.
+* **Required stub labels:** `HPPerLabel` / `ManPercLabel` / `FatiguePercLabel` must exist as minimal `<Label>` pieces (ScreenID only) or the client breaks.
+* **Install script:** Use `bash ui/install.sh` (shebang can fail on some mounts). `EQ_GAME_PATH` overrides auto-detect (Steam Linux path is tried first).
+* **Game path detection:** Looks for `eqgame.exe` in install root (including Proton/Steam Linux `.exe` name).
+
+## Lint / verify (run before commit)
+
+From repo root:
+
+```bash
+# 1. Patches apply cleanly against live uifiles/default/
+bash ui/verify.sh
+
+# 2. Optional: fail if eqgame.exe changed since ui/.verified-build
+bash ui/verify.sh --strict
+
+# 3. After game patch + in-game smoke test — update pin file
+bash ui/verify.sh --record
+```
+
+**Install + verify together:**
+
+```bash
+bash ui/install.sh && bash ui/verify.sh
+```
+
+**After editing `uifiles/isuldor/` in-game or by hand:**
+
+```bash
+bash ui/install.sh --update   # regenerate *.diff (CRLF-safe)
+bash ui/verify.sh --record
+```
+
+**Manual checks** (no automated linter for EQ UI XML):
+
+* No duplicate `<Pieces>` entries in `EQUI_PlayerWindow` (easy to introduce when merging).
+* `grep -c Player_HPLabelShadow` in built XML — should appear twice (element + one Pieces line), not three.
+* Diff size sanity: `EQUI_PlayerWindow.diff` should be hundreds of lines, not 1500+ (signals CRLF/LF mismatch).
+
+**In-game smoke test** (after client update): player window (HP/mana/XP/AA, group roles, aggro), hotbars, chat, spell window; inventory/AA should still look like **Default**.
+
+## Workflow summary
+
+```
+game patch → bash ui/install.sh → bash ui/verify.sh
+          → fix failed hunks (usually EQUI_PlayerWindow) → install.sh --update → verify.sh --record
+          → set UISkin=isuldor in UI INI → login smoke test
+```