entity import

Überführt eine Markdown-Datei in den regulären Bestand eines Vaults — egal ob die Datei extern liegt und neu aufgenommen werden soll, ob sie bereits unter content/ liegt und nicht dem Schema entspricht, oder ob eine ehemals reguläre Entität nachträglich korrumpiert wurde. Das Kommando kombiniert „Import" und „Sanierung" zu einem einzigen Fluss.

Externe Datei importieren

apparat entity import ~/recherche/max-mustermann.md

Apparat liest die Datei, analysiert Frontmatter und Body und startet einen Walkthrough durch die Pflichtfelder:

Entity type [person]:
Title [Max Mustermann]:
Created [2026-04-19]:
Document language [de]:
Tags (comma-separated, optional) [wcag]:

Jeder Wert ist mit dem vorgefüllt, was Apparat in der Quelldatei oder in Standard-Defaults (Config, Datei-mtime, erste H1) gefunden hat. Enter übernimmt, Eingabe überschreibt.

Nach Bestätigung passiert dies:

1. NanoID vergeben (frisch, falls die Quell-Datei noch keine hatte).
2. Frontmatter neu zusammengesetzt aus den Walkthrough-Werten + allen weiteren Feldern aus der Quell-Datei, die keine Pflichtfelder sind (representations, external, nutzer­definierte Keys bleiben unangetastet).
3. Datei atomar in content/ unter dem Schema-Namen YYYY-MM-DD--slug--nanoid.md geschrieben.
4. Ursprungsdatei bleibt standardmäßig liegen (Kopie-Semantik). Mit --move wird sie nach dem Import gelöscht.

Imported entity V1StGXRa in vault "recherche".
  File: /home/max/vaults/recherche/content/2026-04-19--max-mustermann--V1StGXRa.md
  From: /home/max/recherche/max-mustermann.md

Irreguläre Datei im Vault sanieren

Wenn die Datei bereits in content/ liegt, funktioniert der Aufruf genauso:

apparat entity import vaults/recherche/content/2026-04-19--broken.md

Unterschiede:

• Die Datei wird nicht kopiert, sondern umbenannt (Rename-in-Place). Nach dem Import gibt es nur eine Datei, mit Schema-konformem Namen.
• Das --move-Flag wird bei internen Quellen ignoriert — die Umbenennungs-Semantik ist die einzig sinnvolle.
• Falls die Quell-Datei bereits ein NanoID-Suffix im Namen hat (z.B. weil sie früher eine reguläre Entität war), wird diese NanoID erhalten. Das ist die Stabilitäts-Garantie aus der Spec: einmal vergebene NanoIDs bleiben ihrer Entität treu, auch durch eine Sanierung hindurch.

Korrumpierte Entität reparieren

Ein externer Editor hat dein Frontmatter zerschossen, apparat vault irregular listet die Datei als irregulär? Auch dann derselbe Aufruf:

apparat entity import content/2026-04-19--was-mal-ok-war--V1StGXRa.md

• Parst das YAML nicht mehr, fragt Apparat interaktiv („Soll der kaputte Block als Code-Fence im Body erhalten bleiben, oder verworfen werden?"). Default: erhalten — dann nichts verloren, du kannst es später manuell aufräumen.
• Alle Pflichtfelder werden neu abgefragt, mit den noch lesbaren Werten vorgefüllt.
• NanoID bleibt erhalten, Dateiname wird ggf. angepasst.

NanoID-Mismatch

Wenn der Dateiname eine andere NanoID trägt als das id-Feld im Frontmatter, meldet Apparat das als Warnung und folgt der Spec-Regel: die NanoID im Dateinamen gewinnt. Das id-Feld im Frontmatter wird beim Schreiben auf die Dateiname-NanoID gesetzt.

⚠ Filename NanoId "V1StGXRa" differs from frontmatter id "Ab12Cd34"; filename wins per spec.

Das passiert selten, aber wenn z.B. eine Datei durch einen Sync-Fehler bearbeitet wurde, erkennst du den Drift sofort.

Nicht-interaktiv (Skripte)

apparat entity import ~/recherche/max-mustermann.md \
  --type=person \
  --title="Max Mustermann" \
  --language=de \
  --no-interaction

• Jedes Pflichtfeld muss im nicht-interaktiven Modus auflösbar sein — entweder aus den Flags, aus dem Frontmatter der Quell-Datei oder aus Config-Defaults (APPARAT_DEFAULT_LANGUAGE, heute für created).
• Ist ein Pflichtfeld nicht auflösbar (typisch: --type fehlt und die Quelle hat keinen type im Frontmatter), bricht der Import mit klarer Fehlermeldung ab. Keine stille Default-Vergabe für Typ — der ist zu wichtig, um ihn zu raten.
• --tag=foo --tag=bar ersetzt die Source-Tags komplett. Ohne --tag bleiben die Tags aus dem Quell-Frontmatter erhalten.

Vault wählen

Wie bei allen Entity-Kommandos: ohne --vault übernimmt Apparat die Auflösung (CWD → einziger registrierter Vault → interaktive Auswahl), mit --vault= kannst du explizit setzen.

apparat entity import ~/recherche/max-mustermann.md --vault=arbeit

Fehler

• „Import source "…" does not exist or is not a regular file" — der Pfad ist kein lesbares File (Verzeichnis, kaputter Symlink, existiert gar nicht).
• „--type is required in non-interactive mode when the source has no type" — im nicht-interaktiven Modus ohne Type-Flag und ohne type im Frontmatter kann Apparat keinen Typ raten; siehe Pflicht-Argument oder interaktiv aufrufen.
• „Entity "language" must match BCP-47 subset" — --language muss ^[a-z]{2,3}(-[A-Z]{2})?$ erfüllen, z.B. de, en-GB.
• „NanoId "…" is already taken by "…" — import would collide" — die Quell-NanoID existiert bereits im Vault als andere Datei. Wahrscheinlich ein Duplikat-Import; Quelle prüfen.
• „Refusing to overwrite existing file "…"" — die berechnete Zieldatei existiert schon (z.B. weil Datum+Slug+Id-Kombination durch einen älteren Import belegt ist).

Wirkung im Vault

entity import interpretiert den Body nicht inhaltlich — Markdown-Syntax, Links und eingebettete Bilder bleiben exakt wie in der Quelle. Den Typ wählst du bewusst selbst — Apparat versucht keine automatische Erkennung. Netzwerkzugriff findet nicht statt: externe URLs oder Bilder im Body werden nicht heruntergeladen.