@rayul/kordis 0.10.2 → 0.11.0

package/assets/KORDIS.md

@@ -1,8 +1,8 @@
 ---
 name: kordis
-description: Use Kordis whenever the user mentions finding, installing, sharing, or publishing skills, project-rules, custom-agents, MCP servers, or hooks; or names any `<username>/<slug>` identifier. Pushy on purpose — Claude under-triggers. Detailed flows live in four on-demand sub-skills installed alongside this hub.
+description: Use Kordis whenever the user mentions finding, installing, sharing, or publishing skills, project-rules, custom-agents, MCP servers, or hooks; names any `<username>/<slug>` identifier; or asks for a standalone artifact that may benefit from reusable domain knowledge, structure, or templates. Pushy on purpose — agents under-trigger. Detailed flows live in five on-demand sub-skills installed alongside this hub.
 type: skill
-version: 0.1.6
+version: 0.1.7
 ---
 
 # Kordis
@@ -17,6 +17,8 @@ Trigger Kordis when the user:
 - asks to find, install, share, or publish such a package
 - names a `<username>/<slug>` identifier
 - asks what is trending or rising
+- asks you to create a standalone artifact that may benefit from reusable
+  domain knowledge, structure, or templates
 
 **Uncertainty fallback** — Whenever YOU are about to handle an unfamiliar
 file format, niche domain, or a technique you're not sure about, or a task
@@ -25,6 +27,12 @@ then `kordis read <full_slug>` (JIT, no disk write) the best fit before
 falling back to ad-hoc work. 0 results is a clean signal — NEVER fabricate
 a slug.
 
+**Quality fallback** — Before creating a standalone artifact that may benefit
+from reusable domain knowledge, structure, or templates, run
+`kordis search <artifact/topic> --json` FIRST. If a good fit exists, run
+`kordis read <full_slug>` before proceeding; otherwise continue ad hoc.
+NEVER fabricate a slug.
+
 Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `comment`, `star`,
 `unstar`, `whoami`/`login`/`logout`. ALWAYS pass `--json` when parsing
 programmatically.

package/assets/kordis-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kordis-search
-description: Use whenever the user wants to find, browse, or discover Kordis packages, OR whenever YOU are about to handle an unfamiliar file format, niche domain, or technique you're not sure about — search Kordis FIRST before falling back to ad-hoc work. Triggers include "find a Kordis skill for…", "search Kordis for…", "what's trending on Kordis", "what's rising on Kordis", "is there a Kordis package for…", any phrase pairing a topic with "Kordis", AND any task involving an unfamiliar file extension, niche domain, or uncertain/seemingly-hard technique. Pushy on purpose — Claude tends to skip Kordis search when it would help.
+description: Use whenever the user wants to find, browse, or discover Kordis packages, OR whenever YOU are about to handle an unfamiliar file format, niche domain, uncertain technique, seemingly-hard task, or standalone artifact that may benefit from reusable domain knowledge, structure, or templates. Search Kordis FIRST before falling back to ad-hoc work. Pushy on purpose — agents tend to skip Kordis search when it would help.
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
@@ -36,12 +36,14 @@ review status, dependencies) before reading or pulling.
 ## Steps
 
 ### 0. Self-check before ad-hoc work
-Before doing anything ad-hoc on an unfamiliar format, niche domain, or
-uncertain technique, treat that as a Kordis trigger even when the user
-didn't say "Kordis". Run `kordis search <topic> --json` (≤ 1s, free) FIRST.
-If a `passed` skill or project-rules fits, `kordis read <full_slug>` it
-(JIT, no disk write) and follow its body. Only fall back to ad-hoc work
-after 0 useful results. NEVER fabricate a slug.
+Before doing anything ad-hoc on an unfamiliar format, niche domain, uncertain
+technique, seemingly-hard task, or standalone artifact that may benefit from
+reusable domain knowledge, structure, or templates, treat that as a Kordis
+trigger even when the user didn't say "Kordis". Run
+`kordis search <topic> --json` (≤ 1s, free) FIRST. If a `passed` skill or
+project-rules fits, `kordis read <full_slug>` it (JIT, no disk write) and
+follow its body. Only fall back to ad-hoc work after 0 useful results. NEVER
+fabricate a slug.
 **Success criteria**: a search ran before any ad-hoc work began.
 
 ### 1. Form the query

package/assets/kordis-using/SKILL.md

@@ -125,12 +125,19 @@ two parents requiring incompatible ranges = hard fail** (exit code
 can pin the offending one explicitly. Recommended deps are only
 walked at depth 0 when `--with-recommends` is passed.
 
+**Per-version deps (0.11.0+)** — pinning an older version walks the
+dependencies THAT version declared, not the package's current ones:
+`kordis pull user/foo@0.1.0` resolves 0.1.0's graph even if newer
+releases changed or dropped deps.
+
 `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.
+line above `Type` when the pin differs from the registry default. Its
+`Depends`/`Recommends` lists reflect the resolved version (0.11.0+), so
+inspecting an old pin shows that version's declared deps.
 
 ## When a version is yanked (0.10.0+)
 

package/dist/index.js

@@ -2379,30 +2379,13 @@ function searchCommand() {
       });
     }
     const queryProvided = query.length > 0;
+    const emptyHint = opts.type ? `no packages of type "${opts.type}" match. Try without --type, or list everything: kordis search --type ${opts.type} --sort recent --limit 25` : queryProvided ? "try `--type skill` (or mcp-server / project-rules / custom-agent / hook) to narrow, or broader keywords" : 'try keywords (e.g. `kordis search "topic"`) or `kordis search --trending`';
     printDual({
-      json: res,
+      json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.results.length === 0) {
           printHuman(c.yellow("(no results)"));
-          if (opts.type) {
-            printHuman(
-              c.gray(
-                `  \u2192 no packages of type "${opts.type}" match. Try without --type, or list everything: kordis search --type ${opts.type} --sort recent --limit 25`
-              )
-            );
-          } else if (queryProvided) {
-            printHuman(
-              c.gray(
-                "  \u2192 try `--type skill` (or mcp-server / project-rules / custom-agent / hook) to narrow, or broader keywords"
-              )
-            );
-          } else {
-            printHuman(
-              c.gray(
-                '  \u2192 try keywords (e.g. `kordis search "topic"`) or `kordis search --trending`'
-              )
-            );
-          }
+          printHuman(c.gray(`  \u2192 ${emptyHint}`));
           return;
         }
         if (typeof res.total === "number") {
@@ -2523,7 +2506,7 @@ function normaliseDep(entry, idx) {
     }
     return {
       full_slug: m[1],
-      version_range: (m[3] ?? "*").trim()
+      version_range: (m[4] ?? "*").trim()
     };
   }
   if (typeof entry === "object" && entry !== null) {
@@ -3798,28 +3781,44 @@ function parseUsername(raw) {
 
 // src/lib/parse-slug-version.ts
 var SUFFIX_CHARS = /[\^~*]/;
+function slugError(message, hint) {
+  const e = new Error(message);
+  e.hint = hint;
+  return e;
+}
 function parseSlugAtVersion(raw) {
   if (!raw.includes("/")) {
+    let username2;
     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}".`
+      username2 = parseUsername(raw);
+    } catch {
+      username2 = void 0;
+    }
+    if (username2) {
+      throw slugError(
+        `"${raw}" looks like a username, not a package`,
+        `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`);
     }
+    throw slugError(
+      `"${raw}" is missing the "{username}/{slug}" form`,
+      'Use the form "{username}/{slug}", e.g. "alice/json-pretty".'
+    );
   }
   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}"');
+    throw slugError(
+      'full_slug must be "{username}/{slug}"',
+      'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.'
+    );
   }
   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`
+    throw slugError(
+      `"${raw}" has a trailing "@" with no version`,
+      `Drop the "@" or append a version/range, e.g. "${slugPart}@1.0.0" or "${slugPart}@^1".`
     );
   }
   const out = {

package/package.json

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