Project Media — publishing finished images, videos, and PDFs

Project Media is a server-side storage area for publishing and reusing finished images, videos, and PDFs as Project assets. It is not a place for work-in-progress files. Published media appears in the WebUI's Media tab and can be referenced from conversations, documents, and HTML through a stable canonical URL.

Videos play from the stored original without recompression or downscaling. Slow connections wait for loading instead of switching to lower quality. If your browser cannot play the original, use Download original. Thumbnail generation does not block playback.

Prerequisites and permissions

How to publish

There are two ways to publish.

1. Place a file (the standard path for agents): put a finished file in aachat/teams/<team>/projects/<project>/media/, and it is detected and published to the server automatically. There is no dedicated command. Create the file in a working directory, then move only the finished product into media/ with mv (rename). If you keep updating a half-written file inside media/, it can be picked up in an unfinished state. Outside a Session, while aachat up is running, the same happens in the common root (~/aachat/teams/<team>/projects/<project>/media/) or the same path in a connected repository
2. Upload from the WebUI: Add media in the Media tab (human Collaborator/Admin, active Project only)

File placement detection follows these rules.

• Only regular files under media/ are published. .tmp / .part files, symlinks, and files whose names start with . are not published. Directories whose names start with . are skipped with their contents (this includes media/.downloads/)
• Deleting a file locally does not remove published media. Use explicit deletion to withdraw it
• Overwriting or touching the same still-present path with identical bytes does not re-publish it. Placing different finished bytes at the same path creates a new publication. Reappearance after an observed deletion can also create another publication
• Transient upload failures are retried with a bounded budget. If an upload pauses, restarting the same Session or aachat up resumes it as the same Media

Supported formats and limits

Unsupported formats are rejected with media_type_not_supported; encrypted PDFs and empty files are also rejected. Even a small file can exceed limits on image dimensions, animation frames, PDF pages, or video duration (Limits). Changing only the extension does not change the format.

Upload in the WebUI

1. In the Project's Media tab, click Add media and choose images, videos, or PDFs
2. The Publishing section shows each file's state: Waiting → Preparing → Uploading (progress bar) → Confirming upload → Processing → Ready
3. Once Ready, it appears in the list. Open it with Media detail

Transient failures are retried automatically under the same Media ID and shown as Retrying (n of 3). To stop an upload, or when one stops:

Resume information is kept in the browser tab for 24 hours.

Referencing — canonical URL

The only stable reference to published media is the canonical URL https://aachat.io/m/<uuid>.

• Images can be embedded in Markdown as ![description](https://aachat.io/m/<uuid>). Link videos and PDFs normally
• Signed delivery URLs, storage URLs, /_media/, and /_aachat/media/... are short-lived or generated; do not save them in documents or messages. Always save https://aachat.io/m/<uuid>
• Adding a query, fragment, or different host to a canonical URL stops it from being treated as a Media reference
• Shared Documents, Project messages, user/system Session input, and Session Run input reject Media references that are not ready, belong to another Project, are unknown, or use syntax that does not match their kind. Follow the returned action: retry after the Media is ready, or use a normal link
• Assistant Session text (intermediate and final responses) validates and registers dependencies only for Media found in the same Project. Local Media that is not ready, is being deleted or deleted, or has incompatible syntax still prevents saving. References to other Projects or unknown IDs are saved in the text without adding dependencies, referrers, or deletion protection
• Saving text does not grant viewing access. Other-Project Media is displayed according to the viewer’s permissions and the Media state; viewers without access see Unavailable. Public Session shares do not serve other-Project or unknown Media, and recognized references become Media unavailable
• List Media in the WebUI Media tab, or with chat media <team>/<project> inside a Session. --q <text> filters by display name or publisher name; read further with --last <1-50> (default 30) and next_page. Only ready Media is listed

The canonical URL is a stable identifier, not a public share URL. Opening it in a browser shows the Project's Media detail only to members of the Project that owns it. To show something to outside people, use Markdown or HTML sharing.

The old aachat.work domain is retired. https://aachat.work/m/<uuid> is redirected as a WebUI page to the same path on aachat.io, but old-domain delivery URLs and APIs return 403. Saved old links are not rewritten automatically. An old https://aachat.work/m/<uuid> in text is still recognized as a reference to the same Media, but write new references as https://aachat.io/m/<uuid>.

Read existing Media inside a Session

A listing or canonical URL does not prove that a Session has read the image, video, or PDF itself. To check the content, download it and read the file named by the success JSON. Do not fetch the canonical URL: it returns a login page, not bytes.

1. Read the ready list with chat media <team>/<project> and note the target media.id. Zero results or a missing target does not mean you have checked the content. Check filters, paging, the target Project, and readiness
2. Download it. <MEDIA_ID> accepts a UUID or canonical URL. --download cannot be combined with --q, --last, or --before

chat media <team>/<project> --download <MEDIA_ID>

3. Match data.downloaded.media_id in the success JSON to your target, then open the file at data.downloaded.path with a reader that supports the format. content_type and byte_size are also returned. The file is saved as media/.downloads/<media-id>.<ext> in the target Project, but use the returned path instead of guessing. Confirm download success and reading success separately; if your reader does not support the format, treat the content as unchecked

The downloaded copy is for reading. .downloads is not published, so do not edit it or copy or move it into media/ to republish it. Write the original canonical URL in documents and messages. Do not share the local path as a link.

If chat media --help has no --download, that Session's CLI is outdated. Update the CLI before using it.

When reporting, include the Project, Media ID, time, CLI version, and the error code and message. Do not include credentials or signed URLs.

View in the WebUI and use in a Session

The Media tab can be filtered with Search media and by kind (All / Images / Videos / PDF). Each card's menu offers Open details, Copy link, and Download.

Media detail contains:

• Next to the file name: Copy link (copies the canonical URL) and Download (saves the original file)
• Main header actions:
  • Request changes: when the source Session exists and can continue, ask for a fix in that Session
  • Start new Session: when there is no source Session, start a new Session with this Media as context
  • When follow-up is not possible, a reason is shown instead of the button
• More actions: Open source Session, Open full viewer
• Details: state, kind, size, published time, image dimensions, PDF page count

To reuse media in an existing Session, choose Copy link, open the intended Session, and paste the link into its input. Nothing is sent automatically. From a publication, choose Open details first to access Copy link. Close the image viewer before opening the intended Session.

Image viewer

Inside a Session, images in message bodies, attachments, and result notifications appear as cards. Clicking one opens the shared image viewer without leaving the Session. Your draft is kept, and the browser Back button returns to the Session.

• It has previous/next navigation, zoom in and out, Fit (show the whole image), and Original · 1:1 (a toggle that shows the original at actual size). It loads a lighter viewing image first and loads the original for Original · 1:1
• Request changes: draw numbered regions on the image and describe the change for each. A review image with the regions and the descriptions are added to the Session draft. It works for this Project's images that have finished processing and are static JPEG, PNG, or WebP. When unavailable, the button is disabled and the reason appears in a tooltip
• More actions: Open source Session when known, and Open details (Open in owning Project for another Project's image) unless that exact owning detail is already open. The menu is hidden when neither action is available.

Videos and PDFs published by an Agent also appear as result cards when they can be matched to exactly one message. Check the name, kind, and state, then use Open Media to open the existing Media detail page. Within the same Project, the Session and draft are kept. Uploading, processing, and failed items keep their state and publication summary visible. Play videos and read PDFs on the detail page.

When the card and input are both accessible, drag an image, video, or PDF from the Media list, or a ready image card in a Session, into the input to insert its canonical URL as text. Video and PDF reference cards do not support this drag. On narrow screens, use Copy link and paste. This is not a file upload. Ordinary paste stays text, and attaching a file still uploads it. Copying a link does not grant access to another Project; use the owning Project when needed.

Opening same-Project Media from a Session result badge or popup opens Media detail inside the workspace, keeping your unsent draft and selected agent.

Deleting

Deleting Media on the server is irreversible. Human Collaborators/Admins, and Sessions that have the Project in coverage, can do it.

• WebUI: Delete in Media detail. If a current Shared Document or Project HTML references it, the referencing paths and counts are listed and Delete Media is disabled. Remove the references, then retry. Without blocking references, the number of tracked past references is shown
• Session: chat media <team>/<project> --delete <MEDIA_ID> --revision <N>. <N> is media.revision from the list. When accepted, data.deleted.status is deleting and it disappears from the list
• If media_delete_conflict is returned, read error.message. If references remain, search the Project for the canonical URL to find them and remove them. Re-read media.revision with chat media, and retry deletion only if it is listed. Absence from the ready list does not prove deletion
• After deletion the canonical URL no longer resolves, and links in past messages or external records break
• Local files in media/ remain after deletion. Deleting the file does not delete the Media, and deleting the Media does not delete the file

What is not published — Session attachments

Files passed with --attach on chat session run / chat session send, or attached in the WebUI, go only to that Session. They stay in Session history but are not published to Project Media. Attach to give context for a request; place in media/ to keep a Project asset. Local turn-input files given to a Session are read-only; do not edit, move, or publish them into media/.

Publish and check a finished report

Publish from a Session with coverage and write permission (Collaborator/Admin) in an active Project. Finish ./output/customer-report.pdf outside the watched folder, replace the Project name, and move it:

mkdir -p aachat/teams/acme/projects/customer-research/media
mv ./output/customer-report.pdf aachat/teams/acme/projects/customer-research/media/customer-report.pdf
chat media acme/customer-research --q customer-report

The detected file goes through upload and processing to ready, then appears in chat media. You can also check the preview and Details in the WebUI Media tab. Write the canonical URL returned by the list into documents as is; do not build a UUID from the filename. Placing a file or an accepted upload does not confirm successful processing.

If nothing appears, check that the file is finished, in a supported format and within limits, not ignored (dot-prefixed, .tmp, .part, symlink), in the correct Project path within coverage, and that you have write permission. If Media detail shows Couldn't prepare this Media or Failed, read the error, fix the source, and publish it again as a new finished file. If a document or HTML cannot reference it, check that it is ready and that the canonical reference is exact.

Related pages

• Overview of deliverable surfaces — Projects
• Deliverables shown in a browser — HTML
• Sharing with outside people — Sharing
• Command syntax — CLI
• What is stored on the server — Trust boundary