Add Source References Before Sharing Agent-Generated HTML

Table of contents

1. The link is only half the handoff
2. What counts as a source reference
3. What to include for code review artifacts
4. What to include for reports and dashboards
5. How agents should return the handoff
6. A copyable source-reference checklist

The link is only half the handoff

Publishing generated HTML gives the reviewer a place to open the work. That matters. A dashboard, code review packet, migration explainer, or launch summary is usually easier to read as a browser page than as a long chat response.

But the link alone does not answer the reviewer's next questions:

• Which commit, branch, issue, or run produced this?
• What inputs did the agent use?
• Is this the latest version or a stale draft?
• Can I inspect the generated source if something looks wrong?
• Who owns the artifact if the link needs to be updated or revoked?

Those questions are why source references belong in the handoff, not buried in the agent transcript.

BinHTML already treats source access as a first-class part of artifact review. The API docs return a share URL, management URL, and source download URL when an artifact is published. The MCP docs expose the same idea for agents that publish through a tool call. A useful handoff should put those URLs next to the external evidence that explains the artifact.

What counts as a source reference

A source reference is any stable pointer that helps a reviewer reconstruct the artifact's context.

For developer teams, the strongest references are usually:

• a commit permalink or pull request URL
• a line-level permalink for the code the artifact discusses
• a CI run URL or workflow artifact URL
• a source data export, query ID, or dashboard snapshot
• the prompt or instruction file that shaped the agent output
• the issue, ticket, incident, or release page that requested the work
• the BinHTML source download URL for the generated HTML itself

GitHub's file documentation is a good model here: branch URLs can move, while permalinks point to a specific version of a file. That distinction matters when an HTML report describes a code path or summarizes a test run. If the reference floats with main, the reviewer may see different code than the agent saw.

The same principle applies to workflow output. GitHub Actions supports uploaded artifacts and retention controls, which is a reminder that generated outputs have a lifecycle. If the HTML artifact summarizes CI evidence, link the CI run and keep retention in mind before relying on it as the only source.

What to include for code review artifacts

For an AI-generated code review report, attach enough context for the human reviewer to check the findings without reopening the agent session.

A practical handoff should include:

• the pull request or commit range reviewed
• permalinks to the highest-risk files or lines
• the test command or CI run used as evidence
• the agent instruction or review checklist used
• the BinHTML share URL for the rendered report
• the BinHTML source download URL for the generated HTML
• the owner or channel for follow-up changes

This keeps the HTML artifact focused on reading while the handoff preserves traceability. The report can group findings, explain risk, and show screenshots or diagrams. The source references give reviewers a way to verify the claims.

Avoid stuffing every raw log into the artifact. Link bulky evidence when it already has a better home, such as CI, GitHub, or an internal data system. Use the HTML page for synthesis, not as a storage dump.

What to include for reports and dashboards

For generated reports, the source-reference problem is usually about data freshness and reproducibility.

Include:

• the time window covered by the report
• source system names or query IDs
• data export timestamps when available
• caveats about missing or partial data
• the project or recurring workflow name
• the artifact version or update label
• the source download URL for the HTML

This is especially useful for recurring AI reports. If an agent publishes a daily dashboard into a stable BinHTML project, the project link helps reviewers find the current packet. Source references explain what changed in this run.

The rule is simple: a reviewer should be able to tell whether the artifact is a decision surface, a draft, or an archive. Visibility, expiry, and source access should match that status before the link goes into Slack, Linear, GitHub, or email.

How agents should return the handoff

Agents should return links and metadata, not raw HTML. The Model Context Protocol tools specification supports structured and unstructured tool results, which gives publishing tools room to return stable fields instead of forcing a giant markup blob back into the transcript.

OpenAI's Agents docs describe the result of an agent run as a handoff boundary and continuation surface. That framing is useful for generated HTML: the final answer is not just the text the model writes. It is the package of links, source references, and next steps the next person can act on.

A good final agent response can be short:

• shareUrl: the BinHTML artifact or project link
• sourceDownloadUrl: the generated HTML source
• managementUrl: the owner control surface
• sourceReferences: commit, run, data, prompt, or ticket links
• reviewStatus: draft, ready for review, approved, or superseded
• nextAction: what the reviewer should check first

That shape works for both API publishing and MCP publishing. The transport changes. The handoff contract should not.

A copyable source-reference checklist

Before sharing an agent-generated HTML artifact, check this:

1. The artifact title names the work, not just the tool that made it.
2. The share URL opens the rendered HTML in the expected visibility mode.
3. The source download URL is available to the owner or reviewer who needs it.
4. Code references use commit or line permalinks when the artifact discusses specific code.
5. CI references point to the run, job, or uploaded artifact that supports the summary.
6. Data references name the source, time window, and freshness limit.
7. The prompt, checklist, or agent instruction is linked when it affects interpretation.
8. The artifact has an owner, expiry expectation, and update path.
9. The handoff says whether this is a draft, current version, or archived evidence.
10. The reviewer knows what to verify before acting on the artifact.

This is not bureaucracy. It is what makes a generated HTML link usable outside the moment it was created.

A BinHTML link gives the work a stable review surface. Source references give the reviewer confidence that the surface still points back to the right evidence.