The Auto-Screencast

The Auto-Screencast: a plan that records its own tutorial. Every step carries narration and code; as the plan executes, it emits a markdown episode - prose, code fence, actual output - and then the strange part: the episode is PLAYED BACK. The fences are extracted and re-executed in a fresh context, and the replayed outputs must match what the recording captured. The tutorial is a doctest of itself. Every screencaster knows the shame of the episode that doesn't run on the …

source on github

a real captured run

THE AUTO-SCREENCAST (if the episode doesn't run, it doesn't ship)

  recorded: 4 scenes -> episode-042.md (37 lines of markdown)
  final take: "LAMP x3 - total 5130 cents"

  playback: 4/4 fences re-executed in a fresh context
  every replayed output matches the recording: true

  then an editor 'improves' the discount inside the markdown (0.9 -> 0.8):
  playback catches 2 scene(s) where the fence no longer produces
  its own '# =>' line - the episode convicts its editor.

  the trick is one rule, applied twice: code you SHOW must be code
  you RAN. recording enforces it forward (the fence's # => line is
  the actual output, captured mid-plan by the step that made it),
  and playback enforces it backward (fences are re-executed and
  must reproduce their own annotations - so when someone edits the
  discount in the prose, scene 3 AND the receipt in scene 4 both
  testify). tutorials rot because they're transcripts of a run
  nobody can repeat. this one ships with its own repeat button,
  and refuses to publish a take it can't reproduce.

source

# frozen_string_literal: true

# The Auto-Screencast: a plan that records its own tutorial. Every
# step carries narration and code; as the plan executes, it emits a
# markdown episode - prose, code fence, actual output - and then the
# strange part: the episode is PLAYED BACK. The fences are extracted
# and re-executed in a fresh context, and the replayed outputs must
# match what the recording captured. The tutorial is a doctest of
# itself. Every screencaster knows the shame of the episode that
# doesn't run on the viewer's machine; this one refuses to exist in
# that state. If the episode doesn't run, it doesn't ship.
#
#   bundle exec ruby examples/auto_screencast.rb
#
# Runs offline; exits 1 unless the episode replays faithfully AND
# tampering is detected.

require class="s">"bundler/setup"
require class="s">"agentic"
require class="s">"tmpdir"

Agentic.logger.level = class="y">:fatal

EPISODE = [
  {title: class="s">"Take the order", narration: class="s">"Everything starts with data you can see. No magic yet.",
   code: 'ctx[class="y">:order] = {sku: class="s">"lamp", qty: 3, unit_cents: 1900}'},
  {title: class="s">"Price it", narration: class="s">"Multiply, in integer cents. Floats are for lighting, not money.",
   code: class="s">"ctx[class="y">:subtotal] = ctx[class="y">:order][class="y">:qty] * ctx[class="y">:order][class="y">:unit_cents]"},
  {title: class="s">"Apply the bulk discount", narration: class="s">"Three or more lamps? You're furnishing an office. 10% off.",
   code: class="s">"ctx[class="y">:total] = (ctx[class="y">:order][class="y">:qty] >= 3) ? (ctx[class="y">:subtotal] * 0.9).round : ctx[class="y">:subtotal]"},
  {title: class="s">"Print the receipt", narration: class="s">"And the payoff - always end an episode with visible output.",
   code: 'ctx[class="y">:receipt] = class="s">"LAMP x#{ctx[class="y">:order][class="y">:qty]} - total #{ctx[class="y">:total]} cents"'} # rubocop:disable Lint/InterpolationCheck -- the interpolation belongs to the RECORDED code, evaluated at playback
].freeze

# --- the recording session: each step is a task; the camera is a hook ----------------
def record(episode)
  orchestrator = Agentic:class="y">:PlanOrchestrator.new(concurrency_limit: 1)
  ctx = {}
  takes = []
  previous = nil
  episode.each do |step|
    task = Agentic:class="y">:Task.new(description: step[class="y">:title], agent_spec: {class="s">"name" => step[class="y">:title], class="s">"instructions" => class="s">"w"})
    orchestrator.add_task(task, previous ? [previous] : [], agent: ->(_t) {
      result = eval(step[class="y">:code], binding, class="s">"episode") # rubocop:disable Security/Eval -- the code IS the content being recorded
      takes << {step: step, output: result.inspect}
      result
    })
    previous = task
  end
  orchestrator.execute_plan
  takes
end

def render_markdown(takes)
  takes.each_with_index.map { |take, i|
    <<~MD
      ## #{i + 1}. #{take[:step][:title]}

      #{take[:step][:narration]}

      ```ruby
      #{take[:step][:code]}
      # => #{take[:output]}
      ```
    MD
  }.join(class="s">"\n")
end

# --- playback: extract the fences, re-run them fresh, compare ------------------------
def replay(markdown)
  ctx = {}
  markdown.scan(/```ruby\n(.*?)\n# => (.*?)\n```/m).map do |code, recorded|
    {recorded: recorded, replayed: eval(code, binding, class="s">"playback").inspect} # rubocop:disable Security/Eval -- replaying the recorded fences is the point
  end
end

puts class="s">"THE AUTO-SCREENCAST (if the episode doesn't run, it doesn't ship)"
puts

takes = record(EPISODE)
markdown = render_markdown(takes)
episode_path = File.join(Dir.mktmpdir(class="s">"screencast"), class="s">"episode-042.md")
File.write(episode_path, class="s">"# Episode 42: Pricing lamps, honestly\n\n#{markdown}")
puts class="s">"  recorded: #{EPISODE.size} scenes -> #{File.basename(episode_path)} (#{File.read(episode_path).lines.size} lines of markdown)"
puts class="s">"  final take: #{takes.last[class="y">:output]}"
puts

checks = replay(File.read(episode_path))
faithful = checks.all? { |c| c[class="y">:recorded] == c[class="y">:replayed] }
puts class="s">"  playback: #{checks.size}/#{EPISODE.size} fences re-executed in a fresh context"
puts class="s">"  every replayed output matches the recording: #{faithful}"
puts

# --- the tamper reel: an editor 'improves' the discount in the markdown --------------
tampered = File.read(episode_path).sub(class="s">"* 0.9", class="s">"* 0.8")
tampered_checks = replay(tampered)
caught = tampered_checks.count { |c| c[class="y">:recorded] != c[class="y">:replayed] }
puts class="s">"  then an editor 'improves' the discount inside the markdown (0.9 -> 0.8):"
puts class="s">"  playback catches #{caught} scene(s) where the fence no longer produces"
puts class="s">"  its own '# =>' line - the episode convicts its editor."
puts

failures = []
failures << class="s">"recording incomplete" unless takes.size == EPISODE.size && takes.last[class="y">:output].include?(class="s">"5130")
failures << class="s">"playback unfaithful" unless faithful
failures << class="s">"tampering went undetected" unless caught >= 2

puts class="s">"  the trick is one rule, applied twice: code you SHOW must be code"
puts class="s">"  you RAN. recording enforces it forward (the fence's # => line is"
puts class="s">"  the actual output, captured mid-plan by the step that made it),"
puts class="s">"  and playback enforces it backward (fences are re-executed and"
puts class="s">"  must reproduce their own annotations - so when someone edits the"
puts class="s">"  discount in the prose, scene 3 AND the receipt in scene 4 both"
puts class="s">"  testify). tutorials rot because they're transcripts of a run"
puts class="s">"  nobody can repeat. this one ships with its own repeat button,"
puts class="s">"  and refuses to publish a take it can't reproduce."
exit(failures.empty? ? 0 : 1)