Dokumentieren mit dem Wiki

Neue Inhalte werden ausschließlich im Forgejo-Repository documentation-content angelegt. Ein erfolgreicher Release-Build übernimmt Navigation, Suche, Live-Wiki, statische HTML-Version und ZIP automatisch.

Quellen für die wpmcp00-Instanz

Das getrennte Werkstatt-Wiki verwendet ausschließlich den Unterbaum instances/wpmcp00-wiki/ dieses Repositories. Der Serverpfad /home/wpmcp00/codex-projects/wiki/content-source verweist auf diesen Bestand. Startdateien unter initial-content/ im App-Repository sind Vorlagen; fachliche Änderungen werden hier in einem frischen Branch oder Worktree auf aktuellem main versioniert.

Der Instanzbuild wird über /home/wpmcp00/codex-projects/wiki/bin/werkstatt wiki-build ausgelöst. Er validiert die Originalmetadaten und Markdown-Klassen, prüft lokale Links und erzeugt eine atomare Generation mit HTML und ZIP. Die Oberfläche verwendet eine flache Seitenliste. Instanzseiten erhalten zunächst placement: unlisted, related: [] und passende relative Leselinks, damit der Unterbaum sowohl allein als auch im vollständigen Repository gebaut werden kann. Die bestehende Hauptnavigation wird dadurch nicht verändert.

Dashboard und Wiki der Instanz sind extern passwortgeschützt. Nur der Bedienablauf und die Feldbezeichnung werden dokumentiert: Das konkrete Passwort gehört ausschließlich in die private Serverkonfiguration. Die Erinnerung nach Anmeldung wird dynamisch dargestellt und nie als statische Wiki-Seite gespeichert. Interne Agenten verwenden bin/werkstatt oder den eigenen Loopback-Listener http://127.0.0.1:8189/dashboard/api/ ohne Passwort oder Token. Eine Matrix-Anbindung oder externe Benutzeranmeldung je Channel/MCP ist dafür nicht nötig und noch nicht implementiert. Siehe das Instanz-Autorenhandbuch für Dateien, Metadaten und Exportgrenzen.

Dokumentationsanfragen können über werkstatt wiki-request oder POST /dashboard/api/wiki-master/requests an den festen Empfänger wiki-master gestellt werden. Sie nennen den stabilen Absender, konkrete Quellen, den gewünschten Umfang und eine wiederverwendbare request_id. Eine Aufgabenreferenz kann mit ihrem sprechenden Namen übergeben werden. Nur auf ausdrücklichen Nutzerwunsch wird die Anfrage als dringend markiert.

Der Wiki-Master arbeitet in begrenzten Batches aus eingefrorenen Channel-Manager-Nachrichten. Er dokumentiert Plan, Fortschritt und Ergebnis im Dashboard, darf Wiki-Unteraufträge delegieren und antwortet den Absendern. ACK folgt erst nach Lesen, dokumentierter Disposition und Rückmeldung; der Timer bestätigt selbst nichts. Vor direkter paralleler Quellenarbeit sind der aktive Batch und die vorhandenen Aufgaben zu prüfen.

Die kanonischen Serverarbeitsbäume liegen unter /home/wpmcp00/codex-projects/wiki/source/documentation-wiki-git für die App und source/documentation-content-git für Inhalte. Die umfangreiche Plattformplanung bleibt Aufgabe der Planungssitzung. Das Wiki-Master-Handbuch beschreibt Timing, Pause, Namen und Rückmeldungen.

Diese beiden Arbeitsbäume verwenden einen eigenen schreibberechtigten Forgejo-Deploy-Key mit Zugriff ausschließlich auf ihre beiden Repositories. SSH-Remote, feste private Schlüsseldatei und geprüfte Hostschlüssel sind repositorylokal konfiguriert; der private Schlüssel bleibt auf wpmcp00. Vor Fetch und Push diese Zuordnung erhalten, ohne Schlüsselwerte auszugeben oder Codex-Accounts umzuschalten. Das Instanz-Autorenhandbuch nennt Pfade und Betriebsgrenzen. Ein Git-Push ersetzt weder Content-Build noch Veröffentlichung.

Getrennte Veröffentlichungsgrenzen

Das globale Wiki auf wpmcp veröffentlicht den Hauptbestand ohne instances/. Bei der unveränderten globalen Wiki-Anwendung wird dafür ein sauberer Git-Sparse-Checkout im Non-Cone-Modus mit den Mustern /* und !/instances/ verwendet. Die WPMCP00-Instanz baut weiterhin ausschließlich ihren eigenen Unterbaum. Related-Metadaten verweisen nur auf Seiten im jeweiligen Buildbestand; Verweise auf die andere Instanz verwenden ihre veröffentlichte HTTPS-Wiki-Adresse. Quellpfade bleiben zur Pflege dokumentiert, werden aber nicht als buildübergreifende interne Links behandelt.

Standardablauf

1. Aktuelles main in einen frischen Branch oder Worktree holen.
2. _wiki/navigation.html, AGENTS.md und den Klassenvertrag lesen.
3. Die Seite am fachlich passenden, bestehenden Pfad anlegen.
4. Gültiges wiki-page/v1-Frontmatter beziehungsweise wiki-page-metadata einfügen.
5. Relative Links und Assets ergänzen; keine Secrets, PII oder externen Asset-Hotlinks einchecken.
6. Content-Build, Linkprüfung, HTML-Export, ZIP sowie Desktop- und Mobilansicht prüfen; bei LLM-Änderungen zusätzlich einen synthetischen quellengebundenen Ende-zu-Ende-Auftrag ausführen.
7. Commit reviewen, nach main bringen und ausschließlich über den Releaseprozess veröffentlichen.

Menüplatz festlegen

Eine normale Themenseite verwendet placement: main. topic verweist auf eines der zentral registrierten Haupttopics. parent verweist auf die ID einer anderen Seite im selben Topic; fehlt das Feld, liegt die Seite auf der ersten vertikalen Ebene.

---
wiki:
  schema: wiki-page/v1
  title: Telegram-Dienst
  summary: Architektur und Betrieb des Telegram-Supportdienstes.
  document_type: architecture
  status: active
  navigation:
    placement: main
    topic: uberspace
    id: telegram-service
    parent: services
    label: Telegram-Dienst
    order: 30
    pinned: false
    appearance: strong
  tags: [telegram, support, service]
  aliases: [telegram-bridge]
  audience: [developer, admin, codex]
  owner: infrastructure
  reviewed_at: "2026-08-27"
  toc: auto
  related:
    - operations/telegram-runbook.md
---

placement: footer ist ausschließlich für flache Wiki-interne Seiten gedacht. topic, parent und verschachtelte Footer-Einträge sind dort verboten. Mit placement: unlisted bleibt eine Seite über Links, Suche, CLI und MCP erreichbar, erscheint aber nicht im Menü.

Build stoppt absichtlich

Unbekannte Topics oder Appearance-IDs, doppelte IDs, fehlende Elternknoten, Zyklen, ungültige Related-Ziele und verschachtelte Footer-Seiten sind harte Fehler.

Reichhaltige Inhalte in Markdown

Tabellen

| Dienst | Status | URL |
| --- | --- | --- |
| Wiki | aktiv | `projects.webdevmedia.de/documentation` |
{.wiki-table-compact .wiki-table-striped .wiki-table-scroll}

Aufklappbare Warnungen und Lösungen

> **Warnsignal: Uneindeutiger Releasepfad**
>
> **Evidenz:** Mehrere historische Releases sind vorhanden.
>
> **Auswirkung:** Der aktive Stand kann falsch eingeordnet werden.
{.wiki-warning .wiki-collapsible}

> **Bereinigungsvorschlag**
>
> Releases anhand des aktiven Symlinks und der Git-Hashes klassifizieren.
{.wiki-tip .wiki-collapsible}

Für ein bestätigtes Problem wird .wiki-danger .wiki-collapsible verwendet. Die sichtbare Überschrift muss zusätzlich in Worten deutlich machen, ob es sich um ein Warnsignal, ein Problem oder einen Vorschlag handelt; Farbe allein reicht nicht.

Bilder, Diagramme, Karten und Status

![Architektur](images/architecture.svg){.wiki-image-full .wiki-image-bordered}

- [MCP-Endpunkte](../interfaces/mcp.md)
- [CLI-Befehle](../interfaces/cli.md)
{.wiki-grid-2}

**AKTIV**{.wiki-badge .wiki-status-ok}

SVG-Diagramme und Bilder werden lokal im Content-Repository abgelegt. Der vollständige Klassenumfang steht im CommonMark-Klassenvertrag.

Wann HTML sinnvoll ist

Aktives HTML ist für interaktive Werkzeuge, komplexe Visualisierungen oder individuelle dynamische Layouts vorgesehen. Das Dokument muss vollständiges HTML und ein JSON-Script mit der ID wiki-page-metadata enthalten. Relative CSS-, JavaScript-, Bild- und Datendateien bleiben im selben Content-Unterbaum.

Vertrauensgrenze

HTML, CSS, JavaScript und aktive SVGs besitzen Same-Origin-Rechte und werden deshalb wie Anwendungscode reviewt. Für überwiegend dokumentarische Inhalte bleibt Markdown die kleinere und sicherere Lösung.

Zentrale Navigation erweitern

Neue Haupttopics und individuelle Navigationseffekte werden in _wiki/navigation.html definiert. Die Datei darf geprüftes HTML, CSS und JavaScript enthalten. Jede Änderung benötigt einen dokumentierten SHA-256 und wird zusammen mit dem Content atomar veröffentlicht. Mit ?safe-ui=1 lädt das Live-Wiki die Kernnavigation ohne diese Erweiterungen.

AGENTS.md-Kernsektion für neue Codex-Sitzungen

Die folgende Sektion kann in einer übergeordneten AGENTS.md verwendet werden. Eine projektspezifische AGENTS.md darf Pfade und Prüfbefehle ergänzen, aber die Dokumentationspflicht nicht aufheben.

## Dokumentations-Wiki

Baue vor Infrastruktur-, MCP-, Codex- oder Supportarbeiten zuerst Wissen aus
dem produktiven Wiki unter `https://projects.webdevmedia.de/documentation/`
auf. Nutze je nach verfügbarer Oberfläche die Wiki-CLI, die
`documentation__*`-MCP-Tools oder die Wiki-API. Beginne mit Status,
Themenbaum, Suche und den relevanten Originalquellen. Nutze eine LLM-Frage nur
zur quellengebundenen Synthese; sie ersetzt nicht das Lesen der Quellen.

Pflege Wiki-Inhalte ausschließlich im Forgejo-Repository
`documentation-content`, in einem frischen Branch oder Worktree auf Basis von
aktuellem `main`. Bearbeite niemals `content/current`, Release- oder
Laufzeitverzeichnisse direkt.

Jede Änderung an Serverpfaden, Diensten, URLs, APIs, MCPs, OAuth,
Deployments, Rollbacks, Authentifizierung, Codex-Adaptern, Account-Auswahl,
Modellen oder Betriebsabläufen muss im selben Arbeitsauftrag auf der passenden
kanonischen Wiki-Seite reflektiert werden.

Änderungen an Wiki-Funktionen oder der Wiki-Struktur müssen zusätzlich im
Autorenhandbuch und in der Wiki-Architektur dokumentiert werden. Aktualisiere
je nach Änderung auch `_wiki/navigation.html`, LLM-Sitzungen, CLI, MCP,
URLs/Dienste oder den CommonMark-Klassenvertrag.

Jede Markdown-Seite benötigt `wiki-page/v1`-Frontmatter; jede eigenständige
HTML-Seite benötigt `wiki-page-metadata`. Nutze Markdown als Standard und
aktives HTML nur für echte Interaktion oder komplexe Visualisierungen.

Prüfe Titel, Summary, Navigation, Tags, Related-Links, Owner und
`reviewed_at`. Dokumentiere keine Secrets, Bearer, Zugangscodes, Cookies,
privaten Prompts oder personenbezogenen Accountdaten.

Vor Veröffentlichung müssen Content-Build, Navigation, Links, statische
HTML-Version, ZIP sowie die relevanten Desktop- und Mobilansichten erfolgreich
sein.

Statische HTML-Version

Der Headerlink HTML-Version öffnet die gerenderte Fassung. Erst dort steht ZIP herunterladen; der Live-Header enthält keinen direkten ZIP-Link. Alle internen Links des Exports sind relativ, sodass der entpackte Bestand direkt von HDD gelesen oder über einen lokalen HTTP-Server bereitgestellt werden kann.