@rayul/kordis 0.2.1 → 0.3.0

package/assets/kordis-publishing/SKILL.md

@@ -31,15 +31,22 @@ Publish a valid, AI-review-passing version. ALWAYS dry-run first.
 
 ## Deleting a package
 
-There is **no `kordis delete` CLI command**. Options:
-- Web UI: `https://kordis.store/p/<full_slug>` (if a delete button is available)
-- Registry owner: soft-delete via the prod Postgres
-  (`UPDATE packages SET deleted_at = NOW() WHERE full_slug = '...'`)
-- Workaround: push a new version with `visibility: unlisted` or a
-  deprecation notice in the body
+### `kordis delete <full_slug> [--force]`
 
-If the body contains third-party content, MUST preserve the original copyright
-and license text inside the body and link to source via `homepage`.
+Soft-deletes a package you own. Removes from search / info / read /
+pull. The slug is **permanently reserved** after deletion (supply-chain
+safety) — it cannot be reused even by you. There is **no CLI undo**;
+the registry operator can restore from the soft-delete row if asked.
+
+Without `--force` the CLI shows the package metadata and prompts for
+confirmation. Use `--force` ONLY when the user has explicitly confirmed
+the destructive action (e.g. they said "yes, delete it"). Never pass
+`--force` on the user's behalf.
+
+If the body contains third-party content, MUST preserve the original
+copyright and license text inside the body and link to source via
+`homepage` — even on the version you intend to delete, in case the
+operator restores it.
 
 ## Commands
 
@@ -122,6 +129,15 @@ User: "release with a note that breaking-changes the API"
 2. clean → drop --dry-run for the real push
 </example>
 
+<example>
+User: "delete <full_slug>"
+1. confirm with the user that they understand the slug is permanently
+   reserved (cannot be reused) and there is no CLI undo
+2. kordis delete <full_slug>   # interactive confirmation prompt
+   - if user already confirmed in prior turn, kordis delete <full_slug> --force
+3. show the {status, full_slug} reply to the user
+</example>
+
 ## Forking another Kordis package
 
 When the user asks to fork / adapt / republish someone else's package

package/dist/index.js

@@ -631,7 +631,17 @@ var init_api = __esm({
        * KORDIS.md recommends but does not enforce.
        */
       attribution: z9.string(),
-      read_at: z9.string().datetime({ offset: true })
+      read_at: z9.string().datetime({ offset: true }),
+      /**
+       * Paths (NOT contents) of bundled assets that ship with the package —
+       * `references/*.md`, `assets/*.html`, `scripts/*.py`, etc. Agents reading a
+       * skill that references its own bundled files (e.g. "use
+       * `assets/template.html`") need a structured signal to switch to
+       * `kordis pull`; without it, the only hint is in body prose. Optional in
+       * the schema for backwards compatibility with pre-0.2.3 servers; the
+       * current server always populates it (empty array when no assets).
+       */
+      bundled_assets: z9.array(z9.string()).optional()
     });
     PullPackageResponseSchema = z9.object({
       status: z9.enum(["installed", "already_installed", "skipped"]),
@@ -1041,7 +1051,7 @@ async function saveCliConfig(cfg) {
 }
 
 // src/keychain.ts
-import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, unlink } from "fs/promises";
+import { access, readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, unlink } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
 var SERVICE = "kordis";
@@ -1054,12 +1064,28 @@ async function loadKeytar() {
     return null;
   }
 }
+function kordisHome() {
+  return process.env["KORDIS_HOME"] ?? join2(homedir2(), ".kordis");
+}
 function fallbackPath() {
-  return join2(process.env["KORDIS_HOME"] ?? join2(homedir2(), ".kordis"), ".tokens.json");
+  return join2(kordisHome(), ".tokens.json");
+}
+function warningSentinelPath() {
+  return join2(kordisHome(), ".warned-no-keychain");
+}
+async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
 }
 async function createKeychain() {
   const keytar = await loadKeytar();
   if (keytar) {
+    await unlink(warningSentinelPath()).catch(() => {
+    });
     return {
       async save(username, tokens) {
         await keytar.setPassword(SERVICE, username, JSON.stringify(tokens));
@@ -1073,15 +1099,22 @@ async function createKeychain() {
       }
     };
   }
-  if (!plaintextWarningEmitted && process.env["KORDIS_JSON"] !== "1") {
+  if (!plaintextWarningEmitted && process.env["KORDIS_JSON"] !== "1" && !await pathExists(warningSentinelPath())) {
     plaintextWarningEmitted = true;
     const yellow = "\x1B[33m";
     const reset = "\x1B[0m";
     process.stderr.write(
       `${yellow}[kordis] WARNING: OS keychain unavailable; falling back to plaintext token storage at ~/.kordis/.tokens.json (mode 0600).
-[kordis] On macOS install Xcode Command Line Tools, on Linux install libsecret-1-dev to enable keytar.${reset}
+[kordis] On macOS install Xcode Command Line Tools, on Linux install libsecret-1-dev to enable keytar.
+[kordis] (suppressing this warning on subsequent runs \u2014 delete ~/.kordis/.warned-no-keychain to re-enable)${reset}
 `
     );
+    await mkdir2(kordisHome(), { recursive: true }).catch(() => {
+    });
+    await writeFile2(warningSentinelPath(), "", { mode: 384 }).catch(() => {
+    });
+  } else if (!plaintextWarningEmitted) {
+    plaintextWarningEmitted = true;
   }
   const store = await readAll();
   return {
@@ -1342,11 +1375,31 @@ function searchCommand() {
         limit: opts.limit
       });
     }
+    const queryProvided = query.length > 0;
     printDual({
       json: res,
       human: () => {
         if (res.results.length === 0) {
           printHuman(c.yellow("(no results)"));
+          if (opts.type) {
+            printHuman(
+              c.gray(
+                `  \u2192 no packages of type "${opts.type}" match. Try without --type, or list everything: kordis search --type ${opts.type} --sort recent --limit 25`
+              )
+            );
+          } else if (queryProvided) {
+            printHuman(
+              c.gray(
+                "  \u2192 try `--type skill` (or mcp-server / project-rules / custom-agent / hook) to narrow, or broader keywords"
+              )
+            );
+          } else {
+            printHuman(
+              c.gray(
+                '  \u2192 try keywords (e.g. `kordis search "topic"`) or `kordis search --trending`'
+              )
+            );
+          }
           return;
         }
         for (const p of res.results) {
@@ -1368,6 +1421,13 @@ function searchCommand() {
         if (res.next_cursor) {
           printHuman(c.gray(`(more available \u2014 pass --cursor ${res.next_cursor})`));
         }
+        if (queryProvided && !opts.type && res.results.length > 3) {
+          printHuman(
+            c.gray(
+              "  \u2192 narrow further with `--type skill|mcp-server|project-rules|custom-agent|hook`"
+            )
+          );
+        }
       }
     });
   });
@@ -1427,210 +1487,6 @@ var FrontmatterParseError = class extends Error {
   }
 };
 
-// src/commands/push.ts
-function pushCommand() {
-  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option(
-    "--slug <slug>",
-    'override slug; accepts "user/slug" to point at a specific package'
-  ).option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").action(
-    async (path, opts) => {
-      const bundle = await useClient();
-      const abs = resolve(process.cwd(), path);
-      const s = await stat(abs);
-      let content;
-      let assets = [];
-      if (s.isDirectory()) {
-        ({ content, assets } = await bundleDirectory(abs));
-        content = ensureTypeField(content, "skill");
-      } else if (abs.endsWith(".skill")) {
-        ({ content, assets } = await bundleSkillZip(abs));
-        content = ensureTypeField(content, "skill");
-      } else {
-        content = await readFile3(abs, "utf8");
-      }
-      let nameFromFm = null;
-      try {
-        const fm = parseFrontmatter(content).frontmatter ?? {};
-        const v = fm["name"];
-        if (typeof v === "string") nameFromFm = v;
-      } catch (err) {
-        throw err instanceof Error ? err : new Error(String(err));
-      }
-      let targetUser = null;
-      let targetSlug = null;
-      if (opts.slug && opts.slug.includes("/")) {
-        const [u, s2] = opts.slug.split("/", 2);
-        if (u && s2) {
-          targetUser = u;
-          targetSlug = s2;
-        }
-      } else {
-        if (bundle.username && (opts.slug || nameFromFm)) {
-          targetUser = bundle.username;
-          targetSlug = opts.slug ?? nameFromFm;
-        }
-      }
-      let targetFullSlug;
-      if (targetUser && targetSlug) {
-        try {
-          await bundle.api.getPackage(targetUser, targetSlug);
-          targetFullSlug = `${targetUser}/${targetSlug}`;
-        } catch (err) {
-          if (err instanceof KordisApiError && err.code === "not_found") {
-            targetFullSlug = void 0;
-          } else if (!(err instanceof KordisApiError)) {
-            throw err;
-          }
-        }
-      }
-      const spin = spinner(
-        opts.dryRun ? "Validating" : targetFullSlug ? `Publishing update to ${targetFullSlug}` : "Publishing"
-      );
-      const res = await bundle.authedRequest(
-        (api) => api.publish(
-          {
-            content,
-            assets: assets.length > 0 ? assets : void 0,
-            bump: opts.bump,
-            slug: opts.slug && !opts.slug.includes("/") ? opts.slug : void 0,
-            target_full_slug: targetFullSlug,
-            type: opts.type,
-            changelog: opts.changelog,
-            dry_run: !!opts.dryRun
-          },
-          {
-            waitForReviewMs: opts.wait === false ? 0 : 3e3
-          }
-        )
-      );
-      spin.succeed();
-      printDual({
-        json: res,
-        human: () => {
-          printHuman(
-            `${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")}`
-          );
-          if (assets.length > 0) {
-            printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
-          }
-          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) {
-              printHuman(c.yellow(`    - ${f.code}${f.message ? `: ${f.message}` : ""}`));
-            }
-          }
-        }
-      });
-    }
-  );
-}
-function ensureTypeField(content, defaultType) {
-  const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
-  if (!fmMatch) return content;
-  const fmBlock = fmMatch[1];
-  if (/^type\s*:/m.test(fmBlock)) return content;
-  const injected = fmMatch[0].replace(/^---\r?\n/, `---
-type: ${defaultType}
-`);
-  return content.replace(fmMatch[0], injected);
-}
-var EXCLUDE_NAMES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
-var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", ".git", "evals", "dist", ".turbo"]);
-var EXCLUDE_EXTS = /* @__PURE__ */ new Set([".pyc", ".pyo", ".rbc"]);
-function shouldExclude(relPath, isDir) {
-  const parts = relPath.split(posix.sep);
-  const name = parts[parts.length - 1];
-  if (EXCLUDE_NAMES.has(name)) return true;
-  if (isDir && EXCLUDE_DIRS.has(name)) return true;
-  const ext = name.includes(".") ? "." + name.split(".").pop() : "";
-  if (EXCLUDE_EXTS.has(ext)) return true;
-  return false;
-}
-async function walkDir(base, relDir, collected) {
-  const entries = await readdir(join4(base, relDir), { withFileTypes: true });
-  for (const entry of entries) {
-    const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
-    if (shouldExclude(rel, entry.isDirectory())) continue;
-    if (entry.isDirectory()) {
-      await walkDir(base, rel, collected);
-    } else if (entry.isFile()) {
-      collected.push({ rel, abs: join4(base, rel) });
-    }
-  }
-}
-async function readAsset(absPath) {
-  const buf = await readFile3(absPath);
-  const text = buf.toString("utf8");
-  const roundtrip = Buffer.from(text, "utf8");
-  if (roundtrip.equals(buf)) {
-    return { content: text, encoding: "utf8" };
-  }
-  const b64 = buf.toString("base64");
-  printHuman(c.gray(`  \u2192 encoding ${absPath.split(sep).pop()} as base64`));
-  return { content: b64, encoding: "base64" };
-}
-async function bundleDirectory(dir) {
-  const all = [];
-  await walkDir(dir, "", all);
-  const skillEntry = all.find((f) => f.rel === "SKILL.md");
-  if (!skillEntry) {
-    throw new Error(`No SKILL.md found in directory ${dir}. Push a directory that has SKILL.md at its root.`);
-  }
-  const content = await readFile3(skillEntry.abs, "utf8");
-  const assets = [];
-  for (const f of all) {
-    if (f.rel === "SKILL.md") continue;
-    const { content: fc, encoding } = await readAsset(f.abs);
-    assets.push({ path: f.rel, content: fc, encoding });
-  }
-  return { content, assets };
-}
-async function bundleSkillZip(zipPath) {
-  const buf = await readFile3(zipPath);
-  const zip = await JSZip.loadAsync(buf);
-  const entries = Object.keys(zip.files).filter((k) => !zip.files[k].dir);
-  if (entries.length === 0) throw new Error(".skill file is empty");
-  const firstParts = entries[0].split("/");
-  const prefix = firstParts.length > 1 ? firstParts[0] + "/" : "";
-  const stripped = entries.map((k) => ({
-    zipKey: k,
-    rel: prefix ? k.slice(prefix.length) : k
-  })).filter((f) => f.rel.length > 0 && !shouldExclude(f.rel, false));
-  const skillEntry = stripped.find((f) => f.rel === "SKILL.md");
-  if (!skillEntry) {
-    throw new Error(`.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`);
-  }
-  const content = await zip.files[skillEntry.zipKey].async("string");
-  const assets = [];
-  for (const f of stripped) {
-    if (f.rel === "SKILL.md") continue;
-    const rawBuf = await zip.files[f.zipKey].async("uint8array");
-    const buf2 = Buffer.from(rawBuf);
-    const text = buf2.toString("utf8");
-    const roundtrip = Buffer.from(text, "utf8");
-    if (roundtrip.equals(buf2)) {
-      assets.push({ path: f.rel, content: text, encoding: "utf8" });
-    } else {
-      printHuman(c.gray(`  \u2192 encoding ${f.rel} as base64`));
-      assets.push({ path: f.rel, content: buf2.toString("base64"), encoding: "base64" });
-    }
-  }
-  return { content, assets };
-}
-
-// src/commands/pull.ts
-import { Command as Command5 } from "commander";
-import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname2, join as join6 } from "path";
-
 // ../../packages/harness-schema/src/deps.ts
 init_src();
 import { z as z10 } from "zod";
@@ -2105,6 +1961,312 @@ function zodFail(issues) {
     })
   };
 }
+var ASSET_MAX_COUNT = 50;
+var SAFE_PATH_RE = /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/;
+function isAssetPathSafe(p) {
+  if (!SAFE_PATH_RE.test(p)) return false;
+  return !p.split("/").some((seg) => seg === "..");
+}
+function validateAssets(assets) {
+  const flags = [];
+  if (assets.length > ASSET_MAX_COUNT) {
+    flags.push(
+      flag("too_many_assets", `bundle has ${assets.length} files (max ${ASSET_MAX_COUNT})`, {
+        hint: `Bundle has more than ${ASSET_MAX_COUNT} files. Trim demos or move large reference material to an external Git repo.`
+      })
+    );
+    return { ok: false, flags };
+  }
+  for (const asset of assets) {
+    if (!isAssetPathSafe(asset.path)) {
+      flags.push(
+        flag("asset_path_unsafe", `unsafe asset path: "${asset.path}"`, {
+          field: "assets",
+          hint: 'Asset paths must be relative POSIX, no leading "/", no "..". Example: scripts/run.sh'
+        })
+      );
+    }
+  }
+  return { ok: flags.length === 0, flags };
+}
+
+// src/commands/push.ts
+var ASSET_MAX_BYTES = 2 * 1024 * 1024;
+var BUNDLE_MAX_BYTES = 5 * 1024 * 1024;
+function pushCommand() {
+  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option(
+    "--slug <slug>",
+    'override slug; accepts "user/slug" to point at a specific package'
+  ).option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").action(
+    async (path, opts) => {
+      const bundle = await useClient();
+      const abs = resolve(process.cwd(), path);
+      const s = await stat(abs);
+      let content;
+      let assets = [];
+      if (s.isDirectory()) {
+        ({ content, assets } = await bundleDirectory(abs));
+        content = ensureTypeField(content, "skill");
+      } else if (abs.endsWith(".skill")) {
+        ({ content, assets } = await bundleSkillZip(abs));
+        content = ensureTypeField(content, "skill");
+      } else {
+        content = await readFile3(abs, "utf8");
+      }
+      let nameFromFm = null;
+      try {
+        const fm = parseFrontmatter(content).frontmatter ?? {};
+        const v = fm["name"];
+        if (typeof v === "string") nameFromFm = v;
+      } catch (err) {
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+      if (opts.dryRun) {
+        await runDryRun({ content, assets });
+        return;
+      }
+      let targetUser = null;
+      let targetSlug = null;
+      if (opts.slug && opts.slug.includes("/")) {
+        const [u, s2] = opts.slug.split("/", 2);
+        if (u && s2) {
+          targetUser = u;
+          targetSlug = s2;
+        }
+      } else {
+        if (bundle.username && (opts.slug || nameFromFm)) {
+          targetUser = bundle.username;
+          targetSlug = opts.slug ?? nameFromFm;
+        }
+      }
+      let targetFullSlug;
+      if (targetUser && targetSlug) {
+        try {
+          await bundle.api.getPackage(targetUser, targetSlug);
+          targetFullSlug = `${targetUser}/${targetSlug}`;
+        } catch (err) {
+          if (err instanceof KordisApiError && err.code === "not_found") {
+            targetFullSlug = void 0;
+          } else if (!(err instanceof KordisApiError)) {
+            throw err;
+          }
+        }
+      }
+      const spin = spinner(
+        opts.dryRun ? "Validating" : targetFullSlug ? `Publishing update to ${targetFullSlug}` : "Publishing"
+      );
+      const res = await bundle.authedRequest(
+        (api) => api.publish(
+          {
+            content,
+            assets: assets.length > 0 ? assets : void 0,
+            bump: opts.bump,
+            slug: opts.slug && !opts.slug.includes("/") ? opts.slug : void 0,
+            target_full_slug: targetFullSlug,
+            type: opts.type,
+            changelog: opts.changelog,
+            dry_run: !!opts.dryRun
+          },
+          {
+            waitForReviewMs: opts.wait === false ? 0 : 3e3
+          }
+        )
+      );
+      spin.succeed();
+      printDual({
+        json: res,
+        human: () => {
+          printHuman(
+            `${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")}`
+          );
+          if (assets.length > 0) {
+            printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
+          }
+          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) {
+              printHuman(c.yellow(`    - ${f.code}${f.message ? `: ${f.message}` : ""}`));
+            }
+          }
+        }
+      });
+    }
+  );
+}
+function checkAssetSizesLocal(assets) {
+  const flags = [];
+  let totalBytes = 0;
+  for (const asset of assets) {
+    const byteLen = asset.encoding === "base64" ? Math.ceil(asset.content.length * 3 / 4) : Buffer.byteLength(asset.content, "utf8");
+    if (byteLen > ASSET_MAX_BYTES) {
+      flags.push({
+        code: "asset_too_large",
+        message: `asset "${asset.path}" is ${byteLen} bytes (max ${ASSET_MAX_BYTES})`,
+        hint: `Single asset exceeds the ${ASSET_MAX_BYTES / 1024 / 1024} MB per-file cap. Trim or move large fixtures to an external Git repo.`
+      });
+    }
+    totalBytes += byteLen;
+  }
+  if (totalBytes > BUNDLE_MAX_BYTES) {
+    flags.push({
+      code: "bundle_too_large",
+      message: `bundle totals ${totalBytes} bytes (max ${BUNDLE_MAX_BYTES})`,
+      hint: `Total bundle exceeds ${BUNDLE_MAX_BYTES / 1024 / 1024} MB. Remove generated artifacts; check .gitignore parity.`
+    });
+  }
+  return flags;
+}
+async function runDryRun(args) {
+  const { content, assets } = args;
+  const v = validatePackageSource(content);
+  const assetPathResult = assets.length > 0 ? validateAssets(assets) : { ok: true, flags: [] };
+  const sizeFlags = checkAssetSizesLocal(assets);
+  const allFlags = [...v.flags, ...assetPathResult.flags, ...sizeFlags];
+  const ok = v.ok && assetPathResult.ok && sizeFlags.length === 0;
+  printDual({
+    json: {
+      status: ok ? "dry_run_passed" : "dry_run_failed",
+      type: v.type,
+      tier: v.tier,
+      capabilities: v.capabilities,
+      asset_count: assets.length,
+      flags: allFlags,
+      note: "dry-run validates frontmatter + asset paths/sizes locally; AI review (real publish only) is not performed"
+    },
+    human: () => {
+      if (ok) {
+        printHuman(c.green("\u2713 dry-run validation passed"));
+        if (v.type) printHuman(c.gray(`  type: ${v.type} (tier ${v.tier})`));
+        if (v.capabilities) {
+          printHuman(
+            c.gray(
+              `  capabilities: jit_eligible=${v.capabilities.jit_eligible} executable=${v.capabilities.executable}`
+            )
+          );
+        }
+        if (assets.length > 0) printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
+        printHuman(
+          c.gray("  (AI review only runs on the real push; not performed here)")
+        );
+        return;
+      }
+      printHuman(c.red(`\u2717 dry-run validation failed (${allFlags.length} flag(s))`));
+      for (const f of allFlags) {
+        printHuman(c.red(`  - ${f.code}${f.message ? `: ${f.message}` : ""}`));
+        if (f.hint) {
+          for (const line of f.hint.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
+        }
+      }
+    }
+  });
+  if (!ok) process.exit(30);
+}
+function ensureTypeField(content, defaultType) {
+  const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  if (!fmMatch) return content;
+  const fmBlock = fmMatch[1];
+  if (/^type\s*:/m.test(fmBlock)) return content;
+  const injected = fmMatch[0].replace(/^---\r?\n/, `---
+type: ${defaultType}
+`);
+  return content.replace(fmMatch[0], injected);
+}
+var EXCLUDE_NAMES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
+var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", ".git", "evals", "dist", ".turbo"]);
+var EXCLUDE_EXTS = /* @__PURE__ */ new Set([".pyc", ".pyo", ".rbc"]);
+function shouldExclude(relPath, isDir) {
+  const parts = relPath.split(posix.sep);
+  const name = parts[parts.length - 1];
+  if (EXCLUDE_NAMES.has(name)) return true;
+  if (isDir && EXCLUDE_DIRS.has(name)) return true;
+  const ext = name.includes(".") ? "." + name.split(".").pop() : "";
+  if (EXCLUDE_EXTS.has(ext)) return true;
+  return false;
+}
+async function walkDir(base, relDir, collected) {
+  const entries = await readdir(join4(base, relDir), { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+    if (shouldExclude(rel, entry.isDirectory())) continue;
+    if (entry.isDirectory()) {
+      await walkDir(base, rel, collected);
+    } else if (entry.isFile()) {
+      collected.push({ rel, abs: join4(base, rel) });
+    }
+  }
+}
+async function readAsset(absPath) {
+  const buf = await readFile3(absPath);
+  const text = buf.toString("utf8");
+  const roundtrip = Buffer.from(text, "utf8");
+  if (roundtrip.equals(buf)) {
+    return { content: text, encoding: "utf8" };
+  }
+  const b64 = buf.toString("base64");
+  printHuman(c.gray(`  \u2192 encoding ${absPath.split(sep).pop()} as base64`));
+  return { content: b64, encoding: "base64" };
+}
+async function bundleDirectory(dir) {
+  const all = [];
+  await walkDir(dir, "", all);
+  const skillEntry = all.find((f) => f.rel === "SKILL.md");
+  if (!skillEntry) {
+    throw new Error(`No SKILL.md found in directory ${dir}. Push a directory that has SKILL.md at its root.`);
+  }
+  const content = await readFile3(skillEntry.abs, "utf8");
+  const assets = [];
+  for (const f of all) {
+    if (f.rel === "SKILL.md") continue;
+    const { content: fc, encoding } = await readAsset(f.abs);
+    assets.push({ path: f.rel, content: fc, encoding });
+  }
+  return { content, assets };
+}
+async function bundleSkillZip(zipPath) {
+  const buf = await readFile3(zipPath);
+  const zip = await JSZip.loadAsync(buf);
+  const entries = Object.keys(zip.files).filter((k) => !zip.files[k].dir);
+  if (entries.length === 0) throw new Error(".skill file is empty");
+  const firstParts = entries[0].split("/");
+  const prefix = firstParts.length > 1 ? firstParts[0] + "/" : "";
+  const stripped = entries.map((k) => ({
+    zipKey: k,
+    rel: prefix ? k.slice(prefix.length) : k
+  })).filter((f) => f.rel.length > 0 && !shouldExclude(f.rel, false));
+  const skillEntry = stripped.find((f) => f.rel === "SKILL.md");
+  if (!skillEntry) {
+    throw new Error(`.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`);
+  }
+  const content = await zip.files[skillEntry.zipKey].async("string");
+  const assets = [];
+  for (const f of stripped) {
+    if (f.rel === "SKILL.md") continue;
+    const rawBuf = await zip.files[f.zipKey].async("uint8array");
+    const buf2 = Buffer.from(rawBuf);
+    const text = buf2.toString("utf8");
+    const roundtrip = Buffer.from(text, "utf8");
+    if (roundtrip.equals(buf2)) {
+      assets.push({ path: f.rel, content: text, encoding: "utf8" });
+    } else {
+      printHuman(c.gray(`  \u2192 encoding ${f.rel} as base64`));
+      assets.push({ path: f.rel, content: buf2.toString("base64"), encoding: "base64" });
+    }
+  }
+  return { content, assets };
+}
+
+// src/commands/pull.ts
+import { Command as Command5 } from "commander";
+import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname2, join as join6 } from "path";
 
 // ../../packages/translators/src/skill/identity.ts
 function buildSkillFile(input, outputPath) {
@@ -2733,6 +2895,17 @@ function readCommand() {
       }
       process.stdout.write(res.body);
       if (!res.body.endsWith("\n")) process.stdout.write("\n");
+      const bundled = res.bundled_assets ?? [];
+      if (bundled.length > 0) {
+        process.stderr.write(
+          `${c.gray("\u2014")} ${c.bold(`\u24D8 ${bundled.length} bundled asset(s)`)} \u2014 fetch with ${c.cyan(`kordis pull ${res.full_slug}`)}:
+`
+        );
+        for (const path of bundled) {
+          process.stderr.write(`    ${c.gray("-")} ${path}
+`);
+        }
+      }
       process.stderr.write(
         `${c.gray("\u2014")} ${c.bold(res.full_slug)}${c.gray("@")}${res.version} ${c.gray("\xB7")} ${res.type} (tier ${res.tier}) ${c.gray("\xB7")} ${c.cyan(res.attribution)}
 `
@@ -2815,7 +2988,7 @@ function logoutCommand() {
 }
 
 // src/commands/setup.ts
-import { readFile as readFile5, writeFile as writeFile5, mkdir as mkdir5, access } from "fs/promises";
+import { readFile as readFile5, writeFile as writeFile5, mkdir as mkdir5, access as access2 } from "fs/promises";
 import { homedir as homedir4 } from "os";
 import { join as join7, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -2840,7 +3013,7 @@ var SKILL_TARGETS = [
 ];
 async function exists(path) {
   try {
-    await access(path);
+    await access2(path);
     return true;
   } catch {
     return false;
@@ -3290,6 +3463,11 @@ function outdatedCommand() {
         const outdatedCount = entries.filter((e) => e.outdated).length;
         if (outdatedCount === 0) {
           printHuman(c.green(`\u2713 All ${entries.length} package${entries.length !== 1 ? "s" : ""} are up to date`));
+          printHuman(
+            c.gray(
+              "  \u2192 bundled Kordis sub-skills update with the CLI: `npm i -g @rayul/kordis@latest`"
+            )
+          );
           return;
         }
         printHuman(
@@ -3305,6 +3483,11 @@ function outdatedCommand() {
         }
         printHuman("");
         printHuman(c.gray("Run `kordis update` to upgrade all outdated packages."));
+        printHuman(
+          c.gray(
+            "  \u2192 only `kordis pull`-installed packages are tracked here. Bundled sub-skills update via `npm i -g @rayul/kordis@latest`."
+          )
+        );
       }
     });
   });

package/package.json

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