1 files changed, 59 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b224202
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# Orrery
+
+An ASCII sci-fi-fantasy game for the terminal: a loose wrapping around a few
+minigames (dungeon crawling, flying star systems, mining), with procedurally
+generated everything.
+
+```sh
+cargo run                         # play (a random universe)
+cargo run -- --seed 1312          # play a specific universe
+cargo run -- names                # print generated names, no TUI
+cargo run -- names --culture qaari -n 40
+cargo run -- ship --seed 1312 -n 2   # print the 2nd derelict you'd board
+cargo test
+```
+
+## Derelicts
+
+Press `d` on the title screen to board a derelict. Each one is a ship-shaped
+map: an engine room at the stern, a bridge at the nose, a spine corridor
+between them, and rooms either side (cargo holds, a reliquary, a med-bay...).
+You see only what your lamp reaches. Monsters stay dormant until they come
+into view, then hunt you.
+
+Walk over things to pick them up: `*` artifacts, `%` salvage, `!` medpatches
+(press `m` to use one). Walk back into the airlock `Θ` to leave with what
+you're carrying, which goes into your hold. If you die or abandon ship with
+`esc`, you lose what you were carrying, but your hold is safe.
+
+## Layout
+
+| File | What it does |
+| --- | --- |
+| `src/app.rs` | Game loop (fixed 30 Hz tick) and the scene stack |
+| `src/scenes/` | One file per screen. A scene handles keys, ticks and drawing, and returns a `Transition` (push, pop, quit) |
+| `src/seed.rs` | Stable seed derivation: the whole universe is a function of one `u64` |
+| `src/names/` | Name generator: per-culture syllables and templates, plus artifact names |
+| `src/dungeon/` | Map and tiles; `fov.rs` (sight), `ship.rs` (generating derelicts), `crawl.rs` (turn rules, monsters, loot) |
+| `src/term.rs` | Terminal setup, including the kitty keyboard protocol where supported |
+| `src/cli.rs` | Command-line arguments and `orrery names` |
+
+## Things to know
+
+- **Seeds must stay stable.** `seed::derive` and `seed::rng` give the same
+  output forever, and a test pins them. If you change them, every universe
+  and save file changes too.
+- **Names are tuned by ear.** Edit the syllable lists in `src/names/mod.rs`,
+  then run `cargo run -- names --culture <name> -n 40`.
+- **Held keys.** Only terminals with the kitty keyboard protocol report key
+  releases. The title screen shows whether yours does. Real-time controls
+  need a fallback for terminals that don't.
+- **Cells are about twice as tall as they are wide.** For geometry, either
+  double x, or draw on a braille `Canvas`, where the dots are roughly square
+  (the title screen's orrery does this).
+
+## Next
+
+1. System flight and asteroid mining
+2. Glue: galaxy map, ports, a market to sell salvage, scholars to identify
+   artifacts, quest templates