From e3c1f10233cc0924ff96a643c7c4c1f1278de3e3 Mon Sep 17 00:00:00 2001
From: Thomas Hallock <thomas@evolutioniq.com>
Date: Fri, 31 Oct 2025 10:54:02 -0500
Subject: [PATCH] docs(rithmomachia): Add concise one-page playing guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create quick start guide for competitive play with simple language.
Covers movement, capturing, harmonies, and winning conditions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../rithmomachia/PLAYING_GUIDE.md             | 134 ++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 apps/web/src/arcade-games/rithmomachia/PLAYING_GUIDE.md

diff --git a/apps/web/src/arcade-games/rithmomachia/PLAYING_GUIDE.md b/apps/web/src/arcade-games/rithmomachia/PLAYING_GUIDE.md
new file mode 100644
index 00000000..de99c327
--- /dev/null
+++ b/apps/web/src/arcade-games/rithmomachia/PLAYING_GUIDE.md
@@ -0,0 +1,134 @@
+# Rithmomachia Quick Start Guide
+
+**The Philosopher's Game** — Win by using math to capture pieces and build harmonies in enemy territory.
+
+---
+
+## Goal
+
+Arrange 3 of your pieces in enemy territory to form a **mathematical progression**, survive one opponent turn, and win.
+
+---
+
+## The Board
+
+- **8 rows × 16 columns** (columns A-P, rows 1-8)
+- **Your half:** Black controls rows 5-8, White controls rows 1-4
+- **Enemy territory:** Where you need to build your winning progression
+
+---
+
+## Your Pieces (24 total)
+
+Each piece has a **number value** and moves differently:
+
+| Shape | Symbol | Movement | Count |
+|-------|--------|----------|-------|
+| **Circle** | ○ | Diagonal (like a bishop) | 8 |
+| **Triangle** | △ | Straight lines (like a rook) | 8 |
+| **Square** | □ | Any direction (like a queen) | 7 |
+| **Pyramid** | ◇ | One step any way (like a king) | 1 |
+
+**Pyramids are special:** They have 4 face values. When capturing, you choose which face to use.
+
+---
+
+## How to Move
+
+1. **Click your piece** to select it
+2. **Click destination** to move
+3. Pieces cannot jump over others — path must be clear
+4. You can only move to an empty square OR capture an enemy
+
+---
+
+## How to Capture
+
+You can capture an enemy piece **only if your piece's value relates mathematically** to theirs:
+
+### Simple Relations (no helper needed):
+- **Equal:** Your 25 captures their 25
+- **Multiple/Divisor:** Your 64 captures their 16 (64 ÷ 16 = 4)
+
+### Advanced Relations (need one helper piece):
+- **Sum:** Your 9 + helper 16 = enemy 25
+- **Difference:** Your 30 - helper 10 = enemy 20
+- **Product:** Your 5 × helper 5 = enemy 25
+
+**Helpers** are your other pieces still on the board — they don't move, just provide their value for the math.
+
+The game will show you valid captures when you select a piece.
+
+---
+
+## How to Win
+
+### Victory Condition #1: Harmony (Progression)
+
+Get **3 of your pieces into enemy territory** forming one of these progressions:
+
+- **Arithmetic:** Middle value is the average
+  - Example: 6, 9, 12 (because 9 = (6+12)/2)
+- **Geometric:** Middle value is geometric mean
+  - Example: 4, 8, 16 (because 8² = 4×16)
+- **Harmonic:** Special proportion (formula: 2AB = M(A+B))
+  - Example: 6, 8, 12 (because 2×6×12 = 8×(6+12))
+
+**Important:** Your 3 pieces must be in a straight line (row, column, or diagonal), and all 3 must be in enemy territory.
+
+When you form a harmony, your opponent gets **one turn to break it**. If it survives, you win!
+
+### Victory Condition #2: Exhaustion
+
+If your opponent has no legal moves, they lose.
+
+---
+
+## Key Rules
+
+1. **White moves first**
+2. **No jumping** — paths must be clear
+3. **Can't capture your own pieces**
+4. **Helpers can be anywhere** on the board (not just adjacent)
+5. **Harmonies must survive one turn** to win
+
+---
+
+## Quick Strategy Tips
+
+- **Control the center** — easier to invade enemy territory
+- **Small pieces are fast** — circles (3, 5, 7, 9) can slip into enemy half quickly
+- **Large pieces are powerful** — harder to capture due to their size
+- **Watch for harmony threats** — don't let opponent get 3 pieces deep in your territory
+- **Pyramids are flexible** — choose the right face value for each situation
+
+---
+
+## Common Progressions to Know
+
+**Arithmetic** (easiest to spot):
+- 4, 6, 8
+- 6, 9, 12
+- 5, 7, 9
+
+**Geometric** (same ratio between values):
+- 4, 8, 16
+- 9, 27, 81
+
+**Harmonic** (trickiest):
+- 6, 8, 12
+- 3, 4, 6
+
+Practice spotting these patterns in your pieces!
+
+---
+
+## Ready to Play?
+
+1. Start by moving pieces toward the center
+2. Look for capture opportunities using the math relations
+3. Push into enemy territory (rows 1-4 for Black, rows 5-8 for White)
+4. Watch for harmony opportunities with your forward pieces
+5. Win by forming a progression that survives one turn!
+
+**Remember:** This is a game of mathematical warfare. Every number matters!