sagadeck 1.8.0 → 1.10.0

package/docs/ANDAMENTO.md

@@ -8,11 +8,253 @@ começar. Trabalho em curso vai para o GitHub (commit + push) a cada etapa, nunc
 
 ---
 
+## UX para programação e APIs com cURL — 12/10/2026 (branch `codex/ux-dev-slides`, versão 1.10.0)
+
+Pedido: reduzir dificuldade de uso, facilitar geração técnica, acrescentar recursos e dois temas bonitos com
+animação; testar, PR, merge, publicar no npm e atualizar sagadeck-dev. Trabalho somente na pasta oficial,
+sem worktrees, conforme AGENTS.md. Main começou limpa em `46e0afd`, com a CI dos quatro ambientes verde.
+
+Diagnóstico: recursos técnicos existiam, mas começar dependia de descobrir layouts, escrever briefing do zero e
+preencher campos estruturados. cURL era exibido sem realce de sintaxe; demos extensas não eram uma base curta.
+Mudanças:
+- Biblioteca com entradas Programação/APIs com cURL; Nova com IA oferece exemplos de pedidos, material técnico
+  colado, público/objetivo/roteiro opcionais, resumo, prévia do pedido e Ctrl+Enter. Intenção explícita orienta o
+  modelo pelo prompt, sem regras de decisão por regex; texto e estilo manual continuam prioritários.
+- Bases sem IA (`src/studio/developer-starters.js`), cinco slides com exemplo consistente, guia, saída e terminal
+  de cenas. Criação pela biblioteca; a de APIs usa ENSAIO e funciona localmente sem credenciais externas.
+- Início/Inserir › Código / cURL: conteúdo colado vira código, código guiado ou requisição de API. Parser de
+  argumentos sem shell e sem executar; opções não suportadas geram mensagem antes de inserir. Credenciais
+  reconhecidas viram referências a Segredos antes de gravar. Código de exibição é preservado literalmente.
+- Etapas guiadas por seleção de linhas, no modal e em Formatar; linguagem inferida/selecionável; realce offline
+  novo de Bash/cURL, JSON e SQL. Anexos de código/configuração preservam espaços, indentação e linhas em branco.
+- `terminal-pro` (grafite/menta, IDE) e `aurora-dev` (azul noite/lilás/ciano, painéis e luz suave): fontes embutidas,
+  contraste de texto/sintaxe, rede de capa que para fora dela e em movimento reduzido/exportação. Design usa o
+  mesmo caminho existente de tema salvo; nenhum deck pessoal modificado.
+
+Regressões cobrem parser, segredos, código literal, etapas e arquivos gravados, prompts ao LLM, anexos técnicos,
+criação sem IA, escolha dos temas por teclado, contraste, animação, movimento reduzido e exportação. Testes
+direcionados de motor/fontes/guards: 85 aprovados; temas e geração passaram também no navegador.
+Geração com IA real também aprovada: briefing técnico aplica Aurora Dev e mantém o cURL original copiável (62 s).
+Revisão independente achou e reproduziu perdas de inteiros grandes ao proteger JSON e de variáveis na codificação
+do formulário: proteção agora edita só spans sensíveis do texto. Interpolação contextual opt-in
+(`request.bodyEncoding`/`urlEncoding`) mantém JSON/form/query corretos no envio; ensaio HTTP real confere `&`, aspas,
+barras, Unicode, números grandes e máscara de respostas/gravações. URL com Segredo agora é enviada já resolvida.
+Callbacks de upload/geração são invalidados ao trocar/cancelar modal; Tab fica no diálogo e Escape devolve foco.
+Essas regressões falharam antes das correções e passaram depois. Suíte completa iniciada com as frentes estáveis.
+Entrega final aguardando suíte completa e CI; publicação de `sagadeck@1.10.0` por release com trusted publishing.
+Oracle: atualizar apenas `/opt/sagadeck-dev`/`sagadeck-dev.service` (3518), preservando produção. Reiniciar também
+a instância local verificada na 3517 e conferir versão/recursos depois da atualização.
+Retomada em 13/10 após limite da sessão. Suíte inicial: 1.084 testes, 1.054 aprovados, 27 condicionais pulados e
+3 falhas (uma de Python ausente no PATH, uma de rótulo e a contagem do teste pai). Python passou isolado com o
+runtime disponível no PATH; a guarda de palavras grudadas agora reconhece o nome técnico cURL sem enfraquecer
+os demais rótulos. A revisão final também cobre execução pelo navegador preservando corpo JSON literal e comandos
+equivalentes copiáveis com segredos em JSON/form/query. Suíte final concluída: `npm test`, 1.093 testes,
+1.066 aprovados, 27 condicionais pulados, zero falhas (24 min). Geradores de cURL/JavaScript/Python também
+enviaram pedidos reais ao ensaio HTTP. Preview e Formatar mantêm JSON literal; respostas/gravações não permitem
+recuperar segredos mesmo em logs com JSON aninhado. Instância local reiniciada na 3517, versão 1.10.0, com os novos
+módulos/CSS respondendo 200. PR #197 publicado; os quatro checks originais Ubuntu/Windows, Node 22/24, passaram.
+Por orientação posterior do usuário, o suporte passa a Node 24+: engines, instruções de instalação e matriz da
+CI atualizados, sem mudança no código já aprovado. YAML e metadados conferidos; a nova CI exige Ubuntu e Windows
+com Node 24 antes de merge/release. DEV da Oracle recebeu `135cfd2`, com versão 1.10.0 e ambos os temas disponíveis;
+produção preservada. A publicação npm ainda aguarda merge e CI do commit final.
+PR #197 integrado em `03f9ff4`; local na 3517 e DEV na 3518 reiniciados com esse commit e versão 1.10.0.
+Os dois checks do PR passaram, mas a nova rodada da main encontrou uma corrida no teste de Formatar: o helper
+confirmava a gravação no servidor antes de o formulário do novo slide terminar de renderizar, lendo o corpo
+do slide anterior. Publicação npm suspensa até corrigir e validar essa sincronização. Correção na branch
+`codex/ux-dev-format-sync`; nenhuma mudança no conteúdo das apresentações nem no código da aplicação.
+Atrasar `api/render-slide` em 400 ms reproduziu exatamente a falha da Ubuntu. O helper agora aguarda a
+identidade do formulário pelo campo Título, além da gravação; a mesma regressão passou após o ajuste.
+Seis testes dirigidos aprovados, zero erros JavaScript e corpos JSON/form conferidos também no arquivo salvo.
+Suíte completa após o ajuste: `npm test`, 1.093 testes, 1.066 aprovados, 27 condicionais pulados e zero falhas
+(30 min). A falha da main ficou restrita a essa sincronização; Windows passou. Correção pronta para commit/PR
+e checks Ubuntu/Windows Node 24 antes de integrar e publicar a versão 1.10.0.
+
+## Assistente em prévia de modelo na Oracle — 12/10/2026
+
+O erro `APP_UNKNOWN · a4670ccb` da produção era `path.dirname(null)` no preparo dos anexos: modelos abertos
+pela vitrine ainda não têm arquivo. O pedido parava antes de chegar ao modelo. Agora o chat só prepara documentos
+em uma pasta existente; documento binário, imagem gerada e edição materializam a cópia com os helpers da biblioteca.
+Conversa simples continua sem criar arquivo. A aba do servidor e o endereço do editor passam a usar essa mesma
+cópia, evitando edição perdida ou segunda cópia no pedido seguinte. Modelo de fábrica e outras pessoas preservados.
+Regressão em `test/studio-ai-preview.test.js`: falhou antes com o erro exato; cobre conversa, edição salva,
+recarregamento no navegador, isolamento por usuário e documento inventariado na pasta pessoal.
+Imagem gerada também é conferida no arquivo e na pasta pessoal. Texto e visão reais passaram nos dois serviços.
+A CI da main apresentou timeout no teclado ao mudar o título logo após abrir o editor no Windows 24; o teste da
+biblioteca agora espera a página terminar de carregar antes de editar, mantendo a conferência do arquivo salvo.
+Validação: npm test com 1.034 testes, 1.008 aprovados, 26 condicionais pulados, zero falhas; quatro regressões novas
+passaram na suíte. O teste da biblioteca com a espera de carregamento passou também isolado (13 testes).
+Entrega: commit da correção para os dois serviços da Oracle após validação local; merge do PR somente com os quatro
+checks verdes (Ubuntu/Windows, Node 22/24). Não há mudança de dependências nem publicação de versão no npm.
+PR #196 publicado. Oracle dev (3518) e produção (3517) receberam o commit `e32a3c1` e reiniciaram; nos dois,
+o pedido real em uma prévia voltou com `mode: llm`, conversa, sem diagnóstico de erro e sem criar cópia.
+Bibliotecas pessoais não foram alteradas. A CI do PR continua sendo acompanhada para concluir o merge.
+Revisão adicional reproduziu perda ao recarregar quando o patch só mudava campos do deck (tema, contexto…) ou
+excluía slides: a lista de slides alterados era vazia e a cópia não nascia. A materialização agora vale para toda
+ação do modelo, preservando conversa e alternativas em prévia. Regressão confere tema salvo, exclusão e demais
+slides preservados; falhou antes da correção.
+Suíte completa após esse ajuste: 1.035 testes, 1.009 aprovados, 26 condicionais pulados e zero falhas.
+Os cinco testes de prévia passaram; nova CI será exigida para o commit final antes do merge do PR #196.
+Oracle dev e produção receberam também `333857f`: conversa real e mudança de tema pelo modelo funcionaram;
+o tema permaneceu ao reabrir o arquivo pelas APIs nativas. Apresentações sintéticas removidas pela biblioteca.
+A CI aprovou Ubuntu 22/24 e Windows 22. Windows 24 teve timeout na galeria; o teste isolado passou (3/3) e a
+reexecução aprovou o carrossel, mas encontrou `ERR_NO_BUFFER_SPACE` durante exportação. Isso indica pressão de
+recursos de rede no runner; a faixa TCP dinâmica agora é ampliada somente nas máquinas descartáveis da CI,
+com diagnóstico de estados TCP em falhas. Testes e exigência de zero erros de navegador preservados.
+Código da aplicação permanece o mesmo da suíte local completa aprovada (1.009/26/0); ajuste de CI validado como
+YAML, e os quatro ambientes serão novamente conferidos antes do merge.
+
+## Sobre legível no tema escuro — 12/10/2026 (branch `sobre-tema-escuro`)
+
+Narumi (com print): no Windows e no dev da Oracle o Sobre "não abre direito", com texto apagado. Causa: o CSS do
+`about.js` pegava o fundo de `--panel`/`--bg`, que nenhuma página define (caía no branco), e o texto de `--text`,
+que no tema escuro é claro, o que dava contraste 1,16. Agora fundo, borda e botão vêm de `--chrome`, `--ui-line` e
+`--brand-fill`, que o editor (style.css/studio-next.css) e a biblioteca (library.css) definem nos dois temas. Teste
+novo em `test/sobre.test.js`: contraste WCAG mínimo de 4,5 do texto contra o fundo da janela, nos temas claro e
+escuro, no editor e na biblioteca. Ele falha com o CSS antigo.
+
+## Ajuda › Sobre o SagaDeck — 12/10/2026 (branch `ajuda-sobre`)
+
+Narumi: "insira um help com about no menu onde eu posso ver a versão". A aba **Ajuda** fecha a faixa do editor
+(depois de Avançado, como no PowerPoint) com Sobre o SagaDeck, O que mudou (CHANGELOG) e Demos. O Sobre
+(`src/studio/public/about.js`, `window.SagaAbout`; qualquer elemento com `data-about` abre) mostra a versão em
+destaque, commit, Node e sistema (novos em `/api/instance`), desde quando está no ar, a biblioteca (no multiusuário,
+só que é do servidor) e se a IA está configurada, com Copiar informações para suporte. Na biblioteca, um botão com o
+ícone de informação no alto. Achados de passagem: o `dialog` nativo abria colado no canto (uma regra global zerava
+a margem; o Sobre põe `margin:auto`) e botão da faixa que é link (`a.rbtn`) saía sublinhado. Teste:
+`test/sobre.test.js`; a ordem da faixa em `studio.test.js`.
+
+## `sagadeck ia-check`: o que de IA funciona, sem tela — 12/10/2026 (branch `ia-check`)
+
+Narumi: "o sagadeck está preparado para ser testado por um agente de IA (tipo o Copilot) sem o front-end?
+Principalmente a execução dos modelos: preciso saber rapidamente quais features de IA funcionam". Não estava: só o
+Testar do Configurar IA (uma pergunta de texto) e os testes ao vivo, que avaliam decisões e levam minutos.
+- `src/ai/ia-check.js` (`iaCheck`): texto, visão, imagem, pesquisa e vídeo em paralelo, prazo próprio por recurso,
+  cada resultado avisado ao chegar. Visão com prova: um PNG de duas faixas de cor sorteadas, desenhado no código; o
+  modelo precisa dizer as cores na ordem, e modelo que não aceita imagem falha (o `chat` refazia sem a imagem e dava
+  "ok" sem ver). Pesquisa: a data de hoje. Imagem: confere o tipo pelos bytes e grava o arquivo.
+- Vídeo: Narumi primeiro quis a geração real sempre, depois decidiu: padrão sem custo (catálogo, status `sem_prova`,
+  que não conta como ok) e `--video-real` quando ela pedir (clipe mais curto e leve que o modelo aceita, baixa e confere
+  o MP4).
+- No caminho, a pergunta dela ("o teste usa a chave do OpenRouter? o setup dos modelos não é uma camada separada?")
+  expôs que o vídeo ficava fora da camada da IA: endereço do OpenRouter no código e chave só em variável. Agora
+  `videoSetup` (`video-generation.js`): com modelo de vídeo em Configurar IA (papel novo `video`), usa endereço, chave,
+  cabeçalhos e adaptador de lá; sem ele, o comportamento antigo (Oracle e quem já usava). A consulta e o download só
+  levam a chave ao mesmo servidor configurado (`videoApiURL`). O catálogo virou opcional.
+- Saídas: `sagadeck ia-check` (`--rapido`, `--so`, `--video-real`, `--json`, código de saída), ferramenta MCP
+  `sagadeck_ia_check`, `POST /api/ia/check` (fora do multiusuário). SKILL.md manda o agente rodar antes de prometer
+  recurso de IA.
+- Medido nesta máquina contra o OpenRouter: texto, visão e pesquisa em 2,3 s (`--rapido`); com imagem, 8 a 11 s.
+- Teste `test/ia-check.test.js` (LLM falso e provedor de vídeo simulado: cada falha com o motivo, paralelismo, vídeo
+  pela camada da IA, linha de comando). Achado: o `spawnSync` do teste da linha de comando travava o LLM falso do
+  próprio processo, e o teste só passava por estourar o prazo; virou `execFile` e exige o motivo certo.
+- Flake corrigido: `studio.test.js` procurava "ocr" no slide inteiro e o uid sorteado `s1ocrpz0ieql` derrubou a CI da
+  `main` depois do #191.
+
+## Demos de um assunto só: mapas, programação e APIs com curl — 11/10/2026 (branch `demos-recursos`)
+
+Narumi: em vez do demo inchado que faz tudo (o Conheça o SagaDeck), uma demo só de mapas, uma de programação e uma de
+curl. Entraram em `src/studio/feature-demos.js` (`demoDeck('mapas' | 'programacao' | 'apis')`, `FEATURE_DEMO_NAMES`)
+e vão primeiro na vitrine e em Demos oficiais; o Conheça continua lá, depois delas.
+- **Mapas** (tema oceano): reaproveita as demos de mapa do tour (`mapDemos`, agora exportada) em três partes:
+  mostrar, calcular, editar; a cópia leva as capturas do Editar mapa (`demoAssets`).
+- **Programação** (tema musgo, terminal de cenas na capa): código destacado, guiado, consulta, código explorável,
+  algoritmo, dois terminais, duelo de commits, code review, diagrama de sequência e rede explorável.
+- **APIs com curl** (tema wine): a anatomia de um curl (código guiado), chamadas ao vivo abertas na aba curl (POST,
+  GET com consulta, com token, polling, streaming) na API de mentira do Studio (ENSAIO), as opções do dia a dia em
+  cartões que viram e o aviso do token.
+- Teste: `test/demos-recursos.test.js` (montam sem aviso, cada uma só do seu assunto, e cada chamada da de curl
+  funciona contra a API de mentira); a ordem nova da vitrine em `library-ui.test.js`.
+- **Revisão de todas as demos** (Narumi: "mantenha só o que fizer sentido"). Ficam na vitrine e em Demos oficiais:
+  mapas, programação, APIs com curl, Conheça o SagaDeck, aula de hidráulica, aula de algoritmos e diagramas vivos.
+  Saíram: **Explore uma ideia** ("Uma pergunta, vários caminhos", não demonstrava nada claro), **Novidades** (colcha
+  de retalhos; o slide da planilha dependia de um arquivo que a prévia não tem, e a aba Arquivos aparecia vazia),
+  **Material de consulta** e **Recursos avançados** (quase iguais, com cartões genéricos; a consulta está na de
+  programação) e **Aula de APIs ao vivo** (fica uma demo de API só, a de curl; o ensaio completo continua no
+  `sagadeck ensaio-api`). Os decks dessas demos continuam no código porque os testes os usam como material
+  (código denso, arquivos do projeto, exploração); só não aparecem mais. O teste de ponta a ponta da vitrine com
+  o ENSAIO agora abre a de curl, vira cópia e executa corpo, consulta e token no Studio.
+
+## Temas de infográfico, cartão que vira e botão + — 11/10/2026 (branch `temas-cartoes`, sobre `tema-musgo`)
+
+Pedido da Narumi, com prints de modelos de infográfico interativo: uma variante do musgo com outra paleta e os
+visuais dos prints, com destaque para o cartão que gira no clique e mostra o verso. Entrou:
+- **`wine`**: o musgo em vinho (vermelho-rosado, rosé, vermelho forte só no detalhe). Usa a pele do musgo por
+  `skin: "musgo"` (o `build.js` lê a pele do outro e troca o seletor); fontes em `MUSGO_FACES`.
+- **`caderno`** (visual thinking: Amatic SC + Gelasio, cartões com moldura pastel, rabiscos de ícones Lucide como
+  máscara), **`lousa`** (giz: Cabin Sketch + Itim), **`cartaz`** (protesto: Bebas Neue em faixas vermelhas tortas) e
+  **`infografico`** (dados chapados: Bebas Neue + Montserrat). Fontes OFL em `vendor-fonts.mjs`.
+- **Cartão que vira** (`flip` no cartão; `back` já era o Voltar da navegação e o verificador de links lia o verso como destino; `elements.js` `flipCard`, `base.css`, `runtime.js`): frente e verso na mesma
+  célula, clique/Enter gira, sair do slide desvira; exportação mostra a frente.
+- **Botão + com balão** (`pop` em qualquer lugar; `more` no marco da linha do tempo): abre o balão e escurece o resto
+  com uma sombra enorme em volta do botão; um de cada vez, fecha fora e ao trocar de slide.
+- **Defeito achado:** o ajuste para caber (`fit.js`) via o texto do verso "por cima" do da frente e encolhia o slide
+  inteiro; verso e balão saem dessa conta.
+- Teste do arranjo único por tema aceita o tema irmão (`skin`). Testes: `test/temas-infografico.test.js`.
+
+## Tema musgo, faixa que corre e terminal em cenas — 11/10/2026 (branch `tema-musgo`)
+
+Pedido da Narumi: trazer para o sagadeck o visual de uma página que ela adorou (um site de "segundo cérebro" gerado
+por outro modelo): tema, cores, fontes, botões, o terminal que digita os `curl`, a faixa que fica correndo e o
+separador das seções. Entrou:
+- **Tema `musgo`** (`src/themes.js`, `src/runtime/skins/musgo.css`): verde quase preto com grão, âmbar e sálvia;
+  Fraunces (com tamanho óptico e itálico de verdade), Space Grotesk e IBM Plex Mono, embutidas (OFL, `vendor-fonts.mjs`
+  agora aceita estilo itálico). PPTX com Georgia, Segoe UI e Cascadia Mono. Capa e seção com grade de pontos que some
+  nas bordas, luz âmbar na capa, chapéu com fio âmbar, destaque do título em âmbar itálico (sem marca-texto), seção
+  como separador (número entre fios na linha do chapéu, título grande embaixo), cartões vazados que sobem no mouse,
+  números em monoespaçada, marcador em losango, código em janela e botões âmbar.
+- **Decisão:** no musgo o tom `accent` (o padrão da seção) é escuro com detalhe em âmbar; a página chapada de âmbar
+  destoava do original.
+- **Faixa que corre** (`ticker`, `src/build.js` + `base.css`): só na capa; automática nos temas com `ticker: true`
+  (por enquanto o musgo), com os títulos das seções (ou dos slides, se houver menos de 3 seções); `ticker: [..]` em
+  qualquer tema; `ticker: false` desliga. Separador desenhado em CSS (losango), parada sem movimento e na exportação.
+- **`motion: {type: console}`** (`src/motion.js`): janela com três bolinhas, legenda e contador; cada cena digita o
+  comando e revela a saída linha a linha, segura a leitura e passa para a próxima. Prompt, cursor e seta em CSS
+  (regra de não usar caractere como ícone). Parado, mostra a primeira cena completa.
+- **`ambient: rede`** (`runtime.js`, `mountAmbientNet`): nós à deriva que se ligam por proximidade, num canvas no
+  tamanho lógico do slide, nas cores do tom; anda só no slide atual, um quadro parado sem movimento/exportação. O tema
+  pode pôr na capa sozinho (`coverAmbient`, o musgo põe); `ambient: false` tira. Também no formulário do Studio.
+- Testes: `test/tema-musgo.test.js`. Referência atualizada (tema, `ticker`, `console`, `rede`).
+
+Fica para depois, se ela pedir: o efeito de "decodificar" a palavra em destaque do título da capa (trocar letras
+mexe na largura e na quebra das linhas; precisa de um jeito que não faça o título pular).
+
+## 11/10/2026 — Fases 0+1 do plano de melhorias (branch `arena/349f2d88-sagadeck`)
+
+Veio de uma avaliação do repositório pedida pela Narumi: o plano está em `docs/PLANO-MELHORIAS.md`
+(criado antes desta etapa; continua valendo para as fases 2+). Entrou o que é seguro e não muda
+comportamento do gerador:
+
+- **Suíte verde em qualquer máquina**: seis testes que exercitam o navegador por dentro (foco guiado,
+  `materializeImages` com `image_ref`, "ver o material", rótulos do redesenho) falhavam fora do CI, que
+  tem Chrome; agora pulam com o aviso dos testes de UI (`skipWithoutBrowser` em `test/helpers.js`).
+- **`engines` corrigido**: era `>=18` e não se cumpria (`pdfjs-dist` 6 pede 22.13+/24, `playwright-core`
+  pede 20+). Agora `>=22.13.0`, README e SKILL a par; CI testa Node 22 e 24 no Linux e no Windows.
+- **Audit de dependências na CI** (informativo) + **Dependabot semanal** agrupado; vulnerabilidade de
+  `image-size` (dependência morta declarada pelo pptxgenjs — o bundle nunca a importa) resolvida com
+  `overrides` para 2.0.4: audit em zero, suíte passando, nenhum código do gerador tocado.
+- `CHANGELOG.md` começado (o histórico fino continua sendo este diário), `.editorconfig`, e
+  `keywords`/`homepage`/`bugs` no `package.json`.
+- **Flake do CI no Windows consertado, e era mais sério do que parecia** ("mover (pasta inteira...), renomear
+  e duplicar"): a CI desta branch começou a falhar às vezes no Windows e o passo de falha do workflow (novo)
+  apontou o teste; o bloco de erro trouxe `exitCode 3221226505` (0xC0000409, morte nativa). Causa-raiz:
+  `fs.cpSync`/`fs.rmSync` recursivos têm código nativo que no Windows mata o processo ou copia/apaga NADA
+  com caminho acentuado (nodejs/node#54476, #61878 — "cópia", "Relatório" são a norma aqui). Só apareceu
+  porque a matrix nova testa Node 22 no Windows (main só testava 24, que passa por sorte de versão).
+  Conserto: `copyRetry`/`removeRetry` caminham na mão (readdir/copyFile/unlink/rmdir) e toleram o
+  travamento de um instante; testes de trava simulada (falham sem o conserto) e trava estrutural contra
+  `fs.cpSync`/`fs.rmSync` recursivo cru. Também protege a Studio de morte súbita ao duplicar/apagar deck.
+
+O que ficou para depois (mesmo plano, fases 2+): lint/format com adoção gradual, `@ts-check` nos módulos
+puros, extração dos prompts para arquivos, divisão do `app.js` do Studio, CI paralela por família de
+teste, redimensionador de imagem sem navegador.
+
+---
+
 ## Próximas frentes (levantadas em 08/10/2026, ainda não começadas)
 
 **Para quem pega isto numa sessão nova, sem a conversa de origem.** O projeto é o **sagadeck**:
 - Repositório GitHub `naruminho/sagadeck`, clonado em `C:\Users\narum\src\sagadeck`, branch `main`.
-- Publicado no npm como `sagadeck` (1.7.1: a IA diz por que o `ia.json` não serve e, no servidor, não mostra a configuração; o PyPI parou na 1.5.0).
+- Publicado no npm como `sagadeck` (1.8.0: mapas ao vivo, editor, dados e análises pela IA; o PyPI parou na 1.5.0).
 - Ferramenta Node (ESM) que transforma apresentações escritas em YAML em HTML/PPTX.
 - Tem um editor web, o Studio (`sagadeck studio`, porta 3517).
 - Tem uma IA embutida (provedor direto, configurado em `~/.sagadeck/ia.json` pela tela Configurar IA) que cria e edita decks, inclusive a partir de PDFs de
@@ -42,7 +284,7 @@ datadas abaixo). O resto fica para depois e só entra se for pedido. Antes de co
    ler o conteúdo força o download. Conferir se listar a biblioteca (`openLibrary`, `/api/library`) lê o YAML de
    cada deck; se lê, listar só pelo nome/metadado e abrir o conteúdo sob demanda.
 
-## Frente: mapa (planejada em 10/10/2026, em andamento)
+## Frente: mapa (planejada e publicada em 10/10/2026, versão 1.8.0)
 
 Pedido de Narumi, depois de muita conversa. **Leia antes de mexer.** Recurso de nicho, mas completo: mostrar e
 explicar algo geográfico (pontos de interesse de qualquer tipo, linhas, áreas), com a IA montando a partir de dados.
@@ -138,17 +380,250 @@ Não é um QGIS: análise pesada fica lá; aqui é apresentar bem, com contas si
    de altura zero). Testes: `test/map-analysis.test.js` e o ao vivo "qual loja fica mais perto de cada pedido" (pede
    `mais_proximo`).
 
-**Publicação 1.8.0 (retomada em 10/10):** versão preparada em `package.json` e lockfile, incluindo as cinco entregas
-e o Conheça o SagaDeck. O #178 já foi mergeado; falta concluir a CI e mergear o #179, conferir a CI da `main`, criar a
-release e atualizar a instalação local e o Oracle. No Oracle, o ambiente e os dois `mapa.json` já estão preparados
-com `OPENROUTESERVICE_API_KEY` (modo 600, dono de cada serviço); os serviços aguardam o código da release para
-reiniciar. Os quatro testes de mapa com o modelo real passaram novamente. Suíte completa da 1.8.0: 982 testes,
+**Publicação 1.8.0 (concluída em 10/10):** as cinco entregas e o Conheça o SagaDeck entraram na `main` pelos
+PRs #178 e #179, nessa ordem, ambos com CI verde no Ubuntu e no Windows. A CI da `main` (run 38055530334)
+também passou nas duas máquinas no commit `1b05819`. A release `v1.8.0` aponta para esse commit; o workflow
+`publish` (run 38057571606) publicou `sagadeck@1.8.0` no npm com provenance.
+
+O registro passou a informar `latest: 1.8.0`; esta máquina foi atualizada com `npm install -g sagadeck@1.8.0`.
+O Studio anterior da porta 3517 foi verificado e substituído pelo da versão nova, na mesma porta.
+Conferido em `http://127.0.0.1:3517/api/instance`: versão 1.8.0, biblioteca local; IA configurada,
+configuração do mapa editável e nenhum aviso de código antigo.
+
+No Oracle, por decisão de Narumi, **produção permanece na 1.7.1**, em `/opt/sagadeck`, porta 3517, sem reinício.
+O dev tem código próprio em `/opt/sagadeck-dev`, branch local `dev`, agora na tag `v1.8.0`; somente
+`sagadeck-dev.service` foi reiniciado, na porta 3518. Versão e configuração reservada conferidas pela API;
+IA configurada e arquivos do mapa servidos. A rota real pelo OpenRouteService já havia sido conferida nessa
+mesma versão pelo Claude. O ambiente e os dois `mapa.json` usam `OPENROUTESERVICE_API_KEY`, com modo 600 e
+dono de cada serviço. A separação do código do dev e o guia do mapa no servidor entraram pelos PRs #100 e #99
+do oráculo, respectivamente; não precisam ser refeitos.
+
+A CI intermediária da `main`, após o #178, teve um erro de recursos do navegador no Windows
+(`ERR_NO_BUFFER_SPACE`, no teste da faixa de ferramentas). O teste isolado local passou; a repetição dessa CI
+foi cancelada pela entrada do #179. As CIs posteriores do #179 e da `main` passaram completas nas duas máquinas,
+sem filtros de erro nem alterações para esconder a falha.
+
+Os quatro testes de mapa com o modelo real passaram novamente. Suíte completa da 1.8.0: 982 testes,
 956 passaram, 26 pulados, zero falhas; mapa/editor/exportação/leitores e regras: 22 testes direcionados passaram.
 Na revisão com cliques reais, a planilha cobria o mapa inteiro e a legenda interceptava um ponto no enquadramento
 automático. Corrigidos: a planilha fica ao lado do mapa (sugestões de gráfico recolhidas, com botão para abrir), a
 seleção funciona nas duas direções e o enquadramento reserva espaço para a legenda. O teste reproduziu a obstrução
 antes da correção e agora clica no ponto e na célula, sem disparar eventos sintéticos.
 
+## Assistente em destaque — 11/10/2026
+
+Pedido de Narumi: o chat não deve ficar perdido entre as propriedades. O acesso ao Assistente fica separado
+do grupo Formatar/Propriedades/Variáveis, por último à direita, com o nome sempre visível e aberto por padrão.
+Os controles de edição mantêm nomes acessíveis e dicas; esse arranjo preserva espaço para o slide. Quem fechou
+o painel continua sendo respeitado. O atalho flutuante aparece para reabrir o painel fechado; com ele aberto,
+o botão fixo já dá acesso ao Assistente, inclusive a avisos de novas respostas.
+
+Teste reproduziu a ordem antiga e passou com a nova: clique real nas quatro opções em temas claro/escuro e
+larguras 1280, 1024 e 390, sem corte do cabeçalho, nome do Assistente visível, seleção acessível correta,
+rascunho preservado, ordem de teclado, troca de slide mantendo o chat e apresentação salva intacta.
+Os testes do atalho e da faixa/painel também passaram, com zero erros de JavaScript.
+Conferência visual da interface real em tela grande e celular, nos dois temas: campo e envio acessíveis, sem erros de JavaScript. Suíte completa: 1001 testes, 975 passaram, 26 pulados, zero falhas e encerramento normal em 28 min 18 s. A CI Ubuntu/Windows precede o merge. Pasta oficial, branch `codex/assistente-visivel`.
+
+## Correções visuais da demo — 11/10/2026
+
+Pedidos de Narumi por capturas de tela: rótulos brancos cobriam o mapa; fórmula de Reynolds em cima do resultado;
+capital em reais aparecia como código LaTeX no exercício resolvido.
+
+- Rótulos do mapa têm fundo transparente, sem caixa ou sombra retangular, com contorno leve só no texto. O estilo
+  tem prioridade sobre o CSS do Leaflet, que carrega depois; o rótulo não intercepta cliques. Conferido em temas
+  claro e escuro, com os nomes preservados e clique real no ponto.
+- A calculadora reserva altura e respiro para a fração, sem sobrepor o resultado. Os nomes das faixas ficam visíveis
+  abaixo da régua, mantendo suas posições e as pontas arredondadas. No PPTX, controles deslizantes são capturados
+  com trilho e marcador: antes viravam retângulos brancos, sem representar o valor atual. A linha do resultado
+  também usa o tamanho do número: o PPTX antes reservava 9,6 pt para uma fonte de 38 pt, causando sobreposição.
+  O teste confere a altura exportada e preserva o resultado como texto editável; o ajuste de altura vale também
+  para o modo compacto. A suíte apontou um excesso de 3 px no exemplo com oito resultados; o modo compacto usa
+  uma linha do tamanho da fonte, sem a folga extra do modo comum, e o teste existente de controles/explicação
+  visíveis passou novamente.
+- A conferência da demo completa no PPTX revelou outra causa da régua desformatada: o exportador agrupava filhos
+  posicionados como texto de uma única caixa. Agora cada faixa e cada rótulo conserva sua própria posição e fundo;
+  as três cores e os dois nomes editáveis são conferidos no arquivo real, comparando com as posições do navegador.
+  O teste falhou com o agrupamento antigo e passou após a correção, junto com os demais testes de PowerPoint.
+- Unidades que já contêm `\$` ou `\%` não são escapadas duas vezes pelo motor. O exemplo de juros mantém seus
+  dados, etapas e resposta; a moeda compila em vez de aparecer como erro vermelho. Apresentações pessoais não foram
+  editadas.
+
+Regressões reproduzidas antes das correções: fundo opaco do rótulo, sobreposição/corte na calculadora, unidade já
+escapada inválida e ausência dos controles no PPTX. Testes direcionados passaram. Conferência visual dos modelos
+e PPTX real de três slides: zero erros de JavaScript, dois controles completos no arquivo. Suíte completa concluída:
+999 testes, 973 passaram, 26 pulados, zero falhas, encerramento normal em 21 min 13 s. A suíte final, incluindo
+a régua, concluiu com 1000 testes: 974 passaram, 26 pulados, zero falhas, encerramento normal em 22 min 11 s.
+A demo completa atualizada foi gerada pelo Studio em 61 s e baixada com 85 slides; conferidas as três faixas
+coloridas e os dois nomes em caixas editáveis separadas no PPTX. O PR #184 segue a CI Ubuntu/Windows antes do
+merge e atualização local/dev. A CI da main 38135963264 teve erro `ERR_NO_BUFFER_SPACE` do Chrome no Windows no teste
+da aula de APIs; o fluxo foi concluído, mas a exigência de zero erros apontou o erro de rede. O teste passou
+novamente nesta máquina e o job do Windows foi reexecutado, sem relaxar a verificação: concluiu verde em 29 min 51 s,
+junto com o Ubuntu verde em 23 min 55 s. Produção do Oracle fica na 1.7.1.
+
+## Exportação com progresso e download posterior — 10/10/2026
+
+Pedido: ao baixar a demo como PowerPoint, não ficava claro se estava gerando, tinha falhado ou já havia terminado.
+Na biblioteca, o aviso sumia após seis segundos; no editor, não havia progresso e o aviso prometia poucos segundos.
+
+Editor e biblioteca agora usam uma fila no servidor (`src/studio/export-jobs.js`, `/api/export/jobs`), acompanhada
+por `export-status.js`: preparação, slide atual/total, conclusão do arquivo, tempo decorrido, erro persistente e
+**Pronto para baixar**. Fechar/recarregar a aba não interrompe a geração. Ao voltar à biblioteca ou ao editor, a
+lista reaparece; a aba que pediu tenta iniciar o download quando pronto, e o botão permite baixar novamente.
+O arquivo fica fora da biblioteca/nuvem por até 24 h, enquanto o processo do Studio estiver ligado; mantêm-se
+as dez exportações recentes de cada pessoa. O status e o arquivo só são acessíveis à mesma pessoa no multiusuário.
+Uma geração por vez limita Chrome/memória; pedidos repetidos em andamento reaproveitam a geração existente.
+
+PPTX, PDF, roteiro, material de estudo e Baixar tudo informam etapas reais. Os links antigos e compartilhados
+continuam respondendo com o arquivo. Exportar um modelo em prévia não cria uma cópia na biblioteca. Se salvar
+mudanças falha, o editor interrompe a exportação e mantém a mensagem, em vez de gerar a versão antiga.
+Não foi acrescentado envio de email: a demo oficial de 85 slides terminou em 42 s nesta máquina (44 s até o
+download pelo clique na UI), com os 85 slides no PPTX, zero erros de JavaScript no Studio e nenhuma cópia criada.
+
+Regressão inicial: o pedido assíncrono retornava 404, sem fila nem arquivo recuperável. Testes verificam progresso,
+PPTX real com textos e notas, fechamento da aba e recuperação pela biblioteca, falha persistente, bloqueio após
+erro ao salvar, deduplicação, expiração e isolamento entre pessoas. Suíte completa concluída em 11/10:
+995 testes, 969 passaram, 26 pulados, zero falhas, encerramento normal. O PR #183 entrou na `main` em 11/10
+(`8ff7005`), depois da CI 38133476972 concluir verde no Ubuntu (23 min 59 s) e no Windows (32 min 34 s).
+O Oracle dev foi atualizado para esse commit; geração assíncrona e download real de 17 slides conferidos em 7,5 s.
+Produção do Oracle permanece na 1.7.1, sem atualização nem reinício.
+Uma resposta atrasada de uma consulta anterior podia apagar o acompanhamento de um pedido novo e impedir o download
+automático: reproduzido com a resposta retida, agora só expiram gerações que a consulta já conhecia. O painel fica
+abaixo das janelas de configuração; recolhido no editor, sai da área de digitação do chat. Testes verificam os
+cliques nas janelas e o download real depois da resposta atrasada. A versão antiga também criava uma cópia pessoal
+ao exportar um modelo em prévia: reproduzido usando o app.js da main, e a regressão confere o PPTX e a biblioteca.
+
+## Fundo do mapa sem a falsa costa — retomada em 10/10/2026
+
+Pedido: esconder a linha marítima do OpenStreetMap que parecia um litoral afastado das áreas. Os modos claro e
+escuro usam agora os estilos Positron e Dark do OpenFreeMap, sem chave; o estilo exclui fronteiras marítimas e
+preserva divisas terrestres, rios e o litoral verdadeiro. O mar fica azul suave no claro e azul profundo no escuro.
+O modo ruas e fundos raster personalizados continuam disponíveis. Configurar mapa ganhou os dois fundos; apagar
+o endereço restaura o padrão (antes, a gravação parcial conservava o endereço antigo).
+
+MapLibre e a ligação Leaflet vão no pacote, com as licenças; no HTML exportado, entram embutidos apenas se houver
+mapa vetorial e só carregam no primeiro slide que os usa. O worker é clássico para abrir também por file://. Só o
+slide atual conserva o contexto gráfico; sair e voltar preserva a câmera e a legenda. A exportação mantém o limite
+de espera de 8 s também ao voltar a um mapa cujo fundo não responde. Recusa no estilo, nos
+metadados ou no primeiro tile desliga o fundo na sessão sem insistir, mantendo as camadas e o Tentar de novo.
+
+Conferido nos dois fundos reais no litoral do Rio: áreas sobre a costa, nenhuma linha paralela no mar, nenhum erro
+de JavaScript. Regressões reproduziram a falha do worker e o contexto que continuava ativo fora do slide antes das
+correções. Testes cobrem pixels de terra/mar, divisa terrestre versus marítima, exportação por arquivo, câmera,
+retomada, carregamento local no Studio e recusa com uma tentativa. Esta retomada preserva os commits anteriores de
+tour, demos oficiais, editor de mapa, calendário e retirada de tipografia cinética e texto no cenário.
+Na revisão da compatibilidade, um slide antigo com subtítulo e legenda perdia a legenda na conversão. A regressão
+reproduziu a perda; agora os dois textos continuam juntos, com e sem imagem.
+Achado na suíte: o teste da categoria Aula consultava a galeria antes da resposta de prévias. A resposta atrasada
+reproduziu a falha; o teste agora aguarda os cartões e confere que a categoria escolhida durante o carregamento
+continua valendo. Nenhuma exceção de JavaScript foi ignorada.
+Outro achado na suíte: o encerramento das capturas iniciava `browser.close()` sem aguardá-lo. O evento de
+desconexão do navegador antigo podia apagar a referência de um novo, deixando um Chrome aberto e impedindo a suíte
+de terminar. Teste com fechamento atrasado reproduziu o problema; agora o encerramento espera e cada desconexão
+só limpa sua própria referência.
+
+Validação completa desta retomada: `npm test`, 988 testes, 962 passaram, 26 pulados, zero falhas; o processo
+encerrou normalmente. A revisão do pacote confirmou os renderizadores e suas licenças no npm. Entrega por PR
+com CI verde no Ubuntu e Windows; atualização da porta local 3517 e somente do Oracle dev (3518). O serviço
+estável do Oracle permanece na 1.7.1, conforme pedido de Narumi. PR #182 mergeado com a CI concluída verde nos
+dois sistemas; dev atualizado para a main `df5d42d`, produção conferida na 1.7.1 com o mesmo processo. As quatro
+worktrees antigas foram removidas depois de conferir os commits incorporados e as duplicatas locais; a pasta
+oficial e seu node_modules foram preservados.
+
+## Texto no cenário sai; fundo claro do mapa com o mar visível — 10/10/2026
+
+Narumi: "pode excluir também o texto no cenário. Ele é muito limitado e teoricamente dá para fazer coisas melhores
+pedindo pra IA desenhar". Saiu do motor (`SCENES`, layout `scenography`), do CSS, do Studio (galeria, formulário),
+da vitrine (a demo `templates/cenario`), do tour, da referência e do SKILL; o exemplo de matemática perdeu os três
+slides de cenário. Deck antigo: com imagem, vira imagem de página inteira com o título por cima; sem imagem, frase
+em destaque (`src/fiscal/normalize.js`; `engine.test.js`).
+
+E "a área ainda não está em cima dos estados": os dados estavam certos (pontos do litoral a até 2,6 km da borda); no
+fundo claro, o filtro cinza deixava terra e mar da mesma cor e a fronteira marítima que o OpenStreetMap desenha 12
+milhas mar adentro parecia o litoral. O filtro agora guarda um azul leve no mar (`base.css`; `map.test.js`).
+
+## Mapa: escala única, contornos detalhados e pontos mais bonitos — 10/10/2026
+
+Narumi, no slide dos estados: "isso não parece certo". Cada camada tinha a própria escala (a Bahia, 2.900 MW, saía
+tão forte quanto Minas, 5.100): camadas da mesma medida (a mesma coluna e unidade) agora dividem a escala. Os
+contornos embutidos vinham da malha mínima do IBGE simplificada a 4 km (o DF era um octógono; Rio e Vitória na
+borda): agora malha intermediária a ~650 m e países do Natural Earth 1:50m (`scripts/vendor-map.mjs`; o arquivo foi
+de 181 KB para 690 KB, e no HTML só entram os estados usados). E "os pontos estão com círculos grandes e feios": o
+estilo das linhas e áreas era aplicado também aos pontos (borda grossa colorida); agora ponto é pequeno, na cor, com
+anel branco e sombra, bolha é translúcida com contorno da mesma cor, e o rótulo é uma pílula menor. Testes:
+`map.test.js` (escala dividida, contornos detalhados com a área do IBGE, desenho dos pontos).
+
+## Demos de mapa com cada tipo de objeto e onde se edita — 10/10/2026
+
+Narumi: "ainda não entendi onde vão os menus e propriedades… mostre não só com pontos, mas com cada tipo de objeto".
+A seção Mapas do Conheça o SagaDeck agora tem: pontos por categoria (o exemplo do layout), bolhas pelo tamanho de
+uma coluna, regiões por valor, linhas e áreas, rota pelas ruas e área alcançável (calculadas uma vez pelo
+OpenRouteService em 10/10/2026 e gravadas no tour, com a fonte na legenda), raio em volta de pontos e faixa em volta
+de uma linha (calculados pelo sagadeck). E dois slides de foco guiado com capturas do Studio: onde fica o Editar mapa
+e a tela do mapa (camadas, ferramentas, propriedades, dica, Concluir). As capturas saem de
+`scripts/capturas-tour.mjs` (refazer quando a tela mudar; precisa de internet). A cópia do tour leva as capturas
+(`demoAssets`). Achado no caminho: a faixa em volta de uma linha (também a que a IA grava) aparecia como uma pilha de
+círculos com contorno e com buracos; agora vai marcada (`_faixa`) e sai como uma mancha só (`map.test.js`,
+`map-analysis.test.js`).
+
+## Calendário com visões e a saída da tipografia cinética — 10/10/2026
+
+Narumi: "eu odeio muito a tipografia cinética… se ele não consegue ser melhor, remova completamente". Saiu do motor,
+do runtime, do Studio (galeria, formulário, troca de layout), do tour e da referência. Deck antigo que a usava abre
+como frase em destaque com as mesmas frases, uma por clique (`src/fiscal/normalize.js`; `engine.test.js`).
+
+Sobre o calendário ("ficou excelente… mas se tiverem muitos eventos no mesmo mês vai encher de linhas e extrapolar a
+altura"): o cartão cortava os eventos sem avisar. Agora `view` tem `meses` (o de antes), `mes` (um mês grande de
+parede, os eventos escritos nos dias, "+ N mais" quando o dia lota), `semana` (uma coluna por dia com horário; fim
+de semana vazio some) e `lista` (agenda em colunas, a letra diminui com a quantidade). Sem `view`, escolhe pelo que
+cabe, com a altura medida no navegador (mês de 6 semanas conta). `month`/`week` escolhem o mês e a semana; `time` ou
+"2026-11-16 09:00" dão a hora. No Studio, o formulário tem Visão e o botão **Um slide por mês** (cada slide no mês
+grande, com os eventos dele; o "sem data" fica no primeiro). Testes: `calendar.test.js` (as visões, a escolha e, no
+navegador, de 1 a 8 meses com até 16 eventos: ou cabe ou avisa) e `calendar-studio.test.js` (visão e botão, no deck
+salvo). O calendário ganhou limite de 240 palavras (é denso por natureza).
+
+## Editar mapa: uma tela própria — 10/10/2026
+
+Narumi, testando o mapa da demo oficial: "não consigo clicar pra editar, não sei como edita, não sei se tem uma tela
+diferente", e o ponto novo não gravava. O editor antigo era uma barra por cima do slide escalado (cobria o título), só
+editava planilha e GeoJSON de arquivo (a demo tem tudo escrito no slide) e não tinha propriedades. Agora **Editar mapa**
+(ou dois cliques no mapa) abre uma tela só do mapa (`map-editor.js`, classes `mpe-`; `.mx` já era de um layout):
+camadas à esquerda (tipo, nome, quantos itens, olho), o mapa grande com as ferramentas e a dica do que fazer, e à
+direita as propriedades do selecionado (campos com o que cada um faz no mapa, posição, comprimento ou área, excluir) ou
+da camada e do mapa. Edita pontos e formas escritos no slide e em arquivo; GPX e KML só se leem. Corrigidos no caminho:
+gravar arquivo do projeto em prévia de modelo respondia 409 (agora cria a cópia, `server.js`), planilha nova numa pasta
+que não existia falhava (`writeSheet`), pontos ficavam debaixo de áreas e raios que entravam depois (na apresentação
+também: o clique abria o cartão do raio), e desmontar o mapa no meio de uma animação de zoom dava erro. Testes:
+`map-editor.test.js` (os dois caminhos, inclusive a demo em prévia), `project.test.js` (409), `map.test.js` (pontos por
+cima). Achado na suíte: a faixa "Configure a IA" caía na coluna da lateral e espremia a biblioteca (corrigido, com
+teste em `library-ui.test.js`).
+
+## Conheça o SagaDeck com a demonstração dos mapas e a pasta Demos oficiais — 10/10/2026
+
+Narumi esperava achar a apresentação junto das dela, numa pasta própria e só leitura. Agora a lateral da biblioteca
+tem **Demos oficiais** (cadeado; `data-view="oficiais"` em `library.js`) com o Conheça o SagaDeck em primeiro e as
+demos de recursos da vitrine (as mesmas chaves da `GALLERY`, tipo `recurso`), com a capa de verdade e só Apresentar e
+Abrir: sem menu de mover, renomear ou excluir, sem arrastar, sem "Nova" dentro. O Conheça aparece também como o
+primeiro cartão de Recentes e Todas, e debaixo da mensagem de biblioteca vazia. Abrem em prévia (`editor?model=…`).
+Defeito achado pelo teste novo: **Apresentar uma prévia criava uma cópia** na biblioteca (o Apresentar mandava o deck
+ao servidor, e na prévia isso conta como primeira mudança); agora, em prévia, ele não envia (o servidor já tem o mesmo
+deck). Teste: `library-ui.test.js` (pasta, cartões, só leitura, abrir e apresentar sem criar arquivo).
+
+**Exemplos sem nada da empresa de quem desenvolve.** Narumi viu o tour falar da Bridge e do processo de experimento e
+projeto (DEV, HOM, PROD, Key Vault): vinha dos exemplos dos layouts (`layout-samples.js`) e da referência que ensina a
+IA. Trocados por assuntos variados (viagem, loja, clínica, inscrições, reciclagem) nos exemplos, na referência, nos
+modelos, nos textos de exemplo da interface e nos testes. Trava: `engine.test.js` ("sem nada da empresa de quem
+desenvolve") falha se nomes de sistemas, processos internos ou produtos do banco voltarem a `src`, `templates`,
+REFERENCIA, README ou SKILL. Os ambientes dev/hom/prod da API são recurso genérico e ficam.
+
+Pedido de Narumi: uma apresentação bem completa do próprio sagadeck, incluindo a demo de mapas. O tour ganhou a seção
+**Mapas** (`mapDemos` em `src/studio/tour.js`, slides marcados `demo: mapa`): o exemplo do layout, estados pintados por
+valor com uma região por clique e a câmera indo até ela, linhas e áreas (GeoJSON escrito no slide, que o motor passou a
+aceitar), cobertura com raios de 1 km calculados pelo código (`circle` de `src/map-analysis.js`) e dois quadros com o
+que a IA e o Studio fazem no mapa. Os extras ganharam pesquisa na web, versões e material de consulta. Valores
+ilustrativos e traçados aproximados dizem isso na tela. Testes: `engine.test.js` (seção de mapas e o tour inteiro sem
+avisos) e `map.test.js` (GeoJSON no slide). Achado de passagem, tarefa à parte: o Studio acusa "texto pequeno" em
+todo cartão (mede a letra da caixa, não a do texto).
+
 ## Conheça o SagaDeck — 10/10/2026
 
 Pergunta de Narumi: a pessoa nem sabe o que dá para gerar. Agora a biblioteca tem, na lateral, **Conheça o