# Images

> Upload screenshots and diagrams, choose who can see them, get a permanent link that works in planpage documents, GitHub issues and pull requests, and see how storage is counted.

People and agents can upload images to a workspace. Each public image gets a permanent link on planpage's sharing host, such as `https://share.planpa.ge/i/4kQ…Zt.png`. Put that link anywhere markdown images work: planpage documents, GitHub issues, pull requests and comments, or a README.

Images can be PNG, JPEG, GIF or WebP, up to 10 MB each. SVG isn't accepted, because an SVG file can carry scripts; export it as PNG instead.

## Who can see an image

An image is either **public** or **private to its workspace**.

- **Public** (the default for images in documents): anyone with the link can see it. The link is long and random, so nobody can guess it, but a link pasted into a GitHub comment, an email or a chat can be opened by everyone who reads it. This is the same as GitHub's own image attachments. Use public images for anything you'll paste outside planpage.
- **Private to the workspace** (always used for screenshots in comments, and for captures from [Planpage Capture](https://planpa.ge/docs/capture.md)): only people signed in who can open the workspace see it. Someone a single document was shared with sees the private images in that document. Share pages and emails show private images through links that stop working after a few hours (share pages) or a week (emails), so a copied link doesn't stay open.

**Images** in the sidebar shows which is which. Choose **Make private to workspace** or **Make public** on an image to switch it; a private image's old public link stops working. Agents can upload private images with `upload_image` and `visibility: "workspace"`, and see them with `view_image`.

Don't upload anything secret as a public image.

## Uploading from an agent

Agents connected to planpage use the `upload_image` tool. It returns the image's `url` and ready-to-paste `markdown`.

- Files up to 2 MB can be sent inline as base64.
- For bigger files, or when the agent has the file on disk, `upload_image` without data returns a single-use upload URL and a `curl` command that sends the file. The URL works once and expires after 15 minutes.

`list_images` lists a workspace's images and its storage use. `delete_image` deletes an image uploaded by you or your agents.

Uploading needs a connection with **Publish only** or **Publish and run** access to the workspace. Read-only connections can list images but not upload them. See [Agents and access](https://planpa.ge/docs/agents-and-access.md).

## Diagrams as images

planpage draws every mermaid diagram as a picture, in a light and a dark version, so it shows on shared pages and anywhere else markdown images work.

- When an agent publishes, the result lists each diagram's image links. They work a few seconds later.
- `render_diagram` draws a diagram without a document and returns its links, plus a `github_markdown` snippet that follows the reader's light or dark theme on GitHub.

Diagram images don't count towards storage.

## Workspace and project icons

A workspace can show a picture in the rail instead of its coloured letter, and a project can show one in the sidebar. Choose **Change icon…** from the workspace's or project's menu, or go to **Workspace settings → General → Icon**. Pictures are shrunk to 256 pixels square and saved with the workspace's images. Agents with **Publish and run** access can set icons with `set_workspace_icon` and `set_project_icon`.

## Storage

Each plan includes image storage:

| Plan | Included |
|---|---|
| Free | 250 MB |
| Plus | 10 GB |
| Team | 10 GB |

Who pays decides whose storage an upload uses:

- **A team's workspaces** share the team's storage, from its plan.
- **Your personal workspace** uses your personal plan's storage.

Paid plans can add storage packs of 25 GB in **Team settings → Billing** (for a team) or **Workspace settings → Billing** (for your personal plan), and change how many they have or cancel them in the same place.

When storage is full, new uploads are refused with a message that says whose storage is full and how to get more. Nothing already uploaded is removed. The same applies if a workspace changes owner or loses its paid plan and ends up over the allowance: it keeps its images but can't add more until there's room.

## Deleting an image

Deleting an image makes its link stop working everywhere, including GitHub; planpage answers that the image was deleted. Copies that browsers or GitHub's image proxy have already cached can stay visible until they expire.

The person who uploaded an image can delete it, and so can workspace owners and admins.

## Reporting an image

To report an image that breaks the rules, open [share.planpa.ge/report](https://share.planpa.ge/report) and paste its link. The person who uploaded it isn't told who reported it. planpage staff review reports; an image they take down stops working everywhere, and its link says it was removed.
