Zum Inhalt

ADR-002 — Doku-Site auf MkDocs Material + Cloudflare Pages mit Auto-Sync

Datum: 2026-05-11 Status: Akzeptiert Supersedes: ADR-001 (2026-05-04) — der „kein Web-UI"-Trade-off wird aufgehoben.

Kontext

ADR-001 hat das Doku-System als rein lokales Markdown-Repo konzipiert, mit dem Argument „Push erst nach Freigabe". In der Praxis sind in den 7 Tagen seitdem null Workflow-Karten geschrieben worden, und es entsteht Bedarf von drei zusätzlichen Audiences:

  • Philip (Manager) fragt regelmäßig nach Status.
  • CS-Agenten sollen auf Prozesse geonboardet werden und perspektivisch zusammen mit Claude Bugs fixen.
  • Susi selbst soll auch unterwegs (Handy) nachschlagen können.

Lokales Markdown reicht für keine dieser drei Gruppen — sie haben keinen Zugriff auf Susis Filesystem.

Entscheidung

  1. Doku-Site: MkDocs Material rendert das docs/-Verzeichnis als statische Site.
  2. Hosting: Cloudflare Pages baut bei jedem Push zum privaten GitHub-Repo automatisch neu (gratis, auch für Private Repos, ~30 Sek. Build-Zeit).
  3. Auth: Cloudflare Access mit Google-OAuth, Policy „nur @mokebo.de-Adressen". Kein Passwort, kein Account-Setup für CS.
  4. URL: zunächst mokebo-ops.pages.dev, später ops.mokebo.de (CNAME).
  5. Single Source of Truth bleibt Markdown im Repo — kein paralleles Notion/Drive.
  6. Auto-Sync via n8n: ein scheduled Workflow DAILY mokebo-ops Sync aktualisiert nachts Status, Erfolgsquoten und Subworkflow-Calls direkt im GitHub-Repo (siehe Phase G im Plan). Susi pflegt nur, was sich nicht aus der API ableiten lässt: Stolpersteine, Debug-Hinweise, Wirkung für CS, Decisions.

Alternativen geprüft

Option Warum nicht
Notion + Notion-MCP Mokebo nutzt kein Notion. Lock-in, neue Lizenz.
Google Drive (Markdown → Google Docs Auto-Convert) Mermaid + Code-Blocks brechen, Diff/History schwach, Doppelpflege.
Zendesk Guide (Internal Articles) Trennt CS-Doku von Tech-Doku → garantiert Drift.
GitHub Pages Erfordert GitHub Pro für private Repos. Cloudflare ist gratis.
Selbst-gehostetes Wiki (Outline, BookStack) Setup + Wartung > Nutzen für Solo-Setup.
PDF-Export per Skript Sharing-Pain, kein Live-Update, nicht durchsuchbar.

Konsequenzen

Positiv:

  • CS + Philip haben einen Link, immer aktuell, Login per Workspace-Account.
  • Susi pflegt da, wo sie eh ist (Markdown lokal mit Claude Code).
  • Auto-Sync killt 80% des Pflegeaufwands.
  • HTML-Dashboards (à la Thariq) lassen sich nativ als Assets einbetten — z.B. das bestehende dashboard.html unter docs/assets/.
  • Volltext-Suche, Mobile-Layout, Dark/Light-Mode out of the box.

Negativ / akzeptierte Trade-offs:

  • Initial-Setup ~2h (Cloudflare-Account, OAuth, Build-Pipeline).
  • HTML-Build-Output (site/) ist nicht versioniert (gitignored) — bei Cloudflare-Ausfall keine schnelle lokale Vorschau ohne mkdocs serve.
  • Zusätzliches System (MkDocs + Cloudflare) zu lernen.
  • Ein API-Key (n8n + GitHub) für den Daily-Sync — verschlüsselt in n8n Credentials.

Gestrichene Strukturen aus ADR-001

  • routines/ (maintenance.md, session-log.md) → wegen Meta-Overhead.
  • roadmap/backlog.md → Backlog lebt eh in handover.md + Memory.
  • onboarding/handover.md → redundant mit docs/index.md.
  • Phase-Konzept (Phase 1/2/3) → ungeeignet für inkrementelles Arbeiten.
  • 4-stufige Pflichtlektüre → ersetzt durch eine Landing-Page.
  • 6 „Pflicht-Updates" in CLAUDE.md → reduziert auf 3 Regeln.

Behalten: architecture/, decisions/, das Karten-Konzept, die Status-Dashboard-Idee, das Custom dashboard.html.