agentilda 2.0.3 → 2.0.4

data/lib/agentilda/presentation/reporter.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Presentation
+    # `/spec-status` — every plan, its state in icon and words, and its pull
+    # requests as clickable links.
+    #
+    # {#render} returns a string and prints nothing. Whoever calls it decides
+    # where it goes, which keeps the table pipeable.
+    class Reporter
+      # Columns, so the header and the rows cannot drift apart.
+      HEADINGS = ["Plan", "⬇", "Status", "Feature", "Pull Requests"].freeze
+
+      # Cells given to the plan number: "018.01" with room to grow.
+      ORDINAL_WIDTH = 7
+
+      # Cells given to a status icon. Emoji vary in both character count and
+      # display width, so the cell is padded to this by {UI.fit} rather than
+      # trusted to be any particular size — see the note there.
+      EMOJI_WIDTH = 2
+
+      # Cells given to a pull request's state, so the URLs line up beneath each
+      # other whichever states the tree happens to contain.
+      STATE_WIDTH = Plans::PullRequests::STATES.map { |_, label| UI.display_width(label) }.max
+
+      # @param tree [Agentilda::Plans::Tree]
+      def initialize(tree:)
+        @tree = tree
+      end
+
+      # @return [Agentilda::Plans::Tree]
+      attr_reader :tree
+
+      # @return [String] the whole table, newline-terminated
+      def render
+        return "No plans found in #{tree.dir}\n" if tree.subjects.empty?
+
+        [header, *tree.subjects.flat_map { |s| rows_for(s) }, "", footer].join("\n") + "\n"
+      end
+
+      # @return [Hash{Symbol => Integer}] how many plans sit in each state
+      def totals
+        tree.subjects.each_with_object(Hash.new(0)) { |s, h| h[s.status.key] += 1 }
+      end
+
+      # Plans whose folder name their contents do not justify.
+      #
+      # @return [Array<Agentilda::Plans::Subject>]
+      def inconsistent = tree.subjects.reject(&:consistent?)
+
+      private
+
+      # @return [Integer] widest status label, so the column lines up
+      def label_width = @label_width ||= tree.subjects.map { |s| UI.display_width(s.status.label) }.max.to_i + 4
+
+      # @return [Integer] widest feature name
+      def title_width = @title_width ||= tree.subjects.map { |s| UI.display_width(s.feature.title) }.max.to_i + 2
+
+      # The one place the table's shape is written down. The heading, the plan
+      # rows, the continuation lines and the violations all come through here, so
+      # a column cannot widen in one of them and stay put in the others.
+      #
+      # Cells arrive already fitted and already painted, in that order, because
+      # the order matters: escape codes count toward a string's length, so
+      # padding a coloured string pads it to a width of which several characters
+      # are invisible, and the column collapses by exactly that much.
+      #
+      # @return [String]
+      def row(flag, ordinal, emoji, label, title, tail)
+        format("%s %s  %s %s  %s %s", flag, ordinal, emoji, label, title, tail)
+      end
+
+      # Cell at which the pull requests start, so a plan's second and third pull
+      # requests sit under its first. Measured by running blanks through {#row}
+      # rather than counted by hand, so the indent cannot drift when the layout
+      # changes.
+      #
+      # @return [Integer]
+      def pr_column
+        @pr_column ||= row(" ",
+          " " * ORDINAL_WIDTH,
+          " " * EMOJI_WIDTH,
+          " " * label_width,
+          " " * title_width,
+          "").length
+      end
+
+      # @return [Integer] cell at which the feature name starts
+      def title_column = pr_column - title_width - 1
+
+      # @return [String]
+      def header
+        text = row(" ",
+          UI.fit(HEADINGS[0], ORDINAL_WIDTH),
+          UI.fit(HEADINGS[1], EMOJI_WIDTH),
+          UI.fit(HEADINGS[2], label_width),
+          UI.fit(HEADINGS[3], title_width),
+          HEADINGS[4])
+
+        rule = "  " + ("─" * (UI.display_width(text) - 2))
+
+        [UI.paint(text, :bold), UI.paint(rule, :bright_yellow)].join("\n")
+      end
+
+      # One line per plan, plus a continuation line for each extra pull request
+      # so that every URL is visible and clickable rather than truncated.
+      #
+      # @param subject [Agentilda::Plans::Subject]
+      # @return [Array<String>]
+      def rows_for(subject)
+        feature = subject.feature
+        prs = subject.pull_requests
+
+        first = row(
+          subject.consistent? ? " " : UI.paint("!", :red),
+          UI.paint(UI.fit(feature.ordinal.to_s, ORDINAL_WIDTH), :bold),
+          UI.fit(feature.status.emoji, EMOJI_WIDTH),
+          UI.paint(UI.fit(feature.status.label, label_width), :yellow),
+          UI.paint(UI.fit(feature.title, title_width), :blue, :bold),
+          prs.empty? ? UI.paint("[none yet]", :bright_red) : link(prs.first)
+        )
+
+        rest = prs.drop(1).map { |pr| (" " * pr_column) + link(pr) }
+
+        [first, *rest, *violation_line(subject)]
+      end
+
+      # The URL is left bare rather than wrapped in an OSC 8 hyperlink: the table
+      # is as likely to be piped into a file as read in a terminal, and every
+      # terminal worth the name linkifies a bare URL anyway.
+      #
+      # @param pr [Agentilda::Plans::PullRequest]
+      # @return [String]
+      def link(pr)
+        colour = state_colour(pr)
+
+        format("#%4s %s %s",
+          pr.number,
+          UI.paint(UI.fit(pr.state, STATE_WIDTH), colour),
+          UI.paint(pr.url.to_s, colour))
+      end
+
+      # @param pr [Agentilda::Plans::PullRequest]
+      # @return [Symbol] a pastel style name
+      def state_colour(pr)
+        if pr.merged?
+          :magenta
+        elsif pr.open?
+          :yellow
+        else
+          :blue
+        end
+      end
+
+      # @param subject [Agentilda::Plans::Subject]
+      # @return [Array<String>]
+      def violation_line(subject)
+        return [] if subject.consistent?
+
+        [(" " * title_column) + UI.paint("↳ #{subject.violation}", :red)]
+      end
+
+      # @return [String]
+      def footer
+        counts = totals.map { |key, n| "#{Plans::STATUS_BY_KEY.fetch(key).emoji} #{n}" }.join("   ")
+        lines = ["  #{tree.subjects.size} #{tree.subjects.size == 1 ? "plan" : "plans"}   #{counts}"]
+
+        unless inconsistent.empty?
+          lines << "  #{UI.paint("#{inconsistent.size} with a status their contents do not justify", :red)}"
+        end
+
+        tree.duplicates.each do |ordinal, dirnames|
+          lines << "  #{UI.paint("#{ordinal} is claimed by #{dirnames.size} folders — a number is an identity:", :red)}"
+          dirnames.each { |d| lines << "    #{UI.paint(d, :bright_black)}" }
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/agentilda/presentation/screen/ratatui/bar.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+
+module Agentilda
+  module Presentation
+    module Screen
+      class Ratatui
+        module Bar
+          # Cells the fill portion occupies.
+          WIDTH = 10
+
+          # Seconds a bar visually maxes out at. Cosmetic only — the color
+          # thresholds below are independent, absolute-minute rules.
+          CAP = 1800
+
+          # @param tui [RatatuiRuby::TUI]
+          # @param seconds [Integer, nil] nil draws an empty, dim bar
+          # @param color [Symbol] the fill's foreground color
+          # @return [RatatuiRuby::Text::Line]
+          def self.cell(tui, seconds, color)
+            return empty(tui) if seconds.nil?
+
+            filled = ((seconds.to_f / CAP).clamp(0.0, 1.0) * WIDTH).round
+            bar = ("▓" * filled) + ("░" * (WIDTH - filled))
+            clock = format(" %2d:%02d", seconds / 60, seconds % 60)
+            tui.text_line(spans: [
+                            tui.text_span(content: bar, style: tui.style(fg: color)),
+                            tui.text_span(content: clock, style: tui.style(fg: :bright_black))
+                          ])
+          end
+
+          # @param tui [RatatuiRuby::TUI]
+          # @return [RatatuiRuby::Text::Line]
+          def self.empty(tui)
+            tui.text_line(spans: [
+                            tui.text_span(content: " " * WIDTH, style: tui.style(fg: :bright_black)),
+                            tui.text_span(content: " --:--", style: tui.style(fg: :bright_black))
+                          ])
+          end
+
+          # @param elapsed [Integer]
+          # @return [Symbol]
+          def self.elapsed_color(elapsed) = elapsed >= 900 ? :yellow : :green
+
+          # @param remaining [Integer, nil]
+          # @return [Symbol]
+          def self.remaining_color(remaining)
+            return :bright_black if remaining.nil?
+            return :red if remaining < 300
+            return :yellow if remaining < 900
+
+            :green
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/presentation/screen/ratatui/key_translator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+
+module Agentilda
+  module Presentation
+    module Screen
+      class Ratatui
+        # RatatuiRuby::Event -> the exact string Keyboard#handle already
+        # expects, so every key binding (select, kill, extend, wrap-up, quit,
+        # the dialog, ctrl-c) is reused verbatim rather than reimplemented.
+        module KeyTranslator
+          # @param event [RatatuiRuby::Event]
+          # @return [String, nil] nil for anything that is not a key press
+          def self.call(event)
+            return nil unless event.key?
+            return "\u0003" if event.interrupt?
+
+            case event.code
+            when "up" then "\e[A"
+            when "down" then "\e[B"
+            when "enter" then "\r"
+            when "esc" then "\e"
+            else event.code
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/presentation/screen/ratatui.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+
+module Agentilda
+  module Presentation
+    module Screen
+      # A ratatui_ruby-backed alternative to {Screen}, selected with `--tui
+      # ratatui`. Unlike {Screen}, whose #draw renders synchronously from the
+      # dispatcher's own tick, ratatui_ruby owns a blocking render+input loop
+      # of its own — see the lifecycle methods added in the next task. This
+      # class carries the parts of that loop with no terminal dependency: the
+      # widget tree built from a {Board}.
+      class Ratatui
+        # Cells each column takes. The last one is stretched to the edge by
+        # ratatui's legacy flex. The elapsed/time-left columns (indices 8 and 9) are 17,
+        # not 13: {Bar.cell} emits a 10-cell bar plus a clock suffix up to 7
+        # characters wide (e.g. " 12:41"), and a narrower column clips the
+        # clock digits once ratatui actually lays the table out (see
+        # spec/agentilda/screen/ratatui_spec.rb's real-terminal regression
+        # test, which is the only one of this file's specs that can see
+        # that — the rest inspect the pre-layout `Text::Line` object).
+        COLUMNS = [9, 7, 16, 18, 8, 8, 5, 13, 17, 17].freeze
+
+        HEADER = %w[time plan feature agent round model subs tokens elapsed left].freeze
+
+        # Blank lines between two agents.
+        ROW_GAP = 1
+
+        # The highlight symbol's column. Reserved even with nothing selected,
+        # so the activity line's x never shifts when a selection appears.
+        HIGHLIGHT_SYMBOL = "> "
+
+        # The activity line starts under the feature column: past the
+        # highlight symbol, time and plan, each column plus its 1-cell gap.
+        ACTIVITY_INDENT = HIGHLIGHT_SYMBOL.length + COLUMNS[0] + 1 + COLUMNS[1] + 1
+
+        # Cells a status line stops short of the terminal's right edge.
+        ACTIVITY_MARGIN = 5
+
+        # Status lines drawn under an agent's row when nobody says otherwise.
+        SCROLL_HEIGHT = 3
+
+        # Seconds between samples for the running-agent-count sparkline.
+        SAMPLE_INTERVAL = 10
+
+        # Points the sparkline keeps before the oldest scrolls off the left.
+        HISTORY = 60
+
+        # @return [Array<Integer>] running-agent-count samples, oldest first
+        attr_reader :history
+
+        # @return [Integer] status lines drawn under each agent's row
+        attr_reader :scroll_height
+
+        # @param runner [#call] `RatatuiRuby.method(:run)` by default; a fake
+        #   in tests, so this class never needs a real terminal to exercise
+        #   its own orchestration
+        # @param scroll_height [Integer] how many of an agent's latest statuses
+        #   show under its row, newest at the top
+        def initialize(runner: RatatuiRuby.method(:run), scroll_height: SCROLL_HEIGHT)
+          @runner = runner
+          @scroll_height = Integer(scroll_height).clamp(1, Engine::Board::Row::HISTORY)
+          @board = nil
+          @keyboard = nil
+          @history = []
+          @last_sample = nil
+          # Read from the dispatcher's thread in #tick's `until @closing` via
+          # #run_loop, written from the caller's thread in #close. Safe only
+          # under MRI/CRuby's GVL, which serializes the read and the write;
+          # a GVL-free Ruby would need a real memory barrier here.
+          @closing = false
+          @error = nil
+          @mutex = Mutex.new
+        end
+
+        # @param keyboard [Agentilda::Presentation::Keyboard] built with `.new`, never
+        #   `.start`'d — this is what feeds it keys, from the thread
+        #   ratatui_ruby's own loop runs on.
+        # @return [void]
+        def attach_keyboard(keyboard) = @keyboard = keyboard
+
+        # @return [void]
+        def open
+          @closing = false
+          @error = nil
+          @thread = Thread.new do
+            Thread.current.report_on_exception = false
+            begin
+              @runner.call { |tui| run_loop(tui) }
+            rescue StandardError => e
+              # A background render thread's job is never to crash the run:
+              # #close's `@thread&.join` would otherwise re-raise this inside
+              # `run.rb`'s `ensure`, after every agent has already run,
+              # discarding the whole run report. Stash it; #close surfaces it
+              # with a one-line warning instead.
+              @error = e
+            end
+          end
+        end
+
+        # Called by {Console#paint} from the dispatcher's own thread, exactly
+        # as {Screen#draw} is. Stores the board; the ratatui thread picks it
+        # up on its own next tick, a fraction of a frame later.
+        #
+        # @param board [Agentilda::Engine::Board]
+        # @return [void]
+        def draw(board) = @mutex.synchronize { @board = board }
+
+        # @return [void]
+        def close
+          @closing = true
+          @thread&.join
+          @thread = nil
+          UI.line("ratatui backend failed: #{@error.message} (the run itself continued; nothing was drawn)") if @error
+        end
+
+        # @param tui [RatatuiRuby::TUI]
+        # @return [void]
+        def run_loop(tui)
+          # `TableState.new`'s documented `selected = nil` default isn't
+          # honored by the native binding — it raises ArgumentError given
+          # zero arguments (see spec/agentilda/screen/ratatui_spec.rb's own
+          # `table_state` let) — so the nil has to be explicit.
+          table_state = tui.table_state(nil)
+          tick(tui, table_state) until @closing
+        end
+
+        # One frame: draw the latest board, sample the sparkline, forward the
+        # next key. Public so the lifecycle spec can drive it without needing
+        # to manage the `until @closing` loop.
+        #
+        # @param tui [RatatuiRuby::TUI]
+        # @param table_state [RatatuiRuby::TableState]
+        # @return [void]
+        def tick(tui, table_state)
+          board = @mutex.synchronize { @board }
+          unless board
+            # `tui.poll_event` below is what paces this loop (ratatui's
+            # default poll timeout is ~16ms); returning ahead of it, as here,
+            # would otherwise spin a CPU core flat out until the dispatcher's
+            # first paint.
+            sleep(0.05)
+            return
+          end
+
+          sample(board)
+          tui.draw { |frame| render(tui, frame, frame.area, board, table_state) }
+          forward(tui.poll_event)
+        end
+
+        # @param tui [RatatuiRuby::TUI]
+        # @param frame [RatatuiRuby::Frame]
+        # @param area [RatatuiRuby::Layout::Rect]
+        # @param board [Agentilda::Engine::Board]
+        # @param table_state [RatatuiRuby::TableState]
+        # @return [void]
+        def render(tui, frame, area, board, table_state)
+          sync_selection(board, table_state)
+          _, top, _, table_area, bottom = tui.layout_split(area,
+            direction:   :vertical,
+            constraints: [tui.constraint_length(1), tui.constraint_length(1), tui.constraint_length(1),
+                          tui.constraint_fill(1), tui.constraint_length(1)])
+          _bottom_text, bottom_spark = tui.layout_split(bottom,
+            direction:   :horizontal,
+            constraints: [tui.constraint_fill(3), tui.constraint_fill(1)])
+
+          frame.render_widget(top_bar(tui, board), top)
+          frame.render_stateful_widget(table(tui, board), table_area, table_state)
+          render_activities(tui, frame, table_area, board, table_state)
+          # The bar is painted across the whole strip first, sparkline area
+          # included, so the cyan reaches both edges; the sparkline is then
+          # drawn over its right-hand share of it, in the same colors.
+          frame.render_widget(bottom_bar(tui, board), bottom)
+          frame.render_widget(tui.sparkline(data: @history, style: tui.style(fg: :black, bg: :cyan)), bottom_spark)
+          render_overlay(tui, frame, area, board)
+        end
+
+        # @param board [Agentilda::Engine::Board]
+        # @return [void]
+        def sample(board)
+          now = UI.monotonic
+          return if @last_sample && now - @last_sample < SAMPLE_INTERVAL
+
+          @last_sample = now
+          @history << board.running
+          @history.shift while @history.size > HISTORY
+        end
+
+        # @param event [RatatuiRuby::Event]
+        # @return [void]
+        def forward(event)
+          key = KeyTranslator.call(event) or return
+          @keyboard&.handle(key)
+        end
+
+        private
+
+        # @param board [Agentilda::Engine::Board]
+        # @param table_state [RatatuiRuby::TableState]
+        # @return [void]
+        def sync_selection(board, table_state)
+          index = board.selected && board.rows.index { |r| r.key == board.selected }
+          table_state.select(index)
+        end
+
+        # @return [RatatuiRuby::Widgets::Paragraph]
+        def top_bar(tui, board)
+          tui.paragraph(
+            text:  "#{board.status} · plans: #{board.plans.join(", ")} " \
+                   "· tokens ↑#{UI.abbreviate(board.up)} ↓#{UI.abbreviate(board.down)}",
+            style: tui.style(fg: :black, bg: :cyan)
+          )
+        end
+
+        # @return [RatatuiRuby::Widgets::Paragraph]
+        def bottom_bar(tui, board)
+          tui.paragraph(
+            text:  "working in #{board.root} · agents running: #{board.running} " \
+                   "· live ↑#{UI.abbreviate(board.live_up)} ↓#{UI.abbreviate(board.live_down)}",
+            style: tui.style(fg: :black, bg: :cyan)
+          )
+        end
+
+        # @return [RatatuiRuby::Widgets::Table]
+        def table(tui, board)
+          tui.table(header: HEADER,
+            rows: board.rows.map { |row| table_row(tui, row) },
+            widths: COLUMNS.map { |w| tui.constraint_length(w) },
+            highlight_symbol: HIGHLIGHT_SYMBOL,
+            highlight_spacing: :always,
+            row_highlight_style: tui.style(modifiers: [:reversed]))
+        end
+
+        # Lines one agent takes: its table row, then its statuses.
+        #
+        # @return [Integer]
+        def row_height = 1 + scroll_height
+
+        # Paints each visible agent's latest statuses over the empty lines
+        # under its table row, newest first: the newest bold, the rest plain,
+        # all yellow. A table cell cannot span columns, so a status would
+        # otherwise be clipped to one column's width; drawn on top, it gets
+        # everything from the feature column to {ACTIVITY_MARGIN} cells before
+        # the right edge, and a longer status ends in an ellipsis.
+        #
+        # @return [void]
+        def render_activities(tui, frame, table_area, board, table_state)
+          width = table_area.width - ACTIVITY_INDENT - ACTIVITY_MARGIN
+          return if width <= 0
+
+          bottom = table_area.y + table_area.height
+          board.rows.drop(table_state.offset.to_i).each_with_index do |row, index|
+            # +1 for the header line, +1 more to land under the row's own line.
+            top = table_area.y + 1 + (index * (row_height + ROW_GAP)) + 1
+            break if top >= bottom
+
+            statuses(row).each_with_index do |text, line|
+              y = top + line
+              break if y >= bottom
+
+              modifiers = line.zero? ? [:bold] : []
+              frame.render_widget(
+                tui.paragraph(text: ellipsize(text, width), style: tui.style(fg: :yellow, modifiers:)),
+                tui.rect(x: table_area.x + ACTIVITY_INDENT, y:, width:, height: 1)
+              )
+            end
+          end
+        end
+
+        # @param text [String]
+        # @param width [Integer] cells available
+        # @return [String] the text, or its head and an ellipsis within +width+
+        def ellipsize(text, width) = text.length > width ? "#{text[0, width - 1]}…" : text
+
+        # @param row [Agentilda::Engine::Board::Row]
+        # @return [Array<String>] newest first, at most {#scroll_height}
+        def statuses(row)
+          lines = row.history.empty? ? [row.message.to_s] : row.history
+          lines.first(scroll_height)
+        end
+
+        # @return [RatatuiRuby::Widgets::Row]
+        def table_row(tui, row)
+          tui.row(height: row_height,
+            bottom_margin: ROW_GAP,
+            cells: [
+              row.at.strftime("%H:%M:%S"),
+              row.ordinal,
+              row.file,
+              tui.text_span(content: row.agent, style: tui.style(fg: :yellow, modifiers: [:bold])),
+              "R:#{row.round}/#{row.rounds}",
+              row.model.to_s,
+              row.subagents.to_s,
+              "↑#{UI.abbreviate(row.up)} ↓#{UI.abbreviate(row.down)}",
+              Bar.cell(tui, row.elapsed, Bar.elapsed_color(row.elapsed)),
+              Bar.cell(tui, row.remaining, Bar.remaining_color(row.remaining))
+            ])
+        end
+
+        # @return [void]
+        def render_overlay(tui, frame, area, board)
+          text = board.dialog || board.help || board.about or return
+          title = if board.dialog
+                    "Agent"
+                  else
+                    (board.help ? "Keys" : "About")
+                  end
+          lines = text.lines.size + 4
+          width = [text.lines.map { |l| l.chomp.length }.max.to_i + 6, area.width].min
+          overlay_area = tui.rect(x: [(area.width - width) / 2, 0].max,
+            y: [(area.height - lines) / 2, 0].max,
+            width:,
+            height: lines)
+          frame.render_widget(tui.paragraph(text:, block: tui.block(title:, borders: [:all])), overlay_area)
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/presentation/viewer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Presentation
+    # Hands Markdown files to a renderer outside this process: the system
+    # viewer via `open`, or mdfried in the terminal.
+    #
+    # Both paths shell out, so the class takes its two effects as lambdas and
+    # the specs assert on the commands instead of launching viewers on the box
+    # running the suite.
+    class Viewer
+      # What to run when mdfried is asked for but not installed. Homebrew is the
+      # one package manager the toolchain already assumes (see the Brewfile
+      # convention), so there is no fallback chain to get wrong.
+      INSTALL = "brew install mdfried >/dev/null"
+
+      # How to notice mdfried is missing without depending on `which`, which
+      # differs across shells; `command -v` is POSIX.
+      DETECT = "command -v mdfried >/dev/null"
+
+      # @param launch [#call] runs a command, returns truthy on success
+      # @param pipe [#call] runs a command, yielding its stdin as an IO
+      def initialize(launch: ->(*cmd) { system(*cmd) },
+        pipe: ->(cmd, &block) { IO.popen(cmd, "w", &block) })
+        @launch = launch
+        @pipe = pipe
+      end
+
+      # Opens each file in whatever the system has configured for Markdown.
+      #
+      # @param paths [Array<String>]
+      # @return [void]
+      def open(paths)
+        Array(paths).each { |path| @launch.call("open", path) }
+      end
+
+      # Streams each file's content into mdfried, installing it first when it
+      # is missing.
+      #
+      # @param paths [Array<String>]
+      # @return [void]
+      # @raise [Agentilda::Error] when mdfried is absent and brew cannot fix that
+      def mdfried(paths)
+        ensure_mdfried!
+        Array(paths).each do |path|
+          @pipe.call("mdfried") { |io| io.write(File.read(path)) }
+        end
+      end
+
+      private
+
+      # @return [void]
+      # @raise [Agentilda::Error]
+      def ensure_mdfried!
+        return if @launch.call(DETECT)
+
+        @launch.call(INSTALL) or
+          raise Error, "mdfried is not installed, and `brew install mdfried` failed"
+      end
+    end
+  end
+end

data/lib/agentilda/presentation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Everything a person reads: the live dashboard, the status table, the
+  # generated conventions and the state diagram. These render strings and
+  # draw on STDERR; none of them changes a plan.
+  module Presentation
+    module_function
+
+    # @return [String] the conventions document, derived
+    def documentation = Documentation.new.render
+
+    # @return [String] the state machine, drawn for a terminal
+    def diagram = Diagram.new.render
+
+    # @param tree [Agentilda::Plans::Tree]
+    # @return [Agentilda::Presentation::Reporter]
+    def reporter(tree:) = Reporter.new(tree:)
+
+    # @return [Agentilda::Presentation::Viewer]
+    def viewer = Viewer.new
+  end
+end