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 today">Available today</span>`
  `<span class="badge planned">Planned</span>`
- **Tighter prose** than Step 1 — strip the speaker-note nuance; keep the
  leadership-relevant selling points.

### Step 3 — PPTX export

Export the Marp deck to PPTX for stakeholders who want a slide file:

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

## 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
├── the-developer-experience.md                 ← Step 1: full source of truth
├── the-developer-experience-marp.md            ← Step 2: Marp deck
└── 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 two badges:

| Badge | Meaning |
|---|---|
| `Available today` | Shipped and verified in the platform |
| `Planned` | On the roadmap, not yet shipped |

This is non-negotiable for a leadership audience: never present a roadmap
item as a current capability, and never bury a shipped 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 (for browser preview)

```bash
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  npx --yes @marp-team/marp-cli@latest \
  docs/presentations/<deck-name>-marp.md \
  -o <output-path>.html
```

HTML export inlines images as base64 data URIs — no `--allow-local-files`
needed.

### Export a Marp deck to PPTX (for stakeholders)

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

## 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. **Export to PPTX** with `--allow-local-files`.
5. **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) | Audience |
|---|---|---|---|
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps |