acdl/docs/presentations

Presentations

Leadership-facing presentation decks for the Nova platform.

The 3-step slide creation process

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

Step 1: Author the deck       Step 2: Render              Step 3: Talking points
(source of truth)       ──►   (HTML + dual PPTX)     ──►   (presenter cues)
*-marp.md                      *.html                       *-talking-points.md
+ ## Slide N — Title          + mermaid PNGs               + 3-6 bullets per slide
+ <!-- Speaker notes: -->     + MARP PPTX (image-of-slide)  + key takeaway per slide
+ <!-- Talking points: -->    + python PPTX (structured)    + indexed by slide #
+ <div class="benefit">       + base64-inlined HTML         + content distilled from
+ embedded PNG diagrams        (self-contained)              the Marp deck

Step 1 — Author the deck (source of truth)

File convention: <deck-name>-marp.md (e.g. nova-autonomous-cloud-delivery-marp.md).

This is the sole source of truth — the Marp deck that is both authored and rendered. It contains:

• Marp frontmatter at the top: marp: true, theme: default, paginate: true, size: 16x9, a header/footer, and an inline style: block carrying the S&P palette (#D6002A red, #1B1B1B black, the section.title rule). The styling is inline — no standalone theme CSS is loaded at render time.
• Every slide as an ## Slide N — Title (or ## Appendix A1 — Title) H2 section. The H1 title slide precedes slide 1.
• Tight bullets with leadership-relevant content.
• Speaker notes as <!-- Speaker notes: ... --> HTML comments at the end of each slide. Marp excludes HTML comments from the rendered slide; they are for authors/presenters only.
• Talking points as <!-- Talking points: ... --> HTML comments (also excluded from rendering — Step 3 mirrors them into a standalone cue sheet).
• Benefit callouts as <div class="benefit">...</div> (styled by the inline style: block — italic, S&P-red top border). No **Benefit:** text prefixes.
• Mermaid diagrams pre-rendered to PNG under assets/png/ and embedded with ![w:1000](assets/png/<name>.png) (or h:480 class:tall for tall images). The .mmd sources live under assets/mmd/.
• No maturity badges, no version in the footer, no internal decision/requirement IDs or .py file paths in the slide bodies (those live in the .ciagent/ files only; speaker-note HTML comments are exempt).
• 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 the Marp deck 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 HTML and PPTX are derived artifacts — if a fact is wrong, fix it here and re-run Step 2.

nova-sp-theme.css is RETIRED from render. The standalone theme stylesheet under assets/nova-sp-theme.css is kept as a reference only and is not loaded at render time. The live styling is the inline style: block in the -marp.md frontmatter. Do NOT pass the CSS via --theme; it is not in the render path.

Step 2 — Render (HTML + dual PPTX)

bash scripts/render_slides.sh [deck-name] renders the Marp deck end-to-end:

1. Mermaid PNGs — each assets/mmd/*.mmd → assets/png/*.png (S&P-themed via sp-theme.json, 2x scale, transparent background).
2. MARP HTML — *-marp.md → *.html (S&P inline style, Marp default theme). Pinned @marp-team/marp-cli@4.5.0.
3. MARP PPTX — *-marp.md → *.pptx (image-of-slide PPTX; the primary release attachment).
4. Inline images — scripts/inline_images.py rewrites the HTML to base64-embed every assets/ image so the HTML is self-contained (no external asset folder needed for redistribution).
5. python PPTX — scripts/render_pptx.py produces a second, structured, editable PPTX (*-python.pptx) with native text boxes, native tables, embedded pictures, and italic benefit callouts.
6. Stage — all rendered artifacts (PNGs + HTML + both PPTX) are git add-ed for commit.

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

Both the HTML and both PPTX files are committed to the repo; the MARP PPTX is also attached to the phase's release via scripts/attach_release_asset.py.

Dual-PPTX output

PPTX	File	Render	Purpose
MARP PPTX	*.pptx	@marp-team/marp-cli (Chrome screenshot of each slide)	Image-of-slide; the primary release attachment (pixel-perfect, not editable)
python PPTX	*-python.pptx	scripts/render_pptx.py (python-pptx)	Structured, editable PPTX (native text boxes, tables, pictures) for comparison/editing

Step 3 — Talking points (presenter cues)

File convention: <deck-name>-talking-points.md (e.g. nova-autonomous-cloud-delivery-talking-points.md).

Distill the deck's <!-- Talking points: --> HTML comments into presenter-ready cues, indexed by the Marp deck (Step 1) 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 Marp deck's <!-- Talking points: --> comments.
• 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.

Directory layout

docs/presentations/
├── README.md                                  ← this file
├── nova-autonomous-cloud-delivery-marp.md            ← Step 1: sole source of truth (title + 20 main + 1 appendix = 22 slides + speaker notes + talking points)
├── nova-autonomous-cloud-delivery.html               ← Step 2: rendered HTML (committed, S&P inline style, base64-inlined images)
├── nova-autonomous-cloud-delivery.pptx               ← Step 2: MARP PPTX (image-of-slide, primary release attachment)
├── nova-autonomous-cloud-delivery-python.pptx        ← Step 2: python-pptx (structured, editable)
├── nova-autonomous-cloud-delivery-talking-points.md  ← Step 3: presenter cues (21 sections)
└── assets/
    ├── nova-sp-theme.css                       ← RETIRED from render — reference only (not loaded; live styling is the inline `style:` block)
    ├── 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, 2x, transparent)

Tooling & scripts

Script	Purpose
scripts/render_slides.sh	End-to-end render: mermaid PNGs → MARP HTML + PPTX → base64-inlined HTML → python-pptx PPTX → stage all artifacts. Pinned @marp-team/marp-cli@4.5.0 + @mermaid-js/mermaid-cli@11.16.0.
scripts/inline_images.py	Rewrites the rendered HTML to base64-embed every assets/ image (self-contained HTML for redistribution).
scripts/render_pptx.py	Produces the structured, editable *-python.pptx (native text boxes, tables, pictures, italic benefit callouts) via python-pptx.
scripts/attach_release_asset.py	Attaches the MARP PPTX to the phase's release.

Dependency	Where declared	Purpose
@marp-team/marp-cli@4.5.0	scripts/render_slides.sh (pinned)	Marp → HTML + PPTX
@mermaid-js/mermaid-cli@11.16.0	scripts/render_slides.sh (pinned)	Mermaid → PNG
python-pptx>=0.6.23	pyproject.toml [project.optional-dependencies] slides	Structured PPTX (pip install -e ".[slides]")

Conventions

Slide structure

Each Marp deck has 1 title slide + 20 main slides + 1 appendix slide = 22 rendered slides (21 ## sections + the H1 title 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 main count from 18 to 20.)

• Title slide (H1): <!-- _class: title --> + <!-- _paginate: false --> for the dark-background title style (S&P-red top border on black).
• 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 slide bodies — those live in the .ciagent/ files only (and may appear inside <!-- ... --> speaker-note comments, which Marp excludes from the rendered slide). 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 are authored as assets/mmd/*.mmd source files and rendered to PNG under assets/png/:

1. Author the mermaid block as 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 (scripts/render_slides.sh does this with the S&P theme JSON).
4. Embed with ![w:1000](assets/png/<name>.png) (or h:480 class:tall for tall images).
5. The render pipeline base64-inlines the PNGs into the committed HTML so the HTML is self-contained.

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)
• Python 3.10+ with the slides extra: pip install -e ".[slides]" (installs python-pptx>=0.6.23)

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

Render the deck (HTML + dual PPTX + inlined images)

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

This renders all mermaid PNGs, the HTML (with base64-inlined images), the MARP PPTX, and the python-pptx PPTX, and stages them for commit. Both HTML and both PPTX files are committed to the repo; the MARP PPTX is also attached to the phase's release.

Adding a new presentation

1. Author the Marp deck as <deck-name>-marp.md — frontmatter (marp: true, theme: default, paginate: true, size: 16x9, an inline style: block with the S&P palette), ## Slide N — Title sections, <!-- Speaker notes: --> + <!-- Talking points: --> HTML comments, and <div class="benefit"> callouts. This is the sole source of truth.
2. Author any mermaid diagrams as assets/mmd/<deck-name>-<slide>-<name>.mmd (Step 2 renders them to assets/png/).
3. Render via bash scripts/render_slides.sh <deck-name> — this produces the HTML (base64-inlined), the MARP PPTX, and the python-pptx PPTX, and stages all of them (plus the PNGs) for commit.
4. 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 Marp deck's <!-- Talking points: --> comments, indexed by the Marp deck slide structure.
5. Verify the PPTX slide count and that media files are embedded:

   python3 -c "
   import zipfile, re
   with zipfile.ZipFile('docs/presentations/<deck-name>.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)	Rendered HTML + dual PPTX (Step 2)	Talking points (Step 3)	Slides	Audience
Nova — The Autonomous Cloud Delivery Platform	nova-autonomous-cloud-delivery-marp.md	nova-autonomous-cloud-delivery.html (inlined) + nova-autonomous-cloud-delivery.pptx (MARP, release-attached) + nova-autonomous-cloud-delivery-python.pptx (structured)	nova-autonomous-cloud-delivery-talking-points.md	title + 20 main + 1 appendix (22)	CTO, Head of Cloud, Head of Infra, Head of DevOps

v1.23: the slide creation process collapsed from 4 steps to 3 — the plain <deck-name>.md was deleted; <deck-name>-marp.md is now the sole source of truth. The standalone nova-sp-theme.css was retired from render (the live styling is the inline style: block in the -marp.md frontmatter; the CSS file is retained as a reference only). Speaker notes moved from blockquotes into <!-- Speaker notes: --> HTML comments. Benefit callouts moved from **Benefit:** prefixes to <div class="benefit">. The render pipeline now produces a dual-PPTX output (MARP image-of-slide + python-pptx structured) and base64-inlines all images into the committed HTML.