@rayul/kordis 0.6.6 → 0.7.0

package/README.md

@@ -56,6 +56,25 @@ Pass `--json` on any command to get machine-readable output.
 
 Refresh and access tokens are stored in the OS keychain via `keytar` (with a file-based fallback at `~/.kordis/.tokens.json`, mode `0600`, when keytar is unavailable).
 
+## Privacy & environment variables
+
+Kordis collects two opt-in signals, both off by default. Both can be set non-interactively for agents (`kordis setup --personalization on|off` and `kordis setup --error-telemetry on|off`) and both have an env-var escape hatch that overrides config.
+
+| env var | purpose | default |
+|---|---|---|
+| `KORDIS_NO_CONTEXT=1` | suppress personalization header even if opted in | off |
+| `KORDIS_NO_TELEMETRY=1` | suppress error telemetry POST even if opted in | off |
+| `KORDIS_NO_KEYCHAIN=1` | force plaintext token storage even when keytar loads (escape hatch for macOS keychain-prompt fatigue) | off |
+| `KORDIS_DEBUG=1` | surface auto-finalize stage outcomes to stderr (diagnostic) | off |
+
+**What error telemetry carries** (0.7.0+, when `error_telemetry: 'on'`):
+- error `kind` (4 enum values — auto-finalize Stage 1/2 failure, network unreachable, unhandled error)
+- `cli_version`, `node_version`, `platform`
+- `message_excerpt` — first 200 chars of `err.message` AFTER client-side sanitization (homedir → `~`; unix paths ≥2 segments → `<path>`; Windows paths → `<path>`; query strings → `?<query>`; JWTs → `<jwt>`; UUIDs → `<uuid>`; hex runs ≥32 → `<hex>`)
+- optional `error_code` (when present on the Error) + `elapsed_ms` + ISO timestamp
+
+**What it NEVER carries**: `argv`, env-var values, file paths (after sanitization), identity (`user_id`, `username`, `session_id`, refresh tokens), `X-Kordis-Context` content, full stack traces. The server route additionally ignores any `Authorization` header so identity can't leak in even by accident.
+
 ## Docs
 
 The agent guide that `setup` injects is also shipped as `assets/KORDIS.md` in this package.

package/assets/kordis-using/SKILL.md

@@ -155,3 +155,43 @@ User: "add a pre-commit hook that blocks committing API keys"
 - confirm with the user before pulling
 - kordis pull <full_slug>
 </example>
+
+## Telemetry & opt-in (0.7.0+)
+
+Kordis can send anonymized error reports to help maintainers fix wild failures that the user might otherwise just give up on. Off by default.
+
+When asked at `kordis setup`, the consent prompt explicitly states the payload contents. Agents that already received user consent in chat can record it non-interactively:
+
+```
+kordis setup --error-telemetry on
+kordis setup --error-telemetry off
+```
+
+The same applies to the older personalization opt-in:
+
+```
+kordis setup --personalization on
+kordis setup --personalization off
+```
+
+**Never assume consent on the user's behalf.** Ask in plain words, then record their answer with the flag.
+
+**What error telemetry carries** (sent to `POST /api/telemetry/error`):
+
+| field | value |
+|---|---|
+| `kind` | one of `auto_finalize_stage1_fail`, `auto_finalize_stage2_fail`, `network_unreachable`, `unhandled_error` |
+| `cli_version`, `node_version`, `platform` | version + OS strings |
+| `message_excerpt` | first 200 chars of `err.message` after sanitization (homedir → `~`; paths / JWTs / UUIDs / long hex runs stripped) |
+| `error_code`, `elapsed_ms` | optional |
+| `timestamp` | ISO 8601 |
+
+**Never carries**: `argv`, env-var values, file paths (after sanitization), identity (`user_id` / `username` / `session_id` / refresh tokens), `X-Kordis-Context` content, full stack traces. The server's POST route ignores `Authorization` headers entirely.
+
+**Escape hatches** (highest precedence wins):
+
+1. `KORDIS_NO_TELEMETRY=1` env var — disables for that invocation
+2. `kordis setup --error-telemetry off` — persists the off decision
+3. `kordis setup --error-telemetry on` — persists the on decision
+
+If a user asks "what does Kordis collect about me" — quote the table above; don't paraphrase.

package/dist/index.js

@@ -829,6 +829,69 @@ var init_recommend = __esm({
   }
 });
 
+// ../../packages/contracts/src/telemetry.ts
+import { z as z12 } from "zod";
+var TelemetryErrorKindSchema, TelemetryPlatformSchema, TelemetryErrorPayloadSchema, AdminTelemetrySummaryQuerySchema, TelemetryKindCountSchema, TelemetryDailyBucketSchema, TelemetryTopExcerptSchema, AdminTelemetrySummaryResponseSchema;
+var init_telemetry = __esm({
+  "../../packages/contracts/src/telemetry.ts"() {
+    "use strict";
+    TelemetryErrorKindSchema = z12.enum([
+      /** Stage 1 of CLI auto-finalize (pollDeviceFlow) failed with a non-pending error. */
+      "auto_finalize_stage1_fail",
+      /** Stage 2 of CLI auto-finalize (me/keychain/saveConfig) failed — the 0.6.6 class. */
+      "auto_finalize_stage2_fail",
+      /** Top-level CLI handler caught KordisNetworkError. */
+      "network_unreachable",
+      /** Top-level CLI handler caught an unrecognised error class. */
+      "unhandled_error"
+    ]);
+    TelemetryPlatformSchema = z12.enum(["darwin", "linux", "win32", "other"]);
+    TelemetryErrorPayloadSchema = z12.object({
+      kind: TelemetryErrorKindSchema,
+      cli_version: z12.string().min(1).max(32),
+      node_version: z12.string().min(1).max(32),
+      platform: TelemetryPlatformSchema,
+      /** First 200 chars of err.message AFTER client-side sanitization. */
+      message_excerpt: z12.string().min(1).max(200),
+      /** err.code when present on the original error object. */
+      error_code: z12.string().min(1).max(64).optional(),
+      /** Optional timing — duration of the failing operation if the catch site knows it. */
+      elapsed_ms: z12.number().int().nonnegative().optional(),
+      /** ISO 8601 UTC. */
+      timestamp: z12.string().min(1).max(40)
+    });
+    AdminTelemetrySummaryQuerySchema = z12.object({
+      /** ISO 8601 cutoff; defaults to 7 days back. */
+      since: z12.string().datetime().optional()
+    });
+    TelemetryKindCountSchema = z12.object({
+      kind: TelemetryErrorKindSchema,
+      cli_version: z12.string(),
+      count: z12.number().int().nonnegative()
+    });
+    TelemetryDailyBucketSchema = z12.object({
+      /** YYYY-MM-DD UTC. */
+      date: z12.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+      count: z12.number().int().nonnegative()
+    });
+    TelemetryTopExcerptSchema = z12.object({
+      kind: TelemetryErrorKindSchema,
+      message_excerpt: z12.string(),
+      count: z12.number().int().nonnegative()
+    });
+    AdminTelemetrySummaryResponseSchema = z12.object({
+      /** Cutoff applied to all aggregates. */
+      since: z12.string().datetime(),
+      /** Count grouped by (kind, cli_version), descending. */
+      counts: z12.array(TelemetryKindCountSchema),
+      /** Top 10 distinct message_excerpts per kind, for quick triage. */
+      top_excerpts: z12.array(TelemetryTopExcerptSchema),
+      /** Daily volume sparkline, oldest → newest. */
+      daily: z12.array(TelemetryDailyBucketSchema)
+    });
+  }
+});
+
 // ../../packages/contracts/src/index.ts
 var init_src = __esm({
   "../../packages/contracts/src/index.ts"() {
@@ -844,6 +907,7 @@ var init_src = __esm({
     init_api();
     init_context();
     init_recommend();
+    init_telemetry();
   }
 });
 
@@ -1136,6 +1200,24 @@ var init_client = __esm({
           `/api/comments/${id}/replies`
         );
       }
+      // ─── telemetry ─────────────────────────────────────────────────────────
+      /**
+       * Fire-and-forget anonymized error report (0.7.0). The CLI's
+       * `apps/cli/src/lib/error-reporter.ts` wraps this with sanitization +
+       * gating + timeout. The server route is anonymous-OK (no Authorization
+       * header read) and rate-limited to 30/min per IP via its own bucket so
+       * a CI runner burst can't lock the IP out of the actual API.
+       *
+       * Server returns `204 No Content` on success; the reporter ignores
+       * any non-2xx (and even network errors — telemetry MUST NOT itself
+       * become a source of user-visible failure).
+       */
+      recordTelemetryError(payload) {
+        return this.request("/api/telemetry/error", {
+          method: "POST",
+          body: payload
+        });
+      }
     };
   }
 });
@@ -1186,7 +1268,8 @@ async function loadCliConfig() {
       apiUrl: apiUrlFromEnv ?? parsed.apiUrl ?? "https://api.kordis.store",
       ...parsed.username ? { username: parsed.username } : {},
       ...parsed.sessionId ? { sessionId: parsed.sessionId } : {},
-      personalization: parsed.personalization ?? "undecided"
+      personalization: parsed.personalization ?? "undecided",
+      error_telemetry: parsed.error_telemetry ?? "undecided"
     };
   } catch {
     return { apiUrl: apiUrlFromEnv ?? "https://api.kordis.store" };
@@ -1518,15 +1601,93 @@ async function getCachedContextHeader(cwd = process.cwd()) {
   return header;
 }
 
+// src/lib/error-reporter.ts
+init_src2();
+import { homedir as homedir4, platform } from "os";
+
+// src/version.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join as join4 } from "path";
+var __dir = dirname(fileURLToPath(import.meta.url));
+var pkgPath = join4(__dir, "..", "package.json");
+var VERSION = (() => {
+  try {
+    const raw = readFileSync(pkgPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === "string" ? parsed.version : "0.0.0-unknown";
+  } catch {
+    return "0.0.0-unknown";
+  }
+})();
+
+// src/lib/error-reporter.ts
+var HOME = homedir4();
+var REPORT_TIMEOUT_MS = 3e3;
+function sanitizeMessage(raw) {
+  let s = raw;
+  if (HOME && HOME.length > 0) {
+    s = s.split(HOME).join("~");
+  }
+  s = s.replace(/(\/[^\s'"]+){2,}/g, "<path>");
+  s = s.replace(/[A-Za-z]:\\[^\s'"]+/g, "<path>");
+  s = s.replace(/\?[^\s'"]+/g, "?<query>");
+  s = s.replace(/eyJ[\w-]+\.[\w-]+\.[\w-]+/g, "<jwt>");
+  s = s.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<uuid>");
+  s = s.replace(/\b[0-9a-f]{32,}\b/gi, "<hex>");
+  s = s.trim().slice(0, 200);
+  return s.length === 0 ? "<empty>" : s;
+}
+function normalisePlatform() {
+  const p = platform();
+  if (p === "darwin" || p === "linux" || p === "win32") return p;
+  return "other";
+}
+async function telemetryBaseUrl() {
+  const override = process.env["KORDIS_TELEMETRY_URL"];
+  if (override) return override;
+  const cfg = await loadCliConfig();
+  return cfg.apiUrl;
+}
+async function reportError(kind, err, extras = {}) {
+  try {
+    if (process.env["KORDIS_NO_TELEMETRY"] === "1") return;
+    const cfg = await loadCliConfig();
+    if (cfg.error_telemetry !== "on") return;
+    const rawMessage = err instanceof Error ? err.message : String(err);
+    const detectedCode = extras.error_code ?? (err.code !== void 0 ? String(err.code).slice(0, 64) : void 0);
+    const payload = {
+      kind,
+      cli_version: VERSION,
+      node_version: process.version,
+      platform: normalisePlatform(),
+      message_excerpt: sanitizeMessage(rawMessage),
+      ...detectedCode ? { error_code: detectedCode } : {},
+      ...extras.elapsed_ms !== void 0 ? { elapsed_ms: extras.elapsed_ms } : {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const baseUrl = await telemetryBaseUrl();
+    const client = new KordisClient({
+      baseUrl,
+      userAgent: `kordis-cli/${VERSION}/telemetry node/${process.version}`
+    });
+    await Promise.race([
+      client.recordTelemetryError(payload),
+      new Promise((resolve2) => setTimeout(resolve2, REPORT_TIMEOUT_MS))
+    ]);
+  } catch {
+  }
+}
+
 // src/lib/pending-login.ts
 import { readFile as readFile4, writeFile as writeFile3, unlink as unlink2, mkdir as mkdir3 } from "fs/promises";
-import { homedir as homedir4 } from "os";
-import { join as join4 } from "path";
+import { homedir as homedir5 } from "os";
+import { join as join5 } from "path";
 function dir() {
-  return process.env["KORDIS_HOME"] ?? join4(homedir4(), ".kordis");
+  return process.env["KORDIS_HOME"] ?? join5(homedir5(), ".kordis");
 }
 function path() {
-  return join4(dir(), "pending-login.json");
+  return join5(dir(), "pending-login.json");
 }
 async function readPending() {
   try {
@@ -1552,22 +1713,6 @@ function isExpired(file) {
   return Math.floor(Date.now() / 1e3) >= file.expires_at_epoch;
 }
 
-// src/version.ts
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join as join5 } from "path";
-var __dir = dirname(fileURLToPath(import.meta.url));
-var pkgPath = join5(__dir, "..", "package.json");
-var VERSION = (() => {
-  try {
-    const raw = readFileSync(pkgPath, "utf8");
-    const parsed = JSON.parse(raw);
-    return typeof parsed.version === "string" ? parsed.version : "0.0.0-unknown";
-  } catch {
-    return "0.0.0-unknown";
-  }
-})();
-
 // src/client.ts
 async function useClient() {
   let cfg = await loadCliConfig();
@@ -1599,6 +1744,7 @@ async function useClient() {
               process.stderr.write(`[kordis] auto-finalize: poll failed (code=${code ?? "none"}): ${msg}
 `);
             }
+            void reportError("auto_finalize_stage1_fail", err);
           }
         }
         if (pollResult) {
@@ -1631,6 +1777,7 @@ async function useClient() {
               `[kordis] auto-finalize: server issued tokens but local persistence failed (${msg}). Run \`kordis login --emit-only\` again to retry.
 `
             );
+            void reportError("auto_finalize_stage2_fail", err);
           }
         }
       }
@@ -1848,10 +1995,10 @@ import { Command as Command3 } from "commander";
 
 // src/lib/recommendation-cache.ts
 import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir4 } from "fs/promises";
-import { homedir as homedir5 } from "os";
+import { homedir as homedir6 } from "os";
 import { join as join6 } from "path";
 function cacheDir() {
-  return process.env["KORDIS_HOME"] ?? join6(homedir5(), ".kordis");
+  return process.env["KORDIS_HOME"] ?? join6(homedir6(), ".kordis");
 }
 function cachePath() {
   return join6(cacheDir(), "recommendations.json");
@@ -1919,14 +2066,47 @@ var SORT_MODES = [
   "rising"
 ];
 var TIME_WINDOWS = ["24h", "7d", "30d"];
+var TOOL_SLUGS = [
+  "claude-code",
+  "codex",
+  "cursor",
+  "antigravity",
+  "windsurf",
+  "continue",
+  "copilot",
+  "opencode",
+  "gemini-cli"
+];
+var TOOL_ALIASES = {
+  claude: "claude-code",
+  gemini: "gemini-cli"
+};
 function searchCommand() {
-  return new Command3("search").description("search the Kordis registry").argument("[query...]", "keywords to match against title/description").option("--type <type>", "filter by harness type (skill|mcp-server|project-rules|custom-agent|hook)").option("--tool <tool>", "filter by compatible tool (claude-code|codex|cursor|...)").option("--tier <tier>", "filter by portability tier (A|B|C|D)").option("--author <username>", "filter to a single author (server returns exact total when set)").option("--sort <mode>", `sort: ${SORT_MODES.join("|")}`).option("--trending", "list trending packages (overrides --sort)", false).option("--rising", "list rising packages by 7d acceleration (overrides --sort)", false).option("--window <w>", `time window for --trending: ${TIME_WINDOWS.join("|")}`, "24h").option("--limit <n>", "max results", (v) => parseInt(v, 10), 20).action(async (query, opts) => {
+  return new Command3("search").description("search the Kordis registry").argument("[query...]", "keywords to match against title/description").option("--type <type>", "filter by harness type (skill|mcp-server|project-rules|custom-agent|hook)").option(
+    "--tool <tool>",
+    `filter by compatible tool \u2014 one of: ${TOOL_SLUGS.join("|")} (aliases: ${Object.entries(
+      TOOL_ALIASES
+    ).map(([alias, canonical]) => `${alias}\u2192${canonical}`).join(", ")})`
+  ).option("--tier <tier>", "filter by portability tier (A|B|C|D)").option("--author <username>", "filter to a single author (server returns exact total when set)").option(
+    "--cursor <token>",
+    "pagination cursor \u2014 pass the next_cursor field from a prior search response to fetch the next page"
+  ).option("--sort <mode>", `sort: ${SORT_MODES.join("|")}`).option("--trending", "list trending packages (overrides --sort)", false).option("--rising", "list rising packages by 7d acceleration (overrides --sort)", false).option("--window <w>", `time window for --trending: ${TIME_WINDOWS.join("|")}`, "24h").option("--limit <n>", "max results", (v) => parseInt(v, 10), 20).action(async (query, opts) => {
     if (opts.sort && !SORT_MODES.includes(opts.sort)) {
       throw new Error(`--sort must be one of ${SORT_MODES.join(", ")}`);
     }
     if (opts.window && !TIME_WINDOWS.includes(opts.window)) {
       throw new Error(`--window must be one of ${TIME_WINDOWS.join(", ")}`);
     }
+    let resolvedTool;
+    if (opts.tool) {
+      const candidate = TOOL_ALIASES[opts.tool] ?? opts.tool;
+      if (!TOOL_SLUGS.includes(candidate)) {
+        throw new Error(
+          `--tool must be one of ${TOOL_SLUGS.join(", ")} (you passed "${opts.tool}")`
+        );
+      }
+      resolvedTool = candidate;
+    }
     const bundle = await useClient();
     let res;
     if (opts.rising) {
@@ -1944,9 +2124,10 @@ function searchCommand() {
       res = await bundle.api.search({
         q: query.join(" ") || void 0,
         type: opts.type ? [opts.type] : void 0,
-        tool: opts.tool ? [opts.tool] : void 0,
+        tool: resolvedTool ? [resolvedTool] : void 0,
         tier: opts.tier,
         ...opts.author ? { author: opts.author } : {},
+        ...opts.cursor ? { cursor: opts.cursor } : {},
         sort: opts.sort ?? "relevance",
         limit: opts.limit
       });
@@ -2073,9 +2254,9 @@ var FrontmatterParseError = class extends Error {
 
 // ../../packages/harness-schema/src/deps.ts
 init_src();
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var StringDepRe = /^([a-z0-9](-?[a-z0-9])*\/[a-z0-9](-?[a-z0-9])*)(?:@(.+))?$/;
-var ObjectDepSchema = z12.object({
+var ObjectDepSchema = z13.object({
   full_slug: FullSlugSchema,
   version_range: SemverRangeSchema.default("*")
 });
@@ -2111,50 +2292,50 @@ init_src();
 
 // ../../packages/harness-schema/src/types/skill.ts
 init_src();
-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),
+import { z as z14 } from "zod";
+var SkillFrontmatterSchema = z14.object({
+  name: z14.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "name must be lowercase-with-hyphens (Agent Skills spec)"),
+  description: z14.string().min(1).max(2048),
   version: SemverSchema.optional(),
   // Agent Skills optional metadata
-  license: z13.string().max(64).optional(),
-  homepage: z13.string().url().optional(),
-  model: z13.string().optional(),
+  license: z14.string().max(64).optional(),
+  homepage: z14.string().url().optional(),
+  model: z14.string().optional(),
   // model override hint
-  "allowed-tools": z13.array(z13.string()).optional(),
-  "disable-model-invocation": z13.boolean().optional(),
+  "allowed-tools": z14.array(z14.string()).optional(),
+  "disable-model-invocation": z14.boolean().optional(),
   // Kordis-forwarded cross-type fields (kept minimal to not pollute the spec)
-  title: z13.string().min(1).max(200).optional(),
-  tags: z13.array(TagSchema).max(16).optional(),
-  tools: z13.array(ToolSlugSchema).optional()
+  title: z14.string().min(1).max(200).optional(),
+  tags: z14.array(TagSchema).max(16).optional(),
+  tools: z14.array(ToolSlugSchema).optional()
 }).strict();
 
 // ../../packages/harness-schema/src/types/mcp-server.ts
 init_src();
-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({})
+import { z as z15 } from "zod";
+var McpTransportSchema = z15.union([
+  z15.object({
+    type: z15.literal("stdio"),
+    command: z15.string().min(1),
+    args: z15.array(z15.string()).optional().default([]),
+    env: z15.record(z15.string()).optional().default({})
   }),
-  z14.object({
-    type: z14.enum(["http", "sse"]),
-    url: z14.string().url(),
-    headers: z14.record(z14.string()).optional().default({})
+  z15.object({
+    type: z15.enum(["http", "sse"]),
+    url: z15.string().url(),
+    headers: z15.record(z15.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 McpCapabilitiesSchema = z15.object({
+  tools: z15.array(z15.string()).optional().default([]),
+  resources: z15.array(z15.string()).optional().default([]),
+  prompts: z15.array(z15.string()).optional().default([])
 });
-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),
+var McpServerFrontmatterSchema = z15.object({
+  name: z15.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
+  description: z15.string().min(1).max(2048),
   version: SemverSchema,
-  mcp_spec_version: z14.string().default("2026-03"),
+  mcp_spec_version: z15.string().default("2026-03"),
   transport: McpTransportSchema,
   capabilities: McpCapabilitiesSchema.optional().default({
     tools: [],
@@ -2162,35 +2343,35 @@ var McpServerFrontmatterSchema = z14.object({
     prompts: []
   }),
   /** Human-readable setup / auth instructions. Surfaced in `kordis info`. */
-  auth_notes: z14.string().optional(),
+  auth_notes: z15.string().optional(),
   /** Required env vars with description + whether they must be secret. */
-  env_schema: z14.record(
-    z14.object({
-      description: z14.string(),
-      required: z14.boolean().default(true),
-      secret: z14.boolean().default(false)
+  env_schema: z15.record(
+    z15.object({
+      description: z15.string(),
+      required: z15.boolean().default(true),
+      secret: z15.boolean().default(false)
     })
   ).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()
+  homepage: z15.string().url().optional(),
+  repository: z15.string().url().optional(),
+  license: z15.string().max(64).optional(),
+  title: z15.string().min(1).max(200).optional()
 }).strict();
 
 // ../../packages/harness-schema/src/types/project-rules.ts
 init_src();
-import { z as z15 } from "zod";
-var ProjectRulesFrontmatterSchema = z15.object({
-  title: z15.string().min(1).max(200),
-  description: z15.string().min(1).max(2048),
+import { z as z16 } from "zod";
+var ProjectRulesFrontmatterSchema = z16.object({
+  title: z16.string().min(1).max(200),
+  description: z16.string().min(1).max(2048),
   version: SemverSchema.optional(),
-  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([]),
+  scope: z16.enum(["root", "nested", "globs"]).default("root"),
+  target_path: z16.string().optional(),
+  globs: z16.array(z16.string()).optional(),
+  target_tools: z16.array(ToolSlugSchema).optional().default([]),
   /** When true, installation is idempotent via `<!-- kordis:... -->` markers. */
-  mergeable: z15.boolean().default(true),
-  license: z15.string().max(64).optional()
+  mergeable: z16.boolean().default(true),
+  license: z16.string().max(64).optional()
 }).strict().refine(
   (v) => v.scope !== "nested" || !!v.target_path,
   { message: 'scope="nested" requires target_path' }
@@ -2201,33 +2382,33 @@ var ProjectRulesFrontmatterSchema = z15.object({
 
 // ../../packages/harness-schema/src/types/custom-agent.ts
 init_src();
-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(),
+import { z as z17 } from "zod";
+var CustomAgentFrontmatterSchema = 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(),
   /** System prompt that defines the agent's persona + rules. Required. */
-  system_prompt: z16.string().min(1).max(5e4),
+  system_prompt: z17.string().min(1).max(5e4),
   /** Optional model override — string passed verbatim to the host. */
-  model: z16.string().optional(),
+  model: z17.string().optional(),
   /** Tools this agent can call. Host-specific names (no uniform namespace). */
-  allowed_tools: z16.array(z16.string()).optional().default([]),
-  disallowed_tools: z16.array(z16.string()).optional().default([]),
+  allowed_tools: z17.array(z17.string()).optional().default([]),
+  disallowed_tools: z17.array(z17.string()).optional().default([]),
   /** Fork/context behaviour hint (Claude: `context: fork` etc.). */
-  context: z16.enum(["inherit", "fork", "isolated"]).optional(),
+  context: z17.enum(["inherit", "fork", "isolated"]).optional(),
   /** Known-good tool runtimes. Empty = untested everywhere. */
-  tool_compat: z16.array(ToolSlugSchema).optional().default([]),
+  tool_compat: z17.array(ToolSlugSchema).optional().default([]),
   /** Pre-load skills when this agent activates. */
-  preload_skills: z16.array(z16.string()).optional().default([]),
-  license: z16.string().max(64).optional(),
-  homepage: z16.string().url().optional()
+  preload_skills: z17.array(z17.string()).optional().default([]),
+  license: z17.string().max(64).optional(),
+  homepage: z17.string().url().optional()
 }).strict();
 
 // ../../packages/harness-schema/src/types/hook.ts
 init_src();
-import { z as z17 } from "zod";
-var HookEventSchema = z17.enum([
+import { z as z18 } from "zod";
+var HookEventSchema = z18.enum([
   "PreToolUse",
   "PostToolUse",
   "UserPromptSubmit",
@@ -2239,37 +2420,37 @@ var HookEventSchema = z17.enum([
   "SubagentStop",
   "Background"
 ]);
-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)
+var HookActionSchema = z18.union([
+  z18.object({
+    type: z18.literal("command"),
+    command: z18.string().min(1),
+    timeout_ms: z18.number().int().positive().max(6e5).optional(),
+    blocking: z18.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)
+  z18.object({
+    type: z18.literal("http"),
+    url: z18.string().url(),
+    method: z18.enum(["GET", "POST", "PUT", "PATCH"]).default("POST"),
+    headers: z18.record(z18.string()).optional().default({}),
+    timeout_ms: z18.number().int().positive().max(6e5).optional(),
+    blocking: z18.boolean().default(false)
   })
 ]);
-var HookBindingSchema = z17.object({
+var HookBindingSchema = z18.object({
   event: HookEventSchema,
-  matcher: z17.string().optional(),
+  matcher: z18.string().optional(),
   action: HookActionSchema
 });
-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(),
+var HookFrontmatterSchema = z18.object({
+  name: z18.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
+  description: z18.string().min(1).max(2048),
+  title: z18.string().min(1).max(200).optional(),
   version: SemverSchema.optional(),
   /** One or more hook bindings. */
-  hooks: z17.array(HookBindingSchema).min(1),
+  hooks: z18.array(HookBindingSchema).min(1),
   /** Declared to surface in search filters — always "claude-code" for now. */
-  tool_compat: z17.array(z17.enum(["claude-code"])).default(["claude-code"]),
-  license: z17.string().max(64).optional()
+  tool_compat: z18.array(z18.enum(["claude-code"])).default(["claude-code"]),
+  license: z18.string().max(64).optional()
 }).strict();
 
 // ../../packages/harness-schema/src/validator.ts
@@ -3299,21 +3480,26 @@ function getTranslator(type, format) {
 }
 
 // src/lockfile.ts
-import { homedir as homedir6 } from "os";
+import { homedir as homedir7 } from "os";
 import { join as join8 } from "path";
 import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir5 } from "fs/promises";
-var LOCKFILE_PATH = join8(homedir6(), ".kordis", "installed.json");
+function kordisHome2() {
+  return process.env["KORDIS_HOME"] ?? join8(homedir7(), ".kordis");
+}
+function lockfilePath() {
+  return join8(kordisHome2(), "installed.json");
+}
 async function readLockfile() {
   try {
-    const raw = await readFile7(LOCKFILE_PATH, "utf8");
+    const raw = await readFile7(lockfilePath(), "utf8");
     return JSON.parse(raw);
   } catch {
     return { packages: {} };
   }
 }
 async function writeLockfile(lf) {
-  await mkdir5(join8(homedir6(), ".kordis"), { recursive: true });
-  await writeFile5(LOCKFILE_PATH, JSON.stringify(lf, null, 2) + "\n", "utf8");
+  await mkdir5(kordisHome2(), { recursive: true });
+  await writeFile5(lockfilePath(), JSON.stringify(lf, null, 2) + "\n", "utf8");
 }
 async function recordInstalled(fullSlug, entry) {
   const lf = await readLockfile();
@@ -3582,7 +3768,7 @@ function logoutCommand() {
 
 // src/commands/setup.ts
 import { readFile as readFile8, writeFile as writeFile7, mkdir as mkdir7, access as access3 } from "fs/promises";
-import { homedir as homedir7 } from "os";
+import { homedir as homedir8 } from "os";
 import { join as join10, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command as Command9 } from "commander";
@@ -3691,8 +3877,11 @@ 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").option(
     "--personalization <choice>",
     "record opt-in non-interactively: 'on' | 'off' (skips the Y/n prompt; safe for agents that just received user consent in chat)"
+  ).option(
+    "--error-telemetry <choice>",
+    "record opt-in non-interactively: 'on' | 'off' (skips the Y/n prompt; agent forwards consent received in chat)"
   ).action(async (opts) => {
-    const home = homedir7();
+    const home = homedir8();
     const dryRun = opts.dryRun ?? false;
     if (opts.personalization !== void 0) {
       const v = opts.personalization.toLowerCase();
@@ -3715,6 +3904,27 @@ function setupCommand() {
         }
       }
     }
+    if (opts.errorTelemetry !== void 0) {
+      const v = opts.errorTelemetry.toLowerCase();
+      if (v !== "on" && v !== "off") {
+        throw new Error("--error-telemetry must be 'on' or 'off'");
+      }
+      if (!dryRun) {
+        const cfg = await loadCliConfig();
+        await saveCliConfig({ ...cfg, error_telemetry: v });
+      }
+      if (!opts.silent) {
+        if (v === "on") {
+          printHuman(
+            c.green("\u2713 error telemetry on") + c.gray(" \u2014 anonymized: kind + cli/node version + platform + sanitized message excerpt (\u2264200 chars). Never carries identity, paths, or env values. Override any time: `KORDIS_NO_TELEMETRY=1` env or `kordis setup --error-telemetry off`")
+          );
+        } else {
+          printHuman(
+            c.gray("\u2192 error telemetry off \u2014 failures stay on your machine.")
+          );
+        }
+      }
+    }
     let hubContent;
     let subSkillContents;
     try {
@@ -3820,6 +4030,30 @@ function setupCommand() {
           );
         }
       }
+      const cfg2 = await loadCliConfig();
+      if (cfg2.error_telemetry === "undecided") {
+        printHuman("");
+        const { enable } = await prompts({
+          type: "confirm",
+          name: "enable",
+          message: "Send anonymized error reports to help fix wild failures? Payload: kind + cli/node version + platform + sanitized message excerpt (\u2264200 chars). NEVER includes paths, env values, identity, query text, or the full stack. KORDIS_NO_TELEMETRY=1 disables any time.",
+          initial: true
+        });
+        const newCfg = {
+          ...cfg2,
+          error_telemetry: enable ? "on" : "off"
+        };
+        await saveCliConfig(newCfg);
+        if (enable) {
+          printHuman(
+            c.green("\u2713 error telemetry on") + c.gray(" \u2014 disable any time: `KORDIS_NO_TELEMETRY=1` env or `kordis setup --error-telemetry off`")
+          );
+        } else {
+          printHuman(
+            c.gray("\u2192 error telemetry off \u2014 failures stay on your machine.")
+          );
+        }
+      }
     }
   });
 }
@@ -3833,6 +4067,8 @@ var KINDS = [
   "praise",
   "question"
 ];
+var LIST_SORTS = ["recent", "old"];
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function commentCommand() {
   return new Command10("comment").description("post a comment on a package").argument("<full_slug>", "package identifier {username}/{slug}").requiredOption("--body <text>", "comment body (1\u201310000 chars)").option("--kind <kind>", `top-level kind: ${KINDS.join("|")}`, "comment").option("--title <text>", "top-level post title (1\u2013140 chars)").action(
     async (rawSlug, opts) => {
@@ -3863,11 +4099,103 @@ function commentCommand() {
           if (res.permalink) {
             printHuman(c.gray(`  view: ${res.permalink}`));
           }
+          printHuman(c.gray(`  delete: kordis uncomment ${res.id}`));
         }
       });
     }
   );
 }
+function commentsCommand() {
+  return new Command10("comments").description("list comments on a package").argument("<full_slug>", "package identifier {username}/{slug}").option("--limit <n>", "max top-level comments (1\u201350)", (v) => parseInt(v, 10), 20).option("--cursor <token>", "pagination cursor returned by a prior call as next_cursor").option(
+    "--kind <kind>",
+    `filter top-level posts by kind: ${KINDS.join("|")}`
+  ).option("--sort <mode>", `sort: ${LIST_SORTS.join("|")} (default: recent)`).action(
+    async (rawSlug, opts) => {
+      const [username, slug] = rawSlug.split("/");
+      if (!username || !slug) {
+        throw new Error('full_slug must be "{username}/{slug}"');
+      }
+      if (opts.kind && !KINDS.includes(opts.kind)) {
+        throw new Error(`--kind must be one of ${KINDS.join(", ")}`);
+      }
+      if (opts.sort && !LIST_SORTS.includes(opts.sort)) {
+        throw new Error(`--sort must be one of ${LIST_SORTS.join(", ")}`);
+      }
+      const bundle = await useClient();
+      const res = await bundle.api.listComments(username, slug, {
+        limit: opts.limit,
+        ...opts.cursor ? { cursor: opts.cursor } : {},
+        ...opts.kind ? { kind: opts.kind } : {},
+        ...opts.sort ? { sort: opts.sort } : {}
+      });
+      printDual({
+        json: res,
+        human: () => {
+          if (res.results.length === 0) {
+            printHuman(c.yellow("(no comments)"));
+            printHuman(
+              c.gray("  \u2192 be the first: kordis comment " + rawSlug + ' --body "..."')
+            );
+            return;
+          }
+          printHuman(
+            c.gray(
+              `Showing ${res.results.length} of ${res.total} top-level comment${res.total === 1 ? "" : "s"}`
+            )
+          );
+          printHuman("");
+          for (const node of res.results) {
+            renderCommentNode(node, 0);
+          }
+          if (res.next_cursor) {
+            printHuman(
+              c.gray(
+                `(more available \u2014 kordis comments ${rawSlug} --cursor ${res.next_cursor})`
+              )
+            );
+          }
+        }
+      });
+    }
+  );
+}
+function renderCommentNode(node, depth) {
+  const indent = "  ".repeat(depth);
+  const tag = node.kind === "comment" ? "" : c.cyan(`[${node.kind}]`) + " ";
+  const title = node.title ? c.bold(node.title) + " " : "";
+  const author = `${node.author.username}${node.author.display_name ? ` (${node.author.display_name})` : ""}`;
+  printHuman(`${indent}${tag}${title}${c.gray(`\u2014 ${author}`)}`);
+  for (const line of node.body.split("\n")) {
+    printHuman(`${indent}  ${line}`);
+  }
+  const trail = [`id: ${node.id}`];
+  if (node.reply_count > 0) trail.push(`${node.reply_count} repl${node.reply_count === 1 ? "y" : "ies"}`);
+  if (node.is_edited) trail.push("edited");
+  if (node.permalink) trail.push(`view: ${node.permalink}`);
+  printHuman(c.gray(`${indent}  ${trail.join(" \xB7 ")}`));
+  printHuman("");
+  for (const child of node.replies) {
+    renderCommentNode(child, depth + 1);
+  }
+}
+function uncommentCommand() {
+  return new Command10("uncomment").description("delete one of your comments by id").argument("<id>", "comment id (uuid v4)").action(async (id) => {
+    if (!UUID_RE.test(id)) {
+      throw new Error(
+        "comment id must be a uuid v4 \u2014 get it from `kordis comments <slug>` or the `id` field on `kordis comment`'s response"
+      );
+    }
+    const bundle = await useClient();
+    requireAuth(bundle);
+    await bundle.authedRequest((api) => api.deleteComment(id));
+    printDual({
+      json: { status: "deleted", id },
+      human: () => {
+        printHuman(c.gray(`\u2717 deleted comment ${id}`));
+      }
+    });
+  });
+}
 
 // src/commands/star.ts
 import { Command as Command11 } from "commander";
@@ -4465,6 +4793,8 @@ function buildProgram() {
   program.addCommand(readCommand());
   program.addCommand(infoCommand());
   program.addCommand(commentCommand());
+  program.addCommand(commentsCommand());
+  program.addCommand(uncommentCommand());
   program.addCommand(starCommand());
   program.addCommand(unstarCommand());
   program.addCommand(deleteCommand());
@@ -4533,6 +4863,7 @@ function handleError(err) {
       printHuman(c.red(`\u2717 ${err.message}`));
       for (const line of hint.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
     }
+    void reportError("network_unreachable", err);
     process.exit(err.exitCode());
   }
   if (err instanceof Error) {
@@ -4552,6 +4883,7 @@ function handleError(err) {
         for (const line of hintStr.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
       }
     }
+    void reportError("unhandled_error", err);
     process.exit(1);
   }
   if (isJsonMode()) printJson({ error: { code: "generic_failure", message: String(err) } });

package/package.json

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