wizz-method 2.11.2 → 2.13.0

package/src/skills-lib/wizz-video-effects/scripts/timeline.py

@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+"""Read and write the timeline JSON every script shares.
+
+The shape is documented in references/data-contract.md. This module only
+normalizes it: absent lists become empty lists, never errors, and every
+instant comes back as a float in seconds.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+class TimelineError(Exception):
+    """Timeline file missing or malformed."""
+
+
+def load(path: str | Path) -> dict:
+    p = Path(path)
+    if not p.exists():
+        raise TimelineError(f"timeline not found: {p}")
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise TimelineError(f"{p} is not valid JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise TimelineError(f"{p}: the timeline must be a JSON object")
+    return data
+
+
+def save(path: str | Path, data: dict) -> None:
+    Path(path).write_text(json.dumps(data, ensure_ascii=False, indent=1) + "\n",
+                          encoding="utf-8")
+
+
+def instants(items, key: str = "at") -> list[float]:
+    """A list of numbers OR of objects {key: ...} as sorted floats."""
+    if not items:
+        return []
+    return sorted(float(i[key]) if isinstance(i, dict) else float(i) for i in items)
+
+
+def transitions(scenes) -> list[float]:
+    """Scene starts with a real transition (not empty, not 'cut')."""
+    out = []
+    for s in scenes or []:
+        tr = s.get("transition")
+        if tr and tr != "cut" and "start" in s:
+            out.append(float(s["start"]))
+    return sorted(out)
+
+
+def duration(data: dict) -> tuple[float, bool]:
+    """(duration, derived). Uses `duration`; else the largest scene end."""
+    if data.get("duration"):
+        return float(data["duration"]), False
+    ends = [float(s["start"]) + float(s.get("dur", 0.0))
+            for s in (data.get("scenes") or []) if "start" in s]
+    return (max(ends), True) if ends else (0.0, True)
+
+
+def fps(data: dict, default: int) -> int:
+    return int(data.get("fps") or default)
+
+
+def sounds(data: dict) -> list[dict]:
+    """Every sound of the piece, sorted by `at`: sfx[] plus scene-level sfx
+    (a scene's `sfx` plays at the scene start)."""
+    out = [dict(s) for s in (data.get("sfx") or [])]
+    for sc in data.get("scenes") or []:
+        s = sc.get("sfx")
+        if isinstance(s, dict) and "start" in sc:
+            out.append({**s, "at": float(sc["start"]), "scene": True})
+    return sorted(out, key=lambda s: float(s["at"]))
+
+
+def effect_events(data: dict) -> dict[str, list[float]]:
+    """Visual effect instants by budget kind."""
+    return {
+        "punch": instants(data.get("punches")),
+        "shake": instants(data.get("shakes")),
+        "flash": instants(data.get("flashes")),
+        "interrupt": instants(data.get("interrupts")),
+        "transition": transitions(data.get("scenes")),
+    }

package/tools/installer/banner.js

@@ -1,40 +1,91 @@
 const prompts = require('./prompts');
+const { t } = require('./guided/messages');
+
+// Wizz brand palette (brand book): Wizz Orange and its deep shade.
+const BRAND_ORANGE = [255, 69, 0];
+const BRAND_DEEP = [204, 55, 0];
+// Built from the char code on purpose: a literal escape byte in source turns
+// the file binary for git (see the review-prep.mjs incident).
+const ESC = String.fromCodePoint(27);
+
+/**
+ * Paint text with a 24-bit brand color, or leave it plain when the terminal
+ * has no color support (NO_COLOR, pipes, CI logs).
+ * @param {number[]} rgb - [r, g, b]
+ * @param {string} text - Text to paint
+ * @param {boolean} enabled - Whether color is supported
+ * @returns {string}
+ */
+function paint(rgb, text, enabled) {
+  if (!enabled) return text;
+  return `${ESC}[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}${ESC}[39m`;
+}
+
+const LOGO_WIDE = [
+  '██╗    ██╗ ██╗ ███████╗ ███████╗    ███╗   ███╗ ███████╗ ████████╗ ██╗  ██╗  ██████╗  ██████╗  ™',
+  '██║    ██║ ██║ ╚══███╔╝ ╚══███╔╝    ████╗ ████║ ██╔════╝ ╚══██╔══╝ ██║  ██║ ██╔═══██╗ ██╔══██╗',
+  '██║ █╗ ██║ ██║   ███╔╝    ███╔╝     ██╔████╔██║ █████╗      ██║    ███████║ ██║   ██║ ██║  ██║',
+  '██║███╗██║ ██║  ███╔╝    ███╔╝      ██║╚██╔╝██║ ██╔══╝      ██║    ██╔══██║ ██║   ██║ ██║  ██║',
+  '╚███╔███╔╝ ██║ ███████╗ ███████╗    ██║ ╚═╝ ██║ ███████╗    ██║    ██║  ██║ ╚██████╔╝ ██████╔╝',
+  ' ╚══╝╚══╝  ╚═╝ ╚══════╝ ╚══════╝    ╚═╝     ╚═╝ ╚══════╝    ╚═╝    ╚═╝  ╚═╝  ╚═════╝  ╚═════╝ ',
+];
+
+const LOGO_NARROW = [
+  '██╗    ██╗ ██╗ ███████╗ ███████╗ ™',
+  '██║    ██║ ██║ ╚══███╔╝ ╚══███╔╝',
+  '██║ █╗ ██║ ██║   ███╔╝    ███╔╝ ',
+  '██║███╗██║ ██║  ███╔╝    ███╔╝  ',
+  '╚███╔███╔╝ ██║ ███████╗ ███████╗',
+  ' ╚══╝╚══╝  ╚═╝ ╚══════╝ ╚══════╝',
+];
 
 const CLIUtils = {
   /**
-   * Display Wizz Method logo and version using @clack intro + box
+   * Display the Wizz Method opening screen. With `steps`, it also lists the
+   * guided path's four steps so the user knows what comes next.
+   * @param {Object} [opts]
+   * @param {boolean} [opts.steps=false] - Show the "what happens next" list
+   * @param {'en'|'pt'} [opts.lang='en'] - Display language
+   * @param {string} [opts.version] - Version shown under the logo
    */
-  async displayLogo() {
+  async displayLogo(opts = {}) {
+    const { steps = false, lang = 'en', version } = opts;
     const color = await prompts.getColor();
+    const colorOn = color.isColorSupported !== false;
     const termWidth = process.stdout.columns || 80;
 
-    // Full "WIZZ METHOD" logo for wide terminals, "WIZZ" only for narrow
-    const logoWide = [
-      '██╗    ██╗ ██╗ ███████╗ ███████╗    ███╗   ███╗ ███████╗ ████████╗ ██╗  ██╗  ██████╗  ██████╗  ™',
-      '██║    ██║ ██║ ╚══███╔╝ ╚══███╔╝    ████╗ ████║ ██╔════╝ ╚══██╔══╝ ██║  ██║ ██╔═══██╗ ██╔══██╗',
-      '██║ █╗ ██║ ██║   ███╔╝    ███╔╝     ██╔████╔██║ █████╗      ██║    ███████║ ██║   ██║ ██║  ██║',
-      '██║███╗██║ ██║  ███╔╝    ███╔╝      ██║╚██╔╝██║ ██╔══╝      ██║    ██╔══██║ ██║   ██║ ██║  ██║',
-      '╚███╔███╔╝ ██║ ███████╗ ███████╗    ██║ ╚═╝ ██║ ███████╗    ██║    ██║  ██║ ╚██████╔╝ ██████╔╝',
-      ' ╚══╝╚══╝  ╚═╝ ╚══════╝ ╚══════╝    ╚═╝     ╚═╝ ╚══════╝    ╚═╝    ╚═╝  ╚═╝  ╚═════╝  ╚═════╝ ',
-    ];
-
-    const logoNarrow = [
-      '    ██╗    ██╗ ██╗ ███████╗ ███████╗ ™',
-      '    ██║    ██║ ██║ ╚══███╔╝ ╚══███╔╝',
-      '    ██║ █╗ ██║ ██║   ███╔╝    ███╔╝ ',
-      '    ██║███╗██║ ██║  ███╔╝    ███╔╝  ',
-      '    ╚███╔███╔╝ ██║ ███████╗ ███████╗',
-      '     ╚══╝╚══╝  ╚═╝ ╚══════╝ ╚══════╝',
-    ];
-
-    const logoLines = termWidth >= 95 ? logoWide : logoNarrow;
-    const logo = logoLines.map((line) => color.blue(line)).join('\n');
-    const tagline = color.white('    Método de agência orientado por IA\n    © Wizz! comms.  ·  method.wizzcomms.com');
-
-    await prompts.box(`${logo}\n${tagline}`, '', {
-      contentAlign: 'center',
+    const wide = termWidth >= 100;
+    const logoLines = wide ? LOGO_WIDE : LOGO_NARROW;
+    // Top half in Wizz Orange, bottom half in the deep shade: reads as a
+    // light-to-shadow gradient without a per-character color ramp.
+    const half = Math.ceil(logoLines.length / 2);
+    const logo = logoLines.map((line, i) => paint(i < half ? BRAND_ORANGE : BRAND_DEEP, line, colorOn));
+    if (!wide) logo.push(paint(BRAND_ORANGE, 'M E T H O D', colorOn));
+
+    const lines = [...logo, ''];
+    const versionTag = version ? color.dim(`v${version}`) : '';
+    lines.push(`${color.white(t(lang, 'tagline'))}  ${versionTag}`.trimEnd());
+
+    if (steps) {
+      lines.push('', `${color.bold(t(lang, 'whatHappens'))}  ${color.dim(`(${t(lang, 'duration')})`)}`);
+      for (const [i, name] of t(lang, 'stepNames').entries()) {
+        lines.push(`${paint(BRAND_ORANGE, String(i + 1), colorOn)} ▸ ${name}`);
+      }
+    }
+
+    lines.push('', color.dim('© Wizz! comms.  ·  method.wizzcomms.com'));
+
+    // A terminal that reports 0 columns (some ptys, expect, CI with a TTY)
+    // makes clack's box compute a negative width and throw. Print the same
+    // lines without the frame instead of failing the install.
+    if (!process.stdout.columns || process.stdout.columns < 40) {
+      process.stdout.write(`${lines.join('\n')}\n\n`);
+      return;
+    }
+    await prompts.box(lines.join('\n'), '', {
+      contentAlign: steps ? 'left' : 'center',
       rounded: true,
-      formatBorder: color.blue,
+      formatBorder: (text) => paint(BRAND_DEEP, text, colorOn),
     });
   },
 
@@ -50,4 +101,4 @@ const CLIUtils = {
   },
 };
 
-module.exports = { CLIUtils };
+module.exports = { CLIUtils, paint, BRAND_ORANGE, BRAND_DEEP };

package/tools/installer/commands/catalog.js

@@ -0,0 +1,87 @@
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('node:fs');
+const { getProjectRoot } = require('../project-root');
+const { loadYamlCached } = require('../core/yaml-cache');
+const { AREA_LABELS, cliBadges, cliDescription } = require('../guided/labels');
+const { normalizeLang, t } = require('../guided/messages');
+const { paint, BRAND_ORANGE } = require('../banner');
+
+const SKILL_DIRS = ['.claude/skills', '.agents/skills'];
+
+/**
+ * Whether a skill folder exists in the project or in the global Claude
+ * skills folder. Only a hint for the ✓ mark; nothing depends on it.
+ */
+function isSkillInstalled(id, projectDir, home) {
+  const places = [...SKILL_DIRS.map((dir) => path.join(projectDir, dir, id)), path.join(home, '.claude', 'skills', id)];
+  return places.some((place) => fs.existsSync(place));
+}
+
+/** First sentence of a registry `when:`, cut to fit one terminal line. */
+function shortWhen(when, max = 90) {
+  const first = String(when || '').split(/(?<=[.!?])\s/)[0];
+  return first.length > max ? `${first.slice(0, max - 1)}…` : first;
+}
+
+/**
+ * Render the catalog as plain text lines.
+ * @param {Object} registry - Parsed skills-registry.yaml
+ * @param {Object} opts
+ * @param {'en'|'pt'} opts.lang - Display language
+ * @param {string|null} opts.area - Only this area, or null for all
+ * @param {(id: string) => boolean} opts.installed - Installed check
+ * @param {boolean} opts.color - Whether to paint
+ * @returns {string[]}
+ */
+function renderCatalog(registry, opts) {
+  const { lang, area, installed, color } = opts;
+  const areas = Object.entries(registry.areas || {}).filter(([key]) => !area || key === area);
+  const lines = [];
+  for (const [key, entry] of areas) {
+    const label = AREA_LABELS[key] ? AREA_LABELS[key][lang] : { name: key, help: entry.summary || '' };
+    lines.push('', `${paint(BRAND_ORANGE, `■ ${label.name}`, color)}  (${key}) · ${label.help}`);
+    for (const skill of entry.skills || []) {
+      const mark = installed(skill.id) ? '✓' : ' ';
+      lines.push(`  ${mark} ${skill.id.padEnd(40)} ${shortWhen(skill.when)}`);
+    }
+    for (const cli of entry.clis || []) {
+      const badges = cliBadges(cli, lang);
+      const needs = badges.length > 0 ? ` [${badges.join(', ')}]` : ` [${t(lang, 'free')}]`;
+      lines.push(`  ⌘ ${cli.id.padEnd(40)} ${cliDescription(cli.id, lang)}${needs}`);
+    }
+    for (const mcp of entry.mcps || []) {
+      lines.push(`  ◇ ${mcp.id.padEnd(40)} ${shortWhen(mcp.when)}`);
+    }
+  }
+  return lines;
+}
+
+module.exports = {
+  command: 'catalog',
+  description: 'List every area, skill and tool Wizz Method can install (✓ = installed)',
+  options: [
+    ['--area <area>', 'Only one area, e.g. social or dev'],
+    ['--lang <lang>', 'Language for area names and tool descriptions: en (default) or pt'],
+  ],
+  action: async (options) => {
+    const registry = await loadYamlCached(path.join(getProjectRoot(), 'skills-registry.yaml'));
+    if (options.area && !(registry.areas || {})[options.area]) {
+      process.stderr.write(`Unknown area "${options.area}". Areas: ${Object.keys(registry.areas).join(', ')}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    const projectDir = process.cwd();
+    const home = os.homedir();
+    const lang = normalizeLang(options.lang) || 'en';
+    const lines = renderCatalog(registry, {
+      lang,
+      area: options.area || null,
+      installed: (id) => isSkillInstalled(id, projectDir, home),
+      color: !!process.stdout.isTTY && !process.env.NO_COLOR,
+    });
+    lines.push('', t(lang, 'catalogLegend'), '');
+    process.stdout.write(lines.join('\n'));
+  },
+  renderCatalog,
+};

package/tools/installer/commands/install.js

@@ -47,6 +47,11 @@ module.exports = {
     ['--output-folder <path>', 'Output folder path relative to project root (default: _wizz-output)'],
     ['--custom-source <sources>', 'Comma-separated Git URLs or local paths to install custom modules from'],
     ['-y, --yes', 'Accept all defaults and skip prompts where possible'],
+    ['--lang <lang>', 'Installer language for the guided install: en (default) or pt'],
+    [
+      '--advanced',
+      'Skip the guided install and ask every question: module list, community modules, release channels, artifact folders and the routing meter',
+    ],
     [
       '--channel <channel>',
       'Apply channel (stable|next) to all external modules being installed. --all-stable and --all-next are aliases.',
@@ -171,6 +176,10 @@ module.exports = {
           process.exit(1);
         }
         if (result.success) {
+          if (config.guided) {
+            const { showGuidedOutro } = require('../guided/outro');
+            await showGuidedOutro(config);
+          }
           process.exit(0);
         }
       }

package/tools/installer/guided/detect-tools.js

@@ -0,0 +1,53 @@
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+
+/**
+ * Signs that an AI tool is present on this machine: a binary on PATH, a
+ * config folder in the home directory or an installed app. Any one is
+ * enough; this only decides which option comes pre-checked, never what
+ * gets installed.
+ */
+const SIGNS = {
+  'claude-code': { bins: ['claude'], homeDirs: ['.claude'], apps: [] },
+  codex: { bins: ['codex'], homeDirs: ['.codex'], apps: [] },
+  cursor: { bins: ['cursor'], homeDirs: ['.cursor'], apps: ['Cursor.app'] },
+  'github-copilot': { bins: [], homeDirs: [], apps: [], vscodeExtension: 'github.copilot' },
+};
+
+function onPath(bin) {
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const exts = process.platform === 'win32' ? ['.exe', '.cmd', ''] : [''];
+  return dirs.some((dir) => exts.some((ext) => fs.existsSync(path.join(dir, bin + ext))));
+}
+
+function hasVscodeExtension(prefix, home) {
+  const extDir = path.join(home, '.vscode', 'extensions');
+  try {
+    return fs.readdirSync(extDir).some((name) => name.toLowerCase().startsWith(prefix));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Which of the preferred AI tools look installed.
+ * @param {Object} [deps] - Injection seam for tests
+ * @param {string} [deps.home] - Home directory
+ * @returns {string[]} Tool ids, e.g. ['claude-code', 'cursor']
+ */
+function detectAiTools(deps = {}) {
+  const home = deps.home || os.homedir();
+  const found = [];
+  for (const [id, sign] of Object.entries(SIGNS)) {
+    const present =
+      sign.bins.some((bin) => onPath(bin)) ||
+      sign.homeDirs.some((dir) => fs.existsSync(path.join(home, dir))) ||
+      sign.apps.some((app) => fs.existsSync(path.join('/Applications', app))) ||
+      (sign.vscodeExtension ? hasVscodeExtension(sign.vscodeExtension, home) : false);
+    if (present) found.push(id);
+  }
+  return found;
+}
+
+module.exports = { detectAiTools };

package/tools/installer/guided/flow.js

@@ -0,0 +1,203 @@
+/**
+ * Guided install: the default path for a first install in an interactive
+ * terminal. Four steps (folder, profile, AI tool, name), a review screen and
+ * sensible defaults for everything else. The full question-by-question flow
+ * stays available with --advanced, and every non-interactive flag keeps
+ * working exactly as before (those paths never reach this file).
+ */
+const prompts = require('../prompts');
+const { t, LANGUAGES } = require('./messages');
+const { getProfile, summarizeAreas } = require('./profiles');
+const steps = require('./steps');
+const { AREA_LABELS } = require('./labels');
+
+// Flags that already answer part of the install: when present the user is
+// scripting or knows what they want, so the legacy flow handles it verbatim.
+const SCRIPTED_FLAGS = [
+  'yes',
+  'advanced',
+  'modules',
+  'tools',
+  'areas',
+  'mcps',
+  'clis',
+  'customSource',
+  'action',
+  'set',
+  'channel',
+  'allStable',
+  'allNext',
+  'next',
+  'pin',
+];
+
+/**
+ * Whether this run should take the guided path.
+ * @param {Object} options - Parsed CLI options
+ * @param {boolean} [isTTY] - Injection seam for tests
+ * @returns {boolean}
+ */
+function isGuidedEligible(options = {}, isTTY = !!process.stdin.isTTY) {
+  if (!isTTY) return false;
+  return !SCRIPTED_FLAGS.some((flag) => {
+    const value = options[flag];
+    return Array.isArray(value) ? value.length > 0 : value !== undefined && value !== false;
+  });
+}
+
+async function listModules() {
+  const { OfficialModules } = require('../modules/official-modules');
+  const { ExternalModuleManager } = require('../modules/external-manager');
+  const builtIn = ((await new OfficialModules().listAvailable()).modules || []).map((mod) => ({
+    code: mod.id,
+    name: mod.name,
+    description: mod.description,
+    defaultSelected: mod.defaultSelected,
+    fromBmad: false,
+  }));
+  const seen = new Set(builtIn.map((mod) => mod.code));
+  const external = (await new ExternalModuleManager().listAvailable())
+    .filter((mod) => !mod.builtIn && !mod.deprecated && !mod.advancedOnly && !seen.has(mod.code))
+    .map((mod) => ({
+      code: mod.code,
+      name: mod.name,
+      description: mod.description,
+      defaultSelected: false,
+      fromBmad: String(mod.url || '').includes('bmad-code-org'),
+    }));
+  return [...builtIn, ...external];
+}
+
+/**
+ * Resolve what a profile installs. Custom asks modules and areas here.
+ * @returns {Promise<{modules: string[], areas: string[]}>} areas [] = all
+ */
+async function resolveSelection(profileId, lang, registry) {
+  const profile = getProfile(profileId);
+  if (profile.id !== 'custom') {
+    return { modules: [...profile.modules], areas: profile.areas ? [...profile.areas] : [] };
+  }
+  const modules = await steps.askModules(lang, await listModules());
+  const areas = modules.includes('bmm') ? await steps.askAreas(lang, registry) : [];
+  return { modules, areas };
+}
+
+async function showReview(ctx) {
+  const { lang, profileId, selection, registry, ides } = ctx;
+  const color = await prompts.getColor();
+  const summary = summarizeAreas(registry, selection.areas);
+  const ok = color.green('✓');
+  const lines = [
+    `${ok} ${t(lang, 'reviewAgents', { n: summary.agents })}  ${color.dim(summary.areas.map((key) => (AREA_LABELS[key] ? AREA_LABELS[key][lang].name : key)).join(' · '))}`,
+    `${ok} ${t(lang, 'reviewSkills', { n: summary.skills })}  ${color.dim(t(lang, 'reviewSkillsHint'))}`,
+    `${ok} ${t(lang, 'reviewMemory')}  ${color.dim(t(lang, 'reviewMemoryHint'))}`,
+    `${ok} ${t(lang, 'reviewTools')}  ${color.dim(ides.join(', '))}`,
+  ];
+  if (selection.modules.includes('lowticket')) lines.push(`${ok} ${t(lang, 'reviewLowticket')}`);
+  await prompts.note(lines.join('\n'), `${t(lang, 'reviewTitle')} (${getProfile(profileId)[lang].name})`);
+}
+
+async function chooseClis(ui, lang, selection) {
+  const plan = await ui.selectClis(selection.modules, selection.areas, {
+    cliMessage: t(lang, 'optionalTitle'),
+    cliOption: (cli) => steps.cliOption(cli, lang),
+  });
+  if (plan.alreadyInstalled.length > 0) {
+    await prompts.log.info(t(lang, 'alreadyInstalled', { list: plan.alreadyInstalled.map((c) => c.id).join(', ') }));
+  }
+  return plan;
+}
+
+async function chooseMcps(ui, lang, profileId, selection) {
+  // Profiles never write MCP config on their own: they only print the
+  // command, like --yes does. Custom asks, same as the legacy flow.
+  if (profileId !== 'custom') return ui.selectMcps(selection.modules, selection.areas, { yes: true });
+  return ui.selectMcps(selection.modules, selection.areas, { mcpMessage: t(lang, 'mcpsQuestion') });
+}
+
+/**
+ * Steps 2 to 4 plus the review loop. Returns everything the installer
+ * needs except module configs.
+ */
+async function collectChoices(ui, lang, registry, ideManager) {
+  let profileId = 'everything';
+  let selection;
+  let ides;
+  let userName;
+  for (;;) {
+    await steps.stepHeader(lang, 2);
+    profileId = await steps.askProfile(lang, profileId);
+    selection = await resolveSelection(profileId, lang, registry);
+    if (!ides) {
+      await steps.stepHeader(lang, 3);
+      ides = await steps.askTools(lang, ideManager);
+      await steps.stepHeader(lang, 4);
+      userName = await steps.askName(lang);
+    }
+    await showReview({ lang, profileId, selection, registry, ides });
+    const cliPlan = await chooseClis(ui, lang, selection);
+    const action = await prompts.select({
+      message: t(lang, 'reviewAction'),
+      choices: [
+        { name: t(lang, 'actionInstall'), value: 'install' },
+        { name: t(lang, 'actionProfile'), value: 'profile' },
+        { name: t(lang, 'actionCustomize'), value: 'customize' },
+      ],
+      default: 'install',
+    });
+    if (action === 'install') {
+      const mcpPlan = await chooseMcps(ui, lang, profileId, selection);
+      return { profileId, selection, ides, userName, cliPlan, mcpPlan };
+    }
+    if (action === 'customize') profileId = 'custom';
+  }
+}
+
+/**
+ * Run the guided fresh install and return the same config shape the legacy
+ * flow returns, so the installer itself does not change.
+ * @param {Object} ui - The UI instance (reuses its validators and pickers)
+ * @param {Object} options - Parsed CLI options
+ * @param {{directory: string, lang: 'en'|'pt', channelOptions: Object}} ctx
+ */
+async function runGuidedInstall(ui, options, ctx) {
+  const { directory, lang, channelOptions } = ctx;
+  const registry = await ui._loadSkillsRegistry();
+  const { IdeManager } = require('../ide/manager');
+  const ideManager = new IdeManager();
+  await ideManager.ensureInitialized();
+
+  const choices = await collectChoices(ui, lang, registry, ideManager);
+  const modules = ['core', ...choices.selection.modules.filter((code) => code !== 'core')];
+  const language = LANGUAGES.find((l) => l.value === lang).communication;
+  const { moduleConfigs, setOverrides } = await ui.collectModuleConfigs(directory, modules, {
+    ...options,
+    userName: choices.userName,
+    communicationLanguage: language,
+    documentOutputLanguage: language,
+    outputFolder: '_wizz-output',
+    yes: true,
+    quiet: true,
+    channelOptions,
+  });
+
+  return {
+    actionType: 'install',
+    directory,
+    modules,
+    ides: choices.ides,
+    skipIde: choices.ides.length === 0,
+    selectedAreas: choices.selection.areas,
+    mcpPlan: choices.mcpPlan,
+    cliPlan: choices.cliPlan,
+    coreConfig: moduleConfigs.core || {},
+    moduleConfigs,
+    setOverrides,
+    skipPrompts: false,
+    channelOptions,
+    traceEnabled: null,
+    guided: { lang, profile: choices.profileId },
+  };
+}
+
+module.exports = { isGuidedEligible, runGuidedInstall, SCRIPTED_FLAGS };