@rayul/kordis 0.1.2 → 0.1.3

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.3
 ---
 
 # 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`,
-`whoami`/`login`/`logout`. ALWAYS pass `--json` when parsing programmatically.
+Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `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
 
 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,59 @@
 ---
 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, or check who they are logged in as. Triggers include "log into Kordis", "kordis login", "who am I logged in as on Kordis", "log me out of Kordis". Pure identity / session management — community features (comments, stars) are not yet exposed in the CLI.
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
 
-# Kordis: Social
+# Kordis: Identity & Session
 
 ## Goal
-Drive identity (login state) and community interactions (comments, stars).
+Drive login state. `whoami` to inspect; `login`/`logout` to change.
 
 ## 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
+### `kordis whoami [--json]`
+Show the currently authenticated user (or that the CLI is anonymous).
+
+### `kordis login [--provider <name>]`
+Opens browser device-flow pairing. `--provider` defaults to `discord`.
+Required before any authenticated action (e.g. `kordis push`).
 
-### 1. Verify identity (if needed)
-`kordis whoami --json`. If `not_authenticated` (exit 10) → `kordis login`,
-then retry.
+### `kordis logout`
+Clears local tokens.
 
-**Success criteria**: `whoami` returns a username.
+## Steps
 
-### 2. Run the action
-Match command to user intent.
+### 1. Inspect identity (when in doubt)
+`kordis whoami --json`. **Success criteria**: returns either a username +
+profile, or the anonymous-state error indicating the user is not logged in.
 
-**Success criteria**: command exits 0; surface returned IDs / URLs to the
-user.
+### 2. Change state on user request
+- "log me into Kordis" → `kordis login`. Tell the user a browser will open and
+  they must complete the pairing. **Success criteria**: subsequent
+  `kordis whoami --json` returns a username.
+- "log me out" → `kordis logout`. **Success criteria**: subsequent
+  `kordis whoami --json` is anonymous.
 
 ## 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 (and primary_provider if useful)
 </example>
 
 <example>
-User: "who am I logged into Kordis as"
-- kordis whoami --json
-- show username + session expiry
+User: "log into Kordis"
+- kordis login
+- explain that a browser device-flow page will open; user must approve on
+  their auth provider
+- after they confirm, run kordis whoami --json to verify
 </example>
+
+## Limitations
+
+The CLI does NOT yet expose `comment`, `star`/`unstar`, follow, or
+notification verbs. If the user asks for those interactions, tell them
+truthfully that those CLI verbs are not implemented yet — do not fabricate
+a command. Direct them to the web UI at `https://kordis.store` for now.

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] [--version <semver>] [--json]`
+Returns the full body (Markdown) of a text-bearing package, plus an
+`attribution` string. `--version` 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> --version 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/package.json

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