entity meta

Bearbeitet das Frontmatter einer Entität — Typ, Sprache, Tags, eigene Felder. Der Fließtext bleibt unberührt; den kümmert sich entity edit, den Titel entity rename.

Drei Wege arbeiten zusammen:

Weg 1 — Interaktiver Walkthrough

apparat entity meta V1StGXRa

Apparat fragt nacheinander die drei Consolidation-Felder ab, jeweils mit dem aktuellen Wert als Default:

 ┌ Entity type ─────────────────────────────────────────────────┐
 │ person                                                       │
 └──────────────────────────────────────────────────────────────┘

 ┌ Document language ───────────────────────────────────────────┐
 │ de                                                           │
 └──────────────────────────────────────────────────────────────┘

 ┌ Tags (comma-separated) ──────────────────────────────────────┐
 │ wcag, kollegin                                               │
 │ Existing tags: barrierefreiheit, wcag, kollegin, berlin      │
 └──────────────────────────────────────────────────────────────┘

Wenn du einen Typ/eine Sprache oder einen Tag eingibst, der einer bestehenden kanonischen Schreibweise im Vault nahekommt (z.B. Person → person), fragt Apparat, ob du die kanonische Form übernehmen willst.

Auch ohne exakten Treffer prüft Apparat deine Eingabe auf Tippfehler und Buchstaben­dreher gegen die bestehenden Werte. Für Typ und für jeden neu eingeführten Tag erscheint eine Auswahl zwischen deinem genuinen Wert und ähnlichen Bestands­werten. Der Flag-Pfad (--set/--tag) bleibt absichtlich frei davon — Skript-Aufrufe sollen nicht durch Rückfragen unterbrochen werden, und wer die Flags benutzt, weiß in der Regel, was er will. Eine Übersicht aller Ähnlichkeits-Verfahren liegt in den Grundbegriffen.

Tags folgen Replace-Semantik: Die zurückgegebene Liste ist die neue Wahrheit. Was du aus der Liste löschst, wird entfernt. Was du ergänzt, wird hinzugefügt.

Nach den drei Prompts kommt der Abschluss:

Edit additional fields (raw YAML)? [y/N]

Mit yes wechselst du in Weg 3 (siehe unten). Mit no (oder Enter, Default) wird der Walkthrough committet.

Weg 2 — Flags

Für Skripte oder einzelne präzise Änderungen — kein Walkthrough:

# Einzelnes Feld setzen
apparat entity meta V1StGXRa --set residence=Berlin

# Mehrere Änderungen in einem Aufruf
apparat entity meta V1StGXRa \
    --set language=en-GB \
    --tag barrierefreiheit \
    --untag wcag

# Eigenes Feld entfernen
apparat entity meta V1StGXRa --unset residence

CSV-Splitting für type und tags

Wenn du --set type=... oder --set tags=... mit einer kommagetrennten Liste aufrufst, zerlegt Apparat den Wert automatisch:

apparat entity meta V1StGXRa --set type=document,concept

Produziert:

type:
  - document
  - concept

Für andere Felder bleibt der Wert ein roher String, auch wenn Kommas vorkommen.

Sobald ein Flag vorhanden ist

…läuft nur der Flag-Pfad. Der Walkthrough entfällt, --advanced ist nicht kombinierbar mit Mutations-Flags (würde sich gegenseitig ausschließen).

Weg 3 — YAML-Editor für Custom-Felder

apparat entity meta V1StGXRa --advanced

Öffnet $EDITOR (Default: nano) auf einer Tempdatei, die nur das Frontmatter enthält — ohne ----Fences, ohne Body. Beispiel:

id: V1StGXRa
type: person
created: '2026-04-19'
language: de
updated: '2026-05-10T12:00:00+00:00'
title: Maria Beispiel
tags:
  - wcag
  - kollegin
birthday: 1982-03-15
residence: Berlin

Du editierst, speicherst, schließt. Apparat parst und validiert.

Bei Validierungsfehlern: Retry-Schleife

Wenn das YAML kaputt ist oder gegen die reservierten Felder verstößt, öffnet der Editor sich erneut — mit einem kommentierten Fehler-Banner oben:

# Apparat: the frontmatter you saved did not validate.
# ERROR: line 4: unterminated single-quoted string
# Fix the errors above and save, or save an empty file to abort.
# Lines starting with `#` are stripped before parsing.

id: V1StGXRa
type: person
...

--advanced aus dem Walkthrough heraus

Wenn du im Walkthrough die Abschluss-Frage („Edit additional fields?") mit yes beantwortest, geht's genau in diesen Modus über — mit dem Unterschied, dass der Editor nicht mit dem aktuellen Frontmatter gefüllt ist, sondern mit dem post-Walkthrough-Stand. Deine Walkthrough-Entscheidungen sind also bereits sichtbar, und du editierst von dort aus weiter.

Reservierte Felder

Apparat beschützt ein paar Felder, deren Identität oder Routing-Logik kaputtgehen würde:

Feld Verhalten
id Darf nie geändert werden. Hart abgewiesen in allen drei Wegen.
updated Wird vom Backend bei jedem Schreibvorgang automatisch gesetzt. Nutzer-Eingaben werden ignoriert.
deleted Wird von entity delete gesetzt, nicht per meta. Hart abgewiesen.
title Gehört zu entity rename (beeinflusst Slug und Dateiname). Hart abgewiesen mit Hinweis.
created Ist mit dem Datumspräfix im Dateinamen gekoppelt. Hart abgewiesen.

Die Sperren gelten in allen drei Wegen gleich — flags, Walkthrough (indirekt, weil keine Prompts für reservierte Felder), YAML-Editor (Retry mit Fehler-Banner).

Shape-Validierung

Über die reservierten Felder hinaus prüft Apparat die Form des language-Werts: Er muss dem BCP-47-Subset aus der Spec entsprechen:

^[a-z]{2,3}(-[A-Z]{2})?$

Also zwei- oder dreibuchstabiger Kleinbuchstaben-Sprach­code, optional gefolgt von einem Bindestrich und einer zweibuchstabigen Region in Großbuchstaben. Gültige Beispiele: de, en, fr, de-DE, en-GB, pt-BR.

Dieselbe Regel gilt beim Anlegen per entity new — dort wird die Validierung vom EntityDraft übernommen, die Fehlermeldung sieht entsprechend aus.

Andere Felder (eigene Felder wie residence, birthday etc.) werden nicht formal geprüft — sie sind schemafrei, wie in der Spec vorgesehen. Konventions­warnungen für solche Felder (camelCase-Keys, zu lange String-Werte) werden von vault validate gemeldet.

Vault-Auswahl

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

apparat entity meta V1StGXRa --vault=arbeit --set language=en-GB
apparat entity meta V1StGXRa --vault=/home/max/vaults/recherche

Nicht-interaktiver Modus

Im --no-interaction-Modus gilt:

No metadata changes in non-interactive mode: pass --set/--unset/--tag/--untag, or use --advanced for a raw-YAML session.

Ausgabe

Nach erfolgreicher Änderung zeigt Apparat einen Diff:

Updated metadata on entity V1StGXRa in vault "recherche".
   type       person      →  concept
   language   de          →  en-GB
  +residence  Berlin
  +tag       barrierefreiheit
  -tag       wcag
  File: /home/max/projects/apparat/vaults/recherche/content/2026-04-19--maria-beispiel--V1StGXRa.md

Bei einem Aufruf ohne effektive Änderung (nur updated-Refresh) meldet Apparat das explizit:

No metadata changes on entity V1StGXRa in vault "recherche" (timestamp refreshed).

Abgrenzung zu anderen Kommandos

entity meta arbeitet ausschließlich am Frontmatter; der Body bleibt auch im YAML-Editor unangetastet. Zum Bearbeiten des Fließtexts ist entity edit zuständig, zum Ändern von Titel und Dateiname entity rename. Konventions-Warnungen aus vault validate (etwa camelCase-Keys statt snake_case) werden hier nicht automatisch korrigiert — wer aufräumen will, setzt oder entfernt die Felder gezielt. Frontmatter-Felder, die auf andere Entitäten verweisen (works_at: <NanoID>), werden wörtlich geschrieben; die Auflösung der Verlinkungen läuft im Hintergrund über den Beziehungs-Graph.

Fehler