Add a roadmap and reference file

docs/reference.txt

@@ -0,0 +1,61 @@
+slaywithfriends quick reference
+(text version of board game Reference.png)
+
+================================
+COMBAT ROUND
+================================
+
+PLAYER TURN
+  1. start of turn
+     - reset to 3 energy, 0 block
+     - draw 5 cards
+     - roll die
+     - resolve start-of-turn abilities
+  2. action phase
+     - discuss with team
+     - play cards, use potions
+  3. end of turn
+     - resolve end-of-turn effects
+     - discard hand
+
+ENEMY TURN
+  1. remove enemy block
+  2. enemy actions resolve
+  3. advance action cubes
+
+================================
+ICONS
+================================
+
+  /\    hit - deals damage
+  ()    block - prevents damage
+  /\+1  deal +1 damage on all hits
+  /\x2  deal 2x damage on all hits in next attack,
+        then remove one vulnerable token
+  /\-1  deal -1 damage on all hits,
+        then remove one weak token
+
+  vulnerable vs weak:
+    when a vulnerable target is attacked by a weak attacker,
+    they cancel each other out and one of both tokens is removed
+
+  *     area of effect - affects all enemies in a row and the boss.
+        on enemy actions, it affects all players.
+
+  [gem]  energy - used to play cards
+         colors: red (ironclad), green (silent),
+                 blue (defect), purple (watcher)
+
+  [chest] reveal 3 card rewards. add 1 to your deck or skip.
+  [star]  reveal 3 rare rewards. add 1 to your deck or skip.
+
+================================
+MAP NODES
+================================
+
+  enemies    put a die in each player's row
+  elite      put a cube in the bottom row
+  event      draw a ?
+  merchant   flip this board over
+  treasure   each player gains a relic
+  campfire   [rest] heal 3 hp, or [smith] upgrade a card

docs/roadmap.md

@@ -0,0 +1,198 @@
+# slaywithfriends roadmap
+
+overall progress tracker. references existing plans and design docs.
+
+key docs:
+- docs/plans/2026-02-23-single-combat-plan.md (implementation plan)
+- docs/plans/2026-02-23-single-combat-design.md (design decisions)
+- docs/rules-web-mvp.md (what we're building toward)
+- docs/rules-canon.md (board game source of truth)
+- docs/rules-web-delta.md (known differences)
+
+---
+
+## phase 0: foundation [done]
+
+project scaffold, core engine, first playable encounter.
+
+- [x] bun + biome project setup
+- [x] card data module (cards.js, starter deck)
+- [x] state module (combat init, draw, play, end turn)
+- [x] effect resolver (hit, block, status, draw, lose_hp)
+- [x] die roll + enemy action resolver
+- [x] combat orchestration (turn flow, win/loss)
+- [x] html shell + css layout + dev server
+- [x] render module (state to dom)
+- [x] main module (event handling, game loop)
+- [x] ironclad starter card image mapping
+
+## phase 1: data pipeline [in progress]
+
+extract all board game data into structured json.
+
+branch: data-pipeline-merge-and-assets
+- [x] extract ironclad cards from board game sheets
+- [x] extract silent cards
+- [x] extract defect cards
+- [ ] extract watcher cards (in progress - 8/~120 done)
+- [x] extract colorless cards
+- [x] merge per-character files into unified cards.json (410 cards)
+- [x] map card images: ironclad (118), silent (108), defect (106), watcher (8)
+- [x] extract enemy data (57 enemies across acts 1-4)
+- [x] switch cards.js to load full cards.json
+- [x] add data validation tests (cards + enemies schema)
+- [ ] 70 cards still missing image paths (28 ironclad, 20 silent, 22 defect)
+- [ ] potion data extraction
+- [ ] relic data extraction
+
+## phase 2: multiplayer state model [in progress]
+
+restructure engine for multiple players and enemies.
+
+branch: engine-multiplayer-state
+- [x] indexed players[] and enemies[] arrays
+- [x] backward-compat aliases for single-player code
+- [x] getEntity/setEntity abstraction in effects
+- [x] per-player draw/play/endTurn
+- [x] per-enemy combat resolution
+- [x] fix draw effect player index bug
+- [x] fix lose_hp semantics (damages caster)
+- [x] playersReady duplicate guard
+- [x] refactor playCard to options-based API
+- [x] enemy instanceId for multi-enemy encounters
+- [ ] enemy targeting logic (currently always player 0)
+- [ ] turn order for simultaneous play
+
+## phase 3: board game assets + ui
+
+use board game visual assets for an authentic feel.
+
+### icons (manual extraction needed - jared doing this)
+the Reference.png has all the game icons. plan:
+- [ ] extract individual icons from reference card (jared, manual)
+- [ ] try svg versions of icons
+- [ ] evaluate emoji as slottable icon alternatives
+- [ ] text version of reference card for image-free mode
+      (see docs/reference.txt)
+
+### board game art for ui
+StS_BG_assets/ has a wealth of material:
+- [ ] player boards (Player_Board_Ironclad.png etc) - character select / stats
+- [ ] playmats (Playmat.jpg, per-character variants) - combat background
+- [ ] boss art (front + back, normal + A9 variants) - encounter screens
+- [ ] enemy/elite card sheets - could crop individual enemy art
+- [ ] map tiles + tokens - for map navigation screen
+- [ ] hp tracker (HP_Tracker.png) - compact tens/ones component
+- [ ] status tokens (Token_Vulnerable.png etc) - inline status display
+- [ ] potion sheet (Potions.png) - potion inventory
+- [ ] relic sheets (Relics_Common.png, Relics_Boss.png)
+- [ ] shop image (Shop.png) - merchant screen
+- [ ] card back (Cards_Back.png) - draw pile / face-down cards
+- [ ] mini character portraits (Mini_Ironclad.png etc) - player indicators
+
+### card images
+- [ ] decide: crop individual cards from sheets vs use video game card images
+- [ ] or: combine all into single spritesheet for efficient loading
+- [ ] image-free fallback mode (text + icons only)
+
+## phase 4: full combat
+
+complete combat mechanics per rules-web-mvp.md.
+
+- [ ] all keywords: exhaust, ethereal, retain, scry, unplayable
+- [ ] area of effect (single row + boss)
+- [ ] multi-hit with correct token consumption
+- [ ] poison mechanic (max 30 across all enemies)
+- [ ] start-of-turn / end-of-turn trigger system
+- [ ] status cards (dazed, slime, burn, wound, void)
+- [ ] potion system (max 3, use/discard flow)
+- [ ] combat log (scrollable history of actions)
+
+## phase 5: character mechanics
+
+each character's unique systems.
+
+- [ ] ironclad: strength interactions, heal 1 hp end of combat
+- [ ] silent: shiv generation, poison limits/behavior
+- [ ] defect: orb channel/end-of-turn/evoke
+- [ ] watcher: neutral/calm/wrath stances + miracle tokens
+
+## phase 6: map + progression
+
+between-combat game flow.
+
+- [ ] map generation (acts 1-3 structure)
+- [ ] room types: encounter, elite, event, campfire, treasure, merchant, boss
+- [ ] deck building / card reward selection
+- [ ] upgraded card rewards, rare rewards
+- [ ] campfire: rest (heal) / smith (upgrade)
+- [ ] merchant: buy cards, remove cards, buy potions/relics
+- [ ] events (act-specific event decks)
+- [ ] relic system
+- [ ] act transitions
+- [ ] neow bonuses (run start)
+
+## phase 7: multiplayer
+
+the "with friends" part.
+
+- [ ] websocket server (bun serve)
+- [ ] lobby/room creation
+- [ ] simultaneous play during player turn
+- [ ] row-based enemy targeting across players
+- [ ] shared combat state sync
+- [ ] reconnection handling
+- [ ] spectator mode
+
+## phase 8: polish
+
+- [ ] animations (card play, damage, block, status)
+- [ ] sound effects
+- [ ] mobile touch optimization
+- [ ] save/load (persist run state)
+- [ ] ascension levels (A1-A20)
+- [ ] act 4 (corrupt heart)
+- [ ] daily climb mode
+
+---
+
+## asset inventory (StS_BG_assets/)
+
+game state / reference:
+- Reference.png - combat flow + icon glossary + map nodes
+- HP_Tracker.png - tens/ones hp dial
+- Ascension_Reference.png - ascension level modifiers
+- Kindling.png / Kindling_Back.png - campfire resource
+
+per-character:
+- Player_Board_{character}.png - stats/ability board
+- Playmat_{character}.png (+ Playmat.jpg generic)
+- Mini_{character}.png - small portrait
+- Cards_{character}.png / _Rare.png / _Start.png + upgraded variants
+
+enemies/bosses:
+- Enemies_Act{1-3}.png + _Back.png (+ Act1_First_Back.png)
+- Elites_Act{1-3}.png + _Back.png
+- Boss_Act{1-4}_{name}.png + variants (A9, Back, Summon)
+- Summons_Act{1-3}.png + _Back.png
+
+map:
+- Map.png, Map_Act{1-3}.png
+- Map_Token_{type}.png (Back, Camp, Elite, Empty, Encounter, Enemy, Shop)
+
+tokens:
+- Token_Block_5.png, Token_Gold_{1,5}.png
+- Token_Poison.png, Token_Poison_{5,10}.png
+- Token_Strength.png, Token_Strength_5.png
+- Token_Vulnerable.png, Token_Weak.png
+- Token_Shield.png, Token_Shiv.png, Token_Miracle.png
+- Status_Dazed.png, Status_Slime_Burn.png
+
+other:
+- Cards_Back.png, Cards_Colorless.png + upgraded
+- Curse.png, Curse_A5.png
+- Events.png, Events_Act{1-3}.png + _Back.png
+- Neows_Blessing.png + _Back.png
+- Potions.png + _Back.png
+- Relics_Common.png, Relics_Boss.png + _Back variants
+- Shop.png

docs/rules.md

@@ -1,7 +1,15 @@
-# rules docs index
+# docs index
 
 Use these files by intent:
 
+- `docs/roadmap.md`
+  - Overall project progress tracker.
+  - References all plans, tracks what's done and what's next.
+
+- `docs/reference.txt`
+  - Text version of the board game Reference card.
+  - Combat flow, icon glossary, map node types.
+
 - `docs/rules-canon.md`
   - Canonical rules reference based on `STS_KS_Rulebook.pdf`.
   - Use for correctness decisions.
@@ -16,3 +24,9 @@ Use these files by intent:
 
 - `docs/rules-legacy.md`
   - Previous condensed rules writeup kept for historical reference.
+
+- `docs/plans/2026-02-23-single-combat-plan.md`
+  - Step-by-step implementation plan for first playable encounter.
+
+- `docs/plans/2026-02-23-single-combat-design.md`
+  - Design decisions for single combat slice.