sagadeck 1.2.0

package/src/ws.js

@@ -0,0 +1,134 @@
+// WebSocket mínimo (RFC 6455) sem dependências: cliente (Studio → serviço de conversa em tempo real) e o
+// lado servidor (usado pela API de mentira). Feito à mão para aceitar cabeçalhos (token) e o certificado
+// da empresa (ca), que o WebSocket do navegador/Node não deixam configurar.
+import crypto from "node:crypto";
+import net from "node:net";
+import tls from "node:tls";
+import { EventEmitter } from "node:events";
+
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+const accept = (key) => crypto.createHash("sha1").update(key + GUID).digest("base64");
+
+// ---------- quadros ----------
+function encode(data, { opcode, mask }) {
+  const payload = Buffer.isBuffer(data) ? data : Buffer.from(String(data), "utf8");
+  const op = opcode ?? (Buffer.isBuffer(data) ? 0x2 : 0x1);
+  const len = payload.length;
+  const head = [0x80 | op];
+  let ext = Buffer.alloc(0);
+  if (len < 126) head.push((mask ? 0x80 : 0) | len);
+  else if (len < 65536) { head.push((mask ? 0x80 : 0) | 126); ext = Buffer.alloc(2); ext.writeUInt16BE(len); }
+  else { head.push((mask ? 0x80 : 0) | 127); ext = Buffer.alloc(8); ext.writeBigUInt64BE(BigInt(len)); }
+  if (!mask) return Buffer.concat([Buffer.from(head), ext, payload]);
+  const key = crypto.randomBytes(4);
+  const masked = Buffer.alloc(len);
+  for (let i = 0; i < len; i++) masked[i] = payload[i] ^ key[i & 3];
+  return Buffer.concat([Buffer.from(head), ext, key, masked]);
+}
+
+// Conexão já estabelecida (depois do handshake), dos dois lados.
+class Conn extends EventEmitter {
+  constructor(socket, { client }) {
+    super();
+    this.socket = socket;
+    this.client = client; // cliente mascara o que envia
+    this.buf = Buffer.alloc(0);
+    this.parts = null; // mensagem fragmentada em andamento
+    this.open = true;
+    socket.on("data", (d) => { this.buf = Buffer.concat([this.buf, d]); this.parse(); });
+    socket.on("close", () => { if (this.open) { this.open = false; this.emit("close", 1006, "conexão caiu"); } });
+    // conexão derrubada do outro lado (ECONNRESET…): vira "close", nunca um erro solto que derruba o Studio
+    socket.on("error", (e) => {
+      if (this.listenerCount("error")) this.emit("error", e);
+      if (this.open) { this.open = false; this.emit("close", 1006, e.message); }
+    });
+  }
+  parse() {
+    for (;;) {
+      if (this.buf.length < 2) return;
+      const b0 = this.buf[0], b1 = this.buf[1];
+      const fin = !!(b0 & 0x80), op = b0 & 0x0f, masked = !!(b1 & 0x80);
+      let len = b1 & 0x7f, off = 2;
+      if (len === 126) { if (this.buf.length < 4) return; len = this.buf.readUInt16BE(2); off = 4; }
+      else if (len === 127) { if (this.buf.length < 10) return; len = Number(this.buf.readBigUInt64BE(2)); off = 10; }
+      const need = off + (masked ? 4 : 0) + len;
+      if (this.buf.length < need) return;
+      let payload = this.buf.subarray(off + (masked ? 4 : 0), need);
+      if (masked) { const k = this.buf.subarray(off, off + 4); payload = Buffer.from(payload.map((x, i) => x ^ k[i & 3])); }
+      this.buf = this.buf.subarray(need);
+      if (op === 0x8) { // close
+        const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005;
+        if (this.open) { this.open = false; try { this.socket.write(encode(payload.subarray(0, 2), { opcode: 0x8, mask: this.client })); } catch {} this.socket.end(); this.emit("close", code, payload.subarray(2).toString()); }
+        return;
+      }
+      if (op === 0x9) { this.socket.write(encode(payload, { opcode: 0xa, mask: this.client })); continue; } // ping → pong
+      if (op === 0xa) continue;
+      if (op === 0x0) { if (!this.parts) continue; this.parts.chunks.push(payload); }
+      else this.parts = { op, chunks: [payload] };
+      if (fin && this.parts) {
+        const all = Buffer.concat(this.parts.chunks), isText = this.parts.op === 0x1;
+        this.parts = null;
+        this.emit("message", isText ? all.toString("utf8") : all, isText);
+      }
+    }
+  }
+  send(data) { if (this.open) this.socket.write(encode(data, { mask: this.client })); }
+  close(code = 1000) {
+    if (!this.open) return;
+    const p = Buffer.alloc(2); p.writeUInt16BE(code);
+    try { this.socket.write(encode(p, { opcode: 0x8, mask: this.client })); } catch {}
+    this.open = false;
+    setTimeout(() => this.socket.destroy(), 200);
+    this.emit("close", code, "");
+  }
+}
+
+// Cliente: ws:// ou wss://, com cabeçalhos e certificado da empresa.
+export function connectWs(url, { headers = {}, ca, insecure = false, timeout = 15000, protocols } = {}) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try { u = new URL(url); } catch { reject(Object.assign(new Error(`Endereço inválido: ${url}`), { kind: "config" })); return; }
+    if (!/^wss?:$/.test(u.protocol)) { reject(Object.assign(new Error(`Conversa em tempo real precisa de ws:// ou wss:// (veio ${u.protocol})`), { kind: "config" })); return; }
+    const secure = u.protocol === "wss:";
+    const port = Number(u.port) || (secure ? 443 : 80);
+    const key = crypto.randomBytes(16).toString("base64");
+    const opts = { host: u.hostname, port, servername: u.hostname, ca, rejectUnauthorized: !insecure };
+    const socket = secure ? tls.connect(opts) : net.connect(opts);
+    const timer = setTimeout(() => { socket.destroy(); reject(Object.assign(new Error(`sem resposta de ${u.host} em ${Math.round(timeout / 1000)}s`), { code: "TIMEOUT" })); }, timeout);
+    socket.once("error", (e) => { clearTimeout(timer); reject(e); });
+    socket.once(secure ? "secureConnect" : "connect", () => {
+      const lines = [`GET ${u.pathname}${u.search} HTTP/1.1`, `Host: ${u.host}`, "Upgrade: websocket", "Connection: Upgrade",
+        `Sec-WebSocket-Key: ${key}`, "Sec-WebSocket-Version: 13", ...(protocols ? [`Sec-WebSocket-Protocol: ${[].concat(protocols).join(", ")}`] : []),
+        ...Object.entries(headers).map(([k, v]) => `${k}: ${v}`)];
+      socket.write(lines.join("\r\n") + "\r\n\r\n");
+    });
+    let head = Buffer.alloc(0);
+    const onData = (d) => {
+      head = Buffer.concat([head, d]);
+      const end = head.indexOf("\r\n\r\n");
+      if (end < 0) return;
+      socket.removeListener("data", onData);
+      clearTimeout(timer);
+      const text = head.subarray(0, end).toString();
+      const status = Number((text.match(/^HTTP\/1\.1 (\d+)/) || [])[1]);
+      if (status !== 101 || !text.toLowerCase().includes(`sec-websocket-accept: ${accept(key).toLowerCase()}`)) {
+        socket.destroy();
+        const body = head.subarray(end + 4).toString().slice(0, 400);
+        reject(Object.assign(new Error(`o serviço recusou a conexão (HTTP ${status || "?"})${body ? ": " + body : ""}`), { status }));
+        return;
+      }
+      const conn = new Conn(socket, { client: true });
+      const rest = head.subarray(end + 4);
+      resolve(conn);
+      if (rest.length) { conn.buf = rest; conn.parse(); }
+    };
+    socket.on("data", onData);
+  });
+}
+
+// Servidor: responde ao "upgrade" de um http.Server e devolve a conexão (usado pela API de mentira).
+export function acceptWs(req, socket) {
+  const key = req.headers["sec-websocket-key"];
+  socket.write(["HTTP/1.1 101 Switching Protocols", "Upgrade: websocket", "Connection: Upgrade", `Sec-WebSocket-Accept: ${accept(key)}`].join("\r\n") + "\r\n\r\n");
+  return new Conn(socket, { client: false });
+}

package/templates/cenario/Texto no cen/303/241rio.yaml"

@@ -0,0 +1,171 @@
+# Demonstração do "Texto no cenário" (layout scenography): todas as composições e tudo o que dá para ajustar.
+# Biblioteca: Nova, "Exemplo: texto no cenário". As imagens de exemplo estão em imagens/ (troque pelas suas).
+title: Texto no cenário
+theme: aurora
+motion: none
+author: Seu nome
+duration: 15
+slides:
+  - layout: scenography
+    scene: stage
+    kicker: DEMONSTRAÇÃO
+    title: "TEXTO NO\nCENÁRIO"
+    subtitle: Treze composições e tudo o que dá para ajustar.
+    caption: SAGADECK / TEXTO NO CENÁRIO
+    notes: Cada slide deste deck mostra uma composição (campo scene) ou uma opção. Abra o painel Formatar para ver os campos.
+
+  - layout: section
+    title: As composições
+    subtitle: Campo "Composição" (scene). O texto continua editável em todas.
+
+  - layout: scenography
+    scene: stage
+    kicker: "scene: stage"
+    title: "ALÉM DO\nÓBVIO"
+    subtitle: Palco e profundidade. Letras monumentais atrás de uma escultura.
+    caption: PALCO E PROFUNDIDADE
+
+  - layout: scenography
+    scene: floor
+    kicker: "scene: floor"
+    title: "NOVOS\nCAMINHOS"
+    caption: CHÃO EM PERSPECTIVA
+
+  - layout: scenography
+    scene: signs
+    kicker: "scene: signs"
+    title: "IDEIAS\nEM CENA"
+    subtitle: Uma placa na cidade.
+    caption: PLACAS NA CIDADE
+
+  - layout: scenography
+    scene: terminal
+    kicker: ./acesso --scene terminal
+    title: "acesso\nconcedido"
+    subtitle: Segurança começa pela curiosidade.
+    caption: TERMINAL HACKER
+
+  - layout: scenography
+    scene: cafe
+    kicker: "Hoje no cardápio (scene: cafe)"
+    title: "Ideias coadas\nna hora"
+    subtitle: Com calma, açúcar a gosto.
+    caption: LOUSA DE CAFÉ
+
+  - layout: scenography
+    scene: travel
+    kicker: "EMBARQUE IMEDIATO / scene: travel"
+    title: "PRÓXIMO\nDESTINO"
+    subtitle: O plano para os próximos 12 meses.
+    caption: CARTÃO DE EMBARQUE
+
+  - layout: scenography
+    scene: ticker
+    kicker: "Q3 2026 / scene: ticker"
+    title: "RESULTADO\nRECORDE"
+    subtitle: Receita 38% acima do ano passado.
+    caption: PREGÃO FINANCEIRO
+
+  - layout: scenography
+    scene: marquee
+    kicker: "EM CARTAZ / scene: marquee"
+    title: "HOJE:\nA ESTREIA"
+    subtitle: Sessão única, entrada franca.
+    caption: LETREIRO DE CINEMA
+
+  - layout: scenography
+    scene: blueprint
+    kicker: "scene: blueprint"
+    title: "PROJETO\nDO FUTURO"
+    subtitle: medidas em ideias, escala 1:1
+    caption: PLANTA TÉCNICA
+
+  - layout: scenography
+    scene: magazine
+    kicker: "CAPA / scene: magazine"
+    title: "O ANO DA\nVIRADA"
+    subtitle: Como uma equipe pequena mudou o jogo.
+    caption: CAPA DE REVISTA
+
+  - layout: scenography
+    scene: orbit
+    kicker: "scene: orbit"
+    title: "MISSÃO\nCUMPRIDA"
+    subtitle: Da ideia à órbita em seis meses.
+    caption: ÓRBITA
+
+  - layout: scenography
+    scene: synthwave
+    kicker: "scene: synthwave"
+    title: "DE VOLTA\nAO FUTURO"
+    subtitle: As ideias que voltaram com tudo.
+    caption: NEON ANOS 80
+
+  - layout: scenography
+    scene: gallery
+    kicker: "scene: gallery"
+    title: "Menos\né mais"
+    subtitle: Uma ideia por parede.
+    caption: PAREDE DE GALERIA
+
+  - layout: section
+    title: E dá para ajustar
+    subtitle: Imagem de fundo, transparência, recorte na frente das letras e tamanho do texto.
+
+  - layout: scenography
+    scene: stage
+    image: imagens/cidade.svg
+    imageOpacity: 1
+    kicker: "image: imagens/cidade.svg"
+    title: "IMAGEM DE\nFUNDO"
+    subtitle: "Imagem de fundo (image), sem transparência: imageOpacity: 1"
+    caption: IMAGEM DE FUNDO
+    notes: Troque imagens/cidade.svg por uma foto sua (arquivo ao lado do deck ou link).
+
+  - layout: scenography
+    scene: stage
+    image: imagens/cidade.svg
+    imageOpacity: 0.3
+    kicker: "imageOpacity: 0.3"
+    title: "MAIS\nTRANSPARENTE"
+    subtitle: De 0 (some) a 1 (inteira). Sem o campo, fica em 0.85.
+    caption: TRANSPARÊNCIA DO FUNDO
+
+  - layout: scenography
+    scene: floor
+    foreground: imagens/pessoa.svg
+    kicker: "foreground: imagens/pessoa.svg"
+    title: "NA FRENTE\nDAS LETRAS"
+    caption: RECORTE EM PRIMEIRO PLANO
+    notes: O recorte (PNG ou SVG com fundo transparente, do tamanho do slide) fica por cima do texto. O fundo não é recortado sozinho; recorte a pessoa num editor.
+
+  - layout: scenography
+    scene: gallery
+    foreground: imagens/pessoa.svg
+    kicker: "foreground + gallery"
+    title: "Olhe de\nperto"
+    subtitle: Alguém parado diante da parede.
+    caption: RECORTE NA GALERIA
+
+  - layout: scenography
+    scene: stage
+    image: imagens/cidade.svg
+    imageOpacity: 0.6
+    foreground: imagens/pessoa.svg
+    titleSize: 300
+    kicker: "titleSize: 300"
+    title: "TUDO\nJUNTO"
+    subtitle: Fundo, transparência, recorte e texto maior.
+    caption: TUDO JUNTO
+
+  - layout: scenography
+    scene: orbit
+    titleSize: 110
+    kicker: "titleSize: 110"
+    title: "Texto menor, mais respiro"
+    subtitle: Sem titleSize, cada composição usa o seu tamanho padrão.
+    caption: TAMANHO DO TEXTO
+
+  - layout: end
+    title: Agora é com você
+    subtitle: Inserir, Texto no cenário. Depois é só escolher a composição.

package/templates/cenario/imagens/cidade.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <!-- fundo de exemplo do deck "Texto no cenário": uma cidade ao entardecer (troque por uma foto sua) -->
+  <defs>
+    <linearGradient id="ceu" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#241a4f"/>
+      <stop offset=".55" stop-color="#b8517a"/>
+      <stop offset=".8" stop-color="#ffb070"/>
+    </linearGradient>
+    <pattern id="janelas" width="36" height="44" patternUnits="userSpaceOnUse">
+      <rect x="8" y="10" width="14" height="18" fill="#ffd98a" opacity=".75"/>
+    </pattern>
+  </defs>
+  <rect width="1920" height="1080" fill="url(#ceu)"/>
+  <circle cx="1380" cy="700" r="170" fill="#ffe2a6" opacity=".9"/>
+  <g fill="#3a2350">
+    <rect x="0" y="640" width="220" height="440"/><rect x="240" y="520" width="170" height="560"/>
+    <rect x="430" y="700" width="260" height="380"/><rect x="700" y="430" width="150" height="650"/>
+    <rect x="870" y="610" width="230" height="470"/><rect x="1120" y="540" width="190" height="540"/>
+    <rect x="1330" y="760" width="210" height="320"/><rect x="1560" y="480" width="160" height="600"/>
+    <rect x="1740" y="660" width="180" height="420"/>
+  </g>
+  <g fill="#1d1230">
+    <rect x="100" y="780" width="260" height="300"/><rect x="560" y="820" width="210" height="260"/>
+    <rect x="980" y="760" width="240" height="320"/><rect x="1450" y="840" width="300" height="240"/>
+  </g>
+  <g fill="url(#janelas)">
+    <rect x="240" y="520" width="170" height="560"/><rect x="700" y="430" width="150" height="650"/>
+    <rect x="1120" y="540" width="190" height="540"/><rect x="1560" y="480" width="160" height="600"/>
+  </g>
+</svg>

package/templates/cenario/imagens/pessoa.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="1920" height="1080">
+  <!-- recorte de exemplo (fundo transparente): uma pessoa em pé, à direita. Fica na frente das letras (foreground).
+       Para uma foto sua, recorte a pessoa num editor e salve como PNG transparente do mesmo tamanho do slide. -->
+  <defs>
+    <linearGradient id="luz" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#2a2238"/>
+      <stop offset=".75" stop-color="#1a1424"/>
+      <stop offset="1" stop-color="#ff9a6b"/>
+    </linearGradient>
+  </defs>
+  <g fill="url(#luz)">
+    <ellipse cx="1470" cy="455" rx="62" ry="74"/>
+    <path d="M1452 520h40l10 30c70 10 118 40 130 110l40 250c6 40-40 50-52 12l-40-190-10 398h-68l-20-300-20 300h-68l-12-398-40 190c-12 38-58 28-52-12l40-250c12-70 60-100 122-110z"/>
+  </g>
+</svg>

package/templates/cenario-e-ciencia.yaml

@@ -0,0 +1,47 @@
+title: Texto no cenário e matemática
+id: cenario-e-ciencia
+theme: aurora
+motion: none
+slides:
+  - layout: scenography
+    scene: stage
+    kicker: IDEIAS QUE OCUPAM ESPAÇO
+    title: "ALÉM DO\nÓBVIO"
+    subtitle: O texto também faz parte da história.
+    caption: SAGADECK / ESTUDO 01
+    deco: none
+  - layout: scenography
+    scene: floor
+    kicker: UMA NOVA PERSPECTIVA
+    title: "NOVOS\nCAMINHOS"
+    caption: SAGADECK / ESTUDO 02
+    deco: none
+  - layout: scenography
+    scene: signs
+    kicker: PRÓXIMA PARADA
+    title: "IDEIAS\nEM CENA"
+    subtitle: Mensagens que pertencem ao lugar.
+    caption: SAGADECK / ESTUDO 03
+    deco: none
+  - layout: science
+    title: A onda e sua derivada
+    equations:
+      - label: Função
+        latex: 'f(x)=\sin(x)'
+      - label: Derivada
+        latex: 'f\prime(x)=\cos(x)'
+      - label: Identidade
+        latex: '\sin^2(x)+\cos^2(x)=1'
+    plot:
+      preset: wave
+    notes: Arraste uma área do gráfico para dar zoom. Passe o mouse para consultar os valores.
+  - layout: science
+    title: Matemática que você pode explorar
+    equations:
+      - label: Raio
+        latex: 'r=\sqrt{x^2+y^2}'
+      - label: Superfície
+        latex: 'z=\sin(r)'
+    plot:
+      preset: surface
+    notes: Arraste para girar. Use a roda do mouse para aproximar.

package/templates/ensaio-api.yaml

@@ -0,0 +1,160 @@
+# Ensaio de aula de APIs de IA: roda contra a API de mentira, no ambiente embutido ENSAIO do Studio
+# (biblioteca → Nova → "Exemplo: aula de APIs ao vivo", ou `sagadeck ensaio-api`).
+# Serve de modelo: troque as URLs e os caminhos $.… pelos do seu serviço e cadastre os seus ambientes
+# no Studio (Inserir → Ambientes), que grava em ~/.sagadeck/ambientes.yaml. Veja "Slide api" em docs/REFERENCIA.md.
+title: "Ensaio: APIs de IA ao vivo"
+theme: sinal
+author: Seu nome
+duration: 30
+slides:
+  - layout: cover
+    kicker: Ensaio
+    title: APIs de IA, ==ao vivo==
+    subtitle: Do token à resposta, executando na frente de todo mundo
+    notes: |
+      Este deck roda contra uma API de mentira (o ambiente ENSAIO, que o Studio sobe sozinho). Apresente e clique em Executar em cada slide.
+      Se você já tem ambientes seus, clique no selo do slide (DEV, HOM…) e escolha ENSAIO.
+      Tudo funciona igual com o serviço de verdade: troque os endereços em Inserir → Ambientes.
+
+  - layout: api
+    id: identity
+    kicker: Passo 1 · Identity
+    title: Primeiro, o ==token==
+    text: Toda chamada leva um JWT que vale 30 minutos
+    request:
+      method: POST
+      url: "{{identity}}"
+      auth: false
+      body: { client_id: "{{client_id}}", client_secret: "{{secret.client_secret}}" }
+    token: "$.data.token"
+    notes: |
+      Mostre o corpo: o client_secret aparece como {{secret.client_secret}} — o valor fica no ambiente, nunca no slide.
+      Execute: o JWT aparece decodificado, com a contagem regressiva. Daqui para frente, todo slide usa este token (olhe o final ••••).
+
+  - layout: api
+    id: llm
+    kicker: Passo 2 · LLM
+    title: A pergunta mais ==simples==
+    request:
+      method: POST
+      url: "{{base}}/sync"
+      body: { messages: [ { role: user, content: "O que é RAG, em uma frase?" } ] }
+    answer: "$.choices[0].message.content"
+    notes: Edite a pergunta na hora (aba Corpo) e execute de novo. Mostre as abas curl e Python.
+
+  - layout: api
+    id: openrouter-nemotron
+    kicker: OpenRouter (real)
+    title: Pergunte ao ==Nemotron==
+    text: Chamada real ao modelo gratuito NVIDIA Nemotron pelo OpenRouter
+    request:
+      method: POST
+      url: "{{base}}/chat/completions"
+      auth: false
+      headers:
+        Authorization: "Bearer {{secret.openrouter_api_key}}"
+        X-Title: SagaDeck
+      body:
+        model: nvidia/nemotron-3-super-120b-a12b:free
+        max_tokens: 350
+        messages:
+          - role: user
+            content: "Explique o que é uma API em uma frase, em português."
+    answer: "$.choices[0].message.content"
+    notes: |
+      Esta chamada acessa o OpenRouter de verdade com um modelo gratuito compatível com Chat Completions.
+      No selo de ambiente, escolha OPENROUTER.
+      A chave não fica no deck: defina OPENROUTER_API_KEY no processo que inicia o Studio e reinicie-o.
+      Edite a pergunta na aba Corpo e execute novamente para testar o comportamento do modelo.
+
+  - layout: api
+    id: workflow
+    kicker: Passo 3 · Workflow
+    title: Inicia e ==acompanha== até terminar
+    text: O início devolve só o código da execução; a consulta repete até FINISHED
+    mode: polling
+    tab: python-comentado
+    request: { url: "{{base}}/start", body: { workflow: "{{wf}}", input: { path_id: "store/contrato.txt" } } }
+    polling: { id: "$.executionId", check: { url: "{{base}}/status/{{id}}" }, status: "$.status", done: [FINISHED], failed: [ERROR], interval: 0.8 }
+    steps: "$.responses"
+    stepText: "$.output"
+    notes: Deixe na aba Python comentado e execute — o laço while acende a cada consulta, enquanto a linha do tempo cresce.
+
+  - layout: api
+    id: stream
+    kicker: Passo 4 · Streaming
+    title: A resposta chega ==aos poucos==
+    mode: stream
+    request: { method: POST, url: "{{base}}/stream", body: { stream: true } }
+    notes: "Compare com o síncrono: aqui o texto aparece enquanto é gerado."
+
+  - layout: api
+    id: upload
+    kicker: Passo 5 · FileManager
+    title: Sobe o arquivo, volta o ==path_id==
+    file: contrato.txt
+    request: { url: "{{base}}/upload", form: { file: "@file", pasta: workshop } }
+    save: { path_id: "$.path_id" }
+    notes: Arraste outro arquivo no slide se quiser. O path_id fica guardado para os próximos slides.
+
+  - layout: api
+    id: ocr
+    kicker: Passo 6 · OCR
+    title: Lendo pelo ==path_id==
+    request: { url: "{{base}}/ocr", body: { path_id: "{{path_id}}" } }
+    answer: "$.text"
+    notes: "Mostre que {{path_id}} veio do slide anterior (aba curl: já com o valor)."
+
+  - layout: api
+    id: indexador
+    kicker: Passo 7 · Indexador
+    title: Planilha ==linha a linha==
+    tab: fields
+    request: { url: "{{base}}/index", body: { path_id: "{{path_id}}", mode: rows, sheet: { header_row: 1 }, chunk_size: 0 } }
+    fields:
+      "$.mode": "rows: cada linha vira um documento; pdf: o arquivo inteiro, em pedaços"
+      "$.sheet.header_row": "linha do cabeçalho (começa em 1): as colunas viram metadados"
+      "$.chunk_size": "com rows, tem que ser 0 — qualquer outro valor faz a indexação falhar"
+      "$.path_id": "o que o FileManager devolveu"
+    answer: "$.documents"
+    notes: "Mude chunk_size para 800 na aba Corpo e execute: a indexação falha. É a combinação que a documentação não conta."
+
+  - layout: api
+    id: embeddings
+    kicker: Passo 8 · Embeddings
+    title: Qual frase fica ==mais perto==?
+    request: { url: "{{base}}/embeddings", body: { model: emb, input: "{{text}}" } }
+    similarity:
+      reference: Quero abrir uma conta no banco
+      texts: [ "Vai chover amanhã em São Paulo?", "Como faço para abrir uma conta?", "Abrir conta no banco hoje" ]
+    notes: "Peça frases para a plateia e escreva na aba Frases."
+
+  - layout: api
+    id: tts
+    kicker: Passo 9 · Voz
+    title: Texto que ==fala==
+    audio: fala.wav
+    request: { url: "{{base}}/tts", body: { text: "Bom dia, pessoal" } }
+
+  - layout: api
+    id: stt
+    kicker: Passo 10 · Escuta
+    title: Fala que vira ==texto==
+    mic: true
+    request: { url: "{{base}}/stt", form: { audio: "@file", idioma: pt-BR } }
+    answer: "$.text"
+    notes: "Clique em Gravar, fale, clique em Parar: ele envia sozinho."
+
+  - layout: api
+    id: tempo-real
+    kicker: Passo 11 · Tempo real
+    title: Conversa por ==voz==, ao vivo
+    mode: realtime
+    realtime:
+      url: "{{ws}}/realtime"
+      open: [ { type: session.update, session: { voice: alloy, instructions: "Responda em português, curto." } } ]
+    notes: "Conecte, clique em Falar, fale e clique em Parar. Mostre a aba Mensagens: cada evento do WebSocket, nos dois sentidos."
+
+  - layout: end
+    title: Obrigado.
+    subtitle: Perguntas?

package/templates/exemplo-alegre.yaml

@@ -0,0 +1,75 @@
+title: Apresentação Alegre e Visual
+theme: rabisco
+duration: 15
+slides:
+  - layout: cover
+    kicker: Ideias Vivas · Sem Sono
+    title: Como Criar Slides Bonitinhos & Visuais
+    subtitle: Menos texto longo, muito mais impacto e cores alegres
+    author: SagaDeck Studio
+  - layout: stats
+    kicker: Métricas em Destaque
+    title: O Poder dos Números Visuais
+    stats:
+      - value: 98.7%
+        label: Retenção da Atenção
+        trend: +34%
+        trendUp: true
+        icon: heart
+        text: Público conectado do início ao fim
+      - value: 4.8x
+        label: Mais Rápido de Ler
+        trend: recorde
+        trendUp: true
+        icon: zap
+        text: Zero cansaço visual
+      - value: 2.100+
+        label: Ícones Disponíveis
+        trend: ilimitado
+        trendUp: true
+        icon: sparkles
+        text: Elementos gráficos prontos
+  - layout: steps
+    kicker: Fluxo Visual
+    title: Processo Simples em 3 Etapas
+    steps:
+      - stepNum: 1
+        title: Rascunho
+        text: Escolha o tema Rabisco ou Oceano
+        icon: pen-tool
+        tag: 1 Minuto
+      - stepNum: 2
+        title: Visualizar
+        text: Troque parágrafos por cards e métricas
+        icon: layout-grid
+        tag: Auto-Fit
+      - stepNum: 3
+        title: Apresentar
+        text: Entregue um show no palco sem sono
+        icon: smile
+        tag: Aplausos
+  - layout: cards
+    kicker: Cartões Inteligentes
+    title: Widgets que Eliminam Textão
+    cols: 3
+    items:
+      - icon: check-circle-2
+        badge: Recomendado
+        title: Checklist Visual
+        text: Substitui listas sem graça por confirmações visuais.
+        check: true
+        checkText: Pronto para uso
+      - icon: target
+        title: Meta de Conclusão
+        text: Progresso visual fácil de acompanhar.
+        progress: 88
+        progressLabel: Meta Atingida
+      - icon: award
+        title: Avaliação do Público
+        text: Nota máxima dada pela audiência.
+        rating: 5
+        ratingLabel: 5.0 no G2
+        tags:
+          - Alegre
+          - Dinâmico
+          - Sem Sono