entity attach

Fügt einer bestehenden Entität eine oder mehrere Repräsentationen hinzu. Das Gegenstück zu --attach bei entity new, für den Fall, dass die Entität schon existiert und ein Asset später hinzukommt.

Ein Asset anhängen

apparat entity attach V1StGXRa ~/aufnahmen/2026-04-21-max.mp3

Pro Datei passiert dabei dasselbe wie bei entity new --attach:

1. Die Quell­datei wird nach assets/ kopiert und auf das Schema YYYY-MM-DD--slug--nanoid.ext umbenannt. Das Datum ist der Import­zeitpunkt, der Slug wird aus dem Original-Dateinamen abgeleitet, die NanoID ist frisch und einmalig.
2. Im Frontmatter der Ziel-Entität wird ein neuer Eintrag unter representations angehängt — nach den bereits vorhandenen Einträgen. Bestehende Repräsentationen bleiben unangetastet.
3. Das updated-Feld der Entität wird auf den aktuellen Zeitpunkt aktualisiert.

Mehrere Assets in einem Aufruf

Alle weiteren Positional-Argumente nach der NanoID werden als Attach-Pfade verstanden:

apparat entity attach V1StGXRa \
  ~/aufnahmen/2026-04-21-max.mp3 \
  ~/aufnahmen/2026-04-21-max.txt

Die Reihen­folge der Pfade bestimmt die Reihen­folge, in der sie ans representations-Array angehängt werden.

Kopieren vs. verschieben

Standard­mäßig kopiert Apparat die Quell­datei. Mit --move wird die Quelle nach erfolgreichem Import gelöscht:

apparat entity attach V1StGXRa ~/Downloads/bescheid.pdf --move

Das Flag wirkt auf alle Pfade eines Aufrufs.

Doppelte Inhalte werden erkannt

Vor dem Kopieren berechnet Apparat den Inhalts-Hash der Quell­datei (SHA-256) und prüft, ob im Vault bereits ein Asset mit demselben Inhalt liegt. Bei einem Treffer wird kein zweites Mal kopiert; statt­dessen verweist die neue Repräsentation auf das bestehende Asset:

✅ Attached 1 representation to entity V1StGXRa in vault "recherche".
  File: …/content/2026-04-21--maria-beispiel--V1StGXRa.md
  Reused:   2026-04-12--screenshot--Az3kLm9p.png (image/png) — already in vault as Az3kLm9p

Die Prüfung läuft pro Vault — Cross-Vault-Dedup gibt es nicht. Mit --move wird die Quell­datei trotzdem gelöscht (das ist der Sinn des Flags), nur die Asset-Datei im Vault bleibt die schon vorhandene.

Vault wählen

Ohne --vault verwendet Apparat die übliche Auflösung (CWD → einziger registrierter Vault → interaktive Auswahl). Mit --vault übersteuerst du sie:

apparat entity attach V1StGXRa aufnahme.mp3 --vault=arbeit

Fehler

• „Entity id "…" is not a valid NanoId" — das Positional-Argument muss eine 8-stellige NanoID aus [A-Za-z0-9] sein.
• „No entity with id "…" in vault "…"" — zur angegebenen NanoID existiert im Vault keine Entität.
• „At least one attachment path is required" — mindestens ein Pfad nach der NanoID ist Pflicht.
• „Attachment source "…" does not exist or is not a regular file" — der angegebene Pfad zeigt ins Leere oder auf ein Verzeichnis. Bereits in einem Batch kopierte Assets werden zurückgerollt, das Frontmatter bleibt unverändert.

Wirkung im Vault

Neue Repräsentationen werden an die bestehende Liste angehängt — die schon vorhandenen behalten ihre Reihenfolge. Der Markdown-Body bleibt unangetastet; ein eingebettetes Inline-Element zum neuen Asset setzt du bei Bedarf selbst. Externe URL-Verweise gehören nicht hierher, dafür gibt es entity external.