wizz-method 1.4.0 → 1.5.0

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

@@ -19,34 +19,32 @@
 // a `claude mcp add` command renderer for the recommend path.
 
 const path = require('node:path');
+const crypto = require('node:crypto');
 const fs = require('../fs-native');
 const { defaultExec } = require('./cli-config');
+const { resolveAreaEntries } = require('./registry-resolve');
 
 /**
  * Resolve the recommended MCP entries for the chosen areas, deduped by id.
  * Empty / undefined / containing 'all' means every area. The cross-cutting
  * `mcp_utility:` servers are always included.
  *
+ * Wrapper fino sobre `resolveAreaEntries` (A16): a resolução por área em si
+ * (sentinel `wantAll`, dedupe por Map, lista cross-cutting) vive em
+ * `registry-resolve.js`; aqui só ficam a forma da entrada de MCP e o filtro
+ * de elegibilidade (precisa de `server`).
+ *
  * @param {Object} registry - Parsed skills-registry.yaml
  * @param {string[]} [selectedAreas] - Area keys to resolve
  * @returns {Array<{id: string, when: string, server: Object, areas: string[]}>}
  *   One entry per unique MCP id, carrying which area(s) recommended it.
  */
 function resolveMcps(registry, selectedAreas) {
-  const byId = new Map();
-  const areas = (registry && registry.areas) || {};
-  const wantAll = !selectedAreas || selectedAreas.length === 0 || selectedAreas.includes('all');
-  const chosen = wantAll ? Object.keys(areas) : selectedAreas;
-
-  const add = (mcp, areaKey) => {
-    if (!mcp || !mcp.id || !mcp.server) return;
-    const existing = byId.get(mcp.id);
-    if (existing) {
-      if (areaKey && !existing.areas.includes(areaKey)) existing.areas.push(areaKey);
-      return;
-    }
-    byId.set(mcp.id, {
-      id: mcp.id,
+  return resolveAreaEntries(registry, selectedAreas, {
+    listKey: 'mcps',
+    utilityKey: 'mcp_utility',
+    isActionable: (mcp) => !!mcp.server,
+    mapEntry: (mcp) => ({
       when: mcp.when || '',
       server: mcp.server,
       // `setup` (optional) declares how to make a `command:`-relative server
@@ -55,17 +53,8 @@ function resolveMcps(registry, selectedAreas) {
       // verify it boots. Carried here so prepareMcps() can act on it; dropped
       // from what toServerConfig() writes (it never belongs in .mcp.json).
       setup: mcp.setup || null,
-      areas: areaKey ? [areaKey] : [],
-    });
-  };
-
-  for (const area of chosen) {
-    for (const mcp of (areas[area] && areas[area].mcps) || []) add(mcp, area);
-  }
-  // Cross-cutting servers are offered regardless of area selection.
-  for (const mcp of (registry && registry.mcp_utility) || []) add(mcp, null);
-
-  return [...byId.values()];
+    }),
+  });
 }
 
 /**
@@ -81,6 +70,22 @@ function toServerConfig(server) {
   return out;
 }
 
+/**
+ * Content marker for a server block (A13: "Merge aditivo do .mcp.json congela
+ * pins de segurança para sempre"). Hashes the NORMALIZED (`toServerConfig`)
+ * shape, not the raw registry `server`, so the hash matches exactly what
+ * lands on disk in `.mcp.json` — a block written by the installer and a block
+ * hand-typed by a user with the same effective config hash identically.
+ * @param {Object} server - { command, args?, env? }
+ * @returns {string} sha256 hex digest
+ */
+function hashServerBlock(server) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(toServerConfig(server || {})))
+    .digest('hex');
+}
+
 /**
  * POSIX-quote a path so it survives interpolation into a shell command even
  * when it contains spaces or shell metacharacters. Single-quote wrapped, with
@@ -111,8 +116,19 @@ function substituteBin(command, binPath) {
  * does not always inherit the user's ~/.local/bin on PATH, so a relative name
  * fails with ENOENT even when the tool is installed. We resolve and write the
  * absolute path instead. Tries `command -v` first (honors the current PATH),
- * then the conventional user-local bin dir where `uv tool` / `pipx` / `pip
- * --user` land executables. Returns null when the binary is nowhere to be found.
+ * then the conventional user-local bin dirs where `uv tool` / `pipx` / `pip
+ * --user` land executables:
+ *   - `~/.local/bin` (uv tool / pipx / pip --user on Linux, and pip --user
+ *     on modern macOS with `--user` in a non-framework Python)
+ *   - `/opt/homebrew/bin` and `/usr/local/bin` (Homebrew on Apple Silicon and
+ *     Intel respectively); a client launched via `npx` from a GUI app often
+ *     inherits a minimal PATH that never saw `brew shellenv`, so a Homebrew
+ *     install looks absent and gets reinstalled via uv/pipx/pip (duplicate
+ *     binary) unless we check here too
+ *   - `~/Library/Python/<version>/bin` (macOS `pip install --user`, which
+ *     lands executables under a Python-version-specific directory, not
+ *     `~/.local/bin`)
+ * Returns null when the binary is nowhere to be found.
  *
  * @param {string} bin - Binary name to locate
  * @param {Function} [exec] - Injected runner (command, opts) => {ok, stdout,...}
@@ -125,11 +141,31 @@ async function resolveBinPath(bin, exec = defaultExec) {
     const found = (viaWhich.stdout || '').trim().split('\n')[0].trim();
     if (found) return found;
   }
+
   const home = process.env.HOME || process.env.USERPROFILE || '';
-  if (home) {
-    const candidate = path.join(home, '.local', 'bin', bin);
+  const candidateDirs = [];
+  if (home) candidateDirs.push(path.join(home, '.local', 'bin'));
+  candidateDirs.push('/opt/homebrew/bin', '/usr/local/bin');
+
+  for (const dir of candidateDirs) {
+    const candidate = path.join(dir, bin);
     if (await fs.pathExists(candidate)) return candidate;
   }
+
+  if (home && process.platform === 'darwin') {
+    const pyUserBase = path.join(home, 'Library', 'Python');
+    try {
+      const versions = await fs.readdir(pyUserBase);
+      for (const version of versions) {
+        const candidate = path.join(pyUserBase, version, 'bin', bin);
+        if (await fs.pathExists(candidate)) return candidate;
+      }
+    } catch {
+      // No ~/Library/Python directory; pip --user was never used here, or
+      // there is nothing to enumerate. Not an error condition.
+    }
+  }
+
   return null;
 }
 
@@ -247,20 +283,93 @@ function renderAddCommand({ id, server }) {
   return `claude mcp add ${id}${envFlags ? ` ${envFlags}` : ''} -- ${cmd}`.replaceAll(/\s+/g, ' ').trim();
 }
 
+/**
+ * Split resolved MCP entries into those that still need the DETECT/INSTALL/
+ * VERIFY/RESOLVE pipeline (prepareMcps) and those whose id is already present
+ * in `.mcp.json` and will be skipped anyway by the additive merge in
+ * writeMcpConfig. Filtering here avoids paying for a subprocess-heavy setup
+ * (npm install -g, browser download, binary verification) on every
+ * re-install for servers we already know will be discarded downstream.
+ *
+ * Read failures (missing/malformed `.mcp.json`) fall back to "prepare
+ * everything", the safe default, and let writeMcpConfig raise the real
+ * error later if the file truly is invalid JSON.
+ *
+ * @param {Object} args
+ * @param {string} args.projectDir - Project root where `.mcp.json` lives
+ * @param {Array<{id: string}>} args.mcps - Resolved MCP entries to partition
+ * @returns {Promise<{toPrepare: Array<Object>, alreadyConfigured: string[]}>}
+ */
+async function partitionAlreadyConfigured({ projectDir, mcps }) {
+  if (!mcps || mcps.length === 0) return { toPrepare: [], alreadyConfigured: [] };
+
+  const file = path.join(projectDir, '.mcp.json');
+  let existingIds = 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) existingIds = new Set(Object.keys(servers));
+    } catch {
+      return { toPrepare: [...mcps], alreadyConfigured: [] };
+    }
+  }
+
+  const toPrepare = [];
+  const alreadyConfigured = [];
+  for (const mcp of mcps) {
+    if (mcp && mcp.id && existingIds.has(mcp.id)) alreadyConfigured.push(mcp.id);
+    else toPrepare.push(mcp);
+  }
+  return { toPrepare, alreadyConfigured };
+}
+
 /**
  * Merge the chosen MCP entries into `<projectDir>/.mcp.json`, additively.
  * Reads any existing file (preserving unknown keys and existing servers),
- * adds only ids not already present, and writes back pretty-printed JSON.
+ * adds ids not already present, and writes back pretty-printed JSON.
+ *
+ * A13 ("Merge aditivo do .mcp.json congela pins de segurança para sempre"):
+ * for an id already present, `previousPins[id]` (the hash the installer
+ * recorded the LAST time it wrote that block, from
+ * `skill-deps-cache.json`/`deps-cache.js`) tells us whether the on-disk block
+ * is still exactly what we wrote or whether the user hand-edited it:
+ *   - on-disk hash === current registry hash        → nothing to do (current)
+ *   - on-disk hash === previousPins[id] (untouched)  → the registry pin moved
+ *     and the user never touched this block: SAFE to apply the update automatically
+ *     (`pinUpdated`). This is not overwriting a customization — it is finishing
+ *     an update the user already implicitly opted into by never editing our block.
+ *   - on-disk hash !== previousPins[id] (or no recorded hash — pre-A13 install)
+ *     → the user's edit (or an unknown state) wins; NEVER overwritten, only
+ *     surfaced (`pinCustomized`) so the caller can warn "update available, but
+ *     this server was customized".
  *
  * @param {Object} args
  * @param {string} args.projectDir - Project root where `.mcp.json` lives
  * @param {Array<{id: string, server: Object}>} args.mcps - Entries to write
+ * @param {Record<string,string>} [args.previousPins] - id => hash recorded at
+ *   the installer's last write of that block (from skill-deps-cache.json)
  * @param {(absPath: string) => void} [args.trackFile] - Record the written file
- * @returns {Promise<{added: string[], skipped: string[], file: string|null}>}
- *   `added` = ids newly written, `skipped` = ids already present (left intact).
+ * @param {boolean} [args.dryRun] - Compute the merge (added/skipped/pinHashes/
+ *   etc.) WITHOUT touching disk. Used by fresh installs (A14): `.mcp.json`
+ *   lives outside `_wizz/`, so it must not be mutated until the atomic
+ *   install's tmp→real swap has succeeded — but `pinHashes` is still needed
+ *   beforehand to seed `skill-deps-cache.json`. The caller re-invokes without
+ *   `dryRun` after the swap to perform the real write.
+ * @returns {Promise<{added: string[], skipped: string[], file: string|null,
+ *   pinHashes: Record<string,string>, pinUpdated: Array<{id:string,from:string,to:string}>,
+ *   pinCustomized: Array<{id:string}>}>}
+ *   `added` = ids newly written. `skipped` = ids already current, nothing to
+ *   do. `pinCustomized` = ids left intact because the on-disk block diverges
+ *   from what we last wrote (a separate bucket from `skipped` so the caller
+ *   can warn specifically about those). `pinHashes` = id => hash of what is
+ *   now on disk for every resolved id, meant to be persisted as the NEXT
+ *   `previousPins`.
  */
-async function writeMcpConfig({ projectDir, mcps, trackFile = () => {} }) {
-  if (!mcps || mcps.length === 0) return { added: [], skipped: [], file: null };
+async function writeMcpConfig({ projectDir, mcps, previousPins = {}, trackFile = () => {}, dryRun = false }) {
+  const empty = { added: [], skipped: [], file: null, pinHashes: {}, pinUpdated: [], pinCustomized: [] };
+  if (!mcps || mcps.length === 0) return empty;
 
   const file = path.join(projectDir, '.mcp.json');
   let config = {};
@@ -276,29 +385,63 @@ async function writeMcpConfig({ projectDir, mcps, trackFile = () => {} }) {
 
   const added = [];
   const skipped = [];
+  const pinHashes = {};
+  const pinUpdated = [];
+  const pinCustomized = [];
+  let changed = false;
+
   for (const mcp of mcps) {
+    const newHash = hashServerBlock(mcp.server);
+
     if (Object.prototype.hasOwnProperty.call(config.mcpServers, mcp.id)) {
-      skipped.push(mcp.id); // never clobber the user's existing server
+      const onDisk = config.mcpServers[mcp.id];
+      const onDiskHash = hashServerBlock(onDisk);
+
+      if (onDiskHash === newHash) {
+        skipped.push(mcp.id); // already current, nothing to do
+        pinHashes[mcp.id] = newHash;
+        continue;
+      }
+
+      const recordedHash = previousPins[mcp.id];
+      if (recordedHash && recordedHash === onDiskHash) {
+        // Untouched since our last write, and the registry pin moved — safe
+        // to apply automatically. Never a silent overwrite of user work.
+        config.mcpServers[mcp.id] = toServerConfig(mcp.server);
+        pinUpdated.push({ id: mcp.id, from: recordedHash, to: newHash });
+        pinHashes[mcp.id] = newHash;
+        changed = true;
+      } else {
+        // No recorded hash (pre-A13 install) or the hash diverges: the user
+        // may have hand-edited this block. Never clobber it — only report.
+        pinCustomized.push({ id: mcp.id });
+        pinHashes[mcp.id] = onDiskHash;
+      }
       continue;
     }
+
     config.mcpServers[mcp.id] = toServerConfig(mcp.server);
     added.push(mcp.id);
+    pinHashes[mcp.id] = newHash;
+    changed = true;
   }
 
-  if (added.length === 0) return { added, skipped, file };
+  if (!changed || dryRun) return { added, skipped, file, pinHashes, pinUpdated, pinCustomized };
 
   await fs.writeJson(file, config, { spaces: 2 });
   trackFile(file);
-  return { added, skipped, file };
+  return { added, skipped, file, pinHashes, pinUpdated, pinCustomized };
 }
 
 module.exports = {
   resolveMcps,
   toServerConfig,
+  hashServerBlock,
   renderAddCommand,
   writeMcpConfig,
   prepareMcp,
   prepareMcps,
+  partitionAlreadyConfigured,
   resolveBinPath,
   shellQuote,
   substituteBin,

package/tools/installer/modules/module-help-schema.js

@@ -1,7 +1,8 @@
 /**
  * Canonical schema for per-module `module-help.csv` files.
  *
- * Both the merger (`Installer.mergeModuleHelpCatalogs`) and the synthesizer
+ * Both the merger (`core/help-catalog.js` `mergeModuleHelpCatalogs`, exposed
+ * on `Installer` as a thin wrapper) and the synthesizer
  * (`PluginResolver._buildSynthesizedHelpCsv`) emit this exact header. The
  * merger compares each per-module file's header against this string and
  * warns on drift, so any rename here must be matched in external module

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

@@ -3,7 +3,7 @@ const fs = require('../fs-native');
 const yaml = require('yaml');
 const prompts = require('../prompts');
 const { getProjectRoot, getSourcePath, getModulePath } = require('../project-root');
-const { CLIUtils } = require('../cli-utils');
+const { CLIUtils } = require('../banner');
 const { ExternalModuleManager } = require('./external-manager');
 
 class OfficialModules {

package/tools/installer/modules/registry-resolve.js

@@ -0,0 +1,74 @@
+// Resolução genérica de entradas por área do skills-registry.yaml.
+//
+// A16 (auditoria 2026-07-07): resolveMcps (mcp-config.js), resolveClis
+// (cli-config.js) e resolveSkillIds (skills-lib.js) implementavam
+// literalmente o mesmo algoritmo — sentinel `wantAll` -> `chosen = wantAll ?
+// Object.keys(areas) : selectedAreas` -> dedupe por Map acumulando `areas[]`
+// -> inclusão da lista cross-cutting (`mcp_utility`/`cli_utility`/`utility`)
+// -> só a FORMA da entrada final (quais campos ela carrega) mudava por
+// chamador. Esta função extrai o algoritmo; os três módulos originais viram
+// wrappers finos que só declaram o que é específico deles: a chave da lista
+// por área/utility, o filtro de elegibilidade (`isActionable`) e a forma dos
+// campos extras (`mapEntry`).
+//
+// Contrato preservado: mesma assinatura pública e mesmo comportamento
+// observável dos três resolvers originais. As suítes test/test-mcp-config.js,
+// test/test-cli-config.js e o teste de instalação que cobre skills-lib.js são
+// o safety net desta extração.
+
+/**
+ * Resolve entradas cross-cutting-aware por área, deduplicadas por `id`.
+ *
+ * Vazio/undefined/contendo `'all'` em `selectedAreas` significa "todas as
+ * áreas" (mesmo sentinel usado pelos três resolvers originais). A lista
+ * `utilityKey` no topo do registry (ex.: `mcp_utility`, `cli_utility`,
+ * `utility`) é sempre incluída, independente da seleção de área.
+ *
+ * @param {Object} registry - skills-registry.yaml já parseado
+ * @param {string[]} [selectedAreas] - Chaves de área a resolver
+ * @param {Object} opts
+ * @param {string} opts.listKey - Chave da lista por área (ex.: 'mcps', 'clis', 'skills')
+ * @param {string} opts.utilityKey - Chave da lista cross-cutting no topo do registry
+ * @param {(raw: Object) => boolean} [opts.isActionable] - Filtro extra de elegibilidade
+ *   além de exigir `id` (que esta função já garante). Default: sempre true.
+ * @param {(raw: Object) => Object} [opts.mapEntry] - Molda os campos extras da entrada
+ *   resolvida. `id` e `areas` são sempre geridos por esta função e sobrescrevem
+ *   qualquer campo homônimo devolvido por `mapEntry`. Default: devolve o objeto
+ *   cru como veio do registry.
+ * @returns {Array<Object>} Uma entrada por id único, com `id` + `areas: string[]`
+ *   somados aos campos de `mapEntry`. Quando o mesmo id aparece em mais de uma
+ *   área, `areas` acumula todas elas (a primeira ocorrência decide os demais
+ *   campos, igual ao comportamento original).
+ */
+function resolveAreaEntries(registry, selectedAreas, opts) {
+  const { listKey, utilityKey, isActionable = () => true, mapEntry = (raw) => raw } = opts;
+  const byId = new Map();
+  const areas = (registry && registry.areas) || {};
+  const wantAll = !selectedAreas || selectedAreas.length === 0 || selectedAreas.includes('all');
+  const chosen = wantAll ? Object.keys(areas) : selectedAreas;
+
+  const add = (raw, areaKey) => {
+    if (!raw || !raw.id) return;
+    if (!isActionable(raw)) return;
+    const existing = byId.get(raw.id);
+    if (existing) {
+      if (areaKey && !existing.areas.includes(areaKey)) existing.areas.push(areaKey);
+      return;
+    }
+    byId.set(raw.id, {
+      ...mapEntry(raw),
+      id: raw.id,
+      areas: areaKey ? [areaKey] : [],
+    });
+  };
+
+  for (const area of chosen) {
+    for (const raw of (areas[area] && areas[area][listKey]) || []) add(raw, area);
+  }
+  // A lista cross-cutting é oferecida independente da seleção de área.
+  for (const raw of (registry && registry[utilityKey]) || []) add(raw, null);
+
+  return [...byId.values()];
+}
+
+module.exports = { resolveAreaEntries };

package/tools/installer/modules/skills-lib.js

@@ -13,36 +13,38 @@
 // It also installs the registry itself into `_wizz/_config/` so the maestro can
 // read the same file at runtime (the routing source and the install source stay
 // identical by construction). Every step is a no-op when its source is missing.
+//
+// On top of the monolith copy, it also SLICES the registry per area into
+// `_wizz/_config/registry/` (index.yaml + <area>.yaml + _shared.yaml). Area
+// agents read their own slice at runtime instead of the whole ~26KB file; the
+// monolith copy stays in place as the fallback/compat path (see
+// generateRegistrySlices doc below for the exact shape of each slice).
 
 const path = require('node:path');
 const fs = require('../fs-native');
 const yaml = require('yaml');
 const { getProjectRoot, getSourcePath } = require('../project-root');
+const { resolveAreaEntries } = require('./registry-resolve');
 
 /**
  * Resolve which skill ids to install from the registry for the chosen areas.
  * Empty / undefined / containing 'all' means every area. Utility skills
  * (graphify, find-skills, ...) are cross-cutting and always included.
+ *
+ * Wrapper fino sobre `resolveAreaEntries` (A16): a resolução por área vive em
+ * `registry-resolve.js`; aqui só sobra reduzir as entradas resolvidas ao
+ * `id` (esta função nunca precisou de mais nada — nem de `areas`).
+ *
  * @param {Object} registry - Parsed skills-registry.yaml
  * @param {string[]} [selectedAreas] - Area keys to install
  * @returns {string[]} Deduped skill ids
  */
 function resolveSkillIds(registry, selectedAreas) {
-  const ids = new Set();
-  const areas = (registry && registry.areas) || {};
-  const wantAll = !selectedAreas || selectedAreas.length === 0 || selectedAreas.includes('all');
-  const chosen = wantAll ? Object.keys(areas) : selectedAreas;
-
-  for (const area of chosen) {
-    const skills = (areas[area] && areas[area].skills) || [];
-    for (const skill of skills) {
-      if (skill && skill.id) ids.add(skill.id);
-    }
-  }
-  for (const util of (registry && registry.utility) || []) {
-    if (util && util.id) ids.add(util.id);
-  }
-  return [...ids];
+  const entries = resolveAreaEntries(registry, selectedAreas, {
+    listKey: 'skills',
+    utilityKey: 'utility',
+  });
+  return entries.map((entry) => entry.id);
 }
 
 /**
@@ -73,6 +75,64 @@ const isCopyableEntry = (src) => {
   return !(name.startsWith('.') && name !== '.gitkeep');
 };
 
+// Header stamped on every generated slice — warns readers (humans and agents)
+// not to hand-edit a file that gets clobbered on the next install.
+const SLICE_HEADER =
+  '# GERADO PELO INSTALLER — NÃO EDITAR (sobrescrito a cada install).\n' +
+  '# Fonte única: skills-registry.yaml na raiz do repo. Esta fatia existe só\n' +
+  '# para leitura leve em runtime; qualquer mudança de conteúdo vai no monólito.\n\n';
+
+/**
+ * Slice the parsed registry into `_wizz/_config/registry/`:
+ *   - index.yaml: version + areas (only `agent`/`summary`) — a lightweight
+ *     area→agent map for the maestro to route without loading full skill lists.
+ *   - <area>.yaml: the full block for that area (skills/mcps/clis/references),
+ *     wrapped as `area: <name>` + the area's own fields, for the area agent
+ *     that owns it to read directly instead of the monolith.
+ *   - _shared.yaml: the cross-cutting sections (utility, mcp_utility,
+ *     cli_utility, squads) any agent may still need alongside its own slice.
+ *
+ * ALL areas are sliced regardless of `selectedAreas` — generation is cheap
+ * (in-memory yaml.stringify) and this avoids a missing-slice bug if the user
+ * later switches to an agent whose area wasn't installed this run.
+ *
+ * @param {Object} registry - Parsed skills-registry.yaml
+ * @param {string} registryDir - Destination dir (`_wizz/_config/registry`)
+ * @param {(absPath: string) => void} trackFile - Record an installed file
+ */
+async function generateRegistrySlices(registry, registryDir, trackFile) {
+  await fs.ensureDir(registryDir);
+
+  const areas = (registry && registry.areas) || {};
+
+  const indexAreas = {};
+  for (const [name, area] of Object.entries(areas)) {
+    indexAreas[name] = { agent: area && area.agent, summary: area && area.summary };
+  }
+  const indexPath = path.join(registryDir, 'index.yaml');
+  await fs.writeFile(indexPath, SLICE_HEADER + yaml.stringify({ version: registry && registry.version, areas: indexAreas }));
+  trackFile(indexPath);
+
+  for (const [name, area] of Object.entries(areas)) {
+    const areaPath = path.join(registryDir, `${name}.yaml`);
+    await fs.writeFile(areaPath, SLICE_HEADER + yaml.stringify({ area: name, ...area }));
+    trackFile(areaPath);
+  }
+
+  const sharedPath = path.join(registryDir, '_shared.yaml');
+  await fs.writeFile(
+    sharedPath,
+    SLICE_HEADER +
+      yaml.stringify({
+        utility: (registry && registry.utility) || [],
+        mcp_utility: (registry && registry.mcp_utility) || [],
+        cli_utility: (registry && registry.cli_utility) || [],
+        squads: (registry && registry.squads) || {},
+      }),
+  );
+  trackFile(sharedPath);
+}
+
 /**
  * Copy the area-selected skills from src/skills-lib into `_wizz/skills-lib`, and
  * the registry into `_wizz/_config/skills-registry.yaml`. No-op when sources are
@@ -129,7 +189,12 @@ async function installSkillsLib({ wizzDir, selectedAreas, trackFile = () => {} }
   await fs.copy(srcRegistry, destRegistry);
   trackFile(destRegistry);
 
+  // Also slice it per area (see generateRegistrySlices) so agents can read a
+  // few KB instead of the whole monolith; the copy above stays as fallback.
+  const registryDir = path.join(wizzDir, '_config', 'registry');
+  await generateRegistrySlices(registry, registryDir, trackFile);
+
   return { copied, skipped, registry: true };
 }
 
-module.exports = { installSkillsLib, resolveSkillIds };
+module.exports = { installSkillsLib, resolveSkillIds, generateRegistrySlices };

package/tools/installer/ui.js

@@ -5,7 +5,7 @@ const yaml = require('yaml');
 const fs = require('./fs-native');
 const { getProjectRoot } = require('./project-root');
 const installerPackageJson = require('../../package.json');
-const { CLIUtils } = require('./cli-utils');
+const { CLIUtils } = require('./banner');
 const { ExternalModuleManager } = require('./modules/external-manager');
 const { resolveModuleVersion } = require('./modules/version-resolver');
 const { Manifest } = require('./core/manifest');
@@ -238,6 +238,7 @@ class UI {
         choices.push({
           name: 'Quick Update',
           value: 'quick-update',
+          hint: 'Atualiza só os módulos instalados. Não instala skills/MCPs/CLIs novos (use Modify Wizz Installation para isso)',
         });
       }
 
@@ -434,6 +435,18 @@ class UI {
     const selectedAreas = await this.selectSkillAreas(selectedModules, options);
     const mcpPlan = await this.selectMcps(selectedModules, selectedAreas, options);
     const cliPlan = await this.selectClis(selectedModules, selectedAreas, options);
+
+    // 3.8-E1: local routing-trace opt-in. Only relevant when wizz-router is
+    // actually part of the install (bmm), and — like the MCP/CLI pickers
+    // above — only offered on a genuinely interactive TTY (never --yes/CI).
+    // `null` (not asked) is distinct from `false` (asked, declined) so the
+    // final summary can tell the two apart.
+    let traceEnabled = null;
+    if (selectedModules.includes('bmm')) {
+      const traceInteractive = !(!!options.yes || !process.stdin.isTTY);
+      traceEnabled = await this.promptTraceOptIn(confirmedDirectory, { interactive: traceInteractive });
+    }
+
     const { moduleConfigs, setOverrides } = await this.collectModuleConfigs(confirmedDirectory, selectedModules, {
       ...options,
       channelOptions,
@@ -466,19 +479,25 @@ class UI {
       setOverrides,
       skipPrompts: options.yes || false,
       channelOptions,
+      traceEnabled,
     };
   }
 
   /**
    * Load and parse skills-registry.yaml from the package root.
+   * A corrupted/unparsable registry still degrades to null (areas/MCPs/CLIs
+   * come back empty rather than crashing the install), but that degradation
+   * is never silent: it is logged so the failure is diagnosable instead of
+   * looking like "nothing to choose from" (audit finding M11).
    * @returns {Object|null} Parsed registry, or null when absent/unreadable
    */
   _loadSkillsRegistry() {
+    const registryPath = path.join(getProjectRoot(), 'skills-registry.yaml');
+    if (!fs.existsSync(registryPath)) return null;
     try {
-      const registryPath = path.join(getProjectRoot(), 'skills-registry.yaml');
-      if (!fs.existsSync(registryPath)) return null;
       return yaml.parse(fs.readFileSync(registryPath, 'utf8'));
-    } catch {
+    } catch (error) {
+      console.warn(`⚠ skills-registry.yaml failed to parse (${error.message}). Areas/MCPs/CLIs will be empty until this is fixed.`);
       return null;
     }
   }
@@ -660,7 +679,9 @@ class UI {
       options: missing.map((c) => ({
         label: c.id,
         value: c.id,
-        hint: c.when,
+        // M27/M14: prefer the upgrade/verify-failure reason when present —
+        // more actionable than the generic `when` in those two cases.
+        hint: c.upgradeMessage || c.verifyWarning || c.when,
       })),
       initialValues: [],
       required: false,
@@ -669,6 +690,51 @@ class UI {
     return split(selected || []);
   }
 
+  /**
+   * 3.8-E1: ask whether to opt into the local routing-trace measurement and,
+   * if yes, persist `WIZZ_TRACE=1` into the project's
+   * `.claude/settings.local.json` (chave `env`) — the exact merge-writer 3.3
+   * built for MCP env vars (`persistProjectEnv`), reused here so there is
+   * only one implementation of "merge a value into settings.local.json's
+   * `env` key without clobbering what's already there" (see
+   * `tools/installer/modules/env-vars.js`).
+   *
+   * The trace is entirely local: `tools/hooks/wizz-router-enforce.js`
+   * (already installed globally) reads `process.env.WIZZ_TRACE` and, when
+   * set, appends one JSON line per routed prompt to
+   * `~/.claude/wizz-trace.jsonl` on this machine — nothing leaves it. Claude
+   * Code merges a project's `.claude/settings.local.json` `env` key into
+   * every subprocess it spawns for that project, so setting the key here is
+   * enough to turn the hook's trace on for sessions in this project, with no
+   * change to the hook itself.
+   *
+   * `interactive` is computed by the caller (not read from `process.stdin`
+   * here) so this stays a plain, TTY-independent function to unit test —
+   * mirrors the seam `promptMissingEnvVars`/`resolveEnvVars` already use in
+   * env-vars.js. Never opts in silently: a `false`/no-TTY caller always
+   * skips without prompting, so telemetry is opt-in by construction, never
+   * default-on.
+   *
+   * @param {string} projectDir - Project root (where `.claude/` lives)
+   * @param {Object} [opts]
+   * @param {boolean} [opts.interactive=false] - Whether to actually prompt
+   * @returns {Promise<boolean>} Whether WIZZ_TRACE was turned on
+   */
+  async promptTraceOptIn(projectDir, opts = {}) {
+    const { interactive = false } = opts;
+    if (!interactive) return false;
+
+    const enable = await prompts.confirm({
+      message: 'Quer ligar o medidor de roteamento? (local, grava só em ~/.claude/wizz-trace.jsonl na sua máquina, nunca sai daqui)',
+      default: false,
+    });
+    if (!enable) return false;
+
+    const { persistProjectEnv } = require('./modules/env-vars');
+    await persistProjectEnv(projectDir, { WIZZ_TRACE: '1' });
+    return true;
+  }
+
   /**
    * Prompt for tool/IDE selection (called after module configuration)
    * Uses a split prompt approach: