@marver-design/marver 0.12.0 → 0.14.0

package/src/client/stage/main.tsx

@@ -21,6 +21,14 @@ const params = new URLSearchParams(location.search)
 // token systems, .dark for class-keyed ones (Tailwind/shadcn). Missing the class made
 // play render class-keyed apps light while the canvas showed them dark.
 const bootTheme = params.get('theme') ?? 'light'
+// slides mode (v1.5): the shell says so in the URL; the stage stamps the ONE
+// attribute the content primitives observe (data-sl-play lifts the rest-state
+// motion reset; data-sl-entered arms the entrance presets after each swap
+// settles). `tr=none` and prefers-reduced-motion both skip view transitions.
+const slidesMode = params.get('slides') === '1'
+const deckTransition = params.get('tr') ?? 'fade'
+if (slidesMode) document.documentElement.setAttribute('data-sl-play', '')
+const reducedMotion = typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches
 document.documentElement.dataset.theme = bootTheme
 document.documentElement.classList.toggle('dark', bootTheme === 'dark')
 const startId = params.get('at') ?? ''
@@ -95,9 +103,41 @@ function Stage() {
       // inspect.getId() never reports the new frame while the old DOM is still live -
       // a pick / anchor-resolve landing mid-swap then carries the old id and the shell
       // guards drop it instead of stamping it onto the wrong frame.
-      const apply = () => { if (seq === swapSeq.current) { flushSync(() => { setErr(null); setMounted(next) }); current.current = id } }
-      if (document.startViewTransition) document.startViewTransition(apply)
-      else { apply(); document.getElementById('root')?.animate([{ opacity: 0.35 }, { opacity: 1 }], { duration: 180, easing: 'ease-out' }) }
+      // slides: the entrance presets re-arm per swap. The disarm (drop `entered`,
+      // strip data-animate from morph-owned elements) runs INSIDE the transition's
+      // update callback - after the new DOM commits, before the NEW-state capture.
+      // Disarming before startViewTransition would capture the OUTGOING slide with
+      // its [data-animate] elements at opacity 0 (they'd vanish from the old
+      // snapshot), and a morphed element still carrying data-animate would be
+      // captured transparent and pop in after the morph.
+      const disarm = () => {
+        if (!slidesMode) return
+        document.documentElement.removeAttribute('data-sl-entered')
+        // one transform owner: an element that morphs must not also run an
+        // entrance preset - CSS cannot see a computed view-transition-name,
+        // so the stage strips data-animate from morph-owned elements here
+        for (const el of document.querySelectorAll('[data-animate]'))
+          if (getComputedStyle(el).viewTransitionName !== 'none') el.removeAttribute('data-animate')
+      }
+      const apply = () => { if (seq === swapSeq.current) { flushSync(() => { setErr(null); setMounted(next) }); current.current = id; disarm() } }
+      const entered = () => {
+        if (!slidesMode || seq !== swapSeq.current) return
+        document.documentElement.setAttribute('data-sl-entered', '')
+      }
+      const skipVt = reducedMotion || (slidesMode && deckTransition === 'none')
+      if (document.startViewTransition && !skipVt) {
+        const vt = document.startViewTransition(apply)
+        vt.finished.then(entered, entered)
+      } else if (skipVt) { apply(); entered() }
+      else {
+        // no view transitions here: a plain crossfade at the deck's tempo, so
+        // the one-tempo contract holds even where morphs cannot
+        apply(); entered()
+        const raw = getComputedStyle(document.documentElement).getPropertyValue('--marver-slide-tempo').trim()
+        const m = /^(\d*\.?\d+)\s*(ms|s)?$/i.exec(raw)
+        const tempo = m ? parseFloat(m[1]) * (m[2]?.toLowerCase() === 's' ? 1000 : 1) : 350   // a CSS <time>: 350ms or .35s; 0 is honoured
+        if (tempo > 0) document.getElementById('root')?.animate([{ opacity: 0.35 }, { opacity: 1 }], { duration: tempo, easing: 'ease-out' })
+      }
       if (announce) post({ type: 'sh:stage-at', at: id })
     } catch (e) {
       if (seq !== swapSeq.current) return
@@ -129,6 +169,12 @@ function Stage() {
     // laser/comment click owns the press instead - it must not navigate.
     const onClick = (e: MouseEvent) => {
       if (inspect.modeActive()) return
+      // slides: a background click advances (posted as the Space key) - never
+      // on anything interactive, and data-goto (below) always wins
+      if (slidesMode && e.target instanceof Element
+        && !e.target.closest('a, button, input, textarea, select, video, .mv-video, [contenteditable], [data-goto]')) {
+        post({ type: 'sh:stage-key', key: ' ', code: 'Space' })
+      }
       const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
       if (!el) return
       e.preventDefault()
@@ -149,6 +195,11 @@ function Stage() {
       // l/c toggle laser/comment, C (shift+c) hides pins; the shell acts and broadcasts back.
       if (/^Digit[0-9]$/.test(e.code) || ['d', 'h', 'r', 'l', 'c', 'C', '[', ']', 'ArrowRight', 'ArrowLeft'].includes(e.key))
         post({ type: 'sh:stage-key', key: e.key, code: e.code })
+      // slides: Space advances - but never stolen from anything interactive
+      if (slidesMode && e.key === ' ' && !(e.target instanceof Element && e.target.closest('button, input, textarea, select, video, .mv-video, a, [contenteditable]'))) {
+        e.preventDefault()
+        post({ type: 'sh:stage-key', key: ' ', code: e.code })
+      }
     }
     window.addEventListener('keydown', onKey)
 

package/src/shared/events.ts

@@ -10,6 +10,13 @@ export type EventType = 'create' | 'reply' | 'edit' | 'resolve' | 'reopen' | 're
 // Live Jam: provenance stamped by the daemon on agent-authored events (who orchestrated the change).
 export interface AgentMeta { devUser?: string; harness?: string; model?: string; effort?: string }
 
+/** A person named in a comment (sharing v1.1). Splits exactly like `author`:
+ *  canonical logs carry `email`, browser transports carry `id` (the same
+ *  opaque per-canvas HMAC) - exactly one of the two is present. `label` is the
+ *  display name the composer inserted (bodies stay plain text; rendering
+ *  highlights `@label` runs by matching it). */
+export interface Mention { email?: string; id?: string; label: string }
+
 export interface CommentEvent {
   id: string                      // client-generated UUID - the idempotency key
   ts: number                      // ms epoch at creation
@@ -25,6 +32,7 @@ export interface CommentEvent {
    *  travels to another viewer's browser. Exactly one of the two is present. */
   author?: { email?: string; id?: string; name?: string; avatar?: string }
   body?: string                   // plain text in v1
+  mentions?: Mention[]            // create/reply only - people named in the body (v1.1)
   emoji?: string                  // react events
   addressedIn?: string            // resolve events: the variant frame that answered
   // --- Live Jam additions ---
@@ -44,7 +52,8 @@ export interface Thread {
   addressedIn?: string
   agent?: boolean                 // root authored by the agent
   agentMeta?: AgentMeta
-  replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number; agent?: boolean; agentMeta?: AgentMeta }[]
+  mentions?: Mention[]
+  replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number; agent?: boolean; agentMeta?: AgentMeta; mentions?: Mention[] }[]
   reactions: Record<string, string[]>   // emoji -> author emails (toggle semantics)
 }
 
@@ -67,7 +76,7 @@ export function replay(events: CommentEvent[]): Thread[] {
     threads.set(ev.commentId, {
       id: ev.commentId, board: ev.board, nodeKey: ev.nodeKey, frame: ev.frame,
       anchor: ev.anchor, author: ev.author, body: ev.body, ts: ev.ts,
-      resolved: false, agent: ev.agent, agentMeta: ev.agentMeta, replies: [], reactions: {},
+      resolved: false, agent: ev.agent, agentMeta: ev.agentMeta, mentions: ev.mentions, replies: [], reactions: {},
     })
   }
   for (const ev of ordered) {
@@ -75,7 +84,7 @@ export function replay(events: CommentEvent[]): Thread[] {
       case 'reply': {
         const t = ev.parentId ? threads.get(ev.parentId) : undefined
         if (!t || !ev.commentId || t.replies.some((r) => r.id === ev.commentId)) break
-        t.replies.push({ id: ev.commentId, author: ev.author, body: ev.body, ts: ev.ts, agent: ev.agent, agentMeta: ev.agentMeta })
+        t.replies.push({ id: ev.commentId, author: ev.author, body: ev.body, ts: ev.ts, agent: ev.agent, agentMeta: ev.agentMeta, mentions: ev.mentions })
         break
       }
       case 'edit': {

package/src/shared/utm.ts

@@ -4,12 +4,13 @@
  *    utm_source   = the surface class ('published-canvas' | 'dev-canvas')
  *    utm_medium   = the link unit ('powered-by')
  *    utm_campaign = THIS canvas's name, slugged ("Marver tour" -> "marver-tour")
- *    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page)
+ *    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page |
+ *                   'play-brand' the present/slides brand pill)
  */
 export function poweredByUrl(
   canvasName: string | undefined,
   source: 'published-canvas' | 'dev-canvas',
-  content: 'gate' | 'shell' | 'sign-in',
+  content: 'gate' | 'shell' | 'sign-in' | 'play-brand',
 ): string {
   const slug = (canvasName ?? '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
   const q = new URLSearchParams({

package/templates/AGENTS-embedded.md

@@ -22,6 +22,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board, choosing what ships | instructions/boards.md |
+| Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
 | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 | Live Jam | responding to an `@marver` comment (a spawned job); on by default - confirm it names YOUR tool | instructions/jam.md |
 

package/templates/AGENTS-studio.md

@@ -22,6 +22,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board, choosing what ships | instructions/boards.md |
+| Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
 | Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
 | Live Jam | responding to an `@marver` comment (a spawned job); on by default - confirm it names YOUR tool | instructions/jam.md |
 

package/templates/instructions/publish.md

@@ -51,6 +51,13 @@ vars if the host has no CLI.
    container disk is the one real deploy mistake - comments would vanish on
    redeploy; marver fails loudly if the dir cannot be created.
 
+Then one line before you build: **name the canvas** -
+`share: { name: "Your App" }` in `design/config.ts`. The name is the gate's
+title, the brand pill's tooltip, and the `utm_campaign` on every powered-by
+link the canvas emits (the wordmark, the gate, the play brand pill). With no
+name it falls back to the ROOT DIRECTORY, which in a container is `app` -
+every containerised canvas you never named reports as the same campaign.
+
 ## The serve contract (env vars, complete list)
 
 | Var | Meaning |

package/templates/instructions/reference/deck-layouts.md

@@ -0,0 +1,230 @@
+# Deck layouts - the atlas, the grid, the budgets
+
+Required reading at step 4 of every deck. The doctrine's recipe list is the core;
+this is the full atlas grouped by the JOB a slide does, the shared stage and the
+optional banded grid recipes draw from, and the content budgets that keep type at design size. The atlas
+is a vocabulary, not a fence: when nothing fits the concept you wrote for the
+slide, compose it from divs.
+
+Words used below: **kicker** = the small-caps `sl-caption` label above a title;
+**hero** = a card's one-line headline in `sl-support`; **ghost numeral** = a large,
+low-contrast number behind or beside a card that carries order; **display** =
+`sl-display`, the one oversize role; **stat** = `sl-stat`, the row-of-figures size.
+
+## The stage and the banded grid (content box 1104×632px)
+
+Stage margins are asymmetric: 88px at the sides, 44px top and bottom, in px
+at every viewport. Every silhouette shares those margins and nothing else.
+The BANDED grid below is the shell for grid and split recipes that carry a
+title band; statements, heroes, fields, and bookends build their own
+geometry inside the same margins. (The doctrine's 85% rule and spacing scale
+govern every silhouette.)
+
+- **Title band** - the top ~113px: kicker (18px, one line) over the assertion
+  (56px, one line), a hairline under. Within a visual group it sits in the
+  same place on each slide, so a travelling title lands where it left.
+- **Body band** - full width, ~438px, starting 48px below the title block.
+  Content fills at most ~372px of it. This band is the slide.
+- **Foot** - the source line (25px), 48px under the body. A takeaway bar sits
+  between them: 56px tall, 40px clear above it.
+- **Split** - text left at 43% of the width, visual right at 48%, a 9% gutter.
+  Argument reads first, proof confirms it. A `sl-assertion` in a 43% column
+  holds ~20 characters a line - write to it.
+- **Columns** - three equal at a 32px gap (~347px each); five narrow (~192px)
+  for spectrums; a 2×2 when the four cells are peers. Card padding 32px.
+- **Dominance before containers.** Decide what is biggest on the slide before
+  choosing what holds the rest. Whitespace that makes the dominant object read
+  as dominant needs no defence; a companion panel added to "fill the other
+  half" does - if it is not evidence, leave the half empty.
+
+The banded skeleton, in the project's own Tailwind - for the grid and split
+slides that carry a title band, and only those:
+
+```tsx
+<Slide>
+  {/* one child at flex:1 claims the box, so the bands land in the same
+      place across a visual group; gap 48 is the title-to-body / body-to-foot step */}
+  <div className="flex-1 min-h-0 flex flex-col gap-12">
+    <header className="shrink-0">
+      <p className="sl-caption uppercase tracking-[.14em]">Retention</p>
+      <h1 className="sl-assertion mt-2">Churn halved after onboarding v2</h1>
+      <hr className="mt-5 border-0 h-px bg-black/10" />
+    </header>
+    <div className="flex-1 min-h-0 grid grid-cols-[43fr_9fr_48fr] items-center gap-8">
+      <div className="sl-body space-y-6">…argument…</div>
+      <div />
+      <Chart option={…} />
+    </div>
+    <footer className="sl-caption shrink-0">Source: product analytics, Aug 2026</footer>
+  </div>
+</Slide>
+```
+
+## The atlas (when · skeleton · budget · anchor)
+
+A recipe without a named anchor does not morph - hard cut. Anchors are named
+only inside a declared visual group or build; never a deck-wide fallback.
+Budgets are heuristics: the rendered 1280×720 frame and the Slide's overflow
+outline are the authority - when they disagree with a number here, the frame
+wins. And a slide that merely FITS is not done: the 85% rule is the bar.
+
+**Parallel points**
+- **cards** - 2-6 equal cards (kicker · hero · body), ghost numerals for order,
+  at most ONE accented card for the emphasised option. Budget: 2-3 cards carry a
+  body (≤120 chars, 3 lines); 4-6 cards are kicker + hero only. Anchor: the row.
+- **spectrum** - 3-7 narrow cards for a progression or maturity model, low to
+  high left to right. Budget: kicker ≤8 chars, hero ≤15, body ≤40 (≤5 cards) or
+  none (6-7).
+- **columns** - N headers + descriptions + an optional metric strip beneath:
+  product lines, tracks, team areas. Budget: ≤4 columns with bodies, ≤6 without.
+- **stacked list** - 4-6 items in the right field, argument on the left; the
+  numbered variant carries ghost numerals for ordered reasons. Budget: item ≤2
+  lines at 24px. Anchor: the list.
+- **split** - argument left (1-3 short paragraphs, optional `sl-support`
+  sub-head), ONE visual right (metric, card, image, chart). The workhorse of
+  analytical slides. Anchor: the visual.
+- **insight + evidence** - one large insight left (≤30 words, `sl-support`),
+  3-4 evidence items right (one-line title + one line). Anchor: the insight.
+
+**Proof**
+- **metric** - one hero number (`sl-display`) with label + sub-line, enclosed
+  only when the boundary means something;
+  pair with a split or a stat row. Budget: value ≤8 chars, label ≤20, sub ≤30.
+- **stat row** - 3-4 figures across in `sl-stat` with a label under each.
+  Budget: value ≤7 chars at 3 across, ≤5 at 4; label ≤4 words. Anchor: the row.
+- **trajectory** - stacked from → to pairs with a label ("$100k → $480k MRR").
+  Budget: 3-4 pairs. Anchor: the arrows.
+- **table** - header row with a rule under it, zebra rows, numbers right-aligned,
+  units in the header. Budget at 24px: ≤5 columns × ≤6 rows, header ≤15 chars,
+  cell ≤14; more than that is two slides or a chart.
+- **mini grid** - N×M small value + label cells with hairline dividers, for a
+  dashboard glance. Budget: ≤12 cells (4×3).
+- **takeaway bar** (modifier) - a full-width dark bar at the foot with the
+  so-what, centred, no trailing full stop, ≤12 words. Never a paraphrase of the
+  assertion - a different angle or nothing.
+
+**Contrast**
+- **before / after** - the doctrine's two-up, the "after" side accented.
+- **scenarios** - bear / base / bull columns over a metric list, the recommended
+  column highlighted. Budget: 3 scenarios × ≤5 metrics.
+
+**Process** (the subject, never the provenance)
+- **flow** - step cards with forward arrows; ≤5 steps keep bodies, 6+ drop to
+  labels only. Budget: label ≤15 chars, body ≤40.
+- **cycle** - 3-6 auto-numbered nodes around a centre; four nodes sit square at
+  the corners, others on a circle. Budget: label ≤15, body ≤40. Anchor: the ring.
+- **chain** - primary chevrons for the value chain with support bars beneath (the
+  enabling activities). Budget: ≤6 chevrons, ≤3 bars.
+- **swim lanes** - lanes (rows) × stages (columns) with mini-cards at the
+  intersections: hand-offs, RACI, cross-functional flow. Budget: ≤4 lanes × ≤5
+  columns, card ≤8 words.
+- **funnel** - 3-8 narrowing tiers, the drop-off stated. Budget: label + one
+  line ≤5 tiers; labels only at 6-8.
+
+**Time**
+- **schedule** - sections × time columns, task bars, milestone diamonds. Budget:
+  ≤7 rows, ≤8 columns. Anchor: the time header.
+- **timeline**, **roadmap phases** - the doctrine's; alternate event labels
+  above and below the spine when they crowd.
+
+**Structure and position**
+- **layers** - full-width stacked layers with tag pills; the foundation layer
+  dark. Budget: ≤5 layers, ≤4 tags each.
+- **org** - boxes + connectors, two levels max; deeper goes to an appendix.
+- **venn** - 2-3 circles with 2-3 items each and a named overlap.
+- **concentric** - TAM / SAM / SOM rings, labels inside the rings, legend right.
+- **pyramid** - 3-6 trapezoid tiers, widest at the top, each tier a label + 1-3
+  items. For priority, never for volume (that is the funnel).
+- **number line** - ticks with labels, one highlighted range: pricing tiers, a
+  valuation range, benchmarks. Budget: ≤6 ticks.
+- **capability matrix** - competitors × capabilities with empty / half / full
+  circles (CSS), us in the first column. Budget: ≤6 × ≤7.
+
+**Status**
+- **scorecard** - rows with a red / amber / green dot + a one-line note. ≤7 rows.
+- **heat map** - rows × columns of RAG cells, a legend, no numbers inside cells.
+  Budget: ≤6 × ≤6.
+- **tracker** - initiative · owner · phase · next milestone; or decision · owner ·
+  date · status. Budget: ≤6 rows, owners as initials badges.
+
+**People and voice**
+- **testimonials** - 1-6 quote cards with an initials avatar, name, company -
+  attributed voices (the doctrine's quote-wall is unattributed fragments, ≤15
+  words). Budget: ≤25 words a quote at ≤4 cards, ≤15 at 5-6. Anchor: the avatars.
+- **team** - 1-8 people: initials, name (≤15 chars), role (≤22). Budget: ≤4
+  people carry a bio (≤30 words); 5-8 are name + role.
+- **manifesto** - a single large claim in `sl-support` or `sl-display`, one
+  accent-coloured phrase, an attribution line. Budget: ≤20 words. Anchor: the
+  accent phrase.
+
+**Images**
+- **framed source** - a screenshot, a chart from a PDF, a product shot: the real
+  image on the right, framing text on the left saying what it shows. The bitmap
+  is at least 2× the CSS box it renders in. Never redraw a source chart as a
+  fake: rebuild it as a `Chart` when the underlying data is available, embed the
+  render when it is not.
+
+## Budgets that keep type at design size
+
+| Element | Cap |
+|---|---|
+| card kicker · hero · body | 20 · 30 · 120 chars (bodies only at ≤3 cards) |
+| narrow (spectrum) card | 8 · 15 · 40 chars |
+| metric value · label · sub | 8 · 20 · 30 chars |
+| table header · cell | 15 · 14 chars, ≤5 × ≤6 |
+| flow / cycle label · body | 15 · 40 chars |
+| timeline date · title · body | 8 · 20 · 20 chars |
+| quote | 30 words; testimonial 25 (≤4) / 15 (5-6); quote-wall 15 |
+| bio | 30 words at ≤4 people; name 15 chars, role 22 |
+| takeaway bar | 12 words, one line |
+| body paragraphs | 3-5 short paragraphs, ~600 chars total |
+
+A breach is a different recipe or a split. Type never shrinks to fit - the review
+gate reads shrunk type as the tell it is.
+
+## Rebuilding an existing deck
+
+When the human hands you a finished deck to rebuild on the canvas, ask which
+mode - and default to faithful:
+
+- **Faithful** - their order, their words, exactly. You may normalise
+  punctuation (em dashes → commas or periods) and number formats; you may not
+  change a word. Label titles stay labels. Suggested rewrites go in a comment on
+  the frame, never on the slide.
+- **Editorial** (opt-in) - order kept, copy passed through the doctrine's words
+  rules: jargon, hedges, filler out; numbers, names, dates verbatim; titles
+  turned into assertions where the source supports the claim.
+
+Then map shapes - a companion visual ONLY where the source supplies it; a
+paragraph with no metric, image, or chart behind it is a text-led composition,
+and that whitespace is honest:
+
+| Source shape | Layout |
+|---|---|
+| a paragraph | split when the source has a companion (metric, image, chart); else text-led |
+| 3 bullets | cards |
+| 4-6 bullets | stacked list (numbered if ordered) |
+| up to 4 numbers | metric grid or stat row |
+| a quote | quote |
+| a table | table (or two slides past the budget) |
+| a chart with its data | `Chart` from the data |
+| an image, chart, schedule, diagram you cannot rebuild losslessly | framed source |
+
+## Charts and diagrams - the extra mile
+
+- **Decision flows**: boil choices to yes / no, quantify the branches (%, volumes)
+  so the eye follows the path that matters, hang customer quotes on the node
+  they support.
+- **Waterfalls** beat tables for build-ups and breakdowns: left to right in the
+  logical order, the one or two bars that matter highlighted, a few callouts that
+  pre-empt the room's questions.
+- **When a slide must be complex**: large visual cues (boxes, highlights) on the
+  point, grouping and colour that steer interpretation, and the voiceover ON the
+  page - the slide must make sense with no presenter.
+- **Aggregate.** The chart is not the model. Single series is fine. Overlay
+  detail (lines, shading) on the base chart instead of adding a second chart.
+- **Formatting**: label bars directly and drop the value axis when the chart is
+  simple (keep the axis for dense or grouped series); growth rates visible; one
+  label size across the deck; series in logical order (base first, growth
+  next); same hue = same thing on every slide; charts aligned to the grid and to
+  each other across slides.

package/templates/instructions/reference/deck-story.md

@@ -0,0 +1,110 @@
+# Deck story - the argument before the slides
+
+The slides doctrine (instructions/slides.md) gives the pipeline. This file is the
+depth behind steps 1-3: how to find the answer, shape the argument, calibrate it to
+the room, and write words that carry it. Pull it when the material is thin or
+rich, the audience is senior, or the first slide list reads like a table of
+contents.
+
+## Intake - seven questions, one message
+
+Ask them all at once; skip any the human already answered (pasted bullets, a linked
+doc). The first three are required - ask again if skipped, they shape everything.
+
+0. **The one thing.** If they remember nothing else, what? ("Approve the Q3 budget",
+   "Retention is the lever, not acquisition".)
+1. **The goal.** What happens after the last slide? (a decision, alignment, a meeting)
+2. **The audience.** Executives / cross-functional team / own team / external
+   (client, partner, board). Named people help.
+3. **Raw material.** Bullets, a doc, "start from scratch" - messy is fine.
+4. **Numbers.** Metrics and proof points. Numbers make slides land.
+5. **The energy.** Urgent / confident / informational / exploratory.
+6. **Constraints.** Time, slide cap, topics to avoid, must-have slides, who presents.
+
+## Find the answer first - five questions, in order
+
+| Ask | Yields |
+|---|---|
+| What is top of mind for the audience - goal, worry, definition of success? | the objective |
+| Twenty seconds in a lift: what do you tell them? | THE ANSWER |
+| Which logical steps take them from where they are to the answer? | the storyline |
+| Where will they disagree? What moves them to act? | the slides |
+| What do you not know? What is the burden of proof? | the evidence |
+
+Top-down, always. Never start from the slides or the analysis. The answer's shape:
+context ("this matters, in these ways") · options ("two paths, here they are") ·
+recommendation ("the first, for these reasons") · next steps ("what it takes, by
+when"). "We don't know yet, but here is how we find out" IS an answer; a hedge is not.
+
+**The pyramid.** Slides 1-2 carry the conclusion. Each argument is a slide group.
+Evidence sits under its argument, never free-floating. A deck where the answer
+arrives on slide 14 has been built bottom-up - rebuild it.
+
+**Insights first, outputs second, provenance never.** How the model works,
+what alternatives were considered, how long it took, what went wrong - none
+of it belongs in the room. Time spent making a slide earns it nothing. (A
+process that IS the subject - the operating model you propose, the rollout
+plan - is content, and the atlas has layouts for it.)
+
+## Calibrate to the room
+
+- **Executives** - so-what framing, 12-15 slides, one ask.
+- **The team** - actionable detail: owners, dates, dependencies.
+- **External (client, partner, investor)** - polished narrative, social proof,
+  evidence-heavy, the firm's specific language in the titles.
+- **Board** - trajectory, risks, asks. Concise.
+- **Summary vs full material.** A summary is the conversation about the
+  answer: sized to HALF the meeting (a 45-minute slot carries 12-20 slides;
+  the rest is discussion). The full deck is the reference ("see slide 53"),
+  organised behind the thesis and its drivers, as long as it needs to be.
+  Know which you are building; never blend them.
+- **Wayfinding.** An agenda only when there are three or more sections, each
+  item a section name + the slide it starts on. Section dividers only past ~25
+  slides - below that, section changes live in the assertions themselves.
+
+## The evidence check - before designing anything
+
+Walk every planned slide with one question: could I draft this without inventing a
+single fact? Mark it has-enough or not. For the gaps, write SPECIFIC questions (not
+"more on the team" but "which four people, prior firms, role on this project?"),
+at most two or three per slide, only where the answer changes the slide. Then one
+deck-level call:
+- **ask** - the default when any slide lacks material; put the consolidated list
+  to the human before building;
+- **shrink to the evidence** - when most slides lack material and the human
+  plainly has no more (early stage, the narrative is the product) - propose the
+  smaller deck;
+- **proceed with placeholders** - only when the gaps are editorial (framing,
+  taglines), never data (numbers, names, dates).
+
+Every claim traces to source, and the gap has a stage. In the scaffold (the
+one-sentence slides on the canvas) a missing fact is a visible `[PLACEHOLDER:
+what belongs here]`. In the build, a factual placeholder BLOCKS its slide -
+answered, or the slide is cut - never filled with plausible prose. Editorial
+gaps (a tagline, a caption, a transition line) you DO draft, labelled as
+proposed in the frame's comment - that is writing, not invention.
+
+## Writing that carries
+
+- **Distil the voice first.** Scan the material for concepts that recur on three
+  or more slides; give each a 2-4 word mnemonic, imperative verb preferred
+  ("Decide fast", "See everything"), and use it identically everywhere it applies.
+- **Mine the material for specifics** and keep them verbatim: "19 of 25 operators"
+  beats "most operators"; "$100k to $480k MRR" (from X to Y) beats "grew strongly".
+- **Assertions fit their box.** ~40 characters full-width, ~20 inside a split,
+  two lines the ceiling - compress the phrasing, keep the claim, never shrink
+  the type, and check the render.
+- **Paragraphs over bullets for narrative.** 15-30 words, one to three per block.
+  Bullets are for parallel lists and action items; a bullet with "and" is two.
+- **Tone follows the energy.** Urgent: "Double down now or miss the target."
+  Confident: "Retention hit 85%, the best quarter yet." Informational: "Retention
+  stands at 85%, up 12 points." Exploratory: "Three approaches, different trade-offs."
+- **Voice follows the deck type.** Strategy commits to positions. A pitch is warm
+  and aspirational. A case study attributes results to named actions. A status
+  update is crisp - state, delta, next.
+- **Kill list, extended.** Beyond the doctrine's: "utilize", "unlock", "harness",
+  "empower", "seamless", "delve", "unleash", "synergize", "operationalize",
+  "cutting-edge", "best-in-class", "at the end of the day", "in terms of".
+- **The ask closes.** Decision, owner, date: "Approve $200k for Q3 retention by
+  Friday." The closing slide is that ask - if the house style ends on a bare
+  end card (mark on an image), the ask is the slide before it.