diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9e818e4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,30 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a collection of small independant apps that help with the rules for Pathfinder 2E (Remastered).
+
+## Architecture
+
+Everything lives in `perception.html`: styles, markup, and JavaScript are co-located in one file. There are no external dependencies except Mermaid.js loaded from CDN.
+
+### Key structural areas in `perception.html`
+
+- **CSS custom properties** (`--bg`, `--surface`, `--border`, `--accent`, per-state color triplets `--c-<state>`, `--c-<state>-hi`, `--c-<state>-border`) drive the entire dark-fantasy color theme. Detection state colors: observed (green), hidden (amber), undetected (orange), unnoticed (red), concealed (blue), invisible (purple).
+
+- **Tab system** (`#stealth`, `#detection`, `#simulator`): three `<div class="tab-panel">` elements toggled by `showTab()`. The Situation Simulator is the default active tab.
+
+- **Sidebar** (`<aside id="sidebar">`): contains Detection Conditions reference cards. Hidden by default (`width: 0`), slides open with `.open` class via CSS transition. On mobile (≤640px) it becomes a fixed overlay with a backdrop (`#sidebar-overlay`).
+
+- **Mermaid diagrams**: Two flowcharts defined as raw text inside `<div class="mermaid">` elements, rendered programmatically on `DOMContentLoaded` via `mermaid.render()`. The stealth diagram (`#stealth-diagram`) is LR-oriented; the detection diagram (`#detection-diagram`) is TD-oriented.
+
+- **Situation Simulator**: A client-side state machine driven by two data objects:
+  - `SIM_STATES` — maps state keys (`OBSERVED`, `HIDDEN`, `UNDETECTED`, `UNNOTICED`) to display labels, CSS classes, and effect descriptions.
+  - `SIM_ACTIONS` — maps state keys to arrays of possible actions, each with optional roll outcomes that transition to a new state.
+  - State is held in `simCurrentState` and `simHistory`. `simSetState()` resets; `simSelectAction()` handles immediate or roll-based transitions; `simSelectOutcome()` resolves roll outcomes.
+
+## Resources
+
+`resources/rules/all.md` contains the full PF2e rules text (gitignored from commits). `resources/diagrams/` contains reference image files. These are reference-only and not served.