/render-html

name: render-html
description: "Render an ARIS Markdown / JSON artifact (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN, research-wiki state, etc.) into a single-file HTML view designed for human reading. Academic template outputs are gated by a fresh cross-model Codex review for render fidelity + safety (the ARIS invariant). Use when the user says \"渲染 HTML\", \"出一份 HTML 报告\", \"render html\", \"make this readable\", \"export to html\", or wants a polished web-rendered view of a Markdown artifact. Markdown/JSON stays the canonical source; HTML is a generated, reviewed view."
argument-hint: <input.md> [--template academic|dashboard] [--out <path>] [--title ...] [--state <state.json>] [--json <sidecar.json>] [--offline] [--review|--no-review]
allowed-tools: Bash(*), Read, Write, mcp__codex__codex

/render-html: Markdown → single-file HTML for human reading

> **Markdown is for writers. HTML is for readers.** ARIS workflow nodes write Markdown (canonical, audit-trail-friendly, machine-parseable). `/render-html` turns *selected* artifacts into a polished single-file HTML view for the human who actually has to read them. The Markdown stays the source of truth.

When to use this skill

**Use `/render-html` for** ARIS artifacts that have a real human reader:

| Artifact | Why HTML helps | Template | |----------|----------------|----------| | `idea-stage/IDEA_REPORT.md` | Ranked ideas + pilot signal + scores feel like a decision dashboard, not a flat list | `academic` | | `review-stage/AUTO_REVIEW.md` (+ `REVIEW_STATE.json`) | Round-by-round score progression + weakness status; pass `--state` to embed the JSON | `academic` | | `paper/KILL_ARGUMENT.md` (+ `KILL_ARGUMENT.json`) | Per-point attack/defense with `<details>` Q&A cards + red/yellow/green callouts | `academic` | | `research-wiki/SUMMARY.md` (or `research-wiki/index.md`) | Cross-entity cockpit: papers / ideas / experiments / claims at a glance | `dashboard` | | `PAPER_PLAN.md` (optional) | Claims-evidence matrix renders better as a polished table than raw MD | `academic` | | `RESUBMIT_REPORT.{md,json}` (optional) | 7-state failure-mode ledger | `academic` or `dashboard` |

**Do NOT use** for:

• LaTeX paper output — the final reader-facing artifact is PDF, not HTML.
• `SKILL.md` files — those are internal LLM-facing protocol.
• `.aris/traces/*` review traces — forensic debug, not human display.
• Every Markdown file in your project — only artifacts that benefit from sticky TOC, callouts, math, or score progressions.

Core invariants

• **MD / JSON is canonical, HTML is generated view.** Edit the source, then re-render. Do not hand-edit the HTML.
• **Cross-model review at the artifact boundary** (ARIS invariant). Academic-template HTML — used for the artifacts humans actually read (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN) — is reviewed by a fresh cross-family Codex thread before being claimed as a finished view. Dashboard-template HTML (cockpit / debug views) skips review by default but accepts `--review` to force it. See § *HTML Review Gate* below.
• **Drift detection.** Every rendered HTML embeds the source path, SHA256, and generation timestamp in `<meta>` tags AND in the visible page header. If the HTML and source diverge, the meta tells you which version of the source produced it.
• **Single-file output.** No build system, no separate CSS, no `node_modules`. Just one `.html`.
• **CDN-friendly default, `--offline` fallback.** MathJax 3 and highlight.js load from `cdn.jsdelivr.net` by default. Pass `--offline` to skip both — math will appear as raw `$x$`, code blocks won't get syntax highlighting, but everything stays readable.
• **Pure stdlib helper.** `render_html.py` uses only `re`, `html`, `hashlib`, `json`, `datetime`, `pathlib`, `argparse`, `sys`. No pip install required.
• **Defense-in-depth XSS sanitization.** The helper strips `<script>`/`<style>`/`<iframe>`/`<object>`/`<embed>`/`<form>`/`<input>`/`<button>`/`<link>`/`<meta>`/`<base>` tags, all `on*` event-handler attributes (`onclick`, `onload`, …), and rewrites `javascript:`/`vbscript:`/`data:` href/src/action schemes to `#blocked-unsafe-url:`. ARIS workflow artifacts should not contain these in the first place, but the sanitizer is the safety net in case an LLM hallucinates one. Markdown text content is HTML-escaped separately and never reaches the sanitizer.

Tool Location

In **this repo (ARIS-in-AI-Offer)** the renderer lives at `tools/render_html.py`, with its templates at `tools/templates/{academic,dashboard}.html`. It is pure stdlib — no install step, no `scripts/` subdirectory. Resolve `$RENDER_HTML` from the repo root:

# Run from the ARIS-in-AI-Offer repo root (where tools/ lives).
RENDER_HTML="tools/render_html.py"
[ -f "$RENDER_HTML" ] || RENDER_HTML="$(git rev-parse --show-toplevel 2>/dev/null)/tools/render_html.py"
[ -f "$RENDER_HTML" ] || {
  echo "ERROR: tools/render_html.py not found — run from the ARIS-in-AI-Offer repo root." >&2
  exit 1
}

> **Vendoring note.** If you copy this skill into a self-contained `skills/render-html/scripts/` layout (the upstream ARIS convention), move `render_html.py` + `templates/` there and repoint `$RENDER_HTML` accordingly. In *this* repo the single source of truth is `tools/` — do not introduce a second copy.

Invocation

# Default: academic template, output to <input>.html alongside source
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md

# Dashboard template for cockpit-style views
python3 "$RENDER_HTML" research-wiki/SUMMARY.md --template dashboard

# Custom output path + title + eyebrow
python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \
  --out review-stage/AUTO_REVIEW.html \
  --title "Auto Review — overnight run" \
  --eyebrow "Workflow 2"

# Embed sidecar state JSON (rendered as a folded <details> JSON block at end)
python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \
  --state review-stage/REVIEW_STATE.json

# Embed sidecar JSON (e.g., for KILL_ARGUMENT.md