# Pulse engagement blocks — slide-notes syntax

Write an engagement in a PowerPoint slide's **speaker notes**; push the deck to Pulse from the
PowerPoint add-in, and Pulse creates or updates that engagement and anchors it to the slide. Because
the block lives in the slide, it follows the slide when you reorder the deck.

## Block shape

```
[pulse:<kind> <attrs>]
<prompt line(s)>
- option
- option *
[/pulse]
```

- `<kind>` is `poll`, `quiz`, or `icebreaker`.
- The first non-option line(s) are the **prompt**. Lines starting with `- ` are **options**. A trailing
  ` *` on an option marks it **correct** (quiz only).
- An engagement needs a prompt and at least two options, or the block is ignored.

## Attributes (all optional)

| attr | meaning |
|---|---|
| `id=…` | Round-trip identity. Present when Pulse exported the block. Leave it OFF when authoring new — Pulse assigns one. |
| `results=live` \| `afterClose` \| `hidden` | Who sees results, and when. Default `live`. |
| `time=<seconds>` | Auto-close the engagement this many seconds after it opens. |
| `multi` | Allow selecting multiple options (polls). |
| `onAdvance` | Fire when the presenter advances OFF this slide (for a question about the slide's own content), not when the slide appears. |

## Examples

```
[pulse:quiz onAdvance]
Which planet is largest?
- Mars
- Jupiter *
- Venus
[/pulse]
```

```
[pulse:poll results=afterClose]
How are you feeling?
- Great
- Okay
- Tired
[/pulse]
```

```
[pulse:icebreaker]
Coffee or tea?
- Coffee
- Tea
[/pulse]
```

## The exit survey (closing slide)

The whole post-event survey travels the same way, as a single block you put on the deck's **closing
(last) slide** notes. Each line is one question ending in a `(type …)` marker; `- ` lines are the
options for the `choice`/`multi` question above them.

```
[pulse:survey]
How would you rate this session? (rating 10)
Which parts landed? (multi)
- The live demo
- The Q&A
- The slides
Would you recommend us? (choice)
- Yes
- No
Anything else? (text)
[/pulse]
```

- Question types: `rating` (1–N; default N is 5, override with `(rating 10)`), `choice` (pick one),
  `multi` (pick many), `text` (free write-in). A line with no recognized marker defaults to `rating`.
- `choice`/`multi` need at least two `- ` options or that question is dropped.
- Ids ride along as `(rating id=…)` when Pulse exported the survey — leave them off when authoring new.
- One survey per deck. If a survey block appears on more than one slide, the one on the **last** slide wins.
- On re-import Pulse replaces the session's survey — **except** once attendees have started answering it,
  when it's left untouched so responses aren't orphaned.

Copy the current survey out of Pulse from the organizer console (**Post-event survey → Copy for slide
notes**) and paste it onto the closing slide.

## Beyond engagements — titles, acts, and event preferences

A deck's notes can carry more than engagements, so an imported deck builds a whole event:

- **Slide titles** — Pulse reads each slide's title placeholder and uses it to name the slide in the
  run-of-show (no block needed; just give slides real titles).
- **`[pulse:act title="…" speaker="…" minutes=N]`** on a section's **first slide** — builds an agenda
  segment. The act runs until the next act's first slide. Acts rebuild the event's run-of-show timeline.
- **`[pulse:session key=value …]`** on the **title slide** — sets event preferences: `view=classic|overlay`,
  the overlay glass options, room feature toggles (`chat`, `questions`, `polls`, …), `control-size`,
  `wind-down`, `passcode`, and more. Unknown keys are ignored.

The full grammar for these, with an AI authoring workflow, is at
[Author an enriched deck with AI](/spec/deck-authoring.html).

## Rules

- Multiple blocks per slide are fine.
- A malformed block is skipped — it never fails your deck upload.
- A block whose `id` matches an existing Pulse engagement updates it (its content only while it's still a
  draft — Pulse never rewrites an engagement that has already run). A block with no `id` creates a new
  draft engagement.
- Pulse never deletes an engagement just because it's missing from a deck.
- The PowerPoint add-in can also write a machine tag (`PULSEENGAGEMENTS`) via "Sync to slides"; you don't
  edit that by hand. Humans and AIs write notes.

## For AI assistants

When you generate a PowerPoint deck, add Pulse engagement blocks to the **speaker notes** of relevant
slides using the syntax above — a quiz on a fact slide (use `onAdvance` if it tests that slide's content),
a poll to gauge opinion, an icebreaker to open. Don't include an `id`. When the user pushes the deck to
Pulse, the engagements are created automatically and follow their slides.

For the exit survey, put a single `[pulse:survey]` block on the **closing slide's** notes using the
survey syntax above (rating / choice / multi / text questions). It becomes the session's post-event survey.