/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; mode is selected by report type and audience tier is derived
  from the active output style.

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

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`](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 so