@solgridai/cli 0.1.1 → 0.2.0-beta.0

package/dist/index.js

@@ -2075,7 +2075,7 @@ function useColor() {
 // node_modules/commander/index.js
 var program = new Command;
 // src/build-info.ts
-var buildInfo = { packageName: "@solgridai/cli", version: "0.1.1" };
+var buildInfo = { packageName: "@solgridai/cli", version: "0.2.0-beta.0" };
 
 // src/core/errors.ts
 class CliError extends Error {
@@ -2091,16 +2091,43 @@ class CliError extends Error {
     this.details = options.details ?? [];
     this.data = options.data;
   }
+  copyWith(changes) {
+    return new CliError(this.code, this.message, {
+      hint: changes.hint ?? this.hint,
+      details: this.details,
+      data: changes.data ?? this.data,
+      cause: this
+    });
+  }
 }
 
 class ApiError extends CliError {
   status;
   key;
+  routeMissing;
+  apiKeySentTo;
+  signedUrl;
   constructor(code, message, options = {}) {
     super(code, message, options);
     this.name = "ApiError";
     this.status = options.status;
     this.key = options.key;
+    this.routeMissing = options.routeMissing === true;
+    this.apiKeySentTo = options.apiKeySentTo;
+    this.signedUrl = options.signedUrl === true;
+  }
+  copyWith(changes) {
+    return new ApiError(this.code, this.message, {
+      ...this.status !== undefined ? { status: this.status } : {},
+      ...this.key ? { key: this.key } : {},
+      routeMissing: this.routeMissing,
+      ...this.apiKeySentTo ? { apiKeySentTo: this.apiKeySentTo } : {},
+      signedUrl: this.signedUrl,
+      hint: changes.hint ?? this.hint,
+      details: this.details,
+      data: changes.data ?? this.data,
+      cause: this
+    });
   }
 }
 function errorCodeForStatus(status) {
@@ -2181,7 +2208,19 @@ var isPrice = objectWith({
   selectors: optional(listOf(objectWith({ key: isString, label: optional(isText) }))),
   variants: optional(listOf(objectWith({ when: isObject, price: isLeafPrice }))),
   tiers: optional(listOf(objectWith({ label: isText, when: isObject, price: isLeafPrice }))),
-  notes: optional(listOf(isText))
+  notes: optional(listOf(isText)),
+  unit: optional(isText),
+  unitSize: optional(isNumber),
+  description: optional(isText),
+  rates: optional(listOf(objectWith({
+    meter: isString,
+    unitPriceUsd: isNumber,
+    unitSize: optional(isNumber),
+    freeUnits: optional(isNumber),
+    maximumUnits: optional(isNumber),
+    roundUpTo: optional(isNumber),
+    conditions: optional(isObject)
+  })))
 });
 var isMetrics = objectWith({
   status: isString,
@@ -2225,12 +2264,12 @@ async function inspect(client, params) {
   const data = await client.post("/v1/tools/inspect", params);
   return expectShape("/v1/tools/inspect", data, TOOL_FIELDS);
 }
-async function createRun(client, params, idempotencyKey) {
+async function createRun(client, params, idempotencyKey, request = {}) {
   const data = await client.post("/v1/runs/create", {
     provider: params.provider,
     endpoint: params.endpoint,
     ...params.input ? { input: params.input } : {}
-  }, { "Idempotency-Key": idempotencyKey });
+  }, { "Idempotency-Key": idempotencyKey }, request);
   return expectShape("/v1/runs/create", data, RUN_FIELDS);
 }
 async function stopRun(client, runId) {
@@ -2265,7 +2304,8 @@ var TOOL_FIELDS = {
   provider: isString,
   endpoint: isString,
   description: isText,
-  price: isPrice,
+  price: optional(isPrice),
+  externalPrice: optional(isText),
   tags: optional(listOf(isText)),
   notes: optional(listOf(isText)),
   metrics: optional(isMetrics)
@@ -2540,10 +2580,36 @@ class ApiClient {
     }
     if (!response.ok) {
       const text = await response.text().catch(() => "");
-      throw envelopeError(response, parseEnvelope(text), text, url.split("?")[0] ?? url);
+      throw envelopeError(response, parseEnvelope(text), text, url.split("?")[0] ?? url, {
+        signedUrl: true
+      });
     }
     return response;
   }
+  async openDownload(path) {
+    const url = `${this.baseUrl}${path}`;
+    let response;
+    try {
+      response = await this.options.fetch(url, {
+        method: "GET",
+        headers: {
+          "X-Solgrid-Client": this.options.clientId,
+          ...this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {}
+        },
+        signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS)
+      });
+    } catch (cause) {
+      throw transportError(cause, this.baseUrl, path, TRANSFER_TIMEOUT_MS);
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw envelopeError(response, parseEnvelope(text), text, url, this.sentWith());
+    }
+    return response;
+  }
+  sentWith() {
+    return this.options.apiKey ? { apiKeySentTo: this.baseUrl } : {};
+  }
   async send(method, path, options = {}) {
     const timeoutMs = options.timeoutMs ?? this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     let response;
@@ -2567,7 +2633,7 @@ class ApiClient {
     const url = `${this.baseUrl}${path.split("?")[0] ?? path}`;
     const envelope = parseEnvelope(text);
     if (!response.ok || envelope?.success === false) {
-      throw envelopeError(response, envelope, text, url);
+      throw envelopeError(response, envelope, text, url, this.sentWith());
     }
     if (!envelope || !("data" in envelope)) {
       throw new ApiError("INVALID_RESPONSE", `Unexpected response from ${path}: ${describeBody(response, text)}`, { status: response.status });
@@ -2575,6 +2641,9 @@ class ApiClient {
     return envelope.data;
   }
 }
+function isResponseData(envelope) {
+  return typeof envelope?.success === "boolean";
+}
 function parseEnvelope(text) {
   try {
     const value = JSON.parse(text);
@@ -2583,25 +2652,28 @@ function parseEnvelope(text) {
     return;
   }
 }
-function envelopeError(response, envelope, text, url) {
-  if (!envelope && response.status === 404) {
+function envelopeError(response, envelope, text, url, auth) {
+  if (response.status === 404 && !isResponseData(envelope)) {
     return new ApiError("NOT_FOUND", `${url} does not exist`, {
       status: 404,
+      routeMissing: true,
       hint: "This Solgrid API may not support this command yet, or SOLGRID_API_BASE_URL points to the wrong server."
     });
   }
   const bodyCode = typeof envelope?.code === "number" && envelope.code >= 400 && envelope.code <= 599 ? envelope.code : undefined;
   const status = bodyCode ?? (response.ok ? 400 : response.status);
-  const key = typeof envelope?.message === "string" && envelope.message ? envelope.message : undefined;
+  const serverMessage = typeof envelope?.message === "string" && envelope.message ? envelope.message : undefined;
+  const key = errorKeyOf(envelope);
   const details = [
-    ...validationDetails(envelope?.errorData),
+    ...validationDetails(envelope?.errorData, key),
     ...frameworkErrorDetails(envelope?.errors)
   ];
   const serverJsonHint = hasSerializerErrors(envelope?.errors) ? "The server failed to read JSON while handling this request. This is most likely a problem on the Solgrid side, not in your input; try again later or report it." : undefined;
-  const message = key ?? (envelope ? `HTTP ${response.status}` : `HTTP ${response.status}: ${describeBody(response, text)}`);
+  const message = serverMessage ?? (envelope ? `HTTP ${response.status}` : `HTTP ${response.status}: ${describeBody(response, text)}`);
   return new ApiError(errorCodeForStatus(status), message, {
     status,
     ...key ? { key } : {},
+    ...auth,
     ...serverJsonHint ? { hint: serverJsonHint } : {},
     details
   });
@@ -2616,10 +2688,21 @@ function hasSerializerErrors(errors) {
   const value = errors?.serializerErrors;
   return Array.isArray(value) ? value.length > 0 : typeof value === "string" && value.length > 0;
 }
-function validationDetails(items) {
+var ERROR_KEY = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
+function errorKeyOf(envelope) {
+  const items = Array.isArray(envelope?.errorData) ? envelope.errorData : [];
+  const item = items.find((entry) => entry && !entry.propertyName && typeof entry.errorCode === "string" && ERROR_KEY.test(entry.errorCode));
+  if (item?.errorCode)
+    return item.errorCode;
+  const message = envelope?.message;
+  return typeof message === "string" && ERROR_KEY.test(message) ? message : undefined;
+}
+function validationDetails(items, key) {
   if (!Array.isArray(items))
     return [];
   return items.flatMap((item) => {
+    if (key && !item?.propertyName && item?.errorCode === key)
+      return [];
     const text = item?.errorMessage?.trim();
     if (!text)
       return [];
@@ -2677,6 +2760,62 @@ var KEY_PRESENTATIONS = {
     message: "This tool is not available to run.",
     hint: "Check the provider and endpoint with `solgrid inspect`, or pick another tool with `solgrid discover`."
   },
+  skill_archive_size_invalid: {
+    message: "The Skill package is too large unpacked.",
+    hint: "A Skill may hold at most 10,000,000 bytes of files."
+  },
+  skill_archive_entries_invalid: {
+    message: "The Skill package is empty or has too many entries (at most 1,000).",
+    hint: undefined
+  },
+  skill_archive_file_count_exceeded: {
+    message: "The Skill package has more than 200 files.",
+    hint: undefined
+  },
+  skill_archive_path_invalid: {
+    message: "The Skill package has a path SkillHub does not accept.",
+    hint: "Remove links, encrypted entries, absolute paths, `..`, backslashes, and names that differ only in case."
+  },
+  skill_archive_scripts_not_supported: {
+    message: "This Solgrid server does not accept a scripts directory in a Skill.",
+    hint: "Remove the scripts directories, or try again once the server allows them."
+  },
+  skill_archive_structure_invalid: {
+    message: "The Skill package needs SKILL.md at its top, or inside a single top-level directory.",
+    hint: "Pack the Skill directory with `--dir` and the CLI builds the right layout."
+  },
+  skill_archive_markdown_invalid: {
+    message: "SKILL.md in the package is empty or not valid UTF-8.",
+    hint: undefined
+  },
+  skill_archive_frontmatter_invalid: {
+    message: "SKILL.md must start with YAML frontmatter between --- lines, followed by the instructions.",
+    hint: "The frontmatter needs `name: <the Skill's slug>` and `description: <what it does>`."
+  },
+  skill_archive_name_invalid: {
+    message: "The name in SKILL.md's frontmatter is missing or not valid.",
+    hint: 'Use 1–64 lowercase letters, digits or hyphens, not starting or ending with a hyphen and without "--".'
+  },
+  skill_archive_description_invalid: {
+    message: "The description in SKILL.md's frontmatter is missing or longer than 1,024 characters.",
+    hint: undefined
+  },
+  creative_case_skill_name_mismatch: {
+    message: "The name in SKILL.md must equal the Skill's slug.",
+    hint: "Set `name: <slug>` in SKILL.md's frontmatter, or pass the matching --slug."
+  },
+  creative_case_slug_invalid: {
+    message: "The slug is not valid.",
+    hint: 'Use 1–64 lowercase letters, digits or hyphens, not starting or ending with a hyphen and without "--".'
+  },
+  skill_archive_content_invalid: {
+    message: "The Skill package is damaged or could not be unpacked.",
+    hint: "Pack it again, e.g. with `--dir`."
+  },
+  file_content_type_not_allowed: {
+    message: "Solgrid does not accept this kind of file.",
+    hint: undefined
+  },
   file_size_invalid: {
     message: "The file is larger than Solgrid accepts for its type.",
     hint: "Limits: images and audio 20 MiB, video 200 MiB, Skill ZIP 10 MB."
@@ -2703,7 +2842,10 @@ function presentError(error) {
 }
 function presentApiError(error) {
   const base = explain(error);
-  const hint = [base.hint, error.hint].filter(Boolean).join(`
+  const steps = [base.hint, error.hint];
+  if (error.code === "AUTH_FAILED")
+    steps.reverse();
+  const hint = steps.filter(Boolean).join(`
 `) || undefined;
   return { message: base.message, hint };
 }
@@ -2713,6 +2855,12 @@ function explain(error) {
     return known;
   switch (error.code) {
     case "AUTH_FAILED":
+      if (error.signedUrl) {
+        return {
+          message: "The download link was refused.",
+          hint: "Signed links expire after 24 hours. Get a fresh one (e.g. `solgrid files url -i <fileId>`) and try again."
+        };
+      }
       return {
         message: "The API key is missing, invalid or revoked.",
         hint: `Create a key at ${CONSOLE_URLS.apiKeys}, then run: solgrid keys add -k <key> -l <label>`
@@ -2720,7 +2868,10 @@ function explain(error) {
     case "INVALID_INPUT":
       return { message: `Invalid request: ${error.message}`, hint: undefined };
     case "NOT_FOUND":
-      return { message: `Not found: ${error.message}`, hint: undefined };
+      return {
+        message: error.message === error.key ? `Not found: ${error.message}` : error.message,
+        hint: undefined
+      };
     case "TOO_LARGE":
       return {
         message: "The upload was rejected as too large.",
@@ -2864,13 +3015,14 @@ async function runAction(ctx, json, body) {
   try {
     await body(out);
   } catch (error) {
-    out.error(error);
+    out.error(withAuthContext(ctx, error));
     ctx.exitCode = 1;
   }
 }
 function configStore(ctx) {
   return new ConfigStore(resolveConfigDir(ctx.env, ctx.homeDir));
 }
+var sentKeys = new WeakMap;
 function apiClient(ctx) {
   const resolved = resolveApiKey(configStore(ctx), ctx.env);
   if (!resolved) {
@@ -2878,6 +3030,7 @@ function apiClient(ctx) {
       hint: `Create a key at ${CONSOLE_URLS.apiKeys}, then run: solgrid keys add -k <key> -l <label>`
     });
   }
+  sentKeys.set(ctx, resolved);
   return new ApiClient({
     baseUrl: ctx.env[ENV.apiBaseUrl]?.trim() || DEFAULT_API_BASE_URL,
     apiKey: resolved.key,
@@ -2885,6 +3038,21 @@ function apiClient(ctx) {
     fetch: ctx.fetch
   });
 }
+function withAuthContext(ctx, error) {
+  const key = sentKeys.get(ctx);
+  if (!(error instanceof ApiError) || error.code !== "AUTH_FAILED" || !key)
+    return error;
+  const baseUrl = error.apiKeySentTo;
+  if (!baseUrl)
+    return error;
+  const which = key.source === "env" ? `the key from ${ENV.apiKey} (${maskApiKey(key.key)})` : `key "${key.label}" (${maskApiKey(key.key)})`;
+  const where = baseUrl === DEFAULT_API_BASE_URL ? `${baseUrl}, the production API` : `${baseUrl}, set by ${ENV.apiBaseUrl}`;
+  const advice = baseUrl === DEFAULT_API_BASE_URL ? `If this key is for another environment, set ${ENV.apiBaseUrl} to that environment's API.` : `If this key is for production, unset ${ENV.apiBaseUrl}.`;
+  return error.copyWith({
+    hint: [`Sent ${which} to ${where}. ${advice}`, error.hint].filter(Boolean).join(`
+`)
+  });
+}
 
 // src/commands/account.ts
 function registerAccountCommands(program, ctx) {
@@ -3417,14 +3585,19 @@ var TRANSIENT = new Set([
   "RATE_LIMITED",
   "INVALID_RESPONSE"
 ]);
+var SUBMIT_TIMEOUT_MS = 10 * 60000;
+var LOOKUP_TIMEOUT_MS = 30000;
 var RESUBMIT_BACKOFF_MS = [1000, 2000, 4000];
 var LOOKUP_BACKOFF_MS = [1000, 2000];
 async function submitRun(client, request, options) {
   const { idempotencyKey } = request;
+  const budget = submitBudget(idempotencyKey, options);
   for (let resubmissions = 0;; resubmissions++) {
     let failure;
     try {
-      const run = await createRun(client, request, idempotencyKey);
+      const run = await createRun(client, request, idempotencyKey, {
+        timeoutMs: budget.timeoutFor(SUBMIT_TIMEOUT_MS, { wholeBudget: true })
+      });
       return { run, recovered: false };
     } catch (error) {
       if (!(error instanceof ApiError) || REJECTED.has(error.code)) {
@@ -3432,31 +3605,60 @@ async function submitRun(client, request, options) {
       }
       failure = error;
     }
-    const existing = await lookupByKey(client, idempotencyKey, options.sleep);
+    const existing = await lookupByKey(client, idempotencyKey, budget);
     if (existing)
       return { run: verifyRecovered(existing, request), recovered: true };
     if (resubmissions >= RESUBMIT_BACKOFF_MS.length) {
       throw withContext(failure, { idempotencyKey });
     }
     options.onRetry?.(resubmissions + 1, failure);
-    await options.sleep(RESUBMIT_BACKOFF_MS[resubmissions] ?? 4000);
+    await budget.pause(RESUBMIT_BACKOFF_MS[resubmissions] ?? 4000);
   }
 }
-async function lookupByKey(client, idempotencyKey, sleep) {
+function isNoRunForKey(error) {
+  if (!(error instanceof ApiError) || error.code !== "NOT_FOUND" || error.routeMissing)
+    return false;
+  return error.key === undefined || error.key === "tool_run_not_found";
+}
+async function lookupByKey(client, idempotencyKey, budget) {
   for (let attempt = 0;; attempt++) {
     try {
-      return await getRunByIdempotencyKey(client, idempotencyKey);
+      return await getRunByIdempotencyKey(client, idempotencyKey, {
+        timeoutMs: budget.timeoutFor(LOOKUP_TIMEOUT_MS)
+      });
     } catch (error) {
-      if (error instanceof ApiError && error.key === "tool_run_not_found")
+      if (isNoRunForKey(error))
         return;
+      budget.check();
       const transient = error instanceof ApiError && TRANSIENT.has(error.code);
       if (!transient || attempt >= LOOKUP_BACKOFF_MS.length) {
         throw withContext(error, { idempotencyKey }, { lead: "Could not confirm whether the run was accepted." });
       }
-      await sleep(LOOKUP_BACKOFF_MS[attempt] ?? 2000);
+      await budget.pause(LOOKUP_BACKOFF_MS[attempt] ?? 2000);
     }
   }
 }
+function submitBudget(idempotencyKey, options) {
+  const { deadline } = options;
+  const left = () => deadline === undefined ? Infinity : deadline - options.now().getTime();
+  const check = () => {
+    if (left() <= 0)
+      throw withContext(submitTimeout(), { idempotencyKey });
+  };
+  return {
+    check,
+    timeoutFor(cap, { wholeBudget = false } = {}) {
+      if (deadline === undefined)
+        return cap;
+      check();
+      return wholeBudget ? left() : Math.min(cap, left());
+    },
+    async pause(ms) {
+      check();
+      await options.sleep(Math.min(ms, left()));
+    }
+  };
+}
 function verifyRecovered(run, request) {
   const data = { idempotencyKey: request.idempotencyKey, runId: run.runId };
   const check = `Inspect it with: solgrid runs get -r ${run.runId}`;
@@ -3490,18 +3692,11 @@ function withContext(error, data, options = {}) {
   } else if (data.idempotencyKey && options.retryable !== false) {
     steps.push(`Retry safely with --idempotency-key ${data.idempotencyKey}, or check: solgrid runs get --idempotency-key ${data.idempotencyKey}`);
   }
-  const rebuilt = {
+  return error.copyWith({
     hint: [error.hint, ...steps].filter(Boolean).join(`
 `),
-    details: error.details,
-    data: { ...error.data, ...data },
-    cause: error
-  };
-  return error instanceof ApiError ? new ApiError(error.code, error.message, {
-    ...rebuilt,
-    ...error.status !== undefined ? { status: error.status } : {},
-    ...error.key ? { key: error.key } : {}
-  }) : new CliError(error.code, error.message, rebuilt);
+    data: { ...error.data, ...data }
+  });
 }
 function sameInput(stored, submitted) {
   return canonical(normalize(stored)) === canonical(normalize(submitted));
@@ -3534,7 +3729,7 @@ var MAX_POLL_MS = 1e4;
 async function waitFor(fetchRun, options) {
   const deadline = options.now().getTime() + options.timeoutMs;
   const remaining = () => deadline - options.now().getTime();
-  const timedOut = () => waitTimeout(options.description, last, options.timeoutMs, options.checkCommand);
+  const timedOut = () => waitTimeout(options.description, last, options.totalMs ?? options.timeoutMs, options.checkCommand);
   let delay = FIRST_POLL_MS;
   let last;
   for (;; ) {
@@ -3566,6 +3761,11 @@ function waitForRun(client, runId, options) {
     checkCommand: `solgrid runs get -r ${runId} --wait`
   });
 }
+function submitTimeout() {
+  return new CliError("WAIT_TIMEOUT", "The wait ended before the run could be confirmed.", {
+    hint: "It may still be running on Solgrid, or may not have started."
+  });
+}
 function waitTimeout(description, last, timeoutMs, checkCommand) {
   const runId = last?.runId;
   const status = last?.status;
@@ -3721,6 +3921,8 @@ function registerRunCommand(program, ctx) {
     const idempotencyKey = opts.idempotencyKey ?? ctx.randomUUID();
     validateIdempotencyKey(idempotencyKey);
     const waitSeconds = opts.wait === true ? DEFAULT_WAIT_SECONDS : opts.wait;
+    const budgetMs = waitSeconds !== undefined || opts.output !== undefined ? (waitSeconds ?? DEFAULT_WAIT_SECONDS) * 1000 : undefined;
+    const deadline = budgetMs !== undefined ? ctx.now().getTime() + budgetMs : undefined;
     const client = apiClient(ctx);
     out.progress.start(`Submitting ${opts.provider} ${opts.endpoint}…`);
     const { run: submitted, recovered } = await submitRun(client, {
@@ -3729,15 +3931,17 @@ function registerRunCommand(program, ctx) {
       ...input ? { input } : {},
       idempotencyKey
     }, {
+      now: () => ctx.now(),
       sleep: (ms) => ctx.sleep(ms),
-      onRetry: (attempt) => out.progress.update(`Submission interrupted, retrying (${attempt})…`)
+      onRetry: (attempt) => out.progress.update(`Submission interrupted, retrying (${attempt})…`),
+      ...deadline !== undefined ? { deadline } : {}
     });
     try {
       await finishRun(ctx, client, out, {
         submitted,
         recovered,
         idempotencyKey,
-        ...waitSeconds !== undefined ? { waitSeconds } : {},
+        ...budgetMs !== undefined && deadline !== undefined ? { budgetMs, deadline } : {},
         ...opts.output !== undefined ? { outputPath: opts.output } : {}
       });
     } catch (error) {
@@ -3747,13 +3951,14 @@ function registerRunCommand(program, ctx) {
 }
 async function finishRun(ctx, client, out, params) {
   const { submitted, recovered, idempotencyKey, outputPath } = params;
-  const wait = params.waitSeconds !== undefined || outputPath !== undefined;
+  const wait = params.deadline !== undefined;
   if (!wait && !isTerminal(submitted.status)) {
     out.result({ ...submitted, idempotencyKey, recovered }, () => renderSubmitted(submitted.runId, submitted.status, idempotencyKey, recovered, out));
     return;
   }
   const finished = isTerminal(submitted.status) ? submitted : await waitForRun(client, submitted.runId, {
-    timeoutMs: (params.waitSeconds ?? DEFAULT_WAIT_SECONDS) * 1000,
+    timeoutMs: params.deadline - ctx.now().getTime(),
+    totalMs: params.budgetMs,
     now: () => ctx.now(),
     sleep: (ms) => ctx.sleep(ms),
     onPoll: (run) => out.progress.update(`Waiting for ${run.runId} (${run.status})…`)
@@ -3863,6 +4068,893 @@ function registerSessionIdCommand(program, ctx) {
   }));
 }
 
+// src/commands/skills.ts
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+
+// src/core/skill-markdown.ts
+var MAX_SKILL_NAME_LENGTH = 64;
+var MAX_SKILL_DESCRIPTION_LENGTH = 1024;
+var SKILL_NAME = /^[a-z0-9](?:[a-z0-9]|-(?!-))*$/;
+function isSkillName(value) {
+  return value.length <= MAX_SKILL_NAME_LENGTH && SKILL_NAME.test(value) && !value.endsWith("-");
+}
+function readFrontmatter(text) {
+  const lines = text.replace(/^\uFEFF/, "").split(/\r\n|\r|\n/);
+  if (lines[0] !== "---")
+    return;
+  const end = lines.indexOf("---", 1);
+  if (end === -1)
+    return;
+  if (!lines.slice(end + 1).join(`
+`).trim())
+    return;
+  const fields = topLevelScalars(lines.slice(1, end));
+  return { name: fields.get("name"), description: fields.get("description") };
+}
+function frontmatterProblem(frontmatter) {
+  if (!frontmatter)
+    return "missing";
+  const { name, description } = frontmatter;
+  if (name === undefined || name !== null && !isSkillName(name))
+    return "name";
+  if (description === undefined || description !== null && (!description.trim() || description.length > MAX_SKILL_DESCRIPTION_LENGTH)) {
+    return "description";
+  }
+  return;
+}
+function topLevelScalars(lines) {
+  const fields = new Map;
+  for (let i = 0;i < lines.length; i++) {
+    const match = /^(?:"([^"\\]*)"|'([^']*)'|([^\s#:'"][^:]*?))[ \t]*:(?:[ \t]+(.*))?$/.exec(lines[i]);
+    if (!match)
+      continue;
+    const key = (match[1] ?? match[2] ?? match[3]).trim();
+    const rest = [];
+    while (i + 1 < lines.length && /^(?:[ \t]|$)/.test(lines[i + 1])) {
+      rest.push(lines[++i]);
+    }
+    let value;
+    try {
+      value = scalar((match[4] ?? "").trim(), rest);
+    } catch {
+      value = null;
+    }
+    if (value !== undefined)
+      fields.set(key, value);
+  }
+  return fields;
+}
+var NESTED = /^(?:-(?:[ \t]|$)|(?:"[^"\\]*"|'[^']*'|[^\s#'"][^:]*?)[ \t]*:(?:[ \t]|$))/;
+function scalar(head, rest) {
+  if (!head) {
+    const index = rest.findIndex((line) => line.trim() && !line.trim().startsWith("#"));
+    if (index === -1)
+      return "";
+    const first = rest[index].trim();
+    if (NESTED.test(first))
+      return;
+    return scalar(first, rest.slice(index + 1));
+  }
+  if (head.startsWith('"') || head.startsWith("'"))
+    return quoted([head, ...rest]);
+  const more = rest.map((line) => line.trim()).filter(Boolean);
+  if (/^[|>]/.test(head)) {
+    return more.join(head.startsWith("|") ? `
+` : " ");
+  }
+  if (/^[[{]/.test(head))
+    return;
+  if (/^[&*!]/.test(head))
+    return null;
+  return [head, ...more].filter((line) => !line.startsWith("#")).join(" ").replace(/\s+#.*$/, "");
+}
+var ESCAPES = {
+  "0": "\x00",
+  a: "\x07",
+  b: "\b",
+  t: "\t",
+  "\t": "\t",
+  n: `
+`,
+  v: "\v",
+  f: "\f",
+  r: "\r",
+  e: "\x1B",
+  " ": " ",
+  '"': '"',
+  "/": "/",
+  "\\": "\\",
+  N: "…",
+  _: " ",
+  L: "\u2028",
+  P: "\u2029"
+};
+var HEX_ESCAPES = { x: 2, u: 4, U: 8 };
+function quoted(lines) {
+  const text = lines.join(`
+`);
+  const quote = text[0];
+  let value = "";
+  let i = 1;
+  for (;; ) {
+    if (i >= text.length)
+      return null;
+    const char = text[i];
+    if (char === quote) {
+      if (quote === "'" && text[i + 1] === "'") {
+        value += "'";
+        i += 2;
+        continue;
+      }
+      break;
+    }
+    if (char === "\\" && quote === '"') {
+      const next = text[i + 1] ?? "";
+      if (next === `
+`) {
+        i += 2;
+        while (text[i] === " " || text[i] === "\t")
+          i++;
+        continue;
+      }
+      const digits = HEX_ESCAPES[next];
+      if (digits !== undefined) {
+        const hex = text.slice(i + 2, i + 2 + digits);
+        if (!new RegExp(`^[0-9a-fA-F]{${digits}}$`).test(hex))
+          return null;
+        const codePoint = Number.parseInt(hex, 16);
+        if (codePoint > 1114111)
+          return null;
+        value += String.fromCodePoint(codePoint);
+        i += 2 + digits;
+        continue;
+      }
+      const escaped = ESCAPES[next];
+      if (escaped === undefined)
+        return null;
+      value += escaped;
+      i += 2;
+      continue;
+    }
+    if (char === `
+`) {
+      value = value.replace(/[ \t]+$/, "");
+      let breaks = 0;
+      while (text[i] === `
+`) {
+        breaks++;
+        i++;
+        while (text[i] === " " || text[i] === "\t")
+          i++;
+      }
+      value += breaks === 1 ? " " : `
+`.repeat(breaks - 1);
+      continue;
+    }
+    value += char;
+    i++;
+  }
+  return /^[ \t]*(?:#[^\n]*)?(?:\n[ \t]*(?:#[^\n]*)?)*$/.test(text.slice(i + 1)) ? value : null;
+}
+
+// src/core/skill-package.ts
+import { lstatSync, mkdtempSync, readdirSync, readFileSync as readFileSync3, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename as basename2, join as join3, relative, sep } from "node:path";
+import { deflateRawSync } from "node:zlib";
+var MAX_SKILL_BYTES = 1e7;
+var MAX_SKILL_FILES = 200;
+var MAX_DEPTH = 16;
+var MAX_PATH_LENGTH = 1024;
+var SKIPPED = new Set([".git", ".DS_Store"]);
+function invalid(dir, reason, hint) {
+  return new CliError("USAGE", `${dir} is not a valid Skill: ${reason}.`, hint ? { hint } : {});
+}
+function collect(dir) {
+  const entries = [];
+  const seen = new Map;
+  let total = 0;
+  const walk = (current, depth) => {
+    for (const name of readdirSync(current).sort()) {
+      if (SKIPPED.has(name))
+        continue;
+      const full = join3(current, name);
+      const zipName = relative(dir, full).split(sep).join("/");
+      if (/[:\\\u0000-\u001f\u007f]/.test(name)) {
+        throw invalid(dir, `"${zipName}" has a ":", a backslash or a control character in its name`);
+      }
+      if (zipName.length > MAX_PATH_LENGTH || depth > MAX_DEPTH) {
+        throw invalid(dir, `"${zipName}" is nested too deeply or its path is too long`);
+      }
+      const lower = zipName.toLowerCase();
+      const clash = seen.get(lower);
+      if (clash)
+        throw invalid(dir, `"${clash}" and "${zipName}" differ only in case`);
+      seen.set(lower, zipName);
+      const stat = lstatSync(full);
+      if (stat.isSymbolicLink()) {
+        throw invalid(dir, `"${zipName}" is a symbolic link`, "Replace links with the files themselves.");
+      }
+      if (stat.isDirectory()) {
+        walk(full, depth + 1);
+      } else if (stat.isFile()) {
+        if (entries.length >= MAX_SKILL_FILES) {
+          throw invalid(dir, `it has more than ${MAX_SKILL_FILES} files`);
+        }
+        total += stat.size;
+        if (total > MAX_SKILL_BYTES) {
+          throw invalid(dir, `its files add up to more than ${MAX_SKILL_BYTES.toLocaleString("en-US")} bytes`);
+        }
+        entries.push({ name: zipName, data: readFileSync3(full) });
+      } else {
+        throw invalid(dir, `"${zipName}" is not a regular file or directory`);
+      }
+    }
+  };
+  walk(dir, 1);
+  return entries;
+}
+var FRONTMATTER_EXAMPLE = `Start SKILL.md with:
+---
+name: my-skill
+description: What the Skill does and when to use it.
+---
+followed by the instructions.`;
+function checkSkillMarkdown(dir, entries) {
+  const markdown = entries.find((entry) => entry.name === "SKILL.md");
+  if (!markdown) {
+    const wrongCase = entries.find((entry) => entry.name.toLowerCase() === "skill.md");
+    throw invalid(dir, wrongCase ? `the file must be named SKILL.md, not ${wrongCase.name}` : "it has no SKILL.md at the top", "Put SKILL.md directly in the directory you pass to --dir.");
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(markdown.data);
+  } catch {
+    throw invalid(dir, "SKILL.md is not valid UTF-8");
+  }
+  if (!text.trim())
+    throw invalid(dir, "SKILL.md is empty");
+  const frontmatter = readFrontmatter(text);
+  switch (frontmatterProblem(frontmatter)) {
+    case "missing":
+      throw invalid(dir, "SKILL.md must start with frontmatter between --- lines, followed by the instructions", FRONTMATTER_EXAMPLE);
+    case "name":
+      throw invalid(dir, frontmatter?.name === undefined ? "SKILL.md's frontmatter has no name" : `the name "${frontmatter.name}" in SKILL.md is not valid`, `Use 1–64 lowercase letters, digits or hyphens, not starting or ending with a hyphen and without "--". It must equal the Skill's slug.`);
+    case "description":
+      throw invalid(dir, `SKILL.md's frontmatter needs a description of 1–${MAX_SKILL_DESCRIPTION_LENGTH.toLocaleString("en-US")} characters`, "Say what the Skill does and when to use it.");
+  }
+  return frontmatter?.name ?? undefined;
+}
+function packSkillDirectory(dir) {
+  try {
+    if (!lstatSync(dir).isDirectory())
+      throw new Error("not a directory");
+  } catch (cause) {
+    throw new CliError("USAGE", `Cannot read the directory ${dir}.`, { cause });
+  }
+  const entries = collect(dir);
+  const name = checkSkillMarkdown(dir, entries);
+  const zip = buildZip(entries);
+  if (zip.length > MAX_SKILL_BYTES) {
+    throw invalid(dir, `the package would be ${zip.length.toLocaleString("en-US")} bytes, over the limit`);
+  }
+  const temp = mkdtempSync(join3(tmpdir(), "solgrid-skill-"));
+  const path = join3(temp, `${basename2(dir) || "skill"}.zip`);
+  writeFileSync3(path, zip);
+  return {
+    path,
+    files: entries.length,
+    bytes: zip.length,
+    name,
+    cleanup: () => rmSync(temp, { recursive: true, force: true })
+  };
+}
+var CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0;n < 256; n++) {
+    let c = n;
+    for (let k = 0;k < 8; k++)
+      c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+function crc32(data) {
+  let crc = 4294967295;
+  for (const byte of data)
+    crc = CRC_TABLE[(crc ^ byte) & 255] ^ crc >>> 8;
+  return (crc ^ 4294967295) >>> 0;
+}
+var DOS_TIME = 0;
+var DOS_DATE = 1 << 5 | 1;
+var UTF8_NAMES = 2048;
+function buildZip(entries) {
+  const parts = [];
+  const central = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = Buffer.from(entry.name, "utf8");
+    const deflated = deflateRawSync(entry.data);
+    const stored = deflated.length >= entry.data.length;
+    const body = stored ? Buffer.from(entry.data) : deflated;
+    const method = stored ? 0 : 8;
+    const crc = crc32(entry.data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(67324752, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(UTF8_NAMES, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(DOS_TIME, 10);
+    local.writeUInt16LE(DOS_DATE, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(entry.data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    parts.push(local, name, body);
+    const header = Buffer.alloc(46);
+    header.writeUInt32LE(33639248, 0);
+    header.writeUInt16LE(3 << 8 | 20, 4);
+    header.writeUInt16LE(20, 6);
+    header.writeUInt16LE(UTF8_NAMES, 8);
+    header.writeUInt16LE(method, 10);
+    header.writeUInt16LE(DOS_TIME, 12);
+    header.writeUInt16LE(DOS_DATE, 14);
+    header.writeUInt32LE(crc, 16);
+    header.writeUInt32LE(body.length, 20);
+    header.writeUInt32LE(entry.data.length, 24);
+    header.writeUInt16LE(name.length, 28);
+    header.writeUInt32LE(33188 << 16 >>> 0, 38);
+    header.writeUInt32LE(offset, 42);
+    central.push(header, name);
+    offset += local.length + name.length + body.length;
+  }
+  const directory = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(101010256, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(directory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...parts, directory, end]);
+}
+
+// src/core/skills.ts
+import { openAsBlob as openAsBlob2, statSync as statSync2 } from "node:fs";
+import { basename as basename3, extname as extname2 } from "node:path";
+var SKILL_KINDS = ["image", "video", "web", "audio"];
+var KIND_NAME = {
+  image: "Image",
+  video: "Video",
+  web: "Web",
+  audio: "Audio"
+};
+var KIND_BY_NUMBER2 = { 1: "image", 2: "video", 3: "web", 4: "audio" };
+function kindName(value) {
+  if (typeof value === "number")
+    return KIND_BY_NUMBER2[value];
+  if (typeof value === "string") {
+    const name = value.toLowerCase();
+    return SKILL_KINDS.find((kind) => kind === name);
+  }
+  return;
+}
+var CARD_FIELDS = {
+  id: isString,
+  title: isText,
+  tags: optional(listOf(isText)),
+  author: optional(objectWith({ nickname: optional(isText) }))
+};
+async function listSkills(client, params) {
+  const path = params.mine ? "/v1/creative-cases/list-mine" : "/v1/creative-cases/list";
+  const data = await client.post(path, {
+    ...params.page !== undefined ? { pageIndex: params.page } : {},
+    ...params.pageSize !== undefined ? { pageSize: params.pageSize } : {},
+    ...params.kind ? { kind: KIND_NAME[params.kind] } : {},
+    ...params.keyword ? { keyword: params.keyword } : {},
+    ...params.slug ? { slug: params.slug } : {}
+  });
+  return expectShape(path, data, {
+    items: listOf(objectWith(CARD_FIELDS)),
+    total: isNumber,
+    pageIndex: isNumber,
+    pageSize: isNumber
+  });
+}
+async function getSkill(client, target) {
+  const path = "/v1/creative-cases/get";
+  const data = await client.post(path, target);
+  return expectShape(path, data, {
+    ...CARD_FIELDS,
+    slug: isString,
+    description: isText,
+    skillFileAssetId: isString
+  });
+}
+function contentBody(content) {
+  return {
+    title: content.title,
+    kind: KIND_NAME[content.kind],
+    description: content.description,
+    tags: content.tags,
+    coverFileAssetId: content.coverFileAssetId ?? null,
+    previewFileAssetId: content.previewFileAssetId ?? null,
+    skillFileAssetId: content.skillFileAssetId
+  };
+}
+var MUTATION_FIELDS = { id: isString };
+async function createSkill(client, slug, content) {
+  const path = "/v1/creative-cases/create";
+  const data = await client.post(path, { ...contentBody(content), slug });
+  return expectShape(path, data, MUTATION_FIELDS);
+}
+async function updateSkill(client, id, content) {
+  const path = "/v1/creative-cases/update";
+  const data = await client.post(path, { id, ...contentBody(content) });
+  return expectShape(path, data, MUTATION_FIELDS);
+}
+async function deleteSkill(client, id) {
+  await client.post("/v1/creative-cases/delete", { id });
+}
+function contentOf(skill) {
+  const kind = kindName(skill.kind);
+  if (!kind) {
+    throw new CliError("INVALID_RESPONSE", `Unexpected kind ${JSON.stringify(skill.kind)} for this Skill.`);
+  }
+  return {
+    title: skill.title,
+    kind,
+    description: skill.description,
+    tags: skill.tags ?? [],
+    coverFileAssetId: skill.cover?.fileAssetId ?? null,
+    previewFileAssetId: skill.previewFileAssetId ?? null,
+    skillFileAssetId: skill.skillFileAssetId
+  };
+}
+var MAX_TAGS = 3;
+async function listSkillTags(client) {
+  const path = "/v1/creative-cases/list-tags";
+  const data = await client.post(path);
+  const checked = expectShape(path, { tags: data }, {
+    tags: listOf(objectWith({ id: isString, name: isText }))
+  });
+  return checked.tags;
+}
+function checkTags(tags, available) {
+  if (tags.length > MAX_TAGS) {
+    throw new CliError("USAGE", `A Skill takes at most ${MAX_TAGS} tags; ${tags.length} were given.`);
+  }
+  const known = new Set(available.map((tag) => tag.id));
+  const unknown = tags.filter((tag) => !known.has(tag));
+  if (unknown.length > 0) {
+    throw new CliError("USAGE", `Unknown tag${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.`, {
+      hint: `Pick from: ${available.map((tag) => tag.id).join(", ")} (see \`solgrid skills tags\`).`
+    });
+  }
+}
+var PUBLIC_DISPLAY = "1";
+function prepareSkillFile(path, role) {
+  let size;
+  try {
+    const stat = statSync2(path);
+    if (!stat.isFile())
+      throw new Error("not a file");
+    size = stat.size;
+  } catch (cause) {
+    throw new CliError("USAGE", `Cannot read ${path}.`, { cause });
+  }
+  if (size === 0)
+    throw new CliError("USAGE", `${path} is empty.`);
+  const kind = guessKind(path);
+  const allowed = {
+    cover: ["image"],
+    preview: ["image", "video", "audio"],
+    skill: ["skill"]
+  };
+  if (!kind || !allowed[role].includes(kind)) {
+    const expected = role === "skill" ? "a .zip file" : `an ${allowed[role].join(", ")} file`;
+    throw new CliError("USAGE", `The ${role === "skill" ? "Skill package" : role} must be ${expected}: ${basename3(path)}.`);
+  }
+  if (size > SIZE_LIMIT[kind]) {
+    throw new CliError("USAGE", `${basename3(path)} is ${formatBytes(size)}, over the ${formatBytes(SIZE_LIMIT[kind])} limit for ${kind} files.`);
+  }
+  return { kind, size };
+}
+var CONTENT_TYPE = {
+  image: {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif"
+  },
+  video: { ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm" },
+  audio: { ".mp3": "audio/mpeg", ".wav": "audio/wav", ".m4a": "audio/mp4", ".ogg": "audio/ogg" },
+  skill: { ".zip": "application/zip" }
+};
+async function uploadSkillFile(client, path, role) {
+  const { kind } = prepareSkillFile(path, role);
+  const form = new FormData;
+  form.append("fileType", String(FILE_TYPE_CODE[kind]));
+  form.append("purpose", PUBLIC_DISPLAY);
+  const type = CONTENT_TYPE[kind][extname2(path).toLowerCase()] ?? "application/octet-stream";
+  form.append("file", await openAsBlob2(path, { type }), basename3(path));
+  const data = await client.upload("/v1/files/upload", form);
+  return expectShape("/v1/files/upload", data, { fileAssetId: isString });
+}
+function openSkillPackage(client, slug) {
+  return client.openDownload(`/v1/skills/${encodeURIComponent(slug)}/content`);
+}
+
+// src/commands/skills.ts
+var MAX_INLINE_DESCRIPTION_CHARS = 1500;
+function parseKind2(value) {
+  const kind = kindName(value);
+  if (!kind)
+    throw new InvalidArgumentError(`must be one of ${SKILL_KINDS.join(", ")}.`);
+  return kind;
+}
+function parseSlug(value) {
+  if (!isSkillName(value)) {
+    throw new InvalidArgumentError('use 1–64 lowercase letters, digits or hyphens, not starting or ending with a hyphen and without "--".');
+  }
+  return value;
+}
+function collect2(value, previous = []) {
+  return [...previous, value];
+}
+function addContentOptions(command, required) {
+  const note = required ? "" : " (replaces the current one)";
+  command.option("-t, --title <title>", `title${note}`).option("--kind <kind>", `what the Skill makes: ${SKILL_KINDS.join(", ")}${note}`, parseKind2).option("-d, --description <text>", `a short description shown under the title${note}`).option("--description-file <path>", "read the description from a file instead").option("--tag <id>", `a tag ID from \`solgrid skills tags\`; up to ${MAX_TAGS}, repeat for several${required ? "" : " (replaces all current tags)"}`, collect2).option("--cover <path>", `cover image; required unless the kind is video${note}`).option("--preview <path>", `preview image, video or audio; required for video and audio${note}`).option("--dir <path>", `a Skill directory with SKILL.md at its top, packed for you${note}`).option("--zip <path>", `or an already packed Skill (.zip with SKILL.md)${note}`);
+  return command;
+}
+function readDescription(opts) {
+  if (opts.description !== undefined && opts.descriptionFile !== undefined) {
+    throw new CliError("USAGE", "Use either --description or --description-file, not both.");
+  }
+  if (opts.descriptionFile === undefined)
+    return opts.description;
+  try {
+    return readFileSync4(opts.descriptionFile, "utf8");
+  } catch (cause) {
+    throw new CliError("USAGE", `Cannot read ${opts.descriptionFile}.`, { cause });
+  }
+}
+function aSkill(kind) {
+  return `${kind === "image" || kind === "audio" ? "An" : "A"} ${kind} Skill`;
+}
+function checkMedia(kind, hasCover, hasPreview) {
+  if (kind !== "video" && !hasCover) {
+    throw new CliError("USAGE", `${aSkill(kind)} needs a cover image.`, {
+      hint: "Pass --cover <image>."
+    });
+  }
+  if ((kind === "video" || kind === "audio") && !hasPreview) {
+    throw new CliError("USAGE", `${aSkill(kind)} needs a preview.`, {
+      hint: `Pass --preview <${kind} or image file>.`
+    });
+  }
+}
+function pickTarget(opts) {
+  if (opts.slug === undefined === (opts.id === undefined)) {
+    throw new CliError("USAGE", "Pass exactly one of --slug or --id.");
+  }
+  return opts.slug !== undefined ? { slug: opts.slug } : { id: opts.id };
+}
+function targetName(target) {
+  return "slug" in target ? target.slug : target.id;
+}
+function isApiNotFound(error) {
+  return error instanceof ApiError && error.code === "NOT_FOUND" && !error.routeMissing;
+}
+async function findSkill(client, target) {
+  try {
+    return await getSkill(client, target);
+  } catch (error) {
+    if (!isApiNotFound(error))
+      throw error;
+    throw new CliError("NOT_FOUND", `No Skill with ${"slug" in target ? "slug" : "ID"} "${targetName(target)}".`, {
+      hint: "Search with `solgrid skills list -q <words>`, or list yours with `solgrid skills list --mine`.",
+      cause: error
+    });
+  }
+}
+function notYours(error, slug) {
+  if (!isApiNotFound(error))
+    return error;
+  return new CliError("NOT_FOUND", `Skill ${slug} is not one of yours.`, {
+    hint: "Only your own Skills can be changed. List them with `solgrid skills list --mine`.",
+    cause: error
+  });
+}
+function skillPackage(opts) {
+  if (opts.dir !== undefined && opts.zip !== undefined) {
+    throw new CliError("USAGE", "Use either --dir or --zip, not both.");
+  }
+  if (opts.dir !== undefined)
+    return packSkillDirectory(opts.dir);
+  if (opts.zip !== undefined) {
+    prepareSkillFile(opts.zip, "skill");
+    return { path: opts.zip, cleanup: () => {} };
+  }
+  return;
+}
+function slugFor(pkg, opts) {
+  const { slug } = opts;
+  if (pkg.name === undefined) {
+    if (slug === undefined) {
+      throw new CliError("USAGE", opts.zip !== undefined ? "Pass --slug with --zip." : "Could not read the name in SKILL.md; pass --slug.", {
+        hint: opts.zip !== undefined ? "It must equal the name in the package's SKILL.md. With --dir the CLI reads it for you." : "It must equal the name in SKILL.md's frontmatter."
+      });
+    }
+    return slug;
+  }
+  if (slug !== undefined && slug !== pkg.name)
+    throw nameMismatch(pkg.name, slug);
+  return pkg.name;
+}
+function nameMismatch(name, slug) {
+  return new CliError("USAGE", `The name in SKILL.md is "${name}", but the Skill's slug is "${slug}". They must be the same.`, { hint: `Set \`name: ${slug}\` in SKILL.md's frontmatter.` });
+}
+async function checkTagOptions(client, out, tags) {
+  if (tags === undefined)
+    return;
+  if (tags.length > MAX_TAGS)
+    checkTags(tags, []);
+  out.progress.update("Checking tags…");
+  checkTags(tags, await listSkillTags(client));
+}
+async function confirmOrRefuse(ctx, out, opts, question, refusal) {
+  if (opts.yes)
+    return true;
+  if (opts.json || !ctx.stdinIsTTY) {
+    throw new CliError("USAGE", refusal, { hint: "Pass --yes to confirm in non-interactive use." });
+  }
+  out.progress.stop();
+  return ctx.confirm(question);
+}
+async function uploadIfGiven(client, out, path, role) {
+  if (path === undefined)
+    return;
+  out.progress.update(`Uploading ${path}…`);
+  return (await uploadSkillFile(client, path, role)).fileAssetId;
+}
+function registerSkillsCommand(program, ctx) {
+  const skills = program.command("skills").description("Find, publish and manage Skills on SkillHub.").addHelpText("after", `
+A Skill is public as soon as it is created. Its slug identifies it everywhere and cannot
+be changed later.`);
+  skills.command("list").description("Search Skills, newest first.").option("-q, --query <words>", "match titles and tags").option("--kind <kind>", `only this kind: ${SKILL_KINDS.join(", ")}`, parseKind2).option("--mine", "only your own Skills").option("-l, --limit <n>", "Skills per page (default 20, up to 100)", parsePositiveInt).option("--page <n>", "page number (default 1)", parsePositiveInt).option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+    const client = apiClient(ctx);
+    out.progress.start("Searching Skills…");
+    const data = await listSkills(client, {
+      ...opts.mine ? { mine: true } : {},
+      ...opts.query ? { keyword: opts.query } : {},
+      ...opts.kind ? { kind: opts.kind } : {},
+      ...opts.limit !== undefined ? { pageSize: opts.limit } : {},
+      ...opts.page !== undefined ? { page: opts.page } : {}
+    });
+    out.result(data, () => {
+      if (data.items.length === 0) {
+        return opts.query || opts.kind ? "No Skills match. Try other words, or drop --kind." : opts.mine ? "You have not published any Skills yet. Publish one with `solgrid skills create`." : "No Skills yet.";
+      }
+      const lines = [
+        renderTable(["ID", "TITLE", "KIND", "AUTHOR", "UPDATED"], data.items.map((skill) => [
+          skill.id,
+          truncate(skill.title, 40),
+          kindName(skill.kind) ?? "-",
+          skill.author?.nickname || "-",
+          formatTime(skill.updatedAt ?? skill.createdAt)
+        ]), { formatHeader: (text) => out.style("dim", text) })
+      ];
+      const shown = (data.pageIndex - 1) * data.pageSize + data.items.length;
+      if (shown < data.total) {
+        lines.push("", out.style("dim", `${shown} of ${data.total}. Next page: add --page ${data.pageIndex + 1}`));
+      }
+      lines.push("", out.style("dim", "Details: solgrid skills get -i <id>"));
+      return lines.join(`
+`);
+    });
+  }));
+  skills.command("get").description("Show a Skill's details.").option("-s, --slug <slug>", "the Skill's slug").option("-i, --id <id>", "the Skill's ID").option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+    const target = pickTarget(opts);
+    const client = apiClient(ctx);
+    out.progress.start("Fetching Skill…");
+    const skill = await findSkill(client, target);
+    out.result(skill, () => renderSkill(skill, out.style));
+  }));
+  skills.command("tags").description(`List the tags a Skill can carry (up to ${MAX_TAGS} each).`).option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+    const client = apiClient(ctx);
+    out.progress.start("Fetching tags…");
+    const tags = await listSkillTags(client);
+    out.result({ tags }, () => [
+      renderTable(["ID", "NAME"], tags.map((tag) => [tag.id, tag.name]), { formatHeader: (text) => out.style("dim", text) }),
+      "",
+      out.style("dim", "Use the ID with --tag, e.g. --tag cat_anime.")
+    ].join(`
+`));
+  }));
+  addContentOptions(skills.command("create").description("Publish a new Skill. It is public as soon as it is created.").option("-s, --slug <slug>", "the Skill's unique ID; must equal the name in SKILL.md (default: that name)", parseSlug), true).option("-y, --yes", "publish without asking").option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+    const description = readDescription(opts);
+    const missing = [
+      ["--title", opts.title],
+      ["--kind", opts.kind],
+      ["--description or --description-file", description],
+      ["--dir or --zip", opts.dir ?? opts.zip]
+    ].filter(([, value]) => !value).map(([name]) => name);
+    if (missing.length > 0)
+      throw new CliError("USAGE", `Missing ${missing.join(", ")}.`);
+    const kind = opts.kind;
+    checkMedia(kind, opts.cover !== undefined, opts.preview !== undefined);
+    if (opts.cover)
+      prepareSkillFile(opts.cover, "cover");
+    if (opts.preview)
+      prepareSkillFile(opts.preview, "preview");
+    const pkg = skillPackage(opts);
+    try {
+      const slug = slugFor(pkg, opts);
+      const client = apiClient(ctx);
+      out.progress.start("Checking…");
+      await checkTagOptions(client, out, opts.tag);
+      const confirmed = await confirmOrRefuse(ctx, out, opts, `Publish "${opts.title}" (${slug}) publicly on SkillHub?`, "Refusing to publish a Skill without confirmation.");
+      if (!confirmed) {
+        out.result({ slug, created: false }, () => "Cancelled.");
+        return;
+      }
+      out.progress.start("Uploading…");
+      const content = {
+        title: opts.title,
+        kind,
+        description,
+        tags: opts.tag ?? [],
+        skillFileAssetId: await uploadIfGiven(client, out, pkg.path, "skill"),
+        coverFileAssetId: await uploadIfGiven(client, out, opts.cover, "cover") ?? null,
+        previewFileAssetId: await uploadIfGiven(client, out, opts.preview, "preview") ?? null
+      };
+      out.progress.update("Publishing…");
+      const { id } = await createSkill(client, slug, content).catch((error) => {
+        if (error instanceof ApiError && error.code === "CONFLICT") {
+          throw new CliError("CONFLICT", `The slug "${slug}" is already taken.`, {
+            hint: "Choose another name in SKILL.md (and --slug).",
+            cause: error
+          });
+        }
+        throw error;
+      });
+      out.result({ id, slug, created: true }, () => [
+        `Published "${content.title}" as ${slug}.`,
+        ...renderFields([["ID", id]], out.style),
+        "",
+        out.style("dim", `See it with: solgrid skills get -s ${slug}`)
+      ].join(`
+`));
+    } finally {
+      pkg.cleanup();
+    }
+  }));
+  addContentOptions(skills.command("update").description("Change one of your Skills. Only the options you pass are changed; the slug never is.").option("-s, --slug <slug>", "the Skill's slug").option("-i, --id <id>", "the Skill's ID"), false).option("--clear-tags", "remove all tags").option("--clear-preview", "remove the preview (image and web Skills only)").option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+    const target = pickTarget(opts);
+    const description = readDescription(opts);
+    if (opts.clearTags && opts.tag !== undefined) {
+      throw new CliError("USAGE", "Use either --tag or --clear-tags, not both.");
+    }
+    const tags = opts.clearTags ? [] : opts.tag;
+    if (opts.clearPreview && opts.preview !== undefined) {
+      throw new CliError("USAGE", "Use either --preview or --clear-preview, not both.");
+    }
+    const changes = [
+      opts.title,
+      opts.kind,
+      description,
+      tags,
+      opts.cover,
+      opts.preview,
+      opts.clearPreview,
+      opts.dir,
+      opts.zip
+    ];
+    if (changes.every((value) => value === undefined)) {
+      throw new CliError("USAGE", "Nothing to change.", {
+        hint: "Pass at least one of --title, --kind, --description, --tag, --clear-tags, --cover, --preview, --clear-preview, --dir or --zip."
+      });
+    }
+    if (opts.cover)
+      prepareSkillFile(opts.cover, "cover");
+    if (opts.preview)
+      prepareSkillFile(opts.preview, "preview");
+    const pkg = skillPackage(opts);
+    try {
+      const client = apiClient(ctx);
+      out.progress.start("Fetching Skill…");
+      const skill = await findSkill(client, target);
+      if (pkg?.name !== undefined && pkg.name !== skill.slug) {
+        throw nameMismatch(pkg.name, skill.slug);
+      }
+      const next = {
+        ...contentOf(skill),
+        ...opts.title !== undefined ? { title: opts.title } : {},
+        ...opts.kind !== undefined ? { kind: opts.kind } : {},
+        ...description !== undefined ? { description } : {},
+        ...tags !== undefined ? { tags } : {},
+        ...opts.clearPreview ? { previewFileAssetId: null } : {}
+      };
+      if (opts.clearPreview && (next.kind === "video" || next.kind === "audio")) {
+        throw new CliError("USAGE", `${aSkill(next.kind)} needs a preview; it cannot be removed.`, {
+          hint: "Replace it with --preview <file> instead."
+        });
+      }
+      checkMedia(next.kind, Boolean(opts.cover ?? next.coverFileAssetId), Boolean(opts.preview ?? next.previewFileAssetId));
+      await checkTagOptions(client, out, opts.tag);
+      next.skillFileAssetId = await uploadIfGiven(client, out, pkg?.path, "skill") ?? next.skillFileAssetId;
+      next.coverFileAssetId = await uploadIfGiven(client, out, opts.cover, "cover") ?? next.coverFileAssetId;
+      next.previewFileAssetId = await uploadIfGiven(client, out, opts.preview, "preview") ?? next.previewFileAssetId;
+      out.progress.update("Saving…");
+      await updateSkill(client, skill.id, next).catch((error) => {
+        throw notYours(error, skill.slug);
+      });
+      out.result({ id: skill.id, slug: skill.slug, updated: true }, () => `Updated Skill ${skill.slug}.`);
+    } finally {
+      pkg?.cleanup();
+    }
+  }));
+  skills.command("delete").description("Delete one of your Skills. It disappears from SkillHub.").option("-s, --slug <slug>", "the Skill's slug").option("-i, --id <id>", "the Skill's ID").option("-y, --yes", "delete without asking").option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+    const target = pickTarget(opts);
+    const client = apiClient(ctx);
+    out.progress.start("Finding Skill…");
+    const { id, slug } = await findSkill(client, target);
+    const confirmed = await confirmOrRefuse(ctx, out, opts, `Delete Skill ${slug}? It will no longer be listed on SkillHub.`, "Refusing to delete a Skill without confirmation.");
+    if (!confirmed) {
+      out.result({ id, slug, deleted: false }, () => "Cancelled.");
+      return;
+    }
+    out.progress.start("Deleting…");
+    await deleteSkill(client, id).catch((error) => {
+      throw notYours(error, slug);
+    });
+    out.result({ id, slug, deleted: true }, () => `Deleted Skill ${slug}.`);
+  }));
+  skills.command("download").description("Download a Skill's package (.zip).").requiredOption("-s, --slug <slug>", "the Skill's slug").option("-o, --output <path>", "where to save it (default: <slug>.zip in the current directory)").option("--force", "overwrite the output file if it exists").option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+    const client = apiClient(ctx);
+    out.progress.start("Downloading…");
+    const response = await openSkillPackage(client, opts.slug);
+    const destination = opts.output ?? filenameFromDisposition(response.headers.get("content-disposition")) ?? `${opts.slug}.zip`;
+    if (existsSync3(destination) && !opts.force) {
+      await response.body?.cancel();
+      throw new CliError("USAGE", `${destination} already exists.`, {
+        hint: "Pass --force to overwrite it, or choose another path with -o."
+      });
+    }
+    if (!response.body)
+      throw new CliError("INVALID_RESPONSE", "The download has no content.");
+    const bytes = await saveDownload(response.body, destination, {
+      overwrite: opts.force === true
+    });
+    out.result({ slug: opts.slug, path: destination, sizeBytes: bytes }, () => `Saved ${destination} (${formatBytes(bytes)}).`);
+  }));
+}
+function renderSkill(skill, style) {
+  const lines = [
+    style("bold", skill.title),
+    "",
+    ...renderFields([
+      ["Slug", skill.slug],
+      ["ID", skill.id],
+      ["Kind", kindName(skill.kind)],
+      ["Author", skill.author?.nickname || undefined],
+      ["Tags", skill.tags?.length ? skill.tags.join(", ") : undefined],
+      ["Created", skill.createdAt ? formatTime(skill.createdAt) : undefined],
+      ["Updated", skill.updatedAt ? formatTime(skill.updatedAt) : undefined]
+    ], style)
+  ];
+  if (skill.description) {
+    const text = skill.description.trim();
+    lines.push("", text.length > MAX_INLINE_DESCRIPTION_CHARS ? `${text.slice(0, MAX_INLINE_DESCRIPTION_CHARS)}
+${style("dim", `… ${text.length - MAX_INLINE_DESCRIPTION_CHARS} more characters; use --json for the full description.`)}` : text);
+  }
+  lines.push("", style("dim", `Download it with: solgrid skills download -s ${skill.slug}`));
+  return lines.join(`
+`);
+}
+
 // src/output/price.ts
 function periodText(period) {
   const unit = period.unit.toLowerCase();
@@ -3899,7 +4991,80 @@ function describeLeaf(leaf) {
   const text = withUnit(formatAmount(leaf.amount), unitText(leaf));
   return leaf.flatFee ? `${text} + ${formatAmount(leaf.flatFee)} flat` : text;
 }
-function summarizePrice(price) {
+var METER_UNITS = {
+  Calls: ["call", "calls"],
+  WebSearchCalls: ["web search", "web searches"],
+  InputImages: ["input image", "input images"],
+  OutputImages: ["output image", "output images"],
+  InputVideoSeconds: ["second of input video", "seconds of input video"],
+  OutputVideoSeconds: ["second of output video", "seconds of output video"],
+  TotalVideoSeconds: ["second of video", "seconds of video"],
+  BilledTokens: ["token", "tokens"],
+  Token: ["token", "tokens"],
+  BilledCharacters: ["character", "characters"],
+  Characters: ["character", "characters"],
+  Credits: ["credit", "credits"],
+  ProviderUnits: ["Unit", "Units"],
+  PROVIDER_UNIT: ["Unit", "Units"],
+  Unit: ["Unit", "Units"]
+};
+function meterText(meter, size = 1) {
+  const [one, many] = METER_UNITS[meter] ?? [meter, meter];
+  return size === 1 ? `per ${one}` : `per ${countText(size)} ${many}`;
+}
+function rateAmount(rate) {
+  const micros = Math.ceil(Number((rate.unitPriceUsd * 1e6).toPrecision(12)));
+  return formatAmount({ value: (micros / 1e6).toFixed(6), currency: "USD" });
+}
+function describeRate(rate) {
+  return `${rateAmount(rate)} ${meterText(rate.meter, rate.unitSize)}`;
+}
+function ratesByMeter(rates) {
+  const groups = new Map;
+  for (const rate of rates)
+    groups.set(rate.meter, [...groups.get(rate.meter) ?? [], rate]);
+  return [...groups.values()];
+}
+function perUnit(rate) {
+  return rate.unitPriceUsd / (rate.unitSize || 1);
+}
+function hasConditions(rate) {
+  return Boolean(rate.conditions && Object.keys(rate.conditions).length > 0);
+}
+function summarizeRates(price, rates) {
+  const only = rates.length === 1 ? rates[0] : undefined;
+  if (only) {
+    const amount = price.amount ? formatAmount(price.amount) : rateAmount(only);
+    const text = `${amount} ${meterText(only.meter, only.unitSize)}`;
+    return hasConditions(only) ? `${text} (${conditionsText(only)})` : text;
+  }
+  return ratesByMeter(rates).map((group) => {
+    const cheapest = group.reduce((a, b) => perUnit(b) < perUnit(a) ? b : a);
+    const varies = new Set(group.map(describeRate)).size > 1;
+    return `${varies ? "from " : ""}${describeRate(cheapest)}`;
+  }).join(" + ");
+}
+function rateNotes(rate) {
+  const notes = [];
+  if (rate.freeUnits)
+    notes.push(`first ${rate.freeUnits} free`);
+  if (typeof rate.maximumUnits === "number")
+    notes.push(`billed up to ${rate.maximumUnits}`);
+  if (rate.roundUpTo)
+    notes.push(`rounded up to ${rate.roundUpTo}`);
+  return notes.join("; ");
+}
+function conditionsText(rate) {
+  const conditions = rate.conditions && typeof rate.conditions === "object" ? rate.conditions : {};
+  return whenText(conditions) || "-";
+}
+function summarizePrice(price, fallback) {
+  if (!price)
+    return fallback || "-";
+  if (price.rates?.length)
+    return summarizeRates(price, price.rates);
+  if (!price.amount)
+    return fallback || "-";
   let text;
   switch (price.type) {
     case "PER_UNIT_MATRIX": {
@@ -3925,9 +5090,41 @@ function summarizePrice(price) {
 function whenText(when) {
   return Object.entries(when).map(([key, value]) => `${key}=${String(value)}`).join(", ");
 }
-function priceDetail(price) {
+function priceDetail(price, fallback) {
   const rows = [];
   const lines = [];
+  const summary = summarizePrice(price, fallback);
+  if (!price)
+    return { summary, rows, lines };
+  const rates = price.rates ?? [];
+  if (rates.length > 1 || rates.some(hasConditions)) {
+    const notes = rates.map(rateNotes);
+    const withNotes = notes.some(Boolean);
+    rows.push(["CHARGE", "CONDITIONS", "PRICE", ...withNotes ? ["NOTES"] : []]);
+    rates.forEach((rate, index) => {
+      const [one] = METER_UNITS[rate.meter] ?? [rate.meter];
+      rows.push([
+        one,
+        conditionsText(rate),
+        describeRate(rate),
+        ...withNotes ? [notes[index] || "-"] : []
+      ]);
+    });
+    if (ratesByMeter(rates).length > 1) {
+      lines.push("Different charges add up; for each charge, the row matching the request applies.");
+    } else if (rates.length > 1) {
+      lines.push("The row matching the request applies.");
+    } else {
+      lines.push("This price applies when the request matches its conditions.");
+    }
+  } else if (rates[0] && rateNotes(rates[0])) {
+    lines.push(rateNotes(rates[0]));
+  }
+  if (price.description)
+    lines.push(price.description);
+  if (rates.length > 0) {
+    lines.push("The final cost depends on actual usage: see `cost` in `solgrid runs get`.");
+  }
   if (price.type === "PER_UNIT_MATRIX" && price.variants?.length) {
     const keys = price.selectors?.map((s) => s.key) ?? Object.keys(price.variants[0]?.when ?? {});
     const labels = keys.map((key) => price.selectors?.find((s) => s.key === key)?.label ?? key);
@@ -3944,11 +5141,11 @@ function priceDetail(price) {
   }
   for (const note of price.notes ?? [])
     lines.push(note);
-  return { summary: summarizePrice(price), rows, lines };
+  return { summary, rows, lines };
 }
 
 // src/output/schema.ts
-var MAX_DEPTH = 2;
+var MAX_DEPTH2 = 2;
 var MAX_ENUM_VALUES = 6;
 function isSchema(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -3993,7 +5190,7 @@ function schemaFields(schema, prefix = "", depth = 0) {
       required: required.has(name),
       description: describe(property)
     });
-    if (property.type === "object" && depth + 1 < MAX_DEPTH) {
+    if (property.type === "object" && depth + 1 < MAX_DEPTH2) {
       fields.push(...schemaFields(property, `${path}.`, depth + 1));
     }
   }
@@ -4021,7 +5218,7 @@ function registerToolCommands(program, ctx) {
       const table = renderTable(["PROVIDER", "ENDPOINT", "PRICE", "HEALTH", "DESCRIPTION"], data.results.map((r) => [
         r.provider,
         r.endpoint,
-        summarizePrice(r.price),
+        truncate(summarizePrice(r.price, r.externalPrice), 60),
         formatHealth(r.metrics, out.style),
         truncate(r.description, 60)
       ]), { formatHeader: (text) => out.style("dim", text) });
@@ -4045,7 +5242,7 @@ function registerToolCommands(program, ctx) {
   }));
 }
 function renderInspect(tool, style) {
-  const price = priceDetail(tool.price);
+  const price = priceDetail(tool.price, tool.externalPrice);
   const runtime = tool.metrics?.runTimeMs;
   const lines = [
     style("bold", `${tool.providerName || tool.provider} · ${tool.endpoint}`),
@@ -4119,6 +5316,7 @@ function createProgram(ctx, options = {}) {
   registerRunCommand(program, ctx);
   registerRunsCommand(program, ctx);
   registerFilesCommand(program, ctx);
+  registerSkillsCommand(program, ctx);
   registerAccountCommands(program, ctx);
   registerKeysCommand(program, ctx);
   registerSessionIdCommand(program, ctx);