plai_testr 0.2.0 → 0.2.1

data/docs/technical/runner.md

@@ -0,0 +1,158 @@
+# The runner
+
+A game's runner subclasses `PlaiTestr::Session::Runner`. The gem owns the decision loop; the runner supplies the rules through *hooks*, public methods the loop calls.
+
+## The decision loop
+
+Each decision:
+
+1. `next_player` says who acts.
+2. `@rng` is reseeded for this decision (see [Randomness](#randomness)).
+3. `legal_moves(player)` builds the menu, and `pick_range(player)` says whether it's a choose-one or choose-several decision. The gem checks the menu (see [Moves](#moves-and-actions)).
+4. Someone decides:
+   - A menu with one option is applied without asking anyone.
+   - Otherwise the model gets the persona, rules text, view, recent events and the numbered menu, and replies with a choice, its reasoning and its plan. In `--mode hybrid`, an *obvious* bot move is played without asking the model. In `--mode bot` and botruns, the bot decides.
+5. `apply_action_effects(player, action)` applies the chosen move.
+6. The game is saved, and the loop repeats until `game_over?`.
+
+Then each model player is debriefed (see [Debrief](debrief.md)) and the report is written.
+
+Registration ties the runner to the game's other classes, in `lib/<name>.rb`:
+
+```ruby
+PlaiTestr.register('hearts',
+                   runner_class:        Hearts::Session::Runner,
+                   game_state_class:    Hearts::State::GameState,
+                   botrun_report_class: Hearts::Reporter::BotrunReport,   # optional, see Reports
+                   players:             ['Player 1', 'Player 2', 'Player 3', 'Player 4'],
+                   recent_events:       12,                                # log lines per prompt (default 8)
+                   max_decisions:       5_000,                             # this game's decision limit
+                   model_settings:      { context_size: 12_288 })          # this game's model settings
+```
+
+`players` is the default seating when `rules.json` has no `player_count`. `comparison_class:` swaps in a subclass of `Reporter::ModelComparison` for `compare`.
+
+## Hooks
+
+| Hook | Required | Purpose |
+|---|---|---|
+| `setup` | yes | Build the starting state. Not called on resume. |
+| `legal_moves(player)` | yes | The menu: an array of `option(...)` entries |
+| `apply_action_effects(player, action)` | yes | Apply the chosen move's action to `@game_state` |
+| `view_text_for(player)` | expected | The player's view of the game, as text |
+| `debrief_facts(player)` | expected | Engine-counted facts for the debrief, as a Hash (default: `botrun_stats`; see [Debrief](debrief.md)) |
+| `next_player` | | Who acts next (default: alternate) |
+| `pick_range(player)` | | `[min, max]` to pick several options at once |
+| `game_over?` | | Default: `status['game_over']` |
+| `turn_phase(player)` | | Short step label for the console and report |
+| `rules_text_for(player)` | | Rules text (default: the game's `data/rules.md`; call `super` to extend it) |
+| `prompt_note_for(player)` | | A one-off note for this prompt |
+| `recent_events_for(player)` | | Recent events from the event log (default: the last 8 this player may see; `recent_events:` in `register`) |
+| `log_turn`, `log_turn_name` | | The number stamped on log entries and its name (default: the decision number) |
+| `persona_for(player)` | | Strategy text for the system prompt (default: built from `personas.yml`) |
+| `display_name(player)` | | Name in the console and reports (default: the persona's key, title-cased, else the player id) |
+| `bot_choice(player, moves, pick: nil)` | | Bot rules (see [Personas and bots](personas-and-bots.md)) |
+| `think_about?(player)` | | With `--think`: whether this turn gets thinking (default: every turn) |
+| `debrief_questions(player)` | | End-of-game feedback questions |
+| `debrief_view_for(player)` | | The final position the debrief reads (default: the result, final scores, `view_text_for` and the player's visible log) |
+| `debrief_summary(player)` | | Built by the gem, not overridden: the summary that opens each debrief prompt |
+| `report_sections`, `report_debrief?` | | Extra report sections; false to render the debrief yourself (see [Reports](reports.md)) |
+| `botrun_stats` | | Game-specific numbers for one botrun game (see [Reports](reports.md)) |
+
+Hooks are public, so specs can call them directly; the helpers below are private. Put your own helpers below `private` too. Avoid public helper names that could collide with future hooks.
+
+### Helpers
+
+Available inside hooks:
+
+| Helper | |
+|---|---|
+| `option(label, public:, log:, **action)` | Build a menu entry (see below) |
+| `menu(player)` | The menu as the runner sees it, after checking |
+| `data` | `@game_state.data`, the game's own state |
+| `log(text, to: nil)` | Add an event to the event log; `to:` makes it private to one player |
+| `event_log` | The log itself |
+| `players`, `pstate(player)` | Player names in seat order; one player's `PlayerState` |
+| `whose(player, viewer)` | "You" when the player is the viewer, else the player's name, for view text |
+| `tally(player, key, amount = 1)` | Count something per player in `data['tally']` (for facts and reports) |
+| `sole_leader(scores = @game_state.scores)` | The single highest scorer, or `nil` on a tie |
+| `persona(player)`, `persona_name(player)`, `bot_strategy_for(player)` | The player's persona key, its display name, its bot parameters |
+| `@rng`, `@rules`, `@game_state`, `out` | Random generator, parsed `rules.json`, state, console output |
+
+## Moves and actions
+
+```ruby
+def legal_moves(player)
+  hand(player).map { |card| option("Play #{card['name']}", public: "played #{card['name']}", play: { value: card['uid'] }) }
+end
+
+def apply_action_effects(player, action)
+  case action
+  in { play: { value: uid } }  then play(player, uid)
+  in { pass: { value: uids } } then pass(player, uids)
+  end
+end
+```
+
+- `label` (the first argument) is what the acting player sees; `public:` is what the others see; `log:` is a shorter console line.
+- The action has exactly one name (`play:` above). `value:` is its main parameter; others sit beside it (`play: { value: uid, target: 2 }`).
+- Moves and actions have symbol keys, so `apply_action_effects` and the bot can pattern-match them. A hand-written move with string keys is converted.
+- On a pick turn (`pick_range` returns `[min, max]`) the chosen values arrive together: `{ pass: { value: [42, 17, 9] } }`.
+- Every menu is checked before it's used. A misspelled key or a malformed action raises `PlaiTestr::MoveError` naming the hook, player, decision and option; repeated labels get a warning.
+
+### Writing good menus
+
+Small local models 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 or check legality.
+- **Put engine-computed facts on options, never advice.** "Discard 9♥ (deadwood after: 31)" is a fact; "Discard 9♥ (best)" decides for the model.
+- **Generate views from state**, never hand-written summaries, which go stale or leak hidden information.
+- **Keep menus short.** Merge equivalent options (identical cards, interchangeable targets); split a huge decision into steps.
+- **Hide safety caps.** Turn or hand limits that stop runaway games must not appear in views or rules text, or models play for the cap.
+- **Scope long rules.** Override `rules_text_for` to send only the sections the current step needs.
+
+## Steps
+
+Most games model a turn as a small state machine in `data['step']` (`draw` → `discard` → next player). `legal_moves` and `apply_action_effects` switch on the step, and `turn_phase` usually shows it. For decisions inside decisions (an attack the defender may answer, a triggered effect), use [FrameQueue](frame-queue.md).
+
+## Ending the game
+
+Set the status when the game ends:
+
+```ruby
+@game_state.apply_changes('status' => { 'game_over' => true, 'winner' => leader, 'end_reason' => 'points' })
+```
+
+`winner` is `nil` for a tie. `end_reason` is a short key, shown in reports and counted by botruns.
+
+## Randomness
+
+Use `@rng` for all randomness (`deck.shuffle(random: @rng)`, `@rng.rand(6) + 1`). It is reseeded for each decision from the game's seed and the decision number, so the same seed and the same choices always give the same game, interrupted or not. Any other source of randomness breaks replays and resume.
+
+## Limits and fallbacks
+
+- Every game stops at a decision limit, ending with `end_reason: 'decision_limit_reached'` and no winner, so a buggy game can't run forever. Set `max_decisions:` in `register`; otherwise the app's `max_decisions` applies.
+- When the model never gives a valid answer after retries, the bot's choice is played instead (or a random legal move, from a separate generator, when the bot has none), and the turn is flagged in the report.
+- A bot rule that raises in a model game is skipped with a warning; in a botrun it is recorded as a crash for that seed.
+
+## The event log
+
+`log(text)` records a public event; `log(text, to: player)` a private one ("You drew the 2♠"). Each entry is stamped with `log_turn`: the decision number by default. A game with rounds returns its round number, with `log_turn_name` its word for it ("round", "hand"). `recent_events_for` shows each player the last events they may see, and the debrief view shows the player's whole visible log.
+
+## Checking a prompt
+
+Read what the model sees before running a model game:
+
+```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] }
+
+runner.play_turn until runner.game_over?
+puts runner.debrief_summary(player), runner.debrief_view_for(player)
+```

data/docs/technical/specs.md

@@ -0,0 +1,62 @@
+# Specs
+
+Each game's specs are in `games/<name>/spec/` and run with [RSpec](https://rspec.info):
+
+```sh
+bundle exec rspec                       # every game
+bundle exec rspec games/hearts/spec     # one game
+```
+
+They need no model and run in seconds, so run them after every change.
+
+## The standard checks
+
+Every game includes the gem's shared checks (from `plai_testr/rspec`, which the app's `spec_helper` requires):
+
+```ruby
+RSpec.describe Hearts::Session::Runner do
+  it_behaves_like 'a PlAI Testr game', 'hearts'
+end
+```
+
+At every player count in `rules.json`, over a few seeds, they check that:
+
+- bot games reach an ending
+- every turn prompt builds, and every debrief prompt at the end (botruns never build prompts, so this is the only check before a model game)
+- state survives a JSON round trip
+- resuming from a mid-game checkpoint gives the same result
+- no player's prompt shows another player's hand
+
+Options: `seeds: [1, 2, 3]` sets which games are played; `pending: 'reason'` holds the checks while a new game is being built (the generated spec starts with it).
+
+The checks come from the installed gem, so upgrading the gem adds checks without editing the game. Don't copy them into a game.
+
+## Rules specs
+
+Rules specs drive the runner directly. Build it without saving anything, set up a situation, and check the menu or the effects:
+
+```ruby
+RSpec.describe Hearts::Session::Runner do
+  let(:game)   { PlaiTestr.load('hearts') }
+  let(:runner) { described_class.new(game: game, players: game.players, seed: 1, mode: 'bot', persist: false, out: StringIO.new) }
+  let(:state)  { runner.game_state }
+  let(:deck)   { PlaiTestr::Deck.build(game.rules) }
+
+  def cards(*names) = names.map { |name| deck.find { |c| c['name'] == name } }
+
+  def labels(player) = runner.legal_moves(player).map { |m| m[:label] }
+
+  before { runner.setup }
+
+  it 'follows the suit led when it can' do
+    state.data.merge!('step' => 'play', 'tricks' => 1, 'active' => 'Player 2', 'trick' => [{ 'player' => 'Player 1', 'card' => cards('9♣').first }])
+    state.player_state('Player 2').hand.replace(cards('5♥', '7♣', 'K♣'))
+
+    expect(labels('Player 2')).to eq(['Play 7♣ (stays under the 9♣)', 'Play K♣ (wins the trick so far)'])
+  end
+end
+```
+
+Hooks are public, so specs call them directly (the runner's private helpers such as `pstate` aren't; use `runner.game_state`). `runner.play_turn` and `runner.play_out` play one decision or the rest of the game. Write rules specs before any model plays: rules bugs are cheapest here.
+
+Add specs for what's specific to the game too: card counts, report sections, bot rules (`spec/bot_spec.rb`). If `data/` is copied from another repository, add a spec that fails when the copy is behind.

data/docs/technical/state.md

@@ -0,0 +1,60 @@
+# State
+
+Everything a game knows lives in `@game_state` ([`game_state.rb`](../../lib/plai_testr/state/game_state.rb)), so the gem can save it after every decision and restore it exactly.
+
+## Game state
+
+`@game_state` holds:
+
+- `turn`: decisions so far
+- `players`: player names, in seat order
+- `status`: owned by the runner. Set `game_over`, `winner` and `end_reason` when the game ends, with `@game_state.apply_changes('status' => {...})`.
+- `data`: the game's own state
+
+Each `player_state(name)` ([`player_state.rb`](../../lib/plai_testr/state/player_state.rb)), or `pstate(name)` in the runner, holds `score`, `hand` and its own `data`.
+
+### Rules for `data`
+
+- **Plain JSON values only**: hashes with string keys, arrays, strings, numbers, booleans, `nil`. Saving is a JSON dump, so anything else (symbols, objects, sets) breaks resume.
+- **Stable ids.** Give every card a `uid` (`Deck.build` does) and keep pile and slot indexes fixed. Never re-index things players refer to.
+- **Counters belong in `data` too**, so reports and debrief facts survive a resume (`tally` stores them in `data['tally']`).
+- **No instance variables for game state.** They're gone after a resume or when `debrief` rebuilds a report.
+
+### Naming your keys
+
+Subclass `GameState` to give `data` keys readers:
+
+```ruby
+module Hearts
+  module State
+    class GameState < PlaiTestr::State::GameState
+      def step  = @data['step']
+      def trick = @data['trick'] ||= []
+    end
+  end
+end
+```
+
+Register the subclass with `game_state_class:`.
+
+## Hidden information
+
+Each prompt is built from what that player may know. Two methods decide it:
+
+- **`GameState#data_for(observer)`** (private) returns the `data` an observer may see. The default already hides the event log entries meant for other players and the game's internal warnings. Extend it to hide decks or secret choices:
+
+  ```ruby
+  def data_for(observer)
+    super.except('deck', 'passes').merge('deck_size' => @data['deck'].length)
+  end
+  ```
+
+- **`PlayerState#serialize_for(observer)`** shows a player their whole state and others only `name`, `score`, `hand_size` and `public_data`. Subclass `PlayerState` and override `public_data` to show opponents more (a face-up card, a pile size), and override `player_state_class` in your `GameState` to use it.
+
+The [standard checks](specs.md) verify that no player's prompt shows another player's hand.
+
+## Checkpoints and resume
+
+After every decision the gem replaces `sessions/<id>/state.json` with the full state, the turn log, and a *fingerprint*: a hash of the game's `data/` and `lib/` files and the gem version. `resume` restores the state and continues from the next decision; since `@rng` is reseeded per decision, the game plays exactly as it would have without the interruption.
+
+`resume` refuses when the fingerprint differs: changed code or data might replay differently, and a mismatched replay would make the report misleading. `debrief` warns instead, since it only rebuilds the debrief.

data/lib/plai_testr/cli.rb

@@ -286,6 +286,6 @@ module PlaiTestr
 
     def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-    def duration(seconds) = format('%dm %02ds', seconds / 60, seconds % 60)
+    def duration(seconds) = Reporter::Duration.format(seconds)
   end
 end

data/lib/plai_testr/examples.rb

@@ -0,0 +1,37 @@
+require 'yaml'
+
+module PlaiTestr
+  module Examples
+    DIR     = File.expand_path('../../templates/examples', __dir__)
+    STAMP   = '.plai_testr.yml'
+    SKIPPED = %w[sessions reports].freeze
+
+    def self.names = Dir.children(DIR).sort
+
+    def self.checksum(dir)
+      files  = Dir.glob('**/*', base: dir).reject { |path| SKIPPED.include?(path.split('/').first) }.select { |path| File.file?(File.join(dir, path)) }.sort
+      digest = Digest::SHA256.new
+      files.each { |path| digest << path << "\0" << File.binread(File.join(dir, path)) << "\0" }
+      digest.hexdigest
+    end
+
+    def self.template_checksum(name) = checksum(File.join(DIR, name))
+
+    def self.stamp(game_dir, name)
+      File.write(File.join(game_dir, STAMP), <<~YAML)
+        # Written by plai_testr when it copied this example game. A gem update replaces the game
+        # only while its files still match this checksum; once edited, the new version goes alongside.
+        #{YAML.dump('example' => name, 'version' => VERSION, 'checksum' => template_checksum(name)).delete_prefix("---\n").chomp}
+      YAML
+    end
+
+    def self.stamp_for(game_dir) = YAML.safe_load_file(File.join(game_dir, STAMP))
+
+    def self.replaceable?(game_dir) = stamp_for(game_dir)['checksum'] == checksum(game_dir)
+
+    def self.current?(game_dir)
+      stamp = stamp_for(game_dir)
+      checksum(game_dir) == template_checksum(stamp['example'])
+    end
+  end
+end

data/lib/plai_testr/generator.rb

@@ -15,8 +15,9 @@ module PlaiTestr
       raise UsageError, "#{dir} already exists and is not empty" if Dir.exist?(root) && !Dir.empty?(root)
 
       copy(File.join(TEMPLATES, 'app'), root, app_name: File.basename(root), version: VERSION.split('.').first(2).join('.'))
-      Dir.children(File.join(TEMPLATES, 'examples')).sort.each do |example|
-        copy(File.join(TEMPLATES, 'examples', example), File.join(root, 'games', example))
+      Examples.names.each do |example|
+        copy(File.join(Examples::DIR, example), File.join(root, 'games', example))
+        Examples.stamp(File.join(root, 'games', example), example)
       end
       Guide.link(root)
       root

data/lib/plai_testr/reporter/botrun_report.rb

@@ -32,7 +32,7 @@ module PlaiTestr
           "| **Players** | #{@played.first&.dig('names')&.length || '—'} |"
         ]
         rows << "| **Personas** | #{@personas ? @personas.join(', ') : 'random per seed'} |" if personas?
-        rows << "| **Time** | #{@seconds.round(1)} s (#{(@seconds * 1000 / [@results.length, 1].max).round} ms per game) |"
+        rows << "| **Wall time** | #{Duration.format(@seconds)} (#{(@seconds * 1000 / [@results.length, 1].max).round} ms per game) |"
         rows << "| **Generated** | #{Time.now.strftime('%Y-%m-%d %H:%M')} |"
 
         "# Botrun: #{@game}\n\n| | |\n|---|---|\n#{rows.join("\n")}\n\n" \

data/lib/plai_testr/reporter/duration.rb

@@ -0,0 +1,12 @@
+module PlaiTestr
+  module Reporter
+    module Duration
+      def self.format(seconds)
+        seconds = seconds.round
+        return "#{seconds / 3600}h #{(seconds % 3600 / 60).to_s.rjust(2, '0')}m" if seconds >= 3600
+
+        "#{seconds / 60}m #{(seconds % 60).to_s.rjust(2, '0')}s"
+      end
+    end
+  end
+end

data/lib/plai_testr/reporter/report_builder.rb

@@ -37,6 +37,7 @@ module PlaiTestr
         rows << "| **Personas** | #{data['personas'].map { |p, label| "#{p}: #{label}" }.join('; ')} |" if data['personas']
         rows << "| **Model settings** | #{settings.map { |key, value| "#{key} #{value}" }.join(', ')} |" if settings && !bot_only
         rows << "| **Decisions** | #{@game_state.turn} |"
+        rows << "| **Wall time** | #{Duration.format(data['wall_seconds'])} |" if data['wall_seconds']
         rows << "| **Generated** | #{Time.now.strftime('%Y-%m-%d %H:%M')} |"
 
         "# Playtest Report: #{@rules.dig('game', 'name')}\n\n| | |\n|---|---|\n#{rows.join("\n")}"

data/lib/plai_testr/session/runner.rb

@@ -62,6 +62,7 @@ module PlaiTestr
         @turn_log      = []
         @warnings      = []
         @running       = true
+        @started       = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         @fingerprint   = game.fingerprint if persist
         @client        = Agents::OllamaClient.new(think_log: (think_log_path if persist), out: out, verbose: verbose)
         @settings      = resolve_settings
@@ -610,11 +611,12 @@ module PlaiTestr
       end
 
       def finish
+        data['wall_seconds'] = data.fetch('wall_seconds', 0) + Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started
         if game_over? && @running
           @status = 'completed'
           save_checkpoint('completed')
           @report_path = generate_report
-          out.puts "\nGame complete. Report: #{@report_path}"
+          out.puts "\nGame complete in #{Reporter::Duration.format(data['wall_seconds'])}. Report: #{@report_path}"
         else
           @status = 'interrupted'
           save_checkpoint('interrupted')

data/lib/plai_testr/state/game_state.rb

@@ -86,7 +86,7 @@ module PlaiTestr
       # the event log entries meant for them. Subclasses hide more with
       # `super.except('deck').merge('deck_size' => ...)`. serialize (checkpoints) keeps all of @data.
       def data_for(observer)
-        shown = @data.except('warnings')
+        shown = @data.except('warnings', 'wall_seconds')
         return shown unless shown.key?('log')
 
         shown.merge('log' => EventLog.new(shown['log']).visible_to(observer))

data/lib/plai_testr/version.rb

@@ -1,3 +1,3 @@
 module PlaiTestr
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/plai_testr.rb

@@ -43,6 +43,7 @@ require_relative 'plai_testr/agents/referee_agent'
 require_relative 'plai_testr/rules_loader'
 require_relative 'plai_testr/personas'
 require_relative 'plai_testr/reporter/tables'
+require_relative 'plai_testr/reporter/duration'
 require_relative 'plai_testr/reporter/think_log'
 require_relative 'plai_testr/reporter/report_builder'
 require_relative 'plai_testr/reporter/model_comparison'
@@ -60,5 +61,6 @@ require_relative 'plai_testr/deck'
 require_relative 'plai_testr/event_log'
 require_relative 'plai_testr/names'
 require_relative 'plai_testr/guide'
+require_relative 'plai_testr/examples'
 require_relative 'plai_testr/generator'
 require_relative 'plai_testr/cli'

data/templates/app/AGENTS.md.erb

@@ -2,7 +2,7 @@
 
 This app playtests tabletop games with [PlAI Testr](https://github.com/armahillo/plai_testr).
 
-The PlAI Testr guide for AI assistants is `.plai_testr/gem/docs/AGENTS.md`: read it before working here. `.plai_testr/gem` links to the installed gem (every `plai_testr` command and spec run keeps it current), so its `README.md`, `docs/` and `templates/examples/` are there too. Gem-wide guidance lives in the gem; this file holds only what is specific to this app.
+The PlAI Testr guide for AI assistants is `.plai_testr/gem/docs/AGENTS.md`: read it before working here. `.plai_testr/gem` links to the installed gem (every `plai_testr` command and spec run keeps it current), so its `docs/` (including the technical reference in `docs/technical/`) and `templates/examples/` are there too. Gem-wide guidance lives in the gem; this file holds only what is specific to this app.
 
 ## This app
 

data/templates/app/README.md.erb

@@ -34,7 +34,7 @@ Every command takes `--help` to list its options, e.g. `bundle exec plai_testr h
 
 `--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`.
+Settings for the whole app (decision limit, model, Ollama host, context size) are in `config/plai_testr.rb`. [Running playtests](https://github.com/armahillo/plai_testr/blob/main/docs/running-playtests.md) covers every command, option and setting.
 
 ## Layout
 
@@ -85,9 +85,9 @@ Some ways to start:
 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.
+This creates the skeleton above. Write the rules in `data/rules.md` and the components in `data/components/`, then build the harness: see [Ingesting a game with an agent](https://github.com/armahillo/plai_testr/blob/main/docs/ingesting-a-game-with-an-agent.md) or [Ingesting a game manually](https://github.com/armahillo/plai_testr/blob/main/docs/ingesting-a-game-manually.md). The same guides are in `.plai_testr/gem/docs/`, matching the installed version.
 
-`bundle exec rspec games/my_game` runs its specs. The generated botrun spec stays pending until the game can play itself to the end.
+`bundle exec rspec games/my_game/spec` runs its specs. The standard checks stay pending until the game can play itself to the end.
 
 ## Removing a game
 

data/templates/examples/gin_rummy/data/components/cards.csv

@@ -0,0 +1,53 @@
+name,suit,rank
+A♣,clubs,1
+2♣,clubs,2
+3♣,clubs,3
+4♣,clubs,4
+5♣,clubs,5
+6♣,clubs,6
+7♣,clubs,7
+8♣,clubs,8
+9♣,clubs,9
+10♣,clubs,10
+J♣,clubs,11
+Q♣,clubs,12
+K♣,clubs,13
+A♦,diamonds,1
+2♦,diamonds,2
+3♦,diamonds,3
+4♦,diamonds,4
+5♦,diamonds,5
+6♦,diamonds,6
+7♦,diamonds,7
+8♦,diamonds,8
+9♦,diamonds,9
+10♦,diamonds,10
+J♦,diamonds,11
+Q♦,diamonds,12
+K♦,diamonds,13
+A♠,spades,1
+2♠,spades,2
+3♠,spades,3
+4♠,spades,4
+5♠,spades,5
+6♠,spades,6
+7♠,spades,7
+8♠,spades,8
+9♠,spades,9
+10♠,spades,10
+J♠,spades,11
+Q♠,spades,12
+K♠,spades,13
+A♥,hearts,1
+2♥,hearts,2
+3♥,hearts,3
+4♥,hearts,4
+5♥,hearts,5
+6♥,hearts,6
+7♥,hearts,7
+8♥,hearts,8
+9♥,hearts,9
+10♥,hearts,10
+J♥,hearts,11
+Q♥,hearts,12
+K♥,hearts,13

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

@@ -9,68 +9,5 @@
   "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" }
-      ]
-    }
-  ]
+  "undercut_bonus": 25
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plai_testr
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Aaron H
@@ -68,8 +68,20 @@ files:
 - README.md
 - bin/plai_testr
 - docs/AGENTS.md
-- docs/frame_queue.md
-- docs/referee.md
+- docs/getting-started.md
+- docs/ingesting-a-game-manually.md
+- docs/ingesting-a-game-with-an-agent.md
+- docs/running-playtests.md
+- docs/technical/README.md
+- docs/technical/debrief.md
+- docs/technical/frame-queue.md
+- docs/technical/personas-and-bots.md
+- docs/technical/referee.md
+- docs/technical/reports.md
+- docs/technical/rules-and-components.md
+- docs/technical/runner.md
+- docs/technical/specs.md
+- docs/technical/state.md
 - lib/plai_testr.rb
 - lib/plai_testr/agents/ollama_client.rb
 - lib/plai_testr/agents/player_agent.rb
@@ -80,6 +92,7 @@ files:
 - lib/plai_testr/deck.rb
 - lib/plai_testr/errors.rb
 - lib/plai_testr/event_log.rb
+- lib/plai_testr/examples.rb
 - lib/plai_testr/game.rb
 - lib/plai_testr/generator.rb
 - lib/plai_testr/guide.rb
@@ -88,6 +101,7 @@ files:
 - lib/plai_testr/personas.rb
 - lib/plai_testr/preflight.rb
 - lib/plai_testr/reporter/botrun_report.rb
+- lib/plai_testr/reporter/duration.rb
 - lib/plai_testr/reporter/model_comparison.rb
 - lib/plai_testr/reporter/report_builder.rb
 - lib/plai_testr/reporter/tables.rb
@@ -111,6 +125,7 @@ files:
 - templates/app/spec/spec_helper.rb
 - templates/examples/gin_rummy/NOTES.md
 - templates/examples/gin_rummy/data/bots.yml
+- templates/examples/gin_rummy/data/components/cards.csv
 - templates/examples/gin_rummy/data/personas.yml
 - templates/examples/gin_rummy/data/rules.json
 - templates/examples/gin_rummy/data/rules.md