sagadeck 1.6.0 → 1.7.0

package/README.md

@@ -24,11 +24,14 @@ Requer **Node.js 18+** e **Chrome ou Edge** instalados (o PDF, o PNG e as confer
 ```bash
 sagadeck studio
 ```
-e abra **http://127.0.0.1:3517** no navegador. **Essa é a página do sagadeck**: a biblioteca das suas
-apresentações, o editor (estilo PowerPoint) e o chat com a IA. Não há outra interface para abrir nem para criar.
-
-Para usar a IA (gerar apresentações, conversar com o chat), clique em **Configurar IA** no alto da biblioteca (ou
-em **IA desligada**, no editor), escolha o provedor, cole a chave, clique em **Testar** e **Salvar**. Detalhes em
+O navegador abre sozinho em **http://127.0.0.1:3517** (se não abrir, abra esse endereço). **Essa é a página do
+sagadeck**: a biblioteca das suas apresentações, o editor (estilo PowerPoint) e o chat com a IA. Não há outra interface
+para abrir nem para criar. Deixe o terminal aberto enquanto usa; `--sem-navegador` não abre o navegador.
+
+Para usar a IA (gerar apresentações, conversar com o chat), clique em **Configurar IA** (a biblioteca mostra uma faixa
+enquanto ela não está configurada). **Usar a recomendação** preenche o OpenRouter com modelos que funcionam; cole a
+chave, clique em **Testar** e **Salvar**. Se nem a recomendação responder, o problema é a rede ou a chave. Depois,
+troque pelo provedor e pelos modelos que quiser. Detalhes em
 [IA de verdade](#ia-de-verdade-llm).
 
 ## Como usar
@@ -252,8 +255,11 @@ Para ver funcionando sem configurar nada:
   O painel **Formatar** edita o endereço, o corpo em JSON, o modo (síncrono, polling, streaming, tempo real)
   e o que guardar para os próximos slides.
 - **Inserir → Ambientes:** onde ficam os endereços (`{{base}}`), tokens e segredos do *seu* serviço
-  (dev, hom, prod). É gravado em `~/.sagadeck/ambientes.yaml`, na sua máquina, nunca no deck. O selo no
-  slide (DEV, HOM, ENSAIO…) troca o ambiente na hora.
+  (dev, hom, prod). Preenche-se por campos: endereço base, variáveis, segredos (guardados cifrados) e a
+  autenticação (nenhuma, token fixo ou token que expira), com **Testar**; quem prefere edita o YAML na aba
+  "Como texto". É gravado em `~/.sagadeck/ambientes.yaml`, na sua máquina, nunca no deck. Sem ambiente seu, o
+  **ENSAIO** (API de mentira) já funciona. O selo no slide (DEV, HOM, ENSAIO…) troca o ambiente na hora. No
+  servidor multiusuário o botão não aparece (lá os slides de API não executam).
 
 Executar só funciona no Studio local; no HTML exportado e no modo multiusuário, o slide mostra a última
 resposta gravada. Todos os campos estão na [referência](docs/REFERENCIA.md#slide-api-requisição-ao-vivo).

package/SKILL.md

@@ -12,12 +12,13 @@ O sagadeck gera apresentações profissionais a partir de um arquivo YAML, ofere
 Quando a pessoa pede para instalar o sagadeck e deixar pronto:
 
 1. `npm install -g sagadeck` (Node 18+; não precisa de Python).
-2. `sagadeck studio` e diga para ela abrir **http://127.0.0.1:3517** (a primeira linha que o comando escreve é
-   esse endereço). **O Studio é a interface do sagadeck**: biblioteca, editor e chat com IA.
+2. `sagadeck studio`: o navegador abre sozinho em **http://127.0.0.1:3517** (é também a primeira linha que o
+   comando escreve; `--sem-navegador` não abre). **O Studio é a interface do sagadeck**: biblioteca, editor e chat com
+   IA. O terminal fica aberto enquanto ela usa.
 3. **Nunca crie uma página, um servidor ou uma interface própria** para o sagadeck, nem "suba as APIs" à mão: tudo
    que a pessoa precisa está no Studio.
 4. Para a IA, mostre onde configurar: **Configurar IA** no alto da biblioteca (ou **IA desligada** no editor):
-   provedor, chave, Testar e Salvar. A configuração fica em `~/.sagadeck/ia.json`; nunca grave a chave no código nem
+   **Usar a recomendação** (OpenRouter com modelos que funcionam), a chave, Testar e Salvar. A configuração fica em `~/.sagadeck/ia.json`; nunca grave a chave no código nem
    na pasta das apresentações.
 5. As apresentações moram na biblioteca (`SAGADECK_HOME`, senão Documentos\sagadeck no Windows e `~/sagadeck` fora
    dele). Não crie decks em outra pasta.

package/bin/sagadeck.js

@@ -40,6 +40,12 @@ for (let i = 0; i < rawRest.length; i++) {
 
 const HELP = `sagadeck — YAML -> apresentação (HTML animado + PowerPoint editável + PDF + roteiro)
 
+  Para começar:  sagadeck studio
+                 abre o Studio no navegador (biblioteca, editor e chat com IA; http://127.0.0.1:3517).
+                 Deixe o terminal aberto enquanto usa. A IA se configura lá, em Configurar IA.
+
+  Todos os comandos:
+
   sagadeck new <nome> --prompt "briefing" [--slides=10] [--duration=20] [--theme=x]  deck inteiro escrito pelo LLM
                                    (pesquisa na web quando o pedido precisa de informação recente ou de um artigo; --sem-pesquisa desliga)
                                    (--duration dispensa --slides: ~1 slide a cada 1,5 min)
@@ -56,7 +62,7 @@ const HELP = `sagadeck — YAML -> apresentação (HTML animado + PowerPoint edi
   sagadeck roteiro <deck.yaml>                 gera <deck> - roteiro.pdf (miniaturas + notas + tempos)
   sagadeck estudo <deck.yaml> [--html]         gera <deck> - material de estudo.pdf (cada slide + texto de consulta)
   sagadeck all <deck.yaml>                     build + check + pptx + pdf + roteiro
-  sagadeck studio [deck.yaml|x.sagadeck] [--port=3517] [--library=PASTA]  sem arquivo: abre a biblioteca; já aberto: usa o aberto
+  sagadeck studio [deck.yaml|x.sagadeck] [--port=3517] [--library=PASTA] [--sem-navegador]  sem arquivo: abre a biblioteca (no navegador); já aberto: usa o aberto
                                    (PASTA padrão: SAGADECK_HOME, senão Documentossagadeck no Windows, ~/sagadeck fora dele); com arquivo: abre o editor dele
                                    --host=0.0.0.0 abre para a rede (padrão: só esta máquina)
                                    --multiuser: uma biblioteca por usuário, atrás de um proxy que envia X-Sagadeck-User
@@ -387,6 +393,7 @@ async function main() {
           else { console.error(`O Studio já está aberto em http://${shownHost}:${port} com a biblioteca ${library}, e este deck está fora dela. Use --port=OUTRA para abri-lo à parte.`); process.exit(1); }
         }
         console.log(`✓ O SagaDeck Studio ${found.version} já está aberto (processo ${found.pid}): ${url}`);
+        { const B = await import("../src/studio/open-browser.js"); if (B.shouldOpenBrowser({ flags, multiuser })) B.openBrowser(url); }
         break;
       }
       if (decision.action === "conflict") {
@@ -403,6 +410,9 @@ async function main() {
       server.listen(port, host, async () => {
         const { studioBanner } = await import("../src/studio/banner.js");
         for (const line of studioBanner({ version: VERSION, url: `http://${shownHost}:${port}/`, library, ai: (await import("../src/ai/llm.js")).llmConfig(), multiuser, usersDir: path.join(library, "usuarios"), isLibrary: !deckFile })) console.log(line);
+        // depois do endereço (a primeira linha é sempre ele): abre o navegador na página
+        const B = await import("../src/studio/open-browser.js");
+        if (B.shouldOpenBrowser({ flags, multiuser }) && B.openBrowser(`http://${shownHost}:${port}/`)) console.log("  (abrindo no navegador; --sem-navegador desliga)");
       });
       break;
     }

package/docs/ANDAMENTO.md

@@ -12,7 +12,7 @@ começar. Trabalho em curso vai para o GitHub (commit + push) a cada etapa, nunc
 
 **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.6.0: IA embutida, só npm; o PyPI parou na 1.5.0).
+- Publicado no npm como `sagadeck` (1.7.0: primeiro uso guiado, Ambientes por campos; 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 (via modelrelay em `http://127.0.0.1:8765/v1`) que cria e edita decks, inclusive a partir de PDFs de
@@ -108,6 +108,51 @@ os achados para os slides").
   `missed`, elas entram no inventário com a caixa exata do texto e passam pela mesma releitura do recorte
   (`transcribeEquation`) que escreve o LaTeX das outras. Saiu da lista.
 
+## Primeiro uso: navegador abre sozinho, "Para começar" e a recomendação de IA — 09/10/2026
+
+Pergunta de Narumi: quem instala pelo npm sabe pôr no ar, sabe a URL, precisa editar arquivo para a IA? Antes: um
+comando (`sagadeck studio`), mas o navegador não abria, o `sagadeck` sozinho mostrava o `studio` como 19º item de uma
+lista longa, e os campos de modelo do Configurar IA vinham vazios (ninguém sabe o nome exato de um modelo).
+
+- `sagadeck studio` **abre o navegador** na página (`src/studio/open-browser.js`), inclusive quando já está aberto;
+  só para quem está no terminal: nunca em serviço/teste (sem TTY), CI, multiusuário, Linux sem tela ou
+  `--sem-navegador` / `SAGADECK_NO_BROWSER=1`. A primeira linha continua sendo o endereço.
+- `sagadeck` sozinho começa com **"Para começar: sagadeck studio"** (o que faz, o endereço, deixar o terminal aberto).
+- **Configurar IA** com a recomendação (`RECOMMENDED` em `src/ai/ia-config.js`: OpenRouter, DeepSeek para texto e
+  visão, Gemini para imagem, `:online` para busca) e **Usar a recomendação**, que preenche provedor e modelos. Ela é
+  também o teste da instalação: se nem com ela a IA responde, o problema é rede ou chave. Os campos trazem exemplos e
+  a tela diz que imagem e busca dependem do provedor. Sem listar os modelos do provedor (decisão: endereço próprio ou
+  de empresa pode não ter a lista, ou ser bloqueado).
+- **Faixa "Configure a IA"** na biblioteca enquanto não está configurada (só onde se pode configurar; some ao salvar).
+- Testes: `test/instance.test.js` (quando abre o navegador e o comando de cada sistema; `sagadeck` sozinho),
+  `test/library-ui.test.js` (faixa, recomendação preenche, salvar some a faixa).
+- **Testes isolados de verdade**: a suíte completa falhou só nesta máquina num teste da lixeira, que leu as
+  Preferências reais (lixeira em 1 dia). 41 arquivos de teste não carregavam o isolamento (só os que importavam o
+  `helpers.js`). Agora `test/isolate.js` (biblioteca, ambientes, Preferências, IA e registro de comandos em pasta
+  temporária) é carregado antes de tudo pelo `npm test` (`--import`) e importado por todo arquivo de teste;
+  `guards.test.js` reprova arquivo de teste que não carregue.
+- A avaliação ao vivo (`test/bench-live.test.js`) não fechava o navegador da revisão dos slides: o processo ficava
+  pendurado (dias). Fecha no fim; `guards.test.js` exige isso de todo teste que gera pelo caminho do Studio.
+## Ambientes por campos e sem o botão no servidor — 09/10/2026
+
+Pergunta de Narumi: quem instala do zero sabe preencher o `ambientes.yaml` (slides de API)? O lugar já era automático
+(o Studio grava em `~/.sagadeck/ambientes.yaml`), mas preencher era editar YAML numa caixa de texto. E no servidor
+(multiusuário) o botão abria a janela com "O serviço recusou o acesso…", parecendo defeito.
+
+- **Por campos** (`src/studio/public/api-envs-form.js`, aba padrão): um cartão por ambiente com endereço base,
+  variáveis, segredos (digitado vai cifrado; em branco mantém; ou o nome de uma variável de ambiente), autenticação
+  (nenhuma; token fixo, que vira `Authorization: Bearer {{secret.token}}`; token que expira, client credentials) e
+  **Testar** (salva, chama o endereço base e pede o token). Sem ambiente próprio, a tela explica que o ENSAIO já
+  funciona. A aba **Como texto** é o editor de YAML de antes.
+- Motor (`src/api-client.js`): `formState`/`saveForm` (o mesmo arquivo, preservando comentários e o que o
+  formulário não conhece: `ca`, outros cabeçalhos), `check` (o Testar), cabeçalhos do ambiente com `{{secret.…}}` e
+  client secret do token cifrado. Rotas `/api/http/ambientes/form` e `/api/http/ambientes/testar`.
+- **No servidor o botão some** (o slide de API não executa lá; `/api/http/state` diz `live: false`).
+- Testes: `test/api-client.test.js` (salvar e ler de volta sem o valor dos segredos, comentários e `ca` preservados,
+  token fixo no pedido, segredo mantido em branco, Testar), `test/studio.test.js` (instalação do zero pela tela, até o
+  Testar confirmar com o token chegando na API), `test/studio-scripts.test.js` (botão some no multiusuário; falhava
+  sem o módulo).
+
 ## IA embutida, só npm e o Studio como a página do sagadeck — 09/10/2026
 
 Pedido de Narumi, depois de um agente (Copilot) instalar o sagadeck, abrir a página do modelrelay e, sem achar a

package/docs/REFERENCIA.md

@@ -282,7 +282,9 @@ No Studio, a aba **Variáveis** mostra o ambiente atual em uma tabela **Nome / V
 normais ali; nomes e valores são salvos no arquivo de ambientes, nunca no deck. Arraste um nome da tabela
 para um campo do slide para inserir `{{nome}}`. Segredos são listados pelo nome, mas seu valor nunca aparece.
 Os campos `save` do deck também aparecem com sua origem e disponibilidade.
-O editor de ambientes valida o YAML antes de habilitar **Salvar** e preserva a versão anterior em `ambientes.yaml.bak`.
+O editor de ambientes abre **por campos** (endereço base, variáveis, segredos, autenticação: nenhuma, token fixo
+`Authorization: Bearer {{secret.token}}` ou token que expira; **Testar** chama o endereço base e pede o token). A aba
+**Como texto** valida o YAML antes de habilitar **Salvar**. Os dois preservam a versão anterior em `ambientes.yaml.bak`.
 O botão **Variáveis** (na barra do slide) é o inspect/watch da apresentação, tudo num lugar só:
 - **Ambiente**: as variáveis (criar, editar, apagar) e as **protegidas** (marque "protegida" ao criar): na tela só o nome
   e ••••; o olhinho mostra o valor por 15 segundos. Nos slides e no código gerado aparece o nome (`{{secret.chave}}`),
@@ -334,8 +336,9 @@ texto) para o modo sem Studio.
 
 Endereços, credenciais e segredos ficam **na máquina**, nunca no deck (o deck pode ir para o GitHub).
 Outro lugar: variável `SAGADECK_AMBIENTES`. O selo no slide (DEV, HOM…) troca o ambiente. No Studio,
-**Inserir → Ambientes** mostra o arquivo (ou um modelo comentado, se ele ainda não existe), confere o YAML
-antes de gravar e troca o ambiente em uso.
+**Inserir → Ambientes** preenche o arquivo por campos (ou mostra o YAML na aba Como texto, com um modelo comentado
+se ele ainda não existe), confere antes de gravar e troca o ambiente em uso. Os cabeçalhos do ambiente (`headers`)
+aceitam `{{secret.nome}}`; o client secret do token pode ficar cifrado (`client_secret: "dpapi:…"` no Windows).
 
 ```yaml
 current: hom

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sagadeck",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Gerador de apresentações: YAML -> HTML animado + PowerPoint editável, com temas e figuras geradas na hora.",
   "type": "module",
   "bin": {
@@ -39,9 +39,9 @@
     "dev": "node bin/sagadeck.js studio",
     "build:code-lab": "node scripts/bundle-code-lab.mjs",
     "test:live": "node tools/test-live.mjs",
-    "test": "node --test --test-concurrency=1 \"test/*.test.js\"",
-    "test:unit": "node --test test/engine.test.js",
-    "test:ui": "node --test --test-concurrency=1 test/runtime.test.js test/studio.test.js"
+    "test": "node --import ./test/isolate.js --test --test-concurrency=1 \"test/*.test.js\"",
+    "test:unit": "node --import ./test/isolate.js --test test/engine.test.js",
+    "test:ui": "node --import ./test/isolate.js --test --test-concurrency=1 test/runtime.test.js test/studio.test.js"
   },
   "repository": {
     "type": "git",

package/src/ai/ia-config.js

@@ -13,6 +13,12 @@ export const PROVIDERS = {
   openrouter: { label: "OpenRouter", url: "https://openrouter.ai/api/v1", keyEnv: "OPENROUTER_API_KEY" },
   openai: { label: "OpenAI", url: "https://api.openai.com/v1", keyEnv: "OPENAI_API_KEY" },
 };
+// Recomendação para começar, mostrada na tela Configurar IA. Serve também de teste da instalação: se nem com ela a IA
+// responde, o problema é o ambiente (rede, chave), não o modelo escolhido. Depois, cada um põe o modelo que quiser.
+export const RECOMMENDED = {
+  provider: "openrouter",
+  models: { text: "deepseek/deepseek-v4.1-flash", vision: "deepseek/deepseek-v4.1-flash", image: "google/gemini-3.1-flash-image", search: "deepseek/deepseek-v4.1-flash:online" },
+};
 // os papéis que o sagadeck usa; cada um aponta para um modelo do provedor
 export const ROLES = ["text", "vision", "image", "search"];
 

package/src/api-client.js

@@ -25,6 +25,7 @@ import { connectWs } from "./ws.js";
 import { protect, unprotect, unprotectAll, PROTECTION } from "./protect.js";
 
 const C = globalThis.SagadeckApiCore;
+const BEARER = "Bearer {{secret.token}}"; // o "token fixo" do formulário: cabeçalho em todo pedido do ambiente
 
 // As variáveis e segredos dos slides de API moram FORA das apresentações: ~/.sagadeck/ambientes.yaml (no Windows,
 // C:\Users\<você>\.sagadeck\ambientes.yaml) ou SAGADECK_AMBIENTES. Mandar um deck para alguém nunca leva segredo
@@ -128,7 +129,7 @@ export class ApiEnvironments {
     catch (e) { throw new ApiError(`${this.file}: YAML inválido: ${e.message}`, "config"); }
     const envs = data.environments && typeof data.environments === "object" ? data.environments : {};
     // segredos cifrados (dpapi:…): decifra todos de uma vez (um PowerShell só)
-    try { unprotectAll(Object.values(envs).flatMap((e) => Object.values((e && e.secrets) || {}))); }
+    try { unprotectAll(Object.values(envs).flatMap((e) => [...Object.values((e && e.secrets) || {}), e?.token?.client_secret].filter((v) => typeof v === "string"))); }
     catch (e) { throw new ApiError(`${this.file}: ${e.message}`, "config"); }
     return { current: data.current || null, environments: envs };
   }
@@ -236,6 +237,106 @@ export class ApiEnvironments {
     return this.state();
   }
 
+  // ---- tela Ambientes por campos (src/studio/public/api-envs-form.js) ----------------------------------------------
+  // O mesmo arquivo, visto como formulário: endereço base, variáveis, segredos (só o nome e de onde vêm; o valor nunca
+  // sai) e a autenticação (nenhuma, token fixo ou token que expira). O que o formulário não conhece (ca, insecure,
+  // outros cabeçalhos) fica no arquivo como estava.
+  formState() {
+    const raw = fs.existsSync(this.file) ? (YAML.parse(fs.readFileSync(this.file, "utf8")) || {}) : {};
+    const envs = raw.environments && typeof raw.environments === "object" ? raw.environments : {};
+    return {
+      file: this.file, exists: fs.existsSync(this.file), protection: PROTECTION, current: raw.current || null,
+      builtin: Object.keys(this.builtin),
+      envs: Object.entries(envs).map(([name, e = {}]) => {
+        const bearer = e.headers?.Authorization === BEARER;
+        const auth = e.token?.url ? { type: "token", url: e.token.url, client_id: e.token.client_id || "", field: e.token.field || "", secretEnv: e.token.client_secret_env || "", secretSet: e.token.client_secret != null }
+          : bearer ? { type: "bearer", secretEnv: typeof e.secrets?.token === "object" ? e.secrets.token.env || "" : "", secretSet: typeof e.secrets?.token === "string" }
+          : { type: "nenhuma" };
+        const otherHeaders = Object.keys(e.headers || {}).filter((h) => !(bearer && h === "Authorization"));
+        return {
+          name, base: e.vars?.base != null ? String(e.vars.base) : "",
+          vars: Object.entries(e.vars || {}).filter(([k]) => k !== "base").map(([k, v]) => ({ name: k, value: String(v) })),
+          secrets: Object.entries(e.secrets || {}).filter(([k]) => !(bearer && k === "token")).map(([k, v]) => ({ name: k, env: typeof v === "object" && v ? v.env || "" : "", set: typeof v === "string" })),
+          auth, advanced: !!(e.ca || e.insecure || otherHeaders.length),
+        };
+      }),
+    };
+  }
+
+  saveForm(list, { current } = {}) {
+    if (!Array.isArray(list)) throw new ApiError("Mande a lista de ambientes.", "config");
+    const NAME = /^[A-Za-z0-9_-]{1,40}$/, VAR = /^[A-Za-z_][A-Za-z0-9_]*$/;
+    const seen = new Set();
+    for (const f of list) {
+      if (!NAME.test(String(f?.name || ""))) throw new ApiError(`Nome de ambiente inválido: "${f?.name || ""}". Use letras, números, - e _ (ex.: dev, hom, prod).`, "config");
+      if (seen.has(f.name)) throw new ApiError(`O ambiente "${f.name}" aparece duas vezes.`, "config");
+      seen.add(f.name);
+      if (f.base && !/^https?:\/\//i.test(f.base)) throw new ApiError(`Ambiente "${f.name}": o endereço base começa com http:// ou https://.`, "config");
+      for (const v of [...(f.vars || []), ...(f.secrets || [])]) if (!VAR.test(String(v?.name || ""))) throw new ApiError(`Ambiente "${f.name}": nome inválido "${v?.name || ""}". Use letras, números e _ (ex.: path_id).`, "config");
+      if (f.auth?.type === "token" && !/^https?:\/\//i.test(f.auth.url || "")) throw new ApiError(`Ambiente "${f.name}": falta o endereço do token (https://…).`, "config");
+    }
+    this.editFile((doc) => {
+      const old = doc.toJS()?.environments || {};
+      for (const name of Object.keys(old)) if (!seen.has(name)) doc.deleteIn(["environments", name]);
+      for (const f of list) {
+        const at = (...k) => ["environments", f.name, ...k];
+        const prev = old[f.name] || {};
+        if (!doc.hasIn(at())) doc.setIn(at(), doc.createNode({}));
+        // variáveis: base + as da tabela; a que saiu da tabela sai do arquivo
+        const vars = { ...(f.base ? { base: f.base } : {}), ...Object.fromEntries((f.vars || []).map((v) => [v.name, String(v.value ?? "")])) };
+        for (const k of Object.keys(prev.vars || {})) if (!(k in vars)) doc.deleteIn(at("vars", k));
+        for (const [k, v] of Object.entries(vars)) doc.setIn(at("vars", k), v);
+        // segredos: valor novo (cifrado), variável de ambiente, ou fica o que já estava
+        const keepToken = f.auth?.type === "bearer";
+        const wanted = new Set([...(f.secrets || []).map((x) => x.name), ...(keepToken ? ["token"] : [])]);
+        for (const k of Object.keys(prev.secrets || {})) if (!wanted.has(k)) doc.deleteIn(at("secrets", k));
+        const putSecret = (name, { value, env } = {}) => {
+          if (env) doc.setIn(at("secrets", name), doc.createNode({ env }));
+          else if (value) doc.setIn(at("secrets", name), protect(String(value)));
+          else if (!doc.hasIn(at("secrets", name))) throw new ApiError(`Ambiente "${f.name}": falta o valor do segredo "${name}".`, "config");
+        };
+        for (const x of f.secrets || []) putSecret(x.name, x);
+        // autenticação
+        const ourBearer = doc.getIn(at("headers", "Authorization")) === BEARER;
+        if (f.auth?.type === "bearer") {
+          putSecret("token", { value: f.auth.value, env: f.auth.secretEnv });
+          doc.setIn(at("headers", "Authorization"), BEARER);
+        } else if (ourBearer) doc.deleteIn(at("headers", "Authorization"));
+        if (doc.getIn(at("headers")) && !Object.keys(doc.getIn(at("headers")).toJSON?.() || {}).length) doc.deleteIn(at("headers"));
+        if (f.auth?.type === "token") {
+          const t = { url: f.auth.url, ...(f.auth.client_id ? { client_id: f.auth.client_id } : {}), ...(f.auth.field ? { field: f.auth.field } : {}) };
+          for (const k of ["url", "client_id", "field"]) if (!(k in t)) doc.deleteIn(at("token", k)); else doc.setIn(at("token", k), t[k]);
+          if (f.auth.secretEnv) { doc.setIn(at("token", "client_secret_env"), f.auth.secretEnv); doc.deleteIn(at("token", "client_secret")); }
+          else if (f.auth.value) { doc.setIn(at("token", "client_secret"), protect(String(f.auth.value))); doc.deleteIn(at("token", "client_secret_env")); }
+          else if (!doc.hasIn(at("token", "client_secret")) && !doc.hasIn(at("token", "client_secret_env"))) throw new ApiError(`Ambiente "${f.name}": falta o segredo do token (client secret).`, "config");
+        } else if (doc.hasIn(at("token"))) doc.deleteIn(at("token"));
+      }
+      const names = list.map((f) => f.name);
+      doc.set("current", names.includes(current) ? current : names[0] || null);
+    });
+    this.tokens.clear();
+    return this.formState();
+  }
+
+  // Testar um ambiente salvo: o endereço base responde? o token sai? (só diz o que aconteceu; nada vai para a tela)
+  async check(name) {
+    const env = this.env(name);
+    const out = { name: env.name };
+    const base = env.vars?.base;
+    if (base) {
+      try {
+        const res = await open({ method: "GET", url: String(base), headers: { Accept: "*/*", ...C.render(env.headers || {}, this.secretVars(env)) }, ca: this.ca(env), insecure: !!env.insecure, timeout: 10000 });
+        res.resume();
+        out.base = { ok: true, status: res.statusCode };
+      } catch (e) { out.base = { ok: false, error: this.maskText(env, e.message) }; }
+    }
+    if (env.token?.url) {
+      try { const v = await this.token(env, { renew: true }); out.token = { ok: true, last4: v.slice(-4) }; }
+      catch (e) { out.token = { ok: false, error: this.maskText(env, e.message) }; }
+    }
+    return out;
+  }
+
   env(name) {
     const data = this.load();
     const n = name || this.currentName(data);
@@ -257,7 +358,7 @@ export class ApiEnvironments {
 
   secrets(env) {
     const t = env.token || {};
-    const out = [this.tokens.get(env.name)?.value, t.client_secret, t.client_secret_env && process.env[t.client_secret_env], ...Object.values(env.headers || {}), ...Object.values(this.secretVars(env))];
+    const out = [this.tokens.get(env.name)?.value, t.client_secret != null ? unprotect(t.client_secret) : null, t.client_secret_env && process.env[t.client_secret_env], ...Object.values(env.headers || {}), ...Object.values(this.secretVars(env))];
     return out.filter((s) => typeof s === "string" && s.length >= 6);
   }
 
@@ -273,7 +374,7 @@ export class ApiEnvironments {
     const cached = this.tokens.get(env.name);
     if (!renew && cached && Date.now() < cached.renewAt) return cached.value;
     const id = t.client_id ?? (t.client_id_env && process.env[t.client_id_env]);
-    const secret = t.client_secret ?? (t.client_secret_env && process.env[t.client_secret_env]);
+    const secret = (t.client_secret != null ? unprotect(t.client_secret) : null) ?? (t.client_secret_env && process.env[t.client_secret_env]);
     if (!id || !secret) throw new ApiError(`Ambiente "${env.name}": falta client_id/client_secret do token (ou a variável ${t.client_secret_env || t.client_id_env || "…"})`, "config");
     const fields = { [t.id_field || "client_id"]: id, [t.secret_field || "client_secret"]: secret, ...(t.extra || {}) };
     const form = t.format === "form";
@@ -320,7 +421,7 @@ export class ApiEnvironments {
       throw new ApiError(`Ambiente "${env.name}" não tem ${names.join(", ")} configurado em secrets:`, "config");
     }
     req = { ...req, url: C.render(req.url, sv), headers: C.render(req.headers || {}, sv), body: C.render(req.body, sv) };
-    const headers = { Accept: "application/json, text/event-stream, */*", ...(env.headers || {}), ...(req.headers || {}) };
+    const headers = { Accept: "application/json, text/event-stream, */*", ...C.render(env.headers || {}, sv), ...(req.headers || {}) };
     let body = req.body;
     const file = req.file || null; // { name, type, data: Buffer } — o arquivo do slide (upload ou base64)
     const needsFile = (req.form && Object.values(req.form).includes("@file")) || /\{\{\s*file\./.test(JSON.stringify(body ?? ""));
@@ -488,7 +589,7 @@ export class ApiEnvironments {
     const sv = this.secretVars(env);
     let url = C.render(String(rt.url || ""), { ...(env.vars || {}), ...sv });
     const t = env.token || {};
-    const headers = { ...(env.headers || {}) };
+    const headers = { ...C.render(env.headers || {}, sv) };
     const auth = String(rt.auth || "header");
     if (auth !== "none") {
       const tok = await this.token(env);

package/src/studio/api-routes.js

@@ -54,10 +54,21 @@ export async function apiRoutes({ req, res, pathname, url, W, apiEnv, rtSessions
     const exists = fs.existsSync(apiEnv.file);
     return reply(200, { file: apiEnv.file, exists, text: exists ? fs.readFileSync(apiEnv.file, "utf8") : AMBIENTES_MODELO, builtin: Object.keys(apiEnv.builtin) });
   }
+  // tela Ambientes por campos: o mesmo arquivo como formulário (o valor de segredo nunca vem)
+  if (pathname === "/api/http/ambientes/form" && req.method === "GET") {
+    try { return reply(200, apiEnv.formState()); } catch (e) { return reply(400, { error: `${apiEnv.file}: ${e.message}` }); }
+  }
   if (req.method !== "POST") return reply(405, { error: "use POST" });
   if (!/^application\/json/i.test(req.headers["content-type"] || "")) return reply(415, { error: "envie JSON" });
   let body;
   try { body = await readJSON(req); } catch (e) { return reply(400, { error: e.message }); }
+  if (pathname === "/api/http/ambientes/form") {
+    if (fs.existsSync(apiEnv.file)) { fs.copyFileSync(apiEnv.file, `${apiEnv.file}.bak`); fs.chmodSync(`${apiEnv.file}.bak`, 0o600); }
+    try { return reply(200, apiEnv.saveForm(body.envs, { current: body.current })); } catch (e) { return reply(400, { error: e.message }); }
+  }
+  if (pathname === "/api/http/ambientes/testar") {
+    try { return reply(200, await apiEnv.check(String(body.name || ""))); } catch (e) { return reply(400, { error: e.message }); }
+  }
   if (pathname === "/api/http/ambientes" || pathname === "/api/http/ambientes/validar") {
     const text = String(body.text ?? "");
     let data;

package/src/studio/ia-routes.js

@@ -1,6 +1,6 @@
 // Tela "Configurar IA" do Studio: ler (a chave nunca sai inteira), salvar e testar a configuração da IA desta máquina
 // (src/ai/ia-config.js). No multiusuário quem configura é quem administra o servidor (arquivo ou variáveis), não a tela.
-import { PROVIDERS, ROLES, iaFile, loadIA, saveIA, maskedIA, keyOf } from "../ai/ia-config.js";
+import { PROVIDERS, ROLES, RECOMMENDED, iaFile, loadIA, saveIA, maskedIA, keyOf } from "../ai/ia-config.js";
 import { chat, llmConfig, llmAvailable } from "../ai/llm.js";
 
 const json = (res, status, data) => { res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" }); res.end(JSON.stringify(data)); };
@@ -23,7 +23,7 @@ function draft(body, current) {
 export async function iaRoutes({ req, res, pathname, opts, readJSON }) {
   if (pathname === "/api/ia" && req.method === "GET") {
     const cfg = llmConfig();
-    json(res, 200, { config: maskedIA(loadIA()), file: iaFile(), source: cfg.source, providers: PROVIDERS, roles: ROLES, editable: !opts.multiuser });
+    json(res, 200, { config: maskedIA(loadIA()), file: iaFile(), source: cfg.source, configured: !!(cfg.url || cfg.adaptador), providers: PROVIDERS, roles: ROLES, recommended: RECOMMENDED, editable: !opts.multiuser });
     return true;
   }
   if ((pathname === "/api/ia" || pathname === "/api/ia/test") && req.method === "POST") {

package/src/studio/open-browser.js

@@ -0,0 +1,17 @@
+// `sagadeck studio` abre o navegador na página certa: quem acabou de instalar não precisa achar o endereço no meio do
+// que o terminal escreveu. Só quando faz sentido: alguém no terminal (não um serviço, não um teste, não a CI), sem
+// servidor multiusuário e sem --sem-navegador / SAGADECK_NO_BROWSER=1.
+import { spawn } from "node:child_process";
+
+export function shouldOpenBrowser({ flags = {}, env = process.env, isTTY = process.stdout.isTTY, multiuser = false, platform = process.platform } = {}) {
+  if (flags["sem-navegador"] || flags["no-browser"] || env.SAGADECK_NO_BROWSER === "1") return false;
+  if (multiuser || env.CI || !isTTY) return false;
+  if (platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY) return false; // servidor sem tela
+  return true;
+}
+
+export function openBrowser(url, { platform = process.platform, spawnFn = spawn } = {}) {
+  const [cmd, args] = platform === "win32" ? ["cmd", ["/c", "start", "", url]] : platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try { const child = spawnFn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true }); child.on?.("error", () => {}); child.unref?.(); return true; }
+  catch { return false; }
+}

package/src/studio/public/ai-settings.js

@@ -6,6 +6,7 @@ window.SagaAISettings = (() => {
 .ai-cfg label{display:block;margin:10px 0 3px;font-weight:600;font-size:12px}.ai-cfg input,.ai-cfg select{width:100%;box-sizing:border-box;padding:7px 9px;border:1px solid var(--border,#c9ced6);border-radius:8px;background:var(--bg,#fff);color:inherit;font:inherit}
 .ai-cfg .grid{display:grid;grid-template-columns:1fr 1fr;gap:0 12px}.ai-cfg small{color:var(--text-3,#777);font-size:12px}.ai-cfg .warn{background:#fef3c7;color:#78350f;border-radius:8px;padding:8px 10px}
 .ai-cfg .row{display:flex;gap:8px;justify-content:flex-end;margin-top:16px;flex-wrap:wrap}.ai-cfg button{padding:7px 14px;border-radius:8px;border:1px solid var(--border,#c9ced6);background:transparent;color:inherit;cursor:pointer;font:inherit}
+.ai-cfg .rec{background:var(--selected,#eef);border-radius:8px;padding:8px 10px;margin:6px 0 4px}.ai-cfg .rec button{margin-top:6px;display:block}
 .ai-cfg button.primary{background:var(--brand,#5b4bdb);border-color:var(--brand,#5b4bdb);color:#fff}.ai-cfg [data-status]{margin-top:10px;min-height:1.4em}.ai-cfg [data-status].ok{color:#15803d}.ai-cfg [data-status].err{color:#b91c1c}`;
   const LABEL = { text: "Modelo de texto", vision: "Modelo que vê imagens", image: "Modelo de imagem", search: "Modelo de busca na web" };
   const HINT = { text: "obrigatório", vision: "opcional; vazio = o de texto", image: "opcional; para gerar ilustrações", search: "opcional; no OpenRouter, um modelo :online" };
@@ -27,13 +28,15 @@ window.SagaAISettings = (() => {
       <p>O sagadeck fala direto com o provedor que você escolher. A chave fica só nesta máquina, em <code>${esc(info.file)}</code>.</p>
       ${info.source === "variável" ? '<p class="warn">As variáveis SAGADECK_LLM_URL / SAGADECK_LLM_KEY estão definidas e valem por cima desta tela.</p>' : ""}
       ${info.editable ? "" : '<p class="warn">Neste servidor, quem configura a IA é quem administra.</p>'}
+      ${info.recommended ? `<div class="rec"><b>Recomendado para começar:</b> ${esc(providers[info.recommended.provider]?.label || info.recommended.provider)}, com ${esc(info.recommended.models.text)} (texto e visão), ${esc(info.recommended.models.image)} (imagem) e ${esc(info.recommended.models.search)} (busca). Se a IA não responder nem com isso, o problema é a rede ou a chave, não o modelo. Depois, troque pelo modelo que quiser. <button type="button" data-rec>Usar a recomendação</button></div>` : ""}
       <label for="ai-cfg-provider">Provedor</label>
       <select id="ai-cfg-provider" data-f="provider">${Object.entries(providers).map(([k, p]) => `<option value="${k}">${esc(p.label)}</option>`).join("")}<option value="outro">Outro compatível com a API da OpenAI</option></select>
       <label for="ai-cfg-url">Endereço da API</label>
       <input id="ai-cfg-url" data-f="url" placeholder="https://…/v1" spellcheck="false">
       <label for="ai-cfg-key">Chave</label>
       <input id="ai-cfg-key" data-f="key" type="password" autocomplete="off" spellcheck="false" placeholder="${c.keySet ? `configurada (${esc(c.keyHint)}${c.keyFrom === "variável" ? `, da variável ${esc(c.keyEnv)}` : ""}); em branco mantém` : "cole a chave do provedor"}">
-      <div class="grid">${(info.roles || []).map((r) => `<div><label for="ai-cfg-${r}">${LABEL[r] || r}</label><input id="ai-cfg-${r}" data-model="${r}" value="${esc(c.models?.[r])}" spellcheck="false"><small>${HINT[r] || ""}</small></div>`).join("")}</div>
+      <div class="grid">${(info.roles || []).map((r) => `<div><label for="ai-cfg-${r}">${LABEL[r] || r}</label><input id="ai-cfg-${r}" data-model="${r}" value="${esc(c.models?.[r])}" placeholder="${info.recommended?.models?.[r] ? `ex.: ${esc(info.recommended.models[r])}` : ""}" spellcheck="false"><small>${HINT[r] || ""}</small></div>`).join("")}</div>
+      <p><small>Texto e visão funcionam em qualquer provedor compatível com a API da OpenAI. Gerar imagem e buscar na web dependem do provedor: funcionam no OpenRouter com modelos de imagem e modelos <code>:online</code>; em outros, a pesquisa usa buscadores diretos e a imagem pode não sair.</small></p>
       <div data-status role="status"></div>
       <div class="row"><button type="button" data-close>Fechar</button><button type="button" data-test>Testar</button><button type="button" class="primary" data-save>Salvar</button></div>`;
     const sel = dialog.querySelector('[data-f="provider"]'), url = dialog.querySelector('[data-f="url"]');
@@ -44,6 +47,13 @@ window.SagaAISettings = (() => {
     sel.onchange = sync;
     if (!info.editable) dialog.querySelectorAll("input,select,[data-save],[data-test]").forEach((el) => (el.disabled = true));
     dialog.querySelector("[data-close]").onclick = () => dialog.close();
+    const rec = dialog.querySelector("[data-rec]");
+    if (rec) rec.onclick = () => {
+      sel.value = info.recommended.provider; sync();
+      for (const [r, m] of Object.entries(info.recommended.models)) { const el = dialog.querySelector(`[data-model="${r}"]`); if (el) el.value = m; }
+      const st = dialog.querySelector("[data-status]"); st.className = ""; st.textContent = info.config?.keySet ? "Preenchido. Clique em Testar." : "Preenchido. Cole a chave do OpenRouter e clique em Testar.";
+      dialog.querySelector('[data-f="key"]').focus();
+    };
     dialog.querySelector("[data-test]").onclick = () => submit("api/ia/test");
     dialog.querySelector("[data-save]").onclick = () => submit("api/ia");
   }

package/src/studio/public/api-envs-form.js

@@ -0,0 +1,148 @@
+// Ambientes dos slides de API por campos: quem instala do zero preenche endereço, variáveis, segredos e autenticação
+// sem escrever YAML (o arquivo é o mesmo, ~/.sagadeck/ambientes.yaml; a aba "Como texto" continua para quem prefere).
+// Segredo digitado vai cifrado para o arquivo e nunca volta para a página. No servidor multiusuário (ou Studio aberto
+// para a rede) os slides de API não executam: o botão Ambientes nem aparece.
+window.SagaApiEnvsForm = (() => {
+  const $ = (id) => document.getElementById(id);
+  const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+  const svg = (n) => `<i class="ic" data-ic="${n}"><svg viewBox="0 0 24 24" aria-hidden="true">${(window.UI_ICONS || {})[n] || ""}</svg></i>`;
+  let st = null, tab = "form";
+  const status = (text, kind = "") => { const el = $("api-envs-status"); if (el) { el.textContent = text; el.className = `sf-hint api-envs-status ${kind}`; } };
+
+  // sem execução neste Studio (multiusuário, aberto para a rede): o botão some
+  fetch("api/http/state").then((r) => r.json()).then((s) => { if (s && s.live === false) $("btn-api-envs")?.setAttribute("hidden", ""); }).catch(() => {});
+
+  const row = (kind, item = {}) => kind === "var"
+    ? `<div class="aef-row" data-row="var"><input data-k="name" placeholder="nome (ex.: modelo)" value="${esc(item.name)}" spellcheck="false" aria-label="Nome da variável"><input data-k="value" placeholder="valor" value="${esc(item.value)}" spellcheck="false" aria-label="Valor da variável"><button type="button" class="icon-btn" data-del title="Tirar">${svg("x")}</button></div>`
+    : `<div class="aef-row" data-row="secret"><input data-k="name" placeholder="nome (ex.: senha)" value="${esc(item.name)}" spellcheck="false" aria-label="Nome do segredo"><input data-k="value" type="password" autocomplete="off" placeholder="${item.set ? "guardado; em branco mantém" : "valor (guardado cifrado)"}" aria-label="Valor do segredo"><input data-k="env" placeholder="ou variável de ambiente" value="${esc(item.env)}" spellcheck="false" aria-label="Variável de ambiente do segredo"><button type="button" class="icon-btn" data-del title="Tirar">${svg("x")}</button></div>`;
+
+  function card(e, current) {
+    const a = e.auth || { type: "nenhuma" };
+    return `<section class="aef-env" data-env>
+      <div class="aef-head"><input data-k="envname" value="${esc(e.name)}" placeholder="nome (dev, hom, prod)" spellcheck="false" aria-label="Nome do ambiente">
+        <label class="aef-cur"><input type="radio" name="aef-current" ${e.name === current ? "checked" : ""}> em uso</label>
+        <button type="button" class="btn btn-secondary btn-sm" data-test>Testar</button>
+        <button type="button" class="icon-btn" data-remove title="Tirar este ambiente">${svg("trash-2")}</button></div>
+      <label>Endereço base <small>vira <code>{{base}}</code> nos slides</small></label>
+      <input data-k="base" value="${esc(e.base)}" placeholder="https://api.exemplo.com/v1" spellcheck="false">
+      <label>Variáveis <small><code>{{nome}}</code> nos slides</small></label>
+      <div data-list="var">${(e.vars || []).map((v) => row("var", v)).join("")}</div>
+      <button type="button" class="btn-link" data-add="var">+ variável</button>
+      <label>Segredos <small><code>{{secret.nome}}</code> nos slides; nunca vão para o deck</small></label>
+      <div data-list="secret">${(e.secrets || []).map((v) => row("secret", v)).join("")}</div>
+      <button type="button" class="btn-link" data-add="secret">+ segredo</button>
+      <label>Autenticação</label>
+      <select data-k="auth"><option value="nenhuma">Nenhuma</option><option value="bearer">Token fixo (Authorization: Bearer)</option><option value="token">Token que expira (client credentials)</option></select>
+      <div class="aef-auth" data-auth="bearer"><input data-k="bearer" type="password" autocomplete="off" placeholder="${a.type === "bearer" && a.secretSet ? "token guardado; em branco mantém" : "o token"}" aria-label="Token fixo"><input data-k="bearerEnv" placeholder="ou variável de ambiente" value="${esc(a.type === "bearer" ? a.secretEnv : "")}" spellcheck="false" aria-label="Variável do token"></div>
+      <div class="aef-auth" data-auth="token"><input data-k="tokenUrl" placeholder="endereço do token (https://…/token)" value="${esc(a.url)}" spellcheck="false" aria-label="Endereço do token"><input data-k="clientId" placeholder="client id" value="${esc(a.client_id)}" spellcheck="false" aria-label="Client id"><input data-k="clientSecret" type="password" autocomplete="off" placeholder="${a.type === "token" && a.secretSet ? "client secret guardado; em branco mantém" : "client secret"}" aria-label="Client secret"><input data-k="clientSecretEnv" placeholder="ou variável de ambiente do secret" value="${esc(a.type === "token" ? a.secretEnv : "")}" spellcheck="false" aria-label="Variável do client secret"><input data-k="field" placeholder="campo do token na resposta (access_token)" value="${esc(a.field)}" spellcheck="false" aria-label="Campo do token"></div>
+      ${e.advanced ? '<p class="muted aef-note">Este ambiente tem configurações avançadas (certificado, outros cabeçalhos); elas ficam como estão. Veja na aba Como texto.</p>' : ""}
+      <div class="aef-result" data-result></div>
+    </section>`;
+  }
+
+  function wire(root) {
+    root.querySelectorAll("[data-env]").forEach((sec) => {
+      const sel = sec.querySelector('[data-k="auth"]');
+      const show = () => sec.querySelectorAll("[data-auth]").forEach((d) => { d.hidden = d.dataset.auth !== sel.value; });
+      sel.onchange = show;
+      sec.querySelector("[data-remove]").onclick = () => { sec.remove(); empty(); };
+      sec.querySelector("[data-test]").onclick = () => test(sec);
+      sec.querySelectorAll("[data-add]").forEach((b) => (b.onclick = () => { sec.querySelector(`[data-list="${b.dataset.add}"]`).insertAdjacentHTML("beforeend", row(b.dataset.add)); wireRows(sec); }));
+      wireRows(sec);
+      show();
+    });
+  }
+  const wireRows = (sec) => sec.querySelectorAll("[data-del]").forEach((b) => (b.onclick = () => b.closest(".aef-row").remove()));
+  function empty() {
+    const intro = $("api-envs-form").querySelector("[data-intro]");
+    if (intro) intro.hidden = !!$("api-envs-form").querySelector("[data-env]");
+  }
+
+  function render() {
+    const box = $("api-envs-form");
+    box.innerHTML = `<div class="aef-intro" data-intro><p><b>Você ainda não tem ambientes seus.</b> O <b>ENSAIO</b> (uma API de mentira que vem com o sagadeck) já funciona nos slides de API, sem configurar nada.</p><p>Para ligar a sua API, adicione um ambiente: o endereço base, as variáveis, os segredos e como ela autentica. Fica gravado nesta máquina, em <code>${esc(st.file)}</code>.</p></div>
+      <div data-envs>${st.envs.map((e) => card(e, st.current)).join("")}</div>
+      <button type="button" class="btn btn-secondary" data-new>${svg("plus")} Adicionar ambiente</button>`;
+    box.querySelectorAll("[data-env]").forEach((sec, i) => { sec.querySelector('[data-k="auth"]').value = st.envs[i].auth?.type || "nenhuma"; });
+    box.querySelector("[data-new]").onclick = () => {
+      const names = new Set([...box.querySelectorAll('[data-k="envname"]')].map((i) => i.value));
+      const name = ["dev", "hom", "prod"].find((n) => !names.has(n)) || `ambiente${names.size + 1}`;
+      box.querySelector("[data-envs]").insertAdjacentHTML("beforeend", card({ name, base: "", vars: [], secrets: [], auth: { type: "nenhuma" } }, names.size ? st.current : name));
+      wire(box.querySelector("[data-envs]").lastElementChild.parentElement);
+      empty();
+      box.querySelector("[data-envs]").lastElementChild.querySelector('[data-k="base"]').focus();
+    };
+    wire(box);
+    empty();
+  }
+
+  function collect() {
+    const envs = [], box = $("api-envs-form");
+    let current = null;
+    for (const sec of box.querySelectorAll("[data-env]")) {
+      const v = (k) => sec.querySelector(`[data-k="${k}"]`)?.value.trim() || "";
+      const name = v("envname");
+      if (sec.querySelector('input[name="aef-current"]').checked) current = name;
+      const rows = (kind) => [...sec.querySelectorAll(`[data-row="${kind}"]`)].map((r) => Object.fromEntries([...r.querySelectorAll("[data-k]")].map((i) => [i.dataset.k, i.value.trim()]))).filter((r) => r.name);
+      const type = v("auth");
+      const auth = type === "bearer" ? { type, value: v("bearer"), secretEnv: v("bearerEnv") }
+        : type === "token" ? { type, url: v("tokenUrl"), client_id: v("clientId"), value: v("clientSecret"), secretEnv: v("clientSecretEnv"), field: v("field") }
+        : { type: "nenhuma" };
+      envs.push({ name, base: v("base"), vars: rows("var"), secrets: rows("secret"), auth });
+    }
+    return { envs, current };
+  }
+
+  async function save() {
+    status("Salvando…");
+    const r = await fetch("api/http/ambientes/form", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(collect()) });
+    const j = await r.json().catch(() => ({}));
+    if (!r.ok) { status(`Não salvou: ${j.error || r.status}`, "err"); return false; }
+    st = j;
+    render();
+    status(`Salvo em ${st.file}. Os slides de API já usam os ambientes novos.`, "ok");
+    return true;
+  }
+
+  async function test(sec) {
+    const out = sec.querySelector("[data-result]");
+    out.className = "aef-result"; out.textContent = "Salvando e testando…";
+    if (!(await save())) { out.textContent = ""; return; }
+    const name = sec.querySelector('[data-k="envname"]')?.value.trim();
+    const again = [...$("api-envs-form").querySelectorAll("[data-env]")].find((s) => s.querySelector('[data-k="envname"]').value === name);
+    const res = again?.querySelector("[data-result]") || out;
+    try {
+      const j = await (await fetch("api/http/ambientes/testar", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name }) })).json();
+      if (j.error) throw new Error(j.error);
+      const parts = [j.base ? (j.base.ok ? `endereço respondeu (HTTP ${j.base.status})` : `endereço não respondeu: ${j.base.error}`) : "sem endereço base",
+        ...(j.token ? [j.token.ok ? `token obtido (…${j.token.last4})` : `token falhou: ${j.token.error}`] : [])];
+      const ok = (!j.base || j.base.ok) && (!j.token || j.token.ok);
+      res.className = `aef-result ${ok ? "ok" : "err"}`;
+      res.textContent = (ok ? "Funcionou: " : "Problema: ") + parts.join("; ") + ".";
+    } catch (e) { res.className = "aef-result err"; res.textContent = `Não testou: ${e.message}`; }
+  }
+
+  function setTab(t) {
+    tab = t;
+    document.querySelectorAll("[data-envs-tab]").forEach((b) => b.classList.toggle("active", b.dataset.envsTab === t));
+    $("api-envs-form").hidden = t !== "form";
+    $("api-envs-textmode").hidden = t !== "text";
+    $("btn-api-envs-save").disabled = false;
+    status("");
+    if (t === "text") $("api-envs-text").dispatchEvent(new Event("input")); // a aba de texto valida antes de liberar o Salvar
+  }
+
+  async function open() {
+    document.querySelectorAll("[data-envs-tab]").forEach((b) => (b.onclick = async () => { if (b.dataset.envsTab === "text") { const j = await (await fetch("api/http/ambientes")).json().catch(() => ({})); if (j.text != null) $("api-envs-text").value = j.text; } else await load(); setTab(b.dataset.envsTab); }));
+    await load();
+    setTab("form");
+  }
+  async function load() {
+    const r = await fetch("api/http/ambientes/form");
+    st = await r.json().catch(() => ({ envs: [] }));
+    if (!r.ok) { status(st.error || `HTTP ${r.status}`, "err"); st = { envs: [], file: "" }; }
+    render();
+  }
+
+  return { open, save, active: () => tab === "form" };
+})();

package/src/studio/public/app.js

@@ -3430,6 +3430,7 @@ ${ta.value}`;
     renderApiEnvChips(st);
     if (!j.exists) apiEnvsStatus("Este arquivo ainda não existe. Validando o modelo antes de habilitar Salvar…");
     void validateApiEnvs();
+    await window.SagaApiEnvsForm.open(); // por campos é o padrão (api-envs-form.js); o texto fica na outra aba
   }
   function closeApiEnvs() { apiEnvsModal().classList.add("hidden"); }
   async function saveApiEnvs() {
@@ -3915,7 +3916,7 @@ ${ta.value}`;
     document.getElementById("btn-api-envs").addEventListener("click", openApiEnvs);
     document.getElementById("btn-close-api-envs").addEventListener("click", closeApiEnvs);
     document.getElementById("btn-api-envs-cancel").addEventListener("click", closeApiEnvs);
-    document.getElementById("btn-api-envs-save").addEventListener("click", saveApiEnvs);
+    document.getElementById("btn-api-envs-save").addEventListener("click", async () => { if (!window.SagaApiEnvsForm.active()) return saveApiEnvs(); if (await window.SagaApiEnvsForm.save()) await refreshStudioVars(); });
     document.getElementById("btn-api-vars-studio").addEventListener("click", () => openPane("vars"));
     document.getElementById("api-envs-text").addEventListener("input", scheduleApiEnvValidation);
     // grade de variáveis: grava ao sair da célula (change) ou no Enter; Esc desfaz; a linha em branco do fim cria

package/src/studio/public/index.html

@@ -748,11 +748,15 @@
       <div class="modal-dialog-body api-envs-body">
         <p class="muted api-envs-intro">Endereços, tokens e segredos ficam na sua máquina, nunca no deck (o deck pode ir para o GitHub).
           Nos slides, <code>{{base}}</code> vira o <code>vars.base</code> do ambiente em uso; segredos entram como <code>{{secret.nome}}</code>.</p>
+        <div class="api-envs-tabs" role="tablist"><button type="button" role="tab" data-envs-tab="form" class="active">Por campos</button><button type="button" role="tab" data-envs-tab="text">Como texto (avançado)</button></div>
+        <div id="api-envs-form" class="api-envs-form"></div>
+        <div id="api-envs-textmode" hidden>
         <p class="muted api-envs-safety">O YAML é validado antes de salvar. Uma cópia da versão anterior fica ao lado do arquivo como <code>.bak</code>.</p>
         <div class="napkin-label">Ambiente em uso <span class="muted">— o selo no slide também troca</span></div>
         <div id="api-envs-list" class="api-envs-list"></div>
         <div class="napkin-label">Arquivo <code id="api-envs-file" class="muted"></code></div>
         <textarea id="api-envs-text" class="form-control mono" rows="20" spellcheck="false" aria-label="Conteúdo do ambientes.yaml"></textarea>
+        </div>
         <div id="api-envs-status" class="sf-hint api-envs-status"></div>
       </div>
       <div class="modal-dialog-footer">
@@ -843,6 +847,7 @@
   <script src="ui-icons.js"></script>
   <script src="update-notice.js"></script>
   <script src="ai-settings.js"></script>
+  <script src="api-envs-form.js"></script>
   <script src="calc-fields.js"></script>
   <script src="art-preview.js"></script>
   <script src="api-collections.js"></script>

package/src/studio/public/library.css

@@ -28,6 +28,10 @@ body.lib { display: grid; grid-template-columns: 218px minmax(0, 1fr); grid-temp
 .lib-search { display: flex; align-items: center; gap: 9px; width: 228px; height: 37px; color: var(--text-3); padding: 0 11px; background: transparent; border: 1px solid var(--ui-line); border-radius: 8px; }
 .lib-search input { background: none; color: var(--text); border: 0; outline: 0; width: 100%; min-width: 0; font-size: 11px; }
 .lib-search kbd { border: 1px solid var(--ui-line); border-radius: 3px; font-size: 10px; padding: 0 4px; }
+.ai-banner { display: flex; align-items: center; gap: 12px; margin: 10px 24px 0; padding: 10px 14px; border-radius: 10px; background: #fef3c7; color: #78350f; border: 1px solid #f59e0b; font-size: 13px; }
+.ai-banner[hidden] { display: none; }
+.ai-banner span { flex: 1; }
+.ai-banner .ic { width: 18px; height: 18px; flex: none; }
 .lib-btn { display: inline-flex; justify-content: center; align-items: center; gap: 8px; min-height: 38px; padding: 0 15px; border-radius: 8px; border: 1px solid transparent; font-size: 12px; font-weight: 600; text-decoration: none; transition: background .15s, transform .15s; }
 .lib-btn.primary { background: var(--brand-fill); color: var(--on-brand); box-shadow: 0 3px 8px #634ce916; }
 .lib-btn.primary:hover { background: var(--brand-fill-hover); transform: translateY(-1px); }

package/src/studio/public/library.html

@@ -28,6 +28,7 @@
     <button class="lib-icon-btn" id="btn-theme" title="Alternar tema claro e escuro" aria-label="Alternar tema claro e escuro"><i class="ic" data-ic="sun-moon"></i></button>
     <div class="lib-user" id="user" hidden><div class="lib-avatar" id="avatar"></div><span class="uname" id="uname"></span></div>
   </header>
+  <div class="ai-banner" id="ai-banner" role="status" hidden><i class="ic" data-ic="sparkles"></i><span>A IA ainda não está configurada. Configure para gerar apresentações e conversar no chat (o resto já funciona).</span><button type="button" class="lib-btn primary" id="ai-banner-btn">Configurar IA</button></div>
   <div class="lib-body">
     <aside class="lib-side">
       <nav id="side" aria-label="Biblioteca"></nav>

package/src/studio/public/library.js

@@ -59,8 +59,11 @@
     render();
   }
   // botão IA: provedor, chave e modelos desta máquina (ai-settings.js); no multiusuário quem configura é quem administra
-  api("api/ia").then(({ editable }) => { $("#btn-ai").hidden = !editable; }).catch(() => {});
-  $("#btn-ai").onclick = () => window.SagaAISettings.open();
+  // e, enquanto a IA não estiver configurada, a faixa "Configure a IA" (some ao salvar)
+  const aiSaved = () => { $("#ai-banner").hidden = true; };
+  api("api/ia").then(({ editable, configured }) => { $("#btn-ai").hidden = !editable; $("#ai-banner").hidden = !editable || configured; hydrate($("#ai-banner")); }).catch(() => {});
+  $("#btn-ai").onclick = () => window.SagaAISettings.open(aiSaved);
+  $("#ai-banner-btn").onclick = () => window.SagaAISettings.open(aiSaved);
   const openEditor = (id, present) => { location.href = `editor?deck=${encodeURIComponent(id)}${present ? "&present=1" : ""}`; };
 
   // ---------------------------------------------------------------- barra lateral

package/src/studio/public/style.css

@@ -812,6 +812,29 @@ textarea.form-control.napkin-input { min-height: 220px; resize: vertical; font-f
 .bs-option:disabled { opacity: .5; }
 .ai-msg.bs .ai-avatar { background: #8b5cf6; }
 .bs-tag { font-size: 11px; color: var(--text-3); margin-bottom: 4px; }
+/* Ambientes por campos (api-envs-form.js) */
+.api-envs-tabs { display: flex; gap: 6px; margin: 4px 0 10px; }
+.api-envs-tabs button { border: 1px solid var(--border, rgba(127,127,127,.3)); background: transparent; color: inherit; border-radius: 999px; padding: 4px 12px; cursor: pointer; font-size: 12px; }
+.api-envs-tabs button.active { background: var(--selected); border-color: var(--brand); color: var(--brand); }
+.api-envs-form { display: flex; flex-direction: column; gap: 10px; }
+.aef-intro p { margin: 0 0 6px; }
+.aef-env { border: 1px solid var(--border, rgba(127,127,127,.3)); border-radius: 10px; padding: 10px 12px; display: flex; flex-direction: column; gap: 4px; }
+.aef-env label { font-size: 12px; font-weight: 600; margin-top: 6px; }
+.aef-env label small { font-weight: 400; color: var(--text-3); }
+.aef-env input, .aef-env select { width: 100%; box-sizing: border-box; padding: 5px 8px; border: 1px solid var(--border, rgba(127,127,127,.3)); border-radius: 6px; background: var(--bg, transparent); color: inherit; font: inherit; font-size: 13px; }
+.aef-head { display: flex; gap: 8px; align-items: center; }
+.aef-head input[data-k="envname"] { font-weight: 600; max-width: 180px; }
+.aef-head .aef-cur { display: flex; align-items: center; gap: 4px; margin: 0; font-weight: 400; white-space: nowrap; }
+.aef-head .aef-cur input { width: auto; }
+.aef-head [data-test] { margin-left: auto; }
+.aef-row, .aef-auth { display: flex; gap: 6px; align-items: center; }
+.aef-auth { flex-wrap: wrap; margin-top: 4px; }
+.aef-auth input { flex: 1 1 180px; }
+.aef-env .btn-link { align-self: flex-start; background: none; border: 0; color: var(--brand); cursor: pointer; padding: 2px 0; font-size: 12px; }
+.aef-note { font-size: 12px; margin: 6px 0 0; }
+.aef-result { font-size: 12px; min-height: 1em; }
+.aef-result.ok { color: #15803d; } .aef-result.err { color: var(--danger, #b91c1c); }
+
 /* leitura crítica: um cartão por ponto, ligado ao slide, com Aplicar e Ignorar */
 .crit-list { display: flex; flex-direction: column; gap: 8px; margin-top: 10px; }
 .crit-item { border: 1px solid var(--border, rgba(127,127,127,.3)); border-radius: 10px; padding: 8px 10px; display: flex; flex-direction: column; gap: 4px; }