plai_testr 0.1.1

data/lib/plai_testr/generator.rb

@@ -0,0 +1,50 @@
+require 'erb'
+require 'pathname'
+
+module PlaiTestr
+  class Generator
+    TEMPLATES = File.expand_path('../../templates', __dir__)
+    GAME_NAME = /\A[a-z][a-z0-9_]*\z/
+
+    def initialize(out: $stdout)
+      @out = out
+    end
+
+    def app(dir)
+      root = File.expand_path(dir)
+      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))
+      end
+      root
+    end
+
+    def game(name, games_dir: PlaiTestr.games_dir)
+      raise UsageError, "Game names are lowercase snake_case, like my_game (got #{name.inspect})" unless name.match?(GAME_NAME)
+
+      root  = File.join(games_dir, name)
+      words = name.split('_').map(&:capitalize)
+      raise UsageError, "#{root} already exists" if File.exist?(root)
+
+      copy(File.join(TEMPLATES, 'game'), root, name: name, module_name: words.join, title: words.join(' '))
+      root
+    end
+
+    private
+
+    def copy(source, target, **locals)
+      Dir.glob('**/*', File::FNM_DOTMATCH, base: source).sort.each do |path|
+        from = File.join(source, path)
+        next if File.directory?(from)
+
+        to = File.join(target, path.gsub('__name__', locals[:name].to_s).delete_suffix('.erb'))
+        FileUtils.mkdir_p(File.dirname(to))
+        File.write(to, path.end_with?('.erb') ? ERB.new(File.read(from), trim_mode: '-').result_with_hash(locals) : File.read(from))
+        File.chmod(File.stat(from).mode, to)
+        @out.puts "  create  #{Pathname(to).relative_path_from(Dir.pwd)}"
+      end
+    end
+  end
+end

data/lib/plai_testr/model_settings.rb

@@ -0,0 +1,25 @@
+module PlaiTestr
+  module ModelSettings
+    MIN_CONTEXT = 2048
+
+    def self.resolve(game_settings, model_max: nil)
+      settings = PlaiTestr.config.model_settings.merge(game_settings)
+      unknown  = settings.keys - Config::MODEL_SETTINGS.keys
+      raise UsageError, "Unknown model setting(s): #{unknown.join(', ')} (known: #{Config::MODEL_SETTINGS.keys.join(', ')})" if unknown.any?
+
+      notes = []
+      clamp = lambda do |key, min, max|
+        bounded = settings[key].clamp(min, max)
+        notes << "#{key} #{settings[key]} is outside #{min}–#{max}; using #{bounded}" unless bounded == settings[key]
+        settings[key] = bounded
+      end
+
+      %i[context_size long_context_size].each { |key| clamp.call(key, MIN_CONTEXT, model_max || [settings[key], MIN_CONTEXT].max) }
+      clamp.call(:temperature, 0.0, 2.0)
+      %i[menu_budget referee_budget].each { |key| clamp.call(key, 1, settings[:context_size] - 1) }
+      %i[think_budget debrief_budget].each { |key| clamp.call(key, 1, settings[:long_context_size] - 1) }
+
+      [settings, notes]
+    end
+  end
+end

data/lib/plai_testr/names.rb

@@ -0,0 +1,7 @@
+module PlaiTestr
+  def self.rename(text, names)
+    return text if names.empty?
+
+    text.gsub(Regexp.union(names.keys.sort_by { |id| -id.length })) { |id| names[id] }
+  end
+end

data/lib/plai_testr/personas.rb

@@ -0,0 +1,97 @@
+require 'yaml'
+
+module PlaiTestr
+  class Personas
+    WILDCARD = '*'
+    ALL      = 'all'
+
+    def self.load(dir)
+      personas_file = read(File.join(dir, 'personas.yml'))
+      bots_file     = read(File.join(dir, 'bots.yml'))
+
+      new(basic_strategy: section(personas_file, 'basic_strategy'), personas: section(personas_file, 'personas'),
+          bot_strategy: section(bots_file, 'bot_strategy'), bots: section(bots_file, 'bots'))
+    end
+
+    def self.read(path)
+      return {} unless File.exist?(path)
+
+      content = YAML.safe_load_file(path, aliases: true) || {}
+      raise PersonaError, "#{path}: expected keys at the top level, got #{content.class}" unless content.is_a?(Hash)
+
+      content.merge('_path' => path)
+    rescue Psych::SyntaxError => e
+      raise PersonaError, "#{path}: #{e.message}"
+    end
+
+    def self.section(file, key)
+      value = file[key] || {}
+      raise PersonaError, "#{file['_path']}: '#{key}' must be a set of key: value entries, got #{value.class}" unless value.is_a?(Hash)
+
+      value
+    end
+
+    attr_reader :basic_strategy, :bot_strategy
+
+    def initialize(basic_strategy: {}, personas: {}, bot_strategy: {}, bots: {})
+      @basic_strategy = basic_strategy
+      @personas       = personas
+      @bot_strategy   = bot_strategy
+      @bots           = bots
+
+      @personas.each do |key, persona|
+        raise PersonaError, "personas.yml: persona '#{key}' must be a set of key: value entries" unless persona.is_a?(Hash)
+      end
+      orphans = @bots.keys - keys
+      raise PersonaError, "bots.yml: bots #{orphans.join(', ')} match no persona in personas.yml (personas: #{keys.join(', ')})" if orphans.any?
+    end
+
+    def keys = @personas.keys
+
+    def any? = @personas.any?
+
+    def name(key) = key.split('_').map(&:capitalize).join(' ')
+
+    def strategy(key) = @personas.fetch(key).values
+
+    def bot(key) = @bots.fetch(key, @bot_strategy)
+
+    def lint
+      @personas.filter_map do |key, persona|
+        missing = @basic_strategy.keys - persona.keys
+        "personas.yml: persona '#{key}' is missing basic_strategy #{missing.join(', ')} (add <<: *basics?)" if missing.any?
+      end
+    end
+
+    def check_request(request, players:, all: false)
+      request = Array(request)
+      return request if request.empty?
+      raise PersonaError, 'This game defines no personas (add data/personas.yml)' unless any?
+      return request if all && request == [ALL]
+      raise PersonaError, "#{request.length} personas given for #{players} players" if request.length > players
+
+      unknown = request - keys - [WILDCARD]
+      raise PersonaError, "Unknown persona #{unknown.first.inspect} (choose from #{keys.join(', ')}, or #{WILDCARD})" if unknown.any?
+
+      request
+    end
+
+    def assign(players, request, rng)
+      request = Array(request)
+      spare   = keys - request
+      spare   = keys if spare.empty?
+      pool    = []
+
+      players.each_with_index.to_h do |player, i|
+        key = request[i]
+        if key.nil? || key == WILDCARD
+          pool = spare.shuffle(random: rng) if pool.empty?
+          key  = pool.shift
+        end
+        [player, key]
+      end
+    end
+
+    def pairings(players) = keys.permutation(players).to_a
+  end
+end

data/lib/plai_testr/preflight.rb

@@ -0,0 +1,70 @@
+module PlaiTestr
+  class Preflight
+    LINT_SEEDS    = (1..5).to_a.freeze
+    PROMPT_LIMIT  = 0.9
+    START_COMMAND = { /darwin/ => 'brew services start ollama', /linux/ => 'sudo systemctl start ollama' }.freeze
+
+    def initialize(game:, players:, models:, personas: nil, out: $stdout)
+      @game     = game
+      @players  = players
+      @models   = models
+      @personas = personas
+      @out      = out
+      @client   = Agents::OllamaClient.new(out: out)
+    end
+
+    def run(seed)
+      ollama!
+      prompt_size!(seed)
+      lint!
+    end
+
+    def ollama!
+      available = begin
+        @client.model_names
+      rescue ModelError => e
+        start = START_COMMAND.find { |platform, _| RUBY_PLATFORM.match?(platform) }&.last || 'ollama serve'
+        raise ModelError, "#{e.message}\nStart it with: #{start}"
+      end
+      @out.puts "  Ollama at #{PlaiTestr.config.ollama_host}:#{PlaiTestr.config.ollama_port}: reachable"
+
+      wanted.each do |model|
+        @client.pull(model) unless available.include?(model) || available.include?("#{model}:latest")
+        @client.chat(model: model, messages: [{ role: 'user', content: 'Reply with OK.' }], think: false, num_predict: 1, keep_alive: '30m')
+        @out.puts "  #{model}: ready"
+      end
+    end
+
+    def prompt_size!(seed)
+      probe    = runner(seed)
+      probe.setup
+      player   = probe.next_player
+      settings, = ModelSettings.resolve(@game.model_settings, model_max: @client.context_length(@models[:player]))
+      agent    = Agents::PlayerAgent.new(name: player, model: @models[:player], client: @client, game_name: @game.rules.dig('game', 'name'),
+                                         settings: settings, think: @models[:think] == true)
+      used     = agent.prompt_tokens(rules_text: probe.rules_text_for(player), view_text: probe.view_text_for(player),
+                                     labels: probe.menu(player).map { |m| m[:label] }, recent: probe.recent_events_for(player),
+                                     prompt_note: probe.prompt_note_for(player), persona: probe.persona_for(player))
+      limit    = agent.context_size
+
+      if used > limit * PROMPT_LIMIT
+        raise ModelError, "The first prompt needs #{used} tokens, over #{(PROMPT_LIMIT * 100).round}% of the #{limit}-token context. " \
+                          "Raise context_size#{' (long_context_size with --think)' if @models[:think]} in config/plai_testr.rb or in the game's registration."
+      end
+      @out.puts "  First prompt: #{used} of #{limit} tokens"
+    end
+
+    def lint!
+      LINT_SEEDS.each { |seed| runner(seed).play_out }
+      @out.puts "  Lint: #{LINT_SEEDS.length} bot games played without errors"
+    end
+
+    private
+
+    def wanted = @models.values_at(:player, :referee).compact.uniq
+
+    def runner(seed)
+      @game.runner_class.new(game: @game, players: @players, seed: seed, personas: @personas, mode: 'bot', persist: false, out: StringIO.new, echo_warnings: false)
+    end
+  end
+end

data/lib/plai_testr/reporter/botrun_report.rb

@@ -0,0 +1,141 @@
+module PlaiTestr
+  module Reporter
+    class BotrunReport
+      def initialize(results, game:, version:, seconds:, personas: nil, planned: results.length)
+        @results  = results
+        @planned  = planned
+        @played   = results.reject { |r| r['error'] }
+        @game     = game
+        @version  = version
+        @seconds  = seconds
+        @personas = personas
+      end
+
+      def to_markdown
+        [header, endings, persona_wins, matchups, seat_wins, lengths, rules_fired, *extra_sections, outliers, warnings, errors].compact.join("\n\n") + "\n"
+      end
+
+      private
+
+      def extra_sections = []
+
+      def header
+        seeds = @results.map { |r| r['seed'] }
+        games = ["#{@results.length}"]
+        games << " of #{@planned}, stopped early" if @results.length < @planned
+        games << " (seeds #{seeds.min}–#{seeds.max})" if seeds.any?
+        games << ", #{@results.length - @played.length} crashed" if @played.length < @results.length
+
+        rows = [
+          "| **Rules version** | #{@version} |",
+          "| **Games** | #{games.join} |",
+          "| **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 << "| **Generated** | #{Time.now.strftime('%Y-%m-%d %H:%M')} |"
+
+        "# Botrun: #{@game}\n\n| | |\n|---|---|\n#{rows.join("\n")}\n\n" \
+          "Every decision was made by the game's bot rules; no model was called. Results describe how the bot plays, so confirm anything surprising with a few model games."
+      end
+
+      def personas? = @personas || @played.any? { |r| r['personas'] }
+
+      def endings
+        rows = @played.group_by { |r| r['end_reason'] || 'unknown' }.sort_by { |_, list| -list.length }
+                      .map { |reason, list| "| #{reason} | #{list.length} | #{pct(list.length, @played.length)} |" }
+        table('## How games ended', %w[Ending Games Share], rows)
+      end
+
+      def persona_wins
+        seats = @played.flat_map { |r| r['personas'].to_h.map { |player, persona| [persona, r['winner'] == player, r['winner'].nil?] } }
+        return nil if seats.empty?
+
+        rows = seats.group_by(&:first).sort.map do |persona, list|
+          wins = list.count { |_, won, _| won }
+          "| #{persona} | #{list.length} | #{wins} | #{list.count { |_, _, draw| draw }} | #{pct(wins, list.length)} | #{wilson(wins, list.length)} |"
+        end
+        table('## Wins by persona', ['Persona', 'Games', 'Wins', 'Draws', 'Win rate', '95% range'], rows,
+              'A persona playing itself counts once per seat. The 95% range is how far the true win rate could plausibly be from this sample; ranges that overlap are not a real difference.')
+      end
+
+      def matchups
+        pairs = @played.select { |r| r['personas'].to_h.length == 2 && r['personas'].values.uniq.length == 2 }
+        return nil if pairs.empty?
+
+        rows = pairs.group_by { |r| r['personas'].values.sort }.sort.map do |(a, b), list|
+          wins_a = list.count { |r| r['personas'][r['winner']] == a }
+          wins_b = list.count { |r| r['personas'][r['winner']] == b }
+          "| #{a} vs #{b} | #{list.length} | #{wins_a} | #{wins_b} | #{list.length - wins_a - wins_b} | #{pct(wins_a, list.length)} #{wilson(wins_a, list.length)} |"
+        end
+        table('## Matchups', ['Matchup', 'Games', 'First wins', 'Second wins', 'Draws', 'First win rate (95% range)'], rows)
+      end
+
+      def seat_wins
+        seats = @played.first&.dig('names')&.keys or return nil
+        rows  = seats.map do |seat|
+          wins = @played.count { |r| r['winner'] == seat }
+          "| #{seat} | #{wins} | #{pct(wins, @played.length)} | #{wilson(wins, @played.length)} |"
+        end
+        table('## Wins by seat', ['Seat', 'Wins', 'Win rate', '95% range'], rows)
+      end
+
+      def lengths
+        counts = @played.map { |r| r['decisions'] }.sort
+        return nil if counts.empty?
+
+        stats = [counts.sum.fdiv(counts.length).round, percentile(counts, 50), percentile(counts, 90), counts.max]
+        table('## Game length (decisions)', %w[Mean Median 90th Max], ["| #{stats.join(' | ')} |"])
+      end
+
+      def rules_fired
+        tally = @played.each_with_object(Hash.new(0)) { |r, sum| r['rules'].each { |rule, n| sum[rule] += n } }
+        total = tally.values.sum
+        rows  = tally.sort_by { |_, n| -n }.map { |rule, n| "| #{rule} | #{n} | #{pct(n, total)} |" }
+        table('## Bot rules used', %w[Rule Decisions Share], rows,
+              '`none` means the bot had no rule for that decision and took option 1; a large share points at a gap in the bot.')
+      end
+
+      def outliers
+        longest = @played.max_by(5) { |r| r['decisions'] }.map { |r| "seed #{r['seed']} (#{r['decisions']} decisions, #{r['end_reason']})" }
+        common  = @played.map { |r| r['end_reason'] }.tally.max_by { |_, n| n }&.first
+        rare    = @played.reject { |r| r['end_reason'] == common }.group_by { |r| r['end_reason'] }
+                         .map { |reason, list| "- #{reason}: seeds #{list.first(10).map { |r| r['seed'] }.join(', ')}#{' …' if list.length > 10}" }
+        "## Games to look at\n\n- Longest: #{longest.join('; ')}\n#{rare.join("\n")}".strip
+      end
+
+      def warnings
+        tally = @played.flat_map { |r| r['warnings'].to_a.uniq }.tally
+        return nil if tally.empty?
+
+        rows = tally.sort_by { |_, games| -games }.map { |text, games| "| #{text.gsub('|', '\\|')} | #{games} |" }
+        table('## Warnings', %w[Warning Games], rows)
+      end
+
+      def errors
+        crashed = @results.select { |r| r['error'] }
+        return nil if crashed.empty?
+
+        "## Crashes\n\n#{crashed.first(20).map { |r| "- seed #{r['seed']}: #{r['error']}" }.join("\n")}"
+      end
+
+      def table(title, headers, rows, note = nil)
+        ["#{title}\n", "| #{headers.join(' | ')} |", "|#{'---|' * headers.length}", *rows, (note && "\n#{note}")].compact.join("\n")
+      end
+
+      def pct(count, total) = total.zero? ? '—' : "#{(100.0 * count / total).round}%"
+
+      def percentile(sorted, p) = sorted[((p / 100.0) * (sorted.length - 1)).round]
+
+      def wilson(wins, total)
+        return '—' if total.zero?
+
+        z      = 1.96
+        rate   = wins.fdiv(total)
+        center = (rate + z**2 / (2 * total)) / (1 + z**2 / total)
+        half   = z * Math.sqrt(rate * (1 - rate) / total + z**2 / (4 * total**2)) / (1 + z**2 / total)
+        "#{((center - half) * 100).round}–#{((center + half) * 100).round}%"
+      end
+    end
+  end
+end

data/lib/plai_testr/reporter/model_comparison.rb

@@ -0,0 +1,104 @@
+module PlaiTestr
+  module Reporter
+    class ModelComparison
+      BASE_COLUMNS = [
+        'Model', 'Host', 'Games', 'Seeds', 'Avg minutes', 'Avg s / call', 'Prompt tok/s', 'Gen tok/s',
+        'Avg / max prompt tokens', 'Retries', 'Fallbacks', 'Endings', 'Wins by persona'
+      ].freeze
+
+      BASE_NOTES = [
+        '*Avg s / call, Prompt tok/s, Gen tok/s*: Ollama\'s own timings per model call. Compare hosts on the same model and seeds. Sessions from before these were logged show —.',
+        '*Retries / fallbacks*: reliability. A fallback means the model never gave a valid choice and the bot (or a random pick) chose instead.',
+        '*Endings*: each game\'s end reason and how often it happened.',
+        '*Wins by persona*: the winning player\'s persona in each decided game, for games that assign personas.',
+        '*Debrief answers given*: non-empty, non-"nothing" answers to the end-of-game questions. Read them in the session reports; count alone says little.'
+      ].freeze
+
+      def initialize(sessions_dir, since: nil)
+        @sessions_dir = sessions_dir
+        @since        = since
+      end
+
+      def to_markdown
+        groups = sessions.group_by { |s| [s[:model], s[:host]] }
+        return "No completed sessions with a recorded player model#{" since #{@since}" if @since}.\n" if groups.empty?
+
+        headers = BASE_COLUMNS + extra_columns.map(&:first) + ['Debrief answers given']
+        rows    = groups.map { |(model, host), list| "| #{row(model, host, list).join(' | ')} |" }
+
+        <<~MD
+          # #{title}
+
+          Generated #{Time.now.strftime('%Y-%m-%d %H:%M')}#{" — sessions since #{@since}" if @since}.
+
+          | #{headers.join(' | ')} |
+          |#{'---|' * headers.length}
+          #{rows.join("\n")}
+
+          **How to read it**
+          #{(BASE_NOTES + notes).map { |n| "- #{n}" }.join("\n")}
+        MD
+      end
+
+      private
+
+      def title = 'Model comparison'
+
+      def extra_columns = []
+
+      def notes = []
+
+      def sessions
+        Dir.glob(File.join(@sessions_dir, '*', 'state.json')).filter_map do |path|
+          id = File.basename(File.dirname(path))
+          next if @since && id < @since
+
+          data  = JSON.parse(File.read(path))
+          state = data['game_state']
+          model = state.dig('data', 'player_model')
+          next unless data['status'] == 'completed' && model
+
+          { model: "#{model}#{' +think' if state.dig('data', 'think')}", host: state.dig('data', 'host') || 'unknown', seed: state.dig('data', 'seed'), state: state,
+            turns: data['turn_log'].reject { |t| t['auto'] }, log: ThinkLog.load(File.join(File.dirname(path), 'think.log')) }
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      def row(model, host, list)
+        logs    = list.map { |s| s[:log] }
+        turns   = list.flat_map { |s| s[:turns] }
+        tokens  = logs.flat_map { |l| l.values('prompt_tokens') }
+        answers = list.flat_map { |s| s[:state].dig('data', 'debrief').to_h.values.flatten }
+        given   = answers.count { |a| !a['answer'].to_s.strip.empty? && !a['answer'].to_s.strip.match?(/\Anothing\.?\z/i) }
+
+        [
+          "`#{model}`", host, list.length, list.map { |s| s[:seed] }.sort.join(', '),
+          avg(logs.filter_map(&:minutes), 1),
+          avg(logs.flat_map { |l| l.values('total_s') }, 1),
+          avg(logs.flat_map { |l| l.values('prompt_tps') }, 0),
+          avg(logs.flat_map { |l| l.values('eval_tps') }, 1),
+          tokens.empty? ? '—' : "#{avg(tokens, 0)} / #{tokens.max.round}",
+          turns.count { |t| t['attempts'].to_i > 1 },
+          turns.count { |t| t['fallback'] },
+          list.map { |s| s[:state].dig('status', 'end_reason') || 'unknown' }.tally.map { |r, c| "#{r} #{c}" }.join(', '),
+          persona_wins(list),
+          *extra_columns.map { |_, value| value.call(list) },
+          answers.empty? ? '—' : "#{given}/#{answers.length}"
+        ]
+      end
+
+      def persona_wins(list)
+        wins = list.filter_map { |s| s[:state].dig('data', 'personas', s[:state].dig('status', 'winner').to_s) }
+        wins.empty? ? '—' : wins.tally.map { |label, count| "#{label} #{count}" }.join(', ')
+      end
+
+      def avg(values, digits)
+        return '—' if values.empty?
+
+        mean = values.sum.to_f / values.length
+        digits.zero? ? mean.round : mean.round(digits)
+      end
+    end
+  end
+end

data/lib/plai_testr/reporter/report_builder.rb

@@ -0,0 +1,154 @@
+module PlaiTestr
+  module Reporter
+    class ReportBuilder
+      def initialize(session_id:, rules:, game_state:, turn_log:, think_log: ThinkLog.new(''), sections: [], names: {}, debrief: true, warnings: [])
+        @session_id = session_id
+        @rules      = rules
+        @game_state = game_state
+        @turn_log   = turn_log
+        @think_log  = think_log
+        @sections   = sections
+        @names      = names
+        @debrief    = debrief
+        @warnings   = warnings
+      end
+
+      def build
+        report = [header, result, reliability, bot_agreement, speed, warnings, *@sections, debrief, turn_log_section].compact.join("\n\n---\n\n")
+        path   = File.join(PlaiTestr.reports_dir, "#{@session_id}.md")
+        File.write(path, report)
+        path
+      end
+
+      private
+
+      def header
+        data     = @game_state.data
+        settings = data['model_settings']
+        bot_only = data['mode'] == 'bot'
+        rows     = [
+          "| **Session** | `#{@session_id}` |",
+          "| **Rules version** | #{@rules.dig('game', 'version')} |",
+          "| **Players** | #{@game_state.players.map { |p| name(p).include?(p) ? name(p) : "#{name(p)} (#{p})" }.join(', ')} |",
+          bot_only ? '| **Player model** | none — mode: bot |' : "| **Player model** | #{data['player_model'] || 'unknown'}#{' (thinking)' if data['think']}#{" — mode: #{data['mode']}" if data['mode'] && data['mode'] != 'llm'} |",
+          "| **Host** | #{data['host'] || 'unknown'} |",
+          "| **Seed** | #{data['seed']} |"
+        ]
+        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 << "| **Generated** | #{Time.now.strftime('%Y-%m-%d %H:%M')} |"
+
+        "# Playtest Report: #{@rules.dig('game', 'name')}\n\n| | |\n|---|---|\n#{rows.join("\n")}"
+      end
+
+      def result
+        status = @game_state.status
+        winner = status['winner'] || leader
+        scores = @game_state.scores.map { |p, s| "| #{name(p)} | #{s} |" }.join("\n")
+
+        <<~MD.strip
+          ## Result
+
+          **Winner: #{winner ? name(winner) : 'none'}**#{" (#{status['end_reason'].to_s.tr('_', ' ')})" if status['end_reason']}
+
+          | Player | Score |
+          |---|---|
+          #{scores}
+        MD
+      end
+
+      def name(player) = @names.fetch(player, player)
+
+      def leader
+        top = @game_state.scores.select { |_, s| s.to_i.positive? }.max_by { |_, s| s.to_i }
+        top && @game_state.scores.values.count(top.last) == 1 ? top.first : nil
+      end
+
+      def reliability
+        bot       = @turn_log.count { |t| t['decider'] == 'BOT' && !t['fallback'] }
+        asked     = @turn_log.reject { |t| t['auto'] || (t['decider'] == 'BOT' && !t['fallback']) }
+        fallbacks = asked.count { |t| t['fallback'] }
+        rate      = asked.empty? ? 0 : (100.0 * fallbacks / asked.length).round(1)
+        full      = @turn_log.count { |t| t['context_full'] }
+
+        <<~MD.strip
+          ## Model reliability
+
+          | Decisions | Asked the model | Bot rules | Only one option | Needed a retry | Fallbacks (no valid choice → 🤖 bot or 🎲 random) | Fallback rate | Context nearly full |
+          |---|---|---|---|---|---|---|---|
+          | #{@turn_log.length} | #{asked.length} | #{bot} | #{@turn_log.length - asked.length - bot} | #{asked.count { |t| t['attempts'].to_i > 1 }} | #{fallbacks} | #{rate}% | #{full} |
+        MD
+      end
+
+      def bot_agreement
+        shadowed = @turn_log.select { |t| t['bot_rule'] }
+        return nil if shadowed.empty?
+
+        rows = shadowed.group_by { |t| [t['bot_rule'], t['bot_obvious']] }.sort_by { |(rule, obvious), _| [obvious ? 0 : 1, rule] }.map do |(rule, obvious), list|
+          agreed = list.count { |t| Array(t['choice']).sort == Array(t['bot_choice']).sort }
+          "| #{rule} | #{obvious ? 'obvious' : 'default'} | #{list.length} | #{agreed} | #{(100.0 * agreed / list.length).round}% |"
+        end
+
+        <<~MD.strip
+          ## Bot agreement
+
+          On model turns the bot's choice is recorded too. Low agreement on an *obvious* rule means the model missed a clearly best move (or the rule is wrong); *default* rules are only the bot's guess. Fallback turns are left out.
+
+          | Bot rule | Kind | Model turns | Model agreed | Agreement |
+          |---|---|---|---|---|
+          #{rows.join("\n")}
+        MD
+      end
+
+      def speed
+        log = @think_log
+        return "## Speed\n\nNo model calls were logged." if log.calls.empty?
+
+        cell = ->(value, digits = 1) { value ? value.round(digits) : '—' }
+
+        <<~MD.strip
+          ## Speed
+
+          | Model calls | Minutes | Avg s / call | Avg prompt tokens | Prompt tok/s | Gen tok/s | Model load s (total) |
+          |---|---|---|---|---|---|---|
+          | #{log.calls.length} | #{cell.call(log.minutes)} | #{cell.call(log.average('total_s'))} | #{cell.call(log.average('prompt_tokens'), 0)} | #{cell.call(log.average('prompt_tps'), 0)} | #{cell.call(log.average('eval_tps'))} | #{cell.call(log.values('load_s').sum)} |
+        MD
+      end
+
+      def warnings
+        return nil if @warnings.empty?
+
+        "## Warnings\n\n#{@warnings.tally.map { |text, count| "- #{text}#{" (×#{count})" if count > 1}" }.join("\n")}"
+      end
+
+      def debrief
+        answers = @game_state.data['debrief']
+        return nil unless @debrief && answers&.any?
+
+        players = answers.map do |player, list|
+          "**#{name(player)}**\n\n#{list.map { |a| "- *#{a['question']}*\n  #{a['answer'].to_s.empty? ? '_(no answer)_' : a['answer']}" }.join("\n")}"
+        end
+
+        "## Debrief\n\n#{players.join("\n\n")}"
+      end
+
+      def turn_line(turn)
+        parts = ["- **#{turn['turn']}. #{name(turn['player'])}"]
+        parts << " · #{turn['phase']}" if turn['phase']
+        parts << ':** '
+        parts << "#{DECIDER_ICONS[turn['decider']]} " if turn['decider']
+        parts << PlaiTestr.rename((turn['log'] || turn['label']).to_s, @names)
+        parts << ' _(only option)_' if turn['auto']
+        parts << " _(rule: #{turn['rule']})_" if turn['decider'] == 'BOT'
+        parts << ' **[FALLBACK]**' if turn['fallback']
+        parts << "\n  > #{turn['reasoning']}" unless turn['reasoning'].to_s.empty?
+        parts.join
+      end
+
+      def turn_log_section
+        "## Turn log\n\n<details><summary>#{@turn_log.length} decisions</summary>\n\n#{@turn_log.map { |t| turn_line(t) }.join("\n")}\n\n</details>"
+      end
+    end
+  end
+end