acdl/docs/presentations

Presentations

Leadership-facing presentation decks for the ACDL platform.

The 3-step slide creation process

Every presentation in this folder is produced by the same three-step process. Never edit the Marp deck or the PPTX directly — always start from the full markdown source of truth (Step 1), synthesize the Marp deck (Step 2), then export to PPTX (Step 3). This keeps a reviewable, plain-text source of truth for every deck.

Step 1: full markdown       Step 2: Marp deck           Step 3: PPTX export
(source of truth)    ──►    (lean, no notes)     ──►    (presentation-ready)
*.md                        *-marp.md                   *.pptx
+ speaker notes             + embedded PNG diagrams     + embedded images
+ mermaid code blocks       + Marp frontmatter

Step 1 — Full markdown (source of truth)

File convention: <deck-name>.md (e.g. how-the-platform-works.md).

Write the complete deck as a standard markdown file. This is the source of truth — it contains:

• Every slide as an ## Slide N — Title H2 section.
• Tight bullets with leadership-relevant content.
• A > **Speaker notes:** block at the end of each slide with the nuance, the "who cares and why," and the honesty caveats.
• Mermaid diagrams as ```mermaid fenced code blocks (these render on GitHub/Pages but not in Marp — Step 2 converts them to images).
• An honest "shipped vs. planned" framing: every "available today" claim is grounded in shipped/verified work; every "planned" item is explicitly marked.

Why this file is the source of truth: it is reviewable in any markdown viewer, diffs cleanly in git, and carries the full reasoning (speaker notes) that a presenter needs. The Marp deck and PPTX are derived artifacts — if a fact is wrong, fix it here and re-run Steps 2 and 3.

Step 2 — Marp deck synthesis

File convention: <deck-name>-marp.md (e.g. how-the-platform-works-marp.md).

Synthesize the full markdown into a lean Marp deck:

• Marp frontmatter at the top: marp: true, theme: default, paginate: true, size: 16x9, a header/footer, and an inline style: block for fonts, colors, tables, badges.
• No speaker notes. The Marp deck is what the audience sees; the speaker notes live only in the Step 1 source of truth.
• Mermaid diagrams → PNG images. Marp does not render mermaid fenced blocks natively. Extract each mermaid block from Step 1 into a .mmd source file under assets/mmd/, render it to PNG under assets/png/, and embed it with ![w:1000](assets/png/<name>.png).
• <!-- _class: title --> + <!-- _paginate: false --> on title and closing slides for the dark-background title style.
• Maturity badges using inline spans: <span class="badge today">Available today</span> <span class="badge planned">Planned</span>
• Tighter prose than Step 1 — strip the speaker-note nuance; keep the leadership-relevant selling points.

Step 3 — Render to HTML and PPTX

Both formats are derived from the Marp deck. HTML is committed to the repo (viewable in any browser, self-contained with base64-embedded images). PPTX is uploaded to the Gitea release as a downloadable attachment (binary, not committed to git).

HTML export (committed to repo)

CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  npx --yes @marp-team/marp-cli@latest --allow-local-files \
  docs/presentations/<deck-name>-marp.md \
  -o docs/presentations/<deck-name>.html

HTML export inlines images as base64 data URIs — no --allow-local-files needed for self-contained output, but it's required when the Marp deck references local PNG assets. The resulting HTML is a single self-contained file that renders the full deck with the S&P Global Energy theme.

Re-render the HTML whenever the Marp source changes. The HTML files are committed artifacts, not generated on-the-fly — they must be re-rendered and re-committed when the Marp deck is updated.

PPTX export (uploaded to Gitea release)

CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  npx --yes @marp-team/marp-cli@latest --allow-local-files \
  docs/presentations/<deck-name>-marp.md \
  -o <output-path>.pptx

The --allow-local-files flag is required for PPTX export so the local PNG diagrams are embedded in the file. PPTX files are not committed to the repo (binary, no meaningful diffs) — they are uploaded to the Gitea release as downloadable attachments.

Directory layout

docs/presentations/
├── README.md                                  ← this file
├── how-the-platform-works.md                  ← Step 1: full source of truth
├── how-the-platform-works-marp.md              ← Step 2: Marp deck
├── how-the-platform-works.html                  ← Step 3: rendered HTML (committed)
├── the-developer-experience.md                 ← Step 1: full source of truth
├── the-developer-experience-marp.md            ← Step 2: Marp deck
├── the-developer-experience.html               ← Step 3: rendered HTML (committed)
└── assets/
    ├── puppeteer-config.json                   ← no-sandbox config for mmdc
    ├── mmd/                                     ← mermaid source files (Step 2 input)
    │   ├── platform-works-01-contract-driven.mmd
    │   ├── platform-works-02-end-to-end-flow.mmd
    │   ├── developer-experience-01-two-surfaces.mmd
    │   ├── developer-experience-02-what-dev-does.mmd
    │   └── developer-experience-03-no-cloning.mmd
    └── png/                                     ← rendered PNGs (embedded in Marp)
        ├── platform-works-01-contract-driven.png
        ├── platform-works-02-end-to-end-flow.png
        ├── developer-experience-01-two-surfaces.png
        ├── developer-experience-02-what-dev-does.png
        └── developer-experience-03-no-cloning.png

Conventions

Maturity framing

Every capability claim in a deck is tagged with one of two badges:

Badge	Meaning
Available today	Shipped and verified in the platform
Planned	On the roadmap, not yet shipped

This is non-negotiable for a leadership audience: never present a roadmap item as a current capability, and never bury a shipped capability's availability. When in doubt, check .ciagent/ROADMAP.md and the milestone status in .ciagent/PROJECT.md.

Audience

The audience for these decks is Senior Leadership: CTO, Head of Cloud, Head of Infrastructure, Head of DevOps. The framing rules:

• No jargon. Translate internal terms: "primitives/modules" not "L1/L2", "intent" not "IR", "human attestation" not "HITL", "pattern" not "composition."
• Selling points forward. Each slide leads with the leadership-relevant outcome; the mechanism follows.
• Zero-trust, security, observability, auditability, DX, citizen developer are the themes — not implementation details.

Diagrams

Mermaid diagrams in the Step 1 source use the repo's existing flowchart style (renders on GitHub/Pages). For the Marp deck (Step 2):

1. Extract the mermaid block into assets/mmd/<deck>-<slide>-<name>.mmd.
2. Use horizontal layouts (flowchart LR) or subgraph row-wrapping for wide diagrams so the PNG fits a 16:9 slide without shrinking to illegibility. A 9-node sequential flowchart TD renders as a tall thin strip — restructure it as 2-row subgraphs or flowchart LR.
3. Render with a 2x scale factor and transparent background for crisp slides.
4. Embed with ![w:1000](assets/png/<name>.png) (or h:320 for tall images).

Build commands

Prerequisites

• Node.js + npx (for @marp-team/marp-cli and @mermaid-js/mermaid-cli)
• A Chrome/Chromium binary (Marp PPTX export requires it)

This environment has a working Chromium at: /root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome

Render all mermaid diagrams to PNG

cd docs/presentations/assets
for f in mmd/*.mmd; do
  name=$(basename "$f" .mmd)
  PUPPETEER_EXECUTABLE_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
    npx --yes @mermaid-js/mermaid-cli@latest \
    -i "$f" -o "png/$name.png" \
    -p puppeteer-config.json -s 2 -b transparent
done

The puppeteer-config.json passes --no-sandbox to the headless browser (required when running as root in this environment).

Export a Marp deck to HTML (committed to repo)

CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  npx --yes @marp-team/marp-cli@latest --allow-local-files \
  docs/presentations/<deck-name>-marp.md \
  -o docs/presentations/<deck-name>.html

HTML export inlines images as base64 data URIs. The --allow-local-files flag is needed when the Marp deck references local PNG assets (like the diagram images in assets/png/). The resulting HTML is self-contained.

The HTML files are committed artifacts — re-render and re-commit whenever the Marp source changes.

Export a Marp deck to PPTX (uploaded to Gitea release)

CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  npx --yes @marp-team/marp-cli@latest --allow-local-files \
  docs/presentations/<deck-name>-marp.md \
  -o <output-path>.pptx

--allow-local-files is required for PPTX so local PNG diagrams are embedded in the file. PPTX files are not committed to git — upload them as attachments to the Gitea release.

Adding a new presentation

1. Write the full markdown as <deck-name>.md following the ## Slide N — Title + > **Speaker notes:** structure. This is the source of truth.
2. Extract any mermaid diagrams into assets/mmd/<deck-name>-<slide>-<name>.mmd and render them to assets/png/ (command above).
3. Synthesize the Marp deck as <deck-name>-marp.md with frontmatter, no speaker notes, embedded PNGs, and maturity badges.
4. Render to HTML with --allow-local-files and commit the HTML to docs/presentations/<deck-name>.html.
5. Render to PPTX with --allow-local-files and upload to the Gitea release (do not commit PPTX to git).
6. Verify the PPTX slide count and that media files are embedded:

   python3 -c "
   import zipfile, re
   with zipfile.ZipFile('<output>.pptx') as z:
       slides = [n for n in z.namelist() if re.match(r'ppt/slides/slide\d+\.xml$', n)]
       media = [n for n in z.namelist() if n.startswith('ppt/media/')]
       print(f'{len(slides)} slides, {len(media)} media files')
   "
   

Current decks

Deck	Source of truth (Step 1)	Marp deck (Step 2)	Rendered HTML (Step 3)	Audience
How the Platform Works	how-the-platform-works.md	how-the-platform-works-marp.md	how-the-platform-works.html	CTO, Head of Cloud, Head of Infra, Head of DevOps
The Developer Experience	the-developer-experience.md	the-developer-experience-marp.md	the-developer-experience.html	CTO, Head of Cloud, Head of Infra, Head of DevOps