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 — PPTX export

Export the Marp deck to PPTX for stakeholders who want a slide file:

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.

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
├── the-developer-experience.md                 ← Step 1: full source of truth
├── the-developer-experience-marp.md            ← Step 2: Marp deck
└── 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 (for browser preview)

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

HTML export inlines images as base64 data URIs — no --allow-local-files needed.

Export a Marp deck to PPTX (for stakeholders)

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.

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. Export to PPTX with --allow-local-files.
5. 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)	Audience
How the Platform Works	how-the-platform-works.md	how-the-platform-works-marp.md	CTO, Head of Cloud, Head of Infra, Head of DevOps
The Developer Experience	the-developer-experience.md	the-developer-experience-marp.md	CTO, Head of Cloud, Head of Infra, Head of DevOps