docs: Theme Builder guide, instructions, readme and spec for 0.5.0

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/guides/divi-library.md

@@ -33,8 +33,25 @@ Die Divi-Bibliothek speichert Layouts, Abschnitte, Zeilen und Module zur Wiederv
 - `lit/library-save`: einen Abschnitt, eine Zeile oder ein Modul als neuen Eintrag speichern (`post_id`,
   `tree_rev`, Pfad-ID `id`, `title`, `scope: "normal"` oder `"global"`, vorhandene `categories`/`tags`). Der
   Knoten auf der Seite bleibt eine eigenständige Kopie – um ihn zu verknüpfen, ihn durch eine Instanz
-  ersetzen (siehe Ablauf unten). Ein Knoten, der selbst ein globales Modul ist oder eines enthält, lässt sich
-  nicht als globaler Eintrag speichern.
+  ersetzen (siehe Ablauf unten). Ein Knoten, der selbst ein globales Modul ist oder auf einen Eintrag verweist
+  (auch als Divi-4-Shortcode mit `global_module` in einem Text), lässt sich nicht als globaler Eintrag speichern.
+- `lit/library-find-similar`: Knoten finden, die wie ein Knoten (`post_id` und `id`) oder ein Eintrag
+  (`library_id`) aufgebaut sind. `match: "identical"` = gleicher Inhalt einschließlich aller Texte (nur
+  Admin-Labels ausgenommen), `"structure"` = gleicher Aufbau (Modultypen, Spalten, Presets) mit anderen Inhalten.
+  Durchsucht werden Einträge der Divi-Inhaltstypen (optional nur `post_type`), nie Bibliothekseinträge oder
+  Theme-Builder-Layouts; nur Einträge, die das Konto bearbeiten darf. Höchstens 200 Einträge je Aufruf
+  (`limit`), weiter mit `next_cursor`; bei sehr vielen Treffern endet ein Aufruf früher und sagt das in `note`.
+  Jeder Treffer nennt `tree_rev`.
+- `lit/library-make-global`: einen Knoten einer Seite oder eines Beitrags in ein globales Modul umwandeln
+  (`post_id`, `tree_rev`, `id`, `title`, optional `categories`/`tags`): neuer globaler Eintrag mit genau diesem
+  Inhalt, der Knoten wird durch die Instanz ersetzt – alles oder nichts. Weitere, inhaltsgleiche Vorkommen
+  ersetzen: `library_id` und `targets` (je `post_id`, `tree_rev`, `ids` der Treffer `"identical"`; höchstens 20
+  Seiten). Alle Ziele werden vorher geprüft; ohne `confirm` ist das ein Probelauf (`confirm_required` mit
+  `affected`), dann `confirm: true`. Jede Seite bekommt eine Revision (`pages`). Nur Seiten und Beiträge
+  (Inhaltstypen `page` und `post`), die das Konto bearbeiten darf – keine Bibliothekseinträge und keine
+  Theme-Builder-Layouts, auch nicht als Quelle. Knoten, die auf einen Eintrag verweisen, werden kein globales
+  Modul. Schlägt eine Seite fehl, bleiben die vorher ersetzten Seiten ersetzt (je mit Revision), die übrigen
+  unverändert; der Fehler nennt alle drei Gruppen (`changed_posts`, `failed_post`, `unchanged_posts`).
 - `lit/divi-node-copy`: einen Knoten von einem Eintrag an eine Position eines anderen kopieren
   (`source_post_id`, `source_id`, `source_tree_rev` aus `lit-divi-outline` der Quelle – Pflicht, weil
   Pfad-IDs nur für diesen Stand gelten; Ziel mit `post_id`, `tree_rev`, Position). Quelle und Ziel dürfen
@@ -84,6 +101,9 @@ wird leer; ein globaler Eintrag enthält keine globalen Module. Nur aktive Eintr
 `lit-page-render-summary` zeigt globale Module nicht (über die Schnittstelle rendert Divi sie nicht) und nennt
 sie in `notes`; ihren Inhalt mit `lit-divi-outline` und der ID lesen.
 
+Fügt eine Divi-Änderung einen Abschnitt ein, der wie ein Abschnitt der Bibliothek aufgebaut ist, nennt
+`warnings` den Eintrag – dann `lit-library-insert` erwägen.
+
 ## Rechte
 
 - WordPress: die Bibliothek nutzen = Beiträge bearbeiten dürfen; einen Eintrag lesen oder ändern = diesen
@@ -96,10 +116,8 @@ sie in `notes`; ihren Inhalt mit `lit-divi-outline` und der ID lesen.
   Hinweis.
 - Einstellungen → LIT MCP → Tools: Gruppe „Divi-Bibliothek“ auf „nur lesen“ sperrt jeden Schreibzugriff auf
   Bibliothekseinträge, auch über die Divi-Werkzeuge; deaktiviert gilt jeder Eintrag als nicht vorhanden.
-  Grenze: Die Einträge selbst sind dann nicht lesbar und nicht änderbar, aber `lit-divi-outline`,
-  `lit-divi-node-get` und `lit-page-render-summary` einer Seite nennen die ID eines dort verwendeten globalen
-  Moduls weiterhin (auch ohne das Recht „Divi-Bibliothek“). Diese ID mit den Divi-Werkzeugen zu öffnen,
-  antwortet `not_found`; dann nicht weiter versuchen.
+  Ohne das Recht „Divi-Bibliothek“ oder mit deaktivierter Gruppe nennen `lit-divi-outline`, `lit-divi-node-get`
+  und `lit-page-render-summary` globale Module nur als solche, ohne ihre ID.
   `lit-library-insert` und `lit/divi-node-copy` sind außerdem gesperrt, wenn `lit-divi-insert` gesperrt ist;
   `lit/divi-node-copy` mit einem Bibliothekseintrag als Quelle auch, wenn `lit-library-insert` gesperrt ist.
 - Ohne das Recht `unfiltered_html` überträgt LIT MCP beim Kopieren, Einfügen und Speichern (`lit/divi-node-copy`,
@@ -113,13 +131,12 @@ sie in `notes`; ihren Inhalt mit `lit-divi-outline` und der ID lesen.
 
 ## Ablauf: globale Module vorschlagen
 
-1. Die Seiten lesen (`lit-divi-outline`) und wiederkehrende Abschnitte suchen (gleiche Admin-Labels oder
-   Texte, z. B. Kontakt, Öffnungszeiten, Call-to-Action).
-2. Dem Nutzer vorschlagen, welche davon globale Module werden sollen, und erklären: eine Änderung wirkt
-   danach auf allen Seiten.
-3. Nach Zustimmung den Abschnitt einer Seite mit `lit/library-save` und `scope: "global"` speichern.
-4. Auf jeder Seite (auch der ersten) die Instanz mit `lit-library-insert` direkt vor dem bisherigen Abschnitt
-   einfügen und den bisherigen Abschnitt nach Rückfrage mit `lit-divi-delete` entfernen.
+1. Wiederkehrende Abschnitte suchen: `lit/library-find-similar` mit einem typischen Abschnitt (`post_id`, `id`)
+   – z. B. Kontakt, Öffnungszeiten, Call-to-Action.
+2. Dem Nutzer die Treffer zeigen und erklären: eine Änderung wirkt danach auf allen Seiten mit dem Modul.
+   Treffer mit `match: "structure"` unterscheiden sich im Inhalt – vorher klären, welche Fassung gilt, und die
+   übrigen angleichen (`lit-divi-update`) oder weglassen.
+3. Nach Zustimmung `lit/library-make-global` mit dem gewählten Abschnitt.
+4. Die inhaltsgleichen Vorkommen mit `lit/library-make-global` (`library_id`, `targets` mit der `tree_rev` aus
+   `lit/library-find-similar`) ersetzen: Probelauf zeigen, dann `confirm: true`.
 5. Den Nutzer bitten, das Ergebnis im Divi-Builder anzusehen.
-
-Unterscheiden sich die Abschnitte in Details, vorher mit dem Nutzer klären, welche Fassung gilt.