diff --git a/README.md b/README.md
new file mode 100644
index 0000000..796baf8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+# SCICRAFT — The Dark Photon Protocol
+
+> *"The last signal of the Second Renegade Flight hums in your blood.
+> Rebuild the Lattice. The Protocol is never finished — only maintained."*
+
+SCICRAFT is a 140+ mod **NeoForge 1.21.1** kitchen-sink modpack with a
+sci-fi / Whovian story layer. A collapsed star-empire is leaking back into
+reality through the Dimensional Doors; you are a proto-Time-Lord engineer
+rebuilding the **Quantum Lattice** — the emitter of the Dark Photon Protocol
+— and holding the global **Corruption Tide** at bay.
+
+The entire pack is managed with **packwiz** and ships as two synchronized
+packs: a full client pack and a server-only pack.
+
+---
+
+## Features
+
+- **NeoForge 1.21.1 (21.1.248)** · packwiz v1.1.0
+- **Tech pillars:** Mekanism, Applied Energistics 2, Create, FastPipes,
+  Flux Networks, LaserIO, Modular Routers, Entangled
+- **Dimensions:** Dimensional Doors, Void Dimension, Deeper and Darker,
+  Stellaris (rockets to moon/mars/venus/mercury)
+- **Mobs & combat:** Born in Chaos, Mutant Monsters, Nyf's Spiders,
+  Better Combat, Simply Swords
+- **Building:** FramedBlocks, Chipped, Supplementaries, Architect's Palette,
+  Building Gadgets, Handcrafted, Every Compat
+- **Story layer:** KubeJS-driven lore — the Quantum Lattice, the global
+  Corruption Tide, Renegade Glass, a 9-node advancement phase tree
+- **QoL:** JEI, Jade, JourneyMap, Waystones, Curios, AppleSkin, IPN,
+  FTB Chunks/Quests
+- **Client stack:** Iris + Sodium (native NeoForge), Cull Leaves,
+  LambDynamicLights, Dynamic FPS, flywheel compat
+- **Server stack:** ModernFix, FerriteCore, ImmediatelyFast, Entity Culling,
+  BadOptimizations, Krypton Reno
+
+---
+
+## Requirements
+
+- **Java 21** (Adoptium Temurin 21 LTS recommended)
+- Client: ~12 GB RAM free, **4 GB VRAM** recommended (shader preset included)
+- Server: 8 GB RAM minimum
+- Disk: keep the world under **100 GB** total
+
+---
+
+## Directory layout
+
+```
+.
+├── server_pack/          # Server-only packwiz pack (137 mod files)
+├── client_pack/          # Full client packwiz pack (146 mod files)
+│   └── shaderpacks/      # Complementary Reimagined setup guide (4GB VRAM preset)
+├── kubejs/               # (generated inside each pack) story scripts + datapack
+├── tools/gen_textures.py # regenerates placeholder item/block textures
+├── SERVER_MASTER_GUIDE.md  # install, server.properties, JVM flags, operations
+├── STORY_CANON.md          # the lore bible — where story lives & how to extend it
+└── README.md
+```
+
+Both packs are identical except the client pack adds render/shader/visual
+mods. Keep them in sync after any change:
+
+```bash
+rm -rf client_pack/kubejs && cp -r server_pack/kubejs client_pack/kubejs
+```
+
+---
+
+## Install — server
+
+```bash
+git clone git@git.mithraic.cloud:ad3laid3/SciCraft.git
+cd SciCraft
+
+packwiz install --dir server_pack
+java -Xms2G -Xmx6G -jar server_pack/neoforge-21.1.248-installer.jar --installServer
+
+# accept EULA (server_pack/eula.txt), then launch with the recommended flags:
+java -Xms4G -Xmx8G -XX:+UseG1GC \
+  -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 \
+  -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC \
+  -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 \
+  -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 \
+  -jar server_pack/neoforge-21.1.248-server.jar nogui
+```
+
+Recommended `server.properties`: `view-distance=8`, `simulation-distance=6`.
+Full details in **SERVER_MASTER_GUIDE.md**.
+
+## Install — client
+
+```bash
+git clone git@git.mithraic.cloud:ad3laid3/SciCraft.git
+cd SciCraft
+packwiz install --dir client_pack
+```
+
+Add `client_pack` as a **packwiz** modpack in your launcher
+(Prism/ATLauncher/PolyMC) or use `packwiz serve` from `client_pack` and
+install via the Modrinth/packwiz installers. Drop a shaderpack into
+`client_pack/shaderpacks/` — see the README there for the 4 GB VRAM preset.
+
+> **Multiplayer:** players join with the **client pack**; the server runs
+> the **server pack**. Never put client-only mods on the server (see the
+> client-only list in SERVER_MASTER_GUIDE.md §2).
+
+---
+
+## The story (short version)
+
+1. **Dark photons are real** — a fifth force the Second Renegade Flight
+   harnessed. They are the binding force of the Door.
+2. **You are a proto-Time-Lord** — the only one who can read the Protocol.
+3. **The wound** — the Flight's seal on a collapsed star-empire is failing.
+   The Void Dimension is the leak; the Deeper and Darker is what answers.
+4. **The Protocol** — rebuild the Quantum Lattice and keep it online.
+5. **The Corruption Tide** — rises while Doors go unsealed (global, all
+   players share). Re-seal Doors at the Lattice with a Void Stabilizer.
+   No fail state — soft escalation only.
+6. **The Doctor connection is atmospheric only** — Renegade Glass,
+   *Per Spatium*, portal styling. Never plot-driving.
+
+Full canon, file map, and a 5-minute "add a story beat" workflow:
+**STORY_CANON.md**.
+
+---
+
+## License & credits
+
+Pack content is assembled for the SciCraft server. All mods belong to their
+respective authors. Original story text, scripts, and pack configuration are
+MIT licensed.