ma-agents 3.17.0-beta.0 → 3.17.0-beta.2

package/bin/cli.js

@@ -39,7 +39,8 @@ const { reconfigure: runReconfigure, ReconfigureYesRejectedError, ManifestNotFou
 const { uninstallProfileArtifacts } = require('../lib/uninstall');
 const bmad = require('../lib/bmad');
 const { getBmadPlatformCode } = require('../lib/agents');
-const { enumerateCustomSource, NFR71_WARNING, CustomMarketplaceError, reconcileCustomMarketplaceSelection } = require('../lib/custom-marketplace');
+const { enumerateCustomSource, NFR71_WARNING, CustomMarketplaceError, reconcileCustomMarketplaceSelection, registryTrustLabel } = require('../lib/custom-marketplace');
+const { setLogSink, diag, diagError } = require('../lib/diag');
 const { handleCreateSkill, handleValidateSkill, handleSetMandatory, handleCustomizeAgent, handleCreateAgent } = require('../lib/skill-authoring');
 
 const PKG = require('../package.json');
@@ -55,9 +56,21 @@ const VERSION = PKG.version;
  */
 function setupLogging(logFilePath) {
   const logFd = fs.openSync(logFilePath, 'w');
-  const header = `[${new Date().toISOString()}] ${NAME} v${VERSION} — log started\n`;
+  // Rich header — the environment facts needed to make sense of a report later:
+  // exact version, how it was invoked, runtime, platform, and where it ran.
+  const header =
+    `[${new Date().toISOString()}] ${NAME} v${VERSION} — log started\n` +
+    `  argv:     ${process.argv.slice(1).join(' ')}\n` +
+    `  node:     ${process.version}\n` +
+    `  platform: ${process.platform} ${process.arch}\n` +
+    `  cwd:      ${process.cwd()}\n`;
   fs.writeSync(logFd, header);
 
+  // Route log-file-only diagnostics (lib/diag.js) to this fd. These breadcrumbs
+  // (custom-marketplace phases, swallowed error causes, etc.) land ONLY in the
+  // log, never on the user's console.
+  setLogSink((s) => { try { fs.writeSync(logFd, s); } catch { /* ignore */ } });
+
   const origStdoutWrite = process.stdout.write.bind(process.stdout);
   const origStderrWrite = process.stderr.write.bind(process.stderr);
 
@@ -81,6 +94,7 @@ function setupLogging(logFilePath) {
     process.stderr.write = origStderrWrite;
     const footer = `\n[${new Date().toISOString()}] log ended\n`;
     try { fs.writeSync(logFd, footer); } catch { /* ignore */ }
+    setLogSink(null);
     try { fs.closeSync(logFd); } catch { /* ignore */ }
     delete process.env.MA_AGENTS_LOG_ACTIVE;
   };
@@ -990,7 +1004,7 @@ function resolveBaseBmadOk({ bmadInstalled, attempted, success }) {
  * @param {Object} ctx
  * @param {string} [ctx.bmadCustomSourceFlag] - `--bmad-custom-source <ref>` value
  * @param {boolean} [ctx.yesFlag] - non-interactive run
- * @returns {Promise<null|{ source: string, mode: 'discovery'|'direct', selectedCodes: string[],
+ * @returns {Promise<null|{ source: string, mode: 'discovery'|'direct'|'registry', selectedCodes: string[],
  *   plugins: Array<Object>, rootDir: string, sourceUrl: string|null }>}
  */
 async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = false } = {}) {
@@ -1025,13 +1039,16 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
   }
 
   let enumerated;
+  diag('custom-source: enumerate begin', { source });
   try {
     enumerated = await enumerateCustomSource(source);
   } catch (err) {
     // Fail clean (spike §3 contract) — a short, human-readable message only.
     // Never print err.stack here: an unreachable/unauthorized custom source
     // must not dump a raw upstream stack, and must never touch the base
-    // install (the rest of installWizard proceeds unaffected).
+    // install (the rest of installWizard proceeds unaffected). The full cause
+    // (and stack) goes to the LOG FILE only, for diagnosis.
+    diagError('custom-source: enumerate failed', err);
     const message = err instanceof CustomMarketplaceError ? err.message : `Custom marketplace source error: ${err.message}`;
     console.log(chalk.red(`\n  ${message}`));
     console.log(chalk.gray('  Skipping custom marketplace source; the rest of the install is unaffected.'));
@@ -1039,6 +1056,11 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
   }
 
   const { plugins, mode, rootDir, sourceUrl } = enumerated;
+  diag('custom-source: enumerated', {
+    source, mode, rootDir, sourceUrl,
+    pluginCount: (plugins || []).length,
+    codes: (plugins || []).map((p) => p.code),
+  });
   if (!plugins || plugins.length === 0) {
     console.log(chalk.yellow(`  Custom marketplace source "${source}" declared no plugins — nothing to select.`));
     return { source, mode, selectedCodes: [], plugins: [], rootDir, sourceUrl };
@@ -1056,15 +1078,31 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
     return { source, mode, selectedCodes, plugins, rootDir, sourceUrl };
   }
 
+  // Registry mode (this story): show display_name + trust tier + category and
+  // make the community/unverified trust tier explicit PER ENTRY (AC2, NFR71).
+  // Registry entries are opt-in — nothing is pre-selected (AC1/AC2). Discovery/
+  // direct keep their existing "all pre-selected" behavior unchanged (AC6).
+  const isRegistry = mode === 'registry';
   const { chosenCodes } = await prompts({
     type: 'multiselect',
     name: 'chosenCodes',
     message: `Select extensions to install from "${source}":`,
-    choices: plugins.map((p) => ({
-      title: chalk.white(p.code) + chalk.gray(p.description ? ` — ${p.description}` : ''),
-      value: p.code,
-      selected: true,
-    })),
+    choices: plugins.map((p) => {
+      if (isRegistry) {
+        const label = registryTrustLabel(p);
+        const certified = p.trustTier === 'bmad-certified';
+        const head = chalk.white(p.displayName || p.name || p.code);
+        const tier = (certified ? chalk.green : chalk.yellow)(`[${label}]`);
+        const cat = p.category ? chalk.gray(` {${p.category}${p.subcategory ? `/${p.subcategory}` : ''}}`) : '';
+        const desc = p.description ? chalk.gray(` — ${p.description}`) : '';
+        return { title: `${head} ${tier}${cat}${desc}`, value: p.code, selected: false };
+      }
+      return {
+        title: chalk.white(p.code) + chalk.gray(p.description ? ` — ${p.description}` : ''),
+        value: p.code,
+        selected: true,
+      };
+    }),
     instructions: chalk.gray('  Use space to toggle, enter to confirm.'),
   });
 
@@ -1093,7 +1131,7 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
  *
  * @param {Object} ctx
  * @param {string} ctx.projectRoot
- * @returns {Promise<undefined|null|{ source: string, mode: 'discovery'|'direct',
+ * @returns {Promise<undefined|null|{ source: string, mode: 'discovery'|'direct'|'registry',
  *   selectedCodes: string[], plugins: Array<Object>, rootDir: string, sourceUrl: string|null }>}
  *   `undefined` — nothing persisted; caller should fall back to `promptCustomMarketplace()`.
  *   `null` — persisted source exists but could not be re-enumerated (fail-loud; skip this run).
@@ -1101,12 +1139,16 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
  */
 async function reconcileCustomMarketplaceOnUpdate({ projectRoot }) {
   const persisted = getCustomMarketplaceSelection(projectRoot);
+  diag('custom-source: reconcile on update', persisted
+    ? { source: persisted.source, mode: persisted.mode, selectedCodes: persisted.selectedCodes }
+    : { persisted: false });
   if (!persisted) return undefined;
 
   let enumerated;
   try {
     enumerated = await enumerateCustomSource(persisted.source);
   } catch (err) {
+    diagError('custom-source: reconcile re-enumerate failed', err);
     const message = err instanceof CustomMarketplaceError ? err.message : `Custom marketplace source error: ${err.message}`;
     console.log(chalk.red(`\n  Custom marketplace update FAILED: ${message}`));
     console.log(
@@ -1531,6 +1573,12 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
         }
       }
       if (customMarketplaceSelection && customMarketplaceSelection.selectedCodes.length > 0) {
+        diag('custom-source: install begin', {
+          mode: customMarketplaceSelection.mode,
+          source: customMarketplaceSelection.source,
+          selectedCodes: customMarketplaceSelection.selectedCodes,
+          baseBmadOk,
+        });
         if (!baseBmadOk) {
           // AC 6 (30.6b) — never layer --custom-source onto a project with no
           // (or a broken) base BMAD install. The rest of the install is
@@ -1549,10 +1597,14 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
               tools: bmadTools,
               selection: customMarketplaceSelection,
             });
+            diag('custom-source: install result', { success: !!success });
             if (success) {
               console.log(chalk.green('  Custom marketplace subset installed successfully!'));
             }
           } catch (err) {
+            // User sees the one-liner; the full cause/stack (which entry, the
+            // git/resolve error, the FR238 zero-module detail) goes to the log.
+            diagError('custom-source: install failed', err);
             console.log(chalk.red(`\n  Custom marketplace install failed: ${err.message}`));
           }
         }

package/lib/bmad-extension-plugin/.claude-plugin/marketplace.json

@@ -37,7 +37,7 @@
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.17.0-beta.0",
+      "version": "3.17.0-beta.2",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad.js

@@ -1686,7 +1686,7 @@ async function deployClineWorkflows(projectRoot, tools = []) {
  * @param {string} ctx.projectRoot
  * @param {string[]} ctx.modules - The same bmad module set used for the base install.
  * @param {string[]} ctx.tools - The same IDE/tool set used for the base install.
- * @param {{ source: string, mode: 'discovery'|'direct', selectedCodes: string[],
+ * @param {{ source: string, mode: 'discovery'|'direct'|'registry', selectedCodes: string[],
  *   plugins: Array<Object>, rootDir: string, sourceUrl: string|null }} ctx.selection -
  *   30.6a's `promptCustomMarketplace()` return value (extended with `rootDir`/`sourceUrl`).
  * @returns {Promise<boolean>} true on success; false on any failure (logged, never thrown).
@@ -1705,6 +1705,7 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
     // bmad-method child process or fighting Node's require-cache semantics
     // to stub out module-internal function bindings.
     const stageFn = deps.stageCustomMarketplaceSubset || customMarketplace.stageCustomMarketplaceSubset;
+    const stageRegistryFn = deps.stageRegistrySubset || customMarketplace.stageRegistrySubset;
     const runCommandFn = deps.runCommand || runCommand;
     const deployClineWorkflowsFn = deps.deployClineWorkflows || deployClineWorkflows;
     const cleanupStageFn = deps.cleanupStage || cleanupStage;
@@ -1719,15 +1720,27 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
     let customSourceArg;
     let resolvedModules;
     try {
-        ({ stagePath, customSourceArg, resolvedModules } = await stageFn({
-            source: selection.source,
-            mode: selection.mode,
-            rootDir: selection.rootDir,
-            sourceUrl: selection.sourceUrl,
-            plugins: selection.plugins,
-            selectedCodes: selection.selectedCodes,
-            projectRoot,
-        }));
+        if (selection.mode === 'registry') {
+            // Registry-index mode (this story): two-level clone+resolve+stage of
+            // each selected entry's own repository. Shares the same stage dir +
+            // install path as discovery/direct; only the staging step differs.
+            ({ stagePath, customSourceArg, resolvedModules } = await stageRegistryFn({
+                source: selection.source,
+                plugins: selection.plugins,
+                selectedCodes: selection.selectedCodes,
+                projectRoot,
+            }));
+        } else {
+            ({ stagePath, customSourceArg, resolvedModules } = await stageFn({
+                source: selection.source,
+                mode: selection.mode,
+                rootDir: selection.rootDir,
+                sourceUrl: selection.sourceUrl,
+                plugins: selection.plugins,
+                selectedCodes: selection.selectedCodes,
+                projectRoot,
+            }));
+        }
     } catch (err) {
         const message = err instanceof CustomMarketplaceError ? err.message : `Custom marketplace staging error: ${err.message}`;
         console.error(chalk.red(`  Custom marketplace subset staging failed: ${message}`));
@@ -1763,14 +1776,28 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
         // failure is logged as a warning only — it must never turn an
         // otherwise-successful install into a reported failure.
         try {
-            const sha = (resolvedModules || []).map((m) => m.cloneSha).find((s) => s) || null;
-            setCustomMarketplaceSelectionFn(projectRoot, {
+            const persistEntry = {
                 source: selection.source,
                 sourceUrl: selection.sourceUrl ?? null,
                 mode: selection.mode,
                 selectedCodes: selection.selectedCodes,
-                sha,
-            });
+            };
+            if (selection.mode === 'registry') {
+                // AC5 — record each selected entry's registry-provided
+                // `approved_sha` (the immutable pin the registry declares), plus
+                // its `approved_tag`. `sha` (the top-level field) mirrors the
+                // first available approved_sha for back-compat with readers that
+                // only look at `sha`.
+                const selectedSet = new Set(selection.selectedCodes);
+                const registryEntries = (selection.plugins || [])
+                    .filter((p) => selectedSet.has(p.code))
+                    .map((p) => ({ code: p.code, approvedSha: p.approvedSha ?? null, approvedTag: p.approvedTag ?? null }));
+                persistEntry.entries = registryEntries;
+                persistEntry.sha = registryEntries.map((e) => e.approvedSha).find((s) => s) || null;
+            } else {
+                persistEntry.sha = (resolvedModules || []).map((m) => m.cloneSha).find((s) => s) || null;
+            }
+            setCustomMarketplaceSelectionFn(projectRoot, persistEntry);
         } catch (persistErr) {
             console.warn(chalk.yellow(`  Warning: could not persist custom marketplace selection: ${persistErr.message}`));
         }

package/lib/custom-marketplace.js

@@ -39,10 +39,34 @@
 
 const path = require('node:path');
 const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const { diag } = require('./diag');
 
 /** Deep, pinned-internal require path (NFR17). Single call site. */
 const CUSTOM_MODULE_MANAGER_PATH = 'bmad-method/tools/installer/modules/custom-module-manager.js';
 
+/**
+ * Registry-index mode (this story) — the BMAD registry layout used by the
+ * official plugin registry (`bmad-code-org/bmad-plugins-marketplace`) and any
+ * source that follows the same convention. A `registry/` directory holding
+ * `official.yaml` and/or `community-index.yaml` (each a top-level `modules:`
+ * list) is a THIRD source shape, distinct from `discovery`
+ * (`.claude-plugin/marketplace.json`) and `direct` (whole repo = one module).
+ * Detection precedence is: discovery > registry > direct (see
+ * `enumerateCustomSource`).
+ */
+const REGISTRY_DIR_NAME = 'registry';
+const REGISTRY_OFFICIAL_INDEX = 'official.yaml';
+const REGISTRY_COMMUNITY_INDEX = 'community-index.yaml';
+const REGISTRY_SCHEMA_FILE = 'registry-schema.yaml';
+
+/** Convert an OS-native relative path to a POSIX ('/'-separated) one for the
+ *  staged marketplace.json (bmad-method's parseSource/skills detection is
+ *  POSIX-oriented, and JSON marketplaces are always written POSIX-style). */
+function toPosix(relPath) {
+    return relPath.split(path.sep).join('/');
+}
+
 /**
  * The `CustomModuleManager` methods the custom-marketplace feature depends on.
  * Any drift in this set (renamed/removed on a bmad-method pin bump) must fail
@@ -63,6 +87,23 @@ const NFR71_WARNING =
     'Custom marketplace content is outside ma-agents\' sealed-bundle guarantee — ' +
     'it is installed as-is from the source you provided and is not vetted by ma-agents.';
 
+/**
+ * NFR71 (registry mode) — a per-entry trust annotation the wizard appends to
+ * each registry choice so the community/unverified trust tier is explicit at
+ * the point of selection (not just in the one-time source-level warning). A
+ * `bmad-certified` (official) entry is labelled as such; anything else is made
+ * explicitly "unverified/community — installed as-is, not vetted".
+ *
+ * @param {{ trustTier?: string, type?: string }} plugin - a normalized registry entry
+ * @returns {string} human-readable trust label
+ */
+function registryTrustLabel(plugin) {
+    if (plugin && plugin.trustTier === 'bmad-certified') {
+        return 'bmad-certified';
+    }
+    return 'unverified/community — installed as-is, not vetted by ma-agents';
+}
+
 /**
  * Error type raised by this adapter for any enumeration failure (unreachable
  * source, invalid input, drifted surface). Callers should catch this and
@@ -150,6 +191,150 @@ function assertCustomModuleManagerSurface() {
     return { version, mgr };
 }
 
+// ─── Registry-index mode (this story) ──────────────────────────────────────
+
+/**
+ * Detect the BMAD registry-index layout inside an already-resolved source root.
+ * A source is treated as a registry when its `registry/` directory holds an
+ * `official.yaml` and/or a `community-index.yaml` module index (or, failing
+ * those, a `registry-schema.yaml`, which still marks the source as a registry
+ * even if it currently declares no modules). Called ONLY after discovery
+ * (`.claude-plugin/marketplace.json`) has been ruled out, so discovery always
+ * wins (AC1 precedence).
+ *
+ * @param {string} rootDir - Absolute resolved source root.
+ * @returns {Promise<{ isRegistry: boolean, officialPath: string|null, communityPath: string|null }>}
+ */
+async function detectRegistryLayout(rootDir) {
+    const registryDir = path.join(rootDir, REGISTRY_DIR_NAME);
+    if (!(await fs.pathExists(registryDir))) {
+        return { isRegistry: false, officialPath: null, communityPath: null };
+    }
+    const officialAbs = path.join(registryDir, REGISTRY_OFFICIAL_INDEX);
+    const communityAbs = path.join(registryDir, REGISTRY_COMMUNITY_INDEX);
+    const schemaAbs = path.join(registryDir, REGISTRY_SCHEMA_FILE);
+    const [hasOfficial, hasCommunity, hasSchema] = await Promise.all([
+        fs.pathExists(officialAbs),
+        fs.pathExists(communityAbs),
+        fs.pathExists(schemaAbs),
+    ]);
+    if (!hasOfficial && !hasCommunity && !hasSchema) {
+        return { isRegistry: false, officialPath: null, communityPath: null };
+    }
+    return {
+        isRegistry: true,
+        officialPath: hasOfficial ? officialAbs : null,
+        communityPath: hasCommunity ? communityAbs : null,
+    };
+}
+
+/**
+ * Normalize one raw registry-index entry (conforming to
+ * `registry/registry-schema.yaml`) into the SAME plugin-choice object shape the
+ * wizard's multiselect (30.6a/6b) already consumes, plus the registry-only
+ * pointer fields the two-level install needs (`repository`, `moduleDefinition`,
+ * `approvedSha`, `approvedTag`, `version`, `trustTier`).
+ *
+ * @param {Object} entry - raw YAML module entry
+ * @param {{ official: boolean }} ctx - which index the entry came from
+ * @returns {Object} normalized plugin-choice object
+ */
+function normalizeRegistryEntry(entry, { official }) {
+    const trustTier = entry.trust_tier || (official ? 'bmad-certified' : 'unverified');
+    const type = entry.type || (official ? 'bmad-org' : 'community');
+    return {
+        code: entry.code || entry.name,
+        name: entry.name,
+        displayName: entry.display_name || entry.name,
+        description: entry.description || '',
+        type,
+        trustTier,
+        category: entry.category || null,
+        subcategory: entry.subcategory || null,
+        // Registry-only pointer fields (two-level install).
+        repository: entry.repository || null,
+        moduleDefinition: entry.module_definition || null,
+        approvedSha: entry.approved_sha || null,
+        approvedTag: entry.approved_tag || null,
+        version: entry.version || null,
+        builtIn: entry.built_in === true,
+        isExternal: true,
+    };
+}
+
+/**
+ * Parse one registry index file (`official.yaml` / `community-index.yaml`) into
+ * a normalized entry list. A missing/empty `modules:` key yields `[]`; a YAML
+ * syntax error or a non-list `modules:` throws a clean `CustomMarketplaceError`
+ * (AC4 malformed-index fail-clean). Individual entries that lack a usable
+ * `name` or `repository` pointer are SKIPPED (they are not installable and must
+ * not sink an otherwise-valid registry).
+ *
+ * @param {string} indexPath - absolute path to the index file
+ * @param {{ official: boolean }} ctx
+ * @returns {Promise<Array<Object>>} normalized entries
+ * @throws {CustomMarketplaceError}
+ */
+async function parseRegistryIndex(indexPath, { official }) {
+    const label = path.basename(indexPath);
+    let raw;
+    try {
+        raw = await fs.readFile(indexPath, 'utf8');
+    } catch (err) {
+        throw new CustomMarketplaceError(`Could not read registry index "${label}": ${err.message}`, { cause: err });
+    }
+    let doc;
+    try {
+        doc = yaml.load(raw);
+    } catch (err) {
+        throw new CustomMarketplaceError(
+            `Registry index "${label}" is not valid YAML: ${err.message}`,
+            { cause: err }
+        );
+    }
+    if (doc === null || doc === undefined) return [];
+    if (typeof doc !== 'object' || Array.isArray(doc)) {
+        throw new CustomMarketplaceError(`Registry index "${label}" is not a mapping with a "modules" list.`);
+    }
+    const modules = doc.modules;
+    if (modules === undefined || modules === null) return [];
+    if (!Array.isArray(modules)) {
+        throw new CustomMarketplaceError(`Registry index "${label}" has a "modules" key that is not a list.`);
+    }
+    const out = [];
+    for (const entry of modules) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+        if (typeof entry.name !== 'string' || !entry.name.trim()) continue; // not addressable — skip
+        if (typeof entry.repository !== 'string' || !entry.repository.trim()) continue; // no pointer — not installable
+        out.push(normalizeRegistryEntry(entry, { official }));
+    }
+    return out;
+}
+
+/**
+ * Build the `registry`-mode enumeration result: parse the official + community
+ * indexes, merge, and de-dupe by `name` (official — bmad-certified — wins over
+ * a same-named community entry).
+ *
+ * @param {string} rootDir
+ * @param {string|null} sourceUrl
+ * @param {{ officialPath: string|null, communityPath: string|null }} layout
+ * @returns {Promise<{ mode: 'registry', plugins: Array<Object>, rootDir: string, sourceUrl: string|null }>}
+ */
+async function enumerateRegistrySource(rootDir, sourceUrl, layout) {
+    const official = layout.officialPath ? await parseRegistryIndex(layout.officialPath, { official: true }) : [];
+    const community = layout.communityPath ? await parseRegistryIndex(layout.communityPath, { official: false }) : [];
+
+    // Official entries are appended first so they win the de-dupe on a name
+    // collision (a bmad-certified module must never be shadowed by an unverified
+    // community entry of the same name).
+    const byName = new Map();
+    for (const p of [...official, ...community]) {
+        if (!byName.has(p.name)) byName.set(p.name, p);
+    }
+    return { mode: 'registry', plugins: [...byName.values()], rootDir, sourceUrl };
+}
+
 /**
  * Enumerate the plugins declared by a custom marketplace source.
  *
@@ -204,6 +389,31 @@ async function enumerateCustomSource(source) {
         return { mode: 'discovery', plugins, rootDir: resolved.rootDir, sourceUrl: resolved.sourceUrl };
     }
 
+    // AC1 precedence: discovery (above) wins; else a `registry/` layout →
+    // `registry` mode; else `direct` (below). The registry index is a
+    // higher-level pointer format (each entry names a separate module repo),
+    // so it is enumerated distinctly from a single-repo direct source.
+    let registryLayout;
+    try {
+        registryLayout = await detectRegistryLayout(resolved.rootDir);
+    } catch (err) {
+        throw new CustomMarketplaceError(
+            `Could not inspect "${source}" for a registry layout: ${err.message}`,
+            { cause: err }
+        );
+    }
+    if (registryLayout.isRegistry) {
+        try {
+            return await enumerateRegistrySource(resolved.rootDir, resolved.sourceUrl, registryLayout);
+        } catch (err) {
+            if (err instanceof CustomMarketplaceError) throw err;
+            throw new CustomMarketplaceError(
+                `Could not read the registry index from "${source}": ${err.message}`,
+                { cause: err }
+            );
+        }
+    }
+
     // FR240 — "direct" mode (no marketplace.json at the source root): treat the
     // whole source as a single module so the wizard's multiselect still has
     // exactly one, well-described choice. 30.6b decides how a direct-mode
@@ -244,17 +454,17 @@ const CUSTOM_MARKETPLACE_STAGE_DIR_NAME = '.ma-agents-custom-marketplace-stage';
  * @param {string} rootDir - Absolute path to the direct-mode source root.
  * @returns {Promise<string[]>} Directory names (not paths) that contain a SKILL.md.
  */
-async function scanDirectModeSkillDirs(rootDir) {
+async function scanSkillDirs(baseDir) {
     let entries;
     try {
-        entries = await fs.readdir(rootDir, { withFileTypes: true });
+        entries = await fs.readdir(baseDir, { withFileTypes: true });
     } catch {
         return [];
     }
     const skillDirs = [];
     for (const entry of entries) {
         if (!entry.isDirectory()) continue;
-        const skillMd = path.join(rootDir, entry.name, 'SKILL.md');
+        const skillMd = path.join(baseDir, entry.name, 'SKILL.md');
         if (await fs.pathExists(skillMd)) {
             skillDirs.push(entry.name);
         }
@@ -262,6 +472,12 @@ async function scanDirectModeSkillDirs(rootDir) {
     return skillDirs;
 }
 
+/** Story 30.6b direct-mode scan (thin alias of {@link scanSkillDirs} at the
+ *  source root) — kept as a named export for the 30.6b surface. */
+async function scanDirectModeSkillDirs(rootDir) {
+    return scanSkillDirs(rootDir);
+}
+
 /**
  * Resolve every selected plugin's installable skill/module layout via
  * bmad-method's own `CustomModuleManager#resolvePlugin` (the pinned-internal
@@ -336,14 +552,38 @@ async function resolveSelectedPlugins({ mode, rootDir, sourceUrl, plugins, selec
  * @returns {Array<Object>} The flattened list of resolved modules (all plugins).
  * @throws {CustomMarketplaceError} on any violation above.
  */
-function assertResolutionNonEmptyAndUniqueLeaves(resolvedByPlugin, { source = '' } = {}) {
+function assertResolutionNonEmptyAndUniqueLeaves(resolvedByPlugin, { source = '', mode = null } = {}) {
     const allModules = resolvedByPlugin.flatMap((r) => r.resolved || []);
 
+    // Per-plugin resolution detail → log file only. When the guard below trips,
+    // this line pinpoints WHICH entry resolved to nothing (and how many
+    // skills each resolved module got) — the crux of a "zero modules" report.
+    diag('custom-source: resolution', {
+        source, mode,
+        perPlugin: resolvedByPlugin.map((r) => ({
+            plugin: (r.plugin && (r.plugin.code || r.plugin.name)) || (r.rawPlugin && r.rawPlugin.name) || '?',
+            modules: (r.resolved || []).length,
+            skills: (r.resolved || []).reduce((n, m) => n + ((m.skillPaths && m.skillPaths.length) || 0), 0),
+        })),
+        totalModules: allModules.length,
+    });
+
     if (allModules.length === 0) {
+        // AC7 — a direct-mode source that resolves to nothing is the exact
+        // failure a mis-pointed registry URL used to produce. Name the likely
+        // cause and note that registry indexes are now supported (so re-running
+        // will auto-detect them), instead of a bare "zero modules" abort.
+        const directHint =
+            mode === 'direct'
+                ? ' The source has no `.claude-plugin/marketplace.json` and no `module.yaml`/skills ' +
+                  'directories at its root. If it is a BMAD registry index (a `registry/` directory ' +
+                  'with `official.yaml`/`community-index.yaml`), that format is now supported — re-run ' +
+                  'and it will be detected as a `registry` source.'
+                : '';
         throw new CustomMarketplaceError(
             `Custom marketplace selection from "${source}" resolved to zero installable modules ` +
             `— bmad-method's PluginResolver could not locate module.yaml/skills for any selected ` +
-            `plugin. Nothing would be installed; aborting before staging (FR238).`
+            `plugin. Nothing would be installed; aborting before staging (FR238).${directHint}`
         );
     }
 
@@ -392,17 +632,19 @@ function assertResolutionNonEmptyAndUniqueLeaves(resolvedByPlugin, { source = ''
  * @throws {CustomMarketplaceError} on a drifted surface, an unmatched selection, or a failed
  *   FR238 pre-flight check (see assertResolutionNonEmptyAndUniqueLeaves).
  */
-async function stageCustomMarketplaceSubset({ source, mode, rootDir, sourceUrl, plugins, selectedCodes, projectRoot }) {
-    projectRoot = path.resolve(projectRoot);
-
-    const resolvedByPlugin = await resolveSelectedPlugins({ mode, rootDir, sourceUrl, plugins, selectedCodes });
-    const allModules = assertResolutionNonEmptyAndUniqueLeaves(resolvedByPlugin, { source });
-
+/**
+ * Prepare a clean, empty stage directory under `projectRoot`. Safety pattern
+ * mirrors lib/bmad.js#stagePlugin (Story 22.6/22.8): never follow a pre-existing
+ * stage path that is a symlink, and wipe any stale stage from a prior failed run
+ * before copying fresh content. Shared by both the discovery/direct
+ * (`stageCustomMarketplaceSubset`) and registry (`stageRegistrySubset`) paths.
+ *
+ * @param {string} projectRoot - already-resolved absolute project root
+ * @returns {string} absolute stage path (created empty)
+ * @throws {CustomMarketplaceError}
+ */
+function prepareCleanStageDir(projectRoot) {
     const stagePath = path.join(projectRoot, CUSTOM_MARKETPLACE_STAGE_DIR_NAME);
-
-    // Safety pattern mirrors lib/bmad.js#stagePlugin (Story 22.6/22.8): never
-    // follow a pre-existing stage path that is a symlink, and wipe any stale
-    // stage from a prior failed run before copying fresh content.
     if (fs.existsSync(stagePath)) {
         const stageLstat = fs.lstatSync(stagePath);
         if (stageLstat.isSymbolicLink()) {
@@ -418,6 +660,16 @@ async function stageCustomMarketplaceSubset({ source, mode, rootDir, sourceUrl,
         }
     }
     fs.mkdirpSync(stagePath);
+    return stagePath;
+}
+
+async function stageCustomMarketplaceSubset({ source, mode, rootDir, sourceUrl, plugins, selectedCodes, projectRoot }) {
+    projectRoot = path.resolve(projectRoot);
+
+    const resolvedByPlugin = await resolveSelectedPlugins({ mode, rootDir, sourceUrl, plugins, selectedCodes });
+    const allModules = assertResolutionNonEmptyAndUniqueLeaves(resolvedByPlugin, { source, mode });
+
+    const stagePath = prepareCleanStageDir(projectRoot);
 
     // Copy every resolved file, preserving its path relative to rootDir, so
     // bmad-method's own re-resolution against the stage (a fresh 'local' type
@@ -459,6 +711,235 @@ async function stageCustomMarketplaceSubset({ source, mode, rootDir, sourceUrl,
     return { stagePath, customSourceArg, resolvedModules: allModules };
 }
 
+// ─── Registry-index mode — two-level stage + install ───────────────────────
+
+/**
+ * Resolve one selected registry entry into a staged rawPlugin + resolved
+ * modules. Two-level: clone the entry's `repository` (via bmad-method's own
+ * `resolveSource`/`cloneRepo` — ambient git creds, GIT_TERMINAL_PROMPT=0, no
+ * token handling — FR241), locate the module at `module_definition` (fallback:
+ * the repo root, i.e. PluginResolver over the whole clone), scan for skill
+ * directories, and resolve via `resolvePlugin`.
+ *
+ * A community entry is cloned at its `approved_tag` (the tag the registry
+ * publishes for the approved release — it points at `approved_sha`). We pin to
+ * the TAG rather than the raw SHA because bmad-method's `cloneRepo()` drives
+ * `git clone --branch <ref>` / `git fetch origin <ref>`, which accept a tag or
+ * branch but NOT a bare commit SHA. The `approved_sha` is still recorded on the
+ * persisted selection (see lib/bmad.js#installCustomMarketplaceSubset) as the
+ * immutable record of what the registry approved.
+ *
+ * @param {Object} plugin - a normalized registry entry (from enumerateCustomSource)
+ * @param {(input: string, opts: Object) => Promise<Object>} resolveSourceFn
+ * @param {(repoPath: string, rawPlugin: Object, url: string|null, local: string|null) => Promise<Array>} resolvePluginFn
+ * @returns {Promise<{ plugin: Object, rawPlugin: Object, resolved: Array<Object>, entryRootDir: string }>}
+ * @throws {CustomMarketplaceError}
+ */
+async function resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn) {
+    if (!plugin.repository) {
+        throw new CustomMarketplaceError(
+            `Registry entry '${plugin.code}' has no repository pointer — cannot install it.`
+        );
+    }
+
+    // Pin ref (tag/branch) via the `@<ref>` SOURCE-STRING SUFFIX that
+    // bmad-method's resolveSource() parses (custom-module-manager.js:
+    // "Extract optional @<tag-or-branch> suffix"). resolveSource has NO
+    // pinOverride/option for this — the ref MUST ride on the input string. A raw
+    // commit SHA is unsupported (`git clone --branch` can't take one), so we pin
+    // to `approved_tag` (the registry publishes it pointing at `approved_sha`);
+    // `approved_sha` is still recorded verbatim on the persisted selection.
+    const pinRef = plugin.approvedTag || null;
+    // The ref must match resolveSource's own ref rule (/^[\w.\-+/]+$/, no ':')
+    // or we omit it and clone the default branch rather than build a malformed
+    // source string.
+    const safePinRef = pinRef && /^[\w.\-+/]+$/.test(pinRef) && !pinRef.includes(':') ? pinRef : null;
+    const cloneInput = safePinRef ? `${plugin.repository}@${safePinRef}` : plugin.repository;
+    diag('custom-source: registry entry clone', {
+        code: plugin.code,
+        repository: plugin.repository,
+        pinRef: safePinRef,
+        approvedSha: plugin.approvedSha || null,
+        moduleDefinition: plugin.moduleDefinition || '(none — repo root)',
+    });
+
+    let resolvedSource;
+    try {
+        resolvedSource = await resolveSourceFn(cloneInput, {
+            skipInstall: true,
+            silent: true,
+        });
+    } catch (err) {
+        throw new CustomMarketplaceError(
+            `Could not clone registry entry '${plugin.code}' from "${plugin.repository}"` +
+            `${safePinRef ? ` @ ${safePinRef}` : ''}: ${err.message}`,
+            { cause: err }
+        );
+    }
+
+    const entryRootDir = resolvedSource.rootDir;
+    const entrySourceUrl = resolvedSource.sourceUrl || null;
+
+    // Locate the module within the clone. `module_definition` is a POSIX,
+    // repo-relative path to the module's module.yaml; its directory is the
+    // module root. Absent → fall back to the repo root (PluginResolver over the
+    // whole clone), matching the AC3 fallback.
+    let relModuleDirPosix = '.';
+    if (plugin.moduleDefinition) {
+        const defPosix = toPosix(plugin.moduleDefinition).replace(/^\.\//, '');
+        const moduleYamlAbs = path.join(entryRootDir, ...defPosix.split('/'));
+        if (!(await fs.pathExists(moduleYamlAbs))) {
+            throw new CustomMarketplaceError(
+                `Registry entry '${plugin.code}': module_definition "${plugin.moduleDefinition}" ` +
+                `was not found inside ${plugin.repository}. The registry pointer is stale or the ` +
+                `repository layout changed; aborting before staging (FR238).`
+            );
+        }
+        relModuleDirPosix = path.posix.dirname(defPosix);
+    }
+
+    const moduleBaseAbs =
+        relModuleDirPosix === '.' ? entryRootDir : path.join(entryRootDir, ...relModuleDirPosix.split('/'));
+    const skillNames = await scanSkillDirs(moduleBaseAbs);
+    const skillRelPaths = skillNames.map((n) => (relModuleDirPosix === '.' ? n : `${relModuleDirPosix}/${n}`));
+    diag('custom-source: registry entry resolved', {
+        code: plugin.code,
+        moduleDir: relModuleDirPosix,
+        skillDirsFound: skillNames.length,
+        skills: skillNames,
+    });
+
+    const rawPlugin = {
+        name: plugin.code,
+        description: plugin.description || '',
+        version: plugin.version || null,
+        source: relModuleDirPosix,
+        // Empty when the module dir has no SKILL.md subdirs — resolvePlugin then
+        // returns [] and the FR238 guard aborts cleanly (zero installable modules).
+        skills: skillRelPaths,
+    };
+
+    const localPath = entrySourceUrl ? null : entryRootDir;
+    const resolved = await resolvePluginFn(entryRootDir, rawPlugin, entrySourceUrl, localPath);
+
+    return { plugin, rawPlugin, resolved, entryRootDir };
+}
+
+/**
+ * Registry-mode counterpart of {@link stageCustomMarketplaceSubset}. For each
+ * selected registry entry it clones the entry's `repository`, resolves the
+ * pointed module, and stages the resolved content into the SAME project-local
+ * stage directory the discovery/direct path uses — but namespaced under the
+ * entry's `code/` so modules pulled from DIFFERENT repositories can never
+ * collide on a shared relative path. Enforces the same FR238 non-empty +
+ * unique-leaf guard, then returns the same `{ stagePath, customSourceArg,
+ * resolvedModules }` shape so lib/bmad.js#installCustomMarketplaceSubset installs
+ * it identically via `buildBmadArgs` + `--custom-source`.
+ *
+ * @param {Object} ctx
+ * @param {string} ctx.source - Original registry source string (messages only).
+ * @param {Array<Object>} ctx.plugins - Full enumerated registry entry list.
+ * @param {string[]} ctx.selectedCodes
+ * @param {string} ctx.projectRoot
+ * @param {Object} [ctx.deps] - Injectable seams (tests): { resolveSource, resolvePlugin }.
+ * @returns {Promise<{ stagePath: string, customSourceArg: string, resolvedModules: Array<Object> }>}
+ * @throws {CustomMarketplaceError}
+ */
+async function stageRegistrySubset({ source, plugins, selectedCodes, projectRoot, deps = {} }) {
+    projectRoot = path.resolve(projectRoot);
+    const { mgr } = assertCustomModuleManagerSurface();
+    const resolveSourceFn = deps.resolveSource || ((input, opts) => mgr.resolveSource(input, opts));
+    const resolvePluginFn =
+        deps.resolvePlugin || ((repoPath, rawPlugin, url, local) => mgr.resolvePlugin(repoPath, rawPlugin, url, local));
+
+    const selectedSet = new Set(selectedCodes);
+    const selected = (plugins || []).filter((p) => selectedSet.has(p.code));
+    if (selected.length === 0) {
+        throw new CustomMarketplaceError(
+            `None of the selected codes (${[...selectedSet].join(', ') || '(none)'}) matched a ` +
+            `registry entry — nothing to stage.`
+        );
+    }
+
+    // Each entry is staged under its own `code/` namespace, so two selected
+    // entries sharing a code would silently overwrite each other. enumerate
+    // de-dupes by `name`, but a malformed registry could give two differently-
+    // named entries the same `code` — reject that here rather than stage a
+    // corrupt subset (FR238 fail-clean).
+    const seenCodes = new Set();
+    for (const p of selected) {
+        if (seenCodes.has(p.code)) {
+            throw new CustomMarketplaceError(
+                `Two selected registry entries share the code '${p.code}' — codes must be unique ` +
+                `to install. Aborting before staging (FR238).`
+            );
+        }
+        seenCodes.add(p.code);
+    }
+
+    // Resolve every selected entry (each from its own clone) BEFORE touching the
+    // stage dir, so an unreachable/stale entry aborts clean with nothing staged.
+    const entries = [];
+    for (const plugin of selected) {
+        entries.push(await resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn));
+    }
+
+    const allModules = assertResolutionNonEmptyAndUniqueLeaves(
+        entries.map(({ plugin, rawPlugin, resolved }) => ({ plugin, rawPlugin, resolved })),
+        { source, mode: 'registry' }
+    );
+
+    const stagePath = prepareCleanStageDir(projectRoot);
+
+    // Copy each entry's resolved content under a `code/` namespace so entries
+    // cloned from different repos never overwrite each other, and rewrite the
+    // staged rawPlugin's skill/source paths to match that namespace so
+    // bmad-method's re-resolution against the stage reproduces the identical
+    // module (skills at code/<rel>, module.yaml at their common parent).
+    const stagedPlugins = [];
+    try {
+        for (const { plugin, resolved, entryRootDir } of entries) {
+            const prefix = plugin.code;
+            const relFromEntry = (absSrc) => toPosix(path.relative(entryRootDir, absSrc));
+            const copyUnderPrefix = (absSrc) => {
+                const dest = path.join(stagePath, prefix, ...relFromEntry(absSrc).split('/'));
+                fs.copySync(absSrc, dest, { overwrite: true, dereference: true });
+            };
+
+            const stagedSkills = [];
+            for (const mod of resolved) {
+                for (const skillPath of mod.skillPaths) {
+                    copyUnderPrefix(skillPath);
+                    stagedSkills.push(`${prefix}/${relFromEntry(skillPath)}`);
+                }
+                if (mod.moduleYamlPath) copyUnderPrefix(mod.moduleYamlPath);
+                if (mod.moduleHelpCsvPath) copyUnderPrefix(mod.moduleHelpCsvPath);
+            }
+
+            stagedPlugins.push({
+                name: plugin.code,
+                description: plugin.description || '',
+                version: plugin.version || null,
+                source: prefix,
+                skills: stagedSkills,
+            });
+        }
+    } catch (err) {
+        try { fs.removeSync(stagePath); } catch { /* swallow — primary error wins */ }
+        throw new CustomMarketplaceError(`Staging the registry subset failed: ${err.message}`, { cause: err });
+    }
+
+    const marketplaceDir = path.join(stagePath, '.claude-plugin');
+    fs.mkdirpSync(marketplaceDir);
+    fs.writeFileSync(
+        path.join(marketplaceDir, 'marketplace.json'),
+        JSON.stringify({ name: 'ma-agents-custom-registry-subset', plugins: stagedPlugins }, null, 2)
+    );
+
+    const customSourceArg = `./${CUSTOM_MARKETPLACE_STAGE_DIR_NAME}`;
+    return { stagePath, customSourceArg, resolvedModules: allModules };
+}
+
 // ─── Story 30.7 — persist + re-enumerate/reconcile on update ───────────────
 
 /**
@@ -499,9 +980,21 @@ module.exports = {
     // Story 30.6b — prune + stage the selected subset
     CUSTOM_MARKETPLACE_STAGE_DIR_NAME,
     scanDirectModeSkillDirs,
+    scanSkillDirs,
     resolveSelectedPlugins,
     assertResolutionNonEmptyAndUniqueLeaves,
     stageCustomMarketplaceSubset,
+    // Registry-index mode (this story)
+    REGISTRY_DIR_NAME,
+    REGISTRY_OFFICIAL_INDEX,
+    REGISTRY_COMMUNITY_INDEX,
+    registryTrustLabel,
+    detectRegistryLayout,
+    parseRegistryIndex,
+    normalizeRegistryEntry,
+    enumerateRegistrySource,
+    resolveRegistryEntry,
+    stageRegistrySubset,
     // Story 30.7 — persist + reconcile on update
     reconcileCustomMarketplaceSelection,
 };

package/lib/diag.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Log-file-only diagnostics.
+ *
+ * When `--log` is active, bin/cli.js#setupLogging installs a sink that writes
+ * to the log file descriptor. `diag()`/`diagError()` then emit structured
+ * breadcrumbs to the LOG FILE ONLY — never to the user's console (the wizard's
+ * user-facing output intentionally stays clean; e.g. a failed custom-marketplace
+ * source shows a one-line message, not a raw stack — NFR71). Without a sink
+ * (no `--log`), every call is a cheap no-op.
+ *
+ * This is how the swallowed root cause of a custom-marketplace failure (the
+ * git/clone/resolve error behind a clean CustomMarketplaceError, the per-entry
+ * module_definition that was missing, the FR238 zero-module trigger, etc.)
+ * reaches the log for post-hoc diagnosis without leaking to the terminal.
+ */
+
+let sink = null;
+
+/**
+ * @param {((text: string) => void)|null} fn - writer for log-file output, or null to disable.
+ */
+function setLogSink(fn) {
+  sink = typeof fn === 'function' ? fn : null;
+}
+
+/** @returns {boolean} whether diagnostics are being captured. */
+function isActive() {
+  return sink !== null;
+}
+
+function stamp() {
+  // new Date() is available in the CLI runtime (this is not a workflow script).
+  return new Date().toISOString();
+}
+
+function stringify(detail) {
+  if (typeof detail === 'string') return detail;
+  try {
+    return JSON.stringify(detail);
+  } catch {
+    return String(detail);
+  }
+}
+
+/**
+ * Emit one diagnostic breadcrumb to the log file (no-op without a sink).
+ * @param {string} label
+ * @param {*} [detail] - string or JSON-serializable value.
+ */
+function diag(label, detail) {
+  if (!sink) return;
+  let line = `[diag ${stamp()}] ${label}`;
+  if (detail !== undefined) line += `: ${stringify(detail)}`;
+  try {
+    sink(line + '\n');
+  } catch {
+    /* never let diagnostics break the install */
+  }
+}
+
+/**
+ * Emit an error — including its `stack` AND any wrapped `cause` (message +
+ * stack) — to the log file. This is the crucial bit for custom-marketplace
+ * failures, whose user-facing message deliberately hides the upstream cause.
+ * @param {string} label
+ * @param {Error|*} err
+ */
+function diagError(label, err) {
+  if (!sink || !err) return;
+  const parts = [`[diag ${stamp()}] ${label}: ${err.message || String(err)}`];
+  if (err.stack) parts.push(`  stack: ${err.stack}`);
+  if (err.cause) {
+    const c = err.cause;
+    parts.push(`  cause: ${(c && c.message) || String(c)}`);
+    if (c && c.stack) parts.push(`  cause.stack: ${c.stack}`);
+  }
+  try {
+    sink(parts.join('\n') + '\n');
+  } catch {
+    /* never let diagnostics break the install */
+  }
+}
+
+module.exports = { setLogSink, isActive, diag, diagError };

package/lib/profile.js

@@ -286,9 +286,11 @@ function markNoticeShown(projectRoot, noticeId) {
  *   {
  *     source: string,            // original user input (local path or Git URL)
  *     sourceUrl: string|null,    // resolved clone URL (Git sources) or null (local)
- *     mode: 'discovery'|'direct',
+ *     mode: 'discovery'|'direct'|'registry',
  *     selectedCodes: string[],
- *     sha: string|null,          // resolved commit SHA pin (Git-URL sources only)
+ *     sha: string|null,          // resolved commit SHA pin (Git-URL / registry sources)
+ *     entries?: Array<{ code: string, approvedSha: string|null, approvedTag: string|null }>,
+ *                                // registry-mode only: per-entry approved_sha/tag pins (AC5)
  *     updatedAt: string,         // ISO timestamp of the last persist
  *   }
  */
@@ -342,8 +344,8 @@ function setCustomMarketplaceSelection(projectRoot, entry) {
   if (typeof entry.source !== 'string' || !entry.source) {
     throw new Error('setCustomMarketplaceSelection requires a non-empty "source" string');
   }
-  if (entry.mode !== 'discovery' && entry.mode !== 'direct') {
-    throw new Error(`setCustomMarketplaceSelection requires mode 'discovery' or 'direct' (got ${JSON.stringify(entry.mode)})`);
+  if (entry.mode !== 'discovery' && entry.mode !== 'direct' && entry.mode !== 'registry') {
+    throw new Error(`setCustomMarketplaceSelection requires mode 'discovery', 'direct' or 'registry' (got ${JSON.stringify(entry.mode)})`);
   }
   if (!Array.isArray(entry.selectedCodes)) {
     throw new Error('setCustomMarketplaceSelection requires "selectedCodes" to be an array');
@@ -362,7 +364,7 @@ function setCustomMarketplaceSelection(projectRoot, entry) {
     manifest = bootstrapRootManifest();
   }
 
-  manifest.customMarketplace = {
+  const record = {
     source: entry.source,
     sourceUrl: entry.sourceUrl ?? null,
     mode: entry.mode,
@@ -370,6 +372,23 @@ function setCustomMarketplaceSelection(projectRoot, entry) {
     sha: entry.sha ?? null,
     updatedAt: new Date().toISOString(),
   };
+
+  // Registry-mode (this story): each selected entry pins its own commit via the
+  // registry's `approved_sha`. Record them per-entry so a later reconcile/update
+  // knows exactly what the registry approved at install time (AC5). Only
+  // persisted when the caller supplies a well-formed `entries` array — the
+  // discovery/direct path leaves this key absent (back-compat).
+  if (Array.isArray(entry.entries)) {
+    record.entries = entry.entries
+      .filter(e => e && typeof e === 'object' && typeof e.code === 'string' && e.code.length > 0)
+      .map(e => ({
+        code: e.code,
+        approvedSha: e.approvedSha ?? null,
+        approvedTag: e.approvedTag ?? null,
+      }));
+  }
+
+  manifest.customMarketplace = record;
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.17.0-beta.0",
+  "version": "3.17.0-beta.2",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bundle-filter-set-equality.test.js && node test/bmad-version-bump.test.js && node test/staging-6-10-0-regression.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/demerzel-ml-removal-drift.test.js && node test/demerzel-deprecation-notice.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js && node test/agent-injection-strategy.test.js && node test/bmad-module-selection.test.js && node test/custom-marketplace-surface-drift.test.js && node test/custom-marketplace-wizard.test.js && node test/custom-marketplace-live-clone.test.js && node test/custom-marketplace-stage-install.test.js && node test/custom-marketplace-persist-reconcile.test.js && node test/demerzel-nondestructive-invariant.test.js && node test/fr243-custom-source-allowlist-nonleak.test.js",
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bundle-filter-set-equality.test.js && node test/bmad-version-bump.test.js && node test/staging-6-10-0-regression.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/demerzel-ml-removal-drift.test.js && node test/demerzel-deprecation-notice.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js && node test/agent-injection-strategy.test.js && node test/bmad-module-selection.test.js && node test/custom-marketplace-surface-drift.test.js && node test/custom-marketplace-wizard.test.js && node test/custom-marketplace-live-clone.test.js && node test/custom-marketplace-stage-install.test.js && node test/custom-marketplace-persist-reconcile.test.js && node test/demerzel-nondestructive-invariant.test.js && node test/fr243-custom-source-allowlist-nonleak.test.js && node test/custom-marketplace-registry.test.js && node test/diag.test.js",
     "build:bmad-cache": "node scripts/build-bmad-cache.js",
     "build:plugin": "node scripts/build-plugin.js",
     "build:atlas": "node scripts/build-atlas.js",