@rayul/kordis 0.8.1 → 0.9.1

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>". Covers dry-run flow, frontmatter requirements, version bump strategies, 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", "버전 올리기". Covers dry-run flow, frontmatter requirements, version bump strategies, semver rules, and the AI review pipeline.
 type: skill
 allowed-tools: ["Bash(kordis:*)", "Read", "Edit"]
 ---
@@ -107,6 +107,31 @@ non-patch update.
 four to the user. If `status: "pending"`, the AI reviewer hasn't decided
 yet — re-check with `kordis info <full_slug> --json` (or wait and re-run
 `kordis info`); the `pending` page is not yet served on the public URL.
+
+## Versioning your push (0.9.0+)
+
+- **First publish** derives the version from the frontmatter `version:`
+  field if present, else defaults to `0.1.0`. Passing `--bump` on a
+  first publish now returns a clear `usage_error` (pre-0.9 silently
+  ignored it) — drop `--bump` or set the frontmatter version explicitly.
+- **Subsequent pushes** default to `--bump patch`. Explicit
+  `--bump minor` or `--bump major` ships the matching jump.
+- **Frontmatter `version:` on an update** must match the result of
+  the bump strategy, else the server rejects with `usage_error` naming
+  both values. Easier to drop the frontmatter version once a package is
+  published and let `--bump` drive it.
+- **Prereleases** (`1.0.0-beta.1`) ship via frontmatter on first publish
+  or via an explicit prerelease push. `--bump` strips prerelease
+  suffixes; `current_version` never gets set to a prerelease via bump,
+  so installers on a bare `kordis pull <slug>` skip prereleases by
+  default. Consumers who want a prerelease pin explicitly:
+  `kordis pull <slug>@1.0.0-beta.1`.
+- **AI review runs per-version** — every push enters the review queue
+  even if a prior version was already passed. Re-pushed packages can
+  legitimately fail review if new content trips a Stage-1 rule.
+
+`kordis versions <slug>` lists everything ever published, with each
+row's `review_status` so consumers know which versions are pull-safe.
 If `status: "rejected"`, surface `review.flags` to the user and DO NOT
 silently retry — explain why.
 

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…". Covers JIT read vs pull, the five Kordis package types, dependencies, version pinning, 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". Covers JIT read vs pull, the five Kordis package types, dependencies, version pinning, range syntax, and attribution. Load eagerly when in doubt.
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
@@ -42,14 +42,15 @@ immediately (e.g. to verify a package you just pushed), use `pull` with
 Returns the full body (Markdown) of a text-bearing package, plus an
 `attribution` string. `--pin <semver>` overrides any `@suffix` on the slug.
 
-### `kordis pull <full_slug>[@<version>] [options]`
+### `kordis pull <full_slug>[@<version|range>] [options]`
 Writes files into the current project.
 
-| flag                  | meaning                                              |
-| --------------------- | ---------------------------------------------------- |
-| `--tool <name>`       | force a target tool format (default: auto-detect)    |
-| `--target <path>`     | install into a sub-directory (default: cwd)          |
-| `--with-recommends`   | also install recommended dependencies                |
+| flag                       | meaning                                                       |
+| -------------------------- | ------------------------------------------------------------- |
+| `--tool <name>`            | force a target tool format (default: auto-detect)             |
+| `--target <path>`          | install into a sub-directory (default: cwd)                   |
+| `--with-recommends`        | also install depth-0 recommended dependencies (0.9.0+)        |
+| `--no-with-required`       | skip transitive required deps (advanced; default installs)    |
 
 IMPORTANT: `pull` **fails fast** when the target tool can't be inferred from
 the cwd (no `.claude/`, `.codex/`, `.cursor/`, `AGENTS.md`, `CLAUDE.md`,
@@ -97,6 +98,39 @@ machine.
 - IMPORTANT: hooks execute arbitrary code. EXPLAIN in plain words what the
   hook does, and confirm with the user BEFORE pulling.
 
+## Pinning versions and ranges (0.9.0+)
+
+Append `@<version|range>` to a slug on `kordis pull`, `kordis read`,
+`kordis info` (and check what's available with `kordis versions`).
+Supported forms:
+
+| input                              | meaning                                                          |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `user/foo` (no @)                  | latest `current_version` (server's bumped default)               |
+| `user/foo@1.2.3`                   | exact version                                                    |
+| `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@*`                       | alias for `current_version`                                      |
+
+Comparator strings (`>=1 <2`, `||`) are NOT supported in 0.9.x —
+server returns `usage_error` with the accepted-forms list. Deferred to
+0.10.x if demand emerges.
+
+`kordis pull` walks transitive `required` deps by default — each child
+is resolved against the range its parent declared. **Conflict between
+two parents requiring incompatible ranges = hard fail** (exit code
+35 `dependency_conflict`); the CLI prints the conflict chain so users
+can pin the offending one explicitly. Recommended deps are only
+walked at depth 0 when `--with-recommends` is passed.
+
+`kordis read @range` resolves to a concrete version (the stderr footer
+shows it: `… @1.4.2 (resolved @^1 → 1.4.2)`) but does NOT walk
+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.
+
 ## 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

@@ -143,6 +143,13 @@ var init_errors = __esm({
        */
       "jit_blocked",
       // 33
+      /**
+       * dependency_conflict — `kordis pull` resolver hit two incompatible
+       * version ranges in the install plan. Server returns the conflict
+       * chain via `flags`; CLI exits 35.
+       */
+      "dependency_conflict",
+      // 35
       "conflict",
       // 40 (slug taken, version exists)
       "filesystem_error",
@@ -160,6 +167,7 @@ var init_errors = __esm({
       rate_limited: 31,
       ai_review_rejected: 32,
       jit_blocked: 33,
+      dependency_conflict: 35,
       conflict: 40,
       filesystem_error: 50,
       not_found: 1,
@@ -320,7 +328,13 @@ var init_package = __esm({
       depends: z6.array(DependencySpecSchema),
       recommends: z6.array(DependencySpecSchema),
       categories: z6.array(z6.string()).optional().default([]),
-      verified_by_kordis: z6.boolean()
+      verified_by_kordis: z6.boolean(),
+      /**
+       * 0.9.0+ — when the caller pinned a `@version` or `@range`, the
+       * concrete resolved version. Absent for bare-slug calls (where the
+       * response reflects `current_version`).
+       */
+      requested_version: SemverSchema.optional()
     });
     PackageVersionSchema = z6.object({
       id: UuidSchema,
@@ -486,7 +500,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, PullPackageResponseSchema, 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, 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";
@@ -652,6 +666,25 @@ var init_api = __esm({
        */
       bundled_assets: z9.array(z9.string()).optional()
     });
+    PullPackageRequestSchema = z9.object({
+      /**
+       * Exact version (`"1.2.3"`) or range (`"^1.2"`, `"~1.2"`, `"*"`). When
+       * absent the resolver returns `current_version`. Unsupported syntax
+       * (`">="`, `"<"`, `"||"`) is rejected with usage_error.
+       */
+      version: SemverRangeSchema.optional(),
+      /**
+       * Walk `required` deps transitively (DFS, conflict = hard-fail, max
+       * depth 8). Default true — matches the user expectation that "install
+       * X" means everything X needs to function.
+       */
+      with_required: z9.boolean().optional().default(true),
+      /**
+       * Walk depth-0 `recommended` deps (transitive recommends NOT followed).
+       * Default false — opt-in noise.
+       */
+      with_recommends: z9.boolean().optional().default(false)
+    });
     PullPackageResponseSchema = z9.object({
       status: z9.enum(["installed", "already_installed", "skipped"]),
       full_slug: FullSlugSchema,
@@ -665,7 +698,11 @@ var init_api = __esm({
             full_slug: FullSlugSchema,
             version: SemverSchema,
             status: z9.enum(["installed", "already_installed", "skipped", "failed"]),
-            paths: z9.array(z9.string()).optional()
+            paths: z9.array(z9.string()).optional(),
+            /** 0.9.0+ — range the parent asked for, e.g. `"^1.2"`. */
+            requested_range: SemverRangeSchema.optional(),
+            /** 0.9.0+ — which package required this one (null for root). */
+            requested_by: FullSlugSchema.nullable().optional()
           })
         ),
         recommended: z9.array(
@@ -673,12 +710,27 @@ var init_api = __esm({
             full_slug: FullSlugSchema,
             version: SemverSchema,
             status: z9.enum(["installed", "skipped"]),
-            paths: z9.array(z9.string()).optional()
+            paths: z9.array(z9.string()).optional(),
+            requested_range: SemverRangeSchema.optional(),
+            requested_by: FullSlugSchema.nullable().optional()
           })
         )
       }),
       recommends_hint: z9.string().nullable()
     });
+    ResolveVersionQuerySchema = z9.object({
+      range: SemverRangeSchema
+    });
+    ResolveVersionResponseSchema = z9.object({
+      full_slug: FullSlugSchema,
+      requested_range: SemverRangeSchema,
+      resolved_version: SemverSchema,
+      current_version: SemverSchema,
+      is_prerelease: z9.boolean()
+    });
+    GetPackageQuerySchema = z9.object({
+      version: SemverRangeSchema.optional()
+    });
     ListVersionsResponseSchema = z9.object({
       full_slug: FullSlugSchema,
       current_version: SemverSchema,
@@ -1135,8 +1187,10 @@ var init_client = __esm({
           body
         });
       }
-      getPackage(username, slug) {
-        return this.request(`/api/packages/${username}/${slug}`);
+      getPackage(username, slug, opts = {}) {
+        return this.request(`/api/packages/${username}/${slug}`, {
+          query: opts
+        });
       }
       deletePackage(username, slug) {
         return this.request(`/api/packages/${username}/${slug}`, { method: "DELETE" });
@@ -1147,10 +1201,20 @@ var init_client = __esm({
           { query: opts }
         );
       }
-      pull(username, slug) {
+      /**
+       * 0.9.0+ — resolve a range to a concrete version without committing
+       * to a pull. Used by `kordis info @range` and `kordis read @range`.
+       */
+      resolveVersion(username, slug, range) {
+        return this.request(
+          `/api/packages/${username}/${slug}/resolve`,
+          { query: { range } }
+        );
+      }
+      pull(username, slug, opts = {}) {
         return this.request(
           `/api/packages/${username}/${slug}/pull`,
-          { method: "POST" }
+          { method: "POST", body: opts }
         );
       }
       /**
@@ -2904,6 +2968,22 @@ function pushCommand() {
         throw err instanceof Error ? err : new Error(String(err));
       }
       if (opts.dryRun) {
+        const explicitBump = opts.bump && opts.bump !== "patch" ? opts.bump : null;
+        if (explicitBump && nameFromFm) {
+          const slugForCheck = opts.slug?.includes("/") ? opts.slug.split("/", 2) : bundle.username ? [bundle.username, opts.slug ?? nameFromFm] : null;
+          if (slugForCheck && slugForCheck[0] && slugForCheck[1]) {
+            const [u, s2] = slugForCheck;
+            try {
+              await bundle.api.getPackage(u, s2);
+            } catch (err) {
+              if (err && typeof err === "object" && "code" in err && err.code === "not_found") {
+                throw new Error(
+                  `--bump ${explicitBump} cannot apply to a first publish (no existing version to bump from). First publish derives version from frontmatter \`version:\` or defaults to "0.1.0". Drop --bump (or set frontmatter version explicitly), then re-run.`
+                );
+              }
+            }
+          }
+        }
         await runDryRun({ content, assets });
         return;
       }
@@ -3599,6 +3679,11 @@ function kordisHome2() {
 function lockfilePath() {
   return join8(kordisHome2(), "installed.json");
 }
+function lockfileDisplayPath() {
+  const path2 = lockfilePath();
+  const home = process.env["HOME"];
+  return home && path2.startsWith(home) ? "~" + path2.slice(home.length) : path2;
+}
 async function readLockfile() {
   try {
     const raw = await readFile7(lockfilePath(), "utf8");
@@ -3617,16 +3702,80 @@ async function recordInstalled(fullSlug, entry) {
   await writeLockfile(lf);
 }
 
+// src/lib/parse-username.ts
+init_src();
+var SORT_KEYWORDS = ["latest", "popular", "recent", "updated", "stars", "downloads"];
+function parseUsername(raw) {
+  if (SORT_KEYWORDS.includes(raw.toLowerCase())) {
+    throw new Error(
+      `"${raw}" is a sort keyword \u2014 did you mean \`--sort ${raw}\`? Username arguments must follow the Kordis username shape (lowercase alphanumeric, hyphens allowed).`
+    );
+  }
+  const parsed = UsernameSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(
+      `invalid username "${raw}" \u2014 must be 3-32 chars, lowercase alphanumeric with single hyphens (e.g. "alice", "my-team")`
+    );
+  }
+  return parsed.data;
+}
+
+// src/lib/parse-slug-version.ts
+var SUFFIX_CHARS = /[\^~*]/;
+function parseSlugAtVersion(raw) {
+  if (!raw.includes("/")) {
+    try {
+      const username2 = parseUsername(raw);
+      throw new Error(
+        `"${raw}" looks like a username, not a package \u2014 try \`kordis profile ${username2}\` for user details, or pass a full slug like "{username}/{slug}".`
+      );
+    } catch (err) {
+      if (err instanceof Error) throw err;
+      throw new Error(`"${raw}" is missing the "{username}/{slug}" form`);
+    }
+  }
+  const atIdx = raw.indexOf("@");
+  const slugPart = atIdx === -1 ? raw : raw.slice(0, atIdx);
+  const versionPart = atIdx === -1 ? "" : raw.slice(atIdx + 1);
+  const [username, slug] = slugPart.split("/");
+  if (!username || !slug) {
+    throw new Error('full_slug must be "{username}/{slug}"');
+  }
+  if (atIdx !== -1 && versionPart.length === 0) {
+    throw new Error(
+      `"${raw}" has a trailing "@" with no version \u2014 drop the "@" or pass a version/range after it`
+    );
+  }
+  const out = {
+    fullSlug: slugPart,
+    username,
+    slug
+  };
+  if (versionPart.length > 0) {
+    if (SUFFIX_CHARS.test(versionPart)) {
+      out.range = versionPart;
+    } else {
+      out.version = versionPart;
+    }
+  }
+  return out;
+}
+
 // src/commands/pull.ts
-async function doPullInstall(fullSlug, tool, installRoot, version) {
+async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
   const [username, slug] = fullSlug.split("/");
   if (!username || !slug) throw new Error('full_slug must be "{username}/{slug}"');
   const bundle = await useClient();
-  const detail = await bundle.api.getPackage(username, slug);
-  await bundle.api.pull(username, slug);
+  const pullRes = await bundle.api.pull(username, slug, {
+    ...opts.version ? { version: opts.version } : {},
+    ...opts.withRequired !== void 0 ? { with_required: opts.withRequired } : {},
+    ...opts.withRecommends !== void 0 ? { with_recommends: opts.withRecommends } : {}
+  });
   const contentRes = await bundle.api.getContent(username, slug, {
     format: "canonical",
-    ...version ? { version } : {}
+    // Server resolved the range during pull; pass the concrete version
+    // through to /content so we get the exact bytes recorded above.
+    version: pullRes.version
   });
   const parsed = validatePackageSource(contentRes.content);
   if (!parsed.ok || !parsed.type || !parsed.frontmatter) {
@@ -3679,21 +3828,34 @@ async function doPullInstall(fullSlug, tool, installRoot, version) {
     version: installedVersion,
     tool,
     target: installRoot,
-    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...opts.requestedRange ? { requestedRange: opts.requestedRange } : {},
+    ...opts.installedBy ? { installedBy: opts.installedBy } : {}
   });
-  return { version: installedVersion, tool, installRoot, written, notes };
+  return {
+    version: installedVersion,
+    tool,
+    installRoot,
+    written,
+    notes,
+    plan: pullRes.dependencies
+  };
 }
 function pullCommand() {
-  return new Command5("pull").description("install a package into the current project").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--tool <name>", "target tool format (default: auto-detect)").option("--target <path>", "install into a subdirectory (default: cwd)").option("--with-recommends", "also install recommended dependencies", false).action(
+  return new Command5("pull").description("install a package into the current project").argument(
+    "<full_slug>",
+    "package identifier {username}/{slug} or {username}/{slug}@{version|range}"
+  ).option("--tool <name>", "target tool format (default: auto-detect)").option("--target <path>", "install into a subdirectory (default: cwd)").option(
+    "--with-recommends",
+    "also install recommended (depth-0) dependencies",
+    false
+  ).option(
+    "--no-with-required",
+    "skip transitive required dependencies (advanced; default is to install)"
+  ).action(
     async (fullSlugArg, opts) => {
-      const atIdx = fullSlugArg.lastIndexOf("@");
-      const hasPinnedVersion = atIdx > fullSlugArg.indexOf("/");
-      const fullSlug = hasPinnedVersion ? fullSlugArg.slice(0, atIdx) : fullSlugArg;
-      const pinnedVersion = hasPinnedVersion ? fullSlugArg.slice(atIdx + 1) : void 0;
-      const [username, slug] = fullSlug.split("/");
-      if (!username || !slug) {
-        throw new Error('full_slug must be "{username}/{slug}" or "{username}/{slug}@{version}"');
-      }
+      const parsed = parseSlugAtVersion(fullSlugArg);
+      const 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);
@@ -3702,25 +3864,68 @@ function pullCommand() {
           "Cannot detect target tool from the current directory.\n  Pass --tool <name> explicitly. Valid: claude-code, codex, cursor,\n  continue, windsurf, antigravity, copilot.\n  Or run `kordis pull` inside a project that already has one of:\n  .claude/, .codex/, .cursor/, AGENTS.md, CLAUDE.md, .cursorrules,\n  .continue/, .windsurf/, .antigravity/, .github/copilot-instructions.md"
         );
       }
-      const spinLabel = pinnedVersion ? `Pulling ${fullSlug}@${pinnedVersion}` : `Pulling ${fullSlug}`;
-      const spin = spinner(spinLabel);
-      const result = await doPullInstall(fullSlug, detected, installRoot, pinnedVersion);
+      const rootLabel = pin ? `${parsed.fullSlug}@${pin}` : parsed.fullSlug;
+      const spin = spinner(`Pulling ${rootLabel}`);
+      const result = await doPullInstall(parsed.fullSlug, detected, installRoot, {
+        ...pin ? { version: pin } : {},
+        withRequired: opts.withRequired,
+        withRecommends: opts.withRecommends,
+        installedBy: "user",
+        ...pin ? { requestedRange: pin } : {}
+      });
       spin.succeed();
+      const dependencyInstalls = [];
+      const installPlan = [
+        ...result.plan?.required.map((n) => ({ ...n, kind: "required" })) ?? [],
+        ...opts.withRecommends ? result.plan?.recommended.map((n) => ({ ...n, kind: "recommended" })) ?? [] : []
+      ];
+      for (const node of installPlan) {
+        const subSpin = spinner(
+          `  \u21B3 ${node.kind === "required" ? "dep" : "rec"} ${node.full_slug}@${node.version}`
+        );
+        try {
+          const subRes = await doPullInstall(node.full_slug, detected, installRoot, {
+            version: node.version,
+            withRequired: false,
+            withRecommends: false,
+            installedBy: "dependency",
+            ...node.requested_range ? { requestedRange: node.requested_range } : {}
+          });
+          subSpin.succeed();
+          dependencyInstalls.push({ fullSlug: node.full_slug, result: subRes });
+        } catch (err) {
+          subSpin.fail();
+          throw err;
+        }
+      }
       printDual({
         json: {
           status: "installed",
-          full_slug: fullSlug,
+          full_slug: parsed.fullSlug,
           version: result.version,
+          ...pin ? { requested_range: pin } : {},
           tool_detected: result.tool,
           installed_paths: result.written,
-          notes: result.notes
+          notes: result.notes,
+          dependencies: dependencyInstalls.map((d) => ({
+            full_slug: d.fullSlug,
+            version: d.result.version,
+            installed_paths: d.result.written
+          }))
         },
         human: () => {
           printHuman(
-            c.green(`\u2713 Installed ${c.bold(fullSlug)} v${result.version}`)
+            c.green(`\u2713 Installed ${c.bold(parsed.fullSlug)} v${result.version}`)
           );
           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) {
+            printHuman(
+              c.green(`  \u21B3 Installed ${c.bold(dep.fullSlug)} v${dep.result.version}`)
+            );
+            for (const w of dep.result.written) printHuman(`    ${c.gray("wrote")} ${w}`);
+          }
+          printHuman(c.gray(`  lockfile: ${lockfileDisplayPath()}`));
         }
       });
       const reminder = await maybeRenderReminder();
@@ -3765,18 +3970,22 @@ import { Command as Command6 } from "commander";
 function readCommand() {
   return new Command6("read").description("fetch a package body into the agent context (no install)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--pin <semver>", "pin to an exact version (overrides @suffix)").action(
     async (rawSlug, opts) => {
-      const atIdx = rawSlug.lastIndexOf("@");
-      const fullSlug = atIdx > 0 ? rawSlug.slice(0, atIdx) : rawSlug;
-      const inlineVersion = atIdx > 0 ? rawSlug.slice(atIdx + 1) : void 0;
-      const version = opts.pin ?? inlineVersion;
-      const [username, slug] = fullSlug.split("/");
-      if (!username || !slug) {
-        throw new Error('full_slug must be "{username}/{slug}" (optional "@version")');
-      }
+      const parsed = parseSlugAtVersion(rawSlug);
+      const pin = opts.pin ?? parsed.version ?? parsed.range;
       const bundle = await useClient();
-      const res = await bundle.api.jitRead(username, slug, {
+      let resolvedVersion;
+      if (parsed.range && !opts.pin) {
+        const resolved = await bundle.api.resolveVersion(
+          parsed.username,
+          parsed.slug,
+          parsed.range
+        );
+        resolvedVersion = resolved.resolved_version;
+      }
+      const versionForRead = resolvedVersion ?? pin;
+      const res = await bundle.api.jitRead(parsed.username, parsed.slug, {
         allow_pending: opts.allowPending,
-        ...version ? { version } : {}
+        ...versionForRead ? { version: versionForRead } : {}
       });
       if (isJsonMode()) {
         printJson(res);
@@ -3795,8 +4004,9 @@ function readCommand() {
 `);
         }
       }
+      const resolvedNote = parsed.range && resolvedVersion ? ` ${c.gray("(resolved")} ${c.gray("@" + parsed.range)} ${c.gray("\u2192")} ${resolvedVersion}${c.gray(")")}` : "";
       process.stderr.write(
-        `${c.gray("\u2014")} ${c.bold(res.full_slug)}${c.gray("@")}${res.version} ${c.gray("\xB7")} ${res.type} (tier ${res.tier}) ${c.gray("\xB7")} ${c.cyan(res.attribution)}
+        `${c.gray("\u2014")} ${c.bold(res.full_slug)}${c.gray("@")}${res.version}${resolvedNote} ${c.gray("\xB7")} ${res.type} (tier ${res.tier}) ${c.gray("\xB7")} ${c.cyan(res.attribution)}
 `
       );
       printHuman("");
@@ -3808,27 +4018,31 @@ function readCommand() {
 init_src();
 import { Command as Command7 } from "commander";
 function infoCommand() {
-  return new Command7("info").description("show details about a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (fullSlug) => {
-    const [username, slug] = fullSlug.split("/");
-    if (!username || !slug) {
-      if (!fullSlug.includes("/")) {
-        throw new Error(
-          `"${fullSlug}" looks like a username, not a package \u2014 try \`kordis profile ${fullSlug}\` for user details, or pass a full slug like "{username}/{slug}".`
-        );
-      }
-      throw new Error('full_slug must be "{username}/{slug}"');
-    }
+  return new Command7("info").description("show details about a package").argument(
+    "<full_slug>",
+    "package identifier {username}/{slug} or {username}/{slug}@{version|range}"
+  ).option("--pin <semver>", "pin to an exact version or range (overrides @suffix)").action(async (fullSlug, opts) => {
+    const parsed = parseSlugAtVersion(fullSlug);
+    const pin = opts.pin ?? parsed.version ?? parsed.range;
     const bundle = await useClient();
-    const detail = await bundle.api.getPackage(username, slug);
+    const detail = await bundle.api.getPackage(parsed.username, parsed.slug, {
+      ...pin ? { version: pin } : {}
+    });
     const typeDefaults = CAPABILITIES_OF_TYPE[detail.type];
     const jitEligible = detail.jit_eligible ?? typeDefaults.jit_eligible;
     const executable = detail.executable ?? typeDefaults.executable;
     printDual({
       json: detail,
       human: () => {
-        printHuman(c.bold(detail.full_slug) + " " + c.gray(`v${detail.current_version}`));
+        const headerVersion = detail.requested_version ?? detail.current_version;
+        printHuman(c.bold(detail.full_slug) + " " + c.gray(`v${headerVersion}`));
         printHuman("  " + detail.description);
         printHuman("");
+        if (detail.requested_version && detail.requested_version !== detail.current_version) {
+          printHuman(
+            `  ${c.cyan("Requested")}: ${detail.requested_version} ${c.gray(`(current: ${detail.current_version})`)}`
+          );
+        }
         printHuman(`  ${c.cyan("Type")}: ${detail.type} (tier ${detail.tier})`);
         printHuman(
           `  ${c.cyan("JIT-readable")}: ${jitEligible ? c.green("yes") : c.red("no")}`
@@ -4396,26 +4610,6 @@ function deleteCommand() {
 
 // src/commands/list.ts
 import { Command as Command13 } from "commander";
-
-// src/lib/parse-username.ts
-init_src();
-var SORT_KEYWORDS = ["latest", "popular", "recent", "updated", "stars", "downloads"];
-function parseUsername(raw) {
-  if (SORT_KEYWORDS.includes(raw.toLowerCase())) {
-    throw new Error(
-      `"${raw}" is a sort keyword \u2014 did you mean \`--sort ${raw}\`? Username arguments must follow the Kordis username shape (lowercase alphanumeric, hyphens allowed).`
-    );
-  }
-  const parsed = UsernameSchema.safeParse(raw);
-  if (!parsed.success) {
-    throw new Error(
-      `invalid username "${raw}" \u2014 must be 3-32 chars, lowercase alphanumeric with single hyphens (e.g. "alice", "my-team")`
-    );
-  }
-  return parsed.data;
-}
-
-// src/commands/list.ts
 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) => {
     const bundle = await useClient();
@@ -4545,16 +4739,9 @@ function relativeTime(isoString) {
 
 // src/commands/outdated.ts
 import { Command as Command15 } from "commander";
-function isNewer(a, b) {
-  const parse = (v) => {
-    const [maj = 0, min = 0, pat = 0] = v.split("-")[0].split(".").map(Number);
-    return [maj, min, pat];
-  };
-  const [aMaj, aMin, aPat] = parse(a);
-  const [bMaj, bMin, bPat] = parse(b);
-  if (bMaj !== aMaj) return bMaj > aMaj;
-  if (bMin !== aMin) return bMin > aMin;
-  return bPat > aPat;
+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 () => {
@@ -4575,13 +4762,37 @@ function outdatedCommand() {
     for (const fullSlug of slugs) {
       const [username, slug] = fullSlug.split("/");
       if (!username || !slug) continue;
-      const installed = lf.packages[fullSlug].version;
+      const entry = lf.packages[fullSlug];
+      const installed = entry.version;
+      const requestedRange = effectiveRange(entry);
       try {
         const detail = await bundle.api.getPackage(username, slug);
         const latest = detail.current_version;
-        entries.push({ full_slug: fullSlug, installed, latest, outdated: isNewer(installed, latest) });
+        let status;
+        if (!semver.gt(latest, installed)) {
+          status = "up_to_date";
+        } else if (semver.satisfies(latest, requestedRange)) {
+          status = "in_range_update";
+        } else {
+          status = "out_of_range";
+        }
+        entries.push({
+          full_slug: fullSlug,
+          installed,
+          latest,
+          requested_range: requestedRange,
+          status,
+          outdated: status !== "up_to_date"
+        });
       } catch {
-        entries.push({ full_slug: fullSlug, installed, latest: installed, outdated: false });
+        entries.push({
+          full_slug: fullSlug,
+          installed,
+          latest: installed,
+          requested_range: requestedRange,
+          status: "up_to_date",
+          outdated: false
+        });
       }
     }
     spin.succeed();
@@ -4603,10 +4814,19 @@ function outdatedCommand() {
         );
         printHuman("");
         for (const e of entries) {
-          const status = e.outdated ? c.yellow("Outdated") : c.green("Up to date");
-          const arrow = e.outdated ? c.yellow(` \u2192 ${e.latest}`) : "";
+          let label;
+          let arrow = "";
+          if (e.status === "up_to_date") {
+            label = c.green("Up to date");
+          } else if (e.status === "in_range_update") {
+            label = c.yellow("Outdated");
+            arrow = c.yellow(` \u2192 ${e.latest}`);
+          } else {
+            label = c.yellow(`Outdated ${c.gray(`(out of range ${e.requested_range})`)}`);
+            arrow = c.yellow(` \u2192 ${e.latest}`);
+          }
           printHuman(
-            `  ${c.bold(e.full_slug)}  ${c.gray(e.installed)}${arrow}  ${status}`
+            `  ${c.bold(e.full_slug)}  ${c.gray(e.installed)}${arrow}  ${label}`
           );
         }
         printHuman("");
@@ -4623,16 +4843,9 @@ function outdatedCommand() {
 
 // src/commands/update.ts
 import { Command as Command16 } from "commander";
-function isNewer2(a, b) {
-  const parse = (v) => {
-    const [maj = 0, min = 0, pat = 0] = v.split("-")[0].split(".").map(Number);
-    return [maj, min, pat];
-  };
-  const [aMaj, aMin, aPat] = parse(a);
-  const [bMaj, bMin, bPat] = parse(b);
-  if (bMaj !== aMaj) return bMaj > aMaj;
-  if (bMin !== aMin) return bMin > aMin;
-  return bPat > aPat;
+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) => {
@@ -4660,15 +4873,18 @@ function updateCommand() {
       const entry = lf.packages[fullSlug];
       const [username, slug] = fullSlug.split("/");
       if (!username || !slug) continue;
+      const requestedRange = effectiveRange2(entry);
       try {
-        const detail = await bundle.api.getPackage(username, slug);
-        if (isNewer2(entry.version, detail.current_version)) {
+        const resolved = await bundle.api.resolveVersion(username, slug, requestedRange);
+        if (semver2.gt(resolved.resolved_version, entry.version)) {
           candidates.push({
             fullSlug,
             installed: entry.version,
-            latest: detail.current_version,
+            target_version: resolved.resolved_version,
+            requestedRange,
             tool: entry.tool,
-            target: entry.target
+            target: entry.target,
+            ...semver2.gt(resolved.current_version, resolved.resolved_version) ? { outOfRangeMajor: resolved.current_version } : {}
           });
         }
       } catch {
@@ -4686,7 +4902,7 @@ function updateCommand() {
       const dryEntries = candidates.map((c2) => ({
         full_slug: c2.fullSlug,
         from: c2.installed,
-        to: c2.latest,
+        to: c2.target_version,
         status: "dry_run"
       }));
       printDual({
@@ -4699,8 +4915,9 @@ function updateCommand() {
           );
           printHuman("");
           for (const cand of candidates) {
+            const tail = cand.outOfRangeMajor ? c.gray(` (registry has ${cand.outOfRangeMajor}, out of range ${cand.requestedRange})`) : "";
             printHuman(
-              `  ${c.bold(cand.fullSlug)}  ${c.gray(cand.installed)} \u2192 ${c.green(cand.latest)}`
+              `  ${c.bold(cand.fullSlug)}  ${c.gray(cand.installed)} \u2192 ${c.green(cand.target_version)}${tail}`
             );
           }
         }
@@ -4709,11 +4926,17 @@ function updateCommand() {
     }
     const summary = [];
     for (const cand of candidates) {
+      const tail = cand.outOfRangeMajor ? c.gray(` (registry has ${cand.outOfRangeMajor}, out of range ${cand.requestedRange})`) : "";
       printHuman(
-        `  ${c.cyan("\u2191")} Updating ${c.bold(cand.fullSlug)} ${c.gray(cand.installed)} \u2192 ${c.green(cand.latest)}`
+        `  ${c.cyan("\u2191")} Updating ${c.bold(cand.fullSlug)} ${c.gray(cand.installed)} \u2192 ${c.green(cand.target_version)}${tail}`
       );
       try {
-        const result = await doPullInstall(cand.fullSlug, cand.tool, cand.target);
+        const result = await doPullInstall(cand.fullSlug, cand.tool, cand.target, {
+          version: cand.target_version,
+          withRequired: false,
+          withRecommends: false,
+          requestedRange: cand.requestedRange
+        });
         summary.push({
           full_slug: cand.fullSlug,
           from: cand.installed,
@@ -4727,7 +4950,7 @@ function updateCommand() {
         summary.push({
           full_slug: cand.fullSlug,
           from: cand.installed,
-          to: cand.latest,
+          to: cand.target_version,
           status: "failed",
           error: message
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "open": "^10.1.0",
     "ora": "^8.1.1",
     "prompts": "^2.4.2",
+    "semver": "^7.6.3",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },
@@ -47,6 +48,7 @@
     "@types/jszip": "^3.4.1",
     "@types/node": "^22.9.0",
     "@types/prompts": "^2.4.9",
+    "@types/semver": "^7.5.8",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3",