Record adventure mode phase 1 decisions

docs/adventure-mode-plan.md

@@ -29,6 +29,37 @@ Write down the rules needed for the first prototype, distinguishing firm contrac
 
 Use four ordered slots, readiness adjustable during puzzles, and reordering between puzzles. Givens produce no turns; ordinary one-square reveals do. Retain generated color assignments. Keep numerical values provisional.
 
+### Decisions
+
+- **Hints:** A stump revealed by Woodpecker or Owl is a normal turn with a collection, exactly like a player reveal. The player doesn't choose the region, so the pulse color can help or hurt. Squirrel and an Owl explanation without a reveal reveal nothing and produce no turn.
+- **Puzzle loss:** For the first version, losing a puzzle (running out of acorns) ends the adventure run. Adventure puzzles never get silver acorn mode by random selection; it is enabled only for a deliberate adventure reason.
+- **Freebies:** Adventure puzzles are generated without freebies (one-square regions or stumps revealed at the start), using the generator's existing `freebies: 0` setting, except when the adventure adds one for a plot reason.
+- **Abandonment and retries:** An adventure puzzle cannot be abandoned or retried; it ends only when solved, lost, or when the whole run is abandoned. The home screen has an Adventure Mode entry the player can exit and resume at any time, which neither ends the run nor quits the current puzzle. Regular puzzles are started, restarted, and resumed from the home screen independently of the adventure. There is one adventure slot. (This also answers phase 5's question: ordinary play and an adventure each keep their own unfinished puzzle.)
+- **Adventure death:** When the character dies, the current puzzle ends with the run and the player goes straight to the run summary. (This replaces the concept's "the puzzle always continues to completion" for adventure puzzles.)
+- **Stats:** Adventure puzzle solves are kept out of the main solve stats and times for now.
+- **Difficulty:** The first version uses 9×9 boards, starting with medium tier. Size and tier remain engine parameters.
+- **Equipment:** As recommended below: ordered slots, each pulse goes to the first eligible readied item, readiness toggles freely during puzzles without using a turn, and reordering happens between puzzles. The number of slots, and whether all are generic or some are restricted to certain kinds of items, is left to tuning (start with four generic slots).
+- **Timing:** Each turn resolves in a fixed order: the player's pulse first, then enemy actions and timed effects (such as poison) that are due, then all cooldowns, countdowns, and timed effects advance by one. The player's pulse resolving first is the "Millennium Falcon effect": a last-moment block, attack, or heal can land in the same turn an attack goes off. Block absorbs the next attack, then any remainder is lost, and it expires at round end. Cooldowns count turns and reset between rounds. Charges persist within a round and expire at its end unless an item says otherwise. Unfinished enemy countdowns carry into the next round unchanged. All numbers remain provisional.
+
+### Rules table
+
+| Event | Turn? | Collection? | Notes |
+|---|---|---|---|
+| Correct reveal | Yes | Yes, region color and size | Pulse resolves before enemy actions due that turn |
+| Wrong reveal | Yes | No | Costs an acorn |
+| Woodpecker or Owl reveal | Yes | Yes | Same as a correct reveal; region not chosen by the player |
+| Owl explanation without a reveal, Squirrel | No | No | |
+| Given stump at puzzle start | No | No | |
+| X marks, What if? mode | No | No | |
+| Readiness toggle | No | No | Free during a puzzle |
+| Equipment reordering | No | No | Between rounds only |
+| Leave for home screen | No | No | Adventure and puzzle resume later |
+| Puzzle solved | Round ends: completed | | Round-end resets apply; encounter may continue |
+| Acorns run out | Run ends | | |
+| Character dies | Run ends | | Puzzle ends with it; straight to run summary |
+| New puzzle or retry | Not available | | Only abandoning the whole run ends an adventure puzzle early |
+
+
 ### Completion criteria
 
 A short rules table covers every player action and round-ending condition. Theme, campaign structure, and the full equipment catalog can remain open.
@@ -192,3 +223,12 @@ Apply versioning and changelog updates as required by `AGENTS.md`.
 The most consequential decisions to make first are hint behavior, puzzle-loss behavior, retry/abandonment rules, and the initial difficulty.
 
 Final theme, map generation, permanent progression, and exact win rates can wait for evidence from the sandbox. Timing and persistence contracts need explicit decisions before their implementation phases complete; equipment values and encounter numbers should continue to evolve through simulation and playtesting.
+
+## Ideas for later
+
+Ideas raised during planning, not yet part of any phase.
+
+- **Hint-based equipment and effects:** A weapon with a special attack that consumes one of the puzzle's hints, or a curse that disables hints.
+- **Silver acorn encounters:** Enable silver acorn mode (one acorn) for specific adventure reasons, such as a challenge room, a curse, or a special boss fight.
+- **Multiple adventure slots:** Keep more than one adventure run in progress at once.
+- **Varying puzzle sizes:** Offer a range of board sizes, perhaps driven by particular enemies or power-ups.

docs/adventure-mode-technical.md

@@ -1155,13 +1155,14 @@ The engine should avoid hardcoding decisions that are still under consideration.
 | Charge persistence | Configurable per ability |
 | Healing and economy | Limited by abilities and encounter context |
 | Encounter duration | Independent of round length |
-| Difficulty | Fixes size and tier (and so the colors available), possibly size mix |
+| Difficulty | Fixes size and tier (and so the colors available). First version: 9×9 medium |
 | Color identity | Palette index; hue comes from the theme |
 | Color assignment | Generator's random order; the adventure may reorder it per puzzle to tune difficulty |
 | What if? mode | Allowed; it reveals nothing, so it creates no turns |
-| Hint reveals | Undecided: a turn with a collection like a player reveal, a collection without a turn, or no collection. Hints may also be disabled in adventures |
-| Lost puzzle | Undecided. Stumped stops a puzzle when the acorns run out. The round ends as failed; retrying the same puzzle would offer the same collections again, so the adventure should start a new puzzle instead, or Stumped gains an adventure-only "keep going" rule |
-| Silver acorns | Off unless chosen as part of the adventure difficulty |
+| Hint reveals | Decided: a Woodpecker or Owl reveal is a turn with a collection, like a player reveal ([implementation plan](adventure-mode-plan.md), phase 1) |
+| Lost puzzle | Decided for the first version: running out of acorns ends the run. Adventure puzzles cannot be retried or abandoned ([implementation plan](adventure-mode-plan.md), phase 1) |
+| Silver acorns | Never chosen at random; only for a deliberate adventure reason, such as a challenge or curse |
+| Freebies | Off (`freebies: 0`) unless the adventure adds one for a plot reason |
 | Permanent progression | Characters, history, and variety rather than escalating power |
 | Trace-driven balance | Observed collection sequences as baseline |
 | Wrong turns | Exact events once recorded (section 11.5); synthetic otherwise |