@sdelsad/commodity-desk-daily 1.0.18 → 1.13.2

package/build_email.py

@@ -0,0 +1,773 @@
+#!/usr/bin/env python3
+"""
+Soft Commodity Trading — daily e-mail builder.
+
+The e-mail used to be improvised every morning, which meant it drifted. This
+renders it deterministically from the same epNN.md the page is built from, so
+the eight sections are always the same eight sections, in the same order.
+
+Usage:
+    python3 build_email.py --notes ep05.md --number 5 \
+        --title "Wheat: The Map and the Screens" \
+        --audio-url "https://.../ep05.mp3" \
+        --page-url  "https://.../ep05.html" \
+        --duration 739 --date "Friday 14 August 2026" \
+        --charts URL1,URL2,URL3 --glossary glossary_final.md \
+        --drill-index 5 --drill-file conversions.md \
+        --out ep05_email.html
+
+Writes the HTML to --out and the plain-text alternative alongside it
+(ep05_email.txt), built from the same parse so the two cannot disagree.
+
+E-mail HTML is not web HTML, and this file obeys the difference:
+
+  * layout is tables, every style is inline, nothing depends on a <style>
+    block, and there is no flexbox, grid, CSS variable or dark-mode query;
+  * the card is a fixed 600px table with the width attribute set, because
+    Outlook's Word engine ignores max-width;
+  * charts are <img> pointing at the published PNGs — Gmail strips inline SVG
+    — each with alt text, an explicit width, and max-width:100%;height:auto;
+  * the spoiler gap is a table row with a fixed height, because Gmail
+    collapses stacked <br> and would hand the reader the answers.
+
+Zero runtime dependencies: standard library only.
+"""
+import argparse
+import html
+import json
+import os
+import re
+import sys
+import textwrap
+
+try:
+    from build_page import classify_move, is_numeric, MOVE_HEADS, SIGNED, \
+        FLAT_WORDS, BLANKS, _clean
+except ImportError:                                # build_page.py sits next to us
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    from build_page import classify_move, is_numeric, MOVE_HEADS, SIGNED, \
+        FLAT_WORDS, BLANKS, _clean
+
+SHOW = "Soft Commodity Trading"
+SITE_URL = "https://storage.googleapis.com/podcast-audio-2647223968/index.html"
+FEED_URL = ("https://storage.googleapis.com/podcast-audio-2647223968/"
+            "commodity-desk-daily/feed.xml")
+
+# palette, spelled out because an e-mail cannot have CSS variables
+INK = "#16110c"
+SOFT = "#4a4238"
+FAINT = "#8b8375"
+LINE = "#e3ddd2"
+PAPER = "#faf7f1"
+OUTER = "#ece7db"
+GOLD = "#a8813c"
+ACCENT = "#1d4032"
+UP = "#215c44"
+DOWN = "#8a2f2f"
+SPOILER = "#8a2f2f"
+TINT = "#f4efe4"
+
+SERIF = "Georgia,'Times New Roman',Times,serif"
+SANS = "'Helvetica Neue',Helvetica,Arial,sans-serif"
+
+PAD = "0 28px"                       # the content gutter, used on every row
+BODY = f"font-family:{SERIF};font-size:16px;line-height:1.62;color:{INK};"
+KICKER = (f"font-family:{SANS};font-size:11px;line-height:1.4;font-weight:bold;"
+          f"letter-spacing:.16em;text-transform:uppercase;color:{GOLD};")
+
+
+def esc(s):
+    return html.escape(s or "", quote=True)
+
+
+# ---------------------------------------------------------------- markdown --
+
+FENCE = "```"
+
+
+def inline(text):
+    """Inline markdown → HTML with inline styles only."""
+    text = re.sub(r"`([^`]+)`",
+                  rf'<code style="font-family:Consolas,Menlo,monospace;'
+                  rf'font-size:14px;background:{TINT};padding:1px 4px;">\1</code>',
+                  text)
+    text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
+    text = re.sub(r"(?<![\w*])\*(?!\s)(.+?)(?<!\s)\*(?![\w*])", r"<em>\1</em>", text)
+    text = re.sub(r"(?<![\w_])_(?!\s)(.+?)(?<!\s)_(?![\w_])", r"<em>\1</em>", text)
+    text = re.sub(r"\[(.+?)\]\((.+?)\)",
+                  rf'<a href="\2" style="color:{ACCENT};">\1</a>', text)
+    return text
+
+
+def plain(text):
+    """Inline markdown → plain text."""
+    text = re.sub(r"`([^`]+)`", r"\1", text)
+    text = re.sub(r"\*\*(.+?)\*\*", r"\1", text)
+    text = re.sub(r"(?<![\w*])\*(?!\s)(.+?)(?<!\s)\*(?![\w*])", r"\1", text)
+    text = re.sub(r"(?<![\w_])_(?!\s)(.+?)(?<!\s)_(?![\w_])", r"\1", text)
+    text = re.sub(r"\[(.+?)\]\((.+?)\)", r"\1 (\2)", text)
+    return text
+
+
+def blocks(md):
+    """Markdown → a list of (kind, payload) blocks. One parse feeds both the
+    HTML and the plain-text renderer, so they cannot drift apart."""
+    out, lines, i = [], md.split("\n"), 0
+    while i < len(lines):
+        stripped = lines[i].strip()
+        if not stripped:
+            i += 1
+            continue
+
+        if stripped.startswith(FENCE + "chart"):
+            spec, i = [], i + 1
+            while i < len(lines) and not lines[i].strip().startswith(FENCE):
+                spec.append(lines[i])
+                i += 1
+            i += 1
+            try:
+                spec = json.loads("\n".join(spec))
+            except ValueError:
+                spec = {}
+            # the spec's own title and caption become the alt text: half the
+            # readers of any e-mail have images turned off
+            out.append(("chart", spec))
+            continue
+
+        if stripped.startswith("<") or re.match(r"^(&nbsp;\s*)+$", stripped):
+            i += 1                                     # raw HTML / e-mail spacers
+            continue
+
+        if re.match(r"^(-{3,}|\*{3,})$", stripped):
+            out.append(("rule", None))
+            i += 1
+            continue
+
+        m = re.match(r"^(#{1,6})\s+(.*)$", stripped)
+        if m:
+            out.append(("h", (len(m.group(1)), m.group(2))))
+            i += 1
+            continue
+
+        if stripped.startswith("|") and i + 1 < len(lines) and \
+                re.match(r"^\|[\s:|-]+\|$", lines[i + 1].strip()):
+            head = [c.strip() for c in stripped.strip("|").split("|")]
+            i += 2
+            rows = []
+            while i < len(lines) and lines[i].strip().startswith("|"):
+                rows.append([c.strip() for c in lines[i].strip().strip("|").split("|")])
+                i += 1
+            out.append(("table", (head, rows)))
+            continue
+
+        if re.match(r"^[-*]\s+", stripped):
+            items = []
+            while i < len(lines) and re.match(r"^[-*]\s+", lines[i].strip()):
+                items.append(re.sub(r"^[-*]\s+", "", lines[i].strip()))
+                i += 1
+            out.append(("ul", items))
+            continue
+
+        if re.match(r"^\d+[.)]\s+", stripped):
+            items = []
+            while i < len(lines) and re.match(r"^\d+[.)]\s+", lines[i].strip()):
+                items.append(re.sub(r"^\d+[.)]\s+", "", lines[i].strip()))
+                i += 1
+            out.append(("ol", items))
+            continue
+
+        if stripped.startswith(">"):
+            quote = []
+            while i < len(lines) and lines[i].strip().startswith(">"):
+                quote.append(lines[i].strip().lstrip("> ").rstrip())
+                i += 1
+            out.append(("quote", quote))
+            continue
+
+        para = []
+        while i < len(lines) and lines[i].strip() and \
+                not re.match(r"^(#{1,6}\s|[-*]\s|\d+[.)]\s|\||>|<|-{3,}|```)",
+                             lines[i].strip()):
+            para.append(lines[i].strip())
+            i += 1
+        if para:
+            out.append(("p", " ".join(para)))
+        else:
+            i += 1
+    return out
+
+
+# ------------------------------------------------------------------ tables --
+
+def column_kinds(head, rows):
+    ncol = max([len(head)] + [len(r) for r in rows]) if rows else len(head)
+    numeric, moves = [], []
+    for c in range(ncol):
+        col = [r[c] for r in rows if c < len(r)]
+        filled = [x for x in col if x.strip().lower() not in BLANKS]
+        title = (head[c].lower().strip(" .:") if c < len(head) else "")
+        hits = sum(1 for x in filled if is_numeric(x))
+        numeric.append(bool(filled) and hits >= max(1, int(len(filled) * 0.6)))
+        signed = sum(1 for x in filled if SIGNED.match(x.strip())
+                     or any(w in x.lower() for w in FLAT_WORDS))
+        moves.append(title in MOVE_HEADS or (bool(filled) and signed == len(filled)))
+    return ncol, numeric, moves
+
+
+def table_html(head, rows):
+    ncol, numeric, moves = column_kinds(head, rows)
+    th = []
+    for c in range(ncol):
+        cell = head[c] if c < len(head) else ""
+        align = "right" if (numeric[c] or moves[c]) else "left"
+        th.append(
+            f'<th align="{align}" style="font-family:{SANS};font-size:11px;'
+            f'font-weight:bold;letter-spacing:.09em;text-transform:uppercase;'
+            f'color:{SOFT};text-align:{align};padding:0 8px 8px 0;'
+            f'border-bottom:1px solid {INK};">{inline(esc(cell))}</th>')
+    body = []
+    for r in rows:
+        tds = []
+        for c in range(ncol):
+            cell = r[c] if c < len(r) else ""
+            align = "right" if (numeric[c] or moves[c]) else "left"
+            style = (f"font-family:{SANS};font-size:14px;line-height:1.45;"
+                     f"color:{INK};padding:9px 8px 9px 0;text-align:{align};"
+                     f"border-bottom:1px solid {LINE};vertical-align:top;")
+            if c == 0:
+                style += "font-weight:bold;"
+            rendered = inline(esc(cell))
+            if moves[c]:
+                shown, direction = classify_move(cell)
+                if direction:
+                    if shown != cell:
+                        rendered = inline(esc(shown))
+                    colour = {"up": UP, "down": DOWN, "flat": SOFT}[direction]
+                    rendered = (f'<span style="color:{colour};font-weight:bold;">'
+                                f"{rendered}</span>")
+            tds.append(f'<td align="{align}" style="{style}">{rendered}</td>')
+        body.append("<tr>" + "".join(tds) + "</tr>")
+    return ('<table role="presentation" width="100%" cellpadding="0" cellspacing="0" '
+            'border="0" style="width:100%;border-collapse:collapse;margin:0 0 20px;">'
+            f'<thead><tr>{"".join(th)}</tr></thead>'
+            f'<tbody>{"".join(body)}</tbody></table>')
+
+
+def table_text(head, rows, width=76):
+    ncol, numeric, moves = column_kinds(head, rows)
+    grid = [[plain(head[c]) if c < len(head) else "" for c in range(ncol)]]
+    for r in rows:
+        line = []
+        for c in range(ncol):
+            cell = r[c] if c < len(r) else ""
+            if moves[c]:
+                shown, direction = classify_move(cell)
+                cell = shown if direction else cell
+            line.append(plain(cell))
+        grid.append(line)
+    # Fit the columns inside `width` by shaving the widest one, then wrap
+    # rather than truncate: a clipped contract name is worse than a long table.
+    widths = [max(len(row[c]) for row in grid) for c in range(ncol)]
+    gap = 2
+    while sum(widths) + gap * (ncol - 1) > width and max(widths) > 12:
+        widths[widths.index(max(widths))] -= 1
+
+    out = []
+    for n, row in enumerate(grid):
+        wrapped = [textwrap.wrap(row[c], widths[c]) or [""] for c in range(ncol)]
+        for line in range(max(len(w) for w in wrapped)):
+            cells = []
+            for c in range(ncol):
+                txt = wrapped[c][line] if line < len(wrapped[c]) else ""
+                right = (numeric[c] or moves[c]) and c > 0
+                cells.append(txt.rjust(widths[c]) if right else txt.ljust(widths[c]))
+            out.append((" " * gap).join(cells).rstrip())
+        if n == 0:
+            out.append("-" * (sum(widths) + gap * (ncol - 1)))
+    return "\n".join(out)
+
+
+# ------------------------------------------------------------ block render --
+
+def render_html(bs, charts, chart_at, base_h=3):
+    """Blocks → e-mail HTML. `chart_at` is the running global chart index."""
+    out = []
+    for kind, payload in bs:
+        if kind == "chart":
+            n = chart_at[0]
+            chart_at[0] += 1
+            url = charts[n] if n < len(charts) else ""
+            if not url:
+                print(f"[email] no URL for chart {n + 1}; skipped", file=sys.stderr)
+                continue
+            spec = payload or {}
+            # the PNG already carries its own title, caption and source, drawn
+            # by chart.py — only the alt text has to be supplied here
+            alt = " — ".join(x for x in (spec.get("title"), spec.get("caption"),
+                                         spec.get("source")) if x) \
+                or f"Chart {n + 1}"
+            out.append(
+                f'<table role="presentation" width="100%" cellpadding="0" '
+                f'cellspacing="0" border="0" style="margin:6px 0 22px;">'
+                f'<tr><td align="center" style="border:1px solid {LINE};'
+                f'background:{PAPER};padding:10px;">'
+                f'<img src="{esc(url)}" width="522" alt="{esc(alt)}" '
+                f'title="{esc(alt)}" '
+                f'style="display:block;width:100%;max-width:522px;height:auto;'
+                f'border:0;outline:none;text-decoration:none;">'
+                f"</td></tr></table>")
+        elif kind == "h":
+            level, text = payload
+            if level <= 3:
+                out.append(
+                    f'<h3 style="margin:26px 0 10px;font-family:{SERIF};'
+                    f'font-size:19px;line-height:1.3;font-weight:normal;'
+                    f'color:{INK};">{inline(esc(text))}</h3>')
+            else:
+                out.append(
+                    f'<h4 style="margin:20px 0 6px;font-family:{SANS};'
+                    f'font-size:15px;line-height:1.35;color:{INK};">'
+                    f"{inline(esc(text))}</h4>")
+        elif kind == "p":
+            out.append(f'<p style="margin:0 0 16px;{BODY}">{inline(esc(payload))}</p>')
+        elif kind in ("ul", "ol"):
+            tag = "ul" if kind == "ul" else "ol"
+            items = "".join(
+                f'<li style="margin:0 0 9px;{BODY}">{inline(esc(it))}</li>'
+                for it in payload)
+            out.append(f'<{tag} style="margin:0 0 16px;padding-left:22px;">'
+                       f"{items}</{tag}>")
+        elif kind == "quote":
+            inner = "<br>".join(inline(esc(q)) for q in payload)
+            out.append(
+                f'<table role="presentation" width="100%" cellpadding="0" '
+                f'cellspacing="0" border="0" style="margin:0 0 20px;"><tr>'
+                f'<td style="border-left:3px solid {GOLD};padding:4px 0 4px 16px;'
+                f'font-family:{SERIF};font-size:16px;line-height:1.55;'
+                f'font-style:italic;color:{SOFT};">{inner}</td></tr></table>')
+        elif kind == "table":
+            out.append(table_html(*payload))
+        elif kind == "rule":
+            out.append(
+                f'<table role="presentation" width="100%" cellpadding="0" '
+                f'cellspacing="0" border="0"><tr><td height="1" '
+                f'style="height:1px;line-height:1px;font-size:1px;'
+                f'background:{LINE};">&nbsp;</td></tr>'
+                f'<tr><td height="22" style="height:22px;line-height:22px;'
+                f'font-size:1px;">&nbsp;</td></tr></table>')
+    return "\n".join(out)
+
+
+def render_text(bs, charts, chart_at, width=76):
+    out = []
+    for kind, payload in bs:
+        if kind == "chart":
+            n = chart_at[0]
+            chart_at[0] += 1
+            spec = payload or {}
+            bits = [x for x in (spec.get("title"), spec.get("caption"),
+                                spec.get("source")) if x]
+            if n < len(charts) and charts[n]:
+                bits.append(charts[n])
+            if bits:
+                out.append(textwrap.fill("[chart] " + " — ".join(bits), width,
+                                         subsequent_indent="        "))
+        elif kind == "h":
+            text = plain(payload[1])
+            out.append(text + "\n" + "-" * min(len(text), width))
+        elif kind == "p":
+            out.append(textwrap.fill(plain(payload), width))
+        elif kind == "ul":
+            for it in payload:
+                out.append(textwrap.fill(plain(it), width,
+                                         initial_indent="  * ",
+                                         subsequent_indent="    "))
+        elif kind == "ol":
+            for n, it in enumerate(payload, 1):
+                out.append(textwrap.fill(plain(it), width,
+                                         initial_indent=f"  {n}. ",
+                                         subsequent_indent="     "))
+        elif kind == "quote":
+            for q in payload:
+                out.append(textwrap.fill(plain(q), width - 2,
+                                         initial_indent="  | ",
+                                         subsequent_indent="  | "))
+        elif kind == "table":
+            out.append(table_text(*payload, width=width))
+        elif kind == "rule":
+            out.append("-" * width)
+    return "\n\n".join(out)
+
+
+# --------------------------------------------------------------- sections ---
+
+def split_sections(md):
+    """[(title, level, markdown)] for every H2/H3 section, in document order."""
+    md = re.sub(r"^#{1,6}\s*.*SOLUTIONS.*$", "## Solutions", md,
+                flags=re.MULTILINE | re.IGNORECASE)
+    md = re.sub(r"^\s*(▼|▲).*$", "", md, flags=re.MULTILINE)
+    md = re.sub(r"\A\s*#\s+.*?\n(##\s+.*?\n)?", "", md, count=1)
+    parts, cur = [], None
+    for line in md.split("\n"):
+        m = re.match(r"^(#{2,3})\s+(.*)$", line.strip())
+        if m:
+            cur = [m.group(2).strip(), len(m.group(1)), []]
+            parts.append(cur)
+        elif cur is not None:
+            cur[2].append(line)
+        # anything before the first heading is the title block: dropped
+    return [(t, lv, "\n".join(body).strip()) for t, lv, body in parts]
+
+
+def classify(title):
+    t = title.lower()
+    if "market pulse" in t:
+        return "pulse"
+    if "quiz" in t:
+        return "quiz"
+    if "solution" in t:
+        return "solutions"
+    if "in writing" in t or "the episode" in t:
+        return "written"
+    return "extra"
+
+
+def group_sections(md):
+    """The notes, sorted into the e-mail's eight fixed slots.
+
+    Sections are recognised by their heading, not their position, because the
+    early episodes ordered them differently. Anything unrecognised (key
+    takeaways, vocabulary) stays with the pulse, where the notes put it.
+    """
+    out = {"pulse": [], "extra": [], "quiz": [], "solutions": [], "written": []}
+    current = None
+    for title, level, body in split_sections(md):
+        kind = classify(title)
+        if kind == "extra" and current in ("written", "quiz", "solutions"):
+            kind = current            # an H3 inside a big section stays there
+        else:
+            current = kind
+        out[kind].append((title, level, body))
+    return out
+
+
+def drill(path, index):
+    """One conversion drill out of conversions.md."""
+    if not path or not os.path.exists(path):
+        return None
+    text = open(path, encoding="utf-8").read()
+    found = re.split(r"^##\s+Drill\s+(\d+)\s*[—–-]\s*(.*)$", text,
+                     flags=re.MULTILINE)
+    # [preamble, num, title, body, num, title, body, ...]
+    for i in range(1, len(found) - 2, 3):
+        if int(found[i]) == index:
+            return found[i + 1].strip(), found[i + 2].strip()
+    return None
+
+
+def glossary(path):
+    terms = []
+    if not path or not os.path.exists(path):
+        return terms
+    for line in open(path, encoding="utf-8").read().splitlines():
+        m = re.match(r"^-\s+\*\*(.+?)\*\*\s+—\s+(.+?)(?:\s+_\(ep (\d+)\)_)?$",
+                     line.strip())
+        if m:
+            terms.append((m.group(1).strip(), m.group(2).strip(), m.group(3) or ""))
+    return terms
+
+
+# ---------------------------------------------------------------- assembly --
+
+def row(inner, pad=PAD, bg=PAPER):
+    return (f'<tr><td style="padding:{pad};background:{bg};">{inner}</td></tr>')
+
+
+def spacer(height, bg=PAPER):
+    return (f'<tr><td height="{height}" style="height:{height}px;'
+            f'line-height:{height}px;font-size:1px;background:{bg};">'
+            f"&nbsp;</td></tr>")
+
+
+def kicker(text):
+    return f'<p style="margin:0 0 12px;{KICKER}">{esc(text)}</p>'
+
+
+def button(url, label, bg=ACCENT, fg=PAPER):
+    return ('<table role="presentation" cellpadding="0" cellspacing="0" border="0">'
+            f'<tr><td bgcolor="{bg}" style="border-radius:6px;">'
+            f'<a href="{esc(url)}" style="display:inline-block;padding:14px 28px;'
+            f'font-family:{SANS};font-size:15px;font-weight:bold;color:{fg};'
+            f'text-decoration:none;border-radius:6px;">{esc(label)}</a>'
+            "</td></tr></table>")
+
+
+def build(args):
+    md = open(args.notes, encoding="utf-8").read()
+    groups = group_sections(md)
+    charts = [c.strip() for c in (args.charts or "").split(",") if c.strip()]
+    terms = glossary(args.glossary)
+    idx = args.drill_index or ((args.number - 1) % 12) + 1
+    dr = drill(args.drill_file, idx)
+    mins, secs = divmod(args.duration, 60)
+    length = f"{mins} min {secs:02d}"
+
+    # charts are numbered across the whole document, in document order, which
+    # is the order --charts lists them and the order build_page.py printed them
+    at = [0]
+
+    def sec(items):
+        return "\n".join(
+            (f'<h3 style="margin:26px 0 10px;font-family:{SERIF};font-size:19px;'
+             f'line-height:1.3;font-weight:normal;color:{INK};">{esc(t)}</h3>'
+             if lv >= 3 else "") +
+            render_html(blocks(body), charts, at)
+            for t, lv, body in items)
+
+    dek = args.dek.strip() or ""
+    preheader = dek or f"Episode {args.number}: {args.title}"
+    parts = []
+
+    # 1 — header, with the listen button
+    parts.append(row(
+        f'<p style="margin:0 0 6px;{KICKER}">{esc(SHOW)}</p>'
+        f'<p style="margin:0 0 14px;font-family:{SANS};font-size:11px;'
+        f'font-weight:bold;letter-spacing:.14em;text-transform:uppercase;'
+        f'color:{FAINT};">Episode {args.number:02d} · {esc(args.date)} '
+        f"· {length}</p>"
+        f'<h1 style="margin:0 0 12px;font-family:{SERIF};font-size:29px;'
+        f'line-height:1.2;font-weight:normal;color:{INK};">{esc(args.title)}</h1>'
+        + (f'<p style="margin:0 0 22px;font-family:{SERIF};font-size:17px;'
+           f'line-height:1.5;color:{SOFT};">{esc(dek)}</p>' if dek else "")
+        + button(args.audio_url, f"▶  Listen — {mins} min"),
+        pad="30px 28px 24px"))
+
+    # 2 — read online
+    parts.append(row(
+        f'<p style="margin:0;font-family:{SANS};font-size:13px;line-height:1.6;'
+        f'color:{SOFT};">'
+        f'<a href="{esc(args.page_url)}" style="color:{ACCENT};font-weight:bold;">'
+        f"Read this episode online &rarr;</a>"
+        f'<span style="color:{FAINT};"> &nbsp;·&nbsp; charts, the quiz and the '
+        f'running glossary</span></p>',
+        pad="0 28px 22px"))
+    parts.append(rule_row())
+
+    # 3 — market pulse, with its chart
+    if groups["pulse"] or groups["extra"]:
+        parts.append(row(kicker("Market pulse") + sec(groups["pulse"])
+                         + sec(groups["extra"]), pad="24px 28px 4px"))
+        parts.append(rule_row())
+
+    # 4 — the conversion drill
+    if dr:
+        title, body = dr
+        parts.append(row(
+            kicker(f"Conversion drill {idx} of 12")
+            + f'<h3 style="margin:0 0 12px;font-family:{SERIF};font-size:19px;'
+              f'line-height:1.3;font-weight:normal;color:{INK};">{esc(title)}</h3>'
+            + render_html(blocks(body), charts, at),
+            pad="24px 28px 4px", bg=TINT))
+        parts.append(rule_row())
+
+    # 5 — the quiz
+    if groups["quiz"]:
+        parts.append(row(kicker("Quiz") + sec(groups["quiz"]),
+                         pad="24px 28px 4px"))
+
+    # 6 — the spoiler separator: a fixed-height row, not a stack of <br>
+    if groups["solutions"]:
+        parts.append(
+            f'<tr><td align="center" style="padding:20px 28px;background:{TINT};'
+            f'border-top:1px solid {LINE};border-bottom:1px solid {LINE};">'
+            f'<p style="margin:0;font-family:{SANS};font-size:12px;'
+            f'font-weight:bold;letter-spacing:.12em;text-transform:uppercase;'
+            f'color:{SPOILER};">Solutions below &mdash; '
+            f"answer first</p></td></tr>")
+        parts.append(spacer(240))
+        parts.append(spacer(240))
+
+        # 7 — the solutions
+        parts.append(row(kicker("Solutions") + sec(groups["solutions"]),
+                         pad="10px 28px 4px"))
+        parts.append(rule_row())
+
+    # 8 — the written edition, lesson charts inline
+    if groups["written"]:
+        parts.append(row(kicker("The episode, in writing")
+                         + sec(groups["written"]), pad="24px 28px 4px"))
+        parts.append(rule_row())
+
+    # 9 — the cumulative glossary
+    if terms:
+        rows = []
+        for term, definition, ep in terms:
+            tag = (f'<span style="font-family:{SANS};font-size:10px;'
+                   f'letter-spacing:.08em;text-transform:uppercase;'
+                   f'color:{FAINT};">&nbsp;ep {ep}</span>' if ep else "")
+            rows.append(
+                f'<p style="margin:0 0 9px;font-family:{SERIF};font-size:15px;'
+                f'line-height:1.5;color:{SOFT};"><strong style="color:{INK};">'
+                f"{esc(term)}</strong> &mdash; {inline(esc(definition))}{tag}</p>")
+        parts.append(row(
+            kicker(f"Glossary · {len(terms)} terms")
+            + f'<p style="margin:0 0 16px;font-family:{SANS};font-size:13px;'
+              f'line-height:1.6;color:{FAINT};">Everything the show has '
+              f"introduced so far.</p>" + "".join(rows),
+            pad="24px 28px 8px"))
+
+    # footer
+    parts.append(
+        f'<tr><td style="padding:22px 28px 30px;background:{OUTER};'
+        f'border-top:1px solid {LINE};">'
+        f'<p style="margin:0 0 6px;font-family:{SANS};font-size:12px;'
+        f'line-height:1.7;color:{SOFT};"><strong>{esc(SHOW)}</strong> '
+        f"&mdash; a daily briefing on physical commodity trading.</p>"
+        f'<p style="margin:0;font-family:{SANS};font-size:12px;line-height:1.7;'
+        f'color:{FAINT};">'
+        f'<a href="{esc(SITE_URL)}" style="color:{SOFT};">All episodes</a> '
+        f'&nbsp;·&nbsp; <a href="{esc(FEED_URL)}" style="color:{SOFT};">'
+        f"Subscribe by RSS</a> &nbsp;·&nbsp; "
+        f'<a href="{esc(args.page_url)}" style="color:{SOFT};">This episode '
+        f"online</a></p></td></tr>")
+
+    doc = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="x-apple-disable-message-reformatting">
+<meta name="color-scheme" content="light">
+<meta name="supported-color-schemes" content="light">
+<title>{esc(SHOW)} — Ep {args.number}: {esc(args.title)}</title>
+</head>
+<body style="margin:0;padding:0;background:{OUTER};-webkit-text-size-adjust:100%;">
+<div style="display:none;max-height:0;overflow:hidden;mso-hide:all;">{esc(preheader)}</div>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:{OUTER};">
+<tr><td align="center" style="padding:20px 10px;">
+<table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" align="center" style="width:100%;max-width:600px;background:{PAPER};border:1px solid {LINE};">
+{chr(10).join(parts)}
+</table>
+</td></tr>
+</table>
+</body>
+</html>
+"""
+    return doc, build_text(args, groups, charts, terms, dr, idx, length)
+
+
+def rule_row():
+    return (f'<tr><td style="padding:0 28px;background:{PAPER};">'
+            f'<table role="presentation" width="100%" cellpadding="0" '
+            f'cellspacing="0" border="0"><tr><td height="1" style="height:1px;'
+            f'line-height:1px;font-size:1px;background:{LINE};">&nbsp;</td>'
+            f"</tr></table></td></tr>")
+
+
+def build_text(args, groups, charts, terms, dr, idx, length):
+    """The plain-text alternative, from the same parse and the same order."""
+    at = [0]
+    W = 76
+    L = []
+
+    def head(title):
+        L.append("")
+        L.append(title.upper())
+        L.append("=" * min(len(title), W))
+        L.append("")
+
+    def body(items):
+        for t, lv, md in items:
+            if lv >= 3:
+                L.append(plain(t))
+                L.append("-" * min(len(t), W))
+                L.append("")
+            L.append(render_text(blocks(md), charts, at, W))
+            L.append("")
+
+    L.append(f"{SHOW.upper()}")
+    L.append(f"Episode {args.number:02d} · {args.date} · {length}")
+    L.append("")
+    L.append(args.title)
+    if args.dek.strip():
+
+        L.append(textwrap.fill(args.dek.strip(), W))
+    L.append("")
+    L.append(f"Listen:      {args.audio_url}")
+    L.append(f"Read online: {args.page_url}")
+
+    if groups["pulse"] or groups["extra"]:
+        head("Market pulse")
+        body(groups["pulse"])
+        body(groups["extra"])
+    if dr:
+        title, md = dr
+        head(f"Conversion drill {idx} of 12 — {title}")
+        L.append(render_text(blocks(md), charts, at, W))
+        L.append("")
+    if groups["quiz"]:
+        head("Quiz")
+        body(groups["quiz"])
+    if groups["solutions"]:
+        L.append("")
+        L.append("=" * W)
+        L.append("SOLUTIONS BELOW — ANSWER FIRST".center(W))
+        L.append("=" * W)
+        L.extend([""] * 25)
+        head("Solutions")
+        body(groups["solutions"])
+    if groups["written"]:
+        head("The episode, in writing")
+        body(groups["written"])
+    if terms:
+        head(f"Glossary — {len(terms)} terms")
+        for term, definition, ep in terms:
+            L.append(textwrap.fill(
+                f"{term} — {plain(definition)}" + (f"  (ep {ep})" if ep else ""),
+                W, subsequent_indent="    "))
+    L.append("")
+    L.append("-" * W)
+    L.append(f"{SHOW} — a daily briefing on physical commodity trading.")
+    L.append(f"All episodes: {SITE_URL}")
+    L.append(f"RSS: {FEED_URL}")
+    return "\n".join(L) + "\n"
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Render the daily e-mail (HTML + plain text) from epNN.md.")
+    ap.add_argument("--notes", required=True)
+    ap.add_argument("--number", type=int, required=True)
+    ap.add_argument("--title", required=True)
+    ap.add_argument("--dek", default="", help="one sentence under the headline")
+    ap.add_argument("--audio-url", required=True)
+    ap.add_argument("--page-url", required=True)
+    ap.add_argument("--duration", type=int, required=True, help="seconds")
+    ap.add_argument("--date", default="")
+    ap.add_argument("--charts", default="",
+                    help="comma-separated published PNG URLs, in the order "
+                         "build_page.py printed CHART_PNG= lines")
+    ap.add_argument("--glossary", default="",
+                    help="glossary.md, for the cumulative glossary at the foot")
+    ap.add_argument("--drill-index", type=int, default=0,
+                    help="which conversion drill; defaults to ((N-1) mod 12)+1")
+    ap.add_argument("--drill-file", default="conversions.md")
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--text-out", default="",
+                    help="plain-text alternative; defaults to --out with .txt")
+    args = ap.parse_args()
+
+    doc, text = build(args)
+    with open(args.out, "w", encoding="utf-8") as fh:
+        fh.write(doc)
+    txt_path = args.text_out or re.sub(r"\.html?$", "", args.out) + ".txt"
+    with open(txt_path, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    print(f"[email] {args.out} | {len(doc):,} bytes")
+    print(f"[email] {txt_path} | {len(text):,} bytes")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())