From 812630b8bd2260afbf34f536f0a8836426ba6132 Mon Sep 17 00:00:00 2001
From: Justin Bennett <oss@just-be.dev>
Date: Tue, 23 Sep 2025 00:22:00 -0400
Subject: [PATCH] Add CLAUDE.md with code guidance and architecture overview

Create CLAUDE.md to guide Claude Code on using mise tasks,
running scripts, and understanding the solitaire game's architecture.
Document state management, controls, layout, card system, and dependencies
to improve maintainability and onboarding.
---
 CLAUDE.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3c998c3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- Always prefer to use a `mise` task when possible by running `mise run ...`. For instance, `mise run build`. If you need to invoke another command like `bun`, do so via `mise x --` like `mise x -- bun add`. Otherwise you'll get a not found error.
+
+### Available Scripts
+- `mise run build` - Compile TypeScript to JavaScript
+- `mise run dev` - Run the game in watch mode with hot reload
+- `mise run start` - Start the solitaire game
+- `mise x -- bun game` - Alternative way to start the game
+- `mise run format` - Format code using Biome
+- `mise run lint` - Lint and auto-fix code using Biome
+- `mise run release` - Release a new version using auto
+
+### Running the Game
+- `npx @zephraph/solitaire` - Run the published package
+- `mise run dev` - Run in development mode with hot reload
+
+## Architecture Overview
+
+This is a terminal-based solitaire game built with React (via @opentui/react for terminal rendering), TypeScript, and Zustand for state management.
+
+### Key Architecture Components
+
+**State Management (store.ts)**
+- Uses Zustand for global game state
+- Single store pattern with actions and derived state getters
+- Main state includes deck (CardState[]) and highlightedArea
+- Cards have area, position, rank, suit, faceUp, and selected properties
+- Four main areas: "stock", "waste", "foundation", "tableau"
+
+**Controls System (controls.ts)**
+- Three separate hook-based control systems:
+  - `useHighlightCardControls()` - Arrow key navigation between game areas
+  - `useStockControls()` - Space key to flip stock cards to waste pile
+  - `useSelectCardControls()` - Space key to select/move cards, flip face-down cards
+- Uses @opentui/react's useKeyboard hook for input handling
+
+**Game Layout (components/Board/)**
+- Board component renders four main game areas:
+  - Stock - Face-down deck pile
+  - Waste - Face-up cards from stock
+  - Foundation - Four suit-specific foundation piles (Ace to King)
+  - Tableau - Seven columns of cascading cards
+- Each area is a separate React component
+
+**Card System**
+- CardState interface defines card properties (rank, suit, position, area, faceUp, selected)
+- Helper functions for game logic (isCardMovableToTableau, isCardMovableToFoundation, etc.)
+- Standard 52-card deck generation with proper solitaire layout initialization
+
+### Key Dependencies
+- @opentui/react - Terminal-based React rendering
+- zustand - State management
+- es-toolkit - Utility functions (cloneDeep, last, etc.)
+- biome - Code formatting and linting
+
+The game follows standard Klondike solitaire rules with keyboard navigation using arrow keys for highlighting and space for selection/actions.
\ No newline at end of file