This or That: RLHF for Your Agent — agent setup guide

Following this file sets up: a local "this or that" voting lab in the user's current project — a duel harness page, a tiny vote-recording server, a manifest of options, and three demo options. The user votes with arrow keys; every vote is appended to votes.jsonl for you (the agent) to read and act on.

Human companion pages on this site: the section guide (kit, prompts, the full write-up), the Session Replay (turn-by-turn replay of the round where this loop chose the workshop's own page format — 13 formats, 27 votes), and the Socratic Dialogue (attendee Q&A).

Placeholders used below: <project-root> = the project you are working in. All paths are relative to <project-root>.

Prerequisites

Check each before starting:

Steps

  1. Create this-or-that/compare.html with exactly this content — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, s skip, f finish, per-vote notes, optional light/dark axis, synced scrolling):
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>this or that</title>
<style>
:root{color-scheme:dark}
*{box-sizing:border-box}
body{margin:0;font:14px/1.45 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;background:#101114;color:#e8e8ea;height:100vh;display:flex;flex-direction:column;overflow:hidden}
header{display:flex;align-items:center;gap:.9rem;padding:.5rem .9rem;background:#17181c;border-bottom:1px solid #26272c;flex:0 0 auto;flex-wrap:wrap}
#status{font-weight:700;white-space:nowrap}
#mode{font-weight:700;font-size:12px;padding:.2rem .6rem;border-radius:99px;border:1px solid #34353c;cursor:pointer;white-space:nowrap;display:none}
#mode.on{display:inline-block}
#mode.light{background:#f5f2ea;color:#3a3830}
#mode.dark{background:#0d0b08;color:#d8d2c4}
#board{color:#9fa3ad;font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
#board b{color:#ffd479}
#hint{color:#8b8d94;font-size:12px}
.hbtn{background:#26272c;color:#c9cbd2;border:1px solid #34353c;border-radius:6px;padding:.3rem .7rem;font:inherit;font-size:12px;cursor:pointer;white-space:nowrap}
.hbtn:hover{border-color:#4a4c55;color:#fff}
.hbtn.warn{color:#ff9d9d}
#note{margin-left:auto;background:#0d0e11;border:1px solid #2a2b31;color:#e8e8ea;border-radius:6px;padding:.35rem .6rem;width:240px;font:inherit}
#note::placeholder{color:#5b5d66}
.stage{flex:1;display:flex;min-height:0}
.pane{flex:1;display:flex;flex-direction:column;min-width:0;border-right:1px solid #26272c}
.pane:last-child{border-right:0}
.pane-bar{display:flex;align-items:center;gap:.6rem;padding:.38rem .8rem;background:#131418;border-bottom:1px solid #26272c}
.pane-bar b{font-size:13px}
.pane-bar .side{color:#8b8d94;font-size:12px}
.pane-bar button{margin-left:auto;background:#2b6cf6;color:#fff;border:0;border-radius:6px;padding:.3rem .85rem;font-weight:600;cursor:pointer;font:inherit}
.pane-bar button:hover{background:#3d7bff}
iframe{flex:1;border:0;width:100%;background:#fff}
kbd{background:#26272c;border:1px solid #34353c;border-bottom-width:2px;border-radius:4px;padding:0 .4rem;font-family:ui-monospace,Menlo,monospace;font-size:12px}
#overlay{position:fixed;inset:0;background:rgba(8,8,10,.93);display:none;place-items:center;z-index:9}
#overlay.show{display:grid}
.card{background:#17181c;border:1px solid #2a2b31;border-radius:14px;padding:1.5rem 1.9rem;max-width:680px;max-height:85vh;overflow:auto}
.card h2{margin:0 0 .7rem}
.card table{border-collapse:collapse;width:100%;margin:.5rem 0 1rem}
.card td,.card th{padding:.28rem .6rem;border-bottom:1px solid #26272c;text-align:left;font-size:13px}
.card th{color:#8b8d94;font-weight:600}
.card p{color:#b9bbc3}
.card button{background:#2b6cf6;color:#fff;border:0;border-radius:8px;padding:.5rem 1.1rem;font-weight:600;cursor:pointer;font:inherit}
</style>
</head>
<body>
<header>
  <span id="status"></span>
  <button id="mode" onclick="toggleMode(true)"></button>
  <span id="board"></span>
  <button class="hbtn warn" onclick="bothBad()">Both bad <kbd>↓</kbd></button>
  <button class="hbtn" onclick="skip()">Skip <kbd>s</kbd></button>
  <button class="hbtn" onclick="finish()">Finish <kbd>f</kbd></button>
  <span id="hint"></span>
  <input id="note" placeholder="optional note — saved with vote">
</header>
<div class="stage" id="stage"></div>
<div id="overlay"><div class="card" id="ocard"></div></div>
<script>
'use strict';
let V = [], MODES = false, TITLE = 'this or that';
const K = 32;
let elo = [], games = [], rec = [];
let mode = 'duel', A = -1, B = -1, voteN = 0, duelN = 0, browseI = 0, lastKey = '';
let uiMode = 'light', toggled = false;

const stage = document.getElementById('stage');
const statusEl = document.getElementById('status');
const modeEl = document.getElementById('mode');
const board = document.getElementById('board');
const hint = document.getElementById('hint');
const note = document.getElementById('note');
const overlay = document.getElementById('overlay');

const N = () => V.length;
const src = i => V[i].src;
const name = i => V[i].name;

function post(d){ d.lab = TITLE; fetch('/vote',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(d)}).catch(()=>{}); }
function expected(ra, rb){ return 1/(1+Math.pow(10,(rb-ra)/400)); }
function applyResult(w, l){
  const ew = expected(elo[w], elo[l]);
  elo[w] = Math.round(elo[w] + K*(1-ew));
  elo[l] = Math.round(elo[l] - K*(1-ew));
  games[w]++; games[l]++;
  if (MODES) rec[w][uiMode].w++, rec[l][uiMode].l++;
}
function ranked(){ return V.map((v,i)=>i).sort((a,b)=>elo[b]-elo[a]); }
function renderBoard(){
  board.innerHTML = 'top: ' + ranked().slice(0,3).map(i=>`<b>${name(i)}</b> ${elo[i]}`).join(' · ');
}
function renderMode(){
  if (!MODES) return;
  modeEl.className = 'on ' + uiMode;
  modeEl.textContent = (uiMode === 'light' ? '☀ light' : '☾ dark') + ' — d flips';
}
function applyMode(){
  renderMode();
  if (!MODES) return;
  document.querySelectorAll('iframe').forEach(f => {
    try { f.contentWindow.document.documentElement.dataset.mode = uiMode; } catch(e){}
  });
}
window.toggleMode = (manual) => {
  if (!MODES) return;
  uiMode = uiMode === 'light' ? 'dark' : 'light';
  if (manual) toggled = true;
  applyMode();
};
function pickPair(){
  let best = null, bestScore = Infinity;
  for (let i=0;i<N();i++) for (let j=i+1;j<N();j++){
    const key = i+'-'+j;
    if (key === lastKey) continue;
    const score = (games[i]+games[j])*60 + Math.abs(elo[i]-elo[j]) + Math.random()*40;
    if (score < bestScore){ bestScore = score; best = [i,j]; }
  }
  lastKey = best[0]+'-'+best[1];
  return Math.random() < .5 ? best : [best[1], best[0]];
}
function hookIframes(){
  const frames = [...document.querySelectorAll('iframe')];
  frames.forEach(f => f.addEventListener('load', () => {
    try {
      if (MODES) f.contentWindow.document.documentElement.dataset.mode = uiMode;
      f.contentWindow.addEventListener('keydown', onKey);
      const other = frames.find(x => x !== f);
      if (!other) return;
      let lock = false;
      f.contentWindow.addEventListener('scroll', () => {
        if (lock) { lock = false; return; }
        try {
          const a = f.contentWindow, b = other.contentWindow;
          const ah = a.document.documentElement.scrollHeight - a.innerHeight;
          const bh = b.document.documentElement.scrollHeight - b.innerHeight;
          if (ah > 0 && bh > 0){ lock = true; b.scrollTo(0, a.scrollY/ah*bh); }
        } catch(e){}
      }, {passive:true});
    } catch(e){}
  }));
}
function paneHTML(i, side, key){
  return `<div class="pane"><div class="pane-bar"><b>${name(i)}</b><span class="side">${side} · elo ${elo[i]} · ${games[i]} games</span>`+
        `<button onclick="pick('${side}')">This one <kbd>${key}</kbd></button></div>`+
        `<iframe src="${src(i)}"></iframe></div>`;
}
function renderDuel(){
  [A, B] = pickPair();
  duelN++;
  if (MODES){ uiMode = duelN % 2 ? 'light' : 'dark'; toggled = false; }
  stage.innerHTML = paneHTML(A,'left','←') + paneHTML(B,'right','→');
  statusEl.textContent = `Vote ${voteN+1}`;
  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> pick · winner-agnostic pairing · vote until it stops being informative';
  renderBoard(); renderMode();
  hookIframes();
}
window.pick = side => {
  if (mode !== 'duel') return;
  const w = side === 'left' ? A : B, l = side === 'left' ? B : A;
  applyResult(w, l);
  voteN++;
  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), winner:name(w), loser:name(l),
             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
  post(d);
  note.value = '';
  renderDuel();
};
window.bothBad = () => {
  if (mode !== 'duel') return;
  elo[A] = Math.round(elo[A] - 12); elo[B] = Math.round(elo[B] - 12);
  games[A]++; games[B]++;
  voteN++;
  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), result:'both_bad',
             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
  post(d);
  note.value = '';
  renderDuel();
};
window.skip = () => { if (mode === 'duel') renderDuel(); };
window.finish = () => {
  if (mode !== 'duel') return;
  mode = 'browse'; browseI = ranked()[0];
  const table = ranked().map(i => {
    const r = {id:V[i].id, name:name(i), elo:elo[i], games:games[i]};
    if (MODES){ r.light = `${rec[i].light.w}-${rec[i].light.l}`; r.dark = `${rec[i].dark.w}-${rec[i].dark.l}`; }
    return r;
  });
  post({mode:'final', votes:voteN, table});
  document.getElementById('ocard').innerHTML =
    `<h2>Standings — ${voteN} votes</h2>`+
    `<table><tr><th>#</th><th>Option</th><th>Elo</th><th>Games</th>${MODES?'<th>Light W-L</th><th>Dark W-L</th>':''}</tr>`+
    table.map((r,i)=>`<tr><td>${i+1}</td><td>${r.name}</td><td>${r.elo}</td><td>${r.games}</td>${MODES?`<td>${r.light}</td><td>${r.dark}</td>`:''}</tr>`).join('')+
    `</table><p>Saved to <code>votes.jsonl</code> — tell your agent to read it. <kbd>←</kbd>/<kbd>→</kbd> browse · <kbd>r</kbd> keep voting</p>`+
    `<button onclick="closeOverlay()">Browse →</button>`;
  overlay.classList.add('show');
};
window.closeOverlay = () => { overlay.classList.remove('show'); renderBrowse(); };
function renderBrowse(){
  stage.innerHTML = `<div class="pane"><div class="pane-bar"><b>${name(browseI)}</b>`+
    `<span class="side">elo ${elo[browseI]} · ${ranked().indexOf(browseI)+1} of ${N()}</span></div><iframe src="${src(browseI)}"></iframe></div>`;
  statusEl.textContent = 'Browse';
  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> cycle by rank · <kbd>r</kbd> keep voting';
  hookIframes();
}
function onKey(e){
  if (e.target === note) return;
  if (e.key === 'd'){ toggleMode(true); return; }
  if (mode === 'duel'){
    if (e.key === 'ArrowLeft'){ e.preventDefault(); pick('left'); }
    else if (e.key === 'ArrowRight'){ e.preventDefault(); pick('right'); }
    else if (e.key === 'ArrowDown'){ e.preventDefault(); bothBad(); }
    else if (e.key === 's'){ skip(); }
    else if (e.key === 'f' || e.key === 'Enter'){ finish(); }
  } else {
    const order = ranked();
    const pos = order.indexOf(browseI);
    if (e.key === 'ArrowLeft'){ browseI = order[(pos+N()-1)%N()]; renderBrowse(); }
    else if (e.key === 'ArrowRight'){ browseI = order[(pos+1)%N()]; renderBrowse(); }
    else if (e.key === 'r'){ mode = 'duel'; renderDuel(); }
  }
}
document.addEventListener('keydown', onKey);

fetch('options.json').then(r => r.json()).then(cfg => {
  TITLE = cfg.title || TITLE;
  MODES = !!cfg.modes;
  V = cfg.options;
  document.title = TITLE + ' — this or that';
  elo = V.map(() => 1000);
  games = V.map(() => 0);
  rec = V.map(() => ({light:{w:0,l:0}, dark:{w:0,l:0}}));
  renderDuel();
}).catch(() => {
  stage.innerHTML = '<div style="padding:2rem;color:#ff9d9d">Could not load options.json — serve this directory with server.py, not file://</div>';
});
</script>
</body>
</html>
  1. Create this-or-that/server.py — serves the directory and appends every POSTed vote to votes.jsonl:
#!/usr/bin/env python3
"""this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl."""
import json, os, sys, time
from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler

ROOT = os.path.dirname(os.path.abspath(__file__))
PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477

class Handler(SimpleHTTPRequestHandler):
    def __init__(self, *a, **kw):
        super().__init__(*a, directory=ROOT, **kw)

    def do_POST(self):
        if self.path != "/vote":
            self.send_response(404); self.end_headers(); return
        n = int(self.headers.get("Content-Length", 0))
        try:
            data = json.loads(self.rfile.read(n) or b"{}")
        except Exception:
            data = {"error": "unparseable"}
        data["ts"] = time.strftime("%Y-%m-%dT%H:%M:%S")
        with open(os.path.join(ROOT, "votes.jsonl"), "a", encoding="utf-8") as f:
            f.write(json.dumps(data) + "\n")
        self.send_response(204); self.end_headers()

    def log_message(self, *a):
        pass

if __name__ == "__main__":
    print(f"this-or-that → http://127.0.0.1:{PORT}/compare.html")
    ThreadingHTTPServer(("127.0.0.1", PORT), Handler).serve_forever()
  1. Create this-or-that/options.json — the manifest. src is anything an iframe can render (HTML page, image, code/text file). Set "modes": true only if every option responds to <html data-mode="light|dark">; duels then alternate modes, d flips both panes, and per-mode win-loss records are tracked:
{
  "title": "Pick a direction",
  "modes": false,
  "options": [
    { "id": "a", "name": "Option A", "src": "options/sample-a.html" },
    { "id": "b", "name": "Option B", "src": "options/sample-b.html" },
    { "id": "c", "name": "Option C", "src": "options/sample-c.html" }
  ]
}
  1. Create the three demo options (same subject, three deliberately different styles). For a real decision, replace these with the user's options and update options.json:

this-or-that/options/sample-a.html:

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>A</title>
<style>body{margin:0;font-family:system-ui;background:oklch(98% .008 80);color:oklch(16% .008 80);display:grid;place-items:center;min-height:100vh}
.hero{max-width:26rem;padding:2rem}.hero h1{font-size:2.6rem;font-weight:820;letter-spacing:-.03em;line-height:1;margin:0 0 .6rem}
.hero p{color:oklch(55% .016 80)}.hero button{background:oklch(60% .19 40);color:#fff;border:0;padding:.7rem 1.4rem;font:inherit;font-weight:700;text-transform:uppercase;font-size:.7rem;letter-spacing:.06em}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option A: big type, one accent, flat.</p><button>Get started</button></div></body></html>

this-or-that/options/sample-b.html:

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>B</title>
<style>body{margin:0;font-family:ui-serif,Georgia,serif;background:oklch(97% .02 85);color:oklch(22% .015 80);display:grid;place-items:center;min-height:100vh}
.hero{max-width:24rem;padding:2rem;text-align:center}.hero h1{font-size:2.1rem;font-weight:650;margin:0 0 .6rem}
.hero p{font-style:italic;color:oklch(50% .03 80)}.hero button{background:none;color:oklch(45% .13 25);border:2px solid currentColor;border-radius:99px;padding:.6rem 1.5rem;font:inherit;font-weight:600}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option B: centered serif, soft, outlined.</p><button>Get started</button></div></body></html>

this-or-that/options/sample-c.html:

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>C</title>
<style>body{margin:0;font-family:ui-monospace,Menlo,monospace;background:oklch(15% .01 250);color:oklch(90% .01 250);display:grid;place-items:center;min-height:100vh}
.hero{max-width:26rem;padding:2rem;border:1px solid oklch(35% .02 250)}.hero h1{font-size:1.6rem;font-weight:700;margin:0 0 .6rem}.hero h1::before{content:"$ ";color:oklch(75% .15 150)}
.hero p{color:oklch(65% .02 250)}.hero button{background:oklch(75% .15 150);color:oklch(15% .05 150);border:0;padding:.6rem 1.2rem;font:inherit;font-weight:700}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option C: terminal dark, mono, green go.</p><button>Get started</button></div></body></html>
  1. Start the server and tell the user where to vote:
cd this-or-that && python3 server.py
# → this-or-that → http://127.0.0.1:8477/compare.html

Success check

With the server running:

curl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{"probe":true}'
tail -1 this-or-that/votes.jsonl
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8477/compare.html

Expected: the tail prints a JSON line containing "probe": true plus a "ts" timestamp, and the last command prints 200. Also confirm in a browser that compare.html shows two options side by side with "This one" buttons. Report all results to your user, then remove the probe line from votes.jsonl.

Notes for agents

# This or That: RLHF for Your Agent — agent setup guide

Following this file sets up: a local "this or that" voting lab in the user's current project — a duel harness page, a tiny vote-recording server, a manifest of options, and three demo options. The user votes with arrow keys; every vote is appended to `votes.jsonl` for you (the agent) to read and act on.

Human companion pages on this site: the [section guide](https://gentle-lasso-9d5n.here.now/) (kit, prompts, the full write-up), the [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) (turn-by-turn replay of the round where this loop chose the workshop's own page format — 13 formats, 27 votes), and the [Socratic Dialogue](https://gentle-lasso-9d5n.here.now/dialogue.html) (attendee Q&A).

Placeholders used below: `<project-root>` = the project you are working in. All paths are relative to `<project-root>`.

## Prerequisites

Check each before starting:

- `python3 --version` — any Python 3.8+.
- A browser on the same machine (the lab runs at `http://127.0.0.1:8477`).
- Port 8477 free (or pick another: `python3 server.py 8481`).

## Steps

1. Create `this-or-that/compare.html` with exactly this content — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, `s` skip, `f` finish, per-vote notes, optional light/dark axis, synced scrolling):

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>this or that</title>
<style>
:root{color-scheme:dark}
*{box-sizing:border-box}
body{margin:0;font:14px/1.45 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;background:#101114;color:#e8e8ea;height:100vh;display:flex;flex-direction:column;overflow:hidden}
header{display:flex;align-items:center;gap:.9rem;padding:.5rem .9rem;background:#17181c;border-bottom:1px solid #26272c;flex:0 0 auto;flex-wrap:wrap}
#status{font-weight:700;white-space:nowrap}
#mode{font-weight:700;font-size:12px;padding:.2rem .6rem;border-radius:99px;border:1px solid #34353c;cursor:pointer;white-space:nowrap;display:none}
#mode.on{display:inline-block}
#mode.light{background:#f5f2ea;color:#3a3830}
#mode.dark{background:#0d0b08;color:#d8d2c4}
#board{color:#9fa3ad;font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
#board b{color:#ffd479}
#hint{color:#8b8d94;font-size:12px}
.hbtn{background:#26272c;color:#c9cbd2;border:1px solid #34353c;border-radius:6px;padding:.3rem .7rem;font:inherit;font-size:12px;cursor:pointer;white-space:nowrap}
.hbtn:hover{border-color:#4a4c55;color:#fff}
.hbtn.warn{color:#ff9d9d}
#note{margin-left:auto;background:#0d0e11;border:1px solid #2a2b31;color:#e8e8ea;border-radius:6px;padding:.35rem .6rem;width:240px;font:inherit}
#note::placeholder{color:#5b5d66}
.stage{flex:1;display:flex;min-height:0}
.pane{flex:1;display:flex;flex-direction:column;min-width:0;border-right:1px solid #26272c}
.pane:last-child{border-right:0}
.pane-bar{display:flex;align-items:center;gap:.6rem;padding:.38rem .8rem;background:#131418;border-bottom:1px solid #26272c}
.pane-bar b{font-size:13px}
.pane-bar .side{color:#8b8d94;font-size:12px}
.pane-bar button{margin-left:auto;background:#2b6cf6;color:#fff;border:0;border-radius:6px;padding:.3rem .85rem;font-weight:600;cursor:pointer;font:inherit}
.pane-bar button:hover{background:#3d7bff}
iframe{flex:1;border:0;width:100%;background:#fff}
kbd{background:#26272c;border:1px solid #34353c;border-bottom-width:2px;border-radius:4px;padding:0 .4rem;font-family:ui-monospace,Menlo,monospace;font-size:12px}
#overlay{position:fixed;inset:0;background:rgba(8,8,10,.93);display:none;place-items:center;z-index:9}
#overlay.show{display:grid}
.card{background:#17181c;border:1px solid #2a2b31;border-radius:14px;padding:1.5rem 1.9rem;max-width:680px;max-height:85vh;overflow:auto}
.card h2{margin:0 0 .7rem}
.card table{border-collapse:collapse;width:100%;margin:.5rem 0 1rem}
.card td,.card th{padding:.28rem .6rem;border-bottom:1px solid #26272c;text-align:left;font-size:13px}
.card th{color:#8b8d94;font-weight:600}
.card p{color:#b9bbc3}
.card button{background:#2b6cf6;color:#fff;border:0;border-radius:8px;padding:.5rem 1.1rem;font-weight:600;cursor:pointer;font:inherit}
</style>
</head>
<body>
<header>
  <span id="status"></span>
  <button id="mode" onclick="toggleMode(true)"></button>
  <span id="board"></span>
  <button class="hbtn warn" onclick="bothBad()">Both bad <kbd>↓</kbd></button>
  <button class="hbtn" onclick="skip()">Skip <kbd>s</kbd></button>
  <button class="hbtn" onclick="finish()">Finish <kbd>f</kbd></button>
  <span id="hint"></span>
  <input id="note" placeholder="optional note — saved with vote">
</header>
<div class="stage" id="stage"></div>
<div id="overlay"><div class="card" id="ocard"></div></div>
<script>
'use strict';
let V = [], MODES = false, TITLE = 'this or that';
const K = 32;
let elo = [], games = [], rec = [];
let mode = 'duel', A = -1, B = -1, voteN = 0, duelN = 0, browseI = 0, lastKey = '';
let uiMode = 'light', toggled = false;

const stage = document.getElementById('stage');
const statusEl = document.getElementById('status');
const modeEl = document.getElementById('mode');
const board = document.getElementById('board');
const hint = document.getElementById('hint');
const note = document.getElementById('note');
const overlay = document.getElementById('overlay');

const N = () => V.length;
const src = i => V[i].src;
const name = i => V[i].name;

function post(d){ d.lab = TITLE; fetch('/vote',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(d)}).catch(()=>{}); }
function expected(ra, rb){ return 1/(1+Math.pow(10,(rb-ra)/400)); }
function applyResult(w, l){
  const ew = expected(elo[w], elo[l]);
  elo[w] = Math.round(elo[w] + K*(1-ew));
  elo[l] = Math.round(elo[l] - K*(1-ew));
  games[w]++; games[l]++;
  if (MODES) rec[w][uiMode].w++, rec[l][uiMode].l++;
}
function ranked(){ return V.map((v,i)=>i).sort((a,b)=>elo[b]-elo[a]); }
function renderBoard(){
  board.innerHTML = 'top: ' + ranked().slice(0,3).map(i=>`<b>${name(i)}</b> ${elo[i]}`).join(' · ');
}
function renderMode(){
  if (!MODES) return;
  modeEl.className = 'on ' + uiMode;
  modeEl.textContent = (uiMode === 'light' ? '☀ light' : '☾ dark') + ' — d flips';
}
function applyMode(){
  renderMode();
  if (!MODES) return;
  document.querySelectorAll('iframe').forEach(f => {
    try { f.contentWindow.document.documentElement.dataset.mode = uiMode; } catch(e){}
  });
}
window.toggleMode = (manual) => {
  if (!MODES) return;
  uiMode = uiMode === 'light' ? 'dark' : 'light';
  if (manual) toggled = true;
  applyMode();
};
function pickPair(){
  let best = null, bestScore = Infinity;
  for (let i=0;i<N();i++) for (let j=i+1;j<N();j++){
    const key = i+'-'+j;
    if (key === lastKey) continue;
    const score = (games[i]+games[j])*60 + Math.abs(elo[i]-elo[j]) + Math.random()*40;
    if (score < bestScore){ bestScore = score; best = [i,j]; }
  }
  lastKey = best[0]+'-'+best[1];
  return Math.random() < .5 ? best : [best[1], best[0]];
}
function hookIframes(){
  const frames = [...document.querySelectorAll('iframe')];
  frames.forEach(f => f.addEventListener('load', () => {
    try {
      if (MODES) f.contentWindow.document.documentElement.dataset.mode = uiMode;
      f.contentWindow.addEventListener('keydown', onKey);
      const other = frames.find(x => x !== f);
      if (!other) return;
      let lock = false;
      f.contentWindow.addEventListener('scroll', () => {
        if (lock) { lock = false; return; }
        try {
          const a = f.contentWindow, b = other.contentWindow;
          const ah = a.document.documentElement.scrollHeight - a.innerHeight;
          const bh = b.document.documentElement.scrollHeight - b.innerHeight;
          if (ah > 0 && bh > 0){ lock = true; b.scrollTo(0, a.scrollY/ah*bh); }
        } catch(e){}
      }, {passive:true});
    } catch(e){}
  }));
}
function paneHTML(i, side, key){
  return `<div class="pane"><div class="pane-bar"><b>${name(i)}</b><span class="side">${side} · elo ${elo[i]} · ${games[i]} games</span>`+
        `<button onclick="pick('${side}')">This one <kbd>${key}</kbd></button></div>`+
        `<iframe src="${src(i)}"></iframe></div>`;
}
function renderDuel(){
  [A, B] = pickPair();
  duelN++;
  if (MODES){ uiMode = duelN % 2 ? 'light' : 'dark'; toggled = false; }
  stage.innerHTML = paneHTML(A,'left','←') + paneHTML(B,'right','→');
  statusEl.textContent = `Vote ${voteN+1}`;
  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> pick · winner-agnostic pairing · vote until it stops being informative';
  renderBoard(); renderMode();
  hookIframes();
}
window.pick = side => {
  if (mode !== 'duel') return;
  const w = side === 'left' ? A : B, l = side === 'left' ? B : A;
  applyResult(w, l);
  voteN++;
  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), winner:name(w), loser:name(l),
             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
  post(d);
  note.value = '';
  renderDuel();
};
window.bothBad = () => {
  if (mode !== 'duel') return;
  elo[A] = Math.round(elo[A] - 12); elo[B] = Math.round(elo[B] - 12);
  games[A]++; games[B]++;
  voteN++;
  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), result:'both_bad',
             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
  post(d);
  note.value = '';
  renderDuel();
};
window.skip = () => { if (mode === 'duel') renderDuel(); };
window.finish = () => {
  if (mode !== 'duel') return;
  mode = 'browse'; browseI = ranked()[0];
  const table = ranked().map(i => {
    const r = {id:V[i].id, name:name(i), elo:elo[i], games:games[i]};
    if (MODES){ r.light = `${rec[i].light.w}-${rec[i].light.l}`; r.dark = `${rec[i].dark.w}-${rec[i].dark.l}`; }
    return r;
  });
  post({mode:'final', votes:voteN, table});
  document.getElementById('ocard').innerHTML =
    `<h2>Standings — ${voteN} votes</h2>`+
    `<table><tr><th>#</th><th>Option</th><th>Elo</th><th>Games</th>${MODES?'<th>Light W-L</th><th>Dark W-L</th>':''}</tr>`+
    table.map((r,i)=>`<tr><td>${i+1}</td><td>${r.name}</td><td>${r.elo}</td><td>${r.games}</td>${MODES?`<td>${r.light}</td><td>${r.dark}</td>`:''}</tr>`).join('')+
    `</table><p>Saved to <code>votes.jsonl</code> — tell your agent to read it. <kbd>←</kbd>/<kbd>→</kbd> browse · <kbd>r</kbd> keep voting</p>`+
    `<button onclick="closeOverlay()">Browse →</button>`;
  overlay.classList.add('show');
};
window.closeOverlay = () => { overlay.classList.remove('show'); renderBrowse(); };
function renderBrowse(){
  stage.innerHTML = `<div class="pane"><div class="pane-bar"><b>${name(browseI)}</b>`+
    `<span class="side">elo ${elo[browseI]} · ${ranked().indexOf(browseI)+1} of ${N()}</span></div><iframe src="${src(browseI)}"></iframe></div>`;
  statusEl.textContent = 'Browse';
  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> cycle by rank · <kbd>r</kbd> keep voting';
  hookIframes();
}
function onKey(e){
  if (e.target === note) return;
  if (e.key === 'd'){ toggleMode(true); return; }
  if (mode === 'duel'){
    if (e.key === 'ArrowLeft'){ e.preventDefault(); pick('left'); }
    else if (e.key === 'ArrowRight'){ e.preventDefault(); pick('right'); }
    else if (e.key === 'ArrowDown'){ e.preventDefault(); bothBad(); }
    else if (e.key === 's'){ skip(); }
    else if (e.key === 'f' || e.key === 'Enter'){ finish(); }
  } else {
    const order = ranked();
    const pos = order.indexOf(browseI);
    if (e.key === 'ArrowLeft'){ browseI = order[(pos+N()-1)%N()]; renderBrowse(); }
    else if (e.key === 'ArrowRight'){ browseI = order[(pos+1)%N()]; renderBrowse(); }
    else if (e.key === 'r'){ mode = 'duel'; renderDuel(); }
  }
}
document.addEventListener('keydown', onKey);

fetch('options.json').then(r => r.json()).then(cfg => {
  TITLE = cfg.title || TITLE;
  MODES = !!cfg.modes;
  V = cfg.options;
  document.title = TITLE + ' — this or that';
  elo = V.map(() => 1000);
  games = V.map(() => 0);
  rec = V.map(() => ({light:{w:0,l:0}, dark:{w:0,l:0}}));
  renderDuel();
}).catch(() => {
  stage.innerHTML = '<div style="padding:2rem;color:#ff9d9d">Could not load options.json — serve this directory with server.py, not file://</div>';
});
</script>
</body>
</html>
```

2. Create `this-or-that/server.py` — serves the directory and appends every POSTed vote to `votes.jsonl`:

```python
#!/usr/bin/env python3
"""this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl."""
import json, os, sys, time
from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler

ROOT = os.path.dirname(os.path.abspath(__file__))
PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477

class Handler(SimpleHTTPRequestHandler):
    def __init__(self, *a, **kw):
        super().__init__(*a, directory=ROOT, **kw)

    def do_POST(self):
        if self.path != "/vote":
            self.send_response(404); self.end_headers(); return
        n = int(self.headers.get("Content-Length", 0))
        try:
            data = json.loads(self.rfile.read(n) or b"{}")
        except Exception:
            data = {"error": "unparseable"}
        data["ts"] = time.strftime("%Y-%m-%dT%H:%M:%S")
        with open(os.path.join(ROOT, "votes.jsonl"), "a", encoding="utf-8") as f:
            f.write(json.dumps(data) + "\n")
        self.send_response(204); self.end_headers()

    def log_message(self, *a):
        pass

if __name__ == "__main__":
    print(f"this-or-that → http://127.0.0.1:{PORT}/compare.html")
    ThreadingHTTPServer(("127.0.0.1", PORT), Handler).serve_forever()
```

3. Create `this-or-that/options.json` — the manifest. `src` is anything an iframe can render (HTML page, image, code/text file). Set `"modes": true` only if every option responds to `<html data-mode="light|dark">`; duels then alternate modes, `d` flips both panes, and per-mode win-loss records are tracked:

```json
{
  "title": "Pick a direction",
  "modes": false,
  "options": [
    { "id": "a", "name": "Option A", "src": "options/sample-a.html" },
    { "id": "b", "name": "Option B", "src": "options/sample-b.html" },
    { "id": "c", "name": "Option C", "src": "options/sample-c.html" }
  ]
}
```

4. Create the three demo options (same subject, three deliberately different styles). For a real decision, replace these with the user's options and update `options.json`:

`this-or-that/options/sample-a.html`:

```html
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>A</title>
<style>body{margin:0;font-family:system-ui;background:oklch(98% .008 80);color:oklch(16% .008 80);display:grid;place-items:center;min-height:100vh}
.hero{max-width:26rem;padding:2rem}.hero h1{font-size:2.6rem;font-weight:820;letter-spacing:-.03em;line-height:1;margin:0 0 .6rem}
.hero p{color:oklch(55% .016 80)}.hero button{background:oklch(60% .19 40);color:#fff;border:0;padding:.7rem 1.4rem;font:inherit;font-weight:700;text-transform:uppercase;font-size:.7rem;letter-spacing:.06em}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option A: big type, one accent, flat.</p><button>Get started</button></div></body></html>
```

`this-or-that/options/sample-b.html`:

```html
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>B</title>
<style>body{margin:0;font-family:ui-serif,Georgia,serif;background:oklch(97% .02 85);color:oklch(22% .015 80);display:grid;place-items:center;min-height:100vh}
.hero{max-width:24rem;padding:2rem;text-align:center}.hero h1{font-size:2.1rem;font-weight:650;margin:0 0 .6rem}
.hero p{font-style:italic;color:oklch(50% .03 80)}.hero button{background:none;color:oklch(45% .13 25);border:2px solid currentColor;border-radius:99px;padding:.6rem 1.5rem;font:inherit;font-weight:600}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option B: centered serif, soft, outlined.</p><button>Get started</button></div></body></html>
```

`this-or-that/options/sample-c.html`:

```html
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>C</title>
<style>body{margin:0;font-family:ui-monospace,Menlo,monospace;background:oklch(15% .01 250);color:oklch(90% .01 250);display:grid;place-items:center;min-height:100vh}
.hero{max-width:26rem;padding:2rem;border:1px solid oklch(35% .02 250)}.hero h1{font-size:1.6rem;font-weight:700;margin:0 0 .6rem}.hero h1::before{content:"$ ";color:oklch(75% .15 150)}
.hero p{color:oklch(65% .02 250)}.hero button{background:oklch(75% .15 150);color:oklch(15% .05 150);border:0;padding:.6rem 1.2rem;font:inherit;font-weight:700}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option C: terminal dark, mono, green go.</p><button>Get started</button></div></body></html>
```

5. Start the server and tell the user where to vote:

```bash
cd this-or-that && python3 server.py
# → this-or-that → http://127.0.0.1:8477/compare.html
```

## Success check

With the server running:

```bash
curl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{"probe":true}'
tail -1 this-or-that/votes.jsonl
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8477/compare.html
```

Expected: the `tail` prints a JSON line containing `"probe": true` plus a `"ts"` timestamp, and the last command prints `200`. Also confirm in a browser that `compare.html` shows two options side by side with "This one" buttons. Report all results to your user, then remove the probe line from `votes.jsonl`.

## Notes for agents

- **Serve, don't open as a file.** `compare.html` fetches `options.json` and POSTs votes — `file://` breaks both. Always go through `server.py`.
- **Options must be same-origin** (files inside `this-or-that/`). Cross-origin option URLs render, but scroll-sync and the light/dark stamp fail silently.
- **Generating options for a real decision:** make them genuinely DISTINCT — different structure, not one knob turned. If two options could be confused at arm's length, replace one. Keep the subject constant across all options; only the approach varies. 6–12 options is the useful range.
- **When the user says they're done voting:** read `this-or-that/votes.jsonl`. Vote lines carry `winner`, `loser`, a full `elo` snapshot, and an optional `note`; a `"mode": "final"` line carries the standings table. Report the ranking, infer explicit taste rules (quote the evidence — especially notes and `both_bad` results), and propose the next round: keep the top 2–3, cut the rest, generate new options that push on what won.
- **Bank the outcome.** After a winner ships, append the standings and the inferred taste rules to the project's `DECISIONS.md` so future sessions inherit the preference record instead of re-asking.
- **Productized forms of this loop.** In John's workshop repo, `flows/this-or-that.md` runs an entire round as one mdflow command — `md flows/this-or-that.md --_question "..." --_subject "..."` — and injects the banked taste records fresh on every run (the flow file is printed verbatim on the section guide). For any other repo, the generalized `this-or-that` agent skill (`~/.agents/skills/this-or-that/SKILL.md`) runs the same loop and pulls this exact kit from `https://gentle-lasso-9d5n.here.now/kit/`. Both artifacts are published on this site as machine-fetchable attachments (the `?raw` suffix is required — the bare `.md` URL serves an HTML viewer): the flow at `https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw` (fetch it into `flows/this-or-that.md`; it @-imports two taste-record files by relative path — point those at your own `RESULTS.md` files outside the workshop repo), and the skill at `https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw`. Skill install: `mkdir -p skill-src/this-or-that && curl -fsSL "https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw" -o skill-src/this-or-that/SKILL.md && npx skills add ./skill-src --skill this-or-that -y` — do NOT stage in a dir named `skills/`; the skills CLI claims that name as its own symlink target and installs an empty skill. Proof it works: a second real round (13 authoring formats, 27 votes) chose the Session Replay + Socratic Dialogue page pair now used across the workshop sites — replayed at `https://gentle-lasso-9d5n.here.now/replay.html`.
- **Known failure modes:** port already in use → pass another port (`python3 server.py 8481`) and use that URL everywhere; `votes.jsonl` missing → no votes have been cast yet (the file is created on first POST); a duel pane is blank → that option's `src` path in `options.json` is wrong (paths are relative to `this-or-that/`).