@jarel/myskills 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -41,9 +41,29 @@ myskills login [--api-url <url>] [--method <password|api-key>] [--email <email>]
 myskills login --api-key [--api-url <url>]
 myskills logout [--api-url <url>] [--token <token>]
 myskills whoami [--api-url <url>] [--token <token>]
+myskills auth status [--api-url <url>] [--token <token>]
+myskills doctor [--api-url <url>] [--json]
+myskills config get api-url
+myskills config set api-url <url>
+myskills config reset api-url
+myskills config list
 myskills submit --path <file-directory-or-zip> [--api-url <url>] [--token <token>]
 myskills review submissions [--api-url <url>] [--token <token>]
-myskills review action <submission-id> --action <approve|publish> [--reason <text>]
+myskills review action <submission-id> --action <approve|request-changes|reject|publish> [--reason <text>] [--api-url <url>] [--token <token>]
+myskills submissions list [--api-url <url>] [--token <token>]
+myskills submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]
+myskills skills edit <skill-slug> [--title <text>] [--summary <text>] [--visibility <scope>] [--tag <tag>] [--reason <text>] [--api-url <url>] [--token <token>]
+myskills skills archive|restore|delete <skill-slug> [--reason <text>] [--api-url <url>] [--token <token>]
+myskills releases list <skill-slug> [--api-url <url>] [--token <token>]
+myskills releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--reason <text>] [--replacement <version>] [--api-url <url>] [--token <token>]
+myskills teams list|skills [--api-url <url>] [--token <token>]
+myskills teams create <team-name> [--name <team-name>] [--api-url <url>] [--token <token>]
+myskills teams invite <team-id> --email <email> [--api-url <url>] [--token <token>]
+myskills teams accept <invitation-id> [--api-url <url>] [--token <token>]
+myskills sharing get <skill-slug> [--api-url <url>] [--token <token>]
+myskills sharing set <skill-slug> --visibility <scope> [--team <team-id>] [--user <email>]
+myskills admin sharing get [--api-url <url>] [--token <token>]
+myskills admin sharing set [--public <true|false>] [--authenticated <true|false>] [--teams <true|false>] [--team-visibility <true|false>] [--user-visibility <true|false>]
 myskills export <skill-slug> --version <version> --platform <platform> --output <dir>
 myskills install <skill-slug> [--version <version>] [--platform <platform>] [--dir <install-root>]
 myskills list [--dir <install-root>]
@@ -72,9 +92,13 @@ npm install -g @jarel/myskills@alpha
 
 `validate`, `scan`, and `submit` accept a manifest file, package directory, or local `.zip` package. `login` prompts for the API URL when one is not supplied; the default is the local API at `http://localhost:3001`, and custom hosted URLs can be entered manually. Successful login stores the selected API URL in local CLI config so later commands can omit `--api-url`. API URL resolution is `--api-url`, then `MYSKILLS_API_URL`, then saved config, then `http://localhost:3001`.
 
-`login` supports an email/password session flow and an API-key flow. The email/password flow handles MFA challenges with a TOTP or recovery code prompt and stores only the verified session token. The API-key flow validates the key with `/v1/me` before storing it. Token resolution is `--token`, then `MYSKILLS_TOKEN`, then the stored login token. The default token store uses the platform credential store through `@napi-rs/keyring` and falls back to `tokens.json` with user-only file permissions when keyring storage is unavailable or `MYSKILLS_TOKEN_STORE=file`/`MYSKILLS_TOKEN_FILE` is set. `logout` revokes stored session tokens and clears the local entry; stored API tokens are removed locally and must be revoked with `token revoke`.
+`login` supports an email/password session flow and an API-key flow. The email/password flow handles MFA challenges with a TOTP or recovery code prompt and stores only the verified session token. The API-key flow validates the key with `/v1/me` before storing it. Token resolution is `--token`, then `MYSKILLS_TOKEN`, then the stored login token. The default token store uses the platform credential store through `@napi-rs/keyring` and falls back to `tokens.json` with user-only file permissions when keyring storage is unavailable or `MYSKILLS_TOKEN_STORE=file`/`MYSKILLS_TOKEN_FILE` is set. `auth status` validates the current token without printing it. `logout` revokes stored session tokens and clears the local entry; stored API tokens are removed locally and must be revoked with `token revoke`.
 
-`submit` validates and scans locally before sending package directories as normalized text entries or `.zip` packages as base64 archive uploads for server-side extraction. `export` downloads server-authorized bundle content, verifies byte size and SHA-256 against release metadata, and writes normalized package paths under the requested output directory. `install` uses the same verified bundle path, writes into `--dir`, `MYSKILLS_INSTALL_DIR`, or the user data directory, and records local state in `.myskills-app/installed.json`; `update` preserves a rollback snapshot before replacing files, and `rollback` restores the most recent snapshot. `token create` prints the plaintext API token only once and does not overwrite the stored login session. Browser/device login, platform-specific install adapters, and archive creation are still planned.
+`config get api-url`, `config set api-url <url>`, `config reset api-url`, and `config list` manage the saved API URL. `doctor` checks the CLI version, Node version, resolved API URL, `/health`, auth status, token-store backend, install-directory writability, and `/v1/capabilities`. If the CLI is pointed at the web app instead of the API, or a newer command is sent to an older server, command errors include concrete next steps and `--json` returns structured error codes.
+
+`submit` validates and scans locally before sending package directories as normalized text entries or `.zip` packages as base64 archive uploads for server-side extraction. Authors can inspect their submitted versions with `submissions list` and withdraw unreviewed or changes-requested submissions with `submissions withdraw`. Maintainers can approve, request changes, reject, and publish submitted versions through `review action`.
+
+Published artifacts remain immutable. `skills edit` changes mutable skill metadata only, while `releases deprecate`, `releases unpublish`, `releases revoke`, `releases restore`, and `releases delete` update server-owned lifecycle state for a specific version. Deprecated releases remain visible and installable; unpublished, revoked, archived, and deleted releases are hidden from install/export queries. `export` downloads server-authorized bundle content, verifies byte size and SHA-256 against release metadata, and writes normalized package paths under the requested output directory. `install` uses the same verified bundle path, writes into `--dir`, `MYSKILLS_INSTALL_DIR`, or the user data directory, and records local state in `.myskills-app/installed.json`; `update` preserves a rollback snapshot before replacing files, and `rollback` restores the most recent snapshot. `token create` prints the plaintext API token only once and does not overwrite the stored login session. Browser/device login, platform-specific install adapters, and archive creation are still planned.
 
 Common scopes:
 

package/dist/index.js

@@ -16321,7 +16321,7 @@ function decodePackageText(buffer, relativePath) {
 
 // src/cli.ts
 var DEFAULT_API_URL = "http://localhost:3001";
-var CLI_VERSION = "0.1.0-alpha.1";
+var CLI_VERSION = "0.1.0-alpha.3";
 var CLI_VISIBILITY_SCOPES = ["public", "authenticated", "organization", "team", "private", "explicit-users"];
 var LOGIN_AUTH_METHODS = ["password", "api-key"];
 async function runCli(argv, runtime) {
@@ -16353,10 +16353,22 @@ async function runCli(argv, runtime) {
         return await logoutCommand(parsed, runtime);
       case "whoami":
         return await whoamiCommand(parsed, runtime);
+      case "auth":
+        return await authCommand(parsed, runtime);
+      case "config":
+        return await configCommand(parsed, runtime);
+      case "doctor":
+        return await doctorCommand(parsed, runtime);
       case "submit":
         return await submitCommand(parsed, runtime);
       case "review":
         return await reviewCommand(parsed, runtime);
+      case "submissions":
+        return await submissionsCommand(parsed, runtime);
+      case "skills":
+        return await skillsCommand(parsed, runtime);
+      case "releases":
+        return await releasesCommand(parsed, runtime);
       case "teams":
         return await teamsCommand(parsed, runtime);
       case "sharing":
@@ -16380,10 +16392,19 @@ async function runCli(argv, runtime) {
     }
   } catch (error51) {
     if (error51 instanceof CliError) {
-      runtime.io.stderr(error51.message);
+      if (parsed.options.json) {
+        runtime.io.stderr(JSON.stringify({ error: error51.toJSON() }, null, 2));
+      } else {
+        runtime.io.stderr(error51.message);
+      }
       return error51.exitCode;
     }
-    runtime.io.stderr(error51 instanceof Error ? error51.message : "Unexpected CLI failure.");
+    const message = error51 instanceof Error ? error51.message : "Unexpected CLI failure.";
+    if (parsed.options.json) {
+      runtime.io.stderr(JSON.stringify({ error: { code: "UNEXPECTED_CLI_FAILURE", message } }, null, 2));
+    } else {
+      runtime.io.stderr(message);
+    }
     return 1;
   }
 }
@@ -16538,6 +16559,143 @@ async function whoamiCommand(parsed, runtime) {
   }
   return 0;
 }
+async function authCommand(parsed, runtime) {
+  const subcommand = parsed.args[0];
+  if (subcommand === "status") {
+    return await authStatusCommand(parsed, runtime);
+  }
+  throw new CliError("Usage: myskills auth status", 2, "USAGE_ERROR");
+}
+async function authStatusCommand(parsed, runtime) {
+  const api = apiBaseUrlResolution(parsed, runtime);
+  const resolved = await resolveToken(parsed, runtime);
+  if (!resolved) {
+    const status2 = {
+      apiUrl: api.url,
+      apiUrlSource: api.source,
+      status: "not_logged_in",
+      tokenSource: "none",
+      tokenStore: await tokenStoreInfo(runtime)
+    };
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify(status2, null, 2));
+    } else {
+      runtime.io.stdout(`API URL: ${status2.apiUrl} (${status2.apiUrlSource})`);
+      runtime.io.stdout("Status: not logged in");
+      runtime.io.stdout(`Token store: ${status2.tokenStore.backend}`);
+    }
+    return 0;
+  }
+  const response = await apiGet("/v1/me", parsed, runtime, resolved.value);
+  const user = response.user;
+  const status = {
+    apiUrl: api.url,
+    apiUrlSource: api.source,
+    status: "logged_in",
+    tokenSource: resolved.source,
+    tokenKind: resolved.stored.kind,
+    tokenStore: await tokenStoreInfo(runtime),
+    user: {
+      email: user.email,
+      roles: user.roles,
+      mfaVerified: user.mfaVerified
+    },
+    expiresAt: resolved.stored.expiresAt ?? null
+  };
+  if (parsed.options.json) {
+    runtime.io.stdout(JSON.stringify(status, null, 2));
+  } else {
+    runtime.io.stdout(`API URL: ${status.apiUrl} (${status.apiUrlSource})`);
+    runtime.io.stdout(`Status: logged in (${status.tokenKind}, ${status.tokenSource})`);
+    runtime.io.stdout(`User: ${user.email}`);
+    runtime.io.stdout(`Roles: ${user.roles.join(",") || "-"}`);
+    runtime.io.stdout(`MFA: ${user.mfaVerified ? "verified" : "not-verified"}`);
+    runtime.io.stdout(`Expires: ${status.expiresAt ?? "-"}`);
+    runtime.io.stdout(`Token store: ${status.tokenStore.backend}`);
+  }
+  return 0;
+}
+async function configCommand(parsed, runtime) {
+  const subcommand = parsed.args[0];
+  const key = parsed.args[1];
+  if (!runtime.configStore) {
+    throw new CliError("No config store is configured.", 1, "CONFIG_STORE_UNAVAILABLE");
+  }
+  if (subcommand === "get" && key === "api-url") {
+    const apiUrl = runtime.configStore.getApiUrl() ?? null;
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify({ apiUrl }, null, 2));
+    } else {
+      runtime.io.stdout(apiUrl ?? "unset");
+    }
+    return 0;
+  }
+  if (subcommand === "set" && key === "api-url") {
+    const apiUrl = parsed.args[2];
+    if (!apiUrl) {
+      throw new CliError("Usage: myskills config set api-url <url>", 2, "USAGE_ERROR");
+    }
+    await runtime.configStore.setApiUrl(normalizeApiUrlOption(apiUrl));
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify({ apiUrl: normalizeApiUrlOption(apiUrl) }, null, 2));
+    } else {
+      runtime.io.stdout(`api-url=${normalizeApiUrlOption(apiUrl)}`);
+    }
+    return 0;
+  }
+  if (subcommand === "reset" && key === "api-url") {
+    await runtime.configStore.resetApiUrl();
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify({ apiUrl: null }, null, 2));
+    } else {
+      runtime.io.stdout("api-url unset");
+    }
+    return 0;
+  }
+  if (subcommand === "list") {
+    const resolved = apiBaseUrlResolution(parsed, runtime);
+    const saved = runtime.configStore.getApiUrl() ?? null;
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify({ apiUrl: saved, resolvedApiUrl: resolved.url, resolvedApiUrlSource: resolved.source }, null, 2));
+    } else {
+      runtime.io.stdout(`api-url=${saved ?? "unset"}`);
+      runtime.io.stdout(`resolved-api-url=${resolved.url}	source=${resolved.source}`);
+    }
+    return 0;
+  }
+  throw new CliError("Usage: myskills config get api-url | config set api-url <url> | config reset api-url | config list", 2, "USAGE_ERROR");
+}
+async function doctorCommand(parsed, runtime) {
+  const api = apiBaseUrlResolution(parsed, runtime);
+  const checks = [];
+  checks.push(nodeVersionCheck());
+  checks.push({ name: "cli_version", ok: true, message: CLI_VERSION, details: { version: CLI_VERSION } });
+  checks.push({ name: "api_url", ok: true, message: `${api.url} (${api.source})`, details: api });
+  const health = await doctorHealthCheck(parsed, runtime);
+  checks.push(health);
+  const token = await resolveToken(parsed, runtime);
+  checks.push(await doctorAuthCheck(parsed, runtime, token));
+  checks.push(await doctorTokenStoreCheck(runtime));
+  checks.push(await doctorInstallDirCheck(parsed, runtime));
+  checks.push(await doctorCapabilitiesCheck(parsed, runtime));
+  const failed = checks.filter((check2) => !check2.ok);
+  const result = {
+    cliVersion: CLI_VERSION,
+    apiUrl: api.url,
+    apiUrlSource: api.source,
+    checks
+  };
+  if (parsed.options.json) {
+    runtime.io.stdout(JSON.stringify(result, null, 2));
+  } else {
+    runtime.io.stdout(`MySkills CLI ${CLI_VERSION}`);
+    runtime.io.stdout("");
+    for (const check2 of checks) {
+      runtime.io.stdout(`${check2.ok ? "ok" : "fail"}	${check2.name}	${check2.message}`);
+    }
+  }
+  return failed.length === 0 ? 0 : 1;
+}
 async function tokenCommand(parsed, runtime) {
   const token = await tokenOption(parsed, runtime);
   if (!token) {
@@ -16622,11 +16780,11 @@ async function reviewCommand(parsed, runtime) {
   if (subcommand === "action") {
     const submissionId = parsed.args[1];
     if (!submissionId) {
-      throw new CliError("Usage: myskills review action <submission-id> --action <approve|publish>", 2);
+      throw new CliError("Usage: myskills review action <submission-id> --action <approve|request-changes|reject|publish> [--reason <text>] [--api-url <url>] [--token <token>]", 2);
     }
     const action = stringOption(parsed, "action");
-    if (action !== "approve" && action !== "publish") {
-      throw new CliError("--action must be approve or publish.", 2);
+    if (action !== "approve" && action !== "request-changes" && action !== "reject" && action !== "publish") {
+      throw new CliError("--action must be approve, request-changes, reject, or publish.", 2);
     }
     const reason = optionalStringOption(parsed, "reason");
     const response = await apiPost(`/v1/review/submissions/${encodeURIComponent(submissionId)}/actions`, {
@@ -16641,7 +16799,144 @@ async function reviewCommand(parsed, runtime) {
     }
     return 0;
   }
-  throw new CliError("Usage: myskills review submissions | review action <submission-id> --action <approve|publish>", 2);
+  throw new CliError("Usage: myskills review submissions | review action <submission-id> --action <approve|request-changes|reject|publish> [--reason <text>]", 2);
+}
+async function submissionsCommand(parsed, runtime) {
+  const token = await requireToken(parsed, runtime);
+  const subcommand = parsed.args[0];
+  if (subcommand === "list" || subcommand === "mine") {
+    const response = await apiGet("/v1/submissions/mine", parsed, runtime, token);
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify(response, null, 2));
+    } else {
+      const submissions = arrayField(response, "submissions");
+      if (submissions.length === 0) {
+        runtime.io.stdout("No submissions.");
+      } else {
+        for (const value of submissions) {
+          const submission = recordField(value, "submission");
+          runtime.io.stdout([
+            requiredRecordString(submission, "id", "Submission response is missing id."),
+            `${requiredRecordString(submission, "slug", "Submission response is missing slug.")}@${requiredRecordString(submission, "version", "Submission response is missing version.")}`,
+            optionalRecordString(submission, "reviewStatus") ?? "-",
+            optionalRecordString(submission, "lifecycleStatus") ?? "-",
+            optionalRecordString(submission, "securityStatus") ?? "-"
+          ].join("	"));
+        }
+      }
+    }
+    return 0;
+  }
+  if (subcommand === "withdraw") {
+    const submissionId = parsed.args[1];
+    if (!submissionId) {
+      throw new CliError("Usage: myskills submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const response = await apiPost(`/v1/submissions/${encodeURIComponent(submissionId)}/actions`, {
+      action: "withdraw",
+      ...reasonPayload(parsed)
+    }, parsed, runtime, token);
+    printNamedRecord(response, "submission", runtime.io, ["id", "slug", "version", "reviewStatus", "lifecycleStatus"]);
+    return 0;
+  }
+  throw new CliError("Usage: myskills submissions list | submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+}
+async function skillsCommand(parsed, runtime) {
+  const token = await requireToken(parsed, runtime);
+  const subcommand = parsed.args[0];
+  const slug = parsed.args[1];
+  if (subcommand === "edit") {
+    if (!slug) {
+      throw new CliError("Usage: myskills skills edit <skill-slug> [--title <text>] [--summary <text>] [--visibility <scope>] [--tag <tag>] [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const payload = {
+      ...reasonPayload(parsed)
+    };
+    const title = optionalStringOption(parsed, "title");
+    const summary = optionalStringOption(parsed, "summary");
+    const visibility = optionalStringOption(parsed, "visibility");
+    const tags = stringListOption(parsed, "tag");
+    if (title !== void 0) {
+      payload.title = title;
+    }
+    if (summary !== void 0) {
+      payload.summary = summary;
+    }
+    if (visibility !== void 0) {
+      if (!CLI_VISIBILITY_SCOPES.includes(visibility)) {
+        throw new CliError(`--visibility must be one of: ${CLI_VISIBILITY_SCOPES.join(", ")}.`, 2);
+      }
+      payload.visibility = visibility;
+    }
+    if (tags.length > 0) {
+      payload.tags = tags;
+    }
+    if (Object.keys(payload).every((key) => key === "reason")) {
+      throw new CliError("At least one metadata option is required.", 2);
+    }
+    const response = await apiPut(`/v1/skills/${encodeURIComponent(parseInstallSlug(slug))}`, payload, parsed, runtime, token);
+    printNamedRecord(response, "skill", runtime.io, ["slug", "title", "lifecycleStatus", "visibility"]);
+    return 0;
+  }
+  if (subcommand === "archive" || subcommand === "restore" || subcommand === "delete") {
+    if (!slug) {
+      throw new CliError("Usage: myskills skills archive|restore|delete <skill-slug> [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const response = await apiPost(`/v1/skills/${encodeURIComponent(parseInstallSlug(slug))}/actions`, {
+      action: subcommand,
+      ...reasonPayload(parsed)
+    }, parsed, runtime, token);
+    printNamedRecord(response, "skill", runtime.io, ["slug", "title", "lifecycleStatus", "visibility"]);
+    return 0;
+  }
+  throw new CliError("Usage: myskills skills edit|archive|restore|delete <skill-slug> [--api-url <url>] [--token <token>]", 2);
+}
+async function releasesCommand(parsed, runtime) {
+  const subcommand = parsed.args[0];
+  if (subcommand === "list") {
+    const slug = parsed.args[1];
+    if (!slug) {
+      throw new CliError("Usage: myskills releases list <skill-slug>", 2);
+    }
+    const token = await tokenOption(parsed, runtime) ?? void 0;
+    const response = await apiGet(`/v1/skills/${encodeURIComponent(parseInstallSlug(slug))}/releases`, parsed, runtime, token);
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify(response, null, 2));
+    } else {
+      const releases = arrayField(response, "releases");
+      if (releases.length === 0) {
+        runtime.io.stdout("No releases.");
+      } else {
+        for (const value of releases) {
+          const release = recordField(value, "release");
+          runtime.io.stdout([
+            `${requiredRecordString(release, "slug", "Release response is missing slug.")}@${requiredRecordString(release, "version", "Release response is missing version.")}`,
+            optionalRecordString(release, "lifecycleStatus") ?? "-",
+            optionalRecordString(release, "reviewStatus") ?? "-",
+            optionalRecordString(release, "securityStatus") ?? "-",
+            `published=${optionalRecordString(release, "publishedAt") ?? "-"}`
+          ].join("	"));
+        }
+      }
+    }
+    return 0;
+  }
+  if (["deprecate", "unpublish", "revoke", "restore", "delete"].includes(subcommand ?? "")) {
+    const target = parsed.args[1];
+    if (!target) {
+      throw new CliError("Usage: myskills releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--reason <text>] [--replacement <version>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const { slug, version: version2 } = parseReleaseTarget(target);
+    const token = await requireToken(parsed, runtime);
+    const response = await apiPost(`/v1/skills/${encodeURIComponent(slug)}/releases/${encodeURIComponent(version2)}/actions`, {
+      action: subcommand,
+      ...reasonPayload(parsed),
+      ...optionalStringOption(parsed, "replacement") ? { replacement: optionalStringOption(parsed, "replacement") } : {}
+    }, parsed, runtime, token);
+    printNamedRecord(response, "release", runtime.io, ["slug", "version", "lifecycleStatus", "reviewStatus", "securityStatus"]);
+    return 0;
+  }
+  throw new CliError("Usage: myskills releases list <skill-slug> | releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--api-url <url>] [--token <token>]", 2);
 }
 async function teamsCommand(parsed, runtime) {
   const token = await requireToken(parsed, runtime);
@@ -17356,6 +17651,26 @@ function recordField(input, label) {
   }
   return input;
 }
+function printNamedRecord(response, key, io, fields) {
+  const record2 = recordField(response[key], key);
+  io.stdout(fields.map((field) => optionalRecordString(record2, field) ?? "-").join("	"));
+}
+function reasonPayload(parsed) {
+  const reason = optionalStringOption(parsed, "reason");
+  return reason ? { reason } : {};
+}
+function parseReleaseTarget(target) {
+  const separator = target.lastIndexOf("@");
+  if (separator <= 0 || separator === target.length - 1) {
+    throw new CliError("Release target must be <skill-slug>@<version>.", 2);
+  }
+  const slug = parseInstallSlug(target.slice(0, separator));
+  const version2 = target.slice(separator + 1);
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version2)) {
+    throw new CliError("Release version is invalid.", 2);
+  }
+  return { slug, version: version2 };
+}
 function arrayField(record2, key) {
   const value = record2[key];
   return Array.isArray(value) ? value : [];
@@ -17412,101 +17727,296 @@ function assertChildPath(root, target) {
   }
 }
 async function apiGet(pathname, parsed, runtime, token) {
-  const baseUrl = apiBaseUrl(parsed, runtime);
   const headers = {};
   if (token) {
     headers.authorization = `Bearer ${token}`;
   }
-  const response = await runtime.fetch(`${baseUrl}${pathname}`, { headers });
-  const text = await response.text();
-  const body = text ? JSON.parse(text) : {};
-  if (!response.ok) {
-    const error51 = body.error;
-    throw new CliError(error51?.message ?? `API request failed with ${response.status}.`, 1);
-  }
-  return body;
+  return await apiJsonRequest(pathname, parsed, runtime, { headers });
 }
 async function apiGetText(pathname, parsed, runtime, token) {
-  const baseUrl = apiBaseUrl(parsed, runtime);
   const headers = {};
   if (token) {
     headers.authorization = `Bearer ${token}`;
   }
-  const response = await runtime.fetch(`${baseUrl}${pathname}`, { headers });
-  const text = await response.text();
+  const response = await apiFetch(pathname, parsed, runtime, { headers });
   if (!response.ok) {
-    const error51 = parseApiError(text);
-    throw new CliError(error51 ?? `API request failed with ${response.status}.`, 1);
+    throw apiErrorFromResponse(pathname, apiBaseUrl(parsed, runtime), response.status, response.text);
   }
-  return text;
+  return response.text;
 }
 async function apiPost(pathname, payload, parsed, runtime, token) {
-  const baseUrl = apiBaseUrl(parsed, runtime);
   const headers = {
     "content-type": "application/json"
   };
   if (token) {
     headers.authorization = `Bearer ${token}`;
   }
-  const response = await runtime.fetch(`${baseUrl}${pathname}`, {
+  return await apiJsonRequest(pathname, parsed, runtime, {
     method: "POST",
     headers,
     body: JSON.stringify(payload)
   });
-  const text = await response.text();
-  const body = text ? JSON.parse(text) : {};
-  if (!response.ok) {
-    const error51 = body.error;
-    throw new CliError(error51?.message ?? `API request failed with ${response.status}.`, 1);
-  }
-  return body;
 }
 async function apiPut(pathname, payload, parsed, runtime, token) {
-  const baseUrl = apiBaseUrl(parsed, runtime);
   const headers = {
     "content-type": "application/json"
   };
   if (token) {
     headers.authorization = `Bearer ${token}`;
   }
-  const response = await runtime.fetch(`${baseUrl}${pathname}`, {
+  return await apiJsonRequest(pathname, parsed, runtime, {
     method: "PUT",
     headers,
     body: JSON.stringify(payload)
   });
-  const text = await response.text();
-  const body = text ? JSON.parse(text) : {};
-  if (!response.ok) {
-    const error51 = body.error;
-    throw new CliError(error51?.message ?? `API request failed with ${response.status}.`, 1);
-  }
-  return body;
 }
 async function apiDelete(pathname, parsed, runtime, token) {
-  const baseUrl = apiBaseUrl(parsed, runtime);
-  const response = await runtime.fetch(`${baseUrl}${pathname}`, {
+  return await apiJsonRequest(pathname, parsed, runtime, {
     method: "DELETE",
     headers: {
       authorization: `Bearer ${token}`
     }
   });
-  const text = await response.text();
-  const body = text ? JSON.parse(text) : {};
+}
+async function apiJsonRequest(pathname, parsed, runtime, init) {
+  const baseUrl = apiBaseUrl(parsed, runtime);
+  const response = await apiFetch(pathname, parsed, runtime, init);
+  const body = parseJsonResponse(pathname, baseUrl, response.text);
   if (!response.ok) {
-    const error51 = body.error;
-    throw new CliError(error51?.message ?? `API request failed with ${response.status}.`, 1);
+    throw apiErrorFromBody(pathname, baseUrl, response.status, body, response.text);
   }
   return body;
 }
-function parseApiError(text) {
+async function apiFetch(pathname, parsed, runtime, init) {
+  const baseUrl = apiBaseUrl(parsed, runtime);
+  let response;
+  try {
+    response = await runtime.fetch(`${baseUrl}${pathname}`, init);
+  } catch {
+    throw new CliError([
+      "Could not reach the MySkills API.",
+      "",
+      `API URL: ${baseUrl}`,
+      "Check that the API is running, or use:",
+      "  myskills <command> --api-url https://myskills.sh/api"
+    ].join("\n"), 1, "API_UNREACHABLE");
+  }
+  return {
+    ok: response.ok,
+    status: response.status,
+    text: await response.text()
+  };
+}
+function parseJsonResponse(pathname, baseUrl, text) {
+  if (!text) {
+    return {};
+  }
+  if (/^\s*</.test(text)) {
+    throw htmlApiError(baseUrl);
+  }
+  try {
+    const body = JSON.parse(text);
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+      throw new Error("not object");
+    }
+    return body;
+  } catch {
+    throw new CliError(`API response for ${pathname} was not valid JSON.`, 1, "API_INVALID_JSON");
+  }
+}
+function apiErrorFromBody(pathname, baseUrl, status, body, text) {
+  if (status === 404 && isUnsupportedEndpointBody(body, text)) {
+    const command = unsupportedCommandForPath(pathname);
+    if (command) {
+      return new CliError([
+        `This MySkills server does not support the \`${command}\` command yet.`,
+        "",
+        `CLI version: ${CLI_VERSION}`,
+        `API URL: ${baseUrl}`,
+        "Run `myskills doctor` to inspect server capabilities."
+      ].join("\n"), 1, "API_UNSUPPORTED_ENDPOINT", status);
+    }
+  }
+  const error51 = body.error;
+  return new CliError(error51?.message ?? `API request failed with ${status}.`, 1, error51?.code ?? "API_REQUEST_FAILED", status);
+}
+function apiErrorFromResponse(pathname, baseUrl, status, text) {
+  if (/^\s*</.test(text)) {
+    return htmlApiError(baseUrl);
+  }
   try {
     const body = text ? JSON.parse(text) : {};
-    const error51 = body.error;
-    return error51?.message ?? null;
+    return apiErrorFromBody(pathname, baseUrl, status, body, text);
   } catch {
-    return null;
+    return new CliError(`API request failed with ${status}.`, 1, "API_REQUEST_FAILED", status);
+  }
+}
+function htmlApiError(baseUrl) {
+  return new CliError([
+    "The API URL returned HTML instead of JSON.",
+    "You may be pointing the CLI at the web app.",
+    "",
+    `Current API URL: ${baseUrl}`,
+    "Try: myskills <command> --api-url https://myskills.sh/api"
+  ].join("\n"), 1, "API_RETURNED_HTML");
+}
+function isUnsupportedEndpointBody(body, text) {
+  return typeof body.message === "string" && /Route .+ not found/.test(body.message) || typeof body.error === "string" && body.error === "Not Found" || /Route .+ not found/.test(text);
+}
+function unsupportedCommandForPath(pathname) {
+  if (pathname.startsWith("/v1/teams")) {
+    return "teams";
+  }
+  if (pathname.includes("/sharing") || pathname.startsWith("/v1/admin/sharing")) {
+    return "sharing";
+  }
+  return null;
+}
+function nodeVersionCheck() {
+  const version2 = process.versions.node;
+  const major = Number.parseInt(version2.split(".")[0] ?? "0", 10);
+  return {
+    name: "node",
+    ok: major >= 20,
+    message: `v${version2} (${major >= 20 ? "satisfies >=20" : "requires >=20"})`,
+    details: { version: version2, engine: ">=20" }
+  };
+}
+async function doctorHealthCheck(parsed, runtime) {
+  const baseUrl = apiBaseUrl(parsed, runtime);
+  try {
+    const response = await apiFetch("/health", parsed, runtime);
+    const body = parseJsonResponse("/health", baseUrl, response.text);
+    return {
+      name: "api_health",
+      ok: response.ok,
+      message: response.ok ? "ok" : `HTTP ${response.status}`,
+      details: { status: response.status, body }
+    };
+  } catch (error51) {
+    return {
+      name: "api_health",
+      ok: false,
+      message: error51 instanceof Error ? firstLine(error51.message) : "failed"
+    };
   }
 }
+async function doctorAuthCheck(parsed, runtime, resolved) {
+  if (!resolved) {
+    return {
+      name: "auth",
+      ok: true,
+      message: "not logged in",
+      details: { status: "not_logged_in" }
+    };
+  }
+  try {
+    const response = await apiGet("/v1/me", parsed, runtime, resolved.value);
+    const user = response.user;
+    return {
+      name: "auth",
+      ok: true,
+      message: `${user.email ?? "unknown"} (${resolved.stored.kind}, ${resolved.source})`,
+      details: {
+        status: "logged_in",
+        tokenSource: resolved.source,
+        tokenKind: resolved.stored.kind,
+        expiresAt: resolved.stored.expiresAt ?? null,
+        user
+      }
+    };
+  } catch (error51) {
+    return {
+      name: "auth",
+      ok: false,
+      message: error51 instanceof Error ? firstLine(error51.message) : "failed"
+    };
+  }
+}
+async function doctorTokenStoreCheck(runtime) {
+  const info = await tokenStoreInfo(runtime);
+  if (info.backend === "file" && info.filePath) {
+    const permissions = await filePermissions(info.filePath);
+    if (permissions && permissions !== "600") {
+      return {
+        name: "token_store",
+        ok: false,
+        message: `file permissions ${permissions}; expected 600`,
+        details: { ...info, permissions }
+      };
+    }
+    return {
+      name: "token_store",
+      ok: true,
+      message: permissions ? `file ${info.filePath} (${permissions})` : `file ${info.filePath} (not created)`,
+      details: { ...info, permissions }
+    };
+  }
+  return {
+    name: "token_store",
+    ok: true,
+    message: info.backend,
+    details: info
+  };
+}
+async function doctorInstallDirCheck(parsed, runtime) {
+  const root = installRoot(parsed, runtime);
+  const testFile = path2.join(root, ".myskills-app", "doctor-write-test");
+  try {
+    await mkdir(path2.dirname(testFile), { recursive: true });
+    await writeFile(testFile, "ok\n", "utf8");
+    await rm(testFile, { force: true });
+    return {
+      name: "install_dir",
+      ok: true,
+      message: `writable ${root}`,
+      details: { path: root }
+    };
+  } catch (error51) {
+    return {
+      name: "install_dir",
+      ok: false,
+      message: error51 instanceof Error ? firstLine(error51.message) : "not writable",
+      details: { path: root }
+    };
+  }
+}
+async function doctorCapabilitiesCheck(parsed, runtime) {
+  try {
+    const response = await apiGet("/v1/capabilities", parsed, runtime);
+    const capabilities = response.capabilities && typeof response.capabilities === "object" && !Array.isArray(response.capabilities) ? response.capabilities : {};
+    const supported = Object.entries(capabilities).filter(([, value]) => value === true).map(([key]) => key);
+    const unsupported = Object.entries(capabilities).filter(([, value]) => value === false).map(([key]) => key);
+    return {
+      name: "capabilities",
+      ok: true,
+      message: `supported=${supported.join(",") || "-"} unsupported=${unsupported.join(",") || "-"}`,
+      details: response
+    };
+  } catch (error51) {
+    return {
+      name: "capabilities",
+      ok: true,
+      message: `unknown (${error51 instanceof Error ? firstLine(error51.message) : "not available"})`
+    };
+  }
+}
+async function tokenStoreInfo(runtime) {
+  return await runtime.tokenStore?.describe?.() ?? { backend: "memory" };
+}
+async function filePermissions(filePath) {
+  try {
+    return ((await stat(filePath)).mode & 511).toString(8).padStart(3, "0");
+  } catch (error51) {
+    if (isNodeError(error51) && error51.code === "ENOENT") {
+      return null;
+    }
+    throw error51;
+  }
+}
+function firstLine(message) {
+  return message.split("\n")[0] ?? message;
+}
 function printScanResult(result, io) {
   if (result.findings.length === 0) {
     io.stdout(`clean files=${result.filesScanned} bytes=${result.bytesScanned}`);
@@ -17792,9 +18302,21 @@ function helpText() {
     "  login --api-key [--api-url <url>]",
     "  logout [--api-url <url>] [--token <token>]",
     "  whoami [--api-url <url>] [--token <token>]",
+    "  auth status [--api-url <url>] [--token <token>]",
+    "  doctor [--api-url <url>] [--json]",
+    "  config get api-url",
+    "  config set api-url <url>",
+    "  config reset api-url",
+    "  config list",
     "  submit --path <file-directory-or-zip> [--api-url <url>] [--token <token>]",
     "  review submissions [--api-url <url>] [--token <token>]",
-    "  review action <submission-id> --action <approve|publish> [--reason <text>]",
+    "  review action <submission-id> --action <approve|request-changes|reject|publish> [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  submissions list [--api-url <url>] [--token <token>]",
+    "  submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  skills edit <skill-slug> [--title <text>] [--summary <text>] [--visibility <scope>] [--tag <tag>] [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  skills archive|restore|delete <skill-slug> [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  releases list <skill-slug> [--api-url <url>] [--token <token>]",
+    "  releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--reason <text>] [--replacement <version>] [--api-url <url>] [--token <token>]",
     "  teams list|skills [--api-url <url>] [--token <token>]",
     "  teams create <team-name> [--name <team-name>] [--api-url <url>] [--token <token>]",
     "  teams invite <team-id> --email <email> [--api-url <url>] [--token <token>]",
@@ -17820,15 +18342,26 @@ function helpText() {
   ].join("\n");
 }
 var CliError = class extends Error {
-  constructor(message, exitCode) {
+  constructor(message, exitCode, code = "CLI_ERROR", status) {
     super(message);
     this.exitCode = exitCode;
+    this.code = code;
+    this.status = status;
   }
   exitCode;
+  code;
+  status;
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.status !== void 0 ? { status: this.status } : {}
+    };
+  }
 };
 
 // src/config-store.ts
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path3 from "node:path";
 function createFileConfigStore(env = process.env) {
@@ -17844,6 +18377,10 @@ function createFileConfigStore(env = process.env) {
         apiUrl: apiUrl.replace(/\/+$/, "")
       };
       writePayload(filePath, payload);
+    },
+    async resetApiUrl() {
+      payload = { version: 1 };
+      rmSync(filePath, { force: true });
     }
   };
 }
@@ -17922,10 +18459,17 @@ function createFileTokenStore(env = process.env) {
         return;
       }
       await writePayload2(filePath, payload);
+    },
+    describe() {
+      return {
+        backend: "file",
+        filePath
+      };
     }
   };
 }
 function createKeyringTokenStore(fallback) {
+  const fallbackInfo = fallback.describe?.();
   return {
     async get(apiUrl) {
       const keyringToken = await readKeyringToken(apiUrl);
@@ -17940,6 +18484,12 @@ function createKeyringTokenStore(fallback) {
     async delete(apiUrl) {
       await deleteKeyringToken(apiUrl);
       await fallback.delete(apiUrl);
+    },
+    describe() {
+      return {
+        backend: "keyring",
+        fallbackFilePath: fallbackInfo?.filePath
+      };
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarel/myskills",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "Command-line client for publishing, discovering, installing, updating, and rolling back MySkills packages.",
   "license": "Apache-2.0",
   "private": false,