entity unlink

Entfernt eine einzelne Beziehungs-Kante im Frontmatter der Quell-Entität. Das ist das symmetrische Gegenstück zu entity link: ein gezielter Eingriff, der genau einen Eintrag unter einer Relation wegstrickt, ohne andere Kanten oder die Ziel-Entität anzutasten.

Grundaufruf

apparat entity unlink V1StGXRa Qw9pLm2n --rel=works_at

Apparat liest das Frontmatter von V1StGXRa, sucht unter works_at den Eintrag mit target: Qw9pLm2n, und entfernt ihn:

• Bleiben danach zwei oder mehr Einträge unter works_at übrig, behält Apparat die Liste mit den verbleibenden Einträgen.
• Bleibt ein Eintrag übrig, wird der als Top-Level-Mapping geschrieben (Langform).
• Bleibt kein Eintrag übrig, wird der works_at-Schlüssel komplett aus dem Frontmatter entfernt.

Das updated-Feld wird bei jedem erfolgreichen Aufruf auf den aktuellen Zeitpunkt aktualisiert.

Automatische Disambiguierung

Wenn du --rel weglässt, sucht Apparat in allen Relations-Feldern der Quell-Entität nach Einträgen, deren target auf die angegebene Ziel-NanoID zeigt — und wählt automatisch aus, wenn nur eine Relation passt:

apparat entity unlink V1StGXRa Qw9pLm2n
# → findet `works_at` als einzigen Kandidaten → entfernt dort die Kante

Gibt es mehrere Kandidaten (z.B. jemand steht unter knows und collaborates_with auf derselben Person), zeigt Apparat interaktiv eine Auswahl:

 ┌ Which relation should the edge be removed from?
 │ ● knows
 │ ○ collaborates_with

Im nicht-interaktiven Modus bricht Apparat mit einer Fehlermeldung ab und zählt die Kandidaten auf — du setzt dann --rel explizit.

Fehlende Kante

apparat entity unlink V1StGXRa Qw9pLm2n
# → ❌ Entity "V1StGXRa" has no relation linking to "Qw9pLm2n".

entity unlink bricht mit einem klaren Fehler ab, wenn die Quell-Entität überhaupt keine Kante zum Ziel hat. Das ist Absicht — stillschweigendes Nichts-Tun würde dich bei Tipp­fehlern nicht schützen.

Vault wählen

Wie üblich — ohne --vault übernimmt Apparat die Auflösung (CWD → einziger registrierter Vault → interaktive Auswahl), mit --vault=… explizit:

apparat entity unlink V1StGXRa Qw9pLm2n --rel=works_at --vault=arbeit

Fehler

• „Source/Target entity id "…" is not a valid NanoId" — beide Positional-Argumente müssen 8-stellige NanoIDs aus [A-Za-z0-9] sein.
• „No source entity with id "…" in vault "…"" — zur Quell-NanoID gibt es keine Entität im Vault.
• „Entity "…" has no relation linking to "…"" — die Quelle hat aktuell keine Kante, deren Target auf die Ziel-NanoID zeigt. Kein Edge zum Entfernen.
• „--rel "…" does not match any relation linking to the target" — der explizit angegebene Relations-Key enthält keine Kante zu diesem Ziel; die Fehlermeldung listet die tatsächlich passenden Kandidaten auf.
• „Multiple relations link to the target; pass --rel to disambiguate" — nicht-interaktiv, mehrere Kandidaten. --rel=<name> setzen.
• „Entity "…" does not link to "…" via relation "…"" — Konsistenz-Fehler (z.B. wenn die Datei zwischen Kandidaten-Scan und Schreiben von außen geändert wurde).

Wirkung im Vault

entity unlink ändert ausschließlich das Frontmatter der Quell-Entität — die Zielentität bleibt unverändert; eine umgekehrt gerichtete Beziehung wird nicht automatisch mit entfernt. Wenn mehrere Beziehungen auf dasselbe Ziel zeigen, gibst du jeweils per --rel an, welche du lösen willst. Asset-Verweise zählen nicht als Beziehungen — die löst du über entity detach.