# Attachments

Attachments live on a page and are referenced by filename. They survive page
moves and template changes, but they do not survive page deletion.

## Upload via mcp-atlassian

```python
mcp__atlassian.confluence_upload_attachment(
    pageId=…,
    filePath="path/to/file.png",
    comment="optional version note",
)
```

Returns a metadata object including the download URL. Use that URL inside the
page body, not a local file path.

## Reference in the body

By attachment filename:

```xml
<ac:link>
  <ri:attachment ri:filename="diagram.png" />
  <ac:plain-text-link-body><![CDATA[diagram]]></ac:plain-text-link-body>
</ac:link>
```

As an inline image:

```xml
<ac:image ac:width="600">
  <ri:attachment ri:filename="diagram.png" />
</ac:image>
```

Always set `ac:alt` for accessibility:

```xml
<ac:image ac:width="600">
  <ri:attachment ri:filename="diagram.png" />
  <ac:alt>Sequence diagram of the order → inventory → shipment flow.</ac:alt>
</ac:image>
```

## What NOT to do

- Don't paste base64 PNG into the body. The page editor can't replace it
  without re-rendering the whole page; it bloats the storage body; the page
  cannot be reviewed by lint.
- Don't link to a public CDN. BASS pages are private; CDN URLs leak and break
  on access-controlled spaces.
- Don't re-upload the same file under a new name. Confluence deduplicates by
  hash within a page, but the editor doesn't surface duplicates well.

## Versioning

Attach with a version suffix (`diagram-v2.png`) when updating. Confluence
keeps the old version in the attachments list and the page body continues to
reference the filename; change the filename in the body to point at the new
version.

## Cleanup

Pages with stale attachments show up in the space's attachment report. When
removing a diagram, also remove the attachment (do not leave orphaned files
on the page).