📎 Manage Attachments¶

The Manage Attachments panel gives you a central, cross-item overview of everything stored in your knowledge base's attachment repository — images, documents (PDF, Word, Excel, PowerPoint, plain text), and item notes. Instead of jumping from item to item to find where a specific file lives, this panel lists every stored attachment in one place and lets you attach it to (or detach it from) any item with a simple drag-and-drop.

📋 The Attachment List¶

Each entry in the list shows:

Preview: A thumbnail for images, or a small file-type icon for documents — unless a custom preview image was supplied for that file via metadata.json on import (see below), in which case that image is shown instead. Entries without a preview show no icon at all.
Name, and on hover a tooltip with the description.
Attachment count: The number on the right shows how many items (or relations) this entry is currently attached to. An entry with a count of 0 exists in the repository but is not attached anywhere yet.

Click the small ▶ arrow to expand an entry. This reveals, indented below it, every item it is currently attached to.

Clicking one of these indented rows jumps to that item in the diagram.
Clicking the ✕ next to an indented row removes just that one attachment link — the repository entry itself, and its other links, are kept.
Clicking the entry's own row (collapsed or expanded) opens a full-screen preview of its content — see Viewing an Attachment below.

🗑️ Deleting Attachments¶

There are two different ways to delete something here, and it's important to know the difference:

✕ on an indented "attached to" row: Removes only that link. The file or note stays in the repository and remains attached everywhere else.
✕ on the entry's own row: After a confirmation prompt, this permanently deletes the entry from the repository and removes it from every item it was attached to.

You can also select one or more entries (see below) and press the Delete key on your keyboard.

☑️ Selecting Multiple Entries¶

To delete several attachments in one step:

Click "Select" in the toolbar to turn on selection mode — recommended on touch devices, where the "✕" is otherwise only revealed for selected rows.
Ctrl/Cmd-click, or Shift-click for a range, to select entries directly on desktop without needing to turn on selection mode first.
With several entries selected, click the ✕ on any one of them to delete the entire selection in one combined action (a single undo step).

The same selection mechanism also works on the indented "attached to" rows, letting you detach several items from a repository entry at once.

🎯 Attaching Items via Drag-and-Drop¶

To attach an existing repository entry to an item in your diagram (in edit mode):

Click and hold an entry in the list.
Drag it onto the target item in the diagram — a connecting line follows your cursor.
Release the mouse button over the item.

Pro tip: If you have multiple entries selected, starting the drag from any one of the selected rows attaches all of them to the target item at once.

🖼️ Using an Image as the Diagram Background¶

In edit mode, hover over the row of an image: a ▨ icon appears next to the ✕. Clicking it immediately sets that image as the background of the current diagram — in the 3D view as a surrounding backdrop.

The image does not have to be attached to any item; an entry with a reference count of 0 works just as well. The route via the selection dialog is described in the chapter Formatting the Diagram.

📥 Importing New Attachments¶

Click Import in the toolbar to add new files to the repository without attaching them to any item yet — perfect for building up a library of documents that you attach to items later, exactly when you need them.

Select files, drag & drop, or paste from the clipboard — the same familiar options as the "Insert Images" dialog.
Besides image formats, you can now also import documents: PDF, Word, Excel, PowerPoint, and plain text files.
Update existing attachments: Check this option to have the import overwrite an existing entry with the same file (matched by name, or precisely by the uri field from a metadata.json file — see below) instead of creating a duplicate. All existing attachment links are preserved when an entry is updated this way.

💡 Pro Tip: Bulk-Import with `metadata.json`¶

If you select or drop a file named metadata.json together with your other files, the import dialog reads it automatically and uses it to fill in proper names and descriptions for each file — ideal for importing a whole folder of documents at once instead of ending up with raw filenames in your list.

{
    "update": true,
    "files": {
        "handbook.pdf": {
            "name": "User Handbook",
            "description": "Version 2.1, published 2026-07-01",
            "uri": "doc-handbook",
            "content": "<h1>User Handbook</h1><p>Extracted text used for the preview and for search…</p>",
            "preview": "iVBORw0KGgoAAAANSUhEUgAAAUAAAAD..."
        }
    }
}

update (optional): If true, matching files overwrite existing entries instead of creating duplicates.
name / description: Shown in the attachment list instead of the raw filename.
uri: A stable identifier used to reliably match a file to an existing entry on repeated imports — recommended whenever you plan to re-import an updated version of the same file later.
content: Extracted text (as simple HTML), used to show a readable preview for document types the browser cannot render directly, and for future full-text search.
preview (optional): A Base64-encoded PNG image shown as the entry's thumbnail in the attachment list, replacing the generic file-type icon — ideal for showing an actual screenshot of a document's content instead of just its file extension.

Pro tip: Writing a metadata.json file by hand for a whole folder of documents is tedious. The create-attachment-metadata developer skill in this repository generates it automatically — including real content-based preview images (a rendered page screenshot for PDF and Office documents where possible, or a text-excerpt preview card otherwise) and text extraction from a wide range of file types.

👁️ Viewing an Attachment¶

Clicking an entry's own row opens it in a full-screen preview, sliding in from the side:

Images open with pan & zoom.
PDF files are rendered directly in the preview.
Notes are displayed with the same formatting as in the Notes on Item panel.
Other document types (e.g. Word, Excel) show a placeholder icon — click the open icon in the top-right corner to open the original file.

Close the preview with the ✕ icon in the top-right corner.