From 90ba15b734a4995ee7c097510c630036f3eea4f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=CE=B1=CE=B7dr3=CE=B15=20=C9=AE=CE=B1=CE=B7=C9=A6=D6=85l?=
 =?UTF-8?q?=CA=903=CA=80?= <2878033+a6b8@users.noreply.github.com>
Date: Mon, 22 Jun 2026 16:13:47 +0200
Subject: [PATCH] Neutralize source comments and template DE version

- Strip internal record/decision references and German from Astro/script comments and the team page
- Convert the hand-maintained DE how-it-works page to a placeholder template (single-source version)
- Fix the docs deploy trigger: dispatch deploy after a GITHUB_TOKEN sync push (loop-protection workaround)
---
 .github/workflows/sync-spec.yml               |  11 +
 src/components/HeaderCopyButton.astro         |   6 +-
 src/components/PageTitleWithBreadcrumb.astro  |   6 +-
 .../docs/de/quickstart/how-it-works.md        |   4 +-
 src/content/docs/team/index.mdx               |  21 +-
 src/pages/404.astro                           |  11 +-
 src/pages/blog/[...slug].astro                |  11 +-
 src/pages/blog/index.astro                    |   9 +-
 src/pages/configurator.astro                  |   8 +-
 src/scripts/mermaid-zoom.mjs                  |  17 +-
 .../de/quickstart/how-it-works.template.md    | 231 ++++++++++++++++++
 11 files changed, 277 insertions(+), 58 deletions(-)
 create mode 100644 src/templates/de/quickstart/how-it-works.template.md

diff --git a/.github/workflows/sync-spec.yml b/.github/workflows/sync-spec.yml
index f960b13..146f0dd 100644
--- a/.github/workflows/sync-spec.yml
+++ b/.github/workflows/sync-spec.yml
@@ -8,6 +8,7 @@ on:
 
 permissions:
   contents: write
+  actions: write
 
 jobs:
   sync:
@@ -45,6 +46,8 @@ jobs:
       # derived from flowmcp-spec.
       - name: Sync, commit and push (race-safe)
         working-directory: flowmcp.github.io
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
@@ -60,6 +63,14 @@ jobs:
             git commit -m "chore: sync spec from flowmcp-spec [auto]"
             if git push origin HEAD:"$BRANCH"; then
               echo "Pushed on attempt $attempt."
+              # A push made with GITHUB_TOKEN does NOT trigger deploy.yml's
+              # `on: push` (GitHub loop-protection), so synced spec changes would
+              # never go live on their own. Explicitly dispatch the deploy
+              # workflow. (Alternative: push these changes with a PAT instead of
+              # GITHUB_TOKEN, which would trigger `on: push` naturally.)
+              if [ "$BRANCH" = "main" ]; then
+                gh workflow run deploy.yml --ref "$BRANCH" || echo "::warning::deploy dispatch failed; site may not redeploy until next push"
+              fi
               exit 0
             fi
             echo "Push rejected on attempt $attempt — concurrent push moved $BRANCH. Resetting to remote and re-syncing."
diff --git a/src/components/HeaderCopyButton.astro b/src/components/HeaderCopyButton.astro
index a26ada9..532a87f 100644
--- a/src/components/HeaderCopyButton.astro
+++ b/src/components/HeaderCopyButton.astro
@@ -1,5 +1,5 @@
 ---
-// HeaderCopyButton.astro — Memo 064 Phase 4 PRD-009
+// HeaderCopyButton.astro
 // ONE small icon-only button injected on the heading line of every content page
 // (via the PageTitle override). Click copies the page content as Markdown.
 //
@@ -128,8 +128,8 @@ const labels = LABELS[ lang ]
     const getPageMarkdown = async ( slug ) => {
         if( !slug ) { throw new Error( 'HeaderCopyButton: missing slug' ) }
         const trimmed = slug.replace( /^\/+|\/+$/g, '' )
-        // Memo 069 PRD-002: the slug comes from the URL pathname, so a directory
-        // page like /about/ yields slug "about". The generator
+        // The slug comes from the URL pathname, so a directory page like
+        // /about/ yields slug "about". The generator
         // (generate-markdown-map.mjs) writes index pages as {dir}/index.md, so
         // "about" → about/index.md, not about.md. Try the direct file first, then
         // fall back to the {slug}/index.md variant for directory-index pages.
diff --git a/src/components/PageTitleWithBreadcrumb.astro b/src/components/PageTitleWithBreadcrumb.astro
index 7dcb564..315d6a2 100644
--- a/src/components/PageTitleWithBreadcrumb.astro
+++ b/src/components/PageTitleWithBreadcrumb.astro
@@ -4,9 +4,9 @@ import Breadcrumb from './Breadcrumb.astro'
 import SidebarHooks from './SidebarHooks.astro'
 import HeaderCopyButton from './HeaderCopyButton.astro'
 
-// Memo 064 Phase 4 PRD-009: exactly ONE small copy button on the heading line
-// of every documentation page, injected via this PageTitle override. Replaces
-// all manual per-page <CopyMarkdown mode="page"> embeds.
+// Exactly ONE small copy button on the heading line of every documentation
+// page, injected via this PageTitle override. Replaces all manual per-page
+// <CopyMarkdown mode="page"> embeds.
 //
 // Suppressed on splash/landing pages (homepage, blog index, blog posts): those
 // hide the page title and have no per-slug markdown source, so the button would
diff --git a/src/content/docs/de/quickstart/how-it-works.md b/src/content/docs/de/quickstart/how-it-works.md
index 17452b4..424f9f3 100644
--- a/src/content/docs/de/quickstart/how-it-works.md
+++ b/src/content/docs/de/quickstart/how-it-works.md
@@ -90,7 +90,7 @@ Die Schema-Schicht ist dein Arbeitsbereich. Alles andere wird von der Runtime ue
 
 ## Schema-Anatomie
 
-Jedes FlowMCP v4.1.0 Schema nutzt das **Two-Export-Pattern**:
+Jedes FlowMCP v4.3.0 Schema nutzt das **Two-Export-Pattern**:
 
 ### main (erforderlich)
 
@@ -227,5 +227,5 @@ Schemas, die versuchen Module zu importieren, auf das Dateisystem zuzugreifen od
 :::
 
 :::note
-Fuer die vollstaendige Spezifikation einschliesslich aller Validierungsregeln, Parameterformate und Sicherheitsdetails, siehe die [Spezifikation v4.1.0](/de/specification/overview/).
+Fuer die vollstaendige Spezifikation einschliesslich aller Validierungsregeln, Parameterformate und Sicherheitsdetails, siehe die [Spezifikation v4.3.0](/de/specification/overview/).
 :::
diff --git a/src/content/docs/team/index.mdx b/src/content/docs/team/index.mdx
index 031527e..203ea76 100644
--- a/src/content/docs/team/index.mdx
+++ b/src/content/docs/team/index.mdx
@@ -12,26 +12,7 @@ experience in API design, developer tooling, and open data.
 
 ## Team
 
-{/*
-  TODO (PRD-31, Memo 052 Phase 8): Team-Mitglieder mit User-Sign-off einfuegen.
-
-  Personen-Daten erfordern explizite Freigabe. Pro Person folgendes Schema:
-
-    ### Person Name
-    ![Photo](/images/team/person-slug.png)
-    **Role:** Maintainer / Co-Founder / Contributor
-    [LinkedIn](https://linkedin.com/in/...)
-
-    Bio in 2-3 sentences. Focus: role, experience, relation to FlowMCP.
-    Tonality: sachlich (Anders-Persona). Keine Buzzwords, keine Emojis.
-
-  Vor dem Einfuegen:
-  1. Name, Rolle, Bio-Text vom User freigeben lassen
-  2. Optional: Profilbild in public/images/team/ ablegen
-  3. Optional: LinkedIn-URL ergaenzen
-  4. DE-Pendant (src/content/docs/de/roadmap/team.md) analog pflegen
-  5. Im Commit-Body User-Sign-off-Bestaetigung dokumentieren
-*/}
+{/* Team member profiles to be added with sign-off. */}
 
 Will be filled by maintainer.
 
diff --git a/src/pages/404.astro b/src/pages/404.astro
index bbddc10..8e04143 100644
--- a/src/pages/404.astro
+++ b/src/pages/404.astro
@@ -1,9 +1,8 @@
 ---
-// 404 Page — Memo 064 Phase 4 PRD-010
+// 404 Page
 // Pagefind search removed (locked decision). Page reduced to clear links:
 // home + the main areas. Pagefind remains the GLOBAL Starlight search
 // (SearchCustom.astro override) — only the 404 usage was removed here.
-// History: Memo 057 PRD-03 introduced the (now removed) search field.
 ---
 
 <html lang="en">
@@ -46,7 +45,7 @@
     </main>
 
     <style>
-        /* PRD-07: Skip-Link visible on focus */
+        /* Skip-Link visible on focus */
         .skip-link {
             position: absolute;
             top: -40px;
@@ -65,9 +64,9 @@
             outline-offset: 2px;
         }
 
-        /* Memo 059 PRD-005 (A13, A14, A15):
-         *   - logo (via /logo.svg) renders in Babyblau by default
-         *   - --notfound-accent is the Babyblau brand colour (was purple #8c5dff)
+        /* Brand colour tokens:
+         *   - logo (via /logo.svg) renders in baby blue by default
+         *   - --notfound-accent is the baby blue brand colour
          *   - --notfound-muted aligns with --color-text-secondary token in custom.css */
         :root {
             --notfound-bg: #0e0f12;
diff --git a/src/pages/blog/[...slug].astro b/src/pages/blog/[...slug].astro
index 949ed87..d3ed6a3 100644
--- a/src/pages/blog/[...slug].astro
+++ b/src/pages/blog/[...slug].astro
@@ -1,10 +1,9 @@
 ---
-// Memo 060 PRD-005 (Phase 1a.4): Standalone-Page wurde zu einem duennen
-// Wrapper um BlogPostLayout.astro reduziert. getStaticPaths bleibt hier,
-// damit Astro die Routen aus der `blog`-Content-Collection generiert; die
-// eigentliche Render-Logik (Title + Author + Tags + Reading-Progress +
-// Custom-TOC + Share + Related-Posts) lebt jetzt im Layout und wird ueber
-// <StarlightPage> in den Starlight-Frame eingebettet.
+// Thin wrapper around BlogPostLayout.astro. getStaticPaths stays here so
+// Astro generates the routes from the `blog` content collection; the actual
+// render logic (Title + Author + Tags + Reading-Progress + Custom-TOC +
+// Share + Related-Posts) lives in the layout and is embedded via
+// <StarlightPage> into the Starlight frame.
 import BlogPostLayout from '../../layouts/BlogPostLayout.astro'
 import { getCollection } from 'astro:content'
 
diff --git a/src/pages/blog/index.astro b/src/pages/blog/index.astro
index ffad244..6b38b55 100644
--- a/src/pages/blog/index.astro
+++ b/src/pages/blog/index.astro
@@ -1,9 +1,8 @@
 ---
-// Memo 060 PRD-005 (Phase 1a.5): Standalone-Page wurde zu einem duennen
-// Wrapper um BlogIndexLayout.astro reduziert. Die eigentliche Render-Logik
-// (Featured + Filter + Grid) lebt jetzt im Layout und wird ueber
-// <StarlightPage> in den Starlight-Frame eingebettet — damit greift der
-// globale Header.astro mit funktionaler Pagefind-Search + LanguageSelect.
+// Thin wrapper around BlogIndexLayout.astro. The actual render logic
+// (Featured + Filter + Grid) lives in the layout and is embedded via
+// <StarlightPage> into the Starlight frame — so the global Header.astro
+// with the functional Pagefind search + LanguageSelect applies.
 import BlogIndexLayout from '../../layouts/BlogIndexLayout.astro'
 ---
 <BlogIndexLayout lang="en" />
diff --git a/src/pages/configurator.astro b/src/pages/configurator.astro
index 1e5274e..7ff88e0 100644
--- a/src/pages/configurator.astro
+++ b/src/pages/configurator.astro
@@ -1,8 +1,8 @@
 ---
-// Memo 121 Phase 5 (PRD-008): thin wrapper around ConfiguratorLayout.astro.
-// The render logic lives in the layout, embedded via <StarlightPage> so the
-// global Header.astro / Footer.astro apply unchanged (integration constraint,
-// Memo 121 Kap. 2). Mirrors the src/pages/blog/index.astro pattern.
+// Thin wrapper around ConfiguratorLayout.astro. The render logic lives in
+// the layout, embedded via <StarlightPage> so the global Header.astro /
+// Footer.astro apply unchanged (integration constraint). Mirrors the
+// src/pages/blog/index.astro pattern.
 import ConfiguratorLayout from '../layouts/ConfiguratorLayout.astro'
 ---
 <ConfiguratorLayout lang="en" />
diff --git a/src/scripts/mermaid-zoom.mjs b/src/scripts/mermaid-zoom.mjs
index e080fd0..c97a39e 100644
--- a/src/scripts/mermaid-zoom.mjs
+++ b/src/scripts/mermaid-zoom.mjs
@@ -1,7 +1,6 @@
-// Mermaid-Zoom — Memo 088 Kap. 5 (Phase 2)
-// Lightbox fuer rehype-mermaid inline-svg. Kein .mermaid-Wrapper:
-// rehype-mermaid rendert bare <svg id="mermaid-…">. Vanilla, keine Dependency.
-// Portiert aus cli/memo-toolkit/editor/src/MemoView.mjs (:8047-8082).
+// Mermaid zoom
+// Lightbox for rehype-mermaid inline SVG. No .mermaid wrapper:
+// rehype-mermaid renders a bare <svg id="mermaid-…">. Vanilla, no dependency.
 
 const OVERLAY_ID = 'flowmcp-mermaid-overlay'
 const TARGET_SELECTOR = '.sl-markdown-content svg[id^="mermaid"]'
@@ -26,11 +25,11 @@ const openOverlay = ( svgEl ) => {
     const overlay = ensureOverlay()
     const stage = overlay.querySelector( '.mermaid-overlay__stage' )
     const clone = svgEl.cloneNode( true )
-    // ID NICHT entfernen: rehype-mermaid bettet die Theme-Styles als
-    // id-skopierte Regeln ein (`#mermaid-N .node rect { fill: … }`). Ohne die ID
-    // greift keine Regel mehr und das SVG faellt auf SVG-Default fill:#000 zurueck
-    // (schwarze Boxen). Das Duplikat-ID-Risiko ist unkritisch (Original liegt
-    // unsichtbar hinter dem Overlay).
+    // Do NOT remove the ID: rehype-mermaid embeds the theme styles as
+    // id-scoped rules (`#mermaid-N .node rect { fill: … }`). Without the ID no
+    // rule matches and the SVG falls back to the SVG default fill:#000
+    // (black boxes). The duplicate-ID risk is harmless (the original sits
+    // invisibly behind the overlay).
     clone.removeAttribute( 'style' )
     clone.style.width = '100%'
     clone.style.height = '100%'
diff --git a/src/templates/de/quickstart/how-it-works.template.md b/src/templates/de/quickstart/how-it-works.template.md
new file mode 100644
index 0000000..3435041
--- /dev/null
+++ b/src/templates/de/quickstart/how-it-works.template.md
@@ -0,0 +1,231 @@
+---
+title: Wie es funktioniert
+description: "FlowMCP-Architektur und Datenfluss vom Schema zum KI-Tool"
+---
+<!-- PAGEFIND-META-START -->
+<span style="display:none" data-pagefind-meta="section">Docs > Getting Started</span>
+<!-- PAGEFIND-META-END -->
+
+## Architektur-Ueberblick
+
+FlowMCP transformiert deklarative Schema-Dateien in MCP Tools, die KI-Clients aufrufen koennen. Daten fliessen durch vier Schichten:
+
+```
+Web-Datenquellen → Schemas → Core Runtime → MCP Server → KI-Client
+    (APIs)          (.mjs)    (FlowMCP)      (stdio/HTTP)   (Claude, etc.)
+```
+
+Die Schema-Schicht ist dein Arbeitsbereich. Alles andere wird von der Runtime uebernommen.
+
+## Die vier Schritte
+
+1. **Definieren**
+
+   Schreibe ein Schema als `.mjs`-Datei. Jedes Schema deklariert ein oder mehrere API-Tools mit ihren Endpoints, Parametern, Authentifizierung und erwarteten Antworten.
+
+   ```javascript
+   // coingecko-ping.mjs
+   export const main = {
+       namespace: 'coingecko',
+       name: 'Ping',
+       description: 'Check CoinGecko API server status',
+       version: '4.1.0',
+       root: 'https://api.coingecko.com/api/v3',
+       requiredServerParams: [],
+       requiredLibraries: [],
+       headers: {},
+       tools: {
+           ping: {
+               method: 'GET',
+               path: '/ping',
+               description: 'Check if CoinGecko API is online',
+               parameters: []
+           }
+       }
+   }
+   ```
+
+2. **Validieren**
+
+   FlowMCP Core validiert dein Schema gegen Validierungsregeln, die Struktur, Namenskonventionen, Parameterformate, Sicherheitsbeschraenkungen und Output-Deklarationen abdecken.
+
+   ```javascript
+   import { FlowMCP } from 'flowmcp-core'
+   import { main } from './coingecko-ping.mjs'
+
+   const { status, messages } = FlowMCP.validateSchema( { schema: main } )
+   // status: true — Schema ist gueltig
+   // messages: [] — keine Validierungsfehler
+   ```
+
+   Validierung erkennt Probleme zur Entwicklungszeit — bevor dein Schema die Produktion erreicht.
+
+3. **Aktivieren**
+
+   FlowMCP Core transformiert dein Schema in MCP Tools mit automatisch generierter Zod-Validierung fuer jeden Parameter. Ein Schema mit 5 Tools wird zu 5 MCP Tools.
+
+   ```javascript
+   import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+
+   const server = new Server(
+       { name: 'my-server', version: '1.0.0' },
+       { capabilities: { tools: {} } }
+   )
+
+   FlowMCP.activateServerTools( { server, schemas: [main] } )
+   // Registriert: coingecko__ping als MCP Tool
+   ```
+
+4. **Nutzen**
+
+   KI-Clients entdecken und rufen deine Tools ueber das MCP-Protokoll auf. Der Client sieht Tool-Namen, Beschreibungen und Input-Schemas — alles, was fuer fundierte Tool-Aufrufe noetig ist.
+
+   ```
+   KI-Client: "Welche Tools sind verfuegbar?"
+   MCP Server: [coingecko__ping] — Check if CoinGecko API is online
+
+   KI-Client: ruft coingecko__ping({}) auf
+   MCP Server: { "gecko_says": "(V3) To the Moon!" }
+   ```
+
+## Schema-Anatomie
+
+Jedes FlowMCP v{{spec.currentVersion}} Schema nutzt das **Two-Export-Pattern**:
+
+### main (erforderlich)
+
+Der `main` Export ist ein einfaches JavaScript-Objekt, das alles ueber deine API-Endpoints deklariert. Es ist JSON-serialisierbar und kann fuer Integritaetspruefungen gehasht werden.
+
+```javascript
+export const main = {
+    // Identitaet
+    namespace: 'provider',       // Provider-Name (Kleinbuchstaben)
+    name: 'ToolName',            // Lesbarer Name
+    description: 'What it does', // Wird von KI-Clients genutzt
+    version: '4.1.0',            // Schema-Format-Version
+
+    // Verbindung
+    root: 'https://api.example.com', // Basis-URL
+    requiredServerParams: ['API_KEY'], // Serverseitige Secrets
+    requiredLibraries: [],        // Erlaubte npm-Pakete
+    headers: {                    // Request-Header
+        'Authorization': 'Bearer {{API_KEY}}'
+    },
+
+    // Tools (API Endpoints)
+    tools: {
+        toolName: {
+            method: 'GET',
+            path: '/endpoint/{{PARAM}}',
+            description: 'What this tool does',
+            parameters: [/* ... */],
+            output: {/* ... */}
+        }
+    },
+
+    // Resources (optional, SQLite schreibgeschuetzte Daten)
+    resources: {
+        resourceName: {
+            description: 'Read-only data lookup',
+            source: 'sqlite',
+            database: 'data.db',
+            queries: { /* ... */ }
+        }
+    },
+
+    // Skills (optional, KI-Agent-Anweisungen)
+    skills: [
+        { name: 'skill-name', file: 'skill-name.mjs', description: 'What this skill does' }
+    ]
+}
+```
+
+### handlers (optional)
+
+Der `handlers` Export ist eine **Factory-Funktion**, die injizierte Abhaengigkeiten empfaengt und Handler-Funktionen nach Tool-Name zurueckgibt. Verwende ihn, wenn API-Antworten transformiert werden muessen.
+
+```javascript
+export const handlers = ( { sharedLists, libraries } ) => ({
+    toolName: {
+        postProcess: ( { data } ) => {
+            // Die rohe API-Antwort transformieren
+            const parsed = JSON.parse( data )
+            const summary = parsed.results
+                .map( ( item ) => `${item.name}: ${item.value}` )
+                .join( '\n' )
+
+            return summary
+        }
+    }
+})
+```
+
+Das Factory-Pattern stellt sicher:
+- Keine freien Imports — Abhaengigkeiten werden injiziert
+- Shared Lists sind ohne Dateizugriff verfuegbar
+- Libraries sind via `requiredLibraries` vorab genehmigt
+
+## Parameter-Fluss
+
+Wenn ein KI-Client ein FlowMCP Tool aufruft, durchlaeuft der Request mehrere Stufen:
+
+```
+User Input          →  Zod-Validierung    →  URL-Konstruktion     →  API-Aufruf
+{ "id": "bitcoin" }    Validiert Typen,       Ersetzt {{ID}} in      GET https://api.
+                       Laengen, Formate       Pfad und Query         coingecko.com/...
+
+                                                                         ↓
+
+MCP-Antwort         ←  Handler (optional)  ←  Rohe Antwort
+{ content: [...] }     postProcess()          { "bitcoin": { ... } }
+                       transformiert Daten
+```
+
+Jede Stufe ist deterministisch: gleiche Eingabe erzeugt immer den gleichen API-Aufruf. Parameter-Validierung nutzt Zod-Schemas, die automatisch aus dem `parameters` Array im Schema generiert werden.
+
+## Shared Lists
+
+Manche Parameterwerte sind schema-uebergreifend wiederverwendbar — Chain IDs, Token-Symbole, Protokollnamen. Statt dass jedes Schema diese unabhaengig definiert, injiziert FlowMCP **Shared Lists** zur Ladezeit.
+
+```javascript
+// Im Schema — eine Shared List referenzieren
+parameters: [
+    {
+        position: { key: 'chain', value: '{{CHAIN}}', location: 'insert' },
+        z: { primitive: 'enum()', options: ['$chainIds'] }
+        //                                  ^ wird zur Laufzeit injiziert
+    }
+]
+
+// In Handlern — auf Shared Lists zugreifen
+export const handlers = ( { sharedLists } ) => ({
+    toolName: {
+        postProcess: ( { data } ) => {
+            const chainName = sharedLists.chainIds[data.chainId]
+            return `Chain: ${chainName}`
+        }
+    }
+})
+```
+
+Das haelt Schemas DRY und stellt Konsistenz ueber Provider hinweg sicher.
+
+## Sicherheitsmodell
+
+FlowMCP erzwingt Sicherheit auf Schema-Ebene:
+
+| Beschraenkung | Zweck |
+|---------------|-------|
+| **Null Imports** | Schemas koennen weder `import` noch `require` verwenden — alle Abhaengigkeiten werden injiziert |
+| **Library-Allowlist** | Nur in `requiredLibraries` deklarierte Pakete sind in Handlern verfuegbar |
+| **Statischer Scan** | Schemas werden zur Ladezeit auf verbotene Muster analysiert |
+| **Server Params** | API-Keys bleiben serverseitig — niemals fuer KI-Clients sichtbar |
+| **Integritaets-Hash** | Der `main` Export kann gehasht werden, um Schema-Manipulation zu erkennen |
+
+:::caution
+Schemas, die versuchen Module zu importieren, auf das Dateisystem zuzugreifen oder nicht deklarierte Libraries zu nutzen, werden zur Ladezeit abgelehnt. Das ist beabsichtigt — es schuetzt sowohl den Server-Betreiber als auch den KI-Client.
+:::
+
+:::note
+Fuer die vollstaendige Spezifikation einschliesslich aller Validierungsregeln, Parameterformate und Sicherheitsdetails, siehe die [Spezifikation v{{spec.currentVersion}}](/de/specification/overview/).
+:::