plai_testr 0.1.1

data/lib/plai_testr/state/player_state.rb

@@ -0,0 +1,61 @@
+module PlaiTestr
+  module State
+    class PlayerState < Base
+      attr_reader :name, :score, :hand, :data
+
+      def initialize(name:, score: 0, hand: [], data: {})
+        @name  = name
+        @score = score.to_i
+        @hand  = hand.dup
+        @data  = data.dup
+      end
+
+      def self.from_h(data)
+        new(
+          name:  data['name'],
+          score: data.fetch('score', 0),
+          hand:  data.fetch('hand',  []),
+          data:  data.fetch('data',  {})
+        )
+      end
+
+      def apply_changes(changes)
+        return if changes.nil? || changes.empty?
+
+        @score = changes['score'] if changes.key?('score')
+        @hand  = changes['hand']  if changes.key?('hand')
+        @data.merge!(changes['data']) if changes['data']
+      end
+
+      # Full state — for checkpoints
+      def serialize
+        {
+          'name'  => @name,
+          'score' => @score,
+          'hand'  => @hand,
+          'data'  => @data
+        }
+      end
+
+      # Opponent-visible state — hand contents are hidden, only size shown
+      # Subclasses override to expose game-specific public fields (e.g. top stance card)
+      def serialize_for(observer)
+        return serialize if observer == @name
+
+        {
+          'name'      => @name,
+          'score'     => @score,
+          'hand_size' => @hand.length,
+          'data'      => public_data
+        }
+      end
+
+      private
+
+      # Override in subclasses to selectively expose data to opponents
+      def public_data
+        {}
+      end
+    end
+  end
+end

data/lib/plai_testr/version.rb

@@ -0,0 +1,3 @@
+module PlaiTestr
+  VERSION = '0.1.1'
+end

data/lib/plai_testr.rb

@@ -0,0 +1,61 @@
+require_relative 'plai_testr/version'
+require 'digest'
+require 'fileutils'
+require 'json'
+require 'net/http'
+require 'optparse'
+require 'socket'
+require 'stringio'
+require 'time'
+require 'uri'
+
+module PlaiTestr
+  DECIDER_ICONS = { 'LLM' => '🧠', 'BOT' => '🤖', 'RNG' => '🎲' }.freeze
+
+  class << self
+    attr_writer :sessions_dir, :reports_dir
+
+    def sessions_dir
+      @sessions_dir || File.join(Dir.pwd, 'sessions')
+    end
+
+    def reports_dir
+      @reports_dir || File.join(Dir.pwd, 'reports')
+    end
+
+    def games_dir
+      @games_dir || File.join(Dir.pwd, 'games')
+    end
+
+    def games_dir=(dir)
+      @games_dir = dir && File.expand_path(dir)
+    end
+  end
+end
+
+require_relative 'plai_testr/errors'
+require_relative 'plai_testr/config'
+require_relative 'plai_testr/model_settings'
+require_relative 'plai_testr/agents/ollama_client'
+require_relative 'plai_testr/agents/player_agent'
+require_relative 'plai_testr/agents/referee_agent'
+require_relative 'plai_testr/rules_loader'
+require_relative 'plai_testr/personas'
+require_relative 'plai_testr/reporter/think_log'
+require_relative 'plai_testr/reporter/report_builder'
+require_relative 'plai_testr/reporter/model_comparison'
+require_relative 'plai_testr/reporter/botrun_report'
+require_relative 'plai_testr/session/manager'
+require_relative 'plai_testr/session/frame_queue'
+require_relative 'plai_testr/session/runner'
+require_relative 'plai_testr/state/base'
+require_relative 'plai_testr/state/player_state'
+require_relative 'plai_testr/state/game_state'
+require_relative 'plai_testr/botrun'
+require_relative 'plai_testr/preflight'
+require_relative 'plai_testr/game'
+require_relative 'plai_testr/deck'
+require_relative 'plai_testr/event_log'
+require_relative 'plai_testr/names'
+require_relative 'plai_testr/generator'
+require_relative 'plai_testr/cli'

data/templates/app/.gitignore

@@ -0,0 +1,3 @@
+.bundle/
+games/*/sessions/
+games/*/reports/

data/templates/app/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+-I spec
+--default-path .

data/templates/app/AGENTS.md

@@ -0,0 +1,158 @@
+# Agent guide
+
+This app playtests tabletop games with [PlAI Testr](https://github.com/armahillo/plai_testr). Local LLM players (via Ollama) and scripted bots play a game; every session produces a markdown report for the designer. If you are an AI assistant helping build or change a test harness here, read this first.
+
+## Start here
+
+When you open this project:
+
+1. Read this file, then `README.md`.
+2. Run `bundle exec rspec`. It is fast, needs no model, and shows the state of every game.
+3. Look at `games/`. Each game's `data/rules.md` is its rulebook, and `NOTES.md` (if present) holds rulings and open questions.
+4. Read the gem's docs when you need them. They ship with the installed gem, so they match the version in use; `bundle info plai_testr --path` prints its directory:
+   - `README.md`: every runner hook, the state classes, configuration
+   - `docs/frame_queue.md`: decisions inside decisions (attacks and responses, triggered effects), with a complete example
+   - `docs/referee.md`: yes/no rulings on free-text conditions by a second model, with an example
+   - `templates/examples/`: pristine copies of the example games, in case they were deleted from `games/`
+
+The example games show working patterns to copy:
+
+- `games/hearts`: 4 players, hidden hands, a pick-3 pass (`pick_range`), a session report section (`report_sections`), a botrun report subclass (`botrun_stats` + `Reporter::BotrunReport`), and personas whose bots play differently (`lib/hearts/bot.rb`, `data/personas.yml`, `data/bots.yml`)
+- `games/gin_rummy`: 2 players, engine-computed facts on every option, melds computed in plain Ruby (`melds.rb`), a bot (`lib/gin_rummy/bot.rb`) with a per-persona parameter (`knock_at` in `data/bots.yml`), and a **Simplifications** section in `data/rules.md`
+
+## Who you are working for
+
+The user is a game designer. The harness exists to tell them how their game plays, so:
+
+- Never change the game's rules to make the harness easier. When the rules are unclear or silent, ask the designer and record the answer (see *Rulings*).
+- Ask before running model games (`play`, `resume`, `preflight`) or pulling models: they take minutes to hours and use the machine. Specs and `botrun` are fast and safe to run.
+- Bot results describe how the bot plays, not how people play. Say so when reporting them.
+
+## Layout
+
+```
+games/<name>/
+  lib/<name>.rb             Requires the game and calls PlaiTestr.register
+  lib/<name>/game.rb        Constants
+  lib/<name>/state/         GameState (and PlayerState) subclasses: what is stored, what each player may see
+  lib/<name>/session/runner.rb   The rules engine: steps, legal moves, effects, views, prompts
+  lib/<name>/bot.rb         Bot rules (bot_choice), included in the runner
+  lib/<name>/reporter/      Optional report classes
+  data/rules.json           Machine-readable rules: game name, version, player_count, card_deck, numbers the engine uses
+  data/rules.md             Rules text the model players read
+  data/personas.yml         Optional: shared strategy and play styles the model players follow
+  data/bots.yml             Optional: parameters the bot reads, per persona
+  NOTES.md                  Optional: open questions and unconfirmed engine choices
+  spec/                     The game's specs
+  sessions/ reports/        Output (gitignored)
+```
+
+Every file a game needs lives under `games/<name>/`, so a game is removed by deleting its directory. Keep it that way. Shared code goes in the plai_testr gem, not in another game.
+
+App-wide settings (the decision limit backstop, model, Ollama host, model settings) live in `config/plai_testr.rb`. A game can set its own `max_decisions:` and `model_settings:` in `PlaiTestr.register`.
+
+`bundle exec plai_testr generate game <name>` creates the skeleton. `games/hearts` (4 players, hidden hands, a pick-3 pass) and `games/gin_rummy` (2 players, draw/discard turns, engine-computed melds) are complete examples.
+
+## How a game runs
+
+Each turn the runner asks `next_player` who acts, builds a numbered menu from `legal_moves(player)`, and the player (model or bot) picks a number. `apply_action_effects` applies the chosen move's `action` to `@game_state`. The game ends when `status['game_over']` is true; set `status['winner']` and `status['end_reason']` too (`@game_state.apply_changes('status' => {...})`). A game that never ends is stopped at the decision limit with `end_reason: 'decision_limit_reached'`.
+
+Build each menu entry with `option(label, public: ..., log: ..., name => params)`:
+
+```ruby
+option('Play 3♣', public: 'played 3♣', play: { value: card['uid'] })
+# => { label: 'Play 3♣', public: 'played 3♣', action: { play: { value: 42 } } }
+
+def apply_action_effects(player, action)
+  case action
+  in { play: { value: uid } } then play(player, uid)
+  end
+end
+```
+
+`label` is what the acting player sees, `public` what other players see, `log` the short console text. The action has exactly one name; `value:` is the main parameter, and others sit beside it. Moves and actions use symbol keys (the runner converts hand-written string keys), so `apply_action_effects` and the bot rules can pattern-match them. The runner checks every menu before using it and raises `PlaiTestr::MoveError` for a misspelled key or a malformed action.
+
+A menu with one move is applied without asking anyone. `pick_range(player)` returning `[min, max]` turns the menu into a pick-N choice, applied as one action whose `value` lists the chosen moves' values: `{ pass: { value: [42, 17, 9] } }`.
+
+Randomness comes from `@rng`. It is reset for each decision from the seed and the decision number, so the same seed and the same choices always give the same game, interrupted or not.
+
+The gem's `README.md` (see *Start here*) lists every hook.
+
+## Building a harness: the order that works
+
+1. **Rules first.** Put the rules text in `data/rules.md` and the numbers in `data/rules.json`. Read them closely; list every gap or ambiguity and ask the designer before coding around it.
+2. **State.** Decide what lives in `data` (`@game_state.data`: decks, piles, step, active player). `status` belongs to the runner. Use stable ids (card `uid`s, fixed pile indexes); never re-index things players refer to. A GameState subclass can name its keys with readers (`def step = @data['step']`).
+3. **Steps.** Model a turn as a small state machine in `data['step']`. `legal_moves` and `apply_action_effects` switch on it.
+4. **Specs for the rules.** Before any model plays, write specs that set up a situation and check the menu (`legal_moves`) and the effects. This is where rules bugs are cheapest.
+5. **Bot rules.** Implement `bot_choice` so the game can play itself. Then `bundle exec plai_testr <game> botrun --games 1000` must finish with no crashes and sensible endings. Add a botrun spec over a few seeds.
+6. **Views and prompts.** Write `view_text_for`, `rules_text_for`, `turn_phase`, `debrief_questions`. Read a few prompts yourself (see *Checking a prompt*).
+7. **Model games.** With the designer's go-ahead: one game with `--mode hybrid` (the bot plays obvious moves), then `--mode llm`.
+
+## Designing what the model sees
+
+Small local models (4B–14B) play well only when the engine does the bookkeeping.
+
+- **The engine lists the legal moves; the model picks a number.** Never ask the model to name a card, type a move, or check legality.
+- **Put engine-computed facts on each option, never advice.** "Discard 9♥ (deadwood after: 31)" is a fact; "Discard 9♥ (best)" decides for the model and ruins the test.
+- **Generate views from state; never hand-write summaries.** Hand-written summaries leak hidden information or go stale.
+- **Show each player only what they may know.** Override `data_for(observer)` in GameState (and `serialize_for` in PlayerState) to hide decks and other hands. Log events with `log(text)`, and `log(text, to: player)` for private ones ("You drew the 2♠"); `recent_events_for` shows each player what they may see.
+- **Keep menus short.** Merge equivalent options (identical cards, interchangeable targets). Split one huge decision into steps.
+- **Hide safety caps from players.** Turn or hand limits that stop runaway games (`MAX_HANDS`, `max_decisions`) must not appear in views or rules text, or models play for the cap.
+- **Scope long rules.** If `rules.md` is long, `rules_text_for` can send only the sections the current step needs.
+- **Personas** (optional): `data/personas.yml` holds a shared `basic_strategy` and play styles under `personas`; each player gets one (`--personas a,b`, or at random) and its strategy goes into the system prompt. `data/bots.yml` holds parameters the bot policy reads with `bot_strategy_for(player)`, so botruns compare styles (see `games/hearts` and `games/gin_rummy`; the generated files explain the format). `botrun --personas all` cycles every arrangement and needs at least as many personas as seats.
+
+## Reports
+
+- `report_sections` adds markdown sections to each session report: game-specific tallies the designer cares about.
+- Debrief answers get their own section in each session report. A game that renders them itself in `report_sections` returns false from `report_debrief?`.
+- `botrun_stats` returns numbers for one bot game; a `PlaiTestr::Reporter::BotrunReport` subclass (registered as `botrun_report_class:`) turns them into sections with `extra_sections`. See `games/hearts`.
+- Keep the counters in `data` so they survive checkpoints and resume.
+
+## Bot rules
+
+`bot_choice(player, moves, pick: nil)` returns `nil` or `{ 'choice' => n, 'rule' => 'name', 'obvious' => bool }` (`'choices' => [...]` for pick-N). When the model never gives a valid answer, the runner plays the bot's choice instead (or a random legal move when there is none) and flags the turn.
+
+- Mark a rule `obvious` only when the move is never worse than any alternative. `--mode hybrid` plays obvious moves without calling the model, and the report scores the model against them.
+- Name rules after the idea (`duck`, `dump_queen`, `shed_deadwood`); the botrun report counts them.
+- Keep the bot simple and readable. It is a baseline and a crash test, not a strong player.
+
+## Rulings and simplifications
+
+- When the designer settles a rules question, add it to a **Rulings** section in `data/rules.md` (dated), so models and future readers see it.
+- When the harness deliberately simplifies a rule, list it in a **Simplifications** section in `data/rules.md` (see `games/gin_rummy`).
+- Keep open questions and engine choices the designer has not confirmed in `games/<name>/NOTES.md`, marked as unconfirmed, and move them into **Rulings** once settled.
+
+## Specs
+
+- Unit specs drive the runner directly: build it with `game.runner_class.new(game: game, players: game.players, seed: 1, mode: 'bot', persist: false, out: StringIO.new)`, call `setup`, arrange the state (`runner.game_state`, `runner.data`), and check `legal_moves` or the effects of `apply_action_effects`. Hooks are public, so specs call them directly. The examples' `spec/` folders show the pattern.
+- Every game keeps a botrun spec: a handful of seeds, no crashes, a winner every time.
+- Botruns never build prompts, so a bug in a view only shows up in a model game. Every game also keeps a spec that plays a few bot games and calls the prompt hooks (`view_text_for`, `rules_text_for`, `recent_events_for`, `persona_for`, `turn_phase`) on every turn; see *builds every prompt a model player would see* in the examples.
+- If `data/` is copied from another repository, add a spec that fails when the copy is behind.
+- `bundle exec rspec` runs every game; `bundle exec rspec games/<name>` runs one.
+
+## Checking a prompt
+
+```ruby
+# bundle exec ruby -e '...'
+require 'plai_testr'
+game   = PlaiTestr.load('hearts')
+runner = game.runner_class.new(game: game, players: game.players, seed: 1, mode: 'bot', persist: false, out: StringIO.new)
+runner.setup
+5.times { runner.play_turn }
+player = runner.next_player
+puts runner.persona_for(player), runner.view_text_for(player), runner.menu(player).map { |m| m[:label] }
+```
+
+## Commands
+
+```
+bundle exec plai_testr <game> botrun --games 1000 [--personas all]    Bots only; report in games/<game>/reports/
+bundle exec plai_testr <game> play [--seed 1] [--mode hybrid]         One model game, after preflight checks (ask first)
+bundle exec plai_testr <game> resume <session_id>                     (ask first)
+bundle exec plai_testr <game> compare | list | preflight
+bundle exec plai_testr generate game <name>
+bundle exec rspec
+
+--quiet shows only progress and the result; --verbose adds the raw model output (play) or every game (botrun).
+Set PLAI_TESTR_DEBUG=1 to see the full backtrace of an error.
+```

data/templates/app/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

data/templates/app/Gemfile.erb

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'plai_testr', '~> <%= version %>'
+
+group :development, :test do
+  gem 'rspec', '~> 3'
+end

data/templates/app/README.md.erb

@@ -0,0 +1,91 @@
+# <%= app_name %>
+
+Automated playtesting for tabletop games with [PlAI Testr](https://github.com/armahillo/plai_testr): local LLM players (via [Ollama](https://ollama.com)) and scripted bots play your game, and every session ends in a markdown report.
+
+## Quick start
+
+```sh
+bundle install
+
+# Bots only, no model needed: 100 games in a few seconds, then a report
+bundle exec plai_testr hearts botrun --games 100
+
+# One game with a local model (needs Ollama running; missing models are pulled)
+bundle exec plai_testr gin_rummy play
+```
+
+Reports go in `games/<game>/reports/`; resumable sessions in `games/<game>/sessions/`.
+
+## Commands
+
+```
+bundle exec plai_testr <game> play      [--seed N] [--model M] [--mode llm|hybrid|bot]  One game (random seed 1-100 unless given)
+bundle exec plai_testr <game> botrun    [--games N] [--personas all]                   Bots only, many games
+bundle exec plai_testr <game> resume    <session_id>                                   Continue an interrupted session
+bundle exec plai_testr <game> preflight                                                Check Ollama, pull and warm up models, lint
+bundle exec plai_testr <game> compare   [--since ID]                                   Compare models across sessions
+bundle exec plai_testr <game> list                                                     List sessions
+bundle exec plai_testr generate game <name>                                            Add a new game
+```
+
+`--quiet` shows only a progress line and the result; `--verbose` shows more. Ctrl+C once saves and stops after the current move (a botrun finishes its current game and reports); Ctrl+C twice quits immediately.
+
+Settings for the whole app (decision limit, model, Ollama host, context size) are in `config/plai_testr.rb`.
+
+## Layout
+
+```
+Gemfile
+AGENTS.md                 Guide for AI assistants helping build harnesses (CLAUDE.md points to it)
+config/plai_testr.rb      App-wide settings
+spec/spec_helper.rb       Loads every game under games/
+games/
+  hearts/                 Example: 4-player trick-taking
+  gin_rummy/              Example: 2-player rummy
+```
+
+Each game lives entirely in its own directory:
+
+```
+games/<name>/
+  lib/<name>.rb           Requires the game and registers it with PlaiTestr
+  lib/<name>/bot.rb       Bot rules: how a bot picks moves
+  lib/<name>/             Runner (rules engine), state classes
+  data/rules.json         Machine-readable rules: game name, version, player count, card deck
+  data/rules.md           Rules text the model players read
+  data/personas.yml       Optional: strategy and play styles for the model players
+  data/bots.yml           Optional: parameters for the bot rules
+  NOTES.md                Optional: open rules questions and unconfirmed engine choices
+  spec/                   The game's specs
+  sessions/ reports/      Output (gitignored)
+```
+
+## Working with an AI assistant
+
+`AGENTS.md` tells an AI coding assistant how this project works: where the docs are, how to build a harness, and what to ask you before doing. Claude Code reads it through `CLAUDE.md`; run `claude` in this directory and start talking.
+
+Some ways to start:
+
+- *Look around this project and tell me what's here and how to run it.*
+- *I want to playtest my game. The rules are in ~/designs/my_game/rules.md. Read them, list every rules question you have, then set up a harness for it.*
+- *Write bot rules for my_game so it can play itself, run a 1000-game botrun, and summarize the report.*
+- *Read the newest report in games/my_game/reports and tell me what it says about balance. Separate what might be the bot's habits from what might be the game.*
+- *The model players in my_game keep making the same bad choice. Show me the prompt they see and suggest how to make the menu clearer, without telling them what to pick.*
+- *I've ruled that a tie goes to the defender. Update the engine, add a spec, and record the ruling in data/rules.md.*
+- *Add personas to my_game: one player who races, one who blocks.*
+
+## Adding a game
+
+```sh
+bundle exec plai_testr generate game my_game
+```
+
+This creates the skeleton above. Fill in `data/rules.json` and `data/rules.md`, then implement the runner hooks (`setup`, `legal_moves`, `apply_action_effects`) and, optionally, bot rules in `bot_choice`. The examples show complete games; the [PlAI Testr README](https://github.com/armahillo/plai_testr#writing-a-game) lists every hook.
+
+`bundle exec rspec games/my_game` runs its specs. The generated botrun spec stays pending until the game can play itself to the end.
+
+## Removing a game
+
+Delete its directory: `rm -rf games/hearts`. Nothing else refers to it.
+
+Keep all of a game's files under `games/<name>/` so that stays true. If a game ever needs files somewhere else (for example `spec/<name>/`), add a rake task that removes them along with the game directory.

data/templates/app/config/plai_testr.rb

@@ -0,0 +1,15 @@
+PlaiTestr.configure do |config|
+  # config.max_decisions = 100_000
+  # config.player_model  = 'qwen3:8b'
+  # config.ollama_host   = 'localhost'
+  # config.ollama_port   = 11434
+  # config.model_settings = {
+  #   context_size:      8192,
+  #   long_context_size: 16_384,
+  #   menu_budget:       512,
+  #   think_budget:      8192,
+  #   debrief_budget:    1024,
+  #   referee_budget:    2048,
+  #   temperature:       0.6
+  # }
+end

data/templates/app/spec/spec_helper.rb

@@ -0,0 +1,25 @@
+require 'fileutils'
+require 'tmpdir'
+
+require 'plai_testr'
+
+PlaiTestr.load_config(File.expand_path('../config/plai_testr.rb', __dir__))
+PlaiTestr.games_dir = File.expand_path('../games', __dir__)
+PlaiTestr.names.each { |name| PlaiTestr.load(name) }
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.disable_monkey_patching!
+  config.warnings = true
+  config.order = :random
+  Kernel.srand config.seed
+end

data/templates/examples/gin_rummy/NOTES.md

@@ -0,0 +1,12 @@
+# Gin Rummy harness notes
+
+For the designer and anyone working on this harness. Model players never see this file.
+
+## Hidden safety caps
+
+- `MAX_TURNS` (120 turns in one hand): the hand is a draw, logged as an ordinary drawn hand and counted as `turn_cap` in `data['results']`. Small models can swap the same few cards through the discard pile forever; a 2026-10-17 qwen3:8b test went 155 turns in hand 1 before the draw options showed deadwood.
+- `MAX_HANDS` (50 hands): the game ends and the higher score wins (`hand_limit`).
+
+## Open questions
+
+- None yet.

data/templates/examples/gin_rummy/data/bots.yml

@@ -0,0 +1,18 @@
+# bot_strategy: parameters your bot (lib/<game>/bot.rb) reads (never shown to the model).
+#   Read them in bot_choice with bot_strategy_for(player).
+#   knock_at: 10
+#   lead_low: true
+#
+# bots: per-persona overrides, keyed by the persona's key in personas.yml.
+#   A key with no matching persona is an error.
+#   gin_hunter:
+#     <<: *bot_defaults
+#     knock_at: 3
+
+bot_strategy: &bot_defaults
+  knock_at: 10
+
+bots:
+  gin_hunter:
+    <<: *bot_defaults
+    knock_at: 3

data/templates/examples/gin_rummy/data/personas.yml

@@ -0,0 +1,26 @@
+# basic_strategy: shared strategy, injected into each persona with <<: *basics.
+#   complete_tricks: Points come only from tricks you win; count them before you lead.
+#   avoid_penalties: Discard high cards early, while they're hard to punish.
+#
+# personas: play styles, picked with --personas a,b (or at random). The key is
+#   the persona's name; every field under it is shown to the model. To override
+#   a basic_strategy item, reuse its key exactly; a new key adds an item.
+#   moon_shooter:
+#     <<: *basics
+#     avoid_penalties: Keep hearts and the Q♠ if you can take every trick.
+#   safe_player:
+#     <<: *basics
+#     goal: Finish every hand with as few points as you can.
+
+basic_strategy: &basics
+  near_melds: Keep cards that are close to melds (pairs, and two cards of one suit in a row); discard unmatched high cards (face cards count 10) early.
+  watch_discards: Taking the top discard shows your opponent what you are collecting. Watch what they take, and avoid discarding cards that fit it.
+  read_deadwood: Every option shows your deadwood after the move. Lower deadwood means a sooner knock and fewer points lost if your opponent knocks first.
+
+personas:
+  quick_knocker:
+    <<: *basics
+    goal: End hands early. Knock the first time your deadwood is 10 or less, before your opponent can improve.
+  gin_hunter:
+    <<: *basics
+    goal: Win big. Hold out for gin, or knock only with 3 or less deadwood, to earn the gin bonus and avoid undercuts. Knock sooner once the stock runs low.

data/templates/examples/gin_rummy/data/rules.json

@@ -0,0 +1,76 @@
+{
+  "game": {
+    "name": "Gin Rummy",
+    "version": "1.0.0",
+    "description": "A 2-player rummy game. Draw and discard to form melds (sets of 3-4 of a rank, runs of 3+ in a suit) and knock when your unmatched cards total 10 or less. First to 100 points wins.",
+    "player_count": { "min": 2, "max": 2, "default": 2 }
+  },
+
+  "points_to_win": 100,
+  "knock_limit": 10,
+  "gin_bonus": 25,
+  "undercut_bonus": 25,
+
+  "components": [
+    {
+      "name": "Deck",
+      "type": "card_deck",
+      "count": 52,
+      "description": "Standard 52-card deck. Aces are low (rank 1); face cards count 10.",
+      "values": [
+        { "name": "A♣", "rank": 1, "suit": "clubs" },
+        { "name": "2♣", "rank": 2, "suit": "clubs" },
+        { "name": "3♣", "rank": 3, "suit": "clubs" },
+        { "name": "4♣", "rank": 4, "suit": "clubs" },
+        { "name": "5♣", "rank": 5, "suit": "clubs" },
+        { "name": "6♣", "rank": 6, "suit": "clubs" },
+        { "name": "7♣", "rank": 7, "suit": "clubs" },
+        { "name": "8♣", "rank": 8, "suit": "clubs" },
+        { "name": "9♣", "rank": 9, "suit": "clubs" },
+        { "name": "10♣", "rank": 10, "suit": "clubs" },
+        { "name": "J♣", "rank": 11, "suit": "clubs" },
+        { "name": "Q♣", "rank": 12, "suit": "clubs" },
+        { "name": "K♣", "rank": 13, "suit": "clubs" },
+        { "name": "A♦", "rank": 1, "suit": "diamonds" },
+        { "name": "2♦", "rank": 2, "suit": "diamonds" },
+        { "name": "3♦", "rank": 3, "suit": "diamonds" },
+        { "name": "4♦", "rank": 4, "suit": "diamonds" },
+        { "name": "5♦", "rank": 5, "suit": "diamonds" },
+        { "name": "6♦", "rank": 6, "suit": "diamonds" },
+        { "name": "7♦", "rank": 7, "suit": "diamonds" },
+        { "name": "8♦", "rank": 8, "suit": "diamonds" },
+        { "name": "9♦", "rank": 9, "suit": "diamonds" },
+        { "name": "10♦", "rank": 10, "suit": "diamonds" },
+        { "name": "J♦", "rank": 11, "suit": "diamonds" },
+        { "name": "Q♦", "rank": 12, "suit": "diamonds" },
+        { "name": "K♦", "rank": 13, "suit": "diamonds" },
+        { "name": "A♠", "rank": 1, "suit": "spades" },
+        { "name": "2♠", "rank": 2, "suit": "spades" },
+        { "name": "3♠", "rank": 3, "suit": "spades" },
+        { "name": "4♠", "rank": 4, "suit": "spades" },
+        { "name": "5♠", "rank": 5, "suit": "spades" },
+        { "name": "6♠", "rank": 6, "suit": "spades" },
+        { "name": "7♠", "rank": 7, "suit": "spades" },
+        { "name": "8♠", "rank": 8, "suit": "spades" },
+        { "name": "9♠", "rank": 9, "suit": "spades" },
+        { "name": "10♠", "rank": 10, "suit": "spades" },
+        { "name": "J♠", "rank": 11, "suit": "spades" },
+        { "name": "Q♠", "rank": 12, "suit": "spades" },
+        { "name": "K♠", "rank": 13, "suit": "spades" },
+        { "name": "A♥", "rank": 1, "suit": "hearts" },
+        { "name": "2♥", "rank": 2, "suit": "hearts" },
+        { "name": "3♥", "rank": 3, "suit": "hearts" },
+        { "name": "4♥", "rank": 4, "suit": "hearts" },
+        { "name": "5♥", "rank": 5, "suit": "hearts" },
+        { "name": "6♥", "rank": 6, "suit": "hearts" },
+        { "name": "7♥", "rank": 7, "suit": "hearts" },
+        { "name": "8♥", "rank": 8, "suit": "hearts" },
+        { "name": "9♥", "rank": 9, "suit": "hearts" },
+        { "name": "10♥", "rank": 10, "suit": "hearts" },
+        { "name": "J♥", "rank": 11, "suit": "hearts" },
+        { "name": "Q♥", "rank": 12, "suit": "hearts" },
+        { "name": "K♥", "rank": 13, "suit": "hearts" }
+      ]
+    }
+  ]
+}

data/templates/examples/gin_rummy/data/rules.md

@@ -0,0 +1,44 @@
+# Gin Rummy
+
+v1.0.0
+
+A card game for 2 players. Form melds, keep your unmatched cards (deadwood) low, and knock before your opponent does. The first player to 100 points wins.
+
+## Cards
+
+A standard 52-card deck. Aces are low: A-2-3 is a run, Q-K-A is not. Face cards count 10, aces 1, and number cards their number.
+
+## Melds
+
+- **Set:** 3 or 4 cards of the same rank (7♣ 7♦ 7♥).
+- **Run:** 3 or more cards in a row of the same suit (4♠ 5♠ 6♠).
+
+A card can belong to only one meld. Cards that are in no meld are **deadwood**.
+
+## Each hand
+
+1. **Deal.** Each player gets 10 cards. The next card is turned face up to start the discard pile; the rest is the face-down stock. The player who did not deal goes first.
+2. **Turn.** Draw one card, either the top card of the stock or the top card of the discard pile. Then discard one card face up. You may not discard the card you just took from the discard pile.
+3. **Knock.** Instead of a plain discard, you may discard and **knock** if your deadwood after discarding totals 10 or less. Knocking with 0 deadwood is **going gin**.
+4. **Lay off.** After a knock, the knocker shows their melds. The other player shows theirs and may lay off deadwood cards onto the knocker's melds (adding to a set or extending a run). No laying off against gin.
+5. **Dead hand.** If the stock is down to 2 cards after a discard and nobody knocked, the hand is a draw and is dealt again.
+
+## Scoring
+
+- **Knock:** if the knocker has less deadwood, they score the difference.
+- **Undercut:** if the other player's deadwood (after laying off) is equal or less, they score the difference plus 25.
+- **Gin:** the knocker scores the other player's deadwood plus 25.
+
+The winner of a hand deals the next one. The first player to reach 100 points wins the game.
+
+## Simplifications in this version
+
+- Melds and lay-offs are arranged automatically to give each player the lowest deadwood.
+- There is no special first-turn offer of the upcard; the first player simply draws.
+- No box, line or game bonuses, and no Big Gin.
+
+## Strategy notes
+
+- Early on, keep cards that are close to melds (pairs, two cards in a row of one suit).
+- Taking from the discard pile tells your opponent what you are collecting.
+- Discard high deadwood (face cards) first; knock early when your deadwood is low.