@rayul/kordis 0.13.0 → 0.13.1

package/README.md

@@ -2,14 +2,18 @@
 
 > The CLI binary is **`kordis`** — only the npm package name is scoped.
 
-Public registry CLI for agentic-coding packages — skills, project rules, MCP servers, hooks, custom agents.
+Your agent hits something it doesn't know — an unfamiliar format, a niche domain, a technique it's unsure about. Kordis is the registry it checks before improvising.
+
+Run `setup` once and the guide is injected into your agent's global instructions, so from the next session your agent reaches for the registry on its own. It reads what it needs at the moment of need, without writing anything to disk, and installs only when you ask.
+
+The registry carries six package types: **skills**, **project rules**, **MCP servers**, **hooks**, **custom agents**, and **judgment patterns** — reusable decision logic (_how_ an agent should decide) rather than files to install.
 
 ## Quick start
 
 ```bash
 npx @rayul/kordis@latest setup           # one-time: register kordis with Claude Code / Codex / Gemini CLI
-npx @rayul/kordis@latest search sql      # find a skill
-npx @rayul/kordis@latest read rayul/sql-reviewer   # JIT-load into your agent context
+npx @rayul/kordis@latest search sql      # find a package
+npx @rayul/kordis@latest read spaceplayentry/db-sql-code-review   # JIT-load into your agent context
 ```
 
 Or install globally:
@@ -35,18 +39,19 @@ Then re-run the install — no `sudo` needed.
 
 ## Commands
 
-| command                               | purpose                                                                       |
-| ------------------------------------- | ----------------------------------------------------------------------------- |
-| `kordis search <query>`               | search the registry                                                           |
-| `kordis info <slug>`                  | inspect a package                                                             |
-| `kordis read <slug>`                  | JIT-fetch body into agent context (skill / project-rules / custom-agent only) |
-| `kordis pull <slug>`                  | install into the current project (mcp-server / hook)                          |
-| `kordis push <file>`                  | publish a new package or version                                              |
-| `kordis pull <slug>@<version>`        | pin a specific version / range (transitive deps resolved)                     |
-| `kordis yank <slug>@<version>`        | unpublish a version (panic-mode; `unyank` restores)                           |
-| `kordis login` / `logout` / `whoami`  | identity                                                                      |
-| `kordis profile` / `follow` / `stars` | social layer                                                                  |
-| `kordis setup`                        | inject usage guide into Claude Code / Codex / Gemini CLI globals              |
+| command                               | purpose                                                                                |
+| ------------------------------------- | -------------------------------------------------------------------------------------- |
+| `kordis search <query>`               | search the registry                                                                    |
+| `kordis info <slug>`                  | inspect a package                                                                      |
+| `kordis read <slug>`                  | JIT-fetch body into agent context — no disk write (all types except mcp-server / hook) |
+| `kordis adapt <slug>`                 | fit a judgment pattern to this project's harness (prints a brief; writes nothing)      |
+| `kordis pull <slug>`                  | install into the current project (the only path for mcp-server / hook)                 |
+| `kordis push <file>`                  | publish a new package or version                                                       |
+| `kordis pull <slug>@<version>`        | pin a specific version / range (transitive deps resolved)                              |
+| `kordis yank <slug>@<version>`        | unpublish a version (panic-mode; `unyank` restores)                                    |
+| `kordis login` / `logout` / `whoami`  | identity                                                                               |
+| `kordis profile` / `follow` / `stars` | social layer                                                                           |
+| `kordis setup`                        | inject usage guide into Claude Code / Codex / Gemini CLI globals                       |
 
 Pass `--json` on any command to get machine-readable output.
 

package/assets/KORDIS.md

@@ -48,6 +48,8 @@ Verbs: `kordis search`, `info`, `read`, `adapt`, `pull`, `push`, `comment`,
 programmatically. Star etiquette: only after the user explicitly confirms in
 the conversation that a package helped may you OFFER to star it — run
 `kordis star` only on their yes; never unprompted, never auto-login for it.
+Never for a package the user authored: the server refuses that with
+`not_authorized`, since stars are readers' endorsements and feed ranking.
 
 Detail lives in five on-demand sub-skills installed at `~/.claude/skills/`,
 `~/.codex/skills/`, and `~/.gemini/skills/`:

package/assets/kordis-recommend/SKILL.md

@@ -2,12 +2,13 @@
 name: kordis-recommend
 description: Use whenever the user wants ideas — phrases like "any new stuff?", "recommend", "추천", "what should I try", "anything fresh?", "discover", "show me good skills", "what's popular for <stack>". Surfaces a personalized menu of Kordis packages the user may want to install or peek at. Read eagerly when the user signals discovery intent without a specific slug in mind.
 type: skill
-allowed-tools: ["Bash(kordis:*)"]
+allowed-tools: ['Bash(kordis:*)']
 ---
 
 # Kordis: Personalized Recommendations
 
 ## Goal
+
 Surface a ranked, agent-friendly menu of packages the user may want next.
 Algorithm is hybrid: content-based (your local stack) + item-CF (other
 users with similar installs) + popularity decay (stars + recency).
@@ -28,14 +29,18 @@ the user names a slug (use `kordis info` / `kordis read`).
 
 ## Command
 
-### `kordis recommend [--limit N] [--verbose] [--no-context] [--json]`
+### `kordis recommend [--limit N] [--no-context] [--json]`
 
-| flag           | meaning                                                          |
-| -------------- | ---------------------------------------------------------------- |
-| `--limit <n>`  | max items (default 10, max 50)                                   |
-| `--verbose`    | include `score_breakdown` per item (content / cf / popularity)   |
+| flag           | meaning                                                             |
+| -------------- | ------------------------------------------------------------------- |
+| `--limit <n>`  | max items (default 10, max 50)                                      |
 | `--no-context` | skip the `X-Kordis-Context` header for this call (one-shot opt-out) |
-| `--json`       | global flag — JSON envelope, no human render                     |
+| `--json`       | global flag — JSON envelope, no human render                        |
+
+`--verbose` still parses but does nothing. It used to print each item's
+score components; the ranking blend is server-private, so there is no
+per-item score to surface. Rank order is the signal — do not tell the user
+a package's numeric score, because you no longer receive one.
 
 Anonymous: works without login. Personalized signal rides on an opt-in
 `X-Kordis-Context` HTTP header (installed agent tools, top 3 CWD file
@@ -56,6 +61,7 @@ The user is asked ONCE. Three paths persist the answer to
    Use this when the user has confirmed consent in chat — see Step 2.5.
 
 Override at runtime (does not change the persisted answer):
+
 - `KORDIS_NO_CONTEXT=1` env — no header for the entire shell session
 - `--no-context` flag — no header for this single call
 
@@ -85,27 +91,31 @@ Surface this AND ask the user before flipping the flag (Step 2.5).
 
 `confidence` interpretation when surfacing to the user:
 
-| value    | how to surface                                                            |
-| -------- | ------------------------------------------------------------------------- |
-| `high`   | "You should try X" — both content match and co-install signal align       |
-| `medium` | "You might like X" — one signal strong                                    |
-| `low`    | "Worth a look — popular right now" — cold-start / no personalization      |
+| value    | how to surface                                                       |
+| -------- | -------------------------------------------------------------------- |
+| `high`   | "You should try X" — both content match and co-install signal align  |
+| `medium` | "You might like X" — one signal strong                               |
+| `low`    | "Worth a look — popular right now" — cold-start / no personalization |
 
 ## Steps
 
 ### 1. Fetch menu
+
 `kordis recommend --limit 10 --json`. (Add `--no-context` ONLY if the user
 explicitly asked you not to share their stack.)
 
 ### 2. Triage
+
 Filter mentally by `confidence`. If everything is `low` and `personalized`
 is `false`, follow Step 2.5 to offer the user a one-click consent path.
 
-If the response carries `capped_by_author > 0`, ALSO surface a one-line
-note to the user — e.g. "N more candidates from the same publisher were
-skipped by the diversity cap" — so they understand why the list is
-shorter than the requested `--limit`. Without this hint users frequently
-mistake a short menu for a sparse or broken registry.
+If the menu is shorter than the requested `--limit`, that now means the
+registry genuinely has fewer candidates — compare against `total_candidates`
+and say so plainly rather than implying the tool is broken. The per-author
+diversity cap no longer shortens the menu: it reorders, pushing a publisher's
+surplus down instead of discarding it, so `capped_by_author` is always `0`.
+(It used to drop them, which capped every menu at 3 items regardless of
+`--limit`.)
 
 ### 2.5. Offer personalization consent (when `personalized: false`)
 
@@ -132,13 +142,16 @@ optionally via `kordis setup --personalization off` so the question
 isn't asked again.
 
 ### 3. Present
+
 Surface 3-5 picks max. For each, show: full_slug, one-line `why_recommended`,
 confidence wording per the table above, and the next-step
 `install_command` / `jit_read_command`. Do NOT dump the whole menu — agent
 should curate.
 
 ### 4. Act
+
 If the user picks one:
+
 - "install it" → run `install_command` from the menu (already a complete
   shell line)
 - "peek first" → run `jit_read_command`, summarize, then offer install

package/assets/kordis-search/SKILL.md

@@ -70,8 +70,9 @@ array.
 ### 3. Triage the results
 
 - Prefer `review_status: passed`, higher `stars`, then `tier: A`.
-- For trending results, the `trending_score` field is populated — surface it
-  when comparing.
+- For trending results, **rank order is the signal** — the server returns no
+  numeric score, so never quote or compare one. Say "3rd on the 7-day
+  trending board", not a number.
 - IMPORTANT: if results are 0, RELAX one filter at a time before giving up.
   **Drop `--tool` first** — many published packages have an empty
   `tools_compatible` field, so `--tool <name>` undercounts hard. Then drop
@@ -125,7 +126,7 @@ User: "any Cursor-compatible package for code review?"
 <example>
 User: "what's trending on Kordis this week?"
 - kordis search --trending --window 7d --json
-- show top 5–10 with their `trending_score`; do NOT fetch bodies unless asked
+- show top 5–10 in the order returned; do NOT fetch bodies unless asked
 </example>
 
 <example>

package/assets/kordis-social/SKILL.md

@@ -66,13 +66,30 @@ response shape is the same whether the call newly starred or no-op'd; if the
 user wants to verify a NEW star landed, compare `stars` from `kordis info
 <full_slug> --json` before and after.
 
+**You cannot star a package the user authored.** The server refuses it with
+`not_authorized` (exit 11) — a star is a reader's endorsement and feeds
+ranking, so authors starring their own work would just be voting for
+themselves. This is a rule, not a glitch: do not retry, do not try another
+route, and do not present it as a failure the user should work around. Say
+what it is in one line and move on.
+
+<example>
+User: "star my rss-reader package"
+- kordis star rayul/rss-reader --json   -> exit 11, not_authorized
+- "본인이 올린 패키지엔 별점을 누를 수 없어요 — 별점은 읽은 사람의 추천이라
+   순위에 들어가서요. 슬러그를 공유하시면 다른 분이 누를 수 있습니다."
+- do NOT retry, do NOT suggest a second account
+</example>
+
 ### `kordis unstar <full_slug> [--json]`
 
 Remove your star. Idempotent — silent no-op when not previously starred.
 Auth required.
 
-Stars feed `--sort stars` ordering on `kordis search` and contribute to the
-`trending_score`.
+Stars feed `--sort stars` ordering on `kordis search` and the trending board.
+Only stars from someone **other than the author** count toward ranking. The
+numeric trending score is server-private and is no longer returned — rank
+order is the signal, so never quote a package's score to the user.
 
 ## Steps
 
@@ -130,6 +147,8 @@ User: "report that the v0.3.0 release of foo/bar is broken on macOS"
 User: "star foo/bar"
 - kordis star foo/bar --json
 - show new star count
+- if it returns `not_authorized` (exit 11), the user authored it — say so
+  in one line, do not retry
 </example>
 
 <example>

package/assets/kordis-using/SKILL.md

@@ -255,6 +255,12 @@ starring needs a one-click browser login; if they decline, drop it. NEVER run
 initiative. Caps: at most ONE offer per session, never twice for the same
 package, and a "no" suppresses all further offers that session.
 
+Do NOT offer for a package the USER themselves authored — the server refuses
+it with `not_authorized` (exit 11), because a star is a reader's endorsement
+and feeds ranking. Check the owner segment of the slug against `kordis
+whoami` before offering. If you offer anyway and it fails, say so once and
+drop it; do not retry.
+
 <example>
 User: "thanks, that fixed the parsing!"
 - reply ends: "following alice/pdf-extract@1.2.0 — want me to star it on Kordis?"

package/dist/index.js

@@ -305,7 +305,13 @@ var init_package = __esm({
       }),
       stars: z6.number().int().nonnegative(),
       downloads: z6.number().int().nonnegative(),
-      trending_score: z6.number().nullable(),
+      // `trending_score` was removed 2026-07-29 — same information class as the
+      // `score_breakdown` dropped from /recommend the same day. Publishing the raw
+      // score let a caller solve for the ranker's constants (star weight 5×, the
+      // verified ×1.15 multiplier, the decay τ) by starring/pulling once and
+      // reading the delta — i.e. it handed out the exact gaming lever. Trending
+      // ORDERING is unchanged; only the exposed number is gone. Callers that want
+      // "is this trending" read position in `GET /api/packages/trending`.
       tools_compatible: z6.array(ToolSlugSchema),
       tags: z6.array(TagSchema),
       agent_skills_compliant: z6.boolean().optional(),
@@ -975,7 +981,7 @@ var init_context = __esm({
 
 // ../../packages/contracts/src/recommend.ts
 import { z as z11 } from "zod";
-var RecommendQuerySchema, RecommendConfidenceSchema, RecommendScoreBreakdownSchema, RecommendMenuItemSchema, RecommendResponseSchema;
+var RecommendQuerySchema, RecommendConfidenceSchema, RecommendMenuItemSchema, RecommendResponseSchema;
 var init_recommend = __esm({
   "../../packages/contracts/src/recommend.ts"() {
     "use strict";
@@ -984,7 +990,10 @@ var init_recommend = __esm({
     RecommendQuerySchema = z11.object({
       limit: z11.coerce.number().int().positive().max(50).default(10),
       /**
-       * Include score_breakdown in the response. CLI sets when --verbose.
+       * Inert since 2026-07-29 — this used to add `score_breakdown` to each
+       * item, which leaked the ranking blend. Still ACCEPTED (not removed)
+       * because shipped CLIs ≤0.13.0 send `?verbose=true` and a stricter
+       * schema would turn their recommend calls into 400s.
        *
        * NOT `z.coerce.boolean()` — that wraps `Boolean()` which treats the
        * literal string `"false"` as truthy (non-empty string). Use explicit
@@ -994,12 +1003,6 @@ var init_recommend = __esm({
       verbose: z11.union([z11.boolean(), z11.enum(["true", "false"])]).transform((v) => v === true || v === "true").optional().default(false)
     });
     RecommendConfidenceSchema = z11.enum(["low", "medium", "high"]);
-    RecommendScoreBreakdownSchema = z11.object({
-      content: z11.number(),
-      cf: z11.number(),
-      popularity: z11.number(),
-      final: z11.number()
-    });
     RecommendMenuItemSchema = z11.object({
       full_slug: FullSlugSchema,
       title: z11.string(),
@@ -1019,9 +1022,7 @@ var init_recommend = __esm({
        * "Trending in your tool's ecosystem this week".
        */
       why_recommended: z11.string(),
-      confidence: RecommendConfidenceSchema,
-      /** Present only when the request specified `verbose=true`. */
-      score_breakdown: RecommendScoreBreakdownSchema.optional()
+      confidence: RecommendConfidenceSchema
     });
     RecommendResponseSchema = z11.object({
       items: z11.array(RecommendMenuItemSchema),
@@ -1033,11 +1034,14 @@ var init_recommend = __esm({
        */
       personalized: z11.boolean(),
       /**
-       * 0.5.0 — number of additional candidates the server had before applying
-       * the per-author cap. When `capped_by_author > 0`, the agent can explain
-       * "menu is shorter than --limit because diversity cap fired" instead of
-       * the user inferring the registry is sparse. Absent on responses from
-       * pre-0.5.0 servers.
+       * 0.5.0 — how many candidates the per-author cap DISCARDED.
+       *
+       * Always `0` since 2026-07-29: the cap now demotes a publisher's surplus to
+       * a tail bucket instead of dropping it, so the menu is never shortened by
+       * the cap. Kept in the response (rather than removed) because shipped CLIs
+       * ≤0.13.0 print "N candidates were skipped by the diversity cap" whenever
+       * this is `> 0` — emitting a nonzero value would make them state something
+       * false. Absent on responses from pre-0.5.0 servers.
        */
       capped_by_author: z11.number().int().nonnegative().optional(),
       /**
@@ -2532,7 +2536,7 @@ var TOOL_ALIASES = {
 function searchCommand() {
   return new Command3("search").description("search the Kordis registry").argument("[query...]", "keywords to match against title/description").option(
     "--type <type>",
-    "filter by harness type (skill|mcp-server|project-rules|custom-agent|hook)"
+    "filter by harness type (skill|mcp-server|project-rules|custom-agent|hook|judgment-pattern)"
   ).option(
     "--tool <tool>",
     `filter by compatible tool \u2014 one of: ${TOOL_SLUGS.join("|")} (aliases: ${Object.entries(
@@ -2618,9 +2622,6 @@ function searchCommand() {
             `\u21E3 ${p.downloads}`,
             `${stripControl(p.author.username)}${p.author.is_verified ? " \u2713" : ""}`
           ];
-          if (typeof p.trending_score === "number") {
-            trail.push(`score ${p.trending_score.toFixed(2)}`);
-          }
           printHuman(c.gray(`  ${trail.join("  ")}`));
           printHuman("");
         }
@@ -6432,7 +6433,7 @@ function diffCommand() {
 import { Command as Command21 } from "commander";
 import prompts4 from "prompts";
 function recommendCommand() {
-  return new Command21("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 Command21("recommend").description("show personalized package recommendations").option("--limit <n>", "max items to return (1-50)", (v) => parseInt(v, 10), 10).option("--verbose", "deprecated \u2014 accepted and ignored", 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 prompts4({
@@ -6457,8 +6458,7 @@ function recommendCommand() {
     const bundle = await useClient();
     const spin = spinner("Computing recommendations");
     const res = await bundle.api.recommend({
-      limit: opts.limit,
-      verbose: opts.verbose
+      limit: opts.limit
     });
     spin.succeed();
     await writeCache(res.items, res.generated_at);
@@ -6493,7 +6493,7 @@ function recommendCommand() {
           `${c.bold(`${res.items.length} pick${res.items.length === 1 ? "" : "s"}`)} ${c.gray(`(${res.personalized ? "personalized" : "popularity-only"} \xB7 generated ${res.generated_at.slice(0, 19)}Z)`)}`
         );
         printHuman("");
-        res.items.forEach((it, idx) => renderItem(idx + 1, it, opts.verbose));
+        res.items.forEach((it, idx) => renderItem(idx + 1, it));
         printHuman("");
         printHuman(
           c.gray(
@@ -6519,7 +6519,7 @@ function recommendCommand() {
     });
   });
 }
-function renderItem(idx, it, verbose) {
+function renderItem(idx, it) {
   const confidenceBadge = it.confidence === "high" ? c.green("high") : it.confidence === "medium" ? c.cyan("medium") : c.gray("low");
   printHuman(
     `${c.bold(`${idx}. ${it.full_slug}`)} ${c.gray(`v${it.current_version}`)} ${c.cyan(`[${it.type}]`)} ${c.gray(`tier ${it.tier}`)} ${c.gray("\xB7")} ${confidenceBadge} confidence`
@@ -6530,14 +6530,6 @@ function renderItem(idx, it, verbose) {
   printHuman(c.gray(`   \u2192 ${it.why_recommended}`));
   printHuman(c.gray(`   install: ${c.cyan(it.install_command)}`));
   printHuman(c.gray(`   read:    ${c.cyan(it.jit_read_command)}`));
-  if (verbose && it.score_breakdown) {
-    const b = it.score_breakdown;
-    printHuman(
-      c.gray(
-        `   score:   content=${b.content} cf=${b.cf} popularity=${b.popularity} final=${b.final}`
-      )
-    );
-  }
   printHuman("");
 }
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",
+  "homepage": "https://kordis.store",
   "type": "module",
   "bin": {
     "kordis": "bin/kordis.js"