hubskillz 0.3.0 → 0.4.0

package/dist/index.js

@@ -2836,9 +2836,9 @@ var asciiTabOrNewline = /[\t\n\r]/g;
 function stripTabAndNewline(value) {
   return value.replace(asciiTabOrNewline, "");
 }
-function urlHostnameOk(url2, hostname5) {
-  hostname5.lastIndex = 0;
-  return hostname5.test(url2.hostname);
+function urlHostnameOk(url2, hostname6) {
+  hostname6.lastIndex = 0;
+  return hostname6.test(url2.hostname);
 }
 function urlProtocolOk(url2, protocol) {
   protocol.lastIndex = 0;
@@ -18899,6 +18899,10 @@ var skillStateSchema = external_exports.enum([
   "drifted",
   "customized",
   "missing",
+  // Absent from a project surface but installed in the machine's global root:
+  // Claude Code loads ~/.claude/skills in every project, so nothing is missing
+  // and nothing must be written. The global surface carries the real state.
+  "inherited",
   "unmanaged"
 ]);
 var surfaceKindSchema = external_exports.literal("claude-code-local");
@@ -18911,12 +18915,14 @@ var MAX_FILES_PER_SKILL = 100;
 var MAX_FILE_CONTENT_CHARS = 2e5;
 var MAX_SKILLS_PER_REQUEST = 500;
 var MAX_SNAPSHOT_CHARS = MAX_FILE_CONTENT_CHARS;
+var MAX_INVENTORY_CHUNK_BYTES = 15e5;
 var inventoryFileSchema = external_exports.object({
   path: skillFilePathSchema,
   hash: external_exports.string().min(1),
   size: external_exports.number().int().nonnegative(),
   content: external_exports.string().max(MAX_FILE_CONTENT_CHARS).optional()
 });
+var SKILL_MD = "SKILL.md";
 var skillFileSchema = external_exports.object({
   path: skillFilePathSchema,
   content: external_exports.string().max(MAX_FILE_CONTENT_CHARS)
@@ -18949,7 +18955,9 @@ var surfaceDescriptorSchema = external_exports.object({
   kind: surfaceKindSchema,
   label: external_exports.string().min(1).max(200),
   machineId: external_exports.string().min(1).max(200),
-  path: external_exports.string().min(1).max(1e3)
+  path: external_exports.string().min(1).max(1e3),
+  /** The global root (~/.claude/skills) or a project. Absent on old CLIs. */
+  scope: external_exports.enum(["global", "project"]).optional()
 });
 var inventoryRequestSchema = external_exports.object({
   surface: surfaceDescriptorSchema,
@@ -18961,7 +18969,12 @@ var inventoryRequestSchema = external_exports.object({
       files: external_exports.array(inventoryFileSchema).max(MAX_FILES_PER_SKILL),
       upstream: inventoryUpstreamSchema.optional()
     })
-  ).max(MAX_SKILLS_PER_REQUEST)
+  ).max(MAX_SKILLS_PER_REQUEST),
+  /** Big surfaces travel in chunks: chunk 0 replaces, the others append. */
+  chunk: external_exports.object({
+    index: external_exports.number().int().min(0),
+    total: external_exports.number().int().min(1)
+  }).optional()
 });
 var inventoryItemSchema = external_exports.object({
   name: external_exports.string(),
@@ -18981,7 +18994,9 @@ var inventoryResponseSchema = external_exports.object({
 });
 var approvedQuerySchema = external_exports.object({ surfaceId: external_exports.string().min(1) });
 var approvedSkillSchema = external_exports.object({
-  name: external_exports.string(),
+  // Kebab, not z.string(): the CLI joins this onto a path (commands/sync.ts),
+  // so the response is validated rather than trusted.
+  name: skillNameSchema,
   versionId: external_exports.string(),
   version: external_exports.number().int(),
   contentHash: external_exports.string(),
@@ -19007,6 +19022,14 @@ var draftResponseSchema = external_exports.object({
   skillId: external_exports.string(),
   versionId: external_exports.string()
 });
+var publishRequestSchema = external_exports.object({
+  name: skillNameSchema,
+  published: external_exports.boolean()
+});
+var publishResponseSchema = external_exports.object({
+  ok: external_exports.literal(true),
+  handle: external_exports.string()
+});
 var pendingQuerySchema = external_exports.object({ surfaceId: external_exports.string().min(1) });
 var pendingResponseSchema = external_exports.object({
   requests: external_exports.array(
@@ -19076,6 +19099,76 @@ var paginationQuerySchema = external_exports.object({
   pageSize: external_exports.coerce.number().int().min(1).max(100).default(25)
 });
 
+// ../shared/src/directory/upstream.ts
+function shortSha(value, length = 7) {
+  return value === void 0 ? "-" : value.slice(0, length);
+}
+
+// ../shared/src/directory/skill-md.ts
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+var BLOCK_SCALAR = /^([|>])[+-]?$/;
+function indentOf(line) {
+  return line.length - line.trimStart().length;
+}
+function parseSkillMd(source) {
+  const match = FRONTMATTER.exec(source);
+  if (match === null) return { frontmatter: [], body: source };
+  const frontmatter = [];
+  const lines = (match[1] ?? "").split("\n");
+  for (let at = 0; at < lines.length; at += 1) {
+    const line = lines[at] ?? "";
+    const separator = line.indexOf(":");
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    let value = line.slice(separator + 1).trim();
+    const block = BLOCK_SCALAR.exec(value);
+    if (block !== null) {
+      const indent = indentOf(line);
+      const collected = [];
+      while (at + 1 < lines.length) {
+        const next = lines[at + 1] ?? "";
+        if (next.trim() !== "" && indentOf(next) <= indent) break;
+        collected.push(next);
+        at += 1;
+      }
+      const filled = collected.filter((entry) => entry.trim() !== "");
+      const common = Math.min(...filled.map(indentOf));
+      const stripped = filled.map((entry) => entry.slice(common).trimEnd());
+      value = stripped.join(block[1] === "|" ? "\n" : " ").trim();
+    }
+    frontmatter.push({ key, value });
+  }
+  return {
+    frontmatter,
+    body: source.slice(match[0].length).replace(/^(\r?\n)+/, "")
+  };
+}
+var QUOTED = /^(["'])([\s\S]*)\1$/;
+var RELEASE = /^v?\d[\w.+-]{0,23}$/;
+function declaredRelease(source) {
+  const entry = parseSkillMd(source).frontmatter.find(
+    (item) => item.key === "version"
+  );
+  const value = (entry?.value ?? "").replace(QUOTED, "$2").trim();
+  return RELEASE.test(value) ? value : null;
+}
+function releaseOf(files) {
+  const skillMd = files.find((file2) => file2.path === "SKILL.md");
+  return skillMd === void 0 ? null : declaredRelease(skillMd.content);
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { readdir as readdir2 } from "node:fs/promises";
+import { hostname as hostname5 } from "node:os";
+import { basename as basename2, dirname as dirname2, join as join4 } from "node:path";
+
+// src/config.ts
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, hostname as hostname3 } from "node:os";
+import { join } from "node:path";
+
 // src/errors.ts
 var CliError = class extends DomainError {
   constructor(code, message) {
@@ -19091,75 +19184,7 @@ function toCliError(cause) {
   return new CliError("UNEXPECTED", String(cause));
 }
 
-// src/api.ts
-async function apiRequest(request) {
-  const url2 = `${request.session.baseUrl}${request.path}`;
-  const bearer = `Bearer ${request.session.token}`;
-  let response;
-  try {
-    response = await fetch(url2, {
-      method: request.method,
-      headers: request.body === void 0 ? { accept: "application/json", authorization: bearer } : {
-        accept: "application/json",
-        authorization: bearer,
-        "content-type": "application/json"
-      },
-      body: request.body === void 0 ? void 0 : JSON.stringify(request.body)
-    });
-  } catch (cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
-    return Result.fail(
-      new CliError("NETWORK", `Cannot reach ${url2}: ${detail}`)
-    );
-  }
-  const text = await response.text();
-  if (response.status === 413) {
-    return Result.fail(
-      new CliError(
-        "HTTP",
-        `${request.method} ${request.path} failed: the inventory is too large (HTTP 413). Reduce the number of skills or roots, or use project roots.`
-      )
-    );
-  }
-  if (!response.ok) {
-    const message = isJson(text) ? decodeBody(text, apiErrorSchema)?.message ?? `${response.status} ${response.statusText}` : `The server returned HTTP ${response.status} (not JSON). Try again in a minute.`;
-    return Result.fail(
-      new CliError(
-        response.status === 401 ? "UNAUTHORIZED" : response.status === 403 ? "FORBIDDEN" : "HTTP",
-        `${request.method} ${request.path} failed: ${message}`
-      )
-    );
-  }
-  const parsed = decodeBody(text, request.schema);
-  if (parsed === null) {
-    return Result.fail(
-      new CliError(
-        "PROTOCOL",
-        `${request.method} ${request.path} returned an unexpected payload (HTTP ${response.status}, not JSON or wrong shape).`
-      )
-    );
-  }
-  return Result.ok(parsed);
-}
-function isJson(text) {
-  try {
-    JSON.parse(text === "" ? "null" : text);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function decodeBody(text, schema) {
-  if (!isJson(text)) return null;
-  const parsed = schema.safeParse(JSON.parse(text === "" ? "null" : text));
-  return parsed.success ? parsed.data : null;
-}
-
 // src/config.ts
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { homedir, hostname as hostname3 } from "node:os";
-import { join } from "node:path";
 var DEFAULT_BASE_URL = "https://api.hubskillz.com";
 var configSchema = external_exports.object({
   baseUrl: external_exports.string().min(1),
@@ -19231,6 +19256,9 @@ async function machineId() {
   const existing = await readConfig();
   return existing.isSuccess ? existing.value.machineId : randomUUID();
 }
+function webOrigin(baseUrl) {
+  return baseUrl === DEFAULT_BASE_URL ? "https://hubskillz.com" : baseUrl;
+}
 function resolveBaseUrl(flag, fromConfig) {
   const env = process.env["HUBSKILLZ_BASE_URL"];
   const chosen = flag ?? env ?? fromConfig ?? DEFAULT_BASE_URL;
@@ -19238,22 +19266,24 @@ function resolveBaseUrl(flag, fromConfig) {
 }
 
 // src/output.ts
-var CSI = "\x1B[";
-var ANSI_PATTERN = new RegExp(`${CSI.replace("[", "\\[")}[0-9;]*m`, "gu");
-function colorEnabled() {
-  return process.env["NO_COLOR"] === void 0 && process.stdout.isTTY === true;
-}
-function wrap(code, text) {
-  return colorEnabled() ? `${CSI}${code}m${text}${CSI}0m` : text;
-}
+import { homedir as homedir2 } from "node:os";
+import { styleText } from "node:util";
+var ANSI_PATTERN = /\u001B\[[0-9;]*m/gu;
 function bold(text) {
-  return wrap("1", text);
+  return styleText("bold", text);
 }
 function dim(text) {
-  return wrap("2", text);
+  return styleText("dim", text);
 }
 function accent(text) {
-  return wrap("33", text);
+  return styleText("yellow", text);
+}
+function shortPath(path) {
+  const home2 = homedir2();
+  return path === home2 || path.startsWith(home2 + "/") ? `~${path.slice(home2.length)}` : path;
+}
+function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
 function table(headers, rows) {
   const widths = headers.map(
@@ -19270,12 +19300,526 @@ function table(headers, rows) {
 function visibleLength(text) {
   return text.replace(ANSI_PATTERN, "").length;
 }
-function shortHash(hash2) {
-  return hash2 === void 0 ? "-" : hash2.slice(0, 8);
+
+// src/scan.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { readdir, readFile as readFile3, realpath } from "node:fs/promises";
+import { homedir as homedir4, hostname as hostname4 } from "node:os";
+import { basename, dirname, join as join3, resolve as resolve2 } from "node:path";
+
+// src/lock.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { join as join2, resolve } from "node:path";
+var entrySchema = external_exports.object({
+  source: external_exports.string().min(1),
+  sourceType: external_exports.string(),
+  skillPath: external_exports.string().min(1).optional(),
+  skillFolderHash: external_exports.string().min(1).optional(),
+  computedHash: external_exports.string().min(1).optional()
+});
+var lockSchema = external_exports.object({ skills: external_exports.record(external_exports.string(), external_exports.unknown()) });
+function globalLockPath() {
+  return join2(homedir3(), ".agents", ".skill-lock.json");
+}
+function projectLockPath(projectDir) {
+  return join2(resolve(projectDir), "skills-lock.json");
+}
+async function readLock(path) {
+  const map2 = /* @__PURE__ */ new Map();
+  const raw = await readFile2(path, "utf8").catch(() => null);
+  if (raw === null) return map2;
+  let json2;
+  try {
+    json2 = JSON.parse(raw);
+  } catch {
+    return map2;
+  }
+  const lock = lockSchema.safeParse(json2);
+  if (!lock.success) return map2;
+  for (const [name, value] of Object.entries(lock.data.skills)) {
+    const entry = entrySchema.safeParse(value);
+    if (!entry.success) continue;
+    const { source, sourceType, skillPath } = entry.data;
+    const hash2 = entry.data.skillFolderHash ?? entry.data.computedHash;
+    if (sourceType !== "github" || skillPath === void 0) continue;
+    if (hash2 === void 0) continue;
+    map2.set(name, { source, skillPath, hash: hash2 });
+  }
+  return map2;
+}
+
+// src/scan.ts
+function globalSkillsRoot() {
+  return join3(homedir4(), ".claude", "skills");
+}
+function projectSkillsRoot(dir) {
+  return join3(resolve2(dir), ".claude", "skills");
+}
+function globalSurfaceLabel() {
+  return hostname4();
+}
+function projectSurfaceLabel(dir) {
+  return `${basename(resolve2(dir))} (${hostname4()})`;
+}
+function exists(path) {
+  return existsSync(path);
+}
+function lockPathFor(root) {
+  const resolved = resolve2(root);
+  if (resolved === globalSkillsRoot()) return globalLockPath();
+  return projectLockPath(dirname(dirname(resolved)));
+}
+async function scanSurface(root, label, machine, scope = "project") {
+  const lock = await readLock(lockPathFor(root));
+  const skills = await scanSkills(root);
+  return {
+    descriptor: {
+      kind: "claude-code-local",
+      label,
+      machineId: machine,
+      path: resolve2(root),
+      scope
+    },
+    skills: await Promise.all(skills.map((skill) => withUpstream(skill, lock)))
+  };
+}
+async function withUpstream(skill, lock) {
+  if (lock.size === 0) return skill;
+  const names = [skill.name];
+  if (skill.link) {
+    const real = await realpath(skill.dir).catch(() => skill.dir);
+    names.push(basename(real));
+  }
+  const upstream = names.map((name) => lock.get(name)).find(Boolean);
+  return upstream === void 0 ? skill : { ...skill, upstream };
+}
+async function scanSkills(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const entry of entries) {
+    if (!isSkillFile(entry.name)) continue;
+    const dir = join3(root, entry.name);
+    const symlink = entry.isSymbolicLink();
+    if (!entry.isDirectory() && !(symlink && isDir(dir))) continue;
+    const skill = await scanSkillDir(dir);
+    if (skill === null) continue;
+    skills.push(symlink ? { ...skill, link: true } : skill);
+  }
+  return skills.sort((a, b) => a.name < b.name ? -1 : 1);
+}
+async function scanSkillDir(dir) {
+  const resolved = resolve2(dir);
+  const walked = await walk(resolved, "", /* @__PURE__ */ new Set());
+  if (walked.files.length === 0) return null;
+  return {
+    name: basename(resolved),
+    dir: resolved,
+    files: walked.files,
+    contentHash: contentHash(walked.files),
+    link: walked.link
+  };
+}
+async function walk(dir, prefix, visited) {
+  const real = await realpath(dir).catch(() => dir);
+  if (visited.has(real)) return { files: [], link: false };
+  visited.add(real);
+  const files = [];
+  let link = false;
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const full = join3(dir, entry.name);
+    const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (!isSkillFile(relative)) continue;
+    const symlink = entry.isSymbolicLink();
+    if (entry.isDirectory() || symlink && isDir(full)) {
+      const nested = await walk(full, relative, visited);
+      files.push(...nested.files);
+      link = link || symlink || nested.link;
+      continue;
+    }
+    if (!entry.isFile() && !symlink) continue;
+    const content = await readFile3(full, "utf8").catch(() => null);
+    if (content === null || content.includes("\0") || content.length > MAX_FILE_CONTENT_CHARS) {
+      continue;
+    }
+    files.push({
+      path: relative,
+      content,
+      hash: createHash2("sha256").update(content).digest("hex"),
+      size: Buffer.byteLength(content, "utf8")
+    });
+  }
+  return { files: files.sort((a, b) => a.path < b.path ? -1 : 1), link };
+}
+function isDir(path) {
+  try {
+    return statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+  } catch {
+    return false;
+  }
+}
+function inventoryRequestOf(surface) {
+  return {
+    surface: surface.descriptor,
+    skills: surface.skills.map(inventorySkillOf)
+  };
+}
+function inventoryChunksOf(surface) {
+  const groups = [];
+  let group2 = [];
+  let bytes = 0;
+  for (const skill of surface.skills) {
+    const item = inventorySkillOf(skill);
+    const size = Buffer.byteLength(JSON.stringify(item), "utf8");
+    if (group2.length > 0 && (bytes + size > MAX_INVENTORY_CHUNK_BYTES || group2.length >= MAX_SKILLS_PER_REQUEST)) {
+      groups.push(group2);
+      group2 = [];
+      bytes = 0;
+    }
+    group2.push(item);
+    bytes += size;
+  }
+  groups.push(group2);
+  if (groups.length === 1) return [inventoryRequestOf(surface)];
+  return groups.map((skills, index) => ({
+    surface: surface.descriptor,
+    skills,
+    chunk: { index, total: groups.length }
+  }));
+}
+function inventorySkillOf(skill) {
+  const snapshot = skill.upstream === void 0 && skill.files.reduce((sum, file2) => sum + file2.content.length, 0) <= MAX_SNAPSHOT_CHARS;
+  const item = {
+    name: skill.name,
+    contentHash: skill.contentHash,
+    files: skill.files.map((file2) => {
+      const entry = {
+        path: file2.path,
+        hash: file2.hash,
+        size: file2.size
+      };
+      if (snapshot) entry.content = file2.content;
+      return entry;
+    })
+  };
+  if (skill.upstream !== void 0) item.upstream = skill.upstream;
+  return item;
+}
+
+// src/surfaces.ts
+import { resolve as resolve3 } from "node:path";
+async function localSurfaces(path, both, machineId2, registered = []) {
+  const projectDir = resolve3(path ?? process.cwd());
+  const projectRoot2 = projectSkillsRoot(projectDir);
+  const hasProject = exists(projectRoot2);
+  const project = async (dir) => scanSurface(
+    projectSkillsRoot(dir),
+    projectSurfaceLabel(dir),
+    machineId2,
+    "project"
+  );
+  const global = async () => scanSurface(globalSkillsRoot(), globalSurfaceLabel(), machineId2, "global");
+  if (!both) return [hasProject ? await project(projectDir) : await global()];
+  const surfaces = [await global()];
+  const dirs = projectDirs(
+    hasProject || path !== void 0 ? projectDir : void 0,
+    registered
+  );
+  for (const dir of dirs) {
+    if (exists(projectSkillsRoot(dir))) {
+      surfaces.push(await project(dir));
+      continue;
+    }
+    process.stdout.write(
+      dim(
+        `skipping ${dir}: no .claude/skills here, run \`hubskillz projects remove ${dir}\` to forget it
+`
+      )
+    );
+  }
+  return surfaces;
+}
+function projectDirs(current, registered) {
+  const dirs = [current, ...registered].filter((dir) => dir !== void 0).map((dir) => resolve3(dir)).filter((dir) => projectSkillsRoot(dir) !== globalSkillsRoot());
+  return [...new Set(dirs)];
+}
+
+// src/commands/doctor.ts
+function whereOf(surface) {
+  return surface.descriptor.scope === "global" ? "global" : basename2(dirname2(dirname2(surface.descriptor.path)));
+}
+function frontmatterOf(skill) {
+  const md = skill.files.find((file2) => file2.path === SKILL_MD);
+  if (md === void 0) return null;
+  return parseSkillMd(md.content).frontmatter.map((entry) => entry.key);
+}
+function skillFindings(skill, where) {
+  const keys = frontmatterOf(skill);
+  if (keys === null) {
+    return [
+      {
+        level: "error",
+        skill: skill.name,
+        where,
+        problem: `no ${SKILL_MD}, nothing for an agent to load`
+      }
+    ];
+  }
+  const findings = [];
+  if (!keys.includes("name")) {
+    findings.push({
+      level: "warn",
+      skill: skill.name,
+      where,
+      problem: `${SKILL_MD} without a name in its frontmatter`
+    });
+  }
+  if (!keys.includes("description")) {
+    findings.push({
+      level: "warn",
+      skill: skill.name,
+      where,
+      problem: `${SKILL_MD} without a description, nothing says when to load it`
+    });
+  }
+  return findings;
+}
+function duplicateFindings(surfaces) {
+  const global = surfaces.find(
+    (surface) => surface.descriptor.scope === "global"
+  );
+  if (global === void 0) return [];
+  const findings = [];
+  for (const surface of surfaces) {
+    if (surface === global) continue;
+    for (const skill of surface.skills) {
+      const twin = global.skills.find((entry) => entry.name === skill.name);
+      if (twin === void 0) continue;
+      findings.push({
+        level: "warn",
+        skill: skill.name,
+        where: whereOf(surface),
+        problem: twin.contentHash === skill.contentHash ? "same content as ~/.claude/skills, `npx hubskillz sync` clears it" : "differs from ~/.claude/skills and wins over it here"
+      });
+    }
+  }
+  return findings;
+}
+function scatteredFindings(surfaces) {
+  const projects2 = surfaces.filter(
+    (surface) => surface.descriptor.scope !== "global"
+  );
+  const global = surfaces.find(
+    (surface) => surface.descriptor.scope === "global"
+  );
+  const counts = /* @__PURE__ */ new Map();
+  for (const surface of projects2) {
+    for (const skill of surface.skills) {
+      const key = `${skill.name}\0${skill.contentHash}`;
+      const seen = counts.get(key) ?? /* @__PURE__ */ new Set();
+      seen.add(surface.descriptor.path);
+      counts.set(key, seen);
+    }
+  }
+  const findings = [];
+  for (const [key, paths] of counts) {
+    const name = key.split("\0")[0] ?? "";
+    if (paths.size < 2) continue;
+    if (global?.skills.some((entry) => entry.name === name) === true) continue;
+    findings.push({
+      level: "warn",
+      skill: name,
+      where: `${paths.size} projects`,
+      problem: `identical in every one, \`hubskillz move ${name} global\` covers them all`
+    });
+  }
+  return findings;
+}
+async function brokenFindings(root, where) {
+  const entries = await readdir2(root, { withFileTypes: true }).catch(() => []);
+  const findings = [];
+  for (const entry of entries) {
+    if (!isSkillFile(entry.name)) continue;
+    const dir = join4(root, entry.name);
+    if (entry.isSymbolicLink() && !existsSync2(dir)) {
+      findings.push({
+        level: "error",
+        skill: entry.name,
+        where,
+        problem: "broken symlink, the target is gone"
+      });
+      continue;
+    }
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (await scanSkillDir(dir) === null) {
+      findings.push({
+        level: "error",
+        skill: entry.name,
+        where,
+        problem: "empty folder, no readable file inside"
+      });
+    }
+  }
+  return findings;
+}
+function staleFindings(registered) {
+  return registered.filter((dir) => !exists(projectSkillsRoot(dir))).map((dir) => ({
+    level: "warn",
+    skill: "-",
+    where: shortPath(dir),
+    problem: "registered without .claude/skills, `hubskillz projects remove` it"
+  }));
+}
+async function doctor(options) {
+  const config2 = await readConfig();
+  const machine = config2.isSuccess ? config2.value.machineId : hostname5();
+  const registered = config2.isSuccess ? config2.value.projects : [];
+  const live = registered.filter((dir) => exists(projectSkillsRoot(dir)));
+  const surfaces = await localSurfaces(options.path, true, machine, live);
+  const findings = [...staleFindings(registered)];
+  for (const surface of surfaces) {
+    const where = whereOf(surface);
+    findings.push(...await brokenFindings(surface.descriptor.path, where));
+    for (const skill of surface.skills) {
+      findings.push(...skillFindings(skill, where));
+    }
+  }
+  findings.push(...duplicateFindings(surfaces), ...scatteredFindings(surfaces));
+  printSurfaces(surfaces);
+  printFindings(findings);
+  return Result.ok(void 0);
+}
+function printSurfaces(surfaces) {
+  for (const surface of surfaces) {
+    process.stdout.write(
+      `${bold(surface.descriptor.label)}  ${dim(
+        `${shortPath(surface.descriptor.path)}, ${plural(surface.skills.length, "skill")}`
+      )}
+`
+    );
+  }
+}
+function group(findings) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    const key = `${finding.level}\0${finding.where}\0${finding.problem}`;
+    const found = groups.get(key) ?? [];
+    found.push(finding);
+    groups.set(key, found);
+  }
+  return groups;
+}
+function printFindings(findings) {
+  if (findings.length === 0) {
+    process.stdout.write(`
+${dim("nothing to fix")}
+`);
+    return;
+  }
+  const groups = [...group(findings).values()].sort(
+    (left, right) => left[0]?.level === right[0]?.level ? 0 : left[0]?.level === "error" ? -1 : 1
+  );
+  process.stdout.write(
+    `
+${table(
+      ["LEVEL", "SKILL", "WHERE", "PROBLEM"],
+      groups.map(([first, ...rest]) => [
+        first?.level === "error" ? accent("error") : dim("warn"),
+        rest.length === 0 ? first?.skill ?? "-" : plural(rest.length + 1, "skill"),
+        first?.where ?? "-",
+        first?.problem ?? ""
+      ])
+    )}
+`
+  );
+  for (const found of groups) {
+    if (found.length < 2) continue;
+    const first = found[0];
+    if (first === void 0) continue;
+    process.stdout.write(
+      `
+${dim(`${first.where}, ${first.problem}`)}
+  ${found.map((finding) => finding.skill).join(", ")}
+`
+    );
+  }
+  const errors = findings.filter((finding) => finding.level === "error").length;
+  process.stdout.write(
+    `
+${plural(findings.length, "problem")}, ${errors} to fix by hand
+`
+  );
+}
+
+// src/api.ts
+async function apiRequest(request) {
+  const url2 = `${request.session.baseUrl}${request.path}`;
+  const bearer = `Bearer ${request.session.token}`;
+  let response;
+  try {
+    response = await fetch(url2, {
+      method: request.method,
+      headers: request.body === void 0 ? { accept: "application/json", authorization: bearer } : {
+        accept: "application/json",
+        authorization: bearer,
+        "content-type": "application/json"
+      },
+      body: request.body === void 0 ? void 0 : JSON.stringify(request.body)
+    });
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return Result.fail(
+      new CliError("NETWORK", `Cannot reach ${url2}: ${detail}`)
+    );
+  }
+  const text = await response.text();
+  if (response.status === 413) {
+    return Result.fail(
+      new CliError(
+        "HTTP",
+        `${request.method} ${request.path} failed: the inventory is too large (HTTP 413). Reduce the number of skills or roots, or use project roots.`
+      )
+    );
+  }
+  if (!response.ok) {
+    const message = decodeBody(text, apiErrorSchema)?.message ?? `The server returned HTTP ${response.status} with an unexpected body. Try again in a minute.`;
+    return Result.fail(
+      new CliError(
+        response.status === 401 ? "UNAUTHORIZED" : response.status === 403 ? "FORBIDDEN" : "HTTP",
+        `${request.method} ${request.path} failed: ${message}`
+      )
+    );
+  }
+  const parsed = decodeBody(text, request.schema);
+  if (parsed === null) {
+    return Result.fail(
+      new CliError(
+        "PROTOCOL",
+        `${request.method} ${request.path} returned an unexpected payload (HTTP ${response.status}, not JSON or wrong shape).`
+      )
+    );
+  }
+  return Result.ok(parsed);
+}
+function decodeBody(text, schema) {
+  try {
+    const parsed = schema.safeParse(JSON.parse(text === "" ? "null" : text));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
 }
 
 // src/prompt.ts
 import { createInterface } from "node:readline/promises";
+import { text as readAll } from "node:stream/consumers";
 var ENTER = /* @__PURE__ */ new Set(["\r", "\n"]);
 var BACKSPACE = /* @__PURE__ */ new Set(["\b", "\x7F"]);
 var CTRL_C = "";
@@ -19324,13 +19868,6 @@ async function confirm(question) {
     rl.close();
   }
 }
-async function readAll(stream) {
-  const chunks = [];
-  for await (const chunk of stream) {
-    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
-  }
-  return Buffer.concat(chunks).toString("utf8");
-}
 function parseSelection(answer, count) {
   const text = answer.trim().toLowerCase();
   if (text === "" || text === "all" || text === "a") {
@@ -19448,210 +19985,130 @@ async function logout() {
   return Result.ok(void 0);
 }
 
-// src/commands/projects.ts
-import { resolve as resolve4 } from "node:path";
-
-// src/discover.ts
-import { readdir as readdir2 } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { join as join4, resolve as resolve3 } from "node:path";
-
-// src/scan.ts
-import { createHash as createHash2 } from "node:crypto";
-import { readdir, readFile as readFile3, realpath, stat } from "node:fs/promises";
-import { homedir as homedir3, hostname as hostname4 } from "node:os";
-import { basename, dirname, join as join3, resolve as resolve2 } from "node:path";
-
-// src/lock.ts
-import { readFile as readFile2 } from "node:fs/promises";
-import { homedir as homedir2 } from "node:os";
-import { join as join2, resolve } from "node:path";
-var entrySchema = external_exports.object({
-  source: external_exports.string().min(1),
-  sourceType: external_exports.string(),
-  skillPath: external_exports.string().min(1).optional(),
-  skillFolderHash: external_exports.string().min(1).optional(),
-  computedHash: external_exports.string().min(1).optional()
-});
-var lockSchema = external_exports.object({ skills: external_exports.record(external_exports.string(), external_exports.unknown()) });
-function globalLockPath() {
-  return join2(homedir2(), ".agents", ".skill-lock.json");
-}
-function projectLockPath(projectDir) {
-  return join2(resolve(projectDir), "skills-lock.json");
-}
-async function readLock(path) {
-  const map2 = /* @__PURE__ */ new Map();
-  const raw = await readFile2(path, "utf8").catch(() => null);
-  if (raw === null) return map2;
-  let json2;
-  try {
-    json2 = JSON.parse(raw);
-  } catch {
-    return map2;
-  }
-  const lock = lockSchema.safeParse(json2);
-  if (!lock.success) return map2;
-  for (const [name, value] of Object.entries(lock.data.skills)) {
-    const entry = entrySchema.safeParse(value);
-    if (!entry.success) continue;
-    const { source, sourceType, skillPath } = entry.data;
-    const hash2 = entry.data.skillFolderHash ?? entry.data.computedHash;
-    if (sourceType !== "github" || skillPath === void 0) continue;
-    if (hash2 === void 0) continue;
-    map2.set(name, { source, skillPath, hash: hash2 });
-  }
-  return map2;
-}
-
-// src/scan.ts
-function globalSkillsRoot() {
-  return join3(homedir3(), ".claude", "skills");
-}
-function projectSkillsRoot(dir) {
-  return join3(resolve2(dir), ".claude", "skills");
-}
-function globalSurfaceLabel() {
-  return hostname4();
-}
-function projectSurfaceLabel(dir) {
-  return `${hostname4()}:${basename(resolve2(dir))}`;
-}
-async function exists(path) {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function lockPathFor(root) {
-  const resolved = resolve2(root);
-  if (resolved === globalSkillsRoot()) return globalLockPath();
-  return projectLockPath(dirname(dirname(resolved)));
-}
-async function scanSurface(root, label, machine) {
-  const lock = await readLock(lockPathFor(root));
-  const skills = await scanSkills(root);
-  return {
-    descriptor: {
-      kind: "claude-code-local",
-      label,
-      machineId: machine,
-      path: resolve2(root)
-    },
-    skills: await Promise.all(skills.map((skill) => withUpstream(skill, lock)))
-  };
-}
-async function withUpstream(skill, lock) {
-  if (lock.size === 0) return skill;
-  const names = [skill.name];
-  if (skill.link) {
-    const real = await realpath(skill.dir).catch(() => skill.dir);
-    names.push(basename(real));
-  }
-  const upstream = names.map((name) => lock.get(name)).find(Boolean);
-  return upstream === void 0 ? skill : { ...skill, upstream };
+// src/commands/move.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { cp, lstat, mkdir as mkdir2, rename, rm as rm2 } from "node:fs/promises";
+import { join as join5, resolve as resolve4 } from "node:path";
+function skillsRootOf(target) {
+  return target === "global" ? globalSkillsRoot() : projectSkillsRoot(target);
+}
+function searchRoots(path, from) {
+  if (from !== void 0) return [skillsRootOf(from)];
+  return [
+    .../* @__PURE__ */ new Set([projectSkillsRoot(path ?? process.cwd()), globalSkillsRoot()])
+  ];
 }
-async function scanSkills(root) {
-  let entries;
-  try {
-    entries = await readdir(root, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const skills = [];
-  for (const entry of entries) {
-    if (!isSkillFile(entry.name)) continue;
-    const dir = join3(root, entry.name);
-    const symlink = entry.isSymbolicLink();
-    if (!entry.isDirectory() && !(symlink && await isDir(dir))) continue;
-    const skill = await scanSkillDir(dir);
-    if (skill === null) continue;
-    skills.push(symlink ? { ...skill, link: true } : skill);
+function pickSource(name, roots, destRoot, holds) {
+  const found = roots.filter((root) => root !== destRoot && holds(root));
+  const [first, second] = found;
+  if (first !== void 0 && second === void 0) return Result.ok(first);
+  if (first === void 0) {
+    return Result.fail(
+      new CliError(
+        "SKILL_NOT_FOUND",
+        `No skill named ${name} in ${roots.map(shortPath).join(" or ")}.`
+      )
+    );
   }
-  return skills.sort((a, b) => a.name < b.name ? -1 : 1);
-}
-async function scanSkillDir(dir) {
-  const resolved = resolve2(dir);
-  const walked = await walk(resolved, "", /* @__PURE__ */ new Set());
-  if (walked.files.length === 0) return null;
-  return {
-    name: basename(resolved),
-    dir: resolved,
-    files: walked.files,
-    contentHash: contentHash(walked.files),
-    link: walked.link
-  };
+  return Result.fail(
+    new CliError(
+      "AMBIGUOUS_SOURCE",
+      `${name} exists in ${found.map(shortPath).join(" and ")}. Pass --from to say which one to move.`
+    )
+  );
 }
-async function walk(dir, prefix, visited) {
-  const real = await realpath(dir).catch(() => dir);
-  if (visited.has(real)) return { files: [], link: false };
-  visited.add(real);
-  const files = [];
-  let link = false;
-  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
-  for (const entry of entries) {
-    const full = join3(dir, entry.name);
-    const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
-    if (!isSkillFile(relative)) continue;
-    const symlink = entry.isSymbolicLink();
-    if (entry.isDirectory() || symlink && await isDir(full)) {
-      const nested = await walk(full, relative, visited);
-      files.push(...nested.files);
-      link = link || symlink || nested.link;
-      continue;
+async function moveSkill(source, dest, force) {
+  if (await lstat(source).catch(() => null) === null) {
+    return Result.fail(new CliError("SKILL_NOT_FOUND", `${source} is gone.`));
+  }
+  if (existsSync3(dest) || await lstat(dest).catch(() => null) !== null) {
+    if (!force) {
+      return Result.fail(
+        new CliError(
+          "DESTINATION_EXISTS",
+          `${shortPath(dest)} already exists. Pass --force to replace it.`
+        )
+      );
     }
-    if (!entry.isFile() && !symlink) continue;
-    const content = await readFile3(full, "utf8").catch(() => null);
-    if (content === null || content.includes("\0") || content.length > MAX_FILE_CONTENT_CHARS) {
-      continue;
+    await rm2(dest, { recursive: true, force: true });
+  }
+  await mkdir2(resolve4(dest, ".."), { recursive: true });
+  try {
+    await rename(source, dest);
+  } catch (cause) {
+    const code = cause instanceof Error && "code" in cause ? cause.code : null;
+    if (code !== "EXDEV") {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      return Result.fail(new CliError("MOVE_FAILED", detail));
     }
-    files.push({
-      path: relative,
-      content,
-      hash: createHash2("sha256").update(content).digest("hex"),
-      size: Buffer.byteLength(content, "utf8")
-    });
+    await cp(source, dest, { recursive: true, verbatimSymlinks: true });
+    await rm2(source, { recursive: true, force: true });
   }
-  return { files: files.sort((a, b) => a.path < b.path ? -1 : 1), link };
+  return Result.ok(void 0);
 }
-async function isDir(path) {
-  return stat(path).then((stats) => stats.isDirectory()).catch(() => false);
+async function sameContent(left, right) {
+  const [one, two] = await Promise.all([
+    scanSkillDir(left),
+    scanSkillDir(right)
+  ]);
+  return one !== null && two !== null && one.contentHash === two.contentHash;
 }
-function inventoryRequestOf(surface) {
-  return {
-    surface: surface.descriptor,
-    skills: surface.skills.map((skill) => {
-      const snapshot = skill.upstream === void 0 && skill.files.reduce((sum, file2) => sum + file2.content.length, 0) <= MAX_SNAPSHOT_CHARS;
-      const item = {
-        name: skill.name,
-        contentHash: skill.contentHash,
-        files: skill.files.map((file2) => {
-          const entry = {
-            path: file2.path,
-            hash: file2.hash,
-            size: file2.size
-          };
-          if (snapshot) entry.content = file2.content;
-          return entry;
-        })
-      };
-      if (skill.upstream !== void 0) item.upstream = skill.upstream;
-      return item;
-    })
-  };
+async function move(options) {
+  if (options.to === void 0) {
+    return Result.fail(
+      new CliError(
+        "USAGE",
+        "hubskillz move needs a destination: `global` or a project directory. Run `hubskillz help move`."
+      )
+    );
+  }
+  const destRoot = skillsRootOf(options.to);
+  const roots = searchRoots(options.path, options.from);
+  const source = pickSource(
+    options.name,
+    roots,
+    destRoot,
+    (root) => existsSync3(join5(root, options.name))
+  );
+  if (source.isFailure) return Result.fail(source.error);
+  const dest = join5(destRoot, options.name);
+  const origin = join5(source.value, options.name);
+  if (!options.force && await sameContent(origin, dest)) {
+    await rm2(origin, { recursive: true, force: true });
+    process.stdout.write(
+      `${shortPath(dest)} already holds this exact skill
+removed the copy in ${shortPath(origin)}
+`
+    );
+    return Result.ok(void 0);
+  }
+  const moved = await moveSkill(origin, dest, options.force);
+  if (moved.isFailure) return moved;
+  process.stdout.write(
+    `moved ${options.name}
+  ${shortPath(origin)}
+  ${shortPath(dest)}
+${dim("run npx hubskillz status to report the new layout")}
+`
+  );
+  return Result.ok(void 0);
 }
 
+// src/commands/projects.ts
+import { resolve as resolve6 } from "node:path";
+
 // src/discover.ts
+import { readdir as readdir3 } from "node:fs/promises";
+import { homedir as homedir5 } from "node:os";
+import { join as join6, resolve as resolve5 } from "node:path";
 var SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", "Library", ".Trash", ".cache"]);
-async function discoverProjects(roots = [homedir4()], maxDepth = 3) {
+async function discoverProjects(roots = [homedir5()], maxDepth = 3) {
   const found = /* @__PURE__ */ new Set();
   const walk2 = async (dir, depth) => {
     if (depth > maxDepth) return;
     let entries;
     try {
-      entries = await readdir2(dir, { withFileTypes: true });
+      entries = await readdir3(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -19659,15 +20116,15 @@ async function discoverProjects(roots = [homedir4()], maxDepth = 3) {
       const name = entry.name;
       if (!entry.isDirectory() || SKIP.has(name)) continue;
       if (name.startsWith(".") && name !== ".claude") continue;
-      const child = join4(dir, name);
+      const child = join6(dir, name);
       if (name === ".claude" && depth > 0) {
-        if (await exists(projectSkillsRoot(dir))) found.add(dir);
+        if (exists(projectSkillsRoot(dir))) found.add(dir);
         continue;
       }
       await walk2(child, depth + 1);
     }
   };
-  for (const root of roots) await walk2(resolve3(root), 0);
+  for (const root of roots) await walk2(resolve5(root), 0);
   return [...found].sort();
 }
 
@@ -19684,7 +20141,7 @@ async function discoverAndRegister(config2, yes) {
   const projects2 = [...config2.projects, ...chosen];
   await writeConfig({ ...config2, projects: projects2 });
   process.stdout.write(
-    `Registered ${chosen.length} project${chosen.length === 1 ? "" : "s"}. They are now part of \`hubskillz sync --all\`.
+    `Registered ${plural(chosen.length, "project")}. They are now part of \`hubskillz sync --all\`.
 `
   );
   return projects2;
@@ -19693,7 +20150,7 @@ async function projects(options) {
   const config2 = await readConfig();
   if (config2.isFailure) return Result.fail(config2.error);
   const current = config2.value.projects;
-  const dir = resolve4(options.dir ?? process.cwd());
+  const dir = resolve6(options.dir ?? process.cwd());
   switch (options.action ?? "list") {
     case "list": {
       if (current.length === 0) {
@@ -19709,7 +20166,7 @@ async function projects(options) {
       return Result.ok(void 0);
     }
     case "add": {
-      if (!await exists(projectSkillsRoot(dir))) {
+      if (!exists(projectSkillsRoot(dir))) {
         return Result.fail(
           new CliError(
             "NO_SKILLS_ROOT",
@@ -19757,6 +20214,32 @@ async function projects(options) {
   }
 }
 
+// src/commands/publish.ts
+async function publish(options) {
+  const config2 = await readConfig();
+  if (config2.isFailure) return Result.fail(config2.error);
+  const session = {
+    baseUrl: resolveBaseUrl(options.baseUrl, config2.value.baseUrl),
+    token: config2.value.token
+  };
+  const result = await apiRequest({
+    session,
+    method: "POST",
+    path: "/api/cli/publish",
+    schema: publishResponseSchema,
+    body: { name: options.name, published: options.published }
+  });
+  if (result.isFailure) return Result.fail(result.error);
+  const page = `${webOrigin(session.baseUrl)}/@${result.value.handle}`;
+  process.stdout.write(
+    options.published ? `${options.name} is public on ${page}
+` : `${options.name} is off your public page.
+${dim(page)}
+`
+  );
+  return Result.ok(void 0);
+}
+
 // src/commands/push.ts
 async function push(options) {
   const config2 = await readConfig();
@@ -19795,47 +20278,6 @@ ${dim(`skill ${draft.value.skillId} version ${draft.value.versionId}`)}
   return Result.ok(void 0);
 }
 
-// src/surfaces.ts
-import { resolve as resolve5 } from "node:path";
-async function localSurfaces(path, both, machineId2, registered = []) {
-  const projectDir = resolve5(path ?? process.cwd());
-  const projectRoot = projectSkillsRoot(projectDir);
-  const hasProject = await exists(projectRoot);
-  const project = async (dir) => scanSurface(projectSkillsRoot(dir), projectSurfaceLabel(dir), machineId2);
-  const global = async () => scanSurface(globalSkillsRoot(), globalSurfaceLabel(), machineId2);
-  if (!both) return [hasProject ? await project(projectDir) : await global()];
-  const surfaces = [await global()];
-  const dirs = projectDirs(
-    hasProject || path !== void 0 ? projectDir : void 0,
-    registered
-  );
-  for (const dir of dirs) {
-    if (await exists(projectSkillsRoot(dir))) {
-      surfaces.push(await project(dir));
-      continue;
-    }
-    process.stdout.write(
-      dim(
-        `skipping ${dir}: no .claude/skills here, run \`hubskillz projects remove ${dir}\` to forget it
-`
-      )
-    );
-  }
-  return surfaces;
-}
-function projectDirs(current, registered) {
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
-  for (const dir of [current, ...registered]) {
-    if (dir === void 0) continue;
-    const abs = resolve5(dir);
-    if (seen.has(abs)) continue;
-    seen.add(abs);
-    out.push(abs);
-  }
-  return out;
-}
-
 // src/commands/status.ts
 async function status(options) {
   const config2 = await readConfig();
@@ -19854,7 +20296,7 @@ async function status(options) {
   for (const surface of surfaces) {
     const inventory = await postInventory(session, surface);
     if (inventory.isFailure) return Result.fail(inventory.error);
-    printSurface(surface, inventory.value);
+    printSurface(surface, inventory.value, session.baseUrl);
   }
   if (quickstartPending(config2)) {
     process.stdout.write(`
@@ -19863,20 +20305,42 @@ ${quickstart(config2)}`);
   return Result.ok(void 0);
 }
 async function postInventory(session, surface) {
-  return apiRequest({
-    session,
-    method: "POST",
-    path: "/api/cli/inventory",
-    schema: inventoryResponseSchema,
-    body: inventoryRequestOf(surface)
-  });
+  const chunks = inventoryChunksOf(surface);
+  let surfaceId;
+  const items = [];
+  for (const body of chunks) {
+    const posted = await apiRequest({
+      session,
+      method: "POST",
+      path: "/api/cli/inventory",
+      schema: inventoryResponseSchema,
+      body
+    });
+    if (posted.isFailure) return posted;
+    surfaceId ??= posted.value.surfaceId;
+    items.push(...posted.value.items);
+  }
+  if (surfaceId === void 0) return Result.ok({ surfaceId: "", items: [] });
+  return Result.ok({ surfaceId, items: mergeItems(items) });
+}
+function mergeItems(items) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const seen = byName.get(item.name);
+    const better = seen === void 0 || seen.installedHash === void 0 && item.installedHash !== void 0;
+    if (better) byName.set(item.name, item);
+  }
+  return [...byName.values()];
 }
 function originOf(surface, name) {
   const skill = surface.skills.find((entry) => entry.name === name);
   if (skill === void 0) return "-";
   return skill.upstream === void 0 ? "private" : `skills.sh ${skill.upstream.source}`;
 }
-function printNotes(surface, items) {
+function reviewUrl(baseUrl) {
+  return `${webOrigin(baseUrl)}/app`;
+}
+function printNotes(surface, items, baseUrl) {
   const importable = items.filter((item) => item.importable).map((item) => item.name);
   if (importable.length > 0) {
     process.stdout.write(
@@ -19888,6 +20352,10 @@ function printNotes(surface, items) {
   if (ahead.length > 0) {
     process.stdout.write(
       `${dim("upstream ahead of approved version, waiting for review:")} ${ahead.join(", ")}
+`
+    );
+    process.stdout.write(
+      `${dim(`review and approve at ${reviewUrl(baseUrl)}`)}
 `
     );
   }
@@ -19899,17 +20367,35 @@ ${bold(surface.descriptor.label)}  ${dim(surface.descriptor.path)}
 `
   );
 }
-function printSurface(surface, inventory) {
-  const rows = inventory.items.map((item) => [
+function printSurface(surface, inventory, baseUrl) {
+  const inherited = inventory.items.filter(
+    (item) => item.state === "inherited"
+  ).length;
+  const rows = inventory.items.filter((item) => item.state !== "inherited").map((item) => [
     item.name,
     originOf(surface, item.name),
     item.required ? `${item.state} ${dim("(required)")}` : item.state,
-    shortHash(item.installedHash),
+    shortSha(item.installedHash, 8),
     item.approvedVersion === void 0 ? "-" : `v${item.approvedVersion}`
   ]);
   printHeader(surface);
+  if (inherited > 0) {
+    process.stdout.write(
+      `${dim(`${plural(inherited, "skill")} inherited from ~/.claude/skills`)}
+`
+    );
+  }
+  const duplicates = inventory.items.filter(
+    (item) => item.state === "inherited" && item.installedHash !== void 0
+  ).length;
+  if (duplicates > 0) {
+    process.stdout.write(
+      `${dim(`${duplicates} duplicate cop${duplicates === 1 ? "y" : "ies"} here: run npx hubskillz sync to remove ${duplicates === 1 ? "it" : "them"}`)}
+`
+    );
+  }
   if (rows.length === 0) {
-    process.stdout.write(`${dim("no skills")}
+    if (inherited === 0) process.stdout.write(`${dim("no skills")}
 `);
     return;
   }
@@ -19918,17 +20404,26 @@ function printSurface(surface, inventory) {
 
 `
   );
-  printNotes(surface, inventory.items);
+  printNotes(surface, inventory.items, baseUrl);
+  const behind = inventory.items.filter(
+    (item) => item.state === "drifted" || item.state === "missing"
+  ).length;
+  if (behind > 0) {
+    process.stdout.write(
+      `${dim(`${plural(behind, "skill")} to install or update: run npx hubskillz sync`)}
+`
+    );
+  }
 }
 
 // src/commands/sync.ts
-import { lstat, readdir as readdir3, realpath as realpath2 } from "node:fs/promises";
-import { homedir as homedir5 } from "node:os";
-import { join as join6, resolve as resolve6, sep as sep2 } from "node:path";
+import { lstat as lstat2, readdir as readdir4, realpath as realpath2, rm as rm4 } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { join as join8, resolve as resolve7, sep as sep2 } from "node:path";
 
 // src/apply.ts
-import { mkdir as mkdir2, mkdtemp, rename, rm as rm2, rmdir, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname2, join as join5, sep } from "node:path";
+import { mkdir as mkdir3, mkdtemp, rename as rename2, rm as rm3, rmdir, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname3, join as join7, sep } from "node:path";
 async function applySkill(input2) {
   for (const path of [...input2.files.map((f) => f.path), ...input2.remove]) {
     if (!isSafeRelativePath(path)) {
@@ -19940,26 +20435,26 @@ async function applySkill(input2) {
       );
     }
   }
-  await mkdir2(input2.dir, { recursive: true });
-  const staging = await mkdtemp(join5(dirname2(input2.dir), ".hubskillz-"));
+  await mkdir3(input2.dir, { recursive: true });
+  const staging = await mkdtemp(join7(dirname3(input2.dir), ".hubskillz-"));
   try {
     for (const file2 of input2.files) {
-      const staged = join5(staging, ...file2.path.split("/"));
-      await mkdir2(dirname2(staged), { recursive: true });
+      const staged = join7(staging, ...file2.path.split("/"));
+      await mkdir3(dirname3(staged), { recursive: true });
       await writeFile2(staged, file2.content, "utf8");
     }
     for (const file2 of input2.files) {
-      const target = join5(input2.dir, ...file2.path.split("/"));
-      await mkdir2(dirname2(target), { recursive: true });
-      await rename(join5(staging, ...file2.path.split("/")), target);
+      const target = join7(input2.dir, ...file2.path.split("/"));
+      await mkdir3(dirname3(target), { recursive: true });
+      await rename2(join7(staging, ...file2.path.split("/")), target);
     }
     for (const path of input2.remove) {
-      const target = join5(input2.dir, ...path.split("/"));
-      await rm2(target, { force: true });
-      await pruneEmptyDirs(dirname2(target), input2.dir);
+      const target = join7(input2.dir, ...path.split("/"));
+      await rm3(target, { force: true });
+      await pruneEmptyDirs(dirname3(target), input2.dir);
     }
   } finally {
-    await rm2(staging, { recursive: true, force: true });
+    await rm3(staging, { recursive: true, force: true });
   }
   return Result.ok(void 0);
 }
@@ -19977,7 +20472,7 @@ async function pruneEmptyDirs(from, stopAt) {
     } catch {
       return;
     }
-    current = dirname2(current);
+    current = dirname3(current);
   }
 }
 
@@ -20006,6 +20501,7 @@ function computePlan(input2) {
       name: skill.name,
       state,
       version: skill.version,
+      release: releaseOf(skill.files),
       action: actionFor(
         state,
         local !== void 0,
@@ -20019,14 +20515,18 @@ function computePlan(input2) {
   }
   return plans.sort((a, b) => a.name < b.name ? -1 : 1);
 }
+function versionLabel(plan) {
+  return plan.release ?? `v${plan.version}`;
+}
 function actionFor(state, installed, diffCount, force) {
+  if (state === "inherited") return installed ? "remove" : "inherited";
   if (state === "customized" && !force) return "skip";
   if (!installed) return "install";
   return diffCount === 0 ? "keep" : "update";
 }
 function planHasWrites(plans) {
   return plans.some(
-    (plan) => plan.action === "install" || plan.action === "update"
+    (plan) => plan.action === "install" || plan.action === "update" || plan.action === "remove"
   );
 }
 
@@ -20083,8 +20583,9 @@ async function syncSurface(session, surface, options) {
   });
   printHeader(surface);
   printPlan(plans, blocked, surface);
-  printNotes(surface, inventory.value.items);
-  if (options.dryRun || !planHasWrites(plans)) return Result.ok(void 0);
+  printNotes(surface, inventory.value.items, session.baseUrl);
+  if (options.dryRun) return Result.ok(void 0);
+  if (!planHasWrites(plans)) return clearPending(session, surfaceId);
   if (!options.yes && !await confirm("Apply?")) {
     process.stdout.write("Nothing applied.\n");
     return Result.ok(void 0);
@@ -20094,7 +20595,8 @@ async function syncSurface(session, surface, options) {
   const rescanned = await scanSurface(
     surface.descriptor.path,
     surface.descriptor.label,
-    surface.descriptor.machineId
+    surface.descriptor.machineId,
+    surface.descriptor.scope
   );
   const reposted = await postInventory(session, rescanned);
   if (reposted.isFailure) return Result.fail(reposted.error);
@@ -20104,9 +20606,15 @@ async function maybeAdopt(session, surface, inventory, options) {
   const importable = inventory.items.filter((item) => item.importable);
   if (importable.length === 0 || options.dryRun) return Result.ok(inventory);
   const wanted = options.adopt || !options.yes && await confirm(
-    `Adopt ${plural(importable.length)} found here as approved in your directory?`
+    `Adopt ${plural(importable.length, "skill")} found here as approved in your directory?`
   );
   if (!wanted) return Result.ok(inventory);
+  process.stdout.write(
+    dim(
+      `adopting ${plural(importable.length, "skill")}, this can take a minute...
+`
+    )
+  );
   const adopted = await apiRequest({
     session,
     method: "POST",
@@ -20125,7 +20633,7 @@ async function maybeAdopt(session, surface, inventory, options) {
   const names = adopted.value.adopted;
   process.stdout.write(
     names.length === 0 ? `${dim("nothing adopted")}
-` : `adopted ${plural(names.length)} as approved: ${names.join(", ")}
+` : `adopted ${plural(names.length, "skill")} as approved: ${names.join(", ")}
 `
   );
   for (const skip of adopted.value.skipped) {
@@ -20135,11 +20643,26 @@ async function maybeAdopt(session, surface, inventory, options) {
   if (adopted.value.adopted.length === 0) return Result.ok(inventory);
   return postInventory(session, surface);
 }
-function plural(n) {
-  return `${n} skill${n === 1 ? "" : "s"}`;
-}
 async function applyPlan(surface, plans, approved) {
   for (const plan of plans) {
+    if (plan.action === "remove") {
+      if (!exists(join8(globalSkillsRoot(), plan.name))) {
+        process.stdout.write(
+          `${plan.name}: no longer in ~/.claude/skills, keeping the copy here
+`
+        );
+        continue;
+      }
+      await rm4(join8(surface.descriptor.path, plan.name), {
+        recursive: true,
+        force: true
+      });
+      process.stdout.write(
+        `removed ${plan.name} (inherited from ~/.claude/skills)
+`
+      );
+      continue;
+    }
     if (plan.action !== "install" && plan.action !== "update") continue;
     const skill = approved.find((entry) => entry.name === plan.name);
     if (skill === void 0) continue;
@@ -20159,19 +20682,19 @@ async function applyPlan(surface, plans, approved) {
     });
     if (written.isFailure) return written;
     process.stdout.write(
-      `${plan.action === "install" ? "installed" : "updated"} ${plan.name} v${plan.version}
+      `${plan.action === "install" ? "installed" : "updated"} ${plan.name} ${versionLabel(plan)}
 `
     );
   }
   return Result.ok(void 0);
 }
 async function writeTarget(root, name) {
-  const dir = join6(root, name);
-  const stats = await lstat(dir).catch(() => null);
+  const dir = join8(root, name);
+  const stats = await lstat2(dir).catch(() => null);
   if (stats === null || !stats.isSymbolicLink()) return Result.ok(dir);
   const target = await realpath2(dir).catch(() => null);
-  const home2 = await realpath2(homedir5()).catch(() => homedir5());
-  if (target === null || !isInside(target, home2) || isInside(target, await realpath2(root).catch(() => resolve6(root)))) {
+  const home2 = await realpath2(homedir6()).catch(() => homedir6());
+  if (target === null || !isInside(target, home2) || isInside(target, await realpath2(root).catch(() => resolve7(root)))) {
     return Result.fail(
       new CliError(
         "UNSAFE_LINK",
@@ -20182,7 +20705,7 @@ async function writeTarget(root, name) {
   return Result.ok(target);
 }
 async function containsSymlink(dir) {
-  const entries = await readdir3(dir, {
+  const entries = await readdir4(dir, {
     recursive: true,
     withFileTypes: true
   }).catch(() => []);
@@ -20211,24 +20734,27 @@ async function clearPending(session, surfaceId) {
   return Result.ok(void 0);
 }
 function printPlan(plans, blocked, surface) {
+  const listed = plans.filter((plan) => plan.action !== "inherited");
   const rows = [
-    ...plans.map((plan) => [
+    ...listed.map((plan) => [
       plan.action,
       plan.name,
       originOf(surface, plan.name),
-      `v${plan.version}`,
+      versionLabel(plan),
       detailOf(plan)
     ]),
     ...blocked.map((skill) => [
       accent("blocked"),
       skill.name,
       originOf(surface, skill.name),
-      `v${skill.version}`,
+      versionLabel({ version: skill.version, release: releaseOf(skill.files) }),
       `org policy: ${skill.blockedReason ?? "no reason given"}`
     ])
   ];
+  const inherited = plans.length - listed.length;
   if (rows.length === 0) {
-    process.stdout.write(`${dim("nothing to sync")}
+    const note = inherited > 0 ? `nothing to sync, ${inherited} inherited from ~/.claude/skills` : "nothing to sync";
+    process.stdout.write(`${dim(note)}
 
 `);
     return;
@@ -20254,6 +20780,11 @@ function printPlan(plans, blocked, surface) {
     [plans.filter((plan) => plan.action === "install").length, "to install"],
     [plans.filter((plan) => plan.action === "update").length, "to update"],
     [plans.filter((plan) => plan.action === "keep").length, "up to date"],
+    [plans.filter((plan) => plan.action === "remove").length, "to remove"],
+    [
+      plans.filter((plan) => plan.action === "inherited").length,
+      "inherited from ~/.claude/skills"
+    ],
     [plans.filter((plan) => plan.action === "skip").length, "skipped"],
     [blocked.length, "blocked"]
   ];
@@ -20268,10 +20799,123 @@ function detailOf(plan) {
   if (plan.action === "skip") {
     return `${accent("customized locally")}, use --force to overwrite`;
   }
+  if (plan.action === "remove") {
+    return "duplicate of ~/.claude/skills, Claude Code loads it from there";
+  }
   if (plan.action === "install") return `+${plan.added.length}`;
   return `+${plan.added.length} ~${plan.changed.length} -${plan.removed.length}`;
 }
 
+// src/commands/upgrade.ts
+import { spawn } from "node:child_process";
+import { homedir as homedir7 } from "node:os";
+import { resolve as resolve8 } from "node:path";
+function globalRoot() {
+  return {
+    label: "global",
+    cwd: homedir7(),
+    scope: "-g",
+    lockPath: globalLockPath()
+  };
+}
+function projectRoot(dir) {
+  return {
+    label: shortPath(resolve8(dir)),
+    cwd: resolve8(dir),
+    scope: "-p",
+    lockPath: projectLockPath(dir)
+  };
+}
+function upgradeRoots(path, all, registered) {
+  const dir = resolve8(path ?? process.cwd());
+  const hasProject = exists(projectSkillsRoot(dir));
+  if (!all) return [hasProject ? projectRoot(dir) : globalRoot()];
+  return [
+    globalRoot(),
+    ...projectDirs(
+      hasProject || path !== void 0 ? dir : void 0,
+      registered
+    ).map(projectRoot)
+  ];
+}
+function runSkills(root, names, yes) {
+  const args = ["--yes", "skills", "update", ...names, root.scope];
+  if (yes) args.push("-y");
+  return new Promise((settle) => {
+    const child = spawn("npx", args, { cwd: root.cwd, stdio: "inherit" });
+    child.on("error", (cause) => {
+      settle(
+        Result.fail(
+          new CliError(
+            "NO_NPX",
+            `Cannot run npx: ${cause.message}. The skills.sh CLI applies the update, install Node's npx and retry.`
+          )
+        )
+      );
+    });
+    child.on("close", (code) => {
+      settle(
+        code === 0 || code === null ? Result.ok(void 0) : Result.fail(
+          new CliError(
+            "SKILLS_FAILED",
+            `npx skills update exited with ${code} in ${root.cwd}.`
+          )
+        )
+      );
+    });
+  });
+}
+async function upgrade(options) {
+  const config2 = await readConfig();
+  const registered = config2.isSuccess ? config2.value.projects : [];
+  const named = options.names.length > 0;
+  const roots = upgradeRoots(options.path, options.all || named, registered);
+  let ran = 0;
+  const found = /* @__PURE__ */ new Set();
+  for (const root of roots) {
+    const lock = await readLock(root.lockPath);
+    const names = options.names.filter((name) => lock.has(name));
+    if (named && names.length === 0) continue;
+    if (!named && lock.size === 0) {
+      process.stdout.write(
+        dim(`${root.label}: no skills.sh lock here, nothing to upgrade
+`)
+      );
+      continue;
+    }
+    for (const name of names) found.add(name);
+    process.stdout.write(
+      `
+${bold(root.label)}  ${dim(named ? names.join(", ") : plural(lock.size, "skill"))}
+`
+    );
+    const result = await runSkills(root, names, options.yes);
+    if (result.isFailure) return result;
+    ran += 1;
+  }
+  const missing = options.names.filter((name) => !found.has(name));
+  if (missing.length > 0) {
+    return Result.fail(
+      new CliError(
+        "NOT_FROM_SKILLS_SH",
+        `No skills.sh lock lists ${missing.join(", ")}. \`npx hubskillz doctor\` lists what is installed where.`
+      )
+    );
+  }
+  if (ran === 0) {
+    process.stdout.write(
+      dim("Nothing installed by `npx skills add` in these roots.\n")
+    );
+    return Result.ok(void 0);
+  }
+  process.stdout.write(
+    dim(
+      "\nUpstream content now sits on disk. Run `npx hubskillz status` to see it against your approved versions, `npx hubskillz sync` to go back to them.\n"
+    )
+  );
+  return Result.ok(void 0);
+}
+
 // src/index.ts
 var GLOBAL_FLAGS = [
   {
@@ -20333,6 +20977,54 @@ var COMMANDS = [
       { spec: "--force", help: "Overwrite skills you customized locally" }
     ]
   },
+  {
+    name: "upgrade",
+    usage: "hubskillz upgrade [SKILL...] [--path DIR] [--all] [--yes]",
+    summary: "Update skills.sh skills to their latest upstream",
+    flags: [
+      {
+        spec: "--path DIR",
+        help: "Project directory (default: current directory)"
+      },
+      { spec: "--all", help: "Global root and every registered project" },
+      { spec: "-y, --yes", help: "Skip the skills.sh prompts" }
+    ]
+  },
+  {
+    name: "doctor",
+    usage: "hubskillz doctor [--path DIR]",
+    summary: "Check every local skills root for problems",
+    flags: [
+      {
+        spec: "--path DIR",
+        help: "Project directory (default: current directory)"
+      }
+    ]
+  },
+  {
+    name: "move",
+    usage: "hubskillz move <skill> <global|DIR> [--from global|DIR] [--force]",
+    summary: "Move a skill between the global root and a project",
+    flags: [
+      {
+        spec: "--from ROOT",
+        help: "Which copy to move when the name exists twice"
+      },
+      { spec: "--force", help: "Replace a skill of the same name over there" }
+    ]
+  },
+  {
+    name: "publish",
+    usage: "hubskillz publish <skill>",
+    summary: "List the skill on your public page",
+    flags: []
+  },
+  {
+    name: "unpublish",
+    usage: "hubskillz unpublish <skill>",
+    summary: "Take the skill off your public page",
+    flags: []
+  },
   {
     name: "push",
     usage: "hubskillz push <skill-dir> [-m MESSAGE]",
@@ -20353,7 +21045,7 @@ function flagLines(flags) {
 }
 function usage() {
   const width = Math.max(...COMMANDS.map((command) => command.name.length));
-  return `${bold("hubskillz")} ${dim(`v${"0.3.0"}`)}  keep your agent skills in sync
+  return `${bold("hubskillz")} ${dim(`v${"0.4.0"}`)}  keep your agent skills in sync
 
 ${bold("Usage")}
   hubskillz <command> [flags]
@@ -20420,6 +21112,7 @@ async function run() {
         "dry-run": { type: "boolean", default: false },
         force: { type: "boolean", default: false },
         message: { type: "string", short: "m" },
+        from: { type: "string" },
         help: { type: "boolean", short: "h", default: false },
         version: { type: "boolean", short: "v", default: false }
       }
@@ -20432,7 +21125,7 @@ Run \`hubskillz help\` for usage.`)
     );
   }
   if (values.version === true) {
-    process.stdout.write(`${"0.3.0"}
+    process.stdout.write(`${"0.4.0"}
 `);
     return Result.ok(void 0);
   }
@@ -20463,6 +21156,50 @@ Run \`hubskillz help\` for usage.`)
         dryRun: values["dry-run"] === true,
         force: values.force === true
       });
+    case "upgrade":
+      return upgrade({
+        names: positionals.slice(1),
+        path: values.path,
+        all: values.all === true,
+        yes: values.yes === true
+      });
+    case "doctor":
+      return doctor({ path: values.path });
+    case "move": {
+      const name = positionals[1];
+      if (name === void 0) {
+        return Result.fail(
+          new CliError(
+            "USAGE",
+            "hubskillz move needs a skill name. Run `hubskillz help move`."
+          )
+        );
+      }
+      return move({
+        name,
+        to: positionals[2],
+        from: values.from,
+        path: values.path,
+        force: values.force === true
+      });
+    }
+    case "publish":
+    case "unpublish": {
+      const name = positionals[1];
+      if (name === void 0) {
+        return Result.fail(
+          new CliError(
+            "USAGE",
+            `hubskillz ${command} needs a skill name. Run \`hubskillz help ${command}\`.`
+          )
+        );
+      }
+      return publish({
+        baseUrl: values["base-url"],
+        name,
+        published: command === "publish"
+      });
+    }
     case "projects":
       return projects({
         action: positionals[1],