we have plans

1 files changed, 30 insertions, 0 deletions

diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..c942ce0
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,30 @@
+# CONTEXT
+
+## Canonical terms
+
+| Term | Definition |
+|------|------------|
+| **HP** | Physical health. Drops when a real Enemy attacks the Player. 0 = death. |
+| **Sanity** | Mental clarity (0–100%). Drops when the Player attacks a Hallucination or discovers a Hallucinated Pickup. Low sanity causes visual/auditory distortions and makes Hallucinations indistinguishable from real Enemies. |
+| **Weakness** | Hunger / exhaustion meter. Increases every Turn. At maximum, drains HP. Reduced by consuming Pickups (Food, Bandage, Pill). Drives hallucination frequency and screen darkness. |
+| **Heartbeat** | Monotonically increasing counter of Turns elapsed. Displayed in the HUD. Drives the rate at which Weakness accumulates. |
+| **Player** | The character controlled by the user. Moves tile-by-tile, attacks adjacent cells, manages an Inventory of Pickups. |
+| **Turn** | One discrete game step triggered by a Player action (move, turn, attack, use item). All Enemies act, and Weakness advances, on every Turn. |
+| **Enemy** | A real hostile entity pre-placed in the Maze. Moves toward the Player on its Turn and deals HP damage when adjacent. Blocked movement into an Enemy wastes the Player's turn and triggers an attack. |
+| **Hallucination** | A fake entity that looks like an Enemy. Walking onto a non-persistent Hallucination makes it vanish harmlessly. Attacking one drains Sanity and vanishes it. At critically low Sanity, Hallucinations become Persistent and do not vanish on attack. At greater Depth / lower Sanity, Hallucinations behave identically to real Enemies (patrol, chase). |
+| **Pickup** | An item placed in the Maze that the Player collects by walking onto its cell. Types: Food (`F`), Pill (`0`), Bandage (`+`), Weapon (`!`). |
+| **Hallucinated Pickup** | A Pickup that is not real. Appears in the Inventory normally but has no effect when used. Discovering one drains Sanity. |
+| **Weapon** | An equipped item that determines base damage when attacking. Has a continuous dice-roll for bonus damage (30% chance for +1, repeat on success). Auto-equips the best found Weapon. |
+| **Inventory** | A limited set of carried Pickups (4 slots). Displayed in the bottom-bar HUD. Items are used explicitly via a "use" key. |
+| **Maze** | The procedural grid of Walls, Passages, and an Exit staircase. A new Maze is generated for each Depth. |
+| **Depth** | The current dungeon floor number (infinite, increases by 1 on descending the Exit). Higher Depth means tougher Enemies, more Hallucinations, and darker visuals. |
+| **Exit** | The staircase cell that descends the Player to the next Depth. |
+| **Phantom Wall** | A Wall rendered by the engine where a Passage actually exists. The Player can walk through it. Frequency increases with low Sanity. |
+| **Phantom Passage** | A Passage rendered where a Wall actually exists. The Player cannot walk through it. Frequency increases with low Sanity. |
+| **Shifting Maze** | Cells of the actual Maze data that rearrange when the Player is not looking. Triggered at low Sanity. |
+| **Persistent Hallucination** | A Hallucination that does not vanish when walked onto or attacked. Occurs only at critically low Sanity (~<20%). The Player is blocked from moving onto its cell and must attack it repeatedly to dissipate it. |
+| **Attack** | The Player action (Space key) that strikes the adjacent cell ahead. Deals Weapon damage to whatever occupies that cell. |
+| **Room** | A rectangular open area (3×3 to 6×6 cells) in the Maze, generated by the rooms-and-corridors algorithm. Rooms provide space for combat maneuvering. |
+| **Corridor** | A 1–2 tile wide passageway connecting Rooms. |
+| **Message Log** | A single line in the HUD that displays the most recent game event (attack result, item use, blocked movement) for 2–3 Turns before fading. |
+| **Score** | Calculated on death: (Kills × 100) + (Depth² × 50) + (Weapon base damage × 500). Output to terminal. |