acdl/docs/presentations/README.md

# 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
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
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:
   ```bash
   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.