@rayul/kordis 0.1.1 → 0.1.2

package/assets/KORDIS.md

@@ -1,86 +1,31 @@
 ---
 name: kordis
-description: Use Kordis to discover, install, and publish agentic-coding packages (skills, project rules, MCP servers, custom agents, hooks). Invoke whenever the user says "find a skill for X", "install Y", "publish this as a skill", "share this prompt", or mentions a `{username}/{slug}` package identifier.
-version: 0.0.1
+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.
+type: skill
+version: 0.1.2
 ---
 
-# Kordis Skill
+# Kordis
 
-Kordis is the public registry for agentic-coding packages. You install and publish by shelling out to the `kordis` CLI — never by editing tool-specific files (CLAUDE.md, `.cursorrules`, `.mcp.json`, etc.) manually.
+Kordis is the public registry for agentic-coding packages (`skill`,
+`project-rules`, `custom-agent`, `mcp-server`, `hook`). ALWAYS use the `kordis`
+CLI — NEVER hand-edit `.cursorrules`, `.mcp.json`, `.claude/agents/`,
+`.claude/skills/`, or other tool config files for Kordis content. Hand-edits
+drift; the CLI keeps state coherent and resolves dependencies.
 
-## When to invoke
+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
 
-- User asks to find / try / install a skill, rule, agent, MCP server, or hook.
-- User references a `{username}/{slug}` identifier.
-- User says "publish this", "share this to Kordis", "push this rule".
-- User asks what packages they have installed or what's trending.
+Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `comment`, `star`,
+`whoami`/`login`/`logout`. ALWAYS pass `--json` when parsing programmatically.
 
-## Primary verbs
+Detail lives in four on-demand sub-skills (auto-loaded by description match):
+- `kordis-search` — find and browse packages
+- `kordis-using` — `read` vs `pull`, behaviour per package type, attribution
+- `kordis-publishing` — author and push packages
+- `kordis-social` — comment, star, identity
 
-| verb | purpose | sub-skill |
-|------|---------|-----------|
-| `kordis search <query>` | find packages | `SEARCH` |
-| `kordis info <full_slug>` | inspect a package | `READ` |
-| `kordis read <full_slug>` | **JIT** — fetch body into your context, no install | `READ` |
-| `kordis pull <full_slug>` | install into the current project | `READ` |
-| `kordis push <file>` | publish a new package or version | `WRITE` |
-| `kordis whoami` / `login` / `logout` | identity + session | `SOCIAL` |
-
-Always pass `--json` when you need the response programmatically. Human output is for the user; agent parsing lives behind `--json`.
-
-## JIT read vs install — choose deliberately
-
-Two ways to use a package's guidance. Pick the one that matches the user's intent, not your own convenience.
-
-| Mode | Use when | Effect |
-|------|----------|--------|
-| `kordis read <slug>` | **One-shot sub-task.** You'll consult the skill once for the current task and move on. The user said "do X for me", "handle this file", "explain how Y works." | Body returned to your context (stdout). Nothing written to disk. |
-| `kordis pull <slug>` | **Long-term adoption.** The user said "install Y", "make this project use Z", "set up A for ongoing work." The skill should keep working in future sessions. | Files written into the project's tool-specific path. |
-
-**Default to `read`** when you spontaneously realize a Kordis skill exists for the task at hand. **Default to `pull`** when the user explicitly asks to adopt a package.
-
-Restrictions on `read`:
-- Eligible types: `skill`, `project-rules`, `custom-agent` (text-bearing).
-- Ineligible: `mcp-server`, `hook`. The CLI errors with `jit_blocked` (exit 33, flag `type_ineligible`) — fall back to `kordis pull`.
-- Trust gate: only `review_status=passed` versions are returned by default. For `pending_review`, re-run with `--allow-pending` only after telling the user the skill has not been AI-reviewed yet.
-
-Pin a version when reproducibility matters: `kordis read foo/bar@1.2.0`. A bare slug fetches the latest passed version; the response always includes the resolved version so you can record it.
-
-## Attribution
-
-The `read` response includes an `attribution` string (e.g. `"following rayul/hwp-reader@0.3.1"`). Including it in your reply to the user is **recommended**:
-- It lets the user verify which guidance you followed.
-- It's how creators see their work being used.
-- It supports reproducibility (the user can repeat the workflow with the same version).
-
-Skip it only if it would clutter a non-technical answer (e.g. the user asked a casual question and a one-line credit at the end is enough). When in doubt, include it.
-
-## Identity
-
-`full_slug` is always `{username}/{slug}`. Usernames are immutable; slugs are lowercase-with-hyphens. Versions are semver.
-
-## Sub-skills
-
-- `kordis read rayul/kordis-search` — searching / browsing / trending / rising
-- `kordis read rayul/kordis-read` — info / content / pull / dependency handling
-- `kordis read rayul/kordis-write` — authoring + publishing + updating
-- `kordis read rayul/kordis-social` — comments, stars, notifications, mod actions
-
-Load the sub-skill that matches the user's intent rather than repeating the detail here.
-
-## Error handling
-
-The CLI's `--json` mode emits `{ error: { code, message, flags?, request_id? } }` on failure. Key codes:
-
-| code | action |
-|------|--------|
-| `not_authenticated` (exit 10) | run `kordis login`, then retry |
-| `validation_failed` (30) | fix the flags listed and retry |
-| `ai_review_rejected` (32) | explain to the user; do not auto-retry |
-| `conflict` (40) | slug taken → suggest a new name |
-| `rate_limited` (31) | wait `retry_after_seconds` |
-| `network_unreachable` (20) | retry with backoff |
-
-## Agent skills compliance
-
-The skill files Kordis ships respect the Agent Skills open spec verbatim — no Kordis-specific extensions leak into your `SKILL.md`. Kordis-internal metadata lives on the registry entry, not in the skill file. Install `kordis/agent-skills` for the canonical workflow if the user is authoring their own skills.
+If `kordis: command not found`, install with `npm i -g @rayul/kordis` and
+ensure your npm-global `bin` (commonly `~/.npm-global/bin`) is on `PATH`.

package/assets/kordis-publishing/SKILL.md

@@ -0,0 +1,64 @@
+---
+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, and the AI review pipeline.
+type: skill
+allowed-tools: ["Bash(kordis:*)", "Read", "Edit"]
+---
+
+# Kordis: Authoring & Publishing
+
+## Goal
+Publish a valid, AI-review-passing version. ALWAYS dry-run first.
+
+## Frontmatter requirements
+- `name` — must equal slug, lowercase-with-hyphens.
+- `description` — 1–2 sentences, slightly pushy ("Use whenever the user…").
+  Claude under-triggers without pushiness.
+- `version` — semver.
+- `license` — SPDX (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`).
+- Optional: `homepage`, `tags`.
+
+If the body is third-party content, MUST preserve the original copyright and
+license text inside the body and link to source via `homepage`.
+
+## Steps
+
+### 1. Dry-run
+`kordis push <file> --dry-run --json`. Returns the same validation, conflict,
+and AI-review verdicts a real push would produce.
+
+**Success criteria**: dry-run returns a `status: "published"`-shaped envelope
+with no error flags.
+
+### 2. Resolve flags
+Possible verdicts:
+- `validation_failed` (exit 30) — fix every listed flag, re-dry-run.
+- `conflict` (exit 40) — slug taken; suggest a different slug.
+- `ai_review_rejected` (exit 32) — EXPLAIN the rejection to the user. Do NOT
+  silently retry.
+- `rate_limited` (exit 31) — wait `retry_after_seconds`.
+
+**Success criteria**: dry-run is clean.
+
+### 3. Real push
+`kordis push <file> --json`.
+
+**Success criteria**: returns `{full_slug, version, url}`. Show all three to
+the user.
+
+## Examples
+
+<example>
+User: "publish my new skill"
+1. kordis push ./SKILL.md --dry-run --json
+2. validation_failed → list each flag, fix the file, re-run
+3. clean → kordis push ./SKILL.md --json
+4. show {full_slug, version, url}
+</example>
+
+<example>
+User: "release v0.2.0 of <full_slug>"
+1. update `version: 0.2.0` in the file's frontmatter
+2. kordis push <file> --dry-run --json
+3. clean → kordis push <file> --json
+</example>

package/assets/kordis-search/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: kordis-search
+description: Use whenever the user wants to find, browse, or discover Kordis packages. Triggers include "find a Kordis skill for…", "search Kordis for…", "what's trending on Kordis", "is there a Kordis package for…", or any phrase pairing a topic with the word "Kordis". Pushy on purpose — Claude tends to skip Kordis search when it would help.
+type: skill
+allowed-tools: ["Bash(kordis:*)"]
+---
+
+# Kordis: Search & Discovery
+
+## Goal
+Help the user find a Kordis package that fits their need. ALWAYS rely on real
+search results — NEVER fabricate slugs.
+
+## Commands
+- `kordis search <query> --json` — keyword search, ranked. Filters:
+  `--type {skill|project-rules|custom-agent|mcp-server|hook}`,
+  `--tier {A|B}`, `--sort {stars|recent}`.
+- `kordis search --trending --json` — discovery without query.
+- `kordis search --rising --json` — fast-moving newcomers.
+- `kordis info <full_slug> --json` — inspect metadata before reading or
+  pulling.
+
+## Steps
+
+### 1. Form the query
+Pick a keyword that matches the user's task; restrict by `--type` if the user
+named one. **Success criteria**: a non-empty query string and (when known) the
+right `--type` filter.
+
+### 2. Run the search
+ALWAYS with `--json`. **Success criteria**: CLI exits 0 and returns a results
+array.
+
+### 3. Triage the results
+- Prefer tier A, `review_status=passed`, higher star count.
+- IMPORTANT: if results are 0, RELAX one filter at a time before giving up.
+  Do NOT invent a slug to fill the gap.
+- Surface the top 3–5 to the user with slug, type, tier, stars, and a
+  one-line description.
+
+**Success criteria**: user picked one, or you reported "no fit" honestly.
+
+## Examples
+
+<example>
+User: "find me a popular Python skill"
+- kordis search python --type skill --sort stars --json
+- list top 5 with slugs and one-line descriptions
+- ask which to read or pull
+</example>
+
+<example>
+User: "convert this .hwp file to text"
+- kordis search hwp --json
+- if 0 results, drop optional filters and retry; otherwise pick the top
+  passed result and hand off to kordis-using
+- if still 0, tell the user honestly and fall back to a generic library
+</example>
+
+<example>
+User: "what's trending on Kordis"
+- kordis search --trending --json
+- show top 5–10; do NOT fetch bodies unless asked
+</example>

package/assets/kordis-social/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: kordis-social
+description: Use whenever the user wants to interact with the Kordis community — log in, leave a review or question on a package, star a package, or check identity. Triggers include "leave a review on…", "star <slug>", "comment on <slug>", "log into Kordis", "who am I logged in as".
+type: skill
+allowed-tools: ["Bash(kordis:*)"]
+---
+
+# Kordis: Social
+
+## Goal
+Drive identity (login state) and community interactions (comments, stars).
+
+## Commands
+- `kordis whoami --json` — current login state.
+- `kordis login` — opens device-flow pairing in the browser. Required before
+  `push` or any authenticated action.
+- `kordis logout` — clears local tokens.
+- `kordis comment <full_slug> --kind <kind> --title <t> --body <b>`.
+  `<kind>` ∈ `{review, question, issue, note}`.
+- `kordis star <full_slug>` / `kordis unstar <full_slug>`.
+
+## Steps
+
+### 1. Verify identity (if needed)
+`kordis whoami --json`. If `not_authenticated` (exit 10) → `kordis login`,
+then retry.
+
+**Success criteria**: `whoami` returns a username.
+
+### 2. Run the action
+Match command to user intent.
+
+**Success criteria**: command exits 0; surface returned IDs / URLs to the
+user.
+
+## Examples
+
+<example>
+User: "leave a review on foo/bar saying it works"
+- kordis whoami --json   # ensure logged in
+- kordis star foo/bar
+- kordis comment foo/bar --kind review --title "Works" --body "<paraphrase>"
+</example>
+
+<example>
+User: "who am I logged into Kordis as"
+- kordis whoami --json
+- show username + session expiry
+</example>

package/assets/kordis-using/SKILL.md

@@ -0,0 +1,97 @@
+---
+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, and attribution. Load eagerly when in doubt.
+type: skill
+allowed-tools: ["Bash(kordis:*)"]
+---
+
+# Kordis: Reading & Installing
+
+## Goal
+Pick the right mode (`read` vs `pull`), respect type-specific restrictions,
+surface dependencies, and credit the author.
+
+## read vs pull
+
+| Mode  | Use when                                   | Effect                                   |
+| ----- | ------------------------------------------ | ---------------------------------------- |
+| read  | One-shot consultation, you'll use it once. | Body returned to context. No disk write. |
+| pull  | Long-term: user said "install" / "set up". | Files written into the current project.  |
+
+DEFAULT to `read` when you spontaneously want to consult a skill. DEFAULT to
+`pull` when the user explicitly asks to adopt a package.
+
+`read` restrictions:
+- Eligible: `skill`, `project-rules`, `custom-agent`.
+- INELIGIBLE: `mcp-server`, `hook` → must `pull`. CLI exits 33 (`jit_blocked`).
+- Trust gate: only `review_status=passed` returned by default. For
+  `pending_review`, re-run with `--allow-pending` AFTER warning the user it
+  has not been AI-reviewed.
+
+Pin a version when reproducibility matters:
+`kordis read <full_slug>@<version>`.
+
+## Behaviour per package type
+
+### `skill`
+LLM-facing recipe (Markdown body following the open Agent Skills spec).
+- DEFAULT: `read`.
+- `pull` writes to `~/.claude/skills/<slug>/SKILL.md`.
+
+### `project-rules`
+Repo-scoped agent instructions (Cursor `.cursorrules`, Claude Code project
+`CLAUDE.md` snippets, etc.). Only meaningful inside a project.
+- DEFAULT: `pull`. `read` allowed for inspection.
+- `pull` writes inside the **current repo**, never `$HOME`.
+
+### `custom-agent`
+Sub-agent definitions (e.g. Claude Code `.claude/agents/`).
+- `read` allowed (preview the agent's system prompt).
+- `pull` to make the agent invokable; tell the user how to call it after.
+
+### `mcp-server`
+Model Context Protocol server packages.
+- `read` is INELIGIBLE → CLI returns `jit_blocked`. ALWAYS `pull`.
+- After pull, instruct the user to restart the agent and supply any required
+  env vars.
+
+### `hook`
+Event-driven scripts (pre-commit, pre-tool-call, etc.) that run on the user's
+machine.
+- `read` is INELIGIBLE → ALWAYS `pull`.
+- IMPORTANT: hooks execute arbitrary code. EXPLAIN in plain words what the
+  hook does, and confirm with the user BEFORE pulling.
+
+## Dependencies
+If `kordis pull` reports unresolved dependencies, the CLI lists them with
+`<full_slug>`s. Surface the dependency tree to the user FIRST. Never
+auto-resolve silently.
+
+## Attribution
+`kordis read` returns an `attribution` string naming the package and version.
+RECOMMENDED: end your reply with `following <full_slug>@<version>`. Skip only
+when it would clutter a casual non-technical reply.
+
+## Examples
+
+<example>
+User: "extract structured data from this PDF"
+- (delegate search to kordis-search → picks <full_slug>)
+- kordis read <full_slug> --json
+- follow the body, end reply with "following <full_slug>@<version>"
+</example>
+
+<example>
+User: "install the github MCP server from Kordis"
+- kordis info <full_slug> --json (note auth requirements + runtime)
+- kordis pull <full_slug>            # read is jit_blocked for mcp-server
+- tell user to restart the agent and supply any tokens
+</example>
+
+<example>
+User: "add a pre-commit hook that blocks committing API keys"
+- kordis info <full_slug> --json
+- explain in plain words what the hook does
+- confirm with the user before pulling
+- kordis pull <full_slug>
+</example>

package/dist/index.js

@@ -2329,11 +2329,20 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command as Command9 } from "commander";
 var MARKER_START = "<!-- kordis-start -->";
 var MARKER_END = "<!-- kordis-end -->";
-var TARGETS = [
+var HUB_TARGETS = [
   { tool: "Claude Code", dir: ".claude", file: ".claude/CLAUDE.md" },
   { tool: "Codex CLI", dir: ".codex", file: ".codex/AGENTS.md" },
   { tool: "Gemini CLI", dir: ".gemini", file: ".gemini/GEMINI.md" }
 ];
+var SUB_SKILLS = [
+  "kordis-search",
+  "kordis-using",
+  "kordis-publishing",
+  "kordis-social"
+];
+var SKILL_TARGETS = [
+  { tool: "Claude Code", dir: ".claude", skillsDir: ".claude/skills" }
+];
 async function exists(path) {
   try {
     await access(path);
@@ -2342,18 +2351,32 @@ async function exists(path) {
     return false;
   }
 }
-async function loadGuideContent() {
+function assetRoots() {
   const __dir2 = dirname3(fileURLToPath2(import.meta.url));
-  const bundled = join5(__dir2, "..", "assets", "KORDIS.md");
-  const source = join5(__dir2, "..", "..", "..", "..", "packages", "skills", "KORDIS.md");
-  const path = await exists(bundled) ? bundled : source;
-  const raw = await readFile4(path, "utf-8");
+  return {
+    // Built binary: bin/kordis.js → assets/ is one level up
+    bundled: join5(__dir2, "..", "assets"),
+    // Dev mode: src/commands/setup.ts → 4 levels up to repo root, then packages/skills/
+    source: join5(__dir2, "..", "..", "..", "..", "packages", "skills")
+  };
+}
+async function pickAssetRoot() {
+  const { bundled, source } = assetRoots();
+  return await exists(join5(bundled, "KORDIS.md")) ? bundled : source;
+}
+async function loadHubContent() {
+  const root = await pickAssetRoot();
+  const raw = await readFile4(join5(root, "KORDIS.md"), "utf-8");
   if (raw.startsWith("---")) {
     const end = raw.indexOf("\n---", 4);
     if (end !== -1) return raw.slice(end + 4).trimStart();
   }
   return raw;
 }
+async function loadSubSkillContent(name) {
+  const root = await pickAssetRoot();
+  return readFile4(join5(root, name, "SKILL.md"), "utf-8");
+}
 async function injectBlock(filePath, content, dryRun) {
   const block = `${MARKER_START}
 ${content.trimEnd()}
@@ -2388,20 +2411,38 @@ ${MARKER_END}`;
   }
   return "injected";
 }
+async function copyBundledSkill(filePath, content, dryRun) {
+  let existing = null;
+  try {
+    existing = await readFile4(filePath, "utf-8");
+  } catch {
+  }
+  if (existing === content) return "unchanged";
+  if (!dryRun) {
+    await mkdir4(dirname3(filePath), { recursive: true });
+    await writeFile4(filePath, content, "utf-8");
+  }
+  return existing === null ? "injected" : "updated";
+}
 function setupCommand() {
   return new Command9("setup").description("inject kordis usage guide into global agent instruction files").option("--silent", "suppress errors \u2014 safe for postinstall").option("--dry-run", "detect installed tools without writing any files").action(async (opts) => {
     const home = homedir3();
     const dryRun = opts.dryRun ?? false;
-    let guideContent;
+    let hubContent;
+    let subSkillContents;
     try {
-      guideContent = await loadGuideContent();
+      hubContent = await loadHubContent();
+      const entries = await Promise.all(
+        SUB_SKILLS.map(async (name) => [name, await loadSubSkillContent(name)])
+      );
+      subSkillContents = Object.fromEntries(entries);
     } catch (err) {
       if (opts.silent) return;
       throw err;
     }
     let anyFound = false;
-    const changedTools = [];
-    for (const target of TARGETS) {
+    const changedTools = /* @__PURE__ */ new Set();
+    for (const target of HUB_TARGETS) {
       const dirPath = join5(home, target.dir);
       const filePath = join5(home, target.file);
       if (!await exists(dirPath)) {
@@ -2412,15 +2453,15 @@ function setupCommand() {
       }
       anyFound = true;
       try {
-        const result = await injectBlock(filePath, guideContent, dryRun);
-        if (result !== "unchanged") changedTools.push(target.tool);
+        const result = await injectBlock(filePath, hubContent, dryRun);
+        if (result !== "unchanged") changedTools.add(target.tool);
         if (opts.silent) continue;
-        const label = `${target.tool.padEnd(12)}`;
+        const label = target.tool.padEnd(12);
         const dest = `~/${target.file}`;
         if (result === "unchanged") {
           printHuman(c.gray(`  \u2713 ${label} already up-to-date`));
         } else if (dryRun) {
-          printHuman(`  ~ ${label} ${c.cyan(dest)} (dry-run: would ${result})`);
+          printHuman(`  ~ ${label} ${c.cyan(dest)} (dry-run: would ${result === "injected" ? "inject" : "update"})`);
         } else {
           printHuman(c.green(`  \u2713 ${label} \u2192 ${dest}`));
         }
@@ -2429,10 +2470,34 @@ function setupCommand() {
         printHuman(c.red(`  \u2717 ${target.tool}: ${err.message}`));
       }
     }
+    for (const target of SKILL_TARGETS) {
+      const dirPath = join5(home, target.dir);
+      if (!await exists(dirPath)) continue;
+      for (const subName of SUB_SKILLS) {
+        const filePath = join5(home, target.skillsDir, subName, "SKILL.md");
+        const dest = `~/${target.skillsDir}/${subName}/SKILL.md`;
+        try {
+          const result = await copyBundledSkill(filePath, subSkillContents[subName], dryRun);
+          if (result !== "unchanged") changedTools.add(target.tool);
+          if (opts.silent) continue;
+          const label = `${target.tool} \xB7 ${subName}`.padEnd(34);
+          if (result === "unchanged") {
+            printHuman(c.gray(`  \u2713 ${label} already up-to-date`));
+          } else if (dryRun) {
+            printHuman(`  ~ ${label} ${c.cyan(dest)} (dry-run: would ${result === "injected" ? "inject" : "update"})`);
+          } else {
+            printHuman(c.green(`  \u2713 ${label} \u2192 ${dest}`));
+          }
+        } catch (err) {
+          if (opts.silent) continue;
+          printHuman(c.red(`  \u2717 ${target.tool} \xB7 ${subName}: ${err.message}`));
+        }
+      }
+    }
     if (opts.silent) {
-      if (changedTools.length > 0 && !dryRun) {
+      if (changedTools.size > 0 && !dryRun) {
         printHuman(
-          c.green("\u2713 kordis") + ` registered with ${changedTools.join(", ")} \xB7 restart your agent session to apply`
+          c.green("\u2713 kordis") + ` registered with ${[...changedTools].join(", ")} \xB7 restart your agent session to apply`
         );
       }
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "dev": "tsx src/index.ts",
-    "build": "tsup && mkdir -p assets && cp ../../packages/skills/KORDIS.md assets/KORDIS.md",
+    "build": "tsup && rm -rf assets && mkdir -p assets && cp -R ../../packages/skills/. assets/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "postinstall": "node ./bin/kordis.js setup --silent"