Release v0.2.0

.gitattributes

@@ -2,3 +2,12 @@
 *.bat text eol=crlf
 # Shell scripts stay LF
 *.sh text eol=lf
+# Release zips (GitHub "Source code" downloads and `git archive`) carry only the
+# game: development tooling stays in the repo for contributors and forks.
+tests/                export-ignore
+sim/                  export-ignore
+.github/              export-ignore
+requirements-dev.txt  export-ignore
+Makefile              export-ignore
+.gitattributes        export-ignore
+.gitignore            export-ignore

.gitignore

@@ -47,3 +47,6 @@ var/
 
 # Design docs are local-only working notes
 docs/
+
+# sim/tune.py writes its proposal here for a human to review; never committed
+data/difficulty.proposed.yaml

CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+Versions follow `0.MINOR.PATCH` while the game is in playtesting: a new MINOR
+for each release to `main`, a PATCH for a fix-only release. The version shows on
+the title screen and on the first line of `debug.log` (with the git commit next
+to it when run from a git checkout), so a screenshot or log names the build it
+came from.
+
+## v0.2.0 — 2026-09-30
+
+### ⚠ Saves
+Saves from v0.1 do not load. The flag hunt changed what a save holds; start a
+new game.
+
+### New: main menu and save slots
+- The title menu has **SETTINGS** (palette, text speed, reduce motion, hints),
+  now arrow-driven: ↑/↓ picks a row, ←/→ changes it. Ctrl+P opens the same screen in-game.
+- Every run has its own save slot (up to 9). **LOAD GAME** lists them with the
+  class, difficulty, level and where you are; Enter continues, `d` deletes.
+  Beaten runs are marked ✓. When all 9 are taken, NEW GAME asks which run to replace.
+- Saves from the old single pool become one slot per hero; the original files
+  are kept in `saves/legacy/`.
+- Leave a run for the main menu: `menu`, or **Save & main menu** / **Main menu
+  without saving** on the quit chooser (Ctrl+Q, Ctrl+C, `quit`). The game-over screen is now r (restore this
+  run) / m (main menu) / q (quit).
+- Fixed: Ctrl+Q or `quit` during a fight said "command not found"; it now asks
+  whether to keep fighting, go to the menu or quit.
+
+### New: capture the flag
+- Every directory hides a flag: 13 in the main tree, 5 more in secret
+  directories. Read one with `cat`, search a huge log with `grep`, or find a
+  rogue process with `ps` and end it with `kill`.
+- `/boot` (the final boss) opens once you hold 11 flags. `tree` and `journal`
+  count them, and capturing one saves a checkpoint.
+- Stuck in a room? `hint` nudges you, and asking again gives the exact command.
+  Echo teaches each new technique the first time you need it, and NPCs drop clues.
+- New commands: `grep` (with `-i` and `-n`) and `kill`.
+- The run recap shows your flags and a rank; capturing everything unlocks an
+  extra epilogue.
+
+### New: keys are earned
+- Keys are no longer scattered at random. The `/mnt`, `/var` and `/usr` flags
+  hand you the keys to `/usr`, `/etc` and `/srv`; bosses drop the rest. Every run
+  can be won.
+- A locked directory stays hidden until you hold its key, so the map unfolds as
+  you learn. `keys` lists what you hold.
+- `/opt` and `/srv` are open to every class, with a damage bonus for the class
+  whose trial it is.
+
+### Tutorial and story
+- The opening and the tutorial explain the goal: capture flags, earn keys,
+  open `/boot`. Skipping the tutorial still tells you.
+- The tutorial now teaches `ls -a`, `cat`, `ps` and `pwd`, gives you starter
+  armor before the first fight, and pins Echo's current instruction above the
+  input. Reading a memory file restores a memory and saves a checkpoint.
+- NPC dialogue changes with what you have done.
+- Picking up an item shows what it is, right under "Added … to your inventory".
+- A Character panel under Stats shows your class's model and the weapon and
+  armor you have on, with their numbers; an empty slot says how to fill it.
+- The class cards list each class's three moves, and the fight menu says which
+  moves heal you or weaken the enemy. When your HP runs low (and in-game hints
+  are on), the fight tells you which key heals.
+
+### Easier to type
+- Forgiving item names, Tab completion, and "Did you mean…" on typos.
+- Combat opens in Selection Mode: number keys attack, `0` flees.
+- Esc cancels a half-typed line instead of quitting.
+- Tab after `cd` completes the directories you can see (it completed nothing
+  before), and never a hidden or still-locked one.
+- Typing `equip`, `take`, `cd` and other exploring commands in a fight says
+  they work once the fight is over, instead of "command not found".
+
+### Look and feel
+- The version is on the title screen and on the first line of `debug.log`.
+- Seven rooms have their own backdrop art: the Archive, the Deprecated
+  Directory, `/root`, `/opt`, `/proc`, `/srv` and `/usr`.
+- One icon per item type in `ls`, `take`, `examine` and the inventory.
+- Cleared rooms get a ✓ in `ls`, the exits list and `tree` (`map` still works).
+- NPC sprites fill their box like everyone else's instead of shrinking.
+- F12 opens the logs; debug logging stays out of the terminal, and each launch
+  starts a fresh log.
+
+### Loot and saves
+- Gear can't drop as a second copy of something you already took.
+- Epic and legendary gear starts locked away instead of lying in `/`.
+- Loading an old save removes a stray copy of a key a flag now hands out.
+- The autosave pool is capped, so the saves folder no longer grows forever.
+
+### Balance
+- Capturing a flag restores you to full HP. Most deaths came from wear across
+  several fights, so runs are now much easier: the run simulator wins nearly
+  every run in every mode, and the earlier targets (about 95% easy, 83% medium,
+  68% hard) no longer apply. Harder modes still mean tougher, longer fights.
+- The Weaver is still the weakest class.
+
+### Fixes
+- The Inventory panel now updates during a fight (used items used to stay
+  listed until the fight ended).
+- The Legacy Backup really revives you, once, then tells you it's spent and how
+  many are left. Trying to `use` one in a fight explains that it works on its own.
+- The Inventory panel shows how much each healing item heals, and every attack
+  in the fight menu has an icon for its type (⚔ physical, ✨ magical, 🌿 nature).
+- `find /dev -name null` no longer names `/dev` before its door is revealed.
+- The Shaman's class card showed 100 HP and 8 damage; it really has 120 and 10.
+  Card numbers now come from the real stats.
+- The game-over screen no longer scrolls or shows stray markup, r/n/q work, and
+  it appears only when you actually die.
+- Saves keep your armor, status effects and difficulty, and defeated bosses no
+  longer come back to life (with fresh drops) when you load.
+- Hidden files show their leading dot, and Tab completes them.
+- The tutorial fight no longer ambushes players who skipped the tutorial, and
+  fleeing it no longer breaks the tutorial.
+- `talk` no longer crashes, and stray markup no longer shows up as text.
+- New installs start in player mode (some testers got the developer settings).
+- The Windows launcher is more robust, and players no longer install developer
+  tools or packages that fail to build on new Python versions.
+
+## v0.1-playtest — 2026-07-10
+
+The first playtest release: explore the haunted filesystem with real Unix
+commands, fight in Pokémon-style battles, pick a class and a difficulty.

README.md

@@ -11,46 +11,74 @@ piece together what happened — using real Unix commands (`ls`, `cd`, `cat`,
 `pwd`) as your only tools.
 
 The directories are real ones. `cd ..` walks up the tree, `ls -a` shows what is
-hidden, and a sealed directory stays sealed until you have permission to enter
-it — including permission on every directory above it. Type `man cd` and the
-game tells you what `cd` does in an actual shell, not just in here.
+hidden, and a locked directory doesn't even show up until you hold its key. Type
+`man cd` and the game tells you what `cd` does in an actual shell, not just in
+here.
+
+Every directory hides a flag. Some you just read with `cat`; some are buried in
+huge logs you'll need `grep` to search; some are rogue processes you find with
+`ps` and end with `kill`. Some flags hand you a key, and a new directory
+appears. Hold 11 flags and `/boot` — where the Daemon Overlord waits — opens.
+Stuck? Type `hint`.
 
 No prior command-line experience needed; the game teaches you as you go.
 
----
+What changed in each version: [CHANGELOG.md](CHANGELOG.md). The version you're
+running is on the title screen and on the first line of `debug.log`.
 
-![Exploring the Graveyard](./assets/screenshot-explore.svg)
-*Exploring the Graveyard — pixel scene view, live panels, ECHO guiding your first `ls`*
+---
 
-| Pokemon-style battles | Pick your difficulty |
-|---|---|
-| ![Battle](./assets/screenshot-battle.svg) | ![Difficulty](./assets/screenshot-difficulty.svg) |
+<img src="./assets/screenshots/explore.svg" alt="Exploring the Graveyard" width="100%">
+
+_Exploring the Graveyard — pixel scene view, live panels, ECHO's quick reference_
+
+<table>
+  <tr>
+    <th width="50%">Pokemon-style battles</th>
+    <th width="50%">Pick your difficulty</th>
+  </tr>
+  <tr>
+    <td><img src="./assets/screenshots/battle.svg" alt="Battle" width="100%"></td>
+    <td><img src="./assets/screenshots/difficulty.svg" alt="Difficulty" width="100%"></td>
+  </tr>
+  <tr>
+    <th>Continue any run — one save slot per run</th>
+    <th>Settings — right from the main menu</th>
+  </tr>
+  <tr>
+    <td><img src="./assets/screenshots/saves.svg" alt="Save slots" width="100%"></td>
+    <td><img src="./assets/screenshots/settings.svg" alt="Settings" width="100%"></td>
+  </tr>
+</table>
 
 ---
 
 ## Getting Started
 
-### Step 0 — get the game and go INTO its folder
+### Step 0 — download the game and go INTO its folder
 
-All commands below must be run **from inside the repo folder**:
+Download **`haunted-terminal-v0.2.0.zip`** from the
+[Releases page](https://github.com/NoHudd/hauntedTerminal/releases/latest),
+unzip it, then open a terminal in that folder:
 
 ```bash
-git clone https://github.com/NoHudd/hauntedTerminal.git
-cd hauntedTerminal
+cd haunted-terminal
 ```
 
-(Downloaded a ZIP instead? Unzip it, then `cd` into the unzipped folder.)
+All commands below must be run **from inside the game folder**.
 
 ### Quick Start (Recommended)
 
-From inside the repo folder, run the start script for your system:
+From inside the game folder, run the start script for your system:
 
 **On Mac/Linux:**
+
 ```bash
 ./start.sh
 ```
 
 **On Windows:**
+
 ```cmd
 start.bat
 ```
@@ -72,7 +100,7 @@ python main.py
 
 ---
 
-Full command list, classes, mechanics, tips, and project structure live in
+Full command list, classes, mechanics and tips live in
 **[REFERENCE.md](./REFERENCE.md)** — the game teaches all of it as you play,
 so treat that as a lookup, not required reading.
 
@@ -112,5 +140,3 @@ This project is licensed under the MIT License — see the LICENSE file for deta
                 ||----w |
                 ||     ||
 ```
-
-*Type `./start.sh` (Mac/Linux) or `start.bat` (Windows) to begin your journey.*

REFERENCE.md

@@ -18,6 +18,8 @@ one does in an actual terminal.
   `cd ..` for the parent, `cd` alone for home
 - `pwd` — print the directory you are in
 - `cat [file]` — read a file
+- `grep [word] [file]` — print only the lines of a file that contain a word
+- `kill [PID]` — end a process (find its PID with `ps`)
 - `tree` — show the filesystem you have discovered so far
 - `find [path] -name [pattern]` — search for a file
 - `ps` — list running processes
@@ -34,11 +36,13 @@ one does in an actual terminal.
 - `attack [enemy]` — start a fight
 - `inventory` / `inv` — view your items
 - `journal` — story memories you have restored
-- `keys` — key progression
+- `keys` — the keys you hold and the directories they open
+- `hint` — a nudge toward this room's flag; ask again for the exact command
 - `shortcuts` — item shortcuts and typing tips
-- `save` — save your progress
+- `save` — save your progress to this run's slot
+- `menu` — back to the title menu (save first, or leave without saving)
 - `quit` / `exit` — exit the game (offers to save). Ctrl+Q, Ctrl+C and ESC do
-  the same thing
+  the same thing; mid-fight they offer keep fighting / main menu / quit, without saving
 
 ### Combat
 
@@ -50,21 +54,21 @@ Selection Mode.
 
 The rooms form a real directory tree. You may `cd` to any path you have
 permission to reach — you are not limited to neighbours. Permission is needed on
-every directory along the way, so a sealed `/usr` also seals `/usr/games`.
+every directory along the way, so a locked `/usr` also hides `/usr/games`.
 
 ```
 /                       Root
 ├── bin/                The Armory — sacred command icons (cp, mv, rm)
-├── boot/               The Core — the Daemon Overlord waits here   [master_key]
+├── boot/               The Core — the Daemon Overlord waits here   [11 flags]
 ├── dev/                The Void — where deleted data accumulates   [sudo badge]
 ├── etc/                The Kernel Gate — the Firewall Knight        [chmod_key]
 ├── home/               The Graveyard — where you wake up
 ├── mnt/                Mount Forest — mounted drives
-├── opt/                Mage Tower               [opt_key, Weaver only, hidden]
+├── opt/                Mage Tower — the Weaver's trial     [opt_key, hidden]
 ├── proc/               Process Secrets
 │   └── self/           The Mirror Sector — the Sudo Trial            [hidden]
 ├── root/               Hidden Directory — ancient knowledge      [system_badge]
-├── srv/                Warrior Tomb           [opt_key, Guardian only]
+├── srv/                Warrior Tomb — the Guardian's trial           [opt_key]
 ├── usr/                The Arcane Library                            [lib_key]
 │   └── games/          The Game Gallery
 │       └── cowsay/     The Bovine Sanctuary — easter egg             [hidden]
@@ -74,7 +78,8 @@ every directory along the way, so a sealed `/usr` also seals `/usr/games`.
 ```
 
 Hidden directories do not appear until you find them. `ls -a` in the parent is
-the usual way; `find /dev -name null` and `ps` also reveal one each.
+the usual way; `ps` in Mount Forest also reveals one. A locked
+directory does not appear at all until you hold its key.
 
 ## Character Classes
 
@@ -109,14 +114,25 @@ an accuracy roll, so a miss is possible.
 - Each level costs 1.5x the previous one (100, 150, 225, …). There is no cap
 - Your difficulty setting scales the award
 
-### Permissions and keys
-- A sealed directory names the key it needs. Carrying that key opens it
-  automatically when you walk in
-- `lib_key` opens `/usr`, `chmod_key` opens `/etc`, `master_key` opens `/boot`,
-  `opt_key` opens the two class areas, `system_badge` opens `/root`
+### Flags
+- Every directory hides a flag (`FLAG{...}`): 13 in the main tree, 5 more in
+  secret directories
+- Capture one by reading its file with `cat`, searching a long file with
+  `grep FLAG [file]`, or ending a rogue process with `kill [PID]`
+- `tree` marks the rooms whose flag you hold with ⚑; `journal` counts them
+- Hold 11 main flags and `/boot` opens. Capturing a flag saves a checkpoint
+- Stuck in a room? `hint` nudges you, and asking again gives the exact command
+
+### Keys
+- Keys are earned, never found lying around: the `/mnt` flag hands you
+  `lib_key` (opens `/usr`), the `/var` flag `chmod_key` (opens `/etc`), and the
+  `/usr` flag `opt_key` (opens `/srv` and a secret)
 - The `sudo_privileges_badge`, earned by beating your Shadow Process in
-  `/proc/self`, opens `/dev`
-- Keys are placed so that a run is always completable
+  `/proc/self`, opens `/dev`; the `system_badge` from the Daemon Overlord opens
+  `/root`
+- A locked directory stays hidden until you hold its key; walk in with the key
+  and it opens
+- The chain always reaches 11 flags, so every run can be won
 
 ### Item Persistence
 - **Persistent items** survive death (weapons, armor, keys)
@@ -160,40 +176,3 @@ lean common, `/dev` favours epic, and `/` can produce legendaries.
 - Discover the Great ASCII Bovine easter egg
 - Defeat the Daemon Overlord in `/boot`
 - Reach the Archive and the Hidden Directory
-
-## Development
-
-### Debug Mode
-
-Copy `config/settings.example.py` to `config/settings.py` and flip:
-
-```python
-DEV_MODE = True
-DEBUG_MODE = True
-SKIP_INTRO = True
-```
-
-Contributors also need the dev tooling (pytest, mypy, ruff):
-
-```bash
-pip install -r requirements-dev.txt
-make check          # ruff + mypy + pytest + content validation
-```
-
-### Project Structure
-
-```
-main.py        # entry point → src.game_engine.main
-src/           # the running game: engine, world, player, combat, commands/, ui/, scene/
-engine/        # typed content schema + validation + headless test driver
-data/          # all game content as YAML — rooms/ enemies/ npcs/ items/ + classes/attacks/abilities
-assets/        # pixel-art sprites and backdrops (PNG)
-sim/           # difficulty simulation harness
-config/        # dev settings (settings.py gitignored)
-tests/ · utils/
-```
-
-Adding content is a matter of dropping a YAML file into the matching `data/`
-directory and running `python -m engine.validate data`, which fails loudly on a
-dangling reference, a duplicate path, or a room whose parent directory does not
-exist.