From 9dd4fcf2a367a44fabbc9027dbafc18164a2b7fc Mon Sep 17 00:00:00 2001
From: audit-loop <sricharan.samba@gmail.com>
Date: Mon, 17 Aug 2026 18:49:26 -0400
Subject: [PATCH] =?UTF-8?q?feat(cli):=20'untell=20humanize=20--html'=20?=
 =?UTF-8?q?=E2=80=94=20self-contained=20HTML=20report=20with=20per-span=20?=
 =?UTF-8?q?lock=20explanations=20(Closes=20#30)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude/human-queue.md      |  25 +++
 tests/test_humanize_html.py | 302 ++++++++++++++++++++++++++++++++++++
 untell/rich_output.py       | 239 ++++++++++++++++++++++++++++
 untell/scripts/run.py       |  71 ++++++++-
 4 files changed, 635 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_humanize_html.py

diff --git a/.claude/human-queue.md b/.claude/human-queue.md
index c206ad10..23bf42bf 100644
--- a/.claude/human-queue.md
+++ b/.claude/human-queue.md
@@ -1647,3 +1647,28 @@ RAN    fast suite green (8427 passed) with all changes present; browser tests 75
 SAW    No queue entry in the original commit (discipline slip — repaired here).
 WHY    New CLI surfaces (--browser auto, signals mode) are AMBER per the envelope.
 NEXT   Issue #3 per-rule rubric tests + #2 live-probe e2e evidence: queued for the next wave.
+## 2026-08-17 slice 2 (wave 6, issue #30) — AMBER — new `untell humanize --html` surface (new CLI flag + HTML artifact)
+
+WHAT   Issue #30: `untell humanize --html` now writes a self-contained, deterministic HTML
+       report of the run to stdout: before/after text, pre/post scores, seed, whether it
+       rewrote, the unified --diff payload, and a per-span lock annotation (via the
+       explain/lock machinery — same single source of truth as lock()). Every dynamic value
+       is HTML-escaped (fuzz-tested against <script>/<img>/<svg> injection shapes), and the
+       document carries no external assets (inline <style>, zero <script>/<link>/remote
+       URLs) so it renders from file://. `--html --json` emits a machine-readable envelope
+       (format "untell-html", version 1) holding the report string plus the diff payload,
+       pre/post, seed, rewrote; the --json error path stays parseable. stdout is the clean
+       document (progress suppressed, like --json), so `untell humanize --html ... > r.html`
+       yields a valid page. Determinism + escaping + self-containment pinned by
+       tests/test_humanize_html.py (15 tests).
+RAN    UNTELL_LITE_NO_TORCH=1 python -m untell.scripts.run --tier lite --rewriter composite
+       --seed 11 --max-iters 6 --best-of 3 --html --json "<AI sample>"  (plus the test file)
+SAW    format=untell-html, seed=11, rewrote=True, iters=1, pre max 0.3736 -> post max
+       0.2115, 2 locked spans preserved verbatim; demo_report.html written; 15/15 html
+       tests green; ruff whole-tree clean; full fast suite green (see commit).
+WHY    AMBER: a NEW CLI flag surface (the humanize --html presentation mode). No existing
+       flag, exit code, error message, result shape or library signature changed; the loop
+       result dict is unchanged, so REST/MCP mirror nothing (test_surface_parity already
+       free-lists "html" as CLI-only). No RED file touched.
+NEXT   A human may extend the HTML report (per-sentence flagged annotations, style/voice,
+       det-detailed rows) or surface it in the REST/MCP API; nothing required.
diff --git a/tests/test_humanize_html.py b/tests/test_humanize_html.py
new file mode 100644
index 00000000..d07bda43
--- /dev/null
+++ b/tests/test_humanize_html.py
@@ -0,0 +1,302 @@
+"""Tests for `untell humanize --html` — a self-contained HTML report (issue #30).
+
+The humanize loop already has a rich terminal report and a `--diff` payload. `--html`
+turns the same run into a single self-contained HTML document that can be saved and
+shared. This file pins the properties the issue's acceptance depends on:
+
+1. **Determinism** — identical inputs produce byte-identical output (no timestamp,
+   no random, no process-dependent value), so the artifact is reproducible.
+
+2. **Escaping / injection** — every value that came from the user's text (original,
+   final, locked spans, rules, rationale, warning) is HTML-escaped. Text that IS
+   attacker-shaped markup (a `<script>` inside the text being humanized) must render
+   as inert characters, never as a live tag. Fuzzed here with several hostile shapes.
+
+3. **Self-contained** — the document carries an inline <style> and zero
+   <script>/<link> references or remote URLs, so it renders identically from a
+   file:// path with no external assets and no JS.
+
+4. **It carries the run** — pre/post scores, the seed, whether it rewrote, the
+   unified --diff hunks and the per-span lock annotations (built on the explain
+   machinery, same single source of truth as `lock()`).
+
+5. **CLI contract** — `--html` prints the document on stdout (and only that, so
+   redirecting to a .html file yields a clean page); `--html --json` emits a
+   machine-readable envelope holding the report string plus the diff payload; the
+   error path stays parseable under `--json`.
+"""
+
+from __future__ import annotations
+
+import json
+
+from untell import rich_output
+from untell.rich_output import render_humanize_html
+from untell.scripts.run import main
+
+AI = (
+    "Furthermore, artificial intelligence has fundamentally transformed numerous industries. "
+    "Moreover, organizations utilize it to significantly improve operational efficiency. Overall, "
+    "the impact continues to grow across various sectors according to Smith (2020), rising 47%."
+)
+
+EDITED = AI.replace("fundamentally transformed", "deeply reshaped")
+
+
+def _scores(pre: float, post: float, tier: str = "lite") -> tuple[dict, dict]:
+    return (
+        {"max": pre, "mean": pre * 0.9, "tier": tier, "threshold": 0.30, "flagged": pre >= 0.3},
+        {"max": post, "mean": post * 0.9, "tier": tier, "threshold": 0.30, "flagged": post >= 0.3},
+    )
+
+
+def _sample_diff(original: str, final: str) -> dict:
+    from untell.scripts.explain import explain_spans
+
+    return rich_output.humanize_diff(original, final, locked_spans=explain_spans(original))
+
+
+# ---------------------------------------------------------------------------
+# determinism + self-containment
+# ---------------------------------------------------------------------------
+
+
+def test_the_report_is_deterministic() -> None:
+    a = render_humanize_html(AI, EDITED, *_scores(0.80, 0.20), 1, "converged", diff=_sample_diff(AI, EDITED), seed=7, rewrote=True)
+    b = render_humanize_html(AI, EDITED, *_scores(0.80, 0.20), 1, "converged", diff=_sample_diff(AI, EDITED), seed=7, rewrote=True)
+    assert a == b
+    assert render_humanize_html("x", "y", *_scores(0.5, 0.5), 1, "limit", seed=1) == render_humanize_html(
+        "x", "y", *_scores(0.5, 0.5), 1, "limit", seed=1
+    )
+
+
+def test_the_report_is_a_complete_self_contained_document() -> None:
+    html = render_humanize_html(AI, EDITED, *_scores(0.80, 0.20), 1, "converged", diff=_sample_diff(AI, EDITED), seed=7, rewrote=True)
+    assert html.startswith("<!DOCTYPE html>") and html.strip().endswith("</html>")
+    assert "<style>" in html and "</style>" in html
+    # No external assets: no JS, no stylesheet link, no remote URL anywhere.
+    for marker in ("<script", "</script>", "<link ", "<img ", "src=", "href=", "http://", "https://"):
+        assert marker not in html, f"external-asset marker {marker!r} present in a self-contained report"
+
+
+# ---------------------------------------------------------------------------
+# escaping / injection (this is a defect — fuzz it)
+# ---------------------------------------------------------------------------
+
+_HOSTILE = [
+    "<script>alert(1)</script>",
+    "</script><script>alert(2)</script>",
+    '<img src=x onerror=alert(3)>',
+    '"><script>alert(4)</script>',
+    "<b>bold</b> & <i>italic</i>",
+    "quote ' single \" double",
+    "<svg/onload=alert(5)>",
+]
+
+
+def test_all_hostile_shapes_are_inert_in_the_report() -> None:
+    for hostile in _HOSTILE:
+        html = render_humanize_html(
+            hostile,
+            hostile,  # unchanged path still renders the hostile text
+            *_scores(0.5, 0.5), 1, "converged",
+            diff={"hunks": []}, seed=1, rewrote=False,
+        )
+        # The escaped spelling appears; a live tag never does. Escaping neutralises the
+        # tag boundaries ("><"), so the real invariant is that no literal `tagname` opens.
+        assert "&lt;" in html or "&#x27;" in html or "&quot;" in html
+        for marker in ("<script", "</script", "<img", "<svg", "<b>", "<i>"):
+            assert marker not in html, f"{hostile!r} leaked a live tag {marker!r}"
+
+
+def test_hostile_span_and_rationale_are_escaped() -> None:
+    """Locked spans and their rationale are user-carried text too — a hostile span must
+    not break out of its table cell or execute."""
+    diff = {
+        "format": "untell-diff", "version": 1, "changed": False, "hunks": [],
+        "locked_spans": [
+            {"sentinel": "⟦HZ0000⟧", "span": '<script>bad()</script>', "rules": ["evil"],
+             "rationale": "note <b>with</b> markup"},
+        ],
+        "locks_preserved": 0,
+    }
+    html = render_humanize_html("in", "in", *_scores(0.5, 0.5), 1, "converged", diff=diff, seed=1)
+    assert "<script>bad()</script>" not in html
+    assert "&lt;script&gt;bad()&lt;/script&gt;" in html
+    assert "&lt;b&gt;with&lt;/b&gt;" in html
+
+
+def test_hostile_warning_is_escaped() -> None:
+    html = render_humanize_html(
+        "a", "b", *_scores(0.8, 0.2), 1, "converged",
+        warning='carried <script>warn()</script> payload', diff=_sample_diff("a", "b"), seed=1, rewrote=True,
+    )
+    assert "<script>warn()</script>" not in html
+    assert "&lt;script&gt;warn()&lt;/script&gt;" in html
+
+
+# ---------------------------------------------------------------------------
+# the renderer carries the run
+# ---------------------------------------------------------------------------
+
+
+def test_the_report_carries_scores_seed_rewrote_and_stopped() -> None:
+    pre, post = _scores(0.82, 0.19)
+    html = render_humanize_html(
+        AI, EDITED, pre, post, 3, "converged",
+        diff=_sample_diff(AI, EDITED), seed=42, rewrote=True, tells_before=9, tells_after=3,
+    )
+    assert "0.8200" in html and "0.1900" in html
+    assert "seed: 42" in html
+    assert "Rewrote" in html
+    assert "3 iterations" in html
+    assert "Converged" in html  # the stopped reason, title-cased from the enum value
+    assert "AI tells" in html and "9" in html and "3" in html
+
+
+def test_the_report_says_when_it_did_not_rewrite() -> None:
+    html = render_humanize_html(AI, AI, *_scores(0.8, 0.8), 0, "no-op", seed=3, rewrote=False, diff={"hunks": []})
+    assert "Returned unchanged" in html or "no change" in html
+
+
+def test_the_lock_annotations_are_present_with_rationale() -> None:
+    html = render_humanize_html(AI, EDITED, *_scores(0.80, 0.20), 1, "converged", diff=_sample_diff(AI, EDITED), seed=7)
+    assert "Locked spans" in html
+    assert "Smith (2020)" in html and "47%" in html
+    # Rationale text from the explain registry rides along.
+    assert "citation" in html.lower() or "number" in html.lower()
+
+
+def test_the_diff_hunks_render() -> None:
+    html = render_humanize_html(AI, EDITED, *_scores(0.80, 0.20), 1, "converged", diff=_sample_diff(AI, EDITED), seed=7)
+    assert "Diff" in html
+    assert "@@" in html  # a unified-diff hunk header
+    assert "deeply reshaped" in html
+
+
+# ---------------------------------------------------------------------------
+# CLI contract
+# ---------------------------------------------------------------------------
+
+
+class _EditRW:
+    name = "edit"
+
+    def available(self):
+        return True
+
+    def rewrite(self, text, score_result, threshold=0.30):
+        return text.replace("fundamentally transformed", "deeply reshaped")
+
+
+class _IdentityRW:
+    name = "identity"
+
+    def available(self):
+        return True
+
+    def rewrite(self, text, score_result, threshold=0.30):
+        return text
+
+
+def _fixed_score(mapping: dict, default: float = 0.8):
+    def _s(text, tier="full", threshold=0.3):
+        mx = mapping.get(text.strip(), default)
+        return {
+            "tier": tier,
+            "detectors": {"perplexity_burstiness": mx},
+            "max": mx,
+            "mean": mx,
+            "threshold": threshold,
+            "flagged": mx >= threshold,
+            "scored": True,
+        }
+
+    return _s
+
+
+def _patch_cli(monkeypatch, rewriter, scores: dict, default: float = 0.8) -> None:
+    import untell.rewriter as rewriter_mod
+    import untell.scripts.run as run_mod
+
+    monkeypatch.setenv("UNTELL_LITE_NO_TORCH", "1")
+    monkeypatch.setattr(rewriter_mod, "get_rewriter", lambda prefer=None: rewriter)
+    monkeypatch.setattr(run_mod, "score_text", _fixed_score(scores, default))
+
+
+def test_cli_escapes_injected_text(monkeypatch, capsys) -> None:
+    """A hostile document must come out of `--html` fully escaped — a defect if it
+    does not, so it is asserted at the CLI surface, not only in the renderer."""
+    _patch_cli(monkeypatch, _IdentityRW(), {}, default=0.8)
+    hostile = "<script>alert(1)</script> AI cost $500 per Smith (2020)."
+    rc = main(["--tier", "lite", "--html", "--max-iters", "1", "--best-of", "1", hostile])
+    assert rc == 0
+    html = capsys.readouterr().out
+    assert "<script>alert(1)</script>" not in html
+    assert "&lt;script&gt;alert(1)&lt;/script&gt;" in html
+
+
+def test_cli_html_human_output(monkeypatch, capsys) -> None:
+    _patch_cli(monkeypatch, _EditRW(), {AI: 0.80, EDITED: 0.20})
+    rc = main(["--tier", "lite", "--html", "--max-iters", "1", "--best-of", "1", AI])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert out.startswith("<!DOCTYPE html>"), "stdout must BE the html document, not a wrapper"
+    assert "Locked spans" in out and "Diff" in out and "Before" in out and "After" in out
+    assert "Rewrote" in out
+    assert "Smith (2020)" in out and "47%" in out
+    # The standard terminal render must not also run.
+    assert "--- Original ---" not in out
+    assert "humanization complete (" not in out
+
+
+def test_cli_html_json_envelope(monkeypatch, capsys) -> None:
+    _patch_cli(monkeypatch, _EditRW(), {AI: 0.80, EDITED: 0.20})
+    rc = main(["--tier", "lite", "--html", "--json", "--max-iters", "1", "--best-of", "1", AI])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["format"] == "untell-html"
+    assert payload["version"] == 1
+    assert payload["html"].startswith("<!DOCTYPE html>")
+    assert payload["diff"]["format"] == "untell-diff"
+    assert payload["rewrote"] is True and payload["seed"] is not None
+    assert payload["pre"]["max"] == 0.80 and payload["post"]["max"] == 0.20
+    spans = [row["span"] for row in payload["diff"]["locked_spans"]]
+    assert "Smith (2020)" in spans and "47%" in spans
+    assert payload["diff"]["locks_preserved"] == len(spans) == 2
+
+
+def test_cli_html_json_envelope_no_change(monkeypatch, capsys) -> None:
+    _patch_cli(monkeypatch, _IdentityRW(), {}, default=0.8)
+    rc = main(["--tier", "lite", "--html", "--json", "--max-iters", "1", "--best-of", "1", AI])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["rewrote"] is False
+    assert payload["diff"]["changed"] is False
+    assert "Returned unchanged" in payload["html"] or "no change" in payload["html"]
+
+
+def test_cli_html_json_error_path_holds(monkeypatch, capsys) -> None:
+    """`--html --json` with no input must answer JSON and exit 2, like the other modes."""
+    _patch_cli(monkeypatch, _IdentityRW(), {})
+    rc = main(["--tier", "lite", "--html", "--json", "   "])
+    assert rc == 2
+    parsed = json.loads(capsys.readouterr().out)
+    assert "error" in parsed
+
+
+def test_cli_html_reports_rewriter_failure(monkeypatch, capsys) -> None:
+    class _BrokenRW:
+        name = "broken"
+
+        def available(self):
+            return True
+
+        def rewrite(self, text, score_result, threshold=0.30):
+            raise RuntimeError("simulated rewriter failure")
+
+    _patch_cli(monkeypatch, _BrokenRW(), {}, default=0.9)
+    rc = main(["--tier", "lite", "--html", "--max-iters", "1", "--best-of", "1", AI])
+    assert rc == 1
+    out = capsys.readouterr().out
+    assert "ERROR" in out and "rewriter failed" in out
diff --git a/untell/rich_output.py b/untell/rich_output.py
index 551d41b3..5cdecc79 100644
--- a/untell/rich_output.py
+++ b/untell/rich_output.py
@@ -523,3 +523,242 @@ def progress_iteration(current: int, total: int, tier: str, score: float | None
     score_part = f"  P(AI)={score:.2f}" if score is not None else ""
     _CONSOLE.print(f"  [dim]→ Iteration {current}/{total}[/]  tier={tier}{score_part}")
     return None
+
+
+# ---------------------------------------------------------------------------
+# HTML report (`untell humanize --html`, issue #30)
+# ---------------------------------------------------------------------------
+#
+# A self-contained, deterministic HTML rendering of a humanize loop run. Unlike
+# the rich terminal views this module also drives, the artifact is meant to be
+# saved and shared, so it carries everything a reader needs to trust the run:
+# before/after text, pre/post scores, seed, whether it rewrote, the unified
+# --diff payload and — via the explain machinery the loop's own lock builds on —
+# a per-span annotation of every frozen fact and why it was frozen.
+#
+# Determinism: the same inputs return byte-identical output. There is no
+# timestamp, no random, no process-dependent value, and the CSS is inlined, so
+# two runs on the same text/seed produce two files that diff to nothing.
+#
+# Escaping is load-bearing, not cosmetic. Every value that came from the user's
+# text — original, final, each locked span, rules, rationale, warning — passes
+# through `html.escape`, so text that *is* attacker-shaped markup (a "<script>"
+# inside the text being humanized) renders as inert characters instead of
+# executing or breaking the page. The escaping tests fuzz this surface directly.
+#
+# No external assets: the whole document is one string with an inline <style>
+# and zero <script>/<link> references, so it renders identically from a
+# file:// path or an air-gapped box. It needs no `rich` and no JS.
+def _esc(value: object) -> str:
+    """HTML-escape an arbitrary value with both quotes, so it is safe in any
+    text node AND inside a quoted attribute."""
+    raw = str(value)
+    return (
+        raw.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&#x27;")
+    )
+
+
+def _score_cell(score: dict, key: str, fmt: str = "{:.2f}") -> str:
+    """A score dict value rendered safely, or \"—\" when absent/non-numeric."""
+    value = (score or {}).get(key)
+    if isinstance(value, (int, float)):
+        try:
+            return fmt.format(value)
+        except (ValueError, TypeError):  # non-finite -> the dash, not a crash
+            return "—"
+    return "—"
+
+
+def _verdict_cell(score: dict) -> str:
+    """The same flag/borderline/clear verdict the terminal table shows, so the
+    HTML and the console cannot disagree about what the score means."""
+    cut = (score or {}).get("verdict_threshold", (score or {}).get("threshold", 0.30))
+    p_ai = (score or {}).get("max")
+    if not isinstance(p_ai, (int, float)) or not isinstance(cut, (int, float)):
+        return "—"
+    if p_ai >= cut:
+        return "flagged"
+    return "borderline" if p_ai >= cut - _VERDICT_BAND else "clear"
+
+
+def render_humanize_html(
+    original: str,
+    final: str,
+    pre_score: dict,
+    post_score: dict,
+    iterations: int,
+    stopped: str,
+    warning: str | None = None,
+    diff: dict | None = None,
+    seed=None,
+    rewrote: bool | None = None,
+    tells_before: int | None = None,
+    tells_after: int | None = None,
+) -> str:
+    """Render a complete standalone HTML report for one humanize run.
+
+    Returns a single ``str`` that is a fully self-contained HTML document
+    (DOCTYPE through </html>). Every dynamic value is HTML-escaped; the output
+    is deterministic and depends on no external file, image, stylesheet or
+    script. Pass the ``humanize_diff`` payload (with its ``locked_spans`` and
+    ``locks_preserved``) as ``diff`` to include the before/after and the
+    per-span lock annotations.
+    """
+    diff = diff or {}
+    changed = rewrote
+    if changed is None:
+        changed = final != original
+    no_change = not changed
+
+    # --- header / summary ---------------------------------------------------
+    title = "untell — humanization report"
+    status = "no change made" if no_change else "humanization complete"
+    plural = "s" if iterations != 1 else ""
+
+    lines: list[str] = [
+        "<!DOCTYPE html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        f"<title>{_esc(title)}</title>",
+        "<style>",
+        "  :root{--bg:#0f172a;--panel:#1e293b;--ink:#e2e8f0;--muted:#94a3b8;"
+        "--add:#166534;--addink:#bbf7d0;--del:#7f1d1d;--delink:#fecaca;--line:#334155;}",
+        "  *{box-sizing:border-box;}",
+        "  body{margin:0;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;"
+        "font-size:14px;line-height:1.5;color:var(--ink);background:var(--bg);}",
+        "  main{max-width:960px;margin:0 auto;padding:24px;}",
+        "  h1{font-size:18px;margin:0 0 4px;}",
+        "  p.sub{color:var(--muted);margin:0 0 20px;font-size:12px;}",
+        "  h2{font-size:14px;border-bottom:1px solid var(--line);padding-bottom:4px;margin:24px 0 10px;}",
+        "  table{border-collapse:collapse;width:100%;margin:6px 0;}",
+        "  th,td{text-align:left;padding:4px 8px;border-bottom:1px solid var(--line);font-size:13px;}",
+        "  th{color:var(--muted);font-weight:600;}",
+        "  .badge{display:inline-block;padding:1px 8px;border-radius:999px;font-size:12px;}"
+        "  .badge.ok{background:var(--add);color:var(--addink);}"
+        "  .badge.no{background:var(--del);color:var(--delink);}",
+        "  .panel{background:var(--panel);border:1px solid var(--line);border-radius:8px;"
+        "padding:10px 12px;margin:4px 0;white-space:pre-wrap;word-break:break-word;}"
+        "  .dig{white-space:pre-wrap;word-break:break-word;}",
+        "  .hunk{background:var(--panel);border:1px solid var(--line);border-radius:8px;"
+        "padding:8px 12px;margin:8px 0;}",
+        "  .hunk .h{color:var(--muted);}",
+        "  .hunk .a{color:var(--delink);}",
+        "  .hunk .d{color:var(--addink);}",
+        "  .why{color:var(--muted);font-size:12px;}",
+        "  .warn{background:#3f1d1d;border:1px solid #7f1d1d;color:#fecaca;border-radius:8px;"
+        "padding:8px 12px;margin:8px 0;}",
+        "  footer{margin-top:32px;color:var(--muted);font-size:11px;border-top:1px solid var(--line);"
+        "padding-top:8px;}",
+        "</style>",
+        "</head>",
+        "<body>",
+        "<main>",
+        f"<h1>{_esc(title)}</h1>",
+        f'<p class="sub">{_esc(status)} &middot; {_esc(iterations)} iteration{_esc(plural)} '
+        f"&middot; stopped: {_esc(stopped.replace('_', ' ').title())}</p>",
+    ]
+
+    # --- summary badges -----------------------------------------------------
+    rewrote_txt = "rewrote" if changed else "returned unchanged"
+    seed_txt = "" if seed is None else f"  seed: {_esc(seed)}"
+    lines.append(
+        f'<p><span class="badge {"ok" if changed else "no"}">{_esc(rewrote_txt.capitalize())}</span>'
+        f"<span class=\"badge ok\">P(AI) {_esc(_score_cell(pre_score, 'max'))} "
+        f"&rarr; {_esc(_score_cell(post_score, 'max'))}</span>{_esc(seed_txt)}</p>"
+    )
+
+    # --- scores table -------------------------------------------------------
+    lines.append("<h2>Score</h2>")
+    lines.append("<table><tr><th>Metric</th><th>Before</th><th>After</th></tr>")
+    for label, key, fmt in (
+        ("P(AI) max", "max", "{:.4f}"),
+        ("P(AI) mean", "mean", "{:.4f}"),
+    ):
+        lines.append(
+            f"<tr><td>{_esc(label)}</td><td>{_esc(_score_cell(pre_score, key, fmt))}</td>"
+            f"<td>{_esc(_score_cell(post_score, key, fmt))}</td></tr>"
+        )
+    lines.append(
+        f"<tr><td>Verdict</td><td>{_esc(_verdict_cell(pre_score))}</td>"
+        f"<td>{_esc(_verdict_cell(post_score))}</td></tr>"
+    )
+    if tells_before is not None and tells_after is not None:
+        lines.append(
+            f"<tr><td>AI tells</td><td>{_esc(tells_before)}</td><td>{_esc(tells_after)}</td></tr>"
+        )
+    tier = (pre_score or {}).get("tier", post_score.get("tier", "?"))
+    lines.append(f"<tr><td>Tier</td><td colspan=\"2\">{_esc(tier)}</td></tr>")
+    lines.append("</table>")
+
+    # --- locked spans -------------------------------------------------------
+    locked = diff.get("locked_spans") or []
+    locks_preserved = diff.get("locks_preserved")
+    lines.append("<h2>Locked spans</h2>")
+    if not locked:
+        lines.append('<p class="sub">No spans locked — the rewriter may touch every word.</p>')
+    else:
+        if locks_preserved is not None:
+            kept_txt = (
+                f"{locks_preserved} of {len(locked)} preserved verbatim"
+                if locks_preserved == len(locked)
+                else f"WARNING: {len(locked) - locks_preserved} of {len(locked)} did NOT survive"
+            )
+            lines.append(f'<p class="sub">{_esc(kept_txt)}</p>')
+        lines.append("<table><tr><th>Sentinel</th><th>Span</th><th>Rules</th><th>Why locked</th></tr>")
+        for row in locked:
+            rules = ", ".join(row.get("rules") or [])
+            preserved = row.get("span", "") in final
+            ok = "kept" if preserved else "LOST"
+            lines.append(
+                "<tr>"
+                f"<td>{_esc(row.get('sentinel', ''))}</td>"
+                f"<td>{_esc(row.get('span', ''))}</td>"
+                f"<td>{_esc(rules)}</td>"
+                f"<td><span class=\"badge {'ok' if preserved else 'no'}\">{_esc(ok)}</span> "
+                f'<span class="why">{_esc(row.get("rationale", ""))}</span></td>'
+                "</tr>"
+            )
+        lines.append("</table>")
+
+    # --- unified diff -------------------------------------------------------
+    lines.append("<h2>Diff</h2>")
+    changed_lines = diff.get("hunks") or []
+    if not changed_lines:
+        lines.append('<p class="sub">No lines changed — the loop returned the original unmodified.</p>')
+    else:
+        lines.append(
+            f'<p class="sub">{_esc(diff.get("added_lines", 0))} added, '
+            f'{_esc(diff.get("removed_lines", 0))} removed.</p>'
+        )
+        for hunk in changed_lines:
+            hdr = "@@ -{} +{} @@".format(
+                _unified_range(hunk["start_original"], hunk["start_original"] + hunk["count_original"]),
+                _unified_range(hunk["start_final"], hunk["start_final"] + hunk["count_final"]),
+            )
+            body = []
+            for line in hunk["lines"]:
+                cls = "a" if line["kind"] == "-" else "d"
+                body.append(f'<div class="{cls}">{_esc(line["text"])}</div>')
+            lines.append(f'<div class="hunk"><div class="h">{_esc(hdr)}</div>{"".join(body)}</div>')
+
+    # --- before / after -----------------------------------------------------
+    lines.append("<h2>Before</h2>")
+    lines.append(f'<div class="panel">{_esc(original)}</div>')
+    lines.append("<h2>After</h2>")
+    lines.append(f'<div class="panel">{_esc(final)}</div>')
+
+    if warning:
+        lines.append(f'<div class="warn">NOTE: {_esc(warning)}</div>')
+
+    lines.append(
+        "<footer>Generated by untell humanize --html &middot; "
+        "lock annotations from the preserve/explain machinery &middot; deterministic.</footer>"
+    )
+    lines += ["</main>", "</body>", "</html>"]
+    return "\n".join(lines)
+
diff --git a/untell/scripts/run.py b/untell/scripts/run.py
index c77d3c9b..6f900b34 100644
--- a/untell/scripts/run.py
+++ b/untell/scripts/run.py
@@ -2035,6 +2035,15 @@ def build_parser() -> argparse.ArgumentParser:
         "hunk payload instead. Built on the preserve-lock explainer: the payload also "
         "reports how many locked spans survived the rewrite byte-for-byte.",
     )
+    parser.add_argument(
+        "--html",
+        action="store_true",
+        help="write a self-contained HTML report of the humanization to stdout: before/after "
+        "text, pre/post scores, seed, whether it rewrote, the unified --diff payload, and a "
+        "per-span annotation of every locked fact (via the explain machinery), all HTML-"
+        "escaped with no external assets. With --json, emit the machine-readable envelope "
+        "holding the report string plus the diff payload.",
+    )
     return parser
 
 
@@ -2053,6 +2062,46 @@ def _diff_payload(text: str, result: dict) -> dict:
     return humanize_diff(text, result.get("final", ""), locked_spans=explain_spans(text))
 
 
+def _html_payload(text: str, result: dict) -> dict:
+    """The `--html` envelope: the rendered report string plus the structured run data.
+
+    ``render_humanize_html`` draws the diff (with its per-span lock annotations) and the
+    score/seed/rewrote facts into one escaped, self-contained document. The envelope keeps
+    the machine-readable pieces alongside the string, so `--html --json` is a parseable
+    contract rather than a page dump — the same split `--diff` / `--diff --json` already
+    makes.
+    """
+    from untell.rich_output import render_humanize_html
+
+    diff = _diff_payload(text, result)
+    html_doc = render_humanize_html(
+        original=text,
+        final=result.get("final", ""),
+        pre_score=result.get("pre", {}),
+        post_score=result.get("post", {}),
+        iterations=result.get("iterations", 0),
+        stopped=result.get("stopped", "unknown"),
+        warning=result.get("warning"),
+        diff=diff,
+        seed=result.get("seed"),
+        rewrote=result.get("changed"),
+        tells_before=result.get("tells_before"),
+        tells_after=result.get("tells_after"),
+    )
+    return {
+        "format": "untell-html",
+        "version": 1,
+        "html": html_doc,
+        "diff": diff,
+        "pre": result.get("pre", {}),
+        "post": result.get("post", {}),
+        "seed": result.get("seed"),
+        "rewrote": result.get("changed"),
+        "iterations": result.get("iterations", 0),
+        "stopped": result.get("stopped", "unknown"),
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
     from untell.scripts.io_utils import configure_utf8_io
@@ -2193,8 +2242,11 @@ def main(argv: list[str] | None = None) -> int:
         seed=args.seed,
         # Only on the human-facing path: --json must stay parseable, so a progress line printed to
         # stdout ahead of the payload would corrupt it for every scripted caller. `--diff --json`
-        # is a scripted caller too — same rule, same flag.
-        progress=not args.json,
+        # is a scripted caller too — same rule, same flag. `--html` is a full-document mode just
+        # like `--json`: stdout IS the report, so progress must go to stderr (where untell_text's
+        # progress printer already sends iterations) or the saved .html file would start with a
+        # stray iteration line.
+        progress=not (args.json or args.html),
         timings=args.timings,
     )
     if args.diff:
@@ -2219,6 +2271,21 @@ def main(argv: list[str] | None = None) -> int:
 
             print_humanize_diff(payload)
         return 0
+    if args.html:
+        if "error" in result:
+            # Same contract as the other modes: under `--html --json` stdout is JSON, so a
+            # caller parsing stdout cannot special-case one branch.
+            if args.json:
+                print(json.dumps(result, ensure_ascii=True, indent=2))
+            else:
+                print(f"ERROR: {result['error']}")
+            return 1
+        payload = _html_payload(text, result)
+        if args.json:
+            print(json.dumps(payload, ensure_ascii=True, indent=2))
+        else:
+            print(payload["html"])
+        return 0
     if args.json:
         print(json.dumps(result, ensure_ascii=True, indent=2))
     elif "error" in result: