commit b2a4f567042ebf328d38a15112a321256082c383
Author: Eric Christian <ray@oat.im>
Date:   Thu Apr 9 00:11:21 2026 -0500

    Add README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..40a0139
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# Stellar Conflicts
+
+A 2D multiplayer space combat game — think bullet hell meets persistent universe. Originally a Flash game, now rebuilt from scratch in Rust.
+
+## Where to Start
+
+**[`reforged`](https://git.oat.im/sc/reforged)** is the main repo. It contains the Godot project, workspace configuration, and pulls in all the crates below. Clone this one.
+
+## Architecture
+
+The game is split into independent crates, each in its own repo. Everything is Rust — there is no GDScript.
+
+| Repo | What it does |
+|------|-------------|
+| [`sc-core`](https://git.oat.im/sc/sc-core) | Stateless game simulation — types, defs, tick functions, wire protocol. The heart of the game. No engine dependency. |
+| [`sc-client`](https://git.oat.im/sc/sc-client) | Client session state — message handling, auth flow, account/hangar data. Pure Rust, no engine dependency. |
+| [`sc-godot`](https://git.oat.im/sc/sc-godot) | Godot rendering shell. Thin bridge between `sc-client` and the engine — spawns nodes, updates transforms, reads input. |
+| [`sc-ui`](https://git.oat.im/sc/sc-ui) | All UI — HUD, menus, radar, chat, docking screens. Godot nodes backed by `sc-client` state. |
+| [`sc-zoned`](https://git.oat.im/sc/sc-zoned) | Zone server. Runs the authoritative sim, relays messages between clients. |
+| [`sc-authd`](https://git.oat.im/sc/sc-authd) | Auth server. Accounts, squads, leaderboards, zone tokens. |
+| [`sc-overlord`](https://git.oat.im/sc/sc-overlord) | AI team commander. Spawns and directs NPC fleets, manages base capture strategy. |
+| [`sc-replicate`](https://git.oat.im/sc/sc-replicate) | Trait-based state replication. Derive macro that auto-syncs entity fields between server and clients. |
+| [`sc-dashboard`](https://git.oat.im/sc/sc-dashboard) | Admin dashboard. |
+| [`sc-decode`](https://git.oat.im/sc/sc-decode) | Packet decoder tool for debugging the wire protocol. |
+| [`sc-xtask`](https://git.oat.im/sc/sc-xtask) | Dev task runner (`cargo xtask serve`, `cargo xtask build`, etc). |
+
+## How it Fits Together
+
+```
+             ┌──────────┐
+             │ sc-core  │  stateless sim, shared types
+             └────┬─────┘
+        ┌─────────┼──────────┬──────────────┐
+        ▼         ▼          ▼              ▼
+  ┌──────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐
+  │sc-client │ │sc-zoned│ │sc-authd  │ │sc-overlord│
+  └────┬─────┘ └────────┘ └──────────┘ └──────────┘
+  ┌────┴─────┐
+  ▼          ▼
+┌──────────┐┌─────┐
+│sc-godot  ││sc-ui│   ← Godot lives here
+└──────────┘└─────┘
+```
+
+## Running Locally
+
+```bash
+git clone https://git.oat.im/sc/reforged.git
+cd reforged
+cargo xtask serve    # starts authd + zoned + overlord
+                     # then open godot/ in Godot 4.5
+```
\ No newline at end of file