add proper readme.md

README.md

@@ -1,2 +1,74 @@
-# blackjack-theory-game
+# Blackjack Theory Trainer
 
+A desktop application for learning and practicing **basic blackjack strategy**. Built with Python and customtkinter, it drills you on the mathematically optimal play for every hand — hard totals, soft totals, and pairs — based on the dealer's upcard.
+
+## Features
+
+- **Interactive practice** — dealt random hands, you choose Hit, Stand, Double, or Split
+- **Instant feedback** — every action is evaluated against basic strategy with an explanation
+- **Scenario tracking** — decisions are categorized into hard totals, soft totals, and pairs
+- **Statistics** — track your accuracy and longest correct streak
+- **Streak notifications** — get notified when you lose a streak of 3+
+- **Visual card display** — rendered card images for a realistic feel
+- **Dark mode UI** — easy on the eyes during extended sessions
+
+## Tech Stack
+
+- **Python 3.10+**
+- **customtkinter** — modern, themed tkinter widgets
+- **Pillow** — card image rendering
+
+## Getting Started
+
+```bash
+# Clone the repository
+git clone https://git.kampmeierdev.com/kampmeierdev/blackjack-theory-game.git
+cd blackjack-theory-game
+
+# Create and activate a virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the application
+python main.py
+```
+
+## Usage
+
+1. You are dealt two cards (the dealer shows one upcard).
+2. Classify your hand and click the correct action.
+3. Green feedback = correct play; Red feedback = mistake with an explanation.
+4. Click **Next Round** to continue.
+5. Use the **Hint** button if you are unsure.
+6. Close the window to view your final session statistics.
+
+## Project Structure
+
+```
+blackjack-theory-game/
+├── gui/
+│   ├── components/       # UI subcomponents (cards, buttons, hints, stats, notifications)
+│   ├── gui.py            # Main GUI application window
+│   └── utils.py          # Image loading utilities
+├── images/cards/         # Card sprite PNGs
+├── blackjack_game.py     # Game state and statistics
+├── constants.py          # Suits and ranks
+├── game_logic.py         # Card dealing, hand evaluation, basic strategy rules
+├── main.py               # Entry point
+└── requirements.txt
+```
+
+## Basic Strategy Reference
+
+The decisions implemented in this trainer follow standard **blackjack basic strategy** for a multi-deck game where the dealer stands on soft 17 (S17) and doubling after splitting (DAS) is allowed. Notable rules:
+
+- **Hard totals**: Stand on 17+, hit on 12–16 vs dealer 7+, double on 11 always
+- **Soft totals**: Double A,6–A,7 vs dealer 3–6; stand on A,8+
+- **Pairs**: Always split Aces and 8s; never split 5s or 10s
+
+## License
+
+MIT