@rayul/kordis 0.3.1 → 0.5.0

package/dist/index.js

@@ -704,6 +704,123 @@ var init_api = __esm({
   }
 });
 
+// ../../packages/contracts/src/context.ts
+import { z as z10 } from "zod";
+var KordisContextSchema, CONTEXT_HEADER_MAX_BYTES, CONTEXT_HEADER_NAME;
+var init_context = __esm({
+  "../../packages/contracts/src/context.ts"() {
+    "use strict";
+    init_primitives();
+    KordisContextSchema = z10.object({
+      /**
+       * Which agentic tool configs exist locally. Presence only — no file
+       * contents inspected. Used to boost packages whose `tools_compatible`
+       * overlaps.
+       */
+      tools: z10.array(ToolSlugSchema).max(8).optional(),
+      /**
+       * Top-3 file extensions in CWD (excluding `.git`, `node_modules`,
+       * `dist`, `.next`, build artifacts). Each entry is a short lowercase
+       * tag like `ts`, `py`, `rs`, `go`.
+       */
+      languages: z10.array(z10.string().min(1).max(8)).max(3).optional(),
+      /**
+       * Frameworks detected from `package.json` deps, `pyproject.toml`,
+       * `Cargo.toml`, `go.mod`. Curated allowlist on the collector side
+       * (next, react, vue, svelte, fastapi, django, fastify, hono, ...).
+       */
+      frameworks: z10.array(z10.string().min(1).max(32)).max(8).optional(),
+      /**
+       * SHA-256 first-8-chars (lowercase hex) of each `full_slug` in the
+       * user's `~/.kordis/installed.json`. The server uses these to find
+       * co-pull patterns WITHOUT learning which slugs the user has installed
+       * (one-way hash, prefix-truncated, still anonymises across the small
+       * registry universe). Max 50 entries.
+       */
+      installed_slugs_hash: z10.array(z10.string().regex(/^[0-9a-f]{8}$/)).max(50).optional()
+    });
+    CONTEXT_HEADER_MAX_BYTES = 1024;
+    CONTEXT_HEADER_NAME = "X-Kordis-Context";
+  }
+});
+
+// ../../packages/contracts/src/recommend.ts
+import { z as z11 } from "zod";
+var RecommendQuerySchema, RecommendConfidenceSchema, RecommendScoreBreakdownSchema, RecommendMenuItemSchema, RecommendResponseSchema;
+var init_recommend = __esm({
+  "../../packages/contracts/src/recommend.ts"() {
+    "use strict";
+    init_primitives();
+    init_enums();
+    RecommendQuerySchema = z11.object({
+      limit: z11.coerce.number().int().positive().max(50).default(10),
+      /**
+       * Include score_breakdown in the response. CLI sets when --verbose.
+       *
+       * NOT `z.coerce.boolean()` — that wraps `Boolean()` which treats the
+       * literal string `"false"` as truthy (non-empty string). Use explicit
+       * string-vs-true matching so URL query `?verbose=false` evaluates as
+       * `false`.
+       */
+      verbose: z11.union([z11.boolean(), z11.enum(["true", "false"])]).transform((v) => v === true || v === "true").optional().default(false)
+    });
+    RecommendConfidenceSchema = z11.enum(["low", "medium", "high"]);
+    RecommendScoreBreakdownSchema = z11.object({
+      content: z11.number(),
+      cf: z11.number(),
+      popularity: z11.number(),
+      final: z11.number()
+    });
+    RecommendMenuItemSchema = z11.object({
+      full_slug: FullSlugSchema,
+      title: z11.string(),
+      description: z11.string(),
+      type: HarnessTypeSchema,
+      tier: TierSchema,
+      current_version: SemverSchema,
+      stars: z11.number().int().nonnegative(),
+      downloads: z11.number().int().nonnegative(),
+      /** Ready-to-execute install command. Always populated. */
+      install_command: z11.string(),
+      /** Ready-to-execute JIT-read command. Always populated; agent decides which to use. */
+      jit_read_command: z11.string(),
+      /**
+       * One-line rationale derived from the strongest scoring signal. E.g.
+       * "You have FastAPI installed; this adds streaming middleware" or
+       * "Trending in your tool's ecosystem this week".
+       */
+      why_recommended: z11.string(),
+      confidence: RecommendConfidenceSchema,
+      /** Present only when the request specified `verbose=true`. */
+      score_breakdown: RecommendScoreBreakdownSchema.optional()
+    });
+    RecommendResponseSchema = z11.object({
+      items: z11.array(RecommendMenuItemSchema),
+      generated_at: IsoDateTimeSchema,
+      /**
+       * Whether personalization context arrived with the request. False means
+       * the server returned popularity-only results — useful for agents to
+       * disclose "context off → less personalised" to the user.
+       */
+      personalized: z11.boolean(),
+      /**
+       * 0.5.0 — number of additional candidates the server had before applying
+       * the per-author cap. When `capped_by_author > 0`, the agent can explain
+       * "menu is shorter than --limit because diversity cap fired" instead of
+       * the user inferring the registry is sparse. Absent on responses from
+       * pre-0.5.0 servers.
+       */
+      capped_by_author: z11.number().int().nonnegative().optional(),
+      /**
+       * 0.5.0 — total number of candidates the server scored before any
+       * trimming/capping. Helps the agent surface "we picked N of M" honesty
+       * when the menu is short. Absent on pre-0.5.0 servers.
+       */
+      total_candidates: z11.number().int().nonnegative().optional()
+    });
+  }
+});
+
 // ../../packages/contracts/src/index.ts
 var init_src = __esm({
   "../../packages/contracts/src/index.ts"() {
@@ -717,6 +834,8 @@ var init_src = __esm({
     init_comment();
     init_auth();
     init_api();
+    init_context();
+    init_recommend();
   }
 });
 
@@ -797,6 +916,7 @@ var init_client = __esm({
         const headers = {
           accept: "application/json",
           ...await this.authHeaders(),
+          ...this.config.getDynamicHeaders ? await this.config.getDynamicHeaders() : {},
           ...opts.headers ?? {}
         };
         if (opts.body !== void 0) headers["content-type"] = "application/json";
@@ -936,6 +1056,20 @@ var init_client = __esm({
       popular() {
         return this.request("/api/packages/popular");
       }
+      /**
+       * Hybrid recommendations (0.4.0+). The personalization signal rides on
+       * the `X-Kordis-Context` header (injected by `getDynamicHeaders`), not in
+       * the query string. Anonymous is fine — server falls back to
+       * popularity-only with `confidence: 'low'`.
+       */
+      recommend(opts = {}) {
+        return this.request("/api/packages/recommend", {
+          query: {
+            ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+            ...opts.verbose !== void 0 ? { verbose: opts.verbose } : {}
+          }
+        });
+      }
       star(username, slug) {
         return this.request(`/api/packages/${username}/${slug}/star`, {
           method: "POST"
@@ -1015,7 +1149,7 @@ var init_src2 = __esm({
 
 // src/index.ts
 init_src2();
-import { Command as Command18 } from "commander";
+import { Command as Command19 } from "commander";
 
 // src/commands/login.ts
 import { Command } from "commander";
@@ -1023,6 +1157,7 @@ import open from "open";
 
 // src/client.ts
 init_src2();
+init_src();
 
 // src/config.ts
 import { homedir } from "os";
@@ -1042,7 +1177,8 @@ async function loadCliConfig() {
     return {
       apiUrl: apiUrlFromEnv ?? parsed.apiUrl ?? "https://api.kordis.store",
       ...parsed.username ? { username: parsed.username } : {},
-      ...parsed.sessionId ? { sessionId: parsed.sessionId } : {}
+      ...parsed.sessionId ? { sessionId: parsed.sessionId } : {},
+      personalization: parsed.personalization ?? "undecided"
     };
   } catch {
     return { apiUrl: apiUrlFromEnv ?? "https://api.kordis.store" };
@@ -1149,12 +1285,236 @@ async function readAll() {
   }
 }
 
+// src/context/collector.ts
+init_src();
+import { access as access2, readFile as readFile3, readdir, stat } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { join as join3, extname } from "path";
+import { createHash } from "crypto";
+async function pathExists2(p) {
+  try {
+    await access2(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectTools() {
+  const checks = [
+    { tool: "claude-code", paths: [join3(homedir3(), ".claude", "skills")] },
+    { tool: "codex", paths: [join3(homedir3(), ".codex"), join3(homedir3(), ".codex", "skills")] },
+    { tool: "cursor", paths: [join3(homedir3(), ".cursor")] },
+    { tool: "gemini-cli", paths: [join3(homedir3(), ".gemini"), join3(homedir3(), ".gemini", "skills")] }
+  ];
+  const found = [];
+  for (const { tool, paths } of checks) {
+    for (const p of paths) {
+      if (await pathExists2(p)) {
+        found.push(tool);
+        break;
+      }
+    }
+  }
+  return found;
+}
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  "target",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".cache",
+  ".turbo"
+]);
+var EXT_TO_TAG = {
+  ".ts": "ts",
+  ".tsx": "ts",
+  ".js": "js",
+  ".jsx": "js",
+  ".mjs": "js",
+  ".cjs": "js",
+  ".py": "py",
+  ".rs": "rs",
+  ".go": "go",
+  ".rb": "rb",
+  ".java": "java",
+  ".kt": "kt",
+  ".swift": "swift",
+  ".c": "c",
+  ".cpp": "cpp",
+  ".cc": "cpp",
+  ".h": "c",
+  ".cs": "cs",
+  ".php": "php",
+  ".lua": "lua",
+  ".r": "r",
+  ".sh": "sh",
+  ".zsh": "sh",
+  ".bash": "sh",
+  ".sql": "sql",
+  ".html": "html",
+  ".css": "css",
+  ".scss": "scss"
+};
+async function detectLanguages(cwd = process.cwd()) {
+  const counts = /* @__PURE__ */ new Map();
+  await walk(cwd, 4, counts);
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([tag]) => tag);
+}
+async function walk(dir, depth, counts) {
+  if (depth < 0) return;
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".") && e.name !== "." && e.name !== "..") {
+      if (SKIP_DIRS.has(e.name)) continue;
+    }
+    if (SKIP_DIRS.has(e.name)) continue;
+    const full = join3(dir, e.name);
+    if (e.isDirectory()) {
+      await walk(full, depth - 1, counts);
+    } else if (e.isFile()) {
+      const tag = EXT_TO_TAG[extname(e.name).toLowerCase()];
+      if (tag) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+  }
+}
+var FRAMEWORK_ALLOWLIST = /* @__PURE__ */ new Set([
+  "next",
+  "react",
+  "vue",
+  "svelte",
+  "angular",
+  "solid",
+  "fastapi",
+  "django",
+  "flask",
+  "rails",
+  "fastify",
+  "hono",
+  "express",
+  "nest",
+  "axum",
+  "actix"
+]);
+async function detectFrameworks(cwd = process.cwd()) {
+  const found = /* @__PURE__ */ new Set();
+  const pkgJsonPath = join3(cwd, "package.json");
+  if (await pathExists2(pkgJsonPath)) {
+    try {
+      const pkg = JSON.parse(await readFile3(pkgJsonPath, "utf8"));
+      const allDeps = Object.keys({
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+        ...pkg.peerDependencies
+      });
+      for (const dep of allDeps) {
+        const root = dep.split("/").pop()?.toLowerCase() ?? "";
+        if (FRAMEWORK_ALLOWLIST.has(root)) found.add(root);
+        if (root === "core" && dep.startsWith("@nestjs/")) found.add("nest");
+      }
+    } catch {
+    }
+  }
+  const pyprojectPath = join3(cwd, "pyproject.toml");
+  if (await pathExists2(pyprojectPath)) {
+    try {
+      const text = (await readFile3(pyprojectPath, "utf8")).toLowerCase();
+      for (const fw of ["fastapi", "django", "flask"]) {
+        if (text.includes(fw)) found.add(fw);
+      }
+    } catch {
+    }
+  }
+  const cargoPath = join3(cwd, "Cargo.toml");
+  if (await pathExists2(cargoPath)) {
+    try {
+      const text = (await readFile3(cargoPath, "utf8")).toLowerCase();
+      for (const fw of ["axum", "actix"]) {
+        if (text.includes(fw)) found.add(fw);
+      }
+    } catch {
+    }
+  }
+  return [...found].slice(0, 8);
+}
+async function installedSlugsHash() {
+  const lockPath = join3(process.env["KORDIS_HOME"] ?? join3(homedir3(), ".kordis"), "installed.json");
+  if (!await pathExists2(lockPath)) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile3(lockPath, "utf8"));
+  } catch {
+    return [];
+  }
+  const slugs = Object.keys(parsed.packages ?? {});
+  return slugs.map((s) => createHash("sha256").update(s).digest("hex").slice(0, 8)).slice(0, 50);
+}
+async function collectContext(cwd = process.cwd()) {
+  const [tools, languages, frameworks, installed_slugs_hash] = await Promise.all([
+    detectTools(),
+    detectLanguages(cwd),
+    detectFrameworks(cwd),
+    installedSlugsHash()
+  ]);
+  const ctx = {};
+  if (tools.length > 0) ctx.tools = tools;
+  if (languages.length > 0) ctx.languages = languages;
+  if (frameworks.length > 0) ctx.frameworks = frameworks;
+  if (installed_slugs_hash.length > 0) ctx.installed_slugs_hash = installed_slugs_hash;
+  return ctx;
+}
+function buildContextHeader(ctx) {
+  if ((!ctx.tools || ctx.tools.length === 0) && (!ctx.languages || ctx.languages.length === 0) && (!ctx.frameworks || ctx.frameworks.length === 0) && (!ctx.installed_slugs_hash || ctx.installed_slugs_hash.length === 0)) {
+    return null;
+  }
+  const tryFields = (fields) => JSON.stringify(fields);
+  let payload = { ...ctx };
+  const dropOrder = [
+    "frameworks",
+    "languages",
+    "installed_slugs_hash"
+  ];
+  let serialised = tryFields(payload);
+  for (const drop of dropOrder) {
+    if (Buffer.byteLength(serialised, "utf8") <= CONTEXT_HEADER_MAX_BYTES) break;
+    payload = { ...payload };
+    delete payload[drop];
+    serialised = tryFields(payload);
+  }
+  if (Buffer.byteLength(serialised, "utf8") > CONTEXT_HEADER_MAX_BYTES) {
+    return null;
+  }
+  return serialised;
+}
+var cachedHeader = null;
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+async function getCachedContextHeader(cwd = process.cwd()) {
+  if (cachedHeader && Date.now() - cachedHeader.ts < CACHE_TTL_MS) {
+    return cachedHeader.value;
+  }
+  const ctx = await collectContext(cwd);
+  const header = buildContextHeader(ctx);
+  cachedHeader = { ts: Date.now(), value: header };
+  return header;
+}
+
 // src/version.ts
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname, join as join3 } from "path";
+import { dirname, join as join4 } from "path";
 var __dir = dirname(fileURLToPath(import.meta.url));
-var pkgPath = join3(__dir, "..", "package.json");
+var pkgPath = join4(__dir, "..", "package.json");
 var VERSION = (() => {
   try {
     const raw = readFileSync(pkgPath, "utf8");
@@ -1171,10 +1531,17 @@ async function useClient() {
   const keychain = await createKeychain();
   const username = cfg.username ?? null;
   let currentTokens = username ? await keychain.load(username) : null;
+  const personalizationEnabled = cfg.personalization === "on" && process.env["KORDIS_NO_CONTEXT"] !== "1" && !process.argv.includes("--no-context");
   const api = new KordisClient({
     baseUrl: cfg.apiUrl,
     userAgent: `kordis-cli/${VERSION} node/${process.version}`,
-    getAccessToken: async () => currentTokens?.access_token
+    getAccessToken: async () => currentTokens?.access_token,
+    ...personalizationEnabled ? {
+      getDynamicHeaders: async () => {
+        const value = await getCachedContextHeader();
+        return value ? { [CONTEXT_HEADER_NAME]: value } : {};
+      }
+    } : {}
   });
   const authedRequest = async (fn) => {
     try {
@@ -1337,6 +1704,70 @@ function whoamiCommand() {
 
 // src/commands/search.ts
 import { Command as Command3 } from "commander";
+
+// src/lib/recommendation-cache.ts
+import { readFile as readFile4, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { join as join5 } from "path";
+function cacheDir() {
+  return process.env["KORDIS_HOME"] ?? join5(homedir4(), ".kordis");
+}
+function cachePath() {
+  return join5(cacheDir(), "recommendations.json");
+}
+async function readCache() {
+  try {
+    const raw = await readFile4(cachePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.generated_at || !Array.isArray(parsed.items)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function writeCache(items, generatedAt) {
+  await mkdir3(cacheDir(), { recursive: true });
+  const payload = {
+    generated_at: generatedAt,
+    items,
+    seen_at: null
+  };
+  await writeFile3(cachePath(), JSON.stringify(payload, null, 2) + "\n", "utf8");
+}
+async function markSeen() {
+  const existing = await readCache();
+  if (!existing) return;
+  await mkdir3(cacheDir(), { recursive: true });
+  const updated = {
+    ...existing,
+    seen_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeFile3(cachePath(), JSON.stringify(updated, null, 2) + "\n", "utf8");
+}
+
+// src/lib/recommendation-footer.ts
+var FRESHNESS_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
+async function maybeRenderReminder() {
+  try {
+    const cfg = await loadCliConfig();
+    if (cfg.personalization === "off") return null;
+    const cache = await readCache();
+    if (!cache || cache.items.length === 0) return null;
+    const generated = new Date(cache.generated_at).getTime();
+    if (!Number.isFinite(generated)) return null;
+    if (Date.now() - generated > FRESHNESS_WINDOW_MS) return null;
+    if (cache.seen_at) {
+      const seen = new Date(cache.seen_at).getTime();
+      if (Number.isFinite(seen) && seen >= generated) return null;
+    }
+    const n = cache.items.length;
+    return `\u2192 ${n} new recommendation${n === 1 ? "" : "s"} match your stack: kordis recommend`;
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/search.ts
 var SORT_MODES = [
   "relevance",
   "stars",
@@ -1438,8 +1869,8 @@ function searchCommand() {
 
 // src/commands/push.ts
 import { Command as Command4 } from "commander";
-import { readFile as readFile3, stat, readdir } from "fs/promises";
-import { resolve, join as join4, posix, sep } from "path";
+import { readFile as readFile5, stat as stat2, readdir as readdir2 } from "fs/promises";
+import { resolve, join as join6, posix, sep } from "path";
 import JSZip from "jszip";
 
 // ../../packages/harness-schema/src/parser.ts
@@ -1492,9 +1923,9 @@ var FrontmatterParseError = class extends Error {
 
 // ../../packages/harness-schema/src/deps.ts
 init_src();
-import { z as z10 } from "zod";
+import { z as z12 } from "zod";
 var StringDepRe = /^([a-z0-9](-?[a-z0-9])*\/[a-z0-9](-?[a-z0-9])*)(?:@(.+))?$/;
-var ObjectDepSchema = z10.object({
+var ObjectDepSchema = z12.object({
   full_slug: FullSlugSchema,
   version_range: SemverRangeSchema.default("*")
 });
@@ -1530,50 +1961,50 @@ init_src();
 
 // ../../packages/harness-schema/src/types/skill.ts
 init_src();
-import { z as z11 } from "zod";
-var SkillFrontmatterSchema = z11.object({
-  name: z11.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "name must be lowercase-with-hyphens (Agent Skills spec)"),
-  description: z11.string().min(1).max(2048),
+import { z as z13 } from "zod";
+var SkillFrontmatterSchema = z13.object({
+  name: z13.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "name must be lowercase-with-hyphens (Agent Skills spec)"),
+  description: z13.string().min(1).max(2048),
   version: SemverSchema.optional(),
   // Agent Skills optional metadata
-  license: z11.string().max(64).optional(),
-  homepage: z11.string().url().optional(),
-  model: z11.string().optional(),
+  license: z13.string().max(64).optional(),
+  homepage: z13.string().url().optional(),
+  model: z13.string().optional(),
   // model override hint
-  "allowed-tools": z11.array(z11.string()).optional(),
-  "disable-model-invocation": z11.boolean().optional(),
+  "allowed-tools": z13.array(z13.string()).optional(),
+  "disable-model-invocation": z13.boolean().optional(),
   // Kordis-forwarded cross-type fields (kept minimal to not pollute the spec)
-  title: z11.string().min(1).max(200).optional(),
-  tags: z11.array(TagSchema).max(16).optional(),
-  tools: z11.array(ToolSlugSchema).optional()
+  title: z13.string().min(1).max(200).optional(),
+  tags: z13.array(TagSchema).max(16).optional(),
+  tools: z13.array(ToolSlugSchema).optional()
 }).strict();
 
 // ../../packages/harness-schema/src/types/mcp-server.ts
 init_src();
-import { z as z12 } from "zod";
-var McpTransportSchema = z12.union([
-  z12.object({
-    type: z12.literal("stdio"),
-    command: z12.string().min(1),
-    args: z12.array(z12.string()).optional().default([]),
-    env: z12.record(z12.string()).optional().default({})
+import { z as z14 } from "zod";
+var McpTransportSchema = z14.union([
+  z14.object({
+    type: z14.literal("stdio"),
+    command: z14.string().min(1),
+    args: z14.array(z14.string()).optional().default([]),
+    env: z14.record(z14.string()).optional().default({})
   }),
-  z12.object({
-    type: z12.enum(["http", "sse"]),
-    url: z12.string().url(),
-    headers: z12.record(z12.string()).optional().default({})
+  z14.object({
+    type: z14.enum(["http", "sse"]),
+    url: z14.string().url(),
+    headers: z14.record(z14.string()).optional().default({})
   })
 ]);
-var McpCapabilitiesSchema = z12.object({
-  tools: z12.array(z12.string()).optional().default([]),
-  resources: z12.array(z12.string()).optional().default([]),
-  prompts: z12.array(z12.string()).optional().default([])
+var McpCapabilitiesSchema = z14.object({
+  tools: z14.array(z14.string()).optional().default([]),
+  resources: z14.array(z14.string()).optional().default([]),
+  prompts: z14.array(z14.string()).optional().default([])
 });
-var McpServerFrontmatterSchema = z12.object({
-  name: z12.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
-  description: z12.string().min(1).max(2048),
+var McpServerFrontmatterSchema = z14.object({
+  name: z14.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
+  description: z14.string().min(1).max(2048),
   version: SemverSchema,
-  mcp_spec_version: z12.string().default("2026-03"),
+  mcp_spec_version: z14.string().default("2026-03"),
   transport: McpTransportSchema,
   capabilities: McpCapabilitiesSchema.optional().default({
     tools: [],
@@ -1581,35 +2012,35 @@ var McpServerFrontmatterSchema = z12.object({
     prompts: []
   }),
   /** Human-readable setup / auth instructions. Surfaced in `kordis info`. */
-  auth_notes: z12.string().optional(),
+  auth_notes: z14.string().optional(),
   /** Required env vars with description + whether they must be secret. */
-  env_schema: z12.record(
-    z12.object({
-      description: z12.string(),
-      required: z12.boolean().default(true),
-      secret: z12.boolean().default(false)
+  env_schema: z14.record(
+    z14.object({
+      description: z14.string(),
+      required: z14.boolean().default(true),
+      secret: z14.boolean().default(false)
     })
   ).optional(),
-  homepage: z12.string().url().optional(),
-  repository: z12.string().url().optional(),
-  license: z12.string().max(64).optional(),
-  title: z12.string().min(1).max(200).optional()
+  homepage: z14.string().url().optional(),
+  repository: z14.string().url().optional(),
+  license: z14.string().max(64).optional(),
+  title: z14.string().min(1).max(200).optional()
 }).strict();
 
 // ../../packages/harness-schema/src/types/project-rules.ts
 init_src();
-import { z as z13 } from "zod";
-var ProjectRulesFrontmatterSchema = z13.object({
-  title: z13.string().min(1).max(200),
-  description: z13.string().min(1).max(2048),
+import { z as z15 } from "zod";
+var ProjectRulesFrontmatterSchema = z15.object({
+  title: z15.string().min(1).max(200),
+  description: z15.string().min(1).max(2048),
   version: SemverSchema.optional(),
-  scope: z13.enum(["root", "nested", "globs"]).default("root"),
-  target_path: z13.string().optional(),
-  globs: z13.array(z13.string()).optional(),
-  target_tools: z13.array(ToolSlugSchema).optional().default([]),
+  scope: z15.enum(["root", "nested", "globs"]).default("root"),
+  target_path: z15.string().optional(),
+  globs: z15.array(z15.string()).optional(),
+  target_tools: z15.array(ToolSlugSchema).optional().default([]),
   /** When true, installation is idempotent via `<!-- kordis:... -->` markers. */
-  mergeable: z13.boolean().default(true),
-  license: z13.string().max(64).optional()
+  mergeable: z15.boolean().default(true),
+  license: z15.string().max(64).optional()
 }).strict().refine(
   (v) => v.scope !== "nested" || !!v.target_path,
   { message: 'scope="nested" requires target_path' }
@@ -1620,33 +2051,33 @@ var ProjectRulesFrontmatterSchema = z13.object({
 
 // ../../packages/harness-schema/src/types/custom-agent.ts
 init_src();
-import { z as z14 } from "zod";
-var CustomAgentFrontmatterSchema = z14.object({
-  name: z14.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
-  description: z14.string().min(1).max(2048),
-  title: z14.string().min(1).max(200).optional(),
+import { z as z16 } from "zod";
+var CustomAgentFrontmatterSchema = z16.object({
+  name: z16.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
+  description: z16.string().min(1).max(2048),
+  title: z16.string().min(1).max(200).optional(),
   version: SemverSchema.optional(),
   /** System prompt that defines the agent's persona + rules. Required. */
-  system_prompt: z14.string().min(1).max(5e4),
+  system_prompt: z16.string().min(1).max(5e4),
   /** Optional model override — string passed verbatim to the host. */
-  model: z14.string().optional(),
+  model: z16.string().optional(),
   /** Tools this agent can call. Host-specific names (no uniform namespace). */
-  allowed_tools: z14.array(z14.string()).optional().default([]),
-  disallowed_tools: z14.array(z14.string()).optional().default([]),
+  allowed_tools: z16.array(z16.string()).optional().default([]),
+  disallowed_tools: z16.array(z16.string()).optional().default([]),
   /** Fork/context behaviour hint (Claude: `context: fork` etc.). */
-  context: z14.enum(["inherit", "fork", "isolated"]).optional(),
+  context: z16.enum(["inherit", "fork", "isolated"]).optional(),
   /** Known-good tool runtimes. Empty = untested everywhere. */
-  tool_compat: z14.array(ToolSlugSchema).optional().default([]),
+  tool_compat: z16.array(ToolSlugSchema).optional().default([]),
   /** Pre-load skills when this agent activates. */
-  preload_skills: z14.array(z14.string()).optional().default([]),
-  license: z14.string().max(64).optional(),
-  homepage: z14.string().url().optional()
+  preload_skills: z16.array(z16.string()).optional().default([]),
+  license: z16.string().max(64).optional(),
+  homepage: z16.string().url().optional()
 }).strict();
 
 // ../../packages/harness-schema/src/types/hook.ts
 init_src();
-import { z as z15 } from "zod";
-var HookEventSchema = z15.enum([
+import { z as z17 } from "zod";
+var HookEventSchema = z17.enum([
   "PreToolUse",
   "PostToolUse",
   "UserPromptSubmit",
@@ -1658,37 +2089,37 @@ var HookEventSchema = z15.enum([
   "SubagentStop",
   "Background"
 ]);
-var HookActionSchema = z15.union([
-  z15.object({
-    type: z15.literal("command"),
-    command: z15.string().min(1),
-    timeout_ms: z15.number().int().positive().max(6e5).optional(),
-    blocking: z15.boolean().default(false)
+var HookActionSchema = z17.union([
+  z17.object({
+    type: z17.literal("command"),
+    command: z17.string().min(1),
+    timeout_ms: z17.number().int().positive().max(6e5).optional(),
+    blocking: z17.boolean().default(false)
   }),
-  z15.object({
-    type: z15.literal("http"),
-    url: z15.string().url(),
-    method: z15.enum(["GET", "POST", "PUT", "PATCH"]).default("POST"),
-    headers: z15.record(z15.string()).optional().default({}),
-    timeout_ms: z15.number().int().positive().max(6e5).optional(),
-    blocking: z15.boolean().default(false)
+  z17.object({
+    type: z17.literal("http"),
+    url: z17.string().url(),
+    method: z17.enum(["GET", "POST", "PUT", "PATCH"]).default("POST"),
+    headers: z17.record(z17.string()).optional().default({}),
+    timeout_ms: z17.number().int().positive().max(6e5).optional(),
+    blocking: z17.boolean().default(false)
   })
 ]);
-var HookBindingSchema = z15.object({
+var HookBindingSchema = z17.object({
   event: HookEventSchema,
-  matcher: z15.string().optional(),
+  matcher: z17.string().optional(),
   action: HookActionSchema
 });
-var HookFrontmatterSchema = z15.object({
-  name: z15.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
-  description: z15.string().min(1).max(2048),
-  title: z15.string().min(1).max(200).optional(),
+var HookFrontmatterSchema = z17.object({
+  name: z17.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
+  description: z17.string().min(1).max(2048),
+  title: z17.string().min(1).max(200).optional(),
   version: SemverSchema.optional(),
   /** One or more hook bindings. */
-  hooks: z15.array(HookBindingSchema).min(1),
+  hooks: z17.array(HookBindingSchema).min(1),
   /** Declared to surface in search filters — always "claude-code" for now. */
-  tool_compat: z15.array(z15.enum(["claude-code"])).default(["claude-code"]),
-  license: z15.string().max(64).optional()
+  tool_compat: z17.array(z17.enum(["claude-code"])).default(["claude-code"]),
+  license: z17.string().max(64).optional()
 }).strict();
 
 // ../../packages/harness-schema/src/validator.ts
@@ -2007,7 +2438,7 @@ function pushCommand() {
     async (path, opts) => {
       const bundle = await useClient();
       const abs = resolve(process.cwd(), path);
-      const s = await stat(abs);
+      const s = await stat2(abs);
       let content;
       let assets = [];
       if (s.isDirectory()) {
@@ -2017,7 +2448,7 @@ function pushCommand() {
         ({ content, assets } = await bundleSkillZip(abs));
         content = ensureTypeField(content, "skill");
       } else {
-        content = await readFile3(abs, "utf8");
+        content = await readFile5(abs, "utf8");
       }
       let nameFromFm = null;
       try {
@@ -2198,19 +2629,19 @@ function shouldExclude(relPath, isDir) {
   return false;
 }
 async function walkDir(base, relDir, collected) {
-  const entries = await readdir(join4(base, relDir), { withFileTypes: true });
+  const entries = await readdir2(join6(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) });
+      collected.push({ rel, abs: join6(base, rel) });
     }
   }
 }
 async function readAsset(absPath) {
-  const buf = await readFile3(absPath);
+  const buf = await readFile5(absPath);
   const text = buf.toString("utf8");
   const roundtrip = Buffer.from(text, "utf8");
   if (roundtrip.equals(buf)) {
@@ -2227,7 +2658,7 @@ async function bundleDirectory(dir) {
   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 content = await readFile5(skillEntry.abs, "utf8");
   const assets = [];
   for (const f of all) {
     if (f.rel === "SKILL.md") continue;
@@ -2237,7 +2668,7 @@ async function bundleDirectory(dir) {
   return { content, assets };
 }
 async function bundleSkillZip(zipPath) {
-  const buf = await readFile3(zipPath);
+  const buf = await readFile5(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");
@@ -2271,8 +2702,8 @@ async function bundleSkillZip(zipPath) {
 
 // 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";
+import { mkdir as mkdir5, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname2, join as join8 } from "path";
 
 // ../../packages/translators/src/skill/identity.ts
 function buildSkillFile(input, outputPath) {
@@ -2714,21 +3145,21 @@ function getTranslator(type, format) {
 }
 
 // src/lockfile.ts
-import { homedir as homedir3 } from "os";
-import { join as join5 } from "path";
-import { readFile as readFile4, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
-var LOCKFILE_PATH = join5(homedir3(), ".kordis", "installed.json");
+import { homedir as homedir5 } from "os";
+import { join as join7 } from "path";
+import { readFile as readFile6, writeFile as writeFile4, mkdir as mkdir4 } from "fs/promises";
+var LOCKFILE_PATH = join7(homedir5(), ".kordis", "installed.json");
 async function readLockfile() {
   try {
-    const raw = await readFile4(LOCKFILE_PATH, "utf8");
+    const raw = await readFile6(LOCKFILE_PATH, "utf8");
     return JSON.parse(raw);
   } catch {
     return { packages: {} };
   }
 }
 async function writeLockfile(lf) {
-  await mkdir3(join5(homedir3(), ".kordis"), { recursive: true });
-  await writeFile3(LOCKFILE_PATH, JSON.stringify(lf, null, 2) + "\n", "utf8");
+  await mkdir4(join7(homedir5(), ".kordis"), { recursive: true });
+  await writeFile4(LOCKFILE_PATH, JSON.stringify(lf, null, 2) + "\n", "utf8");
 }
 async function recordInstalled(fullSlug, entry) {
   const lf = await readLockfile();
@@ -2764,8 +3195,8 @@ async function doPullInstall(fullSlug, tool, installRoot, version) {
       assets: contentRes.assets
     });
     for (const f of result.files) {
-      const abs = join6(installRoot, f.path);
-      await mkdir4(dirname2(abs), { recursive: true });
+      const abs = join8(installRoot, f.path);
+      await mkdir5(dirname2(abs), { recursive: true });
       await writeEmittedFile(abs, f.content, f.encoding);
       written.push(abs);
     }
@@ -2784,8 +3215,8 @@ async function doPullInstall(fullSlug, tool, installRoot, version) {
         `Tool "${format}" is not supported for type "${parsed.type}"; installed canonical form instead.`
       );
       for (const f of result.files) {
-        const abs = join6(installRoot, f.path);
-        await mkdir4(dirname2(abs), { recursive: true });
+        const abs = join8(installRoot, f.path);
+        await mkdir5(dirname2(abs), { recursive: true });
         await writeEmittedFile(abs, f.content, f.encoding);
         written.push(abs);
       }
@@ -2842,11 +3273,13 @@ function pullCommand() {
           for (const n of result.notes) printHuman(c.yellow(`  ! ${n}`));
         }
       });
+      const reminder = await maybeRenderReminder();
+      if (reminder) printHuman(c.gray(reminder));
     }
   );
 }
 async function detectTool(root) {
-  const { stat: stat2 } = await import("fs/promises");
+  const { stat: stat3 } = await import("fs/promises");
   const checks = [
     [".claude", "claude-code"],
     [".cursor", "cursor"],
@@ -2862,7 +3295,7 @@ async function detectTool(root) {
   ];
   for (const [path, tool] of checks) {
     try {
-      await stat2(join6(root, path));
+      await stat3(join8(root, path));
       return tool;
     } catch {
     }
@@ -2871,9 +3304,9 @@ async function detectTool(root) {
 }
 async function writeEmittedFile(abs, content, encoding) {
   if (encoding === "base64") {
-    await writeFile4(abs, Buffer.from(content, "base64"));
+    await writeFile5(abs, Buffer.from(content, "base64"));
   } else {
-    await writeFile4(abs, content, "utf8");
+    await writeFile5(abs, content, "utf8");
   }
 }
 
@@ -2994,11 +3427,12 @@ function logoutCommand() {
 }
 
 // src/commands/setup.ts
-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 { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir6, access as access3 } from "fs/promises";
+import { homedir as homedir6 } from "os";
+import { join as join9, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command as Command9 } from "commander";
+import prompts from "prompts";
 var MARKER_START = "<!-- kordis-start -->";
 var MARKER_END = "<!-- kordis-end -->";
 var HUB_TARGETS = [
@@ -3010,7 +3444,8 @@ var SUB_SKILLS = [
   "kordis-search",
   "kordis-using",
   "kordis-publishing",
-  "kordis-social"
+  "kordis-social",
+  "kordis-recommend"
 ];
 var SKILL_TARGETS = [
   { tool: "Claude Code", dir: ".claude", skillsDir: ".claude/skills" },
@@ -3019,7 +3454,7 @@ var SKILL_TARGETS = [
 ];
 async function exists(path) {
   try {
-    await access2(path);
+    await access3(path);
     return true;
   } catch {
     return false;
@@ -3029,18 +3464,18 @@ function assetRoots() {
   const __dir2 = dirname3(fileURLToPath2(import.meta.url));
   return {
     // Built binary: bin/kordis.js → assets/ is one level up
-    bundled: join7(__dir2, "..", "assets"),
+    bundled: join9(__dir2, "..", "assets"),
     // Dev mode: src/commands/setup.ts → 4 levels up to repo root, then packages/skills/
-    source: join7(__dir2, "..", "..", "..", "..", "packages", "skills")
+    source: join9(__dir2, "..", "..", "..", "..", "packages", "skills")
   };
 }
 async function pickAssetRoot() {
   const { bundled, source } = assetRoots();
-  return await exists(join7(bundled, "KORDIS.md")) ? bundled : source;
+  return await exists(join9(bundled, "KORDIS.md")) ? bundled : source;
 }
 async function loadHubContent() {
   const root = await pickAssetRoot();
-  const raw = await readFile5(join7(root, "KORDIS.md"), "utf-8");
+  const raw = await readFile7(join9(root, "KORDIS.md"), "utf-8");
   if (raw.startsWith("---")) {
     const end = raw.indexOf("\n---", 4);
     if (end !== -1) return raw.slice(end + 4).trimStart();
@@ -3049,7 +3484,7 @@ async function loadHubContent() {
 }
 async function loadSubSkillContent(name) {
   const root = await pickAssetRoot();
-  return readFile5(join7(root, name, "SKILL.md"), "utf-8");
+  return readFile7(join9(root, name, "SKILL.md"), "utf-8");
 }
 async function injectBlock(filePath, content, dryRun) {
   const block = `${MARKER_START}
@@ -3058,14 +3493,14 @@ ${MARKER_END}`;
   let existing = "";
   let fileExists = true;
   try {
-    existing = await readFile5(filePath, "utf-8");
+    existing = await readFile7(filePath, "utf-8");
   } catch {
     fileExists = false;
   }
   if (!fileExists) {
     if (!dryRun) {
-      await mkdir5(dirname3(filePath), { recursive: true });
-      await writeFile5(filePath, block + "\n", "utf-8");
+      await mkdir6(dirname3(filePath), { recursive: true });
+      await writeFile6(filePath, block + "\n", "utf-8");
     }
     return "injected";
   }
@@ -3076,31 +3511,31 @@ ${MARKER_END}`;
     if (current === block) return "unchanged";
     if (!dryRun) {
       const updated = existing.slice(0, startIdx) + block + existing.slice(endIdx + MARKER_END.length);
-      await writeFile5(filePath, updated, "utf-8");
+      await writeFile6(filePath, updated, "utf-8");
     }
     return "updated";
   }
   if (!dryRun) {
-    await writeFile5(filePath, existing.trimEnd() + "\n\n" + block + "\n", "utf-8");
+    await writeFile6(filePath, existing.trimEnd() + "\n\n" + block + "\n", "utf-8");
   }
   return "injected";
 }
 async function copyBundledSkill(filePath, content, dryRun) {
   let existing = null;
   try {
-    existing = await readFile5(filePath, "utf-8");
+    existing = await readFile7(filePath, "utf-8");
   } catch {
   }
   if (existing === content) return "unchanged";
   if (!dryRun) {
-    await mkdir5(dirname3(filePath), { recursive: true });
-    await writeFile5(filePath, content, "utf-8");
+    await mkdir6(dirname3(filePath), { recursive: true });
+    await writeFile6(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 = homedir4();
+    const home = homedir6();
     const dryRun = opts.dryRun ?? false;
     let hubContent;
     let subSkillContents;
@@ -3117,8 +3552,8 @@ function setupCommand() {
     let anyFound = false;
     const changedTools = /* @__PURE__ */ new Set();
     for (const target of HUB_TARGETS) {
-      const dirPath = join7(home, target.dir);
-      const filePath = join7(home, target.file);
+      const dirPath = join9(home, target.dir);
+      const filePath = join9(home, target.file);
       if (!await exists(dirPath)) {
         if (!opts.silent) {
           printHuman(c.gray(`  - ${target.tool.padEnd(12)} not installed, skipped`));
@@ -3145,10 +3580,10 @@ function setupCommand() {
       }
     }
     for (const target of SKILL_TARGETS) {
-      const dirPath = join7(home, target.dir);
+      const dirPath = join9(home, target.dir);
       if (!await exists(dirPath)) continue;
       for (const subName of SUB_SKILLS) {
-        const filePath = join7(home, target.skillsDir, subName, "SKILL.md");
+        const filePath = join9(home, target.skillsDir, subName, "SKILL.md");
         const dest = `~/${target.skillsDir}/${subName}/SKILL.md`;
         try {
           const result = await copyBundledSkill(filePath, subSkillContents[subName], dryRun);
@@ -3180,6 +3615,34 @@ function setupCommand() {
       printHuman(c.gray("No supported agent tools detected."));
       printHuman(c.gray("Run `kordis setup` again after installing Claude Code, Codex, or Gemini CLI."));
     }
+    if (!opts.silent && !dryRun && process.stdin.isTTY && anyFound) {
+      const cfg = await loadCliConfig();
+      if (cfg.personalization === "undecided") {
+        printHuman("");
+        const { enable } = await prompts({
+          type: "confirm",
+          name: "enable",
+          message: "Personalize recommendations using anonymous local signals (installed agent tools, language stats, frameworks)? Server never stores them \u2014 only re-ranks results in-flight.",
+          initial: true
+        });
+        const newCfg = {
+          ...cfg,
+          personalization: enable ? "on" : "off"
+        };
+        await saveCliConfig(newCfg);
+        if (enable) {
+          printHuman(
+            c.green("\u2713 personalization on") + c.gray(" \u2014 disable any time: `KORDIS_NO_CONTEXT=1` env or `--no-context` flag")
+          );
+        } else {
+          printHuman(
+            c.gray(
+              "\u2192 recommendations will use popularity only. Re-enable later via `kordis recommend` if asked again."
+            )
+          );
+        }
+      }
+    }
   });
 }
 
@@ -3280,7 +3743,7 @@ function unstarCommand() {
 
 // src/commands/delete.ts
 import { Command as Command12 } from "commander";
-import prompts from "prompts";
+import prompts2 from "prompts";
 function deleteCommand() {
   return new Command12("delete").description("permanently delete a package you own").argument("<full_slug>", "package identifier {username}/{slug}").option("--force", "skip the confirmation prompt").action(async (fullSlug, opts) => {
     const [username, slug] = fullSlug.split("/");
@@ -3295,7 +3758,7 @@ function deleteCommand() {
       printHuman(`     "${detail.description?.slice(0, 80) ?? ""}"`);
       printHuman(c.yellow(`  The slug cannot be reused after deletion. This cannot be undone via the CLI.`));
       printHuman("");
-      const { confirmed } = await prompts({
+      const { confirmed } = await prompts2({
         type: "confirm",
         name: "confirmed",
         message: `Delete ${c.bold(fullSlug)}?`,
@@ -3709,9 +4172,107 @@ function diffCommand() {
   });
 }
 
+// src/commands/recommend.ts
+import { Command as Command18 } from "commander";
+import prompts3 from "prompts";
+function recommendCommand() {
+  return new Command18("recommend").description("show personalized package recommendations").option("--limit <n>", "max items to return (1-50)", (v) => parseInt(v, 10), 10).option("--verbose", "include score_breakdown per item", false).option("--no-context", "skip the X-Kordis-Context header for this call").action(async (opts) => {
+    const cfg = await loadCliConfig();
+    if (cfg.personalization === "undecided" && process.stdin.isTTY && !isJsonMode() && opts.context !== false) {
+      const { enable } = await prompts3({
+        type: "confirm",
+        name: "enable",
+        message: "Personalize recommendations using anonymous local signals (installed agent tools, language stats, frameworks)? Server never stores them \u2014 only re-ranks results in-flight.",
+        initial: true
+      });
+      const newCfg = {
+        ...cfg,
+        personalization: enable ? "on" : "off"
+      };
+      await saveCliConfig(newCfg);
+      if (!enable) {
+        printHuman(
+          c.gray(
+            "\u2192 recommendations will use popularity only. Re-enable later: `kordis setup` (re-asks the opt-in)."
+          )
+        );
+      }
+    }
+    const bundle = await useClient();
+    const spin = spinner("Computing recommendations");
+    const res = await bundle.api.recommend({
+      limit: opts.limit,
+      verbose: opts.verbose
+    });
+    spin.succeed();
+    await writeCache(res.items, res.generated_at);
+    await markSeen();
+    printDual({
+      json: res,
+      human: () => {
+        if (res.items.length === 0) {
+          printHuman(c.yellow("(no recommendations available right now)"));
+          printHuman(
+            c.gray(
+              "  \u2192 registry may be sparse; try `kordis search --trending` for broader discovery"
+            )
+          );
+          return;
+        }
+        printHuman(
+          `${c.bold(`${res.items.length} pick${res.items.length === 1 ? "" : "s"}`)} ${c.gray(`(${res.personalized ? "personalized" : "popularity-only"} \xB7 generated ${res.generated_at.slice(0, 19)}Z)`)}`
+        );
+        printHuman("");
+        res.items.forEach((it, idx) => renderItem(idx + 1, it, opts.verbose));
+        printHuman("");
+        printHuman(
+          c.gray(
+            "\u2192 install any with `kordis pull <full_slug>` or peek with `kordis read <full_slug>`"
+          )
+        );
+        if (typeof res.capped_by_author === "number" && res.capped_by_author > 0) {
+          const extras = res.capped_by_author;
+          printHuman(
+            c.gray(
+              `\u2192 ${extras} more candidate${extras === 1 ? "" : "s"} from the same publisher${extras === 1 ? " was" : "s were"} skipped by the diversity cap`
+            )
+          );
+        }
+        if (!res.personalized) {
+          printHuman(
+            c.gray(
+              "\u2192 enable personalization for tailored picks: `kordis setup` (re-asks the opt-in)"
+            )
+          );
+        }
+      }
+    });
+  });
+}
+function renderItem(idx, it, verbose) {
+  const confidenceBadge = it.confidence === "high" ? c.green("high") : it.confidence === "medium" ? c.cyan("medium") : c.gray("low");
+  printHuman(
+    `${c.bold(`${idx}. ${it.full_slug}`)} ${c.gray(`v${it.current_version}`)} ${c.cyan(`[${it.type}]`)} ${c.gray(`tier ${it.tier}`)} ${c.gray("\xB7")} ${confidenceBadge} confidence`
+  );
+  printHuman(`   ${it.description.length > 100 ? `${it.description.slice(0, 100)}\u2026` : it.description}`);
+  printHuman(c.gray(`   \u2605 ${it.stars}  \u21E3 ${it.downloads}`));
+  printHuman(c.gray(`   \u2192 ${it.why_recommended}`));
+  printHuman(c.gray(`   install: ${c.cyan(it.install_command)}`));
+  printHuman(c.gray(`   read:    ${c.cyan(it.jit_read_command)}`));
+  if (verbose && it.score_breakdown) {
+    const b = it.score_breakdown;
+    printHuman(
+      c.gray(
+        `   score:   content=${b.content} cf=${b.cf} popularity=${b.popularity} final=${b.final}`
+      )
+    );
+  }
+  printHuman("");
+}
+
 // src/index.ts
 function buildProgram() {
-  const program = new Command18("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 Command19("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);
   });
@@ -3732,6 +4293,7 @@ function buildProgram() {
   program.addCommand(outdatedCommand());
   program.addCommand(updateCommand());
   program.addCommand(diffCommand());
+  program.addCommand(recommendCommand());
   program.addCommand(setupCommand());
   return program;
 }
@@ -3782,8 +4344,15 @@ function handleError(err) {
     process.exit(err.exitCode());
   }
   if (err instanceof KordisNetworkError) {
-    if (isJsonMode()) printJson({ error: { code: "network_unreachable", message: err.message } });
-    else printHuman(c.red(`\u2717 ${err.message}`));
+    const hint = "Check your network connection, or override the API endpoint with `KORDIS_API_URL=https://api.kordis.store` (or your self-hosted instance). If kordis.store itself is down, see https://kordis.store for status.";
+    if (isJsonMode()) {
+      printJson({
+        error: { code: "network_unreachable", message: err.message, hint }
+      });
+    } else {
+      printHuman(c.red(`\u2717 ${err.message}`));
+      for (const line of hint.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
+    }
     process.exit(err.exitCode());
   }
   if (err instanceof Error) {