wize-dev-kit 0.16.0 → 0.17.0

package/tools/installer/wize-cli.js

@@ -3,9 +3,10 @@
  * wize-dev-kit — CLI entry point
  * Subcommands: install, update, uninstall, list, sync, agent, workflow, help
  *
- * This is a v0.1 scaffold. The interactive prompt logic and adapter rendering
- * are stubs; the dispatcher and basic install/uninstall create the .wize/
- * folder layout so downstream agents can be activated.
+ * v0.15.0 — Full-lifecycle CLI with install, update, uninstall, list, sync,
+ * agent, workflow, validate, doctor, and document-project commands. Adapters
+ * render for 11 IDE targets. Security overlay ships with 8 tools.
+ * `install --yes` now enables all harnesses + all overlays by default.
  */
 'use strict';
 
@@ -13,8 +14,16 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
+const { execSync } = require('node:child_process');
 const prompts = require('prompts');
 const { applyGitignore, generateUserToml } = require('./setup-helpers.js');
+const { cmdUpdate, loadProjectConfig } = require('./commands/update.js');
+const { printUpdateHintIfAny } = require('./version-check.js');
+const { cmdSync: cmdSyncReal } = require('./commands/sync.js');
+const { cmdAgentList, cmdAgentCreate, cmdAgentEdit } = require('./commands/agent.js');
+const { cmdDoctor, adapterTargetPath } = require('./commands/doctor.js');
+const { cmdDocumentProject } = require('./commands/document-project.js');
+const { compose: composeOnboarding } = require('./onboarding.js');
 
 const INTERACTIVE = process.stdout.isTTY && process.stdin.isTTY;
 
@@ -28,6 +37,8 @@ const TARGETS = [
   { code: 'codex', label: 'Codex', default: false },
   { code: 'continue', label: 'Continue', default: false },
   { code: 'kimi-code', label: 'Kimi Code', default: false },
+  { code: 'hermes', label: 'Hermes Agent (.hermes/skills/)', default: false },
+  { code: 'kiro', label: 'Kiro — AWS (.kiro/skills/)', default: false },
   { code: 'opencode', label: 'OpenCode', default: false },
   { code: 'antigravity', label: 'Antigravity (CLI + IDE)', default: false },
   { code: 'generic', label: 'Generic fallback (.wize/agents/)', default: true }
@@ -36,7 +47,8 @@ const TARGETS = [
 const PROFILES = [
   { code: 'core', label: 'Wize Dev Core', required: true },
   { code: 'web-overlay', label: 'Wize Web Dev (overlay)', required: false },
-  { code: 'app-overlay', label: 'Wize App Development (overlay)', required: false }
+  { code: 'app-overlay', label: 'Wize App Development (overlay)', required: false },
+  { code: 'security-overlay', label: 'Wize Security (AI Pentester overlay)', required: false }
 ];
 
 // Common BCP-47 short codes. Users can type any other value freely.
@@ -67,6 +79,8 @@ Commands:
   agent <create|list>     Manage agents (built-in or custom).
   workflow <create|list>  Manage workflows.
   validate                Run schema + lint + dry-run validators.
+  doctor                  Diagnose the kit + project state, suggest fixes.
+  document-project        Document the current repo (quick | initial_scan | full_rescan | deep_dive).
   help                    Show this message.
 
 Documentation:
@@ -86,18 +100,131 @@ function logo() {
   ].join('\n');
 }
 
+// Pipe-safe line reader.
+//
+// `readline.question()` has two bugs that bite us when stdin is a pipe (e.g.
+// `printf ... | wize-dev-kit install` or our CI smoke test):
+//   1. Opening a new createInterface per call closes stdin on .close().
+//   2. Even with a shared interface, the second `question` after a single
+//      empty line ("\n") never resolves — readline's question machinery
+//      stalls in non-TTY mode.
+//
+// We replace it with an event-based queue: subscribe to `line` once, push
+// resolved promises in order. Empty lines are propagated as `""`. EOF is
+// treated as end of the queue (remaining waiters resolve with `""`).
+let _rl = null;
+let _queue = [];
+let _waiters = [];
+
+function getRl() {
+  if (_rl) return _rl;
+  _rl = readline.createInterface({ input: process.stdin, terminal: false });
+  _rl.on('line', (line) => {
+    if (_waiters.length) _waiters.shift()(line);
+    else _queue.push(line);
+  });
+  _rl.on('close', () => {
+    while (_waiters.length) _waiters.shift()('');
+  });
+  process.on('exit', () => { if (_rl) { _rl.close(); _rl = null; } });
+  return _rl;
+}
+
 function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => rl.question(question, ans => { rl.close(); resolve(ans.trim()); }));
+  process.stdout.write(question);
+  getRl();
+  // In interactive mode, discard any residual lines left by previous
+  // prompts (e.g. the prompts library) so this prompt always waits for
+  // fresh user input. In non-TTY / piped mode, those queued lines are
+  // intentional input and must be consumed in order.
+  if (INTERACTIVE) {
+    _queue = [];
+  }
+  if (_queue.length) return Promise.resolve(_queue.shift().trim());
+  return new Promise(resolve => _waiters.push((line) => resolve(line.trim())));
 }
 
 async function confirm(question, defaultYes = true) {
+  if (INTERACTIVE) {
+    const { value } = await prompts({
+      type: 'confirm',
+      name: 'value',
+      message: question,
+      initial: defaultYes
+    });
+    if (value === undefined) process.exit(130);
+    return value;
+  }
   const hint = defaultYes ? '[Y/n]' : '[y/N]';
   const ans = (await prompt(`${question} ${hint} `)).toLowerCase();
   if (!ans) return defaultYes;
   return ans.startsWith('y');
 }
 
+async function promptText(question, defaultValue = '') {
+  if (INTERACTIVE) {
+    const { value } = await prompts({
+      type: 'text',
+      name: 'value',
+      message: question,
+      initial: defaultValue
+    });
+    if (value === undefined) process.exit(130);
+    return value.trim();
+  }
+  const ans = (await prompt(`${question} [${defaultValue}]: `)).trim();
+  return ans || defaultValue;
+}
+
+async function promptTextMandatory(question, defaultValue = '') {
+  if (INTERACTIVE) {
+    if (defaultValue) {
+      const { keep } = await prompts({
+        type: 'confirm',
+        name: 'keep',
+        message: `${question} (use "${defaultValue}"?)`,
+        initial: true
+      });
+      if (keep === undefined) process.exit(130);
+      if (keep) return defaultValue;
+    }
+    const { value } = await prompts({
+      type: 'text',
+      name: 'value',
+      message: question
+    });
+    if (value === undefined) process.exit(130);
+    const trimmed = value.trim();
+    if (trimmed) return trimmed;
+    if (defaultValue) return defaultValue;
+    return promptTextMandatory(question, defaultValue);
+  }
+  // Non-TTY: keep asking until non-empty.
+  for (;;) {
+    const ans = (await prompt(`${question}: `)).trim();
+    if (ans) return ans;
+    if (defaultValue) return defaultValue;
+    console.log('Please provide a value.');
+  }
+}
+
+async function select(label, choices, defaultValue) {
+  if (INTERACTIVE) {
+    const initial = choices.findIndex(c => c.value === defaultValue);
+    const { picked } = await prompts({
+      type: 'select',
+      name: 'picked',
+      message: label,
+      choices: choices.map(c => ({ title: c.title, value: c.value, description: c.description })),
+      initial: initial === -1 ? 0 : initial
+    });
+    if (picked === undefined) process.exit(130);
+    return picked;
+  }
+  // Non-TTY fallback: return default.
+  return defaultValue;
+}
+
 async function selectLanguage(label, defaultCode = 'en') {
   if (INTERACTIVE) {
     const choices = LANGUAGES.map(l => ({
@@ -302,49 +429,169 @@ function renderAdapters({ kitRoot, projectRoot, targets, profiles }) {
   return results;
 }
 
+// Parse --key value and --flag from an argv slice. Returns { flags, positional }.
+function parseArgs(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      if (key.includes('=')) {
+        const [k, v] = key.split('=', 2);
+        flags[k] = v;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+        flags[key] = args[++i];
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+function resolveProfiles(flags) {
+  if (!flags.profiles) return null;
+  const codes = flags.profiles.split(',').map(s => s.trim()).filter(Boolean);
+  const resolved = [];
+  for (const c of codes) {
+    const p = PROFILES.find(p => p.code === c);
+    if (p) resolved.push(p);
+    else console.log(`⚠  perfil desconhecido: "${c}" — ignorado`);
+  }
+  if (resolved.length === 0) return null;
+  return resolved;
+}
+
+function resolveTargets(flags) {
+  if (!flags.targets) return null;
+  const codes = flags.targets.split(',').map(s => s.trim()).filter(Boolean);
+  const resolved = [];
+  for (const c of codes) {
+    const t = TARGETS.find(t => t.code === c);
+    if (t) resolved.push(t);
+    else console.log(`⚠  target desconhecido: "${c}" — ignorado`);
+  }
+  if (resolved.length === 0) return null;
+  return resolved;
+}
+
+function resolveLang(flags) {
+  if (!flags.lang) return null;
+  const code = flags.lang.trim();
+  if (/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$/.test(code)) return code;
+  console.log(`⚠  código de idioma inválido: "${code}" — usando pt-BR`);
+  return null;
+}
+
+function resolveName(flags) {
+  if (flags.name) return flags.name.trim();
+  if (flags.yes) {
+    try { return execSync('git config user.name', { encoding: 'utf-8' }).trim(); } catch (_) {}
+    return process.env.USER || process.env.USERNAME || 'Developer';
+  }
+  return null;
+}
+
+// --yes quick install: everything on. All harnesses + all overlays, so
+// `npx wize-dev-kit install --yes` is a true one-shot full install.
+function defaultProfiles() {
+  return PROFILES.slice();
+}
+
+function defaultTargets() {
+  return TARGETS.slice();
+}
+
 async function cmdInstall(args) {
   const cwd = process.cwd();
+  const { flags } = parseArgs(args);
+  const dryRun = !!flags['dry-run'];
+  const nonInteractive = !!flags.yes;
+
   console.log(logo());
-  console.log('Installing Wize Development Kit into:', cwd);
+  if (dryRun) console.log('[DRY-RUN] Nenhum arquivo será modificado.\n');
+  console.log('Instalando Wize Development Kit em:', cwd);
+
   if (!isGitRepo(cwd)) {
-    console.log('\n⚠ not a git repo. Initialize git first or proceed at your own risk.');
-    const ok = await confirm('Continue anyway?', false);
+    console.log('\n⚠ não é um repositório git. Inicialize o git primeiro ou prossiga por sua conta e risco.');
+    if (nonInteractive) {
+      console.log('Modo não-interativo: abortando. Use --yes apenas em repositórios git.');
+      process.exit(1);
+    }
+    const ok = await confirm('Continuar mesmo assim?', false);
     if (!ok) process.exit(1);
   }
 
   const detection = detectBrownfield(cwd);
   if (detection.brownfield) {
-    console.log(`\nBrownfield signals detected: ${detection.signals.join(', ')}`);
+    console.log(`\nSinais de brownfield detectados: ${detection.signals.join(', ')}`);
+  } else {
+    console.log('\nRepositório greenfield detectado.');
+  }
+
+  // Resolve flags or fall back to interactive prompts.
+  let project_name, profiles, targets, communication_language, document_output_language, user_name, wantsGitignore;
+
+  if (nonInteractive) {
+    project_name = flags.name ? resolveName(flags) : (path.basename(cwd));
+    profiles = resolveProfiles(flags) || defaultProfiles();
+    targets = resolveTargets(flags) || defaultTargets();
+    communication_language = resolveLang(flags) || 'pt-BR';
+    document_output_language = resolveLang(flags) || communication_language;
+    user_name = resolveName(flags);
+    wantsGitignore = true;
   } else {
-    console.log('\nGreenfield repo detected.');
-  }
-
-  const project_name = (await prompt(`Project name [${path.basename(cwd)}]: `)) || path.basename(cwd);
-  const profiles = await multiSelect('Select profile(s) to install', PROFILES);
-  const targets = await multiSelect('Select IDE target(s)', TARGETS);
-
-  const communication_language = await selectLanguage(
-    'Communication language (how agents will talk to you in chat)',
-    'en'
-  );
-  const document_output_language = await selectLanguage(
-    `Document output language (language used in generated files; ENTER for "${communication_language}")`,
-    communication_language
-  );
-
-  // Personal touch — the user_name lands in .wize/config/user.toml (per-developer).
-  const defaultName = (os.userInfo().username || '').trim();
-  const user_name = (await prompt(
-    `How should the agents call you? [${defaultName || 'leave blank'}]: `
-  )).trim() || defaultName;
-
-  // Gitignore — opt-in, idempotent.
-  const wantsGitignore = await confirm(
-    'Add the suggested entries to .gitignore (user.toml + scratch + generated adapter outputs)?',
-    true
-  );
-
-  console.log('\nCreating .wize/ skeleton...');
+    project_name = (await promptText(`Nome do projeto`, path.basename(cwd))) || path.basename(cwd);
+    profiles = await multiSelect('Selecione o(s) perfil(is) para instalar', PROFILES);
+    targets = await multiSelect('Selecione o(s) IDE target(s)', TARGETS);
+
+    communication_language = await selectLanguage(
+      'Idioma de comunicação (como os agentes vão falar com você no chat)',
+      'pt-BR'
+    );
+    document_output_language = await selectLanguage(
+      `Idioma dos documentos (idioma usado nos arquivos gerados; ENTER para "${communication_language}")`,
+      communication_language
+    );
+
+    const defaultName = (os.userInfo().username || '').trim();
+    user_name = await promptTextMandatory(
+      'Como os agentes devem te chamar?',
+      defaultName
+    );
+
+    wantsGitignore = await confirm(
+      'Adicionar as entradas sugeridas ao .gitignore (user.toml + scratch + outputs de adapters)?',
+      true
+    );
+  }
+
+  // Show resolved config.
+  console.log(`\nConfiguração:`);
+  console.log(`  Projeto:       ${project_name}`);
+  console.log(`  Perfis:        ${profiles.map(p => p.code).join(', ')}`);
+  console.log(`  IDE targets:   ${targets.map(t => t.code).join(', ')}`);
+  console.log(`  Idioma comm:   ${communication_language}`);
+  console.log(`  Idioma docs:   ${document_output_language}`);
+  if (user_name) console.log(`  Nome:          ${user_name}`);
+  if (dryRun) console.log(`  Modo:          dry-run`);
+
+  if (dryRun) {
+    console.log('\n[DRY-RUN] Criaria estrutura .wize/:');
+    for (const dir of WIZE_DIRS) console.log(`  - ${dir}/`);
+    console.log(`[DRY-RUN] Escreveria .wize/config/project.toml`);
+    console.log(`[DRY-RUN] Escreveria .wize/config/user.toml`);
+    console.log(`[DRY-RUN] Escreveria .wize/config/tea.toml`);
+    if (wantsGitignore) console.log(`[DRY-RUN] Atualizaria .gitignore`);
+    console.log(`\n[DRY-RUN] Geraria adapters para: ${targets.map(t => t.code).join(', ')}`);
+    console.log('\n[DRY-RUN] Concluído. Nenhum arquivo foi modificado.');
+    return;
+  }
+
+  console.log('\nCriando estrutura .wize/...');
   for (const dir of WIZE_DIRS) mkdirp(path.join(cwd, dir));
 
   writeIfMissing(path.join(cwd, '.wize/config/project.toml'), projectToml({
@@ -353,20 +600,26 @@ async function cmdInstall(args) {
   writeIfMissing(path.join(cwd, '.wize/config/user.toml'), generateUserToml({ name: user_name }));
   writeIfMissing(path.join(cwd, '.wize/config/tea.toml'), teaToml());
 
-  console.log('✓ .wize/ created');
-  console.log(`✓ profiles: ${profiles.map(p => p.code).join(', ')}`);
+  console.log('✓ .wize/ criado');
+  console.log(`✓ perfis: ${profiles.map(p => p.code).join(', ')}`);
   console.log(`✓ ide targets: ${targets.map(t => t.code).join(', ')}`);
-  if (user_name) console.log(`✓ user.toml: agents will call you "${user_name}"`);
+  if (user_name) console.log(`✓ user.toml: agentes vão te chamar de "${user_name}"`);
+
+  if (profiles.some(p => p.code === 'security-overlay')) {
+    console.log('\n⚠  security-overlay selecionado — uso autorizado apenas.');
+    console.log('   Uso autorizado. Você é responsável por obter permissão antes de testar alvos que não são seus.');
+    console.log('   O kit detecta alvos fora do scope.md e recusa automaticamente; ainda assim, use com responsabilidade.');
+  }
 
   if (wantsGitignore) {
     const r = applyGitignore(cwd);
-    if (r.changed) console.log(`✓ .gitignore ${r.mode} with the wize-dev-kit block`);
-    else           console.log(`= .gitignore already up to date`);
+    if (r.changed) console.log(`✓ .gitignore ${r.mode} com o bloco wize-dev-kit`);
+    else           console.log(`= .gitignore já está atualizado`);
   } else {
-    console.log('= .gitignore untouched (you opted out of suggested entries)');
+    console.log('= .gitignore não modificado (você optou por não adicionar as entradas sugeridas)');
   }
 
-  console.log('\nGenerating IDE adapters...');
+  console.log('\nGerando adapters IDE...');
   const renderResults = renderAdapters({
     kitRoot: KIT_ROOT,
     projectRoot: cwd,
@@ -374,33 +627,191 @@ async function cmdInstall(args) {
     profiles
   });
   for (const r of renderResults) {
-    if (r.skipped) console.log(`  - ${r.code}: skipped (${r.reason})`);
-    else if (r.written) console.log(`  ✓ ${r.code}: ${r.written} skill(s) emitted`);
+    if (r.skipped) console.log(`  - ${r.code}: pulado (${r.reason})`);
+    else if (r.written) console.log(`  ✓ ${r.code}: ${r.written} skill(s) emitidas`);
     else if (r.error) console.log(`  ✖ ${r.code}: ${r.error}`);
   }
 
   if (detection.brownfield) {
-    const baseline = await confirm('\nRun `wize-document-project` to baseline the existing repo now?', true);
-    if (baseline) {
-      console.log('(stub) Pepper + Peggy would now produce the baseline docs in .wize/knowledge/document-project/.');
+    if (process.env.WIZE_SKIP_BASELINE === '1') {
+      console.log('\nWIZE_SKIP_BASELINE=1 — baseline não será executado.');
+    } else if (!INTERACTIVE || nonInteractive) {
+      console.log('\nInstalação não-interativa detectada; executando baseline rápido...');
+      cmdDocumentProject({ kitRoot: KIT_ROOT, projectRoot: cwd, args: ['quick'], opts: { log: console.log } });
+    } else {
+      const mode = await select(
+        'Documentar o repositório existente agora?',
+        [
+          { title: 'Baseline rápido (padrão, 6 arquivos)', value: 'quick' },
+          { title: 'Scan inicial (documentos de padrão + condicionais)', value: 'initial_scan' },
+          { title: 'Rescan completo (arquiva estado anterior, re-executa)', value: 'full_rescan' },
+          { title: 'Pular documentação por enquanto', value: 'skip' }
+        ],
+        'quick'
+      );
+      if (mode !== 'skip') {
+        cmdDocumentProject({ kitRoot: KIT_ROOT, projectRoot: cwd, args: [mode], opts: { log: console.log } });
+      } else {
+        console.log('\nDocumentação pulada. Execute `wize-dev-kit document-project` depois.');
+      }
     }
   }
 
-  console.log('\nDone. Activate Wizer in your IDE and say: "Brief me on this project."');
+  console.log('\n──────────────────────────────────────────────────────────────');
+  console.log('Concluído.');
+  console.log('');
+  console.log('⚠  Reinicie seu IDE — muitos harnesses carregam skills apenas na inicialização.');
+  console.log(composeOnboarding(detection, profiles));
+  console.log('');
+  console.log('Mantenha o kit sincronizado:');
+  console.log('  • `npx wize-dev-kit update`  atualizar adapters após nova versão do kit');
+  console.log('  • `npx wize-dev-kit sync`    re-renderizar adapters após editar config');
+  console.log('  • `npx wize-dev-kit agent list | create | edit <code>`  gerenciar agentes');
+  console.log('──────────────────────────────────────────────────────────────');
+}
+
+// AGENTS.md signature — used to detect whether the file was generated by the kit.
+const AGENTS_SIGNATURE = '# Agents — Wize Development Kit';
+
+function isKitAgentsMd(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  try {
+    const head = fs.readFileSync(filePath, 'utf-8').slice(0, 200);
+    return head.includes(AGENTS_SIGNATURE);
+  } catch { return false; }
+}
+
+// Delete wize-* entries from an adapter target directory. Returns count of
+// removed items (files + dirs). Safe: only deletes entries whose name starts
+// with "wize-".
+function cleanAdapterTarget(targetDir) {
+  if (!fs.existsSync(targetDir)) return 0;
+  let count = 0;
+  let entries;
+  try { entries = fs.readdirSync(targetDir); } catch { return 0; }
+  for (const name of entries) {
+    if (!name.startsWith('wize-')) continue;
+    const full = path.join(targetDir, name);
+    try {
+      fs.rmSync(full, { recursive: true, force: true });
+      count++;
+    } catch { /* skip permission errors */ }
+  }
+  return count;
 }
 
-async function cmdUninstall() {
+async function cmdUninstall(args) {
   const cwd = process.cwd();
-  const dir = path.join(cwd, '.wize');
-  if (!fs.existsSync(dir)) {
-    console.log('No .wize/ folder found here.');
+  const { flags } = parseArgs(args || []);
+  const dryRun = !!flags['dry-run'];
+
+  if (dryRun) console.log('[DRY-RUN] Nenhum arquivo será removido.\n');
+
+  const wizeDir = path.join(cwd, '.wize');
+  if (!fs.existsSync(wizeDir)) {
+    console.log('Nenhuma pasta .wize/ encontrada aqui.');
     return;
   }
-  const ok = await confirm(`Remove ${dir}? Your project source code is not touched.`, false);
-  if (!ok) return;
-  fs.rmSync(dir, { recursive: true, force: true });
-  console.log('Removed .wize/.');
-  console.log('(stub) IDE adapter files (.claude/skills/wize-*, .cursor/rules/wize-*) would be cleaned here.');
+
+  // Read project.toml to discover which IDE targets were configured.
+  let ideTargets = [];
+  try {
+    const cfg = loadProjectConfig(cwd);
+    ideTargets = (cfg.install && cfg.install.ide_targets) || [];
+  } catch { /* project.toml may be missing or corrupt */ }
+
+  // Build the list of what would be removed.
+  const toRemove = [];
+
+  // 1. Adapter target dirs (wize-* entries).
+  const adapterDirs = [];
+  for (const code of ideTargets) {
+    const dir = adapterTargetPath(code, cwd);
+    if (!dir) continue;
+    if (!fs.existsSync(dir)) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+    for (const name of entries) {
+      if (!name.startsWith('wize-')) continue;
+      adapterDirs.push({ target: code, dir, name, full: path.join(dir, name) });
+    }
+  }
+
+  // 2. .wize/ directory.
+  toRemove.push({ kind: 'diretório', path: wizeDir, label: '.wize/' });
+
+  // 3. AGENTS.md if kit-generated.
+  const agentsMd = path.join(cwd, 'AGENTS.md');
+  if (isKitAgentsMd(agentsMd)) {
+    toRemove.push({ kind: 'arquivo', path: agentsMd, label: 'AGENTS.md' });
+  }
+
+  // Show what will be removed.
+  if (adapterDirs.length > 0) {
+    console.log('Arquivos de adapter que serão removidos:');
+    const byTarget = {};
+    for (const a of adapterDirs) {
+      byTarget[a.target] = byTarget[a.target] || [];
+      byTarget[a.target].push(a.name);
+    }
+    for (const [code, names] of Object.entries(byTarget)) {
+      console.log(`  ${code}: ${names.length} entrada(s) (${names.slice(0, 5).join(', ')}${names.length > 5 ? '...' : ''})`);
+    }
+  } else {
+    console.log('Nenhum arquivo de adapter wize-* encontrado.');
+  }
+
+  console.log(`\nSerá removido:`);
+  for (const item of toRemove) {
+    console.log(`  - ${item.label} (${item.kind})`);
+  }
+  if (adapterDirs.length > 0) {
+    console.log(`  - ${adapterDirs.length} entrada(s) wize-* nos diretórios de adapter`);
+  }
+
+  if (dryRun) {
+    console.log('\n[DRY-RUN] Concluído. Nenhum arquivo foi removido.');
+    return;
+  }
+
+  const totalItems = toRemove.length + adapterDirs.length;
+  if (totalItems === 0) {
+    console.log('\nNada para remover.');
+    return;
+  }
+
+  const ok = await confirm(`\nRemover ${totalItems} item(ns)? O código-fonte do seu projeto não será afetado.`, false);
+  if (!ok) {
+    console.log('Cancelado.');
+    return;
+  }
+
+  // Capture AGENTS.md status before deletion.
+  const hadAgentsMd = isKitAgentsMd(agentsMd);
+
+  // Delete adapter entries first.
+  let adapterCount = 0;
+  for (const a of adapterDirs) {
+    try {
+      fs.rmSync(a.full, { recursive: true, force: true });
+      adapterCount++;
+    } catch (err) {
+      console.log(`  ✖ erro ao remover ${a.name}: ${err.message}`);
+    }
+  }
+
+  // Delete .wize/ and AGENTS.md.
+  for (const item of toRemove) {
+    try {
+      fs.rmSync(item.path, { recursive: true, force: true });
+    } catch (err) {
+      console.log(`  ✖ erro ao remover ${item.label}: ${err.message}`);
+    }
+  }
+
+  console.log(`\n✓ Removido: .wize/ + ${adapterCount} entrada(s) de adapter`);
+  if (hadAgentsMd) console.log('✓ AGENTS.md removido');
+  console.log('\nO código-fonte do seu projeto não foi alterado.');
 }
 
 function cmdList() {
@@ -418,9 +829,10 @@ function cmdList() {
     ['wize-agent-dev', 'Shuri']
   ];
   for (const [code, name] of list) console.log(`  ${code.padEnd(36)} ${name}`);
+  console.log(`  ${'wize-sec-red-teamer'.padEnd(36)} Natasha Romanoff  (security-overlay, opt-in)`);
 
   console.log('\nWorkflows directories:');
-  const phases = ['1-analysis', '2-plan-workflows', '3-solutioning', '4-implementation'];
+  const phases = ['1-analysis', '2-plan', '3-solutioning', '4-implementation'];
   for (const phase of phases) {
     const dir = path.join(KIT_ROOT, 'src/method-skills', phase);
     if (!fs.existsSync(dir)) continue;
@@ -432,17 +844,18 @@ function cmdList() {
 }
 
 function cmdSync() {
-  console.log('(stub) Sync would regenerate IDE adapter files for active targets in .wize/config/project.toml.');
+  return cmdSyncReal({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
 }
 
 function cmdAgent(args) {
   const sub = args[0] || 'list';
-  if (sub === 'list') return cmdList();
-  if (sub === 'create') {
-    console.log('(stub) Interactive agent creation. See src/builder-skills/wize-create-agent/workflow.md.');
-    return;
-  }
+  const rest = args.slice(1);
+  const ctx = { kitRoot: KIT_ROOT, projectRoot: process.cwd() };
+  if (sub === 'list')   return cmdAgentList(ctx);
+  if (sub === 'create') return cmdAgentCreate(ctx);
+  if (sub === 'edit')   return cmdAgentEdit({ ...ctx, code: rest[0] });
   console.log(`Unknown agent subcommand: ${sub}`);
+  console.log('Available: list | create | edit <code>');
 }
 
 function cmdWorkflow(args) {
@@ -459,21 +872,39 @@ function cmdValidate() {
   require('./validators/run-all.js')(KIT_ROOT);
 }
 
+// Commands worth nudging the user about when a newer version exists. Skipped
+// for `update` (already updating), `install` (already setting up), `uninstall`
+// (already leaving), `validate` (developer-tool), and `version` (the user is
+// already asking about versions).
+const HINT_COMMANDS = new Set(['list', 'sync', 'agent', 'workflow', 'help', 'doctor', 'document-project']);
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    await printUpdateHintIfAny(KIT_VERSION);
     console.log(HELP);
     return;
   }
+  if (HINT_COMMANDS.has(cmd)) {
+    await printUpdateHintIfAny(KIT_VERSION);
+  }
   switch (cmd) {
     case 'install':   return cmdInstall(rest);
-    case 'update':    console.log('(stub) Update: diff + preserve customizations. Not yet implemented.'); return;
-    case 'uninstall': return cmdUninstall();
+    case 'update':    return cmdUpdate({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
+    case 'uninstall': return cmdUninstall(rest);
     case 'list':      return cmdList();
     case 'sync':      return cmdSync();
     case 'agent':     return cmdAgent(rest);
     case 'workflow':  return cmdWorkflow(rest);
     case 'validate':  return cmdValidate();
+    case 'doctor':    return cmdDoctor({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
+    case 'document-project':
+      return cmdDocumentProject({
+        kitRoot: KIT_ROOT,
+        projectRoot: process.cwd(),
+        args: rest,
+        opts: { log: console.log }
+      });
     case 'version':
     case '--version':
     case '-v':