RonanCodes/build-session-deck

Build-session deck

A self-contained HTML deck for presenting what you built. One file, opens in any browser, looks great, and has a real presenter view: speaker notes, a timer, and a next-slide preview on your laptop while the clean slide shows on the projector — synced live with no server.

A deck is not enough: also generate a Prep / learning center

A presenter (or a stand-in presentee) needs to get up to speed fast on the material before they present or field questions. So alongside the deck, generate a companion Prep page (a learning center) that teaches the concepts behind the demo. Structure it by the domains that matter for THIS pitch, typically:

• Tech — the stack, the load-bearing architecture decisions, the clever bits a reviewer would probe.
• Domain / business-of-the-industry — the day-to-day of the users (for real estate: the makelaar's workflow, local specifics like bieden/NVM), so the presenter sounds fluent.
• The business case — the problem, the market gap, the competitors, the vision/why-now.

Make it skimmable and optionally interactive (expandable Q&A, "could they ask…" prompts, a quick self-quiz). Source it from real material (the repo, design docs, research notes), not invented. It pairs with the deck: the deck is what you show, the Prep is what you know. Surface it from the presentation hub (below) as a "Prep" / "Study up" option.

The presentation hub (when there may be several decks)

Serve presentations from a hub route (e.g. /present): list the available presentations, pick one, then from that presentation's page offer Present / Speaker / Clicker views (QR beside the clicker for the phone remote) plus the Prep learning center. One entry point, many decks, each with its show-views and its study-view.

The full /present system (what to build)

The canonical experience, build all of it:

• /present hub — lists the available presentations (cards). There may be several over time, so this is a picker, not a single deck. Each card → that presentation's page.
• Per-presentation page — buttons for the three show-views + the study-view:
  • Present (?...) — clean fullscreen audience slides.
  • Speaker (?mode=speaker) — slide + notes + timer + next.
  • Clicker (?mode=clicker) — phone remote (split-tap), shown with a QR code beside it so you scan and go.
  • Prep — the learning center (see above).
• Phone remote (?mode=remote) — a chooser on the phone: Clicker or Speaker.
  • Clicker: full-height split, big Prev/Next thumb zones, status line (N/total · title), and a Notes toggle. Tapping "Notes" reveals the current slide's speaker notes plus a "Next:" one-line summary of the upcoming slide, inline above the thumb zones on the same screen — never a navigation to a separate page. Tap again to hide. The Prev/Next zones stay live underneath so you keep clicking with notes open.
  • Speaker on phone: bottom ~quarter = the clicker, top three-quarters = scrollable speaker notes, a font-size +/- control (persisted), and a "Next:" one-line summary of the next slide's main idea so you're ready.
• QR code — encodes the deck URL (remote mode) so the phone joins instantly. Generate it client-side with an inlined, dependency-free QR generator drawing to a canvas (a strict CSP blocks CDN scripts, so paste a compact QR-in-JS implementation inline). Never an external image API.
• Font zoom — ArrowUp / ArrowDown scale all slide text (root font-scale, clamped, persisted in localStorage). Left/Right stay navigation.
• PWA — manifest + apple-mobile-web-app-capable so the remote adds to the home screen as a standalone app, with an icon.

Reference implementation: the Makely repo (housapp-bieden) under apps/web/public/present/ (hub + makely.html deck) — copy its structure.

Multi-theme presentations (interlinked decks)

A single project demo is often better as several themed decks than one long one. Support splitting a presentation into N named themes, each a self-contained deck (own slides + speaker notes) under the same /present hub, wired so you move between them from the clicker alone.

• Ask which themes to include when generating. Offer "all" or a subset; each chosen theme becomes its own deck file (e.g. present/makely-business.html, -build.html, -way-of-working.html).
• Interlink them. Every theme's deck ends on a "Next theme" chooser slide listing the other themes as big tap targets. Picking one loads that deck (carrying the ?mode= and room params so the clicker stays connected) and that deck ends with its own chooser offering the remaining one(s). So from the remote you traverse the whole set and back, no mouse, no hub round-trip. Define the set as an ordered THEMES array each deck knows, so "next" is deterministic and every deck can render the chooser.
• The clicker drives it. The "Next ›" zone on the final slide advances into the chooser; tapping a theme there navigates the whole presentation to that deck. Keep the relay room stable across decks so the laptop + phone stay in lockstep through the jump.

The reusable three-part project-demo template

A strong default theme set for pitching any project you built (offer it by name when the user is presenting a project/product):

1. Business case — the why: problem, pain points, personas, the moat, what incumbents do and where they fall short, where the opportunity sits, the roadmap forward.
2. What I built (and the concerns) — the how: the pages, the screens, the features, the tech-stack architecture, then scaling + security.
3. The way of working — the meta layer: the harness and process (e.g. Claude Code, goal-driven dynamic workflows, sub-agents, custom skills as hooked-together reusable processes, the human-in-the-loop-only-when-stuck loop, the outer-surface board the team drives it from).

Fill each from real project material (repo, design docs, the About page, research notes), never invented.

The presenter/presentee model (read first)

The deck runs in two modes from the same file, same machine:

• Audience view (deck.html) — clean fullscreen slides. Drag this window to the projector (extended display).
• Speaker view (deck.html?mode=speaker, or press S) — current slide + speaker notes + next-slide preview + elapsed timer + clock. Keep on your laptop.

They sync through BroadcastChannel (same-origin, same browser, same machine): moving slides in either window moves both. No backend, no Durable Object.

Cross-device tier: a phone clicker (PWA)

For a phone as a thumb clicker (or any second device), BroadcastChannel can't reach across devices — you need a network relay. Don't build a Durable Object from scratch: if the app already has Supabase, use Supabase Realtime broadcast as the relay (zero new infra, the anon key is public-safe). Otherwise a tiny WebSocket/Durable Object is the fallback.

• Host the deck (a static file on Vercel/CF, ideally an unguessable path since speaker notes live in the source) so the phone can load it.
• Add a ?mode=clicker screen: a full-height split with a left "‹ Prev" zone and a right "Next ›" zone, huge thumb targets, touch-action:manipulation + user-select:none so taps don't zoom/select, 100dvh + env(safe-area-inset-*) for notch safety, and a status line showing N / total · current title so the presenter never looks up. Add a manifest + apple-mobile-web-app-capable so it adds to the home screen.
• Run both relays at once: BroadcastChannel links the two laptop windows; Realtime links the phone. A go() that navigates locally broadcasts to both; an apply() that receives a peer event updates without re-broadcasting (prevents loops; set Realtime broadcast:{self:false}). A room param namespaces channels so two presenters don't collide.

import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
const sb = createClient(URL, ANON);
const room = sb.channel('deck:'+ROOM, { config:{ broadcast:{ self:false } } });
room.on('broadcast', { event:'nav' }, ({payload}) => apply(payload.i)); // receive: no re-broadcast
room.subscribe();
const net = (i) => room.send({ type:'broadcast', event:'nav', payload:{ i } });
function go(n){ apply(n); bc.postMessage({i}); net(i); }   // local nav → both relays

A Durable Object / dedicated WebSocket is only worth it when there's no Supabase and you need many concurrent rooms — note it as the upgrade path, don't default to it.

Build procedure

1. Gather real material (don't invent): read the repo CLAUDE.md/README, git log for what shipped, any design docs (vault wiki/concepts/*), the live URLs, the data model, and the tech choices. For a demo deck, accuracy > polish — every claim should trace to something real.
2. Outline the story using the section template below. A build-session demo is a narrative, not a feature dump: problem → what I built (the demo) → how it works → how it holds up (scale/security) → who it's for → what's next.
3. Write the slides into the HTML template. Keep each slide to one idea, big type, lots of breathing room. Put the detail in speaker notes, not on the slide.
4. Write speaker notes for every slide — what to actually say, the numbers to quote, the thing to click in the live demo, the question to anticipate. This is what makes the presenter view earn its place.
5. Output to <repo>/.deck/<slug>.html (gitignored) or a path the user names, and open it.

Section template (build-session / weekly demo)

1. Cover — project name, "Build session demo", date, presenter. One striking line.
2. The one-liner — what this is, in a sentence a stranger gets.
3. The problem — who hurts, why now. Make them feel it.
4. What I built — the live demo. The meat. Link the real URLs; list the key flows to click. (They don't review code manually, so show the product working.)
5. How it works — architecture diagram (mermaid or a simple boxes-and-arrows SVG) + the tech stack and why each choice.
6. Under the hood — 2-3 "real engineering" highlights that prove substance without a code review (e.g. row-level security model, agent draft-then-approve trust gradient, eval harness, identity resolution). This is where you earn credibility.
7. How it scales — the path from demo to load: data model, statelessness, caching, the known bottleneck and the plan.
8. Security & privacy — auth model, RLS, data residency, GDPR/AVG for any personal/financial data. Name the hard constraints.
9. User personas — who uses it and the role lenses (e.g. admin / adviser / client), each with their job-to-be-done.
10. What's next — the roadmap, honestly sequenced.
11. Close — one-slide recap + the ask (the decision you want from the room).

Scale up or down to the audience. An interview build-session wants 8-12 slides; a weekly team demo wants 5-7.

Style

• No emojis. Anywhere. Ever. Not in slide bodies, stack pills, section eyebrows, buttons, the hub, the speaker/clicker UI, or status text. This is a hard rule for every deck this skill generates. Use proper icons instead: inline lucide SVGs (the deck is self-contained, so paste the SVG markup directly with stroke="currentColor"), official vendor / simple-icons SVGs for tech logos, or clean text labels. An emoji on a pitch deck reads as unfinished; a real icon reads as built. If a glyph is decorative and adds no meaning (e.g. a coloured dot before a tech name), drop it entirely rather than reaching for an emoji.
• Clean, modern, confident. Big headings, generous whitespace, one accent palette (pull the product's own colours).
• Exciting but not gimmicky: a tasteful entrance animation per slide, a progress bar, slide numbers. No clip-art, no walls of bullets.
• Every slide readable from the back of the room: minimum ~28px body, ~64px+ headings.
• Mobile-safe is irrelevant (it's a projector), but make it responsive enough to rehearse on a laptop.

The HTML engine (copy, then fill SLIDES + notes)

Self-contained. Slides + speaker notes live in one SLIDES array. Keyboard: ←/→/Space navigate, S opens speaker view, F fullscreen. BroadcastChannel keeps both windows in lockstep.

<!doctype html><html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1"><title>DECK TITLE</title>
<style>
  :root{--bg:#0f1115;--fg:#f5f5f4;--muted:#a1a1aa;--accent:#7c3aed;}
  *{box-sizing:border-box;margin:0} html,body{height:100%}
  body{background:var(--bg);color:var(--fg);font:18px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto}
  #stage{height:100vh;display:flex;align-items:center;justify-content:center;padding:6vmin;text-align:center}
  .slide{display:none;max-width:1100px;animation:in .4s ease} .slide.active{display:block}
  @keyframes in{from{opacity:0;transform:translateY(12px)}to{opacity:1;transform:none}}
  h1{font-size:clamp(40px,7vmin,84px);line-height:1.05;letter-spacing:-.02em;font-weight:800}
  h2{font-size:clamp(30px,5vmin,56px);line-height:1.1;letter-spacing:-.01em;font-weight:700;margin-bottom:.4em}
  p,li{font-size:clamp(18px,2.6vmin,28px);color:var(--muted)} ul{margin:.6em auto;max-width:800px;text-align:left}
  li{margin:.4em 0} .eyebrow{text-transform:uppercase;letter-spacing:.18em;font-size:14px;color:var(--accent);font-weight:700;margin-bottom:1em}
  .accent{color:var(--fg)} a{color:var(--accent)}
  #bar{position:fixed;bottom:0;left:0;height:4px;background:var(--accent);transition:width .3s} #num{position:fixed;bottom:14px;right:18px;color:var(--muted);font-size:14px}
  /* speaker view */
  body.speaker #stage{display:none} #spk{display:none}
  body.speaker #spk{display:grid;grid-template-columns:1.4fr 1fr;grid-template-rows:1fr auto;gap:18px;height:100vh;padding:24px}
  #spk .now{background:#000;border-radius:14px;display:flex;align-items:center;justify-content:center;padding:30px;overflow:hidden}
  #spk .now .slide{display:block;transform:scale(.85)} #spk .notes{overflow:auto;background:#17181d;border-radius:14px;padding:24px;font-size:22px;line-height:1.5;color:#e7e7ea}
  #spk .notes h3{color:var(--accent);font-size:14px;text-transform:uppercase;letter-spacing:.14em;margin-bottom:.6em}
  #spk .next{grid-column:1;background:#17181d;border-radius:14px;padding:16px;color:var(--muted);font-size:16px}
  #spk .meta{grid-column:2;display:flex;gap:18px;align-items:center;justify-content:flex-end;font-variant-numeric:tabular-nums;font-size:30px}
  #spk .meta small{display:block;color:var(--muted);font-size:13px;text-transform:uppercase;letter-spacing:.12em}
</style></head><body>
<div id="stage"></div>
<div id="spk"><div class="now" id="spkNow"></div><div class="notes"><h3>Speaker notes</h3><div id="spkNotes"></div></div>
<div class="next" id="spkNext"></div><div class="meta"><div><small>Elapsed</small><span id="elapsed">00:00</span></div><div><small>Time</small><span id="clock">--:--</span></div></div></div>
<div id="bar"></div><div id="num"></div>
<script>
// FILL THIS: one entry per slide. html = the slide markup, notes = what to say.
const SLIDES = [
  { html:`<p class="eyebrow">Build session demo</p><h1>Project <span class="accent">Name</span></h1><p>One striking line.</p>`,
    notes:`Open strong. Say the one-liner. Set the frame: 'here's what I built and why.'` },
  { html:`<h2>The problem</h2><ul><li>Who hurts.</li><li>Why now.</li></ul>`, notes:`Make them feel the pain before the solution.` },
  // ...more slides...
];
const ch = new BroadcastChannel('deck');
let i = 0; const isSpeaker = new URLSearchParams(location.search).get('mode')==='speaker';
if(isSpeaker) document.body.classList.add('speaker');
function renderStage(idx){ const s=SLIDES[idx]; document.getElementById('stage').innerHTML=`<div class="slide active">${s.html}</div>`; }
function renderSpeaker(idx){ const s=SLIDES[idx], n=SLIDES[idx+1];
  document.getElementById('spkNow').innerHTML=`<div class="slide">${s.html}</div>`;
  document.getElementById('spkNotes').innerHTML=(s.notes||'').replace(/\n/g,'<br>');
  document.getElementById('spkNext').innerHTML = n?`<b>Next:</b> ${n.html.replace(/<[^>]+>/g,' ').slice(0,90)}…`:'<b>Last slide.</b>'; }
function paint(){ if(isSpeaker) renderSpeaker(i); else renderStage(i);
  document.getElementById('bar').style.width=((i+1)/SLIDES.length*100)+'%';
  document.getElementById('num').textContent=(i+1)+' / '+SLIDES.length; }
function go(n,broadcast=true){ i=Math.max(0,Math.min(SLIDES.length-1,n)); paint(); if(broadcast) ch.postMessage({i}); }
ch.onmessage=e=>{ if(typeof e.data.i==='number'){ i=e.data.i; paint(); } };
let zoom = +(localStorage.getItem('deckZoom')||1);
function applyZoom(){ document.getElementById('stage').style.fontSize=(zoom*100)+'%'; localStorage.setItem('deckZoom',zoom); }
addEventListener('keydown',e=>{ if(e.key==='ArrowRight'||e.key===' ')go(i+1);
  else if(e.key==='ArrowLeft')go(i-1);
  else if(e.key==='ArrowUp'){ zoom=Math.min(2,zoom+0.1); applyZoom(); }      // font zoom (persisted)
  else if(e.key==='ArrowDown'){ zoom=Math.max(0.6,zoom-0.1); applyZoom(); }
  else if(e.key==='s'||e.key==='S')window.open(location.pathname+'?mode=speaker','speaker','width=1100,height=700');
  else if(e.key==='f'||e.key==='F'){document.fullscreenElement?document.exitFullscreen():document.documentElement.requestFullscreen();} });
applyZoom();
// timer + clock (speaker view)
const t0=Date.now(); setInterval(()=>{ const s=Math.floor((Date.now()-t0)/1000);
  const el=document.getElementById('elapsed'); if(el)el.textContent=String(Math.floor(s/60)).padStart(2,'0')+':'+String(s%60).padStart(2,'0');
  const c=document.getElementById('clock'); if(c){const d=new Date();c.textContent=String(d.getHours()).padStart(2,'0')+':'+String(d.getMinutes()).padStart(2,'0');} },1000);
go(0,false);
</script></body></html>

Narrative arc (default order)

Proven on the Makely build-session deck:

1. Title — product, one-line promise, live URL.
2. Painpoints, both sides — split the pain explicitly (the operator AND the end customer). Incumbents usually serve one side; naming both is the wedge.
3. Introduce the product — the one-liner / philosophy.
4. How it solves each problem — the live demo slide (switch to the app).
5. Tech — the stack, briefly.
6. Architecture / under the hood — substance you can't see in a screenshot.
7. Scaling — built to grow without a rewrite.
8. Security & privacy — speak the domain's regulatory language.
9. Roadmap — where it's going, and the bigger bet.
10. How I built it (agentically) — the coding-factory loop: idea → ticket → agent builds → push → deploy; the engineer-credibility + speed slide.
11. Your turn / build it live — hand them the keys (create a ticket live, watch it ship).

Visual density

Decks skew too wordy. Push for trimmed copy (one idea per slide), official tech-stack SVG icons (vendor or simple-icons), and at least one image per section. Store generic tech icons in this skill's assets/; keep domain imagery in a resources vault (an LLM-wiki vault of icons/images that decks + UI skills reference) so it is reusable. Nudge the user to create that resources vault.

Zoom + light mode (every generated deck)

• Zoom via CSS zoom, never transform: scale(). Transform-scale animates a per-slide transition (the deck visibly "jumps" to the right size on each navigation) and does not reflow, so text overflows when enlarged. zoom: var(--zoom) on the slide reflows responsively with no transition jump. Keep --zoom global (on :root) + persisted in localStorage so it is identical across every slide and across reloads.
• Light-mode hotkey (L), persisted. Presenters need to brighten a deck for a bright room. Drive ALL surface/border colors from CSS vars (--bg --fg --muted --surface --line) and add a body.light{} override toggled on L. Never hardcode dark hex on cards/pills or light mode breaks.

Deploy + clicker notes

• Vercel: git push to main auto-deploys (no vercel CLI). The custom domain can lag the edge cache a few minutes; the raw *.vercel.app URL is always fresh for verification.
• Clicker / remote = one surface: from clicker mode you can toggle to a view with presenter notes + the upcoming slide + a one-line headline. Sync via BroadcastChannel (same device) AND a shared room channel (cross-device); test the cross-device path, it is the one that breaks.

Checklist

• [ ] Content traces to real material (repo, commits, design docs, live URLs), nothing invented.
• [ ] Follows the narrative arc (painpoints-both-sides first, "how I built it agentically" near the end).
• [ ] Visual, not wordy: tech icons + at least one image per section.
• [ ] Zero emojis anywhere (slides, pills, buttons, hub, remote UI, status). Proper icons (inline lucide / vendor SVG) or clean labels only. Grep the output to confirm.
• [ ] Story arc, not a feature list. One idea per slide.
• [ ] Speaker notes on every slide (what to say + what to click in the live demo).
• [ ] Speaker view opens with S, syncs via BroadcastChannel, shows notes + timer + next.
• [ ] Phone remote: mode picker (clicker / speaker), QR to join, syncs cross-device; PWA-installable.
• [ ] ArrowUp/ArrowDown zoom slide text (persisted); Left/Right navigate.
• [ ] /present hub lists presentations; each has Present / Speaker / Clicker + Prep.
• [ ] Prep learning center generated: tech + industry + business-case domains, sourced from real material.
• [ ] Personas, scaling, and security/AVG each get a slide.
• [ ] Reads from the back of the room (big type). Opens offline (self-contained). No em-dashes.