@rayul/kordis 0.6.7 → 0.7.1

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-search/SKILL.md

@@ -26,7 +26,8 @@ Keyword search; `--json` for parsing.
 | `--trending`     | list packages trending in `--window` (overrides `--sort`)                |
 | `--rising`       | list rising packages by 7d acceleration (overrides `--sort`)             |
 | `--window <w>`   | `24h` (default), `7d`, or `30d` — only honoured with `--trending`        |
-| `--limit <n>`    | max results (default 20)                                                 |
+| `--limit <n>`    | max results per page (default 20, max 100)                               |
+| `--cursor <t>`   | pagination — pass `next_cursor` from a prior response to fetch page 2+. 0.6.7+. |
 
 ### `kordis info <full_slug> --json`
 Inspect metadata (title, description, type, tier, version, author, stars,
@@ -121,3 +122,13 @@ User: "how many packages has alice published?" / "alice가 publish한거 다 보
   `total: null`); render "Showing N of M matches"
 - do NOT post-process with jq for author filtering — use the flag
 </example>
+
+<example>
+User: "show me page 2 of those results" / "다음 페이지 보여줘"
+- response from page 1 carries `next_cursor` (opaque base64 token, or
+  `null` when no more pages)
+- kordis search <q> --cursor <token> --json   # 0.6.7+
+- keep feeding `next_cursor` from each response until it comes back `null`
+- DO NOT try `--offset` for cursor-paginated endpoints — CLI passes
+  `--cursor` only
+</example>

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();
   }
 });
 
@@ -929,20 +993,35 @@ var init_client = __esm({
         };
         if (opts.body !== void 0) headers["content-type"] = "application/json";
         let res;
-        try {
-          const init = {
-            method: opts.method ?? "GET",
-            headers,
-            cache: "no-store"
-          };
-          if (opts.body !== void 0) init.body = JSON.stringify(opts.body);
-          res = await this.fetchImpl(url, init);
-        } catch (err) {
+        const init = {
+          method: opts.method ?? "GET",
+          headers,
+          cache: "no-store"
+        };
+        if (opts.body !== void 0) init.body = JSON.stringify(opts.body);
+        const method = (init.method ?? "GET").toUpperCase();
+        const retryable = method === "GET";
+        let lastErr;
+        for (let attempt = 0; attempt < (retryable ? 2 : 1); attempt++) {
+          try {
+            res = await this.fetchImpl(url, init);
+            lastErr = void 0;
+            break;
+          } catch (err) {
+            lastErr = err;
+            if (attempt === 0 && retryable) {
+              await new Promise((resolve2) => setTimeout(resolve2, 150));
+              continue;
+            }
+          }
+        }
+        if (lastErr !== void 0) {
           throw new KordisNetworkError(
-            `cannot reach ${url.hostname}: ${err.message}`,
-            err
+            `cannot reach ${url.hostname}: ${lastErr.message}`,
+            lastErr
           );
         }
+        res = res;
         const requestId = res.headers.get("x-request-id") ?? void 0;
         if (res.status === 204) return void 0;
         const text = await res.text();
@@ -1136,6 +1215,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 +1283,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 +1616,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 +1728,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 +1759,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) {
@@ -1628,9 +1789,10 @@ async function useClient() {
             username = null;
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(
-              `[kordis] auto-finalize: server issued tokens but local persistence failed (${msg}). Run \`kordis login --emit-only\` again to retry.
+              `[kordis] auto-finalize: server issued tokens but local persistence failed (${msg}). Run \`kordis login --emit-only\` again to retry. If this keeps happening on macOS, the OS keychain prompt may be timing out \u2014 set \`KORDIS_NO_KEYCHAIN=1\` to fall back to a plaintext file at ~/.kordis/.tokens.json (mode 0600). Set \`KORDIS_DEBUG=1\` for full auto-finalize stage output.
 `
             );
+            void reportError("auto_finalize_stage2_fail", err);
           }
         }
       }
@@ -1821,7 +1983,7 @@ function requireAuth(bundle) {
     error: {
       code: "not_authenticated",
       message: "authentication required",
-      hint: "Run `kordis login --emit-only` to start browser sign-in (exits immediately, no blocking poll), then re-run this command \u2014 the next CLI call auto-claims the token. For interactive shells, plain `kordis login` (10-min poll) also works."
+      hint: "Run `kordis login --emit-only` to start browser sign-in (exits immediately, no blocking poll), then re-run this command \u2014 the next CLI call auto-claims the token. For interactive shells, plain `kordis login` (10-min poll) also works. If you DID login but auth keeps failing, run with `KORDIS_DEBUG=1` to surface auto-finalize stages (Round 12 F1 \u2014 diagnostic moment-of-need)."
     }
   });
 }
@@ -1848,10 +2010,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");
@@ -2107,9 +2269,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("*")
 });
@@ -2145,50 +2307,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: [],
@@ -2196,35 +2358,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' }
@@ -2235,33 +2397,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",
@@ -2273,37 +2435,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
@@ -3333,11 +3495,11 @@ 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";
 function kordisHome2() {
-  return process.env["KORDIS_HOME"] ?? join8(homedir6(), ".kordis");
+  return process.env["KORDIS_HOME"] ?? join8(homedir7(), ".kordis");
 }
 function lockfilePath() {
   return join8(kordisHome2(), "installed.json");
@@ -3621,7 +3783,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";
@@ -3730,8 +3892,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();
@@ -3754,6 +3919,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 {
@@ -3859,6 +4045,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.")
+          );
+        }
+      }
     }
   });
 }
@@ -4588,7 +4798,16 @@ function buildProgram() {
   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);
-  });
+  }).addHelpText("after", `
+Environment variables (see README.md "Privacy & environment variables"):
+  KORDIS_API_URL=<url>     override registry endpoint (default: https://api.kordis.store)
+  KORDIS_HOME=<dir>        override config + token fallback dir (default: ~/.kordis)
+  KORDIS_NO_CONTEXT=1      suppress personalization header even if opted in
+  KORDIS_NO_TELEMETRY=1    suppress anonymized error telemetry even if opted in
+  KORDIS_NO_KEYCHAIN=1     force plaintext token storage at ~/.kordis/.tokens.json
+                           (escape hatch for macOS keychain-prompt fatigue)
+  KORDIS_DEBUG=1           surface auto-finalize stage outcomes to stderr (diagnostic)
+`);
   program.addCommand(loginCommand());
   program.addCommand(logoutCommand());
   program.addCommand(whoamiCommand());
@@ -4668,6 +4887,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) {
@@ -4687,6 +4907,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.7",
+  "version": "0.7.1",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "MIT",