diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5653b35
--- /dev/null
+++ b/README.md
@@ -0,0 +1,136 @@
+# UE5 Modular Game Framework
+
+**A complete Blueprint architecture for first-person narrative horror games — and beyond.**
+
+This is a production-ready, modular game framework for Unreal Engine 5.5–5.7. It provides 135 self-contained Blueprint systems across 16 categories, plus a fully documented example game prototype ("Project Void"). Built Blueprint-first with 22 supporting C++ classes for performance-critical paths.
+
+---
+
+## What This Framework Covers
+
+### Foundation
+Game Instance kernel, Core GameMode, GameState, PlayerState, Function Library, Macro Library, GameplayTag registry (334 tags across 11 categories), and a unified C++/Blueprint interface library.
+
+### Player Simulation
+Health & damage resistance, Stamina with exhaustion states, Psychological Stress with 5 tiers (calm → catatonic), GASP-integrated Movement & Posture, Hiding & peek system, First-person Embodiment with arm IK, Camera state layers (FOV/offset per action), and Player Metrics tracking (accuracy, playstyle).
+
+### Interaction & World
+Raycast-based Interaction Detector, Physical Doors (open/close/lock/barricade), Puzzle Devices with state machines, Contextual Traversal (vault/mantle/slide via Motion Warping), Physics Drag (grab & throw objects), Usable World Objects (levers, valves, buttons), Diegetic In-World Displays (wristwatch, monitors).
+
+### Inventory & Items
+Grid-based Inventory with weight management, World Pickup actors with soft-reference mesh loading, Equipment Slots (weapon, tool, armor), Active Item quick-slots, Consumable use system, Item Combination crafting, Container inventories (chests, desks), Key Item tracking with loss protection, Document/Journal archive, and Collectible tracking with set bonuses.
+
+### Weapons & Combat
+Weapon Base with fire/holster/FX, Frame-driven Hitscan Firearms, Pellet-spread Shotguns, Melee combos with hit detection, Ammo pools with magazine management, Tactical & empty Reload, Recoil with recovery pattern, Damage Reception pipeline (resistance → shield → health), Hit Reactions (flinch/stagger/knockdown), Combat Feedback (hit markers, kill confirm), Death Cause tracking.
+
+### AI & Enemies
+Enemy Base character, AI Controller with Behavior Tree runner, State Machine (Patrol/Search/Combat/Flee), Alert System (suspicious → alerted → combat), Perception (sight, hearing, damage sense), Memory (last known locations, investigation), Behavior Variant selection (weighted random profiles), Patrol Path splines, Procedural Encounter spawners.
+
+### Narrative & Dialogue
+Narrative State Machine with chapter flags, Objective tracking (activate/complete/fail/branch), Dialogue Playback with VO & subtitles, Dialogue Choices with consequence branching, Cutscene Bridge with skip support, Lore Unlock system, Narrative Trigger Volumes, and a multi-factor Ending Accumulator.
+
+### Menus & HUD (14 widgets)
+Main Menu, Pause Menu, Settings Menu, Inventory Grid UI, Journal/Document Viewer, Diegetic HUD Frame (health, stress, stamina, compass), Interaction Prompt with hold progress, Notification Toasts, Objective Display, Screen Effect Controller (damage vignette, stress blur), Accessibility UI (subtitles, colorblind), Credits Screen, Splash Screen, Debug Menu. All coordinated by a menu-stack Subsystem.
+
+### Save & Persistence
+Save Manager Subsystem (auto-save, manual save, save slots), Checkpoint actors, Death Handling (normal death → respawn OR void-space death), Alt Death Space system, Persistent Corpses, World State Recorder (doors, items, enemies), Player Respawn with state restoration, Run History tracker, and `I_Persistable` interface for any actor.
+
+### Adaptive Environment & Atmosphere
+Dynamic Difficulty (metric-based scaling), Atmosphere State Controller (room tone, mood), Procedural Encounter generation, Adaptive Environment Director (room mutations, reality shifts), Light Events (flicker, dim, strobe, blackout), Memory Drift (visual/audio hallucinations tied to stress), Pacing Director (intensity bands: exploration → tension → combat → recovery), Playstyle Classifier (aggressive vs stealthy), Rare Events, Scare Events (anticipation → payoff → recovery).
+
+### MetaSounds Audio
+Single-entry-point Audio Manager Subsystem with 4 mix buses (SFX, Ambience, Music, Dialogue), Room Audio Zones that auto-switch reverb/occlusion on overlap, 8 gameplay-driven float parameters (heart rate, stress, fear, tension), and 7 acoustic presets (Outdoor, Small Room, Large Hall, Cave, Cathedral, Void, Padded Cell).
+
+### Enhanced Input
+Centralized Input Manager Subsystem with stack-based context switching, 5 priority-layered contexts (Default < Hiding < WristwatchUI < Inspection < UI), 30+ Input Actions, platform profiles (PC, Xbox, PS5), key rebinding with persistence, and input mode coordination with the UI layer.
+
+### Multiplayer Networking
+Server-authoritative replication model. All state mutations gated by `HasAuthority()`. Client→Server RPCs for requests, Server→Client `RepNotify` for state sync. Client-side prediction for cosmetic effects. Anti-cheat validation on all server-side state changes.
+
+### State Management
+Central State Manager (42 exclusive action states + 18 overlay states). All systems query `IsActionPermitted(Tag)` instead of checking other systems directly. Gating rules configured in a designer-editable Data Asset (no Blueprint changes needed). Force Stack pattern for death/cutscenes/void space. GASP liaison for movement→action state mapping. Vital signal tracking (Normal → Critical).
+
+### Polish & Tooling
+Tutorial system with contextual triggers, Loading screen with tips & progress, Credits screen, Analytics tracker (opt-in), Developer Cheat Manager (god mode, noclip, teleport, give item), Error Handler with crash recovery, FPS counter, Debug Menu (state viewer, AI debug, performance, audio).
+
+---
+
+## Example Game Prototype: "Project Void"
+
+A complete psychological horror FPS prototype demonstrating every system. Set in an abandoned asylum. All game content lives in `Content/Game/` — never modifying `Content/Framework/`.
+
+**Features built with this framework:**
+- 11-level scene flow (Splash → Menu → Asylum Entry/WardA/WardB/Basement/WardensOffice → Void Space → 3 Endings → Credits)
+- Full player character with 27 components wired together
+- 18 pickup items (weapons, tools, consumables, keys, documents, collectibles)
+- 4 held weapons (pistol, shotgun, flashlight, crowbar)
+- 3 enemy types with full AI (Patient, Orderly, Void Shade)
+- 4 main objectives + 3 side objectives with branching narrative
+- 3 endings determined by player choices, collectibles, sanity, and playstyle
+- 6 atmosphere profiles with room audio zones
+- 6 scare events with anticipation/payoff/recovery cycles
+- Void space alternate-reality death system
+
+---
+
+## Where to Find Things
+
+| You want to... | Go here |
+|---------------|---------|
+| **Understand the whole framework** | [`UE5_Modular_Game_Framework.md`](UE5_Modular_Game_Framework.md) — the full design document |
+| **See every Blueprint spec** | [`docs/blueprints/INDEX.md`](docs/blueprints/INDEX.md) — 135 system specs with wiring guides |
+| **Learn the architecture** | [`docs/developer/architecture-overview.md`](docs/developer/architecture-overview.md) — layers, communication patterns |
+| **Set up a project from scratch** | [`docs/developer/project-setup-migration.md`](docs/developer/project-setup-migration.md) |
+| **Build the example game** | [`docs/game/GAMEINDEX.md`](docs/game/GAMEINDEX.md) — 170+ assets, 21-phase build order |
+| **Read item build walkthroughs** | [`docs/game/item-flashlight.md`](docs/game/item-flashlight.md) — step-by-step Blueprint wiring |
+| **Check animation requirements** | [`docs/architecture/animation-catalog.md`](docs/architecture/animation-catalog.md) |
+| **Check sound/audio triggers** | [`docs/architecture/sound-catalog.md`](docs/architecture/sound-catalog.md) |
+| **Understand input system** | [`docs/architecture/enhanced-input-system.md`](docs/architecture/enhanced-input-system.md) |
+| **Understand state management** | [`docs/architecture/bpc-statemanager.md`](docs/architecture/bpc-statemanager.md) |
+| **Understand multiplayer** | [`docs/architecture/multiplayer-networking.md`](docs/architecture/multiplayer-networking.md) |
+| **Find Blueprint-only workarounds** | [`docs/architecture/blueprint-limitations-workarounds.md`](docs/architecture/blueprint-limitations-workarounds.md) |
+| **See the HUD architecture** | [`docs/architecture/hud-overview.md`](docs/architecture/hud-overview.md) |
+| **See the audio architecture** | [`docs/architecture/metasounds-audio-system.md`](docs/architecture/metasounds-audio-system.md) |
+| **See C++/BP implementation status** | [`docs/checklists/cpp-blueprint-status.md`](docs/checklists/cpp-blueprint-status.md) |
+
+---
+
+## Tech Stack
+
+- **Engine:** Unreal Engine 5.5–5.7
+- **Scripting:** Blueprint-Only (with 22 C++ support classes)
+- **Locomotion:** GASP (Ground Animation Strafing Platform) — read-only, extended via notifies
+- **Input:** Enhanced Input System — 30+ Input Actions, stack-based context switching
+- **Assets:** `UPrimaryDataAsset` for all content definitions
+- **State:** Central `BPC_StateManager` — 42 exclusive states, 18 overlay states, vital signals
+- **Animation:** GASP Motion Matching + 14 animation notifies
+- **Audio:** MetaSounds — 4 mix buses, room acoustic zones, gameplay-driven float parameters
+- **Networking:** Server-authoritative with client prediction
+
+---
+
+## By the Numbers
+
+| What | How Many |
+|------|:--------:|
+| Blueprint system specs | 135 |
+| C++ classes | 22 |
+| Widget Blueprints | 14 |
+| Blueprint Components | 80 |
+| Blueprint Actors | 11 |
+| Data Assets | 19 |
+| Game Instance Subsystems | 7 |
+| Interfaces | 3 |
+| Gameplay Tags | 334 |
+| Input Actions | 30+ |
+| Animation Notifies | 14 |
+| Architecture docs | 8 |
+| Developer docs | 12 |
+| Game prototype docs | 21 |
+| Example game assets | 170+ |
+
+---
+
+---
+
+*UE5 Modular Game Framework — Build faster. Stay modular. Never hardcode.*