@petercjl/cloud-hug-style-transfer 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 将旧详情页、产品摄影、主 KV 或 SKU 转换为抱抱云朵社品牌视觉，保留当次商品事实、文案与用途。包内包含完整 19 页定稿、品牌标识、人物设定与摄影排版方法，约 41 MB 素材。
 
-支持 Codex、SealSeek、WorkBuddy。需要 Node.js 22+、宿主命令执行和看图能力。生图统一通过必需的 `@petercjl/sealseek-media-cli`（0.6.1+）及其配套 `sealseek-media` Skill 执行；每次任务先检查，缺失或不兼容时暂停整个任务，安装并复查通过后继续。有效 SealSeek 登录、网络及额度由使用者准备，包不附带账号或额度。宿主生图效果仍需分别实测。
+支持 Codex、SealSeek、WorkBuddy。需要 Node.js 22+、宿主命令执行和看图能力。生图统一通过必需的 `@petercjl/sealseek-media-cli`（0.6.1+）及其配套 `sealseek-media` Skill 执行；每次业务任务先检查，缺失或不兼容时暂停整个任务，安装并复查通过后继续。有效 SealSeek 登录、网络及额度由使用者准备，包不附带账号或额度。宿主生图效果仍需分别实测。
 
 先安装生图依赖，将提示词发送给 Agent：
 
@@ -28,7 +28,7 @@
 
 > 请诊断并修复 cloud-hug-style-transfer 的这次报错：粘贴报错内容。
 
-安装、更新与检查由 Agent 执行包内 CLI。包的 `skill source --json` 提供规范来源；Agent 随后调用 `skill install --agent <当前宿主>`，支持 `--root` 指定实际技能目录。普通任务不联网检查或自动更新。显式更新使用 stable latest，备份旧包并同步已登记的受管 Skill，失败时恢复旧包；离线保留当前安装。已有独立安装或本地修改将停止覆盖并报告。源码或上层工具管理的包由其拥有者更新。
+安装、更新与检查由 Agent 执行包内 CLI。包的 `skill source --json` 提供规范来源；Agent 随后调用 `skill install --agent <当前宿主>`，支持 `--root` 指定实际技能目录。普通任务不联网检查或自动更新。显式更新使用 stable latest，备份旧包并同步已登记的受管 Skill；npm 已是最新版时仍修复旧 Skill 与兼容元数据，返回安装位置、来源、校验、备份和耗时。包升级失败时恢复旧包；离线保留当前安装。已有独立安装或本地修改将停止覆盖并报告。源码或上层工具管理的包由其拥有者更新。
 
 兼容证据分别记录安装机制与生图效果。CI 覆盖 macOS、Windows、Linux 的包管理机制；宿主实际生成需使用各自账户独立验证。品牌与输入素材须具备相应使用权；公开 npm 分发不转让商标与素材的独立再分发权。
 

package/capabilities.json

@@ -24,7 +24,7 @@
     "nested_skills": [
       "sealseek-media"
     ],
-    "generation": "Required @petercjl/sealseek-media-cli >=0.6.1 and its canonical sealseek-media Skill; missing or incompatible dependency pauses all tasks before analysis or planning.",
+    "generation": "Required for business planning and generation; maintenance is independent of media service dependencies.",
     "host_capability_skills": {
       "codex": [],
       "sealseek": [],
@@ -70,5 +70,249 @@
     "archive": "none during generation; explicit pair batch after each success",
     "planner": "canvas row --input JSON_FILE --json",
     "recovery": "same canvas/task/row IDs; inspect before replay"
+  },
+  "commandContracts": {
+    "version": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "capabilities": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "doctor": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill source": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill status": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill install": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "skill update": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "update check": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "update install": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        },
+        "--yes": {
+          "type": "boolean",
+          "required": true,
+          "description": "Authorize package and managed Skill reconciliation."
+        }
+      },
+      "sideEffects": "package-and-skill-update"
+    },
+    "canvas row": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--input": {
+          "type": "string",
+          "required": true,
+          "description": "Comparison input JSON file."
+        }
+      },
+      "sideEffects": "none"
+    }
+  },
+  "maintenance": {
+    "targetPrecedence": [
+      "explicit --root",
+      "host skills directory environment",
+      "Agent home/default"
+    ],
+    "codexSkillsEnvironment": "CODEX_SKILLS_DIR",
+    "defaultUpdateScope": "registered and current-host managed targets; explicit --agent selects one target",
+    "receipt": [
+      "package",
+      "version",
+      "source",
+      "entry",
+      "owner",
+      "packageChanged",
+      "skills",
+      "verified",
+      "backup",
+      "warnings",
+      "timingsMs"
+    ],
+    "sameVersion": "reconcile managed Skills and metadata; verified no-op when current",
+    "metadata": "preserve customization; remove known unsupported api product with backup; unknown invalid schema requires reconciliation"
   }
 }

package/npm/arguments.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { root, fail } from './runtime.mjs';
+export const manifest=JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
+export function parse(args) {
+ const tokens=[...args];
+ if(tokens[0]==='--version')tokens[0]='version';
+ if(tokens[0]==='help') {tokens.shift();tokens.push('--help');}
+ const words=[];while(tokens.length&&!tokens[0].startsWith('-'))words.push(tokens.shift());
+ const command=words.join(' '), contract=manifest.commandContracts[command];
+ if(!command&&(!tokens.length||tokens.every(x=>['--help','-h','--json'].includes(x))))return {command:'help',options:{}};
+ if(!contract)throw fail('INVALID_COMMAND','Unknown command; use --help.');
+ const options={};
+ while(tokens.length) {
+  let flag=tokens.shift();if(flag==='-h')flag='--help';
+  const spec=contract.options[flag];
+  if(!spec||flag in options)throw fail('INVALID_ARGUMENT',`Unknown or duplicate option ${flag}; use ${command} --help.`);
+  const value=spec.type==='boolean'?true:tokens.shift();
+  if(value===undefined || (spec.type==='string'&&value.startsWith('-')))throw fail('INVALID_ARGUMENT',`${flag} needs a value.`);
+  if(spec.enum&&!spec.enum.includes(value))throw fail('INVALID_AGENT',`Choose ${spec.enum.join(', ')}.`);
+  options[flag]=value;
+ }
+ if(!options['--help']) {
+  for(const [flag,spec]of Object.entries(contract.options))if(spec.required&&!options[flag])throw fail(flag==='--yes'?'PERMISSION_REQUIRED':'INVALID_ARGUMENT',`${command} requires ${flag}.`);
+  if(['doctor','update check','update install'].includes(command)&&options['--root']&&!options['--agent'])throw fail('INVALID_ARGUMENT','--root requires an explicit --agent for this command.');
+ }
+ return {command,options,contract};
+}

package/npm/cli.mjs

@@ -2,44 +2,38 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { root, pkg, fail } from './runtime.mjs';
-import { source, targetPath, status, install, inventory } from './skills.mjs';
-import { checkUpdate, installUpdate } from './update.mjs';
+import { source, resolveTarget, status, install, inventory, skillMetadata } from './skills.mjs';
+import { checkUpdate, installUpdate, globalPrefix } from './update.mjs';
 import { mediaDependency } from './media-dependency.mjs';
 import { comparisonRow } from './canvas-layout.mjs';
-const args=process.argv.slice(2);
-const option=name=>{const i=args.indexOf(name);if(i<0)return undefined;if(!args[i+1]||args[i+1].startsWith('--'))throw fail('INVALID_ARGUMENT',`${name} needs a value.`);return args[i+1];};
+import { parse, manifest } from './arguments.mjs';
+const started=performance.now();
 const out=value=>console.log(JSON.stringify(value,null,2));
 try {
- if(args[0]==='version'||args[0]==='--version') out({ok:true,name:pkg.name,version:pkg.version});
- else if(args[0]==='capabilities') out({...JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8')),version:pkg.version});
- else if(args[0]==='canvas'&&args[1]==='row') {
-  const input=option('--input');if(!input)throw fail('INVALID_ARGUMENT','canvas row requires --input JSON_FILE.');
-  out(comparisonRow(JSON.parse(fs.readFileSync(input,'utf8'))));
- }
- else if(args[0]==='skill') {
-  const action=args[1];
-  if(action==='source')out({ok:true,package:pkg.name,version:pkg.version,source});
-  else {
-   const target=targetPath(option('--agent')||'codex',option('--root'));
-   if(action==='status')out({...status(target),record:undefined});
-   else if(['install','update'].includes(action))out(install(target));
-   else throw fail('INVALID_COMMAND','Use skill source/status/install/update.');
-  }
- } else if(args[0]==='doctor') {
-  const files=inventory(source), expected=JSON.parse(fs.readFileSync(path.join(root,'npm','integrity.json'),'utf8'));
+ const {command,options:o,contract}=parse(process.argv.slice(2));
+ const identity={package:pkg.name,version:pkg.version,source,entry:{node:process.execPath,cli:path.join(root,'npm/cli.mjs')},owner:globalPrefix()?'global-npm':'source-or-parent'};
+ if(command==='help')out({ok:true,...identity,commands:manifest.commandContracts});
+ else if(o['--help'])out({ok:true,command,...contract});
+ else if(command==='version')out({ok:true,name:pkg.name,...identity});
+ else if(command==='capabilities')out({...manifest,...identity});
+ else if(command==='canvas row')out(comparisonRow(JSON.parse(fs.readFileSync(o['--input'],'utf8'))));
+ else if(command==='skill source')out({ok:true,...identity});
+ else if(command.startsWith('skill ')) {
+  const resolution=resolveTarget(o['--agent']||'codex',o['--root']);
+  const result=command==='skill status'?{ok:true,...status(resolution.target),record:undefined}:install(resolution.target);
+  out({...identity,...result,resolution});
+ } else if(command==='doctor') {
+  const files=inventory(source),expected=JSON.parse(fs.readFileSync(path.join(root,'npm/integrity.json'),'utf8'));
   const problems=Object.entries(expected).filter(([name,hash])=>files[name]!==hash).map(([name])=>name);
-  const capabilities=JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
-  const media=mediaDependency();
-  const result={ok:Number(process.versions.node.split('.')[0])>=22&&problems.length===0&&media.ok,package:pkg.name,version:pkg.version,node:process.versions.node,source,files:Object.keys(files).length,integrity:{ok:problems.length===0,problems},installationReady:problems.length===0,dependencies:{media},hostCapabilityDependencies:capabilities.requirements.host_capability_skills,generation:{provider:'@petercjl/sealseek-media-cli',state:media.ok?'requires-live-preflight':'paused',runtimeTested:false,requiredFeatures:['image-inspection','multiple-reference-edit','local-reference-input','viewable-output']}};
+  const media=mediaDependency();const metadata=skillMetadata(source);
+  const result={ok:Number(process.versions.node.split('.')[0])>=22&&!problems.length&&metadata.valid&&media.ok,...identity,node:process.versions.node,files:Object.keys(files).length,integrity:{ok:!problems.length,problems},metadata:{valid:metadata.valid},installationReady:!problems.length&&metadata.valid,dependencies:{media},hostCapabilityDependencies:manifest.requirements.host_capability_skills,generation:{provider:'@petercjl/sealseek-media-cli',state:media.ok?'requires-live-preflight':'paused',runtimeTested:false,requiredFeatures:['image-inspection','multiple-reference-edit','local-reference-input','viewable-output']}};
   if(!media.ok){result.code=media.code;result.action='pause';result.installPrompt=media.installPrompt;}
-  if(option('--agent'))result.installation={...status(targetPath(option('--agent'),option('--root'))),record:undefined};
-  out(result);if(!result.ok)process.exitCode=1;
- } else if(args[0]==='update') {
-  if(!['check','install'].includes(args[1]))throw fail('INVALID_COMMAND','Use update check/install.');
-  if(args[1]==='install'&&!args.includes('--yes'))throw fail('PERMISSION_REQUIRED','Package update requires --yes.');
-  const check=await checkUpdate();
-  if(args[1]==='check'){out(check);if(!check.ok)process.exitCode=1;}
-  else {if(!check.ok)throw fail(check.code,'Registry unavailable; installed version retained.');out(check.updateAvailable?installUpdate(check):{ok:true,changed:false,version:pkg.version});}
- } else if(!args.length||['--help','help','-h'].includes(args[0])) console.log('cloud-hug-style-transfer\nversion | capabilities --json | doctor --json [--agent AGENT]\ncanvas row --input JSON_FILE --json (read-only comparison layout)\nskill source/status/install/update [--agent codex|sealseek|workbuddy] [--root SKILLS_DIRECTORY]\nupdate check | update install --yes\nNode.js 22+. Updates are explicit; business calls never auto-update.');
- else throw fail('INVALID_COMMAND','Unknown command; use --help.');
-} catch(e){out({ok:false,code:e.code||'COMMAND_FAILED',message:e.message});process.exitCode=1;}
+  if(o['--agent']){result.resolution=resolveTarget(o['--agent'],o['--root']);result.installation={...status(result.resolution.target),record:undefined};if(!result.installation.current){result.ok=false;result.code||='SKILL_RECONCILIATION_REQUIRED';}}
+  out({...result,timingsMs:{total:performance.now()-started}});if(!result.ok)process.exitCode=1;
+ } else if(command.startsWith('update ')) {
+  const resolution=o['--agent']?resolveTarget(o['--agent'],o['--root']):undefined;
+  const registryStarted=performance.now();const check=await checkUpdate();const registryMs=performance.now()-registryStarted;
+  if(command==='update check'){out({...check,...identity,...(resolution?{resolution,installation:{...status(resolution.target),record:undefined}}:{}),timingsMs:{total:performance.now()-started}});if(!check.ok)process.exitCode=1;}
+  else {if(!check.ok)throw fail(check.code,'Registry unavailable; installed version retained.');const result=installUpdate(check,{resolution});out({...result,timingsMs:{...result.timingsMs,registry:registryMs,total:performance.now()-started}});}
+ }
+} catch(e){out({ok:false,code:e.code||'COMMAND_FAILED',message:e.message,...(e.causeCode?{causeCode:e.causeCode}:{}),...(e.backup?{backup:e.backup}:{}),...(e.details?{details:e.details}:{}),timingsMs:{total:performance.now()-started}});process.exitCode=1;}

package/npm/integrity.json

@@ -1,9 +1,9 @@
 {
-  "SKILL.md": "7d7e8c42e4ace458fc92ba9aa544fd9688047136ae991ef10bd1633264a7cdda",
+  "SKILL.md": "98df8d4271e525c687a1f0b3e877345bd42f3ca537515c0f84a9c0d58b17612b",
   "adapters/codex.json": "bea8d59e6e0dafae7439693b33356825023516a6f52be02a64c976d7ce47ce76",
   "adapters/sealseek.json": "04ef053762fd4cfc2309573ec87425afad14b2df85a1ea8ef0aa06d98fee1aee",
   "adapters/workbuddy.json": "cd0a1d8d5b9fcebc5a709b8c7523911f41973adb95f71af2c0f644473a43a6b4",
-  "agents/openai.yaml": "8afeabba706e83f2f20d616579e8d79b6509fe93427acdc2b650ef6387049983",
+  "agents/openai.yaml": "d8ebec24c4e3034f4b45aa052b9468ab35790ec7fd93febcfde512c746d2d1d1",
   "assets/approved/all-colors-user-finish.webp": "539c77de8ec0dd46a29793befecf813e97ce6ae66f7cbe69486846383b2ae936",
   "assets/approved/brand-kv-user-finish-20261012.png": "cb09198481e779444696864b265c689f467207bf7de9610f7adc2b850f0be7b4",
   "assets/approved/detail-final-20261016/01.jpg": "ecb481a422b3eadb0050b8c1080a1781e3fbd50ce4479f92e9f4a8beffd91187",
@@ -56,15 +56,17 @@
   "assets/rejected/overhead-rest-b.webp": "16e5e6fabdc665868ac244d556f3a8a93db826a34425fdee042e4f7a8ebf64c3",
   "assets/rejected/prone-pile-a.webp": "d07f38bbb69fc23b30dca4ed27faa3d7ae58e2e81840a1c3d46101911c28a7a2",
   "capabilities.json": "5d40595bf64402acf700cbaea63065d104547b12e59c275bca59cc9b4658de85",
-  "references/assets.md": "5675ee6b395caca641e8ce56e200cd4391ad67e7afceb44fc6732f253a126926",
-  "references/brand-layout.md": "5668190c1e618a903aa1b5e859405fa43a004da2082dc7040e83ef8cfc0aae86",
+  "references/assets.md": "98b1a60d70cbc9ceec3e0d11dadbc0dc96344ac6f15cd5289009dfbfd8d71d6e",
+  "references/brand-layout.md": "74f2674b7c9987e15a9d2ca7bb18498378eecc2d869d37e9ca1e71bd228ee883",
   "references/canvas-comparison.md": "df85594c92de3e87daa85ee7cd9cc92df4be9049a5d42c32904542faf329a6c7",
   "references/cases.md": "9d0d2d3d210e367411d5a291fc78ef6c9c733afd79c9da76451c580fcbcd4d3e",
-  "references/detail-final-20261016.md": "14acdc2f991b9db1c7d9ada32a35782603ac0aa310dcbe75f9693796a06cad83",
+  "references/detail-final-20261016.md": "d9311413420db743466bbecfe98c31b9753eeead905472d69839afec9578c557",
   "references/kv-layout-case-20261012.md": "845b287cfc57912aabedc48e558ca661cf86bf136304ea841030205a806ef06f",
+  "references/maintenance.md": "ccaa22cbe537885c7936d76b9091ef681491fd75d3791f6dbcf803d2337cee8e",
   "references/model-generation.json": "21daa2c3bf7d2000c7ddf52ab0b980cb7ee95d6c9d345602dc59ecbc128ec147",
   "references/model.md": "c4da688e22e2ada3f251fe0dc87effcaf5cb6ed6176f9d9c20a9661414bffab5",
-  "references/page-patterns.md": "3c126c75e9ccd5fc0b8860efcf2a0e27e9d3ba31e5cdeb407a0a683d8861a978",
-  "references/photography-method.md": "86ed457fc78112c1a2ad9bf9fdb9bcdf92aed71066bac2b3d4255159e3ee5c1c",
-  "references/products.md": "642795ae16803669b169531240723bf72a388cb6351679a2787e67e181dca9cd"
+  "references/page-patterns.md": "bdd6756e303c95e432d0239be27ec5af1faf75abf71594917f2e11467255a1b4",
+  "references/photography-method.md": "c0e54598863f3b4a2d87f27d6f18afb75db22ae71ce2aead41f817f35258807e",
+  "references/products.md": "642795ae16803669b169531240723bf72a388cb6351679a2787e67e181dca9cd",
+  "references/source-page-three-variants.md": "02a265cf11c3ff3bb7796eb289529ce97f6f64f0350a15a7e3275cec24037720"
 }

package/npm/metadata.mjs

@@ -0,0 +1,18 @@
+import { parseDocument } from 'yaml';
+import { fail } from './runtime.mjs';
+const allowed=new Set(['chatgpt','codex','atlas','CHATGPT','CODEX','ATLAS']);
+export function metadataPlan(text) {
+ const doc=parseDocument(text,{uniqueKeys:true});
+ if(doc.errors.length)throw fail('SKILL_METADATA_INVALID','Invalid agents/openai.yaml; preserve and repair the YAML before updating.');
+ const value=doc.toJS();
+ if(!value||typeof value!=='object'||Array.isArray(value))throw fail('SKILL_METADATA_INVALID','Skill metadata must be a mapping.');
+ if(value.interface!==undefined&&(!value.interface||typeof value.interface!=='object'||Array.isArray(value.interface)||Object.values(value.interface).some(v=>typeof v!=='string')))throw fail('SKILL_METADATA_INVALID','Skill interface values must be strings.');
+ if(value.policy!==undefined&&(!value.policy||typeof value.policy!=='object'||Array.isArray(value.policy)))throw fail('SKILL_METADATA_INVALID','Skill policy must be a mapping.');
+ const policy=value.policy;
+ if(policy?.allow_implicit_invocation!==undefined&&typeof policy.allow_implicit_invocation!=='boolean')throw fail('SKILL_METADATA_INVALID','allow_implicit_invocation must be boolean.');
+ const products=policy?.products;
+ if(products!==undefined&&(!Array.isArray(products)||products.some(p=>!allowed.has(p)&&p!=='api')))throw fail('SKILL_METADATA_INVALID','Unsupported policy.products; preserve and resolve the custom policy before updating.');
+ const changed=products?.includes('api')||false;
+ if(changed){const valid=products.filter(p=>p!=='api');if(!valid.length)throw fail('SKILL_METADATA_INVALID','Removing api would leave an empty custom product policy.');doc.setIn(['policy','products'],valid);}
+ return {valid:!changed,changed,text:changed?doc.toString():text,warnings:changed?['Removed unsupported legacy api product; custom interface and other policy fields preserved.']:[]};
+}

package/npm/pack.mjs

@@ -0,0 +1,8 @@
+import path from 'node:path';
+import { pkg, fail } from './runtime.mjs';
+export function packReceipt(text) {
+ let value;try{value=JSON.parse(text);}catch{throw fail('UPDATE_BACKUP_FAILED','npm pack did not return valid JSON.');}
+ const receipt=Array.isArray(value)&&value.length===1?value[0]:value?.[pkg.name];
+ if(!receipt||typeof receipt.filename!=='string'||!receipt.filename.endsWith('.tgz')||receipt.filename.includes('\\')||path.basename(receipt.filename)!==receipt.filename||(receipt.name&&receipt.name!==pkg.name))throw fail('UPDATE_BACKUP_FAILED','Invalid npm pack receipt.');
+ return receipt;
+}

package/npm/skills.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { metadataPlan } from './metadata.mjs';
 import { stateRoot } from './update.mjs';
 import { root, pkg, fail } from './runtime.mjs';
 
@@ -23,14 +24,19 @@ export function inventory(dir) {
   walk(dir);
   return result;
 }
-export function targetPath(agent, targetRoot) {
+export function resolveTarget(agent='codex', targetRoot) {
   if (!['codex', 'sealseek', 'workbuddy'].includes(agent)) throw fail('INVALID_AGENT', 'Choose --agent codex, sealseek or workbuddy.');
-  let base = targetRoot;
-  if (!base && agent === 'codex') base = path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills');
-  if (!base && agent === 'sealseek') base = process.env.SEALSEEK_SKILLS_DIR || path.join(os.homedir(), '.sealseek', 'workspaces', 'default', 'skills');
-  if (!base && agent === 'workbuddy') base = process.env.WORKBUDDY_SKILLS_DIR || path.join(os.homedir(), '.workbuddy', 'skills');
-  if (!base) throw fail('AGENT_PATH_REQUIRED', 'Provide the actual SealSeek skills directory through --root or SEALSEEK_SKILLS_DIR.');
-  return path.join(path.resolve(base), 'cloud-hug-style-transfer');
+  const envName={codex:'CODEX_SKILLS_DIR',sealseek:'SEALSEEK_SKILLS_DIR',workbuddy:'WORKBUDDY_SKILLS_DIR'}[agent];
+  const homeBase=agent==='codex' ? path.join(process.env.CODEX_HOME || path.join(os.homedir(),'.codex'),'skills') : agent==='sealseek' ? path.join(os.homedir(),'.sealseek','workspaces','default','skills') : path.join(os.homedir(),'.workbuddy','skills');
+  const candidates=[targetRoot&&{source:'--root',root:targetRoot},process.env[envName]&&{source:envName,root:process.env[envName]},{source:agent==='codex'&&process.env.CODEX_HOME?'CODEX_HOME':'agent-default',root:homeBase}].filter(Boolean).map(v=>({...v,root:path.resolve(v.root)}));
+  const selected=candidates[0];
+  return {agent,target:path.join(selected.root,'cloud-hug-style-transfer'),root:selected.root,resolvedFrom:selected.source,candidates,warnings:[...new Set(candidates.filter(c=>c.root!==selected.root).map(c=>`${selected.source} takes precedence over ${c.source}.`))]};
+}
+export const targetPath=(agent,targetRoot)=>resolveTarget(agent,targetRoot).target;
+export function skillMetadata(target) {
+  const file=path.join(target,metadata);
+  if(!exists(file))return {valid:false,changed:false,missing:true,warnings:['Skill UI metadata is missing.']};
+  return metadataPlan(fs.readFileSync(file,'utf8'));
 }
 export function status(target) {
   const st = exists(target);
@@ -43,18 +49,21 @@ export function status(target) {
   const files = inventory(target);
   const edited = Object.entries(record.files).some(([file, hash]) => file !== metadata && files[file] !== hash);
   const expected = inventory(source);
-  const current = !edited && Object.entries(expected).every(([file, hash]) => file === metadata || files[file] === hash);
-  return { installed: true, managed: true, current, edited, target, version: record.version, record };
+  const ui=skillMetadata(target);
+  const current = record.version === pkg.version && ui.valid && !edited && Object.entries(expected).every(([file, hash]) => file === metadata || files[file] === hash);
+  return { installed: true, managed: true, current, edited, target, version: record.version, metadata:{valid:ui.valid,migrationRequired:ui.changed,warnings:ui.warnings}, record };
 }
 export function install(target) {
-  const state = status(target);
+  const started=performance.now();
+  let state = status(target);
   if (state.installed && !state.managed) throw fail('SKILL_UNMANAGED', 'An existing user-owned Skill occupies this target; preserve it and choose a new root or explicitly migrate it.');
   if (state.edited) throw fail('SKILL_EDITED', 'Managed Skill files contain local edits; preserve and reconcile those edits before updating.');
   const registry = path.join(stateRoot(), 'skill-targets');
   fs.mkdirSync(registry, { recursive: true });
   const registration = path.join(registry, crypto.createHash('sha256').update(target).digest('hex') + '.json');
   if (!exists(registration)) fs.writeFileSync(registration, JSON.stringify({ target }), { flag: 'wx', mode: 0o600 });
-  if (state.current && state.version === pkg.version) return { ...state, record: undefined, ok: true, changed: false };
+  const receipt={package:pkg.name,source,owner:'package-managed',verified:true};
+  if (state.current && state.version === pkg.version) return { ...state, record: undefined, ...receipt, ok: true, changed: false, timingsMs:{total:performance.now()-started} };
   const expected = inventory(source);
   for (const file of Object.keys(expected)) {
     if (state.installed && exists(path.join(target, file)) && !(file in state.record.files) && file !== metadata) throw fail('SKILL_UNMANAGED_FILE', 'A new bundled file would overwrite a user-owned file.');
@@ -65,6 +74,11 @@ export function install(target) {
   try { lockfd = fs.openSync(lock, 'wx', 0o600); } catch (e) { if (e.code === 'EEXIST') throw fail('SKILL_BUSY', 'Another Skill installation holds the lock.'); throw e; }
   let backup;
   try {
+    state=status(target);
+    if(state.installed&&!state.managed)throw fail('SKILL_UNMANAGED','Target ownership changed while waiting for the lock.');
+    if(state.edited)throw fail('SKILL_EDITED','Target changed while waiting for the lock.');
+    for(const file of Object.keys(expected))if(state.installed&&exists(path.join(target,file))&&!(file in state.record.files)&&file!==metadata)throw fail('SKILL_UNMANAGED_FILE','Target file ownership changed before the lock.');
+    const ui=state.installed?skillMetadata(target):null;
     if (state.installed) {
       backup = path.join(stateRoot(), 'skill-backups', crypto.randomUUID());
       fs.mkdirSync(path.dirname(backup), { recursive: true });
@@ -72,7 +86,7 @@ export function install(target) {
     } else fs.mkdirSync(target);
     // In-place updates support hosts holding a directory handle open. Backup is recoverable.
     for (const file of Object.keys(expected)) {
-      if (file === metadata && exists(path.join(target, file))) continue;
+      if (file === metadata && exists(path.join(target, file))) { if(ui.changed)fs.writeFileSync(path.join(target,file),ui.text); continue; }
       fs.mkdirSync(path.dirname(path.join(target, file)), { recursive: true });
       fs.copyFileSync(path.join(source, file), path.join(target, file));
     }
@@ -81,9 +95,10 @@ export function install(target) {
     }
     const actual = inventory(target);
     if (Object.entries(expected).some(([file, hash]) => file !== metadata && actual[file] !== hash)) throw fail('SKILL_VERIFY_FAILED', 'Installed Skill hashes differ from the package.');
+    if(!skillMetadata(target).valid)throw fail('SKILL_VERIFY_FAILED','Skill UI metadata validation failed.');
     fs.writeFileSync(path.join(target, marker), JSON.stringify({ package: pkg.name, version: pkg.version, files: expected }, null, 2));
-    return { ok: true, installed: true, managed: true, current: true, changed: true, target, version: pkg.version, backup: backup || null };
+    return { ...receipt, metadata:{valid:true,migrated:ui?.changed||false}, warnings:ui?.warnings||[], timingsMs:{total:performance.now()-started}, ok: true, installed: true, managed: true, current: true, changed: true, target, version: pkg.version, backup: backup || null };
   } catch (e) {
-    throw fail('SKILL_INSTALL_FAILED', `Skill installation failed; ${backup ? 'restore from ' + backup : 'inspect the partial target at ' + target}.`);
+    throw Object.assign(fail('SKILL_INSTALL_FAILED', `Skill installation failed; ${backup ? 'restore from ' + backup : 'inspect the partial target at ' + target}.`),{causeCode:e.code,backup:backup||null,target});
   } finally { fs.closeSync(lockfd); fs.unlinkSync(lock); }
 }