Run a Link Preflight Before Sharing Generated HTML

Table of contents

1. Why link preflight belongs before handoff
2. Check outbound links like product surface
3. Stabilize source references
4. Verify BinHTML controls before sharing
5. Make the preflight agent-friendly
6. Final thought

Why link preflight belongs before handoff

Generated HTML artifacts often look finished before the handoff is actually ready. The page renders, the charts appear, and the agent has a share URL. Then a reviewer clicks through and finds a broken source link, a branch URL that drifted, a missing expiry, or a project packet that points at the wrong set of artifacts.

That is not a rendering failure. It is a link preflight failure.

Treat the preflight as the last small gate before an agent posts the BinHTML link into Slack, a ticket, a pull request, or an automation summary. The goal is not to turn every generated report into a full QA cycle. The goal is to catch the link mistakes that make reviewers lose trust quickly.

This fits naturally after a publish manifest. If the previous step says what should be published, the preflight checks whether the published artifact is safe and useful to share.

Check outbound links like product surface

The first pass is simple: every link in the artifact should be intentional, openable, and appropriate for the review audience.

At minimum, check:

• absolute URLs parse cleanly with the browser URL model
• internal navigation points at expected BinHTML routes or artifact sections
• external links do not depend on local files, localhost, or a developer-only VPN
• review links open the exact page the artifact text promises
• no link exposes tokens, signed query strings, or private identifiers that should stay out of the handoff

MDN's URL documentation is a useful baseline because agents and scripts can use the standard URL constructor to reject malformed links before a human sees them. For larger packets, a link checker can catch dead links and redirect surprises, but keep the policy specific to the artifact. A temporary staging URL may be fine for owner review and wrong for a customer-facing handoff.

Also check the behavior of external links. Browser link attributes such as rel="noopener" and rel="noreferrer" exist because opening another page can carry security and privacy side effects. BinHTML's sandboxed viewer is the main boundary for generated HTML, but link hygiene still matters when the artifact sends the reviewer somewhere else.

Stabilize source references

Source links are different from ordinary outbound links. They are part of the audit trail.

If an HTML report cites code, prompts, generated files, CI output, or a dataset note, the source reference should not drift after the reviewer opens it. GitHub's permanent-link guidance is the practical default for repository content: link to a specific commit, not a moving branch path, when the reviewer needs the exact file version.

A useful source preflight asks:

• does each source link explain why it is included?
• does code evidence use commit-pinned URLs instead of branch URLs?
• do issue, PR, or CI links point at the exact run or discussion being summarized?
• are private source links acceptable for the intended reviewers?
• is any source context missing from the artifact description or handoff note?

This is where BinHTML source access and reviewer access should stay separate. The rendered artifact can be shared as an unlisted link, while source inspection remains owner-controlled when the raw HTML or supporting files are sensitive. If your automation needs that distinction, make it explicit in the API docs or MCP docs path you use.

Verify BinHTML controls before sharing

A link preflight should include BinHTML-specific controls, not only links inside the HTML.

Before the agent returns the final URL, confirm:

• visibility matches the audience: private for owner-only iteration, unlisted for direct-link review
• expiresAt is set when the artifact should not live forever
• project grouping is correct when the handoff contains several artifacts
• the project share link is the intended top-level URL for a multi-artifact packet
• source download expectations are clear for reviewers and operators
• a regenerated artifact was checked in Compare before replacing the practical meaning of an existing link

This is especially important for recurring reports and release packets. A stable URL is useful only when the packet behind it stays understandable. If today's run updates yesterday's artifact, compare first. If the work spans a summary, appendix, and dashboard, share the project link instead of a loose pile of artifact URLs.

Plan assumptions also belong in the preflight. If a workflow depends on private artifacts, longer-lived history, or project share links, check /pricing before encoding those expectations in automation.

Make the preflight agent-friendly

The preflight works best when it is a small checklist the agent can run after publishing and before its final response.

A practical agent instruction looks like this:

1. Publish the artifact or project through BinHTML.
2. Extract every outbound URL from the generated HTML and validate that each URL is intentional.
3. Check source references for stable, reviewer-appropriate links.
4. Confirm visibility, expiry, project grouping, and source-access expectations from the publish response.
5. If this is a revision, open the compare path before announcing the updated link.
6. Return one primary BinHTML URL plus a short note about what was checked.

For deterministic automation, put the same steps after the publish API call. For MCP-driven work, put them in the agent's tool-use policy so the model does not treat publish_html or publish_project as the final step by default.

The output should be short. Reviewers do not need the whole checklist pasted into the final message. They need confidence that the link is current, the sources are stable, and the controls match the sharing job.

Final thought

Generated HTML handoffs fail in small, avoidable ways: one bad source URL, one stale project link, one missing expiry, one unreviewed replacement. A link preflight catches those problems before the BinHTML URL becomes the thing everyone forwards.

Publish the artifact. Check the links. Then share the link people should actually open.