HTML Report Generation

When to Use

Task completions with file changes
Research results and analysis
Audits and quality checks
Error/blocker reports requiring user action
Comparisons (tools, approaches, options)
Any output exceeding ~10 lines

When NOT to Use

Short answers, yes/no, status updates
Quick confirmations (<10 lines)

Report Types

task-completion

Sections: Summary, Changes Made (files list), Verification Results, Next Steps

research

Sections: Key Findings, Detailed Analysis, Recommendations, Sources

audit

Sections: Overall Score/Grade, Pass/Fail Table, Detailed Findings, Recommendations

error-blocker

Sections: What's Blocked, Root Cause Analysis, What User Needs To Do, Workarounds

comparison

Sections: Options Overview Table (with pros/cons), Detailed Analysis, Recommendation

Workflow

Generate HTML content using the template below

Get project name:

tmux display-message -p '#S' 2>/dev/null || basename "$PWD"

Get target path:

report --path --project "{name}" --title "{title}" --type {type}

Write the HTML file to that path
Open it:
```
report --open "{filepath}"
```
Print ONE line to terminal: Report: {title} -> {filepath}

HTML Template

<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>REPORT_TITLE</title>
    <meta name="report-type" content="REPORT_TYPE">
    <meta name="report-project" content="PROJECT_NAME">
    <meta name="report-date" content="YYYY-MM-DD">
    <script type="application/json" id="report-meta">
    {"title": "REPORT_TITLE", "type": "REPORT_TYPE", "project": "PROJECT_NAME", "date": "YYYY-MM-DD"}
    </script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
    <style>
        :root { --pico-font-size: 15px; }
        body { max-width: 900px; margin: 0 auto; padding: 2rem 1rem; }
        .report-header { border-bottom: 1px solid var(--pico-muted-border-color); padding-bottom: 1rem; margin-bottom: 2rem; }
        .report-header h1 { margin-bottom: 0.3rem; }
        .meta { font-size: 0.85em; opacity: 0.6; }
        .meta span { margin-right: 1.5em; }
        .badge { display: inline-block; padding: 0.15em 0.5em; border-radius: 4px; font-size: 0.8em; font-weight: 600; }
        .badge-success { background: #065f46; color: #6ee7b7; }
        .badge-warning { background: #78350f; color: #fcd34d; }
        .badge-error { background: #7f1d1d; color: #fca5a5; }
        .badge-info { background: #1e3a5f; color: #93c5fd; }
        table { width: 100%; }
        table td, table th { padding: 0.5rem 0.75rem; }
        .score { font-size: 2em; font-weight: 700; }
        .pass { color: #6ee7b7; }
        .fail { color: #fca5a5; }
        .warn { color: #fcd34d; }
        pre { font-size: 0.85em; overflow-x: auto; }
        .section { margin-bottom: 2rem; }
        details summary { cursor: pointer; font-weight: 600; }
        details { margin-bottom: 1rem; }
    </style>
</head>
<body>
    <div class="report-header">
        <h1>REPORT_TITLE</h1>
        <div class="meta">
            <span>PROJECT_NAME</span>
            <span>YYYY-MM-DD HH:MM</span>
            <span class="badge badge-info">REPORT_TYPE</span>
        </div>
    </div>
    <main>
        <!-- REPORT CONTENT HERE -->
    </main>
    <footer style="margin-top:3rem;padding-top:1rem;border-top:1px solid var(--pico-muted-border-color);font-size:0.8em;opacity:0.4">
        Generated by Claude Code
    </footer>
</body>
</html>

Content Patterns

Pass/Fail Row (for audit tables)

<tr>
    <td>Check Name</td>
    <td><span class="pass">✓ Pass</span></td>
    <td>Details about what was checked</td>
</tr>

File Change Row (for task-completion)

<tr>
    <td><code>path/to/file.py</code></td>
    <td>Modified</td>
    <td>Brief description of change</td>
</tr>

Comparison Cell

<td>
    <strong>Option Name</strong><br>
    <span class="pass">+ Pro point</span><br>
    <span class="fail">- Con point</span>
</td>

Images in Reports

NEVER embed base64-encoded images in report HTML
When including screenshots or images:
1. Save the image file in the same directory as the report HTML
2. Reference with relative path: <img src="screenshot.webp" alt="description">
Image filenames should be descriptive: homepage-hero.webp, error-state.webp, etc.

Important

Reports are SELF-CONTAINED — all CSS is inline or from CDN
Always include the <script id="report-meta"> JSON block for indexing
Always include both <meta name="report-*"> tags AND the JSON block
Use semantic HTML: <section>, <table>, <details>, <pre><code>
Keep reports focused — one topic per report

report