wizz-method 1.4.1 → 1.5.0

package/src/skills-lib/wizz-router/references/routing-table-flat.md

@@ -2,34 +2,34 @@
 
 Use esta tabela **só fora de projeto Wizz** (sem `_wizz/`), quando o router mapeia skills/CLIs/MCPs direto. Dentro de projeto Wizz a delegação é decidida pela regra de dispatch no SKILL.md (maestro vs agente de área) e esta tabela não é necessária.
 
+**Verificação de existência:** antes de oferecer qualquer skill, confirme que ela existe no ambiente (catálogo de skills da sessão ou `ls ~/.claude/skills`); se não existir, não ofereça: use o protocolo de skill faltante (`find-skills`).
+
 ## Área Técnica — Backend / Dados / Infra
 
 | Intenção / palavras-chave | Skills a oferecer | Prioridade |
 |---|---|---|
-| Banco lento, queries, índices, N+1, sharding, connection pool | `database-scaling` + `database-reviewer` | 1 |
+| Banco lento, queries, índices, N+1, sharding, connection pool | `database-scaling` + `supabase-postgres-best-practices` | 1 |
 | Cache, Redis, filas, BullMQ, SQS, Kafka, job assíncrono | `caching-and-queues` | 1 |
 | Kubernetes, auto-scaling, CDN, capacidade, SLO, load test | `infrastructure` | 1 |
 | Cloud spend, custo de infra, right-sizing, AWS/GCP billing | `cloud-and-infra` | 1 |
-| Auth, secrets, tokens, OAuth, JWT, Clerk, permissões | `auth-and-secrets` + `security-reviewer` | 1 |
+| Auth, secrets, tokens, OAuth, JWT, Clerk, permissões | `auth-and-secrets` + `web-security` | 1 |
 | Dependências, packages, vulnerabilidades, npm audit | `database-and-deps` | 2 |
-| Segurança, XSS, CSRF, SQLi, IDOR, OWASP, rate limit, CORS, clickjacking, PII na resposta, enumeração de usuário, headers | `web-security` + `security-reviewer` + `auth-and-secrets` | 1 |
+| Segurança, XSS, CSRF, SQLi, IDOR, OWASP, rate limit, CORS, clickjacking, PII na resposta, enumeração de usuário, headers | `web-security` + `auth-and-secrets` | 1 |
 | Desktop, Electron, contextIsolation, code signing | `desktop-security` | 2 |
 
 ## Área Técnica — Código e Qualidade
 
 | Intenção / palavras-chave | Skills a oferecer | Prioridade |
 |---|---|---|
-| Revisar código, code review, qualidade, refatorar | `code-reviewer` (agente nativo) | 1 |
-| Novo feature, bug fix, TDD, testes, cobertura | `tdd-guide` (agente nativo) | 1 |
-| Build quebrado, erros de TypeScript, lint, CI | `build-error-resolver` (agente nativo) | 1 |
-| Arquitetura, design de sistema, decisão técnica | `architect` (agente nativo) | 1 |
-| Fluxo crítico, E2E, testes de ponta a ponta | `e2e-runner` (agente nativo) | 2 |
-| Dead code, limpeza, refactoring, knip | `refactor-cleaner` (agente nativo) | 2 |
-| SQL, schema, migrations, Supabase, RLS, performance de queries | `database-reviewer` (agente nativo) | 1 |
-| Segunda opinião, revisão crítica adversarial | `adversarial-reviewer` | 2 |
-| Plano técnico, breakdown de tasks, handoff de dev | `implementation-planner` | 2 |
+| Revisar código, code review, qualidade, segunda opinião adversarial | `adversarial-reviewer` | 1 |
+| Novo feature, bug fix, TDD, testes, cobertura | execução direta com TDD (rules globais) e verificação end-to-end ao final | 1 |
+| Build quebrado, erros de TypeScript, lint, CI | execução direta (fix mínimo até build verde) | 2 |
+| Arquitetura, design de sistema, decisão técnica, plano técnico, breakdown, handoff | `implementation-planner` | 1 |
+| Fluxo crítico, E2E, verificação visual no browser | `agent-browser` | 2 |
+| SQL, schema, migrations, Supabase, RLS, performance de queries | `supabase-postgres-best-practices` + `database-scaling` | 1 |
+| Dead code, limpeza, refactoring | execução direta + `adversarial-reviewer` na revisão | 2 |
 | Novo projeto, iniciar app, ponto de partida, onboarding dev | `inicio-de-projeto` | 1 |
-| Construir/melhorar agente ou produto de IA, escrever/revisar system prompt, persona/tom, guardrails, few-shot, chain-of-thought, orquestração multi-agente, avaliar saída de IA | `ai-product-design` | 1 |
+| Construir/melhorar agente ou produto de IA, system prompt, tool definitions | `ai-product-design` | 1 |
 
 ## Área de Design e UI
 
@@ -71,7 +71,7 @@ Use esta tabela **só fora de projeto Wizz** (sem `_wizz/`), quando o router map
 | Ferramenta grátis de captação de leads | `free-tool-strategy` | 2 |
 | A/B test, variações, experimentos de conversão | `ab-test-setup` + `analytics-tracking` | 2 |
 | Copywriting, copy, persuasão, texto de venda | `copywriting` + `humanizer` | 1 |
-| Pesquisa de mercado, inteligência competitiva | agentes nativos: `market-research` / `deep-research` | 2 |
+| Pesquisa de mercado, inteligência competitiva | `deep-research` | 2 |
 
 ## Contexto e Memória
 
@@ -90,6 +90,6 @@ Quando nenhuma skill/MCP instalado cobrir o pedido, **classifique o que falta**
 
 **Falta um MCP:** informe → `claude mcp list` → consulte `skills-registry.yaml` (`mcps:`/`mcp_utility:`, com `server` pronto) → proponha `claude mcp add <id> [-e VAR=$VAR] -- <command> [args]`. Secrets sempre via env/placeholder, nunca token real.
 
-MCPs comuns: context7 (docs de libs), magic/21st (UI), supabase (Postgres), playwright (browser E2E), meta-ads (Meta), exa (pesquisa).
+MCPs comuns: context7 (docs de libs), magic/21st (UI), supabase (Postgres), meta-ads (Meta), exa (pesquisa). Browser/E2E é sempre via CLI `agent-browser`, nunca via MCP Playwright.
 
 Para paid ads Meta, o MCP `mcp-meta-ads` dá acesso real à API Meta Marketing (campanhas, ad sets, ads, métricas, criativos). Combine com `paid-ads` + `ad-creative` + `analytics-tracking`. O `META_ACCESS_TOKEN` vem de env local: nunca exponha em logs ou código commitado.

package/tools/fetch-assets.mjs

@@ -0,0 +1,277 @@
+// fetch-assets.mjs — downloader sob demanda dos assets pesados (MP3/fontes)
+// removidos do pacote npm na Tarefa 2.8 da auditoria (assets lazy).
+//
+// Por que existe: `huashu-design/assets/**/*.mp3` (~30MB) e
+// `canvas-design/canvas-fonts/**/*.ttf` (~5.5MB) inflavam o pacote npm em
+// ~73%, mas só são necessários no primeiro uso real de export de vídeo
+// (BGM/SFX) ou de uma variante de fonte específica. Os arquivos continuam no
+// git (fonte de verdade); só saem do tarball publicado. Este script baixa o
+// bundle certo, no lugar certo, verificando sha256 (mesmo espírito do pin
+// com checksum do rtk — nunca extrai um bundle adulterado).
+//
+// Uso:
+//   node tools/fetch-assets.mjs <bundle> [--dest <dir>] [--force]
+//   node tools/fetch-assets.mjs --all
+//   node tools/fetch-assets.mjs --url <url> --sha256 <hash> --dest <dir> [--marker <file>] [--force]
+//
+// Bundles conhecidos: huashu-audio, canvas-fonts (ver BUNDLES abaixo).
+//
+// Cache: se o arquivo-marcador do bundle já existe no destino, não baixa de
+// novo (a menos que --force). Sem dependência nova: usa `node:https`/
+// `node:http` para o download e o binário `tar` do sistema (macOS/Linux/WSL,
+// mesmo escopo de suporte declarado do resto do framework) para extrair.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import http from 'node:http';
+import https from 'node:https';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+const RELEASE_BASE = 'https://github.com/wizzcomms/wizz-method/releases/download/assets-v1';
+
+// Fonte única dos bundles conhecidos. `dest` é relativo ao root do pacote
+// (repo em dev, node_modules/wizz-method quando instalado via npm — a mesma
+// árvore src/skills-lib/ existe nos dois casos). `marker` é um arquivo que só
+// existe depois de extraído com sucesso; presença dele = cache hit.
+export const BUNDLES = {
+  'huashu-audio': {
+    url: `${RELEASE_BASE}/huashu-audio.tar.gz`,
+    sha256: 'd20ddaefb7fd560837dec8d57ae8698ee51ef553d61a1367f0491183c613129f',
+    dest: 'src/skills-lib/huashu-design/assets',
+    marker: 'bgm-ad.mp3',
+    description: '6 trilhas BGM + SFX (huashu-design/assets/**/*.mp3, ~27MB)',
+  },
+  'canvas-fonts': {
+    url: `${RELEASE_BASE}/canvas-fonts.tar.gz`,
+    sha256: '7ac839f1dee2883b8e9a7022f246cfece4e203a2fd6ea23c81a5ffa49b812396',
+    dest: 'src/skills-lib/canvas-design/canvas-fonts',
+    marker: 'Outfit-Regular.ttf',
+    description: '~54 variantes de fonte (canvas-design/canvas-fonts/*.ttf, ~2.5MB)',
+  },
+};
+
+const NETWORK_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'ETIMEDOUT', 'EAI_AGAIN', 'ENETUNREACH']);
+
+function isNetworkError(err) {
+  return Boolean(err && (NETWORK_ERROR_CODES.has(err.code) || err.name === 'AbortError'));
+}
+
+/** Baixa `url` para `destFile`, seguindo redirects (GitHub release assets fazem 302). */
+function download(url, destFile, { maxRedirects = 5, timeoutMs = 30_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('https:') ? https : http;
+    const req = client.get(url, { timeout: timeoutMs }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        if (maxRedirects <= 0) {
+          reject(new Error(`Muitos redirects ao baixar ${url}`));
+          return;
+        }
+        const nextUrl = new URL(res.headers.location, url).toString();
+        download(nextUrl, destFile, { maxRedirects: maxRedirects - 1, timeoutMs }).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${res.statusCode} ao baixar ${url}`));
+        return;
+      }
+      const fileStream = fs.createWriteStream(destFile);
+      res.pipe(fileStream);
+      fileStream.on('finish', () => fileStream.close(() => resolve()));
+      fileStream.on('error', reject);
+      res.on('error', reject);
+    });
+    req.on('timeout', () => req.destroy(new Error(`Timeout ao baixar ${url}`)));
+    req.on('error', reject);
+  });
+}
+
+function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+function extractTarGz(tarFile, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  execFileSync('tar', ['-xzf', tarFile, '-C', destDir], { stdio: 'pipe' });
+}
+
+function isCached(destDir, marker) {
+  if (!marker) {
+    return fs.existsSync(destDir) && fs.readdirSync(destDir).length > 0;
+  }
+  return fs.existsSync(path.join(destDir, marker));
+}
+
+/**
+ * Baixa, verifica sha256 e extrai um bundle. Não escreve nada no destino se
+ * o sha256 não bater (aborta antes do extract). Cache: pula o download se o
+ * marcador já existir em `dest`, a menos que `force`.
+ *
+ * @returns {Promise<{ cached: boolean }>}
+ */
+export async function fetchBundle({ url, sha256, dest, marker, force = false }) {
+  const destDir = path.isAbsolute(dest) ? dest : path.join(PACKAGE_ROOT, dest);
+
+  if (!force && isCached(destDir, marker)) {
+    return { cached: true, dest: destDir };
+  }
+
+  const tmpFile = path.join(os.tmpdir(), `wizz-fetch-assets-${crypto.randomBytes(6).toString('hex')}.tar.gz`);
+  try {
+    await download(url, tmpFile);
+  } catch (error) {
+    fs.rmSync(tmpFile, { force: true });
+    if (isNetworkError(error)) {
+      throw new FetchAssetsError(
+        `Sem conexão para baixar o asset (${error.code || error.message}).\n` +
+          `  Baixe manualmente: ${url}\n` +
+          `  E extraia em: ${destDir}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+
+  const actualSha256 = await sha256File(tmpFile);
+  if (actualSha256 !== sha256) {
+    fs.rmSync(tmpFile, { force: true });
+    throw new FetchAssetsError(
+      `sha256 não confere para ${url}\n  esperado: ${sha256}\n  obtido:   ${actualSha256}\n` +
+        `Download abortado, nada foi extraído (bundle pode estar corrompido ou adulterado).`,
+    );
+  }
+
+  try {
+    extractTarGz(tmpFile, destDir);
+  } finally {
+    fs.rmSync(tmpFile, { force: true });
+  }
+
+  return { cached: false, dest: destDir };
+}
+
+export class FetchAssetsError extends Error {}
+
+async function fetchNamedBundle(name, { dest, force } = {}) {
+  const bundle = BUNDLES[name];
+  if (!bundle) {
+    throw new FetchAssetsError(`Bundle desconhecido: "${name}". Disponíveis: ${Object.keys(BUNDLES).join(', ')}`);
+  }
+  return fetchBundle({
+    url: bundle.url,
+    sha256: bundle.sha256,
+    dest: dest || bundle.dest,
+    marker: bundle.marker,
+    force,
+  });
+}
+
+function parseArgs(argv) {
+  const opts = { positional: [], force: false, all: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--force': {
+        opts.force = true;
+        break;
+      }
+      case '--all': {
+        opts.all = true;
+        break;
+      }
+      case '--dest': {
+        opts.dest = argv[++i];
+        break;
+      }
+      case '--url': {
+        opts.url = argv[++i];
+        break;
+      }
+      case '--sha256': {
+        opts.sha256 = argv[++i];
+        break;
+      }
+      case '--marker': {
+        opts.marker = argv[++i];
+        break;
+      }
+      default: {
+        opts.positional.push(arg);
+      }
+    }
+  }
+  return opts;
+}
+
+async function main(argv) {
+  const opts = parseArgs(argv);
+
+  if (opts.all) {
+    let exitCode = 0;
+    for (const name of Object.keys(BUNDLES)) {
+      try {
+        const result = await fetchNamedBundle(name, { force: opts.force });
+        console.log(result.cached ? `✓ ${name}: já em cache (${result.dest})` : `✓ ${name}: baixado em ${result.dest}`);
+      } catch (error) {
+        exitCode = 1;
+        console.error(`✗ ${name}: ${error.message}`);
+      }
+    }
+    process.exitCode = exitCode;
+    return;
+  }
+
+  if (opts.url && opts.sha256 && opts.dest) {
+    try {
+      const result = await fetchBundle({ url: opts.url, sha256: opts.sha256, dest: opts.dest, marker: opts.marker, force: opts.force });
+      console.log(result.cached ? `✓ já em cache (${result.dest})` : `✓ baixado em ${result.dest}`);
+    } catch (error) {
+      console.error(`✗ ${error.message}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const bundleName = opts.positional[0];
+  if (!bundleName) {
+    console.error(
+      'Uso: node tools/fetch-assets.mjs <bundle> [--dest <dir>] [--force]\n' +
+        '     node tools/fetch-assets.mjs --all\n' +
+        `Bundles: ${Object.entries(BUNDLES)
+          .map(([id, b]) => `\n  ${id} — ${b.description}`)
+          .join('')}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const result = await fetchNamedBundle(bundleName, { dest: opts.dest, force: opts.force });
+    console.log(result.cached ? `✓ ${bundleName}: já em cache (${result.dest})` : `✓ ${bundleName}: baixado em ${result.dest}`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === __filename;
+if (isMain) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(`✗ Erro inesperado: ${error.stack || error.message}`);
+    process.exitCode = 1;
+  });
+}

package/tools/installer/commands/fetch-assets.js

@@ -0,0 +1,71 @@
+// `wizz fetch-assets` — baixa sob demanda os assets pesados removidos do
+// pacote npm (Tarefa 2.8 da auditoria): MP3 do huashu-design e fontes do
+// canvas-design. Wrapper fino de commander sobre tools/fetch-assets.mjs (ESM
+// puro, sem dependência nova) — o motor real fica lá; este arquivo só expõe
+// o comando pro CLI e traduz flags/erros pro padrão dos outros comandos.
+//
+// `--bundle` (não posicional): o loader genérico em wizz-cli.js registra
+// `program.command(name)` sem placeholder de argumento pros comandos deste
+// diretório (todos os outros — install/status/uninstall — são só opções),
+// então um positional aqui quebraria com "too many arguments". Mantém a
+// mesma convenção do resto do CLI em vez de mexer no loader compartilhado.
+//
+// Por que uma flag --dest é essencial: uma skill instalada globalmente
+// (~/.claude/skills/huashu-design/) ou num projeto (.claude/skills/...) é uma
+// CÓPIA separada do pacote npm de origem — baixar só no pacote de origem não
+// ajuda a cópia já instalada. `npx wizz-method fetch-assets --bundle
+// huashu-audio --dest <pasta-da-skill>/assets`, rodado de dentro da skill
+// instalada, resolve os dois casos (skill local ao repo em dev, ou instalada
+// em qualquer lugar) sem a skill precisar saber onde o pacote wizz-method mora.
+
+module.exports = {
+  command: 'fetch-assets',
+  description: 'Baixa sob demanda os assets pesados (MP3 do huashu-design, fontes do canvas-design)',
+  options: [
+    ['--bundle <name>', 'Bundle a baixar (huashu-audio | canvas-fonts)'],
+    ['--dest <dir>', 'Destino da extração (default: local do bundle dentro do pacote wizz-method)'],
+    ['--force', 'Ignora o cache e rebaixa mesmo se os arquivos já existirem'],
+    ['--all', 'Baixa todos os bundles conhecidos'],
+  ],
+  action: async (options) => {
+    const { fetchBundle, BUNDLES } = await import('../../fetch-assets.mjs');
+
+    const targets = options.all ? Object.keys(BUNDLES) : options.bundle ? [options.bundle] : [];
+
+    if (targets.length === 0) {
+      console.error(
+        'Uso: wizz fetch-assets --bundle <nome> [--dest <dir>] [--force]\n' +
+          '     wizz fetch-assets --all\n' +
+          `Bundles: ${Object.entries(BUNDLES)
+            .map(([id, b]) => `\n  ${id} — ${b.description}`)
+            .join('')}`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    let exitCode = 0;
+    for (const name of targets) {
+      const meta = BUNDLES[name];
+      if (!meta) {
+        console.error(`✗ Bundle desconhecido: "${name}". Disponíveis: ${Object.keys(BUNDLES).join(', ')}`);
+        exitCode = 1;
+        continue;
+      }
+      try {
+        const result = await fetchBundle({
+          url: meta.url,
+          sha256: meta.sha256,
+          dest: options.dest || meta.dest,
+          marker: meta.marker,
+          force: options.force,
+        });
+        console.log(result.cached ? `✓ ${name}: já em cache (${result.dest})` : `✓ ${name}: baixado em ${result.dest}`);
+      } catch (error) {
+        exitCode = 1;
+        console.error(`✗ ${name}: ${error.message}`);
+      }
+    }
+    process.exitCode = exitCode;
+  },
+};

package/tools/installer/commands/install.js

@@ -90,6 +90,9 @@ module.exports = {
       const { checkWindowsNodeFromWsl } = require('../core/wsl-node-check');
       await checkWindowsNodeFromWsl();
 
+      const { checkRequiredTools } = require('../core/preflight-tools-check');
+      await checkRequiredTools();
+
       // Set debug flag as environment variable for all components
       if (options.debug) {
         process.env.WIZZ_DEBUG_MANIFEST = 'true';
@@ -127,6 +130,20 @@ module.exports = {
         const result = await installer.quickUpdate(config);
         await prompts.log.success('Quick update complete!');
         await prompts.log.info(`Updated ${result.moduleCount} modules with preserved settings (${result.modules.join(', ')})`);
+        // Quick Update never provisions global skills/MCPs/CLIs (see the
+        // isQuickUpdate() gate in core/installer.js). Say so in the final
+        // summary too, not just as a menu hint and an in-run log line, so
+        // the "no new skills" outcome is never a silent surprise.
+        await prompts.log.info(
+          'Skills/MCPs/CLIs não foram alterados (Quick Update). Para provisioná-los, rode install e escolha "Modify Wizz Installation".',
+        );
+        if (result.warnings > 0) {
+          await prompts.log.warn(`Concluído com ${result.warnings} aviso(s). Veja o resumo acima para detalhes.`);
+        }
+        if (result.errors > 0) {
+          await prompts.log.error(`Concluído com ${result.errors} falha(s) real(is). Veja o resumo acima para detalhes.`);
+          process.exit(1);
+        }
         process.exit(0);
       }
 
@@ -138,9 +155,24 @@ module.exports = {
         process.exit(0);
       }
 
-      // Check if installation succeeded
-      if (result && result.success) {
-        process.exit(0);
+      // Check if installation succeeded. Best-effort steps (IDE setup, global
+      // skills/MCP/CLI provisioning) never throw, so a real per-step failure
+      // used to leave `result.success` unset and the process to exit 0 by
+      // falling off the end of this handler with nothing left pending. Make
+      // the signal explicit and structured instead (see M24 in the
+      // installer audit): warn count is informational; a nonzero error
+      // count means a real failure happened and the exit code must reflect it.
+      if (result) {
+        if (result.warnings > 0) {
+          await prompts.log.warn(`Concluído com ${result.warnings} aviso(s). Veja o resumo acima para detalhes.`);
+        }
+        if (result.errors > 0) {
+          await prompts.log.error(`Concluído com ${result.errors} falha(s) real(is). Veja o resumo acima para detalhes.`);
+          process.exit(1);
+        }
+        if (result.success) {
+          process.exit(0);
+        }
       }
     } catch (error) {
       try {

package/tools/installer/commands/trace-report.js

@@ -0,0 +1,131 @@
+// `wizz trace-report` — resume o arquivo de trace local do roteamento
+// (Tarefa 3.8-E2 da auditoria 360°, ver `_audit/`). Só leitura: agrega o
+// JSONL escrito pelo hook global `tools/hooks/wizz-router-enforce.js`
+// (função `traceLine`, opt-in via WIZZ_TRACE=1) e imprime um resumo.
+//
+// A fórmula do caminho do arquivo replica `getTraceFile()` de
+// tools/hooks/wizz-router-enforce.js (linha ~170) — os dois arquivos vivem
+// em árvores independentes (tools/hooks/ vs tools/installer/), então
+// duplicar as 2 linhas é aceitável; qualquer mudança na fórmula do hook
+// precisa ser espelhada aqui.
+
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('../fs-native');
+const prompts = require('../prompts');
+
+function getTraceFile() {
+  return process.env.WIZZ_TRACE_FILE || path.join(os.homedir(), '.claude', 'wizz-trace.jsonl');
+}
+
+// Faz o parse de 1 linha JSONL. Retorna `null` (em vez de lançar) para
+// linhas corrompidas — fail-open, mesmo espírito do resto do framework: o
+// trace nunca pode quebrar quem o lê.
+function parseLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+// Agrega as entradas já parseadas em contadores/período. Função pura, sem
+// I/O, para ser testável isoladamente do disco.
+function aggregate(entries) {
+  const byMode = { wizz: 0, flat: 0, null: 0 };
+  let trivialCount = 0;
+  let warningsCount = 0;
+  let firstTs = null;
+  let lastTs = null;
+
+  for (const entry of entries) {
+    if (entry.isTrivial) {
+      trivialCount++;
+    } else {
+      const modeKey = entry.mode === 'wizz' || entry.mode === 'flat' ? entry.mode : 'null';
+      byMode[modeKey]++;
+      if (Array.isArray(entry.warnings) && entry.warnings.length > 0) warningsCount++;
+    }
+
+    if (typeof entry.ts === 'string') {
+      if (firstTs === null || entry.ts < firstTs) firstTs = entry.ts;
+      if (lastTs === null || entry.ts > lastTs) lastTs = entry.ts;
+    }
+  }
+
+  return {
+    total: entries.length,
+    trivialCount,
+    routedCount: entries.length - trivialCount,
+    byMode,
+    warningsCount,
+    firstTs,
+    lastTs,
+  };
+}
+
+function formatSummary(stats, traceFile) {
+  const lines = [
+    `Arquivo:        ${traceFile}`,
+    `Total de linhas: ${stats.total}`,
+    `Triviais:        ${stats.trivialCount}`,
+    `Roteados:        ${stats.routedCount}`,
+    `  modo wizz:     ${stats.byMode.wizz}`,
+    `  modo flat:     ${stats.byMode.flat}`,
+    `  modo nulo:     ${stats.byMode.null}`,
+    `Com warnings:    ${stats.warningsCount}`,
+    `Período:         ${stats.firstTs || '—'} → ${stats.lastTs || '—'}`,
+  ];
+  if (stats.corruptedCount > 0) {
+    lines.push(`Linhas ignoradas (corrompidas): ${stats.corruptedCount}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  command: 'trace-report',
+  description: 'Resume o arquivo local de trace do roteamento (WIZZ_TRACE)',
+  options: [],
+  action: async (options) => {
+    try {
+      const traceFile = getTraceFile();
+
+      if (!(await fs.pathExists(traceFile))) {
+        await prompts.log.warn('Nenhum trace encontrado.');
+        await prompts.log.message(`Local esperado: ${traceFile}`);
+        await prompts.log.message('Rode o install e ligue o medidor de roteamento, ou exporte WIZZ_TRACE=1.');
+        process.exit(0);
+        return;
+      }
+
+      const raw = await fs.readFile(traceFile, 'utf8');
+      const rawLines = raw.split('\n').filter((line) => line.trim().length > 0);
+
+      const entries = [];
+      let corruptedCount = 0;
+      for (const line of rawLines) {
+        const parsed = parseLine(line);
+        if (parsed === null) {
+          corruptedCount++;
+        } else {
+          entries.push(parsed);
+        }
+      }
+
+      const stats = { ...aggregate(entries), corruptedCount };
+
+      await prompts.box(formatSummary(stats, traceFile), 'Wizz Trace Report');
+
+      process.exit(0);
+    } catch (error) {
+      await prompts.log.error(`Trace report failed: ${error.message}`);
+      if (process.env.WIZZ_DEBUG) {
+        await prompts.log.message(error.stack);
+      }
+      process.exit(1);
+    }
+  },
+  // Exportado só para teste unitário direto da agregação, sem precisar
+  // spawnar o processo pra cada caso de borda.
+  _internal: { aggregate, parseLine, formatSummary },
+};

package/tools/installer/core/config.js

@@ -18,6 +18,7 @@ class Config {
     quickUpdate,
     channelOptions,
     setOverrides,
+    traceEnabled,
   }) {
     this.directory = directory;
     this.modules = Object.freeze([...modules]);
@@ -49,6 +50,13 @@ class Config {
     // Intentionally NOT integrated with the prompt/template/schema flow; see
     // `tools/installer/set-overrides.js` for the rationale and tradeoffs.
     this.setOverrides = setOverrides || {};
+    // 3.8-E1: whether the user opted into the local routing-trace measurement
+    // (WIZZ_TRACE=1, persisted into .claude/settings.local.json by the UI
+    // layer BEFORE install() runs — see ui.js#promptTraceOptIn). Tri-state on
+    // purpose: `null` means "never asked" (quick-update, update, or a module
+    // set that doesn't include bmm) so renderInstallSummary can omit the line
+    // entirely instead of misreporting an unasked question as "desligado".
+    this.traceEnabled = traceEnabled === undefined ? null : traceEnabled;
     Object.freeze(this);
   }
 
@@ -78,6 +86,7 @@ class Config {
       quickUpdate: userInput._quickUpdate || false,
       channelOptions: userInput.channelOptions || null,
       setOverrides: userInput.setOverrides || {},
+      traceEnabled: userInput.traceEnabled === undefined ? null : userInput.traceEnabled,
     });
   }