acdl/docs/presentations

Presentations

Leadership-facing presentation decks for the Nova 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, 21 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
                            + no speaker notes                                     + indexed by Marp slide #
                            + no maturity badges                                   + content distilled from Step 1
                            + no version in footer

Step 1 — Full markdown (source of truth)

File convention: <deck-name>.md (e.g. nova-autonomous-cloud-delivery.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. deferred" framing: every "available today" claim is grounded in shipped/verified work; every "deferred" item is explicitly marked with the blocking work in plain language.

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. nova-autonomous-cloud-delivery-marp.md).

Synthesize the full markdown into a lean Marp deck:

• Marp frontmatter at the top: marp: true, theme: nova-sp, paginate: true, size: 16x9, a header/footer, and an inline style: block for fonts, colors, tables.
• 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.
• No maturity badges. The deck no longer uses <span class="badge"> spans. Deferred items are named in plain language with their blocking work, not tagged with a badge.
• No version in the footer. The footer carries the deck title only.
• 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 also committed to the repo as a first-class binary artifact and is attached to the phase's release via scripts/attach_release_asset.py.

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. PPTX export requires --allow-local-files so the local PNG diagrams are embedded in the file. The render + commit + attach pipeline is automated by scripts/render_slides.sh.

Step 4 — Talking points (presenter cues)

File convention: <deck-name>-talking-points.md (e.g. nova-autonomous-cloud-delivery-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 20 main + 1 appendix slide structure exactly.
• 3-6 talking point bullets per slide — punchy, actionable cues distilled from the source markdown's speaker notes.
• 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.

Directory layout

docs/presentations/
├── README.md                                  ← this file
├── nova-autonomous-cloud-delivery.md                 ← Step 1: full source of truth (20 main slides + speaker notes)
├── nova-autonomous-cloud-delivery-marp.md            ← Step 2: Marp deck (20 main + 1 appendix = 21 slides)
├── nova-autonomous-cloud-delivery.html               ← Step 3: rendered HTML (committed, S&P-themed)
├── nova-autonomous-cloud-delivery.pptx               ← Step 3: rendered PPTX (committed, S&P-themed)
├── nova-autonomous-cloud-delivery-talking-points.md  ← Step 4: presenter cues (19 sections)
└── assets/
    ├── nova-sp-theme.css                       ← S&P Global Energy Marp theme (all slide chrome)
    ├── 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)
    │   └── ... (per-slide .mmd files)
    └── png/                                     ← rendered mermaid PNGs (committed, S&P-themed)

Conventions

Appendix structure

Each Marp deck has 20 main slides + 1 appendix slide. The main 20 are the presentation; the appendix is for Q&A backup. (v1.22 split slides 3 and 8 to relieve overflow, increasing the count from 18 to 20.)

• Main slides (1-20): the story arc — Problem → Solution → Proof → Roadmap + Ask. These are what the audience sees during the talk.
• Appendix slide (A1): the Metrics Glossary — detail-heavy reference for Q&A.

Honesty framing

Every capability claim in the deck is grounded, derived, or honestly deferred with its blocking work named in plain language. Internal provenance (decision IDs, requirement IDs, internal file paths) is kept out of the audience-facing slides — those live in the .ciagent/ files only. 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.
• Security, remediation velocity, reliability, lead time, observability, citizen developer are the themes — not implementation details.
• "Infrastructure operations become visible" is the recurring theme across the deck.

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

Render a Marp deck to HTML + PPTX (committed artifacts)

bash scripts/render_slides.sh nova-autonomous-cloud-delivery

This renders all mermaid PNGs, the HTML, and the PPTX, and stages them for commit. The --allow-local-files flag is required so local PNG diagrams are embedded. Both HTML and PPTX are committed to the repo; the PPTX is also attached to the phase's 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 no badges.
4. Render to HTML + PPTX via scripts/render_slides.sh <deck-name> and commit both to docs/presentations/.
5. 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.
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 + PPTX (Step 3)	Talking points (Step 4)	Slides	Audience
Nova — The Autonomous Cloud Delivery Platform	nova-autonomous-cloud-delivery.md	nova-autonomous-cloud-delivery-marp.md	nova-autonomous-cloud-delivery.html + .pptx (committed + release-attached)	nova-autonomous-cloud-delivery-talking-points.md	20 main + 1 appendix (21)	CTO, Head of Cloud, Head of Infra, Head of DevOps

v1.21: the deck was renamed from "No-Humans Infrastructure Platform" to "Autonomous Cloud Delivery Platform" (professional framing; conveys autonomy without the provocative wording). The narrative restructured to a 4-beat arc (Problem → Solution → Proof → Roadmap + Ask). Internal provenance (decision IDs, requirement IDs, file paths) removed from audience-facing slides. Maturity badges removed. The RACI matrix expanded to four roles (Quality Engineering + SRE). The Atelier slide split into two. The pipeline hardened: Checkov on static code before the plan; Wiz-or-Checkov on the plan (never both).