acdl/docs/presentations/README.md

# Presentations

Leadership-facing presentation decks for the ACDL platform.

## The 3-step slide creation process

Every presentation in this folder is produced by the same three-step process.
**Never edit the Marp deck or the PPTX directly** — always start from the full
markdown source of truth (Step 1), synthesize the Marp deck (Step 2), then
export to PPTX (Step 3). This keeps a reviewable, plain-text source of truth
for every deck.

```
Step 1: full markdown       Step 2: Marp deck           Step 3: PPTX export
(source of truth)    ──►    (lean, no notes)     ──►    (presentation-ready)
*.md                        *-marp.md                   *.pptx
+ speaker notes             + embedded PNG diagrams     + embedded images
+ mermaid code blocks       + Marp frontmatter
```

### 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 testing">Testing</span>`
  `<span class="badge planned">Planned</span>`
  `<span class="badge agentic">Agentic</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)

```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 — 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)

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

## 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
├── how-the-platform-works.html                  ← Step 3: rendered HTML (committed)
├── the-developer-experience.md                 ← Step 1: full source of truth
├── the-developer-experience-marp.md            ← Step 2: Marp deck
├── the-developer-experience.html               ← Step 3: rendered HTML (committed)
└── assets/
    ├── puppeteer-config.json                   ← no-sandbox config for mmdc
    ├── mmd/                                     ← mermaid source files (Step 2 input)
    │   ├── platform-works-01-contract-driven.mmd
    │   ├── platform-works-02-end-to-end-flow.mmd
    │   ├── developer-experience-01-two-surfaces.mmd
    │   ├── developer-experience-02-what-dev-does.mmd
    │   └── developer-experience-03-no-cloning.mmd
    └── png/                                     ← rendered PNGs (embedded in Marp)
        ├── platform-works-01-contract-driven.png
        ├── platform-works-02-end-to-end-flow.png
        ├── developer-experience-01-two-surfaces.png
        ├── developer-experience-02-what-dev-does.png
        └── developer-experience-03-no-cloning.png
```

## Conventions

### Maturity framing

Every capability claim in a deck is tagged with one of three badges:

| Badge | Meaning |
|---|---|
| `Testing` | Works internally, not yet released to consumers (0 adoption) |
| `Planned` | On the roadmap, not yet implemented |
| `Agentic` | Involves AI agents, autonomous decision-making, or the citizen developer flow |

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

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

The `puppeteer-config.json` passes `--no-sandbox` to the headless browser
(required when running as root in this environment).

### Export a Marp deck to HTML (committed to repo)

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

```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 <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. **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 (Step 3) | Audience |
|---|---|---|---|---|
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | `how-the-platform-works.html` | 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` | CTO, Head of Cloud, Head of Infra, Head of DevOps |