acdl/docs/presentations/README.md

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

```bash
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

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