@rayul/kordis 0.1.8 → 0.1.10

package/assets/kordis-publishing/SKILL.md

@@ -14,10 +14,18 @@ Publish a valid, AI-review-passing version. ALWAYS dry-run first.
 - `name` — must equal slug, lowercase-with-hyphens.
 - `description` — 1–2 sentences, slightly **pushy** ("Use whenever the
   user…"). Claude under-triggers without pushiness.
-- `version` — semver.
+- `version` — semver. **Behaviour differs by path** (see below).
 - `license` — SPDX (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`).
 - Optional: `homepage`, `tags`, `type`.
 
+**`version` field handling:**
+- **First publish** — used as-is (else defaults to `0.1.0`).
+- **Update** — the registry computes the next version from
+  `current_version + --bump <strategy>` (default `patch`). If the file's
+  `version` differs from that result, the API rejects with `usage`. Either
+  drop the `version` field on updates, set `--bump` to match, or align
+  them.
+
 If the body contains third-party content, MUST preserve the original copyright
 and license text inside the body and link to source via `homepage`.
 
@@ -40,7 +48,14 @@ and license text inside the body and link to source via `homepage`.
 
 ### 1. Dry-run
 `kordis push <file> --dry-run --json`. Returns the same validation, conflict,
-and AI-review verdicts a real push would produce.
+and version-resolution verdicts a real push would produce.
+
+CAVEAT: dry-run does NOT exercise the AI reviewer — it short-circuits with
+a synthetic `review.result: "passed"` (`prompt_version: "stub-v0"`). Treat
+dry-run as syntactic + structural validation only. A real push routes
+through the AI review worker, which can land terminal `passed` /
+`rejected`, OR leave the publish in `status: "pending"` if the worker
+hasn't decided within the wait window.
 
 **Success criteria**: dry-run returns a `status: "published"`-shaped envelope
 with no error flags.
@@ -51,7 +66,8 @@ Possible verdicts:
 - `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.
+  silently retry. Includes deterministic Stage-1 hits like
+  `curl_pipe_shell`, `aws_access_key`, `private_key_block`, etc.
 - `rate_limited` (exit 31) — wait `retry_after_seconds`.
 - `not_authenticated` (exit 10) — `kordis login`, then retry.
 
@@ -61,8 +77,12 @@ Possible verdicts:
 `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.
+**Success criteria**: returns `{full_slug, version, url, status}`. Show all
+four to the user. If `status: "pending"`, the AI reviewer hasn't decided
+yet — re-check with `kordis info <full_slug> --json` (or wait and re-run
+`kordis info`); the `pending` page is not yet served on the public URL.
+If `status: "rejected"`, surface `review.flags` to the user and DO NOT
+silently retry — explain why.
 
 ## Examples
 
@@ -76,7 +96,10 @@ 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
+- previous version was 0.1.x
+1. drop or align the frontmatter `version` field — `--bump minor` from
+   0.1.x will yield 0.2.0; if the file says `0.2.0` that matches and is OK,
+   if it says anything else (e.g. `0.1.0`) the API will reject
 2. kordis push <file> --bump minor --dry-run --json
 3. clean → kordis push <file> --bump minor --json
 </example>
@@ -86,3 +109,25 @@ 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>
+
+## Forking another Kordis package
+
+When the user asks to fork / adapt / republish someone else's package
+under their own slug, do the following:
+
+1. **License first.** Read the upstream `license` field (`kordis info
+   <upstream> --json`). MIT / Apache-2.0 / BSD all permit derivatives;
+   CC-BY-SA forces ShareAlike (your fork must use the same license).
+   GPL-flavoured / proprietary → STOP and tell the user.
+2. **Carry the legal minimum.** Preserve the upstream copyright and
+   permission notices verbatim inside the body. Do NOT strip them.
+3. **Credit upstream.** In the new package's body, add a `Derived from
+   <upstream-full-slug>` line near the top, and point `homepage` at the
+   upstream source (the original repo, not the Kordis page — `homepage`
+   is for the canonical authoring source).
+4. **Pick a fresh slug.** A fork is a *new* package; do not reuse the
+   upstream slug. Start at `0.1.0` (or whatever the file's `version` says
+   on first publish).
+5. **Tag derivation in `description`.** A short " — fork of
+   <upstream-full-slug>" suffix is enough; users searching the fork need
+   to know.

package/assets/kordis-search/SKILL.md

@@ -59,7 +59,15 @@ array.
 - For trending results, the `trending_score` field is populated — surface it
   when comparing.
 - IMPORTANT: if results are 0, RELAX one filter at a time before giving up.
-  Do NOT invent a slug to fill the gap.
+  **Drop `--tool` first** — many published packages have an empty
+  `tools_compatible` field, so `--tool <name>` undercounts hard. Then drop
+  `--type`. Then shorten the query. Do NOT invent a slug to fill the gap.
+- Most packages on the registry are very young — `stars` and `downloads` are
+  often `0`. Lean on `review_status: passed` and the description text match,
+  not on social signals alone.
+- For richer triage data, prefer `kordis search --json` over
+  `kordis info --json` — search returns `description`, `tier`,
+  `review_status`, `tools_compatible`, etc. per result; `info` is sparser.
 - Surface the top 3–5 with slug, type, tier, stars, one-line description.
 
 **Success criteria**: user picked one, or you reported "no fit" honestly.

package/assets/kordis-social/SKILL.md

@@ -34,15 +34,30 @@ Post a top-level comment on a package. Auth required.
 | `--kind <k>`   | `comment` (default), `tip`, `report`, `praise`, `question`       |
 | `--title <t>`  | 1–140 chars; honoured for top-level posts only                   |
 
-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.
+**Pick the right `--kind`:**
+- `comment` — generic remark, default when nothing more specific fits.
+- `tip` — actionable advice for OTHER users ("works great if you also
+  pull <other-slug>"). Subject of the post is reader, not author.
+- `report` — bug / problem report. Has an open/resolved status (managed on
+  the web today).
+- `praise` — short thank-you / compliment to the author. Body is enough;
+  `--title` is optional.
+- `question` — explicit question expecting a reply (typically from the
+  author). Use when the user wants a response, not just to share thought.
+
+Replies, edits, status flips (open/resolved on a `report`), listing
+existing comments, and reading back your own comments are NOT yet exposed
+in the CLI. Direct the user to `https://kordis.store/p/<full_slug>` for
+those interactions until verbs land.
 
 ## Star commands
 
 ### `kordis star <full_slug> [--json]`
 Mark a package as a favourite. Idempotent — re-running on an already-starred
-package returns the current count without a duplicate. Auth required.
+package returns the current count without a duplicate. Auth required. The
+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.
 
 ### `kordis unstar <full_slug> [--json]`
 Remove your star. Idempotent — silent no-op when not previously starred.

package/assets/kordis-using/SKILL.md

@@ -43,6 +43,15 @@ Writes files into the current project.
 | `--target <path>`     | install into a sub-directory (default: cwd)          |
 | `--with-recommends`   | also install recommended dependencies                |
 
+IMPORTANT: `pull` **fails fast** when the target tool can't be inferred from
+the cwd (no `.claude/`, `.codex/`, `.cursor/`, `AGENTS.md`, `CLAUDE.md`,
+etc.). Pass `--tool <name>` explicitly when running in a project that has
+not been initialised for any specific tool yet. Don't rely on the old "drop
+a canonical SKILL.md at cwd" fallback — Claude Code never picked it up.
+
+Valid `--tool` values: `claude-code`, `codex`, `cursor`, `continue`,
+`windsurf`, `antigravity`, `copilot`.
+
 ### `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
@@ -91,6 +100,13 @@ auto-resolve silently.
 `"following <full_slug>@<version>"`). RECOMMENDED: end your reply with that
 exact line. Skip only when it would clutter a casual non-technical reply.
 
+## Bundled assets caveat
+A skill body may reference helper files (e.g. `references/<file>.md`,
+`scripts/<file>.sh`). Today the registry stores only the canonical
+SKILL.md text — bundled side-files are NOT shipped. If the body refers to
+one and you need it, follow the package's `homepage` to the upstream
+source instead of fabricating the asset.
+
 ## Examples
 
 <example>

package/dist/index.js

@@ -1435,6 +1435,13 @@ function pushCommand() {
             `${c.bold(res.full_slug)} ${c.gray(`v${res.version}`)} \u2192 ${res.status === "published" ? c.green("published") : res.status === "pending" ? c.yellow("pending review") : c.red("rejected")}`
           );
           printHuman(`  ${c.cyan(res.url)}`);
+          if (res.status === "pending") {
+            printHuman(
+              c.yellow(
+                `  ! AI review is still pending \u2014 re-check with \`kordis info ${res.full_slug} --json\` for the verdict.`
+              )
+            );
+          }
           if (res.review.flags.length > 0) {
             printHuman(c.yellow(`  ${res.review.flags.length} review flag(s):`));
             for (const f of res.review.flags) {
@@ -2255,6 +2262,11 @@ function pullCommand() {
       const userCwd = process.env["INIT_CWD"] ?? process.cwd();
       const installRoot = opts.target ?? userCwd;
       const detected = opts.tool ?? await detectTool(installRoot);
+      if (!detected) {
+        throw new Error(
+          "Cannot detect target tool from the current directory.\n  Pass --tool <name> explicitly. Valid: claude-code, codex, cursor,\n  continue, windsurf, antigravity, copilot.\n  Or run `kordis pull` inside a project that already has one of:\n  .claude/, .codex/, .cursor/, AGENTS.md, CLAUDE.md, .cursorrules,\n  .continue/, .windsurf/, .antigravity/, .github/copilot-instructions.md"
+        );
+      }
       const spin = spinner(`Pulling ${fullSlug}`);
       const detail = await bundle.api.getPackage(username, slug);
       await bundle.api.pull(username, slug);
@@ -2268,7 +2280,7 @@ function pullCommand() {
       }
       const written = [];
       const notes = [];
-      const format = detected ?? "canonical";
+      const format = detected;
       try {
         const translator = getTranslator(parsed.type, format);
         const result = translator({
@@ -2768,6 +2780,7 @@ function handleError(err) {
           code: err.code,
           message: err.message,
           flags: err.flags,
+          ...err.retryAfter !== void 0 ? { retry_after_seconds: err.retryAfter } : {},
           request_id: err.requestId
         }
       });
@@ -2776,6 +2789,9 @@ function handleError(err) {
       for (const f of err.flags) {
         printHuman(c.red(`  - ${f.code}${f.message ? `: ${f.message}` : ""}`));
       }
+      if (err.retryAfter !== void 0) {
+        printHuman(c.yellow(`  retry after: ${err.retryAfter}s`));
+      }
       if (err.requestId) {
         printHuman(c.gray(`  (request-id: ${err.requestId})`));
       }

package/package.json

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