Implement proxy weapon animation sync for ranged guns

Milestone 1: Proxy actors now equip remote players' right-hand weapons and play armed idle/locomotion poses when weaponDrawn=true. Adds rightHand weapon slot to equippedItems protocol, weapon graph variable support (iSyncGunDown: 0=drawn, 1=holstered), and weapon FSM events (weaponDraw, readyStateEnter, gunDownStateEnter). Fixes two critical animation state churn bugs: frustum-visibility flicker no longer resets animation state on every update tick, and idle proxies no longer register as changed on every frame. Includes WeaponBehavior graph loading via AIProcess::RequestLoadAnimationsForWeaponChange() and manual weapon attachment fallback. New docs/weapon-animation-sync.md reference guide maps animation events and variables from F4-Animation-Research. Experimental alert-state reassertion for armed proxies to test NPC combat state gating of weapon-ready poses.

protocol/packets.md

@@ -71,7 +71,8 @@ Example after server processing:
   "movementSpeed": 186.4,
   "equippedItems": [
     { "slot": "body", "formId": "0001F66A" },
-    { "slot": "headband", "formId": "" }
+    { "slot": "headband", "formId": "" },
+    { "slot": "rightHand", "formId": "0001F4A6" }
   ],
   "appearance": {
     "version": 3,
@@ -154,10 +155,21 @@ eyes
 scalp
 ```
 
-The first equipment-sync milestone sends only resolved `ARMO` form IDs and
-empty strings for unequipped tracked slots. Power armor, weapon models,
-condition, legendary instance data, tint/material overrides, and forms missing
-from the receiver load order are outside this packet extension.
+Tracked slots include 16 visible apparel BIPED slots (listed above) plus:
+
+```text
+rightHand            Right-hand weapon slot (WEAP form ID); optional
+```
+
+The equipment-sync milestones send resolved `ARMO` and `WEAP` form IDs and
+empty strings for unequipped tracked slots. Off-hand weapons, power armor,
+weapon condition, legendary instance data, tint/material overrides, and forms
+missing from the receiver load order are outside this packet extension.
+
+When `rightHand` is missing, receivers keep their existing proxy weapon. When
+present with an empty `formId`, the proxy is unequipped. When a `WEAP` form ID
+is not found locally, receivers log a throttled warning and skip equipping
+that weapon; the proxy continues with its current state and other sync intact.
 
 Appearance fields are optional and additive. When `appearance` is missing,
 receivers keep the proxy's existing/default body and face. When present, it is a

protocol/player-sync.md

@@ -127,8 +127,10 @@ player exists.
 - Transform packets include movement state data (`isMoving`, `movementSpeed`,
   `isSprinting`, `isSneaking`, `isJumping`, `weaponDrawn`).
 - Transform packets can include optional `equippedItems` snapshots for visible
-  clothing, armor, hats, and eyewear slots. The game-thread proxy controller
-  applies those snapshots after proxy 3D is loaded.
+  clothing, armor, hats, eyewear, and right-hand weapon slots. The game-thread
+  proxy controller applies those snapshots after proxy 3D is loaded. Weapons are
+  synced as optional `WEAP` form IDs; missing weapons or unresolved form IDs do
+  not block other equipment sync.
 - Transform packets can include optional `appearance` snapshots for best-effort
   body and face proxy visuals. The game-thread proxy controller applies supported
   fields after proxy 3D is loaded and defers race/gender switching.
@@ -136,7 +138,8 @@ player exists.
   `COVault109` solo cell.
 - The game-thread proxy controller applies confirmed Havok animation graph
   variables to runtime proxy actors from that remote state (locomotion, sneak,
-  jump, weapon drawn). Transform position/heading sync is unchanged.
+  jump). Weapon-drawn state is parsed but animation application is implemented
+  separately (Phase 2 milestone). Transform position/heading sync is unchanged.
 
 ## Transform Cadence