acdl/docs/presentations/README.md

Presentations

Leadership-facing presentation decks for the ACDL platform.

The 4-step slide creation process

Every presentation in this folder is produced by the same four-step process. Never edit the Marp deck, the PPTX, or the talking points directly — always start from the full markdown source of truth (Step 1), synthesize the Marp deck (Step 2), export to HTML + PPTX (Step 3), then distill the talking points (Step 4). This keeps a reviewable, plain-text source of truth for every deck and a presenter-ready cue sheet for delivery.

Step 1: full markdown       Step 2: Marp deck           Step 3: HTML + PPTX         Step 4: Talking points
(source of truth)    ──►    (lean, 10 slides)    ──►    (rendered)           ──►    (presenter cues)
*.md                        *-marp.md                   *.html / *.pptx             *-talking-points.md
+ speaker notes             + embedded PNG diagrams                                 + 3-6 bullets per slide
+ mermaid code blocks       + Marp frontmatter                                     + key takeaway per slide
                            + maturity badges                                      + indexed by Marp slide #
                            + no speaker notes                                     + content distilled from Step 1

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 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.

Step 4 — Talking points (presenter cues)

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

Distill the source of truth (Step 1) into presenter-ready cues, indexed by the Marp deck (Step 2) slide structure:

• One section per Marp slide — ## Slide N — Title, matching the Marp deck's 11 main + Appendix TOC + appendix slide structure exactly. The Marp deck provides the indexing and context (what the audience sees); the source markdown provides the content (the speaker notes, the detail, the nuance).
• 3-6 talking point bullets per slide — punchy, actionable cues distilled from the source markdown's speaker notes. NOT the speaker notes verbatim (those are too long and too contextual). These are prompts: "Land this point," "Contrast with X," "Be honest about Y."
• Key takeaway per slide — the one memorable thing the audience should walk away with from that slide.
• No content duplication — the talking points reference the Marp slides for visual context and the source markdown for full detail. They don't repeat either; they bridge them.

Why this file exists: a presenter needs a cue sheet they can glance at during delivery — not the full speaker notes (too long), not the Marp slides (no detail). The talking points file is the middle layer: what to say, in what order, with what emphasis, per slide.

When to update: re-distill the talking points whenever the Marp deck structure changes (slides added, removed, merged, or re-ordered) or whenever the source markdown's speaker notes are updated. The talking points are a derived artifact — if a fact is wrong, fix it in the source markdown (Step 1) and re-distill.

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 (11 main + TOC + 8 appendix = 20)
├── how-the-platform-works.html                  ← Step 3: rendered HTML (committed)
├── how-the-platform-works-talking-points.md    ← Step 4: presenter cues (20 sections)
├── the-developer-experience.md                 ← Step 1: full source of truth
├── the-developer-experience-marp.md            ← Step 2: Marp deck (11 main + TOC + 7 appendix = 19)
├── the-developer-experience.html               ← Step 3: rendered HTML (committed)
├── the-developer-experience-talking-points.md  ← Step 4: presenter cues (19 sections)
└── assets/
    ├── puppeteer-config.json                   ← no-sandbox config for mmdc
    ├── mmd/                                     ← mermaid source files (Step 2 input)
    │   ├── sp-theme.json                         ← S&P Red/Black/White theme (mermaid-cli --configFile)
    │   ├── platform-works-01-contract-driven.mmd
    │   ├── platform-works-02-frictions.mmd
    │   ├── platform-works-02-end-to-end-flow.mmd
    │   ├── platform-works-03-north-star.mmd
    │   ├── platform-works-03-scope-boundary.mmd
    │   ├── platform-works-04-confidence-signal.mmd
    │   ├── platform-works-05-attestation-flow.mmd
    │   ├── platform-works-07-zero-trust.mmd
    │   ├── developer-experience-01b-scope-boundary.mmd
    │   ├── developer-experience-02-what-dev-does.mmd
    │   ├── developer-experience-03-no-cloning.mmd
    │   ├── developer-experience-04-promotion-journey.mmd
    │   ├── developer-experience-05-catalog.mmd
    │   ├── developer-experience-07-decommission.mmd
    │   ├── developer-experience-08-semver.mmd
    │   ├── platform-architecture.mmd                ← shared high-level logical architecture (both decks)
    │   └── road-to-north-star.mmd
    └── png/                                     ← rendered PNGs (embedded in Marp)
        ├── platform-works-01-contract-driven.png
        ├── platform-works-02-frictions.png
        ├── platform-works-02-end-to-end-flow.png
        ├── platform-works-03-north-star.png
        ├── platform-works-03-scope-boundary.png
        ├── platform-works-04-confidence-signal.png
        ├── platform-works-05-attestation-flow.png
        ├── platform-works-07-zero-trust.png
        ├── developer-experience-01b-scope-boundary.png
        ├── developer-experience-02-what-dev-does.png
        ├── developer-experience-03-no-cloning.png
        ├── developer-experience-04-promotion-journey.png
        ├── developer-experience-05-catalog.png
        ├── developer-experience-07-decommission.png
        ├── developer-experience-08-semver.png
        ├── platform-architecture.png                ← shared high-level logical architecture (both decks)
        └── road-to-north-star.png

Conventions

Appendix structure

Each Marp deck has 11 main slides + an Appendix TOC + appendix slides. The main 11 are the presentation; the appendix is for deep dives and Q&A backup. The platform-works deck has 8 appendix slides (A1–A8); the developer-experience deck has 7 appendix slides (A1–A7). Both include an Appendix TOC slide.

• Main slides (1-11): the story arc, high-impact, minimal text, visual-heavy. These are what the audience sees during the talk.
• Appendix slides (TOC + A1..An): detail-heavy slides moved out of the main 10 to preserve the narrative flow. The appendix starts with a TOC slide listing the contents, followed by detail slides and a glossary.
• The Road to the North Star is a required appendix slide in both decks — a phased timeline from v1.0 demo to the North Star, annotated as "proposed phasing, not formally planned."
• The Glossary is a required appendix slide in both decks — defines acronyms (OIDC, ABAC, CMK, CMDB, RPO, HITL, VCS, NFR) for the audience.

Maturity framing

Every capability claim in a deck is tagged with a Planned badge when the item is on the roadmap but not yet implemented:

Badge	Meaning
Planned	On the roadmap, not yet implemented

This is non-negotiable for a leadership audience: never present a roadmap item as a current capability, and never bury a tested 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 \
    --configFile mmd/sp-theme.json
done

The puppeteer-config.json passes --no-sandbox to the headless browser (required when running as root in this environment). The --configFile mmd/sp-theme.json applies the S&P Global Red/Black/White theme (dark #1B1B1B accent nodes with #D6002A red borders, white supporting nodes, #F0F0F0 subgraph backgrounds). Each .mmd file also carries the same theme inline via a %%{init:...}%% block so it renders correctly even without the --configFile flag.

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. Distill the talking points as <deck-name>-talking-points.md — one section per Marp slide, 3-6 talking point bullets + key takeaway, content distilled from the source markdown (Step 1), indexed by the Marp deck (Step 2) slide structure.
7. 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)	Talking points (Step 4)	Slides	Audience
How the Platform Works	how-the-platform-works.md	how-the-platform-works-marp.md	how-the-platform-works.html	how-the-platform-works-talking-points.md	11 main + TOC + 8 appendix (20)	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	the-developer-experience-talking-points.md	11 main + TOC + 7 appendix (19)	CTO, Head of Cloud, Head of Infra, Head of DevOps