@ahood/cli 0.9.0 → 0.10.0

package/dist/commands/list.js

@@ -1,17 +1,23 @@
 import { apiJson } from "../http.js";
-export async function listOwnSkills() {
-    const { skills } = await apiJson("/api/v1/skills?mine=true");
+import { KINDS, strictKind } from "../kinds.js";
+// A strict kind is filtered by the registry: its `mine=true` branch honours
+// ?kind= (ahood#657) and, with no page/per_page, still returns every owned
+// row unpaginated -- the same shape as before.
+export async function listOwnSkills(kind) {
+    const query = kind ? `mine=true&kind=${encodeURIComponent(kind)}` : "mine=true";
+    const { skills } = await apiJson(`/api/v1/skills?${query}`);
     return skills ?? [];
 }
-export async function listSkills(args = []) {
+export async function listSkills(args = [], scope) {
     const jsonOutput = args.includes("--json");
-    const skills = await listOwnSkills();
+    const kind = strictKind(scope);
+    const skills = await listOwnSkills(kind);
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;
     }
     if (skills.length === 0) {
-        console.log("You haven't published any skills yet.");
+        console.log(kind ? `You haven't published any ${KINDS[kind].plural} yet.` : "You haven't published any skills yet.");
         return;
     }
     for (const skill of skills) {

package/dist/commands/login.js

@@ -1,8 +1,13 @@
-import { apiJson } from "../http.js";
+import { apiJson, parseRetryAfterMs } from "../http.js";
 import { getApiUrl } from "../config.js";
 import { writeCredentials } from "../credentials.js";
 const DEFAULT_EXPIRES_IN_SECONDS = 600; // 10 minutes, matching the previous timeout loop's real-world duration
 const POLL_TIMEOUT_MS = 10_000;
+const POLL_INTERVAL_MS = 2_000;
+// ahood-cli#159: cap on a single 429 backoff hop, same policy as apiJson's
+// rate-limit retry -- however large the server's Retry-After, one wait stays
+// bounded, and the deadline check below keeps the loop inside expires_in.
+const RATE_LIMIT_MAX_BACKOFF_MS = 30_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -10,6 +15,11 @@ export async function login() {
     const { code, verification_url, expires_in } = await apiJson("/api/v1/auth/cli/device", {
         method: "POST",
     });
+    // Printed VERBATIM, deliberately not through sanitizeForTerminal the way
+    // `add` treats server-supplied text: this line exists so the user can
+    // compare it against the code on the /cli-auth page, and a tidied-up
+    // rendering would make that comparison meaningless. Pinned by
+    // tests/login-device-code-verbatim.test.ts (ahood#357).
     console.log(`First, confirm this code matches what you see in your browser: ${code}`);
     console.log(`Open ${verification_url} to approve.`);
     // expires_in is server-supplied; a missing/non-finite value previously
@@ -18,8 +28,29 @@ export async function login() {
     // failed instantly with "timed out" instead of ever actually polling.
     const seconds = Number.isFinite(expires_in) && expires_in > 0 ? expires_in : DEFAULT_EXPIRES_IN_SECONDS;
     const deadline = Date.now() + seconds * 1000;
+    // ahood-cli#159: when the registry rate-limits the poll, `backoffMs` carries
+    // the wait for the NEXT poll -- 429 must not `continue` on the normal
+    // cadence, which is the retry-storm shape: the client answers "you are
+    // asking too often" by asking again on the same schedule, against an
+    // endpoint that can least afford it.
+    let backoffMs;
+    let consecutive429s = 0;
+    // Whether the loop ever saw a 429 -- the timeout message below can then say
+    // why the window ran out instead of blaming the user's pace.
+    let wasRateLimited = false;
     while (Date.now() < deadline) {
-        await sleep(2000);
+        let waitMs = POLL_INTERVAL_MS;
+        if (backoffMs !== undefined) {
+            waitMs = backoffMs;
+            backoffMs = undefined;
+            // The 429 backoff counts against the login deadline like every other
+            // wait: a server that keeps answering "wait 60s" must not stretch the
+            // loop past expires_in -- and past expiry the device code is dead, so
+            // polling after the wait would be pointless anyway.
+            if (Date.now() + waitMs >= deadline)
+                break;
+        }
+        await sleep(waitMs);
         let res;
         try {
             // Poll against the CONFIGURED API host (getApiUrl()), not a URL derived
@@ -27,6 +58,17 @@ export async function login() {
             // shown to the human, never used to build a request, so a compromised
             // or redirected registry response can't point this at a host that
             // then harvests the device code and hands back an attacker's token.
+            //
+            // `code` is sent VERBATIM and must stay that way: do not trim it,
+            // change its case, strip its separator or otherwise tidy it. The format
+            // is defined once, in ahood's lib/auth/device-code.ts, and the server
+            // canonicalizes whatever arrives -- so this CLI stays format-agnostic
+            // and a server-side format fix needs no release of this package. In
+            // ahood#349 that property was all that stood between a bad ten-minute
+            // "Login timed out" and a bad error: the hyphen happens to be
+            // unreserved, so encodeURIComponent left it alone. Pinned by
+            // tests/login-device-code-verbatim.test.ts; contract in ahood's
+            // docs/adr/backend/0005-device-code-cross-repo-contract.md (ahood#357).
             res = await apiFetchWithTimeout(`/api/v1/auth/cli/device/${encodeURIComponent(code)}`);
         }
         catch (error) {
@@ -46,6 +88,22 @@ export async function login() {
         if (res.status === 410 || res.status === 404) {
             throw new Error("This login was cancelled or expired. Run `ahood login` again.");
         }
+        if (res.status === 429) {
+            // ahood-cli#159: the registry has said stop. Back off by Retry-After
+            // (exponentially, 1s doubling, when the header is absent/unparseable)
+            // instead of polling on -- and let the deadline check at the top of the
+            // loop bound the total time, so rate limiting cannot extend the window.
+            wasRateLimited = true;
+            consecutive429s++;
+            // Drain the rejected body so the socket is released while we wait.
+            await res.text().catch(() => "");
+            const retryAfterMs = parseRetryAfterMs(res.headers.get("Retry-After"));
+            const wait = Math.min(retryAfterMs ?? 1_000 * 2 ** (consecutive429s - 1), RATE_LIMIT_MAX_BACKOFF_MS);
+            backoffMs = wait;
+            console.error(`Rate limited while polling; waiting ${Math.ceil(wait / 1000)}s before trying again...`);
+            continue;
+        }
+        consecutive429s = 0;
         let body;
         try {
             body = (await res.json());
@@ -65,7 +123,9 @@ export async function login() {
         }
         // status === "pending" -- keep polling.
     }
-    throw new Error("Login timed out. Run `ahood login` again.");
+    throw new Error(wasRateLimited
+        ? "Login timed out -- the registry kept rate limiting the poll. Wait a bit and run `ahood login` again."
+        : "Login timed out. Run `ahood login` again.");
 }
 // Not apiJson: a non-2xx poll response ("pending", still-provisioning, etc.)
 // is expected and must not throw -- the status code is inspected by the

package/dist/commands/mcp.js

@@ -1,7 +1,10 @@
 import { startMcpServer } from "../mcp/server.js";
-// `ahood mcp` takes no subcommands/flags in v1. Unlike every other
-// account-scoped command it never returns until the client disconnects --
-// see startMcpServer's comment.
+// Starts the local stdio MCP server -- reached as bare `ahood mcp` (the
+// original v1 contract, kept byte-for-byte for existing host configs) or
+// `ahood mcp serve`; index.ts's dispatchMcp() decides which first words mean
+// "serve" and which are registry verbs (ahood-cli#172). Unlike every other
+// command it never returns until the client disconnects -- see
+// startMcpServer's comment.
 export async function mcp(_args) {
     await startMcpServer();
 }

package/dist/commands/publish.js

@@ -6,6 +6,26 @@ 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";
+import { assertKind, strictKind } from "../kinds.js";
+// `ahood agent publish` / `ahood mcp publish` (ahood-cli#172): an existing
+// entry of another kind must be refused before anything is packed, created,
+// or uploaded. The upload would fail server-side anyway -- the processing
+// workflow validates the archive against the entry's stored kind -- but only
+// after a version row was created and a full upload spent. A 404 is the
+// "doesn't exist yet" case publish already handles by creating the entry,
+// now with the scope's kind.
+async function assertPublishTargetKind(scope, owner, skill) {
+    let detail;
+    try {
+        detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 404)
+            return;
+        throw error;
+    }
+    assertKind(scope, `${owner}/${skill}`, detail.kind, "publish", "publish a new version of");
+}
 // 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
@@ -342,10 +362,18 @@ async function initVersion(owner, skill, version, packageSizeBytes, changelog, c
 // validation, network, or a rejected publish -- still yields exactly one
 // JSON object (`{error}`) rather than a human message, while still
 // rethrowing so index.ts's exit-code mapping (exitCodeFor) is unaffected.
-export async function publish(args) {
+export async function publish(args, scope) {
     const jsonOutput = args.includes("--json");
     try {
-        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository, kind, changelog } = parsePublishArgs(args);
+        const parsed = parsePublishArgs(args);
+        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository, changelog } = parsed;
+        // A kind-scoped publish implies its kind. The dispatcher has already
+        // refused a contradictory --kind before this runs, so the flag (when the
+        // legacy `ahood skill publish` passes one through) and the scope can't
+        // disagree here.
+        const scopedKind = strictKind(scope);
+        const kind = scopedKind ?? parsed.kind;
+        const via = scopedKind ? `ahood ${scope.noun} publish` : `publish --kind ${kind}`;
         const skillMdPath = join(path, "SKILL.md");
         const agentMdPath = join(path, "AGENT.md");
         const serverJsonPath = join(path, "server.json");
@@ -355,15 +383,15 @@ export async function publish(args) {
         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.`);
+                throw new Error(`No AGENT.md found at ${agentMdPath} -- ${via} 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.`);
+                throw new Error(`No SKILL.md found at ${skillMdPath} -- ${via} 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.`);
+                throw new Error(`No server.json found at ${serverJsonPath} -- ${via} must point at a folder containing server.json.`);
         }
         else {
             // kind === undefined -- infer from whichever root file(s) are actually present
@@ -390,6 +418,8 @@ export async function publish(args) {
         if (resolvedKind === "skill" || (resolvedKind === undefined && hasSkillMd)) {
             warnAboutSkillDescription(skillMdPath);
         }
+        if (scopedKind !== undefined)
+            await assertPublishTargetKind(scope, owner, skill);
         const archive = await tarGzDirectory(path);
         const { init, created } = await initVersion(owner, skill, version, archive.length, changelog, { name, tagline, tags, license, homepage, repository, kind: resolvedKind }, jsonOutput);
         // TS's lib.dom BodyInit (in scope here since tsconfig has no explicit

package/dist/commands/read.js

@@ -2,6 +2,7 @@ import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
 import { sanitizeDocumentForTerminal, sanitizeForTerminal } from "../terminal-safe.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill read <owner>/<skill> [--json]";
 export async function readSkillMd(owner, skill) {
     const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
@@ -41,12 +42,13 @@ export async function readSkillMd(owner, skill) {
         yanked_reason: detail.skill_versions.yanked_reason ?? null,
     };
 }
-export async function read(args) {
+export async function read(args, scope) {
     const jsonOutput = args.includes("--json");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
         throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    await ensureRemoteKind(scope, owner, skill, "read", "read");
     const { version, content } = await readSkillMd(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify({ version, content }));

package/dist/commands/remove.js

@@ -4,8 +4,34 @@ import { readLockfile, removeLockfileEntry, withLock, writeJsonFileAtomic } from
 import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, MCP_CONFIG_PATH } from "../spec.js";
 import { readMcpConfig, matchesMcpConfigHash } from "./add.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind, ensureRemoteKind, KindMismatchError, describeKind, localInstalledKind, strictKind, } from "../kinds.js";
+// `ahood agent remove` / `ahood mcp remove` (ahood-cli#172): decide whether
+// this install really is the scope's kind BEFORE the prompt and every delete
+// below. Local evidence first -- remove has always worked offline, and the
+// footprint answers it for every install made by a current CLI. Only a pin
+// whose footprint is ambiguous (a pre-fingerprint mcp pin, or a skill whose
+// directory was deleted by hand) asks the registry, and if that can't answer
+// either, nothing is removed.
+async function assertInstalledKind(scope, owner, skill, lockEntry) {
+    const key = `${owner}/${skill}`;
+    const local = localInstalledKind(owner, skill, lockEntry);
+    if (local !== undefined) {
+        assertKind(scope, key, local, "remove", "remove");
+        return;
+    }
+    try {
+        await ensureRemoteKind(scope, owner, skill, "remove", "remove");
+    }
+    catch (error) {
+        if (error instanceof KindMismatchError)
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not confirm that ${key} is installed as ${describeKind(strictKind(scope))}: its local files don't say, and the registry lookup failed (${reason}). ` +
+            `Nothing was removed. Use \`ahood skill remove ${key}\` (legacy, any kind) to remove it anyway.`);
+    }
+}
 const USAGE = "Usage: ahood skill remove <owner>/<skill> [--yes]";
-export async function remove(args) {
+export async function remove(args, scope) {
     const spec = args[0];
     if (!spec)
         throw new UsageError(USAGE);
@@ -35,6 +61,8 @@ export async function remove(args) {
         process.exitCode = 1;
         return;
     }
+    if (scope && strictKind(scope) !== undefined)
+        await assertInstalledKind(scope, owner, skill, lockEntry);
     // Matches unpublish.ts/group.ts's confirm-before-destroy pattern (CLAUDE.md:
     // "Destructive commands ... prompt for confirmation unless --yes is passed").
     // Checked only once something is actually installed, so a no-op remove of an

package/dist/commands/search.js

@@ -1,15 +1,23 @@
 import { apiJson } from "../http.js";
 import { flagValue, parseSearchQuery } from "../flags.js";
 import { UsageError } from "../usage-error.js";
+import { KINDS, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill search <query> [--json] [--limit <n>]";
-export async function searchSkills(query, limit) {
+// `kind` narrows the search server-side (GET /api/v1/skills?kind=, which the
+// backend validates against its ALLOWED_KINDS). Omitted -- the legacy
+// `ahood skill search` and the MCP skill_search tool -- the request is
+// byte-for-byte what it always was: every kind.
+export async function searchSkills(query, limit, kind) {
     const qs = new URLSearchParams({ q: query });
     if (limit !== undefined)
         qs.set("per_page", String(limit));
+    if (kind !== undefined)
+        qs.set("kind", kind);
     const { skills } = await apiJson(`/api/v1/skills?${qs}`);
     return skills ?? [];
 }
-export async function search(args) {
+export async function search(args, scope) {
+    const kind = strictKind(scope);
     const jsonOutput = args.includes("--json");
     const limitStr = flagValue(args, "--limit");
     const query = parseSearchQuery(args, USAGE);
@@ -17,13 +25,13 @@ export async function search(args) {
         throw new UsageError(`--limit must be a positive integer (got "${limitStr}").\n${USAGE}`);
     }
     const limit = limitStr !== undefined ? Number(limitStr) : undefined;
-    const skills = await searchSkills(query, limit);
+    const skills = await searchSkills(query, limit, kind);
     if (jsonOutput) {
         console.log(JSON.stringify(skills));
         return;
     }
     if (skills.length === 0) {
-        console.log("No skills found.");
+        console.log(kind ? `No ${KINDS[kind].plural} found.` : "No skills found.");
         return;
     }
     for (const skill of skills) {

package/dist/commands/share.js

@@ -2,6 +2,7 @@ import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
 import { parseOwnerSkill } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.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
@@ -14,7 +15,7 @@ const UNSHARE_USAGE = "Usage: ahood skill unshare <owner>/<skill> --group <group
 // first (before any flags), since --group takes a value and a "first
 // non---flag token" scan would misidentify the --group value as the spec
 // if --group happened to come first.
-export async function share(args) {
+export async function share(args, scope) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
         throw new UsageError(SHARE_USAGE);
@@ -22,6 +23,7 @@ export async function share(args) {
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
         throw new UsageError(SHARE_USAGE);
+    await ensureRemoteKind(scope, owner, skill, "share", "share");
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -29,7 +31,7 @@ export async function share(args) {
     });
     console.log(`Shared ${owner}/${skill} with ${groupSlug}.`);
 }
-export async function unshare(args) {
+export async function unshare(args, scope) {
     const spec = args[0];
     if (!spec || spec.startsWith("--"))
         throw new UsageError(UNSHARE_USAGE);
@@ -37,6 +39,7 @@ export async function unshare(args) {
     const groupSlug = flagValue(args, "--group");
     if (!groupSlug)
         throw new UsageError(UNSHARE_USAGE);
+    await ensureRemoteKind(scope, owner, skill, "unshare", "unshare");
     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

@@ -1,21 +1,24 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
+import { ensureRemoteKind } from "../kinds.js";
 // Mirrors POST/DELETE /api/v1/skills/{owner}/{skill}/star -- both are
 // idempotent server-side (POST upserts on the stars table's
 // unique(skill_id, user_id) constraint with ignoreDuplicates, DELETE just
 // 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) {
+export async function star(args, scope) {
     const USAGE = "Usage: ahood skill star <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
+    await ensureRemoteKind(scope, owner, skill, "star", "star");
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "POST",
     });
     console.log(`Starred ${owner}/${skill}.`);
 }
-export async function unstar(args) {
+export async function unstar(args, scope) {
     const USAGE = "Usage: ahood skill unstar <owner>/<skill>";
     const { owner, skill } = parseOwnerSkill(args[0] ?? "", USAGE);
+    await ensureRemoteKind(scope, owner, skill, "unstar", "unstar");
     await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/star`, {
         method: "DELETE",
     });

package/dist/commands/unpublish.js

@@ -3,6 +3,7 @@ import { confirm } from "../confirm.js";
 import { parseOwnerSkill, parseOwnerSkillVersion } from "../spec.js";
 import { fetchVersionMeta } from "./add.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.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).
@@ -13,13 +14,15 @@ const USAGE = "Usage: ahood skill unpublish <owner>/<skill>[@version] [--yes]";
 function isVersioned(spec) {
     return spec.lastIndexOf("@") > 0;
 }
-export async function unpublish(args) {
+export async function unpublish(args, scope) {
     const yes = args.includes("--yes");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
         throw new UsageError(USAGE);
     if (isVersioned(spec)) {
         const { owner, skill, version: parsedVersion } = parseOwnerSkillVersion(spec, USAGE);
+        // Before resolving "latest", before the prompt, before the DELETE.
+        await ensureRemoteKind(scope, owner, skill, "unpublish", "yank a version of");
         // parseOwnerSkillVersion only validates *syntax* -- an omitted "@version"
         // or an explicit "@latest" both parse to the literal string "latest".
         // But the yank request below hits DELETE .../versions/{version}, which
@@ -72,6 +75,7 @@ export async function unpublish(args) {
     }
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const key = `${owner}/${skill}`;
+    await ensureRemoteKind(scope, owner, skill, "unpublish", "unpublish");
     // --yes bypasses the prompt for scripts/CI; otherwise a closed stdin (no
     // TTY, no piped answer either) now throws via confirm()'s "close" handling
     // instead of silently exiting 0 with nothing prompted, confirmed, or done.

package/dist/commands/update.js

@@ -2,10 +2,9 @@ import { LOCKFILE_PATH, parseOwnerSkill } from "../spec.js";
 import { readLockfile } from "../lockfile.js";
 import { add, fetchVersionMeta, readMcpConfig, updateMcpEntry } from "./add.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind, isCliKind, KINDS, localInstalledKind, strictKind } from "../kinds.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");
+function toPreview(ownerSlashSkill, currentVersion, meta) {
     const upToDate = currentVersion === meta.version;
     return {
         skill: ownerSlashSkill,
@@ -55,7 +54,7 @@ function padRow(cells, widths) {
 // Prints a side-by-side current/latest table for every previewed skill, then
 // -- for only the skills that actually have an update available -- the
 // changelog for the version they'd move to. Nothing here touches disk or the
-// network beyond the read-only resolution already done in previewSkill().
+// network beyond the read-only resolution already done by the caller before toPreview().
 function printDryRunTable(previews) {
     const header = ["SKILL", "CURRENT", "LATEST", "STATUS"];
     const rows = previews.map((p) => [
@@ -78,7 +77,30 @@ function printDryRunTable(previews) {
         console.log(p.changelog_md ? p.changelog_md : "(no changelog available)");
     }
 }
-export async function update(args) {
+// Kind scoping for update/outdated (ahood-cli#172). Returns true when `key`
+// should be skipped as out of scope, throws when it must be refused, and
+// returns false when it is in scope.
+//
+//   explicit target, wrong kind -> refused (counts as that entry's failure)
+//   no-arg run, wrong kind      -> silently out of scope: `ahood agent update`
+//                                  only ever considers installed agents
+//   no-arg run, kind unknown    -> skipped with a warning rather than guessed
+//                                  into (or out of) the run
+function outOfScope(scope, key, actual, implicit) {
+    const kind = strictKind(scope);
+    if (kind === undefined || actual === kind)
+        return false;
+    if (!implicit) {
+        assertKind(scope, key, actual, "update", "update");
+        return false; // unreachable: assertKind throws for every actual !== kind
+    }
+    if (!isCliKind(actual)) {
+        console.warn(`WARNING: skipping ${key} -- the registry did not report a kind ahood can match against ${KINDS[kind].plural}.`);
+    }
+    return true;
+}
+export async function update(args, scope) {
+    const kind = strictKind(scope);
     const dryRun = args.includes("--dry-run");
     const jsonOutput = args.includes("--json");
     if (jsonOutput && !dryRun) {
@@ -86,9 +108,23 @@ export async function update(args) {
     }
     const targets = args.filter((a) => a !== "--dry-run" && a !== "--json");
     const lockfile = readLockfile(LOCKFILE_PATH);
-    const skillKeys = targets.length > 0 ? targets : Object.keys(lockfile);
+    const implicit = targets.length === 0;
+    let skillKeys = implicit ? Object.keys(lockfile) : targets;
+    if (implicit && kind) {
+        // A cheap local pre-filter so a pin this project's own files already
+        // show to be another kind costs no request (and can't fail the run).
+        // Unknown footprints stay in and are settled by the registry's answer.
+        skillKeys = skillKeys.filter((key) => {
+            const parts = key.split("/");
+            if (parts.length !== 2)
+                return true; // let the loop report the bad key as before
+            const local = localInstalledKind(parts[0], parts[1], lockfile[key]);
+            return local === undefined || local === kind;
+        });
+    }
+    const noneMessage = kind ? `No installed ${KINDS[kind].plural} to update.` : "No installed skills to update.";
     if (skillKeys.length === 0) {
-        console.log("No installed skills to update.");
+        console.log(noneMessage);
         return;
     }
     if (dryRun) {
@@ -99,7 +135,11 @@ export async function update(args) {
         const failures = [];
         for (const key of skillKeys) {
             try {
-                previews.push(await previewSkill(key, lockfile[key]?.version ?? null));
+                const { owner, skill } = parseOwnerSkill(key, USAGE);
+                const meta = await fetchVersionMeta(owner, skill, "latest");
+                if (outOfScope(scope, key, meta.kind, implicit))
+                    continue;
+                previews.push(toPreview(key, lockfile[key]?.version ?? null, meta));
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -120,6 +160,7 @@ export async function update(args) {
         return;
     }
     const failures = [];
+    let inScope = 0;
     for (const ownerSlashSkill of skillKeys) {
         if (!lockfile[ownerSlashSkill]) {
             // Reachable two ways: an explicitly-named skill that was never
@@ -141,6 +182,9 @@ export async function update(args) {
             // mcp-update support) instead.
             const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
             const meta = await fetchVersionMeta(owner, skill, "latest");
+            if (outOfScope(scope, ownerSlashSkill, meta.kind, implicit))
+                continue;
+            inScope++;
             if (meta.kind === "mcp") {
                 const currentEntry = lockfile[ownerSlashSkill];
                 if (currentEntry && currentEntry.version === meta.version && mcpEntryIsIntact(skill)) {
@@ -168,7 +212,12 @@ export async function update(args) {
                 await updateMcpEntry(owner, skill, meta, currentEntry);
                 continue;
             }
-            await add([ownerSlashSkill]); // no @version -- resolves to latest again
+            // no @version -- resolves to latest again. A strict scope is passed on so
+            // add() re-checks the kind it resolves itself before writing anything.
+            if (kind)
+                await add([ownerSlashSkill], scope);
+            else
+                await add([ownerSlashSkill]);
         }
         catch (error) {
             // One skill being removed/yanked/unreachable must not stop every other
@@ -178,6 +227,9 @@ export async function update(args) {
             failures.push(ownerSlashSkill);
         }
     }
+    if (implicit && kind && inScope === 0 && failures.length === 0) {
+        console.log(noneMessage);
+    }
     if (failures.length > 0) {
         console.error(`${failures.length} of ${skillKeys.length} skill(s) failed to update: ${failures.join(", ")}`);
         process.exitCode = 1;

package/dist/commands/versions.js

@@ -1,6 +1,7 @@
 import { apiJson } from "../http.js";
 import { parseOwnerSkill } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { ensureRemoteKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill versions <owner>/<skill> [--json]";
 function formatSize(bytes) {
     if (bytes < 1024)
@@ -18,12 +19,13 @@ export async function listSkillVersions(owner, skill) {
     const { versions } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
     return versions ?? [];
 }
-export async function versions(args) {
+export async function versions(args, scope) {
     const jsonOutput = args.includes("--json");
     const spec = args.find((a) => !a.startsWith("--"));
     if (!spec)
         throw new UsageError(USAGE);
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    await ensureRemoteKind(scope, owner, skill, "versions", "list the versions of");
     const list = await listSkillVersions(owner, skill);
     if (jsonOutput) {
         console.log(JSON.stringify(list));

package/dist/commands/view.js

@@ -3,6 +3,7 @@ import { apiJson } from "../http.js";
 import { getApiUrl } from "../config.js";
 import { parseOwnerSkill } from "../spec.js";
 import { UsageError } from "../usage-error.js";
+import { assertKind, ensureRemoteKind } from "../kinds.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
@@ -26,7 +27,7 @@ function openBrowser(url) {
 export async function viewSkill(owner, skill) {
     return apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
 }
-export async function view(args) {
+export async function view(args, scope) {
     const jsonOutput = args.includes("--json");
     const web = args.includes("--web");
     const spec = args.find((a) => !a.startsWith("--"));
@@ -35,10 +36,12 @@ export async function view(args) {
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const url = `${getApiUrl()}/${owner}/${skill}`;
     if (web) {
+        await ensureRemoteKind(scope, owner, skill, "view", "open");
         openBrowser(url);
         return;
     }
     const detail = await viewSkill(owner, skill);
+    assertKind(scope, `${owner}/${skill}`, detail.kind, "view", "show");
     if (jsonOutput) {
         console.log(JSON.stringify(detail));
         return;