@vibe-agent-toolkit/cli 0.2.0-rc.10 → 0.2.0-rc.12

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

@@ -1,14 +1,18 @@
 /**
  * `vat claude org skills` — manage organization skills via Skills API.
  */
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
 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 { API_SKILL_MAX_UPLOAD_BYTES, collectNonPortableAssetReferenceIssues, collectNonPortableCommandIssues, collectUnqualifiedMcpToolIssues, declaredSkillNameIn, describeOversizeBundle, evalSuiteUnitPath, formatBytes, hostAddedToSkillZip, 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 { direntKindFollowingSync, isAbsoluteAnyPlatform, isFilesystemAccessError, normalizedTmpdir, safePath, toForwardSlashAnyPlatform, } from '@vibe-agent-toolkit/utils';
+import { ARCHIVE_REFUSED_CODE, archiveEntryPlace, direntKindFollowingSync, everywhere, forEachInOrder, isAbsoluteAnyPlatform, isArchiveEntryReadRefusal, isVatError, pathPresent, requireFollowedStatSync, safePath, toForwardSlash, toForwardSlashAnyPlatform, withTempDir } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import { resolveSkillPackagingConfig } from '../../../skill-resolution/packaging-config.js';
+import { CommandRefusalError, errorMessageOf, refusalCodeOf } from '../../../utils/command-refusal.js';
+import { leftoverIssueOf } from '../../../utils/document-writer.js';
+import { requireSkillZipLayout } from '../../../utils/install-plan.js';
+import { requireInputPath } from '../../../utils/project-root-policy.js';
 import { downloadNpmPackage } from '../plugin/helpers.js';
 import { autopaginateSkills, executeOrgCommand, orgCommandFailure } from './helpers.js';
 const SKILL_ID_ARG = '<skill-id>';
@@ -47,7 +51,7 @@ function readSkillUploadResponse(endpoint, raw, fields) {
             [fields.version, version], [fields.createdAt, createdAt],
         ].filter(([, value]) => value === undefined).map(([key]) => String(key));
         const present = Object.keys(body).join(', ') || '(none)';
-        throw new Error(`${endpoint} returned a body with no usable ${missing.join(', ')}. Keys present: ${present}. `
+        throw new CommandRefusalError('EXTERNAL_API_FAILED', `${endpoint} returned a body with no usable ${missing.join(', ')}. Keys present: ${present}. `
             + 'Refusing to report success for an upload whose identifiers cannot be read.');
     }
     return { id, displayTitle, version, createdAt };
@@ -86,7 +90,7 @@ export function readCreateSkillResponse(raw) {
  * `skill_deleted` came back from a live `DELETE /v1/skills/{id}`;
  * `skill_version_deleted` is the plausible spelling for the version endpoint and
  * has never been seen. A single guessed string would make every version delete
- * report `deleted: false` — and now exit 1 — if the vendor spells it differently
+ * report `deleted: false` — and now exit 2 — if the vendor spells it differently
  * by one character. Accepting either keeps the check honest about what it knows:
  * a body naming something that is neither is a real divergence worth failing on.
  */
@@ -106,6 +110,8 @@ export const SKILL_DELETED_TYPES = ['skill_deleted'];
  * {@link readDeleteResponse} for why this is two and not one.
  */
 export const SKILL_VERSION_DELETED_TYPES = ['skill_version_deleted', 'skill_deleted'];
+/** A delete the API answered with an outcome other than a deletion: nothing was destroyed. */
+const NOT_CONFIRMED = { kind: 'failed', cause: 'the API named an outcome other than a deletion' };
 /**
  * A delete's document, tagged as a FAILED run when the API said the thing was
  * not deleted.
@@ -123,7 +129,7 @@ export const SKILL_VERSION_DELETED_TYPES = ['skill_version_deleted', 'skill_dele
  */
 export function reportDelete(raw, requestedId, expectedTypes) {
     const result = readDeleteResponse(raw, requestedId, expectedTypes);
-    return result.deleted ? result : orgCommandFailure(result);
+    return result.deleted ? result : orgCommandFailure(result, NOT_CONFIRMED);
 }
 /**
  * A version delete's document — the same verdict as {@link reportDelete}, about
@@ -148,7 +154,7 @@ export function reportDelete(raw, requestedId, expectedTypes) {
 export function reportVersionDelete(raw, skillId, version) {
     const { deleted } = readDeleteResponse(raw, skillId, SKILL_VERSION_DELETED_TYPES);
     const document = { id: skillId, version, deleted };
-    return deleted ? document : orgCommandFailure(document);
+    return deleted ? document : orgCommandFailure(document, NOT_CONFIRMED);
 }
 /**
  * Add the versions a `--all` run destroyed to its report, preserving whatever
@@ -160,9 +166,9 @@ export function reportVersionDelete(raw, skillId, version) {
  * skill's fields and publish the tag as part of the operator's document.
  */
 export function mergeDeleteReport(result, deletedVersions) {
-    const failed = 'orgCommandFailed' in result;
-    const document = { ...(failed ? result.document : result), deletedVersions };
-    return failed ? orgCommandFailure(document) : document;
+    if (!('orgCommandFailed' in result))
+        return { ...result, deletedVersions };
+    return orgCommandFailure({ ...result.document, deletedVersions }, result.outcome);
 }
 /** Read `POST /v1/skills/{id}/versions`. */
 export function readSkillVersionResponse(raw) {
@@ -230,7 +236,7 @@ export function buildUploadBodyOrRefuse(fields, files, bundleRoot) {
     if (multipart.body.length > API_SKILL_MAX_UPLOAD_BYTES) {
         const sized = files.map(f => ({ path: bundleRelativeName(f.filename, bundleRoot), bytes: f.content.length }));
         const measure = { of: 'upload-request', bytes: multipart.body.length };
-        throw new Error(`${describeOversizeBundle(sized, measure)}. The API will refuse this upload.`);
+        throw new CommandRefusalError('USAGE_INVALID', `${describeOversizeBundle(sized, measure)}. The API will refuse this upload.`);
     }
     return multipart;
 }
@@ -413,10 +419,10 @@ export function explainAnsweredNothing(error, bodyBytes) {
     if (!(error instanceof ApiTransportError))
         return error;
     if (error.bytesSent === 0) {
-        return new Error(`${error.message}\nNo byte of the request left this machine, so nothing was created and `
+        return new CommandRefusalError('EXTERNAL_API_FAILED', `${error.message}\nNo byte of the request left this machine, so nothing was created and `
             + 'there is nothing to clean up. Fix the connection and re-run the same command.', { cause: error });
     }
-    return new Error(`${error.message}\nThe connection closed before the API answered, so this is not a verdict on `
+    return new CommandRefusalError('EXTERNAL_API_FAILED', `${error.message}\nThe connection closed before the API answered, so this is not a verdict on `
         + `the upload. VAT had sent ${formatBytes(error.bytesSent)} of a ${formatBytes(bodyBytes)} `
         + `request body against a ${formatBytes(API_SKILL_MAX_UPLOAD_BYTES)} ceiling; the API has `
         + 'been observed to drop a connection near that ceiling instead of returning 413. Whether '
@@ -463,9 +469,9 @@ export function resolveSourceArgument(source) {
  *
  * 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
- * 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 document.
+ * allocations this module performs on attacker-supplied metadata: reading an
+ * entry inflates up to the size its header claims, and a header can claim
+ * anything. A 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
@@ -502,44 +508,69 @@ const MAX_INSPECTED_DOCUMENT_BYTES = 1024 * 1024;
  *
  * ⚠️ **Reading an entry is not free, and the docstring here used to claim it
  * was** — "no zip-slip or zip-bomb surface is opened — the entries are read, not
- * written" was true of the enumeration half and FALSE of the one `getData()`
- * call, which inflates `header.size` bytes into memory. Worse, it ran BEFORE the
+ * written" was true of the enumeration half and FALSE of the one read of an
+ * entry, which inflates up to its declared size into memory. Worse, it ran BEFORE the
  * 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_DOCUMENT_BYTES},
  * so an archive declaring a 4 GiB SKILL.md is enumerated and never inflated.
+ *
+ * 🔑 **The archive is read through the ONE archive primitive, and held to its ONE
+ * entry policy.** An archive holding an entry VAT would refuse to extract — a
+ * symbolic link, a device, a name outside the archive, two entries that are one
+ * name (a name listed twice included) — or one past the archive limits, or one
+ * that is not a skill ZIP by the one layout rule (`requireSkillZipLayout`), is
+ * refused here (`INPUT_UNREADABLE`), before anything is sent: the same archive is
+ * refused by every verb that takes one. Only bytes the reader cannot PARSE as a
+ * ZIP at all are let through, announced (see the catch).
+ *
+ * @throws ArchiveRefusedError (`INPUT_UNREADABLE`) for an archive the entry policy
+ *   or the archive limits refuse; FsFaultError side `source` when the OS refuses the read
  */
 export async function inspectZipArchive(zipPath) {
-    // `adm-zip` is already a runtime dependency of this package (the packager and
-    // the url skill-source both use it). An earlier comment here reasoned that
-    // reading the archive would mean "adding a dependency … for a log line" and
-    // declined on that basis; the premise was false, and the payoff is not a log
-    // line but a refusal that saves a doomed upload of up to 30 MiB.
-    const AdmZip = (await import('adm-zip')).default;
-    let entries;
+    // Loaded on demand: the archive readers are needed by this one lane of the org commands.
+    const { ARCHIVE_LIMITS, archiveEntryRefusal, ArchiveRefusedError: Refused, openArchive, readArchiveFile, zipOfArchive } = await import('@vibe-agent-toolkit/utils/archive');
+    // Read ONCE: what is judged below, what is re-zipped and what an unreadable upload sends are these bytes.
+    const bytes = await readArchiveFile(zipPath, 'source', ARCHIVE_LIMITS);
+    const source = { bytes, label: toForwardSlash(zipPath) };
+    let opened;
     try {
-        entries = new AdmZip(zipPath).getEntries();
+        opened = await openArchive(source, { format: 'zip', limits: ARCHIVE_LIMITS });
     }
     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. The
+        // Bytes that are no ZIP at all (`unreadable`: no ZIP signature anywhere) are
+        // not VAT's to block: the API is the authority on that upload, and 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) };
+        // That is the ONLY reason let through. A ZIP VAT will not take
+        // (`unsupported`: ZIP64, an ambiguous end record, a directory two readers
+        // would read differently, an end record padded past the 64 KiB a reader
+        // searches) stays loud, like an archive past the limits — were it passed
+        // on, a 20-byte edit or a 64 KiB append to any refused ZIP would send it
+        // with every check skipped. So does one the FILESYSTEM refuses (the path
+        // was readable a moment ago — the caller holds its bytes).
+        if (isUnparseableArchive(error))
+            return { archiveUnreadable: error.message, bytes };
+        throw error;
     }
+    const refusal = archiveEntryRefusal(opened.entries);
+    if (refusal !== undefined)
+        throw new Refused(opened.label, refusal);
+    // The one layout rule for a skill ZIP, shared with the two install verbs: an archive that is
+    // not a skill by it is refused here, never sent for the API to make what it can of.
+    const skillRoot = requireSkillZipLayout(opened.label, opened.entries);
     // PASS 1 — headers only. Nothing is decompressed while this runs, so both
     // refusals the caller can reach are decided on metadata alone.
-    const files = entries.filter(entry => !entry.isDirectory);
-    const uncompressedBytes = files.reduce((sum, entry) => sum + entry.header.size, 0);
+    const hostAdded = opened.entries.map(entry => entry.name).filter(name => hostAddedToSkillZip(name));
+    const sent = {
+        fileBytes: bytes.length,
+        upload: () => zipOfArchive(source, { format: 'zip', limits: ARCHIVE_LIMITS, omit: (entry) => hostAddedToSkillZip(entry.name) }),
+    };
+    const files = opened.entries.filter(entry => entry.kind === 'file' && !hostAddedToSkillZip(entry.name));
+    const uncompressedBytes = files.reduce((sum, entry) => sum + entry.size, 0);
     const neverUploaded = files
-        .map(entry => toForwardSlashAnyPlatform(entry.entryName))
+        .map(entry => toForwardSlashAnyPlatform(entry.name))
         .filter(name => name.split('/').some(segment => NEVER_UPLOADED_DIR_NAMES.has(segment)));
     // 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
@@ -547,23 +578,25 @@ export async function inspectZipArchive(zipPath) {
     // on an upload that cannot happen.
     if (uncompressedBytes > API_SKILL_MAX_UPLOAD_BYTES) {
         return {
-            uncompressedBytes, declaredName: undefined, neverUploaded, documents: [], bundleRoot: undefined, unreadable: [],
+            uncompressedBytes, declaredName: undefined, neverUploaded, documents: [], bundleRoot: undefined, hostAdded, unreadable: [], ...sent,
         };
     }
-    const elected = electShallowestSkillMd(files);
+    const elected = skillMdOf(files, skillRoot);
     const unreadable = [];
     return {
         uncompressedBytes,
-        declaredName: declaredNameOf(elected, unreadable),
+        declaredName: declaredNameOf(opened, elected, unreadable),
         neverUploaded,
-        documents: inflateMarkdownMembers(files, unreadable),
-        bundleRoot: archiveRootOf(elected?.entryName),
+        documents: inflateMarkdownMembers(opened, files, unreadable),
+        bundleRoot: skillRoot === '' ? undefined : skillRoot,
+        hostAdded,
         unreadable,
+        ...sent,
     };
 }
-/** 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);
+/** Whether `error` is the archive module saying the bytes are no ZIP at all — by its code and reason, never its prose. A ZIP it will not take, an entry that does not inflate included, is `unsupported`, and is not this. */
+function isUnparseableArchive(error) {
+    return isVatError(error, ARCHIVE_REFUSED_CODE) && error.reason === 'unreadable';
 }
 /**
  * Every markdown member of the archive, as an upload part.
@@ -577,19 +610,19 @@ function describeZipFailure(error) {
  * {@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.
+ * An entry that will not inflate is SKIPPED here and named: the checks it feeds
+ * only ever warn. The upload is what refuses it — VAT sends its own ZIP of what
+ * it read, and it could not read this.
  */
-function inflateMarkdownMembers(files, unreadable) {
+function inflateMarkdownMembers(archive, files, unreadable) {
     const documents = [];
     for (const entry of files) {
-        const filename = toForwardSlashAnyPlatform(entry.entryName);
+        const filename = toForwardSlashAnyPlatform(entry.name);
         if (!filename.toLowerCase().endsWith('.md'))
             continue;
-        if (entry.header.size > MAX_INSPECTED_DOCUMENT_BYTES)
+        if (entry.size > MAX_INSPECTED_DOCUMENT_BYTES)
             continue;
-        const content = inflateOrRecord(entry, unreadable);
+        const content = inflateOrRecord(archive, entry, unreadable);
         if (content !== undefined)
             documents.push({ fieldName: 'files[]', filename, content });
     }
@@ -598,87 +631,42 @@ function inflateMarkdownMembers(files, unreadable) {
 /**
  * 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.
+ * Reading an entry is the only decompression in this module, so it is the only
+ * thing that can throw here: the archive module refuses an entry with a bad CRC,
+ * a compression method that is not store/deflate, an encrypted entry, or one
+ * that does not hold what it declares (`ArchiveEntryReadError`, `ARCHIVE_ENTRY_UNREADABLE`).
+ * The inspection skips the member AND names it, so every finding the other
+ * members earn is still reported; the archive is not thereby accepted — the
+ * upload re-reads every entry for VAT's own ZIP and refuses this one, so nothing
+ * is sent.
  */
-function inflateOrRecord(entry, unreadable) {
+function inflateOrRecord(archive, entry, unreadable) {
     try {
-        return entry.getData();
+        return archive.read(entry);
     }
     catch (error) {
+        if (!isArchiveEntryReadRefusal(error))
+            throw 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 = toForwardSlashAnyPlatform(entry.entryName);
+        const name = toForwardSlashAnyPlatform(entry.name);
         if (!unreadable.some((failure) => failure.entry === name)) {
-            unreadable.push({ entry: name, reason: describeZipFailure(error) });
+            unreadable.push({ entry: name, reason: error.message });
         }
         return undefined;
     }
 }
 /**
- * The directory the elected SKILL.md sits in, which is the archive's bundle root.
+ * The archive's own SKILL.md: the one at the place the layout rule found the skill
+ * (`requireSkillZipLayout`), which is the one whose `name` the API keys the skill by.
+ * Never a `SKILL.md` deeper in the bundle — a fixture a skill ships is not the skill.
  *
- * `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.
+ * @param files - The archive's file entries
+ * @param root - Where the skill is: `''` for the archive's top level, or its one top-level folder
  */
-function archiveRootOf(entryName) {
-    if (entryName === undefined)
-        return undefined;
-    const cut = toForwardSlashAnyPlatform(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
- * will key the skill by.
- *
- * 🪤 Compared on DEPTH, with name length only as a tiebreak. It used to compare
- * `entryName.length` alone, on the reasoning that "a shortest-path comparison
- * needs no separator at all" — but shortest string is not shallowest path:
- * `a/b/SKILL.md` (12 chars, depth 2) beats `my-skill-bundle/SKILL.md` (24
- * chars, depth 1), so a bundled FIXTURE supplied the name and the operator was
- * advised to `--title` it. ZIP fixes `/` as the entry separator on every
- * platform, so splitting on it is not path handling — it is reading the format.
- */
-function electShallowestSkillMd(files) {
-    let elected;
-    for (const entry of files) {
-        if (basename(entry.entryName) !== 'SKILL.md')
-            continue;
-        if (elected !== undefined && !isShallower(entry.entryName, elected.entryName))
-            continue;
-        elected = entry;
-    }
-    return elected;
-}
-/** Fewer path segments wins; equal depth falls back to the shorter name. */
-function isShallower(candidate, incumbent) {
-    const candidateDepth = zipEntryDepth(candidate);
-    const incumbentDepth = zipEntryDepth(incumbent);
-    return candidateDepth === incumbentDepth
-        ? candidate.length < incumbent.length
-        : candidateDepth < incumbentDepth;
-}
-/**
- * How many segments a ZIP entry name has.
- *
- * Counted rather than `split('/')`-ed because the linter — correctly, for
- * FILESYSTEM paths — refuses that idiom: a host path's separator depends on the
- * platform. A ZIP entry name's does not; the format fixes it as `/`. Counting
- * the separator states that, and needs no exemption.
- */
-function zipEntryDepth(entryName) {
-    let depth = 1;
-    for (const character of entryName) {
-        if (character === '/')
-            depth += 1;
-    }
-    return depth;
+function skillMdOf(files, root) {
+    const place = root === '' ? 'SKILL.md' : `${root}/SKILL.md`;
+    return files.find(entry => archiveEntryPlace(entry.name).join('/') === place);
 }
 /**
  * The frontmatter `name` inside the ELECTED entry — or `undefined`, including
@@ -695,10 +683,10 @@ function zipEntryDepth(entryName) {
  * is already computed from headers) — see {@link inflateOrRecord}, which records
  * the refusal so the operator learns why no name was read.
  */
-function declaredNameOf(entry, unreadable) {
-    if (entry === undefined || entry.header.size > MAX_INSPECTED_DOCUMENT_BYTES)
+function declaredNameOf(archive, entry, unreadable) {
+    if (entry === undefined || entry.size > MAX_INSPECTED_DOCUMENT_BYTES)
         return undefined;
-    const content = inflateOrRecord(entry, unreadable);
+    const content = inflateOrRecord(archive, entry, unreadable);
     return content === undefined ? undefined : declaredSkillNameIn(content.toString('utf8'));
 }
 async function sendSkillUpload(client, displayTitle, files, bundleRoot) {
@@ -712,7 +700,7 @@ async function sendSkillUpload(client, displayTitle, files, bundleRoot) {
 function requireDeclaredName(skillMdPath) {
     const declared = readDeclaredSkillName(skillMdPath);
     if (declared === undefined) {
-        throw new Error(`SKILL.md has no usable frontmatter "name" field: ${skillMdPath}`);
+        throw new CommandRefusalError('USAGE_INVALID', `SKILL.md has no usable frontmatter "name" field: ${skillMdPath}`);
     }
     return declared;
 }
@@ -757,19 +745,21 @@ async function declaredTestInputPaths(skillDir) {
  * named no path and said nothing about what to do. A dangling link produced the
  * same shape of failure with `ENOENT`.
  *
- * `statSync` follows the link, which is the same thing the build-time size walk
+ * `requireFollowedStatSync` follows the link (its chain read first), which is the same thing the build-time size walk
  * does to classify one — so both lanes reach the same verdict about the same
  * entry.
  */
-function resolvesToDirectory(entry, fullPath, relativePath) {
+function resolvesToDirectory(entry, fullPath, relativePath, within) {
     if (!entry.isSymbolicLink())
         return false;
     try {
-        return statSync(fullPath).isDirectory();
+        // The chain is read beneath the skill directory first: a link to a network path is refused
+        // here, by name, before the kernel is asked to follow it.
+        return requireFollowedStatSync(fullPath, within).isDirectory();
     }
     catch (error) {
         const cause = error instanceof Error ? error.message : String(error);
-        throw new Error(`Cannot upload ${relativePath}: it is a symbolic link whose target could not be read `
+        throw new CommandRefusalError('INPUT_UNREADABLE', `Cannot upload ${relativePath}: it is a symbolic link whose target could not be read `
             + `(${cause}). Replace it with the file or directory it should point at, or remove it.`);
     }
 }
@@ -809,7 +799,7 @@ function collectFiles(dir, base, testInput, collected) {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         const fullPath = safePath.join(dir, entry.name);
         const relativePath = safePath.relative(base, fullPath);
-        const linkedDirectory = resolvesToDirectory(entry, fullPath, relativePath);
+        const linkedDirectory = resolvesToDirectory(entry, fullPath, relativePath, base);
         const directoryLike = entry.isDirectory() || linkedDirectory;
         if (testInput.has(safePath.resolve(fullPath))
             || (directoryLike && NEVER_UPLOADED_DIR_NAMES.has(entry.name))) {
@@ -822,7 +812,7 @@ function collectFiles(dir, base, testInput, collected) {
         else if (entry.isSymbolicLink()) {
             // Whatever it points at. A link to a FILE used to fall through to the
             // branch below and be read through — see this function's doc comment.
-            throw new Error(`Cannot upload ${relativePath}: it is a symbolic link${linkedDirectory ? ' to a directory' : ''}, `
+            throw new CommandRefusalError('INPUT_UNREADABLE', `Cannot upload ${relativePath}: it is a symbolic link${linkedDirectory ? ' to a directory' : ''}, `
                 + 'which a multipart upload cannot express. VAT will not publish the bytes it points '
                 + 'at under this name: a link out of the skill directory would send whatever the '
                 + 'target holds into a workspace every org member can read. Replace it with a real '
@@ -844,6 +834,17 @@ export async function collectSkillUploadFiles(skillDir) {
     collectFiles(skillDir, skillDir, await declaredTestInputPaths(skillDir), collected);
     return collected;
 }
+/**
+ * Stat a path the operator named, refusing through the one absent-vs-unreadable
+ * predicate: absent is the invocation's mistake (`USAGE_INVALID`, with this
+ * site's own sentence); anything else — an `EACCES` parent, an `ELOOP` — means
+ * whether it exists is unknown, the INPUT's refusal (`INPUT_UNREADABLE`).
+ * Never `existsSync`: it answers `false` for both.
+ */
+function statNamedPath(path, within, absentMessage) {
+    // Every path from the operator's named tree down to it is the operator's input.
+    return requireInputPath(path, within, { origin: 'argument', message: absentMessage }, everywhere('source'));
+}
 /**
  * Package a skill directory into the multipart file set the API takes.
  *
@@ -855,9 +856,7 @@ export async function collectSkillUploadFiles(skillDir) {
  */
 async function prepareSkillUpload(skillDir, titleOverride, logger) {
     const skillMdPath = safePath.join(skillDir, 'SKILL.md');
-    if (!existsSync(skillMdPath)) {
-        throw new Error(`SKILL.md not found in ${skillDir}. Is this a built skill directory?`);
-    }
+    statNamedPath(skillMdPath, skillDir, `SKILL.md not found in ${skillDir}. Is this a built skill directory?`);
     // The skill's own declared name — not the directory it happens to sit in,
     // which for a built or extracted tree carries no reliable identity.
     const declaredName = requireDeclaredName(skillMdPath);
@@ -1019,19 +1018,19 @@ async function uploadSkillVersionDir(client, skillId, skillDir, logger) {
  * untested — `packages/cli/src/commands/**` is coverage-excluded, so nothing in
  * any report said so.
  */
-export function listNodeModulePackages(nodeModulesDir) {
-    if (!existsSync(nodeModulesDir))
+export function listNodeModulePackages(nodeModulesDir, within) {
+    if (!pathPresent(nodeModulesDir, { follow: within }, everywhere('source'), 'probe'))
         return [];
     const results = [];
     // 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 (direntKindFollowingSync(nodeModulesDir, entry) !== 'directory')
+        if (direntKindFollowingSync(nodeModulesDir, entry, within) !== 'directory')
             continue;
         if (entry.name.startsWith('@')) {
             const scopeDir = safePath.join(nodeModulesDir, entry.name);
             for (const scopedEntry of readdirSync(scopeDir, { withFileTypes: true })) {
-                if (direntKindFollowingSync(scopeDir, scopedEntry) === 'directory')
+                if (direntKindFollowingSync(scopeDir, scopedEntry, within) === 'directory')
                     results.push(safePath.join(scopeDir, scopedEntry.name));
             }
         }
@@ -1046,17 +1045,27 @@ export function listNodeModulePackages(nodeModulesDir) {
  * first, then scans node_modules for sub-packages that contain built skills.
  */
 export function findSkillsDir(packageDir) {
+    // Every probe is beneath the package directory: its links are read before the kernel follows them,
+    // and a probe the OS refuses is the package's source fault, never "no skills here".
+    const present = (path) => pathPresent(path, { follow: packageDir }, everywhere('source'), 'probe');
     const direct = safePath.join(packageDir, 'dist', 'skills');
-    if (existsSync(direct))
+    if (present(direct))
         return direct;
-    const candidates = listNodeModulePackages(safePath.join(packageDir, 'node_modules'));
+    const candidates = listNodeModulePackages(safePath.join(packageDir, 'node_modules'), packageDir);
     for (const pkgDir of candidates) {
         const candidate = safePath.join(pkgDir, 'dist', 'skills');
-        if (existsSync(candidate))
+        if (present(candidate))
             return candidate;
     }
     return undefined;
 }
+/**
+ * The failure row for one skill, coded by the thrown value exactly as a run-level
+ * refusal would be. Exported for testing.
+ */
+export function skillUploadFailure(skill, error) {
+    return { skill, error: { code: refusalCodeOf(error), message: errorMessageOf(error) } };
+}
 /**
  * The batch's report, tagged as a failure when ANY skill did not publish.
  *
@@ -1073,79 +1082,83 @@ export function findSkillsDir(packageDir) {
  * the same lie, only smaller. What did land stays in the document, so the reader
  * can see how far the run got.
  */
-export function summarizeNpmInstall(source, results, errors) {
+export function summarizeNpmInstall(source, results, errors, leftover) {
     const summary = {
         source,
         skillsUploaded: results.length,
         ...(errors.length > 0 ? { skillsFailed: errors.length, errors } : {}),
         skills: results,
+        ...(leftover === undefined ? {} : { warnings: [leftoverIssueOf(leftover)] }),
     };
-    return errors.length > 0 ? orgCommandFailure(summary) : summary;
+    if (errors.length === 0)
+        return summary;
+    // Some landed: the workspace is in a mixed state (`partial`). None did: `failed`.
+    return orgCommandFailure(summary, results.length > 0
+        ? { kind: 'partial', failed: errors.length }
+        : { kind: 'failed', cause: `no skill from ${source} uploaded` });
 }
 /**
- * Upload skills from an npm package.
+ * Upload skills from an npm package. Exported for testing.
  */
-async function installFromNpm(npmPackage, skillFilter, client, logger) {
-    const tempDir = mkdtempSync(safePath.join(normalizedTmpdir(), 'vat-org-skills-'));
-    try {
+export async function installFromNpm(npmPackage, skillFilter, client, logger) {
+    // The download lives in a temp dir disposed of however the upload ends. One the OS will not
+    // remove after the uploads is reported beside them, never in their place: they landed.
+    const { value, leftover } = await withTempDir('vat-org-skills-', async (tempDir) => {
         logger.info(`Downloading: ${npmPackage}`);
-        const packageDir = downloadNpmPackage(npmPackage, tempDir);
+        const packageDir = await downloadNpmPackage(npmPackage, tempDir);
         const skillsDir = findSkillsDir(packageDir);
         if (!skillsDir) {
-            throw new Error(`No dist/skills/ directory found in ${npmPackage}. Was the package built with vat skills build?`);
+            throw new CommandRefusalError('USAGE_INVALID', `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/'}`);
         // Followed: a built skill directory that is a link is still a skill to upload.
         const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
-            .filter(e => direntKindFollowingSync(skillsDir, e) === 'directory')
+            .filter(e => direntKindFollowingSync(skillsDir, e, packageDir) === 'directory')
             .map(e => e.name);
         if (skillDirs.length === 0) {
-            throw new Error(`No skills found in dist/skills/ of ${npmPackage}`);
+            throw new CommandRefusalError('USAGE_INVALID', `No skills found in dist/skills/ of ${npmPackage}`);
         }
         const toUpload = skillFilter
             ? skillDirs.filter(name => name === skillFilter)
             : skillDirs;
         if (toUpload.length === 0) {
-            throw new Error(`Skill "${String(skillFilter)}" not found in ${npmPackage}. Available: ${skillDirs.join(', ')}`);
+            throw new CommandRefusalError('USAGE_INVALID', `Skill "${String(skillFilter)}" not found in ${npmPackage}. Available: ${skillDirs.join(', ')}`);
         }
         logger.info(`Found ${toUpload.length} skill(s) to upload from ${npmPackage}`);
         const results = [];
         const errors = [];
-        for (const skillName of toUpload) {
+        // In order: one rate-limited API, and the result and failure lists follow `toUpload`.
+        await forEachInOrder(toUpload, async (skillName) => {
             const skillDir = safePath.join(skillsDir, skillName);
             try {
                 const result = await uploadSkillDir(client, skillDir, undefined, logger);
                 results.push(result);
             }
             catch (error) {
-                const msg = error instanceof Error ? error.message : String(error);
-                logger.info(`   ⚠ ${skillName}: ${msg}`);
-                errors.push({ skill: skillName, error: msg });
+                const failure = skillUploadFailure(skillName, error);
+                logger.info(`   ⚠ ${skillName}: ${failure.error.message}`);
+                errors.push(failure);
             }
-        }
-        return summarizeNpmInstall(npmPackage, results, errors);
-    }
-    finally {
-        rmSync(tempDir, { recursive: true, force: true });
-    }
+        });
+        return { results, errors };
+    });
+    return summarizeNpmInstall(npmPackage, value.results, value.errors, leftover);
 }
 /**
  * Upload a local skill directory or ZIP file. Exported for testing.
  */
 export async function installFromLocal(source, titleOverride, client, logger) {
     const sourcePath = resolveSourceArgument(source);
-    if (!existsSync(sourcePath)) {
-        throw new Error(`Source not found: ${sourcePath}`);
-    }
-    const stat = statSync(sourcePath);
+    // The operator's own argument: its own `within`.
+    const stat = statNamedPath(sourcePath, sourcePath, `Source not found: ${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
     // an operator has no way to read that refusal as being about capitalisation.
     if (!stat.isDirectory() && sourcePath.toLowerCase().endsWith('.zip')) {
-        return installZipArchive(sourcePath, titleOverride, client, logger);
+        return await installZipArchive(sourcePath, titleOverride, client, logger);
     }
     if (!stat.isDirectory()) {
-        throw new Error(`Source must be a directory or .zip file: ${sourcePath}`);
+        throw new CommandRefusalError('USAGE_INVALID', `Source must be a directory or .zip file: ${sourcePath}`);
     }
     // "Packaging", not "Uploading". Everything that follows this line — reading the
     // config, collecting the file set, weighing the request — happens locally and
@@ -1156,7 +1169,7 @@ export async function installFromLocal(source, titleOverride, client, logger) {
     // all — `--from-npm` packages several skills in a loop, and a packaging error
     // with no path above it names nothing.
     logger.info(`Packaging skill directory: ${sourcePath}`);
-    return uploadSkillDir(client, sourcePath, titleOverride, logger);
+    return await uploadSkillDir(client, sourcePath, titleOverride, logger);
 }
 /**
  * Publish a ZIP archive as a NEW skill.
@@ -1171,12 +1184,9 @@ 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);
-    const zipContent = readFileSync(sourcePath);
-    const files = [{
-            fieldName: 'files[]',
-            filename: basename(sourcePath),
-            content: zipContent,
-        }];
+    // The ONE read of the file: everything below is decided on, and sent from, what this read.
+    const inspected = await inspectZipArchive(sourcePath);
+    const fileBytes = 'archiveUnreadable' in inspected ? inspected.bytes.length : inspected.fileBytes;
     // A ZIP is by construction a single large binary, so this is the shape most
     // likely to be over the ceiling — and the one that reached the wire unmeasured
     // while the check lived only in the directory-packaging path. It is gated in
@@ -1186,37 +1196,34 @@ async function installZipArchive(sourcePath, titleOverride, client, logger) {
     // "Preparing", not "Uploading": nothing has been sent at this point, and the
     // very next step can refuse locally. A line that claims an upload started is
     // the log telling the operator about work that never happened.
-    logger.info(`Preparing ZIP: ${sourcePath} (${formatBytes(zipContent.length)} of file content)`);
+    logger.info(`Preparing ZIP: ${sourcePath} (${formatBytes(fileBytes)} of file content)`);
     // Where the title came FROM, not just what it is. A ZIP's title is the
     // filename — `wiki-lint-v2.zip` publishes a skill called `wiki-lint-v2`,
     // which is a DIFFERENT skill from `wiki-lint` and is not refused, because
     // display_title uniqueness is enforced only when the field is sent. A
     // directory takes its title from SKILL.md instead, so the same tree zipped
-    // and unzipped can publish under two names.
-    //
-    // ⛔ This comment used to end "VAT cannot read the SKILL.md inside the
-    // archive: Node ships no ZIP reader, and adding a dependency to parse one
-    // here would mean owning central-directory, zip64 and zip-slip handling for
-    // a log line." The PREMISE was false — `adm-zip` is already a runtime
-    // dependency of this package — and the cost/benefit was weighed against the
-    // wrong benefit: the same read also answers whether the archive EXPANDS
-    // past the ceiling, which is a refusal, not a log line. So the archive is
-    // now read (see {@link inspectZipArchive}) and the divergence is reported
-    // as a fact below, in addition to this provenance line.
+    // and unzipped can publish under two names — the inspection reads the name
+    // the archive's SKILL.md declares, and the divergence is reported below.
     logger.info(`Display title: "${displayTitle}" (${titleOverride === undefined
         ? 'from the ZIP filename — NOT from the SKILL.md inside it; pass --title to set it'
         : 'from --title'})`);
-    const inspected = await inspectZipArchive(sourcePath);
+    let content;
     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.`);
+        content = inspected.bytes;
     }
     else {
-        refuseOrWarnOnArchive(inspected, displayTitle, zipContent.length, logger);
+        refuseOrWarnOnArchive(inspected, displayTitle, fileBytes, logger);
+        if (inspected.hostAdded.length > 0) {
+            logger.info(`Left out of the upload (added by the host that made the archive, not part of the skill): ${inspected.hostAdded.join(', ')}`);
+        }
+        // What is sent is what was judged: VAT's own ZIP of the entries it read, never the operator's bytes.
+        content = await inspected.upload();
     }
-    return sendSkillUpload(client, displayTitle, files);
+    return sendSkillUpload(client, displayTitle, [{ fieldName: 'files[]', filename: basename(sourcePath), content }]);
 }
 /**
  * The archive lane's own decisions, over what {@link inspectZipArchive} read:
@@ -1239,7 +1246,7 @@ function refuseOrWarnOnArchive(inspected, displayTitle, wireBytes, logger) {
     // 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`
+        throw new CommandRefusalError('USAGE_INVALID', `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 `
@@ -1248,7 +1255,7 @@ function refuseOrWarnOnArchive(inspected, displayTitle, wireBytes, logger) {
             + `\`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 `
+        throw new CommandRefusalError('USAGE_INVALID', `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". `
@@ -1284,8 +1291,8 @@ function refuseOrWarnOnArchive(inspected, displayTitle, wireBytes, logger) {
     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}`);
+        logger.warn(`${String(inspected.unreadable.length)} archive member(s) could not be inflated: ${named}. `
+            + 'They were not checked, and the upload will refuse the archive when it re-reads them — nothing is sent.');
     }
 }
 /**
@@ -1300,9 +1307,9 @@ function refuseOrWarnOnArchive(inspected, displayTitle, wireBytes, logger) {
  * 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.
+ * decides what the outcome means: some deleted plus some failed is a `partial`
+ * write that publishes the record; nothing deleted at all is a refusal with no
+ * record worth publishing. Both end on 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
@@ -1312,7 +1319,8 @@ function refuseOrWarnOnArchive(inspected, displayTitle, wireBytes, logger) {
 export async function deleteEveryVersion(client, skillId, versions, logger) {
     const deleted = [];
     const failures = [];
-    for (const version of versions) {
+    // In order: one rate-limited API, and both lists follow the order versions were handed in.
+    await forEachInOrder(versions, async (version) => {
         try {
             await client.deleteSkillVersion(skillId, version);
         }
@@ -1320,16 +1328,16 @@ export async function deleteEveryVersion(client, skillId, versions, logger) {
             const reason = error instanceof Error ? error.message : String(error);
             failures.push({ version, reason });
             logger.info(`   ⚠ version ${version} was not deleted: ${reason}`);
-            continue;
+            return;
         }
         deleted.push(version);
         logger.info(`   Deleted version ${version}`);
-    }
+    });
     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
+ * published report and the refusal's throw are built from, so the two endings never
  * describe the same run differently.
  */
 export function describeVersionSweepFailures(failures) {
@@ -1341,10 +1349,10 @@ export function describeVersionSweepFailures(failures) {
  *
  * 🔑 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.
+ * reconstruct — and throwing here would publish only the refusal 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 as a `partial` outcome:
+ * the payload is published, and the adapter ends the run on 2.
  *
  * `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
@@ -1352,17 +1360,20 @@ export function describeVersionSweepFailures(failures) {
  */
 export function reportHalfDeleted(report) {
     const { skillId, deletedVersions, failedVersions } = report;
+    // Some writes landed (the deleted versions) and some did not: every version
+    // still there, plus the skill itself, which is never deleted on this path.
+    const outcome = { kind: 'partial', failed: failedVersions.length + 1 };
     return orgCommandFailure({
         id: skillId,
         deleted: false,
         deletedVersions,
         failedVersions,
-        error: report.error,
+        reason: report.reason,
         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.',
-    });
+    }, outcome);
 }
 // ── Commands ───────────────────────────────────────────────────────────
 export function createOrgSkillsCommand() {
@@ -1376,7 +1387,7 @@ export function createOrgSkillsCommand() {
         .description('List organization skills')
         .option('--debug', DEBUG_OPT_DESC)
         .action(async (options) => {
-        await executeOrgCommand('OrgSkillsList', options.debug, async ({ client }) => {
+        await executeOrgCommand('claude org skills list', options.debug, ({ client }) => {
             return autopaginateSkills(client, '/v1/skills');
         });
     })
@@ -1399,8 +1410,7 @@ Example:
         .option('--title <title>', 'Display title override (single skill only)')
         .option('--debug', DEBUG_OPT_DESC)
         .action(async (source, options) => {
-        const commandName = options.fromNpm ? 'OrgSkillsInstallNpm' : 'OrgSkillsInstall';
-        await executeOrgCommand(commandName, options.debug, async ({ client, logger }) => {
+        await executeOrgCommand('claude org skills install', options.debug, ({ client, logger }) => {
             // INSIDE the action, like `versions add`'s own guards. Thrown from the
             // Commander handler instead, these were a floating rejection that
             // reached no catch: Node printed a raw stack trace with absolute $HOME
@@ -1408,22 +1418,22 @@ Example:
             // exited 1 — which the documented contract reads as "at least one
             // error-severity finding" for a run in which nothing executed.
             if (!source && !options.fromNpm) {
-                throw new Error('Provide a <source> path or use --from-npm <package>');
+                throw new CommandRefusalError('USAGE_INVALID', 'Provide a <source> path or use --from-npm <package>');
             }
             if (source && options.fromNpm) {
-                throw new Error('Provide either <source> or --from-npm, not both');
+                throw new CommandRefusalError('USAGE_INVALID', 'Provide either <source> or --from-npm, not both');
             }
             // The other two illegal combinations, refused rather than dropped. Both
             // flags used to be accepted and silently ignored on the lane that cannot
             // honour them, which is how an operator gets a skill published under the
             // wrong title — or every skill in a package published when they named one.
             if (options.title !== undefined && options.fromNpm) {
-                throw new Error('--title applies to a single skill and --from-npm can publish several, so it is '
+                throw new CommandRefusalError('USAGE_INVALID', '--title applies to a single skill and --from-npm can publish several, so it is '
                     + 'refused here rather than silently ignored. Publish the one skill with '
                     + '--skill and set its title in its SKILL.md, or upload its directory directly.');
             }
             if (options.skill !== undefined && !options.fromNpm) {
-                throw new Error('--skill selects one skill inside an npm package; it applies only with --from-npm');
+                throw new CommandRefusalError('USAGE_INVALID', '--skill selects one skill inside an npm package; it applies only with --from-npm');
             }
             if (options.fromNpm) {
                 return installFromNpm(options.fromNpm, options.skill, client, logger);
@@ -1442,10 +1452,27 @@ Description:
 
   A ZIP takes its display_title from the ZIP FILENAME, so my-skill-v2.zip
   publishes a skill titled "my-skill-v2", which is a separate skill from
-  "my-skill" and is not refused as a duplicate. VAT reads the SKILL.md nearest
-  the root of the archive and WARNS when the name it declares differs from that
-  title, because every version the skill ever gets will carry the declared name.
-  Pass --title to set the title explicitly.
+  "my-skill" and is not refused as a duplicate. VAT reads the archive's SKILL.md
+  and WARNS when the name it declares differs from that title, because every
+  version the skill ever gets will carry the declared name. Pass --title to set
+  the title explicitly.
+
+  A ZIP holds SKILL.md at its top level, or exactly one top-level folder with
+  SKILL.md directly inside (a skill folder, compressed) — the layout the install
+  verbs take. Any other layout is refused (INPUT_UNREADABLE), and so is a ZIP
+  holding a symbolic link, a name that leaves the archive, one name twice, or
+  more than 50,000 entries / 256 MiB expanded, a name Windows cannot hold (a
+  ":", < > " | ? *, a control character, a device name such as CON or aux.md,
+  a trailing "." or space), a ZIP64 archive, one whose end record two readers
+  could read differently or is not in its last 64 KiB, one with data before its
+  first local header (a self-extracting ZIP) or a directory entry whose local
+  header is not its own, or one holding an entry VAT cannot inflate. What is
+  sent is VAT's own ZIP of the entries it read and checked (its names, order,
+  timestamps, compression and 0644/0755 modes) — never your file's bytes — so a
+  top-level __MACOSX/ folder or .DS_Store (what macOS adds) is left out.
+  Only bytes that are no ZIP at all (no local-file-header or end-record
+  signature anywhere in them) are sent as they are, with a warning that the
+  checks below were skipped.
 
   A skill's eval suite is its answer key and is never uploaded: whatever the
   governing vibe-agent-toolkit.config.yaml declares as this skill's test input
@@ -1494,9 +1521,10 @@ Description:
 
 Exit Codes:
   0 - Every skill uploaded
-  1 - The run completed and at least one skill failed to upload (--from-npm
-      uploads several; the ones that landed are listed under skills)
-  2 - The run could not happen: no API key, no such source, unusable input
+  2 - At least one skill failed to upload (--from-npm uploads several; the ones
+      that landed are still listed under skills, each failure under errors as
+      { skill, error: { code, message } }), or the run was refused: no
+      API key, no such source, unusable input ({ error: { code, message } })
 
 Examples:
   $ vat claude org skills install dist/skills/org-admin
@@ -1512,23 +1540,22 @@ Examples:
         .option('--all', 'Auto-delete all versions before deleting the skill')
         .option('--debug', DEBUG_OPT_DESC)
         .action(async (skillId, options) => {
-        await executeOrgCommand('OrgSkillsDelete', options.debug, async ({ client, logger }) => {
+        await executeOrgCommand('claude org skills delete', options.debug, async ({ client, logger }) => {
             // Every version this run actually destroyed, accumulated as it goes.
             //
             // 🔑 It is a RECORD, not a progress counter. Version deletion is
             // irreversible and `--all` does it in a loop, so a failure part-way
             // through leaves a workspace nobody can reconstruct — and the old code
-            // threw at that point, which ends on `handleCommandError`'s exit 2
-            // ("the run could not happen") and DISCARDS the document. It happened,
-            // and it destroyed things the operator now has no list of. So the list
-            // travels with the failure, and the run ends 1: it happened, and its
-            // outcome is wrong.
+            // threw at that point, which publishes only the refusal and DISCARDS
+            // the document. It happened, and it destroyed things the operator now
+            // has no list of. So the list travels with the failure as a `partial`
+            // outcome: published, and ending on 2.
             const deletedVersions = [];
             const halfDeleted = (error, failedVersions) => reportHalfDeleted({
                 skillId,
                 deletedVersions,
                 failedVersions,
-                error: error instanceof Error ? error.message : String(error),
+                reason: errorMessageOf(error),
             });
             if (options.all) {
                 const versions = await autopaginateSkills(client, skillVersionsPath(skillId));
@@ -1544,11 +1571,11 @@ Examples:
                 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 refusal (EXTERNAL_API_FAILED, 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. `
+                        throw new CommandRefusalError('EXTERNAL_API_FAILED', `No version of ${skillId} could be deleted, so the skill was left alone. `
                             + `${String(sweep.failures.length)} attempt(s) failed — ${detail}`);
                     }
                     // The skill delete is not attempted: the API refuses a skill that still
@@ -1594,10 +1621,11 @@ Description:
   --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
+  listed under deletedVersions, the ones still there under failedVersions, why
+  under reason, and the run exits 2 with that record published. 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.
+  When nothing was deleted at all, it publishes only the refusal
+  ({ error: { code, message } }), also at 2.
 
   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
@@ -1605,10 +1633,10 @@ Description:
 
 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 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
+  2 - The skill was NOT deleted: the API named a different outcome, or --all
+      destroyed some versions and could not destroy the rest (the document
+      lists both); or the run was refused — no API key, the first request was
+      refused, or --all deleted no version at all ({ error: { code, message } })
 
 Example:
   $ vat claude org skills delete skill_abc123 --all
@@ -1622,7 +1650,7 @@ Example:
         .argument(SKILL_ID_ARG, SKILL_ID_DESC)
         .option('--debug', DEBUG_OPT_DESC)
         .action(async (skillId, options) => {
-        await executeOrgCommand('OrgSkillsVersionsList', options.debug, async ({ client }) => {
+        await executeOrgCommand('claude org skills versions list', options.debug, ({ client }) => {
             return autopaginateSkills(client, skillVersionsPath(skillId));
         });
     })
@@ -1641,7 +1669,7 @@ Example:
         .argument('<version>', 'Version to delete')
         .option('--debug', DEBUG_OPT_DESC)
         .action(async (skillId, version, options) => {
-        await executeOrgCommand('OrgSkillsVersionsDelete', options.debug, async ({ client, logger }) => {
+        await executeOrgCommand('claude org skills versions delete', options.debug, async ({ client, logger }) => {
             logger.info(`Deleting version ${version} of skill ${skillId}`);
             return reportVersionDelete(await client.deleteSkillVersion(skillId, version), skillId, version);
         });
@@ -1659,8 +1687,8 @@ Output:
 
 Exit Codes:
   0 - The version was deleted
-  1 - The run completed and the API named an outcome other than a deletion
-  2 - The run could not happen: no API key, or the request was refused
+  2 - The API named an outcome other than a deletion, or the run was refused:
+      no API key, or the request was refused ({ error: { code, message } })
 
 Example:
   $ vat claude org skills versions delete skill_abc123 1775007400733130
@@ -1678,11 +1706,9 @@ Example:
         .argument('<source>', 'Path to a built skill directory')
         .option('--debug', DEBUG_OPT_DESC)
         .action(async (skillId, source, options) => {
-        await executeOrgCommand('OrgSkillsVersionsAdd', options.debug, async ({ client, logger }) => {
+        await executeOrgCommand('claude org skills versions add', options.debug, ({ client, logger }) => {
             const resolved = resolveSourceArgument(source);
-            if (!existsSync(resolved))
-                throw new Error(`Source not found: ${resolved}`);
-            if (!statSync(resolved).isDirectory()) {
+            if (!statNamedPath(resolved, resolved, `Source not found: ${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
                 // hit this is the one who just read that `install` takes one — and a
@@ -1692,7 +1718,7 @@ Example:
                     ? ' A ZIP is accepted by `vat claude org skills install`, not here:'
                         + ' publish a new version from the built skill directory instead.'
                     : '';
-                throw new Error(`Source must be a skill directory: ${resolved}.${zipHint}`);
+                throw new CommandRefusalError('USAGE_INVALID', `Source must be a skill directory: ${resolved}.${zipHint}`);
             }
             // "Packaging", not "Publishing" — see `installFromLocal`. Measured: this
             // line printed, then `Failed to load config: …`, and nothing had been
@@ -1731,7 +1757,8 @@ Description:
 
 Exit Codes:
   0 - The version was published
-  2 - The run could not happen: no API key, no such source, not a directory,
+  2 - The run was refused ({ error: { code, message } }): no API key, no such
+      source, not a directory,
       over the upload ceiling, or a response the version identifier
       cannot be read from