@ahood/cli 0.5.0 → 0.5.2

package/dist/commands/publish.js

@@ -5,6 +5,7 @@ import { createGzip } from "node:zlib";
 import { apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill, SEMVER_RE, validateExternalUrl } from "../spec.js";
+import { UsageError } from "../usage-error.js";
 // Processing (decompress/validate/checksum/scan/upload) now happens in a
 // background workflow, not inline in versions/complete's response (server
 // issue #120) -- complete returns 202 immediately, so this polls
@@ -24,10 +25,10 @@ async function pollVersionStatus(owner, skill, version) {
             return result;
         await sleep(POLL_INTERVAL_MS);
     }
-    throw new Error(`Still processing after ${POLL_TIMEOUT_MS / 1000}s -- check \`ahood view ${owner}/${skill}\` later for the result.`);
+    throw new Error(`Still processing after ${POLL_TIMEOUT_MS / 1000}s -- check \`ahood skill view ${owner}/${skill}\` later for the result.`);
 }
-const USAGE = "Usage: ahood publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]\n" +
-    "   or: ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z> [--json]";
+const USAGE = "Usage: ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--kind skill|agent|mcp] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]\n" +
+    "   or: ahood skill publish <path> --owner <owner> --slug <skill> --version <x.y.z> [--json]";
 // Matched by ENTRY NAME at every depth, not by path prefix, so a nested
 // `vendor/thing/.git` is skipped the same as a top-level one. Not a
 // .gitignore parser (out of scope) -- just the fixed set of names that must
@@ -109,25 +110,29 @@ function parsePublishArgs(args) {
     const license = flagValue(args, "--license");
     const homepage = flagValue(args, "--homepage");
     const repository = flagValue(args, "--repository");
+    const kind = flagValue(args, "--kind");
     let legacyPath;
     const first = args[0];
     if (first && !first.startsWith("--")) {
         if (first.includes("/") && first.includes("@")) {
-            // Primary form: ahood publish <owner>/<skill>@<version>
+            // Primary form: ahood skill publish <owner>/<skill>@<version>
             const parsed = parseOwnerSkill(first.slice(0, first.lastIndexOf("@")), USAGE);
             owner = owner ?? parsed.owner;
             skill = skill ?? parsed.skill;
             version = version ?? first.slice(first.lastIndexOf("@") + 1);
         }
         else {
-            // Legacy form: ahood publish <path> --owner ... --slug ... --version ...
+            // Legacy form: ahood skill publish <path> --owner ... --slug ... --version ...
             legacyPath = first;
         }
     }
     if (!owner || !skill || !version)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     if (!SEMVER_RE.test(version)) {
-        throw new Error(`--version must be a semver like 1.2.3 (got "${version}").\n${USAGE}`);
+        throw new UsageError(`--version must be a semver like 1.2.3 (got "${version}").\n${USAGE}`);
+    }
+    if (kind !== undefined && kind !== "skill" && kind !== "agent" && kind !== "mcp") {
+        throw new UsageError(`--kind must be "skill", "agent", or "mcp" (got "${kind}").\n${USAGE}`);
     }
     // Validated here, before any network call (including the tar/gzip of the
     // skill directory) -- these only ever reach the server via
@@ -136,7 +141,7 @@ function parsePublishArgs(args) {
         validateExternalUrl(homepage, "--homepage");
     if (repository !== undefined)
         validateExternalUrl(repository, "--repository");
-    return { owner, skill, version, path: pathFlag ?? legacyPath ?? ".", name, tagline, tags, license, homepage, repository };
+    return { owner, skill, version, path: pathFlag ?? legacyPath ?? ".", name, tagline, tags, license, homepage, repository, kind };
 }
 // Creates the skill under the caller's own account when versions/init 404s
 // -- skill creation is CLI-only now (there is no separate `ahood create`;
@@ -159,6 +164,8 @@ async function createSkillForPublish(owner, skill, opts, jsonOutput) {
         body.homepage = opts.homepage;
     if (opts.repository !== undefined)
         body.repository = opts.repository;
+    if (opts.kind !== undefined)
+        body.kind = opts.kind;
     const created = await apiJson("/api/v1/skills", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -171,7 +178,7 @@ async function createSkillForPublish(owner, skill, opts, jsonOutput) {
     if (created.owner !== owner) {
         throw new Error(`Created ${created.owner}/${created.slug}, but this publish targeted "${owner}/${skill}" -- skills ` +
             `are always created under your own account (${created.owner}). Retry with: ` +
-            `ahood publish ${created.owner}/${skill}@<version>.`);
+            `ahood skill publish ${created.owner}/${skill}@<version>.`);
     }
     if (!jsonOutput) {
         console.log(`Created ${created.owner}/${created.slug} -- publishing its first version now.`);
@@ -205,13 +212,45 @@ async function initVersion(owner, skill, version, packageSizeBytes, createOpts,
 export async function publish(args) {
     const jsonOutput = args.includes("--json");
     try {
-        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository } = parsePublishArgs(args);
+        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository, kind } = parsePublishArgs(args);
         const skillMdPath = join(path, "SKILL.md");
-        if (!existsSync(skillMdPath)) {
-            throw new Error(`No SKILL.md found at ${skillMdPath} -- publish must point at a skill folder's root.`);
+        const agentMdPath = join(path, "AGENT.md");
+        const serverJsonPath = join(path, "server.json");
+        const hasSkillMd = existsSync(skillMdPath);
+        const hasAgentMd = existsSync(agentMdPath);
+        const hasServerJson = existsSync(serverJsonPath);
+        let resolvedKind = kind;
+        if (kind === "agent") {
+            if (!hasAgentMd)
+                throw new Error(`No AGENT.md found at ${agentMdPath} -- publish --kind agent must point at a folder containing AGENT.md.`);
+        }
+        else if (kind === "skill") {
+            if (!hasSkillMd)
+                throw new Error(`No SKILL.md found at ${skillMdPath} -- publish --kind skill must point at a folder containing SKILL.md.`);
+        }
+        else if (kind === "mcp") {
+            if (!hasServerJson)
+                throw new Error(`No server.json found at ${serverJsonPath} -- publish --kind mcp must point at a folder containing server.json.`);
+        }
+        else {
+            // kind === undefined -- infer from whichever root file(s) are actually present
+            const present = [hasSkillMd && "SKILL.md", hasAgentMd && "AGENT.md", hasServerJson && "server.json"].filter(Boolean);
+            if (present.length > 1) {
+                throw new Error(`Multiple root files found at ${path} (${present.join(", ")}) -- pass --kind skill, --kind agent, or --kind mcp to disambiguate.`);
+            }
+            if (present.length === 0) {
+                throw new Error(`No SKILL.md, AGENT.md, or server.json found at ${path} -- publish must point at a skill, agent, or mcp folder's root.`);
+            }
+            if (hasAgentMd) {
+                resolvedKind = "agent"; // inferred: only AGENT.md present, no --kind needed
+            }
+            else if (hasServerJson) {
+                resolvedKind = "mcp"; // inferred: only server.json present, no --kind needed
+            }
+            // else: hasSkillMd only -- resolvedKind stays undefined (unchanged existing behavior, server defaults to 'skill')
         }
         const archive = await tarGzDirectory(path);
-        const { init, created } = await initVersion(owner, skill, version, archive.length, { name, tagline, tags, license, homepage, repository }, jsonOutput);
+        const { init, created } = await initVersion(owner, skill, version, archive.length, { name, tagline, tags, license, homepage, repository, kind: resolvedKind }, jsonOutput);
         // TS's lib.dom BodyInit (in scope here since tsconfig has no explicit
         // "lib" override, so DOM is included alongside the Node types) type-checks
         // Buffer/Uint8Array against `Uint8Array<ArrayBuffer>` specifically as of

package/dist/commands/read.js

@@ -1,11 +1,12 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
+import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill read <owner>/<skill> [--json]";
 export async function read(args) {
     const jsonOutput = args.includes("--json");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
     if (!detail.skill_versions) {

package/dist/commands/remove.js

@@ -1,12 +1,13 @@
-import { existsSync, readdirSync, rmSync, rmdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync, rmdirSync, unlinkSync } from "node:fs";
 import { dirname } from "node:path";
 import { removeLockfileEntry } from "../lockfile.js";
-import { LOCKFILE_PATH, parseOwnerSkill, skillDir } from "../spec.js";
-const USAGE = "Usage: ahood remove <owner>/<skill>";
+import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, MCP_CONFIG_PATH } from "../spec.js";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill remove <owner>/<skill>";
 export async function remove(args) {
     const spec = args[0];
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const key = `${owner}/${skill}`;
     const dir = skillDir(owner, skill);
@@ -20,11 +21,49 @@ export async function remove(args) {
     const ownerDir = dirname(dir);
     if (existsSync(ownerDir) && readdirSync(ownerDir).length === 0)
         rmdirSync(ownerDir);
+    // An agent installs as a single flat file (.claude/agents/<owner>@<skill>.md),
+    // never a directory under .claude/skills/ -- skillDir's rmSync above never
+    // touches it. Without this, removing an installed agent silently left the
+    // file on disk (still loaded by Claude Code forever) while reporting
+    // success and clearing the lockfile entry, so a later `update` wouldn't
+    // catch it either (ahood-cli final review finding #2).
+    const agentFile = agentPath(owner, skill);
+    const agentExisted = existsSync(agentFile);
+    if (agentExisted)
+        unlinkSync(agentFile);
     const hadLockfileEntry = removeLockfileEntry(LOCKFILE_PATH, key);
-    if (!dirExisted && !hadLockfileEntry) {
+    if (!dirExisted && !agentExisted && !hadLockfileEntry) {
         console.error(`${key} was not installed -- nothing to remove.`);
         process.exitCode = 1;
         return;
     }
+    // An mcp-kind install has no directory or agent file on disk -- its only
+    // footprint here is the lockfile entry just cleared above and a live
+    // entry in .mcp.json (which add.ts's installMcpEntry merged in, possibly
+    // holding a resolved secret in its `env`). remove() doesn't attempt a real
+    // mcp removal, but staying silent about that entry repeats the exact
+    // false-assurance bug already fixed once for agent installs above: a user
+    // who removes an mcp artifact because they no longer trust it would be
+    // told it's gone while the MCP server (and its credential) still runs on
+    // the next Claude Code start -- and since the lockfile pin is now cleared,
+    // nothing will ever surface this again via `list`/`update`. So: warn
+    // instead of pretending it's gone.
+    if (existsSync(MCP_CONFIG_PATH)) {
+        try {
+            const parsed = JSON.parse(readFileSync(MCP_CONFIG_PATH, "utf-8"));
+            const mcpServers = parsed?.mcpServers;
+            if (mcpServers &&
+                typeof mcpServers === "object" &&
+                !Array.isArray(mcpServers) &&
+                Object.prototype.hasOwnProperty.call(mcpServers, skill)) {
+                console.warn(`WARNING: ${key} still has an entry in ${MCP_CONFIG_PATH} (which may contain secrets you entered) -- remove it manually.`);
+            }
+        }
+        catch {
+            // A malformed .mcp.json isn't this command's problem to fix or crash
+            // on -- add.ts's readMcpConfig is the strict validator for that path.
+            // Skip the warning rather than throw here.
+        }
+    }
     console.log(`Removed ${key}`);
 }

package/dist/commands/search.js

@@ -1,18 +1,19 @@
 import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
-const USAGE = "Usage: ahood search <query> [--json] [--limit <n>]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill search <query> [--json] [--limit <n>]";
 export async function search(args) {
     const jsonOutput = args.includes("--json");
     const limit = flagValue(args, "--limit");
     const queryParts = args.filter((a, i) => a !== "--json" && a !== "--limit" && args[i - 1] !== "--limit");
     const unknownFlag = queryParts.find((a) => a.startsWith("--"));
     if (unknownFlag)
-        throw new Error(`Unknown flag: ${unknownFlag}\n${USAGE}`);
+        throw new UsageError(`Unknown flag: ${unknownFlag}\n${USAGE}`);
     const query = queryParts.join(" ");
     if (!query)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     if (limit !== undefined && (!/^\d+$/.test(limit) || Number(limit) < 1)) {
-        throw new Error(`--limit must be a positive integer (got "${limit}").\n${USAGE}`);
+        throw new UsageError(`--limit must be a positive integer (got "${limit}").\n${USAGE}`);
     }
     const qs = new URLSearchParams({ q: query });
     if (limit !== undefined)

package/dist/commands/share.js

@@ -1,6 +1,7 @@
 import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill } from "../spec.js";
+import { UsageError } from "../usage-error.js";
 // These are skill-entity verbs (reached as `ahood skill share`/`ahood skill
 // unshare`, registered in SKILL_COMMANDS in index.ts), not group verbs --
 // they mutate a skill's sharing, not a group. Grouped together in one file
@@ -16,11 +17,11 @@ const UNSHARE_USAGE = "Usage: ahood skill unshare <owner>/<skill> --group <group
 export async function share(args) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
-        throw new Error(SHARE_USAGE);
+        throw new UsageError(SHARE_USAGE);
     const { owner, skill } = parseOwnerSkill(spec, SHARE_USAGE);
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
-        throw new Error(SHARE_USAGE);
+        throw new UsageError(SHARE_USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -31,11 +32,11 @@ export async function share(args) {
 export async function unshare(args) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
-        throw new Error(UNSHARE_USAGE);
+        throw new UsageError(UNSHARE_USAGE);
     const { owner, skill } = parseOwnerSkill(spec, UNSHARE_USAGE);
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
-        throw new Error(UNSHARE_USAGE);
+        throw new UsageError(UNSHARE_USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share/${encodeURIComponent(groupSlug)}`, { method: "DELETE" });
     console.log(`Unshared ${owner}/${skill} from ${groupSlug}.`);
 }

package/dist/commands/star.js

@@ -6,7 +6,7 @@ import { parseOwnerSkill } from "../spec.js";
 // deletes any matching row), so starring an already-starred skill or
 // unstarring one you never starred is a no-op 200, not an error.
 export async function star(args) {
-    const USAGE = "Usage: ahood star <owner>/<skill>";
+    const USAGE = "Usage: ahood skill star <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "POST",
@@ -14,7 +14,7 @@ export async function star(args) {
     console.log(`Starred ${owner}/${skill}.`);
 }
 export async function unstar(args) {
-    const USAGE = "Usage: ahood unstar <owner>/<skill>";
+    const USAGE = "Usage: ahood skill unstar <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "DELETE",

package/dist/commands/token.js

@@ -1,5 +1,6 @@
 import { apiJson } from "../http.js";
 import { confirm } from "../confirm.js";
+import { UsageError } from "../usage-error.js";
 export async function token(args) {
     const [subcommand, ...rest] = args;
     switch (subcommand) {
@@ -10,13 +11,13 @@ export async function token(args) {
         case "revoke":
             return tokenRevoke(rest);
         default:
-            throw new Error("Usage: ahood token create <name>|list [--json]|revoke <id> [--yes]");
+            throw new UsageError("Usage: ahood token create <name>|list [--json]|revoke <id> [--yes]");
     }
 }
 async function tokenCreate(args) {
     const name = args[0];
     if (!name)
-        throw new Error("Usage: ahood token create <name>");
+        throw new UsageError("Usage: ahood token create <name>");
     // Note: this itself requires an existing session-backed token or a
     // browser login -- per docs/adr/backend/0001-backend-services.md's Phase
     // 3 section, tokens can't mint tokens (POST /auth/tokens is session-only,
@@ -52,7 +53,7 @@ async function tokenRevoke(args) {
     const yes = args.includes("--yes");
     const id = args.find((a) => !a.startsWith("--"));
     if (!id)
-        throw new Error("Usage: ahood token revoke <id> [--yes]");
+        throw new UsageError("Usage: ahood token revoke <id> [--yes]");
     // --yes bypasses both the lookup and the prompt entirely, preserving the
     // original one-shot behavior (a single DELETE call) for scripts/CI that
     // already call `ahood token revoke <id> --yes` unattended.

package/dist/commands/unpublish.js

@@ -2,7 +2,8 @@ import { apiJson } from "../http.js";
 import { confirm } from "../confirm.js";
 import { parseOwnerSkill, parseOwnerSkillVersion } from "../spec.js";
 import { fetchVersionMeta } from "./add.js";
-const USAGE = "Usage: ahood unpublish <owner>/<skill>[@version] [--yes]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill unpublish <owner>/<skill>[@version] [--yes]";
 // A bare "owner/skill" has no "@" at all, so lastIndexOf("@") is -1 and this
 // is a whole-skill unpublish (preserves the exact pre-existing behavior).
 // "owner/skill@1.2.3" has an "@" at index > 0 and is a single-version yank
@@ -16,7 +17,7 @@ export async function unpublish(args) {
     const yes = args.includes("--yes");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     if (isVersioned(spec)) {
         const { owner, skill, version: parsedVersion } = parseOwnerSkillVersion(spec, USAGE);
         // parseOwnerSkillVersion only validates *syntax* -- an omitted "@version"
@@ -63,7 +64,7 @@ export async function unpublish(args) {
         // the whole request, since the yank already took effect. Discarding the
         // response body would silently drop that signal (ahood-cli#68): the
         // pointer could now be stale with nothing in the terminal to say so, and
-        // a later `ahood add owner/skill` trusts latest_version_id completely.
+        // a later `ahood skill add owner/skill` trusts latest_version_id completely.
         if (result.latest_version_warning) {
             console.warn(`WARNING: ${result.latest_version_warning}`);
         }
@@ -82,5 +83,5 @@ export async function unpublish(args) {
         return;
     }
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`, { method: "DELETE" });
-    console.log(`Unpublished ${key}. Run \`ahood remove ${key}\` to also remove your local copy.`);
+    console.log(`Unpublished ${key}. Run \`ahood skill remove ${key}\` to also remove your local copy.`);
 }

package/dist/commands/update.js

@@ -1,7 +1,8 @@
 import { LOCKFILE_PATH, parseOwnerSkill } from "../spec.js";
 import { readLockfile } from "../lockfile.js";
 import { add, fetchVersionMeta } from "./add.js";
-const USAGE = "Usage: ahood update [<owner>/<skill> ...] [--dry-run] [--json]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]";
 async function previewSkill(ownerSlashSkill, currentVersion) {
     const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
     const meta = await fetchVersionMeta(owner, skill, "latest");
@@ -47,7 +48,7 @@ export async function update(args) {
     const dryRun = args.includes("--dry-run");
     const jsonOutput = args.includes("--json");
     if (jsonOutput && !dryRun) {
-        throw new Error(`--json is only supported together with --dry-run.\n${USAGE}`);
+        throw new UsageError(`--json is only supported together with --dry-run.\n${USAGE}`);
     }
     const targets = args.filter((a) => a !== "--dry-run" && a !== "--json");
     const lockfile = readLockfile(LOCKFILE_PATH);
@@ -88,7 +89,7 @@ export async function update(args) {
     for (const ownerSlashSkill of skillKeys) {
         if (!lockfile[ownerSlashSkill]) {
             // Reachable two ways: an explicitly-named skill that was never
-            // installed (`ahood add` is the right command for that -- `update`
+            // installed (`ahood skill add` is the right command for that -- `update`
             // must not silently install and pin it), or -- when targets came from
             // the lockfile itself -- the lockfile changing out from under us
             // mid-loop. Either way: skip, don't abort.
@@ -96,6 +97,22 @@ export async function update(args) {
             continue;
         }
         try {
+            // add() always hits the .mcp.json collision check for an mcp-kind
+            // entry that's already installed (that's the very definition of
+            // "already installed" for that kind), so calling it unconditionally
+            // here would make `ahood skill update` with no arguments permanently
+            // report a failure and exit 1 for every user who has ever installed
+            // an mcp artifact, even when nothing needs updating. fetchVersionMeta
+            // already resolves `kind` as part of the normal "latest" lookup add()
+            // itself does, so resolving it here first lets this skip cleanly
+            // instead of updating and hitting that guaranteed error. This is a
+            // skip-and-report-cleanly fix, not real mcp-update support.
+            const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
+            const meta = await fetchVersionMeta(owner, skill, "latest");
+            if (meta.kind === "mcp") {
+                console.warn(`Skipping ${ownerSlashSkill}: mcp artifacts aren't updatable via this command yet.`);
+                continue;
+            }
             await add([ownerSlashSkill]); // no @version -- resolves to latest again
         }
         catch (error) {

package/dist/commands/versions.js

@@ -1,6 +1,7 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
-const USAGE = "Usage: ahood versions <owner>/<skill> [--json]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill versions <owner>/<skill> [--json]";
 function formatSize(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
@@ -17,7 +18,7 @@ export async function versions(args) {
     const jsonOutput = args.includes("--json");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const { versions: list } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
     if (jsonOutput) {

package/dist/commands/view.js

@@ -2,7 +2,8 @@ import { spawn } from "node:child_process";
 import { apiJson } from "../http.js";
 import { getApiUrl } from "../config.js";
 import { parseOwnerSkill } from "../spec.js";
-const USAGE = "Usage: ahood view <owner>/<skill> [--json] [--web]";
+import { UsageError } from "../usage-error.js";
+const USAGE = "Usage: ahood skill view <owner>/<skill> [--json] [--web]";
 // Spawned with argv as an array (not a shell string), so a crafted owner/skill
 // can never inject shell syntax -- and both segments are already restricted
 // to a safe charset by parseOwnerSkill before this ever runs.
@@ -27,7 +28,7 @@ export async function view(args) {
     const web = args.includes("--web");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
-        throw new Error(USAGE);
+        throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const url = `${getApiUrl()}/${owner}/${skill}`;
     if (web) {
@@ -41,7 +42,7 @@ export async function view(args) {
     }
     const field = (label, value) => console.log(`  ${label.padEnd(13)}${value}`);
     console.log(`${detail.owner}/${detail.slug}`);
-    // Mirrors the wording/tone of `ahood add`'s yanked warning (src/commands/add.ts)
+    // Mirrors the wording/tone of `ahood skill add`'s yanked warning (src/commands/add.ts)
     // and the website's skill detail page banner -- this is the one CLI surface
     // whose entire job is "let me check this out before deciding to install it",
     // so it must not be the one place that stays silent about a yanked version.

package/dist/commands/whoami.js

@@ -20,12 +20,15 @@ export async function whoami(args = []) {
     if (!token) {
         // Previously exited 0 here, defeating whoami's purpose as a scriptable
         // auth check -- "no token configured at all" must fail just like "token
-        // rejected by the server" does below.
+        // rejected by the server" does below. Exit 4 ("authentication required
+        // or rejected"), not the generic 1 -- this is exactly the case the
+        // README's own exit-code table names as the canonical example of 4
+        // (ahood-cli#80).
         if (wantsJson)
             console.log(JSON.stringify({ authenticated: false }));
         else
             console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
-        process.exitCode = 1;
+        process.exitCode = 4;
         return;
     }
     // There is no endpoint that returns an identity for a bearer caller yet, so
@@ -62,11 +65,14 @@ export async function whoami(args = []) {
             return;
         }
         if (error instanceof ApiError && error.status === 401) {
+            // Same exit-4 reasoning as the "no token at all" branch above: the
+            // token was rejected by the server, which is the other half of the
+            // README's exit-code-4 definition ("or the token was refused").
             if (wantsJson)
                 console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
             else
                 console.error("Not authenticated -- your token is invalid or has been revoked.");
-            process.exitCode = 1;
+            process.exitCode = 4;
             return;
         }
         const message = error instanceof Error ? error.message : String(error);

package/dist/config.js

@@ -1,3 +1,4 @@
+import { UsageError } from "./usage-error.js";
 const DEFAULT_API_URL = "https://ahood.vercel.app";
 let warnedAboutOverride = false;
 // AHOOD_API_URL is trusted with the bearer token on every request (see
@@ -15,7 +16,7 @@ export function getApiUrl() {
         url = new URL(trimmed);
     }
     catch {
-        throw new Error(`AHOOD_API_URL is not a valid URL: "${configured}"`);
+        throw new UsageError(`AHOOD_API_URL is not a valid URL: "${configured}"`);
     }
     // Plain http:// is only allowed for localhost and the RFC 2606 reserved
     // test TLDs (.test/.invalid/.example/.localhost), which can never resolve
@@ -26,7 +27,7 @@ export function getApiUrl() {
         url.hostname === "::1" ||
         /\.(test|invalid|example|localhost)$/i.test(url.hostname);
     if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocalHost)) {
-        throw new Error(`AHOOD_API_URL must use https:// (http:// is only allowed for localhost/test hosts); got "${configured}".`);
+        throw new UsageError(`AHOOD_API_URL must use https:// (http:// is only allowed for localhost/test hosts); got "${configured}".`);
     }
     if (trimmed !== DEFAULT_API_URL && !warnedAboutOverride) {
         console.error(`warning: using non-default API endpoint from AHOOD_API_URL: ${trimmed}`);

package/dist/exit-code.js

@@ -1,10 +1,19 @@
 import { ApiError, NetworkError } from "./http.js";
+import { UsageError } from "./usage-error.js";
 // A hung/black-holed connection throws undici's generic TypeError("fetch
 // failed") -- http.ts wraps that into NetworkError so it gets its own exit
 // code here, distinct from a server-returned ApiError. Kept in its own
 // module (rather than inline in index.ts) so it's importable in tests
 // without triggering index.ts's unconditional top-level main() call.
 export function exitCodeFor(error) {
+    // A local validation failure (missing/malformed argument, bad flag value)
+    // is exactly the "bad arguments" half of exit code 2's documented meaning
+    // -- same code the server-rejected branch below already uses, so a caller
+    // branching on exit code sees one consistent "fix your input" signal
+    // regardless of whether the check ran locally or round-tripped to the
+    // server (ahood-cli#80).
+    if (error instanceof UsageError)
+        return 2;
     if (error instanceof ApiError) {
         if (error.status === 401 || error.status === 403)
             return 4;

package/dist/flags.js

@@ -1,3 +1,4 @@
+import { UsageError } from "./usage-error.js";
 // Shared flag-value parsing. Throws instead of silently treating the next flag
 // as this flag's value (e.g. `--tagline --visibility public` used to send
 // "--visibility" as the tagline and drop --visibility entirely).
@@ -20,7 +21,7 @@ export function flagValue(args, flag) {
         if (arg === flag) {
             const value = args[i + 1];
             if (value === undefined || value.startsWith("--")) {
-                throw new Error(`${flag} requires a value.`);
+                throw new UsageError(`${flag} requires a value.`);
             }
             return value;
         }