Moving assets between apps

The person says: “Use the hero photo from the Figma frame on the home page.”

Files cross apps as signed links: the other app hands out a short-lived address, the site fetches the bytes itself, and only the address passes through the conversation. Never paste a file’s contents into a tool call.

The loop

1. Empress:site_status — the site, and an open change set to put the page change in (Empress:changeset_create if there is none).
2. The other app hands out a download link (a design tool’s export, a drive’s download link).
3. Empress:media_ingest — items: [{ target, sourceUrl, filename, alt, optimize: "hero", bind: { collection, id, field }, provenance: { app, ref }, requestKey }], with changeset. The site fetches the file itself; the answer says where it landed, its size and dimensions, its media id, and that the field holds it as a draft.
4. Empress:site_preview — target: "draft" at three widths.
5. Empress:changeset_promote — the person’s yes puts every bind live at once.

A file you hold yourself (no link): leave out sourceUrl. The answer is one upload link per site; PUT the file to each, once, within ten minutes (curl -T hero.png "<link>"). Each answer is the stored file.

The other direction: Empress:site_call with tool: "empress.site_asset_export" (media ids, or a collection) answers signed download links another app can fetch. A file already on the site goes into a field with tool: "empress.media_bind".

Judgment

• A link that expires is fine: use it at once, never store it.
• An image is a reference. Bind the media item the upload returned; a hand-built image value without its storage key breaks the site’s own image.
• Many sites are one call: target: "all" (or a list of slugs) on the item; the answer names any site it could not reach. A requestKey per item makes a retry land nothing twice.
• Optimize an image for its use (hero, card, logo): a 2.7 MB hero is a slow phone page.