docs(opcodes): retire superseded opcode files; update structure + doc pointers

- rm vm-map/opcodes-himegari.json, vm-map/himegari-opcode-notes.md (folded into opcodes.toml; in history)
- PROJECT-STRUCTURE.md: opcodes.toml single-source-of-truth + generated artifacts + convention
- repoint dead references in vm-mapping-plan/sys4-format-notes/himegari-port-reference/phase-a-slice-plan

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/PROJECT-STRUCTURE.md

@@ -33,8 +33,10 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   │                                        where the game / extracted / build dirs are. All
     │   │                                        tools import it; relocatable with no other edits.
     │   ├── sys4load.py                         loader + disassembler (opcode-decoding)
-    │   ├── age_opcodes.py                      548-entry AGE opcode/arg-type table (pristine)
-    │   ├── age_opcodes_himegari.py             inferred Himegari opcode-name overlay
+    │   ├── age_opcodes.py                      548-entry Kelebek AGE opcode/arg-type table (PRISTINE; never edit)
+    │   ├── opcodes_build.py                    generator/linter: vm-map/opcodes.toml -> the 4 artifacts below
+    │   ├── opcodes_model.py                    load + lint (dangling-ref, confidence-ceiling, vocab) + dependents
+    │   ├── age_opcodes_himegari.py             GENERATED from opcodes.toml (do not hand-edit)
     │   ├── vm0.py                              headless Python VM (Phase A0); `--test` = RECOVER unit test
     │   ├── extract_phase2.py                   batch: disasm + text + data extraction
     │   ├── extract_init.py, global_map.py …    *INIT parsers, global-var map builder
@@ -46,9 +48,10 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   └── LzssCpp.dll                         its LZSS codec dependency
     │
     ├── vm-map/                               VM / reverse-engineering reference artifacts
-    │   ├── opcodes-himegari.json               validated opcode table (what this game uses)
+    │   ├── opcodes.toml                        ★ CANONICAL opcode reference (hand-edited: ABI + semantics
+    │   │                                        + provenance + depends_on). Single source of truth for opcodes.
     │   ├── kelebek1-age-shared.cpp / -disassembler.cpp   upstream opcode-table source
-    │   └── opcode-leads.json, small-script-listings.md, himegari-opcode-notes.md
+    │   └── opcode-leads.json, small-script-listings.md
     │
     ├── docs/                                 all documentation
     │   ├── PROJECT-STRUCTURE.md                this file
@@ -58,7 +61,8 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── himegari-port-reference.md          master reference + engine background
     │   ├── name-resolution.md                  call-script + global-var name recovery
     │   ├── sys4-format-notes.md                byte-level container format
-    │   └── script-inventory.md                 what the 481 scripts are
+    │   ├── script-inventory.md                 what the 481 scripts are
+    │   └── opcode-reference.md                 GENERATED from opcodes.toml (human-readable opcode reference)
     │
     ├── build/                               DERIVED (our-work-side) — generated by tools/; disposable
     │   ├── disasm/                            <NAME>.asm — human-readable disassembly, one per script
@@ -69,7 +73,8 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── data/                              parsed data tables (*INIT → JSON)
     │   ├── scripts-json/                      machine-readable full dumps (on demand via --json)
     │   ├── global-var-map.{json,md}           partial global-variable name map
-    │   └── manifest.json, opcode-coverage.md
+    │   ├── opcodes.json                        GENERATED from opcodes.toml (machine view for the C# VM)
+    │   └── manifest.json, opcode-coverage.md   (opcode-coverage.md GENERATED from opcodes.toml)
     │
     └── godot/                               DELIVERABLE — the Godot/C# engine project (built in Phase A2+)
 ```
@@ -90,6 +95,10 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
 - **`build/` and `extracted/` are disposable.** `build/` regenerates via `tools/extract_phase2.py`
   (or `sys4load.py`); `extracted/` regenerates via `bin/BinExtractALF.exe` on the `.ALF` files.
   Safe to delete and rebuild; do not hand-edit.
+- **Opcode knowledge is edited ONLY in `vm-map/opcodes.toml`** (ABI + semantics + provenance +
+  `depends_on`). Run `tools/opcodes_build.py --build` to regenerate the shim (`tools/age_opcodes_himegari.py`),
+  machine JSON (`build/opcodes.json`), reference (`docs/opcode-reference.md`), and coverage. `--lint`
+  checks dangling deps / confidence-ceiling / vocabulary. Kelebek's `tools/age_opcodes.py` stays pristine.
 - **Encoding:** all generated text is UTF-8 (source strings are cp932/Shift-JIS, decoded on
   extraction). Run Python as `py -3.11 -X utf8`.
 - **The game install is a runnable unit** — do not relocate `AGE.EXE`/`*.ALF`/DLLs relative to each