feat(emit): --emit=html for shareable self-contained briefs (#332)

Adds a one-command shareable HTML mode to /last30days. The skill detects HTML intent (explicit --emit=html / --emit:html / --html flag in $ARGUMENTS, or natural-language asks like "give me a shareable brief", "for Slack", "export as HTML"), runs the normal research + chat synthesis flow, then saves a self-contained HTML file to ~/Documents/Last30Days/{topic}-brief.html. The synthesis appears in chat as usual; the HTML is an additional artifact for sharing. User experience: /last30days OpenClaw --emit=html /last30days OpenClaw, give me an HTML brief for Slack Synthesis prints to chat. Last line of the response: "📎 Shareable brief saved to ~/Documents/Last30Days/openclaw-brief.html". Open it, drag it into a message, browser-print to PDF, email it. Architecture: - SKILL.md gets a small detection block (triggers + early exit + MUST/MUST NOT rules + rationale) that points to a reference file. - references/save-html-brief.md owns the implementation: capture the synthesis verbatim into a temp file via heredoc, invoke the engine with --emit=html --synthesis-file, save to disk, append the confirmation line to chat. - lib/render.py exposes render_for_html(report, synthesis_md=None) and render_for_html_comparison(...) -- clean markdown for HTML conversion. Omits debug file header, model-facing safety note, and data quality warnings (those stay in engine stderr; recipients can't act on them in a shared artifact). - lib/html_render.py is a new module: ~200-line CSS template (dark mode default, prefers-color-scheme switch, print stylesheet, mobile breakpoint), stdlib-regex markdown-to-HTML converter, marker-based META + engine-footer wrapping, PROSE_LABELS registry promoting plain -text labels to <h2>, colophon builder. - last30days.py adds --emit=html argparse choice and --synthesis-file PATH flag (engine still callable directly without the skill in the loop). Design: - Voice-led research brief, not corporate report. Inter + JetBrains Mono via Google Fonts with full system fallbacks (no FOIT, works offline). Brand purple #a855f7 (#7c3aed in light mode). Type ramp: body 17px/400/muted, bold lead-in 17px/600/fg, h2 + .prose-label 20px/600/fg, monospace badge/meta/footer/colophon at 13-13.5px. - 720px max-width, generous whitespace, no card layouts or shadows. - Print stylesheet: light theme, A4 margins, [href]::after URL footnotes, page-break-inside:avoid on the engine footer. Templated (locked) shell: - HTML5 boilerplate, Google Fonts <link> with preconnect, all CSS inline. - .badge / .meta / .engine-footer / .colophon containers. Flexible (role-based): - <h2> rendering covers BOTH plain ## headers (comparison mode per LAW 4 exception) AND promoted prose labels via PROSE_LABELS registry. Adding a new SKILL.md prose label is a one-line tuple addition; no CSS or template changes. - Marker-based engine boundaries (, ) survive the markdown converter and get promoted post-conversion. Robust to engine output format changes. - Generic markdown-to-HTML for body content; future SKILL.md additions (new sections, tables, blockquotes) render correctly without code changes. Tests: 30 new tests in tests/test_html_render.py covering snapshots (rich/thin/comparison), CLI parsing, --synthesis-file end-to-end, prose label promotion, warning exclusion from artifact, parseability via html.parser, no-script self-containment. No SKILL.md voice contract changes, no LAWs 1-8 changes, no new pip dependencies, no JavaScript anywhere.
2026-05-02 11:30:22 -07:00
parent 5b87cca886
commit b1773be8f3
8 changed files with 1336 additions and 17 deletions
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [Unreleased]
+
+### Added
+
+- Add `--emit=html` for shareable, print-friendly HTML research briefs.
+
 ## [3.1.1] - 2026-04-24

 ### Fixed
@@ -96,6 +96,28 @@ The synthesis ranks by what real people actually engaged with. Social relevancy,

 ## What v3 Changed

+### Shareable HTML briefs
+
+Ask for an HTML brief and the skill saves a self-contained, dark-mode, print-friendly file you can drop into Slack, email, or Notion. No raw markdown leaks. Inline CSS, system-font fallbacks behind Inter and JetBrains Mono. No JavaScript. Works offline.
+
+```
+/last30days OpenClaw --emit=html
+```
+
+or just ask in plain language:
+
+```
+/last30days OpenClaw, give me a shareable HTML brief
+/last30days Cursor IDE for slack
+/last30days Anthropic earnings export as html
+```
+
+The skill emits the synthesis in chat as usual AND saves a brief to `${LAST30DAYS_MEMORY_DIR}/{topic}-brief.html` (defaults to `~/Documents/Last30Days/`). The chat response ends with the file path so you can `open` it or drag it into a message.
+
+What's in the file: badge, inline metadata line, the model's synthesis verbatim with all citations, the engine footer (✅ All agents reported back! tree), and a colophon noting the topic + how to re-run. Data quality warnings (degraded run, thin evidence, etc.) stay in the engine's stderr logs; they never leak into the shareable artifact.
+
+For direct CLI use without the model in the loop, the engine also accepts `--synthesis-file PATH` to convert any markdown synthesis to HTML.
+
 ### Intelligent search: the killer feature

 The v3 engine doesn't just search for your topic. It figures out *where* to search before the search begins. Type "OpenClaw" and the engine resolves @steipete (Peter Steinberger, the creator), r/openclaw, r/ClaudeCode, and the right YouTube channels and TikTok hashtags - all via a new Python pre-research brain built by [@j-sperling](https://github.com/j-sperling). The old engine searched keywords. The new engine understands your topic first, then searches the right people and communities.
@@ -1507,6 +1507,33 @@ Close with `I have all the links to the {N} {source list} I pulled from. Just as

 ---

+## SHAREABLE HTML BRIEF (when the user asked for one)
+
+**This section fires if EITHER trigger is true:**
+
+- `$ARGUMENTS` contains `--emit=html`, `--emit:html`, or `--html` as a flag
+- The user's natural-language request asks for an HTML brief, shareable doc, or file for sharing (Slack, email, Notion, "export as HTML", etc). Use your judgment for phrasing variants.
+
+**If neither trigger fires, skip this entire section and proceed to WAIT FOR USER'S RESPONSE.** No HTML save flow, no reference read needed.
+
+**When triggered, you MUST:**
+
+- Read `references/save-html-brief.md` BEFORE proceeding to WAIT FOR USER'S RESPONSE
+- Follow that file's instructions exactly - it is the canonical source for the save flow
+- Append the confirmation line (`📎 Shareable brief saved to <path>`) to your already-emitted chat response
+
+**You MUST NOT:**
+
+- Improvise the HTML save flow from memory or from instructions you've seen before
+- Skip the reference read because the steps "look familiar"
+- Save to a different path than the reference specifies
+- Add data quality warnings, debug headers, or safety notes to the saved HTML
+- Re-research the topic for the HTML render - the engine cache covers the second invocation
+
+**Why the directive is forceful:** the reference file is the only source of truth for the save flow. Skipping it produces broken artifacts - wrong path conventions, missing synthesis content, leaked engine debug output, or warnings that don't belong in shareable docs.
+
+---
+
 ## WAIT FOR USER'S RESPONSE

 **STOP and wait** for the user to respond. Do NOT call any tools after displaying the invitation. Do NOT append a `Sources:` section (see override above - WebSearch's mandate does not apply here). The research script already saved raw data to `LAST30DAYS_MEMORY_DIR` (defaults to `~/Documents/Last30Days`) via `--save-dir`.
@@ -0,0 +1,90 @@
+# Save shareable HTML brief
+
+This reference file is loaded by the main `SKILL.md` when the user asked for an HTML brief (either explicitly via `--emit=html` / `--emit:html` / `--html`, or in natural language - "give me a shareable HTML brief", "for Slack", "for Notion", "export as HTML", etc.). The detection happens in `SKILL.md` so that the common no-HTML path stays short; the implementation lives here.
+
+The contract: the synthesis still appears in chat as the primary output. The HTML is an additional artifact saved to disk for sharing. Both happen in the same turn.
+
+## When to fire this flow
+
+- After you have already emitted the full chat response: badge, "What I learned:" (or comparison title), bold-lead-in paragraphs with citations, KEY PATTERNS list, engine footer pass-through, invitation block.
+- BEFORE the WAIT FOR USER'S RESPONSE pause.
+- ONLY if the user asked. Do NOT save HTML when the user didn't ask for it.
+
+## How to fire it
+
+```bash
+# 1. Write your synthesis prose VERBATIM to a temp file. The synthesis is the
+#    "What I learned:" prose label, the bold-lead-in paragraphs with their
+#    inline citations as you wrote them in chat, and the "KEY PATTERNS from
+#    the research:" numbered list. Do NOT include the badge or the engine
+#    footer in the temp file - the engine adds those when it renders the HTML.
+#    Use the EXACT text you just wrote in chat. Do not paraphrase, do not
+#    summarize, do not reorder. The HTML must read identically to the chat
+#    response in voice and citations.
+SYNTHESIS_FILE="/tmp/last30days-synthesis-${CLAUDE_SESSION_ID}.md"
+cat > "$SYNTHESIS_FILE" <<'SYNTHESIS_EOF'
+What I learned:
+
+**{First headline}** - {body with [name](url) inline citations}
+
+**{Second headline}** - {body}
+
+**{Third headline}** - {body}
+
+KEY PATTERNS from the research:
+1. {pattern} - per [@handle](url)
+2. {pattern} - per [r/sub](url)
+3. {pattern} - per [@handle](url)
+SYNTHESIS_EOF
+
+# 2. Convert the synthesis to a self-contained HTML file via the engine.
+#    The engine reuses the cache from your earlier engine run (same topic
+#    + plan), so this second invocation is typically <1s on cache hit.
+SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//')
+HTML_PATH="${LAST30DAYS_MEMORY_DIR}/${SLUG}-brief.html"
+"${LAST30DAYS_PYTHON}" "${SKILL_ROOT}/scripts/last30days.py" "${TOPIC}" \
+  --emit=html \
+  --synthesis-file "$SYNTHESIS_FILE" \
+  > "$HTML_PATH"
+
+# 3. Append ONE line to your already-emitted chat response, after the
+#    invitation block. Use a paperclip emoji as a visible signal that an
+#    artifact was produced:
+echo "📎 Shareable brief saved to $HTML_PATH"
+```
+
+## What ends up in the HTML file
+
+The engine's `--emit=html` renderer combines:
+
+- The badge (`🌐 last30days vX.Y.Z · synced YYYY-MM-DD`) at the top
+- A single inline metadata line (`{date range} · {active sources}`) below the badge
+- Your synthesis verbatim, with prose labels promoted to `<h2>` and bold lead-ins preserved
+- All `[name](url)` citations rendered as `<a>` tags
+- The engine footer (`✅ All agents reported back!` tree) preserved verbatim in monospace
+- A colophon with the topic and a re-run hint
+
+The renderer strips engine-internal noise that doesn't belong in a shareable artifact: the `# last30days vX.Y.Z: TOPIC` debug file header, the model-facing `> Safety note:` blockquote, and the `I'm now an expert on X` invitation block. Data quality warnings (degraded run, thin evidence, etc.) stay in the engine's stderr logs - they never leak into the share-ready file.
+
+## Comparison mode
+
+Same flow when the topic is `X vs Y` (or `X vs Y vs Z`). The engine routes through `render_for_html_comparison` internally; you don't need to do anything special. The synthesis temp file should still contain the comparison-shaped synthesis you wrote in chat (`## Quick Verdict`, `## {Entity}` per entity, `## Head-to-Head` table, `## The Bottom Line`, `## The emerging stack` per LAW 4 comparison exception).
+
+## Follow-up turn
+
+If the user runs `/last30days OpenClaw` normally, sees the synthesis in chat, and THEN says "save that as HTML" or "give me a shareable version" in a follow-up turn, do the same save flow on the synthesis you wrote in the previous turn. Do not re-research; the synthesis is already in the conversation history. Just write it to the temp file and call the engine with `--emit=html --synthesis-file`.
+
+## What NOT to do
+
+- Do NOT save HTML if the user didn't ask. The sparse mode (no synthesis) produces a thin file; not useful as a shareable.
+- Do NOT add content to the temp file beyond your synthesis prose. The badge / footer / colophon come from the engine.
+- Do NOT change the file path convention. `${LAST30DAYS_MEMORY_DIR}/${SLUG}-brief.html` is the canonical location.
+- Do NOT silently overwrite an existing file without telling the user. If `$HTML_PATH` already exists from a prior run, the engine will pick a date-suffixed name (`{slug}-brief-YYYY-MM-DD.html`) automatically; just print whichever path the redirect produced.
+- Do NOT include the data quality warning text in the temp file or in your final chat line. Warnings are an engine-stderr concern, not an artifact concern.
+
+## Edge cases
+
+- **Topic with shell-special characters** (quotes, ampersands): the temp filename uses a slugified version, but the engine receives the raw topic. The `cat <<'SYNTHESIS_EOF'` quoted heredoc form handles arbitrary content without expansion. Your synthesis text can include any character.
+- **Very long synthesis**: no upper bound. The engine handles long markdown bodies. Just paste verbatim.
+- **Synthesis with images or non-ASCII**: emoji and Unicode pass through. Image tags pass through as raw HTML; the renderer doesn't transform them. If you didn't include images in chat, don't add them here.
+- **No `${LAST30DAYS_MEMORY_DIR}` set**: defaults to `~/Documents/Last30Days/` per the SKILL.md `Configuration` section.
@@ -41,7 +41,7 @@ if os.name == "nt":
 SCRIPT_DIR = Path(__file__).parent.resolve()
 sys.path.insert(0, str(SCRIPT_DIR))

-from lib import env, pipeline, render, schema, ui
+from lib import env, html_render, pipeline, render, schema, ui

 _child_pids: set[int] = set()
 _child_pids_lock = threading.Lock()
@@ -91,30 +91,46 @@ def slugify(value: str) -> str:
    return slug or "last30days"


-def save_output(report: schema.Report, emit: str, save_dir: str, suffix: str = "") -> Path:
+def save_output(
+    report: schema.Report,
+    emit: str,
+    save_dir: str,
+    suffix: str = "",
+    synthesis_md: str | None = None,
+) -> Path:
    from datetime import datetime
    path = Path(save_dir).expanduser().resolve()
    path.mkdir(parents=True, exist_ok=True)
    slug = slugify(report.topic)
-    extension = "json" if emit == "json" else "md"
+    extension = "json" if emit == "json" else "html" if emit == "html" else "md"
+    raw_label = "raw-html" if emit == "html" else "raw"
    suffix_part = f"-{suffix}" if suffix else ""
-    out_path = path / f"{slug}-raw{suffix_part}.{extension}"
+    out_path = path / f"{slug}-{raw_label}{suffix_part}.{extension}"
    if out_path.exists():
-        out_path = path / f"{slug}-raw{suffix_part}-{datetime.now().strftime('%Y-%m-%d')}.{extension}"
-    # Always save the FULL dump to disk (all items, all sources, transcripts).
-    # Claude sees compact clusters via --emit=compact on stdout.
-    # The saved file is the complete debug artifact.
-    if emit == "json":
-        content = emit_output(report, emit)
+        out_path = path / f"{slug}-{raw_label}{suffix_part}-{datetime.now().strftime('%Y-%m-%d')}.{extension}"
+    # Markdown saves keep the complete debug artifact. JSON and HTML preserve
+    # their requested wire format so file extensions match their content.
+    if emit in {"json", "html"}:
+        content = emit_output(report, emit, synthesis_md=synthesis_md)
    else:
        content = render.render_full(report)
    out_path.write_text(content, encoding="utf-8")
    return out_path


-def emit_output(report: schema.Report, emit: str, fun_level: str = "medium", save_path: str | None = None) -> str:
+def emit_output(
+    report: schema.Report,
+    emit: str,
+    fun_level: str = "medium",
+    save_path: str | None = None,
+    synthesis_md: str | None = None,
+) -> str:
    if emit == "json":
        return json.dumps(schema.to_dict(report), indent=2, sort_keys=True)
+    if emit == "html":
+        return html_render.render_html(
+            report, fun_level=fun_level, save_path=save_path, synthesis_md=synthesis_md,
+        )
    if emit in {"compact", "md"}:
        return render.render_compact(report, fun_level=fun_level, save_path=save_path)
    if emit == "context":
@@ -127,6 +143,7 @@ def emit_comparison_output(
    emit: str,
    fun_level: str = "medium",
    save_path: str | None = None,
+    synthesis_md: str | None = None,
 ) -> str:
    if emit == "json":
        payload = {
@@ -138,6 +155,13 @@ def emit_comparison_output(
            ],
        }
        return json.dumps(payload, indent=2, sort_keys=True)
+    if emit == "html":
+        return html_render.render_html_comparison(
+            entity_reports,
+            fun_level=fun_level,
+            save_path=save_path,
+            synthesis_md=synthesis_md,
+        )
    if emit in {"compact", "md"}:
        return render.render_comparison_multi(
            entity_reports, fun_level=fun_level, save_path=save_path,
@@ -156,9 +180,10 @@ def compute_save_path_display(save_dir: str, topic: str, suffix: str, emit: str)
    from pathlib import Path as _Path
    path = _Path(save_dir).expanduser().resolve()
    slug = slugify(topic)
-    extension = "json" if emit == "json" else "md"
+    extension = "json" if emit == "json" else "html" if emit == "html" else "md"
+    raw_label = "raw-html" if emit == "html" else "raw"
    suffix_part = f"-{suffix}" if suffix else ""
-    raw = path / f"{slug}-raw{suffix_part}.{extension}"
+    raw = path / f"{slug}-{raw_label}{suffix_part}.{extension}"
    try:
        home = _Path.home().resolve()
        relative = raw.relative_to(home)
@@ -167,6 +192,14 @@ def compute_save_path_display(save_dir: str, topic: str, suffix: str, emit: str)
        return str(raw)


+def read_synthesis_file(path: str) -> str:
+    try:
+        return Path(path).expanduser().read_text(encoding="utf-8")
+    except OSError as exc:
+        sys.stderr.write(f"[last30days] Cannot read --synthesis-file: {exc}\n")
+        raise SystemExit(2)
+
+
 def persist_report(report: schema.Report) -> dict[str, int]:
    import store

@@ -193,7 +226,7 @@ def persist_report(report: schema.Report) -> dict[str, int]:
 def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Research a topic across live social, market, and grounded web sources.")
    parser.add_argument("topic", nargs="*", help="Research topic")
-    parser.add_argument("--emit", default="compact", choices=["compact", "json", "context", "md"])
+    parser.add_argument("--emit", default="compact", choices=["compact", "json", "context", "md", "html"])
    parser.add_argument("--search", help="Comma-separated source list")
    parser.add_argument("--quick", action="store_true", help="Lower-latency retrieval profile")
    parser.add_argument("--deep", action="store_true", help="Higher-recall retrieval profile")
@@ -201,6 +234,7 @@ def build_parser() -> argparse.ArgumentParser:
    parser.add_argument("--mock", action="store_true", help="Use mock retrieval fixtures")
    parser.add_argument("--diagnose", action="store_true", help="Print provider and source availability")
    parser.add_argument("--save-dir", help="Optional directory for saving the rendered output")
+    parser.add_argument("--synthesis-file", help="Markdown synthesis to embed in --emit=html output")
    parser.add_argument("--store", action="store_true", help="Persist ranked findings to the SQLite research store")
    parser.add_argument("--x-handle", help="X handle for targeted supplemental search")
    parser.add_argument("--x-related", help="Comma-separated related X handles (searched with lower weight)")
@@ -537,6 +571,13 @@ def main() -> int:
        parser.print_usage(sys.stderr)
        return 2

+    synthesis_md = None
+    if args.synthesis_file:
+        if args.emit == "html":
+            synthesis_md = read_synthesis_file(args.synthesis_file)
+        else:
+            sys.stderr.write("[last30days] Warning: --synthesis-file is only used with --emit=html; ignoring.\n")
+
    if not os.environ.get("LAST30DAYS_SKIP_PREFLIGHT"):
        from lib import preflight
        refuse_msg = preflight.check_class_1_trap(topic)
@@ -854,15 +895,29 @@ def main() -> int:

    if entity_reports:
        rendered = emit_comparison_output(
-            entity_reports, args.emit, fun_level=fun_level, save_path=footer_save_path,
+            entity_reports,
+            args.emit,
+            fun_level=fun_level,
+            save_path=footer_save_path,
+            synthesis_md=synthesis_md,
        )
    else:
        rendered = emit_output(
-            report, args.emit, fun_level=fun_level, save_path=footer_save_path,
+            report,
+            args.emit,
+            fun_level=fun_level,
+            save_path=footer_save_path,
+            synthesis_md=synthesis_md,
        )
    if args.save_dir:
        # Save the main topic's raw file (single-entity or comparison main).
-        save_path = save_output(report, args.emit, args.save_dir, suffix=args.save_suffix or "")
+        save_path = save_output(
+            report,
+            args.emit,
+            args.save_dir,
+            suffix=args.save_suffix or "",
+            synthesis_md=synthesis_md,
+        )
        sys.stderr.write(f"[last30days] Saved output to {save_path}\n")
        # Competitor / vs-mode: also save a per-entity raw file for each peer.
        # Matches historical vs-mode behavior (N passes → N save files).
@@ -871,6 +926,7 @@ def main() -> int:
                peer_path = save_output(
                    entity_report, args.emit, args.save_dir,
                    suffix=args.save_suffix or "",
+                    synthesis_md=synthesis_md,
                )
                sys.stderr.write(f"[last30days] Saved output to {peer_path}\n")
        sys.stderr.flush()
@@ -0,0 +1,674 @@
+"""HTML rendering for shareable last30days reports."""
+
+from __future__ import annotations
+
+import html
+import re
+from datetime import date
+
+from . import render, schema
+
+
+PROSE_LABELS = [
+    ("What I learned:", "What I learned"),
+    ("KEY PATTERNS from the research:", "Key patterns from the research"),
+]
+
+INVITATION_PATTERN = re.compile(r"^---\nI'm now an expert.*?Just ask\.$", re.MULTILINE | re.DOTALL)
+EVIDENCE_BLOCK_PATTERN = re.compile(r"<!-- EVIDENCE FOR SYNTHESIS.*?<!-- END EVIDENCE FOR SYNTHESIS -->", re.DOTALL)
+PASS_THROUGH_FOOTER_PATTERN = re.compile(r"<!-- PASS-THROUGH FOOTER.*?-->\n(.*?)<!-- END PASS-THROUGH FOOTER -->", re.DOTALL)
+CANONICAL_BOUNDARY_PATTERN = re.compile(r"\n?---\n# END OF last30days CANONICAL OUTPUT.*$", re.DOTALL)
+# render_for_html emits metadata as <!-- META: ... --> so it survives the
+# markdown converter (which escapes raw HTML inside paragraphs). Promoted to
+# a styled <div class="meta"> after conversion.
+META_MARKER_PATTERN = re.compile(r"<!--\s*META:\s*(.*?)\s*-->")
+
+CSS = """
+:root {
+  --bg: #0e0e10;
+  --bg-elev: #18181b;
+  --fg: #fafafa;
+  --fg-muted: #a1a1aa;
+  --fg-subtle: #71717a;
+  --accent: #a855f7;
+  --accent-soft: #c4b5fd;
+  --border: #27272a;
+  --code-bg: #1a1a1d;
+  --max-w: 720px;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg: #ffffff;
+    --bg-elev: #fafafa;
+    --fg: #18181b;
+    --fg-muted: #52525b;
+    --fg-subtle: #71717a;
+    --accent: #7c3aed;
+    --accent-soft: #6d28d9;
+    --border: #e4e4e7;
+    --code-bg: #f4f4f5;
+  }
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  padding: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, system-ui, sans-serif;
+  font-size: 17px;
+  line-height: 1.65;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+}
+
+body {
+  max-width: var(--max-w);
+  margin: 0 auto;
+  padding: 4rem 1.5rem 6rem;
+}
+
+.badge {
+  display: inline-block;
+  padding: 0.4rem 0.85rem;
+  margin-bottom: 2.5rem;
+  background: var(--bg-elev);
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  font-family: 'JetBrains Mono', ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--fg-muted);
+  letter-spacing: 0;
+}
+
+.badge .accent { color: var(--accent); }
+
+.meta {
+  margin: -1.5rem 0 2.5rem;
+  color: var(--fg-subtle);
+  font-family: 'JetBrains Mono', ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace;
+  font-size: 13px;
+  letter-spacing: 0.01em;
+}
+
+h1 {
+  margin: 0 0 1.5rem;
+  color: var(--fg);
+  font-size: 30px;
+  font-weight: 700;
+  line-height: 1.2;
+  letter-spacing: 0;
+}
+
+h2,
+.prose-label {
+  margin: 2.75rem 0 1.25rem;
+  color: var(--fg);
+  font-size: 20px;
+  font-weight: 600;
+  line-height: 1.35;
+  letter-spacing: 0;
+}
+
+.badge + h2,
+.badge + .prose-label { margin-top: 0.5rem; }
+
+h3 {
+  margin: 2rem 0 0.85rem;
+  color: var(--fg);
+  font-size: 17px;
+  font-weight: 600;
+  line-height: 1.4;
+  letter-spacing: 0;
+}
+
+p {
+  margin: 0 0 1.4rem;
+  color: var(--fg-muted);
+}
+
+p strong,
+li strong,
+td strong {
+  color: var(--fg);
+  font-weight: 600;
+}
+
+a {
+  color: var(--accent);
+  text-decoration: none;
+  border-bottom: 1px solid transparent;
+  transition: border-color 0.15s ease;
+}
+
+a:hover { border-bottom-color: var(--accent); }
+
+ul,
+ol {
+  margin: 0 0 1.6rem;
+  padding-left: 1.5rem;
+  color: var(--fg-muted);
+}
+
+li {
+  margin: 0.6rem 0;
+  padding-left: 0.4rem;
+}
+
+li::marker {
+  color: var(--accent);
+  font-weight: 600;
+}
+
+blockquote {
+  margin: 1.5rem 0;
+  padding-left: 1rem;
+  border-left: 3px solid var(--accent);
+  color: var(--fg-muted);
+}
+
+hr {
+  margin: 2.5rem 0;
+  border: 0;
+  border-top: 1px solid var(--border);
+}
+
+code {
+  font-family: 'JetBrains Mono', ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace;
+  font-size: 0.92em;
+  background: var(--code-bg);
+  padding: 0.15rem 0.4rem;
+  border-radius: 4px;
+  color: var(--accent-soft);
+}
+
+pre {
+  margin: 1.4rem 0;
+  background: var(--code-bg);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 1rem 1.25rem;
+  overflow-x: auto;
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+pre code {
+  background: none;
+  padding: 0;
+  color: var(--fg);
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.5rem 0;
+  font-size: 15px;
+}
+
+th,
+td {
+  text-align: left;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border);
+  vertical-align: top;
+}
+
+th {
+  color: var(--fg-muted);
+  font-weight: 600;
+  font-size: 13px;
+  letter-spacing: 0;
+  text-transform: uppercase;
+}
+
+td { color: var(--fg-muted); }
+td:first-child { color: var(--fg); font-weight: 500; }
+
+.engine-footer {
+  margin: 3rem 0 2.5rem;
+  padding: 1.25rem 1.5rem;
+  background: var(--bg-elev);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  color: var(--fg-muted);
+}
+
+.engine-footer pre {
+  margin: 0;
+  padding: 0;
+  background: transparent;
+  border: 0;
+  border-radius: 0;
+  font-family: 'JetBrains Mono', ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace;
+  font-size: 13.5px;
+  font-weight: 400;
+  line-height: 1.75;
+  color: inherit;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.colophon {
+  margin-top: 4rem;
+  padding-top: 2rem;
+  border-top: 1px solid var(--border);
+  color: var(--fg-subtle);
+  font-size: 13px;
+  font-family: 'JetBrains Mono', ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace;
+  line-height: 1.7;
+}
+
+.colophon .rerun {
+  display: inline-block;
+  padding: 0.15rem 0.5rem;
+  margin-left: 0.25rem;
+  background: var(--code-bg);
+  border-radius: 4px;
+  color: var(--accent-soft);
+  font-size: 0.95em;
+}
+
+@media print {
+  :root {
+    --bg: #ffffff;
+    --bg-elev: #f5f5f5;
+    --fg: #000000;
+    --fg-muted: #1f2937;
+    --fg-subtle: #4b5563;
+    --accent: #6d28d9;
+    --accent-soft: #6d28d9;
+    --border: #d4d4d8;
+    --code-bg: #f4f4f5;
+  }
+
+  @page { size: A4; margin: 1.5cm 2cm; }
+
+  body {
+    max-width: none;
+    padding: 0;
+    font-size: 11pt;
+  }
+
+  a {
+    color: inherit;
+    border-bottom: 0;
+    text-decoration: underline;
+  }
+
+  a[href]::after {
+    content: " (" attr(href) ")";
+    font-size: 0.85em;
+    color: var(--fg-subtle);
+  }
+
+  .engine-footer { page-break-inside: avoid; }
+}
+
+@media (max-width: 600px) {
+  body {
+    padding: 2.5rem 1.25rem 4rem;
+    font-size: 16px;
+  }
+
+  h1 { font-size: 25px; }
+  .badge { font-size: 12px; }
+  th, td { padding: 0.65rem 0.5rem; }
+}
+""".strip()
+
+HTML_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>last30days · __TITLE__</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&amp;family=JetBrains+Mono:wght@400;500&amp;display=swap" rel="stylesheet">
+<style>
+__CSS__
+</style>
+</head>
+<body>
+__BODY__
+__COLOPHON__
+</body>
+</html>
+"""
+
+
+def render_html(
+    report: schema.Report,
+    *,
+    fun_level: str = "medium",
+    save_path: str | None = None,
+    synthesis_md: str | None = None,
+) -> str:
+    _ = fun_level
+    md = render.render_for_html(report, synthesis_md=synthesis_md, save_path=save_path)
+    md = _strip_evidence_block(md)
+    md = _strip_invitation(md)
+    md = _strip_canonical_boundary(md)
+    md = _promote_prose_labels(md)
+    body = _markdown_to_html(md)
+    body = _wrap_engine_footer(body)
+    body = _promote_meta_marker(body)
+    colophon = _build_colophon(report)
+    return _wrap_in_template(body, colophon, report.topic)
+
+
+def render_html_comparison(
+    entity_reports: list[tuple[str, schema.Report]],
+    *,
+    fun_level: str = "medium",
+    save_path: str | None = None,
+    synthesis_md: str | None = None,
+) -> str:
+    _ = fun_level
+    md = render.render_for_html_comparison(
+        entity_reports, synthesis_md=synthesis_md, save_path=save_path,
+    )
+    md = _strip_evidence_block(md)
+    md = _strip_invitation(md)
+    md = _strip_canonical_boundary(md)
+    md = _promote_prose_labels(md)
+    body = _markdown_to_html(md)
+    body = _wrap_engine_footer(body)
+    body = _promote_meta_marker(body)
+    topic = " vs ".join(label for label, _ in entity_reports)
+    colophon = _build_colophon(entity_reports[0][1], topic=topic)
+    return _wrap_in_template(body, colophon, topic)
+
+
+def _strip_evidence_block(md: str) -> str:
+    return EVIDENCE_BLOCK_PATTERN.sub("", md)
+
+
+def _strip_invitation(md: str) -> str:
+    return INVITATION_PATTERN.sub("", md)
+
+
+def _strip_canonical_boundary(md: str) -> str:
+    return CANONICAL_BOUNDARY_PATTERN.sub("", md)
+
+
+def _promote_prose_labels(md: str) -> str:
+    for source, normalized in PROSE_LABELS:
+        md = re.sub(
+            rf"^{re.escape(source)}$",
+            f"## {normalized}",
+            md,
+            flags=re.MULTILINE,
+        )
+    return md
+
+
+def _markdown_to_html(md: str) -> str:
+    md, footers = _protect_engine_footers(md)
+    global _ENGINE_FOOTER_STORE
+    _ENGINE_FOOTER_STORE = footers
+    # Strip HTML comments EXCEPT preserved markers used for post-processing
+    # (META is promoted to <div class="meta"> after markdown conversion).
+    md = re.sub(r"<!--(?!\s*META:).*?-->", "", md, flags=re.DOTALL)
+    lines = md.splitlines()
+    out: list[str] = []
+    paragraph: list[str] = []
+    list_type: str | None = None
+    in_code = False
+    code_lines: list[str] = []
+    index = 0
+
+    def flush_paragraph() -> None:
+        nonlocal paragraph
+        if paragraph:
+            text = " ".join(part.strip() for part in paragraph).strip()
+            if text:
+                out.append(f"<p>{_inline_markdown(text)}</p>")
+            paragraph = []
+
+    def close_list() -> None:
+        nonlocal list_type
+        if list_type:
+            out.append(f"</{list_type}>")
+            list_type = None
+
+    while index < len(lines):
+        line = lines[index]
+        stripped = line.strip()
+
+        if in_code:
+            if stripped.startswith("```"):
+                out.append(f"<pre><code>{html.escape(chr(10).join(code_lines))}</code></pre>")
+                code_lines = []
+                in_code = False
+            else:
+                code_lines.append(line)
+            index += 1
+            continue
+
+        if stripped.startswith("```"):
+            flush_paragraph()
+            close_list()
+            in_code = True
+            code_lines = []
+            index += 1
+            continue
+
+        if stripped in footers:
+            flush_paragraph()
+            close_list()
+            out.append(stripped)
+            index += 1
+            continue
+
+        if not stripped:
+            flush_paragraph()
+            close_list()
+            index += 1
+            continue
+
+        if stripped == "---":
+            flush_paragraph()
+            close_list()
+            out.append("<hr>")
+            index += 1
+            continue
+
+        if index + 1 < len(lines) and _is_table_row(stripped) and _is_table_separator(lines[index + 1].strip()):
+            flush_paragraph()
+            close_list()
+            table_lines = [stripped]
+            index += 2
+            while index < len(lines) and _is_table_row(lines[index].strip()):
+                table_lines.append(lines[index].strip())
+                index += 1
+            out.append(_render_table(table_lines))
+            continue
+
+        heading = re.match(r"^(#{1,4})\s+(.+)$", stripped)
+        if heading:
+            flush_paragraph()
+            close_list()
+            level = min(len(heading.group(1)), 3)
+            out.append(f"<h{level}>{_inline_markdown(heading.group(2))}</h{level}>")
+            index += 1
+            continue
+
+        if stripped.startswith(">"):
+            flush_paragraph()
+            close_list()
+            quote_lines = []
+            while index < len(lines) and lines[index].strip().startswith(">"):
+                quote_lines.append(lines[index].strip().lstrip(">").strip())
+                index += 1
+            out.append(f"<blockquote>{_inline_markdown(' '.join(quote_lines))}</blockquote>")
+            continue
+
+        unordered = re.match(r"^[-*]\s+(.+)$", stripped)
+        ordered = re.match(r"^\d+[.)]\s+(.+)$", stripped)
+        if unordered or ordered:
+            flush_paragraph()
+            next_type = "ul" if unordered else "ol"
+            if list_type != next_type:
+                close_list()
+                out.append(f"<{next_type}>")
+                list_type = next_type
+            item = unordered.group(1) if unordered else ordered.group(1)
+            out.append(f"<li>{_inline_markdown(item)}</li>")
+            index += 1
+            continue
+
+        if stripped.startswith("🌐 last30days"):
+            flush_paragraph()
+            close_list()
+            badge_text = _inline_markdown(stripped.removeprefix("🌐").strip())
+            out.append(f'<div class="badge"><span class="accent">🌐</span> {badge_text}</div>')
+            index += 1
+            continue
+
+        paragraph.append(line)
+        index += 1
+
+    if in_code:
+        out.append(f"<pre><code>{html.escape(chr(10).join(code_lines))}</code></pre>")
+    flush_paragraph()
+    close_list()
+    return "\n".join(out).strip()
+
+
+def _protect_engine_footers(md: str) -> tuple[str, dict[str, str]]:
+    footers: dict[str, str] = {}
+
+    def replace(match: re.Match[str]) -> str:
+        token = f"__LAST30DAYS_ENGINE_FOOTER_{len(footers)}__"
+        footers[token] = match.group(1).strip("\n")
+        return f"\n{token}\n"
+
+    return PASS_THROUGH_FOOTER_PATTERN.sub(replace, md), footers
+
+
+def _wrap_engine_footer(body: str) -> str:
+    def replace(match: re.Match[str]) -> str:
+        footer = html.escape(_ENGINE_FOOTER_STORE.get(match.group(0), ""), quote=False)
+        return f'<div class="engine-footer"><pre>{footer}</pre></div>'
+
+    return re.sub(
+        r"__LAST30DAYS_ENGINE_FOOTER_\d+__",
+        replace,
+        body,
+    )
+
+
+def _promote_meta_marker(body: str) -> str:
+    """Promote ``<!-- META: ... -->`` markers into a styled ``<div class="meta">``.
+
+    The marker is preserved through the comment-strip pass (see
+    _markdown_to_html exemption) but the markdown converter wraps it in
+    ``<p>`` and HTML-escapes the angle brackets. After conversion the body
+    contains shapes like:
+      <p>&lt;!-- META: TEXT --&gt;</p>
+      <p><!-- META: TEXT --></p>     (when not escaped)
+    Both collapse to ``<div class="meta">TEXT</div>``.
+    """
+    def replace(match: re.Match[str]) -> str:
+        text = match.group(1).strip()
+        return f'<div class="meta">{text}</div>'
+
+    # Escaped form (most common after markdown conversion)
+    body = re.sub(
+        r"<p>\s*&lt;!--\s*META:\s*(.*?)\s*--&gt;\s*</p>",
+        replace,
+        body,
+    )
+    body = re.sub(r"&lt;!--\s*META:\s*(.*?)\s*--&gt;", replace, body)
+    # Unescaped form (paranoid fallback)
+    body = re.sub(r"<p>\s*<!--\s*META:\s*(.*?)\s*-->\s*</p>", replace, body)
+    body = re.sub(r"<!--\s*META:\s*(.*?)\s*-->", replace, body)
+    return body
+
+
+_ENGINE_FOOTER_STORE: dict[str, str] = {}
+
+
+def _inline_markdown(text: str) -> str:
+    escaped = html.escape(text, quote=True)
+    code_tokens: dict[str, str] = {}
+
+    def code_replace(match: re.Match[str]) -> str:
+        token = f"__CODE_{len(code_tokens)}__"
+        code_tokens[token] = f"<code>{match.group(1)}</code>"
+        return token
+
+    escaped = re.sub(r"`([^`]+)`", code_replace, escaped)
+    escaped = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", escaped)
+    escaped = re.sub(
+        r"\[([^\]]+)\]\(([^)\s]+)\)",
+        r'<a href="\2">\1</a>',
+        escaped,
+    )
+    for token, value in code_tokens.items():
+        escaped = escaped.replace(token, value)
+    return escaped
+
+
+def _is_table_row(line: str) -> bool:
+    return "|" in line and len(_split_table_cells(line)) >= 2
+
+
+def _is_table_separator(line: str) -> bool:
+    cells = _split_table_cells(line)
+    return bool(cells) and all(re.fullmatch(r":?-{3,}:?", cell.strip()) for cell in cells)
+
+
+def _split_table_cells(line: str) -> list[str]:
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
+def _render_table(rows: list[str]) -> str:
+    header = _split_table_cells(rows[0])
+    body_rows = [_split_table_cells(row) for row in rows[1:]]
+    out = ["<table>", "<thead>", "<tr>"]
+    out.extend(f"<th>{_inline_markdown(cell)}</th>" for cell in header)
+    out.extend(["</tr>", "</thead>", "<tbody>"])
+    for row in body_rows:
+        out.append("<tr>")
+        out.extend(f"<td>{_inline_markdown(cell)}</td>" for cell in row)
+        out.append("</tr>")
+    out.extend(["</tbody>", "</table>"])
+    return "\n".join(out)
+
+
+def _build_colophon(report: schema.Report, *, topic: str | None = None) -> str:
+    display_topic = topic or report.topic
+    generated = _generated_date(report)
+    version = render._skill_version()
+    escaped_topic = html.escape(display_topic)
+    rerun = html.escape(f"/last30days {display_topic}")
+    return (
+        '<div class="colophon">\n'
+        f"  Generated {generated} by /last30days v{html.escape(version)} · topic: {escaped_topic}<br>\n"
+        f'  Re-run for fresh data: <span class="rerun">{rerun}</span>\n'
+        "</div>"
+    )
+
+
+def _generated_date(report: schema.Report) -> str:
+    if report.generated_at:
+        return report.generated_at[:10]
+    return date.today().strftime("%Y-%m-%d")
+
+
+def _wrap_in_template(body: str, colophon: str, title: str) -> str:
+    return (
+        HTML_TEMPLATE
+        .replace("__TITLE__", html.escape(title))
+        .replace("__CSS__", CSS)
+        .replace("__BODY__", body)
+        .replace("__COLOPHON__", colophon)
+    )
@@ -171,6 +171,168 @@ def render_compact(report: schema.Report, cluster_limit: int = 8, fun_level: str
    return "\n".join(lines).strip() + "\n"


+def render_for_html(
+    report: schema.Report,
+    synthesis_md: str | None = None,
+    *,
+    save_path: str | None = None,
+) -> str:
+    """Render markdown intended for shareable HTML conversion.
+
+    This output keeps the public badge, compact source/date metadata, an
+    optional one-line data quality note, optional synthesized brief markdown,
+    and the engine footer. It deliberately omits the debug file header,
+    model-facing safety note, and evidence scratchpad emitted by
+    render_compact().
+
+    When synthesis_md is None, the body is intentionally sparse: badge,
+    metadata, optional data quality note, and engine footer only.
+    """
+    lines = [
+        *_render_badge(),
+        *_render_html_metadata(report),
+    ]
+    if synthesis_md:
+        lines.extend(["", synthesis_md.strip()])
+    # Data quality warnings are NOT rendered into the HTML artifact. The HTML
+    # is meant to be shared (Slack, email, Notion); recipients haven't asked
+    # for technical commentary about how the run was produced. Generators see
+    # the same warnings via collect_html_warnings() routed to stderr by the
+    # CLI, so they can fix quality issues before sharing.
+    _append_html_footer(lines, report, save_path)
+    return "\n".join(lines).strip() + "\n"
+
+
+def render_for_html_comparison(
+    entity_reports: list[tuple[str, schema.Report]],
+    synthesis_md: str | None = None,
+    *,
+    save_path: str | None = None,
+) -> str:
+    """Render comparison markdown intended for shareable HTML conversion.
+
+    Same semantics as render_for_html(), but metadata and data quality notes
+    are aggregated across the compared entities.
+    """
+    if not entity_reports:
+        raise ValueError("render_for_html_comparison requires at least one report")
+
+    entities = [label for label, _ in entity_reports]
+    main_report = entity_reports[0][1]
+    meta = (
+        f"<!-- META: {main_report.range_from} to {main_report.range_to} "
+        f"· comparing {len(entities)}: {', '.join(entities)} -->"
+    )
+    lines = [
+        *_render_badge(),
+        meta,
+    ]
+    if synthesis_md:
+        lines.extend(["", synthesis_md.strip()])
+    # Comparison data quality notes also go to stderr, not into the artifact.
+    _append_html_footer(lines, main_report, save_path)
+    return "\n".join(lines).strip() + "\n"
+
+
+def collect_html_warnings(report: schema.Report) -> list[str]:
+    """Collect data quality warnings for stderr output (NOT for the HTML artifact).
+
+    Returns a list of human-readable warning strings. Empty list if the run
+    was clean. Used by the CLI to emit diagnostics to stderr after writing
+    the HTML to stdout/file.
+    """
+    notes: list[str] = []
+    if _render_degraded_run_warning(report):
+        notes.append("Run was missing pre-flight resolution. Re-run with `--plan` for richer results.")
+    elif _render_pre_research_warning(report):
+        notes.append("Pre-research was skipped, so results may be thinner than a resolved run.")
+    freshness_warning = _assess_data_freshness(report)
+    if freshness_warning:
+        notes.append(freshness_warning)
+    notes.extend(report.warnings)
+    return _dedupe_notes(notes)
+
+
+def collect_html_warnings_comparison(
+    entity_reports: list[tuple[str, schema.Report]],
+) -> list[str]:
+    """Collect comparison-mode warnings, prefixed by entity label."""
+    notes: list[str] = []
+    for label, report in entity_reports:
+        for w in collect_html_warnings(report):
+            notes.append(f"{label}: {w}")
+    return notes
+
+
+def _render_html_metadata(report: schema.Report) -> list[str]:
+    """Inline metadata as an HTML comment marker.
+
+    html_render.py post-processes ``<!-- META: ... -->`` markers into a
+    ``<div class="meta">`` after markdown conversion, so the metadata escapes
+    the markdown converter's HTML-escaping pass cleanly. Same pattern as the
+    PASS_THROUGH_FOOTER marker used for the engine tree.
+    """
+    non_empty = [s for s, items in sorted(report.items_by_source.items()) if items]
+    if non_empty:
+        sources = ", ".join(_source_label(s) for s in non_empty)
+    else:
+        sources = "no active sources"
+    return [
+        f"<!-- META: {report.range_from} to {report.range_to} · {sources} -->",
+    ]
+
+
+def _render_html_data_quality_note(report: schema.Report) -> str | None:
+    notes: list[str] = []
+    degraded_warning = _render_degraded_run_warning(report)
+    if degraded_warning:
+        notes.append("This run was missing pre-flight resolution. Re-run with `--plan` for richer results.")
+    pre_research_warning = _render_pre_research_warning(report)
+    if pre_research_warning and not degraded_warning:
+        notes.append("Pre-research was skipped, so results may be thinner than a resolved run.")
+    freshness_warning = _assess_data_freshness(report)
+    if freshness_warning:
+        notes.append(freshness_warning)
+    notes.extend(report.warnings)
+    if not notes:
+        return None
+    return f"> **Data quality note:** {' '.join(_dedupe_notes(notes))}"
+
+
+def _render_html_comparison_data_quality_note(
+    entity_reports: list[tuple[str, schema.Report]],
+) -> str | None:
+    notes: list[str] = []
+    for label, report in entity_reports:
+        note = _render_html_data_quality_note(report)
+        if note:
+            clean = note.removeprefix("> **Data quality note:** ").strip()
+            notes.append(f"{label}: {clean}")
+    if not notes:
+        return None
+    return f"> **Data quality note:** {' '.join(_dedupe_notes(notes))}"
+
+
+def _dedupe_notes(notes: list[str]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for note in notes:
+        normalized = " ".join(str(note).split())
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        out.append(normalized)
+    return out
+
+
+def _append_html_footer(lines: list[str], report: schema.Report, save_path: str | None) -> None:
+    footer = _render_emoji_footer(report, save_path)
+    lines.append("")
+    lines.append("<!-- PASS-THROUGH FOOTER: emit verbatim in the model response per LAW 5. -->")
+    lines.extend(footer)
+    lines.append("<!-- END PASS-THROUGH FOOTER -->")
+
+
 def _render_canonical_boundary() -> list[str]:
    """Emit the explicit END-OF-CANONICAL-OUTPUT boundary.

@@ -0,0 +1,282 @@
+# ruff: noqa: E402
+"""Tests for the HTML emit renderer."""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+import unittest
+from html.parser import HTMLParser
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "skills" / "last30days" / "scripts"))
+
+import last30days as cli
+from lib import html_render, schema
+
+
+def _report(topic: str, cluster_titles: list[str]) -> schema.Report:
+    items: list[schema.SourceItem] = []
+    candidates: list[schema.Candidate] = []
+    clusters: list[schema.Cluster] = []
+
+    for index, title in enumerate(cluster_titles, start=1):
+        item = schema.SourceItem(
+            item_id=f"item-{index}",
+            source="grounding",
+            title=title,
+            body=f"Body for {title}",
+            url=f"https://example.test/{index}",
+            container="example.test",
+            published_at="2026-04-20",
+            date_confidence="high",
+            engagement={"views": index * 100},
+            snippet=f"Snippet for {title}",
+        )
+        candidate = schema.Candidate(
+            candidate_id=f"candidate-{index}",
+            item_id=item.item_id,
+            source="grounding",
+            title=title,
+            url=item.url,
+            snippet=item.snippet,
+            subquery_labels=["primary"],
+            native_ranks={"primary:grounding": index},
+            local_relevance=0.9,
+            freshness=80,
+            engagement=50,
+            source_quality=1.0,
+            rrf_score=0.5,
+            final_score=90 - index,
+            sources=["grounding"],
+            source_items=[item],
+        )
+        cluster = schema.Cluster(
+            cluster_id=f"cluster-{index}",
+            title=title,
+            candidate_ids=[candidate.candidate_id],
+            representative_ids=[candidate.candidate_id],
+            sources=["grounding"],
+            score=90 - index,
+        )
+        items.append(item)
+        candidates.append(candidate)
+        clusters.append(cluster)
+
+    return schema.Report(
+        topic=topic,
+        range_from="2026-03-30",
+        range_to="2026-04-29",
+        generated_at="2026-04-29T12:00:00+00:00",
+        provider_runtime=schema.ProviderRuntime(
+            reasoning_provider="local",
+            planner_model="mock-planner",
+            rerank_model="mock-rerank",
+        ),
+        query_plan=schema.QueryPlan(
+            intent="research",
+            freshness_mode="balanced_recent",
+            cluster_mode="story",
+            raw_topic=topic,
+            subqueries=[
+                schema.SubQuery(
+                    label="primary",
+                    search_query=topic,
+                    ranking_query=topic,
+                    sources=["grounding"],
+                )
+            ],
+            source_weights={"grounding": 1.0},
+        ),
+        clusters=clusters,
+        ranked_candidates=candidates,
+        items_by_source={"grounding": items},
+        errors_by_source={},
+        artifacts={"pre_research_flags_present": True},
+    )
+
+
+def _assert_parses(test_case: unittest.TestCase, html: str) -> None:
+    parser = HTMLParser()
+    parser.feed(html)
+    parser.close()
+    test_case.assertIn("</html>", html)
+
+
+class HtmlRenderSnapshotTests(unittest.TestCase):
+    def test_rich_cluster_fixture_snapshot(self):
+        rendered = html_render.render_html(
+            _report("AI agent frameworks", ["OpenClaw ships containers", "Skills marketplace grows"])
+        )
+        snapshot_markers = [
+            "<!DOCTYPE html>",
+            "<title>last30days · AI agent frameworks</title>",
+            '<div class="badge"><span class="accent">🌐</span> last30days v',
+            '<div class="meta">2026-03-30 to 2026-04-29',
+            '<div class="engine-footer"><pre>---\n✅ All agents reported back!',
+            'Generated 2026-04-29 by /last30days v',
+            '<span class="rerun">/last30days AI agent frameworks</span>',
+        ]
+        for marker in snapshot_markers:
+            self.assertIn(marker, rendered)
+        self.assertNotIn("EVIDENCE FOR SYNTHESIS", rendered)
+        self.assertNotIn("END OF last30days CANONICAL OUTPUT", rendered)
+
+    def test_thin_cluster_fixture_snapshot(self):
+        rendered = html_render.render_html(_report("obscure topic", []))
+        snapshot_markers = [
+            "<title>last30days · obscure topic</title>",
+            "no active sources",
+            "topic: obscure topic",
+        ]
+        for marker in snapshot_markers:
+            self.assertIn(marker, rendered)
+
+    def test_comparison_mode_snapshot(self):
+        reports = [
+            ("OpenClaw", _report("OpenClaw", ["Containers"])),
+            ("Hermes", _report("Hermes", ["Memory"])),
+        ]
+        rendered = html_render.render_html_comparison(reports)
+        snapshot_markers = [
+            "<title>last30days · OpenClaw vs Hermes</title>",
+            'comparing 2: OpenClaw, Hermes</div>',
+            '<div class="meta">2026-03-30 to 2026-04-29',
+            '<span class="rerun">/last30days OpenClaw vs Hermes</span>',
+        ]
+        for marker in snapshot_markers:
+            self.assertIn(marker, rendered)
+
+
+class HtmlRenderBehaviorTests(unittest.TestCase):
+    def test_prose_label_promotion(self):
+        md = html_render._promote_prose_labels("What I learned:")
+        rendered = html_render._markdown_to_html(md)
+        self.assertIn("<h2>What I learned</h2>", rendered)
+        self.assertNotIn("What I learned:", rendered)
+
+    def test_invitation_strip(self):
+        md = "---\nI'm now an expert on OpenClaw. Some things you could ask:\n\nJust ask."
+        self.assertNotIn("I'm now an expert", html_render._strip_invitation(md))
+
+    def test_evidence_block_strip(self):
+        md = "keep\n<!-- EVIDENCE FOR SYNTHESIS -->\nsecret\n<!-- END EVIDENCE FOR SYNTHESIS -->"
+        stripped = html_render._strip_evidence_block(md)
+        self.assertIn("keep", stripped)
+        self.assertNotIn("EVIDENCE FOR SYNTHESIS", stripped)
+        self.assertNotIn("secret", stripped)
+
+    def test_engine_footer_wrapping_preserves_tree(self):
+        md = (
+            "<!-- PASS-THROUGH FOOTER: emit verbatim. -->\n"
+            "✅ All agents reported back!\n"
+            "├─ 🔵 X: 2 posts\n"
+            "└─ 🌐 Web: 1 result\n"
+            "<!-- END PASS-THROUGH FOOTER -->"
+        )
+        body = html_render._wrap_engine_footer(html_render._markdown_to_html(md))
+        self.assertIn('<div class="engine-footer"><pre>✅ All agents reported back!', body)
+        self.assertIn("├─ 🔵 X: 2 posts", body)
+        self.assertIn("└─ 🌐 Web: 1 result", body)
+
+    def test_colophon_contains_topic_and_rerun_command(self):
+        rendered = html_render.render_html(_report("AI agent frameworks", []))
+        self.assertIn("topic: AI agent frameworks", rendered)
+        self.assertIn("/last30days AI agent frameworks", rendered)
+
+    def test_parseability(self):
+        _assert_parses(self, html_render.render_html(_report("parse me", ["One"])))
+
+    def test_self_containedness(self):
+        rendered = html_render.render_html(_report("self contained", []))
+        self.assertNotIn("<script", rendered.lower())
+        self.assertEqual(1, rendered.count('rel="stylesheet"'))
+
+    def test_markdown_links_convert(self):
+        rendered = html_render._markdown_to_html("[name](https://example.test/path)")
+        self.assertIn('<a href="https://example.test/path">name</a>', rendered)
+
+    def test_no_file_header_h1(self):
+        rendered = html_render.render_html(_report("AI agent frameworks", ["One"]))
+        self.assertNotIn("<h1>last30days v", rendered)
+
+    def test_no_safety_note(self):
+        rendered = html_render.render_html(_report("AI agent frameworks", ["One"]))
+        self.assertNotIn("Safety note", rendered)
+
+    def test_synthesis_md_embedded(self):
+        synthesis = "**Test brief** - body content per [@example](https://example.com)"
+        rendered = html_render.render_html(
+            _report("AI agent frameworks", ["One"]),
+            synthesis_md=synthesis,
+        )
+        self.assertIn("<strong>Test brief</strong> - body content per", rendered)
+        self.assertIn('<a href="https://example.com">@example</a>', rendered)
+        metadata_index = rendered.index('<div class="meta">')
+        synthesis_index = rendered.index("<strong>Test brief</strong>")
+        footer_index = rendered.index('<div class="engine-footer">')
+        self.assertLess(metadata_index, synthesis_index)
+        self.assertLess(synthesis_index, footer_index)
+
+    def test_warnings_excluded_from_html_artifact(self):
+        """Data quality warnings must NOT appear in the shareable HTML.
+
+        Recipients of a shared HTML brief don't have context to act on
+        warnings about pre-flight resolution / engine state. The HTML is the
+        artifact; warnings stay in the engine's stderr logs where the
+        generator (not the recipient) sees them.
+        """
+        report = _report("OpenClaw", ["Containers"])
+        report.artifacts["pre_research_flags_present"] = False
+        report.artifacts["plan_source"] = "deterministic"
+        report.warnings.append("Brave quota exhausted")
+        rendered = html_render.render_html(report)
+        # Warning text variations must all be absent from the artifact.
+        self.assertNotIn("Data quality note", rendered)
+        self.assertNotIn("Brave quota exhausted", rendered)
+        self.assertNotIn("DEGRADED RUN WARNING", rendered)
+        self.assertNotIn("Pre-Research Status", rendered)
+        # No blockquote at all in mock output - just badge + meta + footer + colophon
+        self.assertEqual(0, rendered.count("<blockquote>"))
+
+
+class HtmlCliIntegrationTests(unittest.TestCase):
+    def test_parser_accepts_html_emit(self):
+        args = cli.build_parser().parse_args(["AI agents", "--emit=html"])
+        self.assertEqual("html", args.emit)
+
+    def test_synthesis_file_cli(self):
+        synthesis = "**Test brief** - body content per [@example](https://example.com)"
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", delete=False) as tmp:
+            tmp.write(synthesis)
+            tmp_path = tmp.name
+        try:
+            args = cli.build_parser().parse_args([
+                "OpenClaw",
+                "--mock",
+                "--emit=html",
+                "--synthesis-file",
+                tmp_path,
+            ])
+            rendered = cli.emit_output(
+                _report("OpenClaw", ["Containers"]),
+                args.emit,
+                synthesis_md=cli.read_synthesis_file(args.synthesis_file),
+            )
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+        self.assertIn("<strong>Test brief</strong> - body content per", rendered)
+
+    def test_save_output_uses_raw_html_extension_and_suffix(self):
+        report = _report("AI Agent Frameworks", [])
+        with self.subTest("plain"):
+            path = cli.compute_save_path_display("/tmp", report.topic, "", "html")
+            self.assertTrue(path.endswith("/ai-agent-frameworks-raw-html.html"))
+        with self.subTest("suffix"):
+            path = cli.compute_save_path_display("/tmp", report.topic, "v3", "html")
+            self.assertTrue(path.endswith("/ai-agent-frameworks-raw-html-v3.html"))
+
+
+if __name__ == "__main__":
+    unittest.main()