Use a Publish Manifest Before Sharing Generated HTML

Table of contents

1. Why publishing needs a manifest
2. What the manifest should contain
3. Use the manifest with API or MCP
4. Keep sensitive material out
5. A copyable manifest shape

Why publishing needs a manifest

AI agents are good at producing HTML reports, dashboards, prototypes, and review packets. They are less reliable when the publish step is left implicit. One run may create three unrelated links. Another may overwrite the wrong artifact. A third may return a raw HTML blob instead of the review URL people actually need.

A publish manifest fixes that by separating planning from publishing. The agent first writes a small structured object that says what it intends to publish. Then it calls the BinHTML API or BinHTML MCP server using those fields.

That pattern matches how automation systems already work. OpenAPI describes HTTP interfaces so clients can call them predictably. MCP tools can expose input and output schemas so model clients understand the shape of tool calls and results. A manifest applies the same discipline one step earlier: it makes the agent's publishing intent reviewable before any share link exists.

What the manifest should contain

Keep the manifest small. It is not the HTML source, the full transcript, or a second report. It is the control plane for the handoff.

For one artifact, capture:

• title: the human-readable artifact name.
• description: the one-sentence review context.
• visibility: usually unlisted for a direct review link, or private for owner-only iteration.
• expiresAt: an optional future expiry timestamp when the link should not live forever.
• projectName: the project bucket when this artifact belongs with related outputs.
• artifactId: the existing artifact to update when the goal is a new version, not a new link.
• sourceReferences: commit links, issue links, dataset names, or prompt references that explain where the artifact came from.
• reviewerInstructions: the short note the agent should return with the BinHTML share URL.

For several artifacts, add an artifacts array and a projectShare section. BinHTML project links are designed for this shape: the API can group related artifacts by project name, and MCP can publish a set of generated HTML files into one project link for Pro accounts.

Use the manifest with API or MCP

Use the API when the publisher is deterministic automation: a scheduled report job, a CI workflow, or an internal script. The manifest becomes the payload builder. Each entry maps to a POST /api/v1/artifacts call, and the response gives the share, management, and source download URLs the job should store or report.

Use MCP when the publisher is an agent working inside a tool-capable environment. The manifest becomes the agent's local checklist before it calls publish_html or publish_project. MCP tool results should return structured data and human-readable content; the useful result is the BinHTML link plus enough metadata to confirm what changed.

This is also where compare workflows fit. If the manifest includes an artifactId, the agent can publish a new version to the same artifact instead of creating another isolated link. Reviewers can then compare a regenerated artifact against the previous version before approving or forwarding it.

Keep sensitive material out

A publish manifest should be safe to keep in logs. Do not put API keys, raw private datasets, customer secrets, or full HTML source into it. GitHub's artifact tooling defaults away from hidden files because hidden paths often contain sensitive data; use the same instinct for generated HTML publishing.

The manifest should point to source context without copying everything into the publish request. Put the complete HTML in sourceHtml only at the actual publish call. Keep source downloads owner-gated in BinHTML, and return share links to reviewers who only need to inspect the rendered artifact.

Also remember that generated HTML is active content. BinHTML renders shared HTML in a sandboxed viewer, and the browser's iframe sandbox model exists to restrict what embedded documents can do. The manifest should describe visibility and expiry, but the renderer still needs sandboxing and source-access boundaries.

A copyable manifest shape

Use this as an agent instruction or CI intermediate file:

• projectName: Launch review packet
• projectShare.enabled: true
• projectShare.expiresAt: 2026-06-27T18:00:00.000Z
• artifacts[0].title: Launch readiness dashboard
• artifacts[0].description: HTML summary of launch blockers and owner status.
• artifacts[0].visibility: unlisted
• artifacts[0].sourcePath: reports/launch-readiness.html
• artifacts[0].sourceReferences: commit permalink, issue tracker query, and CI run URL
• artifacts[0].reviewerInstructions: review blockers first, then compare owner status against the source issue list

The exact fields can be smaller for a one-off artifact. The important part is that the agent has to name the handoff before it publishes it.

A good BinHTML publish flow should end with fewer surprises: one clear artifact link, one project link when there are multiple outputs, source access kept behind the owner dashboard, and enough metadata for the next reviewer or agent to understand what was shared.