diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..356a945
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,49 @@
+# slaywithfriends
+
+multiplayer browser version of slay the spire, played with friends.
+
+## status
+
+building first playable slice: single ironclad combat encounter.
+see `docs/plans/2026-02-23-single-combat-plan.md` for implementation plan.
+
+## tech
+
+- bun (serve + test), biome (lint/format, 4 spaces)
+- vanilla js, es modules, no framework, no build step
+- html/css rendering (no canvas)
+- client-only for now, multiplayer later
+
+## project structure
+
+- `src/` - game engine modules (state, effects, combat, render)
+- `data/` - card/enemy/potion/relic json databases
+- `assets/` - video game card images (per-character dirs)
+- `StS_BG_assets/` - board game assets (playmats, boards, boss art, tokens)
+- `docs/` - rules, plans, design docs
+- `docs/rules.md` - index to rules docs
+- `docs/plans/` - design docs and implementation plans
+
+## rules
+
+the board game rulebook is the mechanical reference point. the video game
+assets give us card art. goal is a browser-based multiplayer experience
+where friends can play together — not a direct port of either version,
+but something that captures the core deckbuilding + encounter loop in a
+way that works for a group.
+
+- `docs/rules-canon.md` - canonical board game rules
+- `docs/rules-web-mvp.md` - what we're implementing
+- `docs/rules-web-delta.md` - known differences from canon
+
+## card data
+
+board game card values are source of truth (scaled down from video game).
+card data lives in `data/cards.json`. the video game wiki (wiki.gg) has
+structured data as a secondary reference but values differ.
+
+## commands
+
+- `bun run dev` - start dev server
+- `bun run check` - biome check + tests
+- `bun test` - run tests