@neta-art/neta-search-cli 0.2.18 → 0.2.23

package/README.md

@@ -18,6 +18,8 @@ npx -y @neta-art/neta-search-cli@latest skills init <name>               # scaff
 
 `use` prints the skill directory and the full SKILL.md, so an agent can follow it right away; relative paths in SKILL.md resolve against that directory. If the local entry is a pointer (frontmatter `metadata.neta-skill-id`), `use` fetches the full skill it points to.
 
+Each `find --json` item carries a ready-to-run `use` command (`skills use <id> --via find`); prefix it with `npx -y @neta-art/neta-search-cli@latest` or `neta-search`. `--via` only labels where the use came from in usage stats.
+
 Use `@latest` (or an exact version): with a range such as `@0.2`, npx keeps running whatever matching version it cached earlier and never checks for a newer one.
 
 Inside a Cohub sandbox the CLI picks up the sandbox identity automatically; elsewhere it runs anonymously.

package/neta-search.mjs

@@ -7021,8 +7021,8 @@ var require_util2 = __commonJS({
     function createDeferredPromise() {
       let res;
       let rej;
-      const promise = new Promise((resolve, reject) => {
-        res = resolve;
+      const promise = new Promise((resolve2, reject) => {
+        res = resolve2;
         rej = reject;
       });
       return { promise, resolve: res, reject: rej };
@@ -8526,8 +8526,8 @@ Content-Type: ${value.type || "application/octet-stream"}\r
                 });
               }
             });
-            const busboyResolve = new Promise((resolve, reject) => {
-              busboy.on("finish", resolve);
+            const busboyResolve = new Promise((resolve2, reject) => {
+              busboy.on("finish", resolve2);
               busboy.on("error", (err) => reject(new TypeError(err)));
             });
             if (this.body !== null) for await (const chunk of consumeBody(this[kState].body)) busboy.write(chunk);
@@ -9061,9 +9061,9 @@ var require_dispatcher_base = __commonJS({
       }
       close(callback) {
         if (callback === void 0) {
-          return new Promise((resolve, reject) => {
+          return new Promise((resolve2, reject) => {
             this.close((err, data) => {
-              return err ? reject(err) : resolve(data);
+              return err ? reject(err) : resolve2(data);
             });
           });
         }
@@ -9101,12 +9101,12 @@ var require_dispatcher_base = __commonJS({
           err = null;
         }
         if (callback === void 0) {
-          return new Promise((resolve, reject) => {
+          return new Promise((resolve2, reject) => {
             this.destroy(err, (err2, data) => {
               return err2 ? (
                 /* istanbul ignore next: should never error */
                 reject(err2)
-              ) : resolve(data);
+              ) : resolve2(data);
             });
           });
         }
@@ -10166,16 +10166,16 @@ var require_client = __commonJS({
         return this[kNeedDrain] < 2;
       }
       async [kClose]() {
-        return new Promise((resolve) => {
+        return new Promise((resolve2) => {
           if (!this[kSize]) {
-            resolve(null);
+            resolve2(null);
           } else {
-            this[kClosedResolve] = resolve;
+            this[kClosedResolve] = resolve2;
           }
         });
       }
       async [kDestroy](err) {
-        return new Promise((resolve) => {
+        return new Promise((resolve2) => {
           const requests = this[kQueue].splice(this[kPendingIdx]);
           for (let i = 0; i < requests.length; i++) {
             const request3 = requests[i];
@@ -10186,7 +10186,7 @@ var require_client = __commonJS({
               this[kClosedResolve]();
               this[kClosedResolve] = null;
             }
-            resolve();
+            resolve2();
           };
           if (this[kHTTP2Session] != null) {
             util.destroy(this[kHTTP2Session], err);
@@ -10766,7 +10766,7 @@ var require_client = __commonJS({
         });
       }
       try {
-        const socket = await new Promise((resolve, reject) => {
+        const socket = await new Promise((resolve2, reject) => {
           client[kConnector]({
             host,
             hostname,
@@ -10778,7 +10778,7 @@ var require_client = __commonJS({
             if (err) {
               reject(err);
             } else {
-              resolve(socket2);
+              resolve2(socket2);
             }
           });
         });
@@ -11402,12 +11402,12 @@ upgrade: ${upgrade}\r
           cb();
         }
       }
-      const waitForDrain = () => new Promise((resolve, reject) => {
+      const waitForDrain = () => new Promise((resolve2, reject) => {
         assert2(callback === null);
         if (socket[kError]) {
           reject(socket[kError]);
         } else {
-          callback = resolve;
+          callback = resolve2;
         }
       });
       if (client[kHTTPConnVersion] === "h2") {
@@ -11752,8 +11752,8 @@ var require_pool_base = __commonJS({
         if (this[kQueue].isEmpty()) {
           return Promise.all(this[kClients].map((c) => c.close()));
         } else {
-          return new Promise((resolve) => {
-            this[kClosedResolve] = resolve;
+          return new Promise((resolve2) => {
+            this[kClosedResolve] = resolve2;
           });
         }
       }
@@ -12331,7 +12331,7 @@ var require_readable = __commonJS({
         if (this.closed) {
           return Promise.resolve(null);
         }
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           const signalListenerCleanup = signal ? util.addAbortListener(signal, () => {
             this.destroy();
           }) : noop;
@@ -12340,7 +12340,7 @@ var require_readable = __commonJS({
             if (signal && signal.aborted) {
               reject(signal.reason || Object.assign(new Error("The operation was aborted"), { name: "AbortError" }));
             } else {
-              resolve(null);
+              resolve2(null);
             }
           }).on("error", noop).on("data", function(chunk) {
             limit -= chunk.length;
@@ -12362,11 +12362,11 @@ var require_readable = __commonJS({
         throw new TypeError("unusable");
       }
       assert2(!stream[kConsume]);
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve2, reject) => {
         stream[kConsume] = {
           type,
           stream,
-          resolve,
+          resolve: resolve2,
           reject,
           length: 0,
           body: []
@@ -12401,12 +12401,12 @@ var require_readable = __commonJS({
       }
     }
     function consumeEnd(consume2) {
-      const { type, body, resolve, stream, length } = consume2;
+      const { type, body, resolve: resolve2, stream, length } = consume2;
       try {
         if (type === "text") {
-          resolve(toUSVString(Buffer.concat(body)));
+          resolve2(toUSVString(Buffer.concat(body)));
         } else if (type === "json") {
-          resolve(JSON.parse(Buffer.concat(body)));
+          resolve2(JSON.parse(Buffer.concat(body)));
         } else if (type === "arrayBuffer") {
           const dst = new Uint8Array(length);
           let pos = 0;
@@ -12414,12 +12414,12 @@ var require_readable = __commonJS({
             dst.set(buf, pos);
             pos += buf.byteLength;
           }
-          resolve(dst.buffer);
+          resolve2(dst.buffer);
         } else if (type === "blob") {
           if (!Blob2) {
             Blob2 = __require("buffer").Blob;
           }
-          resolve(new Blob2(body, { type: stream[kContentType] }));
+          resolve2(new Blob2(body, { type: stream[kContentType] }));
         }
         consumeFinish(consume2);
       } catch (err) {
@@ -12674,9 +12674,9 @@ var require_api_request = __commonJS({
     };
     function request3(opts, callback) {
       if (callback === void 0) {
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           request3.call(this, opts, (err, data) => {
-            return err ? reject(err) : resolve(data);
+            return err ? reject(err) : resolve2(data);
           });
         });
       }
@@ -12849,9 +12849,9 @@ var require_api_stream = __commonJS({
     };
     function stream(opts, factory, callback) {
       if (callback === void 0) {
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           stream.call(this, opts, factory, (err, data) => {
-            return err ? reject(err) : resolve(data);
+            return err ? reject(err) : resolve2(data);
           });
         });
       }
@@ -13132,9 +13132,9 @@ var require_api_upgrade = __commonJS({
     };
     function upgrade(opts, callback) {
       if (callback === void 0) {
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           upgrade.call(this, opts, (err, data) => {
-            return err ? reject(err) : resolve(data);
+            return err ? reject(err) : resolve2(data);
           });
         });
       }
@@ -13223,9 +13223,9 @@ var require_api_connect = __commonJS({
     };
     function connect3(opts, callback) {
       if (callback === void 0) {
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           connect3.call(this, opts, (err, data) => {
-            return err ? reject(err) : resolve(data);
+            return err ? reject(err) : resolve2(data);
           });
         });
       }
@@ -16847,7 +16847,7 @@ var require_fetch = __commonJS({
       async function dispatch({ body }) {
         const url = requestCurrentURL(request3);
         const agent = fetchParams.controller.dispatcher;
-        return new Promise((resolve, reject) => agent.dispatch(
+        return new Promise((resolve2, reject) => agent.dispatch(
           {
             path: url.pathname + url.search,
             origin: url.origin,
@@ -16923,7 +16923,7 @@ var require_fetch = __commonJS({
                   }
                 }
               }
-              resolve({
+              resolve2({
                 status,
                 statusText,
                 headersList: headers[kHeadersList],
@@ -16966,7 +16966,7 @@ var require_fetch = __commonJS({
                 const val = headersList[n + 1].toString("latin1");
                 headers[kHeadersList].append(key, val);
               }
-              resolve({
+              resolve2({
                 status,
                 statusText: STATUS_CODES[status],
                 headersList: headers[kHeadersList],
@@ -23943,14 +23943,14 @@ var __asyncValues = function(o) {
   }, i);
   function verb(n) {
     i[n] = o[n] && function(v) {
-      return new Promise(function(resolve, reject) {
-        v = o[n](v), settle(resolve, reject, v.done, v.value);
+      return new Promise(function(resolve2, reject) {
+        v = o[n](v), settle(resolve2, reject, v.done, v.value);
       });
     };
   }
-  function settle(resolve, reject, d, v) {
+  function settle(resolve2, reject, d, v) {
     Promise.resolve(v).then(function(v2) {
-      resolve({ value: v2, done: d });
+      resolve2({ value: v2, done: d });
     }, reject);
   }
 };
@@ -24475,14 +24475,14 @@ var __asyncValues2 = function(o) {
   }, i);
   function verb(n) {
     i[n] = o[n] && function(v) {
-      return new Promise(function(resolve, reject) {
-        v = o[n](v), settle(resolve, reject, v.done, v.value);
+      return new Promise(function(resolve2, reject) {
+        v = o[n](v), settle(resolve2, reject, v.done, v.value);
       });
     };
   }
-  function settle(resolve, reject, d, v) {
+  function settle(resolve2, reject, d, v) {
     Promise.resolve(v).then(function(v2) {
-      resolve({ value: v2, done: d });
+      resolve2({ value: v2, done: d });
     }, reject);
   }
 };
@@ -25217,14 +25217,14 @@ var __asyncValues3 = function(o) {
   }, i);
   function verb(n) {
     i[n] = o[n] && function(v) {
-      return new Promise(function(resolve, reject) {
-        v = o[n](v), settle(resolve, reject, v.done, v.value);
+      return new Promise(function(resolve2, reject) {
+        v = o[n](v), settle(resolve2, reject, v.done, v.value);
       });
     };
   }
-  function settle(resolve, reject, d, v) {
+  function settle(resolve2, reject, d, v) {
     Promise.resolve(v).then(function(v2) {
-      resolve({ value: v2, done: d });
+      resolve2({ value: v2, done: d });
     }, reject);
   }
 };
@@ -25862,17 +25862,17 @@ function closedOrError(reason) {
   return isCancel ? closed() : error(reason);
 }
 function connect2(authority, http2SessionOptions) {
-  let resolve;
+  let resolve2;
   let reject;
   const conn = new Promise((res, rej) => {
-    resolve = res;
+    resolve2 = res;
     reject = rej;
   });
   const newConn = http2.connect(authority, http2SessionOptions);
   newConn.on("connect", onConnect);
   newConn.on("error", onError);
   function onConnect() {
-    resolve === null || resolve === void 0 ? void 0 : resolve(newConn);
+    resolve2 === null || resolve2 === void 0 ? void 0 : resolve2(newConn);
     cleanup();
   }
   function onError(err) {
@@ -25958,13 +25958,13 @@ function ready(conn, options) {
     },
     verify() {
       conn.ref();
-      return new Promise((resolve) => {
+      return new Promise((resolve2) => {
         commonPing(() => {
           if (streamCount == 0)
             conn.unref();
-          resolve(true);
+          resolve2(true);
         });
-        conn.once("error", () => resolve(false));
+        conn.once("error", () => resolve2(false));
       });
     },
     abort(reason) {
@@ -26095,7 +26095,7 @@ function createNodeHttpClient(options) {
 function createNodeHttp1Client(httpOptions) {
   return async function request3(req) {
     const sentinel = createSentinel(req.signal);
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       sentinel.catch((e) => {
         reject(e);
       });
@@ -26106,7 +26106,7 @@ function createNodeHttp1Client(httpOptions) {
           response.on("error", sentinel.reject);
           sentinel.catch((reason) => response.destroy(connectErrorFromNodeReason(reason)));
           const trailer = new Headers();
-          resolve({
+          resolve2({
             status: (_a = response.statusCode) !== null && _a !== void 0 ? _a : 0,
             header: nodeHeaderToWebHeader(response.headers),
             body: h1ResponseIterable(sentinel, response, trailer),
@@ -26121,7 +26121,7 @@ function createNodeHttp2Client(sessionProvider) {
   return function request3(req) {
     const sentinel = createSentinel(req.signal);
     const sessionManager = sessionProvider(req.url);
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       sentinel.catch((e) => {
         reject(e);
       });
@@ -26135,7 +26135,7 @@ function createNodeHttp2Client(sessionProvider) {
             body: h2ResponseIterable(sentinel, stream, sessionManager),
             trailer: h2ResponseTrailer(stream)
           };
-          resolve(response);
+          resolve2(response);
         });
       });
     });
@@ -26200,7 +26200,7 @@ function h2Request(sentinel, sm, url, method, headers, options, onStream) {
         return;
       }
       const rstCode = reason instanceof ConnectError && reason.code == Code.Canceled ? H2Code.CANCEL : H2Code.INTERNAL_ERROR;
-      return new Promise((resolve) => stream.close(rstCode, resolve));
+      return new Promise((resolve2) => stream.close(rstCode, resolve2));
     });
     stream.on("error", function h2StreamError(e) {
       if (stream.writableEnded && unwrapNodeErrorChain(e).map(getNodeErrorProps).some((p) => p.code == "ERR_STREAM_WRITE_AFTER_END")) {
@@ -26252,11 +26252,11 @@ function h2ResponseIterable(sentinel, response, sm) {
 }
 async function sinkRequest(request3, nodeRequest, sentinel) {
   if (request3.body === void 0) {
-    await new Promise((resolve) => nodeRequest.end(resolve));
+    await new Promise((resolve2) => nodeRequest.end(resolve2));
     return;
   }
   const it = request3.body[Symbol.asyncIterator]();
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     writeNext();
     function writeNext() {
       if (sentinel.isRejected()) {
@@ -26264,7 +26264,7 @@ async function sinkRequest(request3, nodeRequest, sentinel) {
       }
       it.next().then((r) => {
         if (r.done === true) {
-          nodeRequest.end(resolve);
+          nodeRequest.end(resolve2);
           return;
         }
         nodeRequest.write(r.value, "binary", function(e) {
@@ -26292,8 +26292,8 @@ function createSentinel(signal) {
   let rej;
   let resolved = false;
   let rejected = false;
-  const p = new Promise((resolve, reject) => {
-    res = resolve;
+  const p = new Promise((resolve2, reject) => {
+    res = resolve2;
     rej = reject;
   });
   const c = {
@@ -26906,6 +26906,21 @@ var SkillFeedbackService = {
   }
 };
 
+// cli/src/version.ts
+import { createRequire } from "node:module";
+var OUR_NAMES = /* @__PURE__ */ new Set(["@neta-search/cli", "@neta-art/neta-search-cli"]);
+function cliVersion() {
+  const req = createRequire(import.meta.url);
+  for (const p of ["./package.json", "../package.json"]) {
+    try {
+      const pkg = req(p);
+      if (pkg.name && OUR_NAMES.has(pkg.name) && pkg.version) return pkg.version;
+    } catch {
+    }
+  }
+  return "0.0.0-unknown";
+}
+
 // cli/src/env.ts
 function detectEnv() {
   const actorId = process.env["COHUB_USER_UUID"] ?? "";
@@ -26925,16 +26940,18 @@ function detectEnv() {
     anonymous: actorId === "" || spaceId === ""
   };
 }
+var SEARCH_TIMEOUT_MS = 15e3;
+var REPORT_TIMEOUT_MS = 3e3;
 function searchClient(env) {
-  const transport = createConnectTransport({ baseUrl: env.apiBase, httpVersion: "1.1" });
+  const transport = createConnectTransport({ baseUrl: env.apiBase, httpVersion: "1.1", defaultTimeoutMs: SEARCH_TIMEOUT_MS });
   return createClient(SearchService, transport);
 }
 function feedbackClient(env) {
-  const transport = createConnectTransport({ baseUrl: env.apiBase, httpVersion: "1.1" });
+  const transport = createConnectTransport({ baseUrl: env.apiBase, httpVersion: "1.1", defaultTimeoutMs: REPORT_TIMEOUT_MS });
   return createClient(SkillFeedbackService, transport);
 }
 function eventContext(env, extra = {}) {
-  const ctx = { source: "cli", ...extra };
+  const ctx = { source: "cli", cli_version: cliVersion(), ...extra };
   if (env.sessionId) ctx["session_id"] = env.sessionId;
   if (env.turnId) ctx["turn_id"] = env.turnId;
   return ctx;
@@ -26958,7 +26975,7 @@ async function reportSkillEvent(env, event, skillId, digest, skillName, extra =
     });
     return true;
   } catch (e) {
-    console.error(`\u4E8B\u4EF6\u4E0A\u62A5\u5931\u8D25\uFF08\u4E0D\u5F71\u54CD${event === "install" ? "\u5B89\u88C5" : "\u4F7F\u7528"}\uFF09\uFF1A${e instanceof Error ? e.message : e}`);
+    console.error(`Note: failed to report the ${event} event (this does not affect the ${event}): ${e instanceof Error ? e.message : e}`);
     return false;
   }
 }
@@ -26978,7 +26995,8 @@ async function cmdFind(query, opts) {
           name: c.name,
           description: c.summary,
           match: c.match,
-          sources: sc.sourceCount || void 0
+          sources: sc.sourceCount || void 0,
+          use: useCommand(c.id)
         };
       })
     );
@@ -26987,22 +27005,26 @@ async function cmdFind(query, opts) {
   }
   const candidates = res.groups.flatMap((g) => g.candidates);
   if (candidates.length === 0) {
-    console.log(`\u672A\u627E\u5230 "${query}" \u76F8\u5173 skill\u3002`);
-    console.log(`\uFF08\u8FD9\u672C\u8EAB\u662F\u6709\u4EF7\u503C\u7684\u9700\u6C42\u4FE1\u53F7\u2014\u2014\u7F3A\u8D27\u6E05\u5355\u4F1A\u9A71\u52A8\u8FD0\u8425\u8865\u6536\u5F55\uFF09`);
+    console.log(`No skills found for "${query}".`);
+    console.log(`(This is a useful demand signal: missing capabilities drive what gets added next.)`);
     return 0;
   }
-  console.log(`\u627E\u5230 ${candidates.length} \u4E2A skill\uFF08query: ${query}\uFF09\uFF1A
+  console.log(`Found ${candidates.length} skill${candidates.length === 1 ? "" : "s"} (query: ${query}):
 `);
   for (const c of candidates) {
     const sc = c;
     console.log(`  ${c.id}`);
     if (c.summary) console.log(`    ${trunc(c.summary, 100)}`);
-    if ((sc.sourceCount || 0) > 1) console.log(`    \u21B3 \u540C\u5185\u5BB9\u526F\u672C\u5DF2\u5F52\u5E76\uFF1A${sc.sourceCount} \u4E2A\u6765\u6E90`);
+    if ((sc.sourceCount || 0) > 1) console.log(`    \u21B3 identical copies merged: ${sc.sourceCount} sources`);
     console.log();
   }
-  console.log(`\u7528 neta-search skills add <id> \u5B89\u88C5\uFF1Bneta-search skills use <id> \u514D\u5B89\u88C5\u8BD5\u7528\u3002`);
+  console.log(`Install: neta-search skills add <id>    Try without installing: neta-search ${useCommand("<id>")}`);
   return 0;
 }
+function useCommand(id) {
+  return `skills use ${id} --via ${FIND_VIA}`;
+}
+var FIND_VIA = "find";
 function trunc(s, n) {
   return s.length > n ? s.slice(0, n - 1) + "\u2026" : s;
 }
@@ -27062,19 +27084,22 @@ var TIMEOUT_MS = 6e4;
 var MAX_TRIES = 4;
 var ArchiveNotFound = class extends Error {
 };
-async function fetchArchive(env, id) {
-  const url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
+var DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+async function fetchArchive(env, id, pin) {
+  let url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
+  if (pin) url += `&digest=${encodeURIComponent(pin)}`;
   const res = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(TIMEOUT_MS) });
-  if (res.status === 404) throw new ArchiveNotFound(`${id} \u4E0D\u5B58\u5728\uFF0C\u6216\u8FD8\u6CA1\u6709\u4E0A\u67B6\u7684\u7248\u672C`);
+  if (res.status === 404) throw new ArchiveNotFound(pin ? `version ${pin} of ${id} is not available` : `${id} does not exist or has no released version`);
   const location = res.headers.get("location");
-  if (res.status < 300 || res.status >= 400 || !location) throw new Error(`\u4E0B\u8F7D ${id} \u5931\u8D25\uFF1AHTTP ${res.status}`);
+  if (res.status < 300 || res.status >= 400 || !location) throw new Error(`failed to download ${id}: HTTP ${res.status}`);
   const digest = res.headers.get("x-skill-digest") ?? "";
   const name = res.headers.get("x-skill-name") ?? id.split("/").pop();
-  if (!digest) throw new Error(`\u4E0B\u8F7D ${id} \u5931\u8D25\uFF1A\u670D\u52A1\u7AEF\u6CA1\u6709\u7ED9\u51FA\u7248\u672C\uFF08x-skill-digest\uFF09`);
+  if (!digest) throw new Error(`failed to download ${id}: the server did not return a version (x-skill-digest)`);
+  if (pin && digest !== pin) throw new Error(`failed to download ${id}: asked for version ${pin}, the server offered ${digest}`);
   const body = await download(new URL(location, url).toString(), id);
   const files = untarGz(body);
   const got = digestOf(new Map(files.map((f) => [f.path, f.data])));
-  if (got !== digest) throw new Error(`\u4E0B\u8F7D\u7684 ${id} \u5185\u5BB9\u6821\u9A8C\u5931\u8D25\uFF08\u671F\u671B ${digest}\uFF0C\u5B9E\u9645 ${got}\uFF09`);
+  if (got !== digest) throw new Error(`downloaded ${id} failed verification (expected ${digest}, got ${got})`);
   const handle = res.headers.get("x-skill-handle") || void 0;
   return { id, handle, name, digest, files };
 }
@@ -27083,7 +27108,7 @@ async function archiveHead(env, id) {
   const res = await fetch(url, { method: "HEAD", redirect: "manual", signal: AbortSignal.timeout(1e4) });
   if (res.status === 404) return null;
   const digest = res.headers.get("x-skill-digest") ?? "";
-  if (res.status < 300 || res.status >= 400 || !digest) throw new Error(`\u67E5\u8BE2 ${id} \u5931\u8D25\uFF1AHTTP ${res.status}`);
+  if (res.status < 300 || res.status >= 400 || !digest) throw new Error(`failed to look up ${id}: HTTP ${res.status}`);
   return {
     id: res.headers.get("x-skill-id") ?? id,
     handle: res.headers.get("x-skill-handle") || void 0,
@@ -27094,12 +27119,19 @@ async function archiveHead(env, id) {
 async function download(url, id) {
   for (let attempt = 1; ; attempt++) {
     const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    if (res.status === 202 && attempt < MAX_TRIES) {
-      const body = await res.json().catch(() => ({}));
-      await new Promise((r) => setTimeout(r, Math.min(Math.max(body.retryAfterMs ?? 2e3, 250), 5e3)));
+    if ((res.status === 202 || res.status === 503) && attempt < MAX_TRIES) {
+      let wait = 2e3;
+      if (res.status === 202) {
+        const body = await res.json().catch(() => ({}));
+        wait = body.retryAfterMs ?? wait;
+      } else {
+        const sec = Number(res.headers.get("retry-after"));
+        if (Number.isFinite(sec) && sec > 0) wait = sec * 1e3;
+      }
+      await new Promise((r) => setTimeout(r, Math.min(Math.max(wait, 250), 5e3)));
       continue;
     }
-    if (!res.ok) throw new Error(`\u4E0B\u8F7D ${id} \u5931\u8D25\uFF1Aregistry \u8FD4\u56DE HTTP ${res.status}`);
+    if (!res.ok) throw new Error(`failed to download ${id}: HTTP ${res.status}`);
     return Buffer.from(await res.arrayBuffer());
   }
 }
@@ -27128,7 +27160,7 @@ function untarGz(gz) {
     const path = paxPath ?? (prefix ? `${prefix}/${name}` : name);
     paxPath = null;
     if (path.startsWith("/") || path.split("/").some((s) => s === ".." || s === "")) {
-      throw new Error(`\u5305\u91CC\u6709\u4E0D\u5B89\u5168\u7684\u8DEF\u5F84\uFF1A${path}`);
+      throw new Error(`unsafe path in archive: ${path}`);
     }
     const mode = parseOctal(hdr.subarray(100, 108));
     out.push({ path, data: Buffer.from(body), exec: (mode & 73) !== 0 });
@@ -27175,14 +27207,17 @@ function isHandle(s) {
   return !parseId(s) && HANDLE_RE.test(s);
 }
 async function resolveRef(env, input) {
-  if (!isHandle(input)) return input;
+  return (await resolveRefDetail(env, input)).ref;
+}
+async function resolveRefDetail(env, input) {
+  if (!isHandle(input)) return { ref: input, unreachable: false };
   try {
     const r = await fetch(`${env.apiBase}/v1/skills/resolve?handle=${encodeURIComponent(input)}`, { signal: AbortSignal.timeout(5e3) });
-    if (!r.ok) return input;
+    if (!r.ok) return { ref: input, unreachable: r.status >= 500 };
     const out = await r.json();
-    return typeof out.id === "string" && parseId(out.id) ? out.id : input;
+    return { ref: typeof out.id === "string" && parseId(out.id) ? out.id : input, unreachable: false };
   } catch {
-    return input;
+    return { ref: input, unreachable: true };
   }
 }
 function ownId(env, name) {
@@ -27222,7 +27257,12 @@ function writeSkill(target, files, source) {
   const trash = join2(dirname(target), `.trash-${target.split("/").pop()}-${process.pid}`);
   const hadOld = existsSync(target);
   if (hadOld) renameSync(target, trash);
-  renameSync(staging, target);
+  try {
+    renameSync(staging, target);
+  } catch (e) {
+    rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
   if (hadOld) rmSync(trash, { recursive: true, force: true });
 }
 var POINTER_RE = /^\s*neta-skill-id:\s*["']?(cohub:[^"'\s]+)["']?\s*$/m;
@@ -27253,13 +27293,13 @@ function sharedOptOut(dir) {
 }
 function shareNotice(id, dir, draft, reported) {
   if (draft) {
-    console.error(`\u63D0\u793A\uFF1A\u8349\u7A3F\u533A\u7684 skill \u4E0D\u4F1A\u5206\u4EAB\u3002\u79FB\u5230 ${SKILLS_DIR}/ \u540E\u518D\u7528\uFF0C\u522B\u4EBA\u5C31\u80FD\u627E\u5230\u5E76\u5B89\u88C5\u5B83\u3002`);
+    console.error(`Note: skills in the drafts directory are not shared. Move it to ${SKILLS_DIR}/ and others will be able to find and install it.`);
   } else if (sharedOptOut(dir)) {
-    console.error(`\u63D0\u793A\uFF1A${id} \u5199\u4E86 share: false\uFF0C\u4E0D\u4F1A\u5206\u4EAB\u7ED9\u522B\u4EBA\u3002`);
+    console.error(`Note: ${id} sets share: false, so it is not shared with others.`);
   } else if (!reported) {
-    console.error(`\u63D0\u793A\uFF1A\u8FD9\u6B21\u6CA1\u80FD\u901A\u77E5\u670D\u52A1\u7AEF\uFF0C${id} \u6682\u672A\u5206\u4EAB\u2014\u2014\u4E0B\u6B21\u4F7F\u7528\u65F6\u4F1A\u518D\u8BD5\u3002`);
+    console.error(`Note: could not reach the server this time, so ${id} is not shared yet; it will retry on the next use.`);
   } else {
-    console.error(`\u63D0\u793A\uFF1A\u4F60\u7528\u7684\u8FD9\u4E00\u7248\u4F1A\u5206\u4EAB\u7ED9\u522B\u4EBA\uFF08\u7F72\u540D\u662F\u4F60\uFF0C\u670D\u52A1\u7AEF\u6838\u5B9E\u540E\u751F\u6548\uFF09\uFF1A${id}\u3002\u4E0D\u60F3\u5206\u4EAB\uFF1A\u5728 SKILL.md \u7684 frontmatter \u52A0 share: false`);
+    console.error(`Note: the version you just used will be shared with others under your name once the server verifies it: ${id}. To opt out, add share: false to the SKILL.md frontmatter.`);
   }
 }
 
@@ -27274,32 +27314,32 @@ async function cmdAdd(idOrName, opts) {
     return graduate(env, name, target, opts);
   }
   if (!parsed) {
-    console.log(`"${idOrName}" \u4E0D\u662F id\u2014\u2014\u6309\u540D\u5B57\u68C0\u7D22\uFF0C\u8BF7\u4ECE\u7ED3\u679C\u91CC\u6311 id \u91CD\u8DD1 add\uFF1A`);
+    console.log(`"${idOrName}" is not an id; searching by name. Pick an id from the results and run add again:`);
     await cmdFind(idOrName, { limit: 5, json: false });
     return 1;
   }
   if (parsed.spaceId === env.spaceId) {
-    console.error(`${idOrName} \u662F\u4F60\u81EA\u5DF1 space \u7684 skill\uFF0C\u4E0D\u9700\u8981\u5B89\u88C5\uFF08\u5B83\u5C31\u5728 ${join3(".agents/skills", name)}/ \u6216\u8349\u7A3F\u533A\uFF09\u3002`);
+    console.error(`${idOrName} is a skill in your own space; no need to install it (it is in ${join3(".agents/skills", name)}/ or your drafts).`);
     return 1;
   }
   let archive;
   try {
     archive = await fetchArchive(env, idOrName);
   } catch (e) {
-    console.error(e instanceof ArchiveNotFound ? `${e.message}\u3002\u5148 neta-search skills find \u770B\u770B\u3002` : String(e instanceof Error ? e.message : e));
+    console.error(e instanceof ArchiveNotFound ? `${e.message}. Try neta-search skills find first.` : String(e instanceof Error ? e.message : e));
     return 1;
   }
   mkdirSync2(opts.dir, { recursive: true });
   writeSkill(target, archive.files, { id: archive.id, digest: archive.digest, handle: archive.handle });
   const report = reportSkillEvent(env, "install", archive.id, archive.digest, name);
   if (opts.json) console.log(JSON.stringify({ installed: archive.id, handle: archive.handle, path: target, digest: archive.digest }));
-  else console.log(`\u5DF2\u5B89\u88C5 ${displayRef(archive)} \u2192 ${target}`);
+  else console.log(`Installed ${displayRef(archive)} \u2192 ${target}`);
   await report;
   return 0;
 }
 async function graduate(env, name, target, opts) {
   if (existsSync2(target)) {
-    console.error(`${target} \u5DF2\u5B58\u5728\u2014\u2014\u8349\u7A3F\u533A\u7684 ${name} \u6CA1\u6709\u79FB\u52A8\uFF08\u5148\u5904\u7406\u6389\u5DF2\u6709\u76EE\u5F55\uFF09\u3002`);
+    console.error(`${target} already exists; draft ${name} was not moved (deal with the existing directory first).`);
     return 1;
   }
   mkdirSync2(opts.dir, { recursive: true });
@@ -27308,120 +27348,275 @@ async function graduate(env, name, target, opts) {
   const digest = skillDirDigest(target);
   const reported = await reportSkillEvent(env, "install", id, digest, name);
   if (opts.json) console.log(JSON.stringify({ graduated: id, path: target, digest }));
-  else console.log(`\u8349\u7A3F ${name} \u5DF2\u79FB\u5230 ${target}`);
+  else console.log(`Moved draft ${name} to ${target}`);
   if (!env.anonymous) shareNotice(id, target, false, reported);
   return 0;
 }
 
 // cli/src/skills/use.ts
-import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { join as join4 } from "node:path";
+import { join as join4, resolve } from "node:path";
+
+// cli/src/mounts.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+var SOURCE_RE = /\/checkpoints\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/latest\/?$/i;
+function mountsFile() {
+  return process.env["NETASEARCH_MOUNTS_FILE"] ?? "/proc/mounts";
+}
+function unescape(s) {
+  return s.replace(/\\([0-7]{3})/g, (_, o) => String.fromCharCode(parseInt(o, 8)));
+}
+function modMounts() {
+  let text;
+  try {
+    text = readFileSync3(mountsFile(), "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split("\n")) {
+    const [src, dir] = line.split(" ");
+    if (!src || !dir) continue;
+    const m = SOURCE_RE.exec(unescape(src));
+    if (m) out.push({ spaceId: m[1].toLowerCase(), dir: unescape(dir) });
+  }
+  return out;
+}
+
+// cli/src/skills/use.ts
 var FETCH_ROOT = process.env["NETASEARCH_FETCH_ROOT"] ?? join4("/tmp", "neta-skills");
+var WHERE_LABEL = {
+  local: "from this space",
+  mod: "from a mounted mod",
+  cache: "from the local cache",
+  fetched: "downloaded"
+};
 async function cmdUse(idOrName, opts) {
   const env = detectEnv();
   const input = idOrName;
-  idOrName = await resolveRef(env, idOrName);
-  let handle = isHandle(input) && parseId(idOrName) ? input.toLowerCase() : void 0;
+  const resolved = await resolveRefDetail(env, idOrName);
+  idOrName = resolved.ref;
   const parsed = parseId(idOrName);
   const name = parsed?.name ?? idOrName;
   const mine = !parsed || parsed.spaceId === env.spaceId;
-  let path = null;
-  let where = "local";
-  let reportId = null;
+  let handle = isHandle(input) && parsed ? input.toLowerCase() : void 0;
+  const via = opts.via ? opts.via.slice(0, 32) : null;
+  let viaPointer = false;
+  const entry = opts.entry ? opts.entry.slice(0, 128) : null;
   let notice = null;
+  let found = null;
   let fetchId = parsed && !mine ? idOrName : null;
-  let via = opts.via ? opts.via.slice(0, 32) : null;
+  const pin = opts.digest?.trim().toLowerCase();
+  if (opts.digest !== void 0) {
+    if (!pin || !DIGEST_RE.test(pin)) {
+      console.error(`--digest must look like sha256:<64 hex characters>, got "${opts.digest}".`);
+      return 1;
+    }
+    if (!parsed) {
+      console.error(
+        resolved.unreachable ? `Cannot reach the server (${env.apiBase}), so handle "${input}" could not be resolved. Try again later.` : `--digest needs a handle or an id (cohub:<space>/<name>); "${input}" is neither.`
+      );
+      return 1;
+    }
+    const r = await pinnedFromCacheOrDownload(env, idOrName, pin);
+    if (!r) return 1;
+    return emit(env, r.found, r.handle ?? handle, name, { via, entry, viaPointer: false, notice: null, json: opts.json, pinned: true });
+  }
   const installed = join4(SKILLS_DIR, name);
   const draft = join4(DRAFTS_DIR, name);
   if (skillDirExists(installed)) {
     const src = readSource(installed);
     if (src && (!parsed || src.id === idOrName)) {
-      path = installed;
-      reportId = src.id;
+      found = { path: installed, where: "local", reportId: src.id };
       handle = handle ?? src.handle;
     } else if (!src && mine) {
-      path = installed;
-      reportId = ownId(env, name);
+      found = { path: installed, where: "local", reportId: ownId(env, name) };
       notice = "shared";
     }
   }
-  if (!path && mine && skillDirExists(draft)) {
-    path = draft;
-    reportId = ownId(env, name);
+  if (!found && mine && skillDirExists(draft)) {
+    found = { path: draft, where: "local", reportId: ownId(env, name) };
     notice = "draft";
   }
-  if (!path && !parsed) {
-    const mod = findInMods(name);
-    if (mod) {
-      path = mod;
-      where = "mod";
-    }
+  if (!found) {
+    const r = findInMounts(parsed?.spaceId ?? null, name);
+    if (r === "ambiguous") return 1;
+    if (r) found = r;
   }
-  if (path) {
-    const target = pointerTarget(path);
+  if (found) {
+    const target = pointerTarget(found.path);
     if (target !== null) {
       if (!parseId(target)) {
-        console.error(`${join4(path, "SKILL.md")} \u662F\u6307\u9488\uFF0C\u4F46\u5B83\u7684 neta-skill-id \u4E0D\u662F\u5408\u6CD5 id\uFF1A${target}`);
+        console.error(`${join4(found.path, "SKILL.md")} is a pointer, but its neta-skill-id is not a valid id: ${target}`);
         return 1;
       }
-      via = "pointer";
+      viaPointer = true;
       fetchId = target;
-      path = null;
-      reportId = null;
+      found = null;
       notice = null;
+      const p = parseId(target);
+      const r = findInMounts(p.spaceId, p.name);
+      if (r && r !== "ambiguous" && pointerTarget(r.path) === null) {
+        found = r;
+        fetchId = null;
+      }
     }
   }
-  if (!path && fetchId) {
-    try {
-      const a = await fetchArchive(env, fetchId);
-      const skillMd2 = a.files.find((f) => f.path === "SKILL.md");
-      if (skillMd2 && pointerTargetOf(skillMd2.data.toString("utf8")) !== null) {
-        console.error(`${fetchId} \u4E0B\u8F7D\u5230\u7684\u5185\u5BB9\u8FD8\u662F\u6307\u9488\uFF0C\u505C\u5728\u8FD9\u91CC\uFF08\u4E0D\u8DDF\u7B2C\u4E8C\u5C42\uFF0C\u9632\u6B62\u7ED5\u5708\uFF09\u3002`);
-        return 1;
-      }
-      const p = parseId(a.id);
-      path = join4(FETCH_ROOT, p.spaceId, p.name);
-      const have = readSource(path);
-      if (!skillDirExists(path) || have?.digest !== a.digest) writeSkill(path, a.files, { id: a.id, digest: a.digest, handle: a.handle });
-      reportId = a.id;
-      handle = a.handle ?? handle;
-      where = "fetched";
-    } catch (e) {
-      console.error(e instanceof ArchiveNotFound ? `${e.message}\u3002` : String(e instanceof Error ? e.message : e));
+  if (!found && fetchId) {
+    const r = await fromCacheOrDownload(env, fetchId);
+    if (!r) return 1;
+    found = r.found;
+    handle = r.handle ?? handle;
+  }
+  if (!found) {
+    if (resolved.unreachable) {
+      console.error(`Cannot reach the server (${env.apiBase}), so handle "${input}" could not be resolved. Try again later; if the mod is mounted here, you can read /mods/<mod>/.agents/skills/<name>/SKILL.md directly.`);
       return 1;
     }
-  }
-  if (!path) {
-    console.error(`skill "${idOrName}" \u672C\u5730\u6CA1\u6709\u2014\u2014\u5148 neta-search skills find "${name}" \u62FF\u5230 id\u3002`);
+    console.error(`Skill "${idOrName}" is not available locally. Run neta-search skills find "${name}" to get its id.`);
     return 1;
   }
+  return emit(env, found, handle, name, { via, entry, viaPointer, notice, json: opts.json, pinned: false });
+}
+async function emit(env, found, handle, name, o) {
+  const { via, entry, viaPointer, notice } = o;
   const useId = randomUUID();
-  const extra = { use_id: useId };
+  const extra = { use_id: useId, where: found.where };
   if (via) extra["via"] = via;
-  const reported = reportId ? await reportSkillEvent(env, "use", reportId, skillDirDigest(path), name, extra) : false;
-  const skillMd = readFileSync3(join4(path, "SKILL.md"), "utf8");
-  if (opts.json) {
-    console.log(JSON.stringify({ skill: reportId ?? name, handle, path, where, use_id: reportId ? useId : void 0, skill_md: skillMd }));
+  if (entry) extra["entry"] = entry;
+  if (o.pinned) extra["pinned"] = "true";
+  const digest = found.where === "mod" ? "" : found.digest ?? skillDirDigest(found.path);
+  const reported = found.reportId ? await reportSkillEvent(env, "use", found.reportId, digest, name, extra) : false;
+  const skillMd = readFileSync4(join4(found.path, "SKILL.md"), "utf8");
+  const dir = resolve(found.path);
+  const shown = handle ?? found.reportId ?? name;
+  if (o.json) {
+    console.log(
+      JSON.stringify({
+        skill: found.reportId ?? name,
+        handle,
+        path: dir,
+        where: found.where,
+        entry: entry ?? void 0,
+        use_id: found.reportId ? useId : void 0,
+        skill_md: skillMd
+      })
+    );
   } else {
-    const label = { local: "\u672C\u5730", mod: "\u5E73\u53F0 mod", fetched: "\u5DF2\u4E0B\u8F7D\u5230\u4E34\u65F6\u76EE\u5F55" }[where];
-    console.log(`${handle ?? reportId ?? name} \u5C31\u7EEA\uFF08${label}${via === "pointer" ? "\uFF0C\u7ECF\u6307\u9488" : ""}\uFF09`);
-    console.log(`skill \u76EE\u5F55\uFF1A${path}`);
-    console.log(`SKILL.md \u91CC\u7684\u76F8\u5BF9\u8DEF\u5F84\u90FD\u4ECE\u8FD9\u4E2A\u76EE\u5F55\u7B97\u8D77\u3002\u4E0B\u9762\u5C31\u662F SKILL.md \u7684\u5168\u6587\uFF0C\u7167\u7740\u505A\u5373\u53EF\uFF08\u4E0D\u7528\u518D\u8BFB\u4E00\u6B21\u6587\u4EF6\uFF09\u3002`);
-    console.log(`
------ SKILL.md -----
-${skillMd}${skillMd.endsWith("\n") ? "" : "\n"}----- end -----`);
-  }
-  if (notice && reportId && !env.anonymous) shareNotice(reportId, path, notice === "draft", reported);
+    console.log(`You are being given a skill to execute for the user's request: ${shown} (${WHERE_LABEL[found.where]}${viaPointer ? ", via a pointer" : ""}).`);
+    console.log(`Use the following SKILL.md as your instructions:
+`);
+    console.log(`<SKILL.md>
+${skillMd}${skillMd.endsWith("\n") ? "" : "\n"}</SKILL.md>
+`);
+    console.log(`Skill directory: ${dir}`);
+    console.log(`When the SKILL.md references relative paths, read them from that directory.`);
+  }
+  if (notice && found.reportId && !env.anonymous) shareNotice(found.reportId, found.path, notice === "draft", reported);
   return 0;
 }
-function findInMods(name) {
-  if (!existsSync3("/mods")) return null;
-  for (const m of readdirSync2("/mods")) {
-    const p = join4("/mods", m, ".agents/skills", name);
-    if (skillDirExists(p)) return p;
+function findInMounts(spaceId, name) {
+  if (name.includes("/") || name.startsWith(".")) return null;
+  const mounts = modMounts();
+  if (spaceId) {
+    for (const m of mounts) {
+      const p = join4(m.dir, ".agents/skills", name);
+      if (m.spaceId === spaceId && skillDirExists(p)) return { path: p, where: "mod", reportId: `cohub:${spaceId}/${name}` };
+    }
+    return null;
+  }
+  const hits = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of mounts) {
+    seen.add(resolve(m.dir));
+    const p = join4(m.dir, ".agents/skills", name);
+    if (skillDirExists(p)) hits.push({ path: p, where: "mod", reportId: `cohub:${m.spaceId}/${name}` });
+  }
+  if (existsSync3("/mods")) {
+    for (const d of readdirSync2("/mods")) {
+      const dir = join4("/mods", d);
+      if (seen.has(resolve(dir))) continue;
+      const p = join4(dir, ".agents/skills", name);
+      if (skillDirExists(p)) hits.push({ path: p, where: "mod", reportId: null });
+    }
+  }
+  if (hits.length > 1) {
+    console.error(`${hits.length} mounted mods each have a different skill named ${name}:`);
+    for (const h of hits) console.error(`  ${h.path}${h.reportId ? `  (${h.reportId})` : ""}`);
+    console.error(`Use a handle (<prefix>/${name}) to pick one; neta-search skills find "${name}" shows each handle.`);
+    return "ambiguous";
+  }
+  return hits[0] ?? null;
+}
+function pinnedDir(spaceId, name, digest) {
+  return join4(FETCH_ROOT, spaceId, `${name}@${digest.slice("sha256:".length, "sha256:".length + 12)}`);
+}
+async function pinnedFromCacheOrDownload(env, fetchId, pin) {
+  const p = parseId(fetchId);
+  const dir = pinnedDir(p.spaceId, p.name, pin);
+  const have = skillDirExists(dir) ? readSource(dir) : null;
+  if (have && have.id === fetchId && have.digest === pin) {
+    return { found: { path: dir, where: "cache", reportId: have.id, digest: have.digest }, handle: have.handle };
+  }
+  return download2(env, fetchId, pin, dir);
+}
+async function fromCacheOrDownload(env, fetchId) {
+  const p = parseId(fetchId);
+  const cacheDir = join4(FETCH_ROOT, p.spaceId, p.name);
+  const have = skillDirExists(cacheDir) ? readSource(cacheDir) : null;
+  let head;
+  try {
+    head = await archiveHead(env, fetchId);
+  } catch (e) {
+    if (have) {
+      console.error(`Note: cannot reach the server (${e instanceof Error ? e.message : e}); using the cached copy, which may not be the latest.`);
+      return { found: { path: cacheDir, where: "cache", reportId: have.id, digest: have.digest }, handle: have.handle };
+    }
+    console.error(String(e instanceof Error ? e.message : e));
+    return null;
+  }
+  if (head === null) {
+    console.error(`${fetchId} does not exist or has no released version.`);
+    return null;
+  }
+  if (have && have.digest === head.digest) {
+    if (head.handle && head.handle !== have.handle) writeSource(cacheDir, { ...have, handle: head.handle });
+    return { found: { path: cacheDir, where: "cache", reportId: have.id, digest: have.digest }, handle: head.handle ?? have.handle };
+  }
+  return download2(env, fetchId);
+}
+function sameVersion(dir, want) {
+  if (!skillDirExists(dir)) return false;
+  const have = readSource(dir);
+  return !!have && have.id === want.id && have.digest === want.digest;
+}
+async function download2(env, fetchId, pin, target) {
+  try {
+    const a = await fetchArchive(env, fetchId, pin);
+    const skillMd = a.files.find((f) => f.path === "SKILL.md");
+    if (skillMd && pointerTargetOf(skillMd.data.toString("utf8")) !== null) {
+      console.error(`${fetchId} downloaded as another pointer; stopping here (pointers are followed only one level, to avoid loops).`);
+      return null;
+    }
+    const q = parseId(a.id);
+    const path = target ?? join4(FETCH_ROOT, q.spaceId, q.name);
+    const record = { id: a.id, digest: a.digest, handle: a.handle };
+    if (target) {
+      if (sameVersion(path, record)) return { found: { path, where: "fetched", reportId: a.id, digest: a.digest }, handle: a.handle };
+      try {
+        writeSkill(path, a.files, record);
+      } catch (e) {
+        if (!sameVersion(path, record)) throw e;
+      }
+      return { found: { path, where: "fetched", reportId: a.id, digest: a.digest }, handle: a.handle };
+    }
+    writeSkill(path, a.files, record);
+    return { found: { path, where: "fetched", reportId: a.id, digest: a.digest }, handle: a.handle };
+  } catch (e) {
+    console.error(e instanceof ArchiveNotFound ? `${e.message}.` : String(e instanceof Error ? e.message : e));
+    return null;
   }
-  return null;
 }
 
 // cli/src/skills/init.ts
@@ -27429,50 +27624,50 @@ import { existsSync as existsSync4, mkdirSync as mkdirSync3, writeFileSync as wr
 import { join as join5 } from "node:path";
 async function cmdInit(name, opts) {
   if (!name) {
-    console.error(`\u7528\u6CD5\uFF1Aneta-search skills init <name>\uFF08kebab-case\uFF0C\u5982 brawl-creator\uFF09\u3002`);
+    console.error(`Usage: neta-search skills init <name> (kebab-case, e.g. brawl-creator).`);
     return 1;
   }
   const slug = name;
   if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
-    console.error(`skill \u540D\u5FC5\u987B\u662F kebab-case\uFF08\u5982 brawl-creator\uFF09\uFF0C\u6536\u5230 "${slug}"\u3002`);
+    console.error(`Skill names must be kebab-case (e.g. brawl-creator), got "${slug}".`);
     return 1;
   }
   const dir = opts.here ? "." : join5(".agents", "skills-drafts", slug);
   const target = join5(dir, "SKILL.md");
   if (existsSync4(target)) {
-    console.error(`${target} \u5DF2\u5B58\u5728\u2014\u2014init \u4E0D\u8986\u76D6\u3002`);
+    console.error(`${target} already exists; init does not overwrite it.`);
     return 1;
   }
   mkdirSync3(dir, { recursive: true });
   writeFileSync2(target, template(slug));
-  console.log(`\u5DF2\u521B\u5EFA ${target}\uFF08\u8349\u7A3F\u533A\u2014\u2014\u4E0D\u5360 agent \u76EE\u5F55\uFF0C\u5199\u4F5C\u671F\u96F6\u4E0A\u4E0B\u6587\u6210\u672C\uFF09`);
+  console.log(`Created ${target} (drafts directory: not loaded into the agent's skills while you write it)`);
   console.log(`
-\u4E0B\u4E00\u6B65\uFF1A`);
-  console.log(`  1. \u7F16\u8F91 SKILL.md\uFF08description \u5199\u6E05"\u4EC0\u4E48\u65F6\u5019\u7528\u6211"\u2014\u2014agent \u9760\u5B83\u51B3\u5B9A\u7528\u4E0D\u7528\uFF0C\u68C0\u7D22\u4E5F\u9760\u5B83\uFF09`);
-  console.log(`  2. neta-search skills use ${slug} \u8BD5\u8DD1\uFF08\u8349\u7A3F\u533A\u76F4\u63A5\u53EF\u7528\uFF0C\u8349\u7A3F\u4E0D\u4F1A\u5206\u4EAB\uFF09`);
-  console.log(`  3. \u6EE1\u610F\u540E neta-search skills add ${slug}\u2014\u2014\u79FB\u5230 .agents/skills/\uFF0C\u4E4B\u540E\u4F60\u7528\u7684\u90A3\u4E00\u7248\u4F1A\u5206\u4EAB\u7ED9\u522B\u4EBA`);
-  console.log(`     \uFF08\u7F72\u540D\u662F\u4F60\uFF1B\u4E0D\u60F3\u5206\u4EAB\u5C31\u5728 frontmatter \u52A0 share: false\uFF09`);
+Next steps:`);
+  console.log(`  1. Edit SKILL.md. Make the description say when to use this skill; agents decide by it, and search matches on it.`);
+  console.log(`  2. Try it: neta-search skills use ${slug} (drafts work directly and are not shared)`);
+  console.log(`  3. When it is ready: neta-search skills add ${slug} moves it to .agents/skills/; versions you use from there are shared with others`);
+  console.log(`     (under your name; to opt out, add share: false to the frontmatter)`);
   return 0;
 }
 function template(slug) {
   return `---
 name: ${slug}
-description: \u4E00\u53E5\u8BDD\u5199\u6E05\u89E6\u53D1\u573A\u666F\uFF08\u7528\u6237\u641C\u4EC0\u4E48\u8BCD\u8BE5\u627E\u5230\u4F60\uFF09\u2014\u2014\u68C0\u7D22\u4E3B\u5B57\u6BB5
+description: One sentence on when to use this skill (what a user would search for). Search matches on this field.
 metadata:
   neta-scope: universal  # character|world|image|video|audio|text|universal
-  # neta-tags: []        # \u53EF\u9009\uFF1A\u81EA\u62A5\u6807\u7B7E\uFF08\u670D\u52A1\u7AEF\u4F1A\u8865\u7C97\u6807\uFF09
-# disable-model-invocation: true  # \u53EF\u9009\uFF1A\u88C5\u540E\u9690\u85CF\uFF08\u4E0D\u8FDB agent \u76EE\u5F55\uFF0C\u4EC5\u663E\u5F0F\u70B9\u540D/use\uFF09
+  # neta-tags: []        # optional: your own tags (the server adds coarse tags too)
+# disable-model-invocation: true  # optional: hide from the agent's skill list; only runs when named explicitly or via use
 ---
 
 # ${slug}
 
-## \u8FD9\u662F\u4EC0\u4E48
+## What it does
 
-\uFF08\u505A\u4EC0\u4E48\u3001\u7ED9\u8C01\u7528\uFF09
+(What it does and who it is for.)
 
-## \u600E\u4E48\u7528
+## How to use it
 
-\uFF08\u8C03\u7528\u65B9\u5F0F\u3001\u8F93\u5165\u8F93\u51FA\u3001\u793A\u4F8B\uFF09
+(How to call it, inputs and outputs, examples.)
 `;
 }
 
@@ -27515,8 +27710,8 @@ async function statusOf(env, s) {
     return { status: "unknown", error: e instanceof Error ? e.message : String(e) };
   }
 }
-var KIND_LABEL = { installed: "\u88C5\u6765\u7684", pointer: "\u6307\u9488", own: "\u81EA\u5DF1\u5199\u7684" };
-var STATUS_LABEL = { latest: "\u6700\u65B0", outdated: "\u6709\u66F4\u65B0", unavailable: "\u5DF2\u4E0B\u67B6", unknown: "" };
+var KIND_LABEL = { installed: "installed", pointer: "pointer", own: "your own" };
+var STATUS_LABEL = { latest: "latest", outdated: "update available", unavailable: "no longer available", unknown: "" };
 async function cmdList(opts) {
   const env = detectEnv();
   const local = scanLocal(opts.dir);
@@ -27531,10 +27726,10 @@ async function cmdList(opts) {
     return 0;
   }
   if (rows.length === 0) {
-    console.log(`${opts.dir}/ \u91CC\u6CA1\u6709 skill\u3002\u7528 neta-search skills find <\u610F\u56FE> \u627E\uFF0C\u518D add \u5B89\u88C5\u3002`);
+    console.log(`No skills in ${opts.dir}/. Find one with neta-search skills find <what you want>, then add it.`);
     return 0;
   }
-  console.log(`${opts.dir}/\uFF08${rows.length} \u4E2A\uFF09\uFF1A`);
+  console.log(`${opts.dir}/ (${rows.length}):`);
   for (const r of rows) {
     const st = STATUS_LABEL[r.status] ? `  [${STATUS_LABEL[r.status]}]` : "";
     const from = r.id ? `  ${displayRef(r)}` : "";
@@ -27542,7 +27737,7 @@ async function cmdList(opts) {
   }
   const outdated = rows.filter((r) => r.status === "outdated").length;
   if (outdated > 0) console.log(`
-${outdated} \u4E2A\u6709\u66F4\u65B0\uFF1Aneta-search skills update`);
+${outdated} with updates available: neta-search skills update`);
   return 0;
 }
 async function cmdUpdate(names, opts) {
@@ -27596,15 +27791,15 @@ async function cmdUpdate(names, opts) {
     console.log(JSON.stringify({ results }));
     return failed > 0 ? 1 : 0;
   }
-  if (results.length === 0) console.log(`${opts.dir}/ \u91CC\u6CA1\u6709\u88C5\u6765\u7684 skill\uFF0C\u4E0D\u7528\u66F4\u65B0\u3002`);
+  if (results.length === 0) console.log(`No installed skills in ${opts.dir}/; nothing to update.`);
   const say = {
-    updated: (r) => `\u5DF2\u66F4\u65B0 ${r.name}\uFF08${short(r.from)} \u2192 ${short(r.to)}\uFF09`,
-    latest: (r) => `${r.name} \u5DF2\u662F\u6700\u65B0`,
-    unavailable: (r) => `${r.name} \u6765\u6E90\u5DF2\u4E0B\u67B6\u6216\u64A4\u56DE\uFF0C\u4FDD\u7559\u672C\u5730\u526F\u672C`,
-    own_skipped: (r) => `${r.name} \u662F\u4F60\u81EA\u5DF1\u5199\u7684\uFF0C\u4E0D\u7528\u66F4\u65B0`,
-    pointer_skipped: (r) => `${r.name} \u662F\u6307\u9488\uFF0Cuse \u65F6\u603B\u662F\u53D6\u6700\u65B0\uFF0C\u4E0D\u7528\u66F4\u65B0`,
-    not_found: (r) => `${opts.dir}/${r.name} \u4E0D\u5B58\u5728`,
-    error: (r) => `${r.name} \u66F4\u65B0\u5931\u8D25\uFF1A${r.from ?? ""}`
+    updated: (r) => `Updated ${r.name} (${short(r.from)} \u2192 ${short(r.to)})`,
+    latest: (r) => `${r.name} is up to date`,
+    unavailable: (r) => `${r.name} is no longer available from its source; keeping the local copy`,
+    own_skipped: (r) => `${r.name} is your own skill; nothing to update`,
+    pointer_skipped: (r) => `${r.name} is a pointer; use always fetches the latest, nothing to update`,
+    not_found: (r) => `${opts.dir}/${r.name} does not exist`,
+    error: (r) => `Failed to update ${r.name}: ${r.from ?? ""}`
   };
   for (const r of results) console.log(say[r.result](r));
   return failed > 0 ? 1 : 0;
@@ -27632,51 +27827,36 @@ async function cmdRemove(names, opts) {
   if (opts.json) console.log(JSON.stringify({ results }));
   else
     for (const r of results) {
-      if (r.result === "removed") console.log(`\u5DF2\u5220\u9664 ${join6(opts.dir, r.name)}`);
-      else if (r.result === "not_found") console.error(`${join6(opts.dir, r.name)} \u4E0D\u5B58\u5728`);
-      else console.error(`${r.name} \u662F\u4F60\u81EA\u5DF1\u5199\u7684 skill\uFF08\u6CA1\u6709\u5B89\u88C5\u6765\u6E90\uFF09\uFF0C\u6CA1\u5220\u3002\u786E\u5B9A\u8981\u5220\u5C31\u52A0 --force\u3002`);
+      if (r.result === "removed") console.log(`Removed ${join6(opts.dir, r.name)}`);
+      else if (r.result === "not_found") console.error(`${join6(opts.dir, r.name)} does not exist`);
+      else console.error(`${r.name} is a skill you wrote yourself (no install source), so it was not removed. Add --force if you really want to delete it.`);
     }
   return failed > 0 ? 1 : 0;
 }
 
-// cli/src/version.ts
-import { createRequire } from "node:module";
-var OUR_NAMES = /* @__PURE__ */ new Set(["@neta-search/cli", "@neta-art/neta-search-cli"]);
-function cliVersion() {
-  const req = createRequire(import.meta.url);
-  for (const p of ["./package.json", "../package.json"]) {
-    try {
-      const pkg = req(p);
-      if (pkg.name && OUR_NAMES.has(pkg.name) && pkg.version) return pkg.version;
-    } catch {
-    }
-  }
-  return "0.0.0-unknown";
-}
-
 // cli/src/cli.ts
 var program2 = new Command();
-program2.name("neta-search").description("neta-search\u2014\u2014Cohub \u751F\u6001\u68C0\u7D22 CLI\uFF08\u8D44\u6E90\u5B50\u547D\u4EE4\uFF1Askills\uFF1B\u667A\u80FD\u5728 search-api\uFF0CCLI \u662F\u8584\u58F3\uFF09").version(cliVersion());
-var skills = program2.command("skills").description("skill \u57DF\uFF1Afind/add/use/list/update/remove/init");
-skills.command("find").description("\u627E skill\uFF08\u751F\u6001\u8D26\u672C+\u5916\u90E8\u6E90\u6DF7\u6392\u68C0\u7D22\uFF09").argument("<query>", "\u68C0\u7D22\u610F\u56FE\uFF08\u81EA\u7136\u8BED\u8A00/\u5173\u952E\u8BCD\uFF09").option("-n, --limit <n>", "\u5019\u9009\u6570\u4E0A\u9650", "20").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (query, opts) => {
+program2.name("neta-search").description("neta-search: search the Cohub skill ecosystem").version(cliVersion());
+var skills = program2.command("skills").description("skills: find / add / use / list / update / remove / init");
+skills.command("find").description("search the ecosystem for skills").argument("<query>", "what you want to do (natural language or keywords)").option("-n, --limit <n>", "max results", "20").option("--json", "compact JSON output (for agents)").action(async (query, opts) => {
   await run(cmdFind(query, { limit: Number(opts.limit) || 20, json: opts.json }));
 });
-skills.command("add").description("\u88C5 skill\uFF08find \u7ED3\u679C\u7684 id \u6216 handle\uFF1A\u4E0B\u8F7D\u5F53\u524D\u4E0A\u67B6\u7684\u7248\u672C\uFF1B\u6216\u81EA\u5DF1\u8349\u7A3F\u533A\u7684\u540D\u5B57\uFF1A\u79FB\u5230 .agents/skills/\uFF09").argument("<id-or-name>", "find \u8FD4\u56DE\u7684 skill id \u6216 handle\uFF08\u5982 neta-skills/holo-pack-opening\uFF09\uFF0C\u6216\u81EA\u5DF1\u8349\u7A3F\u533A\u7684 skill \u540D").option("--dir <dir>", "\u5B89\u88C5\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (idOrName, opts) => {
+skills.command("add").description("install a skill: an id or handle from find downloads its current release; a name from your drafts moves it into .agents/skills/").argument("<id-or-name>", "skill id or handle from find (e.g. neta-skills/holo-pack-opening), or the name of one of your drafts").option("--dir <dir>", "install directory", ".agents/skills").option("--json", "compact JSON output (for agents)").action(async (idOrName, opts) => {
   await run(cmdAdd(idOrName, opts));
 });
-skills.command("use").description("\u7528 skill\uFF08\u4E0D\u88C5\uFF1A\u6253\u5370 SKILL.md \u5168\u6587\u548C skill \u76EE\u5F55\uFF1B\u672C\u5730\u6709\u2192\u7528\u672C\u5730\u7684\uFF1B\u672C\u5730\u662F\u6307\u9488\u6216\u6CA1\u6709\u2192\u6309 id \u4E0B\u8F7D\u5230\u4E34\u65F6\u76EE\u5F55\uFF09").argument("<id-or-name>", "skill id\u3001handle\uFF08\u5982 neta-skills/holo-pack-opening\uFF09\u6216\u672C\u5730 skill \u540D").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").option("--via <channel>", "\u4ECE\u54EA\u4E2A\u6E20\u9053\u6765\u7684\uFF08\u8BB0\u8FDB\u4F7F\u7528\u8BB0\u5F55\uFF1Bhub mod \u7684\u6307\u9488\u5199 pointer\uFF09").action(async (idOrName, opts) => {
+skills.command("use").description("use a skill without installing it: prints the full SKILL.md and the skill directory (local copy, mounted mod, cache, or download)").argument("<id-or-name>", "skill id, handle (e.g. neta-skills/holo-pack-opening), or local skill name").option("--json", "compact JSON output (for agents)").option("--via <channel>", "where this use came from, recorded in usage stats (site / board-menu / skill-picker / find)").option("--entry <id>", "entry id (picker / menu entry), recorded in usage stats").addOption(new Option("--digest <sha256>", "use exactly this version (sha256:<hex>); needs a handle or id").hideHelp()).action(async (idOrName, opts) => {
   await run(cmdUse(idOrName, opts));
 });
-skills.command("list").alias("ls").description("\u5217\u51FA\u672C\u5730\u7684 skill\uFF08\u88C5\u6765\u7684 / \u6307\u9488 / \u81EA\u5DF1\u5199\u7684\uFF09\uFF0C\u88C5\u6765\u7684\u987A\u5E26\u67E5\u6709\u6CA1\u6709\u66F4\u65B0").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--offline", "\u4E0D\u8054\u7F51\u67E5\u66F4\u65B0").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (opts) => {
+skills.command("list").alias("ls").description("list local skills (installed / pointer / your own) and check installed ones for updates").option("--dir <dir>", "skills directory", ".agents/skills").option("--offline", "do not check for updates online").option("--json", "compact JSON output (for agents)").action(async (opts) => {
   await run(cmdList({ dir: opts.dir, offline: !!opts.offline, json: !!opts.json }));
 });
-skills.command("update").description("\u66F4\u65B0\u88C5\u6765\u7684 skill \u5230\u5F53\u524D\u4E0A\u67B6\u7684\u7248\u672C\uFF08\u4E0D\u7ED9\u540D\u5B57 = \u5168\u90E8\uFF1B\u81EA\u5DF1\u5199\u7684\u548C\u6307\u9488\u4E0D\u78B0\uFF09").argument("[names...]", "\u8981\u66F4\u65B0\u7684 skill\uFF1A\u76EE\u5F55\u540D\u3001handle\uFF08\u5982 neta-skills/holo-pack-opening\uFF09\u6216\u5B9A\u4F4D\u7B26").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (names, opts) => {
+skills.command("update").description("update installed skills to their current release (no names = all; your own skills and pointers are left alone)").argument("[names...]", "skills to update: directory name, handle (e.g. neta-skills/holo-pack-opening), or id").option("--dir <dir>", "skills directory", ".agents/skills").option("--json", "compact JSON output (for agents)").action(async (names, opts) => {
   await run(cmdUpdate(names, { dir: opts.dir, json: !!opts.json }));
 });
-skills.command("remove").alias("rm").description("\u5220\u9664\u672C\u5730 skill\uFF08\u88C5\u6765\u7684 / \u6307\u9488\uFF1B\u81EA\u5DF1\u5199\u7684\u8981 --force\uFF09").argument("<names...>", "\u8981\u5220\u7684 skill\uFF1A\u76EE\u5F55\u540D\u3001handle \u6216\u5B9A\u4F4D\u7B26").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--force", "\u8FDE\u81EA\u5DF1\u5199\u7684\u4E5F\u5220").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (names, opts) => {
+skills.command("remove").alias("rm").description("remove local skills (installed / pointer; your own need --force)").argument("<names...>", "skills to remove: directory name, handle, or id").option("--dir <dir>", "skills directory", ".agents/skills").option("--force", "also remove skills you wrote yourself").option("--json", "compact JSON output (for agents)").action(async (names, opts) => {
   await run(cmdRemove(names, { dir: opts.dir, force: !!opts.force, json: !!opts.json }));
 });
-skills.command("init").description("\u521B\u5EFA skill \u811A\u624B\u67B6\uFF08SKILL.md + frontmatter \u89C4\u8303\uFF09").argument("[name]", "skill \u540D\uFF08kebab-case\uFF09").option("--here", "\u5728\u5F53\u524D\u76EE\u5F55\u751F\u6210\uFF08\u9ED8\u8BA4\u751F\u6210\u5230 ./<name>/ \u5B50\u76EE\u5F55\uFF09").action(async (name, opts) => {
+skills.command("init").description("scaffold a new skill (SKILL.md with frontmatter)").argument("[name]", "skill name (kebab-case)").option("--here", "create SKILL.md in the current directory instead of the drafts directory").action(async (name, opts) => {
   await run(cmdInit(name, opts));
 });
 async function run(p) {
@@ -27684,7 +27864,7 @@ async function run(p) {
   process.exit(code);
 }
 process.on("unhandledRejection", (err) => {
-  console.error(import_picocolors.default.red(`\u9519\u8BEF\uFF1A${err instanceof Error ? err.message : String(err)}`));
+  console.error(import_picocolors.default.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
   process.exit(1);
 });
 program2.parseAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/neta-search-cli",
-  "version": "0.2.18",
+  "version": "0.2.23",
   "description": "neta-search CLI — find, try and install skills from the Cohub / Neta skill registry",
   "type": "module",
   "bin": {