wizz-method 1.15.0 → 1.16.0

package/src/skills-lib/wizz-offer-forge/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: wizz-offer-forge
+description: Forja ofertas irresistíveis de resposta direta e infoprodutos integrando mecanismo único, tese da oferta, empilhamento de valor, garantia reversa, ancoragem de preço e matriz de criativos para tráfego pago. Use quando o usuário quiser criar uma nova oferta do zero, reestruturar oferta existente que não converte, empilhar bônus de alta percepção, definir garantia agressiva ou traduzir pesquisa de público (Piva/VoC) em uma máquina de vendas. NÃO use para pesquisa bruta de público (use pesquisa-de-publico-do-piva) nem redação final de copy de página (use copywriting).
+---
+
+# Wizz Offer Forge
+
+Sistema de engenharia e forja de ofertas irresistíveis para tráfego direto e infoprodutos. Converte dados brutos de mercado e dores latentes em uma arquitetura de oferta de alta conversão, blindada contra objeções e pronta para escala em mídia paga.
+
+## O que esta skill entrega
+
+Um artefato mestre `OFFER-SPEC.md` contendo:
+1. **Tese da Oferta & Promessa Central** (O Grande Gancho e o Resultado Tangível no Tempo).
+2. **Mecanismo Único Duplo** (Mecanismo da Causa + Mecanismo da Solução).
+3. **Core Deliverable + Empilhamento de Valor** (Produto Principal + Bônus Anti-Objeção).
+4. **Ancoragem de Preço, Modelagem de Planos & Order Bumps / Upsells**.
+5. **Garantia Reversa / Inversão de Risco** (Risco Zero ou Ganho Duplo).
+6. **Ponte de Tráfego: Matriz de Hooks e Ângulos de Criativos**.
+
+## Princípios de Forja de Oferta
+
+- **Clareza vence criatividade vazia:** Se o prospecto precisa pensar para entender o que ganha, a oferta morreu.
+- **Mecanismo Único dá esperança nova:** O público já tentou e falhou. A razão do fracasso anterior não foi incompetência dele, foi a falta do seu Mecanismo.
+- **Bônus que matam a próxima dor:** Cada bônus da pilha deve resolver o obstáculo imediato que surge quando o cliente compra o produto principal.
+- **Risco invertido:** O custo da inação deve parecer infinitamente maior do que o risco financeiro de comprar.
+
+## Fluxo de Trabalho
+
+### Passo 0 — Coleta de Insumos & Ambição
+
+Consulte o contexto existente ou pergunte ao usuário:
+1. **Pesquisa de Público Prévia:** Existe um relatório da skill `pesquisa-de-publico-do-piva` ou notas de VoC? Se sim, importe como insumo primário. Se não, defina Avatar, Dor Latente e Nível de Consciência inicial.
+2. **Modelo de Negócio:** Low-ticket (R$ 10 a R$ 97), Front-end médio (R$ 197 a R$ 497) ou High-ticket / Mentoria (R$ 1.000 a R$ 10.000+)?
+3. **Veículo de Entrega:** Curso gravado, comunidade, templates/ferramentas, mentoria ao vivo, SaaS ou híbrido?
+
+### Passo 1 — Destilação do Mecanismo Único
+
+Consulte `references/mecanismo-unico.md`:
+- **Mecanismo da Causa (O Vilão Oculto):** O motivo real e não-óbvio pelo qual o cliente não teve resultado até hoje com os métodos tradicionais.
+- **Mecanismo da Solução (O Veículo Proprietário):** O processo, método ou framework nomeado que torna o resultado previsível e simples.
+
+### Passo 2 — A Grande Promessa & Posicionamento
+
+Formule a Promessa Primária em 1 frase de alto impacto:
+`[Resultado Específico Desejado] em [Prazo Crível] sem [Principal Dor / Sacrifício Odiado].`
+
+### Passo 3 — Empilhamento de Valor & Matriz de Bônus
+
+Consulte `references/empilhamento-valor.md`:
+- **Produto Principal:** O caminho mais rápido e direto ao resultado.
+- **Bônus 1 (Velocidade):** Templates, atalhos, checklists prontos que encurtam a execução.
+- **Bônus 2 (Segurança):** Como evitar o erro mais comum ou o que fazer em caso de dúvida.
+- **Bônus 3 (Próximo Passo):** O que fazer depois de atingir o primeiro marco.
+- **Order Bump Estratégico:** Complemento impulsivo de alta margem (30-50% de take rate).
+
+### Passo 4 — Ancoragem de Preço & Garantia Reversa
+
+Consulte `references/garantia-reversa.md`:
+- Preço total empilhado vs Preço de ancoragem vs Preço real de lançamento/escala.
+- **Garantia Incondicional:** 7, 15 ou 30 dias sem atrito.
+- **Garantia Condicional Agressiva (Inversão de Risco):** "Se você aplicar o método X por Y dias e não atingir Z, devolvo 100% do seu dinheiro + R$ 100 do meu bolso pelo seu tempo perdido."
+
+### Passo 5 — Ponte de Tráfego & Ângulos de Anúncios
+
+Consulte `references/ponte-trafego.md`:
+- Mapeie 3 a 5 ganchos diretos para alimentar `ad-creative` e `paid-ads` no `traffic-masters` (Pedro Sobral / Molly Pittman / Ad Midas):
+  1. *Gancho da Quebra de Padrão / Vilão Revelado*
+  2. *Gancho do Erro Comum / Teste Rápido*
+  3. *Gancho da Demonstração do Mecanismo*
+  4. *Gancho da História de Transformação / Case*
+
+### Passo 6 — Compilação e Entrega
+
+Grave o artefato final em `{output_folder}/offers/OFFER-[NOME_SLUG].md` e apresente um resumo executivo com os 4 pontos de decisão para validação imediata do usuário.

package/src/skills-lib/wizz-offer-forge/references/empilhamento-valor.md

@@ -0,0 +1,25 @@
+# Empilhamento de Valor & Matriz de Bônus
+
+O valor percebido de uma oferta segue a Equação de Valor (Alex Hormozi):
+`Valor = (Sonho / Resultado Desejado × Certeza Percebida de Alcance) / (Tempo até o Resultado × Esforço e Sacrifício)`
+
+Para maximizar o valor e justificar o preço com facilidade:
+
+## 1. Produto Principal (The Core)
+- Foco em simplicidade e entrega rápida do resultado primário.
+- Menos aulas teóricas, mais implementação passo a passo.
+
+## 2. A Matriz de 4 Bônus Estratégicos
+
+Cada bônus deve ter um propósito psicológico específico:
+
+| Tipo de Bônus | Objetivo | Exemplos |
+|---|---|---|
+| **Bônus 1: Velocidade** | Reduz o tempo até a primeira vitória | Templates prontos, planilhas automáticas, scripts copiar-e-colar |
+| **Bônus 2: Quebra de Objeção** | Elimina a maior desculpa para não comprar | "Guia para quem não entende nada de tecnologia", "Como fazer sem equipe" |
+| **Bônus 3: Blindagem / Segurança** | Dá suporte contra imprevistos | Checklist de auditoria, guia anti-bloqueio, playbook de emergência |
+| **Bônus 4: Próximo Nível** | Mostra o que fazer após a vitória inicial | Treinamento avançado de escala, automação de processos |
+
+## 3. Order Bump (Take Rate 30-50%)
+- Um complemento impulsivo com preço entre 20% a 40% do valor do produto principal.
+- Não deve ser essencial para o funcionamento do core (para não parecer chantagem), mas deve ser irresistivelmente conveniente (ex: *Pack de 100 Criativos Editáveis*, *Acesso Vitalício*, *Templates Canva Prontos*).

package/src/skills-lib/wizz-offer-forge/references/garantia-reversa.md

@@ -0,0 +1,22 @@
+# Garantia Reversa & Inversão Total de Risco
+
+A garantia não é apenas uma formalidade legal; ela é a principal alavanca de conversão na etapa final de decisão de compra.
+
+## 1. Níveis de Garantia
+
+### Nível 1: Incondicional (Padrão)
+- 7 a 30 dias.
+- Devolução integral sem perguntas nem atrito.
+- Elimina o medo inicial de comprar de um desconhecido.
+
+### Nível 2: Condicional de Alta Performance
+- Exige que o cliente mostre que implementou os passos (assistiu as aulas, preencheu as planilhas, subiu a campanha).
+- Se implementou e não teve resultado em 30 a 90 dias, recebe suporte individual ou 100% de reembolso.
+
+### Nível 3: Garantia Reversa / Risco Positivo (The Hormozi Guarantee)
+- O criador assume um risco maior do que o cliente.
+- *Exemplo:* "Se você aplicar o método durante 60 dias e não dobrar o seu retorno em tráfego, devolvemos 100% do valor pago + R$ 200 via PIX pelo seu tempo investido."
+
+## 2. Regras de Segurança e Viabilidade
+- Só use a Garantia Reversa Nível 3 se o seu produto tiver um método comprovadamente eficaz e critérios claros de verificação de execução.
+- A clareza dos termos protege o produtor de fraudes e gera extrema autoridade no mercado.

package/src/skills-lib/wizz-offer-forge/references/mecanismo-unico.md

@@ -0,0 +1,28 @@
+# Mecanismo Único (Causa e Solução)
+
+O Mecanismo Único é a peça central que separa uma oferta genérica de uma máquina de conversão.
+
+## 1. Mecanismo da Causa (Por que falharam antes)
+
+O prospecto já tentou soluções concorrentes e não alcançou o resultado. Se dissermos que ele falhou por falta de esforço ou incompetência, ele rejeitará a mensagem.
+
+O Mecanismo da Causa identifica o **vilão oculto**:
+- A falha estrutural dos métodos tradicionais.
+- A armadilha que o mercado ensina que sabota os resultados.
+- O fator biológico, algorítmico, econômico ou psicológico que ninguém explicou para ele.
+
+*Exemplo:* "Você não consegue manter a dieta porque métodos tradicionais cortam calorias e disparam o hormônio grelina, forçando seu cérebro a sabotar você em nível biológico."
+
+## 2. Mecanismo da Solução (O Veículo Proprietário)
+
+É o nome próprio, método, ferramenta ou tecnologia que resolve a causa raiz de forma elegante:
+- Deve ter um nome memorável (ex: *Protocolo 3-Fases*, *Fórmula da Oferta Invertida*, *Método Turbo-Sync*).
+- Deve ser explicável em 3 passos lógicos e sequenciais.
+- Deve tornar o resultado inevitável se os passos forem seguidos.
+
+## 3. Checklist do Mecanismo Único
+
+- [ ] O mecanismo tem um nome proprietário e sonoro?
+- [ ] Ele isenta o cliente de culpas passadas?
+- [ ] Ele explica por que a concorrência falha?
+- [ ] Ele cria uma categoria própria onde sua oferta não tem concorrente direto?

package/src/skills-lib/wizz-offer-forge/references/ponte-trafego.md

@@ -0,0 +1,21 @@
+# Ponte de Tráfego: Da Oferta ao Criativo
+
+Uma oferta excelente sem uma ponte direta para a mídia paga não escala. A ponte de tráfego traduz a tese da oferta em ganchos e ângulos de anúncios.
+
+## 1. Os 4 Formatos de Anúncios de Entrada
+
+1. **O Gancho da Quebra de Padrão (Pattern Interrupt):**
+   - Ataca a crença tradicional do mercado.
+   - *Estrutura:* "Por que [Conselho Popular] é o motivo exato de você estar [Falhando]."
+2. **O Gancho do Erro Comum / Quiz:**
+   - Desafia o espectador a checar se está cometendo um erro crítico.
+   - *Estrutura:* "Se você está fazendo [Ação X], pare agora antes que aconteça [Consequência Ruim]."
+3. **O Gancho da Demonstração do Mecanismo (Show, Don't Tell):**
+   - Mostra o processo ou o resultado visual imediato em tela.
+   - *Estrutura:* "Como esta ferramenta / método de 3 passos gerou [Resultado] em apenas [Tempo]."
+4. **O Gancho do Relato / Não Consegue Dizer (Can't Tell):**
+   - Toca na ferida emocional profunda que o cliente sente mas tem vergonha de admitir.
+   - *Estrutura:* "A sensação silenciosa de trabalhar 12 horas por dia e ver o saldo da conta estagnado..."
+
+## 2. Handoff para o `traffic-masters` e `copy-squad`
+A matriz de criativos gerada pela skill `wizz-offer-forge` serve como o brief exato para os agentes de mídia paga (`wizz-ads`, `pedro-sobral`, `molly-pittman`, `ad-midas`) e de copy (`wizz-copy`, `hormozi-copy`).

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

@@ -75,6 +75,8 @@ 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 público de oferta, VoC, matriz de ângulos, léxico de infoproduto | `pesquisa-de-publico-do-piva` | 1 |
+| Forjar oferta, criar oferta irresistível, mecanismo único, bônus, garantia | `wizz-offer-forge` + `pricing-strategy` | 1 |
 | Pesquisa de mercado, inteligência competitiva | `deep-research` | 2 |
 
 ## Contexto e Memória

package/tools/installer/core/installer.js

@@ -137,6 +137,12 @@ class Installer {
 
       const restoreResult = await this._restoreUserFiles(paths, updateState);
 
+      // Mostra as mensagens de pós-instalação de "ação necessária" dos módulos
+      // instalados (ex.: rodar uma skill de setup) e deixa o usuário confirmar
+      // antes do resumo final, para "Wizz Method is ready to use!" continuar
+      // sendo a última coisa exibida.
+      await this._displayPostInstallMessages(config, officialModules);
+
       // Render consolidated summary
       await this.renderInstallSummary(results, {
         wizzDir: paths.wizzDir,
@@ -1207,6 +1213,57 @@ class Installer {
     });
   }
 
+  /**
+   * Exibe as mensagens de pós-instalação definidas no registry para os módulos
+   * instalados nesta execução. São avisos de "ação necessária" (ex.: "rode a
+   * skill wizz-loop-setup") que o usuário precisa ver para concluir o setup.
+   * São definidas pela propriedade `post-install-message` na entrada do módulo
+   * em `wizz-modules.yaml`.
+   *
+   * Instalações interativas exigem que o usuário confirme cada mensagem
+   * (Enter); instalações não-interativas (--yes / skipPrompts) imprimem a
+   * mensagem e seguem sem bloquear, para CI e scripts não travarem.
+   *
+   * @param {Object} config - Config da instalação (config.modules, config.skipPrompts)
+   * @param {Object} officialModules - Instância de OfficialModules (carrega o registry)
+   */
+  async _displayPostInstallMessages(config, officialModules) {
+    const moduleCodes = config.modules || [];
+    if (moduleCodes.length === 0) return;
+
+    const externalManager = officialModules && officialModules.externalModuleManager;
+    if (!externalManager) return;
+
+    const color = await prompts.getColor();
+
+    for (const code of moduleCodes) {
+      let moduleInfo;
+      try {
+        moduleInfo = await externalManager.getModuleByCode(code);
+      } catch {
+        continue; // Módulos embutidos (core/bmm/wizz) não estão no registry — pular.
+      }
+
+      const message = moduleInfo && moduleInfo.postInstallMessage;
+      if (!message) continue;
+
+      await prompts.box(String(message).trim(), `⚑ Action needed — ${moduleInfo.name || code}`, {
+        rounded: true,
+        formatBorder: color.yellow,
+      });
+
+      // Interativo: exige confirmação antes de seguir. Pula o prompt bloqueante
+      // em instalações não-interativas (a mensagem continua sendo mostrada).
+      if (!config.skipPrompts) {
+        await prompts.text({
+          message: 'Press Enter to acknowledge',
+          placeholder: '',
+          default: '',
+        });
+      }
+    }
+  }
+
   /**
    * Quick update method - preserves all settings and only prompts for new config fields
    * @param {Object} config - Configuration with directory

package/tools/installer/ide/_config-driven.js

@@ -455,9 +455,9 @@ class ConfigDrivenIdeSetup {
       await fs.ensureDir(skillDir);
       this.skillWriteTracker?.add(canonicalId);
 
-      // Copy all skill files, filtering OS/editor artifacts recursively
-      const skipPatterns = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
-      const skipSuffixes = ['~', '.swp', '.swo', '.bak'];
+      // Copy all skill files, filtering OS/editor artifacts and Python caches recursively
+      const skipPatterns = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini', '__pycache__']);
+      const skipSuffixes = ['~', '.swp', '.swo', '.bak', '.pyc', '.pyo'];
       const filter = (src) => {
         const name = path.basename(src);
         if (src === sourceDir) return true;

package/tools/installer/ide/platform-codes.yaml

@@ -52,6 +52,13 @@ platforms:
       target_dir: .agent/skills
       global_target_dir: ~/.gemini/antigravity/skills
 
+  antigravity-cli:
+    name: "Antigravity CLI (AGY)"
+    preferred: false
+    installer:
+      target_dir: .agents/skills
+      global_target_dir: ~/.gemini/antigravity-cli/skills
+
   auggie:
     name: "Auggie"
     preferred: false
@@ -184,6 +191,20 @@ platforms:
       target_dir: .agents/skills
       global_target_dir: ~/.config/agents/skills
 
+  grok:
+    name: "Grok"
+    preferred: false
+    installer:
+      target_dir: .agents/skills
+      global_target_dir: ~/.grok/skills
+
+  hermes:
+    name: "Hermes Agent"
+    preferred: false
+    installer:
+      target_dir: .agents/skills
+      global_target_dir: ~/.hermes/skills
+
   iflow:
     name: "iFlow"
     preferred: false
@@ -345,6 +366,13 @@ platforms:
       target_dir: .agents/skills
       global_target_dir: ~/.agents/skills
 
+  zcode:
+    name: "ZCode"
+    preferred: false
+    installer:
+      target_dir: .zcode/skills
+      global_target_dir: ~/.zcode/skills
+
   zencoder:
     name: "Zencoder"
     preferred: false

package/tools/installer/modules/external-manager.js

@@ -94,6 +94,13 @@ class ExternalModuleManager {
   // ExternalModuleManager) sees resolutions made during install.
   static _resolutions = new Map();
 
+  // moduleCode → ResolvedModule (do PluginResolver). Preenchido para módulos do
+  // registry marcados com `marketplace-plugin: true`, cujas skills instaláveis
+  // vivem fora de um único diretório de module.yaml e precisam ser resolvidas a
+  // partir de .claude-plugin/marketplace.json. Compartilhado entre instâncias
+  // para o install() aproveitar a resolução feita no findModuleSource.
+  static _pluginResolutions = new Map();
+
   constructor() {}
 
   /**
@@ -105,6 +112,15 @@ class ExternalModuleManager {
     return ExternalModuleManager._resolutions.get(moduleCode) || null;
   }
 
+  /**
+   * Resolução marketplace-plugin em cache para um módulo (se houver).
+   * @param {string} moduleCode
+   * @returns {Object|null} ResolvedModule do PluginResolver, ou null
+   */
+  getPluginResolution(moduleCode) {
+    return ExternalModuleManager._pluginResolutions.get(moduleCode) || null;
+  }
+
   /**
    * Load the official modules registry from the bundled YAML file.
    * @returns {Object} Parsed YAML content with modules array
@@ -147,8 +163,16 @@ class ExternalModuleManager {
       npmPackage: mod.npm_package || mod.npmPackage || null,
       pluginName: mod.plugin_name || mod.pluginName || null,
       defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable',
+      deprecated: mod.deprecated === true,
+      deprecationMessage: mod.deprecation_message || mod['deprecation-message'] || mod.deprecationMessage || null,
+      marketplacePlugin: mod.marketplace_plugin === true || mod['marketplace-plugin'] === true || mod.marketplacePlugin === true,
+      postInstallMessage: mod.post_install_message || mod['post-install-message'] || mod.postInstallMessage || null,
       builtIn: mod.built_in === true,
       isExternal: mod.built_in !== true,
+      // Códigos anteriores sob os quais este módulo foi registrado (ex.: `bmad-loop`
+      // era `bauto`). Deixa um módulo renomeado continuar resolvendo instalações
+      // existentes em vez de órfã-las — ver getModuleByCode().
+      aliases: Array.isArray(mod.aliases) ? mod.aliases : [],
     };
   }
 
@@ -173,13 +197,27 @@ class ExternalModuleManager {
   }
 
   /**
-   * Get module info by code
+   * Get module info by code. Cai no `aliases` da entrada do registry, de modo
+   * que um módulo renomeado (com `code` alterado) ainda resolve para instalações
+   * gravadas sob o código anterior.
    * @param {string} code - The module code (e.g., 'cis')
    * @returns {Object|null} Module info or null if not found
    */
   async getModuleByCode(code) {
     const modules = await this.listAvailable();
-    return modules.find((m) => m.code === code) || null;
+    return modules.find((m) => m.code === code) || modules.find((m) => m.aliases.includes(code)) || null;
+  }
+
+  /**
+   * Resolve a possibly-legacy module code to its current canonical code.
+   * Returns the input unchanged if it doesn't match any registry entry or
+   * alias (e.g. a custom/unknown module).
+   * @param {string} code
+   * @returns {Promise<string>}
+   */
+  async resolveCanonicalCode(code) {
+    const info = await this.getModuleByCode(code);
+    return info ? info.code : code;
   }
 
   /**
@@ -502,6 +540,24 @@ class ExternalModuleManager {
       return null;
     }
 
+    // Normaliza para o código canônico — um install gravado sob um alias
+    // (ex.: `bauto`) precisa resolver para a entrada atual do registry.
+    moduleCode = moduleInfo.code;
+
+    // Módulos marketplace-plugin (entradas do registry marcadas com
+    // `marketplace-plugin`) trazem um .claude-plugin/marketplace.json e mantêm o
+    // module.yaml dentro do assets/ de uma skill, e não num diretório único ao
+    // lado das skills. Resolve pelo PluginResolver (a mesma máquina que os
+    // installs por URL custom usam) e devolve o diretório que contém o
+    // module.yaml, para os chamadores de config/versão/diretório funcionarem;
+    // o install() copia os diretórios de skill resolvidos.
+    if (moduleInfo.marketplacePlugin) {
+      const pluginMod = await this.resolvePluginModule(moduleCode, options);
+      if (pluginMod && pluginMod.moduleYamlPath) {
+        return path.dirname(pluginMod.moduleYamlPath);
+      }
+    }
+
     // Clone the external module repo
     const cloneDir = await this.cloneExternalModule(moduleCode, options);
 
@@ -555,6 +611,88 @@ class ExternalModuleManager {
         `The repository may have been restructured after this release was tagged.${channelHint}`,
     );
   }
+  /**
+   * Resolve um módulo marketplace-plugin do registry para uma definição de
+   * plugin instalável. Clona o repo (respeitando o plano de canal), lê o
+   * .claude-plugin/marketplace.json e roda o PluginResolver contra o plugin que
+   * corresponde a este módulo. O resultado (skillPaths + module.yaml +
+   * module-help.csv) fica em cache para o install() copiar os diretórios de
+   * skill resolvidos.
+   *
+   * @param {string} moduleCode - Código do módulo externo
+   * @param {Object} options - Opções repassadas a cloneExternalModule
+   * @returns {Promise<Object|null>} ResolvedModule do PluginResolver, ou null
+   *   quando o módulo não é marketplace plugin ou não pode ser resolvido.
+   */
+  async resolvePluginModule(moduleCode, options = {}) {
+    const moduleInfo = await this.getModuleByCode(moduleCode);
+    if (!moduleInfo || moduleInfo.builtIn || !moduleInfo.marketplacePlugin) {
+      return null;
+    }
+
+    // Normaliza para o código canônico — ver cloneExternalModule.
+    moduleCode = moduleInfo.code;
+
+    const cloneDir = await this.cloneExternalModule(moduleCode, options);
+
+    const marketplacePath = path.join(cloneDir, '.claude-plugin', 'marketplace.json');
+    if (!(await fs.pathExists(marketplacePath))) {
+      return null;
+    }
+
+    let marketplace;
+    try {
+      marketplace = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
+    } catch {
+      return null;
+    }
+
+    const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+    if (plugins.length === 0) {
+      return null;
+    }
+
+    // Prefere o plugin cujo nome bate com o plugin_name do registry (ou o code),
+    // caindo para qualquer plugin que declare skills.
+    const preferredName = moduleInfo.pluginName || moduleInfo.code;
+    const ordered = [...plugins].sort((a, b) => {
+      const am = a?.name === preferredName ? 0 : 1;
+      const bm = b?.name === preferredName ? 0 : 1;
+      return am - bm;
+    });
+
+    const { PluginResolver } = require('./plugin-resolver');
+    const resolver = new PluginResolver();
+
+    for (const plugin of ordered) {
+      if (!plugin || !Array.isArray(plugin.skills) || plugin.skills.length === 0) {
+        continue;
+      }
+      let resolvedMods;
+      try {
+        resolvedMods = await resolver.resolve(cloneDir, plugin);
+      } catch {
+        continue;
+      }
+      if (!resolvedMods || resolvedMods.length === 0) {
+        continue;
+      }
+      // Casa pelo código do registry, depois pelo nome preferido do plugin,
+      // depois aceita um único módulo resolvido.
+      const match =
+        resolvedMods.find((mod) => mod.code === moduleCode) ||
+        resolvedMods.find((mod) => mod.code === preferredName) ||
+        (resolvedMods.length === 1 ? resolvedMods[0] : null);
+      if (match) {
+        match.repoUrl = moduleInfo.url;
+        ExternalModuleManager._pluginResolutions.set(moduleCode, match);
+        return match;
+      }
+    }
+
+    return null;
+  }
+
   cachedModules = null;
 }
 

package/tools/installer/modules/official-modules.js

@@ -316,7 +316,29 @@ class OfficialModules {
       await fs.remove(targetPath);
     }
 
-    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    // Módulos marketplace-plugin do registry mantêm as skills instaláveis fora do
+    // diretório que contém o module.yaml (sourcePath aponta para o assets/ da
+    // skill -setup), então não dá para instalá-los copiando o sourcePath. Copia
+    // os diretórios de skill resolvidos, do mesmo jeito que um install custom de
+    // marketplace monta um módulo. Todo o resto (manifest, versão) segue pelo
+    // caminho padrão de módulo externo abaixo.
+    const marketplaceInfo = await this.externalModuleManager.getModuleByCode(moduleName);
+    if (marketplaceInfo && marketplaceInfo.marketplacePlugin) {
+      const pluginResolution = this.externalModuleManager.getPluginResolution(moduleName);
+      // Falha alto: copiar o sourcePath aqui instalaria só o assets/ da skill
+      // -setup (module.yaml + module-help.csv) e nenhuma skill — um install
+      // parcial e silenciosamente quebrado. Aborta em vez disso.
+      if (!pluginResolution || !Array.isArray(pluginResolution.skillPaths) || pluginResolution.skillPaths.length === 0) {
+        throw new Error(
+          `Module '${moduleName}' is registered as a marketplace plugin but its skills could not be resolved ` +
+            `from .claude-plugin/marketplace.json (missing or malformed on the selected channel). ` +
+            `Aborting to avoid a partial install with no skills.`,
+        );
+      }
+      await this._copyResolvedSkills(pluginResolution, targetPath, fileTrackingCallback, options.moduleConfig);
+    } else {
+      await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    }
 
     if (!options.skipModuleInstaller) {
       await this.createModuleDirectories(moduleName, wizzDir, options);
@@ -343,41 +365,66 @@ class OfficialModules {
   }
 
   /**
-   * Install a module from a PluginResolver resolution result.
-   * Copies specific skill directories and places module-help.csv at the target root.
-   * @param {Object} resolved - ResolvedModule from PluginResolver
-   * @param {string} wizzDir - Target wizz directory
-   * @param {Function} fileTrackingCallback - Optional callback to track installed files
-   * @param {Object} options - Installation options
+   * Assenta em disco uma resolução do PluginResolver: copia cada diretório de
+   * skill resolvido (achatado pelo nome da folha) para targetPath e coloca o
+   * module-help.csv na raiz do módulo. Compartilhado pelos installs custom de
+   * marketplace (installFromResolution) e pelos installs oficiais de módulo
+   * marketplace-plugin (install), para os dois caminhos não divergirem.
+   * @param {Object} resolved - ResolvedModule do PluginResolver
+   * @param {string} targetPath - Diretório de destino do módulo (ex.: wizzDir/<code>)
+   * @param {Function} fileTrackingCallback - Callback opcional de rastreio de arquivos
+   * @param {Object} moduleConfig - Configuração do módulo repassada ao filtro de cópia
    */
-  async installFromResolution(resolved, wizzDir, fileTrackingCallback = null, options = {}) {
-    const targetPath = path.join(wizzDir, resolved.code);
-
-    if (await fs.pathExists(targetPath)) {
-      await fs.remove(targetPath);
-    }
-
+  async _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
     await fs.ensureDir(targetPath);
 
-    // Copy each skill directory, flattened by leaf name
+    // Copia cada diretório de skill, achatado pelo nome da folha. Os nomes de
+    // folha precisam ser únicos — duas skills que achatam para o mesmo diretório
+    // se sobrescreveriam em silêncio, então falha alto em vez disso.
+    const seenLeaves = new Map();
     for (const skillPath of resolved.skillPaths) {
       const skillDirName = path.basename(skillPath);
+      if (seenLeaves.has(skillDirName)) {
+        throw new Error(
+          `Cannot install module '${resolved.code}': skill directories '${seenLeaves.get(skillDirName)}' and ` +
+            `'${skillPath}' share the leaf name '${skillDirName}' and would overwrite each other. ` +
+            `Skill directory names must be unique.`,
+        );
+      }
+      seenLeaves.set(skillDirName, skillPath);
       const skillTarget = path.join(targetPath, skillDirName);
-      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, options.moduleConfig);
+      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, moduleConfig);
     }
 
-    // Place module-help.csv at the module root
+    // Coloca o module-help.csv na raiz do módulo.
+    const helpTarget = path.join(targetPath, 'module-help.csv');
     if (resolved.moduleHelpCsvPath) {
-      // Strategies 1-4: copy the existing file
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Estratégias 1-4: copia o arquivo existente.
       await fs.copy(resolved.moduleHelpCsvPath, helpTarget, { overwrite: true });
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     } else if (resolved.synthesizedHelpCsv) {
-      // Strategy 5: write synthesized content
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Estratégia 5: escreve o conteúdo sintetizado.
       await fs.writeFile(helpTarget, resolved.synthesizedHelpCsv, 'utf8');
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     }
+  }
+
+  /**
+   * Install a module from a PluginResolver resolution result.
+   * Copies specific skill directories and places module-help.csv at the target root.
+   * @param {Object} resolved - ResolvedModule from PluginResolver
+   * @param {string} wizzDir - Target wizz directory
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} options - Installation options
+   */
+  async installFromResolution(resolved, wizzDir, fileTrackingCallback = null, options = {}) {
+    const targetPath = path.join(wizzDir, resolved.code);
+
+    if (await fs.pathExists(targetPath)) {
+      await fs.remove(targetPath);
+    }
+
+    await this._copyResolvedSkills(resolved, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Create directories declared in module.yaml (strategies 1-4 may have these)
     if (!options.skipModuleInstaller) {