HTML Report

HTML Report — Standalone Artifacts for Humans

You are writing an HTML file a human will open in a browser or receive as an attachment. This skill exists because agents repeatedly ship HTML with unrendered LaTeX inside <pre>/<code> blocks and other recoverable presentation gaps. Follow the checklist below before declaring the file ready.

When to use HTML

Reach for HTML — instead of plain text, Markdown, or a PDF — when the human will benefit from:

• Sectioned research memos or literature maps with anchor navigation.
• Dashboards or audit reports with tables/cards/callouts.
• Side-by-side comparisons (two columns, diff-style tables).
• Anything that contains rendered mathematics.
• Artifacts they will forward to others — HTML opens everywhere with no toolchain.

If the content is short and equation-free, plain text or Markdown is usually enough.

Standalone HTML skeleton

Start from the bundled template — it already wires up typography reset, cards, callouts, tables, anchor nav, print styles, and MathJax. Copy it, fill in the <!-- TODO --> markers, drop unused sections, and save under a project-local path (paper/drafts/<topic>-$(date -u +%Y-%m-%d).html):

cp ~/.lingtai-tui/utilities/swiss-knife/reference/html-report/assets/template.html \
   paper/drafts/<your-topic>-$(date -u +%Y-%m-%d).html

Key rules for any HTML you produce, whether from the template or freshly authored:

• One file, no external assets except CDN scripts. The human will move it around.
• Inline all CSS in a single <style> block in <head>.
• Set <meta charset="utf-8"> first. Math copy-paste from LaTeX sources frequently contains non-ASCII.
• Set a sensible <title> — the human will see it in browser tabs and saved-file names.
• Use semantic tags (<section>, <article>, <aside>, <nav>) — they reflow better on mobile and print.
• Print stylesheet matters. A research memo often gets printed. Add @media print { ... } to hide navigation and force readable margins.

Math rendering checklist

<pre> and <code> render LaTeX as literal text. They do not render math. This is the most common failure mode for HTML deliverables.

If the artifact contains equations:

1. Add MathJax in <head> — once, near the top:

   <script>
   window.MathJax = {
     tex: {
       inlineMath: [['\\(', '\\)']],
       displayMath: [['\\[', '\\]'], ['$$', '$$']],
       processEscapes: true
     },
     svg: { fontCache: 'global' }
   };
   </script>
   <script defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>
   

2. Write inline math as \( ... \) and display math as \[ ... \]. Avoid $...$ — it conflicts with currency in prose. Avoid $$...$$ unless you really want a centered display block and trust the source has no stray $.

3. Do not wrap equations in <pre> or <code>. Put them in <p>, <div>, or directly in <section>. MathJax scans the DOM body for \(...\) and \[...\] and replaces them with rendered SVG.

4. Escape LaTeX backslashes correctly if you are templating from a programming language — \\( in a Python f-string becomes \( in the output.

5. Online vs offline tradeoff. CDN MathJax is one line and works everywhere with network. For fully offline artifacts (air-gapped reader, archival), either:

   • Vendor MathJax under a local asset folder and reference it locally, or
   • Pre-render equations to SVG/PNG at generation time and embed them as <img> (most robust, no JS needed).

   Pick the offline path explicitly if the human said "must work offline." Otherwise CDN is the default.

Source-derived study notes

For study notes, agree the source, goal, scope/order and lesson granularity with the human before generating a batch of artifacts. These source boundaries also apply to research memos and literature maps. For citation-bearing claims, read the academic evidence gate before drafting.

These boundaries are not optional. They apply from intake onward.

• Distill, do not reproduce. Re-explain concepts in your own words with your own examples. Do not copy the author's prose, do not paste chapters or long passages, and do not recreate the book's figures/tables verbatim. Short quotes for commentary are fine; wholesale reproduction is not.
• No piracy enabler. Decline requests framed as "summarize the whole book so I don't have to buy/read it" or "give me the full text." Offer legitimate distillation (concepts, your own worked examples, study aids) instead.
• Always cite the source. Every artifact names title, author, edition, and the page/section range it draws from, plus a provenance caveat that these are re-explained study notes, not the original.
• Confirm authorized access. Only work from material the human can point to a legitimate source for (owned copy, library/institutional access, open-access, their own notes). If they cannot, stop and say so.
• Flag the limits of your knowledge. When you teach from your own knowledge rather than the specific source (e.g. you only have the ToC), label it clearly so the learner knows what is the book's treatment vs. general background. Note that your knowledge has a cutoff and the edition may differ — tell the human to verify specifics against the actual source.
• Stay in the learner's interest. No fabricated citations, no invented page numbers, no confidently wrong technical claims. If unsure of a fact, say so and point the learner to the source section to confirm.

Artifact hygiene

• Write to a project-local path. paper/drafts/<topic>-<YYYY-MM-DD>.html or similar. Never write HTML to /tmp and forget about it — the human cannot find it later.
• Include a header block with title, generation timestamp (use date -u +%Y-%m-%dT%H:%M:%SZ or equivalent), source paths the report draws from, and a one-line caveat ("draft", "automated extract", etc.).
• Cite paths explicitly. If the report summarizes files in the repo, link them as <a href="../path/to/file.md">file.md</a> so the human can jump.
• External links must be absolute. https://arxiv.org/abs/2401.01234, not bare DOIs or arxiv: schemes.
• Verify the file exists after writing — ls -lh paper/drafts/... — and read the head + tail to make sure the write was not truncated.

Validation checklist (before sending)

Run through these every time, in order. They are cheap and the failure modes are common.

1. File exists and is non-empty. ls -lh <path> — sanity check the byte count is plausible (a research memo is typically 10–80 KB).
2. If math is present, MathJax is wired in. grep -l "MathJax" <path> must match. If it does not, math will not render — fix it now.
3. No equations stuck in <pre> or <code>. grep -nE '<(pre|code)>.*\\\\[\(\[]' <path> — any hits are bugs.
4. No stray control characters from programmatic generation. LC_ALL=C grep -nP '[\x00-\x08\x0B\x0C\x0E-\x1F]' <path> should be empty. If you generated HTML from a Python string with raw user input, this can silently break rendering.
5. HTML parses. Optional but cheap: python3 -c "from html.parser import HTMLParser as H; p=H(); p.feed(open('<path>').read())" — raises on malformed tags.
6. External links are absolute. grep -nE 'href="(arxiv:|doi:|//)' <path> — relative or scheme-less hrefs break when the file is downloaded.
7. Open it locally if a browser is available: open <path> (macOS) or xdg-open <path> (Linux). Eyeball the equations and headings.
8. When sending via Telegram/email, attach the actual HTML file (not paste its contents) and include the path in the message so the human can find the source later.

Found a bug or issue? If you encounter any problems with this skill, load the lingtai-issue-report skill and follow its instructions to report it.