onveloz 0.0.0-beta.30 → 0.0.0-beta.31

package/dist/index.mjs

@@ -2,17 +2,17 @@
 import { Cli, middleware, z } from "incur";
 import { exec, execSync } from "node:child_process";
 import * as fs from "node:fs";
-import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { z as z$1 } from "zod";
 import { createORPCClient } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { homedir, platform, tmpdir } from "node:os";
 import chalk from "chalk";
 import { createAuthClient } from "better-auth/client";
-import { deviceAuthorizationClient, organizationClient } from "better-auth/client/plugins";
+import { deviceAuthorizationClient } from "better-auth/client/plugins";
 import * as readline from "node:readline";
 import { createInterface } from "node:readline";
 import ora from "ora";
@@ -21,7 +21,8 @@ import WebSocket from "ws";
 import { link, mkdir, mkdtemp, readdir, rm, stat } from "node:fs/promises";
 import ignore from "ignore";
 import tar from "tar";
-import React, { createElement, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { promisify } from "node:util";
+import React, { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Box, Text, render, useInput, useStdout } from "ink";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { map } from "nanostores";
@@ -1353,7 +1354,7 @@ function getGlobalProjectFlag() {
 	const idx = process.argv.indexOf("--project");
 	if (idx !== -1 && idx + 1 < process.argv.length) return process.argv[idx + 1];
 }
-function isMultipleOrgsError$2(error) {
+function isMultipleOrgsError$1(error) {
 	if (!(error instanceof Error)) return false;
 	const e = error;
 	return e.data?.code === "MULTIPLE_ORGS" && Array.isArray(e.data?.organizations);
@@ -1365,7 +1366,7 @@ async function fetchProjectsWithOrgResolution(client) {
 	try {
 		return await client.projects.list();
 	} catch (error) {
-		if (!isMultipleOrgsError$2(error)) throw error;
+		if (!isMultipleOrgsError$1(error)) throw error;
 		const orgs = error.data.organizations;
 		if (orgs.length === 1) {
 			const org = orgs[0];
@@ -12386,16 +12387,16 @@ const isSuccess$1 = /* @__PURE__ */ matchEager$1({
 	onSuccess: () => true
 });
 /** @internal */
-const delay$1 = /* @__PURE__ */ dual(2, (self, duration) => andThen$1(sleep$3(duration), self));
+const delay$1 = /* @__PURE__ */ dual(2, (self, duration) => andThen$1(sleep$2(duration), self));
 /** @internal */
-const timeoutOrElse$1 = /* @__PURE__ */ dual(2, (self, options) => raceFirst$1(self, flatMap$1(sleep$3(options.duration), options.orElse)));
+const timeoutOrElse$1 = /* @__PURE__ */ dual(2, (self, options) => raceFirst$1(self, flatMap$1(sleep$2(options.duration), options.orElse)));
 /** @internal */
 const timeout$1 = /* @__PURE__ */ dual(2, (self, duration) => timeoutOrElse$1(self, {
 	duration,
 	orElse: () => fail$2(new TimeoutError$1())
 }));
 /** @internal */
-const timeoutOption$1 = /* @__PURE__ */ dual(2, (self, duration) => raceFirst$1(asSome$1(self), as$1(sleep$3(duration), none())));
+const timeoutOption$1 = /* @__PURE__ */ dual(2, (self, duration) => raceFirst$1(asSome$1(self), as$1(sleep$2(duration), none())));
 /** @internal */
 const timed$1 = (self) => clockWith$1((clock) => {
 	const start = clock.currentTimeNanosUnsafe();
@@ -13212,7 +13213,7 @@ const processOrPerformanceNow = /* @__PURE__ */ function() {
 /** @internal */
 const clockWith$1 = (f) => withFiber$1((fiber$2) => f(fiber$2.getRef(ClockRef)));
 /** @internal */
-const sleep$3 = (duration) => clockWith$1((clock) => clock.sleep(fromInputUnsafe(duration)));
+const sleep$2 = (duration) => clockWith$1((clock) => clock.sleep(fromInputUnsafe(duration)));
 /** @internal */
 const TimeoutErrorTypeId$1 = "~effect/Cause/TimeoutError";
 /** @internal */
@@ -15536,7 +15537,7 @@ const toStepWithMetadata = (schedule) => clockWith$1((clock) => map$3(toStep(sch
 			const meta = metaFn(now, input);
 			meta.output = output;
 			meta.duration = duration;
-			return as$1(sleep$3(duration), meta);
+			return as$1(sleep$2(duration), meta);
 		});
 	});
 }));
@@ -18892,7 +18893,7 @@ const delay = delay$1;
 * @since 2.0.0
 * @category Delays & Timeouts
 */
-const sleep$2 = sleep$3;
+const sleep$1 = sleep$2;
 /**
 * Measures the runtime of an effect and returns the duration with its result.
 *
@@ -24079,7 +24080,7 @@ const LOGO_LINES$1 = [
 ];
 const BRAND_COLOR$1 = "#FF4D00";
 function getVersion() {
-	return "0.0.0-beta.30";
+	return "0.0.0-beta.31";
 }
 function printBanner(subtitle) {
 	const version$2 = getVersion();
@@ -25145,6 +25146,7 @@ function printDeployWarnings(warnings) {
 
 //#endregion
 //#region src/lib/auto-update.ts
+const execAsync = promisify(exec);
 const PACKAGE_NAME = "onveloz";
 function detectPackageManager() {
 	try {
@@ -25174,22 +25176,24 @@ async function fetchLatestVersion() {
 	}
 }
 function getCurrentVersion() {
-	return "0.0.0-beta.30";
+	return "0.0.0-beta.31";
 }
 /**
 * Install a specific CLI version. Returns true on success.
 */
-function installVersion(pm, version$2) {
+async function installVersion(pm, version$2) {
 	const installCmd = getInstallCommand(pm, version$2);
 	const spin = spinner(`Atualizando CLI ${chalk.dim(getCurrentVersion())} → ${chalk.bold(version$2)}...`);
 	try {
-		execSync(installCmd, { stdio: "ignore" });
+		await execAsync(installCmd, { timeout: 12e4 });
 		spin.stop();
 		console.log(chalk.green(`\n✓ CLI atualizada: ${chalk.bold(version$2)}\n`));
 		return true;
-	} catch {
+	} catch (error) {
 		spin.stop();
+		const stderr = error.stderr?.trim();
 		console.log(chalk.yellow(`\n⚠ Não foi possível atualizar automaticamente. Execute manualmente:\n  ${installCmd}\n`));
+		if (stderr) console.log(chalk.dim(stderr.split("\n").slice(-5).join("\n")));
 		return false;
 	}
 }
@@ -25215,7 +25219,7 @@ async function autoUpdate() {
 	const currentVersion = getCurrentVersion();
 	const latestVersion = await fetchLatestVersion();
 	if (!latestVersion || latestVersion === currentVersion) return;
-	if (installVersion(pm, latestVersion)) reExec();
+	if (await installVersion(pm, latestVersion)) reExec();
 }
 
 //#endregion
@@ -26288,7 +26292,7 @@ async function addServiceFlow(existingConfig, opts) {
 	await provisionDatabases(updatedConfig, { yes: opts.yes ?? false });
 	await triggerDeploy(service$2.id, service$2.name);
 }
-function isMultipleOrgsError$1(error) {
+function isMultipleOrgsError(error) {
 	if (!(error instanceof Error)) return false;
 	const e = error;
 	return e.data?.code === "MULTIPLE_ORGS" && Array.isArray(e.data?.organizations);
@@ -26300,7 +26304,7 @@ async function resolveOrgIfNeeded(nonInteractive) {
 	try {
 		await client.projects.list();
 	} catch (error) {
-		if (!isMultipleOrgsError$1(error)) throw error;
+		if (!isMultipleOrgsError(error)) throw error;
 		const orgs = error.data.organizations;
 		if (orgs.length === 1) {
 			const org = orgs[0];
@@ -26438,9 +26442,18 @@ async function* mcpDeployFlow(opts) {
 		});
 		return;
 	}
-	const configuredServices = await findServicesFromConfig();
-	if (configuredServices.length === 0) throw new Error("Nenhum serviço configurado. Execute 'veloz deploy' no terminal para configurar o projeto primeiro.");
-	if (!opts.service && !opts.all) {
+	let configuredServices = await findServicesFromConfig();
+	let justBootstrapped = false;
+	if (configuredServices.length === 0) {
+		await mcpBootstrapProjectAndService({
+			app: opts.app,
+			name: opts.name
+		});
+		configuredServices = await findServicesFromConfig();
+		if (configuredServices.length === 0) throw new Error("Falha ao configurar o projeto automaticamente. Verifique o output acima para detalhes.");
+		justBootstrapped = true;
+	}
+	if (!opts.service && !opts.all && !justBootstrapped) {
 		const available = configuredServices.map((s) => `${s.key} (${s.serviceName})`).join(", ");
 		throw new Error(`Especifique o(s) serviço(s) para deploy com --service ou use --all.\n\nServiços disponíveis: ${available}`);
 	}
@@ -26475,6 +26488,76 @@ async function* mcpDeployFlow(opts) {
 		data: result$2
 	};
 }
+/**
+* Bootstrap a project + service for the current cwd in MCP mode.
+*
+* Mirrors the first-deploy setup in `cliDeployFlow` but runs fully
+* non-interactively so agents (including the wizard) can call
+* `veloz:deploy` on a fresh directory without shelling out.
+*/
+async function mcpBootstrapProjectAndService(opts) {
+	await resolveOrgIfNeeded(true);
+	const client = await getClient();
+	const remote = isGitRepo() ? getGitRemote() : null;
+	const project = remote ? await withRetry(() => client.projects.findByRepo({
+		githubRepoOwner: remote.owner,
+		githubRepoName: remote.repo
+	})) : null;
+	if (project && project.services.length > 0) {
+		info(`Projeto encontrado: ${project.name}`);
+		const svc = project.services[0];
+		const detectedType = svc.type?.toLowerCase() ?? "web";
+		saveConfig$1({
+			version: "1.0",
+			project: {
+				id: project.id,
+				name: project.name
+			},
+			services: { main: {
+				id: svc.id,
+				name: svc.name,
+				type: detectedType,
+				root: ".",
+				branch: svc.branch
+			} },
+			created: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		info(`Arquivo ${getConfigFileName()} criado.`);
+		return;
+	}
+	if (project && project.services.length === 0) {
+		info(`Projeto encontrado: ${project.name}. Criando serviço...`);
+		await createServiceFlow(project.id, project.name, remote?.repo ?? project.name, {
+			yes: true,
+			app: opts.app
+		});
+		return;
+	}
+	const dirName = basename(process.cwd());
+	const defaultName = opts.name ?? remote?.repo ?? dirName;
+	const toSlug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
+	let projectSlug = toSlug(defaultName);
+	let slugCheck = await withRetry(() => client.projects.checkSlug({ slug: projectSlug }));
+	if (!slugCheck.available) {
+		projectSlug = toSlug(`${defaultName}-${Math.random().toString(36).slice(2, 6)}`);
+		slugCheck = await withRetry(() => client.projects.checkSlug({ slug: projectSlug }));
+		if (!slugCheck.available) throw new Error(`Não foi possível reservar um subdomínio para "${defaultName}". Tente novamente ou passe --name.`);
+	}
+	info(`Criando projeto "${defaultName}" (${projectSlug}.runveloz.com)...`);
+	const newProject = await withRetry(() => client.projects.create({
+		name: defaultName,
+		slug: projectSlug,
+		...remote && {
+			githubRepoOwner: remote.owner,
+			githubRepoName: remote.repo
+		}
+	}));
+	success(`Projeto criado: ${newProject.name}`);
+	await createServiceFlow(newProject.id, newProject.name, remote?.repo ?? dirName, {
+		yes: true,
+		app: opts.app
+	});
+}
 async function cliDeployFlow(opts) {
 	if (opts.verbose) process.env.VELOZ_VERBOSE = "true";
 	printBanner("Deploy");
@@ -27048,7 +27131,7 @@ function registerUpdate(cli$1) {
 					version: currentVersion
 				};
 			}
-			if (!installVersion(pm, latestVersion)) {
+			if (!await installVersion(pm, latestVersion)) {
 				console.log(chalk.dim(`  Execute manualmente: ${getInstallCommand(pm, latestVersion)}`));
 				return {
 					updated: false,
@@ -27189,6 +27272,25 @@ const FRAMEWORK_LABELS = Object.fromEntries(FRAMEWORK_LIST.map((f) => [f.value,
 
 //#endregion
 //#region src/wizard/agent/agent-prompt.ts
+function renderUserNotes(notes) {
+	if (!notes || !notes.trim()) return "";
+	return `
+
+## Notas do Usuário (instruções explícitas — prioridade máxima)
+O usuário forneceu as seguintes instruções ANTES de iniciar o deploy. Trate-as como requisitos obrigatórios e respeite-as em todas as decisões (escolha de apps, Dockerfile, flags, variáveis, etc.). Se as notas conflitarem com os defaults do wizard, as notas vencem.
+
+${notes.trim()}`;
+}
+/**
+* Max width (in columns) for the diagram drawn via wizard-tools:set_helper_content.
+* The diagram renders inside the right pane of RunScreen (~50% of terminal) and
+* full-width in OutroScreen. Scale with the current terminal width so we don't
+* leave half the pane empty on wide terminals.
+*/
+function getDiagramWidth() {
+	const cols = process.stdout.columns ?? 120;
+	return Math.max(36, Math.floor(cols * .45));
+}
 function assemblePrompt(ctx) {
 	return `Você é o wizard de deploy da Veloz. Sua missão é configurar e fazer deploy do projeto do usuário de forma autônoma.
 
@@ -27196,7 +27298,7 @@ function assemblePrompt(ctx) {
 - Diretório: ${ctx.cwd}
 - Framework detectado: ${ctx.frameworkLabel}
 - Package manager: ${ctx.packageManager}
-- Já autenticado como: ${ctx.userName} (org: ${ctx.orgName})
+- Já autenticado como: ${ctx.userName} (org: ${ctx.orgName})${renderUserNotes(ctx.userNotes)}
 
 ## O que é a Veloz
 A Veloz é uma PaaS brasileira que faz deploy de aplicações a partir do código-fonte. A plataforma:
@@ -27224,54 +27326,334 @@ Leia o arquivo \`.claude/skills/veloz-llms.txt\` para entender a plataforma, fra
 ### 1. Analisar o projeto
 - Leia package.json, configs do framework, .env.example
 - Identifique: build command, start command, porta, variáveis de ambiente necessárias
+- Procure Dockerfiles/containers já existentes (veja seção 1b abaixo)
 - CUIDADO: NÃO rode \`npm run dev\`, \`next dev\`, \`vite\`, \`nodemon\` ou qualquer servidor de desenvolvimento. Isso trava o processo.
 
+### 1b. Escape hatch: Dockerfile
+A Veloz tem dois métodos de build: **nixpacks** (auto-detect a partir do código) e **dockerfile** (usa um Dockerfile explícito). Prefira nixpacks sempre que possível — é mais simples e mais rápido. Mas existem dois cenários em que você DEVE usar Dockerfile:
+
+**Cenário A — já existe um Dockerfile no projeto (USE, não recrie)**
+ANTES de assumir nixpacks, procure por arquivos Docker já presentes:
+
+\`\`\`
+Glob: Dockerfile
+Glob: **/Dockerfile
+Glob: **/Dockerfile.*
+Glob: docker-compose.yml
+\`\`\`
+
+Se houver um Dockerfile no caminho do app (raiz do projeto, ou em \`apps/<app>/Dockerfile\` para monorepos), você DEVE reutilizá-lo:
+- NÃO sobrescreva, NÃO edite, NÃO gere um novo.
+- Configure o serviço para usar \`method: "dockerfile"\` via \`veloz:config_set\`:
+  \`\`\`
+  veloz:config_set { "build": { "method": "dockerfile", "dockerfile": "apps/api/Dockerfile", "context": "." } }
+  \`\`\`
+- \`dockerfile\` é o caminho do Dockerfile relativo à raiz do projeto. \`context\` é o diretório de build (geralmente \`.\` para monorepos que precisam do workspace inteiro, ou o caminho do app para projetos simples).
+- Mencione no diagrama e na confirmação: "Usando Dockerfile existente em \`<caminho>\`".
+
+Se houver múltiplos Dockerfiles (ex: \`Dockerfile\` + \`Dockerfile.dev\`), prefira o que NÃO tem sufixo \`dev\`/\`test\`. Em dúvida, pergunte ao usuário via \`wizard-tools:prompt_user\` com \`type: "choice"\`.
+
+**Cenário B — nixpacks não dá conta do stack (fallback)**
+Criar Dockerfile **novo** (só se não houver nenhum) SOMENTE se:
+- O framework não é suportado pelo Nixpacks (ex: binários compilados customizados, runtime exótico, setup nativo complexo com bibliotecas de sistema específicas)
+- Já tentou corrigir a misconfiguração do nixpacks 2 vezes sem sucesso (via \`veloz:config_set\`)
+- O usuário pediu explicitamente nas notas
+
+Nesse caso:
+1. Escreva um Dockerfile minimalista e idiomático na raiz do app (arquivo novo — OK sem confirmação prévia)
+2. Mencione no resumo da confirmação do deploy (seção 4) que esse arquivo novo será criado
+3. Configure o serviço com \`method: "dockerfile"\` via \`veloz:config_set\`
+4. Re-deploye
+
+Se precisar **editar** um Dockerfile existente (raro), siga a regra de permissão da seção "Edits em arquivos existentes do usuário" — peça confirmação antes.
+
+NUNCA crie um Dockerfile só porque o primeiro build falhou — diagnostique primeiro (seção 7).
+
 ### 2. Configurar variáveis de ambiente
 - Use wizard-tools:check_env_keys para ver quais .env existem
 - Use wizard-tools:prompt_user para pedir valores sensíveis ao usuário (com hint de onde obter)
 - Use veloz:env_set para configurar no servidor ANTES do deploy (variáveis de build como NEXT_PUBLIC_* precisam existir antes)
 - O usuário pode escolher "configurar depois" — nesse caso, continue sem a env var
 
-### 3. Fazer deploy
-Use SEMPRE a ferramenta MCP \`veloz:deploy\` para fazer deploy. NUNCA use Bash para rodar \`veloz deploy\`.
+### 3. Desenhar o diagrama (OBRIGATÓRIO — antes do deploy)
+ANTES de chamar \`veloz:deploy\`, você DEVE chamar \`wizard-tools:set_helper_content\` com um diagrama ASCII da arquitetura que será deployada. Este passo NÃO é opcional — o diagrama aparece na TUI abaixo da lista de tarefas e é essencial para o usuário visualizar o que está acontecendo.
+
+Requisitos do diagrama:
+- Use caracteres de box-drawing (┌─┐│└┘├┤┬┴┼) e setas (→ ↓ ↑)
+- Largura alvo: **~${getDiagramWidth()} colunas** (use a maior parte desse espaço — não deixe o painel vazio). Nunca ultrapasse esse limite ou o diagrama será truncado
+- Mostre: framework do projeto, pipeline (código → build → serviço), porta, URL esperada
+- Inclua serviços auxiliares (banco, cache, workers) se houver
+- Use \`title\` para o cabeçalho e \`lines\` para o corpo
+
+Exemplo (amplie a largura para preencher ~${getDiagramWidth()} colunas):
+\`\`\`
+wizard-tools:set_helper_content {
+  "title": "Deploy — Next.js",
+  "lines": [
+    "┌─────────────────────────────────────────────────────┐",
+    "│  Next.js 15 · porta 3000 · runtime Node 20          │",
+    "└──────────────────────────┬──────────────────────────┘",
+    "                           │ veloz deploy",
+    "                           ▼",
+    "  build (Nixpacks) ───▶ imagem ───▶ serviço (turbo)",
+    "                           │",
+    "                           ▼",
+    "              https://app.runveloz.com"
+  ]
+}
+\`\`\`
+
+Só prossiga para a confirmação DEPOIS que o diagrama for enviado.
+
+### 4. Confirmar com o usuário (OBRIGATÓRIO — antes do deploy)
+ANTES de chamar \`veloz:deploy\`, você DEVE pedir confirmação explícita ao usuário usando \`wizard-tools:prompt_user\` com \`type: "confirm"\`. Este passo NÃO é opcional.
+
+\`\`\`
+wizard-tools:prompt_user {
+  "question": "Pronto para fazer deploy de <framework> com build <build-cmd> e start <start-cmd>? Consulte o diagrama acima.",
+  "type": "confirm"
+}
+\`\`\`
+
+Inclua na pergunta um resumo claro do que vai ser deployado:
+- Framework e caminho do app (para monorepos)
+- Comando de build e start que serão usados
+- Se vai criar banco/volume/serviços auxiliares
+- Variáveis de ambiente que serão configuradas
+
+Regras:
+- Se o usuário responder "sim" → prossiga para o deploy
+- Se o usuário responder "não" → NÃO faça deploy. Emita \`[SUMMARY] Deploy cancelado pelo usuário antes de começar.\` e encerre.
+- Se o usuário não responder (timeout) → NÃO faça deploy. Emita \`[SUMMARY] Deploy cancelado por falta de resposta.\` e encerre.
+
+### 5. Fazer deploy
+Use SEMPRE a ferramenta MCP \`veloz:deploy\` para fazer deploy — inclusive no PRIMEIRO deploy (sem veloz.json ainda). NUNCA use Bash para rodar \`veloz deploy\`.
+
+**5a. Dry-run primeiro (OBRIGATÓRIO)**
+ANTES de fazer o deploy real, você DEVE rodar um dry-run para validar a configuração sem enviar nada:
+
+\`\`\`
+veloz:deploy { "dryRun": true }
+\`\`\`
+
+O dry-run é **local-only** — ele NÃO autentica, NÃO chama API, NÃO faz upload, NÃO cria serviço, NÃO gera veloz.json, NÃO consome quota. Ele apenas:
+- Detecta o framework e lista os serviços que seriam criados
+- Calcula o tamanho do tarball a ser enviado (MB)
+- Mostra build/start/porta/output-dir que seriam usados
+- Reporta warnings de pre-deploy (arquivos suspeitos, configs faltando, etc.)
+
+Use o resultado do dry-run para:
+- Confirmar que o framework/app/serviço detectado está correto
+- Verificar se o tamanho do upload é razoável (>100MB é flag vermelha — provavelmente falta .dockerignore/.gitignore excluindo node_modules/dist/.next)
+- Pegar ajustes óbvios (build/start errado, porta errada, monorepo path errado) ANTES de gastar tempo num build real
+
+**Como corrigir problemas encontrados no dry-run:**
+Porque o dry-run NÃO gera veloz.json e NÃO cria serviço no servidor, \`veloz:config_set\` NÃO funciona antes do primeiro deploy real (ele precisa de um serviço existente). As correções pré-primeiro-deploy só podem ser feitas via **arquivos locais do projeto**:
+
+- **Upload grande demais** → edite/crie \`.dockerignore\` e/ou \`.gitignore\` local para excluir \`node_modules\`, \`dist\`, \`.next\`, \`.turbo\`, \`coverage\`, etc. (pedir permissão via \`wizard-tools:prompt_user\` antes de editar se o arquivo já existir)
+- **Framework detectado errado** → verifique se a raiz do app está correta (use \`--app\` para monorepos) e se \`package.json\` tem os sinais esperados (dependências, \`scripts.build\`/\`start\`). Ajuste scripts do package.json (com permissão)
+- **Build/start command errado ou ausente** → adicione/corrija os scripts em \`package.json\` (com permissão), OU gere um Dockerfile novo (seção 1b cenário B)
+- **Porta errada** → geralmente o framework define; se precisa customizar, edite config do framework (next.config, vite.config) OU use Dockerfile com \`EXPOSE\`
+- **Dockerfile não está sendo usado quando deveria** → garanta que o path do Dockerfile está onde o detector procura (raiz do app)
+
+Repita \`veloz:deploy { "dryRun": true }\` depois de cada correção para confirmar. Só prossiga para 5b quando o dry-run estiver limpo.
+
+**Depois do primeiro deploy real** (\`veloz.json\` criado, serviço existe no servidor), \`veloz:config_set\` passa a funcionar e é a forma preferida de ajustar build/start/port/size/preStart sem re-editar arquivos locais.
+
+Para o dry-run, use as mesmas flags de escopo do deploy real (\`app\`, \`service\`, \`all\`):
+\`\`\`
+veloz:deploy { "dryRun": true, "app": "apps/web" }
+veloz:deploy { "dryRun": true, "service": "nome-servico" }
+\`\`\`
+
+**5b. Deploy real**
+Depois que o dry-run passou limpo, faça o deploy real:
 
 \`\`\`
 veloz:deploy { "yes": true }
 \`\`\`
 
-O deploy via MCP:
+Para monorepos ou deploy de serviço específico:
+- \`veloz:deploy { "yes": true, "app": "apps/web" }\` — deploy de um app específico do monorepo
+- \`veloz:deploy { "yes": true, "service": "nome-servico" }\` — re-deploy de serviço existente
+
+O deploy via MCP, mesmo sem veloz.json, faz tudo de ponta-a-ponta:
 1. Detecta o framework e o tipo de serviço (web, static, worker)
-2. Cria o projeto e o serviço na plataforma
+2. Cria o projeto e o serviço na plataforma (se ainda não existirem)
 3. Gera o arquivo veloz.json com a configuração correta
 4. Faz upload do código e inicia o build
 5. Retorna eventos de progresso e o resultado final
 
-Para monorepos ou deploy de serviço específico:
-- \`veloz:deploy { "yes": true, "app": "apps/web" }\` — deploy de um app específico do monorepo
-- \`veloz:deploy { "yes": true, "service": "nome-servico" }\` — re-deploy de serviço existente
-
 IMPORTANTE:
-- SEMPRE use veloz:deploy (MCP), NUNCA \`veloz deploy\` via Bash. O Bash pode travar esperando input interativo.
-- Se o MCP falhar com erro de conexão ou timeout, aí sim tente via Bash com \`veloz deploy --yes\` como fallback único.
+- SEMPRE rode \`dryRun: true\` ANTES do deploy real. NÃO pule o dry-run.
+- NUNCA passe \`dryRun: true\` no deploy de 5b — isso simula e NÃO faz deploy de verdade. O dry-run é só para o passo 5a.
+- SEMPRE use veloz:deploy (MCP), inclusive no primeiro deploy. NUNCA \`veloz deploy\` via Bash — o Bash pode travar esperando input interativo.
+- Só caia para Bash (\`veloz deploy --yes\`) se o MCP retornar erro explícito de conexão/timeout — nunca por ausência de veloz.json.
 - NUNCA crie ou edite o arquivo veloz.json manualmente. Ele é gerado automaticamente pelo CLI no primeiro deploy.
 - Após o primeiro deploy, se precisar ajustar configurações, use \`veloz:config_set\`.
 
-### 4. Monitorar e diagnosticar
+### 6. Monitorar e diagnosticar
 Após o deploy, use as ferramentas MCP para verificar o resultado:
 - veloz:builds_logs — logs completos do build (stdout + stderr)
 - veloz:builds_show — status detalhado do build
 - veloz:logs_search — logs de runtime do serviço (após o serviço iniciar)
 - veloz:domains_list — ver URLs/domínios disponíveis
 
-### 5. Auto-healing: quando algo falhar
-Você é um engenheiro experiente. Quando um deploy falhar:
+### 6b. Health check pós-deploy (OBRIGATÓRIO quando o deploy retorna LIVE)
+Após um deploy bem-sucedido (\`status: "LIVE"\` no resultado de \`veloz:deploy\`), você DEVE executar um health check completo antes de declarar sucesso. Este passo NÃO é opcional — um deploy "LIVE" não garante que o app esteja respondendo corretamente (pode estar em crash loop, retornando 5xx, consumindo CPU/memória fora do normal, etc.).
+
+**Passo 0 — Desenhar um plano de testes (OBRIGATÓRIO antes de testar)**
+ANTES de rodar qualquer curl/logs/metrics, você DEVE escrever um plano de testes explícito e emitir para o usuário. O plano deve ser específico ao projeto que acabou de ser deployado (framework, rotas conhecidas, dependências), não um template genérico. Formato:
+
+\`\`\`
+[TESTING_PLAN]
+Plano de health check para <nome-do-serviço> (<framework>):
+
+HTTP checks:
+  1. GET <url-base>/ — esperar 2xx/3xx
+  2. GET <url-base>/<rota-de-health-conhecida-se-houver> — esperar 200
+  3. GET <url-base>/<rota-principal-da-app> — esperar 2xx
+  (adicione rotas específicas que você identificou na análise do projeto, ex: /api/health, /_health, /ping)
+
+Logs (janela: últimos 2min):
+  - queries de erro: level:error, "Error:", "TypeError", "ECONNREFUSED", "panic", framework-specific
+  - amostra geral para confirmar tráfego/startup
+
+Métricas (janela: últimos 5min):
+  - CPU: < 90% sustentado
+  - Memória: < 80% do size preset (<preset atual>)
+  - Instâncias reportando samples
+
+Critérios de sucesso:
+  - Todos HTTP checks em 2xx/3xx
+  - Zero erros repetidos nos logs (warnings OK)
+  - Métricas dentro dos limites
+
+Critérios de falha → ação:
+  - 5xx/timeout no HTTP → ler logs, classificar categoria A/B (seção 7)
+  - Erros repetidos nos logs → classificar e corrigir (máx 3 iterações)
+  - CPU sustentado alto sem tráfego → suspeitar crash loop, ler logs
+\`\`\`
+
+Emita esse bloco COMPLETO, com as rotas/thresholds específicos, ANTES de rodar os checks. Depois, execute o plano na ordem listada abaixo.
+
+**1) HTTP check via curl (Bash)**
+Use a URL retornada em \`urls\` (ou \`dashboardUrl\`) pelo \`veloz:deploy\`. Teste com curl — silencioso, só pegando status code, corpo e tempo:
+
+\`\`\`bash
+curl -sS -o /tmp/veloz-health.txt -w "HTTP %{http_code} · %{time_total}s · %{size_download}B\\n" -m 15 "<url>"
+\`\`\`
+
+Aguarde ~5 segundos antes do primeiro curl (tempo para o serviço terminar de subir). Se o status for:
+- **2xx** → OK, prossiga para o passo 2
+- **3xx** → siga o redirect com \`-L\` e re-teste; se continuar 3xx, OK
+- **4xx** (exceto 401/403 que podem ser esperados para rotas autenticadas) → tente \`/\` e \`/health\` / \`/api/health\` se disponível; reporte como aviso mas não falhe
+- **5xx ou timeout** → **falha**. Leia \`/tmp/veloz-health.txt\` para ver o corpo da resposta, vá direto para o passo 2 (logs) e diagnóstico
+
+**2) Checar logs de runtime (veloz:logs_search)**
+Procure erros nos últimos 2 minutos:
+
+\`\`\`
+veloz:logs_search { "query": "level:error OR level:fatal OR \\"Error:\\" OR \\"TypeError\\" OR \\"ECONNREFUSED\\" OR \\"panic\\"", "since": "2m", "limit": 50 }
+\`\`\`
+
+Depois, pegue uma amostra geral para confirmar que o app está servindo requests:
+
+\`\`\`
+veloz:logs_search { "query": "*", "since": "2m", "limit": 30 }
+\`\`\`
+
+Se aparecerem erros repetidos (crash loop, exceções não tratadas, \`ECONNREFUSED\` em deps, migration falhando) → **falha**. Se só aparecem warnings ou os logs mostram o app servindo requests normalmente → OK.
+
+**3) Checar métricas (veloz:metrics_show ou veloz:metrics_query)**
+Verifique CPU e memória nos últimos 5 minutos:
+
+\`\`\`
+veloz:metrics_show { "since": "5m" }
+\`\`\`
+
+Flags de alerta:
+- CPU sustentado > 90% sem tráfego real → provavelmente crash loop ou hot loop
+- Memória subindo rápido ou próxima do limite do size preset → memory leak ou size subdimensionado
+- Zero samples retornadas → serviço pode não estar reportando métricas (serviço não subiu)
+
+**Classificando o resultado do health check:**
 
-1. **Leia os logs**: Use veloz:builds_logs para ver o erro do build, ou veloz:logs_search para erros de runtime
-2. **Diagnostique**: Identifique a causa raiz
-3. **Corrija**: Ajuste a configuração via \`veloz:config_set\` — ele aceita qualquer propriedade do serviço (build, start, port, preStart, size, instances, etc.). Consulte o output de \`veloz --llms-full\` para ver todas as opções disponíveis.
-4. **Re-deploy**: Use veloz:deploy para tentar novamente (até 3 tentativas)
+Se TODOS os 3 checks passaram (HTTP 2xx/3xx, sem erros nos logs, métricas saudáveis):
+- Emita \`[HEALTH_OK]\` com um resumo curto em pt-BR: URL testada, status HTTP, amostra de logs, CPU/memória atuais
+- Encerre com \`[SUMMARY] Deploy concluído e saudável.\`
 
-Se o build falhar, teste localmente com Bash para ver o erro completo antes de ajustar.
+Se qualquer check falhou:
+- Classifique como categoria A (misconfig) ou B (código do usuário) seguindo a seção 7
+- Categoria A típica: porta errada (curl falha com connection refused, mas serviço está LIVE), healthcheck path errado, env var de runtime faltando, migration pendente, connection string de banco errada → corrija via \`veloz:config_set\` / \`veloz:env_set\` e faça o health check de novo
+- Categoria B: se logs mostram \`Error: <erro do código do usuário>\` repetidamente e nenhuma correção de config resolve, emita \`[DEPLOY_UNHEALTHY_USER_CODE]\` com o trecho de erro e instruções de correção
+- Máximo 3 iterações de health check + fix. Depois disso, emita \`[DEPLOY_UNHEALTHY]\` com o que foi tentado e o estado atual.
+
+**IMPORTANTE:** NÃO emita \`[SUMMARY] Deploy concluído\` sem antes rodar o health check. Um deploy LIVE mas com 5xx ou crash loop NÃO é um deploy concluído.
+
+### 7. Classificar falhas e decidir o próximo passo
+Quando um deploy falhar, você DEVE ler os logs com \`veloz:builds_logs\` e classificar o erro em UMA das duas categorias abaixo antes de decidir o que fazer.
+
+**A) Misconfiguração (responsabilidade do wizard — corrija você mesmo)**
+Erros onde o código do usuário está correto, mas a Veloz não sabe como construir/iniciar o app. Exemplos:
+- Comando de build errado ou faltando (ex: \`pnpm run build\` em um projeto sem esse script)
+- Comando de start errado (ex: porta errada, \`npm start\` sem \`start\` script)
+- Porta incorreta configurada no serviço
+- Package manager errado detectado (usando npm num repo pnpm)
+- Workspace/monorepo path incorreto
+- Falta de \`preStart\` para migrações de banco
+- Nixpacks não detectou o framework corretamente
+
+→ Ação: corrija via \`veloz:config_set\` (build, start, port, preStart, packageManager, etc.) e re-deploye. Máximo 3 tentativas. NÃO envolva o usuário — essa é sua responsabilidade como wizard.
+
+Último recurso: se após 2 tentativas o nixpacks ainda não estiver funcionando (detecção falhando, runtime/libs específicas, framework exótico) e NÃO houver Dockerfile existente, gere um Dockerfile minimalista e mude \`build.method\` para \`"dockerfile"\` via \`veloz:config_set\` (veja seção 1b). Se JÁ existe um Dockerfile no repo e você estava ignorando — pare, use o existente.
+
+**B) Falha de testes do usuário (responsabilidade do usuário — ÚNICO caso de handoff)**
+Emita \`[BUILD_FAILED_USER_CODE]\` e pare **APENAS** quando o build falhar porque **testes do usuário estão falhando** (jest, vitest, pytest, go test, cargo test, rspec, phpunit, etc. executados como parte do build/CI do projeto).
+
+Para QUALQUER outro tipo de falha — incluindo TypeScript compile errors, erros de sintaxe, módulos faltando, runtime crashes, falhas em scripts \`postinstall\`/\`prebuild\`, variáveis de ambiente ausentes — você DEVE tratar como categoria A (tentar corrigir via \`veloz:config_set\`, ajustar build/start, adicionar env vars ausentes via \`wizard-tools:prompt_user\`, ou cair no Dockerfile como último recurso). NÃO emita \`[BUILD_FAILED_USER_CODE]\` para esses casos — o wizard existe pra resolvê-los.
+
+→ Ação (somente falha de testes): NÃO tente corrigir o código nem desabilitar os testes. Emita o signal abaixo e encerre:
+
+\`\`\`
+[BUILD_FAILED_USER_CODE]
+Motivo: <explicação curta e clara do erro em pt-BR>
+
+Detalhes:
+<trecho dos logs com o erro, arquivo:linha quando disponível>
+
+Como corrigir:
+- <passo 1 acionável>
+- <passo 2 acionável>
+- <comando sugerido para reproduzir local, ex: pnpm build>
+
+Após corrigir, execute \`veloz deploy\` novamente.
+\`\`\`
+
+Depois de emitir \`[BUILD_FAILED_USER_CODE]\`, PARE. Não re-deploye, não tente editar o código-fonte do usuário, não chame mais ferramentas. Apenas encerre a sessão.
+
+**Regra de ouro**: Se você não tem certeza em qual categoria o erro cai, teste localmente com \`pnpm build\` (ou equivalente) via Bash. Se o build local falha com testes → B (falha de testes). Caso contrário → A (misconfiguração, fixável pelo wizard).
+
+## Edits em arquivos existentes do usuário — SEMPRE peça permissão primeiro
+
+Se em algum momento você precisar **criar, editar ou sobrescrever um arquivo que já existe no projeto do usuário** (package.json, next.config.*, vite.config.*, Dockerfile existente, .env, tsconfig.json, código-fonte em src/, scripts customizados, qualquer arquivo versionado), você DEVE pedir permissão explícita via \`wizard-tools:prompt_user\` com \`type: "confirm"\` ANTES de chamar Write/Edit.
+
+Formato da pergunta:
+
+\`\`\`
+wizard-tools:prompt_user {
+  "question": "Preciso editar <caminho/do/arquivo> para <motivo em 1 linha>. Posso aplicar a mudança?\\n\\nO que vai mudar:\\n- <resumo curto da alteração>\\n- <antes → depois se útil>",
+  "type": "confirm"
+}
+\`\`\`
+
+Regras:
+- Se o usuário responder "sim" → aplique a edição
+- Se o usuário responder "não" → NÃO edite. Encontre uma alternativa (\`veloz:config_set\`, Dockerfile à parte, env var, etc.) ou emita \`[BUILD_FAILED_USER_CODE]\` com instruções para o usuário fazer a edição manualmente
+- Exceção: criar um arquivo **novo** que não existia antes (ex: novo \`Dockerfile\` na raiz quando não há nenhum) NÃO precisa de confirmação prévia — mas mencione no resumo da confirmação do deploy (seção 4) que o arquivo será criado
+- Exceção: arquivos gerenciados pelo wizard (\`.env\` via \`wizard-tools:set_env_values\`, configuração do serviço via \`veloz:config_set\`) NÃO precisam de confirmação por edit — já são escopo do wizard
+
+Em caso de dúvida: peça permissão. É melhor uma pergunta extra do que editar algo que o usuário não queria tocar.
 
 ## Ferramentas Helper (wizard-tools MCP)
 - wizard-tools:check_env_keys — verificar quais env vars existem sem revelar valores
@@ -27279,12 +27661,19 @@ Se o build falhar, teste localmente com Bash para ver o erro completo antes de a
 - wizard-tools:set_helper_content — exibir diagramas e conteúdo visual no painel esquerdo
 - wizard-tools:prompt_user — perguntar algo ao usuário interativamente
 
-## Diagrama Visual
-ANTES de chamar o deploy, chame wizard-tools:set_helper_content com um diagrama ASCII mostrando:
+## Diagrama Visual (OBRIGATÓRIO antes do deploy)
+SEMPRE chame \`wizard-tools:set_helper_content\` ANTES de \`veloz:deploy\`. O diagrama é renderizado abaixo da lista de tarefas na TUI e é parte essencial da experiência do wizard — não pule esse passo.
+
+O diagrama deve mostrar:
 - O framework/tecnologia do projeto
-- O pipeline (source → build → deploy)
+- O pipeline (código → build → serviço)
 - A porta e URL onde o serviço ficará disponível
-- Serviços auxiliares (banco de dados, etc.) se houver
+- Serviços auxiliares (banco de dados, cache, etc.) se houver
+
+Restrições visuais:
+- Largura alvo: ~${getDiagramWidth()} colunas (aproveite o espaço — o painel direito é largo quando o terminal é largo)
+- Use box-drawing (┌─┐│└┘├┤┬┴┼) e setas (→ ↓ ▼)
+- Uma tarefa do TodoWrite DEVE representar esse passo (ver checklist abaixo)
 
 ## Reportar Progresso
 Use a ferramenta TodoWrite para manter uma lista de tarefas atualizada:
@@ -27292,12 +27681,17 @@ Use a ferramenta TodoWrite para manter uma lista de tarefas atualizada:
 - Mude para "in_progress" quando começar cada etapa
 - Mude para "completed" quando terminar
 
-Tarefas típicas:
+Tarefas típicas (inclua TODAS, na ordem):
 1. "Aprender CLI" — ler veloz --llms-full
-2. "Analisar projeto" — ler package.json, configs, estrutura
+2. "Analisar projeto" — ler package.json, configs, estrutura, procurar Dockerfile existente
 3. "Configurar variáveis de ambiente" — env vars no servidor
-4. "Fazer deploy" — enviar código e build
-5. "Verificar resultado" — confirmar que está no ar
+4. "Desenhar diagrama" — chamar wizard-tools:set_helper_content (OBRIGATÓRIO antes do deploy)
+5. "Confirmar com o usuário" — wizard-tools:prompt_user com type="confirm" (OBRIGATÓRIO antes do deploy)
+6. "Validar com dry-run" — veloz:deploy { dryRun: true } para checar detecção/tamanho/config (OBRIGATÓRIO antes do deploy real)
+7. "Fazer deploy" — enviar código e build (veloz:deploy { yes: true }, SEM dryRun)
+8. "Desenhar plano de testes" — emitir [TESTING_PLAN] com rotas e thresholds específicos (OBRIGATÓRIO antes do health check)
+9. "Executar health check" — curl + veloz:logs_search + veloz:metrics_show seguindo o plano
+10. "Finalizar" — emitir [HEALTH_OK] + [SUMMARY] se tudo saudável
 
 ## Regras CRÍTICAS — Uso de Ferramentas
 - SEMPRE use ferramentas MCP (veloz:*) para TODAS as operações da plataforma. NUNCA use Bash para rodar comandos \`veloz\` exceto:
@@ -27309,10 +27703,11 @@ Tarefas típicas:
 
 ## Regras Gerais
 - Comunique-se em português (pt-BR)
-- Não modifique código fonte do app a não ser que seja estritamente necessário para o deploy funcionar
+- Para QUALQUER edit em arquivo existente do projeto (package.json, tsconfig.json, configs de framework, Dockerfile existente, código-fonte, scripts customizados), SEMPRE peça permissão primeiro via \`wizard-tools:prompt_user\` type="confirm" (ver seção "Edits em arquivos existentes do usuário"). Exceções: \`.env\` via \`wizard-tools:set_env_values\` e config de serviço via \`veloz:config_set\` — esses são escopo do wizard.
 - NUNCA crie veloz.json manualmente — o CLI gera automaticamente
+- SEMPRE peça confirmação explícita via wizard-tools:prompt_user (type="confirm") antes de chamar veloz:deploy
 - Para env vars sensíveis, use wizard-tools:prompt_user — nunca invente valores
-- Se algo falhar, DIAGNOSTIQUE E CORRIJA — não desista facilmente
+- Classifique falhas de build: misconfiguração → corrija e retente; erro de código do usuário → emita [BUILD_FAILED_USER_CODE] e PARE
 - NUNCA rode comandos de dev server (next dev, vite, nodemon, npm run dev) — isso trava o processo
 - NUNCA exponha secrets nos seus logs/mensagens
 - Não use terminologia de infraestrutura interna (Kubernetes, pods, containers) — use "serviço", "instância", "build"
@@ -27345,9 +27740,9 @@ function getCommandments() {
 
 7. **Edits mínimos**: Prefira edits focados e mínimos. Não refatore código que não precisa ser mudado. Não adicione comentários desnecessários.
 
-8. **Não modifique código fonte**: Apenas modifique arquivos de configuração (.env, next.config.*, package.json scripts). Não altere componentes, rotas, ou lógica do app. Use \`veloz:config_set\` para ajustar configurações do serviço — nunca edite veloz.json diretamente.
+8. **Peça permissão antes de tocar arquivos do usuário**: Para QUALQUER Write/Edit em arquivo que já existe no projeto (package.json, tsconfig.json, next.config.*, vite.config.*, Dockerfile existente, código em src/, scripts customizados, etc.), você DEVE chamar \`wizard-tools:prompt_user\` com \`type: "confirm"\` explicando arquivo + motivo + o que vai mudar, e só aplicar se o usuário responder "sim". Se responder "não", encontre alternativa ou emita \`[BUILD_FAILED_USER_CODE]\`. Exceções (não precisam de confirmação): \`.env\` via \`wizard-tools:set_env_values\`, configuração de serviço via \`veloz:config_set\`, criar arquivo **novo** que não existia antes. NUNCA edite veloz.json diretamente.
 
-9. **Auto-healing obrigatório**: Se um deploy falhar, NÃO desista. Leia os logs (veloz:builds_logs), diagnostique, corrija, e tente novamente. Máximo de 3 tentativas.
+9. **Classificar falhas de deploy**: Se um deploy falhar, leia os logs (veloz:builds_logs) e classifique o erro. (A) Se for **misconfiguração** da Veloz (build/start/port/preStart errado, package manager incorreto, monorepo path, nixpacks): corrija via \`veloz:config_set\` e retente (máx. 3 tentativas). (B) Se for **erro no código do usuário** (TypeScript, sintaxe, import quebrado, módulo faltando no package.json, teste quebrando no build, runtime crash do app): NÃO tente corrigir o código-fonte, NÃO retente. Emita o signal \`[BUILD_FAILED_USER_CODE]\` com motivo + trecho dos logs + passos para corrigir, e ENCERRE. Em caso de dúvida, teste \`pnpm build\` (ou equivalente) localmente: se falha localmente → é código do usuário.
 
 10. **Build local primeiro**: Quando possível, teste o build localmente (via Bash: pnpm build / npm run build) ANTES de fazer deploy. Isso economiza tempo e créditos.
 
@@ -27357,7 +27752,9 @@ function getCommandments() {
 
 13. **Diagrama ANTES do deploy**: Use wizard-tools:set_helper_content para mostrar um diagrama ASCII da arquitetura ANTES de chamar veloz:deploy. O diagrama deve mostrar: framework detectado, pipeline de build, porta, URL esperada, e serviços auxiliares. Isso é OBRIGATÓRIO — o usuário precisa visualizar o que vai acontecer enquanto o build executa. Use caracteres Unicode para o diagrama (┌┐└┘│─→↓). Atualize o helper conforme avança (ex: diagnóstico de erro, resultado do build).
 
-14. **Perguntar ao usuário**: Use wizard-tools:prompt_user para pedir informações ao usuário. Para variáveis de ambiente, forneça hint de como obtê-las (ex: "Acesse dashboard.stripe.com > API Keys"). O usuário pode optar por configurar depois — nesse caso, continue o deploy sem a env var e informe o comando \`veloz env set\` no final. Use type="confirm" para confirmações antes do deploy.
+14. **Perguntar ao usuário**: Use wizard-tools:prompt_user para pedir informações ao usuário. Para variáveis de ambiente, forneça hint de como obtê-las (ex: "Acesse dashboard.stripe.com > API Keys"). O usuário pode optar por configurar depois — nesse caso, continue o deploy sem a env var e informe o comando \`veloz env set\` no final.
+
+18. **Confirmação obrigatória antes do deploy**: ANTES de chamar \`veloz:deploy\` (primeiro deploy ou re-deploy), você DEVE pedir confirmação explícita ao usuário com \`wizard-tools:prompt_user\` \`type="confirm"\`. A pergunta precisa resumir o que será deployado (framework, app path, build/start, banco/volumes, env vars). Se o usuário responder "não" ou não responder, NÃO faça deploy — emita \`[SUMMARY] Deploy cancelado pelo usuário.\` e encerre. Exceção única: re-deploy de auto-healing de **misconfiguração** (categoria A da regra 9) pode ser feito sem nova confirmação até o limite de 3 tentativas.
 
 15. **NUNCA rode dev server**: Comandos como \`next dev\`, \`vite\`, \`nodemon\`, \`npm run dev\`, \`pnpm dev\` travam o processo do agente. Use apenas comandos de build (\`npm run build\`, \`pnpm build\`) para testes locais.
 
@@ -27365,16 +27762,227 @@ function getCommandments() {
 `.trim();
 }
 
+//#endregion
+//#region src/wizard/debug-logger.ts
+/**
+* Per-session debug logger for `veloz init`.
+*
+* Writes a folder under `~/.veloz/logs/init-<timestamp>-<id>/` with
+* structured files capturing every interesting event in the wizard run,
+* so failures can be diagnosed after the fact.
+*
+* Files:
+*   session.log        — human-readable timeline (append-only)
+*   events.jsonl       — structured events (category, timestamp, data)
+*   sdk-messages.jsonl — raw SDK messages from the Agent SDK
+*   tool-calls.jsonl   — tool_use / tool_result pairs
+*   store-events.jsonl — WizardStore state transitions
+*   build-stream.jsonl — build log streaming events
+*   mcp-tools.jsonl    — wizard-tools MCP server invocations
+*   prompts.md         — initial + continuation prompts
+*   meta.json          — metadata (cwd, framework, user, outcome, timings)
+*
+* The logger never throws — disk failures are swallowed. MCP mode is
+* unaffected because writes only go to the session folder, never stdout.
+*/
+var SessionLogger = class {
+	dir;
+	sessionId;
+	startedAt;
+	meta;
+	constructor(config) {
+		this.startedAt = Date.now();
+		const now = new Date(this.startedAt);
+		this.sessionId = `init-${now.toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
+		this.dir = join(config.root ?? join(homedir(), ".veloz", "logs"), this.sessionId);
+		try {
+			mkdirSync(this.dir, { recursive: true });
+		} catch {}
+		this.meta = {
+			sessionId: this.sessionId,
+			startedAt: now.toISOString(),
+			cwd: config.cwd,
+			node: process.version,
+			platform: process.platform,
+			pid: process.pid
+		};
+		this.writeMeta();
+		this.log("session", "wizard session started", {
+			cwd: config.cwd,
+			pid: process.pid,
+			node: process.version
+		});
+	}
+	/** Append a line to session.log and a structured event to events.jsonl. */
+	log(category, message, data) {
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		const text = data === void 0 ? message : `${message} ${safeStringify(data)}`;
+		this.append("session.log", `[${ts}] [${category}] ${text}\n`);
+		this.appendJsonl("events.jsonl", {
+			ts,
+			category,
+			message,
+			data
+		});
+	}
+	logSdkMessage(message) {
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		this.appendJsonl("sdk-messages.jsonl", {
+			ts,
+			message
+		});
+	}
+	logToolUse(name, input, toolUseId, extra) {
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		this.appendJsonl("tool-calls.jsonl", {
+			ts,
+			kind: "tool_use",
+			name,
+			toolUseId,
+			input,
+			...extra ?? {}
+		});
+		this.append("session.log", `[${ts}] [tool_use] ${name}${toolUseId ? ` (${toolUseId})` : ""}\n`);
+	}
+	logToolResult(toolUseId, content, isError, extra) {
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		this.appendJsonl("tool-calls.jsonl", {
+			ts,
+			kind: "tool_result",
+			toolUseId,
+			isError,
+			content,
+			...extra ?? {}
+		});
+		this.append("session.log", `[${ts}] [tool_result] ${toolUseId}${isError ? " ERROR" : ""}\n`);
+	}
+	logStoreEvent(event, data) {
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		this.appendJsonl("store-events.jsonl", {
+			ts,
+			event,
+			data
+		});
+	}
+	logBuildStream(event, data) {
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		this.appendJsonl("build-stream.jsonl", {
+			ts,
+			event,
+			data
+		});
+		this.append("session.log", `[${ts}] [build-stream] ${event}\n`);
+	}
+	logPrompt(kind, body, context$2) {
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		const header = `\n\n---\n## [${ts}] ${kind} prompt\n`;
+		const ctx = context$2 ? `\n<context>\n${safeStringify(context$2)}\n</context>\n\n` : "\n";
+		this.append("prompts.md", `${header}${ctx}${body}\n`);
+		this.appendJsonl("events.jsonl", {
+			ts,
+			category: "prompt",
+			kind,
+			bytes: body.length
+		});
+	}
+	updateMeta(patch) {
+		this.meta = {
+			...this.meta,
+			...patch
+		};
+		this.writeMeta();
+	}
+	finalize(outcome, info$1) {
+		const endedAt = Date.now();
+		this.updateMeta({
+			outcome,
+			endedAt: new Date(endedAt).toISOString(),
+			durationMs: endedAt - this.startedAt,
+			...info$1 ?? {}
+		});
+		this.log("session", `wizard session finished: ${outcome}`, info$1);
+	}
+	writeMeta() {
+		try {
+			writeFileSync(join(this.dir, "meta.json"), JSON.stringify(this.meta, null, 2));
+		} catch {}
+	}
+	append(file, text) {
+		try {
+			appendFileSync(join(this.dir, file), text);
+		} catch {}
+	}
+	appendJsonl(file, obj) {
+		try {
+			appendFileSync(join(this.dir, file), safeStringify(obj) + "\n");
+		} catch {}
+	}
+};
+/**
+* Safely stringify any value, falling back to a diagnostic shape when the
+* value contains circular references or non-serializable content.
+*/
+function safeStringify(value) {
+	try {
+		return JSON.stringify(value, replacer);
+	} catch (err) {
+		return JSON.stringify({
+			__unserializable: true,
+			reason: err instanceof Error ? err.message : String(err),
+			preview: String(value).slice(0, 500)
+		});
+	}
+}
+function replacer(_key, value) {
+	if (value instanceof Error) return {
+		name: value.name,
+		message: value.message,
+		stack: value.stack
+	};
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "function") return `[Function ${value.name || "anonymous"}]`;
+	return value;
+}
+let active = null;
+function initSessionLogger(config) {
+	active = new SessionLogger(config);
+	return active;
+}
+/** Returns the active logger, or a no-op logger if none was initialized. */
+function getSessionLogger() {
+	return active ?? noopLogger;
+}
+function getSessionLogDir() {
+	return active?.dir ?? null;
+}
+const noopLogger = {
+	dir: "",
+	sessionId: "",
+	log: () => {},
+	logSdkMessage: () => {},
+	logToolUse: () => {},
+	logToolResult: () => {},
+	logStoreEvent: () => {},
+	logBuildStream: () => {},
+	logPrompt: () => {},
+	updateMeta: () => {},
+	finalize: () => {}
+};
+
 //#endregion
 //#region src/wizard/agent/agent-tools.ts
 /**
+* Small in-process MCP server for sensitive wizard operations.
+* Only env var safety tools — everything else the agent does directly.
+*/
+/**
 * Create the wizard-tools MCP server definition.
 * Returns a tools map that the agent SDK can consume as an in-process MCP server.
 */
 function createWizardToolsServer(config) {
 	return {
 		command: "node",
-		args: ["-e", getWizardToolsScript(config.workingDirectory)],
+		args: ["-e", getWizardToolsScript(config.workingDirectory, getSessionLogDir())],
 		env: {}
 	};
 }
@@ -27382,13 +27990,26 @@ function createWizardToolsServer(config) {
 * Generate a self-contained Node.js script that implements the wizard-tools MCP server.
 * This runs as a child process communicating via stdio JSON-RPC.
 */
-function getWizardToolsScript(workingDirectory) {
+function getWizardToolsScript(workingDirectory, logDir) {
 	return `
 'use strict';
 const fs = require('fs');
 const path = require('path');
 
 const CWD = '${workingDirectory.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}';
+const LOG_DIR = '${logDir ? logDir.replace(/\\/g, "\\\\").replace(/'/g, "\\'") : ""}';
+
+function logEvent(event, data) {
+  if (!LOG_DIR) return;
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), event, data }) + '\\n';
+    fs.appendFileSync(path.join(LOG_DIR, 'mcp-tools.jsonl'), line);
+  } catch {}
+}
+
+logEvent('server_start', { cwd: CWD, pid: process.pid });
+process.on('exit', (code) => logEvent('server_exit', { code }));
+process.on('uncaughtException', (err) => logEvent('uncaught_exception', { message: String(err && err.message), stack: String(err && err.stack) }));
 
 const TOOLS = {
   check_env_keys: {
@@ -27434,7 +28055,7 @@ const TOOLS = {
     },
   },
   set_helper_content: {
-    description: 'Exibir conteúdo customizado no painel esquerdo da TUI do wizard. Use para mostrar diagramas de deploy, explicações visuais, ou informações contextuais sobre o projeto. Cada chamada SUBSTITUI o conteúdo anterior. Use linhas vazias e caracteres ASCII para criar diagramas visuais.',
+    description: 'Renderizar um diagrama ASCII abaixo da lista de tarefas na TUI do wizard. OBRIGATÓRIO: chame esta ferramenta antes de veloz:deploy com um diagrama da arquitetura (framework, pipeline, porta, URL, serviços auxiliares). Aproveite a largura disponível do painel — veja o prompt do sistema para a largura alvo em colunas; evite diagramas estreitos que deixam metade do painel vazio. Cada chamada SUBSTITUI o conteúdo anterior — atualize ao final com o estado deployado.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -27602,13 +28223,12 @@ async function handlePromptUser(input) {
   };
 }
 
-// JSON-RPC over stdio with Content-Length framing
-// The MCP protocol uses HTTP-style Content-Length headers:
-//   Content-Length: N\\r\\n\\r\\n{json}
+// MCP stdio transport: newline-delimited JSON (one JSON-RPC message per line).
+// Not LSP Content-Length framing — the Claude Agent SDK rejects that and marks
+// the server as "failed", which is exactly what broke the wizard diagram/prompt.
 
 function send(obj) {
-  const json = JSON.stringify(obj);
-  process.stdout.write('Content-Length: ' + Buffer.byteLength(json) + '\\r\\n\\r\\n' + json);
+  process.stdout.write(JSON.stringify(obj) + '\\n');
 }
 
 async function handleJsonRpc(msg) {
@@ -27639,68 +28259,45 @@ async function handleJsonRpc(msg) {
   } else if (msg.method === 'tools/call') {
     const name = msg.params.name;
     const args = msg.params.arguments || {};
+    logEvent('tool_call_start', { name, args });
     let result;
-    if (name === 'check_env_keys') result = handleCheckEnvKeys(args);
-    else if (name === 'set_env_values') result = handleSetEnvValues(args);
-    else if (name === 'set_helper_content') result = { content: [{ type: 'text', text: 'Conteúdo do helper atualizado com ' + (args.lines || []).length + ' linhas.' }] };
-    else if (name === 'prompt_user') result = await handlePromptUser(args);
-    else result = { content: [{ type: 'text', text: 'Ferramenta desconhecida: ' + name }], isError: true };
+    try {
+      if (name === 'check_env_keys') result = handleCheckEnvKeys(args);
+      else if (name === 'set_env_values') result = handleSetEnvValues(args);
+      else if (name === 'set_helper_content') result = { content: [{ type: 'text', text: 'Conteúdo do helper atualizado com ' + (args.lines || []).length + ' linhas.' }] };
+      else if (name === 'prompt_user') result = await handlePromptUser(args);
+      else result = { content: [{ type: 'text', text: 'Ferramenta desconhecida: ' + name }], isError: true };
+      logEvent('tool_call_done', { name, isError: Boolean(result && result.isError) });
+    } catch (err) {
+      logEvent('tool_call_error', { name, message: String(err && err.message), stack: String(err && err.stack) });
+      result = { content: [{ type: 'text', text: 'Erro: ' + String(err && err.message) }], isError: true };
+    }
     send({ jsonrpc: '2.0', id: msg.id, result });
   } else if (msg.id) {
     send({ jsonrpc: '2.0', id: msg.id, result: {} });
   }
 }
 
-// Parse Content-Length framed messages from stdin
-let rawBuffer = Buffer.alloc(0);
-let expectedLength = -1;
-
+// MCP stdio transport: read newline-delimited JSON-RPC messages from stdin.
+let stdinBuffer = '';
+process.stdin.setEncoding('utf-8');
 process.stdin.on('data', (chunk) => {
-  rawBuffer = Buffer.concat([rawBuffer, chunk]);
-  processBuffer();
-});
-
-function processBuffer() {
-  while (rawBuffer.length > 0) {
-    if (expectedLength === -1) {
-      // Look for Content-Length header
-      const headerEnd = rawBuffer.indexOf('\\r\\n\\r\\n');
-      if (headerEnd === -1) return; // Need more data
-
-      const header = rawBuffer.slice(0, headerEnd).toString('utf-8');
-      const match = header.match(/Content-Length:\\s*(\\d+)/i);
-      if (match) {
-        expectedLength = parseInt(match[1], 10);
-        rawBuffer = rawBuffer.slice(headerEnd + 4); // Skip \\r\\n\\r\\n
-      } else {
-        // No Content-Length header — try line-based JSON (fallback)
-        const lineEnd = rawBuffer.indexOf('\\n');
-        if (lineEnd === -1) return;
-        const line = rawBuffer.slice(0, lineEnd).toString('utf-8').trim();
-        rawBuffer = rawBuffer.slice(lineEnd + 1);
-        if (line) {
-          try {
-            const msg = JSON.parse(line);
-            handleJsonRpc(msg).catch(() => {});
-          } catch {}
-        }
-        continue;
-      }
-    }
-
-    if (expectedLength >= 0 && rawBuffer.length >= expectedLength) {
-      const body = rawBuffer.slice(0, expectedLength).toString('utf-8');
-      rawBuffer = rawBuffer.slice(expectedLength);
-      expectedLength = -1;
-      try {
-        const msg = JSON.parse(body);
-        handleJsonRpc(msg).catch(() => {});
-      } catch {}
-    } else {
-      return; // Need more data
+  stdinBuffer += chunk;
+  let newlineIdx;
+  while ((newlineIdx = stdinBuffer.indexOf('\\n')) !== -1) {
+    const line = stdinBuffer.slice(0, newlineIdx).trim();
+    stdinBuffer = stdinBuffer.slice(newlineIdx + 1);
+    if (!line) continue;
+    try {
+      const msg = JSON.parse(line);
+      handleJsonRpc(msg).catch((err) => {
+        logEvent('handler_error', { message: String(err && err.message) });
+      });
+    } catch (err) {
+      logEvent('parse_error', { message: String(err && err.message), line: line.slice(0, 200) });
     }
   }
-}
+});
 `.trim();
 }
 
@@ -27709,147 +28306,335 @@ function processBuffer() {
 /**
 * Build log streamer for the wizard.
 *
-* When the agent triggers `veloz:deploy`, this module polls the API
-* to find the newly created deployment and streams its build logs
-* back to the wizard store for display in the RunScreen.
-*/
-/**
-* Start streaming build logs for the most recent deployment.
-*
-* This runs in the background while the agent's `veloz:deploy` MCP call
-* is also streaming logs (to stderr). The wizard picks up the same stream
-* independently so it can render the build progress in the TUI.
-*/
-async function startBuildLogStream(config) {
-	const { store, cwd } = config;
+* Triggered by `setBuildDeploymentId` — the deploy tool_result already emits
+* the deployment ID, so we skip the veloz.json round-trip and open the ORPC
+* log stream directly.
+*
+* Runs alongside the tool_result capture in agent-interface.ts (which pushes
+* raw progress messages). This module provides the live stderr-style build
+* output from the platform until the deployment reaches a terminal state.
+*/
+async function streamBuildLogs(config) {
+	const { store, deploymentId } = config;
+	const logger = getSessionLogger();
+	logger.logBuildStream("start", { deploymentId });
+	const client = createWizardClient(store);
+	if (!client) {
+		logger.logBuildStream("no_client", { reason: "missing apiKey" });
+		store.pushBuildLog("[stream] aguardando autenticação para conectar ao build...");
+		return;
+	}
+	store.setBuildStreamActive(true);
 	try {
-		store.setBuildStreamActive(true);
-		const client = await createWizardClient(store, cwd);
-		if (!client) {
-			store.setBuildStreamActive(false);
-			return;
-		}
-		const serviceIds = getServiceIdsFromConfig(cwd);
-		if (serviceIds.length === 0) {
-			store.setBuildStreamActive(false);
-			return;
-		}
-		const deployment = await pollForNewDeployment(client, serviceIds);
-		if (!deployment) {
-			store.setBuildStreamActive(false);
-			return;
-		}
-		store.setBuildDeploymentId(deployment.id);
-		store.pushStatus("Build detectado — transmitindo logs...");
-		await streamLogs(client, deployment.id, store);
-	} catch {} finally {
+		await openStream(client, deploymentId, store);
+		logger.logBuildStream("stream_done", { deploymentId });
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		logger.logBuildStream("error", { message: msg });
+		store.pushBuildLog(`[stream] erro: ${msg}`);
+	} finally {
 		store.setBuildStreamActive(false);
 	}
 }
-function createWizardClient(store, cwd) {
+function createWizardClient(store) {
 	const apiKey = store.session.apiKey;
 	if (!apiKey) return null;
-	const apiUrl = process.env.VELOZ_API_URL || "https://api.onveloz.com";
-	let projectId = null;
-	const configPath = join(cwd, "veloz.json");
-	if (existsSync(configPath)) try {
-		projectId = JSON.parse(readFileSync(configPath, "utf-8"))?.project?.id ?? null;
-	} catch {}
-	return createClient(apiUrl, () => {
+	return createClient(process.env.VELOZ_API_URL || "https://api.onveloz.com", () => {
 		const headers = {
 			Authorization: `Bearer ${apiKey}`,
 			"User-Agent": "veloz-cli/wizard"
 		};
 		if (store.session.orgId) headers["X-Organization-Id"] = store.session.orgId;
-		if (projectId) headers["X-Project-Id"] = projectId;
 		return headers;
 	});
 }
-function getServiceIdsFromConfig(cwd) {
-	const configPath = join(cwd, "veloz.json");
-	if (!existsSync(configPath)) return [];
+async function openStream(client, deploymentId, store) {
+	const logger = getSessionLogger();
+	logger.logBuildStream("open_stream", { deploymentId });
 	try {
-		const raw = JSON.parse(readFileSync(configPath, "utf-8"));
-		const services = [];
-		if (raw?.service?.id) services.push(raw.service.id);
-		if (raw?.services && typeof raw.services === "object") for (const key of Object.keys(raw.services)) {
-			const svc = raw.services[key];
-			if (svc?.id) services.push(svc.id);
-		}
-		return services;
-	} catch {
-		return [];
-	}
-}
-async function pollForNewDeployment(client, serviceIds, maxWaitMs = 3e4) {
-	const startTime = Date.now();
-	const pollInterval = 2e3;
-	while (Date.now() - startTime < maxWaitMs) {
-		for (const serviceId of serviceIds) try {
-			const deployments = await client.deployments.list({
-				serviceId,
-				limit: 1,
-				offset: 0
-			});
-			if (deployments.length > 0) {
-				const d = deployments[0];
-				const status = d.status;
-				if (status === "QUEUED" || status === "BUILDING" || status === "DEPLOYING") return {
-					id: d.id,
-					serviceId,
-					status
-				};
+		const stream = await client.logs.streamBuildLogs({ deploymentId });
+		for await (const event of stream) {
+			logger.logBuildStream("event", event);
+			if (event.type === "status") {
+				const label = statusLabels[event.content] ?? event.content;
+				store.pushBuildLog(`[status] ${label}`);
+				if (event.content === "LIVE") store.pushStatus("Deploy concluído — serviço ativo!");
+				else if (event.content === "BUILD_FAILED" || event.content === "DEPLOY_FAILED") store.pushStatus(`Deploy falhou: ${label}`);
+				if (TERMINAL_STATUSES.has(event.content)) return;
+			} else if (event.type === "log") for (const line of event.content.split("\n")) {
+				const display = formatLogLine(line);
+				if (display) store.pushBuildLog(display);
 			}
-		} catch {}
-		await sleep$1(pollInterval);
+		}
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		store.pushBuildLog(`[stream] desconectou: ${msg} — buscando logs salvos`);
+		await fetchSavedLogs(client, deploymentId, store);
 	}
-	return null;
 }
-async function streamLogs(client, deploymentId, store) {
+/**
+* One-shot fetch of persisted build logs — used when the live stream breaks
+* (e.g. deployment finished before we attached).
+*/
+async function fetchSavedLogs(client, deploymentId, store) {
 	try {
-		const stream = await client.logs.streamBuildLogs({ deploymentId });
-		for await (const event of stream) if (event.type === "status") {
-			const label = statusLabels[event.content] ?? event.content;
-			store.pushBuildLog(`[status] ${label}`);
-			if (event.content === "LIVE") store.pushStatus("Deploy concluído — serviço ativo!");
-			else if (event.content === "BUILD_FAILED" || event.content === "DEPLOY_FAILED") store.pushStatus(`Deploy falhou: ${label}`);
-		} else if (event.type === "log") {
-			const lines = event.content.split("\n");
-			for (const line of lines) {
-				const trimmed = line.trim();
-				if (!trimmed) continue;
-				if (isHiddenMessage(trimmed)) continue;
-				const parsed = parseBuildLine(trimmed);
-				let displayLine = null;
-				switch (parsed.kind) {
-					case "step":
-						displayLine = `[${parsed.stage} ${parsed.step}/${parsed.total}] ${parsed.command}`;
-						break;
-					case "cached":
-						displayLine = `#${parsed.stepNum} CACHED`;
-						break;
-					case "done":
-						displayLine = `#${parsed.stepNum} done ${parsed.duration}`;
-						break;
-					case "output":
-						displayLine = cleanDisplayLine(parsed.text);
-						break;
-					case "platform":
-						displayLine = cleanDisplayLine(parsed.message);
-						break;
-					case "other":
-						displayLine = cleanDisplayLine(parsed.text);
-						break;
-				}
-				if (displayLine) store.pushBuildLog(displayLine);
-			}
+		const logs = await client.logs.getBuildLogs({ deploymentId });
+		if (!logs.buildLogs) return;
+		for (const line of logs.buildLogs.split("\n")) {
+			const display = formatLogLine(line);
+			if (display) store.pushBuildLog(display);
 		}
-	} catch {}
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		store.pushBuildLog(`[stream] falha ao buscar logs salvos: ${msg}`);
+	}
 }
-function sleep$1(ms) {
-	return new Promise((resolve$1) => {
-		setTimeout(resolve$1, ms);
-	});
+function formatLogLine(line) {
+	const trimmed = line.trim();
+	if (!trimmed) return null;
+	if (isHiddenMessage(trimmed)) return null;
+	const parsed = parseBuildLine(trimmed);
+	switch (parsed.kind) {
+		case "step": return `[${parsed.stage} ${parsed.step}/${parsed.total}] ${parsed.command}`;
+		case "cached": return `#${parsed.stepNum} CACHED`;
+		case "done": return `#${parsed.stepNum} done ${parsed.duration}`;
+		case "output": return cleanDisplayLine(parsed.text);
+		case "platform": return cleanDisplayLine(parsed.message);
+		case "other": return cleanDisplayLine(parsed.text);
+	}
+}
+
+//#endregion
+//#region src/wizard/agent/permissions.ts
+const PACKAGE_MANAGERS = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun",
+	"npx",
+	"pnpx",
+	"yarnpkg"
+];
+const SAFE_SCRIPTS = [
+	"install",
+	"add",
+	"ci",
+	"build",
+	"tsc",
+	"typecheck",
+	"type-check",
+	"check-types",
+	"types",
+	"lint",
+	"format",
+	"test"
+];
+const READ_ONLY_COMMANDS = [
+	"ls",
+	"pwd",
+	"cat",
+	"head",
+	"tail",
+	"echo",
+	"which",
+	"node",
+	"env",
+	"printenv",
+	"find",
+	"test",
+	"stat"
+];
+const GIT_READ_SUBCOMMANDS = [
+	"status",
+	"log",
+	"diff",
+	"show",
+	"branch",
+	"remote",
+	"config",
+	"rev-parse",
+	"ls-files"
+];
+/**
+* Read-only subcommand allowlists for third-party platform CLIs.
+* The wizard inspects existing deploys (Vercel, Railway, Render, Fly, Cloudflare, AWS)
+* to migrate config to Veloz — it must never mutate those platforms.
+*/
+const PLATFORM_READ_SUBCOMMANDS = {
+	vercel: [
+		"env",
+		"project",
+		"projects",
+		"domains",
+		"teams",
+		"whoami",
+		"inspect",
+		"list",
+		"ls",
+		"logs"
+	],
+	vc: [
+		"env",
+		"project",
+		"projects",
+		"domains",
+		"teams",
+		"whoami",
+		"inspect",
+		"list",
+		"ls",
+		"logs"
+	],
+	railway: [
+		"status",
+		"variables",
+		"list",
+		"whoami",
+		"environment",
+		"service",
+		"logs"
+	],
+	render: [
+		"services",
+		"env-groups",
+		"list",
+		"whoami",
+		"logs"
+	],
+	fly: [
+		"status",
+		"apps",
+		"secrets",
+		"config",
+		"regions",
+		"info",
+		"logs",
+		"list",
+		"ips",
+		"volumes"
+	],
+	flyctl: [
+		"status",
+		"apps",
+		"secrets",
+		"config",
+		"regions",
+		"info",
+		"logs",
+		"list",
+		"ips",
+		"volumes"
+	],
+	wrangler: [
+		"whoami",
+		"secret",
+		"kv:namespace",
+		"kv",
+		"r2",
+		"d1",
+		"pages",
+		"tail",
+		"deployments"
+	],
+	aws: [
+		"s3",
+		"ec2",
+		"iam",
+		"sts",
+		"ecr",
+		"ecs",
+		"eks",
+		"lambda",
+		"rds",
+		"route53",
+		"cloudformation",
+		"ssm",
+		"secretsmanager"
+	]
+};
+const AWS_READ_VERBS_REGEX = /^(describe-|list-|get-|show-|head-|read-|search-|lookup-|scan$|query$|ls$|whoami$|info$|status$)/;
+const DANGEROUS_OPERATORS = /[;`$()]/;
+function matchesPackageManager(command) {
+	const parts = command.split(/\s+/);
+	if (parts.length === 0 || !PACKAGE_MANAGERS.includes(parts[0])) return false;
+	let scriptIndex = 1;
+	if (parts[scriptIndex] === "run" || parts[scriptIndex] === "exec") scriptIndex++;
+	const scriptPart = parts.slice(scriptIndex).join(" ");
+	return SAFE_SCRIPTS.some((s) => scriptPart.startsWith(s));
+}
+function matchesVeloz(command) {
+	return /^veloz(\s|$)/.test(command);
+}
+function matchesGitRead(command) {
+	const parts = command.split(/\s+/);
+	if (parts[0] !== "git" || !parts[1]) return false;
+	return GIT_READ_SUBCOMMANDS.includes(parts[1]);
+}
+function matchesReadOnly(command) {
+	const first = command.split(/\s+/)[0] ?? "";
+	return READ_ONLY_COMMANDS.includes(first);
+}
+/**
+* Match read-only subcommands on third-party platform CLIs.
+* e.g. `vercel env ls`, `fly secrets list`, `aws s3 ls`.
+*/
+function matchesPlatformRead(command) {
+	const parts = command.split(/\s+/);
+	const cli$1 = parts[0] ?? "";
+	const sub = parts[1] ?? "";
+	const allowed = PLATFORM_READ_SUBCOMMANDS[cli$1];
+	if (!allowed) return false;
+	if (!sub || sub.startsWith("-")) return true;
+	if (!allowed.includes(sub)) return false;
+	if (cli$1 === "aws") {
+		const verb = parts[2] ?? "";
+		if (!verb) return true;
+		return AWS_READ_VERBS_REGEX.test(verb);
+	}
+	return true;
+}
+function isAllowedBashCommand(command) {
+	return matchesVeloz(command) || matchesGitRead(command) || matchesPackageManager(command) || matchesReadOnly(command) || matchesPlatformRead(command);
+}
+function wizardCanUseTool(toolName, input) {
+	if (toolName.startsWith("veloz:") || toolName.startsWith("wizard-tools:") || toolName.startsWith("mcp__")) return {
+		behavior: "allow",
+		updatedInput: input
+	};
+	if (toolName !== "Bash") return {
+		behavior: "allow",
+		updatedInput: input
+	};
+	const command = (typeof input.command === "string" ? input.command : "").trim();
+	if (DANGEROUS_OPERATORS.test(command)) return {
+		behavior: "deny",
+		message: "Operadores shell como ; ` $ ( ) não são permitidos."
+	};
+	const normalized = command.replace(/\s*\d*>&\d+\s*/g, " ").trim();
+	const pipeMatch = normalized.match(/^(.+?)\s*\|\s*(tail|head)(\s+\S+)*\s*$/);
+	if (pipeMatch) {
+		const base = pipeMatch[1].trim();
+		if (/[|&]/.test(base)) return {
+			behavior: "deny",
+			message: "Múltiplos pipes não são permitidos. Apenas | tail/head."
+		};
+		if (isAllowedBashCommand(base)) return {
+			behavior: "allow",
+			updatedInput: input
+		};
+	}
+	if (/[|&]/.test(normalized)) return {
+		behavior: "deny",
+		message: "Pipes só são permitidos com tail/head para limitar saída."
+	};
+	if (isAllowedBashCommand(normalized)) return {
+		behavior: "allow",
+		updatedInput: input
+	};
+	return {
+		behavior: "deny",
+		message: "Comando não permitido. Use veloz, git (leitura), gerenciadores de pacote (install/build/typecheck/lint/test), ou comandos somente-leitura."
+	};
 }
 
 //#endregion
@@ -27881,6 +28666,15 @@ async function getSDKModule() {
 */
 async function runAgent(config) {
 	const { store, cwd } = config;
+	const logger = getSessionLogger();
+	logger.log("agent", "runAgent start", {
+		framework: config.framework,
+		frameworkLabel: config.frameworkLabel,
+		packageManager: config.packageManager,
+		userName: config.userName,
+		orgName: config.orgName,
+		hasNotes: Boolean(config.userNotes)
+	});
 	let attempt = 0;
 	let lastError = null;
 	const cleanupPromptFiles = () => {
@@ -27895,21 +28689,29 @@ async function runAgent(config) {
 	while (attempt <= MAX_RETRIES) {
 		const isRetry = attempt > 0;
 		if (isRetry) {
+			logger.log("agent", "retrying agent run", {
+				attempt: attempt + 1,
+				lastError
+			});
 			store.incrementRetry();
 			store.setAgentPhase("healing");
 			store.pushStatus(`Agente reiniciando — tentativa ${attempt + 1} de ${MAX_RETRIES + 1}...`);
 			store.pushAgentOutput(`--- Reiniciando agente (tentativa ${attempt + 1}) ---`);
 			await sleep(2e3);
 		}
+		logger.log("agent", `invoking runAgentOnce (attempt ${attempt + 1})`);
 		const result$2 = await runAgentOnce(config, isRetry, lastError);
+		logger.log("agent", "runAgentOnce returned", result$2);
 		if (result$2.success) return;
 		if (result$2.fatal) {
+			logger.log("agent", "fatal error — not retrying", { error: result$2.error });
 			store.failAgent(result$2.error ?? "Erro fatal");
 			return;
 		}
 		lastError = result$2.error ?? "Processo do agente encerrou inesperadamente";
 		attempt++;
 		if (attempt > MAX_RETRIES) {
+			logger.log("agent", "retries exhausted", { lastError });
 			store.failAgent(`O agente não conseguiu completar após ${MAX_RETRIES + 1} tentativas. Último erro: ${lastError}. Tente novamente com \`veloz init\` ou faça o deploy manualmente com \`veloz deploy\`.`);
 			return;
 		}
@@ -27921,19 +28723,27 @@ async function runAgent(config) {
 */
 async function runAgentOnce(config, isRetry, previousError) {
 	const { store, cwd } = config;
+	const logger = getSessionLogger();
 	resetBuildStreamState();
 	const query = (await getSDKModule()).query;
+	logger.log("agent", "SDK module loaded");
 	const promptCtx = {
 		cwd,
 		framework: config.framework,
 		frameworkLabel: config.frameworkLabel,
 		userName: config.userName,
 		orgName: config.orgName,
-		packageManager: config.packageManager
+		packageManager: config.packageManager,
+		userNotes: config.userNotes ?? null
 	};
 	const prompt$1 = isRetry ? assembleContinuationPrompt(promptCtx, previousError) : assemblePrompt(promptCtx);
+	logger.logPrompt(isRetry ? "continuation" : "initial", prompt$1, {
+		...promptCtx,
+		previousError: isRetry ? previousError : void 0
+	});
 	const commandments = getCommandments();
 	const wizardTools = createWizardToolsServer({ workingDirectory: cwd });
+	logger.log("agent", "wizard-tools MCP server config created");
 	const mcpServers = {
 		veloz: {
 			command: "npx",
@@ -28016,6 +28826,8 @@ async function runAgentOnce(config, isRetry, previousError) {
 					"TodoWrite",
 					"TodoRead"
 				],
+				disallowedTools: ["AskUserQuestion"],
+				canUseTool: (toolName, input) => Promise.resolve(wizardCanUseTool(toolName, input)),
 				systemPrompt: {
 					type: "preset",
 					preset: "claude_code",
@@ -28031,18 +28843,11 @@ async function runAgentOnce(config, isRetry, previousError) {
 						timeout: 30
 					}],
 					PostToolUse: [{
-						matcher: /^veloz:deploy$/,
+						matcher: /^(mcp__veloz__deploy|veloz:deploy)$/,
 						hooks: [() => {
 							if (store.session.agentPhase !== "deploying") {
 								store.setAgentPhase("deploying");
 								store.pushStatus("Deploy iniciado...");
-								if (!buildStreamStarted) {
-									buildStreamStarted = true;
-									startBuildLogStream({
-										store,
-										cwd
-									}).catch(() => {});
-								}
 							}
 							return {};
 						}]
@@ -28051,7 +28856,8 @@ async function runAgentOnce(config, isRetry, previousError) {
 			}
 		});
 		for await (const message of agentResponse) {
-			handleMessage(message, store, collectedText, cwd, (toolUseId, question) => {
+			logger.logSdkMessage(message);
+			handleMessage(message, store, collectedText, (toolUseId, question) => {
 				handleAskUserQuestion(store, cwd, toolUseId, question).then((response) => {
 					enqueueUserResponse({
 						type: "user",
@@ -28076,33 +28882,73 @@ async function runAgentOnce(config, isRetry, previousError) {
 			});
 			if (message.type === "result") {
 				if (message.subtype === "success" && !message.is_error) receivedSuccessResult = true;
+				logger.log("agent", "SDK result received", {
+					subtype: message.subtype,
+					is_error: message.is_error,
+					errors: message.errors
+				});
 				signalDone();
 			}
 		}
+		const outputText = collectedText.join("\n");
+		logger.log("agent", "agent stream ended", {
+			outputBytes: outputText.length,
+			receivedSuccessResult
+		});
+		const userCodeError = extractUserCodeError(outputText);
+		if (userCodeError) {
+			logger.log("agent", "user-code build failure detected", { error: userCodeError });
+			return {
+				success: false,
+				fatal: true,
+				error: userCodeError
+			};
+		}
+		const cancellation = extractCancellation(outputText);
+		if (cancellation) {
+			logger.log("agent", "user cancelled deploy", { summary: cancellation });
+			return {
+				success: false,
+				fatal: true,
+				error: cancellation
+			};
+		}
 		if (receivedSuccessResult) {
+			logger.log("agent", "deploy reported success");
 			store.pushStatus("Deploy concluído com sucesso!");
 			store.completeAgent();
 			return { success: true };
 		}
-		const outputText = collectedText.join("\n");
-		if (outputText.includes("API Error: 401") || outputText.includes("API Error: 403")) return {
-			success: false,
-			fatal: true,
-			error: "Erro de autenticação. Faça login novamente com `veloz login`."
-		};
-		if (outputText.includes("API Error:")) return {
-			success: false,
-			error: "Erro de API durante o deploy."
-		};
+		if (outputText.includes("API Error: 401") || outputText.includes("API Error: 403")) {
+			logger.log("agent", "auth error detected in output");
+			return {
+				success: false,
+				fatal: true,
+				error: "Erro de autenticação. Faça login novamente com `veloz login`."
+			};
+		}
+		if (outputText.includes("API Error:")) {
+			logger.log("agent", "API error detected in output");
+			return {
+				success: false,
+				error: "Erro de API durante o deploy."
+			};
+		}
+		logger.log("agent", "no explicit success signal — treating as success");
 		store.completeAgent();
 		return { success: true };
 	} catch (error) {
 		signalDone();
 		if (receivedSuccessResult) {
+			logger.log("agent", "post-success error ignored", { error: error instanceof Error ? error.message : String(error) });
 			store.completeAgent();
 			return { success: true };
 		}
 		const errorMessage = error instanceof Error ? error.message : "Erro desconhecido";
+		logger.log("agent", "agent threw", {
+			message: errorMessage,
+			stack: error instanceof Error ? error.stack : void 0
+		});
 		if (errorMessage.includes("ANTHROPIC_API_KEY") || errorMessage.includes("authentication")) return {
 			success: false,
 			fatal: true,
@@ -28117,6 +28963,25 @@ async function runAgentOnce(config, isRetry, previousError) {
 	}
 }
 /**
+* Extract a user-code build failure report emitted by the agent.
+* The agent is instructed to emit `[BUILD_FAILED_USER_CODE]` followed by
+* a detailed explanation (motivo, trecho dos logs, passos para corrigir).
+* Returns the detailed body, or null if the signal wasn't emitted.
+*/
+function extractUserCodeError(text) {
+	const match$3 = text.match(/\[BUILD_FAILED_USER_CODE\]\s*([\s\S]+?)(?:\n\[(?:STATUS|SUMMARY)\]|$)/);
+	if (!match$3?.[1]) return null;
+	const body = match$3[1].trim();
+	return body.length > 0 ? body : null;
+}
+/**
+* Extract a deploy cancellation summary emitted by the agent when the user
+* declined the pre-deploy confirmation prompt.
+*/
+function extractCancellation(text) {
+	return text.match(/\[SUMMARY\]\s*(Deploy cancelado[^\n]*)/i)?.[1]?.trim() ?? null;
+}
+/**
 * Build a continuation prompt for retries. Tells the agent to inspect
 * the current project state and continue from where the previous run left off.
 */
@@ -28148,13 +29013,31 @@ Antes de qualquer coisa, verifique o que já foi feito:
 - Framework: ${ctx.frameworkLabel}
 - Package manager: ${ctx.packageManager}
 - Autenticado como: ${ctx.userName} (org: ${ctx.orgName})
-
+${ctx.userNotes && ctx.userNotes.trim() ? `
+## Notas do Usuário (prioridade máxima — respeitar sempre)
+${ctx.userNotes.trim()}
+` : ""}
 ## Regras
 - Use TodoWrite para reportar progresso
 - NUNCA desista — diagnostique e corrija qualquer problema
 - Comunique-se em português (pt-BR)
 - Se algo falhar, leia os logs e tente uma abordagem diferente`;
 }
+/**
+* Normalize MCP tool names to the `server:tool` shorthand used in prompts.
+*
+* The Claude Agent SDK emits MCP tool_use blocks with names like
+* `mcp__wizard-tools__set_helper_content`. Our interception logic (and the
+* PostToolUse hook matcher) is written against the `wizard-tools:set_helper_content`
+* shorthand used throughout the prompt, so we translate here.
+*/
+function normalizeMcpToolName(name) {
+	if (!name.startsWith("mcp__")) return name;
+	const rest = name.slice(5);
+	const sep = rest.indexOf("__");
+	if (sep < 0) return name;
+	return `${rest.slice(0, sep)}:${rest.slice(sep + 2)}`;
+}
 /** Human-readable labels for common tools. */
 const TOOL_LABELS = {
 	Read: "Lendo arquivo",
@@ -28166,11 +29049,23 @@ const TOOL_LABELS = {
 	TodoWrite: "Atualizando tarefas",
 	TodoRead: "Lendo tarefas"
 };
-/** Track whether build log streaming has already been started for this run. */
-let buildStreamStarted = false;
+/** Tool-use IDs for in-flight deploy invocations — used to forward tool_result output. */
+const deployToolUseIds = /* @__PURE__ */ new Set();
+/** Deployment IDs we've already opened a log stream for in this run. */
+const streamedDeploymentIds = /* @__PURE__ */ new Set();
 /** Reset build stream state for a new agent run. */
 function resetBuildStreamState() {
-	buildStreamStarted = false;
+	deployToolUseIds.clear();
+	streamedDeploymentIds.clear();
+}
+/**
+* Flatten a tool_result `content` field into plain text.
+* The SDK may return a string or an array of text blocks.
+*/
+function extractToolResultText(content) {
+	if (!content) return "";
+	if (typeof content === "string") return content;
+	return content.filter((c) => c.type === "text" && typeof c.text === "string").map((c) => c.text).join("\n");
 }
 /**
 * Handle AskUserQuestion by showing the TUI overlay and waiting for response.
@@ -28200,7 +29095,8 @@ async function handleAskUserQuestion(store, cwd, toolUseId, question) {
 	store.clearAgentPrompt();
 	return "O usuário não respondeu (timeout).";
 }
-function handleMessage(message, store, collectedText, cwd, onAskUser) {
+function handleMessage(message, store, collectedText, onAskUser) {
+	const logger = getSessionLogger();
 	if (message.type === "assistant") {
 		const content = message.message?.content;
 		if (!Array.isArray(content)) return;
@@ -28231,31 +29127,34 @@ function handleMessage(message, store, collectedText, cwd, onAskUser) {
 				if (lastLine) store.pushAgentLog(lastLine.trim());
 			}
 			if (block.type === "tool_use" && block.name) {
-				let toolDescription = `[tool] ${TOOL_LABELS[block.name] ?? block.name}`;
-				if (block.name === "Read" && block.input?.file_path) toolDescription += `: ${block.input.file_path}`;
-				else if (block.name === "Write" && block.input?.file_path) toolDescription += `: ${block.input.file_path}`;
-				else if (block.name === "Edit" && block.input?.file_path) toolDescription += `: ${block.input.file_path}`;
-				else if (block.name === "Bash" && block.input?.command) {
+				const rawName = block.name;
+				const normalizedName = normalizeMcpToolName(rawName);
+				logger.logToolUse(normalizedName, block.input, block.id ?? null, { rawName });
+				let toolDescription = `[tool] ${TOOL_LABELS[rawName] ?? rawName}`;
+				if (rawName === "Read" && block.input?.file_path) toolDescription += `: ${block.input.file_path}`;
+				else if (rawName === "Write" && block.input?.file_path) toolDescription += `: ${block.input.file_path}`;
+				else if (rawName === "Edit" && block.input?.file_path) toolDescription += `: ${block.input.file_path}`;
+				else if (rawName === "Bash" && block.input?.command) {
 					const cmd = String(block.input.command);
 					toolDescription += `: ${cmd.length > 60 ? cmd.slice(0, 60) + "..." : cmd}`;
-				} else if (block.name === "Glob" && block.input?.pattern) toolDescription += `: ${block.input.pattern}`;
-				else if (block.name === "Grep" && block.input?.pattern) toolDescription += `: ${block.input.pattern}`;
-				if (block.name.startsWith("veloz:") || block.name.startsWith("wizard-tools:")) toolDescription = `[tool] Veloz: ${block.name.split(":")[1]}`;
-				const isDeployViaBash = block.name === "Bash" && typeof block.input?.command === "string" && /\bveloz\s+deploy\b/.test(block.input.command);
-				const isDeployViaMcp = block.name === "veloz:deploy";
-				if ((isDeployViaBash || isDeployViaMcp) && !buildStreamStarted) {
-					buildStreamStarted = true;
-					store.setAgentPhase("deploying");
-					store.pushStatus("Deploy iniciado — aguardando build...");
-					startBuildLogStream({
-						store,
-						cwd
-					}).catch(() => {});
+				} else if (rawName === "Glob" && block.input?.pattern) toolDescription += `: ${block.input.pattern}`;
+				else if (rawName === "Grep" && block.input?.pattern) toolDescription += `: ${block.input.pattern}`;
+				if (normalizedName.startsWith("veloz:") || normalizedName.startsWith("wizard-tools:")) toolDescription = `[tool] Veloz: ${normalizedName.split(":")[1]}`;
+				const bashCommand = rawName === "Bash" && typeof block.input?.command === "string" ? block.input.command : null;
+				const isDeployViaBash = bashCommand ? /\bveloz\s+deploy\b/.test(bashCommand) : false;
+				const isDeployViaMcp = normalizedName === "veloz:deploy";
+				const isDryRun = isDeployViaBash ? /--dry-run\b/.test(bashCommand ?? "") : isDeployViaMcp && block.input?.dryRun === true;
+				if ((isDeployViaBash || isDeployViaMcp) && !isDryRun) {
+					if (typeof block.id === "string") deployToolUseIds.add(block.id);
+					if (store.session.agentPhase !== "deploying") {
+						store.setAgentPhase("deploying");
+						store.pushStatus("Deploy iniciado — aguardando build...");
+					}
 				}
 				store.pushAgentOutput(toolDescription);
 				store.pushToolCall(toolDescription);
 				store.pushAgentLog(toolDescription.replace("[tool] ", ""));
-				if (block.name === "wizard-tools:prompt_user" && block.input?.question) store.setAgentPrompt({
+				if (normalizedName === "wizard-tools:prompt_user" && block.input?.question) store.setAgentPrompt({
 					id: `prompt-${Date.now()}`,
 					question: String(block.input.question),
 					hint: typeof block.input.hint === "string" ? block.input.hint : void 0,
@@ -28263,8 +29162,12 @@ function handleMessage(message, store, collectedText, cwd, onAskUser) {
 					options: Array.isArray(block.input.options) ? block.input.options : void 0,
 					envKey: typeof block.input.env_key === "string" ? block.input.env_key : void 0
 				});
-				if (block.name === "AskUserQuestion" && block.input?.question && onAskUser) onAskUser(typeof block.id === "string" ? block.id : `ask-${Date.now()}`, String(block.input.question));
-				if (block.name === "wizard-tools:set_helper_content" && block.input?.lines && Array.isArray(block.input.lines)) {
+				if (rawName === "AskUserQuestion" && onAskUser) {
+					const toolUseId = typeof block.id === "string" ? block.id : `ask-${Date.now()}`;
+					const questionText = extractAskUserQuestionText(block.input);
+					if (questionText) onAskUser(toolUseId, questionText);
+				}
+				if (normalizedName === "wizard-tools:set_helper_content" && block.input?.lines && Array.isArray(block.input.lines)) {
 					const title = typeof block.input.title === "string" ? block.input.title : null;
 					const lines = block.input.lines;
 					const helperLines = title ? [
@@ -28274,7 +29177,7 @@ function handleMessage(message, store, collectedText, cwd, onAskUser) {
 					] : lines;
 					store.setAgentHelper(helperLines);
 				}
-				if (block.name === "TodoWrite" && block.input?.todos && Array.isArray(block.input.todos)) {
+				if (rawName === "TodoWrite" && block.input?.todos && Array.isArray(block.input.todos)) {
 					const tasks = block.input.todos.map((todo, i) => ({
 						id: todo.id ?? `task-${i}`,
 						label: todo.content ?? `Tarefa ${i + 1}`,
@@ -28291,6 +29194,50 @@ function handleMessage(message, store, collectedText, cwd, onAskUser) {
 			}
 		}
 	}
+	if (message.type === "user") {
+		const content = message.message?.content;
+		if (!Array.isArray(content)) return;
+		for (const block of content) {
+			if (block.type !== "tool_result" || !block.tool_use_id) continue;
+			logger.logToolResult(block.tool_use_id, extractToolResultText(block.content), Boolean(block.is_error));
+			if (!deployToolUseIds.has(block.tool_use_id)) continue;
+			const text = extractToolResultText(block.content);
+			if (!text) continue;
+			let lines = [];
+			try {
+				const parsed = JSON.parse(text);
+				if (Array.isArray(parsed)) for (const entry of parsed) {
+					if (typeof entry?.message === "string") lines.push(entry.message);
+					const entryDeploymentId = entry?.data?.deploymentId;
+					if (entryDeploymentId && !streamedDeploymentIds.has(entryDeploymentId)) {
+						streamedDeploymentIds.add(entryDeploymentId);
+						store.setBuildDeploymentId(entryDeploymentId);
+						streamBuildLogs({
+							store,
+							deploymentId: entryDeploymentId
+						}).catch((err) => {
+							const msg = err instanceof Error ? err.message : String(err);
+							store.pushBuildLog(`[stream] ${msg}`);
+						});
+					}
+					const url = entry?.data?.urls?.[0];
+					if (url && !store.session.deployUrl) store.setDeployUrl(url);
+				}
+				else if (parsed && typeof parsed === "object" && "message" in parsed) {
+					const msg = parsed.message;
+					if (typeof msg === "string") lines = [msg];
+				} else lines = text.split("\n");
+			} catch {
+				lines = text.split("\n");
+			}
+			for (const raw of lines) {
+				const line = raw.trim();
+				if (!line) continue;
+				store.pushBuildLog(line);
+			}
+			deployToolUseIds.delete(block.tool_use_id);
+		}
+	}
 	if (message.type === "result") {
 		if (message.is_error && message.errors) for (const err of message.errors) {
 			store.pushAgentLog(`Erro: ${err}`);
@@ -28299,6 +29246,17 @@ function handleMessage(message, store, collectedText, cwd, onAskUser) {
 		}
 	}
 }
+function extractAskUserQuestionText(input) {
+	if (!input) return null;
+	const questions = input.questions;
+	if (Array.isArray(questions) && questions.length > 0) {
+		const first = questions[0];
+		if (first && typeof first.question === "string" && first.question.trim()) return first.question.trim();
+		if (first && typeof first.header === "string" && first.header.trim()) return first.header.trim();
+	}
+	if (typeof input.question === "string" && input.question.trim()) return input.question.trim();
+	return null;
+}
 function mapTodoStatus(status) {
 	switch (status) {
 		case "in_progress": return "in_progress";
@@ -28317,6 +29275,7 @@ function sleep(ms) {
 let Screen = /* @__PURE__ */ function(Screen$1) {
 	Screen$1["Intro"] = "intro";
 	Screen$1["Auth"] = "auth";
+	Screen$1["Notes"] = "notes";
 	Screen$1["Run"] = "run";
 	Screen$1["Outro"] = "outro";
 	return Screen$1;
@@ -28337,6 +29296,11 @@ const FLOW = [
 		show: (s) => s.authPhase !== "done",
 		isComplete: (s) => s.authPhase === "done"
 	},
+	{
+		screen: Screen.Notes,
+		show: () => true,
+		isComplete: (s) => s.notesConfirmed
+	},
 	{
 		screen: Screen.Run,
 		show: () => true,
@@ -28419,9 +29383,27 @@ const COPY = {
 	authTimeout: "Tempo esgotado. Tente novamente com `veloz login`.",
 	authError: "Erro na autenticação.",
 	authOrgSelect: "Selecione o workspace:",
+	authOrgCreateOption: "Criar novo workspace",
+	authOrgCreateTitle: "Criar novo workspace",
+	authOrgCreateQuestion: "Qual o nome do novo workspace?",
+	authOrgCreatePlaceholder: "Digite o nome e pressione Enter...",
+	authOrgCreateHint: "Enter para criar",
+	authOrgCreating: "Criando workspace...",
 	authNoOrg: "Você ainda não tem um workspace.",
 	authNoOrgHint: "Crie um workspace em app.onveloz.com para continuar.",
 	authOrgResolved: "Workspace:",
+	notesTitle: "Notas para o deploy",
+	notesQuestion: "Algo específico que o agente deve saber antes de começar? Deploy de todos os apps, apenas um serviço, flags customizadas, etc.",
+	notesExamplesLabel: "Exemplos:",
+	notesExamples: [
+		"Deploya só o apps/web",
+		"Usa o Dockerfile que está em apps/api",
+		"Ignora o build cache",
+		"Não cria banco — já existe"
+	],
+	notesPlaceholder: "Digite suas notas ou pressione Enter para pular...",
+	notesHint: "Enter para continuar · Esc para pular",
+	notesFooter: "Suas notas serão repassadas ao agente de deploy",
 	runTitle: "Configurando seu projeto...",
 	phaseLabels: {
 		idle: "Aguardando...",
@@ -28490,11 +29472,31 @@ const Icons = {
 	]
 };
 
+//#endregion
+//#region src/wizard/ui/hooks/useGatedInput.ts
+/**
+* useGatedInput — Wrapper around Ink's useInput that respects an
+* InputFocusContext. When an overlay (like the agent prompt) owns
+* input, screens rendered behind it should not react to keystrokes.
+*/
+const InputFocusContext = createContext({ active: true });
+function InputFocusProvider({ active: active$1, children }) {
+	return React.createElement(InputFocusContext.Provider, { value: { active: active$1 } }, children);
+}
+function useGatedInput(handler, options) {
+	const { active: active$1 } = useContext(InputFocusContext);
+	const callerActive = options?.isActive ?? true;
+	useInput(handler, {
+		...options,
+		isActive: callerActive && active$1
+	});
+}
+
 //#endregion
 //#region src/wizard/ui/primitives/PickerMenu.tsx
 function PickerMenu({ items, onSelect, onCancel }) {
 	const [cursor, setCursor] = useState(0);
-	useInput((_input, key) => {
+	useGatedInput((_input, key) => {
 		if (key.upArrow) setCursor((c) => c > 0 ? c - 1 : items.length - 1);
 		if (key.downArrow) setCursor((c) => c < items.length - 1 ? c + 1 : 0);
 		if (key.return) {
@@ -28533,34 +29535,9 @@ function PickerMenu({ items, onSelect, onCancel }) {
 	});
 }
 
-//#endregion
-//#region src/wizard/ui/hooks/useStdoutDimensions.ts
-/**
-* useStdoutDimensions — Returns [columns, rows] and re-renders on terminal resize.
-*/
-function useStdoutDimensions() {
-	const { stdout } = useStdout();
-	const [size, setSize] = useState(() => [stdout.columns || 80, stdout.rows || 24]);
-	useEffect(() => {
-		setSize([stdout.columns || 80, stdout.rows || 24]);
-		const stream = stdout;
-		if (typeof stream.on !== "function") return;
-		const onResize = () => {
-			const c = stdout.columns || 80;
-			const r = stdout.rows || 24;
-			if (c > 0 && r > 0) setSize([c, r]);
-		};
-		stream.on("resize", onResize);
-		return () => {
-			stream.off?.("resize", onResize);
-		};
-	}, [stdout]);
-	return size;
-}
-
 //#endregion
 //#region src/wizard/ui/primitives/ScreenLayout.tsx
-const version = "0.0.0-beta.30";
+const version = "0.0.0-beta.31";
 const LOGO_LINES = [
 	"██╗   ██╗███████╗██╗      ██████╗ ███████╗",
 	"██║   ██║██╔════╝██║     ██╔═══██╗╚══███╔╝",
@@ -28570,10 +29547,11 @@ const LOGO_LINES = [
 	"  ╚═══╝  ╚══════╝╚══════╝ ╚═════╝ ╚══════╝"
 ];
 function ScreenLayout({ children, footer }) {
-	const [, rows] = useStdoutDimensions();
 	return /* @__PURE__ */ jsxs(Box, {
 		flexDirection: "column",
-		height: rows,
+		flexGrow: 1,
+		flexShrink: 1,
+		minHeight: 0,
 		paddingX: 2,
 		paddingY: 1,
 		children: [
@@ -28594,13 +29572,6 @@ function ScreenLayout({ children, footer }) {
 			})] }),
 			/* @__PURE__ */ jsx(Box, {
 				marginTop: 1,
-				marginBottom: 1,
-				children: /* @__PURE__ */ jsx(Text, {
-					color: DIM_COLOR,
-					children: "─".repeat(50)
-				})
-			}),
-			/* @__PURE__ */ jsx(Box, {
 				flexDirection: "column",
 				flexGrow: 1,
 				flexShrink: 1,
@@ -28737,6 +29708,57 @@ function Spinner({ label }) {
 	}), label ? /* @__PURE__ */ jsxs(Text, { children: [" ", label] }) : null] });
 }
 
+//#endregion
+//#region src/wizard/session.ts
+/** Sentinel value used as a PickerMenu item to signal "create new workspace". */
+const CREATE_ORG_ACTION = "__create__";
+function createInitialSession() {
+	return {
+		isAuthenticated: false,
+		userName: "",
+		orgId: "",
+		orgName: "",
+		apiKey: "",
+		authPhase: "checking",
+		authDeviceCode: null,
+		authVerificationUrl: null,
+		availableOrgs: [],
+		selectedOrgId: null,
+		newOrgName: null,
+		orgCreateError: null,
+		detectedFramework: null,
+		detectedFrameworkLabel: null,
+		selectedFramework: null,
+		selectedFrameworkLabel: null,
+		packageManager: "npm",
+		gitRemote: null,
+		isMonorepo: false,
+		agentPhase: "idle",
+		agentTasks: [],
+		agentLogLines: [],
+		agentComplete: false,
+		agentError: null,
+		deployUrl: null,
+		retryCount: 0,
+		buildLogLines: [],
+		buildStreamActive: false,
+		buildDeploymentId: null,
+		statusMessages: [],
+		agentOutputLines: [],
+		toolCallLog: [],
+		learnCardBlockIdx: 0,
+		learnCardComplete: false,
+		agentHelperLines: [],
+		agentPrompt: null,
+		agentSummary: null,
+		userNotes: null,
+		notesConfirmed: false,
+		introConfirmed: false,
+		outroDismissed: false,
+		agentStartedAt: null
+	};
+}
+
 //#endregion
 //#region src/wizard/ui/screens/AuthScreen.tsx
 function AuthScreen({ store }) {
@@ -28773,6 +29795,8 @@ function AuthScreen({ store }) {
 			})
 		]
 	}) : null] });
+	if (session.authPhase === "org-creating") return /* @__PURE__ */ jsx(ScreenLayout, { children: /* @__PURE__ */ jsx(Spinner, { label: COPY.authOrgCreating }) });
+	if (session.authPhase === "org-create") return /* @__PURE__ */ jsx(OrgCreateForm, { store });
 	if (session.authPhase === "no-org") return /* @__PURE__ */ jsxs(ScreenLayout, { children: [/* @__PURE__ */ jsxs(Box, {
 		gap: 1,
 		children: [/* @__PURE__ */ jsx(Text, {
@@ -28792,10 +29816,13 @@ function AuthScreen({ store }) {
 		})]
 	})] });
 	if (session.authPhase === "org-select") {
-		const items = session.availableOrgs.map((org) => ({
+		const items = [...session.availableOrgs.map((org) => ({
 			label: `${org.name} (${org.slug})`,
 			value: org.id
-		}));
+		})), {
+			label: COPY.authOrgCreateOption,
+			value: CREATE_ORG_ACTION
+		}];
 		return /* @__PURE__ */ jsxs(ScreenLayout, { children: [/* @__PURE__ */ jsxs(Box, {
 			gap: 1,
 			children: [/* @__PURE__ */ jsx(Text, {
@@ -28812,7 +29839,10 @@ function AuthScreen({ store }) {
 				marginTop: 1,
 				children: /* @__PURE__ */ jsx(PickerMenu, {
 					items,
-					onSelect: (id) => store.selectOrg(id)
+					onSelect: (id) => {
+						if (id === CREATE_ORG_ACTION) store.requestOrgCreation();
+						else store.selectOrg(id);
+					}
 				})
 			})]
 		})] });
@@ -28841,6 +29871,140 @@ function AuthScreen({ store }) {
 	}) : null] });
 	return /* @__PURE__ */ jsx(ScreenLayout, { children: /* @__PURE__ */ jsx(Spinner, { label: COPY.authChecking }) });
 }
+function OrgCreateForm({ store }) {
+	const [value, setValue] = useState("");
+	const session = store.session;
+	useGatedInput((input, key) => {
+		if (key.return) {
+			if (value.trim().length > 0) store.submitNewOrgName(value.trim());
+			return;
+		}
+		if (key.backspace || key.delete) {
+			setValue((v) => v.slice(0, -1));
+			return;
+		}
+		if (input && !key.ctrl && !key.meta) setValue((v) => v + input);
+	});
+	return /* @__PURE__ */ jsxs(ScreenLayout, { children: [
+		/* @__PURE__ */ jsx(Text, {
+			color: BRAND_COLOR,
+			bold: true,
+			children: COPY.authOrgCreateTitle
+		}),
+		/* @__PURE__ */ jsx(Box, {
+			marginTop: 1,
+			children: /* @__PURE__ */ jsx(Text, {
+				wrap: "wrap",
+				children: COPY.authOrgCreateQuestion
+			})
+		}),
+		/* @__PURE__ */ jsx(Box, {
+			marginTop: 1,
+			children: /* @__PURE__ */ jsxs(Box, {
+				gap: 1,
+				children: [/* @__PURE__ */ jsx(Text, {
+					color: BRAND_COLOR,
+					children: Icons.triangleRight
+				}), /* @__PURE__ */ jsxs(Text, { children: [value || /* @__PURE__ */ jsx(Text, {
+					color: DIM_COLOR,
+					children: COPY.authOrgCreatePlaceholder
+				}), /* @__PURE__ */ jsx(Text, {
+					color: DIM_COLOR,
+					children: "▌"
+				})] })]
+			})
+		}),
+		session.orgCreateError ? /* @__PURE__ */ jsx(Box, {
+			marginTop: 1,
+			children: /* @__PURE__ */ jsx(Text, {
+				color: ERROR_COLOR,
+				children: session.orgCreateError
+			})
+		}) : null
+	] });
+}
+
+//#endregion
+//#region src/wizard/ui/screens/NotesScreen.tsx
+function NotesScreen({ store }) {
+	useSyncExternalStore(store.subscribe, store.getSnapshot);
+	const [value, setValue] = useState("");
+	useGatedInput((input, key) => {
+		if (key.return) {
+			store.confirmNotes(value);
+			return;
+		}
+		if (key.escape) {
+			store.confirmNotes(null);
+			return;
+		}
+		if (key.backspace || key.delete) {
+			setValue((v) => v.slice(0, -1));
+			return;
+		}
+		if (input && !key.ctrl && !key.meta) setValue((v) => v + input);
+	});
+	return /* @__PURE__ */ jsxs(ScreenLayout, {
+		footer: COPY.notesFooter,
+		children: [
+			/* @__PURE__ */ jsx(Text, {
+				color: BRAND_COLOR,
+				bold: true,
+				children: COPY.notesTitle
+			}),
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				children: /* @__PURE__ */ jsx(Text, {
+					wrap: "wrap",
+					children: COPY.notesQuestion
+				})
+			}),
+			/* @__PURE__ */ jsxs(Box, {
+				marginTop: 1,
+				flexDirection: "column",
+				children: [/* @__PURE__ */ jsx(Text, {
+					color: DIM_COLOR,
+					children: COPY.notesExamplesLabel
+				}), COPY.notesExamples.map((ex, i) => /* @__PURE__ */ jsxs(Box, {
+					gap: 1,
+					marginLeft: 2,
+					children: [/* @__PURE__ */ jsx(Text, {
+						color: DIM_COLOR,
+						children: Icons.bullet
+					}), /* @__PURE__ */ jsx(Text, {
+						color: DIM_COLOR,
+						children: ex
+					})]
+				}, i))]
+			}),
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				flexDirection: "column",
+				children: /* @__PURE__ */ jsxs(Box, {
+					gap: 1,
+					children: [/* @__PURE__ */ jsx(Text, {
+						color: BRAND_COLOR,
+						children: Icons.triangleRight
+					}), /* @__PURE__ */ jsxs(Text, { children: [value || /* @__PURE__ */ jsx(Text, {
+						color: DIM_COLOR,
+						children: COPY.notesPlaceholder
+					}), /* @__PURE__ */ jsx(Text, {
+						color: DIM_COLOR,
+						children: "▌"
+					})] })]
+				})
+			}),
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				children: /* @__PURE__ */ jsx(Text, {
+					color: SUCCESS_COLOR,
+					dimColor: true,
+					children: COPY.notesHint
+				})
+			})
+		]
+	});
+}
 
 //#endregion
 //#region src/wizard/ui/primitives/text-helpers.ts
@@ -28976,7 +30140,7 @@ const TEXT_REVEAL_MODE_DEFAULTS = {
 	[TextRevealMode.WordByWord]: 240,
 	[TextRevealMode.SentenceFade]: 2400
 };
-function TextBlock({ text, active, completed, onComplete, mode, bullet, animationInterval, sentenceInterval = 1600, maxHeight, availableWidth }) {
+function TextBlock({ text, active: active$1, completed, onComplete, mode, bullet, animationInterval, sentenceInterval = 1600, maxHeight, availableWidth }) {
 	const speed = animationInterval ?? TEXT_REVEAL_MODE_DEFAULTS[mode];
 	const [animIdx, setAnimIdx] = useState(mode === TextRevealMode.SentenceFade ? 1 : 0);
 	const resetRef = useRef(0);
@@ -28992,14 +30156,14 @@ function TextBlock({ text, active, completed, onComplete, mode, bullet, animatio
 	const sentWordEnds = useMemo(() => sentenceEndWords(text), [text]);
 	const isDone$2 = mode === TextRevealMode.Typewriter ? animIdx >= text.length : mode === TextRevealMode.WordByWord ? animIdx >= words.length : animIdx >= sentences.length;
 	useEffect(() => {
-		if (isDone$2 && active) onComplete();
+		if (isDone$2 && active$1) onComplete();
 	}, [
 		isDone$2,
-		active,
+		active$1,
 		onComplete
 	]);
 	useEffect(() => {
-		if (!active || isDone$2) return;
+		if (!active$1 || isDone$2) return;
 		const token = resetRef.current;
 		const isFirstTick = animIdx === 0;
 		let delay$2 = isFirstTick ? 0 : speed;
@@ -29011,7 +30175,7 @@ function TextBlock({ text, active, completed, onComplete, mode, bullet, animatio
 		}, delay$2);
 		return () => clearTimeout(timer);
 	}, [
-		active,
+		active$1,
 		mode,
 		animIdx,
 		isDone$2,
@@ -29053,22 +30217,22 @@ function TextBlock({ text, active, completed, onComplete, mode, bullet, animatio
 * LinesBlock — Reveals ReactNode lines one at a time.
 * Each line can contain colors, bold, ASCII art — any JSX.
 */
-function LinesBlock({ lines, interval, active, completed, onComplete, maxHeight }) {
+function LinesBlock({ lines, interval, active: active$1, completed, onComplete, maxHeight }) {
 	const [revealedCount, setRevealedCount] = useState(0);
 	useEffect(() => {
-		if (!active || revealedCount >= lines.length) return;
+		if (!active$1 || revealedCount >= lines.length) return;
 		const timer = setTimeout(() => setRevealedCount((c) => c + 1), revealedCount === 0 ? 0 : interval);
 		return () => clearTimeout(timer);
 	}, [
-		active,
+		active$1,
 		revealedCount,
 		lines.length,
 		interval
 	]);
 	useEffect(() => {
-		if (active && revealedCount >= lines.length) onComplete();
+		if (active$1 && revealedCount >= lines.length) onComplete();
 	}, [
-		active,
+		active$1,
 		revealedCount,
 		lines.length,
 		onComplete
@@ -29092,10 +30256,10 @@ function LinesBlock({ lines, interval, active, completed, onComplete, maxHeight
 /**
 * NodeBlock — Renders static JSX, fires onComplete immediately.
 */
-function NodeBlock({ content, active, completed, onComplete }) {
+function NodeBlock({ content, active: active$1, completed, onComplete }) {
 	useEffect(() => {
-		if (active) onComplete();
-	}, [active, onComplete]);
+		if (active$1) onComplete();
+	}, [active$1, onComplete]);
 	if (completed) return /* @__PURE__ */ jsx(Text, {
 		dimColor: true,
 		children: content
@@ -29187,7 +30351,7 @@ function ContentSequencer({ blocks, mode, maxHeight, availableWidth, bullet, ani
 			if (i < clearFloor) return null;
 			if (isClearBlock(block) && i < activeIdx) return null;
 			if (i < visibleStart || i > visibleEnd) return null;
-			const active = i === activeIdx;
+			const active$1 = i === activeIdx;
 			const completed = i < activeIdx || skipCurrent && i === activeIdx;
 			if (completed && isObjectBlock(block)) {
 				const isText = typeof block.content === "string";
@@ -29198,7 +30362,7 @@ function ContentSequencer({ blocks, mode, maxHeight, availableWidth, bullet, ani
 				marginBottom: 1,
 				children: /* @__PURE__ */ jsx(BlockRenderer, {
 					block,
-					active,
+					active: active$1,
 					completed,
 					onComplete: () => handleComplete(i),
 					mode,
@@ -29213,19 +30377,19 @@ function ContentSequencer({ blocks, mode, maxHeight, availableWidth, bullet, ani
 		})
 	});
 }
-function BlockRenderer({ block, active, completed, onComplete, mode, bullet, animationInterval, sentenceInterval, lineInterval, maxHeight, availableWidth }) {
+function BlockRenderer({ block, active: active$1, completed, onComplete, mode, bullet, animationInterval, sentenceInterval, lineInterval, maxHeight, availableWidth }) {
 	const isClear = isClearBlock(block);
 	useEffect(() => {
-		if (isClear && active) onComplete();
+		if (isClear && active$1) onComplete();
 	}, [
 		isClear,
-		active,
+		active$1,
 		onComplete
 	]);
 	if (isClear) return null;
 	if (typeof block === "string") return /* @__PURE__ */ jsx(TextBlock, {
 		text: block,
-		active,
+		active: active$1,
 		completed,
 		onComplete,
 		mode,
@@ -29238,14 +30402,14 @@ function BlockRenderer({ block, active, completed, onComplete, mode, bullet, ani
 	if (isLinesBlock(block)) return /* @__PURE__ */ jsx(LinesBlock, {
 		lines: block.lines,
 		interval: block.interval ?? lineInterval,
-		active,
+		active: active$1,
 		completed,
 		onComplete,
 		maxHeight
 	});
 	if (typeof block.content === "string") return /* @__PURE__ */ jsx(TextBlock, {
 		text: block.content,
-		active,
+		active: active$1,
 		completed,
 		onComplete,
 		mode: block.mode ?? mode,
@@ -29257,12 +30421,37 @@ function BlockRenderer({ block, active, completed, onComplete, mode, bullet, ani
 	});
 	return /* @__PURE__ */ jsx(NodeBlock, {
 		content: block.content,
-		active,
+		active: active$1,
 		completed,
 		onComplete
 	});
 }
 
+//#endregion
+//#region src/wizard/ui/hooks/useStdoutDimensions.ts
+/**
+* useStdoutDimensions — Returns [columns, rows] and re-renders on terminal resize.
+*/
+function useStdoutDimensions() {
+	const { stdout } = useStdout();
+	const [size, setSize] = useState(() => [stdout.columns || 80, stdout.rows || 24]);
+	useEffect(() => {
+		setSize([stdout.columns || 80, stdout.rows || 24]);
+		const stream = stdout;
+		if (typeof stream.on !== "function") return;
+		const onResize = () => {
+			const c = stdout.columns || 80;
+			const r = stdout.rows || 24;
+			if (c > 0 && r > 0) setSize([c, r]);
+		};
+		stream.on("resize", onResize);
+		return () => {
+			stream.off?.("resize", onResize);
+		};
+	}, [stdout]);
+	return size;
+}
+
 //#endregion
 //#region src/wizard/ui/components/LearnCard.tsx
 /**
@@ -29301,7 +30490,7 @@ const DEPLOY_PIPELINE = {
 			/* @__PURE__ */ jsx(Text, { children: "veloz deploy" }),
 			/* @__PURE__ */ jsx(Text, {
 				color: DIM_COLOR,
-				children: "              │"
+				children: "             │"
 			})
 		] }, "deploy-cmd"),
 		/* @__PURE__ */ jsxs(Text, { children: [/* @__PURE__ */ jsx(Text, {
@@ -29309,7 +30498,7 @@ const DEPLOY_PIPELINE = {
 			children: "  │   ↓"
 		}), /* @__PURE__ */ jsx(Text, {
 			color: DIM_COLOR,
-			children: "                         │"
+			children: "                          │"
 		})] }, "arrow-1"),
 		/* @__PURE__ */ jsxs(Text, { children: [
 			/* @__PURE__ */ jsx(Text, {
@@ -29337,7 +30526,7 @@ const DEPLOY_PIPELINE = {
 			}),
 			/* @__PURE__ */ jsx(Text, {
 				color: DIM_COLOR,
-				children: "        │"
+				children: "         │"
 			})
 		] }, "upload-desc"),
 		/* @__PURE__ */ jsxs(Text, { children: [/* @__PURE__ */ jsx(Text, {
@@ -29345,7 +30534,7 @@ const DEPLOY_PIPELINE = {
 			children: "  │   ↓"
 		}), /* @__PURE__ */ jsx(Text, {
 			color: DIM_COLOR,
-			children: "                         │"
+			children: "                          │"
 		})] }, "arrow-2"),
 		/* @__PURE__ */ jsxs(Text, { children: [
 			/* @__PURE__ */ jsx(Text, {
@@ -29373,7 +30562,7 @@ const DEPLOY_PIPELINE = {
 			}),
 			/* @__PURE__ */ jsx(Text, {
 				color: DIM_COLOR,
-				children: "    │"
+				children: "     │"
 			})
 		] }, "build-deps"),
 		/* @__PURE__ */ jsxs(Text, { children: [
@@ -29387,7 +30576,7 @@ const DEPLOY_PIPELINE = {
 			}),
 			/* @__PURE__ */ jsx(Text, {
 				color: DIM_COLOR,
-				children: "           │"
+				children: "            │"
 			})
 		] }, "build-exec"),
 		/* @__PURE__ */ jsxs(Text, { children: [/* @__PURE__ */ jsx(Text, {
@@ -29395,7 +30584,7 @@ const DEPLOY_PIPELINE = {
 			children: "  │   ↓"
 		}), /* @__PURE__ */ jsx(Text, {
 			color: DIM_COLOR,
-			children: "                         │"
+			children: "                          │"
 		})] }, "arrow-3"),
 		/* @__PURE__ */ jsxs(Text, { children: [
 			/* @__PURE__ */ jsx(Text, {
@@ -29423,7 +30612,7 @@ const DEPLOY_PIPELINE = {
 			}),
 			/* @__PURE__ */ jsx(Text, {
 				color: DIM_COLOR,
-				children: "             │"
+				children: "              │"
 			})
 		] }, "url-label"),
 		/* @__PURE__ */ jsx(Text, {
@@ -29806,73 +30995,159 @@ function RunScreen({ store }) {
 	const topRows = Math.max(6, Math.floor(contentRows * .6));
 	const bottomRows = Math.max(4, contentRows - topRows);
 	const isNarrow = columns < 80;
-	const helperContent = session.agentHelperLines.length > 0 ? /* @__PURE__ */ jsx(AgentHelperPane, { lines: session.agentHelperLines }) : session.learnCardComplete ? /* @__PURE__ */ jsx(TipsCard, {}) : /* @__PURE__ */ jsx(LearnCard, {
+	const helperContent = session.learnCardComplete ? /* @__PURE__ */ jsx(TipsCard, {}) : /* @__PURE__ */ jsx(LearnCard, {
 		store,
 		onComplete: () => store.setLearnCardComplete()
 	});
-	const rightPane = /* @__PURE__ */ jsx(TasksPane, { store });
-	const showBuildLogs = session.buildLogLines.length > 0 && (session.agentPhase === "deploying" || session.buildStreamActive);
-	const visibleStatus = session.statusMessages.slice(-5);
-	return /* @__PURE__ */ jsxs(ScreenLayout, { children: [
-		/* @__PURE__ */ jsx(Box, {
+	const hasAgentHelper = session.agentHelperLines.length > 0;
+	const rightPane = /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		flexGrow: 1,
+		overflow: "hidden",
+		children: [/* @__PURE__ */ jsx(TasksPane, { store }), hasAgentHelper ? /* @__PURE__ */ jsx(Box, {
+			marginTop: 1,
 			flexGrow: 1,
-			flexShrink: 1,
-			height: topRows,
-			children: isNarrow ? rightPane : /* @__PURE__ */ jsxs(Box, {
-				flexDirection: "row",
-				flexGrow: 1,
-				gap: 2,
-				children: [/* @__PURE__ */ jsxs(Box, {
-					width: "50%",
-					flexDirection: "column",
-					overflow: "hidden",
-					children: [visibleStatus.length > 0 ? /* @__PURE__ */ jsx(Box, {
-						flexDirection: "column",
-						paddingX: 1,
-						marginBottom: 1,
-						children: visibleStatus.map((msg, i, arr) => {
-							const isCurrent = i === arr.length - 1;
-							return /* @__PURE__ */ jsxs(Text, {
-								color: DIM_COLOR,
-								dimColor: !isCurrent,
-								children: [
-									isCurrent ? Icons.diamond : Icons.bullet,
-									" ",
-									msg
-								]
-							}, i);
-						})
-					}) : null, helperContent]
-				}), /* @__PURE__ */ jsx(Box, {
-					width: "50%",
+			overflow: "hidden",
+			children: /* @__PURE__ */ jsx(AgentHelperPane, { lines: session.agentHelperLines })
+		}) : null]
+	});
+	const [activeTab, setActiveTab] = useState("agent");
+	const [seenBuildCount, setSeenBuildCount] = useState(0);
+	const unreadBuildLogs = activeTab !== "build" && session.buildLogLines.length > seenBuildCount;
+	useEffect(() => {
+		if (activeTab === "build") setSeenBuildCount(session.buildLogLines.length);
+	}, [activeTab, session.buildLogLines.length]);
+	useGatedInput((_input, key) => {
+		if (key.tab) setActiveTab((prev) => prev === "agent" ? "build" : "agent");
+	});
+	const statusMessages = session.statusMessages;
+	return /* @__PURE__ */ jsxs(ScreenLayout, { children: [/* @__PURE__ */ jsx(Box, {
+		flexGrow: 1,
+		flexShrink: 1,
+		height: topRows,
+		children: isNarrow ? /* @__PURE__ */ jsx(PaneBox, {
+			title: "Tarefas",
+			flexGrow: 1,
+			children: rightPane
+		}) : /* @__PURE__ */ jsxs(Box, {
+			flexDirection: "row",
+			flexGrow: 1,
+			gap: 1,
+			children: [/* @__PURE__ */ jsxs(PaneBox, {
+				width: "50%",
+				children: [/* @__PURE__ */ jsx(Box, {
 					flexDirection: "column",
+					flexGrow: 1,
+					flexShrink: 1,
 					overflow: "hidden",
-					children: rightPane
-				})]
-			})
-		}),
-		/* @__PURE__ */ jsx(Box, {
-			paddingX: 1,
-			children: /* @__PURE__ */ jsx(Text, {
-				color: DIM_COLOR,
-				children: "─".repeat(Math.min(columns - 8, 120))
+					children: helperContent
+				}), statusMessages.length > 0 ? /* @__PURE__ */ jsx(Box, {
+					marginTop: 1,
+					flexShrink: 0,
+					children: /* @__PURE__ */ jsx(ScrollableStatus, {
+						messages: statusMessages,
+						maxLines: 5
+					})
+				}) : null]
+			}), /* @__PURE__ */ jsx(PaneBox, {
+				title: "Tarefas",
+				width: "50%",
+				children: rightPane
+			})]
+		})
+	}), /* @__PURE__ */ jsx(Box, {
+		marginTop: 1,
+		flexGrow: 0,
+		flexShrink: 0,
+		height: bottomRows,
+		children: /* @__PURE__ */ jsx(PaneBox, {
+			flexGrow: 1,
+			header: /* @__PURE__ */ jsx(TabBar, {
+				active: activeTab,
+				tabs: [{
+					id: "agent",
+					label: "Agente"
+				}, {
+					id: "build",
+					label: "Build",
+					badge: unreadBuildLogs
+				}]
+			}),
+			children: activeTab === "build" ? /* @__PURE__ */ jsx(BuildLogPane, {
+				buildLogLines: session.buildLogLines,
+				maxLines: bottomRows - 3
+			}) : /* @__PURE__ */ jsx(ScrollableLogPane, {
+				lines: session.agentOutputLines,
+				maxLines: bottomRows - 2,
+				isComplete: session.agentComplete
 			})
-		}),
-		showBuildLogs ? /* @__PURE__ */ jsx(Box, {
+		})
+	})] });
+}
+function PaneBox({ title, header, children, width, flexGrow }) {
+	const headerNode = header ?? (title ? /* @__PURE__ */ jsx(Text, {
+		bold: true,
+		color: ACCENT_COLOR,
+		children: title
+	}) : null);
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		width,
+		height: "100%",
+		flexGrow,
+		borderStyle: "single",
+		borderColor: DIM_COLOR,
+		paddingX: 1,
+		overflow: "hidden",
+		children: [headerNode ? /* @__PURE__ */ jsx(Box, {
+			marginBottom: 1,
+			children: headerNode
+		}) : null, /* @__PURE__ */ jsx(Box, {
 			flexDirection: "column",
-			height: bottomRows,
-			paddingX: 1,
+			flexGrow: 1,
 			overflow: "hidden",
-			children: /* @__PURE__ */ jsx(BuildLogPane, {
-				buildLogLines: session.buildLogLines,
-				maxLines: bottomRows - 1
-			})
-		}) : /* @__PURE__ */ jsx(ScrollableLogPane, {
-			lines: session.agentOutputLines,
-			maxLines: bottomRows,
-			isComplete: session.agentComplete
+			children
+		})]
+	});
+}
+function TabBar({ tabs, active: active$1 }) {
+	const [pulse, setPulse] = useState(true);
+	useEffect(() => {
+		if (!tabs.some((t) => t.badge && t.id !== active$1)) {
+			setPulse(true);
+			return;
+		}
+		const id = setInterval(() => setPulse((p) => !p), 500);
+		return () => clearInterval(id);
+	}, [tabs, active$1]);
+	return /* @__PURE__ */ jsx(Box, {
+		flexDirection: "row",
+		gap: 2,
+		children: tabs.map((tab, i) => {
+			const isActive = tab.id === active$1;
+			const flashing = Boolean(tab.badge) && !isActive;
+			return /* @__PURE__ */ jsxs(Box, {
+				flexDirection: "row",
+				children: [
+					/* @__PURE__ */ jsxs(Text, {
+						bold: true,
+						color: isActive ? ACCENT_COLOR : flashing ? pulse ? BRAND_COLOR : ACCENT_COLOR : DIM_COLOR,
+						dimColor: !isActive && !flashing,
+						children: [isActive ? "● " : flashing ? pulse ? "◆ " : "◇ " : "○ ", tab.label]
+					}),
+					flashing ? /* @__PURE__ */ jsx(Text, {
+						bold: true,
+						color: pulse ? BRAND_COLOR : ACCENT_COLOR,
+						children: pulse ? " NOVO" : " ●"
+					}) : null,
+					i === tabs.length - 1 ? /* @__PURE__ */ jsxs(Text, {
+						dimColor: true,
+						children: ["  ", "Tab para alternar"]
+					}) : null
+				]
+			}, tab.id);
 		})
-	] });
+	});
 }
 function TaskIcon({ status }) {
 	switch (status) {
@@ -29912,57 +31187,94 @@ function TasksPane({ store }) {
 	const tasks = session.agentTasks;
 	const completedCount = tasks.filter((t) => t.status === "completed").length;
 	const totalCount = tasks.length;
+	const progressText = totalCount > 0 && !session.agentComplete ? completedCount < totalCount ? `${completedCount}/${totalCount}` : "…" : null;
 	return /* @__PURE__ */ jsxs(Box, {
 		flexDirection: "column",
-		paddingX: 1,
-		flexGrow: 1,
-		children: [
-			/* @__PURE__ */ jsxs(Box, {
-				gap: 1,
-				children: [!session.agentComplete ? /* @__PURE__ */ jsx(Spinner, { label: phaseLabel }) : /* @__PURE__ */ jsx(Text, {
+		flexShrink: 0,
+		children: [/* @__PURE__ */ jsxs(Box, {
+			gap: 1,
+			children: [
+				!session.agentComplete ? /* @__PURE__ */ jsx(Spinner, { label: phaseLabel }) : /* @__PURE__ */ jsx(Text, {
 					bold: true,
 					color: session.agentError ? ERROR_COLOR : SUCCESS_COLOR,
 					children: phaseLabel
-				}), /* @__PURE__ */ jsxs(Text, {
+				}),
+				/* @__PURE__ */ jsxs(Text, {
 					dimColor: true,
 					children: [
 						"(",
 						elapsed,
 						")"
 					]
-				})]
-			}),
-			/* @__PURE__ */ jsx(Box, { height: 1 }),
-			tasks.length > 0 ? /* @__PURE__ */ jsxs(Box, {
-				flexDirection: "column",
-				children: [tasks.map((task, i) => {
-					const label = task.status === "in_progress" && task.activeForm ? task.activeForm : task.label;
-					return /* @__PURE__ */ jsxs(Box, {
-						gap: 1,
-						children: [/* @__PURE__ */ jsx(TaskIcon, { status: task.status }), /* @__PURE__ */ jsx(Text, {
-							dimColor: task.status === "pending",
-							children: label
-						})]
-					}, task.id || i);
-				}), totalCount > 0 && !session.agentComplete ? /* @__PURE__ */ jsx(Box, {
-					marginTop: 1,
-					children: /* @__PURE__ */ jsx(Text, {
-						dimColor: true,
-						children: completedCount < totalCount ? `Progresso: ${completedCount}/${totalCount}` : "Finalizando..."
-					})
-				}) : null]
-			}) : !session.agentComplete ? /* @__PURE__ */ jsx(Text, {
-				dimColor: true,
-				children: "Analisando projeto..."
-			}) : null,
-			session.retryCount > 0 ? /* @__PURE__ */ jsx(Box, {
-				marginTop: 1,
-				children: /* @__PURE__ */ jsxs(Text, {
+				}),
+				progressText ? /* @__PURE__ */ jsxs(Text, {
+					dimColor: true,
+					children: ["· ", progressText]
+				}) : null,
+				session.retryCount > 0 ? /* @__PURE__ */ jsxs(Text, {
 					color: BRAND_COLOR,
-					children: ["Tentativa ", session.retryCount + 1]
-				})
-			}) : null
-		]
+					children: ["· tentativa ", session.retryCount + 1]
+				}) : null
+			]
+		}), tasks.length > 0 ? /* @__PURE__ */ jsx(Box, {
+			flexDirection: "column",
+			marginTop: 1,
+			children: tasks.map((task, i) => {
+				const label = task.status === "in_progress" && task.activeForm ? task.activeForm : task.label;
+				return /* @__PURE__ */ jsxs(Box, {
+					gap: 1,
+					children: [/* @__PURE__ */ jsx(TaskIcon, { status: task.status }), /* @__PURE__ */ jsx(Text, {
+						dimColor: task.status === "pending",
+						wrap: "truncate",
+						children: label
+					})]
+				}, task.id || i);
+			})
+		}) : null]
+	});
+}
+function ScrollableStatus({ messages, maxLines }) {
+	const [scrollOffset, setScrollOffset] = useState(0);
+	const [userScrolled, setUserScrolled] = useState(false);
+	useEffect(() => {
+		if (!userScrolled) setScrollOffset(0);
+	}, [messages.length, userScrolled]);
+	useGatedInput((_input, key) => {
+		if (key.pageUp) {
+			setUserScrolled(true);
+			setScrollOffset((prev) => Math.min(prev + 3, Math.max(0, messages.length - maxLines)));
+		}
+		if (key.pageDown) setScrollOffset((prev) => {
+			const next = Math.max(0, prev - 3);
+			if (next === 0) setUserScrolled(false);
+			return next;
+		});
+	});
+	const endIdx = messages.length - scrollOffset;
+	const startIdx = Math.max(0, endIdx - maxLines);
+	const visible = messages.slice(startIdx, endIdx);
+	const isAtBottom = scrollOffset === 0;
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		children: [!isAtBottom ? /* @__PURE__ */ jsxs(Text, {
+			dimColor: true,
+			children: [
+				"PgUp/PgDn · ",
+				scrollOffset,
+				" abaixo"
+			]
+		}) : null, visible.map((msg, i) => {
+			const isCurrent = i === visible.length - 1 && isAtBottom;
+			return /* @__PURE__ */ jsxs(Text, {
+				color: DIM_COLOR,
+				dimColor: !isCurrent,
+				children: [
+					isCurrent ? Icons.diamond : Icons.bullet,
+					" ",
+					msg
+				]
+			}, `${startIdx + i}`);
+		})]
 	});
 }
 function ScrollableLogPane({ lines, maxLines, isComplete }) {
@@ -29975,7 +31287,7 @@ function ScrollableLogPane({ lines, maxLines, isComplete }) {
 	useEffect(() => {
 		if (userScrolled && scrollOffset === 0) setUserScrolled(false);
 	}, [scrollOffset, userScrolled]);
-	useInput((_input, key) => {
+	useGatedInput((_input, key) => {
 		if (key.upArrow) {
 			setUserScrolled(true);
 			setScrollOffset((prev) => Math.min(prev + 3, Math.max(0, lines.length - contentLines)));
@@ -29992,23 +31304,18 @@ function ScrollableLogPane({ lines, maxLines, isComplete }) {
 	return /* @__PURE__ */ jsxs(Box, {
 		flexDirection: "column",
 		height: maxLines,
-		paddingX: 1,
 		overflow: "hidden",
-		children: [/* @__PURE__ */ jsxs(Box, {
-			gap: 1,
-			children: [/* @__PURE__ */ jsx(Text, {
-				bold: true,
-				color: ACCENT_COLOR,
-				children: "Agente"
-			}), !(scrollOffset === 0) ? /* @__PURE__ */ jsxs(Text, {
+		children: [!(scrollOffset === 0) ? /* @__PURE__ */ jsx(Box, {
+			marginBottom: 1,
+			children: /* @__PURE__ */ jsxs(Text, {
 				dimColor: true,
 				children: [
 					"↑↓ rolar · ",
 					scrollOffset,
 					" linhas abaixo"
 				]
-			}) : null]
-		}), visibleLines.length > 0 ? visibleLines.map((line, i) => {
+			})
+		}) : null, visibleLines.length > 0 ? visibleLines.map((line, i) => {
 			if (line.startsWith("[tool] ")) return /* @__PURE__ */ jsx(Text, {
 				color: CYAN_COLOR,
 				wrap: "wrap",
@@ -30026,12 +31333,37 @@ function ScrollableLogPane({ lines, maxLines, isComplete }) {
 	});
 }
 function BuildLogPane({ buildLogLines, maxLines }) {
-	const recentLines = buildLogLines.slice(-maxLines);
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Text, {
-		bold: true,
-		color: CYAN_COLOR,
-		children: "BUILD"
-	}), recentLines.map((line, i) => {
+	const contentLines = Math.max(1, maxLines - 1);
+	const [scrollOffset, setScrollOffset] = useState(0);
+	const [userScrolled, setUserScrolled] = useState(false);
+	useEffect(() => {
+		if (!userScrolled) setScrollOffset(0);
+	}, [buildLogLines.length, userScrolled]);
+	useGatedInput((_input, key) => {
+		if (key.upArrow) {
+			setUserScrolled(true);
+			setScrollOffset((prev) => Math.min(prev + 3, Math.max(0, buildLogLines.length - contentLines)));
+		}
+		if (key.downArrow) setScrollOffset((prev) => {
+			const next = Math.max(0, prev - 3);
+			if (next === 0) setUserScrolled(false);
+			return next;
+		});
+	});
+	const endIdx = buildLogLines.length - scrollOffset;
+	const startIdx = Math.max(0, endIdx - contentLines);
+	const recentLines = buildLogLines.slice(startIdx, endIdx);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [!(scrollOffset === 0) ? /* @__PURE__ */ jsx(Box, {
+		marginBottom: 1,
+		children: /* @__PURE__ */ jsxs(Text, {
+			dimColor: true,
+			children: [
+				"↑↓ rolar · ",
+				scrollOffset,
+				" linhas abaixo"
+			]
+		})
+	}) : null, recentLines.map((line, i) => {
 		if (line.startsWith("[status] ")) {
 			const statusText = line.slice(9);
 			return /* @__PURE__ */ jsxs(Text, {
@@ -30108,10 +31440,12 @@ function AgentHelperPane({ lines }) {
 			if (i === 0 && line.trim()) return /* @__PURE__ */ jsx(Text, {
 				bold: true,
 				color: ACCENT_COLOR,
+				wrap: "truncate",
 				children: line
 			}, i);
 			return /* @__PURE__ */ jsx(Text, {
 				color: DIM_COLOR,
+				wrap: "truncate",
 				children: line
 			}, i);
 		})
@@ -30147,6 +31481,17 @@ function MarkdownText({ children }) {
 		children: children.split("\n").map((line, i) => {
 			const trimmed = line.trimStart();
 			if (trimmed === "") return /* @__PURE__ */ jsx(Box, { height: 1 }, i);
+			const headingMatch = trimmed.match(/^(#{1,3})\s+(.*)$/);
+			if (headingMatch) {
+				const level = headingMatch[1]?.length ?? 1;
+				const content = headingMatch[2] ?? "";
+				return /* @__PURE__ */ jsx(Text, {
+					bold: true,
+					color: level === 1 ? BRAND_COLOR : level === 2 ? ACCENT_COLOR : void 0,
+					wrap: "wrap",
+					children: renderInline(content, `h${level}-${i}`)
+				}, i);
+			}
 			if (trimmed.startsWith("- ") || trimmed.startsWith("* ")) {
 				const content = trimmed.slice(2);
 				return /* @__PURE__ */ jsxs(Box, {
@@ -30183,7 +31528,7 @@ function OutroScreen({ store }) {
 	const [columns] = useStdoutDimensions();
 	const sepWidth = Math.min(columns - 8, 80);
 	const aiSetup = useMemo(() => checkAiSetup(), []);
-	useInput((_input, key) => {
+	useGatedInput((_input, key) => {
 		if (key.return || key.escape) {
 			store.dismissOutro();
 			process.exit(isSuccess$4 ? 0 : 1);
@@ -30234,10 +31579,12 @@ function OutroScreen({ store }) {
 					if (i === 0 && line.trim()) return /* @__PURE__ */ jsx(Text, {
 						bold: true,
 						color: ACCENT_COLOR,
+						wrap: "truncate",
 						children: line
 					}, i);
 					return /* @__PURE__ */ jsx(Text, {
 						color: DIM_COLOR,
+						wrap: "truncate",
 						children: line
 					}, i);
 				})
@@ -30381,7 +31728,7 @@ function Separator({ width }) {
 //#endregion
 //#region src/wizard/ui/overlays/ErrorOverlay.tsx
 function ErrorOverlay({ message, onDismiss }) {
-	useInput((_input, key) => {
+	useGatedInput((_input, key) => {
 		if (key.return || key.escape) onDismiss();
 	});
 	return /* @__PURE__ */ jsxs(Box, {
@@ -30415,7 +31762,7 @@ function ErrorOverlay({ message, onDismiss }) {
 //#region src/wizard/ui/overlays/ConfirmExitOverlay.tsx
 function ConfirmExitOverlay({ onConfirm, onCancel }) {
 	const [selected, setSelected] = useState(1);
-	useInput((_input, key) => {
+	useGatedInput((_input, key) => {
 		if (key.upArrow || key.downArrow) setSelected((s) => s === 0 ? 1 : 0);
 		if (key.return) if (selected === 0) onConfirm();
 		else onCancel();
@@ -30462,6 +31809,11 @@ function ConfirmExitOverlay({ onConfirm, onCancel }) {
 * Shows question + hint with pulse animation. Supports text input,
 * confirm (yes/no), and choice selection. User can skip env prompts.
 */
+/** Preferred prompt box width, clamped to terminal columns minus margin. */
+function useOverlayWidth() {
+	const [columns] = useStdoutDimensions();
+	return Math.max(30, Math.min(60, columns - 4));
+}
 function PromptOverlay({ prompt: prompt$1, onSubmit, onSkip }) {
 	const [pulse, setPulse] = useState(true);
 	useEffect(() => {
@@ -30489,6 +31841,7 @@ function PromptOverlay({ prompt: prompt$1, onSubmit, onSkip }) {
 function TextPrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 	const [value, setValue] = useState("");
 	const [mode, setMode] = useState("ask");
+	const width = useOverlayWidth();
 	useInput((input, key) => {
 		if (mode === "ask") {
 			if (input === "1" || key.return) setMode("input");
@@ -30515,7 +31868,7 @@ function TextPrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 		borderColor: pulse ? BRAND_COLOR : ACCENT_COLOR,
 		paddingX: 2,
 		paddingY: 1,
-		width: 60,
+		width,
 		children: [
 			/* @__PURE__ */ jsxs(Box, {
 				gap: 1,
@@ -30530,10 +31883,7 @@ function TextPrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 			}),
 			/* @__PURE__ */ jsx(Box, {
 				marginTop: 1,
-				children: /* @__PURE__ */ jsx(Text, {
-					wrap: "wrap",
-					children: prompt$1.question
-				})
+				children: /* @__PURE__ */ jsx(MarkdownText, { children: prompt$1.question })
 			}),
 			prompt$1.hint ? /* @__PURE__ */ jsxs(Box, {
 				marginTop: 1,
@@ -30542,10 +31892,9 @@ function TextPrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 					color: CYAN_COLOR,
 					bold: true,
 					children: "Dica:"
-				}), /* @__PURE__ */ jsxs(Text, {
-					color: DIM_COLOR,
-					wrap: "wrap",
-					children: [" ", prompt$1.hint]
+				}), /* @__PURE__ */ jsx(Box, {
+					marginLeft: 1,
+					children: /* @__PURE__ */ jsx(MarkdownText, { children: prompt$1.hint })
 				})]
 			}) : null,
 			prompt$1.envKey ? /* @__PURE__ */ jsx(Box, {
@@ -30598,6 +31947,7 @@ function TextPrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 }
 function ConfirmPrompt({ prompt: prompt$1, pulse, onSubmit }) {
 	const [selected, setSelected] = useState(0);
+	const width = useOverlayWidth();
 	useInput((_input, key) => {
 		if (key.upArrow || key.downArrow) setSelected((s) => s === 0 ? 1 : 0);
 		if (key.return) onSubmit(selected === 0 ? "sim" : "não");
@@ -30608,7 +31958,7 @@ function ConfirmPrompt({ prompt: prompt$1, pulse, onSubmit }) {
 		borderColor: pulse ? BRAND_COLOR : ACCENT_COLOR,
 		paddingX: 2,
 		paddingY: 1,
-		width: 60,
+		width,
 		children: [
 			/* @__PURE__ */ jsxs(Box, {
 				gap: 1,
@@ -30623,10 +31973,7 @@ function ConfirmPrompt({ prompt: prompt$1, pulse, onSubmit }) {
 			}),
 			/* @__PURE__ */ jsx(Box, {
 				marginTop: 1,
-				children: /* @__PURE__ */ jsx(Text, {
-					wrap: "wrap",
-					children: prompt$1.question
-				})
+				children: /* @__PURE__ */ jsx(MarkdownText, { children: prompt$1.question })
 			}),
 			/* @__PURE__ */ jsx(Box, {
 				marginTop: 1,
@@ -30648,6 +31995,7 @@ function ConfirmPrompt({ prompt: prompt$1, pulse, onSubmit }) {
 function ChoicePrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 	const options = prompt$1.options ?? [];
 	const [selected, setSelected] = useState(0);
+	const width = useOverlayWidth();
 	useInput((_input, key) => {
 		if (key.upArrow) setSelected((s) => Math.max(0, s - 1));
 		if (key.downArrow) setSelected((s) => Math.min(options.length - 1, s + 1));
@@ -30660,7 +32008,7 @@ function ChoicePrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 		borderColor: pulse ? BRAND_COLOR : ACCENT_COLOR,
 		paddingX: 2,
 		paddingY: 1,
-		width: 60,
+		width,
 		children: [
 			/* @__PURE__ */ jsxs(Box, {
 				gap: 1,
@@ -30675,18 +32023,11 @@ function ChoicePrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 			}),
 			/* @__PURE__ */ jsx(Box, {
 				marginTop: 1,
-				children: /* @__PURE__ */ jsx(Text, {
-					wrap: "wrap",
-					children: prompt$1.question
-				})
+				children: /* @__PURE__ */ jsx(MarkdownText, { children: prompt$1.question })
 			}),
 			prompt$1.hint ? /* @__PURE__ */ jsx(Box, {
 				marginTop: 1,
-				children: /* @__PURE__ */ jsx(Text, {
-					color: DIM_COLOR,
-					wrap: "wrap",
-					children: prompt$1.hint
-				})
+				children: /* @__PURE__ */ jsx(MarkdownText, { children: prompt$1.hint })
 			}) : null,
 			/* @__PURE__ */ jsx(Box, {
 				marginTop: 1,
@@ -30717,83 +32058,82 @@ function ChoicePrompt({ prompt: prompt$1, pulse, onSubmit, onSkip }) {
 //#region src/wizard/ui/App.tsx
 function App({ store, router, cwd }) {
 	useSyncExternalStore(store.subscribe, store.getSnapshot);
+	const [, rows] = useStdoutDimensions();
 	const { session } = store;
 	const writePromptResponse = useCallback((value, skipped) => {
-		writeFileSync(join(cwd, ".veloz-wizard-response.json"), JSON.stringify({
+		const responsePath = join(cwd, ".veloz-wizard-response.json");
+		getSessionLogger().log("prompt-response", "user responded to agent prompt", {
+			skipped,
+			bytes: value.length,
+			promptId: session.agentPrompt?.id ?? null,
+			envKey: session.agentPrompt?.envKey ?? null
+		});
+		writeFileSync(responsePath, JSON.stringify({
 			value,
 			skipped
 		}));
 		store.clearAgentPrompt();
-	}, [cwd, store]);
-	if (session.agentPrompt) return /* @__PURE__ */ jsx(PromptOverlay, {
-		prompt: session.agentPrompt,
-		onSubmit: (value) => writePromptResponse(value, false),
-		onSkip: () => writePromptResponse("", true)
-	});
+	}, [
+		cwd,
+		store,
+		session.agentPrompt
+	]);
 	const overlay = router.activeOverlay;
-	if (overlay === Overlay.ConfirmExit) return /* @__PURE__ */ jsx(ConfirmExitOverlay, {
+	let baseLayer;
+	if (overlay === Overlay.ConfirmExit) baseLayer = /* @__PURE__ */ jsx(ConfirmExitOverlay, {
 		onConfirm: () => {
 			router.popOverlay();
 			process.exit(130);
 		},
 		onCancel: () => router.popOverlay()
 	});
-	if (overlay === Overlay.Error) return /* @__PURE__ */ jsx(ErrorOverlay, {
+	else if (overlay === Overlay.Error) baseLayer = /* @__PURE__ */ jsx(ErrorOverlay, {
 		message: session.agentError ?? "Erro desconhecido",
 		onDismiss: () => router.popOverlay()
 	});
-	switch (router.resolve(session)) {
-		case Screen.Intro: return /* @__PURE__ */ jsx(IntroScreen, { store });
-		case Screen.Auth: return /* @__PURE__ */ jsx(AuthScreen, { store });
-		case Screen.Run: return /* @__PURE__ */ jsx(RunScreen, { store });
-		case Screen.Outro: return /* @__PURE__ */ jsx(OutroScreen, { store });
-		default: return /* @__PURE__ */ jsx(Box, { children: /* @__PURE__ */ jsx(IntroScreen, { store }) });
+	else switch (router.resolve(session)) {
+		case Screen.Intro:
+			baseLayer = /* @__PURE__ */ jsx(IntroScreen, { store });
+			break;
+		case Screen.Auth:
+			baseLayer = /* @__PURE__ */ jsx(AuthScreen, { store });
+			break;
+		case Screen.Notes:
+			baseLayer = /* @__PURE__ */ jsx(NotesScreen, { store });
+			break;
+		case Screen.Run:
+			baseLayer = /* @__PURE__ */ jsx(RunScreen, { store });
+			break;
+		case Screen.Outro:
+			baseLayer = /* @__PURE__ */ jsx(OutroScreen, { store });
+			break;
+		default: baseLayer = /* @__PURE__ */ jsx(IntroScreen, { store });
 	}
-}
-
-//#endregion
-//#region src/wizard/session.ts
-function createInitialSession() {
-	return {
-		isAuthenticated: false,
-		userName: "",
-		orgId: "",
-		orgName: "",
-		apiKey: "",
-		authPhase: "checking",
-		authDeviceCode: null,
-		authVerificationUrl: null,
-		availableOrgs: [],
-		selectedOrgId: null,
-		detectedFramework: null,
-		detectedFrameworkLabel: null,
-		selectedFramework: null,
-		selectedFrameworkLabel: null,
-		packageManager: "npm",
-		gitRemote: null,
-		isMonorepo: false,
-		agentPhase: "idle",
-		agentTasks: [],
-		agentLogLines: [],
-		agentComplete: false,
-		agentError: null,
-		deployUrl: null,
-		retryCount: 0,
-		buildLogLines: [],
-		buildStreamActive: false,
-		buildDeploymentId: null,
-		statusMessages: [],
-		agentOutputLines: [],
-		toolCallLog: [],
-		learnCardBlockIdx: 0,
-		learnCardComplete: false,
-		agentHelperLines: [],
-		agentPrompt: null,
-		agentSummary: null,
-		introConfirmed: false,
-		outroDismissed: false,
-		agentStartedAt: null
-	};
+	const prompt$1 = session.agentPrompt;
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		height: rows,
+		children: [/* @__PURE__ */ jsx(InputFocusProvider, {
+			active: !prompt$1,
+			children: /* @__PURE__ */ jsx(Box, {
+				flexDirection: "column",
+				flexGrow: 1,
+				flexShrink: 1,
+				minHeight: 0,
+				overflow: "hidden",
+				children: baseLayer
+			})
+		}), prompt$1 ? /* @__PURE__ */ jsx(Box, {
+			flexShrink: 0,
+			paddingX: 2,
+			paddingY: 1,
+			children: /* @__PURE__ */ jsx(PromptOverlay, {
+				prompt: prompt$1,
+				onSubmit: (value) => writePromptResponse(value, false),
+				onSkip: () => writePromptResponse("", true)
+			})
+		}) : null]
+	});
 }
 
 //#endregion
@@ -30874,6 +32214,12 @@ var WizardStore = class {
 		this.$session.setKey("introConfirmed", true);
 		this.emitChange();
 	}
+	confirmNotes(notes) {
+		const trimmed = notes?.trim();
+		this.$session.setKey("userNotes", trimmed && trimmed.length > 0 ? trimmed : null);
+		this.$session.setKey("notesConfirmed", true);
+		this.emitChange();
+	}
 	setAuth(data) {
 		this.$session.setKey("isAuthenticated", true);
 		this.$session.setKey("userName", data.userName);
@@ -30902,7 +32248,32 @@ var WizardStore = class {
 		this.$session.setKey("selectedOrgId", orgId);
 		this.emitChange();
 	}
+	/** User chose "create new" from the org picker — switch to the create screen. */
+	requestOrgCreation() {
+		this.$session.setKey("authPhase", "org-create");
+		this.$session.setKey("newOrgName", null);
+		this.$session.setKey("orgCreateError", null);
+		this.emitChange();
+	}
+	/** User submitted a name on the org-create screen. The runner picks this up via a gate. */
+	submitNewOrgName(name) {
+		this.$session.setKey("newOrgName", name);
+		this.$session.setKey("authPhase", "org-creating");
+		this.$session.setKey("orgCreateError", null);
+		this.emitChange();
+	}
+	/** Creation failed — surface the error and send the user back to the input. */
+	failOrgCreation(error) {
+		this.$session.setKey("orgCreateError", error);
+		this.$session.setKey("newOrgName", null);
+		this.$session.setKey("authPhase", "org-create");
+		this.emitChange();
+	}
 	setAgentPhase(phase) {
+		getSessionLogger().logStoreEvent("agentPhase", {
+			from: this.session.agentPhase,
+			to: phase
+		});
 		this.$session.setKey("agentPhase", phase);
 		if (phase !== "idle" && !this.session.agentStartedAt) this.$session.setKey("agentStartedAt", Date.now());
 		this.emitChange();
@@ -30913,6 +32284,14 @@ var WizardStore = class {
 		this.emitChange();
 	}
 	syncTasks(tasks) {
+		getSessionLogger().logStoreEvent("syncTasks", {
+			count: tasks.length,
+			tasks: tasks.map((t) => ({
+				id: t.id,
+				label: t.label,
+				status: t.status
+			}))
+		});
 		this.$session.setKey("agentTasks", tasks);
 		this.emitChange();
 	}
@@ -30925,15 +32304,18 @@ var WizardStore = class {
 		this.emitChange();
 	}
 	setDeployUrl(url) {
+		getSessionLogger().logStoreEvent("setDeployUrl", { url });
 		this.$session.setKey("deployUrl", url);
 		this.emitChange();
 	}
 	completeAgent() {
+		getSessionLogger().logStoreEvent("completeAgent");
 		this.$session.setKey("agentComplete", true);
 		this.$session.setKey("agentPhase", "done");
 		this.emitChange();
 	}
 	failAgent(error) {
+		getSessionLogger().logStoreEvent("failAgent", { error });
 		this.$session.setKey("agentError", error);
 		this.$session.setKey("agentPhase", "error");
 		this.$session.setKey("agentComplete", true);
@@ -30951,6 +32333,7 @@ var WizardStore = class {
 	pushStatus(message) {
 		const msgs = this.session.statusMessages;
 		if (msgs.length > 0 && msgs[msgs.length - 1] === message) return;
+		getSessionLogger().logStoreEvent("status", { message });
 		this.$session.setKey("statusMessages", [...msgs, message].slice(-50));
 		this.emitChange();
 	}
@@ -30989,32 +32372,43 @@ var WizardStore = class {
 	}
 	/** Show a prompt overlay to the user. */
 	setAgentPrompt(prompt$1) {
+		getSessionLogger().logStoreEvent("setAgentPrompt", {
+			id: prompt$1.id,
+			type: prompt$1.type,
+			envKey: prompt$1.envKey,
+			question: prompt$1.question
+		});
 		this.$session.setKey("agentPrompt", prompt$1);
 		this.emitChange();
 	}
 	/** Clear the prompt overlay after user responds. */
 	clearAgentPrompt() {
+		getSessionLogger().logStoreEvent("clearAgentPrompt");
 		this.$session.setKey("agentPrompt", null);
 		this.emitChange();
 	}
 	/** Set the agent's final summary for the outro screen. */
 	setAgentSummary(summary) {
+		getSessionLogger().logStoreEvent("setAgentSummary", { bytes: summary.length });
 		this.$session.setKey("agentSummary", summary);
 		this.emitChange();
 	}
 	/** Push a build log line from the deployment stream. */
 	pushBuildLog(line) {
+		getSessionLogger().logBuildStream("line", { line });
 		const lines = [...this.session.buildLogLines, line].slice(-500);
 		this.$session.setKey("buildLogLines", lines);
 		this.emitChange();
 	}
 	/** Mark the build log stream as active/inactive. */
-	setBuildStreamActive(active) {
-		this.$session.setKey("buildStreamActive", active);
+	setBuildStreamActive(active$1) {
+		getSessionLogger().logBuildStream("active", { active: active$1 });
+		this.$session.setKey("buildStreamActive", active$1);
 		this.emitChange();
 	}
 	/** Set the deployment ID being streamed. */
 	setBuildDeploymentId(id) {
+		getSessionLogger().logBuildStream("deploymentId", { id });
 		this.$session.setKey("buildDeploymentId", id);
 		this.emitChange();
 	}
@@ -31042,7 +32436,12 @@ function startTUI(cwd) {
 	let sigintCount = 0;
 	process.on("SIGINT", () => {
 		sigintCount++;
-		if (sigintCount >= 2) process.exit(130);
+		const logger = getSessionLogger();
+		logger.log("signal", "SIGINT received", { count: sigintCount });
+		if (sigintCount >= 2) {
+			logger.finalize("abort", { error: "user double-SIGINT" });
+			process.exit(130);
+		}
 		router.pushOverlay(Overlay.ConfirmExit);
 	});
 	return {
@@ -31053,6 +32452,122 @@ function startTUI(cwd) {
 	};
 }
 
+//#endregion
+//#region src/wizard/upload-telemetry.ts
+/**
+* Upload per-session debug logs to MGC via presigned URLs.
+*
+* Flow:
+*   1. Read meta.json from the session folder
+*   2. Call `initTelemetry.start` → server creates InitSession row + returns
+*      a presigned PUT URL for each file
+*   3. PUT each file to MGC directly (no server round-trip)
+*   4. Call `initTelemetry.finalize` → server patches the row with outcome
+*
+* Runs best-effort. Errors are logged to stderr only so they never block
+* `veloz init`. Disabled via `VELOZ_NO_TELEMETRY=1`.
+*/
+const CONTENT_TYPES = {
+	"meta.json": "application/json",
+	"events.jsonl": "application/x-ndjson",
+	"sdk-messages.jsonl": "application/x-ndjson",
+	"tool-calls.jsonl": "application/x-ndjson",
+	"store-events.jsonl": "application/x-ndjson",
+	"build-stream.jsonl": "application/x-ndjson",
+	"mcp-tools.jsonl": "application/x-ndjson",
+	"session.log": "text/plain; charset=utf-8",
+	"prompts.md": "text/markdown; charset=utf-8"
+};
+function contentTypeFor(filename) {
+	return CONTENT_TYPES[filename] ?? "application/octet-stream";
+}
+async function uploadInitTelemetry(sessionDir) {
+	if (process.env.VELOZ_NO_TELEMETRY === "1") {
+		process.stderr.write("[veloz init] telemetria desativada (VELOZ_NO_TELEMETRY=1)\n");
+		return;
+	}
+	const metaPath = join(sessionDir, "meta.json");
+	let meta;
+	try {
+		meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+	} catch (err) {
+		process.stderr.write(`[veloz init] falha ao ler meta.json: ${err instanceof Error ? err.message : String(err)}\n`);
+		return;
+	}
+	const authConfig = loadConfig();
+	if (!authConfig.apiKey) {
+		process.stderr.write("[veloz init] sem apiKey — telemetria não enviada\n");
+		return;
+	}
+	const files = readdirSync(sessionDir).filter((name) => {
+		const full = join(sessionDir, name);
+		try {
+			const s = statSync(full);
+			return s.isFile() && s.size > 0;
+		} catch {
+			return false;
+		}
+	});
+	if (files.length === 0) return;
+	const client = createClient(authConfig.apiUrl, () => {
+		const headers = {
+			Authorization: `Bearer ${authConfig.apiKey}`,
+			"User-Agent": "veloz-cli/telemetry"
+		};
+		if (authConfig.organizationId) headers["X-Organization-Id"] = authConfig.organizationId;
+		return headers;
+	});
+	let started;
+	try {
+		started = await client.initTelemetry.start({
+			clientSessionId: meta.sessionId,
+			cwd: meta.cwd,
+			framework: meta.framework,
+			frameworkLabel: meta.frameworkLabel,
+			packageManager: meta.packageManager,
+			isMonorepo: meta.isMonorepo,
+			gitRemote: meta.gitRemote ?? void 0,
+			userName: meta.userName,
+			orgName: meta.orgName,
+			node: meta.node,
+			platform: meta.platform,
+			pid: meta.pid,
+			startedAt: meta.startedAt,
+			files
+		});
+	} catch (err) {
+		process.stderr.write(`[veloz init] telemetria (start) falhou: ${err instanceof Error ? err.message : String(err)}\n`);
+		return;
+	}
+	const failures = (await Promise.allSettled(files.map(async (filename) => {
+		const url = started.uploads[filename];
+		if (!url) return;
+		const body = readFileSync(join(sessionDir, filename));
+		const res = await fetch(url, {
+			method: "PUT",
+			headers: { "Content-Type": contentTypeFor(filename) },
+			body
+		});
+		if (!res.ok) throw new Error(`${filename}: HTTP ${res.status}`);
+	}))).filter((r) => r.status === "rejected");
+	if (failures.length > 0) for (const failure of failures) process.stderr.write(`[veloz init] upload de arquivo falhou: ${String(failure.reason?.message ?? failure.reason)}\n`);
+	try {
+		await client.initTelemetry.finalize({
+			id: started.id,
+			outcome: meta.outcome ?? "unknown",
+			error: meta.error ?? null,
+			deployUrl: meta.deployUrl ?? null,
+			retries: meta.retries,
+			durationMs: meta.durationMs,
+			endedAt: meta.endedAt
+		});
+	} catch (err) {
+		process.stderr.write(`[veloz init] telemetria (finalize) falhou: ${err instanceof Error ? err.message : String(err)}\n`);
+		return;
+	}
+	process.stderr.write(`[veloz init] telemetria enviada (sessão ${started.id})\n`);
+}
+
 //#endregion
 //#region src/wizard/index.ts
 /**
@@ -31102,18 +32617,37 @@ function registerInit(cli$1) {
 		outputPolicy: "agent-only",
 		async run(c) {
 			const cwd = process.cwd();
+			const logger = initSessionLogger({ cwd });
+			logger.log("init", "veloz init invoked", {
+				cwd,
+				framework: c.options.framework ?? null,
+				ci: c.options.ci,
+				isTTY: Boolean(process.stdout.isTTY),
+				argv: process.argv.slice(2)
+			});
+			process.stderr.write(`[veloz init] debug logs: ${logger.dir}\n`);
 			const analysis = detectLocalRepo(cwd);
+			logger.log("detection", "repo analysis complete", {
+				framework: analysis.framework?.name ?? null,
+				frameworkLabel: analysis.framework?.label ?? null,
+				packageManager: analysis.packageManager,
+				isMonorepo: analysis.isMonorepo
+			});
 			const detectedFrameworkId = analysis.framework ? DETECTOR_TO_FRAMEWORK[analysis.framework.name] ?? "nodejs" : null;
 			const detectedLabel = analysis.framework?.label ?? null;
 			const forcedFramework = c.options.framework;
-			if (!process.stdout.isTTY || c.options.ci) return await runHeadless({
-				cwd,
-				frameworkId: forcedFramework ?? detectedFrameworkId ?? "nodejs",
-				frameworkLabel: forcedFramework ? FRAMEWORK_LABELS[forcedFramework] ?? forcedFramework : detectedLabel ?? "Node.js",
-				packageManager: analysis.packageManager ?? "npm"
-			});
+			if (!process.stdout.isTTY || c.options.ci) {
+				logger.log("mode", "running headless (no TUI)");
+				return await runHeadless({
+					cwd,
+					frameworkId: forcedFramework ?? detectedFrameworkId ?? "nodejs",
+					frameworkLabel: forcedFramework ? FRAMEWORK_LABELS[forcedFramework] ?? forcedFramework : detectedLabel ?? "Node.js",
+					packageManager: analysis.packageManager ?? "npm"
+				});
+			}
 			const tui = startTUI();
 			const { store } = tui;
+			logger.log("tui", "TUI started");
 			store.setDetection({
 				framework: detectedFrameworkId,
 				frameworkLabel: detectedLabel,
@@ -31125,10 +32659,37 @@ function registerInit(cli$1) {
 				store.selectFramework(forcedFramework, FRAMEWORK_LABELS[forcedFramework] ?? forcedFramework);
 				store.confirmIntro();
 			}
+			logger.log("flow", "awaiting intro confirmation");
 			await tui.waitForIntro();
+			logger.log("flow", "intro confirmed");
 			const selectedFramework = store.session.selectedFramework ?? detectedFrameworkId ?? "nodejs";
 			const selectedLabel = store.session.selectedFrameworkLabel ?? detectedLabel ?? "Node.js";
+			logger.updateMeta({
+				framework: selectedFramework,
+				frameworkLabel: selectedLabel,
+				packageManager: store.session.packageManager ?? "npm",
+				isMonorepo: store.session.isMonorepo,
+				gitRemote: store.session.gitRemote
+			});
+			logger.log("flow", "resolving auth + org");
 			await resolveAuthAndOrg(store);
+			logger.log("auth", "auth + org resolved", {
+				userName: store.session.userName,
+				orgId: store.session.orgId,
+				orgName: store.session.orgName
+			});
+			logger.updateMeta({
+				userName: store.session.userName,
+				orgName: store.session.orgName,
+				orgId: store.session.orgId
+			});
+			logger.log("flow", "awaiting user notes");
+			await store.getGate("notes", (s) => s.notesConfirmed);
+			logger.log("flow", "notes confirmed", {
+				hasNotes: Boolean(store.session.userNotes),
+				bytes: store.session.userNotes?.length ?? 0
+			});
+			logger.log("agent", "invoking runAgent");
 			await runAgent({
 				store,
 				cwd,
@@ -31136,12 +32697,29 @@ function registerInit(cli$1) {
 				frameworkLabel: selectedLabel,
 				userName: store.session.userName,
 				orgName: store.session.orgName,
-				packageManager: store.session.packageManager ?? "npm"
+				packageManager: store.session.packageManager ?? "npm",
+				userNotes: store.session.userNotes
 			});
+			logger.log("agent", "runAgent returned", {
+				phase: store.session.agentPhase,
+				error: store.session.agentError,
+				deployUrl: store.session.deployUrl,
+				retryCount: store.session.retryCount
+			});
+			logger.log("flow", "awaiting outro dismissal");
 			await store.getGate("outro", (s) => s.outroDismissed);
+			logger.log("flow", "outro dismissed");
 			tui.unmount();
+			logger.log("tui", "TUI unmounted");
+			const success$1 = !store.session.agentError;
+			logger.finalize(success$1 ? "success" : "error", {
+				error: store.session.agentError ?? void 0,
+				deployUrl: store.session.deployUrl ?? void 0,
+				retries: store.session.retryCount
+			});
+			await uploadInitTelemetry(logger.dir);
 			return {
-				success: !store.session.agentError,
+				success: success$1,
 				url: store.session.deployUrl ?? void 0
 			};
 		}
@@ -31150,6 +32728,8 @@ function registerInit(cli$1) {
 async function runHeadless(opts) {
 	const { WizardStore: WizardStore$1 } = await import("./store-CFF2J0lW.mjs");
 	const { runAgent: run } = await import("./agent-interface-DL5S8SEn.mjs");
+	const logger = getSessionLogger();
+	logger.log("headless", "resolving auth (non-interactive)");
 	const config = await requireAuth({ nonInteractive: true });
 	const store = new WizardStore$1();
 	store.setAuth({
@@ -31163,6 +32743,14 @@ async function runHeadless(opts) {
 		const lastLog = s.agentLogLines[s.agentLogLines.length - 1];
 		if (lastLog) process.stderr.write(`[veloz init] ${lastLog}\n`);
 	});
+	logger.updateMeta({
+		framework: opts.frameworkId,
+		frameworkLabel: opts.frameworkLabel,
+		packageManager: opts.packageManager,
+		userName: "CI",
+		orgId: config.organizationId ?? ""
+	});
+	logger.log("headless", "invoking runAgent");
 	await run({
 		store,
 		cwd: opts.cwd,
@@ -31172,29 +32760,18 @@ async function runHeadless(opts) {
 		orgName: "",
 		packageManager: opts.packageManager
 	});
+	const success$1 = !store.session.agentError;
+	logger.finalize(success$1 ? "success" : "error", {
+		error: store.session.agentError ?? void 0,
+		deployUrl: store.session.deployUrl ?? void 0,
+		retries: store.session.retryCount
+	});
+	await uploadInitTelemetry(logger.dir);
 	return {
-		success: !store.session.agentError,
+		success: success$1,
 		url: store.session.deployUrl ?? void 0
 	};
 }
-function isMultipleOrgsError(error) {
-	if (!(error instanceof Error)) return false;
-	const e = error;
-	return e.data?.code === "MULTIPLE_ORGS" && Array.isArray(e.data?.organizations);
-}
-function isNoOrgError(error) {
-	if (!(error instanceof Error)) return false;
-	return error.data?.code === "NO_ORGANIZATION";
-}
-/**
-* Build a Better Auth client with org plugin (extends the device auth client).
-*/
-function buildOrgAuthClient(apiUrl) {
-	return createAuthClient({
-		baseURL: apiUrl,
-		plugins: [organizationClient()]
-	});
-}
 /**
 * Perform device auth with TUI feedback — reuses shared helpers from login.ts.
 * No console.log or ora spinners; all progress goes through the store.
@@ -31209,100 +32786,141 @@ async function performDeviceAuth(store, apiUrl) {
 	store.setAuthPhase("polling");
 	return pollForToken(authClient, data.device_code, data.interval || 5);
 }
+/** Fetch the list of orgs the user belongs to via Better Auth. */
+async function listOrganizations(apiUrl, apiKey) {
+	const res = await fetch(`${apiUrl}/api/auth/organization/list`, { headers: {
+		Authorization: `Bearer ${apiKey}`,
+		"User-Agent": "veloz-cli"
+	} });
+	if (!res.ok) throw new Error(`Falha ao listar workspaces (${res.status}).`);
+	return (await res.json()).map((o) => ({
+		id: o.id,
+		name: o.name,
+		slug: o.slug
+	}));
+}
 /**
-* Build an ORPC API client with explicit credentials (no requireAuth prompts).
+* Create a new organization via Better Auth. The slug is derived from the name
+* and suffixed with a random token when a collision occurs.
 */
-function buildApiClient(apiUrl, apiKey, organizationId) {
-	return createClient(apiUrl, () => {
-		const headers = {
-			Authorization: `Bearer ${apiKey}`,
-			"User-Agent": "veloz-cli"
-		};
-		if (organizationId) headers["X-Organization-Id"] = organizationId;
-		return headers;
-	});
+async function createOrganization(apiUrl, apiKey, name) {
+	const baseSlug = name.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "workspace";
+	let slug = baseSlug;
+	for (let attempt = 0; attempt < 3; attempt++) {
+		const res = await fetch(`${apiUrl}/api/auth/organization/create`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+				"User-Agent": "veloz-cli"
+			},
+			body: JSON.stringify({
+				name,
+				slug
+			})
+		});
+		if (res.ok) {
+			const data = await res.json();
+			return {
+				id: data.id,
+				name: data.name,
+				slug: data.slug
+			};
+		}
+		const errorText = await res.text().catch(() => "");
+		if (res.status === 400 && errorText.toLowerCase().includes("already")) {
+			slug = `${baseSlug}-${Math.random().toString(36).slice(2, 6)}`;
+			continue;
+		}
+		throw new Error(errorText || `Falha ao criar workspace (${res.status}).`);
+	}
+	throw new Error("Não foi possível gerar um slug único para o workspace.");
 }
 /**
 * Full TUI-aware auth + org resolution.
 *
 * 1. If already authenticated, skip login
 * 2. If not, perform device auth with TUI feedback
-* 3. Resolve organization (single/multi/none)
-* 4. If no org, auto-create one
+* 3. Always show the org picker (or the create screen if the user has no orgs)
+* 4. Persist the selected/created org id
 * 5. Update store.setAuth() when done
 */
 async function resolveAuthAndOrg(store) {
+	const logger = getSessionLogger();
 	let config = loadConfig();
 	if (!isAuthenticated()) {
 		const envApiKey = process.env.VELOZ_API_KEY;
 		if (envApiKey) {
+			logger.log("auth", "using VELOZ_API_KEY from env");
 			saveConfig({ apiKey: envApiKey });
 			config = loadConfig();
 		} else {
+			logger.log("auth", "starting device auth flow", { apiUrl: config.apiUrl });
 			store.setAuthPhase("browser");
 			const token = await performDeviceAuth(store, config.apiUrl);
-			if (!token) throw new Error("Autenticação cancelada ou expirada.");
+			if (!token) {
+				logger.log("auth", "device auth failed or expired");
+				throw new Error("Autenticação cancelada ou expirada.");
+			}
+			logger.log("auth", "device auth succeeded");
 			saveConfig({ apiKey: token });
 			config = loadConfig();
 		}
-	}
-	const projectConfig = loadConfig$1();
-	const needsOrgResolution = !config.organizationId && !projectConfig?.project?.id;
-	let orgName = "";
-	if (needsOrgResolution) {
-		const client = buildApiClient(config.apiUrl, config.apiKey);
-		try {
-			await client.projects.list();
-		} catch (error) {
-			if (isMultipleOrgsError(error)) {
-				const orgs = error.data.organizations;
-				if (orgs.length === 1) {
-					const org = orgs[0];
-					saveConfig({ organizationId: org.id });
-					config = loadConfig();
-					orgName = org.name;
-				} else {
-					store.setAvailableOrgs(orgs);
-					await store.getGate("org-select", (s) => s.selectedOrgId !== null);
-					const selectedOrgId = store.session.selectedOrgId;
-					const selectedOrg = orgs.find((o) => o.id === selectedOrgId);
-					saveConfig({ organizationId: selectedOrgId });
-					config = loadConfig();
-					orgName = selectedOrg?.name ?? selectedOrgId;
-				}
-			} else if (isNoOrgError(error)) {
-				store.setAuthPhase("no-org");
-				const authClient = buildOrgAuthClient(config.apiUrl);
-				const userName = process.env.USER ?? process.env.USERNAME ?? "meu-workspace";
-				const slug = userName.toLowerCase().replace(/[^a-z0-9-]/g, "-").slice(0, 30);
-				const createResult = await authClient.organization.create({
-					name: `${userName}'s workspace`,
-					slug
-				});
-				if (createResult.error || !createResult.data) {
-					await openBrowser(`${config.apiUrl.includes("localhost") ? "http://localhost:3001" : "https://app.onveloz.com"}/onboarding`);
-					throw new Error("Não foi possível criar o workspace automaticamente. Crie um em app.onveloz.com e tente novamente.", { cause: createResult.error });
-				}
-				const newOrg = createResult.data;
-				saveConfig({ organizationId: newOrg.id });
-				config = loadConfig();
-				orgName = newOrg.name;
-			} else throw error;
+	} else logger.log("auth", "already authenticated from config");
+	logger.log("auth", "fetching organizations");
+	const orgs = await listOrganizations(config.apiUrl, config.apiKey);
+	logger.log("auth", "organizations loaded", { count: orgs.length });
+	let chosen;
+	if (orgs.length === 0) {
+		store.setAuthPhase("org-create");
+		chosen = await runOrgCreationFlow(store, config.apiUrl, config.apiKey);
+	} else {
+		store.setAvailableOrgs(orgs);
+		await store.getGate("org-select", (s) => s.selectedOrgId !== null || s.authPhase === "org-create");
+		if (store.session.authPhase === "org-create") chosen = await runOrgCreationFlow(store, config.apiUrl, config.apiKey);
+		else {
+			const selectedOrgId = store.session.selectedOrgId;
+			const match$3 = orgs.find((o) => o.id === selectedOrgId);
+			if (!match$3) throw new Error("Workspace selecionado não encontrado.");
+			chosen = match$3;
 		}
 	}
+	saveConfig({ organizationId: chosen.id });
+	config = loadConfig();
 	store.setAuth({
 		userName: config.apiKey ? "Usuário" : "",
-		orgId: config.organizationId ?? "",
-		orgName,
+		orgId: chosen.id,
+		orgName: chosen.name,
 		apiKey: config.apiKey
 	});
 }
+/**
+* Drive the org-create screen: wait for the user to submit a name, try to
+* create it, and retry on failure without leaving the wizard.
+*/
+async function runOrgCreationFlow(store, apiUrl, apiKey) {
+	store.requestOrgCreation();
+	for (;;) {
+		await store.getGate(`org-create-${Date.now()}-${Math.random()}`, (s) => s.newOrgName !== null && s.authPhase === "org-creating");
+		const name = store.session.newOrgName?.trim() ?? "";
+		if (!name) {
+			store.failOrgCreation("Digite um nome para o workspace.");
+			continue;
+		}
+		try {
+			return await createOrganization(apiUrl, apiKey, name);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			store.failOrgCreation(message);
+		}
+	}
+}
 
 //#endregion
 //#region src/index.ts
 if (process.argv.includes("--mcp")) process.env.VELOZ_MCP = "true";
 const cli = Cli.create("veloz", {
-	version: "0.0.0-beta.30",
+	version: "0.0.0-beta.31",
 	description: "CLI da plataforma Veloz — deploy rápido para o Brasil",
 	env: z.object({ VELOZ_ENV: z.string().optional().describe("Ambiente alvo (ex: preview, staging)") }),
 	mcp: { command: "npx -y onveloz --mcp" }