docs: name tools and error codes the way the client sees them

Indirect abilities are written lit/<name> (via mcp-adapter-execute-ability) in guides, descriptions and hints, direct tools lit-<name>; guides use the client-visible codes (write_failed, partial_write) and say exactly which tools return a revision_id. ToolNamingTest keeps guides and sources consistent with Ability::isDirect() and checks the overview's direct-tool list. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7
2026-09-26 01:28:18 +02:00
parent b3c9109e47
commit fea75b03d6
19 changed files with 186 additions and 55 deletions
@@ -1,5 +1,8 @@
 # Inhalte, Felder und Status

+Werkzeugnamen: `lit-…` sind direkt aufrufbare Tools; `lit/…` sind Abilities, die über
+`mcp-adapter-execute-ability` (Name in `ability_name`, Eingaben in `parameters`) aufgerufen werden.
+
 ## Inhaltstypen erkennen

 - `lit-content-types` ohne Parameter listet alle Inhaltstypen (Seiten, Beiträge, eigene Typen) mit
@@ -32,20 +35,27 @@
 - Begriffe: `terms: {"category": [4, "Neuer Begriff"]}` ersetzt die Zuordnung dieser Taxonomie (IDs oder
  Namen; unbekannte Namen werden angelegt, falls erlaubt).
 - Felder leeren: Wert `null`. Pflichtfelder können nicht geleert werden.
- Beziehungsfelder erwarten Eintrags-IDs, Datei-/Bildfelder Anhang-IDs aus der Mediathek.
+- Beziehungsfelder erwarten IDs von Einträgen, die der Nutzer lesen darf; Datei-/Bildfelder Anhang-IDs aus der
+  Mediathek.
+- Einträge im Papierkorb werden nicht geändert (auch nicht veröffentlicht, geplant oder wiederhergestellt);
+  zuerst in WordPress aus dem Papierkorb holen.
+- Ist ein geplanter Eintrag über seinen Veröffentlichungszeitpunkt hinaus (verpasster Termin), würde jedes
+  Speichern ihn sofort veröffentlichen – `lit-content-update`, `lit/revision-restore` und
+  `lit/post-replace-with-copy` verweigern das dann. Mit dem Nutzer klären: jetzt veröffentlichen
+  (`lit-post-publish`) oder neu planen (`lit/post-schedule`).

 ## Status

- Veröffentlichen, Zurückziehen und Planen sind eigene Werkzeuge (`lit-post-publish`, `lit-post-unpublish`,
-  `lit-post-schedule` mit `date` = „JJJJ-MM-TT HH:MM“ in der Zeitzone der Website). Nur auf ausdrücklichen
+- Veröffentlichen, Zurückziehen und Planen sind eigene Werkzeuge (`lit-post-publish`, `lit/post-unpublish`,
+  `lit/post-schedule` mit `date` = „JJJJ-MM-TT HH:MM“ in der Zeitzone der Website). Nur auf ausdrücklichen
  Wunsch des Nutzers verwenden.
- `lit-post-trash` legt in den Papierkorb (nie endgültig) und braucht `confirm: true` nach Rückfrage.
+- `lit/post-trash` legt in den Papierkorb (nie endgültig) und braucht `confirm: true` nach Rückfrage.

 ## Sicher überarbeiten

-1. `lit-post-duplicate` → Entwurfskopie; die Antwort enthält die `rev` der Kopie für `lit-content-update`.
+1. `lit/post-duplicate` → Entwurfskopie; die Antwort enthält die `rev` der Kopie für `lit-content-update`.
 2. Kopie mit `lit-content-update` (oder den Divi-Tools) bearbeiten und dem Nutzer die Vorschau zeigen.
-3. `lit-post-replace-with-copy` übernimmt die Kopie ins Original (ID, URL, Status und Menüeinträge bleiben).
+3. `lit/post-replace-with-copy` übernimmt die Kopie ins Original (ID, URL, Status und Menüeinträge bleiben).
   Voraussetzungen: die Kopie muss noch Entwurf oder ausstehend sein, `rev` des Originals aus
   `lit-content-get` ist Pflicht (sie deckt Titel, Inhalt, Auszug und Status ab – Felder/Meta, die direkt am
   Original geändert wurden, werden dabei überschrieben), und erst nach Rückfrage mit `confirm: true`
@@ -53,14 +63,16 @@
   Papierkorb (`backup_id` in der Antwort); danach wandert die Kopie ebenfalls in den Papierkorb. Ist der
   Papierkorb der Website deaktiviert, wird der Austausch verweigert, statt die Kopie endgültig zu löschen.

-Jede Änderung liefert `revision_id` (Stand vorher) und `log_id`. Rückgängig: `lit-revisions-list` →
-`lit-revision-restore` mit der `rev` des Eintrags (aus `lit-content-get`) und `confirm: true`. Revisionen
-umfassen Titel, Inhalt und Auszug – Felder und Begriffe nicht.
+Jede Änderung liefert `log_id`. Eine `revision_id` (Revision mit dem Stand vorher) liefern nur
+`lit-content-update`, `lit/post-replace-with-copy` und `lit/revision-restore`; bei allen anderen Tools ist sie
+`null`. Rückgängig: `lit/revisions-list` → `lit/revision-restore` mit der `rev` des Eintrags (aus
+`lit-content-get`) und `confirm: true`. Revisionen umfassen Titel, Inhalt und Auszug – Felder und Begriffe
+nicht (dafür bei `lit/post-replace-with-copy` die Sicherung `backup_id`).

 ## Wenn ein Schreibvorgang fehlschlägt

-Schlägt ein Schreibvorgang nach ersten Änderungen fehl, meldet das Tool `lit_write_failed` (alles wurde
-zurückgenommen, nichts wurde gespeichert) oder `lit_partial_write` (die Rücknahme war unvollständig). Beide
-Fehler stecken als JSON (`code`, `message`, `hint`, ggf. weitere Felder) in der Fehlermeldung. Bei
-`lit_partial_write` vor einem erneuten Versuch immer erst den aktuellen Stand prüfen (`lit-content-get`,
-`lit-menu-get` o. Ä.) statt den Aufruf einfach zu wiederholen – dem `hint` folgen.
+Fehler stecken als JSON (`code`, `message`, `hint`, ggf. weitere Felder) in der Fehlermeldung. Schlägt ein
+Schreibvorgang nach ersten Änderungen fehl, ist `code` = `write_failed` (alles wurde zurückgenommen, nichts
+wurde gespeichert) oder `partial_write` (die Rücknahme war unvollständig). Bei `partial_write` vor einem
+erneuten Versuch immer erst den aktuellen Stand prüfen (`lit-content-get`,
+`lit/menu-get` o. Ä.) statt den Aufruf einfach zu wiederholen – dem `hint` folgen.
@@ -20,7 +20,8 @@ des verbundenen WordPress-Benutzers.
 Direkt sichtbar: `lit-guide`, `lit-site-status`, `lit-content-types`, `lit-content-query`,
 `lit-content-get`, `lit-content-create`, `lit-content-update`, `lit-post-publish`.

-Über `mcp-adapter-discover-abilities` / `mcp-adapter-execute-ability` (Ability-Namen `lit/…`):
+Über `mcp-adapter-discover-abilities` / `mcp-adapter-execute-ability` (Ability-Namen `lit/…`; in Guides und
+Hinweisen immer so geschrieben):
 Status (`lit/post-unpublish`, `lit/post-schedule`, `lit/post-trash`), Kopien (`lit/post-duplicate`,
 `lit/post-replace-with-copy`), Revisionen (`lit/revisions-list`, `lit/revision-restore`), Menüs
 (`lit/menu-list`, `lit/menu-get`, `lit/menu-create`, `lit/menu-set-items`, `lit/menu-assign-location`),
@@ -30,6 +31,8 @@ Weitere Themen: `lit-guide` mit `topic` = `content-types` oder `workflows`.

 ## Rückmeldungen

- Erfolg: `ok`, `summary`, `changed`, `warnings`, `revision_id` (Stand vorher), `log_id`, URLs.
- Fehler: JSON mit `code`, `message`, `hint` (und ggf. `fields`). Dem `hint` folgen.
+- Erfolg: `ok`, `summary`, `changed`, `warnings`, `rev`, `revision_id` (Revision mit dem Stand vorher, nur bei
+  Tools, die Inhalt überschreiben, sonst `null`), `log_id`, URLs.
+- Fehler: JSON mit `code` (z. B. `validation_failed`, `rev_mismatch`, `write_failed`, `partial_write`),
+  `message`, `hint` (und ggf. `fields`). Dem `hint` folgen.
 - `confirm_required`: Nutzer fragen, dann mit `confirm: true` wiederholen.
@@ -3,18 +3,18 @@
 ## Neue Website aufsetzen

 1. `lit-site-status` und `lit-content-types` lesen.
-2. Grundeinstellungen: `lit-wp-settings-get`, dann `lit-wp-settings-update` (Titel, Untertitel, Sprache,
+2. Grundeinstellungen: `lit/wp-settings-get`, dann `lit/wp-settings-update` (Titel, Untertitel, Sprache,
   Zeitzone, Datumsformat, Permalinks `/%postname%/`). `previous` in der Antwort enthält die alten Werte.
 3. Seiten als Entwürfe anlegen (`lit-content-create`), Hierarchie über `parent`.
 4. Startseite: Seite veröffentlichen (nach Rückfrage), dann
   `{"settings": {"page_on_front": <ID>, "show_on_front": "page"}}`.
-5. Menü: `lit-menu-create` (optional mit `location` aus `lit-menu-list`), Einträge mit `lit-menu-set-items`.
+5. Menü: `lit/menu-create` (optional mit `location` aus `lit/menu-list`), Einträge mit `lit/menu-set-items`.
 6. Veröffentlichen erst, wenn der Nutzer es ausdrücklich möchte.

 ## Menüs pflegen

- `lit-menu-get` liefert den Baum. Für größere Umbauten den Baum verändern und vollständig als `items` an
-  `lit-menu-set-items` senden (bestehende Einträge mit `id`, neue ohne `id`). Wird der Baum unverändert
+- `lit/menu-get` liefert den Baum. Für größere Umbauten den Baum verändern und vollständig als `items` an
+  `lit/menu-set-items` senden (bestehende Einträge mit `id`, neue ohne `id`). Wird der Baum unverändert
  zurückgeschickt, meldet das Tool „keine Änderung“ und schreibt nichts.
 - Für kleine Änderungen `operations`: `{op: "add", item, parent_id?, position?}`,
  `{op: "move", id, parent_id?, position?}`, `{op: "remove", id}` (Kinder eines entfernten Eintrags rücken