Moai Domain HTML Report

html-report — Single-File HTML Report Renderer

Purpose and Scope

This skill is a terminal renderer that converts a markdown report into a single self-contained HTML file. It accepts any markdown body produced by a text, analysis, or reporting workflow and emits one .html file that opens directly in a browser, attaches to email, prints cleanly, and works offline.

Core principles:

• Zero external JS libraries (no Chart.js, D3, htmx)
• Zero external CSS frameworks (no Tailwind, Bootstrap)
• Inline SVG renders all charts directly
• A font-CDN <link> is permitted for Korean readability
• A mermaid-CDN <script> is permitted only in the basic and learn audience tiers, always paired with a no-JS fallback (see § Diagram Policy). The expert tier remains strictly zero-JS.

This skill does not replace the markdown output. Markdown remains the single source of truth; HTML rendering is an additional branch that operates on it.

The asymmetry principle — HTML is rich, the markdown twin is lean

The two artifacts this skill produces serve different readers and therefore carry different amounts of content. They are not the same document in two syntaxes:

[HARD] Audience-tier enrichment scales the HTML and NEVER the markdown twin. Raising the tier from expert to learn must not add a single primer, analogy, or worked example to the .md twin — that enrichment exists to teach a human, and it is pure token cost to an agent that already understands the domain. A learn-tier report and an expert-tier report of the same source produce markdown twins of substantially the same size; only their HTML differs.

Input

mode and audience are orthogonal: mode picks the report's structure (which sections exist), audience picks its depth (how much explanation each section carries). Every mode renders at every tier.

Reading report.format (delivery format)

Before delivering, read report.format from the settings chain (.moai/config/sections/report.yaml; the skill-routing doctrine couples on it). Closed set: html+md (default) | md | artifact — html+md renders the classic browser path below; md leaves the skill idle (markdown is the native output); artifact renders the HTML conformed to the artifact page contract (references/artifact-contract.md) and publishes it as a Claude Artifact, falling back to html+md automatically when the Artifact tool is absent (no error — § After rendering (b)).

Output

Two files at .moai/reports/<slug>-<YYYYMMDD>.{html,md}. If the .moai/reports/ directory does not exist yet, create it before writing either file:

The .html file — the human-facing artifact:

• Size: ≤ 50KB at the expert tier; ≤ 120KB at the basic / learn tiers (the enrichment budget — diagrams and examples cost bytes)
• External dependencies: one font-CDN <link> + two preconnect hints (Korean fonts), plus one mermaid-CDN <script> at the basic / learn tiers only
• Self-contained: opens directly in a browser, email-attachable, print-clean, and readable offline (diagrams degrade to their fallback — see § Diagram Policy)

The .md twin — the agent-facing artifact (below).

Markdown twin (agent-context artifact)

Alongside every .html file, write a markdown twin at the same path with the .md extension (<slug>-<YYYYMMDD>.md). The HTML file is the human-viewing artifact; the markdown twin is the machine-context artifact, and per § The asymmetry principle it is deliberately leaner than the HTML, not merely the same content with tags stripped.

What the twin contains — the load-bearing facts only:

• The findings, decisions, numbers, and conclusions
• Tables (as markdown tables) and any figures the numbers depend on
• Action items, owners, and open questions
• The mermaid source of a diagram only when the diagram encodes information the prose does not (a real state machine, a real dependency graph). A diagram that merely re-illustrates a sentence for a beginner is enrichment — it is omitted.

What the twin OMITS — everything the audience tier added for the human:

• Plain-language primers and jargon glossaries
• Analogies and motivating narratives
• Worked step-by-step examples that re-derive a stated result
• Self-check questions, callout boxes, decorative diagrams
• All HTML tags, inline CSS, <script> blocks, and SVG chart markup

Consumption rule (token discipline): whenever a report is needed as context — an Agent() spawn prompt, a follow-up analysis turn, a cross-session Read of a past report — use the .md twin, NEVER the .html file. Raw HTML wastes tokens on tags, style blocks, and SVG paths that carry no information the markdown does not already have (typically 3-5x the tokens for identical content), and the tier enrichment on top of that is pure cost to an agent.

Legacy HTML without a twin: when only an .html file exists, extract the load-bearing facts into markdown first (strip tags, <style>, <script>, SVG chart markup, and the tier enrichment; convert <table> to markdown tables) and inject the extraction — not the raw HTML — into the agent prompt or context. Write the extraction next to the HTML as its .md twin so the cost is paid once.

After rendering — report back to the user

Once the .html file and its .md twin are written to .moai/reports/, the pair files always exist on disk — the delivery step chooses how the user reaches them, driven by report.format (§ Input). The response MUST do two things:

1. Summary — print a concise summary of what was rendered: the mode, the audience tier (and what it was derived from — the active output style, or an explicit audience argument), the report title, and the key sections or figures the file contains (a short paragraph or a few bullets). Do not paste the full HTML into the response.

2. Deliver — exactly one of the following, by report.format:

   (a) format: artifact and the Artifact tool is available — conform the document to the artifact page contract (standalone skeleton, 2-4-word <title>, :root tokens + dual dark-mode blocks, explicit body background, 16px phone gutter, Google-Fonts-only stylesheets, pre.mermaid diagrams, no external script — full contract: references/artifact-contract.md), publish the HTML as a Claude Artifact, and present the artifact link in the summary instead of the browser auto-open. Loading artifact-design for the publication contract in this step is correct routing — content and rendering stay owned here (skill-routing).

   (b) format: artifact and the Artifact tool is NOT available (Codex, GLM, API-key sessions) — deliver through the existing html+md path (opener below) without treating it as an error, and state the fallback and reason in one summary sentence ("Artifact tool unavailable in this session — delivered as html+md instead"). The .moai/reports/ pair is written exactly as in (a).

   (c) format: html+md — immediately open the rendered file in the user's default browser by running the platform-appropriate opener via the Bash tool. Do NOT ask the user to type ! open themselves; run the opener directly so the report appears in one step on macOS, Windows, and Linux alike:

   case "$(uname -s)" in
     Darwin) open "<output_path>" ;;
     Linux)  xdg-open "<output_path>" >/dev/null 2>&1 || echo "Open manually: <output_path>" ;;
     MINGW*|MSYS*|CYGWIN*) start "" "<output_path>" ;;
     *) echo "Open manually: <output_path>" ;;
   esac

   macOS uses open, Linux uses xdg-open (fall back to printing the absolute path when no opener/display is available — headless or WSL environments), Windows Git-Bash/MSYS uses start. If the opener command fails or the permission is denied, print the absolute path so the user can open the file manually.

   In path (c) always auto-open the report (or, failing that, print its absolute path) — a rendered report the user cannot locate or open has no value.

3. Republishing keeps the artifact URL — regenerating an artifact-delivered report at the same output path and republishing the same file path preserves the artifact URL (same path → same link). The .moai/reports/<slug>-<YYYYMMDD>.{html,md} pair is written on every regeneration regardless of format.

Audience Tiers

The report adapts its depth to the reader. The tier is derived from the active output style unless an explicit audience argument overrides it.

Resolving the tier

Read outputStyle from the settings chain — .claude/settings.local.json (highest) → .claude/settings.json → ~/.claude/settings.json → hardcoded default — and map it:

An explicit audience argument always wins over the derived value.

What each tier renders

The last row is the invariant, restated because it is the one that is easy to violate: no tier adds anything to the markdown twin. Enrichment is an HTML-only concern.

Authoring the enrichment (basic / learn)

• Explain, then state. At basic / learn, a section that opens with a raw metric is a miss. Open with one sentence saying what the metric is and why the reader should care, then give the number.
• Define every term on first use. Everyday-language gloss first, canonical English term in parentheses: 배포 (deployment) — 만든 코드를 실제 사용자에게 내보내는 일. After the first definition the bare term is fine.
• Prefer a diagram to a paragraph when the content is a flow, a sequence, or a state machine. That is exactly what these tiers exist for.
• Ground every example. A worked example uses real inputs from the report, not foo / bar.
• Never pad. Enrichment means more understanding, not more words. A section a beginner already grasps needs no primer.