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>.
Check each before starting:
python3 --version — any Python 3.8+.http://127.0.0.1:8477).python3 server.py 8481).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>
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()
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" }
]
}
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>
cd this-or-that && python3 server.py
# → this-or-that → http://127.0.0.1:8477/compare.html
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.
compare.html fetches options.json and POSTs votes — file:// breaks both. Always go through server.py.this-or-that/). Cross-origin option URLs render, but scroll-sync and the light/dark stamp fail silently.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.DECISIONS.md so future sessions inherit the preference record instead of re-asking.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.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/).# 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/`).