wizz-method 1.6.0 → 1.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Wizz Method — método de agência orientado por IA em PT-BR (fork independente do BMad Method)",
   "keywords": [
     "agile",

package/src/skills-lib/motion-3d-director/references/motion-paths.md

@@ -27,7 +27,7 @@ Usar quando precisa de **interação real**.
 - Drei;
 - GLSL / shaders;
 - Framer Motion ou Motion para integração com scroll;
-- GSAP apenas se necessário.
+- GSAP (ScrollTrigger) quando o scroll orquestra a cena — 100% gratuito desde a v3.13, todos os plugins incluídos.
 
 **Exemplos:** objeto 3D que segue o cursor; esfera de partículas mouse-reactive; câmera que avança no scroll; wireframe terrain em tempo real; produto 3D configurável; background WebGL interativo.
 
@@ -107,6 +107,8 @@ Usar quando 3D é exagero ou não aumenta conversão.
 
 **Inclui:** text reveal; parallax; masked typography; image reveal; hover cards; SVG motion; scroll storytelling; magnetic buttons; animated mockups; cinematic section transitions; gradient background animado; background noise; reveal por seção; staggered animations.
 
+**Stack recomendada:** Framer Motion/Motion para UI React declarativa; GSAP + ScrollTrigger/SplitText para scroll storytelling, pinning e text reveal avançado (gratuito desde a v3.13); anime.js v4 para stagger, SVG motion e microinterações imperativas leves (~10kb core, MIT).
+
 **Usar quando:**
 
 - o projeto é Advanced Site;

package/src/skills-lib/premium-landing-ui-researcher/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: premium-landing-ui-researcher
-description: Pesquisar animações, componentes, referências visuais e padrões de conversão para criar landing pages premium em React, Next.js, Tailwind, shadcn/ui, Framer Motion, Three.js e React Three Fiber. Use esta skill quando o usuário pedir para analisar um projeto existente, classificar o nível de complexidade do site (básico, intermediário, avançado, 3D high-end com modo Signature), escolher componentes ou animações adequados, melhorar uma UI genérica, criar uma landing page completa, transformar uma oferta em página estratégica, projetar também um dashboard SaaS junto da landing, criar um site de autoridade/portfolio para agência, estúdio, consultoria, marca pessoal ou lead passivo, criar case studies e selected work editoriais, criar uma experiência 3D cinematográfica para marcas premium, buscar referências em React Bits, Cult UI, Componentry, Animmaster Lib, Ali Imam, Watermelon UI, StyleUI, Refero, Impeccable, Taste Skill, Design Motion Principles, MotionSites, Vibe Code Components, Landing Love, Godly, Design Spells, Mobbin, ScreensDesign, DesignVault, Spline, Unicorn Studio, Skiper UI, 21st.dev (Magic MCP ou 21st CLI), ou implementar uma experiência visual sofisticada orientada à conversão ou à autoridade.
+description: Pesquisar animações, componentes, referências visuais e padrões de conversão para criar landing pages premium em React, Next.js, Tailwind, shadcn/ui, Framer Motion, Three.js e React Three Fiber. Use esta skill quando o usuário pedir para analisar um projeto existente, classificar o nível de complexidade do site (básico, intermediário, avançado, 3D high-end com modo Signature), escolher componentes ou animações adequados, melhorar uma UI genérica, criar uma landing page completa, transformar uma oferta em página estratégica, projetar também um dashboard SaaS junto da landing, criar um site de autoridade/portfolio para agência, estúdio, consultoria, marca pessoal ou lead passivo, criar case studies e selected work editoriais, criar uma experiência 3D cinematográfica para marcas premium, buscar referências em React Bits, Cult UI, Componentry, Animmaster Lib, Ali Imam, Watermelon UI, StyleUI, Bklit UI, Refero, Impeccable, Taste Skill, Design Motion Principles, MotionSites, Vibe Code Components, Landing Love, Godly, Design Spells, Mobbin, ScreensDesign, DesignVault, Spline, Unicorn Studio, Skiper UI, 21st.dev (Magic MCP ou 21st CLI), escolher entre GSAP, anime.js e Framer Motion para animações e scroll storytelling, ou implementar uma experiência visual sofisticada orientada à conversão ou à autoridade.
 ---
 
 # Premium Landing UI Researcher
@@ -49,7 +49,7 @@ Classificar o projeto em um dos 5 níveis (regras, motion permitido/proibido e b
 | Processo obrigatório de 12 passos e checkpoint de honestidade | [mandatory-process](references/mandatory-process.md) |
 | Source-First Mandate completo + protocolo em 5 fases (inventário, repos em cache, Magic MCP, 21st CLI, confirmação; 21st = fonte paga complementar) | [source-first-protocol](references/source-first-protocol.md) |
 | Audit Protocol: Pass 1 Taste, Pass 2 Impeccable, Pass 3 Cross-check, Pass 4 A11y/Perf | [audit-protocol](references/audit-protocol.md) |
-| Fontes de componentes (React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, 21st.dev + 21st CLI), fontes de referência e inspiração visual, Clone Policy, Paid Source Policy | [component-sources](references/component-sources.md) |
+| Fontes de componentes (React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, Bklit UI, 21st.dev + 21st CLI), animation engines (GSAP, anime.js), fontes de referência e inspiração visual, Clone Policy, Paid Source Policy | [component-sources](references/component-sources.md) |
 | Stack default, direção visual, paletas, tipografia e regras de seleção de animação | [stack-and-visual-direction](references/stack-and-visual-direction.md) |
 | Estrutura obrigatória da landing, case studies/portfolio, copywriting, conversão e CTA externo/WhatsApp | [landing-page-strategy](references/landing-page-strategy.md) |
 | Prompts base (landing completa e hero 3D com scroll) | [prompt-templates](references/prompt-templates.md) |

package/src/skills-lib/premium-landing-ui-researcher/references/component-sources.md

@@ -131,6 +131,14 @@ Usar para: templates, landing page layouts, páginas prontas, seções instaláv
 - Mesmo gate de custo do 21st.dev: só com aprovação do usuário, quando as gratuitas não cobrirem
 - O que o usuário já comprou/baixou dela vale como recurso local (inspecionar em `modelos lp/`)
 
+### Bklit UI
+
+- Site: https://bklit.com/ · GitHub: https://github.com/bklit/bklit-ui (MIT, gratuito, open source)
+- Charts e componentes utilitários React/TypeScript/Tailwind via registry shadcn (~15 tipos: área, barras, linha, pizza, radar, Sankey, candlestick, choropleth, gauge)
+- **Não clonar**: instalar direto pelo registry — `npx shadcn@latest add @bklit/<chart>` (ex: `@bklit/line-chart`)
+- Fonte prioritária para: dashboards SaaS, data viz, seções de métricas/estatísticas na landing, gráficos animados premium (complementa/substitui Recharts cru)
+- O Bklit Studio (playground) é proprietário; os componentes em si são MIT
+
 ### Skiper UI
 
 Skiper UI **não deve ser clonado**.
@@ -147,6 +155,24 @@ Usar para: uncommon shadcn components, efeitos visuais diferenciados, seções p
 
 Evitar: depender de componentes premium sem autorização; assumir acesso pago.
 
+## Animation Engine Libraries (libs de código, via npm)
+
+Motores de animação instaláveis como dependência npm normal (não são registries de componentes; não precisam de clone — os repos podem ser inspecionados para exemplos/demos).
+
+### GSAP
+
+- GitHub: https://github.com/greensock/GSAP.git · Docs: https://gsap.com/docs/
+- **100% gratuito desde a v3.13** (aquisição pela Webflow, 2025), incluindo todos os plugins antes pagos: ScrollTrigger, ScrollSmoother, SplitText, MorphSVG, DrawSVG, etc. Instalar: `npm i gsap` (+ `@gsap/react` para o hook `useGSAP`)
+- Usar para: scroll storytelling e animações scroll-driven complexas (ScrollTrigger), timelines longas e sequenciadas, text reveal por caractere/palavra (SplitText), morph de SVG, animações fora do ciclo do React, sites high-end estilo Awwwards
+- Preferir GSAP sobre Framer Motion quando: a animação é orquestrada por scroll com pinning/scrub, a timeline tem muitos passos encadeados, ou o efeito anima elementos fora de componentes React
+
+### anime.js
+
+- GitHub: https://github.com/juliangarnier/anime.git · Docs: https://animejs.com/ (MIT, gratuito)
+- v4: API modular e tree-shakeable (~10kb core), timelines, stagger, springs, draggable, scroll observer, SVG (draw/morph/motion path), WAAPI. Instalar: `npm i animejs`
+- Usar para: microinterações e animações leves quando GSAP seria peso demais, stagger/grid animations, animação de SVG, contadores/números animados, projetos sem React ou fora do ecossistema Motion
+- Regra de escolha: Framer Motion/Motion para UI React declarativa → anime.js para efeitos leves imperativos → GSAP para scroll orquestrado e timelines cinematográficas
+
 ## Authorized Reference Inspection Sources
 
 Estas fontes podem ser inspecionadas ou consultadas para princípios, critérios de qualidade, motion e taste, mas **não devem ser tratadas como dependências de projeto**.

package/src/skills-lib/premium-landing-ui-researcher/references/source-first-protocol.md

@@ -53,6 +53,9 @@ Para cada efeito visual ainda não resolvido pela fase 1, inspecionar o **cache
 | SaaS components / dashboards / product UI blocks | `~/.claude/design-sources/watermelon/` | `git -C ~/.claude/design-sources/watermelon pull` |
 | Templates / landing layouts prontos / páginas base | `~/.claude/design-sources/styleui/` | `git -C ~/.claude/design-sources/styleui pull` |
 | Componentes shadcn premium específicos | **Skiper UI** | `npx shadcn add @skiper-ui/skiperXX` (sem clone, instala direto) |
+| Charts / data viz / seções de métricas / gráficos de dashboard | **Bklit UI** | `npx shadcn@latest add @bklit/<chart>` (sem clone, registry shadcn) |
+| Scroll storytelling / pinning / timelines cinematográficas / SplitText | **GSAP** (lib npm, 100% gratuita desde a v3.13) | `npm i gsap @gsap/react` (sem clone) |
+| Microinterações imperativas leves / stagger / SVG motion / contadores | **anime.js v4** (lib npm, MIT) | `npm i animejs` (sem clone) |
 
 **Fluxo de uso do cache:**
 

package/src/skills-lib/premium-landing-ui-researcher/references/source-links.md

@@ -10,6 +10,7 @@
 - Watermelon UI: https://github.com/WatermelonCorp/watermellon-registry.git
 - StyleUI: https://github.com/heyfabrika/styleui.git
 - Skiper UI command: `npx shadcn add @skiper-ui/skiper40`
+- Bklit UI (charts shadcn, MIT, gratuito): https://github.com/bklit/bklit-ui — `npx shadcn@latest add @bklit/<chart>`
 - Componentry (React animado, gratuito/open source, Vercel OSS): https://componentry.dev/
 - Componentry MCP (via shadcn MCP + registry `@componentry`): https://componentry.dev/docs/mcp
 - Animmaster Lib (300 componentes animados, PAGO): https://animmasterlib.dev/
@@ -22,6 +23,11 @@
 - 21st instalação: `21st add <user>/<slug>` ou `npx shadcn@latest add https://21st.dev/r/<user>/<slug>`
 - 21st API keys (CI/headless, env API_KEY_21ST): https://21st.dev/settings/api-keys
 
+## Animation Engine Libraries (npm)
+
+- GSAP (100% gratuito desde a v3.13, todos os plugins incluídos): https://github.com/greensock/GSAP.git — `npm i gsap @gsap/react`
+- anime.js v4 (MIT, ~10kb core): https://github.com/juliangarnier/anime.git — `npm i animejs`
+
 ## Reference Sources (taste, qualidade visual, motion)
 
 - Impeccable: https://github.com/pbakaus/impeccable.git

package/src/skills-lib/premium-landing-ui-researcher/references/stack-and-visual-direction.md

@@ -8,11 +8,13 @@ Se o usuário não especificar stack, assumir:
 - Tailwind CSS;
 - shadcn/ui;
 - Framer Motion ou Motion;
+- GSAP (com ScrollTrigger/SplitText, 100% gratuito desde a v3.13) para scroll storytelling e timelines cinematográficas;
+- anime.js v4 para microinterações imperativas leves e SVG motion;
 - React Bits;
 - React Three Fiber para projetos 3D;
 - Three.js para WebGL avançado;
 - lucide-react para ícones;
-- Recharts para dashboards SaaS.
+- Recharts ou Bklit UI (charts shadcn) para dashboards SaaS.
 
 Se o projeto for simples, reduzir stack e evitar complexidade desnecessária.
 

package/tools/installer/modules/env-vars.js

@@ -29,17 +29,36 @@
 //     placeholder stays in `.mcp.json`, and the summary explains how to
 //     configure it later.
 //
+// GLOBAL KEY STORE (`~/.claude/wizz-env.json`): a key the user already typed
+// in ANY project is reused silently in every new install — the store is read
+// by the installer only (C7 still holds: the runtime never reads it), and a
+// hit is copied into the new project's `settings.local.json`. A key typed at
+// the prompt is saved to the store too, so it is only ever asked once.
+//
 // API (decomposed per E3 so each piece is unit-testable without a TTY):
 //   extractEnvPlaceholders(mcps)              — pure
 //   resolveEnvVars(vars, opts)                — I/O read (providers + prompt)
 //   persistEnvValues(toPersist, opts)         — I/O write (settings.local.json)
 //   persistProjectEnv(projectDir, envRecord)  — the actual writer, reusable
+//   persistGlobalEnv(storePath, envRecord)    — writer do store global
 //   promptMissingEnvVars(mcps, opts)          — thin orchestrator of the above
 
 const path = require('node:path');
+const os = require('node:os');
 const fs = require('../fs-native');
 const prompts = require('../prompts');
 
+// Global key store, read by the INSTALLER only (never by the Claude Code
+// runtime — C7 still holds). A value found here is copied into the project's
+// `.claude/settings.local.json` at install time, which IS what reaches the
+// MCP subprocess. This is what makes a key typed once in project A resolve
+// silently in projects B, C, D... without ever living in the global
+// settings.json `env` (which would expose it to every session of every
+// project — the exact pattern the 360° audit flagged as a security critical).
+function defaultGlobalEnvPath() {
+  return path.join(os.homedir(), '.claude', 'wizz-env.json');
+}
+
 // Deliberately POSIX-strict (uppercase + underscore only): this both matches
 // standard env var naming and doubles as a defensive filter against false
 // positives like `{bin}` (no `$` prefix at all, so it never matches) or a
@@ -168,12 +187,51 @@ function createDotenvFileProvider(dotenvPath) {
 }
 
 /**
- * Try each provider in order, returning the first non-empty value found.
+ * The global key store (`~/.claude/wizz-env.json`, flat `{ "VAR": "value" }`
+ * map, chmod 600) as a provider. Read-only here — `persistGlobalEnv` is the
+ * writer. Marked `persistToProject: true`: unlike `process.env`, a value from
+ * this store is NOT in the runtime's environment, so the resolver must copy
+ * it into the project's `settings.local.json` for it to actually reach the
+ * MCP subprocess (C7).
+ * @param {string} storePath - Absolute path to the global store file
+ * @returns {{name: string, persistToProject: boolean, available: () => Promise<boolean>, get: (name: string) => Promise<string|undefined>}}
+ */
+function createGlobalStoreProvider(storePath) {
+  let cache = null;
+
+  async function load() {
+    if (cache) return cache;
+    cache = {};
+    if (!storePath || !(await fs.pathExists(storePath))) return cache;
+    try {
+      const parsed = JSON.parse(await fs.readFile(storePath, 'utf8'));
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) cache = parsed;
+    } catch {
+      // Malformed/unreadable store — treat as empty, never throw.
+      cache = {};
+    }
+    return cache;
+  }
+
+  return {
+    name: 'global-store',
+    persistToProject: true,
+    available: async () => !!storePath && (await fs.pathExists(storePath)),
+    get: async (name) => {
+      const value = (await load())[name];
+      return typeof value === 'string' && value !== '' ? value : undefined;
+    },
+  };
+}
+
+/**
+ * Try each provider in order, returning the first non-empty value found and
+ * the provider that had it (so the caller can honor `persistToProject`).
  * A provider throwing or being unavailable is skipped, never fatal — one
  * broken provider must not block the chain (e.g. an unreadable `.env`).
  * @param {string} name - Var name to look up
  * @param {Array<Object>} providers
- * @returns {Promise<string|undefined>}
+ * @returns {Promise<{value: string, provider: Object}|undefined>}
  */
 async function findInProviders(name, providers) {
   for (const provider of providers || []) {
@@ -182,7 +240,7 @@ async function findInProviders(name, providers) {
       const isAvailable = typeof provider.available === 'function' ? await provider.available() : true;
       if (!isAvailable) continue;
       const value = await provider.get(name);
-      if (value !== undefined && value !== null && value !== '') return value;
+      if (value !== undefined && value !== null && value !== '') return { value, provider };
     } catch {
       continue;
     }
@@ -221,7 +279,14 @@ function createDefaultPrompter() {
  * @param {boolean} [opts.interactive=false] - Whether to prompt for missing vars
  * @param {Array<Object>} [opts.providers] - Provider chain, tried in order
  * @param {(entry) => Promise<string|undefined>} [opts.prompter] - Injectable prompt fn
- * @returns {Promise<{filled: Array, skipped: Array, existing: Array, toPersist: Record<string,string>}>}
+ * @returns {Promise<{filled: Array, skipped: Array, existing: Array, imported: Array,
+ *   toPersist: Record<string,string>, toPersistGlobal: Record<string,string>}>}
+ *   `existing` = found in a runtime-visible source (process.env/.env), nothing
+ *   to write. `imported` = found in a `persistToProject` provider (the global
+ *   store): resolved without prompting, but must be written to the project's
+ *   settings.local.json (included in `toPersist`). `toPersistGlobal` = the
+ *   subset of typed answers that should ALSO be saved to the global store so
+ *   the next project never asks.
  */
 async function resolveEnvVars(vars, opts = {}) {
   const { interactive = false, providers = [createProcessEnvProvider()], prompter = null } = opts;
@@ -229,7 +294,9 @@ async function resolveEnvVars(vars, opts = {}) {
   const filled = [];
   const skipped = [];
   const existing = [];
+  const imported = [];
   const toPersist = {};
+  const toPersistGlobal = {};
 
   for (const entry of vars || []) {
     // A default is resolved by the Claude Code runtime itself; asking would
@@ -242,7 +309,12 @@ async function resolveEnvVars(vars, opts = {}) {
 
     const found = await findInProviders(entry.name, providers);
     if (found !== undefined) {
-      existing.push(entry);
+      if (found.provider && found.provider.persistToProject) {
+        imported.push(entry);
+        toPersist[entry.name] = found.value;
+      } else {
+        existing.push(entry);
+      }
       continue;
     }
 
@@ -259,9 +331,10 @@ async function resolveEnvVars(vars, opts = {}) {
 
     filled.push(entry);
     toPersist[entry.name] = answer;
+    toPersistGlobal[entry.name] = answer;
   }
 
-  return { filled, skipped, existing, toPersist };
+  return { filled, skipped, existing, imported, toPersist, toPersistGlobal };
 }
 
 /**
@@ -352,23 +425,80 @@ async function persistEnvValues(toPersist, opts = {}) {
   return persistProjectEnv(projectDir, toPersist);
 }
 
+/**
+ * Merge `envRecord` into the flat global store (`~/.claude/wizz-env.json`).
+ * Additive only — a key already present is never overwritten (same rule as
+ * `persistProjectEnv`; a prompt only ever fires for a var no provider had,
+ * so an overwrite here would always mean clobbering something newer). File
+ * is chmod 600 after any write that changed it, same best-effort semantics
+ * as the project writer.
+ *
+ * @param {string} storePath - Absolute path to the global store file
+ * @param {Record<string,string>} envRecord - Vars to merge
+ * @returns {Promise<string|null>} Path written/merged, or null when empty
+ */
+async function persistGlobalEnv(storePath, envRecord) {
+  if (!storePath || !envRecord || Object.keys(envRecord).length === 0) return null;
+
+  await fs.ensureDir(path.dirname(storePath));
+
+  let store = {};
+  if (await fs.pathExists(storePath)) {
+    try {
+      const parsed = JSON.parse(await fs.readFile(storePath, 'utf8'));
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) store = parsed;
+    } catch {
+      // A corrupt store must never eat keys the user just typed: keep the
+      // broken file aside and start a fresh store with the new values.
+      try {
+        await fs.rename(storePath, `${storePath}.bak`);
+      } catch {
+        // Even the rename failing must not block the install.
+      }
+    }
+  }
+
+  let changed = false;
+  for (const [key, value] of Object.entries(envRecord)) {
+    if (Object.prototype.hasOwnProperty.call(store, key)) continue;
+    store[key] = value;
+    changed = true;
+  }
+
+  if (changed) {
+    await fs.writeJson(storePath, store, { spaces: 2 });
+    if (process.platform !== 'win32') {
+      try {
+        await fs.chmod(storePath, 0o600);
+      } catch {
+        // Best-effort, same as persistProjectEnv.
+      }
+    }
+  }
+
+  return storePath;
+}
+
 /**
  * Render the DX summary (E6) — the highest-value part of this feature: turn
  * a skipped var from a dead end into a 30-second fix. One line per var,
  * grouped by outcome. Never includes a raw secret value, only names/status.
- * @param {{filled: Array, skipped: Array, existing: Array}} resolved
+ * @param {{filled: Array, skipped: Array, existing: Array, imported: Array}} resolved
  * @returns {string|null} Formatted block, or null when there is nothing to say
  */
-function formatSummary({ filled, skipped, existing }) {
-  const total = (filled?.length || 0) + (skipped?.length || 0) + (existing?.length || 0);
+function formatSummary({ filled, skipped, existing, imported }) {
+  const total = (filled?.length || 0) + (skipped?.length || 0) + (existing?.length || 0) + (imported?.length || 0);
   if (total === 0) return null;
 
   const lines = [];
   for (const entry of existing || []) {
     lines.push(`  ✓ ${entry.name.padEnd(28)} já existia no ambiente`);
   }
+  for (const entry of imported || []) {
+    lines.push(`  ✓ ${entry.name.padEnd(28)} importada do global (~/.claude/wizz-env.json)`);
+  }
   for (const entry of filled || []) {
-    lines.push(`  ✓ ${entry.name.padEnd(28)} configurada agora (.claude/settings.local.json)`);
+    lines.push(`  ✓ ${entry.name.padEnd(28)} configurada agora (+ salva no global p/ próximos projetos)`);
   }
   for (const entry of skipped || []) {
     if (entry.hasDefault) {
@@ -403,18 +533,26 @@ function formatSummary({ filled, skipped, existing }) {
  * @param {string} opts.projectDir - Project root (for persistence + the
  *   default `.env` provider)
  * @param {boolean} [opts.interactive=false]
- * @param {Array<Object>} [opts.providers] - Defaults to `[processEnv, dotenvFile(<projectDir>/.env)]`
+ * @param {Array<Object>} [opts.providers] - Defaults to `[processEnv,
+ *   dotenvFile(<projectDir>/.env), globalStore(~/.claude/wizz-env.json)]`
+ * @param {string} [opts.globalEnvPath] - Global store path (default
+ *   `~/.claude/wizz-env.json`); used for both the default provider chain and
+ *   the save-on-prompt write. Injectable so tests never touch the real home.
  * @param {(entry) => Promise<string|undefined>} [opts.prompter] - Defaults to
  *   the masked `password()` prompter
- * @returns {Promise<{filled: Array, skipped: Array, existing: Array, envFile: string|null}>}
+ * @returns {Promise<{filled: Array, skipped: Array, existing: Array, imported: Array, envFile: string|null}>}
  */
 async function promptMissingEnvVars(mcps, opts = {}) {
-  const { projectDir, interactive = false, providers, prompter } = opts;
+  const { projectDir, interactive = false, providers, prompter, globalEnvPath = defaultGlobalEnvPath() } = opts;
 
   const vars = extractEnvPlaceholders(mcps);
-  if (vars.length === 0) return { filled: [], skipped: [], existing: [], envFile: null };
+  if (vars.length === 0) return { filled: [], skipped: [], existing: [], imported: [], envFile: null };
 
-  const resolvedProviders = providers || [createProcessEnvProvider(), createDotenvFileProvider(path.join(projectDir, '.env'))];
+  const resolvedProviders = providers || [
+    createProcessEnvProvider(),
+    createDotenvFileProvider(path.join(projectDir, '.env')),
+    createGlobalStoreProvider(globalEnvPath),
+  ];
   const resolvedPrompter = interactive ? prompter || createDefaultPrompter() : null;
 
   const resolved = await resolveEnvVars(vars, {
@@ -428,10 +566,27 @@ async function promptMissingEnvVars(mcps, opts = {}) {
     envFile = await persistEnvValues(resolved.toPersist, { projectDir, target: 'settings-local' });
   }
 
+  // Typed answers also go to the global store so the NEXT project resolves
+  // them silently. Failure here must never block the install — the project
+  // write above already succeeded, which is what this install needs.
+  if (Object.keys(resolved.toPersistGlobal).length > 0) {
+    try {
+      await persistGlobalEnv(globalEnvPath, resolved.toPersistGlobal);
+    } catch {
+      // Global save is a convenience for future installs, never a blocker.
+    }
+  }
+
   const summary = formatSummary(resolved);
   if (summary) await prompts.log.info(summary);
 
-  return { filled: resolved.filled, skipped: resolved.skipped, existing: resolved.existing, envFile };
+  return {
+    filled: resolved.filled,
+    skipped: resolved.skipped,
+    existing: resolved.existing,
+    imported: resolved.imported,
+    envFile,
+  };
 }
 
 module.exports = {
@@ -439,8 +594,11 @@ module.exports = {
   resolveEnvVars,
   persistEnvValues,
   persistProjectEnv,
+  persistGlobalEnv,
   promptMissingEnvVars,
   createProcessEnvProvider,
   createDotenvFileProvider,
+  createGlobalStoreProvider,
+  defaultGlobalEnvPath,
   formatSummary,
 };

package/tools/installer/modules/mcp-config.js

@@ -19,6 +19,7 @@
 // a `claude mcp add` command renderer for the recommend path.
 
 const path = require('node:path');
+const os = require('node:os');
 const crypto = require('node:crypto');
 const fs = require('../fs-native');
 const { defaultExec } = require('./cli-config');
@@ -325,6 +326,48 @@ async function partitionAlreadyConfigured({ projectDir, mcps }) {
   return { toPrepare, alreadyConfigured };
 }
 
+/**
+ * Split resolved MCP entries into those still worth offering/installing in
+ * the project and those the user already configured GLOBALLY (user scope, the
+ * `mcpServers` key of `~/.claude.json`). A server configured there is live in
+ * every project already — usually with the real key embedded — so writing the
+ * registry's `${VAR}`-placeholder copy into the project `.mcp.json` would at
+ * best duplicate it and at worst shadow a working global config with a broken
+ * placeholder one, then prompt the user for a key they already provided.
+ *
+ * Read failures (missing/malformed `~/.claude.json`) fall back to "nothing is
+ * global", the safe default: worst case the user sees the old behavior.
+ *
+ * @param {Object} args
+ * @param {Array<{id: string}>} args.mcps - Resolved MCP entries to partition
+ * @param {string} [args.claudeJsonPath] - Override of `~/.claude.json` (tests)
+ * @returns {Promise<{toInstall: Array<Object>, globallyConfigured: string[]}>}
+ */
+async function partitionGloballyConfigured({ mcps, claudeJsonPath }) {
+  if (!mcps || mcps.length === 0) return { toInstall: [], globallyConfigured: [] };
+
+  const file = claudeJsonPath || path.join(os.homedir(), '.claude.json');
+  let globalIds = new Set();
+  if (await fs.pathExists(file)) {
+    try {
+      const config = JSON.parse(await fs.readFile(file, 'utf8'));
+      const servers =
+        config && typeof config === 'object' && config.mcpServers && !Array.isArray(config.mcpServers) ? config.mcpServers : null;
+      if (servers) globalIds = new Set(Object.keys(servers));
+    } catch {
+      globalIds = new Set();
+    }
+  }
+
+  const toInstall = [];
+  const globallyConfigured = [];
+  for (const mcp of mcps) {
+    if (mcp && mcp.id && globalIds.has(mcp.id)) globallyConfigured.push(mcp.id);
+    else toInstall.push(mcp);
+  }
+  return { toInstall, globallyConfigured };
+}
+
 /**
  * Merge the chosen MCP entries into `<projectDir>/.mcp.json`, additively.
  * Reads any existing file (preserving unknown keys and existing servers),
@@ -442,6 +485,7 @@ module.exports = {
   prepareMcp,
   prepareMcps,
   partitionAlreadyConfigured,
+  partitionGloballyConfigured,
   resolveBinPath,
   shellQuote,
   substituteBin,

package/tools/installer/ui.js

@@ -17,7 +17,7 @@ const {
   bundledTargetWarnings,
 } = require('./modules/channel-plan');
 const channelResolver = require('./modules/channel-resolver');
-const { resolveMcps } = require('./modules/mcp-config');
+const { resolveMcps, partitionGloballyConfigured } = require('./modules/mcp-config');
 const { resolveClis, detectClis } = require('./modules/cli-config');
 const prompts = require('./prompts');
 const { parseSetEntries } = require('./set-overrides');
@@ -571,9 +571,21 @@ class UI {
     if (!selectedModules.includes('bmm')) return { toWrite: [], toRecommend: [] };
 
     const registry = this._loadSkillsRegistry();
-    const resolved = resolveMcps(registry, selectedAreas);
+    let resolved = resolveMcps(registry, selectedAreas);
     if (resolved.length === 0) return { toWrite: [], toRecommend: [] };
 
+    // A server the user already configured globally (user scope, `mcpServers`
+    // in ~/.claude.json) is live in every project — offering it again would
+    // duplicate config and re-prompt for a key that already works. Filter it
+    // out of every path below (multiselect, --mcps, --yes) with an info line
+    // so nothing disappears silently.
+    const { toInstall, globallyConfigured } = await partitionGloballyConfigured({ mcps: resolved });
+    if (globallyConfigured.length > 0) {
+      await prompts.log.info(`MCPs já configurados no seu Claude global (~/.claude.json), pulados: ${globallyConfigured.join(', ')}`);
+      resolved = toInstall;
+      if (resolved.length === 0) return { toWrite: [], toRecommend: [] };
+    }
+
     const byId = new Map(resolved.map((m) => [m.id, m]));
     const split = (writeIds) => {
       const writeSet = new Set(writeIds);