render-html

# /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 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`](../shared-references/integration-contract.md) §2, **Policy A — skill-local gate**): ```bash # 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 ```bash # 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 a fresh cross-family Codex thread 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: 1. **Information fidelity** — every section, claim, table, code block, list, math snippet, sidecar payload is present in the HTML (no silent drop) 2. **Structural integrity** — heading hierarchy / nested lists / table cells / code fences / `<details>` blocks / math delimiters survive parsing 3. **Callout routing** — `> 🚨 …` got `.callout-bad`, `> 💡 …` got `.callout-info`, etc. 4. **Safety / escaping** — no raw `<script>` / `onclick=` / `javascript:` / unreplaced placeholders / template-leak survives 5. **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**: 1. Write the JSON verdict to `<out_path>.review.json` (sibling to the HTML).