skillpass 0.1.0 → 0.3.0

package/dist/{cli.mjs → cli.js}

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // src/index.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 import { createInterface } from "node:readline/promises";
 
 // ../../node_modules/.pnpm/fflate@0.8.3/node_modules/fflate/esm/index.mjs
@@ -493,16 +493,16 @@ function unzipSync(data, opts) {
 
 // src/add.ts
 import {
-  existsSync,
-  mkdirSync,
-  readdirSync as readdirSync2,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readdirSync as readdirSync3,
   renameSync,
   rmdirSync,
   rmSync,
-  statSync as statSync2,
-  writeFileSync
+  statSync as statSync3,
+  writeFileSync as writeFileSync2
 } from "node:fs";
-import { dirname, isAbsolute, join as join3, resolve } from "node:path";
+import { dirname, isAbsolute, join as join4, resolve as resolve2 } from "node:path";
 
 // ../validator/src/load.ts
 import { createHash } from "node:crypto";
@@ -15281,10 +15281,10 @@ function parseManifest(input) {
 }
 
 // ../skill-schema/src/report.ts
-var reportFindingSchema = external_exports.strictObject({
+var reportFindingSchema = external_exports.object({
   code: external_exports.string().min(1),
   message: external_exports.string().min(1),
-  location: external_exports.strictObject({
+  location: external_exports.object({
     path: external_exports.string().min(1),
     line: external_exports.number().int().positive().optional(),
     snippet: external_exports.string().optional()
@@ -15313,11 +15313,11 @@ var validationReportSchema = external_exports.strictObject({
 });
 
 // ../skill-schema/src/passport.ts
-var skillPassportSchema = external_exports.strictObject({
+var skillPassportSchema = external_exports.object({
   schemaVersion: external_exports.literal("0.1"),
   validationStatus: validationStatusSchema,
   riskLevel: riskLevelSchema,
-  permissionsSummary: external_exports.strictObject({
+  permissionsSummary: external_exports.object({
     declared: external_exports.array(permissionKeySchema),
     detected: external_exports.array(permissionKeySchema)
   }),
@@ -15338,7 +15338,7 @@ var skillPassportSchema = external_exports.strictObject({
 
 // ../skill-schema/src/ai-review.ts
 var aiReviewVerdictSchema = external_exports.enum(["clear", "caution", "concern"]);
-var aiReviewSchema = external_exports.strictObject({
+var aiReviewSchema = external_exports.object({
   summary: external_exports.string().min(1).max(600),
   verdict: aiReviewVerdictSchema,
   reasoning: external_exports.string().min(1).max(800),
@@ -15390,9 +15390,14 @@ var publishResultSchema = external_exports.object({
   slug: external_exports.string().min(1),
   version: external_exports.string().min(1)
 });
+var MAX_SLUG_LENGTH = 60;
+function slugForSkill(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, MAX_SLUG_LENGTH).replace(/-+$/, "");
+  return slug || "skill";
+}
 
 // ../skill-schema/src/public.ts
-var publicSkillSummarySchema = external_exports.strictObject({
+var publicSkillSummarySchema = external_exports.object({
   slug: external_exports.string().min(1),
   name: external_exports.string().min(1),
   summary: external_exports.string().min(1),
@@ -15422,7 +15427,7 @@ var publicSkillSummarySchema = external_exports.strictObject({
   publishedAt: external_exports.iso.datetime()
 });
 var publicSkillListSchema = external_exports.array(publicSkillSummarySchema);
-var publicSkillVersionSchema = external_exports.strictObject({
+var publicSkillVersionSchema = external_exports.object({
   version: external_exports.string().min(1),
   validationStatus: validationStatusSchema,
   riskLevel: riskLevelSchema,
@@ -15431,10 +15436,10 @@ var publicSkillVersionSchema = external_exports.strictObject({
 var publicSkillDetailSchema = publicSkillSummarySchema.extend({
   // Full member entries (incl. per-target variants) for a pack; the CLI's
   // per-target install resolution reads exactly this. Null for single skills.
-  packMembers: external_exports.array(skillEntrySchema).nullable().optional(),
+  packMembers: external_exports.array(external_exports.object(skillEntrySchema.shape)).nullable().optional(),
   githubRepoUrl: external_exports.string().min(1).nullable(),
   passport: skillPassportSchema,
-  maintainerInfo: external_exports.strictObject({
+  maintainerInfo: external_exports.object({
     username: external_exports.string().min(1),
     displayName: external_exports.string().min(1),
     avatarUrl: external_exports.string().min(1)
@@ -15443,18 +15448,18 @@ var publicSkillDetailSchema = publicSkillSummarySchema.extend({
   // The cached AI review for this version's source hash; null until generated.
   aiReview: aiReviewSchema.nullable()
 });
-var publicSkillSourceSchema = external_exports.strictObject({
+var publicSkillSourceSchema = external_exports.object({
   version: external_exports.string().min(1),
   sourceHash: external_exports.string().min(1),
-  files: external_exports.array(external_exports.strictObject({ path: external_exports.string().min(1), content: external_exports.string() }))
+  files: external_exports.array(external_exports.object({ path: external_exports.string().min(1), content: external_exports.string() }))
 });
 
 // ../skill-schema/src/preflight.ts
-var permissionSetDiffSchema = external_exports.strictObject({
+var permissionSetDiffSchema = external_exports.object({
   added: external_exports.array(permissionKeySchema),
   removed: external_exports.array(permissionKeySchema)
 });
-var publicPreflightSchema = external_exports.strictObject({
+var publicPreflightSchema = external_exports.object({
   version: external_exports.string().min(1),
   validationStatus: validationStatusSchema,
   riskLevel: riskLevelSchema,
@@ -15462,11 +15467,11 @@ var publicPreflightSchema = external_exports.strictObject({
   sourceVerified: external_exports.boolean(),
   resolvedCommitSha: external_exports.string().min(1).nullable(),
   generatedAt: external_exports.iso.datetime(),
-  permissions: external_exports.strictObject({
+  permissions: external_exports.object({
     declared: external_exports.array(permissionKeySchema),
     detected: external_exports.array(permissionKeySchema)
   }),
-  diff: external_exports.strictObject({
+  diff: external_exports.object({
     previousVersion: external_exports.string().min(1),
     declared: permissionSetDiffSchema,
     detected: permissionSetDiffSchema
@@ -15546,6 +15551,39 @@ var resolveReportInputSchema = external_exports.strictObject({
   status: external_exports.enum(["reviewed", "actioned"])
 });
 
+// ../skill-schema/src/maintainer.ts
+var SKILL_STATUSES = ["published", "draft", "private", "flagged"];
+var skillStatusSchema = external_exports.enum(SKILL_STATUSES);
+var maintainerSkillSchema = external_exports.strictObject({
+  slug: external_exports.string().min(1),
+  name: external_exports.string().min(1),
+  status: skillStatusSchema,
+  version: external_exports.string().nullable(),
+  validationStatus: validationStatusSchema.nullable(),
+  riskLevel: riskLevelSchema.nullable(),
+  updatedAt: external_exports.iso.datetime()
+});
+var maintainerReportSchema = external_exports.strictObject({
+  id: external_exports.number().int().positive(),
+  skill: external_exports.strictObject({ slug: external_exports.string(), name: external_exports.string() }),
+  reason: external_exports.string(),
+  status: abuseReportStatusSchema,
+  createdAt: external_exports.iso.datetime()
+});
+
+// ../skill-schema/src/user.ts
+var USER_ROLES = ["user", "maintainer", "admin"];
+var userRoleSchema = external_exports.enum(USER_ROLES);
+var publicUserSchema = external_exports.object({
+  id: external_exports.number().int().positive(),
+  username: external_exports.string().min(1),
+  displayName: external_exports.string().min(1),
+  avatarUrl: external_exports.string().min(1),
+  role: userRoleSchema,
+  reputation: external_exports.number().int(),
+  createdAt: external_exports.iso.datetime()
+});
+
 // ../validator/src/rules/permissions.ts
 var PERMISSION_SIGNALS = [
   {
@@ -15600,24 +15638,30 @@ var PERMISSION_SIGNALS = [
   }
 ];
 function detectPermissions(files) {
-  const detected = /* @__PURE__ */ new Map();
+  const detected = /* @__PURE__ */ new Set();
   for (const file2 of files) {
-    file2.content.split("\n").forEach((line, i2) => {
+    for (const line of file2.content.split("\n")) {
       for (const signal of PERMISSION_SIGNALS) {
         if (!detected.has(signal.permission) && signal.pattern.test(line)) {
-          detected.set(signal.permission, {
-            permission: signal.permission,
-            description: signal.description,
-            location: { path: file2.path, line: i2 + 1, snippet: line.trim() }
-          });
+          detected.add(signal.permission);
         }
       }
-    });
+    }
   }
-  return [...detected.values()];
+  return [...detected];
 }
 
 // ../validator/src/load.ts
+var NUL_SCAN_BYTES = 8e3;
+function isBinary(bytes) {
+  if (bytes.subarray(0, NUL_SCAN_BYTES).includes(0)) return true;
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return false;
+  } catch {
+    return true;
+  }
+}
 var PackageReadError = class extends Error {
   constructor(dir, cause) {
     super(`cannot read skill package at "${dir}"`, { cause });
@@ -15626,19 +15670,23 @@ var PackageReadError = class extends Error {
 };
 var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
 function walk(root, rel = "") {
-  const files = [];
+  const tree = { files: [], binaries: [] };
   for (const name of readdirSync(join(root, rel)).sort()) {
     const relPath = rel === "" ? name : `${rel}/${name}`;
     const stats = statSync(join(root, relPath));
     if (stats.isDirectory()) {
       if (!SKIP_DIRS.has(name)) {
-        files.push(...walk(root, relPath));
+        const sub = walk(root, relPath);
+        tree.files.push(...sub.files);
+        tree.binaries.push(...sub.binaries);
       }
     } else {
-      files.push({ path: relPath, content: readFileSync(join(root, relPath), "utf8") });
+      const bytes = readFileSync(join(root, relPath));
+      if (isBinary(bytes)) tree.binaries.push(relPath);
+      else tree.files.push({ path: relPath, content: bytes.toString("utf8") });
     }
   }
-  return files;
+  return tree;
 }
 function hashFiles(files) {
   const hash2 = createHash("sha256");
@@ -15665,7 +15713,7 @@ function readManifest(files) {
   if (!result.success) {
     return { state: "invalid", error: result.error };
   }
-  return { state: "ok", data: result.data, raw: file2.content };
+  return { state: "ok", data: result.data };
 }
 var FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
 function readSkillMeta(content) {
@@ -15690,19 +15738,43 @@ function readSkillMeta(content) {
         const text = block[1] === ">" ? gathered.join(" ").replace(/\s+/g, " ").trim() : gathered.join("\n").trim();
         if (text) out[key] = text;
       } else {
-        out[key] = kv[2].replace(/^["']|["']$/g, "");
+        const parts = [kv[2]];
+        for (let j = i2 + 1; j < lines.length && /^\s+\S/.test(lines[j]); j++) parts.push(lines[j].trim());
+        out[key] = parts.join(" ").replace(/^["']|["']$/g, "");
       }
     }
   }
   if (!out.description) {
-    const prose = body.split("\n").map((line) => line.trim()).find((line) => line && !line.startsWith("#"));
-    if (prose) out.description = prose.slice(0, 200);
+    const prose = firstParagraph(body);
+    if (prose) out.description = prose;
   }
   return out;
 }
-function slugify2(value) {
-  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug || "skill";
+var HTML_TAG_RE = /<\/?[a-zA-Z][^>]*>/g;
+var MD_LINK_RE = /\[([^\]]*)\]\([^)]*\)/g;
+var STRUCTURAL_LINE_RE = /^(#|!\[|\[!\[|---$|\*\*\*$|___$)|^<h[1-6][\s>]/i;
+var DESCRIPTION_MAX = 200;
+var cleanInline = (line) => line.replace(HTML_TAG_RE, " ").replace(MD_LINK_RE, "$1").replace(/^>\s?/, "").replace(/\s+/g, " ").trim();
+function clip(text, max2) {
+  if (text.length <= max2) return text;
+  const head = text.slice(0, max2);
+  const sentenceEnd = Math.max(head.lastIndexOf(". "), head.lastIndexOf("! "), head.lastIndexOf("? "));
+  if (sentenceEnd >= 60) return head.slice(0, sentenceEnd + 1);
+  const wordEnd = head.lastIndexOf(" ");
+  return (wordEnd > 0 ? head.slice(0, wordEnd) : head).replace(/[,;:]+$/, "").trim();
+}
+function firstParagraph(text) {
+  const kept = [];
+  for (const raw of text.split("\n")) {
+    const source = raw.trim();
+    const line = STRUCTURAL_LINE_RE.test(source) ? "" : cleanInline(source);
+    if (!line) {
+      if (kept.length > 0) break;
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.length > 0 ? clip(kept.join(" "), DESCRIPTION_MAX) : void 0;
 }
 function inferTargets(files) {
   const targets = /* @__PURE__ */ new Set();
@@ -15715,8 +15787,8 @@ function inferTargets(files) {
 function inferManifest(files, fallbackName) {
   const skillFile = files.find((f) => f.path === "SKILL.md");
   const meta3 = skillFile ? readSkillMeta(skillFile.content) : {};
-  const name = slugify2(meta3.name ?? fallbackName);
-  const permissions = [...new Set(detectPermissions(files).map((d) => d.permission))];
+  const name = slugForSkill(meta3.name ?? fallbackName);
+  const permissions = detectPermissions(files);
   return {
     schemaVersion: "0.1",
     name,
@@ -15751,11 +15823,7 @@ function collectMemberFiles(files) {
 }
 function readmeProse(files) {
   const readme = files.find((f) => f.path === "README.md");
-  if (!readme) return void 0;
-  const prose = readme.content.split("\n").map((line) => line.trim()).find(
-    (line) => line && !line.startsWith("#") && !line.startsWith("![") && !line.startsWith("[![") && !line.startsWith("<")
-  );
-  return prose?.slice(0, 200);
+  return readme ? firstParagraph(readme.content) : void 0;
 }
 function inferNestedManifest(files, fallbackName) {
   const members = collectMemberFiles(files).sort(
@@ -15770,8 +15838,8 @@ function inferNestedManifest(files, fallbackName) {
     const entryPath = member.claudePath ?? member.agentsPath ?? member.plainPath;
     const file2 = files.find((f) => f.path === entryPath);
     const meta3 = readSkillMeta(file2.content);
-    let entryName = slugify2(meta3.name ?? member.folder);
-    if (used.has(entryName)) entryName = slugify2(member.folder);
+    let entryName = slugForSkill(meta3.name ?? member.folder);
+    if (used.has(entryName)) entryName = slugForSkill(member.folder);
     used.add(entryName);
     const targets = member.plainPath ? inferTargets(files) : [
       ...member.claudePath ? ["claude-code"] : [],
@@ -15787,10 +15855,10 @@ function inferNestedManifest(files, fallbackName) {
     };
   });
   const single = entries.length === 1 ? entries[0] : null;
-  const permissions = [...new Set(detectPermissions(files).map((d) => d.permission))];
+  const permissions = detectPermissions(files);
   return {
     schemaVersion: "0.1",
-    name: single ? single.name : slugify2(fallbackName),
+    name: single ? single.name : slugForSkill(fallbackName),
     description: single ? single.description ?? single.name : readmeProse(files) ?? `A pack of ${entries.length} skills`,
     targets: [...packTargets],
     permissions,
@@ -15820,82 +15888,33 @@ function resolveEntries(dir, manifest, files) {
   ]);
 }
 var byPath = (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
-function loadPackageFromFiles(files, name = "package") {
+function loadPackageFromFiles(files, name = "package", binaries = []) {
   const sorted = [...files].sort(byPath);
   let manifest = readManifest(sorted);
   if (manifest.state === "missing") {
     const data = sorted.some((f) => f.path === "SKILL.md") ? inferManifest(sorted, name) : inferNestedManifest(sorted, name);
     if (data) {
-      manifest = { state: "ok", inferred: true, data, raw: JSON.stringify(data, null, 2) };
+      manifest = { state: "ok", inferred: true, data };
     }
   }
   return {
-    dir: name,
     files: sorted,
     manifest,
     entries: resolveEntries(name, manifest, sorted),
-    sourceHash: hashFiles(sorted)
+    sourceHash: hashFiles(sorted),
+    binaries
   };
 }
 function loadPackage(dir) {
-  let files;
+  let tree;
   try {
-    files = walk(dir);
+    tree = walk(dir);
   } catch (err2) {
     throw new PackageReadError(dir, err2);
   }
-  return loadPackageFromFiles(files, dir);
+  return loadPackageFromFiles(tree.files, dir, tree.binaries);
 }
 
-// ../validator/src/rules/structure.ts
-var structureRule = (pkg) => {
-  if (pkg.files.length === 0) {
-    return [
-      {
-        severity: "failure",
-        code: "empty-package",
-        message: "the package contains no files"
-      }
-    ];
-  }
-  const findings = [];
-  if (pkg.manifest.state === "missing") {
-    findings.push({
-      severity: "warning",
-      code: "missing-manifest",
-      message: "no skill.json manifest; permissions and targets are undeclared"
-    });
-  } else if (pkg.manifest.state === "invalid") {
-    findings.push({
-      severity: "failure",
-      code: "invalid-manifest",
-      message: `skill.json is invalid: ${pkg.manifest.error}`,
-      location: { path: "skill.json" }
-    });
-  }
-  for (const entry of pkg.entries) {
-    if (!entry.exists) {
-      findings.push({
-        severity: "failure",
-        code: "missing-skill-file",
-        message: `skill "${entry.skillName}" references "${entry.path}", which does not exist`,
-        location: { path: entry.path }
-      });
-    } else {
-      const file2 = pkg.files.find((f) => f.path === entry.path);
-      if (file2 !== void 0 && file2.content.trim() === "") {
-        findings.push({
-          severity: "failure",
-          code: "missing-skill-file",
-          message: `skill "${entry.skillName}" entry "${entry.path}" is empty`,
-          location: { path: entry.path }
-        });
-      }
-    }
-  }
-  return findings;
-};
-
 // ../validator/src/rules/content.ts
 var SECRET_PATTERNS = [
   {
@@ -16037,28 +16056,113 @@ var ALL_ROWS = [
   ...advisory(MALWARE_PATTERNS),
   ...advisory(CREDENTIAL_PATTERNS)
 ];
+var DOCUMENTED_PLACEHOLDERS = ["AKIAIOSFODNN7EXAMPLE", "AKIAI44QH8DHBEXAMPLE"];
+var withoutPlaceholders = (line) => DOCUMENTED_PLACEHOLDERS.reduce((l, p) => l.replaceAll(p, " "), line);
+var REDACTIONS = ALL_ROWS.filter((row2) => row2.redact).map(
+  (row2) => new RegExp(row2.pattern.source, `${row2.pattern.flags}g`)
+);
+var redactLine = (line) => REDACTIONS.reduce((l, re) => l.replace(re, "[redacted]"), line);
 var contentRule = (pkg) => {
   const findings = [];
   for (const file2 of pkg.files) {
-    file2.content.split("\n").forEach((line, i2) => {
-      for (const row2 of ALL_ROWS) {
-        if (row2.pattern.test(line)) {
-          const snippet = row2.redact ? line.trim().replace(row2.pattern, "[redacted]") : line.trim();
-          findings.push({
-            severity: row2.severity ?? "failure",
-            code: row2.code,
-            message: row2.message,
-            location: { path: file2.path, line: i2 + 1, snippet }
-          });
-        }
+    file2.content.split("\n").forEach((rawLine, i2) => {
+      const line = withoutPlaceholders(rawLine);
+      const hits = ALL_ROWS.filter((row2) => row2.pattern.test(line));
+      if (hits.length === 0) return;
+      const snippet = redactLine(line).trim();
+      for (const row2 of hits) {
+        findings.push({
+          severity: row2.severity ?? "failure",
+          code: row2.code,
+          message: row2.message,
+          location: { path: file2.path, line: i2 + 1, snippet }
+        });
+      }
+    });
+  }
+  return findings;
+};
+
+// ../validator/src/rules/structure.ts
+var structureRule = (pkg) => {
+  if (pkg.files.length === 0) {
+    return [
+      {
+        severity: "failure",
+        code: "empty-package",
+        message: "the package contains no files"
       }
+    ];
+  }
+  const findings = [];
+  if (pkg.manifest.state === "missing") {
+    findings.push({
+      severity: "warning",
+      code: "missing-manifest",
+      message: "no skill.json manifest; permissions and targets are undeclared"
+    });
+  } else if (pkg.manifest.state === "invalid") {
+    findings.push({
+      severity: "failure",
+      code: "invalid-manifest",
+      message: `skill.json is invalid: ${pkg.manifest.error}`,
+      location: { path: "skill.json" }
+    });
+  }
+  for (const path of pkg.binaries) {
+    findings.push({
+      severity: "warning",
+      code: "binary-dropped",
+      message: `"${path}" is not a text file and was left out of the snapshot; installs will not include it`,
+      location: { path }
     });
   }
+  for (const entry of pkg.entries) {
+    if (!entry.exists) {
+      findings.push({
+        severity: "failure",
+        code: "missing-skill-file",
+        message: `skill "${entry.skillName}" references "${entry.path}", which does not exist`,
+        location: { path: entry.path }
+      });
+    } else {
+      const file2 = pkg.files.find((f) => f.path === entry.path);
+      if (file2 !== void 0 && file2.content.trim() === "") {
+        findings.push({
+          severity: "failure",
+          code: "missing-skill-file",
+          message: `skill "${entry.skillName}" entry "${entry.path}" is empty`,
+          location: { path: entry.path }
+        });
+      }
+    }
+  }
   return findings;
 };
 
+// ../validator/package.json
+var package_default = {
+  name: "validator",
+  version: "0.3.0",
+  private: true,
+  type: "module",
+  exports: {
+    ".": "./src/index.ts"
+  },
+  scripts: {
+    typecheck: "tsc --noEmit"
+  },
+  dependencies: {
+    "skill-schema": "workspace:*"
+  },
+  devDependencies: {
+    "@types/node": "^22.0.0",
+    typescript: "^6.0.3"
+  }
+};
+
 // ../validator/src/validate.ts
-var ENGINE_VERSION = "0.3.0";
+var ENGINE_VERSION = package_default.version;
 var RULES = [
   { key: "structure", label: "Check package structure", run: structureRule },
   { key: "content", label: "Scan content for risky patterns", run: contentRule }
@@ -16070,7 +16174,7 @@ function toReportFindings(findings) {
 }
 function buildReport(pkg, findings, opts = {}) {
   const declared = pkg.manifest.state === "ok" ? pkg.manifest.data.permissions : [];
-  const detected = detectPermissions(pkg.files).map((d) => d.permission).sort();
+  const detected = [...detectPermissions(pkg.files)].sort();
   const status = findings.some((f) => f.severity === "failure") ? "failed" : findings.some((f) => f.severity === "warning") ? "warning" : "passed";
   const report = {
     schemaVersion: "0.1",
@@ -16103,7 +16207,8 @@ async function validatePackage(dir, opts = {}) {
 // src/api.ts
 var DEFAULT_API_URL = "https://api.skillpass.dev";
 function resolveApiUrl(override) {
-  return (override ?? process.env.SKILLPASS_API ?? DEFAULT_API_URL).replace(/\/$/, "");
+  const url2 = override ?? process.env.SKILLPASS_API;
+  return (url2 || DEFAULT_API_URL).replace(/\/$/, "");
 }
 function parseSkillRef(ref) {
   const at = ref.indexOf("@");
@@ -16159,6 +16264,52 @@ async function fetchPreflight(fetchImpl, apiUrl, ref) {
   return { ok: true, slug, detail: detail.data, preflight: preflight.data };
 }
 
+// src/install.ts
+import { existsSync, readdirSync as readdirSync2, statSync as statSync2 } from "node:fs";
+var GLOBAL_NEEDS_TARGET = "error: --global needs --target (e.g. --target claude-code)";
+var TARGET_OR_DIR = "error: pass --target or --dir, not both";
+function createOutput(emit) {
+  const lines = [];
+  const streamed = emit !== void 0;
+  const push = (...next) => {
+    lines.push(...next);
+    if (next.length > 0) emit?.(next.join("\n"));
+  };
+  const done = (exitCode) => ({ lines, exitCode, streamed });
+  return { push, done };
+}
+function isOccupied(path) {
+  return existsSync(path) && (!statSync2(path).isDirectory() || readdirSync2(path).length > 0);
+}
+function receiptFor(preflight, packSlug) {
+  return {
+    version: preflight.version,
+    sourceHash: preflight.sourceHash,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...packSlug ? { pack: { slug: packSlug, version: preflight.version } } : {}
+  };
+}
+function memberFiles(files, sourceDir) {
+  if (sourceDir === ".") {
+    return files;
+  }
+  const prefix = `${sourceDir}/`;
+  return files.filter((f) => f.path.startsWith(prefix)).map((f) => ({ path: f.path.slice(prefix.length), content: f.content }));
+}
+function planMembers(installs, files) {
+  return installs.map((m) => ({ ...m, files: memberFiles(files, m.sourceDir) }));
+}
+async function confirmRisk(preflight, opts, question, abortLine, push) {
+  if (preflight.riskLevel === "low" || opts.yes) return true;
+  if (!opts.confirmImpl) {
+    push("", `error: a ${preflight.riskLevel}-risk skill needs confirmation; rerun with --yes`);
+    return false;
+  }
+  if (await opts.confirmImpl(question)) return true;
+  push("", abortLine);
+  return false;
+}
+
 // src/pack.ts
 import { posix } from "node:path";
 function resolvePackMembers(members, target) {
@@ -16177,6 +16328,53 @@ function resolvePackMembers(members, target) {
   return { installs, skipped };
 }
 
+// src/receipts.ts
+import { mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+var RECEIPT_FILE = ".skillpass.json";
+function looksLikeReceipt(value) {
+  return typeof value === "object" && value !== null && typeof value.version === "string" && typeof value.sourceHash === "string";
+}
+function readReceipts(areaDir) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(join2(areaDir, RECEIPT_FILE), "utf8"));
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return {};
+  }
+  const index = {};
+  for (const [slug, receipt] of Object.entries(parsed)) {
+    if (looksLikeReceipt(receipt)) {
+      index[slug] = receipt;
+    }
+  }
+  return index;
+}
+function writeReceipts(areaDir, index) {
+  try {
+    mkdirSync(areaDir, { recursive: true });
+    writeFileSync(join2(areaDir, RECEIPT_FILE), `${JSON.stringify(index, null, "	")}
+`);
+  } catch {
+  }
+}
+function recordReceipt(areaDir, slug, receipt) {
+  const index = readReceipts(areaDir);
+  index[slug] = receipt;
+  writeReceipts(areaDir, index);
+}
+function removeReceipt(areaDir, slug) {
+  const index = readReceipts(areaDir);
+  if (!(slug in index)) {
+    return;
+  }
+  delete index[slug];
+  writeReceipts(areaDir, index);
+}
+
 // src/style.ts
 var wrap = (open, close) => (text) => `\x1B[${open}m${text}\x1B[${close}m`;
 var ANSI = {
@@ -16285,11 +16483,11 @@ function renderDiff(diff) {
 
 // src/targets.ts
 import { homedir } from "node:os";
-import { join as join2 } from "node:path";
+import { join as join3, resolve } from "node:path";
 function installAreas(home = homedir()) {
   return {
-    "claude-code": { project: join2(".claude", "skills"), global: join2(home, ".claude", "skills") },
-    codex: { project: join2(".agents", "skills") }
+    "claude-code": { project: join3(".claude", "skills"), global: join3(home, ".claude", "skills") },
+    codex: { project: join3(".agents", "skills") }
   };
 }
 var MAPPED_TARGETS = Object.keys(installAreas());
@@ -16320,11 +16518,31 @@ function resolveTargetArea(target, global = false, home) {
 }
 function resolveTargetDir(target, slug, global = false, home) {
   const area = resolveTargetArea(target, global, home);
-  return area.ok ? { ok: true, dir: join2(area.dir, slug) } : area;
+  return area.ok ? { ok: true, dir: join3(area.dir, slug) } : area;
 }
 function mappableDeclaredTargets(declared) {
   return declared.filter((t) => MAPPED_TARGETS.includes(t));
 }
+function knownAreas(cwd, home) {
+  const areas = [];
+  const byTarget = installAreas(home);
+  for (const tool of MAPPED_TARGETS) {
+    const area = byTarget[tool];
+    if (!area) {
+      continue;
+    }
+    areas.push({
+      tool,
+      global: false,
+      label: `${tool} project (${area.project})`,
+      dir: resolve(cwd, area.project)
+    });
+    if (area.global) {
+      areas.push({ tool, global: true, label: `${tool} user (${area.global})`, dir: area.global });
+    }
+  }
+  return areas;
+}
 
 // src/add.ts
 function unsafeEntryPath(path) {
@@ -16391,12 +16609,12 @@ function writeTree(files, target) {
   const tempDir = `${target}.tmp-${process.pid}`;
   try {
     for (const file2 of files) {
-      const filePath = join3(tempDir, file2.path);
-      mkdirSync(dirname(filePath), { recursive: true });
-      writeFileSync(filePath, file2.content);
+      const filePath = join4(tempDir, file2.path);
+      mkdirSync2(dirname(filePath), { recursive: true });
+      writeFileSync2(filePath, file2.content);
     }
-    mkdirSync(dirname(target), { recursive: true });
-    if (existsSync(target)) {
+    mkdirSync2(dirname(target), { recursive: true });
+    if (existsSync2(target)) {
       rmdirSync(target);
     }
     renameSync(tempDir, target);
@@ -16405,13 +16623,6 @@ function writeTree(files, target) {
     throw err2;
   }
 }
-function memberFiles(files, sourceDir) {
-  if (sourceDir === ".") {
-    return files;
-  }
-  const prefix = `${sourceDir}/`;
-  return files.filter((f) => f.path.startsWith(prefix)).map((f) => ({ path: f.path.slice(prefix.length), content: f.content }));
-}
 function installChoices(declared, slug) {
   const choices = [];
   const ordered = [
@@ -16463,209 +16674,117 @@ function packChoices(declared, slug, count) {
   choices.push({ label: `current directory (./${slug}, raw pack source)` });
   return choices;
 }
-async function runAdd(ref, opts = {}) {
-  const lines = [];
-  const streamed = opts.emit !== void 0;
-  const push = (...next) => {
-    lines.push(...next);
-    if (next.length > 0) {
-      opts.emit?.(next.join("\n"));
-    }
-  };
-  const done = (exitCode) => ({ lines, exitCode, streamed });
-  if (opts.target && opts.dir) {
-    push("error: pass --target or --dir, not both");
+async function promptIndex(ask, count, push) {
+  while (true) {
+    const answer = (await ask(`Where should it go? [1-${count}, default 1] `)).trim();
+    if (answer === "") return 0;
+    const index = /^\d+$/.test(answer) ? Number.parseInt(answer, 10) - 1 : -1;
+    if (index >= 0 && index < count) return index;
+    push(`  answer 1-${count}, or press enter for the default`);
+  }
+}
+async function choosePackLocation(ctx, detail, memberCount, prompt) {
+  if (prompt) {
+    const choices = packChoices(detail.targets, ctx.slug, memberCount);
+    ctx.push("", "Install location:");
+    choices.forEach((choice, i2) => ctx.push(`  ${i2 + 1}) ${choice.label}`));
+    const chosen = choices[await promptIndex(prompt, choices.length, ctx.push)];
+    return chosen.tool ? { tool: chosen.tool, global: chosen.global ?? false } : { dir: ctx.slug };
+  }
+  const mappable = mappableDeclaredTargets(detail.targets);
+  if (mappable.length > 0) {
+    ctx.push(
+      "",
+      `tip: --target ${mappable[0]} installs the ${memberCount} skills into the tool's skills folder`
+    );
+  }
+  return { dir: ctx.slug };
+}
+async function chooseSingleLocation(ctx, detail, prompt) {
+  const choices = installChoices(detail.targets, ctx.slug);
+  if (prompt && choices.length > 1) {
+    ctx.push("", "Install location:");
+    choices.forEach((choice, i2) => ctx.push(`  ${i2 + 1}) ${choice.label}`));
+    return choices[await promptIndex(prompt, choices.length, ctx.push)].dir;
+  }
+  const mappable = mappableDeclaredTargets(detail.targets);
+  if (mappable.length > 0) {
+    ctx.push("", `tip: --target ${mappable[0]} installs into the tool's skills folder`);
+  }
+  return ctx.slug;
+}
+async function installPack(ctx, members, tool, global) {
+  const { push, done, slug, preflight } = ctx;
+  const area = resolveTargetArea(tool, global);
+  if (!area.ok) {
+    push("", `error: ${area.message}`);
     return done(2);
   }
-  if (opts.global && !opts.target) {
-    push("error: --global needs --target (e.g. --target claude-code)");
+  const { installs, skipped } = resolvePackMembers(members, tool);
+  if (installs.length === 0) {
+    push("", `error: none of this pack's skills support ${tool}`);
     return done(2);
   }
-  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
-  const apiUrl = resolveApiUrl(opts.apiUrl);
-  const fetched = await fetchPreflight(fetchImpl, apiUrl, ref);
-  if (!fetched.ok) {
-    push(...fetched.result.lines);
-    return done(fetched.result.exitCode);
+  const areaAbs = resolve2(ctx.cwd, area.dir);
+  const conflicts = installs.map((m) => join4(areaAbs, m.name)).filter(isOccupied);
+  if (conflicts.length > 0) {
+    push(
+      "",
+      "error: these destinations already exist and are not empty; nothing was installed:",
+      ...conflicts.map((c) => `  ${c}`)
+    );
+    return done(2);
   }
-  const { slug, detail, preflight } = fetched;
-  push(...renderPreflightReport(detail, preflight, opts.style));
-  if (preflight.blocked) {
-    return done(1);
+  const download = await downloadVerified(ctx.fetchImpl, ctx.apiUrl, slug, preflight.version, preflight.sourceHash);
+  if (!download.ok) {
+    push("", `error: ${download.message}`);
+    return done(2);
   }
-  const members = detail.packMembers ?? [];
-  const isPack = members.length > 0;
-  let targetDir = opts.dir;
-  let packTool;
-  let packGlobal = false;
-  if (opts.target) {
-    const resolved = isPack ? resolveTargetArea(opts.target, opts.global) : resolveTargetDir(opts.target, slug, opts.global);
-    if (!resolved.ok) {
-      push("", `error: ${resolved.message}`);
-      return done(2);
-    }
-    if (isPack) {
-      packTool = opts.target;
-      packGlobal = opts.global ?? false;
-    } else {
-      targetDir = resolved.dir;
-    }
-    if (!detail.targets.includes(opts.target)) {
-      push("", `warning: this skill does not declare ${opts.target} as a target`);
-    }
-  }
-  if (preflight.riskLevel !== "low" && !opts.yes) {
-    if (!opts.confirmImpl) {
-      push("", `error: a ${preflight.riskLevel}-risk skill needs confirmation; rerun with --yes`);
-      return done(2);
-    }
-    const confirmed = await opts.confirmImpl(
-      `Install ${slug}@${preflight.version} (${preflight.riskLevel} risk)? [y/N] `
-    );
-    if (!confirmed) {
-      push("", "Install aborted.");
-      return done(2);
-    }
+  const plans = planMembers(installs, download.files);
+  const missing = plans.find((p) => p.files.length === 0);
+  if (missing) {
+    push("", `error: the snapshot has no files for "${missing.name}"; nothing was installed`);
+    return done(2);
   }
-  const prompt = opts.promptImpl;
-  const promptIndex = async (ask, count) => {
-    while (true) {
-      const answer = (await ask(`Where should it go? [1-${count}, default 1] `)).trim();
-      if (answer === "") {
-        return 0;
-      }
-      const index = /^\d+$/.test(answer) ? Number.parseInt(answer, 10) - 1 : -1;
-      if (index >= 0 && index < count) {
-        return index;
-      }
-      push(`  answer 1-${count}, or press enter for the default`);
-    }
-  };
-  if (isPack && packTool === void 0 && targetDir === void 0) {
-    if (prompt) {
-      const choices = packChoices(detail.targets, slug, members.length);
-      push("", "Install location:");
-      choices.forEach((choice, i2) => push(`  ${i2 + 1}) ${choice.label}`));
-      const chosen = choices[await promptIndex(prompt, choices.length)];
-      if (chosen.tool) {
-        packTool = chosen.tool;
-        packGlobal = chosen.global ?? false;
-      } else {
-        targetDir = slug;
-      }
-    } else {
-      targetDir = slug;
-      const mappable = mappableDeclaredTargets(detail.targets);
-      if (mappable.length > 0) {
-        push(
-          "",
-          `tip: --target ${mappable[0]} installs the ${members.length} skills into the tool's skills folder`
-        );
-      }
-    }
+  for (const name of skipped) {
+    push("", `note: ${name} does not support ${tool}; skipped`);
   }
-  if (packTool !== void 0) {
-    const area = resolveTargetArea(packTool, packGlobal);
-    if (!area.ok) {
-      push("", `error: ${area.message}`);
-      return done(2);
-    }
-    const { installs, skipped } = resolvePackMembers(members, packTool);
-    if (installs.length === 0) {
-      push("", `error: none of this pack's skills support ${packTool}`);
-      return done(2);
-    }
-    const areaAbs = resolve(opts.cwd ?? process.cwd(), area.dir);
-    const conflicts = installs.map((m) => join3(areaAbs, m.name)).filter(
-      (dest) => existsSync(dest) && (!statSync2(dest).isDirectory() || readdirSync2(dest).length > 0)
-    );
-    if (conflicts.length > 0) {
-      push(
-        "",
-        "error: these destinations already exist and are not empty; nothing was installed:",
-        ...conflicts.map((c) => `  ${c}`)
-      );
-      return done(2);
-    }
-    const download2 = await downloadVerified(
-      fetchImpl,
-      apiUrl,
-      slug,
-      preflight.version,
-      preflight.sourceHash
-    );
-    if (!download2.ok) {
-      push("", `error: ${download2.message}`);
-      return done(2);
-    }
-    const plans = installs.map((m) => ({ ...m, files: memberFiles(download2.files, m.sourceDir) }));
-    const missing = plans.find((p) => p.files.length === 0);
-    if (missing) {
-      push("", `error: the snapshot has no files for "${missing.name}"; nothing was installed`);
-      return done(2);
-    }
-    for (const name of skipped) {
-      push("", `note: ${name} does not support ${packTool}; skipped`);
-    }
-    const written = [];
-    try {
-      for (const plan of plans) {
-        writeTree(plan.files, join3(areaAbs, plan.name));
-        written.push(plan.name);
-      }
-    } catch {
-      push(
-        "",
-        `error: could not write ${plans[written.length].name}; installed before the failure: ${written.join(", ") || "none"}`
-      );
-      return done(2);
+  const written = [];
+  try {
+    for (const plan of plans) {
+      writeTree(plan.files, join4(areaAbs, plan.name));
+      written.push(plan.name);
+      recordReceipt(areaAbs, plan.name, receiptFor(preflight, slug));
     }
+  } catch {
     push(
       "",
-      `Installed ${written.length} skills to ${areaAbs}`,
-      `  ${written.join(", ")}`,
-      "Source hash verified against the Skill Passport."
-    );
-    return done(0);
-  }
-  if (isPack && opts.dir) {
-    push(
-      "",
-      `note: --dir installs the raw pack source; --target <tool> installs the ${members.length} skills individually`
+      `error: could not write ${plans[written.length].name}; installed before the failure: ${written.join(", ") || "none"}`
     );
+    return done(2);
   }
-  if (!targetDir) {
-    const choices = installChoices(detail.targets, slug);
-    if (prompt && choices.length > 1) {
-      push("", "Install location:");
-      choices.forEach((choice, i2) => push(`  ${i2 + 1}) ${choice.label}`));
-      targetDir = choices[await promptIndex(prompt, choices.length)].dir;
-    } else {
-      targetDir = slug;
-      const mappable = mappableDeclaredTargets(detail.targets);
-      if (mappable.length > 0) {
-        push("", `tip: --target ${mappable[0]} installs into the tool's skills folder`);
-      }
-    }
-  }
-  const target = resolve(opts.cwd ?? process.cwd(), targetDir);
-  if (existsSync(target)) {
-    if (!statSync2(target).isDirectory()) {
+  push(
+    "",
+    `Installed ${written.length} skills to ${areaAbs}`,
+    `  ${written.join(", ")}`,
+    "Source hash verified against the Skill Passport."
+  );
+  return done(0);
+}
+async function installSingle(ctx, targetDir) {
+  const { push, done, slug, preflight } = ctx;
+  const target = resolve2(ctx.cwd, targetDir);
+  if (existsSync2(target)) {
+    if (!statSync3(target).isDirectory()) {
       push("", `error: target ${target} already exists and is not a directory`);
       return done(2);
     }
-    if (readdirSync2(target).length > 0) {
+    if (readdirSync3(target).length > 0) {
       push("", `error: target directory ${target} already exists and is not empty`);
       return done(2);
     }
   }
-  const download = await downloadVerified(
-    fetchImpl,
-    apiUrl,
-    slug,
-    preflight.version,
-    preflight.sourceHash
-  );
+  const download = await downloadVerified(ctx.fetchImpl, ctx.apiUrl, slug, preflight.version, preflight.sourceHash);
   if (!download.ok) {
     push("", `error: ${download.message}`);
     return done(2);
@@ -16676,6 +16795,10 @@ async function runAdd(ref, opts = {}) {
     push("", "error: could not write the install; nothing was installed");
     return done(2);
   }
+  const area = knownAreas(ctx.cwd).find((a) => a.dir === dirname(target));
+  if (area) {
+    recordReceipt(area.dir, slug, receiptFor(preflight));
+  }
   push(
     "",
     `Installed ${download.files.length} file(s) to ${target}`,
@@ -16683,30 +16806,89 @@ async function runAdd(ref, opts = {}) {
   );
   return done(0);
 }
-
-// src/list.ts
-import { existsSync as existsSync2, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
-import { join as join4, resolve as resolve2 } from "node:path";
-function knownAreas(cwd, home) {
-  const areas = [];
-  const byTarget = installAreas(home);
-  for (const tool of MAPPED_TARGETS) {
-    const area = byTarget[tool];
-    if (!area) {
-      continue;
+async function runAdd(ref, opts = {}) {
+  const { push, done } = createOutput(opts.emit);
+  if (opts.target && opts.dir) {
+    push(TARGET_OR_DIR);
+    return done(2);
+  }
+  if (opts.global && !opts.target) {
+    push(GLOBAL_NEEDS_TARGET);
+    return done(2);
+  }
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const apiUrl = resolveApiUrl(opts.apiUrl);
+  const fetched = await fetchPreflight(fetchImpl, apiUrl, ref);
+  if (!fetched.ok) {
+    push(...fetched.result.lines);
+    return done(fetched.result.exitCode);
+  }
+  const { slug, detail, preflight } = fetched;
+  push(...renderPreflightReport(detail, preflight, opts.style));
+  if (preflight.blocked) {
+    return done(1);
+  }
+  const members = detail.packMembers ?? [];
+  const isPack = members.length > 0;
+  let targetDir = opts.dir;
+  let pack;
+  if (opts.target) {
+    const resolved = isPack ? resolveTargetArea(opts.target, opts.global) : resolveTargetDir(opts.target, slug, opts.global);
+    if (!resolved.ok) {
+      push("", `error: ${resolved.message}`);
+      return done(2);
     }
-    areas.push({ label: `${tool} project (${area.project})`, dir: resolve2(cwd, area.project) });
-    if (area.global) {
-      areas.push({ label: `${tool} user (${area.global})`, dir: area.global });
+    if (isPack) {
+      pack = { tool: opts.target, global: opts.global ?? false };
+    } else {
+      targetDir = resolved.dir;
+    }
+    if (!detail.targets.includes(opts.target)) {
+      push("", `warning: this skill does not declare ${opts.target} as a target`);
     }
   }
-  return areas;
+  const confirmed = await confirmRisk(
+    preflight,
+    opts,
+    `Install ${slug}@${preflight.version} (${preflight.riskLevel} risk)? [y/N] `,
+    "Install aborted.",
+    push
+  );
+  if (!confirmed) return done(2);
+  const ctx = {
+    push,
+    done,
+    fetchImpl,
+    apiUrl,
+    cwd: opts.cwd ?? process.cwd(),
+    slug,
+    preflight
+  };
+  if (isPack && pack === void 0 && targetDir === void 0) {
+    const location = await choosePackLocation(ctx, detail, members.length, opts.promptImpl);
+    if ("tool" in location) pack = location;
+    else targetDir = location.dir;
+  }
+  if (pack !== void 0) {
+    return installPack(ctx, members, pack.tool, pack.global);
+  }
+  if (isPack && opts.dir) {
+    push(
+      "",
+      `note: --dir installs the raw pack source; --target <tool> installs the ${members.length} skills individually`
+    );
+  }
+  return installSingle(ctx, targetDir ?? await chooseSingleLocation(ctx, detail, opts.promptImpl));
 }
+
+// src/list.ts
+import { existsSync as existsSync3, readdirSync as readdirSync4, statSync as statSync4 } from "node:fs";
+import { join as join5 } from "node:path";
 function installedIn(dir) {
-  if (!existsSync2(dir)) {
+  if (!existsSync3(dir)) {
     return [];
   }
-  return readdirSync3(dir).sort().filter((name) => statSync3(join4(dir, name)).isDirectory());
+  return readdirSync4(dir).sort().filter((name) => statSync4(join5(dir, name), { throwIfNoEntry: false })?.isDirectory() ?? false);
 }
 function runList(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -16720,8 +16902,10 @@ function runList(opts = {}) {
       lines.push("");
     }
     lines.push(area.label);
+    const receipts = readReceipts(area.dir);
     for (const name of names) {
-      lines.push(`  ${name}`);
+      const version2 = receipts[name]?.version;
+      lines.push(version2 ? `  ${name}  ${version2}` : `  ${name}`);
     }
   }
   if (lines.length === 0) {
@@ -16730,36 +16914,182 @@ function runList(opts = {}) {
   return { lines, exitCode: 0 };
 }
 
-// src/remove.ts
-import { existsSync as existsSync3, rmSync as rmSync2, statSync as statSync4 } from "node:fs";
-import { join as join5, resolve as resolve3 } from "node:path";
-function looksLikeInstalledSkill(dir) {
-  return existsSync3(join5(dir, "SKILL.md")) || existsSync3(join5(dir, "skill.json"));
+// src/outdated.ts
+import { join as join6 } from "node:path";
+async function identifyByHash(fetchImpl, apiUrl, slug, dir) {
+  let hash2;
+  try {
+    hash2 = loadPackage(dir).sourceHash;
+  } catch {
+    return void 0;
+  }
+  const detail = await getParsed(
+    fetchImpl,
+    `${apiUrl}/skills/${encodeURIComponent(slug)}`,
+    publicSkillDetailSchema
+  );
+  if (!detail.ok) {
+    return void 0;
+  }
+  for (const version2 of detail.data.versions) {
+    const preflight = await getParsed(
+      fetchImpl,
+      `${apiUrl}/skills/${encodeURIComponent(slug)}/${encodeURIComponent(version2.version)}/preflight`,
+      publicPreflightSchema
+    );
+    if (preflight.ok && preflight.data.sourceHash === hash2) {
+      return version2.version;
+    }
+  }
+  return void 0;
 }
-function candidateDirs(slug, cwd, home) {
-  const dirs = [];
-  const byTarget = installAreas(home);
-  for (const tool of MAPPED_TARGETS) {
-    const area = byTarget[tool];
-    if (!area) {
+async function runOutdated(opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const apiUrl = resolveApiUrl(opts.apiUrl);
+  const cwd = opts.cwd ?? process.cwd();
+  const fetched = await getParsed(fetchImpl, `${apiUrl}/skills`, publicSkillListSchema);
+  if (!fetched.ok) {
+    return { lines: [`error: ${fetched.message}`], exitCode: 2 };
+  }
+  const latestBySlug = new Map(fetched.data.map((s) => [s.slug, s]));
+  const lines = [];
+  let outdatedCount = 0;
+  let tracked = 0;
+  for (const area of knownAreas(cwd, opts.home)) {
+    const names = installedIn(area.dir);
+    if (names.length === 0) {
       continue;
     }
-    dirs.push(resolve3(cwd, join5(area.project, slug)));
-    if (area.global) {
-      dirs.push(join5(area.global, slug));
+    const receipts = readReceipts(area.dir);
+    const rows = [];
+    const seenPacks = /* @__PURE__ */ new Set();
+    let unrelated = 0;
+    for (const name of names) {
+      const receipt = receipts[name];
+      if (receipt?.pack) {
+        if (seenPacks.has(receipt.pack.slug)) {
+          continue;
+        }
+        seenPacks.add(receipt.pack.slug);
+        tracked += 1;
+        const members = Object.values(receipts).filter(
+          (r) => r.pack?.slug === receipt.pack?.slug
+        ).length;
+        const latest = latestBySlug.get(receipt.pack.slug)?.version;
+        if (latest === void 0) {
+          rows.push(`  ${receipt.pack.slug}  ${receipt.pack.version}  not in the directory`);
+        } else if (latest === receipt.pack.version) {
+          rows.push(`  ${receipt.pack.slug}  ${receipt.pack.version}  current (pack, ${members} skills)`);
+        } else {
+          outdatedCount += 1;
+          rows.push(
+            `  ${receipt.pack.slug}  ${receipt.pack.version} -> ${latest}  (pack, ${members} skills)`
+          );
+        }
+        continue;
+      }
+      if (receipt) {
+        tracked += 1;
+        const latest = latestBySlug.get(name)?.version;
+        if (latest === void 0) {
+          rows.push(`  ${name}  ${receipt.version}  not in the directory`);
+        } else if (latest === receipt.version) {
+          rows.push(`  ${name}  ${receipt.version}  current`);
+        } else {
+          outdatedCount += 1;
+          rows.push(`  ${name}  ${receipt.version} -> ${latest}`);
+        }
+        continue;
+      }
+      if (!latestBySlug.has(name)) {
+        unrelated += 1;
+        continue;
+      }
+      const identified = await identifyByHash(fetchImpl, apiUrl, name, join6(area.dir, name));
+      if (identified !== void 0) {
+        tracked += 1;
+        const latest = latestBySlug.get(name)?.version;
+        if (latest === identified) {
+          rows.push(`  ${name}  ${identified}  current (identified by hash)`);
+        } else {
+          outdatedCount += 1;
+          rows.push(`  ${name}  ${identified} -> ${latest}  (identified by hash)`);
+        }
+        continue;
+      }
+      rows.push(`  ${name}  ?  no receipt - reinstall to track updates`);
     }
+    if (rows.length > 0) {
+      if (lines.length > 0) {
+        lines.push("");
+      }
+      lines.push(area.label, ...rows);
+      if (unrelated > 0) {
+        lines.push(`  (${unrelated} folder(s) not from the directory)`);
+      }
+    }
+  }
+  if (tracked === 0 && lines.length === 0) {
+    return { lines: ["No skills installed in the known install areas."], exitCode: 0 };
   }
-  dirs.push(resolve3(cwd, slug));
-  return [...new Set(dirs)];
+  lines.push(
+    "",
+    outdatedCount === 0 ? "Everything is current." : `${outdatedCount} update(s) available - skillpass update <slug>`
+  );
+  return { lines, exitCode: outdatedCount === 0 ? 0 : 1 };
+}
+
+// src/remove.ts
+import { existsSync as existsSync4, rmSync as rmSync2, statSync as statSync5 } from "node:fs";
+import { dirname as dirname2, join as join7, resolve as resolve3 } from "node:path";
+function looksLikeInstalledSkill(dir) {
+  return existsSync4(join7(dir, "SKILL.md")) || existsSync4(join7(dir, "skill.json"));
+}
+function candidateDirs(slug, cwd, home) {
+  const inAreas = knownAreas(cwd, home).map((area) => join7(area.dir, slug));
+  return [.../* @__PURE__ */ new Set([...inAreas, resolve3(cwd, slug)])];
 }
 function runRemove(slug, opts = {}) {
   if (opts.target && opts.dir) {
-    return { lines: ["error: pass --target or --dir, not both"], exitCode: 2 };
+    return { lines: [TARGET_OR_DIR], exitCode: 2 };
   }
   if (opts.global && !opts.target) {
-    return { lines: ["error: --global needs --target (e.g. --target claude-code)"], exitCode: 2 };
+    return { lines: [GLOBAL_NEEDS_TARGET], exitCode: 2 };
   }
   const cwd = opts.cwd ?? process.cwd();
+  if (!opts.dir) {
+    let areas = knownAreas(cwd, opts.home);
+    if (opts.target) {
+      areas = areas.filter((a) => a.tool === opts.target && a.global === (opts.global ?? false));
+    }
+    const packHits = areas.map((area) => ({
+      area,
+      members: Object.entries(readReceipts(area.dir)).filter(([, r]) => r.pack?.slug === slug).map(([name]) => name)
+    })).filter((hit) => hit.members.length > 0);
+    if (packHits.length > 1) {
+      return {
+        lines: [
+          `error: the ${slug} pack is installed in more than one place; pick one with --target:`,
+          ...packHits.map((hit) => `  ${hit.area.dir}`)
+        ],
+        exitCode: 2
+      };
+    }
+    if (packHits.length === 1) {
+      const { area, members } = packHits[0];
+      for (const name of members) {
+        rmSync2(join7(area.dir, name), { recursive: true, force: true });
+        removeReceipt(area.dir, name);
+      }
+      return {
+        lines: [
+          `Removed pack ${slug} (${members.length} skills) from ${area.dir}`,
+          `  ${members.sort().join(", ")}`
+        ],
+        exitCode: 0
+      };
+    }
+  }
   let dir;
   if (opts.target) {
     const resolved = resolveTargetDir(opts.target, slug, opts.global, opts.home);
@@ -16771,7 +17101,7 @@ function runRemove(slug, opts = {}) {
     dir = resolve3(cwd, opts.dir);
   } else {
     const found = candidateDirs(slug, cwd, opts.home).filter(
-      (candidate) => existsSync3(candidate)
+      (candidate) => existsSync4(candidate)
     );
     if (found.length === 0) {
       return { lines: [`error: ${slug} is not installed in any known location`], exitCode: 2 };
@@ -16787,10 +17117,10 @@ function runRemove(slug, opts = {}) {
     }
     dir = found[0];
   }
-  if (!existsSync3(dir)) {
+  if (!existsSync4(dir)) {
     return { lines: [`error: nothing installed at ${dir}`], exitCode: 2 };
   }
-  if (!statSync4(dir).isDirectory()) {
+  if (!statSync5(dir).isDirectory()) {
     return { lines: [`error: ${dir} is not a directory`], exitCode: 2 };
   }
   if (!looksLikeInstalledSkill(dir)) {
@@ -16800,6 +17130,7 @@ function runRemove(slug, opts = {}) {
     };
   }
   rmSync2(dir, { recursive: true });
+  removeReceipt(dirname2(dir), slug);
   return { lines: [`Removed ${slug} from ${dir}`], exitCode: 0 };
 }
 
@@ -16928,6 +17259,260 @@ async function runSearch(opts = {}) {
   };
 }
 
+// src/update.ts
+import { existsSync as existsSync5, renameSync as renameSync2, rmSync as rmSync3 } from "node:fs";
+import { join as join8 } from "node:path";
+async function locate(slug, opts, fetchImpl, apiUrl) {
+  const cwd = opts.cwd ?? process.cwd();
+  let areas = knownAreas(cwd, opts.home);
+  if (opts.target) {
+    areas = areas.filter((a) => a.tool === opts.target && a.global === (opts.global ?? false));
+  }
+  const hits = [];
+  for (const area of areas) {
+    const receipts = readReceipts(area.dir);
+    const receipt = receipts[slug];
+    const dir = join8(area.dir, slug);
+    if (receipt) {
+      hits.push({
+        area,
+        dir,
+        installedVersion: receipt.version,
+        packSlug: receipt.pack?.slug
+      });
+      continue;
+    }
+    const packMember = Object.values(receipts).find((r) => r.pack?.slug === slug);
+    if (packMember?.pack) {
+      hits.push({ area, dir: area.dir, installedVersion: packMember.pack.version, packSlug: slug });
+      continue;
+    }
+    if (existsSync5(dir)) {
+      const identified = await identifyByHash(fetchImpl, apiUrl, slug, dir);
+      if (identified !== void 0) {
+        hits.push({ area, dir, installedVersion: identified });
+      }
+    }
+  }
+  return hits;
+}
+function permissionChanges(installed, target) {
+  const flat = (sets) => /* @__PURE__ */ new Set([...sets.declared, ...sets.detected]);
+  const before = flat(installed);
+  const after = flat(target);
+  return {
+    added: [...after].filter((key) => !before.has(key)).sort(),
+    removed: [...before].filter((key) => !after.has(key)).sort()
+  };
+}
+function swapTree(files, dir) {
+  const fresh = `${dir}.new-${process.pid}`;
+  const aside = `${dir}.old-${process.pid}`;
+  rmSync3(fresh, { recursive: true, force: true });
+  writeTree(files, fresh);
+  try {
+    if (existsSync5(dir)) renameSync2(dir, aside);
+    renameSync2(fresh, dir);
+  } catch (err2) {
+    if (existsSync5(aside) && !existsSync5(dir)) renameSync2(aside, dir);
+    rmSync3(fresh, { recursive: true, force: true });
+    throw err2;
+  }
+  rmSync3(aside, { recursive: true, force: true });
+}
+async function runUpdate(ref, opts = {}) {
+  const { push, done } = createOutput(opts.emit);
+  const st = opts.style ?? PLAIN;
+  if (opts.global && !opts.target) {
+    push(GLOBAL_NEEDS_TARGET);
+    return done(2);
+  }
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const apiUrl = resolveApiUrl(opts.apiUrl);
+  const { slug } = parseSkillRef(ref);
+  if (!slug) {
+    push(`error: invalid skill reference "${ref}"`);
+    return done(2);
+  }
+  const hits = await locate(slug, opts, fetchImpl, apiUrl);
+  const memberHit = hits.find((h) => h.packSlug !== void 0 && h.packSlug !== slug);
+  if (memberHit?.packSlug !== void 0) {
+    push(
+      `error: ${slug} is part of the ${memberHit.packSlug} pack; run skillpass update ${memberHit.packSlug}`
+    );
+    return done(2);
+  }
+  if (hits.length === 0) {
+    push(
+      `error: ${slug} is not installed in a known skills area (only receipted or hash-identifiable installs can update)`
+    );
+    return done(2);
+  }
+  if (hits.length > 1) {
+    push(
+      `error: ${slug} is installed in more than one place; pick one with --target [--global]:`,
+      ...hits.map((h) => `  ${h.dir}`)
+    );
+    return done(2);
+  }
+  const installed = hits[0];
+  const fetched = await fetchPreflight(fetchImpl, apiUrl, ref);
+  if (!fetched.ok) {
+    push(...fetched.result.lines);
+    return done(fetched.result.exitCode);
+  }
+  const { detail, preflight } = fetched;
+  if ((detail.packMembers?.length ?? 0) > 0 || installed.packSlug === slug) {
+    return runPackUpdate(slug, installed, detail, preflight, opts, fetchImpl, apiUrl, st, push, done);
+  }
+  if (installed.installedVersion === preflight.version) {
+    push(`${slug} is already at ${preflight.version}.`);
+    return done(0);
+  }
+  push(...renderPreflightReport(detail, preflight, opts.style));
+  push("", ...await changesVsInstalled(fetchImpl, apiUrl, slug, installed, preflight, st));
+  if (preflight.blocked) {
+    return done(1);
+  }
+  const confirmed = await confirmRisk(
+    preflight,
+    opts,
+    `Update ${slug} to ${preflight.version} (${preflight.riskLevel} risk)? [y/N] `,
+    "Update aborted; the installed version was left in place.",
+    push
+  );
+  if (!confirmed) return done(2);
+  const download = await downloadVerified(fetchImpl, apiUrl, slug, preflight.version, preflight.sourceHash);
+  if (!download.ok) {
+    push("", `error: ${download.message}`);
+    return done(2);
+  }
+  try {
+    swapTree(download.files, installed.dir);
+  } catch {
+    push("", "error: could not replace the install; the installed version was left in place");
+    return done(2);
+  }
+  recordReceipt(installed.area.dir, slug, receiptFor(preflight));
+  push(
+    "",
+    `Updated ${slug} ${installed.installedVersion ?? "?"} -> ${preflight.version} in ${installed.dir}`,
+    "Source hash verified against the Skill Passport."
+  );
+  return done(0);
+}
+async function changesVsInstalled(fetchImpl, apiUrl, slug, installed, target, st) {
+  if (installed.installedVersion === void 0) {
+    return ["Changes vs installed: unknown (no version identified)"];
+  }
+  const before = await getParsed(
+    fetchImpl,
+    `${apiUrl}/skills/${encodeURIComponent(slug)}/${encodeURIComponent(installed.installedVersion)}/preflight`,
+    publicPreflightSchema
+  );
+  if (!before.ok) {
+    return [
+      `Changes vs installed v${installed.installedVersion}: unavailable (that version is no longer published)`
+    ];
+  }
+  const { added, removed } = permissionChanges(before.data.permissions, target.permissions);
+  if (added.length === 0 && removed.length === 0) {
+    return [`Changes vs installed v${installed.installedVersion}: no permission changes`];
+  }
+  return [
+    `Changes vs installed v${installed.installedVersion}`,
+    ...added.map((key) => st.red(`  + ${key} (new)`)),
+    ...removed.map((key) => `  - ${key} (no longer requested)`)
+  ];
+}
+async function runPackUpdate(slug, installed, detail, preflight, opts, fetchImpl, apiUrl, st, push, done) {
+  if (installed.packSlug !== slug) {
+    push(`error: ${slug} is a pack but this install is not tracked as one; reinstall with skillpass add`);
+    return done(2);
+  }
+  if (installed.installedVersion === preflight.version) {
+    push(`${slug} is already at ${preflight.version}.`);
+    return done(0);
+  }
+  push(...renderPreflightReport(detail, preflight, opts.style));
+  push("", ...await changesVsInstalled(fetchImpl, apiUrl, slug, installed, preflight, st));
+  if (preflight.blocked) {
+    return done(1);
+  }
+  const confirmed = await confirmRisk(
+    preflight,
+    opts,
+    `Update ${slug} to ${preflight.version} (${preflight.riskLevel} risk)? [y/N] `,
+    "Update aborted; the installed version was left in place.",
+    push
+  );
+  if (!confirmed) return done(2);
+  const areaDir = installed.area.dir;
+  const { installs, skipped } = resolvePackMembers(detail.packMembers ?? [], installed.area.tool);
+  if (installs.length === 0) {
+    push("", `error: none of the new version's skills support ${installed.area.tool}`);
+    return done(2);
+  }
+  const receipts = readReceipts(areaDir);
+  const currentMembers = Object.entries(receipts).filter(([, r]) => r.pack?.slug === slug).map(([name]) => name);
+  const newNames = new Set(installs.map((m) => m.name));
+  const toRemove = currentMembers.filter((name) => !newNames.has(name));
+  const additions = installs.filter((m) => !currentMembers.includes(m.name));
+  const conflicts = additions.map((m) => join8(areaDir, m.name)).filter(isOccupied);
+  if (conflicts.length > 0) {
+    push(
+      "",
+      "error: these destinations already exist and are not empty; nothing was changed:",
+      ...conflicts.map((c) => `  ${c}`)
+    );
+    return done(2);
+  }
+  const download = await downloadVerified(fetchImpl, apiUrl, slug, preflight.version, preflight.sourceHash);
+  if (!download.ok) {
+    push("", `error: ${download.message}`);
+    return done(2);
+  }
+  const plans = planMembers(installs, download.files);
+  const missing = plans.find((p) => p.files.length === 0);
+  if (missing) {
+    push("", `error: the snapshot has no files for "${missing.name}"; nothing was changed`);
+    return done(2);
+  }
+  for (const name of skipped) {
+    push("", `note: ${name} does not support ${installed.area.tool}; skipped`);
+  }
+  const done1 = [];
+  try {
+    for (const plan of plans) {
+      const dest = join8(areaDir, plan.name);
+      if (existsSync5(dest)) {
+        swapTree(plan.files, dest);
+      } else {
+        writeTree(plan.files, dest);
+      }
+      done1.push(plan.name);
+      recordReceipt(areaDir, plan.name, receiptFor(preflight, slug));
+    }
+  } catch {
+    push(
+      "",
+      `error: could not write ${plans[done1.length].name}; updated before the failure: ${done1.join(", ") || "none"}`
+    );
+    return done(2);
+  }
+  for (const name of toRemove) {
+    rmSync3(join8(areaDir, name), { recursive: true, force: true });
+    removeReceipt(areaDir, name);
+  }
+  push(
+    "",
+    `Updated ${slug} ${installed.installedVersion ?? "?"} -> ${preflight.version} in ${areaDir}`,
+    `  ${done1.length} skill(s)${additions.length > 0 ? `, added: ${additions.map((m) => m.name).join(", ")}` : ""}${toRemove.length > 0 ? `, removed: ${toRemove.join(", ")}` : ""}`,
+    "Source hash verified against the Skill Passport."
+  );
+  return done(0);
+}
+
 // src/scan.ts
 async function runScan(path, opts = {}) {
   let report;
@@ -16970,7 +17555,7 @@ async function runScan(path, opts = {}) {
 }
 
 // src/index.ts
-var VERSION = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8")).version;
+var VERSION = JSON.parse(readFileSync3(new URL("../package.json", import.meta.url), "utf8")).version;
 var USAGE = [
   "skillpass - validate AI agent skills locally and inspect hosted passports",
   "",
@@ -16984,6 +17569,9 @@ var USAGE = [
   "  skillpass remove <slug> [--target <tool> [--global] | --dir <path>]",
   "                                             remove an installed skill",
   "  skillpass list                              show installed skills in the known areas",
+  "  skillpass outdated                          compare installed skills to the directory",
+  "  skillpass update <slug>[@version] [--target <tool> [--global]] [--yes]",
+  "                                             update an installed skill through the gate",
   "",
   "Flags:",
   "  --json    print machine-readable JSON instead of the readable report",
@@ -16998,7 +17586,8 @@ var USAGE = [
   "  --help    show this message",
   "",
   "The search, report, and add commands read the API base URL from SKILLPASS_API.",
-  "Exit codes: 0 ok/warning, 1 failed or blocked, 2 usage/load/network errors."
+  "Exit codes: 0 ok/warning, 1 failed or blocked, 2 usage/load/network errors",
+  "(outdated exits 1 when updates are available)."
 ].join("\n");
 var COMMAND_FLAGS = {
   scan: ["--json"],
@@ -17006,6 +17595,8 @@ var COMMAND_FLAGS = {
   add: ["--yes", "--target", "--dir", "--global"],
   remove: ["--target", "--dir", "--global"],
   list: [],
+  outdated: [],
+  update: ["--yes", "--target", "--global"],
   search: ["--target", "--category", "--packs", "--json"]
 };
 function parseCliArgs(argv) {
@@ -17124,6 +17715,27 @@ async function run(argv) {
     }
     return runList();
   }
+  if (args.command === "update") {
+    const [ref] = args.positional;
+    if (!ref) {
+      return { lines: ["error: update needs a skill slug", "", USAGE], exitCode: 2 };
+    }
+    const tty = Boolean(process.stdin.isTTY);
+    return runUpdate(ref, {
+      yes: args.yes,
+      target: args.target,
+      global: args.global,
+      style: styler(Boolean(process.stdout.isTTY)),
+      confirmImpl: tty ? confirmViaTty : void 0,
+      emit: (text) => console.log(text)
+    });
+  }
+  if (args.command === "outdated") {
+    if (args.positional.length > 0) {
+      return { lines: ["error: outdated takes no arguments", "", USAGE], exitCode: 2 };
+    }
+    return runOutdated();
+  }
   if (args.command === "report") {
     const [ref] = args.positional;
     if (!ref) {
@@ -17150,10 +17762,17 @@ async function run(argv) {
   }
   return { lines: [`error: unknown command "${args.command}"`, "", USAGE], exitCode: 2 };
 }
-async function main(argv) {
-  const result = await run(argv);
+async function main(argv, runImpl = run) {
+  let result;
+  try {
+    result = await runImpl(argv);
+  } catch (err2) {
+    console.error(`error: ${err2 instanceof Error ? err2.message : String(err2)}`);
+    process.exitCode = 2;
+    return;
+  }
   if (!result.streamed) {
-    console.log(result.lines.join("\n"));
+    (result.exitCode === 2 ? console.error : console.log)(result.lines.join("\n"));
   }
   process.exitCode = result.exitCode;
 }