# Ask an AI coding agent for a single-file HTML report you can read anywhere

Canonical: https://githtml.com/guides/ask-ai-coding-agent-for-single-file-html-report
Published: 2026-10-10
Publisher: WaveTech LLC / gitHtml

Tell the agent exactly what the report is for, which files and revision it may read, and the output contract: one .html file, inline CSS, no external scripts or fonts, a viewport tag, and claims linked to file paths. Then check the result yourself before committing it. The format requirements make it portable; the evidence requirements make it trustworthy.

## Why specify the format

Coding agents will happily produce HTML, but left alone they often reach for a CDN framework, a web font, a chart library, or a layout tuned for a wide monitor. Those choices look fine in the agent's preview and fail when the file is opened offline, in a reader with scripts disabled, or on a phone. Asking up front costs one paragraph and saves a round of fixes.

Equally important is scope. A report that says the service retries three times is only useful if the reader can see where that came from. Ask for paths and line references next to claims so a reviewer can verify them.

## A reusable prompt

Adapt the bracketed parts and keep the output rules. The read-only instruction matters for analysis tasks: you want a description of the current code, not a report mixed with unrequested edits.

````text
Write a report explaining [how request authentication works in services/api]
for [a new on-call engineer]. Read only; do not modify source files.

Output contract:
- One file: docs/reports/[auth-flow].html, complete document with <!doctype html>.
- <meta name="viewport" content="width=device-width, initial-scale=1">.
- All CSS in a single <style> element. System font stack. No external
  scripts, stylesheets, fonts, or images.
- Diagrams as inline SVG or ordered lists, each with a text explanation.
- Wide tables and code inside containers with overflow-x: auto.
- Start with: title, one-paragraph summary, revision (git commit), date.
- After each factual claim, cite the file path and line range.
- Mark anything inferred rather than read as "Inferred:".
- End with open questions and what you did not inspect.
````

## Acceptance checks before committing

Treat the output as a draft from a fast colleague. The format checks take a minute; the evidence checks take longer and are where the value is.

1. Search the file for http and src= to confirm there are no external dependencies.
2. Open it with JavaScript disabled and the network off; every section should still read.
3. Narrow the browser to phone width and check tables, code, and diagrams for overflow.
4. Spot-check at least three cited file paths and line ranges against the stated commit.
5. Read every Inferred: line and either verify it or keep it labeled.
6. Confirm the report contains no secrets, tokens, or customer data copied from logs.

## Commit and read it

Commit the report in a predictable folder such as docs/reports with a descriptive filename. In gitHtml it then appears alongside the repository's other HTML documents and renders on iPhone or iPad with scripts and remote resources off by default, which is exactly the environment the output contract was designed for. When the code changes, regenerate the report from the new commit instead of editing old claims by hand.

## Sources and further reading

- [MDN: viewport meta tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/viewport)
- [MDN: The style element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/style)
- [OWASP: LLM Prompt Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html)

## Related guides

- [Write a read-only AI documentation prompt with explicit boundaries](https://githtml.com/guides/read-only-ai-documentation-prompt)
- [Build an evidence ledger for AI-generated documentation](https://githtml.com/guides/ai-documentation-evidence-ledger)
- [Build a single-file HTML document that travels well](https://githtml.com/guides/portable-single-file-html-document)
- [Verify AI-generated API documentation against the actual contract](https://githtml.com/guides/verify-ai-generated-api-documentation)

Editorial approach: https://githtml.com/guides/about