/moai-domain-html-report

name: moai-domain-html-report
description: >
  Markdown-to-single-file-HTML report renderer. Six modes (status, incident,
  plan, explainer, financial, pr) selected by report type, crossed with three
  audience tiers (expert, basic, learn) derived from the active output style.
  The basic and learn tiers enrich the HTML with mermaid flowcharts, worked
  examples, and plain-language primers; the expert tier stays dense. Zero
  external JS/CSS framework dependencies — inline SVG charts, a font-CDN
  exception for Korean readability, and a tier-gated mermaid-CDN exception.
  Self-contained output for email attachment, print, and offline viewing.

when_to_use: >
  Use when a markdown report must be rendered into a single self-contained
  HTML file. Trigger phrases include "render this report as HTML", "weekly
  status report as one HTML file", "convert the financial statements to an
  HTML report", "incident report as HTML", "printable business plan HTML",
  "email-ready HTML report", and "explain this as an HTML report with
  diagrams".

license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
user-invocable: true
metadata:
  version: "1.1.0"
  category: "domain"
  status: "active"

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:

| Artifact | Reader | Content rule | |----------|--------|--------------| | `.html` | **the human** | **Enriched.** May carry MORE than the source markdown — plain-language primers, mermaid diagrams, worked examples, analogies, glossary callouts — scaled by the audience tier (§ Audience Tiers). | | `.md` twin | **the agent** (context) | **Lean.** Carries ONLY the load-bearing facts: findings, decisions, numbers, tables, action items. Never the tier enrichment. |

[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

| Argument | Required | Default | Description | |----------|----------|---------|-------------| | `markdown` | yes | — | The markdown body to convert | | `mode` | yes | — | `status` \| `incident` \| `plan` \| `explainer` \| `financial` \| `pr` | | `audience` | no | derived from the active output style | `expert` \| `basic` \| `learn` — see § Audience Tiers | | `slug` | no | auto-derived from the title | Output filename prefix | | `output_path` | no | `<cwd>/reports/<slug>-<YYYYMMDD>.html` | Output path | | `font_stack` | no | per-mode default | Font mapping override |

`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.

---

Output

Two files at `<cwd>/reports/<slug>-<YYYYMMDD>.{html,md}`:

**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 CS