For agents

Handoff

Once an agent has published an artifact, the URL becomes shared infrastructure — the agent, the human, and any other agent that picks up the thread can all read and write against it. Below are the patterns we see working.

Pattern 1 — agent publishes, human reviews

The agent generates a plan, publishes it, drops the URL into chat. The human opens the link, reads the rendered page (much easier than scrolling chat), and replies with feedback. The agent updates in place.

[agent] Here's the plan: https://dropfast.dev/s/launch-plan-a1b2/
[human] Looks good. Cut section 4 and tighten section 2.
[agent] Updated — same URL.

The human never has to swap links. The URL is the document.

Pattern 2 — human edits, agent re-reads

Some workflows let the human edit the published HTML directly (we don't do this for you — but you can give the human an editor that re-uploads via PUT). On the next agent turn, the agent fetches the URL, diffs against the version it last shipped, and reacts.

[human] Read https://dropfast.dev/s/launch-plan-a1b2/, then implement section 3.
[agent] Read 4.2 KB. Implementing section 3 now…

This is the cheapest way to give an agent a shared whiteboard.

Pattern 3 — agent → agent

Two agents working on the same problem can publish their drafts to the same slug. Use private mode and make sure both agents have the API key that owns the slug.

[planner]  POST → slug=feature-spec-7c
[designer] GET feature-spec-7c, generate mock, PUT
[planner]  GET feature-spec-7c, sees mock embedded, refines

PUT replaces every file under the slug, so don't try to merge — design the artifact so the latest version is the source of truth.

Pattern 4 — human leaves inline feedback (Phase 4 spike)

Sometimes "looks good, tighten section 2" in chat isn't enough — the human wants to point at the second paragraph specifically. Publish the artifact with commentsEnabled: true (any of publish_html, publish_zip, publish_markdown, or the corresponding REST POST with -F commentsEnabled=true). The served page renders a small Shadow-DOM overlay; the human selects an element or a quote, drops a plain-text note, and the agent reads it back on the next turn.

[agent]  publish_html(html=..., commentsEnabled=true)
         → https://dropfast.dev/s/launch-plan-a1b2/
[human]  (selects section 2 paragraph, drops "tighten this")
[agent]  get_comments(slug=launch-plan-a1b2)
         → [{ id: "c_…", bodyText: "tighten this",
              target: { cssSelector: "section[id=section-2] p:nth-child(2)" } }]
         update_site(slug=launch-plan-a1b2, html=…revised…)
         resolve_comment(commentId=c_…)

If you forgot to enable comments at publish, flip it on later:

update_site_settings(slug=launch-plan-a1b2, commentsEnabled=true)

The same REST shape works: PATCH /api/v1/sites/launch-plan-a1b2 with {"commentsEnabled":true}.

Notes:

• Comments: reads are owner-scoped on private/password sites, public on public sites. Writes mirror reads — anyone who can read can comment, including anonymous viewers on a public site (labeled anonymous); private/password sites require the owner. Resolving a comment still requires the author or the owner.
• Calling get_comments on a site with comments off returns the COMMENTS_SPIKE_DISABLED error — the fix field tells you to call update_site_settings with commentsEnabled:true.
• The overlay HTML is injected at serve time; comments-enabled pages serve Cache-Control: private, no-store. Note: if a public page was already cached at the CDN edge before you enabled comments, the edge may keep serving the pre-overlay HTML for a few minutes (up to the max-age=300 window, then stale-while-revalidate) until it re-fetches. A hard reload or a re-publish busts it immediately.

Watch out for

• Stale slugs after delete. If one agent deletes the site, the other agent's next PUT returns 404. Treat the slug as durable but not immortal — re-publish if needed.
• Concurrent writes. PUT is last-write-wins. If two agents publish at the same instant, only one survives. Serialise writes when this matters.
• Cookies and password sites. A password cookie is per-browser. If your agent is fetching with a clean session every time, you'll hit the gate. Prefer private mode (with the agent's API key) for agent-only artifacts.