docs: Update C++ integration guide and blueprint specifications for various systems, adding detailed setup instructions and clarifying implementation statuses

docs/developer/cpp-integration-guide.md

@@ -1,11 +1,62 @@
 # C++ Integration Guide — UE5 Modular Game Framework
 
-**Version:** 1.0 | **Generated:** 2026-05-20 | **Systems:** 12 C++ classes | **Pages:** Full per-system setup
+**Version:** 1.1 | **Generated:** 2026-05-21 | **Systems:** 22 C++ classes (12 full + 10 stubs) | **Pages:** Full per-system setup
 
 This guide covers every C++ class in `Source/PG_Framework/`. For each system: what Blueprint child to create, what Project Settings to change, what assets to assign, and how other systems call into it.
 
 ---
 
+## Quick Start — What to Do With Each C++ Class
+
+If you just want to know what action to take for each C++ class, start here. Detailed setup follows in the per-system sections below.
+
+| # | C++ Class | Status | **Exact Action to Take** |
+|---|-----------|--------|--------------------------|
+| 01 | `UDA_GameTagRegistry` | ✅ Full | Create a **Data Asset instance**: Right-click → Miscellaneous → Data Asset → pick `DA_GameTagRegistry`. Assign 11 Data Tables to `TagDataTables` array. |
+| 02 | `UFL_GameUtilities` | ✅ Full | **Nothing.** Static library — functions appear under `Framework\|Utilities` in every BP right-click menu. |
+| 03 | 9 `UInterface`s | ✅ Full | **Nothing to create.** On any BP actor: Class Settings → Interfaces → Add → type `UInteractable`, `UDamageable`, `ULockable`, etc. Events auto-appear. |
+| 04 | `UGI_GameFramework` | ✅ Full | Create **BP child**: Blueprint Class → All Classes → `GI_GameFramework`. Set `TagRegistry` in Class Defaults. Assign in Project Settings as Game Instance Class. |
+| 05 | `AGM_CoreGameMode` | ✅ Full | Create **BP child**: Blueprint Class → All Classes → `GM_CoreGameMode`. In Class Defaults → **"Classes"** section (inherited from AGameModeBase) → set all 4 class references. Assign in Project Settings as Default GameMode. |
+| 06 | `AGS_CoreGameState` | ✅ Full | Create **BP child**: Blueprint Class → All Classes → `GS_CoreGameState`. No config needed — replicated state works automatically. |
+| 07 | `UDA_ItemData` | ✅ Full | Create **Data Asset instances** (one per item): Right-click → Miscellaneous → Data Asset → `DA_ItemData`. Fill ItemTag, DisplayName, Icon, WorldMesh, Weight, ItemType, etc. See [game examples](../game/). |
+| 08 | `UBPC_HealthSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `MaxHealth`, `CurrentHealth`, `OnHealthChanged`, `OnDeath` dispatchers. Add `TakeDamage()`, `Heal()`, regen logic in BP. |
+| 09 | `UBPC_StaminaSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `MaxStamina`, `CurrentStamina`, `OnExhaustionStateChanged`. Add drain/regen/exhaustion logic in BP. |
+| 10 | `UBPC_StressSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `EStressTier` enum + `OnStressTierChanged` dispatcher. Add accumulation/decay/tier-transition logic in BP. |
+| 11 | `UBPC_MovementStateSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `CurrentMovementMode` GameplayTag + `OnMovementModeChanged` dispatcher. Add CMC reads, GASP bridge, posture detection in BP. |
+| — | `APC_CoreController` | 🟡 Stub | Create **BP child** → set in `GM_CoreGameMode` Class Defaults. Add `BeginPlay`: cast to `GI_GameFramework` → `GetSubsystem<SS_EnhancedInputManager>` → `PushContext(IMC_Default)`. |
+| — | `APS_CorePlayerState` | 🟡 Stub | Create **BP child** → set in `GM_CoreGameMode` Class Defaults. Add replicated variables (inventory, equipped items, narrative flags) with `OnRep_` handlers. |
+| 31 | `UBPC_InventorySystem` | ✅ Full | **Attach directly to player pawn** — no BP child needed. Add Component → `BPC_InventorySystem`. Set `GridWidth=8`, `GridHeight=5`, `MaxWeight=50` in Details panel. |
+| 35 | `USS_SaveManager` | ✅ Full | **Auto-created** by UE's subsystem system. Access from any BP: `FL_GameUtilities::GetSubsystemSafe<USS_SaveManager>()` or `Get Game Instance → Get Subsystem(SS_SaveManager)`. |
+| 72 | `UBPC_DamageReceptionSystem` | ✅ Full | **Attach directly to player/enemy pawns** — no BP child needed. Add Component → `BPC_DamageReceptionSystem`. Call `ApplyDamage(RawDamage, Causer, DamageType, HitLocation, HitDirection)`. |
+| 75 | `UBPC_HitReactionSystem` | 🟡 Stub | Create **BP child** → attach to player/enemy pawns. C++ provides `PlayHitReaction()` stub + `FlinchThreshold` + `RagdollThreshold`. Add animation selection/trigger logic in BP. |
+| 79 | `UBPC_ShieldDefenseSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `ShieldHealth`, `MaxShieldHealth`, `BlockAngle`, `bShieldBroken`. Add block/raise/lower/break logic in BP. |
+| 120 | `UDA_EquipmentConfig` | 🟡 Stub | Create **Data Asset instances** (one per equipment piece). C++ provides `FDamageTypeResistance` struct + `GetResistance()` query. |
+| 128 | `USS_EnhancedInputManager` | ✅ Full | **Auto-created** by UE. Access via `GetSubsystem<USS_EnhancedInputManager>()`. Call `PushContext()` / `PopContext()` / `SetInputMode()`. Create 22 IA_* + 5 IMC_* assets in editor. |
+| 130 | `UBPC_StateManager` | ✅ Full | **Attach directly to player pawn** (component slot 0). Assign `GatingTable` → `DA_StateGatingTable`. Every system calls `IsActionPermitted(Tag)`. |
+| 131 | `UDA_StateGatingTable` | 🟡 Stub | Create **Data Asset instance** — populate `GatingRules` with 37 rules (ActionTag, BlockedByState, bIsBlocked). C++ provides `FStateGatingRule` struct + `IsActionGated()`. |
+
+### What "Full" vs "Stub" vs "Auto-Created" Means
+
+| Term | Meaning | Example |
+|------|---------|---------|
+| **Full C++** | Complete gameplay logic compiled natively. The asset you create (BP child or Data Asset instance) is only for configuration — no logic to add. | `BPC_InventorySystem` — attach, set grid size, call `AddItem()` |
+| **C++ Stub** | C++ has the UCLASS shell, basic variables, and event dispatchers so the module can compile (other classes forward-reference it). You must add all gameplay logic in the BP child. | `BPC_HealthSystem` — C++ gives you `MaxHealth` + `OnDeath`. You add `TakeDamage()`, regen, death sequence. |
+| **Auto-Created** | `UGameInstanceSubsystem`. UE creates it automatically when GameInstance initializes. No spawning, no placement, no BP child needed. Access via `GetSubsystem<T>()`. | `SS_SaveManager`, `SS_EnhancedInputManager` |
+| **Data Asset Instance** | Not a Blueprint at all. Right-click → Miscellaneous → Data Asset → pick the C++ class. Fill in properties. Systems reference it by pointer. | `DA_Item_MedKit`, `DA_StateGatingTable` |
+
+### Interfaces: You Don't Build Them, You Implement Them
+
+All 9 interfaces (`I_Interactable`, `I_Damageable`, `I_Persistable`, `I_Lockable`, `I_Holdable`, `I_UsableItem`, `I_Toggleable`, `I_Adjustable`, `I_Inspectable`) are in C++. You do **not** create Blueprint interface assets.
+
+To use them on any BP actor:
+1. **Class Settings → Interfaces → Add** → type `UInteractable` (or `UDamageable`, etc.)
+2. **Compile** — the interface events appear in your Event Graph
+3. Override `Interact`, `Can Interact`, `Get Interaction Prompt`, etc.
+
+Other systems call these interfaces through C++ `BlueprintNativeEvent` functions — the framework never checks "Is this a BP_ItemPickup?" It checks "Does this implement I_Interactable?"
+
+---
+
 ## Setup Before You Start
 
 ### 1. Add Framework Module to Your Project