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/theme-builder.md

@@ -0,0 +1,117 @@
+# Divi Theme Builder
+
+Der Theme Builder legt fest, wie Kopfzeile, Inhalt und Fußzeile für bestimmte Seiten aussehen – z. B. für alle
+Einträge eines eigenen Inhaltstyps. Eine **Vorlage** hat Bedingungen („gilt für alle Personen“) und bis zu drei
+**Layouts** (Kopfzeile, Inhalt, Fußzeile). Die **Standardvorlage** gilt überall, wo keine andere greift; ihre
+Kopf- und Fußzeile heißen „global“, weil andere Vorlagen sie mitbenutzen.
+
+## Grundregel: nichts wird ohne Freigabe sichtbar
+
+- Neue Vorlagen legt LIT MCP immer **deaktiviert** an – Besucher sehen nichts davon.
+- Aktivieren und Deaktivieren gibt es nur mit `lit/tb-activate`, und immer so: Probelauf (Bedingungen, Layouts,
+  andere aktive Vorlagen mit denselben oder verwandten Bedingungen unter `overlaps`/`possible_overlaps`) →
+  Nutzer fragen → dieselbe Anfrage mit `confirm: true`.
+- Auch alles andere, was Besucher sofort sähen, ist zuerst ein Probelauf (`confirm_required`) und braucht
+  `confirm: true`: Bedingungen einer aktiven Vorlage ändern (`lit/tb-assign`) und ein Layout ändern, das eine
+  aktive Vorlage zeigt (die `lit-divi-…`-Werkzeuge; die Antwort nennt die Vorlagen unter `templates`). Vor dem
+  Speichern eines sichtbaren Layouts entsteht eine Revision; sind Revisionen abgeschaltet, eine
+  Sicherungskopie im Papierkorb (`backup_id`).
+- `lit/divi-replace-text` ändert sichtbare Layouts nicht; solche Änderungen mit `lit-divi-update` und
+  `confirm: true` vornehmen.
+- Die Standardvorlage ändert LIT MCP nicht (nur im Theme Builder).
+
+## Werkzeuge (über `mcp-adapter-execute-ability`)
+
+- `lit/tb-list`: alle Vorlagen mit `enabled`, `live` (für Besucher wirksam), Bedingungen (`use_on`,
+  `exclude_from` und Beschriftungen), Layouts (`id`, Titel, `shared_with` = andere Vorlagen mit demselben
+  Layout) und `template_rev`. `template_id`: nur diese Vorlage. `conditions: true` liefert alle Bedingungen,
+  die Divi anbietet; eine ID, die auf „:“ endet, braucht ein Objekt am Ende, z. B.
+  `singular:post_type:page:id:42`. `detached` zeigt Vorlagen, die ein Speichern im Theme Builder entfernt hat
+  (siehe unten); `draft_pending` zeigt ungespeicherte Änderungen im Theme Builder.
+- `lit/tb-create-template`: `title`, je Bereich (`header`, `body`, `footer`) `source`:
+  `"new"` (neues Layout; optional `nodes` wie bei `lit-divi-insert` und `title`), `"global"` (Kopf-/Fußzeile
+  der Standardvorlage mitbenutzen; nicht für `body`), `"default"` (nichts Eigenes, Standard bei fehlender
+  Angabe) oder `"hidden"` (Bereich ausblenden). Optional `use_on`/`exclude_from`. Alles oder nichts: schlägt
+  ein Schritt fehl, entfernt LIT MCP alles wieder. Antwort: `template_id`, `template_rev`, `enabled: false`,
+  `layouts`.
+- `lit/tb-assign`: Bedingungen ersetzen (`template_id`, `template_rev`, `use_on`). Fehlt `exclude_from`,
+  bleiben die bisherigen Ausnahmen; `[]` entfernt sie. Der Probelauf einer aktiven Vorlage zeigt vorher/nachher
+  (`before`, `after`) und Überschneidungen. Die Antwort nennt die bisherigen Bedingungen unter `previous`.
+- `lit/tb-activate`: `enabled: true` oder `false` (`template_id`, `template_rev`). Deaktivieren ist der
+  schnelle Weg zurück. Zum Aktivieren müssen alle Layouts der Vorlage noch aktiv sein.
+- Layouts bearbeiten: `lit-divi-outline`, `lit-divi-node-get`, `lit-divi-insert`, `lit-divi-update`,
+  `lit-divi-move`, `lit-divi-delete` … mit der Layout-ID als `post_id` (aus `lit/tb-list`). Benutzt eine
+  andere Vorlage dasselbe Layout (`shared_with`), wirkt die Änderung auch dort. Das Modul „Beitragsinhalt“
+  (`post-content`) gibt es nur im Inhalt-Layout, nicht in Kopf- oder Fußzeile.
+
+## Bedingungen
+
+Erlaubt sind nur die Bedingungen, die Divi selbst anbietet (`lit/tb-list` mit `conditions: true`), höchstens 50
+je Liste. Ein Objekt am Ende (Seite, Beitrag, Begriff, Person) muss existieren und für das Konto lesbar bzw.
+zuweisbar sein; sonst lautet die Antwort wie bei einer unbekannten ID. Bedingungen für Autoren
+(`archive:user:id:…`) verlangen das Recht, Benutzer aufzulisten (`list_users`) – strenger als Divi.
+
+## Felder im Inhalt-Layout (Dynamic Content)
+
+Im Inhalt-Layout zeigen Platzhalter die Daten des jeweiligen Eintrags: `{{post:title}}`, `{{post:excerpt}}`,
+`{{post:date}}` und Felder als `{{field:<Schlüssel>}}`. Welche Felder ein Inhaltstyp hat und welche Divi als Text
+zeigt, liefert `lit/divi-dynamic-sources` mit `post_type`. Nur textartige Felder eignen sich: Bei Auswahlfeldern
+zeigt Divi den gespeicherten Wert, nicht die Beschriftung; Beziehungs- und Dateifelder zeigen nur IDs, Pods mit
+Tabellen-Speicherung gar nichts.
+
+LIT MCP prüft die Felder eines geänderten Inhalt-Layouts gegen die Inhaltstypen aus den Bedingungen
+(`singular:post_type:<typ>:…`) der Vorlagen, die das Layout benutzen, und warnt (`warnings`) – gespeichert wird
+trotzdem. Das gilt für die Kurzform `{{field:…}}` und für Felder, die im Divi-Builder über „Benutzerdefiniertes
+Feld“ gewählt wurden. Bei einem sichtbaren Layout stehen die Warnungen schon im Probelauf. Ohne solche Bedingung
+bleiben die Felder ungeprüft (die Antwort sagt das). Kopf- und Fußzeile werden nicht geprüft.
+
+## Wenn der Theme Builder gerade offen ist
+
+- Hat der Theme Builder ungespeicherte Änderungen (Entwurf, `draft_pending`), lehnen `lit/tb-create-template`,
+  `lit/tb-assign` und das Aktivieren ab: erst dort speichern oder verwerfen.
+- Deaktivieren (`lit/tb-activate` mit `enabled: false`) geht immer – auch dann, und auch bei einer aktiven
+  Vorlage im Papierkorb. Die Antwort warnt: Speichert jemand ein offenes Theme-Builder-Fenster, kann Divi
+  seinen eigenen Stand wiederherstellen; danach mit `lit/tb-list` prüfen.
+- Speichert jemand in einem Theme-Builder-Fenster, das vor dem Anlegen einer Vorlage geöffnet wurde, entfernt
+  Divi die neue Vorlage wieder aus der Liste und löscht sie 7 Tage später. `lit/tb-list` zeigt sie dann unter
+  `detached` (mit `marked_unused`). Nur auf ausdrücklichen Wunsch: `lit/tb-assign` mit `reattach: true` ordnet
+  sie wieder zu – immer deaktiviert, und nur, wenn ihre Layouts noch aktiv sind.
+
+## Rechte
+
+- WordPress: „Beiträge anderer bearbeiten“ (`edit_others_posts`) und „Design bearbeiten“
+  (`edit_theme_options`); je Vorlage und Layout das Recht, sie zu bearbeiten; zum Anlegen zusätzlich
+  „veröffentlichen“ (Divi legt Vorlagen und Layouts sofort aktiv an).
+- Divi → Rollen-Editor: „Theme Builder“ – standardmäßig nur für Administratoren.
+- Fehlt eines davon, gibt es für dieses Konto keine Vorlagen und Layouts (`not_found` wie bei einer unbekannten
+  ID bzw. `forbidden`). Vorlagen, die das Konto nicht bearbeiten darf, erscheinen nirgends; aktive davon nur als
+  Anzahl (`hidden_live` in `lit/tb-list`, `hidden_overlaps` im Probelauf).
+- Einstellungen → LIT MCP → Tools: Gruppe „Divi Theme Builder“ auf „nur lesen“ sperrt jedes Schreiben, auch über
+  die `lit-divi-…`-Werkzeuge; deaktiviert gibt es keine Vorlagen und Layouts.
+
+## Globale Module im Theme Builder
+
+`lit/library-make-global` wandelt keine Knoten in Theme-Builder-Layouts um. Stattdessen den Abschnitt mit
+`lit/library-save` (`scope: "global"`) speichern und mit `lit-library-insert` (`mode: "global"`) einfügen
+(`lit-guide` topic `divi-library`).
+
+## Rückgängig machen
+
+Vorlagen haben keine Revisionen: `lit/tb-assign` nennt die bisherigen Bedingungen (`previous`), `lit/tb-activate`
+schaltet zurück; jede Änderung steht im Protokoll. Layouts erhalten wie Divi-Seiten eine Revision. Neu angelegte
+Vorlagen im Divi Theme Builder löschen.
+
+## Ablauf: Vorlage für einen Inhaltstyp (custom-post-type-vorlage)
+
+1. Inhaltstyp und Felder klären: `lit-content-types`, dann `lit/divi-dynamic-sources` mit `post_type`.
+2. `lit/tb-list` lesen: gibt es schon eine Vorlage für den Typ? Gibt es eine globale Kopf-/Fußzeile?
+3. Mit dem Nutzer den Aufbau abstimmen (welche Felder, welche Reihenfolge, Kopf-/Fußzeile global oder eigen).
+4. `lit/tb-create-template` mit `use_on: ["singular:post_type:<typ>:all"]`, `header`/`footer` meist
+   `{"source": "global"}`, `body` mit `source: "new"` und `nodes` (Überschrift `{{post:title}}`, Texte mit
+   `{{field:…}}`, das Modul `post-content`, wenn der Eintrag eigenen Inhalt hat). Warnungen zu Feldern beachten.
+5. Das Inhalt-Layout bei Bedarf mit `lit-divi-outline`/`lit-divi-update` verfeinern (Layout-ID als `post_id`;
+   solange die Vorlage deaktiviert ist, ohne Probelauf).
+6. Den Nutzer bitten, die Vorlage im Theme Builder anzusehen (Vorschau eines Eintrags ist erst nach dem
+   Aktivieren möglich).
+7. Erst auf ausdrücklichen Wunsch: `lit/tb-activate` mit `enabled: true` – Probelauf zeigen, dann
+   `confirm: true`.