@rayul/kordis 0.1.2 → 0.1.4

package/assets/KORDIS.md

@@ -2,7 +2,7 @@
 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.
 type: skill
-version: 0.1.2
+version: 0.1.4
 ---
 
 # Kordis
@@ -18,14 +18,14 @@ Trigger Kordis when the user:
 - names a `<username>/<slug>` identifier
 - asks what is trending or rising
 
-Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `comment`, `star`,
+Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `comment`,
 `whoami`/`login`/`logout`. ALWAYS pass `--json` when parsing programmatically.
 
 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
+- `kordis-social` — identity, session, and posting comments
 
 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

@@ -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, 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>". Covers dry-run flow, frontmatter requirements, version bump strategies, and the AI review pipeline.
 type: skill
 allowed-tools: ["Bash(kordis:*)", "Read", "Edit"]
 ---
@@ -12,14 +12,29 @@ 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.
+- `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`.
+- Optional: `homepage`, `tags`, `type`.
 
-If the body is third-party content, MUST preserve the original copyright and
-license text inside the body and link to source via `homepage`.
+If the body contains third-party content, MUST preserve the original copyright
+and license text inside the body and link to source via `homepage`.
+
+## Commands
+
+### `kordis push <file> [options]`
+
+| flag                  | meaning                                                  |
+| --------------------- | -------------------------------------------------------- |
+| `--dry-run`           | validate only; do not publish                            |
+| `--bump <strategy>`   | `patch` (default) / `minor` / `major` — only on update   |
+| `--slug <slug>`       | override slug on first publish                           |
+| `--type <type>`       | override type inference                                  |
+| `--changelog <text>`  | optional changelog entry attached to this version        |
+| `--no-wait`           | return immediately without waiting for AI review         |
+
+`--json` is the global output flag.
 
 ## Steps
 
@@ -33,15 +48,18 @@ 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.
+- `conflict` (exit 40) — slug taken; suggest a different slug (or pass
+  `--slug` if first publish).
 - `ai_review_rejected` (exit 32) — EXPLAIN the rejection to the user. Do NOT
   silently retry.
 - `rate_limited` (exit 31) — wait `retry_after_seconds`.
+- `not_authenticated` (exit 10) — `kordis login`, then retry.
 
 **Success criteria**: dry-run is clean.
 
 ### 3. Real push
-`kordis push <file> --json`.
+`kordis push <file> --json`. Add `--bump minor` (or `major`) when shipping a
+non-patch update.
 
 **Success criteria**: returns `{full_slug, version, url}`. Show all three to
 the user.
@@ -59,6 +77,12 @@ User: "publish my new skill"
 <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
+2. kordis push <file> --bump minor --dry-run --json
+3. clean → kordis push <file> --bump minor --json
+</example>
+
+<example>
+User: "release with a note that breaking-changes the API"
+1. kordis push <file> --bump major --changelog "BREAKING: <summary>" --dry-run --json
+2. clean → drop --dry-run for the real push
 </example>

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. 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.
+description: Use whenever the user wants to find, browse, or discover Kordis packages. Triggers include "find a Kordis skill for…", "search Kordis for…", "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:*)"]
 ---
@@ -12,40 +12,45 @@ 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.
+
+### `kordis search [query...] [options]`
+Keyword search; `--json` for parsing.
+
+| flag           | meaning                                                |
+| -------------- | ------------------------------------------------------ |
+| `--type <t>`   | `skill`, `mcp-server`, `project-rules`, `custom-agent`, `hook` |
+| `--tool <s>`   | filter by compatible tool (`claude-code`, `codex`, `cursor`, …) |
+| `--limit <n>`  | max results (default 20)                               |
+
+### `kordis info <full_slug> --json`
+Inspect metadata (title, description, type, tier, version, author, stars,
+review status, dependencies) 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.
+named a package type, and by `--tool` if the user named their tool. **Success
+criteria**: a non-empty query and (when known) the right filters.
 
 ### 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.
+- Prefer `review_status: passed`, higher `stars`, then `tier: A`.
 - 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.
+- Surface the top 3–5 with slug, type, tier, stars, 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
+User: "find me a Python skill"
+- kordis search python --type skill --json
+- list top results with slugs and one-line descriptions
 - ask which to read or pull
 </example>
 
@@ -58,7 +63,7 @@ User: "convert this .hwp file to text"
 </example>
 
 <example>
-User: "what's trending on Kordis"
-- kordis search --trending --json
-- show top 5–10; do NOT fetch bodies unless asked
+User: "any Cursor-compatible package for code review?"
+- kordis search "code review" --tool cursor --json
+- present top results scoped to Cursor compatibility
 </example>

package/assets/kordis-social/SKILL.md

@@ -1,49 +1,93 @@
 ---
 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".
+description: Use whenever the user wants to log into Kordis, log out, check identity, or post a typed comment on a Kordis package. Triggers include "log into Kordis", "kordis login", "who am I logged in as on Kordis", "log me out of Kordis", "leave a tip on <slug>", "report a bug on <slug>", "comment on <slug>".
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
 
-# Kordis: Social
+# Kordis: Identity & Comments
 
 ## Goal
-Drive identity (login state) and community interactions (comments, stars).
+Drive the user's login state and let them post typed feedback on packages.
 
-## 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>`.
+## Identity commands
 
-## Steps
+### `kordis whoami [--json]`
+Show the currently authenticated user (or anonymous state).
+
+### `kordis login [--provider <name>]`
+Opens browser device-flow pairing. `--provider` defaults to `discord`.
+Required before `push` or `comment`.
+
+### `kordis logout`
+Clears local tokens.
 
-### 1. Verify identity (if needed)
-`kordis whoami --json`. If `not_authenticated` (exit 10) → `kordis login`,
-then retry.
+## Comment command
 
-**Success criteria**: `whoami` returns a username.
+### `kordis comment <full_slug> --body <text> [--kind <kind>] [--title <text>] [--json]`
+Post a top-level comment on a package. Auth required.
 
-### 2. Run the action
-Match command to user intent.
+| flag           | meaning                                                          |
+| -------------- | ---------------------------------------------------------------- |
+| `--body <t>`   | required, 1–10000 chars                                          |
+| `--kind <k>`   | `comment` (default), `tip`, `report`, `praise`, `question`       |
+| `--title <t>`  | 1–140 chars; honoured for top-level posts only                   |
 
-**Success criteria**: command exits 0; surface returned IDs / URLs to the
-user.
+Replies, edits, status flips (open/resolved on a `report`), and listing
+existing comments are NOT yet exposed in the CLI. Direct the user to
+`https://kordis.store/p/<full_slug>` for those interactions until verbs land.
+
+## Steps
+
+### 1. Inspect identity (when in doubt)
+`kordis whoami --json`. **Success criteria**: returns either a username +
+profile, or the anonymous-state error indicating not logged in.
+
+### 2. Match command to user intent
+- "log me into Kordis" → `kordis login`. Tell the user a browser device-flow
+  page will open; they must approve on their auth provider.
+- "log me out" → `kordis logout`.
+- "leave a tip / question / praise / bug-report / comment on <slug>" → pick
+  the matching `--kind`, generate a concise `--title` if it's a top-level
+  post, and put the substantive content in `--body`.
+
+### 3. Authenticate before posting
+If `kordis comment` returns `not_authenticated` (exit 10), run `kordis login`
+and retry. **Success criteria**: command exits 0; show returned `id` + `kind`
++ `title` (when present).
 
 ## 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>"
+User: "who am I logged into Kordis as?"
+- kordis whoami --json
+- show username + display_name
+</example>
+
+<example>
+User: "log into Kordis"
+- kordis login
+- explain that a browser device-flow page will open
+- after they confirm, run `kordis whoami --json` to verify
 </example>
 
 <example>
-User: "who am I logged into Kordis as"
-- kordis whoami --json
-- show username + session expiry
+User: "leave a tip on foo/bar saying it pairs well with baz/qux"
+- kordis comment foo/bar --kind tip --title "Pairs well with baz/qux" \
+    --body "Combine baz/qux's <feature> with this skill's <step> to <outcome>." --json
+- show returned `{id, kind, title}` so the user can find their post on the web UI
 </example>
+
+<example>
+User: "report that the v0.3.0 release of foo/bar is broken on macOS"
+- kordis comment foo/bar --kind report --title "v0.3.0 broken on macOS" \
+    --body "<reproducible details>" --json
+- mention that opening/resolving the report later requires the web UI
+</example>
+
+## Limitations
+
+The CLI does NOT yet expose `star`/`unstar`, follow, listing comments, replies,
+editing or moderating comments, or notifications. If the user asks for any of
+those, tell them truthfully that the CLI verb is not implemented yet — do NOT
+fabricate a command. For now direct them to `https://kordis.store`.

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, 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…". Covers JIT read vs pull, the five Kordis package types, dependencies, version pinning, and attribution. Load eagerly when in doubt.
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
@@ -24,25 +24,43 @@ DEFAULT to `read` when you spontaneously want to consult a skill. DEFAULT to
 `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.
+- Trust gate: only `review_status=passed` returned by default. To get a
+  `pending_review` body, pass `--allow-pending` AFTER warning the user the
+  package has not been AI-reviewed.
 
-Pin a version when reproducibility matters:
-`kordis read <full_slug>@<version>`.
+## Commands
+
+### `kordis read <full_slug>[@<version>] [--allow-pending] [--pin <semver>] [--json]`
+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]`
+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                |
+
+### `kordis info <full_slug> --json`
+Inspect metadata (description, tier, deps, license, review status, …) before
+reading or pulling. ALWAYS run this for `mcp-server` / `hook` types, where the
+user is about to execute foreign code or runtime config.
 
 ## 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`.
+- `pull` writes to the auto-detected tool's skill path
+  (e.g. `~/.claude/skills/<slug>/SKILL.md` for Claude Code).
 
 ### `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`.
+- Pull writes inside the **current repo**, never `$HOME`.
 
 ### `custom-agent`
 Sub-agent definitions (e.g. Claude Code `.claude/agents/`).
@@ -63,14 +81,15 @@ machine.
   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
+`kordis pull` reports `depends` and `recommends` from the package metadata.
+Surface the dependency tree to the user FIRST. If they accept,
+`--with-recommends` also pulls the recommended set in one go. 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.
+`kordis read` returns an `attribution` string (e.g.
+`"following <full_slug>@<version>"`). RECOMMENDED: end your reply with that
+exact line. Skip only when it would clutter a casual non-technical reply.
 
 ## Examples
 
@@ -81,17 +100,30 @@ User: "extract structured data from this PDF"
 - follow the body, end reply with "following <full_slug>@<version>"
 </example>
 
+<example>
+User: "install foo/bar for this repo"
+- kordis info foo/bar --json   # check tier, deps, license
+- if it has dependencies, surface them and ask before proceeding
+- kordis pull foo/bar
+</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
+- 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: "use the v0.2.0 of <full_slug> specifically"
+- kordis read <full_slug> --pin 0.2.0 --json
+  (or:  kordis read <full_slug>@0.2.0 --json)
+</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
+- explain what the hook does in plain words
 - confirm with the user before pulling
 - kordis pull <full_slug>
 </example>

package/dist/index.js

@@ -932,7 +932,7 @@ var init_src2 = __esm({
 
 // src/index.ts
 init_src2();
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 
 // src/commands/login.ts
 import { Command } from "commander";
@@ -2229,12 +2229,12 @@ async function detectTool(root) {
 // src/commands/read.ts
 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("--version <semver>", "pin to an exact version (overrides @suffix)").action(
+  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.version ?? inlineVersion;
+      const version = opts.pin ?? inlineVersion;
       const [username, slug] = fullSlug.split("/");
       if (!username || !slug) {
         throw new Error('full_slug must be "{username}/{slug}" (optional "@version")');
@@ -2509,9 +2509,55 @@ function setupCommand() {
   });
 }
 
+// src/commands/comment.ts
+import { Command as Command10 } from "commander";
+var KINDS = [
+  "comment",
+  "tip",
+  "report",
+  "praise",
+  "question"
+];
+function commentCommand() {
+  return new Command10("comment").description("post a comment on a package").argument("<full_slug>", "package identifier {username}/{slug}").requiredOption("--body <text>", "comment body (1\u201310000 chars)").option("--kind <kind>", `top-level kind: ${KINDS.join("|")}`, "comment").option("--title <text>", "top-level post title (1\u2013140 chars)").action(
+    async (rawSlug, opts) => {
+      if (!KINDS.includes(opts.kind)) {
+        throw new Error(`--kind must be one of ${KINDS.join(", ")}`);
+      }
+      const [username, slug] = rawSlug.split("/");
+      if (!username || !slug) {
+        throw new Error('full_slug must be "{username}/{slug}"');
+      }
+      const bundle = await useClient();
+      if (!bundle.username) {
+        printHuman(c.yellow("Not logged in. Run `kordis login`."));
+        process.exitCode = 10;
+        return;
+      }
+      const res = await bundle.authedRequest(
+        (api) => api.createComment(username, slug, {
+          kind: opts.kind,
+          ...opts.title ? { title: opts.title } : {},
+          body: opts.body
+        })
+      );
+      printDual({
+        json: res,
+        human: () => {
+          printHuman(c.green("\u2713 comment posted"));
+          printHuman(c.gray(`  id: ${res.id}`));
+          const meta = [`kind: ${res.kind}`];
+          if (res.title) meta.push(`title: "${res.title}"`);
+          printHuman(`  ${meta.join(" \xB7 ")}`);
+        }
+      });
+    }
+  );
+}
+
 // src/index.ts
 function buildProgram() {
-  const program = new Command10("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
+  const program = new Command11("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     if (opts.json) setJsonMode(true);
   });
@@ -2523,6 +2569,7 @@ function buildProgram() {
   program.addCommand(pullCommand());
   program.addCommand(readCommand());
   program.addCommand(infoCommand());
+  program.addCommand(commentCommand());
   program.addCommand(setupCommand());
   return program;
 }

package/package.json

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