Synchronisation von Markdown-Dokumentation ins CMS

Dieses Dokument ist ein operatives Runbook für vertrauenswürdige KI-/Operator-Workflows, die geänderte Markdown-Dokumentationsdateien aus dem Repository-Ordner docs/ in quellverknüpfte WebBlocks-CMS-Dokumentationsseiten synchronisieren. Es handelt sich ausschließlich um dokumentarische Produktanleitung. Es fügt keine Laufzeit-Synchronisations-Engine, keinen Endpunkt, keine Migration, keinen Artisan-Befehl, kein Skript, keinen Job, keine Queue, keine Datenbanktabelle, keinen Release-Prozess und keine Verbindung zu einem Live-Ziel hinzu.

Markdown-Dateien unter docs/ bleiben die maßgebliche Quelle (Source of Truth) für die technische WebBlocks-CMS-Dokumentation. CMS-Dokumentationsseiten sind generierte Entwurfs- oder veröffentlichte Ableitungen dieser Markdown-Dateien. Der Workflow existiert, damit Dokumentationsänderungen aus der normalen Produktentwicklung auf einer CMS-Dokumentationssite abgebildet werden können, ohne die CMS-Seite als maßgebliche Kopie zu behandeln.

Dies ist ein KI-/Operator-Workflow, keine automatische Laufzeit-Synchronisation. Das CMS soll das Repository nicht überwachen, keine Markdown-Dateien abrufen und Inhalte nicht eigenständig verändern. Ein vertrauenswürdiger Operator oder ein KI-Tool plant, validiert und wendet optional sichere Entwurfs-Updates über die Internal Content API an.

Das Modell muss für jede Ziel-CMS-Installation oder Dokumentationssite funktionieren. Dokumentation und Berichte müssen generisch bleiben und dürfen keinen echten Ziel-Site-Namen, keine echte Domain, kein echtes API-Token, keinen lokalen absoluten Pfad, keine Roh-Logs und keine Umgebungswerte enthalten.

Zukünftige Operatoren sollten knappe Prompts wie diese verwenden können:

Aus diesen kurzen Befehlen muss die KI bzw. der Operator den Standard-Workflow ableiten:

• Markdown-Dateien unter docs/ als Kandidaten-Quellmenge verwenden
• geänderte Dateien bevorzugen statt eines vollständigen Scans des docs-Baums
• cms_sync-Frontmatter und Quellmetadaten lesen
• die Ziel-CMS-API über GET /webadmin/api entdecken
• nur entdeckte Content-Verträge und Block-Handles verwenden
• quellverknüpfte CMS-Seiten zuerst über die Quellidentität und erst dann über den Pfad zuordnen
• pro Datei einen Plan und einen Validierungsbericht erstellen
• nur anwenden, wenn der Befehl das sichere Anwenden von Entwürfen ausdrücklich autorisiert oder der Benutzer den exakten Plan genehmigt
• niemals veröffentlichen, es sei denn, der Benutzer fordert die Veröffentlichung ausdrücklich an und das Token besitzt content.publish

Update allein bedeutet: planen, validieren und sichere Entwurfsänderungen nur dann anwenden, wenn die Anweisung des Benutzers das Anwenden eindeutig autorisiert. Es umfasst weder Veröffentlichen, Navigationsänderungen, das Überschreiben von Live-Seiten, Medienimport noch Browser-Automatisierung.

Verwenden Sie diese Reihenfolge, um zu entscheiden, welche Markdown-Dateien Kandidaten sind:

1. Wenn der Benutzer eine explizite Dateiliste angibt, verwenden Sie diese Liste.
2. Andernfalls verwenden Sie die im Repository geänderten Markdown-Dateien unter docs/.
3. Beziehen Sie neu hinzugefügte, geänderte und umbenannte .md-Dateien ein.
4. Schließen Sie archivierte Release-Changelog-Dateien unter docs/releases/ aus, sofern nicht ausdrücklich angefordert.
5. Schließen Sie interne KI-, Worklog-, Audit- oder private Planungsdokumente aus, wenn sie außerhalb der öffentlichen Dokumentation liegen oder als intern markiert sind.
6. Schließen Sie Dateien ohne cms_sync-Metadaten aus, sofern sich der Workflow nicht ausdrücklich im Planungs- oder Adoptionsmodus befindet.
7. Führen Sie einen vollständigen erneuten Scan von docs/ nur aus, wenn der Benutzer dies ausdrücklich anfordert.

Die Erkennung geänderter Dateien ist ausschließlich ein Schritt zur Quellauswahl. Sie darf den Git-Zustand nicht verändern, keine Dateien stagen, keine Release-Artefakte erstellen und keine Ziel-CMS-Installation aus Repository-Remotes ableiten.

Markdown-Dateien nehmen über Frontmatter teil:

cms_site oben ist ein Beispiel für ein Ziel-Site-Handle, keine echte Domain und kein echter Installationsname. cms_source_id ist die stabile Quellidentität. Wenn eine Datei verschoben wird, kann die Quellidentität unverändert bleiben, sodass die Zielseite weiterhin sicher zugeordnet werden kann.

Metadatenregeln:

• cms_source_id ist die stabile Quellidentität.
• cms_path ist der kanonische Page-Translation-Pfad wie /docs/internal-content-api; stellen Sie neuen Docs-Seiten kein /p voran.
• cms_layout hat den Standardwert docs, wenn es fehlt.
• cms_locale hat den Standardwert en, wenn es fehlt.
• cms_title verwendet standardmäßig die erste H1 oder einen aus dem Dateinamen abgeleiteten Titel, wenn es fehlt.
• Der Quell-Hash ist ein SHA-256-Hash des Markdown-Quellinhalts, der zur Erkennung von Änderungen dient.
• Fehlende cms_sync-Metadaten bedeuten, dass die Datei im normalen Update-Modus übersprungen wird und für die Adoptionsplanung gemeldet werden kann.

Die erste Adoption kann als reiner Docs-Schritt zum Seeden von Metadaten erfolgen, bevor eine Live-CMS-Erkennung oder ein Anwendungsversuch stattfindet. Dieser Schritt sollte ausgewählten öffentlichen Dokumentations-Markdown-Dateien sicheres, generisches Frontmatter hinzufügen, damit spätere Pläne Quell-IDs, Pfade, Sprachen (Locales), Layouts und Titel ohne Raten identifizieren können. Ein vollständiger Adoptionsdurchlauf über docs/ sollte archivierte Release-Changelogs unter docs/releases/ weiterhin ausschließen, es sei denn, ein vertrauenswürdiger Operator genehmigt diese Archivseiten ausdrücklich.

Eine quellverknüpfte CMS-Seite sollte Quellmetadaten in den Seiteneinstellungen führen. Für den dokumentierten Workflow reichen die Seiteneinstellungen aus; eine separate Quellzuordnungstabelle kann später nur dann in Betracht gezogen werden, wenn Reporting, Locale-übergreifende Zuordnung, Audit oder groß angelegte Operationen dies erfordern.

Empfohlene Struktur der Seiteneinstellungen:

Der Quellpfad ist beschreibend. Die stabile Identität ist source_id, der Änderungsdetektor ist source_sha256. Die Internal Content API akzeptiert dieses Objekt nur über die auf der Allowlist stehende Seiteneinstellung source_sync, persistiert es nach dem Anwenden und gibt dieselben sicheren Felder in den Seitenlisten-/Detailantworten für die Zuordnung zurück. Speichern Sie keine Tokens, Umgebungswerte, lokalen absoluten Pfade, Serverpfade oder andere Geheimnisse.

Die Zuordnungsreihenfolge muss deterministisch sein:

1. Suchen Sie nach einer CMS-Seite mit übereinstimmender source_sync.source_id oder äquivalenten cms_source_id-Metadaten.
2. Falls gefunden, vergleichen Sie source_sha256.
3. Falls keine Source-ID-Übereinstimmung existiert, suchen Sie nach einer Seite am kanonischen cms_path.
4. Wenn der Pfad ohne passende Quellmetadaten existiert, melden Sie einen Adoptions- oder Konfliktprüfungsfall.
5. Wenn der Pfad zu einer anderen source_id gehört, melden Sie einen Konflikt und stoppen Sie für diese Datei.
6. Wenn am Pfad keine Seite existiert, planen Sie create_draft_page mit page.path gesetzt auf den kanonischen cms_path.

Verwenden Sie den Inhaltsvergleich nicht als primären Zuordnungsmechanismus. Ordnen Sie zuerst über die stabile Quellidentität zu, dann über den Pfad nur für Adoptions- oder Konfliktprüfungen.

Verwenden Sie für geänderte Markdown-Dokumente diese Standardwerte:

• Wenn der Quell-Hash in den CMS-Metadaten unverändert ist, überspringen Sie die Datei.
• Wenn keine passende CMS-Seite existiert, planen Sie create_draft_page.
• Wenn eine passende Entwurfsseite existiert, planen Sie replace_existing_draft_page für verwaltete, der Seite gehörende Slots.
• Wenn nur eine passende veröffentlichte Seite existiert, ersetzen Sie sie nicht direkt, es sei denn, der Workflow verfügt über einen dokumentierten sicheren Entwurfs- oder Staging-Pfad und der Benutzer genehmigt diesen Pfad ausdrücklich.
• Der Standard-verwaltete Slot ist main.
• Bewahren Sie Header, Footer, deaktivierte Slots und Shared-Slot-Zuweisungen.
• Ersetzen Sie keinen von einem Shared Slot gespeisten Slot.
• Planen Sie die Navigation separat und wenden Sie Navigationsänderungen standardmäßig nicht an.
• Das Veröffentlichen ist standardmäßig niemals Teil des Anwendens von Inhalten.

Der Workflow sollte verwaltete, der Seite gehörende Slots aus der Markdown-Quelle neu generieren, statt zu versuchen, manuelle CMS-Bearbeitungen innerhalb dieser Slots zu erhalten. Quellverknüpfte Dokumentationsseiten sind reproduzierbare Ableitungen; Markdown bleibt maßgeblich.

Erstellen Sie strukturierte Inhalte nur mit Handles, die von der Zielinstallation entdeckt wurden. Raten Sie niemals Block-Handles oder ähnliche Schreibweisen.

Praktische Zuordnungsregeln:

• H1 wird dem Seitentitel und/oder einem content_header-Block zugeordnet, wenn dieses Handle verfügbar ist.
• H2 und H3 werden header-Blöcken zugeordnet, mit Ankern, wo unterstützt.
• Absätze werden rich-text zugeordnet.
• Einfache, unformatierte kurze Texte dürfen plain_text verwenden, aber nur dann, wenn das passender ist als Rich Text.
• Listen werden einem Listenblock zugeordnet, wenn der aktuelle Content-Vertrag einen unterstützt; andernfalls bleiben sie in rich-text.
• Tabellen werden nach Möglichkeit einem table-Block zugeordnet.
• Code-Fences werden einem code-Block zugeordnet.
• Blockzitate werden je nach Bedeutung und entdeckten Verträgen quote- oder alert-/Callout-artigen Blöcken zugeordnet.
• Normale Markdown-Links bleiben Rich-Text-Links.
• CTA-artige Links dürfen nur dann zu button_link werden, wenn sie bewusst handlungsorientiert sind.
• Rohes HTML sollte vermieden werden; html ist nur ein geprüfter Fallback, wenn strukturierte Blöcke den Inhalt nicht abbilden können.
• Bilder und Medien sollten nicht heruntergeladen oder importiert werden. Warnen Sie, sofern der Ziel-Workflow Referenzen auf vorhandene Medien nicht ausdrücklich unterstützt.

Bevorzugen Sie eine lesbare Dokumentationsstruktur gegenüber einem einzigen großen rich-text-Block. Eine normale Dokumentationsseite verwendet üblicherweise content_header oder aus der H1 abgeleiteten Titelinhalt, gefolgt von Überschriften, Rich Text, Listen, Tabellen und Codeblöcken innerhalb des verwalteten main-Slots.

Der Workflow ist API-first:

1. Beginnen Sie mit GET /webadmin/api.
2. Verwenden Sie die zurückgegebenen Links für OpenAPI, den KI-Leitfaden, den Content-Vertrag, Blocktypen, Seiten, Navigation und Shared Slots.
3. Bestätigen Sie, dass das Token über die für den angeforderten Modus erforderlichen Fähigkeiten verfügt.
4. Lesen Sie vorhandene Seiten und Quellmetadaten über die API.
5. Erstellen Sie Seitenpläne ausschließlich mit entdeckten Handles.
6. Führen Sie vor dem Anwenden POST /webadmin/api/content/validate aus.
7. Wenden Sie nur nach ausdrücklicher Genehmigung an oder wenn die Anweisung des Benutzers das sichere Anwenden von Entwürfen ausdrücklich autorisiert.
8. Veröffentlichen Sie niemals, es sei denn, der Benutzer fordert die Veröffentlichung ausdrücklich an und das Token besitzt content.publish.
9. Verwenden Sie niemals Browser-Automatisierung, wenn die API verfügbar ist.

API-Fehler sind Workflow-Feedback. Behandeln Sie 401-, 403- und 422-JSON-Antworten als Stopp- oder Überarbeitungssignale, folgen Sie den Discovery-/Dokumentationslinks und melden Sie einen sicheren, zusammengefassten Status, ohne Geheimnisse auszugeben.

Wenn mehrere geänderte Dokumente Kandidaten sind:

• verarbeiten Sie jedes Quelldokument als unabhängiges geplantes Seiten-Update
• validieren Sie alle Kandidaten-Seitenpläne, bevor ein Batch angewendet wird, es sei denn, der Operator wählt ausdrücklich das dateiweise Anwenden
• lassen Sie den Konflikt einer Datei nur diese Datei stoppen, ohne erfolgreiche Pläne für andere Dateien zu verbergen
• melden Sie übersprungene, geplante, validierte, angewendete, fehlgeschlagene und Konfliktdateien getrennt
• nehmen Sie keine Navigationsänderungen vor, nur weil sich mehrere Dokumente geändert haben
• halten Sie die Navigationsplanung als separaten expliziten Plan

Das Anwenden von Batches sollte konservativ erfolgen. Wenn der Benutzer das sichere Anwenden von Entwürfen angefordert hat, wenden Sie nur die validierten, entwurfssicheren Elemente an und lassen Sie Konflikte oder Prüffälle unangewendet.

Stoppen Sie vor dem Anwenden, wenn:

• das API-Token fehlt, ungültig ist oder widerrufen wurde
• die API-Discovery fehlschlägt
• OpenAPI, der Content-Vertrag oder die Blocktypen nicht gelesen werden können
• erforderliche Block-Handles nicht verfügbar sind
• cms_path mit einer anderen cms_source_id in Konflikt steht
• die Zielseite veröffentlicht ist und kein sicherer Entwurfs-Ersetzungspfad verfügbar ist
• der Plan einen von einem Shared Slot gespeisten Slot ersetzen würde
• die Validierung fehlschlägt
• der Benutzer das Anwenden nicht genehmigt hat und die Anweisung Dry-Run oder Plan-only war

Stoppen Sie außerdem vor dem Veröffentlichen, es sei denn, der Benutzer fordert die Veröffentlichung ausdrücklich an, der Plan wurde bereits sicher validiert/angewendet und das Token besitzt content.publish.

Gruppieren Sie bei Batches dieselben Felder unter den Abschnitten skipped, planned, validated, applied, failed, conflict und needs review.

Nur planen:

Nur validieren:

Validieren und sichere Entwurfs-Updates anwenden:

Planung eines vollständigen erneuten Scans:

Nur Navigationsplanung:

Quellverknüpfte Dokumentationsseiten sollten im CMS als quellverwaltet markiert werden. Ein zukünftiger Bearbeitungsbildschirm kann Editoren warnen: "Diese Seite wird aus einer Markdown-Quelle synchronisiert. Bearbeiten Sie stattdessen die Quelldatei."

Manuelle CMS-Bearbeitungen an quellverknüpften Dokumentationsseiten werden bei der nächsten quellgesteuerten Neugenerierung der verwalteten Slots nicht erhalten. Header/Footer und Shared-Slot-Zuweisungen bleiben erhalten, da sie kein der Seite gehörender, verwalteter Markdown-Inhalt sind.

Dokumentation und Operator-Berichte dürfen keine Tokens, Geheimnisse, lokalen absoluten Pfade, Roh-Logs, Umgebungswerte, echten Ziel-Site-Namen oder echten Domains enthalten.