diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9946402
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# Open The Box
+
+A CLI box-opening game where curiosity is the engine and every box is a mystery. Built in C# on .NET 10 with a progressive interface that evolves as you play.
+
+> *Open a box. It contains another box. That one has a key. The key opens a chest. The chest holds a story fragment. The story unlocks a character. The character reveals a place. The place offers an adventure. The adventure rewards... a box.*
+
+## Features
+
+- **Progressive CLI** -- Start with bare `Console.ReadLine` numbered menus. Unlock colors, arrow-key navigation, panels, portraits, and full layouts by finding Meta Boxes.
+- **25+ box types** with weighted loot tables, conditional drops, and nested auto-opening boxes.
+- **9 interactive adventures** powered by [Loreline](https://loreline.app) scripting (Space, Medieval, Pirate, Contemporary, Sentimental, Prehistoric, Cosmic, Microscopic, Dark Fantasy).
+- **160+ items** -- cosmetics, materials, consumables, adventure tokens, lore fragments, fortune cookies.
+- **34 crafting recipes** across 16 workstation types.
+- **Auto-activation system** -- items interact automatically (key + chest, badge + adventure).
+- **Character customization** -- hair, eyes, body, legs, arms, tints with ASCII portrait.
+- **Bilingual** -- full English and French support (UI + adventures).
+- **Save/Load** -- JSON-based save files.
+- **Music Box** -- `Console.Beep` melodies (Windows).
+- **Fortune Cookies** -- 20 box-themed wisdom messages.
+
+## Architecture
+
+The game follows the **Black Box Sim** pattern ([Brian Cronin](https://www.youtube.com/watch?v=jhcHlg7YhPg)): strict separation between simulation and presentation.
+
+```
+Input (keyboard)
+      |
+      v
+  GameAction         -- command sent to the simulation
+      |
+      v
++----------------+
+| GameSimulation |   -- BLACK BOX: zero I/O, pure logic
+|  (GameState)   |
++-------+--------+
+        |
+        v
+   GameEvent[]       -- events describing what happened
+        |
+        v
++----------------+
+|   IRenderer    |   -- BasicRenderer (phase 0) or SpectreRenderer (phases 1-8)
++----------------+
+```
+
+The simulation never reads input or writes output. It receives actions and returns events. The game loop in `Program.cs` bridges input/renderer to simulation.
+
+## Prerequisites
+
+- **Windows 10/11**
+- **.NET 10 SDK** -- install via `winget install Microsoft.DotNet.SDK.10`
+
+## Setup
+
+```powershell
+git clone <repo-url>
+cd openthebox
+.\init.ps1
+```
+
+The init script will:
+1. Check for .NET 10 SDK (offers to install if missing)
+2. Download [Loreline](https://github.com/Loreline/loreline/releases) v0.7.1 DLL
+3. Restore NuGet packages (Spectre.Console)
+
+## Build & Run
+
+```powershell
+dotnet build
+dotnet run --project src/OpenTheBox
+```
+
+## Project Structure
+
+```
+openthebox/
++-- src/OpenTheBox/
+|   +-- Program.cs              # Entry point, game loop
+|   +-- Core/                   # Pure models, enums, no dependencies
+|   +-- Simulation/             # BLACK BOX: GameSimulation, engines, actions, events
+|   +-- Rendering/              # IRenderer, BasicRenderer, SpectreRenderer, Panels
+|   +-- Adventures/             # Loreline integration
+|   +-- Persistence/            # Save/Load
+|   +-- Localization/           # JSON string manager
++-- content/
+|   +-- data/                   # boxes.json, items.json, interactions.json, recipes.json
+|   +-- strings/                # en.json, fr.json
+|   +-- adventures/             # 9 themes, each with .lor + .fr.lor files
++-- docs/GDD.md                 # Game Design Document (French)
++-- init.ps1                    # Setup script
++-- global.json                 # Pins .NET 10 SDK
+```
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Runtime | .NET 10, C# 14 |
+| CLI rendering | [Spectre.Console](https://spectreconsole.net) |
+| Interactive fiction | [Loreline](https://loreline.app) (.lor scripts) |
+| Serialization | System.Text.Json |
+| Localization | JSON string tables + Loreline translation files |
+
+## License
+
+All rights reserved.