diff --git a/docs/superpowers/specs/2026-05-10-mermaid-pipeline-design.md b/docs/superpowers/specs/2026-05-10-mermaid-pipeline-design.md
new file mode 100644
index 0000000..00cbbc2
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-10-mermaid-pipeline-design.md
@@ -0,0 +1,63 @@
+# Mermaid + Marp Pipeline Design
+
+**Date:** 2026-05-10
+**Status:** Approved
+
+## Goal
+
+Enable Mermaid diagrams in Marp presentations without any per-file manual steps for authors. A push to the repo triggers the existing webhook CI, which builds the slides and serves them at `slides.makerfloss.eu`.
+
+## Context
+
+- Webhook CI is live: `push → build-slides.sh → slides/` served at `slides.makerfloss.eu`
+- `build-slides.sh` already passes `--html` to marp (raw HTML in markdown is allowed)
+- Marp emits fenced mermaid blocks as `<pre><code class="language-mermaid">…</code></pre>`
+- A previous attempt (`2459b4c`) used a custom `marp.config.mjs` but failed: it overrode `rules.code` instead of `rules.fence`, so mermaid blocks were never transformed. That approach also required `npm install` on the server. It was reverted.
+
+## Approach: HTML post-processing in `build-slides.sh`
+
+After the marp build, loop over every `slides/*.html`. For each file that contains `class="language-mermaid"`, inject the following snippet before `</body>`:
+
+```html
+<script type="module">
+import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+document.querySelectorAll('code.language-mermaid').forEach(el => {
+  const div = document.createElement('div');
+  div.className = 'mermaid';
+  div.textContent = el.textContent;
+  el.closest('pre').replaceWith(div);
+});
+mermaid.initialize({ startOnLoad: false, theme: 'dark' });
+await mermaid.run();
+</script>
+```
+
+Injection uses `python3` (reliable string replacement, avoids `sed` quoting issues; python3 is available on any Debian-based host).
+
+### Why this approach
+
+- Zero server changes required
+- Zero per-file authoring requirements — authors write normal ` ```mermaid ` fences
+- Works with all three build paths in `build-slides.sh` (npx / global marp / Docker)
+- Only injects into files that actually contain mermaid blocks
+
+### Constraints
+
+- Mermaid theme hardcoded to `'dark'` — all current presentations use the dark gaia theme
+- Requires browser with ES module support (all modern browsers qualify)
+- Mermaid rendering is client-side; diagrams will not appear in PDF exports
+
+## Changes
+
+| File | Change |
+|------|--------|
+| `build-slides.sh` | Add post-processing loop after marp build |
+| `docs/test-mermaid.md` | New test presentation with mermaid diagram |
+
+## Test plan
+
+1. Push `docs/test-mermaid.md` to `main`
+2. Webhook triggers; wait for build
+3. Verify `slides.makerfloss.eu/test-mermaid.html` is listed on the index
+4. Open the slide and confirm the mermaid diagram renders (not a code block)
+5. Verify existing slides (`messaging-presentation`, `SoMe-taxonomi`, `labdesign`) are unaffected