Merge pull request 'docs(runicnpc): 9c, the three fight checks explained; D331 (runicnpc-rust#20, #22)' (#410) from docs/runicnpc-fight-checks-20 into main

Reviewed-on: #410

runicnpc/PLAN.md

@@ -154,6 +154,7 @@ architectural or design decision is implemented.
 | **D328** | **"Still at the plugin's defaults" means every setting, all or nothing.** The installer and the egg write the banner only where `PopupNotifications.json` is missing, or where every setting equals PopupNotifications 0.2.1's own defaults (its `Version` aside; numbers compared as numbers). A config with any one setting changed, or one that does not parse, is kept whole and never merged into. | Field by field: our values only where that one field is still at its default, which mixes two looks nobody chose. |
 | **D329** | **The Kits reload the first load asks for is owed until Kits has the example kits.** The reload ran on a one-second timer, and a timer dies with its plugin. In the 9d session RunicNPC was loaded again inside that second on Carbon, the reload was lost, and since `examplesWritten` was already set the examples stayed refused until Kits was reloaded by hand. Now `state.json` holds `kitsReloadOwed`: every load, and Kits coming back, clears it once Kits knows every kit owed, and otherwise asks for the reload again, at most three times, then warns with the command to run. Oxide never showed it, because loading RunicNPC recompiles and reloads Kits there (`// Requires: Kits`). The org lead chose the fix over recording it (2026-10-09). | Record it as a hot-load artifact, with the remedy in INSTALL.md. |
 | **D330** | **RunicNPC's stage 9 release is v1.0.0, cut by a `feat!:` commit.** The release engine takes its bump from the non-merge commit subjects since the last tag. Every stage had landed as `feat:`, which would have cut v0.2.0. runicnpc-rust#18 (`feat!:`, with a `BREAKING CHANGE:` footer) changed only the README, and made the cutover cut v1.0.0. The API stays 6 (2026-10-09). | Accept v0.2.0 and change the plan's wording. |
+| **D331** | **A kit's extra is found by its item definition when it has no held entity.** Rust's November 2026 build adds the server variable `ItemModEntity.playerOnlyEntityBeltOnly` (on by default): an item Rust marks player-only, the medical syringe among them, has a held entity only while it is in the belt. A kit puts its syringes in the main inventory, so D260's heal, which looked for an item whose held entity is a `MedicalTool`, found none and never healed (runicnpc-rust#20). Every extra (heal, melee, flamethrower, grenade, rocket) now reads the held entity when there is one and the item definition's entity prefab when there is not; holding the item moves it to the belt, where Rust makes its entity. A full belt means no heal, not an error. The org lead chose all five extras over heal alone (2026-11-02). | Fix the heal alone. |
 
 **Borrowing, not copying.** NpcSpawn states no licence at all, so its source grants us nothing and is read only as a
 description of *what* can be done in Rust. HumanNPC is MIT on uMod, which is GPL-compatible, but §1.2 rules out its
@@ -1774,7 +1775,34 @@ found below; two checks are not explained yet (the last item).
   answer in 70 s, D268) and `s5.kit.heal` (healer at health 75 with both syringes unused). Neither left a line in
   Oxide's log, and `s5.fight.factions` and `s5.fight.marked` passed, so the hurt path works. They are re-run on the
   fixed harness with fresh data before anything in the plugin changes for them. That example kits written once
-  keep an older Rust's item condition on a real server is runicnpc-rust#21.
+  keep an older Rust's item condition on a real server is runicnpc-rust#21. Run 49 (build 26344826, #22) failed a
+  third: `s5.fight.leash`, the chase-8 NPC fighting a scientist 25 m off (D263).
+
+**9c, the three fight checks explained (2026-11-02, runicnpc-rust#20, #22).** Probes on `rust-staging` (Rust staging
+26344826, Oxide 2.0.7861 staging, Kits 4.4.10), with Rust's code compared between Oxide's public and staging builds,
+patched against patched, so only Rust's own changes show. Hurt, OnAttacked, Heal, MaxHealth, NPC targeting,
+`MedicalTool` and `ItemModConsumable` are unchanged.
+
+- **`s5.kit.heal` was Rust (D331).** The syringe in the healer's main inventory had no held entity
+  (`ItemModEntity.playerOnlyEntityBeltOnly`), so the heal found nothing and waited 15 s each time. With the fix,
+  on the same rig: heals 2, syringes left 0, health 145. It ships to `main` at the wipe with the field list;
+  without it every `kitUse.heal` NPC would have stopped healing on public Rust.
+- **`s5.fight.shootBack` was the harness.** On the drill's 3500 map (seed 1234), the fifth fight's two spots, 15 m
+  apart, have a cliff rock (`cliff_hills_large_e_arid`) between them: the bully never saw the victim, so never shot
+  it. In the open the victim took its attacker as its target within a second and fought back. Each fight's second
+  NPC now stands where each one's eyes see the other's centre, both ways, as RunicNPC's own line of sight runs:
+  north first, then the other seven ways round, with a note when it moves (harness 0.7.5). A first try traced eye
+  to eye and passed over the rock's edge. On this map the bully now stands 225° round, and the victim answers.
+- **`s5.fight.leash` did not come back** in three tries (the stage 5 group, the five fights laid out alone, and the
+  pair alone); the scientist stayed idle 25 m off and the NPC took no target. The likeliest way in: a target
+  learned from an ally's alarm (D256) or from being shot (D268) is kept while it is within the leash plus the
+  larger of its attack range and 10 m of home, 38 m here, while only a target its own sense finds is held to the
+  8 m. The harness now notes, the moment the check would fail, the NPC's target, its health and how far it and the
+  scientist are from its home, so the next failing run says which. The rule stays until then (org lead,
+  2026-11-02).
+- **With both fixes, on the next staging build** (26377229, out 2026-11-02; fields still 58/58, `added=-`, and
+  Oxide's 31 October staging build boots on it): stage 5 47 pass, 0 fail, and the whole harness 266 pass, 0 fail,
+  `place` included, so cf3997b's spots off the navmesh have now run live too.
 
 **9d. The player walk (D312).** Both rigs are updated first (Rust, Oxide, Carbon) and their builds stated. One
 checklist, published as a page, for one session per rig. I prepare the rigs, the walk site and a linked test