@rayul/kordis 0.9.2 → 0.10.0

package/assets/kordis-publishing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kordis-publishing
-description: Use whenever the user wants to publish, share, or push a package to Kordis — phrases like "publish this", "share this skill to Kordis", "push this rule", "release a new version of <slug>", "bump the version", "semver", "버전 올리기". Covers dry-run flow, frontmatter requirements, version bump strategies, semver rules, and the AI review pipeline.
+description: Use whenever the user wants to publish, share, or push a package to Kordis — phrases like "publish this", "share this skill to Kordis", "push this rule", "release a new version of <slug>", "bump the version", "semver", "버전 올리기", "yank", "withdraw a version", "unpublish a release", "철회". Covers dry-run flow, frontmatter requirements, version bump strategies, semver rules, yank/unyank for retracting bad releases, and the AI review pipeline.
 type: skill
 allowed-tools: ["Bash(kordis:*)", "Read", "Edit"]
 ---
@@ -36,6 +36,40 @@ single `.md` file that doesn't match the SKILL.md filename pattern.
   use only `--bump patch|minor|major` to control versioning. Having both
   is the most common push failure.
 
+## Yanking a bad version (0.10.0+)
+
+When a single release goes wrong — leaked secret, broken on platform X,
+superseded by an urgent fix — use **yank**, not delete.
+
+### `kordis yank <full_slug>@<version> [--reason <text>] [--force]`
+Soft-marks the specific version as "unrecommended". Author-only.
+Versions yanked this way:
+- Disappear from `kordis pull <slug>` (bare slug) and from `@^X.Y` /
+  `@X.x` / `@*` range resolution
+- **Still install** when explicitly pinned to that exact version
+  (`kordis pull <slug>@1.2.3`) — but the consumer's CLI prints a
+  stderr warning naming the reason. This preserves reproducibility of
+  prior pinned installs.
+- Reversible at any time with `kordis unyank`
+
+`--reason` is plain text capped at 280 chars — shown verbatim to
+consumers in `info` / `versions` / pull warning. Examples that work
+well: `"leaked AWS key"`, `"broken on Node 18"`, `"superseded by
+0.5.0 — security fix"`.
+
+### `kordis unyank <full_slug>@<version>`
+Reverses a yank. Idempotent. After unyank, the version re-enters
+range resolution and `current_version` recomputes if appropriate.
+
+### Yank vs delete — pick the right one
+- **`kordis yank <slug>@<version>`** — one bad release. Reversible.
+  Per-version. Preserves pinned-install reproducibility.
+- **`kordis delete <slug>`** — the whole package should disappear.
+  Permanent + slug reservation forever (no successor can republish
+  under the same name). Last-resort.
+
+If you just pushed a wrong version, the answer is almost always yank.
+
 ## Deleting a package
 
 ### `kordis delete <full_slug> [--force]`

package/assets/kordis-using/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kordis-using
-description: Use whenever the user wants to consult or install a Kordis package — including any `<username>/<slug>` reference, "install this skill", "use the X skill", "fetch the Y rule", "set this repo up with…", "pin to version", "specific version", "버전 고정", "전이 의존성", "transitive dependency". Covers JIT read vs pull, the five Kordis package types, dependencies, version pinning, range syntax, and attribution. Load eagerly when in doubt.
+description: Use whenever the user wants to consult or install a Kordis package — including any `<username>/<slug>` reference, "install this skill", "use the X skill", "fetch the Y rule", "set this repo up with…", "pin to version", "specific version", "버전 고정", "전이 의존성", "transitive dependency", "yanked", "version withdrawn", "철회", "unrecommended version". Covers JIT read vs pull, the five Kordis package types, dependencies, version pinning, range syntax, yank semantics, and attribution. Load eagerly when in doubt.
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
@@ -111,6 +111,7 @@ Supported forms:
 | `user/foo@1.0.0-beta.1`            | exact prerelease (only matches if the literal exists)            |
 | `user/foo@^1.2`                    | caret — highest 1.x.y (x≥2). For 0.x.y, caret pins the minor   |
 | `user/foo@~1.2`                    | tilde — highest 1.2.y                                            |
+| `user/foo@0.1.x`                   | x-range — alias for `~0.1` (0.9.3+; semver-native)               |
 | `user/foo@*`                       | alias for `current_version`                                      |
 
 Comparator strings (`>=1 <2`, `||`) are NOT supported in 0.9.x —
@@ -131,6 +132,31 @@ transitive deps — read is a one-shot context inject, no install plan.
 `kordis info user/foo@^1` shows a `Requested: 1.4.2 (current: 2.0.0)`
 line above `Type` when the pin differs from the registry default.
 
+## When a version is yanked (0.10.0+)
+
+Authors can soft-mark a specific release as "yanked" via `kordis yank
+<slug>@<version>` — usually to discourage installs of a broken or
+unsafe version. Yank is reversible (`kordis unyank`), per-version (NOT
+whole-package), and preserves reproducibility of prior pinned
+installs.
+
+Three install behaviours:
+
+| Input                              | Behaviour                                                        |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `kordis pull <slug>`               | Always picks the highest **non-yanked** version. Yanked versions are silently skipped — user sees the next-best release. |
+| `kordis pull <slug>@^X.Y`          | Range resolution skips yanked. If every match is yanked, server returns `not_found` with hint "every version satisfying X has been yanked". |
+| `kordis pull <slug>@<exact>` (pinned to a yanked version) | Succeeds (exit 0) with a stderr warning: `⚠ pulled yanked version X of slug (reason: …) — author marked this as unrecommended on YYYY-MM-DD`. Stays installable so old lockfiles keep working. |
+
+`kordis info <slug>` shows a red `⚠ Yanked YYYY-MM-DD` banner with the
+reason when the resolved version is yanked. `kordis versions <slug>`
+greys out yanked rows and suffixes their status with ` (yanked)`.
+
+Transitive yank: if `A → B@^1` and the only `B@^1` is yanked, server
+returns `dependency_conflict` (exit 35) with a chain link naming the
+parent. Surface that chain to the user — fixing usually means pinning
+A's requirement to a non-yanked range, or contacting B's author.
+
 ## Dependencies
 `kordis pull` reports `depends` and `recommends` from the package metadata.
 Surface the dependency tree to the user FIRST. If they accept,

package/dist/index.js

@@ -334,7 +334,14 @@ var init_package = __esm({
        * concrete resolved version. Absent for bare-slug calls (where the
        * response reflects `current_version`).
        */
-      requested_version: SemverSchema.optional()
+      requested_version: SemverSchema.optional(),
+      /**
+       * 0.10.0+ — yank status of the *displayed* version (requested_version
+       * if pinned, else current_version). Absent for non-yanked versions
+       * so pre-0.10 clients keep ignoring unknown fields.
+       */
+      yanked_at: IsoDateTimeSchema.nullable().optional(),
+      yank_reason: z6.string().max(280).nullable().optional()
     });
     PackageVersionSchema = z6.object({
       id: UuidSchema,
@@ -347,7 +354,15 @@ var init_package = __esm({
       review_status: ReviewStatusSchema,
       review_score: z6.number().nullable(),
       review_flags: z6.array(ReviewFlagSchema),
-      published_at: IsoDateTimeSchema
+      published_at: IsoDateTimeSchema,
+      /**
+       * 0.10.0+ — when set, this version was soft-marked as yanked by the
+       * author (or an admin override). Excluded from range/`*` resolution
+       * but still installable when explicitly pinned (`@<exact>`). Null
+       * for active versions.
+       */
+      yanked_at: IsoDateTimeSchema.nullable().optional(),
+      yank_reason: z6.string().max(280).nullable().optional()
     });
     PackageVersionSummarySchema = PackageVersionSchema.omit({ content: true });
     VersionDiffSchema = z6.object({
@@ -500,7 +515,7 @@ var init_auth = __esm({
 
 // ../../packages/contracts/src/api.ts
 import { z as z9 } from "zod";
-var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, AssetSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageRequestSchema, PullPackageResponseSchema, ResolveVersionQuerySchema, ResolveVersionResponseSchema, GetPackageQuerySchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema, ListUserPackagesResponseSchema, ListUserStarsResponseSchema, FollowResponseSchema, ListFollowersQuerySchema, ListFollowersResponseSchema;
+var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, AssetSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageRequestSchema, PullPackageResponseSchema, YankRequestSchema, YankResponseSchema, ResolveVersionQuerySchema, ResolveVersionResponseSchema, GetPackageQuerySchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema, ListUserPackagesResponseSchema, ListUserStarsResponseSchema, FollowResponseSchema, ListFollowersQuerySchema, ListFollowersResponseSchema;
 var init_api = __esm({
   "../../packages/contracts/src/api.ts"() {
     "use strict";
@@ -692,6 +707,17 @@ var init_api = __esm({
       installed_paths: z9.array(z9.string()),
       tool_detected: ToolSlugSchema.nullable(),
       format: z9.string(),
+      /**
+       * 0.10.0+ — true when the version being pulled was explicitly
+       * pinned (@version) AND has been yanked by its author. CLI uses this
+       * to print the stderr warning. Bare-slug / range pulls never set
+       * this flag (those paths silently skip yanked versions). Field is
+       * omitted entirely (not false) when not relevant, so pre-0.10
+       * clients ignore it cleanly.
+       */
+      yanked: z9.boolean().optional(),
+      yank_reason: z9.string().max(280).nullable().optional(),
+      yanked_at: IsoDateTimeSchema.nullable().optional(),
       dependencies: z9.object({
         required: z9.array(
           z9.object({
@@ -718,6 +744,16 @@ var init_api = __esm({
       }),
       recommends_hint: z9.string().nullable()
     });
+    YankRequestSchema = z9.object({
+      reason: z9.string().max(280).optional()
+    });
+    YankResponseSchema = z9.object({
+      full_slug: FullSlugSchema,
+      version: SemverSchema,
+      yanked_at: IsoDateTimeSchema.nullable(),
+      yank_reason: z9.string().max(280).nullable(),
+      effective_current_version: SemverSchema
+    });
     ResolveVersionQuerySchema = z9.object({
       range: SemverRangeSchema
     });
@@ -1101,6 +1137,8 @@ var init_client = __esm({
         if (opts.body !== void 0) init.body = JSON.stringify(opts.body);
         const method = (init.method ?? "GET").toUpperCase();
         const retryable = method === "GET";
+        const debug = typeof process !== "undefined" && process.env && (process.env["KORDIS_DEBUG"] === "1" || process.env["KORDIS_DEBUG"]?.toLowerCase() === "true");
+        const debugStart = debug ? Date.now() : 0;
         let lastErr;
         for (let attempt = 0; attempt < (retryable ? 2 : 1); attempt++) {
           try {
@@ -1110,12 +1148,22 @@ var init_client = __esm({
           } catch (err) {
             lastErr = err;
             if (attempt === 0 && retryable) {
+              if (debug) {
+                console.error(
+                  `[kordis] api: ${method} ${url.pathname}${url.search} \u2192 fetch failed, retrying in 150ms (${err.message})`
+                );
+              }
               await new Promise((resolve2) => setTimeout(resolve2, 150));
               continue;
             }
           }
         }
         if (lastErr !== void 0) {
+          if (debug) {
+            console.error(
+              `[kordis] api: ${method} ${url.pathname}${url.search} \u2192 ${lastErr.message} (${Date.now() - debugStart}ms)`
+            );
+          }
           throw new KordisNetworkError(
             `cannot reach ${url.hostname}: ${lastErr.message}`,
             lastErr
@@ -1123,6 +1171,11 @@ var init_client = __esm({
         }
         res = res;
         const requestId = res.headers.get("x-request-id") ?? void 0;
+        if (debug) {
+          console.error(
+            `[kordis] api: ${method} ${url.pathname}${url.search} \u2192 ${res.status} (${Date.now() - debugStart}ms${requestId ? `, req-id=${requestId}` : ""})`
+          );
+        }
         if (res.status === 204) return void 0;
         const text = await res.text();
         const parsed = text ? JSON.parse(text) : void 0;
@@ -1285,6 +1338,25 @@ var init_client = __esm({
           `/api/packages/${username}/${slug}/versions`
         );
       }
+      /**
+       * 0.10.0+ — soft-yank a specific version. Author-only by default;
+       * pass `asAdmin: true` to use the admin override (server validates
+       * the caller's role). Reason is plain text, 280 chars max.
+       */
+      yankVersion(username, slug, version, body = {}, opts = {}) {
+        const query = opts.asAdmin ? { as: "admin" } : void 0;
+        return this.request(
+          `/api/packages/${username}/${slug}/versions/${version}/yank`,
+          { method: "POST", body, ...query ? { query } : {} }
+        );
+      }
+      unyankVersion(username, slug, version, opts = {}) {
+        const query = opts.asAdmin ? { as: "admin" } : void 0;
+        return this.request(
+          `/api/packages/${username}/${slug}/versions/${version}/yank`,
+          { method: "DELETE", ...query ? { query } : {} }
+        );
+      }
       diff(username, slug, from, to) {
         return this.request(`/api/packages/${username}/${slug}/diff`, {
           query: { from, to }
@@ -1413,7 +1485,7 @@ var init_src2 = __esm({
 
 // src/index.ts
 init_src2();
-import { Command as Command23 } from "commander";
+import { Command as Command25 } from "commander";
 
 // src/commands/login.ts
 import { Command } from "commander";
@@ -3842,7 +3914,12 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
     installRoot,
     written,
     notes,
-    plan: pullRes.dependencies
+    plan: pullRes.dependencies,
+    ...pullRes.yanked ? {
+      yanked: true,
+      yankReason: pullRes.yank_reason ?? null,
+      yankedAt: pullRes.yanked_at ?? null
+    } : {}
   };
 }
 function pullCommand() {
@@ -3856,10 +3933,10 @@ function pullCommand() {
   ).option(
     "--no-with-required",
     "skip transitive required dependencies (advanced; default is to install)"
-  ).action(
+  ).option("--pin <semver>", "pin to an exact version or range (overrides @suffix)").action(
     async (fullSlugArg, opts) => {
       const parsed = parseSlugAtVersion(fullSlugArg);
-      const pin = parsed.version ?? parsed.range;
+      const pin = opts.pin ?? parsed.version ?? parsed.range;
       const userCwd = process.env["INIT_CWD"] ?? process.cwd();
       const installRoot = opts.target ?? userCwd;
       const detected = opts.tool ?? await detectTool(installRoot);
@@ -3911,6 +3988,11 @@ function pullCommand() {
           tool_detected: result.tool,
           installed_paths: result.written,
           notes: result.notes,
+          ...result.yanked ? {
+            yanked: true,
+            yank_reason: result.yankReason,
+            yanked_at: result.yankedAt
+          } : {},
           dependencies: dependencyInstalls.map((d) => ({
             full_slug: d.fullSlug,
             version: d.result.version,
@@ -3921,6 +4003,16 @@ function pullCommand() {
           printHuman(
             c.green(`\u2713 Installed ${c.bold(parsed.fullSlug)} v${result.version}`)
           );
+          if (result.yanked) {
+            const reasonSuffix = result.yankReason ? ` (reason: ${result.yankReason})` : "";
+            const dateSuffix = result.yankedAt ? ` on ${new Date(result.yankedAt).toISOString().slice(0, 10)}` : "";
+            process.stderr.write(
+              c.yellow(
+                `\u26A0 pulled yanked version ${result.version} of ${parsed.fullSlug}${reasonSuffix} \u2014 author marked this as unrecommended${dateSuffix}
+`
+              )
+            );
+          }
           for (const w of result.written) printHuman(`  ${c.gray("wrote")} ${w}`);
           for (const n of result.notes) printHuman(c.yellow(`  ! ${n}`));
           for (const dep of dependencyInstalls) {
@@ -4043,6 +4135,15 @@ function infoCommand() {
         printHuman(c.bold(detail.full_slug) + " " + c.gray(`v${headerVersion}`));
         printHuman("  " + detail.description);
         printHuman("");
+        if (detail.yanked_at) {
+          printHuman(
+            c.red("  \u26A0 Yanked") + " " + c.gray(new Date(detail.yanked_at).toISOString().slice(0, 10))
+          );
+          if (detail.yank_reason) {
+            printHuman(c.gray(`    reason: ${detail.yank_reason}`));
+          }
+          printHuman("");
+        }
         if (detail.requested_version && detail.requested_version !== detail.current_version) {
           printHuman(
             `  ${c.cyan("Requested")}: ${detail.requested_version} ${c.gray(`(current: ${detail.current_version})`)}`
@@ -4613,10 +4714,135 @@ function deleteCommand() {
   });
 }
 
-// src/commands/list.ts
+// src/commands/yank.ts
 import { Command as Command13 } from "commander";
+import prompts3 from "prompts";
+function yankCommand() {
+  return new Command13("yank").description("soft-mark a specific version of your package as yanked").argument(
+    "<full_slug>",
+    'package identifier with explicit version, e.g. "user/slug@1.2.3"'
+  ).option("--reason <text>", "optional reason shown to consumers (\u2264280 chars)").option("--force", "skip the confirmation prompt").action(
+    async (fullSlugArg, opts) => {
+      const parsed = parseSlugAtVersion(fullSlugArg);
+      if (!parsed.version) {
+        throw new Error(
+          'yank requires an explicit version pin \u2014 use the form "user/slug@1.2.3" (range syntax not allowed)'
+        );
+      }
+      const bundle = await useClient();
+      const detail = await bundle.api.getPackage(parsed.username, parsed.slug);
+      if (!opts.force) {
+        printHuman(c.yellow("  \u26A0  You are about to yank:"));
+        printHuman(
+          `     ${c.bold(detail.full_slug)}  v${parsed.version}`
+        );
+        if (opts.reason) {
+          printHuman(`     reason: ${opts.reason}`);
+        }
+        printHuman(
+          c.gray(
+            "  Yanked versions disappear from range/`*` resolution. Pinned installs (`@" + parsed.version + "`) still work. Reversible with `kordis unyank`."
+          )
+        );
+        printHuman("");
+        const { confirmed } = await prompts3({
+          type: "confirm",
+          name: "confirmed",
+          message: `Yank ${c.bold(`${parsed.fullSlug}@${parsed.version}`)}?`,
+          initial: false
+        });
+        if (!confirmed) {
+          printHuman(c.gray("Aborted."));
+          process.exit(0);
+        }
+      }
+      const res = await bundle.authedRequest(
+        (api) => api.yankVersion(parsed.username, parsed.slug, parsed.version, {
+          ...opts.reason ? { reason: opts.reason } : {}
+        })
+      );
+      printDual({
+        json: res,
+        human: () => {
+          printHuman(
+            c.green(
+              `\u2713 Yanked ${c.bold(parsed.fullSlug)}@${parsed.version}`
+            )
+          );
+          if (res.yank_reason) {
+            printHuman(c.gray(`  reason: ${res.yank_reason}`));
+          }
+          if (res.effective_current_version !== parsed.version) {
+            printHuman(
+              c.gray(
+                `  current_version is now ${c.bold(res.effective_current_version)} (was ${parsed.version})`
+              )
+            );
+          } else {
+            printHuman(
+              c.gray(
+                `  current_version unchanged at ${c.bold(res.effective_current_version)} (no higher non-yanked version exists)`
+              )
+            );
+          }
+          printHuman(
+            c.gray(
+              `  \u2192 Reverse with: kordis unyank ${parsed.fullSlug}@${parsed.version}`
+            )
+          );
+        }
+      });
+    }
+  );
+}
+
+// src/commands/unyank.ts
+import { Command as Command14 } from "commander";
+function unyankCommand() {
+  return new Command14("unyank").description("reverse a yank on a specific version").argument(
+    "<full_slug>",
+    'package identifier with explicit version, e.g. "user/slug@1.2.3"'
+  ).action(async (fullSlugArg) => {
+    const parsed = parseSlugAtVersion(fullSlugArg);
+    if (!parsed.version) {
+      throw new Error(
+        'unyank requires an explicit version pin \u2014 use "user/slug@1.2.3"'
+      );
+    }
+    const bundle = await useClient();
+    const res = await bundle.authedRequest(
+      (api) => api.unyankVersion(parsed.username, parsed.slug, parsed.version)
+    );
+    printDual({
+      json: res,
+      human: () => {
+        printHuman(
+          c.green(
+            `\u2713 Unyanked ${c.bold(parsed.fullSlug)}@${parsed.version}`
+          )
+        );
+        if (res.effective_current_version !== parsed.version) {
+          printHuman(
+            c.gray(
+              `  current_version is ${c.bold(res.effective_current_version)} (highest non-yanked)`
+            )
+          );
+        } else {
+          printHuman(
+            c.gray(
+              `  current_version is now ${c.bold(res.effective_current_version)}`
+            )
+          );
+        }
+      }
+    });
+  });
+}
+
+// src/commands/list.ts
+import { Command as Command15 } from "commander";
 function listCommand() {
-  return new Command13("list").description("list packages \u2014 your own (no arg) or a public user\u2019s (with <username>)").argument("[username]", "kordis username to list (omit for self)").option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "self-mode page number (1-based)", (v) => parseInt(v, 10), 1).option("--cursor <token>", "public-mode pagination cursor").option("--sort <mode>", "sort: latest|popular (self) or stars|downloads|recent|updated (public)", "latest").action(async (rawUsername, opts) => {
+  return new Command15("list").description("list packages \u2014 your own (no arg) or a public user\u2019s (with <username>)").argument("[username]", "kordis username to list (omit for self)").option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "self-mode page number (1-based)", (v) => parseInt(v, 10), 1).option("--cursor <token>", "public-mode pagination cursor").option("--sort <mode>", "sort: latest|popular (self) or stars|downloads|recent|updated (public)", "latest").action(async (rawUsername, opts) => {
     const bundle = await useClient();
     if (rawUsername === void 0) {
       requireAuth(bundle);
@@ -4687,9 +4913,9 @@ function listCommand() {
 }
 
 // src/commands/versions.ts
-import { Command as Command14 } from "commander";
+import { Command as Command16 } from "commander";
 function versionsCommand() {
-  return new Command14("versions").description("list all versions of a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (fullSlug) => {
+  return new Command16("versions").description("list all versions of a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (fullSlug) => {
     const [username, slug] = fullSlug.split("/");
     if (!username || !slug) {
       throw new Error('full_slug must be "{username}/{slug}"');
@@ -4706,12 +4932,17 @@ function versionsCommand() {
         );
         printHuman("");
         for (const v of res.versions) {
-          const statusColor = v.review_status === "passed" ? c.green(v.review_status) : v.review_status === "rejected" ? c.red(v.review_status) : c.yellow(v.review_status);
+          const isYanked = Boolean(v.yanked_at);
+          const reviewLabel = isYanked ? c.gray(`${v.review_status} (yanked)`) : v.review_status === "passed" ? c.green(v.review_status) : v.review_status === "rejected" ? c.red(v.review_status) : c.yellow(v.review_status);
           const age = relativeTime(v.published_at);
           const isCurrent = v.version === res.current_version;
+          const versionLabel = isYanked ? c.gray(v.version) : c.bold(v.version);
           printHuman(
-            `  ${c.bold(v.version)}${isCurrent ? c.cyan(" (current)") : ""}  ${statusColor}  ${c.gray(age)}`
+            `  ${versionLabel}${isCurrent ? c.cyan(" (current)") : ""}  ${reviewLabel}  ${c.gray(age)}`
           );
+          if (isYanked && v.yank_reason) {
+            printHuman(`    ${c.gray(`reason: ${v.yank_reason}`)}`);
+          }
         }
       }
     });
@@ -4743,13 +4974,13 @@ function relativeTime(isoString) {
 }
 
 // src/commands/outdated.ts
-import { Command as Command15 } from "commander";
+import { Command as Command17 } from "commander";
 import semver from "semver";
 function effectiveRange(entry) {
   return entry.requestedRange ?? `^${entry.version}`;
 }
 function outdatedCommand() {
-  return new Command15("outdated").description("check installed packages for available updates").action(async () => {
+  return new Command17("outdated").description("check installed packages for available updates").action(async () => {
     const lf = await readLockfile();
     const slugs = Object.keys(lf.packages);
     if (slugs.length === 0) {
@@ -4847,13 +5078,13 @@ function outdatedCommand() {
 }
 
 // src/commands/update.ts
-import { Command as Command16 } from "commander";
+import { Command as Command18 } from "commander";
 import semver2 from "semver";
 function effectiveRange2(entry) {
   return entry.requestedRange ?? `^${entry.version}`;
 }
 function updateCommand() {
-  return new Command16("update").description("update installed packages to their latest versions").argument("[full_slug]", "package identifier {username}/{slug} (omit to update all)").option("--dry-run", "show what would be updated without doing it", false).action(async (fullSlugArg, opts) => {
+  return new Command18("update").description("update installed packages to their latest versions").argument("[full_slug]", "package identifier {username}/{slug} (omit to update all)").option("--dry-run", "show what would be updated without doing it", false).action(async (fullSlugArg, opts) => {
     const lf = await readLockfile();
     let slugs = Object.keys(lf.packages);
     if (slugs.length === 0) {
@@ -4987,9 +5218,9 @@ function updateCommand() {
 }
 
 // src/commands/diff.ts
-import { Command as Command17 } from "commander";
+import { Command as Command19 } from "commander";
 function diffCommand() {
-  return new Command17("diff").description("show changes between two versions of a package").argument("<full_slug>", "package identifier: {username}/{slug}, or {username}/{slug}@{from}..{to}").argument("[from]", "older version (omit to use second-latest)").argument("[to]", "newer version (omit to use latest)").action(async (fullSlugArg, fromArg, toArg) => {
+  return new Command19("diff").description("show changes between two versions of a package").argument("<full_slug>", "package identifier: {username}/{slug}, or {username}/{slug}@{from}..{to}").argument("[from]", "older version (omit to use second-latest)").argument("[to]", "newer version (omit to use latest)").action(async (fullSlugArg, fromArg, toArg) => {
     let fullSlug = fullSlugArg;
     let from = fromArg;
     let to = toArg;
@@ -5060,13 +5291,13 @@ function diffCommand() {
 }
 
 // src/commands/recommend.ts
-import { Command as Command18 } from "commander";
-import prompts3 from "prompts";
+import { Command as Command20 } from "commander";
+import prompts4 from "prompts";
 function recommendCommand() {
-  return new Command18("recommend").description("show personalized package recommendations").option("--limit <n>", "max items to return (1-50)", (v) => parseInt(v, 10), 10).option("--verbose", "include score_breakdown per item", false).option("--no-context", "skip the X-Kordis-Context header for this call").action(async (opts) => {
+  return new Command20("recommend").description("show personalized package recommendations").option("--limit <n>", "max items to return (1-50)", (v) => parseInt(v, 10), 10).option("--verbose", "include score_breakdown per item", false).option("--no-context", "skip the X-Kordis-Context header for this call").action(async (opts) => {
     const cfg = await loadCliConfig();
     if (cfg.personalization === "undecided" && process.stdin.isTTY && !isJsonMode() && opts.context !== false) {
-      const { enable } = await prompts3({
+      const { enable } = await prompts4({
         type: "confirm",
         name: "enable",
         message: "Personalize recommendations using anonymous local signals (installed agent tools, language stats, frameworks)? Server never stores them \u2014 only re-ranks results in-flight.",
@@ -5171,9 +5402,9 @@ function renderItem(idx, it, verbose) {
 }
 
 // src/commands/profile.ts
-import { Command as Command19 } from "commander";
+import { Command as Command21 } from "commander";
 function profileCommand() {
-  return new Command19("profile").description("inspect a user\u2019s public profile").argument("<username>", "kordis username").action(async (raw) => {
+  return new Command21("profile").description("inspect a user\u2019s public profile").argument("<username>", "kordis username").action(async (raw) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     const profile = await bundle.api.getUserProfile(username);
@@ -5208,9 +5439,9 @@ function profileCommand() {
 }
 
 // src/commands/stars.ts
-import { Command as Command20 } from "commander";
+import { Command as Command22 } from "commander";
 function starsCommand() {
-  return new Command20("stars").description("list packages a user has starred").argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
+  return new Command22("stars").description("list packages a user has starred").argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     const res = await bundle.api.listUserStars(username, {
@@ -5242,9 +5473,9 @@ function starsCommand() {
 }
 
 // src/commands/follow.ts
-import { Command as Command21 } from "commander";
+import { Command as Command23 } from "commander";
 function followCommand() {
-  return new Command21("follow").description("follow a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+  return new Command23("follow").description("follow a kordis user").argument("<username>", "kordis username").action(async (raw) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     requireAuth(bundle);
@@ -5259,7 +5490,7 @@ function followCommand() {
   });
 }
 function unfollowCommand() {
-  return new Command21("unfollow").description("stop following a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+  return new Command23("unfollow").description("stop following a kordis user").argument("<username>", "kordis username").action(async (raw) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     requireAuth(bundle);
@@ -5275,9 +5506,9 @@ function unfollowCommand() {
 }
 
 // src/commands/followers.ts
-import { Command as Command22 } from "commander";
+import { Command as Command24 } from "commander";
 function makeListing(name) {
-  return new Command22(name).description(
+  return new Command24(name).description(
     name === "followers" ? "list users following <username>" : "list users that <username> follows"
   ).argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
     const username = parseUsername(raw);
@@ -5322,7 +5553,7 @@ function followingCommand() {
 
 // src/index.ts
 function buildProgram() {
-  const program = new Command23("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
+  const program = new Command25("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     if (opts.json) setJsonMode(true);
   }).addHelpText("after", `
@@ -5355,6 +5586,8 @@ Environment variables (see README.md "Privacy & environment variables"):
   program.addCommand(followersCommand());
   program.addCommand(followingCommand());
   program.addCommand(deleteCommand());
+  program.addCommand(yankCommand());
+  program.addCommand(unyankCommand());
   program.addCommand(listCommand());
   program.addCommand(versionsCommand());
   program.addCommand(outdatedCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",