asset embed

Importiert eine Datei in den assets/-Ordner deines Vaults und gibt im Anschluss den passenden Markdown-Ausdruck ![alt](../assets/<datei>) auf der Standardausgabe aus. Den Ausdruck pastest du an die Stelle in der Entität, an der das Bild oder das Video erscheinen soll.

Das Kommando ist die Werkzeugschiene für Beilagen im Fließtext — Fotos in einem Reise-Eintrag, Diagramme in einem Konzeptpapier, ein eingebettetes Video in einer Vortragsnotiz. Für formale Repräsentationen einer Entität (z.B. ein Audio-Mitschnitt, der den Primärinhalt eines Interviews ausmacht) gibt es weiterhin entity attach; die beiden Wege schließen einander aus.

Einfachster Fall

apparat asset embed ~/screenshots/diagramm.png --alt="Architekturskizze"

Apparat:

kopiert die Quelldatei nach assets/,
benennt sie auf das Schema YYYY-MM-DD--<slug>--<id>.<ext> um (Datum = heute, Slug aus dem Originaldateinamen),
gibt eine einzige Zeile auf der Standardausgabe aus:

![Architekturskizze](../assets/2026-05-10--diagramm--Az3kLm9p.png)

Diese Zeile kopierst du in den Body der Entität, an die das Bild gehört. Der relative Pfad ../assets/... greift aus jeder Datei in content/ korrekt — er ist also entitäts-unabhängig.

Eine Datei pro Aufruf

asset embed arbeitet immer auf einer einzigen Quelldatei. Mehrere Bilder importierst du als getrennte Aufrufe; das hält den Output pro Aufruf eindeutig (genau eine Markdown-Zeile) und passt zu typischen Editor-Workflows, in denen du genau einen Ausdruck pasten willst.

Inhalts-Identität: dieselbe Datei wird nicht doppelt importiert

Importierst du dieselbe Datei (genauer: denselben Inhalt) ein zweites Mal — etwa weil du dieselbe Skizze in einer zweiten Notiz einbetten willst — erkennt Apparat das anhand des Dateiinhalts und überspringt das Kopieren. Du bekommst denselben Pfad zurück wie beim ersten Aufruf:

apparat asset embed ~/screenshots/diagramm.png --alt="Architekturskizze für die Konzeptseite"
# ![Architekturskizze für die Konzeptseite](../assets/2026-05-10--diagramm--Az3kLm9p.png)

Damit darf dasselbe Asset in beliebig vielen Entitäten als Beilage auftauchen, ohne dass der Vault unter Duplikaten anschwillt. Der Alt-Text wird pro Aufruf neu gesetzt — er ist kontextspezifisch und gehört zur einbettenden Entität, nicht zum Asset.

Alt-Text ist Pflicht

Das Inline-Embedding-Format verlangt einen nicht-leeren Alt-Text. Ohne Alt-Text bricht das Kommando ab; im interaktiven Modus promptet es:

 ┌ Alt text for the embed link ────────────────────
 │ Architekturskizze für die Konzeptseite
 └──────────────────────────────────────────────────

In Skripten oder bei --no-interaction musst du --alt="..." explizit angeben:

apparat asset embed ~/screenshots/diagramm.png --alt="Architekturskizze" --no-interaction

Fehlt das Flag im nicht-interaktiven Modus, meldet Apparat:

❌ --alt is required in non-interactive mode (an inline embed must have a non-empty alt text).

Begründung: ein leerer Alt-Text ist nicht nur ein Stilproblem, sondern auch ein Barrierefreiheitsfehler — die Beilage ist ohne Beschreibung für rein-textliche Auswertungen (Suche, Export, Screen-Reader) verloren. Das Kommando erzwingt den Alt-Text, damit du nicht später per vault validate darauf gestoßen wirst.

Quelle löschen statt kopieren

asset embed kopiert standardmäßig — die Originaldatei bleibt liegen. Mit --move löscht Apparat sie nach erfolgreichem Import:

apparat asset embed ~/Downloads/diagramm.png --alt="Architekturskizze" --move

Praktisch beim Import aus einem temporären Download-Ordner, in dem die Datei nach dem Vault-Eintrag nichts mehr verloren hat.

Typischer Workflow

# Editor offen, Cursor an der Stelle, an der das Bild erscheinen soll.
# In einem zweiten Terminal:
apparat asset embed ~/Pictures/2026-05-10-IMG_4231.jpg \
  --alt="Blick von der Großhesseloher Brücke nach Süden" \
  | xclip -selection clipboard

# Zurück in den Editor, Strg-V — fertig.

Auf macOS ersetzt pbcopy das xclip. Wer ohne Clipboard-Tool arbeitet, kopiert die Zeile aus dem Terminal von Hand.

Vault-Auswahl

Wie bei allen Kommandos: ohne --vault greift die übliche Auto-Lokalisierung (CWD-Erkennung, einziger registrierter Vault, interaktive Auswahl). Explizit:

apparat asset embed ~/screenshots/diagramm.png --alt="…" --vault=recherche
apparat asset embed ~/screenshots/diagramm.png --alt="…" --vault=/home/max/vaults/recherche

Fehler

„--alt is required in non-interactive mode (an inline embed must have a non-empty alt text)." — --no-interaction ist gesetzt und --alt fehlt oder ist leer. Flag ergänzen.
„Attachment source "…" does not exist or is not a regular file." — die übergebene Quelldatei existiert nicht oder ist ein Verzeichnis/Symlink-Ziel ohne Datei. Pfad prüfen.
„Attachment source "…" is not readable." — Apparat darf die Datei nicht öffnen (Berechtigungsproblem). Dateirechte oder Vault-Mount prüfen.

Wirkungsbereich

Das Kommando schreibt ausschließlich in den assets/-Ordner des gewählten Vaults. Es fasst keine Entitätsdatei an — der Markdown-Ausdruck landet auf der Standardausgabe, der Body deiner Entität bleibt unter deiner Hand. Wer dasselbe Asset auf mehreren Entitäten einbetten will, ruft asset embed (oder pastet den Ausdruck aus dem ersten Aufruf) so oft, wie nötig — die Inhalts-Identität sorgt dafür, dass Apparat die Datei nur einmal speichert.