@rayul/kordis 0.2.0 → 0.2.2

package/dist/index.js

@@ -1172,6 +1172,8 @@ import ora from "ora";
 var jsonMode = false;
 function setJsonMode(on) {
   jsonMode = on;
+  if (on) process.env["KORDIS_JSON"] = "1";
+  else delete process.env["KORDIS_JSON"];
 }
 function isJsonMode() {
   return jsonMode;
@@ -1340,11 +1342,31 @@ function searchCommand() {
         limit: opts.limit
       });
     }
+    const queryProvided = query.length > 0;
     printDual({
       json: res,
       human: () => {
         if (res.results.length === 0) {
           printHuman(c.yellow("(no results)"));
+          if (opts.type) {
+            printHuman(
+              c.gray(
+                `  \u2192 no packages of type "${opts.type}" match. Try without --type, or list everything: kordis search --type ${opts.type} --sort recent --limit 25`
+              )
+            );
+          } else if (queryProvided) {
+            printHuman(
+              c.gray(
+                "  \u2192 try `--type skill` (or mcp-server / project-rules / custom-agent / hook) to narrow, or broader keywords"
+              )
+            );
+          } else {
+            printHuman(
+              c.gray(
+                '  \u2192 try keywords (e.g. `kordis search "topic"`) or `kordis search --trending`'
+              )
+            );
+          }
           return;
         }
         for (const p of res.results) {
@@ -1366,6 +1388,13 @@ function searchCommand() {
         if (res.next_cursor) {
           printHuman(c.gray(`(more available \u2014 pass --cursor ${res.next_cursor})`));
         }
+        if (queryProvided && !opts.type && res.results.length > 3) {
+          printHuman(
+            c.gray(
+              "  \u2192 narrow further with `--type skill|mcp-server|project-rules|custom-agent|hook`"
+            )
+          );
+        }
       }
     });
   });
@@ -1425,210 +1454,6 @@ var FrontmatterParseError = class extends Error {
   }
 };
 
-// src/commands/push.ts
-function pushCommand() {
-  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option(
-    "--slug <slug>",
-    'override slug; accepts "user/slug" to point at a specific package'
-  ).option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").action(
-    async (path, opts) => {
-      const bundle = await useClient();
-      const abs = resolve(process.cwd(), path);
-      const s = await stat(abs);
-      let content;
-      let assets = [];
-      if (s.isDirectory()) {
-        ({ content, assets } = await bundleDirectory(abs));
-        content = ensureTypeField(content, "skill");
-      } else if (abs.endsWith(".skill")) {
-        ({ content, assets } = await bundleSkillZip(abs));
-        content = ensureTypeField(content, "skill");
-      } else {
-        content = await readFile3(abs, "utf8");
-      }
-      let nameFromFm = null;
-      try {
-        const fm = parseFrontmatter(content).frontmatter ?? {};
-        const v = fm["name"];
-        if (typeof v === "string") nameFromFm = v;
-      } catch (err) {
-        throw err instanceof Error ? err : new Error(String(err));
-      }
-      let targetUser = null;
-      let targetSlug = null;
-      if (opts.slug && opts.slug.includes("/")) {
-        const [u, s2] = opts.slug.split("/", 2);
-        if (u && s2) {
-          targetUser = u;
-          targetSlug = s2;
-        }
-      } else {
-        if (bundle.username && (opts.slug || nameFromFm)) {
-          targetUser = bundle.username;
-          targetSlug = opts.slug ?? nameFromFm;
-        }
-      }
-      let targetFullSlug;
-      if (targetUser && targetSlug) {
-        try {
-          await bundle.api.getPackage(targetUser, targetSlug);
-          targetFullSlug = `${targetUser}/${targetSlug}`;
-        } catch (err) {
-          if (err instanceof KordisApiError && err.code === "not_found") {
-            targetFullSlug = void 0;
-          } else if (!(err instanceof KordisApiError)) {
-            throw err;
-          }
-        }
-      }
-      const spin = spinner(
-        opts.dryRun ? "Validating" : targetFullSlug ? `Publishing update to ${targetFullSlug}` : "Publishing"
-      );
-      const res = await bundle.authedRequest(
-        (api) => api.publish(
-          {
-            content,
-            assets: assets.length > 0 ? assets : void 0,
-            bump: opts.bump,
-            slug: opts.slug && !opts.slug.includes("/") ? opts.slug : void 0,
-            target_full_slug: targetFullSlug,
-            type: opts.type,
-            changelog: opts.changelog,
-            dry_run: !!opts.dryRun
-          },
-          {
-            waitForReviewMs: opts.wait === false ? 0 : 3e3
-          }
-        )
-      );
-      spin.succeed();
-      printDual({
-        json: res,
-        human: () => {
-          printHuman(
-            `${c.bold(res.full_slug)} ${c.gray(`v${res.version}`)} \u2192 ${res.status === "published" ? c.green("published") : res.status === "pending" ? c.yellow("pending review") : c.red("rejected")}`
-          );
-          if (assets.length > 0) {
-            printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
-          }
-          printHuman(`  ${c.cyan(res.url)}`);
-          if (res.status === "pending") {
-            printHuman(
-              c.yellow(
-                `  ! AI review is still pending \u2014 re-check with \`kordis info ${res.full_slug} --json\` for the verdict.`
-              )
-            );
-          }
-          if (res.review.flags.length > 0) {
-            printHuman(c.yellow(`  ${res.review.flags.length} review flag(s):`));
-            for (const f of res.review.flags) {
-              printHuman(c.yellow(`    - ${f.code}${f.message ? `: ${f.message}` : ""}`));
-            }
-          }
-        }
-      });
-    }
-  );
-}
-function ensureTypeField(content, defaultType) {
-  const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
-  if (!fmMatch) return content;
-  const fmBlock = fmMatch[1];
-  if (/^type\s*:/m.test(fmBlock)) return content;
-  const injected = fmMatch[0].replace(/^---\r?\n/, `---
-type: ${defaultType}
-`);
-  return content.replace(fmMatch[0], injected);
-}
-var EXCLUDE_NAMES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
-var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", ".git", "evals", "dist", ".turbo"]);
-var EXCLUDE_EXTS = /* @__PURE__ */ new Set([".pyc", ".pyo", ".rbc"]);
-function shouldExclude(relPath, isDir) {
-  const parts = relPath.split(posix.sep);
-  const name = parts[parts.length - 1];
-  if (EXCLUDE_NAMES.has(name)) return true;
-  if (isDir && EXCLUDE_DIRS.has(name)) return true;
-  const ext = name.includes(".") ? "." + name.split(".").pop() : "";
-  if (EXCLUDE_EXTS.has(ext)) return true;
-  return false;
-}
-async function walkDir(base, relDir, collected) {
-  const entries = await readdir(join4(base, relDir), { withFileTypes: true });
-  for (const entry of entries) {
-    const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
-    if (shouldExclude(rel, entry.isDirectory())) continue;
-    if (entry.isDirectory()) {
-      await walkDir(base, rel, collected);
-    } else if (entry.isFile()) {
-      collected.push({ rel, abs: join4(base, rel) });
-    }
-  }
-}
-async function readAsset(absPath) {
-  const buf = await readFile3(absPath);
-  const text = buf.toString("utf8");
-  const roundtrip = Buffer.from(text, "utf8");
-  if (roundtrip.equals(buf)) {
-    return { content: text, encoding: "utf8" };
-  }
-  const b64 = buf.toString("base64");
-  printHuman(c.gray(`  \u2192 encoding ${absPath.split(sep).pop()} as base64`));
-  return { content: b64, encoding: "base64" };
-}
-async function bundleDirectory(dir) {
-  const all = [];
-  await walkDir(dir, "", all);
-  const skillEntry = all.find((f) => f.rel === "SKILL.md");
-  if (!skillEntry) {
-    throw new Error(`No SKILL.md found in directory ${dir}. Push a directory that has SKILL.md at its root.`);
-  }
-  const content = await readFile3(skillEntry.abs, "utf8");
-  const assets = [];
-  for (const f of all) {
-    if (f.rel === "SKILL.md") continue;
-    const { content: fc, encoding } = await readAsset(f.abs);
-    assets.push({ path: f.rel, content: fc, encoding });
-  }
-  return { content, assets };
-}
-async function bundleSkillZip(zipPath) {
-  const buf = await readFile3(zipPath);
-  const zip = await JSZip.loadAsync(buf);
-  const entries = Object.keys(zip.files).filter((k) => !zip.files[k].dir);
-  if (entries.length === 0) throw new Error(".skill file is empty");
-  const firstParts = entries[0].split("/");
-  const prefix = firstParts.length > 1 ? firstParts[0] + "/" : "";
-  const stripped = entries.map((k) => ({
-    zipKey: k,
-    rel: prefix ? k.slice(prefix.length) : k
-  })).filter((f) => f.rel.length > 0 && !shouldExclude(f.rel, false));
-  const skillEntry = stripped.find((f) => f.rel === "SKILL.md");
-  if (!skillEntry) {
-    throw new Error(`.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`);
-  }
-  const content = await zip.files[skillEntry.zipKey].async("string");
-  const assets = [];
-  for (const f of stripped) {
-    if (f.rel === "SKILL.md") continue;
-    const rawBuf = await zip.files[f.zipKey].async("uint8array");
-    const buf2 = Buffer.from(rawBuf);
-    const text = buf2.toString("utf8");
-    const roundtrip = Buffer.from(text, "utf8");
-    if (roundtrip.equals(buf2)) {
-      assets.push({ path: f.rel, content: text, encoding: "utf8" });
-    } else {
-      printHuman(c.gray(`  \u2192 encoding ${f.rel} as base64`));
-      assets.push({ path: f.rel, content: buf2.toString("base64"), encoding: "base64" });
-    }
-  }
-  return { content, assets };
-}
-
-// src/commands/pull.ts
-import { Command as Command5 } from "commander";
-import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname2, join as join6 } from "path";
-
 // ../../packages/harness-schema/src/deps.ts
 init_src();
 import { z as z10 } from "zod";
@@ -2103,11 +1928,317 @@ function zodFail(issues) {
     })
   };
 }
+var ASSET_MAX_COUNT = 50;
+var SAFE_PATH_RE = /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/;
+function isAssetPathSafe(p) {
+  if (!SAFE_PATH_RE.test(p)) return false;
+  return !p.split("/").some((seg) => seg === "..");
+}
+function validateAssets(assets) {
+  const flags = [];
+  if (assets.length > ASSET_MAX_COUNT) {
+    flags.push(
+      flag("too_many_assets", `bundle has ${assets.length} files (max ${ASSET_MAX_COUNT})`, {
+        hint: `Bundle has more than ${ASSET_MAX_COUNT} files. Trim demos or move large reference material to an external Git repo.`
+      })
+    );
+    return { ok: false, flags };
+  }
+  for (const asset of assets) {
+    if (!isAssetPathSafe(asset.path)) {
+      flags.push(
+        flag("asset_path_unsafe", `unsafe asset path: "${asset.path}"`, {
+          field: "assets",
+          hint: 'Asset paths must be relative POSIX, no leading "/", no "..". Example: scripts/run.sh'
+        })
+      );
+    }
+  }
+  return { ok: flags.length === 0, flags };
+}
+
+// src/commands/push.ts
+var ASSET_MAX_BYTES = 2 * 1024 * 1024;
+var BUNDLE_MAX_BYTES = 5 * 1024 * 1024;
+function pushCommand() {
+  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option(
+    "--slug <slug>",
+    'override slug; accepts "user/slug" to point at a specific package'
+  ).option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").action(
+    async (path, opts) => {
+      const bundle = await useClient();
+      const abs = resolve(process.cwd(), path);
+      const s = await stat(abs);
+      let content;
+      let assets = [];
+      if (s.isDirectory()) {
+        ({ content, assets } = await bundleDirectory(abs));
+        content = ensureTypeField(content, "skill");
+      } else if (abs.endsWith(".skill")) {
+        ({ content, assets } = await bundleSkillZip(abs));
+        content = ensureTypeField(content, "skill");
+      } else {
+        content = await readFile3(abs, "utf8");
+      }
+      let nameFromFm = null;
+      try {
+        const fm = parseFrontmatter(content).frontmatter ?? {};
+        const v = fm["name"];
+        if (typeof v === "string") nameFromFm = v;
+      } catch (err) {
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+      if (opts.dryRun) {
+        await runDryRun({ content, assets });
+        return;
+      }
+      let targetUser = null;
+      let targetSlug = null;
+      if (opts.slug && opts.slug.includes("/")) {
+        const [u, s2] = opts.slug.split("/", 2);
+        if (u && s2) {
+          targetUser = u;
+          targetSlug = s2;
+        }
+      } else {
+        if (bundle.username && (opts.slug || nameFromFm)) {
+          targetUser = bundle.username;
+          targetSlug = opts.slug ?? nameFromFm;
+        }
+      }
+      let targetFullSlug;
+      if (targetUser && targetSlug) {
+        try {
+          await bundle.api.getPackage(targetUser, targetSlug);
+          targetFullSlug = `${targetUser}/${targetSlug}`;
+        } catch (err) {
+          if (err instanceof KordisApiError && err.code === "not_found") {
+            targetFullSlug = void 0;
+          } else if (!(err instanceof KordisApiError)) {
+            throw err;
+          }
+        }
+      }
+      const spin = spinner(
+        opts.dryRun ? "Validating" : targetFullSlug ? `Publishing update to ${targetFullSlug}` : "Publishing"
+      );
+      const res = await bundle.authedRequest(
+        (api) => api.publish(
+          {
+            content,
+            assets: assets.length > 0 ? assets : void 0,
+            bump: opts.bump,
+            slug: opts.slug && !opts.slug.includes("/") ? opts.slug : void 0,
+            target_full_slug: targetFullSlug,
+            type: opts.type,
+            changelog: opts.changelog,
+            dry_run: !!opts.dryRun
+          },
+          {
+            waitForReviewMs: opts.wait === false ? 0 : 3e3
+          }
+        )
+      );
+      spin.succeed();
+      printDual({
+        json: res,
+        human: () => {
+          printHuman(
+            `${c.bold(res.full_slug)} ${c.gray(`v${res.version}`)} \u2192 ${res.status === "published" ? c.green("published") : res.status === "pending" ? c.yellow("pending review") : c.red("rejected")}`
+          );
+          if (assets.length > 0) {
+            printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
+          }
+          printHuman(`  ${c.cyan(res.url)}`);
+          if (res.status === "pending") {
+            printHuman(
+              c.yellow(
+                `  ! AI review is still pending \u2014 re-check with \`kordis info ${res.full_slug} --json\` for the verdict.`
+              )
+            );
+          }
+          if (res.review.flags.length > 0) {
+            printHuman(c.yellow(`  ${res.review.flags.length} review flag(s):`));
+            for (const f of res.review.flags) {
+              printHuman(c.yellow(`    - ${f.code}${f.message ? `: ${f.message}` : ""}`));
+            }
+          }
+        }
+      });
+    }
+  );
+}
+function checkAssetSizesLocal(assets) {
+  const flags = [];
+  let totalBytes = 0;
+  for (const asset of assets) {
+    const byteLen = asset.encoding === "base64" ? Math.ceil(asset.content.length * 3 / 4) : Buffer.byteLength(asset.content, "utf8");
+    if (byteLen > ASSET_MAX_BYTES) {
+      flags.push({
+        code: "asset_too_large",
+        message: `asset "${asset.path}" is ${byteLen} bytes (max ${ASSET_MAX_BYTES})`,
+        hint: `Single asset exceeds the ${ASSET_MAX_BYTES / 1024 / 1024} MB per-file cap. Trim or move large fixtures to an external Git repo.`
+      });
+    }
+    totalBytes += byteLen;
+  }
+  if (totalBytes > BUNDLE_MAX_BYTES) {
+    flags.push({
+      code: "bundle_too_large",
+      message: `bundle totals ${totalBytes} bytes (max ${BUNDLE_MAX_BYTES})`,
+      hint: `Total bundle exceeds ${BUNDLE_MAX_BYTES / 1024 / 1024} MB. Remove generated artifacts; check .gitignore parity.`
+    });
+  }
+  return flags;
+}
+async function runDryRun(args) {
+  const { content, assets } = args;
+  const v = validatePackageSource(content);
+  const assetPathResult = assets.length > 0 ? validateAssets(assets) : { ok: true, flags: [] };
+  const sizeFlags = checkAssetSizesLocal(assets);
+  const allFlags = [...v.flags, ...assetPathResult.flags, ...sizeFlags];
+  const ok = v.ok && assetPathResult.ok && sizeFlags.length === 0;
+  printDual({
+    json: {
+      status: ok ? "dry_run_passed" : "dry_run_failed",
+      type: v.type,
+      tier: v.tier,
+      capabilities: v.capabilities,
+      asset_count: assets.length,
+      flags: allFlags,
+      note: "dry-run validates frontmatter + asset paths/sizes locally; AI review (real publish only) is not performed"
+    },
+    human: () => {
+      if (ok) {
+        printHuman(c.green("\u2713 dry-run validation passed"));
+        if (v.type) printHuman(c.gray(`  type: ${v.type} (tier ${v.tier})`));
+        if (v.capabilities) {
+          printHuman(
+            c.gray(
+              `  capabilities: jit_eligible=${v.capabilities.jit_eligible} executable=${v.capabilities.executable}`
+            )
+          );
+        }
+        if (assets.length > 0) printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
+        printHuman(
+          c.gray("  (AI review only runs on the real push; not performed here)")
+        );
+        return;
+      }
+      printHuman(c.red(`\u2717 dry-run validation failed (${allFlags.length} flag(s))`));
+      for (const f of allFlags) {
+        printHuman(c.red(`  - ${f.code}${f.message ? `: ${f.message}` : ""}`));
+        if (f.hint) {
+          for (const line of f.hint.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
+        }
+      }
+    }
+  });
+  if (!ok) process.exit(30);
+}
+function ensureTypeField(content, defaultType) {
+  const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  if (!fmMatch) return content;
+  const fmBlock = fmMatch[1];
+  if (/^type\s*:/m.test(fmBlock)) return content;
+  const injected = fmMatch[0].replace(/^---\r?\n/, `---
+type: ${defaultType}
+`);
+  return content.replace(fmMatch[0], injected);
+}
+var EXCLUDE_NAMES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
+var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", ".git", "evals", "dist", ".turbo"]);
+var EXCLUDE_EXTS = /* @__PURE__ */ new Set([".pyc", ".pyo", ".rbc"]);
+function shouldExclude(relPath, isDir) {
+  const parts = relPath.split(posix.sep);
+  const name = parts[parts.length - 1];
+  if (EXCLUDE_NAMES.has(name)) return true;
+  if (isDir && EXCLUDE_DIRS.has(name)) return true;
+  const ext = name.includes(".") ? "." + name.split(".").pop() : "";
+  if (EXCLUDE_EXTS.has(ext)) return true;
+  return false;
+}
+async function walkDir(base, relDir, collected) {
+  const entries = await readdir(join4(base, relDir), { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+    if (shouldExclude(rel, entry.isDirectory())) continue;
+    if (entry.isDirectory()) {
+      await walkDir(base, rel, collected);
+    } else if (entry.isFile()) {
+      collected.push({ rel, abs: join4(base, rel) });
+    }
+  }
+}
+async function readAsset(absPath) {
+  const buf = await readFile3(absPath);
+  const text = buf.toString("utf8");
+  const roundtrip = Buffer.from(text, "utf8");
+  if (roundtrip.equals(buf)) {
+    return { content: text, encoding: "utf8" };
+  }
+  const b64 = buf.toString("base64");
+  printHuman(c.gray(`  \u2192 encoding ${absPath.split(sep).pop()} as base64`));
+  return { content: b64, encoding: "base64" };
+}
+async function bundleDirectory(dir) {
+  const all = [];
+  await walkDir(dir, "", all);
+  const skillEntry = all.find((f) => f.rel === "SKILL.md");
+  if (!skillEntry) {
+    throw new Error(`No SKILL.md found in directory ${dir}. Push a directory that has SKILL.md at its root.`);
+  }
+  const content = await readFile3(skillEntry.abs, "utf8");
+  const assets = [];
+  for (const f of all) {
+    if (f.rel === "SKILL.md") continue;
+    const { content: fc, encoding } = await readAsset(f.abs);
+    assets.push({ path: f.rel, content: fc, encoding });
+  }
+  return { content, assets };
+}
+async function bundleSkillZip(zipPath) {
+  const buf = await readFile3(zipPath);
+  const zip = await JSZip.loadAsync(buf);
+  const entries = Object.keys(zip.files).filter((k) => !zip.files[k].dir);
+  if (entries.length === 0) throw new Error(".skill file is empty");
+  const firstParts = entries[0].split("/");
+  const prefix = firstParts.length > 1 ? firstParts[0] + "/" : "";
+  const stripped = entries.map((k) => ({
+    zipKey: k,
+    rel: prefix ? k.slice(prefix.length) : k
+  })).filter((f) => f.rel.length > 0 && !shouldExclude(f.rel, false));
+  const skillEntry = stripped.find((f) => f.rel === "SKILL.md");
+  if (!skillEntry) {
+    throw new Error(`.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`);
+  }
+  const content = await zip.files[skillEntry.zipKey].async("string");
+  const assets = [];
+  for (const f of stripped) {
+    if (f.rel === "SKILL.md") continue;
+    const rawBuf = await zip.files[f.zipKey].async("uint8array");
+    const buf2 = Buffer.from(rawBuf);
+    const text = buf2.toString("utf8");
+    const roundtrip = Buffer.from(text, "utf8");
+    if (roundtrip.equals(buf2)) {
+      assets.push({ path: f.rel, content: text, encoding: "utf8" });
+    } else {
+      printHuman(c.gray(`  \u2192 encoding ${f.rel} as base64`));
+      assets.push({ path: f.rel, content: buf2.toString("base64"), encoding: "base64" });
+    }
+  }
+  return { content, assets };
+}
+
+// src/commands/pull.ts
+import { Command as Command5 } from "commander";
+import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname2, join as join6 } from "path";
 
 // ../../packages/translators/src/skill/identity.ts
 function buildSkillFile(input, outputPath) {
   const body = input.body.trimStart();
-  const fm = input.frontmatter;
+  const fm = input.frontmatter["version"] === void 0 && input.version ? { ...input.frontmatter, version: input.version } : input.frontmatter;
   const name = typeof fm["name"] === "string" ? fm["name"] : input.fullSlug.split("/")[1];
   const frontmatter = ["---"];
   for (const [k, v] of Object.entries(fm)) {
@@ -3288,6 +3419,11 @@ function outdatedCommand() {
         const outdatedCount = entries.filter((e) => e.outdated).length;
         if (outdatedCount === 0) {
           printHuman(c.green(`\u2713 All ${entries.length} package${entries.length !== 1 ? "s" : ""} are up to date`));
+          printHuman(
+            c.gray(
+              "  \u2192 bundled Kordis sub-skills update with the CLI: `npm i -g @rayul/kordis@latest`"
+            )
+          );
           return;
         }
         printHuman(
@@ -3303,6 +3439,11 @@ function outdatedCommand() {
         }
         printHuman("");
         printHuman(c.gray("Run `kordis update` to upgrade all outdated packages."));
+        printHuman(
+          c.gray(
+            "  \u2192 only `kordis pull`-installed packages are tracked here. Bundled sub-skills update via `npm i -g @rayul/kordis@latest`."
+          )
+        );
       }
     });
   });
@@ -3493,6 +3634,11 @@ function diffCommand() {
         printHuman("");
         if (!diff.unified_diff) {
           printHuman(c.dim("(no content changes between these versions)"));
+          printHuman(
+            c.dim(
+              "  \u2192 likely a metadata-only bump: description, deps, license, or version field"
+            )
+          );
           return;
         }
         for (const line of diff.unified_diff.split("\n")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",