@vibe-agent-toolkit/cli 0.2.0-rc.6 → 0.2.0-rc.8

package/dist/commands/claude/org/skills.js

@@ -6,7 +6,7 @@ import { basename } from 'node:path';
 import { API_SKILL_MAX_UPLOAD_BYTES, collectNonPortableAssetReferenceIssues, collectNonPortableCommandIssues, collectUnqualifiedMcpToolIssues, declaredSkillNameIn, describeOversizeBundle, evalSuiteUnitPath, formatBytes, NEVER_UPLOADED_DIR_NAMES, readDeclaredSkillName, } from '@vibe-agent-toolkit/agent-skills';
 import { ApiRequestError, ApiTransportError, buildMultipartFormData, skillVersionsPath, } from '@vibe-agent-toolkit/claude-marketplace';
 import { createAllowUsageLedger, runValidationFramework } from '@vibe-agent-toolkit/schema';
-import { isAbsoluteAnyPlatform, normalizedTmpdir, safePath, toForwardSlash, } from '@vibe-agent-toolkit/utils';
+import { direntKindFollowingSync, isAbsoluteAnyPlatform, isFilesystemAccessError, normalizedTmpdir, safePath, toForwardSlash, } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import { resolveSkillPackagingConfig } from '../../../skill-resolution/packaging-config.js';
 import { downloadNpmPackage } from '../plugin/helpers.js';
@@ -459,19 +459,23 @@ export function resolveSourceArgument(source) {
         : safePath.resolve(process.cwd(), source);
 }
 /**
- * The largest SKILL.md this will decompress to read a `name` out of.
+ * The largest single markdown member this will decompress to read.
  *
  * Not a limit on what may be PUBLISHED — the API's own ceiling decides that, and
- * a bigger document simply goes unread rather than refused. It bounds the one
- * allocation this module performs on attacker-supplied metadata: `getData()`
+ * a bigger document simply goes unread rather than refused. It bounds the
+ * allocations this module performs on attacker-supplied metadata: `getData()`
  * inflates whatever `header.size` claims, and a header can claim anything. A
- * megabyte is two orders of magnitude above any real SKILL.md.
+ * megabyte is two orders of magnitude above any real skill document.
+ *
+ * ⚠️ It is a PER-ENTRY bound. The total is bounded separately, and more
+ * tightly: nothing is inflated at all until the archive's declared uncompressed
+ * total is known to be within {@link API_SKILL_MAX_UPLOAD_BYTES}.
  */
-const MAX_INSPECTED_SKILL_MD_BYTES = 1024 * 1024;
+const MAX_INSPECTED_DOCUMENT_BYTES = 1024 * 1024;
 /**
  * What a ZIP will weigh AFTER the API expands it, read from the archive's own
- * central directory — plus the name its inner SKILL.md declares, and any answer
- * key it carries.
+ * central directory — plus the name its inner SKILL.md declares, any answer key
+ * it carries, and the markdown members the portability checks read.
  *
  * 🔑 **The API expands a ZIP and applies the ceiling to the UNCOMPRESSED total,
  * not to the archive.** Measured against the live API by an adopter: a
@@ -503,7 +507,7 @@ const MAX_INSPECTED_SKILL_MD_BYTES = 1024 * 1024;
  * caller's uncompressed-total gate, so the ceiling this function exists to
  * enforce could not protect the inflation this function performed. Nothing is
  * written to disk — that part stands — but the decompression is now ordered
- * after the total is known and bounded by {@link MAX_INSPECTED_SKILL_MD_BYTES},
+ * after the total is known and bounded by {@link MAX_INSPECTED_DOCUMENT_BYTES},
  * so an archive declaring a 4 GiB SKILL.md is enumerated and never inflated.
  */
 export async function inspectZipArchive(zipPath) {
@@ -517,11 +521,18 @@ export async function inspectZipArchive(zipPath) {
     try {
         entries = new AdmZip(zipPath).getEntries();
     }
-    catch {
-        // An archive VAT cannot parse is not an archive VAT should block. The API
+    catch (error) {
+        // An archive VAT cannot PARSE is not an archive VAT should block. The API
         // is the authority on the upload either way, and refusing here would turn
-        // "our reader disagrees with your zip tool" into a failed publish.
-        return undefined;
+        // "our reader disagrees with your zip tool" into a failed publish. The
+        // caller is told why, so "checks skipped" is never silent.
+        //
+        // An archive the FILESYSTEM refuses is a different thing: the path was
+        // readable a moment ago (the caller holds its bytes), so a refusal here
+        // is not a parse disagreement and stays loud.
+        if (isFilesystemAccessError(error))
+            throw error;
+        return { archiveUnreadable: describeZipFailure(error) };
     }
     // PASS 1 — headers only. Nothing is decompressed while this runs, so both
     // refusals the caller can reach are decided on metadata alone.
@@ -530,14 +541,97 @@ export async function inspectZipArchive(zipPath) {
     const neverUploaded = files
         .map(entry => toForwardSlash(entry.entryName))
         .filter(name => name.split('/').some(segment => NEVER_UPLOADED_DIR_NAMES.has(segment)));
-    // PASS 2 — the ONE entry worth inflating, and only once the total says this
+    // PASS 2 — the entries worth inflating, and only once the total says this
     // archive is not already refused. An over-ceiling archive is about to be
     // rejected by the caller, so inflating anything out of it would be work spent
     // on an upload that cannot happen.
-    const declaredName = uncompressedBytes > API_SKILL_MAX_UPLOAD_BYTES
-        ? undefined
-        : declaredNameOf(electShallowestSkillMd(files));
-    return { uncompressedBytes, declaredName, neverUploaded };
+    if (uncompressedBytes > API_SKILL_MAX_UPLOAD_BYTES) {
+        return {
+            uncompressedBytes, declaredName: undefined, neverUploaded, documents: [], bundleRoot: undefined, unreadable: [],
+        };
+    }
+    const elected = electShallowestSkillMd(files);
+    const unreadable = [];
+    return {
+        uncompressedBytes,
+        declaredName: declaredNameOf(elected, unreadable),
+        neverUploaded,
+        documents: inflateMarkdownMembers(files, unreadable),
+        bundleRoot: archiveRootOf(elected?.entryName),
+        unreadable,
+    };
+}
+/** adm-zip throws plain `Error`s; the message is all it has to say. */
+function describeZipFailure(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Every markdown member of the archive, as an upload part.
+ *
+ * 🔑 This exists so the ZIP lane can run the portability family through the ONE
+ * function the directory lane runs it through. Until it did, `install <zip>`
+ * performed none of the checks `install --help` promises of "every markdown
+ * document in the bundle": the archive went to `sendSkillUpload` as one opaque
+ * part, and an operator following the documented contract got silence where they
+ * were promised warnings. Routing the parts back through
+ * {@link warnUnportableReferences} keeps ONE implementation of the checks — a
+ * second copy of the three collector calls is how the two lanes start disagreeing.
+ *
+ * An entry that will not inflate is SKIPPED, never fatal: this module's standing
+ * position is that an archive VAT cannot read is not an archive VAT should block,
+ * and the checks it feeds only ever warn.
+ */
+function inflateMarkdownMembers(files, unreadable) {
+    const documents = [];
+    for (const entry of files) {
+        const filename = toForwardSlash(entry.entryName);
+        if (!filename.toLowerCase().endsWith('.md'))
+            continue;
+        if (entry.header.size > MAX_INSPECTED_DOCUMENT_BYTES)
+            continue;
+        const content = inflateOrRecord(entry, unreadable);
+        if (content !== undefined)
+            documents.push({ fieldName: 'files[]', filename, content });
+    }
+    return documents;
+}
+/**
+ * One member's bytes, or `undefined` with the refusal RECORDED.
+ *
+ * `getData()` is the only decompression in this module, so it is the only thing
+ * that can throw here: adm-zip raises on BAD_CRC, on any compression method but
+ * store/deflate, and on an encrypted entry. Those used to escape and abort the
+ * publish on exit 2 — contradicting this module's own stance that an archive VAT
+ * cannot parse is not an archive VAT should block — and then, once caught, were
+ * dropped without a word. The member is skipped AND named.
+ */
+function inflateOrRecord(entry, unreadable) {
+    try {
+        return entry.getData();
+    }
+    catch (error) {
+        // Once per member: the elected SKILL.md is asked for twice (its name, then
+        // its text), and one refusal is one fact.
+        const name = toForwardSlash(entry.entryName);
+        if (!unreadable.some((failure) => failure.entry === name)) {
+            unreadable.push({ entry: name, reason: describeZipFailure(error) });
+        }
+        return undefined;
+    }
+}
+/**
+ * The directory the elected SKILL.md sits in, which is the archive's bundle root.
+ *
+ * `my-skill/SKILL.md` roots the bundle at `my-skill`; a SKILL.md at the archive
+ * root has no prefix, and neither does an archive with no SKILL.md at all. ZIP
+ * fixes `/` as the entry separator, so this reads the format rather than handling
+ * a host path.
+ */
+function archiveRootOf(entryName) {
+    if (entryName === undefined)
+        return undefined;
+    const cut = toForwardSlash(entryName).lastIndexOf('/');
+    return cut === -1 ? undefined : entryName.slice(0, cut);
 }
 /**
  * The SKILL.md nearest the archive root, which is the one whose `name` the API
@@ -597,22 +691,15 @@ function zipEntryDepth(entryName) {
  * the root of their archive. The election decides; whatever it holds is the
  * answer, absence included.
  *
- * `getData()` is the only decompression in this module, so it is the only thing
- * that can throw here: adm-zip raises on BAD_CRC, on any compression method but
- * store/deflate, and on an encrypted entry. Those used to escape and abort the
- * publish on exit 2 — contradicting this module's own stance that an archive VAT
- * cannot parse is not an archive VAT should block. The size total is already
- * computed from headers, so failing here costs only the name.
+ * An elected SKILL.md that will not inflate costs only the name (the size total
+ * is already computed from headers) — see {@link inflateOrRecord}, which records
+ * the refusal so the operator learns why no name was read.
  */
-function declaredNameOf(entry) {
-    if (entry === undefined || entry.header.size > MAX_INSPECTED_SKILL_MD_BYTES)
-        return undefined;
-    try {
-        return declaredSkillNameIn(entry.getData().toString('utf8'));
-    }
-    catch {
+function declaredNameOf(entry, unreadable) {
+    if (entry === undefined || entry.header.size > MAX_INSPECTED_DOCUMENT_BYTES)
         return undefined;
-    }
+    const content = inflateOrRecord(entry, unreadable);
+    return content === undefined ? undefined : declaredSkillNameIn(content.toString('utf8'));
 }
 async function sendSkillUpload(client, displayTitle, files, bundleRoot) {
     const multipart = buildUploadBodyOrRefuse({ display_title: displayTitle }, files, bundleRoot);
@@ -650,7 +737,10 @@ function requireDeclaredName(skillMdPath) {
  * skill dir — nothing inside the tree to withhold.
  */
 async function declaredTestInputPaths(skillDir) {
-    const config = await resolveSkillPackagingConfig(safePath.join(skillDir, 'SKILL.md'));
+    // `'refuse'`: an upload that cannot tell which paths are test input might
+    // publish an answer key. The throw is reported per skill by the install
+    // loop's catch (logged, and counted in its failures) — never swallowed.
+    const config = await resolveSkillPackagingConfig(safePath.join(skillDir, 'SKILL.md'), 'refuse');
     const declared = config?.test?.evals;
     if (declared === undefined)
         return new Set();
@@ -675,7 +765,6 @@ function resolvesToDirectory(entry, fullPath, relativePath) {
     if (!entry.isSymbolicLink())
         return false;
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- collected from dir walk
         return statSync(fullPath).isDirectory();
     }
     catch (error) {
@@ -717,7 +806,6 @@ function resolvesToDirectory(entry, fullPath, relativePath) {
  * would have sent.
  */
 function collectFiles(dir, base, testInput, collected) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- dir from CLI arg
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         const fullPath = safePath.join(dir, entry.name);
         const relativePath = safePath.relative(base, fullPath);
@@ -767,7 +855,6 @@ export async function collectSkillUploadFiles(skillDir) {
  */
 async function prepareSkillUpload(skillDir, titleOverride, logger) {
     const skillMdPath = safePath.join(skillDir, 'SKILL.md');
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- derived from CLI arg
     if (!existsSync(skillMdPath)) {
         throw new Error(`SKILL.md not found in ${skillDir}. Is this a built skill directory?`);
     }
@@ -780,7 +867,6 @@ async function prepareSkillUpload(skillDir, titleOverride, logger) {
     const collected = await collectSkillUploadFiles(skillDir);
     const files = [];
     for (const file of collected.files) {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- collected from dir walk
         const content = readFileSync(file.absolutePath);
         files.push({
             fieldName: 'files[]',
@@ -805,7 +891,7 @@ async function prepareSkillUpload(skillDir, titleOverride, logger) {
     // Resolved HERE rather than plumbed out of `collectSkillUploadFiles`, which is
     // exported and deliberately resolves its own so no caller can hand it a config
     // with the exclusion skipped.
-    const packaging = await resolveSkillPackagingConfig(skillMdPath);
+    const packaging = await resolveSkillPackagingConfig(skillMdPath, 'refuse');
     warnUnportableReferences(files, dirName, packaging?.validation, logger);
     return { displayTitle, files, dirName };
 }
@@ -934,19 +1020,18 @@ async function uploadSkillVersionDir(client, skillId, skillDir, logger) {
  * any report said so.
  */
 export function listNodeModulePackages(nodeModulesDir) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from temp dir
     if (!existsSync(nodeModulesDir))
         return [];
     const results = [];
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from temp dir
+    // Followed: a workspace package under node_modules IS a symlink, and a walk
+    // that tested `isDirectory()` on the link skipped every one of them.
     for (const entry of readdirSync(nodeModulesDir, { withFileTypes: true })) {
-        if (!entry.isDirectory())
+        if (direntKindFollowingSync(nodeModulesDir, entry) !== 'directory')
             continue;
         if (entry.name.startsWith('@')) {
             const scopeDir = safePath.join(nodeModulesDir, entry.name);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from temp dir
             for (const scopedEntry of readdirSync(scopeDir, { withFileTypes: true })) {
-                if (scopedEntry.isDirectory())
+                if (direntKindFollowingSync(scopeDir, scopedEntry) === 'directory')
                     results.push(safePath.join(scopeDir, scopedEntry.name));
             }
         }
@@ -962,13 +1047,11 @@ export function listNodeModulePackages(nodeModulesDir) {
  */
 export function findSkillsDir(packageDir) {
     const direct = safePath.join(packageDir, 'dist', 'skills');
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from temp dir
     if (existsSync(direct))
         return direct;
     const candidates = listNodeModulePackages(safePath.join(packageDir, 'node_modules'));
     for (const pkgDir of candidates) {
         const candidate = safePath.join(pkgDir, 'dist', 'skills');
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from temp dir
         if (existsSync(candidate))
             return candidate;
     }
@@ -1012,9 +1095,9 @@ async function installFromNpm(npmPackage, skillFilter, client, logger) {
             throw new Error(`No dist/skills/ directory found in ${npmPackage}. Was the package built with vat skills build?`);
         }
         logger.info(`Found skills at: ${safePath.relative(packageDir, skillsDir) || 'dist/skills/'}`);
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructed from temp dir
+        // Followed: a built skill directory that is a link is still a skill to upload.
         const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
-            .filter(e => e.isDirectory())
+            .filter(e => direntKindFollowingSync(skillsDir, e) === 'directory')
             .map(e => e.name);
         if (skillDirs.length === 0) {
             throw new Error(`No skills found in dist/skills/ of ${npmPackage}`);
@@ -1051,11 +1134,9 @@ async function installFromNpm(npmPackage, skillFilter, client, logger) {
  */
 export async function installFromLocal(source, titleOverride, client, logger) {
     const sourcePath = resolveSourceArgument(source);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path from CLI arg
     if (!existsSync(sourcePath)) {
         throw new Error(`Source not found: ${sourcePath}`);
     }
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path from CLI arg
     const stat = statSync(sourcePath);
     // Case-INSENSITIVE. `endsWith('.zip')` refused `MySkill.ZIP` as "not a directory
     // or .zip file" — a file Windows and macOS both consider a zip archive, and one
@@ -1090,7 +1171,6 @@ async function installZipArchive(sourcePath, titleOverride, client, logger) {
     // `basename(path, ext)` matches the extension exactly, so the literal '.zip'
     // leaves `.ZIP` on the title. Slice the length instead.
     const displayTitle = titleOverride ?? basename(sourcePath).slice(0, -'.zip'.length);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path from CLI arg
     const zipContent = readFileSync(sourcePath);
     const files = [{
             fieldName: 'files[]',
@@ -1127,50 +1207,162 @@ async function installZipArchive(sourcePath, titleOverride, client, logger) {
         ? 'from the ZIP filename — NOT from the SKILL.md inside it; pass --title to set it'
         : 'from --title'})`);
     const inspected = await inspectZipArchive(sourcePath);
-    if (inspected !== undefined) {
-        // 🚨 REFUSED, not warned. The directory lane refuses an answer key
-        // unconditionally (`NEVER_UPLOADED_DIR_NAMES`, plus whatever the config
-        // declares), and until this existed the ZIP lane bypassed `collectFiles`
-        // entirely and posted the archive as one opaque part — so
-        // `zip -r my-skill.zip my-skill/` over a tree holding
-        // `my-skill/evals/evals.json` published the answer key org-wide with a
-        // green tick, while `install my-skill/` on the very same tree refused.
-        // Two lanes of one command must not disagree about whether a skill's
-        // answer key may be published, and a warning is a disagreement.
-        //
-        // This lane can only see the CONVENTIONAL names: there is no skill
-        // directory to walk up from, so a config-declared suite location is
-        // unreadable here. That is a narrower check than the directory lane's,
-        // not a looser verdict on what it does see.
-        if (inspected.neverUploaded.length > 0) {
-            throw new Error(`This ZIP contains ${String(inspected.neverUploaded.length)} entr`
-                + `${inspected.neverUploaded.length === 1 ? 'y' : 'ies'} that are never published with a `
-                + `skill: ${inspected.neverUploaded.slice(0, 10).join(', ')}`
-                + `${inspected.neverUploaded.length > 10 ? ', …' : ''}. An eval suite is the skill's ANSWER `
-                + `KEY and this would publish it to everyone in the organization. Rebuild the archive from `
-                + `the BUILT skill directory (\`vat skills build\`), or upload that directory directly — `
-                + `\`install <dir>\` withholds these and reports each one.`);
-        }
-        if (inspected.uncompressedBytes > API_SKILL_MAX_UPLOAD_BYTES) {
-            throw new Error(`ZIP expands to ${formatBytes(inspected.uncompressedBytes)}, over the `
-                + `${formatBytes(API_SKILL_MAX_UPLOAD_BYTES)} ceiling. The API expands the archive and `
-                + `weighs the UNCOMPRESSED total, so ${formatBytes(zipContent.length)} on the wire does not `
-                + `get this under the limit — it will refuse with "Zip file uncompressed size exceeds 30MB". `
-                + `Remove files from the bundle; compressing harder cannot help.`);
+    if ('archiveUnreadable' in inspected) {
+        // Degrade, and SAY so. Every check below is skipped, and a skipped check
+        // that is not announced is indistinguishable from one that passed.
+        logger.warn(`Could not read the archive (${inspected.archiveUnreadable}); the answer-key, expanded-size, `
+            + `name and portability checks were not run on it. The API decides the upload.`);
+    }
+    else {
+        refuseOrWarnOnArchive(inspected, displayTitle, zipContent.length, logger);
+    }
+    return sendSkillUpload(client, displayTitle, files);
+}
+/**
+ * The archive lane's own decisions, over what {@link inspectZipArchive} read:
+ * two refusals (answer key, expanded size), and the warnings the inspection
+ * earns (title/name divergence, portability, members it could not inflate).
+ */
+function refuseOrWarnOnArchive(inspected, displayTitle, wireBytes, logger) {
+    // 🚨 REFUSED, not warned. The directory lane refuses an answer key
+    // unconditionally (`NEVER_UPLOADED_DIR_NAMES`, plus whatever the config
+    // declares), and until this existed the ZIP lane bypassed `collectFiles`
+    // entirely and posted the archive as one opaque part — so
+    // `zip -r my-skill.zip my-skill/` over a tree holding
+    // `my-skill/evals/evals.json` published the answer key org-wide with a
+    // green tick, while `install my-skill/` on the very same tree refused.
+    // Two lanes of one command must not disagree about whether a skill's
+    // answer key may be published, and a warning is a disagreement.
+    //
+    // This lane can only see the CONVENTIONAL names: there is no skill
+    // directory to walk up from, so a config-declared suite location is
+    // unreadable here. That is a narrower check than the directory lane's,
+    // not a looser verdict on what it does see.
+    if (inspected.neverUploaded.length > 0) {
+        throw new Error(`This ZIP contains ${String(inspected.neverUploaded.length)} entr`
+            + `${inspected.neverUploaded.length === 1 ? 'y' : 'ies'} that are never published with a `
+            + `skill: ${inspected.neverUploaded.slice(0, 10).join(', ')}`
+            + `${inspected.neverUploaded.length > 10 ? ', …' : ''}. An eval suite is the skill's ANSWER `
+            + `KEY and this would publish it to everyone in the organization. Rebuild the archive from `
+            + `the BUILT skill directory (\`vat skills build\`), or upload that directory directly — `
+            + `\`install <dir>\` withholds these and reports each one.`);
+    }
+    if (inspected.uncompressedBytes > API_SKILL_MAX_UPLOAD_BYTES) {
+        throw new Error(`ZIP expands to ${formatBytes(inspected.uncompressedBytes)}, over the `
+            + `${formatBytes(API_SKILL_MAX_UPLOAD_BYTES)} ceiling. The API expands the archive and `
+            + `weighs the UNCOMPRESSED total, so ${formatBytes(wireBytes)} on the wire does not `
+            + `get this under the limit — it will refuse with "Zip file uncompressed size exceeds 30MB". `
+            + `Remove files from the bundle; compressing harder cannot help.`);
+    }
+    // The title/name divergence this branch discloses above, now stated as a
+    // FACT rather than as a caveat, because the archive can be read after
+    // all. A ZIP whose inner SKILL.md declares a different name publishes a
+    // skill whose title and versions disagree — and that divergence is what
+    // makes a title-keyed lookup unsafe, so it is worth naming at the moment
+    // it is minted rather than diagnosing later.
+    if (inspected.declaredName !== undefined && inspected.declaredName !== displayTitle) {
+        logger.warn(`Title/name divergence: this uploads with display title "${displayTitle}", but the `
+            + `SKILL.md inside declares name "${inspected.declaredName}". Every version will carry `
+            + `the declared name. Pass --title "${inspected.declaredName}" to make them agree.`);
+    }
+    // 🚨 The SAME function the directory lane calls, over the archive's own
+    // markdown. Until this line existed, `install <zip>` ran NONE of the
+    // portability checks its `--help` promises of "every markdown document in
+    // the bundle" — the archive went straight to `sendSkillUpload`, so the
+    // adopter finding that produced the family (10 of 54 skills referencing a
+    // path outside their own tree, published green and unable to run) was
+    // invisible on the lane most likely to carry a hand-built bundle.
+    //
+    // ⚠️ NO validation config, and that is a real narrowing, stated in the
+    // help text. `validation.allow` / `validation.severity` are resolved by
+    // walking up from a skill's SKILL.md to its governing project — and an
+    // archive member has no path on disk to walk up from, the same reason a
+    // config-declared eval-suite location is unreadable here. So a waiver that
+    // silences `vat skills build` does NOT silence this lane. The checks only
+    // warn, so the cost of the narrowing is noise, never a blocked publish;
+    // the cost of skipping them was silence on a documented promise.
+    warnUnportableReferences(inspected.documents, inspected.bundleRoot, undefined, logger);
+    if (inspected.unreadable.length > 0) {
+        const named = inspected.unreadable.map(({ entry, reason }) => `${entry} (${reason})`).join(', ');
+        logger.warn(`${String(inspected.unreadable.length)} archive member(s) could not be inflated and were `
+            + `not checked: ${named}`);
+    }
+}
+/**
+ * Delete every version handed in, and keep going when one refuses.
+ *
+ * 🚨 **One refusal is a fact about ONE version.** This loop used to return on the
+ * first one, so every version after it was never ATTEMPTED — not failed, not
+ * reported, unexamined. Deleting a workspace skill requires deleting every
+ * version first, so the operator was left with a skill that could not be deleted,
+ * a report that named one problem out of an unknown number, and no way to tell
+ * from the output which versions were still there. A transient refusal on version
+ * 2 of 30 hid the state of the other 28.
+ *
+ * The sweep therefore ATTEMPTS all of them and reports both lists. The caller
+ * decides what the outcome means: some deleted plus some failed is a run that
+ * happened and went wrong (exit 1, with the record); nothing deleted at all is
+ * the ending the command's help documents as exit 2.
+ *
+ * ⛔ It deliberately does NOT stop early on a repeated failure. A "the API is
+ * clearly down, give up" heuristic is how the abandoned-versions defect reads
+ * from inside: the whole value here is that every version's state is KNOWN when
+ * the command ends.
+ */
+export async function deleteEveryVersion(client, skillId, versions, logger) {
+    const deleted = [];
+    const failures = [];
+    for (const version of versions) {
+        try {
+            await client.deleteSkillVersion(skillId, version);
         }
-        // The title/name divergence this branch discloses above, now stated as a
-        // FACT rather than as a caveat, because the archive can be read after
-        // all. A ZIP whose inner SKILL.md declares a different name publishes a
-        // skill whose title and versions disagree — and that divergence is what
-        // makes a title-keyed lookup unsafe, so it is worth naming at the moment
-        // it is minted rather than diagnosing later.
-        if (inspected.declaredName !== undefined && inspected.declaredName !== displayTitle) {
-            logger.warn(`Title/name divergence: this uploads with display title "${displayTitle}", but the `
-                + `SKILL.md inside declares name "${inspected.declaredName}". Every version will carry `
-                + `the declared name. Pass --title "${inspected.declaredName}" to make them agree.`);
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            failures.push({ version, reason });
+            logger.info(`   ⚠ version ${version} was not deleted: ${reason}`);
+            continue;
         }
+        deleted.push(version);
+        logger.info(`   Deleted version ${version}`);
     }
-    return sendSkillUpload(client, displayTitle, files);
+    return { deleted, failures };
+}
+/**
+ * Every version the sweep could not delete, and why — the one sentence both the
+ * published report and the exit-2 throw are built from, so the two endings never
+ * describe the same run differently.
+ */
+export function describeVersionSweepFailures(failures) {
+    return failures.map(failure => `${failure.version}: ${failure.reason}`).join('; ');
+}
+/**
+ * The document a `--all` run publishes when it destroyed something and then did
+ * not finish.
+ *
+ * 🔑 The deleted list is a RECORD, not a progress counter. Version deletion is
+ * irreversible, so a failure part-way through leaves a workspace nobody can
+ * reconstruct — and throwing here would end on `handleCommandError`'s exit 2
+ * ("the run could not happen") and DISCARD the document. It happened, and it
+ * destroyed things the operator now has no other list of. So the lists travel
+ * with the failure and the run ends 1: it happened, and its outcome is wrong.
+ *
+ * `failedVersions` is the other half, and the half a re-run needs: what is still
+ * there. Without it the operator knows what they lost and not what they still
+ * have to deal with.
+ */
+export function reportHalfDeleted(report) {
+    const { skillId, deletedVersions, failedVersions } = report;
+    return orgCommandFailure({
+        id: skillId,
+        deleted: false,
+        deletedVersions,
+        failedVersions,
+        error: report.error,
+        note: `${String(deletedVersions.length)} version(s) of ${skillId} were deleted and cannot be `
+            + `restored; ${String(failedVersions.length)} could not be deleted and are still there. `
+            + 'The skill itself still exists — the API refuses a skill that still has versions. '
+            + 'Re-run `--all` once the cause is cleared: it will attempt only what is left.',
+    });
 }
 // ── Commands ───────────────────────────────────────────────────────────
 export function createOrgSkillsCommand() {
@@ -1279,9 +1471,16 @@ Description:
   the non-portable reference, non-portable command, and unqualified MCP tool-name
   checks — the ones that catch a skill referencing a path outside its own tree,
   which cannot resolve once the API publishes it alone. These WARN and never
-  block, and \`validation.allow\` / \`validation.severity\` from the governing
-  config are honoured, so a waiver that makes \`vat skills build\` green makes
-  this quiet too. Run \`vat audit <dir>\` for the full report.
+  block. Run \`vat audit <dir>\` for the full report.
+
+  A ZIP faces the same three checks: its markdown members are read out of the
+  archive and run through them, so a hand-built bundle is not the quiet lane.
+  The one difference is the config. On a DIRECTORY, \`validation.allow\` /
+  \`validation.severity\` from the governing vibe-agent-toolkit.config.yaml are
+  honoured, so a waiver that makes \`vat skills build\` green makes this quiet
+  too. On a ZIP there is no directory to resolve that config from — the same
+  reason a config-declared eval-suite location is invisible here — so the checks
+  run UNWAIVED and a warning you have already waived elsewhere will still print.
 
   There are TWO size gates and a ZIP faces both. The REQUEST gate weighs the
   multipart body — file bytes plus about 156 bytes of framing per file — against
@@ -1325,14 +1524,11 @@ Examples:
             // travels with the failure, and the run ends 1: it happened, and its
             // outcome is wrong.
             const deletedVersions = [];
-            const halfDeleted = (error) => orgCommandFailure({
-                id: skillId,
-                deleted: false,
+            const halfDeleted = (error, failedVersions) => reportHalfDeleted({
+                skillId,
                 deletedVersions,
+                failedVersions,
                 error: error instanceof Error ? error.message : String(error),
-                note: `${String(deletedVersions.length)} version(s) of ${skillId} were deleted before this `
-                    + 'failed and cannot be restored. The skill itself still exists. Re-run '
-                    + '`--all` once the cause is cleared; the versions listed here are already gone.',
             });
             if (options.all) {
                 const versions = await autopaginateSkills(client, skillVersionsPath(skillId));
@@ -1340,21 +1536,25 @@ Examples:
                 // "Found …", not "Deleting …": nothing has been deleted at this point
                 // and the very next call can be refused. Cf. `installFromLocal`.
                 logger.info(`Found ${String(versionData.length)} version(s) of ${skillId} to delete first`);
-                for (const ver of versionData) {
-                    try {
-                        await client.deleteSkillVersion(skillId, ver.version);
+                // ATTEMPTS every version, whatever any one of them answers. See
+                // `deleteEveryVersion`: returning on the first refusal left the rest
+                // unexamined, and the skill undeletable with no record of what remained.
+                const sweep = await deleteEveryVersion(client, skillId, versionData.map(v => v.version), logger);
+                deletedVersions.push(...sweep.deleted);
+                if (sweep.failures.length > 0) {
+                    const detail = describeVersionSweepFailures(sweep.failures);
+                    // Nothing was destroyed, so there is no record worth publishing and
+                    // "could not happen" (exit 2, via the throw) is the honest ending —
+                    // the same rule as before, now decided on the WHOLE sweep rather than
+                    // on its first refusal.
+                    if (deletedVersions.length === 0) {
+                        throw new Error(`No version of ${skillId} could be deleted, so the skill was left alone. `
+                            + `${String(sweep.failures.length)} attempt(s) failed — ${detail}`);
                     }
-                    catch (error) {
-                        // Only after at least one version is gone is there a report worth
-                        // publishing. Before that nothing happened, and "could not happen"
-                        // (exit 2, via the throw) is the honest ending.
-                        if (deletedVersions.length === 0)
-                            throw error;
-                        logger.info(`   ⚠ version ${ver.version} was not deleted`);
-                        return halfDeleted(error);
-                    }
-                    deletedVersions.push(ver.version);
-                    logger.info(`   Deleted version ${ver.version}`);
+                    // The skill delete is not attempted: the API refuses a skill that still
+                    // has versions, so it would spend a round trip to be told what is
+                    // already known here.
+                    return halfDeleted(new Error(detail), sweep.failures.map(failure => failure.version));
                 }
             }
             logger.info(`Deleting skill: ${skillId}`);
@@ -1369,7 +1569,9 @@ Examples:
             catch (error) {
                 if (deletedVersions.length === 0)
                     throw error;
-                return halfDeleted(error);
+                // The sweep completed — every version is gone — and the SKILL delete is
+                // what failed, so nothing is left in `failedVersions`.
+                return halfDeleted(error, []);
             }
             const deleted = reportDelete(raw, skillId, SKILL_DELETED_TYPES);
             return deletedVersions.length === 0
@@ -1389,16 +1591,24 @@ Description:
   delete every version and then the skill in one command; without it, delete the
   versions yourself with \`vat claude org skills versions delete\` first.
 
-  --all deletes irreversibly and in a loop. If it fails part-way through, the
-  versions it already destroyed are listed under deletedVersions in the output
-  and the run exits 1 — the run happened, and its outcome is wrong. It exits 2
-  only when nothing was deleted at all.
+  --all deletes irreversibly and in a loop, and it ATTEMPTS EVERY VERSION even
+  when one refuses — one refusal is a fact about one version, not about the ones
+  after it. When the sweep ends with anything left, the versions it destroyed are
+  listed under deletedVersions, the ones still there under failedVersions, and
+  the run exits 1 — the run happened, and its outcome is wrong. The skill itself
+  is then left alone, because the API refuses a skill that still has versions.
+  It exits 2 only when nothing was deleted at all.
+
+  A version delete whose response is lost is replayed, and the replay is answered
+  404 because the first attempt already removed it. That 404 is read as the
+  delete it is, not as a failure — the version appears under deletedVersions.
 
 Exit Codes:
   0 - The skill was deleted
   1 - The run completed and the skill was NOT deleted: the API named a different
-      outcome, or --all destroyed some versions and then failed
-  2 - The run could not happen: no API key, or the first request was refused
+      outcome, or --all destroyed some versions and could not destroy the rest
+  2 - The run could not happen: no API key, the first request was refused, or
+      --all deleted no version at all
 
 Example:
   $ vat claude org skills delete skill_abc123 --all
@@ -1470,10 +1680,8 @@ Example:
         .action(async (skillId, source, options) => {
         await executeOrgCommand('OrgSkillsVersionsAdd', options.debug, async ({ client, logger }) => {
             const resolved = resolveSourceArgument(source);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- path from CLI arg
             if (!existsSync(resolved))
                 throw new Error(`Source not found: ${resolved}`);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- path from CLI arg
             if (!statSync(resolved).isDirectory()) {
                 // Name the asymmetry IN the refusal, not only in --help. `install`
                 // accepts a ZIP and this verb does not, so the operator most likely to