release-skill 0.4.0 → 0.4.2

package/schemas/release-project.schema.json

@@ -191,6 +191,11 @@
                   "minLength": 1,
                   "pattern": "^[a-z0-9][a-z0-9._-]*$"
                 },
+                "marketplaceSource": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "消费者添加统一市场所用的来源 URL（如 codebuddy plugin marketplace add）；可选，仅在可知时声明"
+                },
                 "marketplaceRepo": {
                   "type": "string",
                   "pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$",

package/skills/release-setup/SKILL.md

@@ -91,6 +91,12 @@ node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>
 node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
 ```
 
+## publisher 字段与个人片段泄漏策略
+
+setup 生成的 `.release-skill/project.yaml` 中 `publisher` 是**已批准的公开发布身份**：它是人工确认的对外发布署名，属于公开面的一部分，而非需要隐藏的私有信息。
+
+若目标仓库用“个人片段”类泄漏策略扫描仓树，而该策略按片段匹配恰好覆盖到 `publisher` 字段，正确做法不是删除或改写策略，而是由贡献者在**本地、gitignore 的个人片段 overlay** 中为该规则声明位置豁免（如 `approvedPlacements`：限定 `publisher` 所在的确切文件路径与行键前缀）。豁免只放行已批准的放置位置，其余出现照常命中；overlay 不入库，个人片段本身不进 committed 策略。
+
 ## 故障路由
 
 - `NEEDS_INPUT`：审阅紧凑摘要；有冲突先修正权威事实并重跑。

package/skills-src/release-setup/SKILL.md

@@ -91,6 +91,12 @@ node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>
 node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
 ```
 
+## publisher 字段与个人片段泄漏策略
+
+setup 生成的 `.release-skill/project.yaml` 中 `publisher` 是**已批准的公开发布身份**：它是人工确认的对外发布署名，属于公开面的一部分，而非需要隐藏的私有信息。
+
+若目标仓库用“个人片段”类泄漏策略扫描仓树，而该策略按片段匹配恰好覆盖到 `publisher` 字段，正确做法不是删除或改写策略，而是由贡献者在**本地、gitignore 的个人片段 overlay** 中为该规则声明位置豁免（如 `approvedPlacements`：限定 `publisher` 所在的确切文件路径与行键前缀）。豁免只放行已批准的放置位置，其余出现照常命中；overlay 不入库，个人片段本身不进 committed 策略。
+
 ## 故障路由
 
 - `NEEDS_INPUT`：审阅紧凑摘要；有冲突先修正权威事实并重跑。

package/src/adapters/npm.mjs

@@ -257,6 +257,13 @@ async function readVerifiedTarballBytes(action, root) {
  * is missing, not valid JSON, or the extracted name/version do not match the
  * expected action values.
  *
+ * When the tarball contains a package/README.md entry (matched
+ * case-insensitively), its content is injected as manifest.readme and its
+ * real entry file name as manifest.readmeFilename, so the registry listing
+ * displays the package README. Ambiguous or unsafe README entries
+ * (duplicate or case-colliding names, non-regular files, out-of-bounds or
+ * oversized bodies) fail closed instead of being treated as metadata.
+ *
  * @param {Buffer} tarballBuffer - the raw tarball bytes (gzipped or plain tar)
  * @param {{ name: string, version: string }} expected - must match manifest
  * @returns {object} the parsed package.json manifest
@@ -275,6 +282,7 @@ function extractManifestFromTarball(tarballBuffer, expected) {
   // Walk tar entries to find package/package.json
   let offset = 0;
   let manifest = null;
+  let readme = null;
   while (offset + 512 <= data.length) {
     // Check for all-zero end-of-archive block
     let allZero = true;
@@ -330,6 +338,25 @@ function extractManifestFromTarball(tarballBuffer, expected) {
       }
     }
 
+    // Match package/README.md case-insensitively (npm registry metadata).
+    // The real entry file name is preserved in readmeFilename, and any
+    // duplicate, case-colliding, or non-regular README entry fails closed,
+    // mirroring the package/package.json checks above.
+    if (entryName.toLowerCase() === 'package/readme.md') {
+      if (readme) throw new Error('tarball contains conflicting package README entries');
+      if (!(typeFlag === 0 || typeFlag === 48 /* '0' */)) {
+        throw new Error('tarball package README must be a regular file');
+      }
+      const bodyStart = offset + 512;
+      const bodyEnd = bodyStart + size;
+      if (bodyEnd > data.length) throw new Error('frozen npm tarball entry exceeds archive bounds');
+      if (size > 10 * 1024 * 1024) throw new Error('tarball package README is unreasonably large');
+      readme = {
+        content: data.subarray(bodyStart, bodyEnd).toString('utf8'),
+        filename: entryName.slice('package/'.length),
+      };
+    }
+
     // Advance to next header: 512 header + ceil(size/512)*512 data
     const nextOffset = offset + 512 + Math.ceil(size / 512) * 512;
     if (!Number.isSafeInteger(nextOffset) || nextOffset > data.length) {
@@ -338,6 +365,10 @@ function extractManifestFromTarball(tarballBuffer, expected) {
     offset = nextOffset;
   }
   if (!manifest) throw new Error('tarball does not contain package/package.json');
+  if (readme) {
+    manifest.readme = readme.content;
+    manifest.readmeFilename = readme.filename;
+  }
   return manifest;
 }
 

package/src/adapters/plugin-marketplace.mjs

@@ -48,8 +48,8 @@ import {
 import {
   CODEBUDDY_REQUIREMENT_FILE,
   CODEBUDDY_ATTESTATION_FILE,
-  CODEBUDDY_MARKETPLACE_NAME,
-  CODEBUDDY_MARKETPLACE_SOURCE,
+  resolveCodeBuddyMarketplace,
+  resolveCodeBuddyMarketplaceSource,
   resolveCodeBuddyBoundPlanDigest,
   codebuddyAuthorityDir,
   validateCodeBuddyAttestation,
@@ -3095,15 +3095,19 @@ export function createPluginMarketplaceAdapter(deps = {}) {
             try {
               attestation = JSON.parse(await readFile(resolve(attestationDir, CODEBUDDY_ATTESTATION_FILE), 'utf8'));
             } catch {
+              // The marketplace source hint follows the frozen action's
+              // resolved marketplace; unknown configured marketplaces cite no
+              // fabricated URL.
+              const marketplaceSource = resolveCodeBuddyMarketplaceSource(action);
               return createResult({
                 actionType,
                 status: ActionStatus.OBSERVED,
                 observation: {
                   installed: false,
                   manualInstallRequired: true,
-                  marketplaceSource: CODEBUDDY_MARKETPLACE_SOURCE,
+                  ...(marketplaceSource ? { marketplaceSource } : {}),
                   attestationDir,
-                  error: `codebuddy attestation is missing; write ${resolve(attestationDir, CODEBUDDY_ATTESTATION_FILE)} after the manual install (marketplace ${CODEBUDDY_MARKETPLACE_SOURCE})`,
+                  error: `codebuddy attestation is missing; write ${resolve(attestationDir, CODEBUDDY_ATTESTATION_FILE)} after the manual install${marketplaceSource ? ` (marketplace ${marketplaceSource})` : ''}`,
                 },
               });
             }
@@ -3162,7 +3166,19 @@ export function createPluginMarketplaceAdapter(deps = {}) {
                 });
               }
               const normalizedPath = normalizedAttestation.installPath.replaceAll('\\', '/');
-              const expectedSuffix = `.workbuddy/plugins/marketplaces/${CODEBUDDY_MARKETPLACE_NAME}/plugins/${action.plugin}`;
+              // The expected suffix follows the frozen action's resolved
+              // marketplace (default constant for legacy plans).
+              let resolvedMarketplace;
+              try {
+                resolvedMarketplace = resolveCodeBuddyMarketplace(action);
+              } catch (resolveErr) {
+                return createResult({
+                  actionType,
+                  status: ActionStatus.OBSERVED,
+                  observation: { installed: false, error: resolveErr.message },
+                });
+              }
+              const expectedSuffix = `.workbuddy/plugins/marketplaces/${resolvedMarketplace}/plugins/${action.plugin}`;
               if (!normalizedPath.endsWith(expectedSuffix)) {
                 return createResult({
                   actionType,

package/src/commands/prepare.mjs

@@ -1289,19 +1289,17 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
       });
       // Consumer marketplace install actions (only when distribution
       // declared), driven by the platform registry (T2.2 step 3): one loop
-      // body for every platform; the registry declares the per-platform
-      // differences (actionType, distributionType, adapter, and — via the
-      // schema required fields — marketplace identity, which kimi does not
-      // carry: Kimi Code has no non-interactive install/marketplace API, so
-      // the kimi action carries no marketplace identity (MINOR-1); plugin +
-      // entrySkill are the meaningful identity fields there).
+      // body for every platform. Marketplace identity follows the distribution
+      // declaration: claude/codex require it via the registry schema fields;
+      // kimi/codebuddy tolerate an optional declaration (codebuddy defaults to
+      // its unified marketplace constant downstream when undeclared).
+      // Undeclared stays absent so legacy frozen plans remain byte-identical.
       const frozenUnitDists = frozenDistributions?.get(unit.id) ?? null;
       for (const platform of PLATFORMS) {
         const dist = frozenUnitDists
           ? frozenUnitDists.find((d) => d.type === platform.distributionType)
           : (unit.distributions ?? []).find((d) => d.type === platform.distributionType);
         if (!dist) continue;
-        const requiresMarketplace = platform.schemaRequiredFields.includes('marketplace');
         const timeoutMs = Number.isInteger(dist.timeoutMs) ? dist.timeoutMs : 300000;
         // External independent marketplace form: the distribution declares
         // marketplaceRepo, so the install targets the external marketplace repo
@@ -1350,7 +1348,8 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
           parameters: {
             consumer: platform.id,
             plugin: dist.plugin,
-            ...(requiresMarketplace ? { marketplace: dist.marketplace } : {}),
+            ...(dist.marketplace !== undefined ? { marketplace: dist.marketplace } : {}),
+            ...(dist.marketplaceSource !== undefined ? { marketplaceSource: dist.marketplaceSource } : {}),
             repo: externalMarketplace ? dist.marketplaceRepo : unit.publicRepo,
             version,
             entrySkill: dist.entrySkill,
@@ -1377,7 +1376,8 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
           expected: {
             installed: true,
             plugin: dist.plugin,
-            ...(requiresMarketplace ? { marketplace: dist.marketplace } : {}),
+            ...(dist.marketplace !== undefined ? { marketplace: dist.marketplace } : {}),
+            ...(dist.marketplaceSource !== undefined ? { marketplaceSource: dist.marketplaceSource } : {}),
             version,
             entrySkill: dist.entrySkill,
             ...(externalMarketplace ? { marketplaceLocation: 'external', repo: dist.marketplaceRepo } : {}),
@@ -1532,13 +1532,17 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
     // non-production loop above plus the production-only bindings
     // (ref/snapshotPath/manifestDigest parameters; consumer/repo/ref/
     // entrySkillFound/manifestDigest expected). Marketplace identity follows
-    // the registry's schema required fields — kimi carries none (MINOR-1).
+    // the distribution declaration, same as the non-production loop.
     for (const platform of PLATFORMS) {
       const dist = frozenUnitDists
         ? frozenUnitDists.find((d) => d.type === platform.distributionType)
         : (unit.distributions ?? []).find((d) => d.type === platform.distributionType);
       if (!dist) continue;
-      const requiresMarketplace = platform.schemaRequiredFields.includes('marketplace');
+      // Marketplace identity follows the distribution declaration: claude/codex
+      // require it via the registry schema fields; kimi/codebuddy tolerate an
+      // optional declaration (codebuddy defaults to its unified marketplace
+      // constant downstream when undeclared). Undeclared stays absent so
+      // legacy frozen plans remain byte-identical.
       const timeoutMs = Number.isInteger(dist.timeoutMs) ? dist.timeoutMs : 300000;
       // External independent marketplace form: the install targets the external
       // marketplace repo with the add-ref + marketplaceCommitSha frozen online
@@ -1583,7 +1587,8 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
         parameters: {
           consumer: platform.id,
           plugin: dist.plugin,
-          ...(requiresMarketplace ? { marketplace: dist.marketplace } : {}),
+          ...(dist.marketplace !== undefined ? { marketplace: dist.marketplace } : {}),
+          ...(dist.marketplaceSource !== undefined ? { marketplaceSource: dist.marketplaceSource } : {}),
           repo: externalMarketplace ? dist.marketplaceRepo : unit.publicRepo,
           ref: externalMarketplace ? freeze.ref : resolvedTag,
           version: unitVersion,
@@ -1622,7 +1627,8 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
           installed: true,
           consumer: platform.id,
           plugin: dist.plugin,
-          ...(requiresMarketplace ? { marketplace: dist.marketplace } : {}),
+          ...(dist.marketplace !== undefined ? { marketplace: dist.marketplace } : {}),
+          ...(dist.marketplaceSource !== undefined ? { marketplaceSource: dist.marketplaceSource } : {}),
           repo: externalMarketplace ? dist.marketplaceRepo : unit.publicRepo,
           version: unitVersion,
           ref: externalMarketplace ? freeze.ref : resolvedTag,

package/src/core/plan.mjs

@@ -751,9 +751,10 @@ export function validatePlanActionCompleteness(plan, options = {}) {
     // consumer id, and — via the schema required fields — whether marketplace
     // identity is a required binding). Platforms without a required
     // marketplace (kimi, MINOR-1: Kimi Code has an interactive marketplace
-    // but no non-interactive install API) tolerate a declared marketplace as
-    // an optional legacy value but never bind it as a required condition, in
-    // parameters or in expected.
+    // but no non-interactive install API; codebuddy, whose unified marketplace
+    // defaults to a constant but may be overridden by the distribution)
+    // tolerate a declared marketplace as an optional value but never bind it
+    // as a required condition, in parameters or in expected.
     for (const platform of PLATFORMS) {
       const dist = distributions.find((d) => d.type === platform.distributionType);
       if (!dist) continue;

package/src/platforms/codebuddy.mjs

@@ -88,15 +88,55 @@ export const CODEBUDDY_REQUIREMENT_FILE = 'release-skill-codebuddy-manual-instal
 export const CODEBUDDY_ATTESTATION_FILE = 'release-skill-codebuddy-attestation.json';
 
 /**
- * Unified marketplace the WorkBuddy desktop app and the codebuddy CLI install
- * release-skill from (verified fact). The attestation `marketplace` field must
- * equal this value; the install path is validated against this marketplace
- * segment in both channels.
+ * Default unified marketplace the WorkBuddy desktop app and the codebuddy CLI
+ * install from (verified fact). A distribution may override this by declaring
+ * `marketplace` (see resolveCodeBuddyMarketplace); the install path is
+ * validated against the resolved marketplace segment in both channels, and a
+ * declared attestation `marketplace` field must equal the resolved name.
  */
 export const CODEBUDDY_MARKETPLACE_NAME = 'artifact-skill-set';
-/** Marketplace source URL used by the isolated-CLI install path. */
+/** Default marketplace source URL (used only when no marketplace override is declared). */
 export const CODEBUDDY_MARKETPLACE_SOURCE = 'https://github.com/ifoohoo/artifact-skill-set';
 
+/**
+ * Resolve the unified marketplace name for a codebuddy action.
+ *
+ * Falls back to CODEBUDDY_MARKETPLACE_NAME when the action carries no
+ * `marketplace` (legacy frozen plans, byte-identical behavior). A declared
+ * marketplace must be a non-empty string; anything else fails closed.
+ *
+ * @param {object} [action] - expanded codebuddy action (may be undefined).
+ * @returns {string} the resolved marketplace name.
+ * @throws {Error} when a declared marketplace is not a non-empty string.
+ */
+export function resolveCodeBuddyMarketplace(action) {
+  const marketplace = action?.marketplace ?? CODEBUDDY_MARKETPLACE_NAME;
+  if (typeof marketplace !== 'string' || marketplace.length === 0) {
+    throw new Error(`codebuddy marketplace must be a non-empty string when declared, got ${JSON.stringify(action?.marketplace)}`);
+  }
+  return marketplace;
+}
+
+/**
+ * Resolve the marketplace source URL for a codebuddy action, when knowable.
+ *
+ * The default marketplace has a verified source constant; a configured
+ * marketplace only has a source when the distribution declared
+ * `marketplaceSource`. When neither applies, null is returned and callers
+ * must NOT fabricate a URL.
+ *
+ * @param {object} [action] - expanded codebuddy action (may be undefined).
+ * @returns {string|null} the source URL, or null when unknown.
+ */
+export function resolveCodeBuddyMarketplaceSource(action) {
+  if (action?.marketplace === undefined || action?.marketplace === null) {
+    return CODEBUDDY_MARKETPLACE_SOURCE;
+  }
+  return typeof action.marketplaceSource === 'string' && action.marketplaceSource.length > 0
+    ? action.marketplaceSource
+    : null;
+}
+
 /** Authoritative codebuddy plugin manifest (single candidate, no precedence). */
 export const CODEBUDDY_PLUGIN_MANIFEST_RELATIVE = join('.codebuddy-plugin', 'plugin.json');
 
@@ -185,7 +225,7 @@ export function codebuddyAuthorityDir(context, planDigest, plugin) {
 /**
  * 统一人工安装说明：面向 CodeBuddy / WorkBuddy 的人工结果流程。
  *
- * @param {{plugin:string, version:string, ref:string, attestationDir:string, requiresInstalledClosure:boolean}} p
+ * @param {{plugin:string, version:string, ref:string, attestationDir:string, requiresInstalledClosure:boolean, marketplace:string, marketplaceSource:string|null}} p
  * @returns {string[]}
  */
 function buildCodeBuddyManualInstructions({
@@ -194,11 +234,13 @@ function buildCodeBuddyManualInstructions({
   ref,
   attestationDir,
   requiresInstalledClosure,
+  marketplace,
+  marketplaceSource,
 }) {
   return [
     `CodeBuddy/WorkBuddy 插件安装无法锁定冻结 ref（codebuddy CLI marketplace add/install 没有 ref 选项，跟踪默认分支），因此安装是需要人工结果证明的手动步骤。`,
     `1) publish 完成所有远端写入后进入 PUBLISHED 状态（自动化 Git 分支/标签、npm 和 GitHub Release 写入已完成）。此 codebuddy 检查点标记为需要人工安装。`,
-    `2) 从统一市场 "${CODEBUDDY_MARKETPLACE_NAME}" (${CODEBUDDY_MARKETPLACE_SOURCE}) 安装 release-skill。确认安装的插件版本等于冻结版本 ${version}。`,
+    `2) 从统一市场 "${marketplace}"${marketplaceSource ? ` (${marketplaceSource})` : ''} 安装 ${plugin}。确认安装的插件版本等于冻结版本 ${version}。`,
     `3) 将人工结果 JSON 写入: ${attestationDir}/${CODEBUDDY_ATTESTATION_FILE}`,
     `   必填字段: platform="codebuddy", version, planDigest（冻结计划摘要）, result("passed" 或 "failed"), actor（确认人）, confirmedAt（ISO 8601 时间戳）${requiresInstalledClosure ? '，installChannel("desktop" 或 "cli")，installPath（实际安装后的插件目录）' : ''}`,
     `   可选字段: note（备注）`,
@@ -312,15 +354,35 @@ export function validateCodeBuddyAttestation(attestation, action, isoNow, boundP
     if (normalized.installPath.includes('..')) {
       return { valid: false, error: 'codebuddy attestation installPath must not contain path traversal ("..")', normalized: null };
     }
-    // CLI 通道：installPath 必须以预期后缀结尾
+    // CLI 通道：installPath 必须以预期后缀结尾（市场名解析自冻结动作，
+    // 未声明时回落到默认统一市场常量）
     if (normalized.installChannel === 'cli') {
-      const expectedSuffix = `.workbuddy/plugins/marketplaces/${CODEBUDDY_MARKETPLACE_NAME}/plugins/${action.plugin}`;
+      let resolvedMarketplace;
+      try {
+        resolvedMarketplace = resolveCodeBuddyMarketplace(action);
+      } catch (resolveErr) {
+        return { valid: false, error: resolveErr.message, normalized: null };
+      }
+      const expectedSuffix = `.workbuddy/plugins/marketplaces/${resolvedMarketplace}/plugins/${action.plugin}`;
       if (!normalized.installPath.endsWith(expectedSuffix)) {
         return { valid: false, error: `codebuddy CLI attestation installPath must end with "${expectedSuffix}", got "${normalized.installPath}"`, normalized: null };
       }
     }
   }
 
+  // 可选 marketplace 字段：一旦声明必须等于冻结动作解析出的市场名
+  if (normalized.marketplace !== undefined) {
+    let resolvedMarketplace;
+    try {
+      resolvedMarketplace = resolveCodeBuddyMarketplace(action);
+    } catch (resolveErr) {
+      return { valid: false, error: resolveErr.message, normalized: null };
+    }
+    if (normalized.marketplace !== resolvedMarketplace) {
+      return { valid: false, error: `codebuddy attestation marketplace "${normalized.marketplace}" does not match the resolved marketplace "${resolvedMarketplace}"`, normalized: null };
+    }
+  }
+
   // result 只接受 passed 或 failed
   if (normalized.result !== 'passed' && normalized.result !== 'failed') {
     return { valid: false, error: `codebuddy attestation result "${normalized.result}" must be "passed" or "failed"`, normalized: null };
@@ -454,6 +516,22 @@ export async function executeCodeBuddyManualRequirement(action, context) {
 
   const ref = action.ref ?? `v${action.version}`;
 
+  // Unified marketplace identity: resolved from the frozen action (declared
+  // `marketplace`/`marketplaceSource`), falling back to the default constants
+  // for legacy plans. A fabricated source URL is never emitted for a
+  // configured marketplace without a declared marketplaceSource.
+  let marketplace;
+  try {
+    marketplace = resolveCodeBuddyMarketplace(action);
+  } catch (marketplaceErr) {
+    return createResult({
+      actionType,
+      status: ActionStatus.EXECUTE_FAILED,
+      error: marketplaceErr.message,
+    });
+  }
+  const marketplaceSource = resolveCodeBuddyMarketplaceSource(action);
+
   // (B) Stable plugin-level authority dir, shared across
   // publish/reconcile/verify run dirs.
   let attestationDir;
@@ -473,6 +551,8 @@ export async function executeCodeBuddyManualRequirement(action, context) {
     ref,
     attestationDir,
     requiresInstalledClosure: Boolean(context.plan?.skillResourceClosure),
+    marketplace,
+    marketplaceSource,
   });
 
   // 统一 requirement 结构：不再包含隔离目录信息
@@ -484,6 +564,8 @@ export async function executeCodeBuddyManualRequirement(action, context) {
     repo: action.repo,
     ref,
     entrySkill: action.entrySkill,
+    marketplace,
+    ...(marketplaceSource ? { marketplaceSource } : {}),
     planDigest,
     attestationDir,
     attestationFile: CODEBUDDY_ATTESTATION_FILE,
@@ -497,7 +579,7 @@ export async function executeCodeBuddyManualRequirement(action, context) {
       ...(context.plan?.skillResourceClosure
         ? {
             installChannel: '<"desktop" or "cli">',
-            installPath: `<actual .workbuddy/plugins/marketplaces/${CODEBUDDY_MARKETPLACE_NAME}/plugins/${action.plugin} directory>`,
+            installPath: `<actual .workbuddy/plugins/marketplaces/${marketplace}/plugins/${action.plugin} directory>`,
           }
         : {}),
       note: '<optional note>',

package/src/platforms/registry.mjs

@@ -359,9 +359,10 @@ const CODEBUDDY = Object.freeze({
     marketplace: '.claude-plugin/marketplace.json',
   }),
   marketplaceSourceForm: null,
-  // codebuddy installs from a unified marketplace but carries no marketplace
-  // identity in the action (the marketplace is a fixed constant in
-  // ./codebuddy.mjs); the entry-version binding does not apply (null = N/A).
+  // codebuddy installs from a unified marketplace whose identity is optional
+  // on the action: a distribution may declare `marketplace` to override the
+  // default constant in ./codebuddy.mjs (resolveCodeBuddyMarketplace); the
+  // entry-version binding does not apply either way (null = N/A).
   marketplaceEntryCarriesVersion: null,
   // codebuddy has no marketplace add that can pin a frozen ref (attestation
   // loop instead), so the marketplace ref form does not apply (null = N/A).