wizz-method 1.0.2 → 1.1.0

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

@@ -19,7 +19,7 @@ function normalizeChannelName(raw) {
 /**
  * Conservative quoting for tag names passed to git commands. Tags are
  * user-typed (--pin) or come from the GitHub API. Only allow the semver
- * character class we use to tag BMad releases; anything else throws.
+ * character class we use to tag Wizz releases; anything else throws.
  */
 function quoteShell(ref) {
   if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
@@ -46,7 +46,7 @@ async function writeChannelMarker(markerPath, data) {
   }
 }
 
-const REGISTRY_CONFIG_PATH = path.join(getProjectRoot(), 'bmad-modules.yaml');
+const REGISTRY_CONFIG_PATH = path.join(getProjectRoot(), 'wizz-modules.yaml');
 
 /**
  * Manages official modules from the bundled registry file. The remote
@@ -109,7 +109,7 @@ class ExternalModuleManager {
       name: mod.display_name || mod.name,
       description: mod.description || '',
       defaultSelected: mod.default_selected === true || mod.defaultSelected === true,
-      type: mod.type || 'bmad-org',
+      type: mod.type || 'wizz-org',
       npmPackage: mod.npm_package || mod.npmPackage || null,
       pluginName: mod.plugin_name || mod.pluginName || null,
       defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable',
@@ -153,7 +153,7 @@ class ExternalModuleManager {
    * @returns {string} Path to the external modules cache directory
    */
   getExternalCacheDir() {
-    const cacheDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules');
+    const cacheDir = path.join(os.homedir(), '.wizz', 'cache', 'external-modules');
     return cacheDir;
   }
 
@@ -255,7 +255,7 @@ class ExternalModuleManager {
       // updates" and re-use the cached version silently — that's the right
       // call for an update/quick-update, since the semantics don't change
       // and the user isn't worse off than before they ran this command.
-      const cachedMarker = await readChannelMarker(path.join(moduleCacheDir, '.bmad-channel.json'));
+      const cachedMarker = await readChannelMarker(path.join(moduleCacheDir, '.wizz-channel.json'));
       if (cachedMarker?.channel && (await fs.pathExists(moduleCacheDir))) {
         if (!silent) {
           await prompts.log.warn(
@@ -309,7 +309,7 @@ class ExternalModuleManager {
     }
 
     // ─── Clone or update cache by resolved channel ────────────────────────
-    const markerPath = path.join(moduleCacheDir, '.bmad-channel.json');
+    const markerPath = path.join(moduleCacheDir, '.wizz-channel.json');
     const currentMarker = await readChannelMarker(markerPath);
     const needsChannelReset = currentMarker && currentMarker.channel !== resolved.channel;
 

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

@@ -0,0 +1,137 @@
+// Configures the recommended MCP servers for the chosen skill areas.
+//
+// The skills-registry.yaml is the single source of truth: besides mapping each
+// AREA to its skills, it declares an `mcps:` list per area (plus a top-level
+// `mcp_utility:` for cross-cutting servers like context7). This module reads
+// that registry, resolves the user's chosen areas to a deduped set of MCP
+// entries, and MERGES the selected ones into the project's `.mcp.json`.
+//
+// Design rules (kept deliberately conservative):
+//   - ADDITIVE: an existing server with the same id is never overwritten. The
+//     user's hand-tuned config always wins; we only ADD what is missing.
+//   - SECRETS STAY PLACEHOLDERS: `env` values come straight from the registry
+//     as `${VAR}` placeholders. We never read, infer, or write a real token.
+//   - NO-OP WHEN ABSENT: missing registry / no MCPs => returns empty, writes
+//     nothing. Always safe to call.
+//
+// The caller decides WHICH ids to write (the interactive multiselect) and which
+// to merely recommend; this module exposes the resolution + merge primitives and
+// a `claude mcp add` command renderer for the recommend path.
+
+const path = require('node:path');
+const fs = require('../fs-native');
+
+/**
+ * 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.
+ *
+ * @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,
+      when: mcp.when || '',
+      server: mcp.server,
+      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()];
+}
+
+/**
+ * Normalize a registry `server` block into the shape written to `.mcp.json`.
+ * Drops empty `args`/`env` so the output stays minimal and diff-friendly.
+ * @param {Object} server - { command, args?, env? } from the registry
+ * @returns {Object} Sanitized server config
+ */
+function toServerConfig(server) {
+  const out = { command: server.command };
+  if (Array.isArray(server.args) && server.args.length > 0) out.args = [...server.args];
+  if (server.env && Object.keys(server.env).length > 0) out.env = { ...server.env };
+  return out;
+}
+
+/**
+ * Render the `claude mcp add` command for an MCP entry — used to recommend
+ * servers the user chose NOT to write (nothing is lost; they can add later).
+ * @param {{id: string, server: Object}} mcp - Resolved MCP entry
+ * @returns {string} A copy-pasteable shell command
+ */
+function renderAddCommand({ id, server }) {
+  const envFlags = Object.entries(server.env || {})
+    .map(([k, v]) => `-e ${k}=${v}`)
+    .join(' ');
+  const args = (server.args || []).join(' ');
+  const cmd = `${server.command}${args ? ` ${args}` : ''}`;
+  return `claude mcp add ${id}${envFlags ? ` ${envFlags}` : ''} -- ${cmd}`.replaceAll(/\s+/g, ' ').trim();
+}
+
+/**
+ * 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.
+ *
+ * @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 {(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).
+ */
+async function writeMcpConfig({ projectDir, mcps, trackFile = () => {} }) {
+  if (!mcps || mcps.length === 0) return { added: [], skipped: [], file: null };
+
+  const file = path.join(projectDir, '.mcp.json');
+  let config = {};
+  if (await fs.pathExists(file)) {
+    try {
+      config = JSON.parse(await fs.readFile(file, 'utf8'));
+    } catch (error) {
+      throw new Error(`.mcp.json existe mas não é JSON válido: ${error.message}`);
+    }
+  }
+  if (!config || typeof config !== 'object') config = {};
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') config.mcpServers = {};
+
+  const added = [];
+  const skipped = [];
+  for (const mcp of mcps) {
+    if (Object.prototype.hasOwnProperty.call(config.mcpServers, mcp.id)) {
+      skipped.push(mcp.id); // never clobber the user's existing server
+      continue;
+    }
+    config.mcpServers[mcp.id] = toServerConfig(mcp.server);
+    added.push(mcp.id);
+  }
+
+  if (added.length === 0) return { added, skipped, file };
+
+  await fs.writeJson(file, config, { spaces: 2 });
+  trackFile(file);
+  return { added, skipped, file };
+}
+
+module.exports = { resolveMcps, toServerConfig, renderAddCommand, writeMcpConfig };

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

@@ -264,27 +264,27 @@ class OfficialModules {
   /**
    * Install a module
    * @param {string} moduleName - Code of the module to install (from module.yaml)
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} wizzDir - Target wizz directory
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
    * @param {Object} options - Additional installation options
    * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
    * @param {Object} options.moduleConfig - Module configuration from config collector
    * @param {Object} options.logger - Logger instance for output
    */
-  async install(moduleName, bmadDir, fileTrackingCallback = null, options = {}) {
+  async install(moduleName, wizzDir, fileTrackingCallback = null, options = {}) {
     // Check if this module has a plugin resolution (custom marketplace install)
     const { CustomModuleManager } = require('./custom-module-manager');
     const customMgr = new CustomModuleManager();
     const resolved = customMgr.getResolution(moduleName);
     if (resolved) {
-      return this.installFromResolution(resolved, bmadDir, fileTrackingCallback, options);
+      return this.installFromResolution(resolved, wizzDir, fileTrackingCallback, options);
     }
 
     const sourcePath = await this.findModuleSource(moduleName, {
       silent: options.silent,
       channelOptions: options.channelOptions,
     });
-    const targetPath = path.join(bmadDir, moduleName);
+    const targetPath = path.join(wizzDir, moduleName);
 
     if (!sourcePath) {
       throw new Error(
@@ -299,18 +299,18 @@ class OfficialModules {
     await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
 
     if (!options.skipModuleInstaller) {
-      await this.createModuleDirectories(moduleName, bmadDir, options);
+      await this.createModuleDirectories(moduleName, wizzDir, options);
     }
 
     const { Manifest } = require('../core/manifest');
     const manifestObj = new Manifest();
-    const versionInfo = await manifestObj.getModuleVersionInfo(moduleName, bmadDir, sourcePath);
+    const versionInfo = await manifestObj.getModuleVersionInfo(moduleName, wizzDir, sourcePath);
 
     // Pick up channel resolution recorded by the external manager (the only
     // manager that does pre-clone resolution now that community is retired).
     const resolution = this.externalModuleManager.getResolution(moduleName);
 
-    await manifestObj.addModule(bmadDir, moduleName, {
+    await manifestObj.addModule(wizzDir, moduleName, {
       version: resolution?.version || versionInfo.version,
       source: versionInfo.source,
       npmPackage: versionInfo.npmPackage,
@@ -326,12 +326,12 @@ 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} bmadDir - Target bmad directory
+   * @param {string} wizzDir - Target wizz directory
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
    * @param {Object} options - Installation options
    */
-  async installFromResolution(resolved, bmadDir, fileTrackingCallback = null, options = {}) {
-    const targetPath = path.join(bmadDir, resolved.code);
+  async installFromResolution(resolved, wizzDir, fileTrackingCallback = null, options = {}) {
+    const targetPath = path.join(wizzDir, resolved.code);
 
     if (await fs.pathExists(targetPath)) {
       await fs.remove(targetPath);
@@ -361,7 +361,7 @@ class OfficialModules {
 
     // Create directories declared in module.yaml (strategies 1-4 may have these)
     if (!options.skipModuleInstaller) {
-      await this.createModuleDirectories(resolved.code, bmadDir, options);
+      await this.createModuleDirectories(resolved.code, wizzDir, options);
     }
 
     // Update manifest. For custom-source installs we derive channel from the
@@ -382,7 +382,7 @@ class OfficialModules {
       if (resolved.rawInput) manifestEntry.rawSource = resolved.rawInput;
     }
     if (resolved.localPath) manifestEntry.localPath = resolved.localPath;
-    await manifestObj.addModule(bmadDir, resolved.code, manifestEntry);
+    await manifestObj.addModule(wizzDir, resolved.code, manifestEntry);
 
     return {
       success: true,
@@ -400,11 +400,11 @@ class OfficialModules {
   /**
    * Update an existing module
    * @param {string} moduleName - Name of the module to update
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} wizzDir - Target wizz directory
    */
-  async update(moduleName, bmadDir) {
+  async update(moduleName, wizzDir) {
     const sourcePath = await this.findModuleSource(moduleName);
-    const targetPath = path.join(bmadDir, moduleName);
+    const targetPath = path.join(wizzDir, moduleName);
 
     if (!sourcePath) {
       throw new Error(`Module '${moduleName}' not found in any source location`);
@@ -426,10 +426,10 @@ class OfficialModules {
   /**
    * Remove a module
    * @param {string} moduleName - Name of the module to remove
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} wizzDir - Target wizz directory
    */
-  async remove(moduleName, bmadDir) {
-    const targetPath = path.join(bmadDir, moduleName);
+  async remove(moduleName, wizzDir) {
+    const targetPath = path.join(wizzDir, moduleName);
 
     if (!(await fs.pathExists(targetPath))) {
       throw new Error(`Module '${moduleName}' is not installed`);
@@ -446,22 +446,22 @@ class OfficialModules {
   /**
    * Check if a module is installed
    * @param {string} moduleName - Name of the module
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} wizzDir - Target wizz directory
    * @returns {boolean} True if module is installed
    */
-  async isInstalled(moduleName, bmadDir) {
-    const targetPath = path.join(bmadDir, moduleName);
+  async isInstalled(moduleName, wizzDir) {
+    const targetPath = path.join(wizzDir, moduleName);
     return await fs.pathExists(targetPath);
   }
 
   /**
    * Get installed module info
    * @param {string} moduleName - Name of the module
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} wizzDir - Target wizz directory
    * @returns {Object|null} Module info or null if not installed
    */
-  async getInstalledInfo(moduleName, bmadDir) {
-    const targetPath = path.join(bmadDir, moduleName);
+  async getInstalledInfo(moduleName, wizzDir) {
+    const targetPath = path.join(wizzDir, moduleName);
 
     if (!(await fs.pathExists(targetPath))) {
       return null;
@@ -557,17 +557,17 @@ class OfficialModules {
    * This replaces the security-risky module installer pattern with declarative config
    * During updates, if a directory path changed, moves the old directory to the new path
    * @param {string} moduleName - Name of the module
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} wizzDir - Target wizz directory
    * @param {Object} options - Installation options
    * @param {Object} options.moduleConfig - Module configuration from config collector
    * @param {Object} options.existingModuleConfig - Previous module config (for detecting path changes during updates)
    * @param {Object} options.coreConfig - Core configuration
    * @returns {Promise<{createdDirs: string[], movedDirs: string[], createdWdsFolders: string[]}>} Created directories info
    */
-  async createModuleDirectories(moduleName, bmadDir, options = {}) {
+  async createModuleDirectories(moduleName, wizzDir, options = {}) {
     const moduleConfig = options.moduleConfig || {};
     const existingModuleConfig = options.existingModuleConfig || {};
-    const projectRoot = path.dirname(bmadDir);
+    const projectRoot = path.dirname(wizzDir);
     const emptyResult = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
 
     // Special handling for core module - it's in src/core-skills not src/modules
@@ -781,16 +781,16 @@ class OfficialModules {
   // ─── Config collection methods (merged from ConfigCollector) ───
 
   /**
-   * Find the bmad installation directory in a project
+   * Find the wizz installation directory in a project
    * V6+ installations can use ANY folder name but ALWAYS have _config/manifest.yaml
    * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} Path to bmad directory
+   * @returns {Promise<string>} Path to wizz directory
    */
-  async findBmadDir(projectDir) {
+  async findWizzDir(projectDir) {
     // Check if project directory exists
     if (!(await fs.pathExists(projectDir))) {
       // Project doesn't exist yet, return default
-      return path.join(projectDir, 'bmad');
+      return path.join(projectDir, 'wizz');
     }
 
     // V6+ strategy: Look for ANY directory with _config/manifest.yaml
@@ -812,15 +812,15 @@ class OfficialModules {
 
     // No V6+ installation found, return default
     // This will be used for new installations
-    return path.join(projectDir, 'bmad');
+    return path.join(projectDir, 'wizz');
   }
 
   /**
-   * Detect the existing BMAD folder name in a project
+   * Detect the existing WIZZ folder name in a project
    * @param {string} projectDir - Project directory
    * @returns {Promise<string|null>} Folder name (just the name, not full path) or null if not found
    */
-  async detectExistingBmadFolder(projectDir) {
+  async detectExistingWizzFolder(projectDir) {
     // Check if project directory exists
     if (!(await fs.pathExists(projectDir))) {
       return null;
@@ -857,11 +857,11 @@ class OfficialModules {
       return false;
     }
 
-    // Find the actual bmad directory (handles custom folder names)
-    const bmadDir = await this.findBmadDir(projectDir);
+    // Find the actual wizz directory (handles custom folder names)
+    const wizzDir = await this.findWizzDir(projectDir);
 
-    // Check if bmad directory exists
-    if (!(await fs.pathExists(bmadDir))) {
+    // Check if wizz directory exists
+    if (!(await fs.pathExists(wizzDir))) {
       return false;
     }
 
@@ -871,7 +871,7 @@ class OfficialModules {
     // every reinstall.
     let foundAny = false;
     for (const fileName of ['config.toml', 'config.user.toml']) {
-      const tomlPath = path.join(bmadDir, fileName);
+      const tomlPath = path.join(wizzDir, fileName);
       if (!(await fs.pathExists(tomlPath))) continue;
       try {
         const content = await fs.readFile(tomlPath, 'utf8');
@@ -893,7 +893,7 @@ class OfficialModules {
     }
 
     // Fallback: legacy per-module config.yaml files (pre-v6 installations).
-    const entries = await fs.readdir(bmadDir, { withFileTypes: true });
+    const entries = await fs.readdir(wizzDir, { withFileTypes: true });
     const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
     for (const entry of entries) {
       if (entry.isDirectory()) {
@@ -901,7 +901,7 @@ class OfficialModules {
           continue;
         }
 
-        const moduleConfigPath = path.join(bmadDir, entry.name, 'config.yaml');
+        const moduleConfigPath = path.join(wizzDir, entry.name, 'config.yaml');
 
         if (await fs.pathExists(moduleConfigPath)) {
           try {
@@ -1447,7 +1447,7 @@ class OfficialModules {
         result = username.charAt(0).toUpperCase() + username.slice(1);
       }
     } catch {
-      // Do nothing, just return 'BMad'
+      // Do nothing, just return 'Wizz'
     }
     return result;
   }

package/tools/installer/modules/plugin-resolver.js

@@ -354,12 +354,12 @@ class PluginResolver {
 
   /**
    * Format a kebab-case or snake_case name into a display name.
-   * Strips common prefixes like "bmad-" or "bmad-agent-".
+   * Strips common prefixes like "wizz-" or "wizz-agent-".
    * @param {string} name - Raw name
    * @returns {string} Formatted display name
    */
   _formatDisplayName(name) {
-    let cleaned = name.replace(/^bmad-agent-/, '').replace(/^bmad-/, '');
+    let cleaned = name.replace(/^wizz-agent-/, '').replace(/^wizz-/, '');
     return cleaned
       .split(/[-_]/)
       .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
@@ -373,7 +373,7 @@ class PluginResolver {
    * @returns {string} Menu code (e.g., "CC" for "code-coach")
    */
   _generateMenuCode(name) {
-    const cleaned = name.replace(/^bmad-agent-/, '').replace(/^bmad-/, '');
+    const cleaned = name.replace(/^wizz-agent-/, '').replace(/^wizz-/, '');
     const words = cleaned.split(/[-_]/).filter((w) => w.length > 0);
     return words
       .map((w) => w.charAt(0).toUpperCase())

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

@@ -0,0 +1,135 @@
+// Installs the global skills library (src/skills-lib) into the project.
+//
+// The skills-registry.yaml is the single source of truth: it maps each AREA
+// (designer, copy, seo, growth, ...) to the skill ids that area pulls. This
+// module reads that registry, resolves the user's chosen areas to a set of
+// skill ids, and copies only those skill directories into `_wizz/skills-lib/`.
+//
+// From there the existing verbatim-skill pipeline takes over untouched:
+//   collectSkills() discovers `_wizz/skills-lib/<id>/SKILL.md`
+//   → writeSkillManifest() records them in `_wizz/_config/skill-manifest.csv`
+//   → installVerbatimSkills() copies each into every selected IDE's skills dir.
+//
+// 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.
+
+const path = require('node:path');
+const fs = require('../fs-native');
+const yaml = require('yaml');
+const { getProjectRoot, getSourcePath } = require('../project-root');
+
+/**
+ * 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.
+ * @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];
+}
+
+/**
+ * Recursively collect every file path under a directory.
+ * @param {string} dir - Directory to walk
+ * @param {string[]} acc - Accumulator of absolute file paths
+ */
+async function collectFiles(dir, acc) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await collectFiles(full, acc);
+    } else {
+      acc.push(full);
+    }
+  }
+}
+
+const isCopyableEntry = (src) => {
+  const name = path.basename(src);
+  if (name === '.DS_Store' || name === 'Thumbs.db' || name === 'desktop.ini') return false;
+  return !(name.startsWith('.') && name !== '.gitkeep');
+};
+
+/**
+ * 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
+ * absent (e.g. a dev tree without the library), so it is always safe to call.
+ *
+ * @param {Object} args
+ * @param {string} args.wizzDir - Installed `_wizz` directory
+ * @param {string[]} [args.selectedAreas] - Area keys; empty/undefined => all areas
+ * @param {(absPath: string) => void} [args.trackFile] - Record an installed file
+ * @returns {Promise<{copied: number, skipped: string[], registry: boolean}>}
+ */
+async function installSkillsLib({ wizzDir, selectedAreas, trackFile = () => {} }) {
+  const srcLib = getSourcePath('skills-lib');
+  const srcRegistry = path.join(getProjectRoot(), 'skills-registry.yaml');
+
+  if (!(await fs.pathExists(srcLib)) || !(await fs.pathExists(srcRegistry))) {
+    return { copied: 0, skipped: [], registry: false };
+  }
+
+  let registry;
+  try {
+    registry = yaml.parse(await fs.readFile(srcRegistry, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to parse skills-registry.yaml: ${error.message}`);
+  }
+
+  const ids = resolveSkillIds(registry, selectedAreas);
+  const destLib = path.join(wizzDir, 'skills-lib');
+  const skipped = [];
+  let copied = 0;
+
+  for (const id of ids) {
+    const srcSkill = path.join(srcLib, id);
+    const skillMd = path.join(srcSkill, 'SKILL.md');
+    if (!(await fs.pathExists(skillMd))) {
+      // A registry id with no shipped skill directory — record and skip quietly.
+      skipped.push(id);
+      continue;
+    }
+
+    const destSkill = path.join(destLib, id);
+    await fs.remove(destSkill); // clear stale files before copy
+    await fs.copy(srcSkill, destSkill, { filter: isCopyableEntry });
+
+    const files = [];
+    await collectFiles(destSkill, files);
+    for (const file of files) trackFile(file);
+    copied++;
+  }
+
+  // Install the registry so the maestro reads the same source at runtime.
+  const destRegistry = path.join(wizzDir, '_config', 'skills-registry.yaml');
+  await fs.ensureDir(path.dirname(destRegistry));
+  await fs.copy(srcRegistry, destRegistry);
+  trackFile(destRegistry);
+
+  return { copied, skipped, registry: true };
+}
+
+module.exports = { installSkillsLib, resolveSkillIds };