From af9133258c13bcbdc5e218d560fd749556d8bd19 Mon Sep 17 00:00:00 2001
From: Tim McCarthy <thoomfish@gmail.com>
Date: Tue, 9 Jun 2026 16:21:48 -0700
Subject: [PATCH] Add README

---
 README.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dc1fffe
--- /dev/null
+++ b/README.md
@@ -0,0 +1,140 @@
+# Rats with Gats Remote Play (`pirats`)
+
+A web-based remote play companion app for the tabletop roleplaying game **Rats with Gats** (where players roleplay as space-faring pirate rats, or "Pi-Rats"). The application manages lobbies, character creation, card mechanics, scene phases, obstacles, challenges, and player voting.
+
+It is built with **FastAPI**, **SQLModel** (SQLite database), **Jinja2 templates**, and **HTMX** for dynamic, real-time page updates.
+
+---
+
+## Features
+
+- **Game Lobby:** Create games and join as players via a unique game ID.
+- **Character Creation:** 
+  - Fill out the character profile (appearance, smell, catchphrase).
+  - Delegate custom "Like/Hate" relationship questionnaire cards to other crewmates (answering them for each other!).
+  - Draft three "Secret Pirate Techniques" which are automatically shuffled and swapped among players.
+  - Bind swapped techniques to Face Cards (Jack, Queen, King) for play.
+- **Dynamic Card Mechanics:**
+  - Automated 54-card deck shuffling and card drawing.
+  - Automatically matches card suits to thematic obstacles (Clubs for combat, Spades for stealth/cunning, Hearts for social/morale, Diamonds for nautical/athletics).
+- **Scene Management:**
+  - Assign roles (Pi-Rats or "The Deep" narrator).
+  - Dynamic challenge creation linking multiple active obstacles.
+  - Automatically handles card matching colors/values, automatic success when playing Face Card techniques, and Joker card triggers to discard/replace obstacles.
+- **Between-Scenes Voting:**
+  - Vote on crewmates to rank up.
+  - Toggle personal objectives (Get a Gat, Earn a Name, Die like a Pirate).
+
+---
+
+## Installation & Running
+
+This project supports standard Python package tools as well as Nix flakes.
+
+### Option 1: Standard Python Installation
+
+#### Prerequisites
+- Python >= 3.9
+- Virtual environment tool (optional but recommended)
+
+#### 1. Setup Virtual Environment (Optional)
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+#### 2. Install Package
+Install the package and its dependencies in editable mode:
+```bash
+pip install -e .
+```
+
+#### 3. Run the App
+Launch the FastAPI server using the installed package entrypoint:
+```bash
+pirats --host 0.0.0.0 --port 8000 --reload
+```
+Alternatively, run it with `uvicorn`:
+```bash
+uvicorn pirats.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Once running, access the web UI at [http://localhost:8000](http://localhost:8000).
+
+---
+
+### Option 2: Using Nix Flakes
+
+If you use the Nix package manager, this repository provides a complete environment.
+
+#### 1. Enter the Development Shell
+Includes Python, all runtime dependencies, and testing tools (`pytest`):
+```bash
+nix develop
+```
+
+#### 2. Run the Application
+Run the package directly from the flake:
+```bash
+nix run . -- --host 0.0.0.0 --port 8000
+```
+
+#### 3. Build the Application Package
+```bash
+nix build .
+```
+The executable will be located in `./result/bin/pirats`.
+
+---
+
+## Deploying as a NixOS Service
+
+The Nix flake exposes a NixOS module that configures the application to run as a systemd service with appropriate sandboxing.
+
+Add this flake to your system configuration and configure the service:
+
+```nix
+services.pirats = {
+  enable = true;
+  host = "127.0.0.1";
+  port = 8000;
+  databasePath = "/var/lib/pirats/rats_with_gats.db";
+  openFirewall = false; # Set to true to open ports in the firewall
+};
+```
+
+---
+
+## Running Tests
+
+Tests are written using `pytest`. 
+
+### Running with Pip
+```bash
+pytest
+```
+
+### Running with Nix
+```bash
+nix develop --command pytest
+```
+
+---
+
+## Project Structure
+
+```
+pirats/
+├── pyproject.toml         # Python package metadata and dependencies
+├── flake.nix              # Nix package, dev shell, and NixOS service module
+├── tests/                 # Unit and integration tests
+│   └── test_game.py       # Game logic and CRUD database test suites
+└── src/
+    └── pirats/            # Core Python package
+        ├── main.py        # FastAPI routes, HTTP endpoints, CLI entrypoint
+        ├── crud.py        # Core database CRUD, game mechanics, and transitions
+        ├── models.py      # SQLModel database tables (Game, Player, Obstacle, Challenge, Vote)
+        ├── cards.py       # Playing card parser, deck setups, and obstacle definitions
+        ├── templates/     # Jinja2 HTML pages and HTMX snippets
+        └── static/        # CSS styles and frontend assets
+```