/render-html: Markdown → single-file HTML for human reading
Before each reviewer slot, follow Selectable Reviewers:
resolve invocation → .aris/reviewer.json → Claude Code default (Codex MCP)
with reviewer_route.py through the canonical helper resolver, preserving this
slot's tier, fresh contexts, source/image inputs and deterministic gates.
Codex examples/pins below apply only to backend=codex; other routes use their
own first-call/reply contract. Save the route and actual returned identity;
unavailable selections are REVIEW_UNAVAILABLE. Classify acceptance from actual
families/completion/scope. Forward invocation reviewer/model/effort overrides
to reviewer-bearing children. Generation workers are unchanged.
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 the selected reviewer in a fresh context; classify its family from actual identities 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
Arch C self-contained: the canonical implementation lives at skills/render-html/scripts/render_html.py (this SKILL's own scripts/ subdirectory), together with its templates at skills/render-html/scripts/templates/{academic,dashboard}.html. The helper is new — no legacy tools/ shim exists.
Resolve $RENDER_HTML with the hybrid chain (Layer 0 prefers the self-contained location for the owning SKILL; Layers 1-3 are the shared-runtime chain documented in shared-references/integration-contract.md §2, Policy A — skill-local gate):
# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
RENDER_HTML=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/render_html.py" ]; then
RENDER_HTML="$CLAUDE_SKILL_DIR/scripts/render_html.py"
fi
# Layers 1-3: shared-runtime chain (non-CC hosts + manual installs).
if [ -z "$RENDER_HTML" ]; then
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
RENDER_HTML=".aris/skills/render-html/scripts/render_html.py"
[ -f "$RENDER_HTML" ] || RENDER_HTML="skills/render-html/scripts/render_html.py"
[ -f "$RENDER_HTML" ] || { [ -n "${ARIS_REPO:-}" ] && RENDER_HTML="$ARIS_REPO/skills/render-html/scripts/render_html.py"; }
[ -f "$RENDER_HTML" ] || RENDER_HTML=""
fi
[ -z "$RENDER_HTML" ] && {
echo "ERROR: render_html.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-3: .aris/skills/render-html/scripts/, skills/render-html/scripts/, \$ARIS_REPO/skills/render-html/scripts/)." >&2
echo " /render-html cannot produce HTML output. Fix: rerun bash tools/install_aris.sh, or copy from \$ARIS_REPO/skills/render-html/scripts/." >&2
exit 1
}
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 + KILL_ARGUMENT.json)
python3 "$RENDER_HTML" paper/KILL_ARGUMENT.md \
--json paper/KILL_ARGUMENT.json \
--title "Kill Argument — adversarial review"
# Offline (no CDN; math + code render as plain text)
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md --offline
# JSON-only input (wrapped in a <pre><code class="language-json"> block)
python3 "$RENDER_HTML" review-stage/REVIEW_STATE.json --template dashboard
# Language attr (default zh-CN; set for English-primary artifacts)
python3 "$RENDER_HTML" docs/SKILLS_CATALOG.md --lang en
# Skip review (academic template otherwise reviews by default)
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md
# … then the skill skips the mcp__codex__codex review step if --no-review
# was on the command line. Pass --review to a dashboard render to force it.
The --review / --no-review flags are parsed by the SKILL orchestrator
(Claude Code), not by render_html.py. The helper itself stays pure
stdlib and never calls MCP. See § HTML Review Gate below for the
exact resolution and prompt.
Workflow
Step 1: Identify the artifact
From $ARGUMENTS, determine what to render. Common patterns:
- "render IDEA_REPORT" →
idea-stage/IDEA_REPORT.md, academic template
- "make AUTO_REVIEW readable" →
review-stage/AUTO_REVIEW.md + --state review-stage/REVIEW_STATE.json
- "show the kill argument as HTML" →
paper/KILL_ARGUMENT.md + --json paper/KILL_ARGUMENT.json
- "research-wiki dashboard" → look for
research-wiki/SUMMARY.md or generate from raw entity counts (Phase 2 work; for Phase 1 just render SUMMARY.md if present, else fall back to listing top-level wiki structure)
Step 2: Pick template
academic (default): linear long-form. Sticky TOC sidebar + serif body + callouts + tables + math + Q&A <details>. Use for IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN.
dashboard: grid layout, smaller font, denser metrics cards, no TOC sidebar. Use for research-wiki cockpit, RESUBMIT_REPORT, multi-project overviews.
Step 3: Run the helper
Use the resolver above to get $RENDER_HTML, then invoke. The script writes the HTML alongside the source by default (or wherever --out says) and prints a one-line confirmation including the source SHA256 prefix.
Step 4: HTML Review Gate (cross-model)
Decide whether to run review. Per ARIS invariant "executor must not judge its own output", the academic-template HTML is reviewed by the selected reviewer in a fresh context; classify its family from actual identities before being claimed as a delivered view. Resolution:
should_review = explicit --review present
or (template == "academic" and --no-review NOT present)
So:
--template academic (default) → review by default. Skip with --no-review.
--template dashboard → no review by default. Force with --review.
- Phase 2 workflow auto-emit (activated 2026-05) selects per-skill via the RENDER_HTML hooks documented below — interim views default to
--no-review, final / audit-class deliverables default to full gate.
If should_review is true, fire a fresh mcp__codex__codex thread (NEVER codex-reply; pin model: gpt-6-astra + config: {"model_reasoning_effort": "xhigh"} per ../shared-references/reviewer-routing.md) with the prompt below. The reviewer reads the source MD + generated HTML directly; it does not see this skill's intermediate state.
Scope of review (narrow on purpose). The HTML reviewer audits render fidelity / safety / structure only — not claim truthfulness. Claim audit belongs upstream (/paper-claim-audit, /research-review, /result-to-claim). Specifically the reviewer checks:
- Information fidelity — every section, claim, table, code block, list, math snippet, sidecar payload is present in the HTML (no silent drop)
- Structural integrity — heading hierarchy / nested lists / table cells / code fences /
<details> blocks / math delimiters survive parsing
- Callout routing —
> 🚨 … got .callout-bad, > 💡 … got .callout-info, etc.
- Safety / escaping — no raw
<script> / onclick= / javascript: / unreplaced placeholders / template-leak survives
- Expected-difference allowance — frontmatter strip, generated header/footer/meta, TOC insert, sanitized unsafe HTML are all expected, not flagged
Codex prompt (mandatory shape). Send this as a fresh thread (mcp__codex__codex, NOT codex-reply):
You are an independent ARIS HTML render auditor. This is a fresh review thread.
Read these files directly:
- Source artifact: <ABS path to source.md or source.json>
- Generated HTML: <ABS path to out.html>
- Optional sidecars: <state.json>, <kill_argument.json> (if any)
Task: Audit whether the generated HTML is a faithful, safe, structurally
usable view of the source artifact. Do NOT judge whether the research
claims are true. Judge only rendering fidelity.
Checks:
1. Information fidelity — sections / claims / tables / code blocks /
lists / math / sidecars not silently dropped or materially altered.
2. Structural integrity — heading hierarchy, tables, nested lists,
code fences, details/summary, math delimiters preserved.
3. Callout routing — warning/critical/good/info blockquotes map to
appropriate CSS classes when present.
4. Safety/escaping — no unexpected raw script/style/iframe/form/
event-handler/javascript/data URL survives from source.
5. Placeholder/template leakage — no unreplaced {{PLACEHOLDER}} or
parser private placeholder character appears.
6. Expected differences — frontmatter strip, generated header/footer/
meta, TOC insertion, sanitized unsafe HTML are EXPECTED and not a
defect.
Return STRICT JSON first, then a short prose note:
{
"verdict": "PASS|WARN|FAIL|ERROR",
"checks": {
"source_hash_match": "pass|warn|fail|unknown",
"information_fidelity": "pass|warn|fail",
"structure": "pass|warn|fail",
"math_code_tables": "pass|warn|fail",
"callouts": "pass|warn|fail|not_applicable",
"safety_escaping": "pass|warn|fail",
"placeholder_leak": "pass|warn|fail"
},
"blocking_issues": [
{"severity": "fail",
"source_location": "L<n>...",
"html_location": "<selector or near-text>",
"issue": "...",
"suggested_fix": "..."}
],
"warnings": [
{"severity": "warn", "issue": "...", "suggested_fix": "..."}
],
"summary": "one paragraph"
}
Verdict rules:
- PASS: no material fidelity/safety issue.
- WARN: readable output with minor unsupported-Markdown or cosmetic
degradation only.
- FAIL: missing/altered meaningful content, broken tables/math/code/
callouts that change interpretation, unsafe executable HTML, source
hash mismatch, or placeholder leakage.
- ERROR: files could not be read or audit could not complete.
Save outputs:
- Write the JSON verdict to
<out_path>.review.json (sibling to the HTML).
- Save the raw codex trace to
.aris/traces/render-html/<YYYY-MM-DD>_run<NN>/review.{txt,json} per shared-references/review-tracing.md.
- Print a one-line summary to the user:
verdict, N blocking, N warnings, trace: <path>.
If verdict == FAIL: the HTML is NOT a delivered review-passed view. Tell the user the blocking issues, point them at the source (fix MD or template, not the HTML), and re-render. Do not silently overwrite or mark as complete.
If verdict == WARN: deliver the HTML but surface the warning list. User decides whether to fix or accept.
If the selected reviewer route is unavailable: emit verdict: REVIEW_UNAVAILABLE to the sidecar, do not fabricate PASS, and tell the user the HTML was generated but not independently reviewed. The user can manually invoke /research-review on the source MD or re-run when the selected reviewer is available.
Step 5: (Optional) Verify in browser
open <out.html> on macOS, xdg-open on Linux, start on Windows. Math + code highlighting need internet (CDN); offline mode degrades gracefully to readable text.
What the helper supports
Markdown subset (chosen to match what ARIS workflows actually emit):
- Headings
#/##/###/#### with auto-generated IDs for TOC
- Paragraphs, bold
**x**, italic *x* / _x_, inline code `x`, strikethrough ~~x~~, links [t](url), images 
- Unordered/ordered lists with 2-space nested indentation
- Code blocks with optional language (
```python) — gets <pre><code class="language-python"> for highlight.js
- ASCII-art code blocks (heuristic: many box-drawing chars) →
<pre class="diagram"> with a distinct cream-yellow background
- Tables with
:--- / :---: / ---: alignment
- Blockquotes
> ... — emoji-prefix detection routes to callout variants:
⚠️ → .callout-warn (Warning)
💡 / 📝 → .callout-info (Tip / Note)
✅ / 🔒 → .callout-good (OK / Guarantee)
❌ / 🚨 → .callout-bad (Blocked / Critical)
- HTML passthrough for
<details>, <summary>, <div>, <figure>, <table>, <section>, etc. (block-level) — used for the existing Round-1/2/3 fix details in KILL_ARGUMENT.md
- LaTeX math: inline
$x$ and display $$x$$ pass through verbatim to MathJax
What the helper does NOT support (intentional simplifications):
- Footnotes (
[^1])
- Definition lists
- Reference-style links
[label][ref]
- Setext-style headings (
=== / --- underline form — ARIS doesn't emit these)
Frontmatter (--- ... ---) at the very top of the file is stripped before rendering (SKILL.md frontmatter style); the body that follows is what gets converted.
Two-phase integration plan (Phase 1 was this skill; Phase 2 is workflow hooks, activated 2026-05)
Phase 1 (originally shipped): Opt-in only. Users explicitly called /render-html <artifact.md> after a workflow completes.
Phase 2 (activated 2026-05): Eight key skills now auto-emit HTML at workflow termination, each guarded by a RENDER_HTML = true constant that the user can flip off per skill (or pass — render html: false at invocation).
Cost-tiered review gate (per artifact type):
| Skill |
Artifact |
Review tier |
Why |
/idea-discovery |
idea-stage/IDEA_REPORT.md |
--no-review |
Interim; source went through novelty + cross-model review already |
/auto-review-loop |
review-stage/AUTO_REVIEW.md |
--no-review |
Per-round log; the loop itself is the cross-model review |
/research-pipeline |
NARRATIVE_REPORT.md |
--no-review |
Internal Stage 5 handoff to /paper-writing; not reviewer-facing — upstream Stage 4 auto-review-loop already gated the claims |
/kill-argument |
<paper-dir>/KILL_ARGUMENT.md |
full gate |
Audit-class artifact; matches skill's own cross-model invariant |
/paper-claim-audit |
paper/PAPER_CLAIM_AUDIT.md |
full gate |
Audit-class artifact |
/citation-audit |
paper/CITATION_AUDIT.md |
full gate |
Audit-class artifact |
/proof-checker |
PROOF_AUDIT.md |
full gate |
Audit-class artifact |
/rebuttal |
REBUTTAL_DRAFT_rich.md |
full gate |
Pre-submission deliverable |
/paper-writing |
(no auto-HTML) |
n/a |
The final reader artifact is PDF |
/research-wiki |
research-wiki/index.html dashboard |
future |
Phase 2.1 — dashboard template work, not in this round |
--no-review for interim reports is intentional: the source MD has already been reviewed by the producing skill's own cross-model gate, and the HTML render only converts structure — it doesn't add new claims. Full review at every checkpoint would multiply Codex calls per pipeline by 4-6×.
To disable HTML output for a specific skill: set RENDER_HTML = false in the skill's constants block or pass — render html: false. To globally disable: skip with environment variable ARIS_RENDER_HTML=0 (planned, not yet implemented; flag per skill in the meantime).
Customizing the templates
The two templates live at skills/render-html/scripts/templates/{academic,dashboard}.html. Each is a single self-contained HTML file with inline CSS using {{PLACEHOLDER}} substitution. To customize:
- Copy one of the templates to a new name, e.g.,
my_brand.html.
- Edit the CSS variables in
:root { ... } to change colors, the font stack, or layout dimensions.
- Add the template name to the
--template choices in render_html.py argparse.
- Re-run
/render-html <input> --template my_brand.
The default templates are derived from the user's own academic-newspaper tutorial style (Source Serif Pro + Songti SC, 3-color palette, sticky TOC, low-flash). Stay close to that idiom for ARIS artifacts unless you have a specific reason to break the visual language.
External alternatives (for richer surfaces)
For deck / poster / Xiaohongshu card / tweet card / data report style outputs, point users to html-anything (Apache-2.0, 3000⭐ at time of writing). It ships 75 SKILL.md templates across 9 surfaces and detects 8 coding-agent CLIs (including Claude Code, Codex, Copilot). ARIS does not depend on it — /render-html covers ARIS-native artifacts; html-anything is the recommended path for richer publishing surfaces.
Key rules
- Do not auto-render every Markdown file. Only artifacts on the whitelist above. File proliferation is the main anti-pattern.
- Do not hand-edit the generated HTML. Edit the source, then re-render. The embedded SHA256 in the HTML meta tells you if the source has changed since render.
- academic-template HTML is a reviewed artifact by default, not raw output. Cross-model Codex review (fresh thread) gates the academic deliverables — the same way
/proof-checker, /paper-claim-audit, /citation-audit, /kill-argument gate their respective products. --no-review is appropriate for interim auto-emits (e.g., idea-stage/IDEA_REPORT.html, per-round review-stage/AUTO_REVIEW.html) where the source MD has already passed an upstream cross-model gate — the HTML render is then a structural conversion, not a new claim audit. For shipped / reviewer-facing / audit-class outputs, keep the full gate.
- The reviewer audits rendering, not research. Claim truthfulness is owned upstream by
/paper-claim-audit, /result-to-claim, /research-review. The HTML reviewer asks: "did the renderer faithfully + safely convert this source?" — nothing more.
- CDN dependency is opt-out, not opt-in. Most users have internet;
--offline is for air-gapped runs / archival.
- The default style is academic-newspaper, not marketing-flashy. Match the existing ARIS tonal voice. If you want decks/posters/social cards, point users to html-anything.
- Pure stdlib only. Adding a
pip install dependency to render_html.py requires an explicit decision — the helper currently has none. MCP calls live in the skill orchestrator, never in the helper script.
1---2name: render-html-33description: "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. 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."4argument-hint: "<input.md> [--template academic|dashboard] [--out <path>] [--title ...] [--state <state.json>] [--json <sidecar.json>] [--offline] [--review|--no-review]"5allowed-tools: Bash(*), Read, Write, mcp__codex__codex, mcp__antigravity__antigravity, mcp__antigravity__antigravity-reply, mcp__grok__grok, mcp__grok__grok-reply, mcp__claude-review__review, mcp__claude-review__review_reply, mcp__claude-review__review_start, mcp__claude-review__review_reply_start, mcp__claude-review__review_status6metadata:7 source: https://skillmd.com/skills/wanshuiyin/render-html-38---910# /render-html: Markdown → single-file HTML for human reading1112> **Before each reviewer slot**, follow [Selectable Reviewers](../shared-references/reviewer-backends.md):13> resolve invocation → `.aris/reviewer.json` → Claude Code default (Codex MCP)14> with `reviewer_route.py` through the canonical helper resolver, preserving this15> slot's tier, fresh contexts, source/image inputs and deterministic gates.16> Codex examples/pins below apply only to `backend=codex`; other routes use their17> own first-call/reply contract. Save the route and actual returned identity;18> unavailable selections are `REVIEW_UNAVAILABLE`. Classify acceptance from actual19> families/completion/scope. Forward invocation reviewer/model/effort overrides20> to reviewer-bearing children. Generation workers are unchanged.212223> **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.2425## When to use this skill2627**Use `/render-html` for** ARIS artifacts that have a real human reader:2829| Artifact | Why HTML helps | Template |30|----------|----------------|----------|31| `idea-stage/IDEA_REPORT.md` | Ranked ideas + pilot signal + scores feel like a decision dashboard, not a flat list | `academic` |32| `review-stage/AUTO_REVIEW.md` (+ `REVIEW_STATE.json`) | Round-by-round score progression + weakness status; pass `--state` to embed the JSON | `academic` |33| `paper/KILL_ARGUMENT.md` (+ `KILL_ARGUMENT.json`) | Per-point attack/defense with `<details>` Q&A cards + red/yellow/green callouts | `academic` |34| `research-wiki/SUMMARY.md` (or `research-wiki/index.md`) | Cross-entity cockpit: papers / ideas / experiments / claims at a glance | `dashboard` |35| `PAPER_PLAN.md` (optional) | Claims-evidence matrix renders better as a polished table than raw MD | `academic` |36| `RESUBMIT_REPORT.{md,json}` (optional) | 7-state failure-mode ledger | `academic` or `dashboard` |3738**Do NOT use** for:39- LaTeX paper output — the final reader-facing artifact is PDF, not HTML.40- `SKILL.md` files — those are internal LLM-facing protocol.41- `.aris/traces/*` review traces — forensic debug, not human display.42- Every Markdown file in your project — only artifacts that benefit from sticky TOC, callouts, math, or score progressions.4344## Core invariants4546- **MD / JSON is canonical, HTML is generated view.** Edit the source, then re-render. Do not hand-edit the HTML.47- **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 the selected reviewer in a fresh context; classify its family from actual identities 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.48- **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.49- **Single-file output.** No build system, no separate CSS, no `node_modules`. Just one `.html`.50- **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.51- **Pure stdlib helper.** `render_html.py` uses only `re`, `html`, `hashlib`, `json`, `datetime`, `pathlib`, `argparse`, `sys`. No pip install required.52- **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.5354## Tool Location5556Arch C self-contained: the canonical implementation lives at `skills/render-html/scripts/render_html.py` (this SKILL's own `scripts/` subdirectory), together with its templates at `skills/render-html/scripts/templates/{academic,dashboard}.html`. The helper is new — no legacy `tools/` shim exists.5758Resolve `$RENDER_HTML` with the hybrid chain (Layer 0 prefers the self-contained location for the owning SKILL; Layers 1-3 are the shared-runtime chain documented in [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2, **Policy A — skill-local gate**):5960```bash61# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).62RENDER_HTML=""63if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/render_html.py" ]; then64 RENDER_HTML="$CLAUDE_SKILL_DIR/scripts/render_html.py"65fi66# Layers 1-3: shared-runtime chain (non-CC hosts + manual installs).67if [ -z "$RENDER_HTML" ]; then68 cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 169 if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then70 ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true71 fi72 RENDER_HTML=".aris/skills/render-html/scripts/render_html.py"73 [ -f "$RENDER_HTML" ] || RENDER_HTML="skills/render-html/scripts/render_html.py"74 [ -f "$RENDER_HTML" ] || { [ -n "${ARIS_REPO:-}" ] && RENDER_HTML="$ARIS_REPO/skills/render-html/scripts/render_html.py"; }75 [ -f "$RENDER_HTML" ] || RENDER_HTML=""76fi77[ -z "$RENDER_HTML" ] && {78 echo "ERROR: render_html.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-3: .aris/skills/render-html/scripts/, skills/render-html/scripts/, \$ARIS_REPO/skills/render-html/scripts/)." >&279 echo " /render-html cannot produce HTML output. Fix: rerun bash tools/install_aris.sh, or copy from \$ARIS_REPO/skills/render-html/scripts/." >&280 exit 181}82```8384## Invocation8586```bash87# Default: academic template, output to <input>.html alongside source88python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md8990# Dashboard template for cockpit-style views91python3 "$RENDER_HTML" research-wiki/SUMMARY.md --template dashboard9293# Custom output path + title + eyebrow94python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \95 --out review-stage/AUTO_REVIEW.html \96 --title "Auto Review — overnight run" \97 --eyebrow "Workflow 2"9899# Embed sidecar state JSON (rendered as a folded <details> JSON block at end)100python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \101 --state review-stage/REVIEW_STATE.json102103# Embed sidecar JSON (e.g., for KILL_ARGUMENT.md + KILL_ARGUMENT.json)104python3 "$RENDER_HTML" paper/KILL_ARGUMENT.md \105 --json paper/KILL_ARGUMENT.json \106 --title "Kill Argument — adversarial review"107108# Offline (no CDN; math + code render as plain text)109python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md --offline110111# JSON-only input (wrapped in a <pre><code class="language-json"> block)112python3 "$RENDER_HTML" review-stage/REVIEW_STATE.json --template dashboard113114# Language attr (default zh-CN; set for English-primary artifacts)115python3 "$RENDER_HTML" docs/SKILLS_CATALOG.md --lang en116117# Skip review (academic template otherwise reviews by default)118python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md119# … then the skill skips the mcp__codex__codex review step if --no-review120# was on the command line. Pass --review to a dashboard render to force it.121```122123The `--review` / `--no-review` flags are parsed by the SKILL orchestrator124(Claude Code), not by `render_html.py`. The helper itself stays pure125stdlib and never calls MCP. See § *HTML Review Gate* below for the126exact resolution and prompt.127128## Workflow129130### Step 1: Identify the artifact131132From `$ARGUMENTS`, determine what to render. Common patterns:133134- "render IDEA_REPORT" → `idea-stage/IDEA_REPORT.md`, academic template135- "make AUTO_REVIEW readable" → `review-stage/AUTO_REVIEW.md` + `--state review-stage/REVIEW_STATE.json`136- "show the kill argument as HTML" → `paper/KILL_ARGUMENT.md` + `--json paper/KILL_ARGUMENT.json`137- "research-wiki dashboard" → look for `research-wiki/SUMMARY.md` or generate from raw entity counts (Phase 2 work; for Phase 1 just render `SUMMARY.md` if present, else fall back to listing top-level wiki structure)138139### Step 2: Pick template140141- `academic` (default): linear long-form. Sticky TOC sidebar + serif body + callouts + tables + math + Q&A `<details>`. Use for IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN.142- `dashboard`: grid layout, smaller font, denser metrics cards, no TOC sidebar. Use for research-wiki cockpit, RESUBMIT_REPORT, multi-project overviews.143144### Step 3: Run the helper145146Use the resolver above to get `$RENDER_HTML`, then invoke. The script writes the HTML alongside the source by default (or wherever `--out` says) and prints a one-line confirmation including the source SHA256 prefix.147148### Step 4: HTML Review Gate (cross-model)149150**Decide whether to run review.** Per ARIS invariant "executor must not judge its own output", the academic-template HTML is reviewed by the selected reviewer in a fresh context; classify its family from actual identities before being claimed as a delivered view. Resolution:151152```153should_review = explicit --review present154 or (template == "academic" and --no-review NOT present)155```156157So:158159- `--template academic` (default) → **review by default**. Skip with `--no-review`.160- `--template dashboard` → no review by default. Force with `--review`.161- Phase 2 workflow auto-emit (activated 2026-05) selects per-skill via the RENDER_HTML hooks documented below — interim views default to `--no-review`, final / audit-class deliverables default to full gate.162163**If `should_review` is true**, fire a fresh `mcp__codex__codex` thread (NEVER `codex-reply`; pin `model: gpt-6-astra` + `config: {"model_reasoning_effort": "xhigh"}` per `../shared-references/reviewer-routing.md`) with the prompt below. The reviewer reads the source MD + generated HTML directly; it does **not** see this skill's intermediate state.164165**Scope of review (narrow on purpose).** The HTML reviewer audits **render fidelity / safety / structure only** — not claim truthfulness. Claim audit belongs upstream (`/paper-claim-audit`, `/research-review`, `/result-to-claim`). Specifically the reviewer checks:1661671. **Information fidelity** — every section, claim, table, code block, list, math snippet, sidecar payload is present in the HTML (no silent drop)1682. **Structural integrity** — heading hierarchy / nested lists / table cells / code fences / `<details>` blocks / math delimiters survive parsing1693. **Callout routing** — `> 🚨 …` got `.callout-bad`, `> 💡 …` got `.callout-info`, etc.1704. **Safety / escaping** — no raw `<script>` / `onclick=` / `javascript:` / unreplaced placeholders / template-leak survives1715. **Expected-difference allowance** — frontmatter strip, generated header/footer/meta, TOC insert, sanitized unsafe HTML are all expected, not flagged172173**Codex prompt (mandatory shape).** Send this as a fresh thread (`mcp__codex__codex`, NOT `codex-reply`):174175```176You are an independent ARIS HTML render auditor. This is a fresh review thread.177178Read these files directly:179- Source artifact: <ABS path to source.md or source.json>180- Generated HTML: <ABS path to out.html>181- Optional sidecars: <state.json>, <kill_argument.json> (if any)182183Task: Audit whether the generated HTML is a faithful, safe, structurally184usable view of the source artifact. Do NOT judge whether the research185claims are true. Judge only rendering fidelity.186187Checks:1881. Information fidelity — sections / claims / tables / code blocks /189 lists / math / sidecars not silently dropped or materially altered.1902. Structural integrity — heading hierarchy, tables, nested lists,191 code fences, details/summary, math delimiters preserved.1923. Callout routing — warning/critical/good/info blockquotes map to193 appropriate CSS classes when present.1944. Safety/escaping — no unexpected raw script/style/iframe/form/195 event-handler/javascript/data URL survives from source.1965. Placeholder/template leakage — no unreplaced {{PLACEHOLDER}} or197 parser private placeholder character appears.1986. Expected differences — frontmatter strip, generated header/footer/199 meta, TOC insertion, sanitized unsafe HTML are EXPECTED and not a200 defect.201202Return STRICT JSON first, then a short prose note:203204{205 "verdict": "PASS|WARN|FAIL|ERROR",206 "checks": {207 "source_hash_match": "pass|warn|fail|unknown",208 "information_fidelity": "pass|warn|fail",209 "structure": "pass|warn|fail",210 "math_code_tables": "pass|warn|fail",211 "callouts": "pass|warn|fail|not_applicable",212 "safety_escaping": "pass|warn|fail",213 "placeholder_leak": "pass|warn|fail"214 },215 "blocking_issues": [216 {"severity": "fail",217 "source_location": "L<n>...",218 "html_location": "<selector or near-text>",219 "issue": "...",220 "suggested_fix": "..."}221 ],222 "warnings": [223 {"severity": "warn", "issue": "...", "suggested_fix": "..."}224 ],225 "summary": "one paragraph"226}227228Verdict rules:229- PASS: no material fidelity/safety issue.230- WARN: readable output with minor unsupported-Markdown or cosmetic231 degradation only.232- FAIL: missing/altered meaningful content, broken tables/math/code/233 callouts that change interpretation, unsafe executable HTML, source234 hash mismatch, or placeholder leakage.235- ERROR: files could not be read or audit could not complete.236```237238**Save outputs**:2392401. Write the JSON verdict to `<out_path>.review.json` (sibling to the HTML).2412. Save the raw codex trace to `.aris/traces/render-html/<YYYY-MM-DD>_run<NN>/review.{txt,json}` per `shared-references/review-tracing.md`.2423. Print a one-line summary to the user: `verdict, N blocking, N warnings, trace: <path>`.243244**If `verdict == FAIL`**: the HTML is **NOT** a delivered review-passed view. Tell the user the blocking issues, point them at the source (fix MD or template, not the HTML), and re-render. Do not silently overwrite or mark as complete.245246**If `verdict == WARN`**: deliver the HTML but surface the warning list. User decides whether to fix or accept.247248**If the selected reviewer route is unavailable**: emit `verdict: REVIEW_UNAVAILABLE` to the sidecar, do not fabricate `PASS`, and tell the user the HTML was generated but **not** independently reviewed. The user can manually invoke `/research-review` on the source MD or re-run when the selected reviewer is available.249250### Step 5: (Optional) Verify in browser251252`open <out.html>` on macOS, `xdg-open` on Linux, `start` on Windows. Math + code highlighting need internet (CDN); offline mode degrades gracefully to readable text.253254## What the helper supports255256**Markdown subset** (chosen to match what ARIS workflows actually emit):257258- Headings `#`/`##`/`###`/`####` with auto-generated IDs for TOC259- Paragraphs, bold `**x**`, italic `*x*` / `_x_`, inline code `` `x` ``, strikethrough `~~x~~`, links `[t](url)`, images ``260- Unordered/ordered lists with 2-space nested indentation261- Code blocks with optional language (` ```python `) — gets `<pre><code class="language-python">` for highlight.js262- ASCII-art code blocks (heuristic: many box-drawing chars) → `<pre class="diagram">` with a distinct cream-yellow background263- Tables with `:---` / `:---:` / `---:` alignment264- Blockquotes `> ...` — emoji-prefix detection routes to callout variants:265 - `⚠️` → `.callout-warn` (Warning)266 - `💡` / `📝` → `.callout-info` (Tip / Note)267 - `✅` / `🔒` → `.callout-good` (OK / Guarantee)268 - `❌` / `🚨` → `.callout-bad` (Blocked / Critical)269- HTML passthrough for `<details>`, `<summary>`, `<div>`, `<figure>`, `<table>`, `<section>`, etc. (block-level) — used for the existing Round-1/2/3 fix details in `KILL_ARGUMENT.md`270- LaTeX math: inline `$x$` and display `$$x$$` pass through verbatim to MathJax271272**What the helper does NOT support** (intentional simplifications):273274- Footnotes (`[^1]`)275- Definition lists276- Reference-style links `[label][ref]`277- Setext-style headings (`===` / `---` underline form — ARIS doesn't emit these)278279**Frontmatter (`--- ... ---`) at the very top of the file is stripped before rendering** (SKILL.md frontmatter style); the body that follows is what gets converted.280281## Two-phase integration plan (Phase 1 was this skill; Phase 2 is workflow hooks, **activated 2026-05**)282283**Phase 1 (originally shipped):** Opt-in only. Users explicitly called `/render-html <artifact.md>` after a workflow completes.284285**Phase 2 (activated 2026-05):** Eight key skills now auto-emit HTML at workflow termination, each guarded by a `RENDER_HTML = true` constant that the user can flip off per skill (or pass `— render html: false` at invocation).286287**Cost-tiered review gate** (per artifact type):288289| Skill | Artifact | Review tier | Why |290|---|---|---|---|291| `/idea-discovery` | `idea-stage/IDEA_REPORT.md` | `--no-review` | Interim; source went through novelty + cross-model review already |292| `/auto-review-loop` | `review-stage/AUTO_REVIEW.md` | `--no-review` | Per-round log; the loop itself is the cross-model review |293| `/research-pipeline` | `NARRATIVE_REPORT.md` | `--no-review` | Internal Stage 5 handoff to `/paper-writing`; not reviewer-facing — upstream Stage 4 auto-review-loop already gated the claims |294| `/kill-argument` | `<paper-dir>/KILL_ARGUMENT.md` | full gate | Audit-class artifact; matches skill's own cross-model invariant |295| `/paper-claim-audit` | `paper/PAPER_CLAIM_AUDIT.md` | full gate | Audit-class artifact |296| `/citation-audit` | `paper/CITATION_AUDIT.md` | full gate | Audit-class artifact |297| `/proof-checker` | `PROOF_AUDIT.md` | full gate | Audit-class artifact |298| `/rebuttal` | `REBUTTAL_DRAFT_rich.md` | full gate | Pre-submission deliverable |299| `/paper-writing` | (no auto-HTML) | n/a | The final reader artifact is PDF |300| `/research-wiki` | `research-wiki/index.html` dashboard | future | Phase 2.1 — dashboard template work, not in this round |301302`--no-review` for interim reports is intentional: the source MD has already been reviewed by the producing skill's own cross-model gate, and the HTML render only converts structure — it doesn't add new claims. Full review at every checkpoint would multiply Codex calls per pipeline by 4-6×.303304To disable HTML output for a specific skill: set `RENDER_HTML = false` in the skill's constants block or pass `— render html: false`. To globally disable: skip with environment variable `ARIS_RENDER_HTML=0` (planned, not yet implemented; flag per skill in the meantime).305306## Customizing the templates307308The two templates live at `skills/render-html/scripts/templates/{academic,dashboard}.html`. Each is a single self-contained HTML file with inline CSS using `{{PLACEHOLDER}}` substitution. To customize:3093101. Copy one of the templates to a new name, e.g., `my_brand.html`.3112. Edit the CSS variables in `:root { ... }` to change colors, the font stack, or layout dimensions.3123. Add the template name to the `--template` choices in `render_html.py` `argparse`.3134. Re-run `/render-html <input> --template my_brand`.314315The default templates are derived from the user's own academic-newspaper tutorial style (Source Serif Pro + Songti SC, 3-color palette, sticky TOC, low-flash). Stay close to that idiom for ARIS artifacts unless you have a specific reason to break the visual language.316317## External alternatives (for richer surfaces)318319For deck / poster / Xiaohongshu card / tweet card / data report style outputs, point users to **[html-anything](https://github.com/nexu-io/html-anything)** (Apache-2.0, 3000⭐ at time of writing). It ships 75 SKILL.md templates across 9 surfaces and detects 8 coding-agent CLIs (including Claude Code, Codex, Copilot). ARIS does *not* depend on it — `/render-html` covers ARIS-native artifacts; html-anything is the recommended path for richer publishing surfaces.320321## Key rules322323- **Do not auto-render every Markdown file.** Only artifacts on the whitelist above. File proliferation is the main anti-pattern.324- **Do not hand-edit the generated HTML.** Edit the source, then re-render. The embedded SHA256 in the HTML meta tells you if the source has changed since render.325- **academic-template HTML is a reviewed artifact by default**, not raw output. Cross-model Codex review (fresh thread) gates the academic deliverables — the same way `/proof-checker`, `/paper-claim-audit`, `/citation-audit`, `/kill-argument` gate their respective products. `--no-review` is appropriate for **interim auto-emits** (e.g., `idea-stage/IDEA_REPORT.html`, per-round `review-stage/AUTO_REVIEW.html`) where the source MD has already passed an upstream cross-model gate — the HTML render is then a structural conversion, not a new claim audit. For **shipped / reviewer-facing / audit-class** outputs, keep the full gate.326- **The reviewer audits rendering, not research.** Claim truthfulness is owned upstream by `/paper-claim-audit`, `/result-to-claim`, `/research-review`. The HTML reviewer asks: "did the renderer faithfully + safely convert this source?" — nothing more.327- **CDN dependency is opt-out, not opt-in.** Most users have internet; `--offline` is for air-gapped runs / archival.328- **The default style is academic-newspaper, not marketing-flashy.** Match the existing ARIS tonal voice. If you want decks/posters/social cards, point users to html-anything.329- **Pure stdlib only.** Adding a `pip install` dependency to `render_html.py` requires an explicit decision — the helper currently has none. MCP calls live in the skill orchestrator, never in the helper script.