@rayul/kordis 0.11.0 → 0.12.0

package/dist/index.js

@@ -20,7 +20,7 @@ var init_primitives = __esm({
     UsernameSchema = z.string().min(3).max(32).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "username must be lowercase alphanumeric with single hyphens");
     SlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "slug must be lowercase alphanumeric with single hyphens");
     FullSlugSchema = z.string().min(5).max(128).regex(/^[a-z0-9](-?[a-z0-9])*\/[a-z0-9](-?[a-z0-9])*$/, "full_slug must match {username}/{slug}");
-    SemverSchema = z.string().regex(
+    SemverSchema = z.string().max(32).regex(
       // eslint-disable-next-line no-useless-escape
       /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,
       "must be a valid semver version"
@@ -45,7 +45,7 @@ var init_primitives = __esm({
 
 // ../../packages/contracts/src/enums.ts
 import { z as z2 } from "zod";
-var HarnessTypeSchema, PHASE_1_TYPES, TierSchema, TIER_OF_TYPE, CAPABILITIES_OF_TYPE, SortModeSchema, TimeWindowSchema, VisibilitySchema, ReviewStatusSchema, PublishStatusSchema, DependencyKindSchema, OAuthProviderSchema, UserRoleSchema, ReportReasonSchema;
+var HarnessTypeSchema, PHASE_1_TYPES, TierSchema, TIER_OF_TYPE, CAPABILITIES_OF_TYPE, FamilySchema, LineageKindSchema, TrustTierSchema, SortModeSchema, TimeWindowSchema, VisibilitySchema, ReviewStatusSchema, PublishStatusSchema, DependencyKindSchema, OAuthProviderSchema, UserRoleSchema, ReportReasonSchema;
 var init_enums = __esm({
   "../../packages/contracts/src/enums.ts"() {
     "use strict";
@@ -55,6 +55,7 @@ var init_enums = __esm({
       "skill",
       "custom-agent",
       "hook",
+      "judgment-pattern",
       "scoped-rule",
       "mdc-rule",
       "plugin"
@@ -64,13 +65,17 @@ var init_enums = __esm({
       "project-rules",
       "skill",
       "custom-agent",
-      "hook"
+      "hook",
+      "judgment-pattern"
     ];
     TierSchema = z2.enum(["A", "B", "C", "D"]);
     TIER_OF_TYPE = {
       "mcp-server": "A",
       "project-rules": "A",
       skill: "A",
+      // Judgment is the most portable unit of all — it carries no tool-specific
+      // wiring, only reasoning. Tier A so it surfaces in every read/search gate.
+      "judgment-pattern": "A",
       "custom-agent": "B",
       "scoped-rule": "B",
       hook: "C",
@@ -80,6 +85,8 @@ var init_enums = __esm({
     CAPABILITIES_OF_TYPE = {
       skill: { jit_eligible: true, executable: false },
       "project-rules": { jit_eligible: true, executable: false },
+      // A judgment is pure text-to-read — never installs or runs anything.
+      "judgment-pattern": { jit_eligible: true, executable: false },
       "custom-agent": { jit_eligible: true, executable: false },
       "scoped-rule": { jit_eligible: true, executable: false },
       "mdc-rule": { jit_eligible: true, executable: false },
@@ -87,6 +94,14 @@ var init_enums = __esm({
       hook: { jit_eligible: false, executable: true },
       plugin: { jit_eligible: false, executable: true }
     };
+    FamilySchema = z2.enum(["component", "judgment"]);
+    LineageKindSchema = z2.enum(["adaptation", "fork", "absorption", "remix"]);
+    TrustTierSchema = z2.enum([
+      "re-verified",
+      "community-adapted",
+      "author-reported",
+      "unsubstantiated"
+    ]);
     SortModeSchema = z2.enum([
       "stars",
       "downloads",
@@ -103,13 +118,7 @@ var init_enums = __esm({
     DependencyKindSchema = z2.enum(["required", "recommended"]);
     OAuthProviderSchema = z2.enum(["discord", "github", "google"]);
     UserRoleSchema = z2.enum(["user", "moderator", "admin"]);
-    ReportReasonSchema = z2.enum([
-      "spam",
-      "harmful",
-      "incorrect",
-      "copyright",
-      "other"
-    ]);
+    ReportReasonSchema = z2.enum(["spam", "harmful", "incorrect", "copyright", "other"]);
   }
 });
 
@@ -329,6 +338,14 @@ var init_package = __esm({
       recommends: z6.array(DependencySpecSchema),
       categories: z6.array(z6.string()).optional().default([]),
       verified_by_kordis: z6.boolean(),
+      /**
+       * v2.1+ — derived evidence trust tier. Non-null only for the `judgment`
+       * family (a judgment's value rests on "this works"); null for component
+       * types. Strongest-wins over {verified_by_kordis, distinct-author lineage
+       * adopters, presence of an `evidence` frontmatter field}. See TrustTierSchema.
+       * Optional so pre-0.12 responses parse cleanly.
+       */
+      trust_tier: TrustTierSchema.nullable().optional(),
       /**
        * 0.9.0+ — when the caller pinned a `@version` or `@range`, the
        * concrete resolved version. Absent for bare-slug calls (where the
@@ -387,13 +404,7 @@ var init_comment = __esm({
     "use strict";
     init_primitives();
     init_user();
-    CommentKindSchema = z7.enum([
-      "comment",
-      "tip",
-      "report",
-      "praise",
-      "question"
-    ]);
+    CommentKindSchema = z7.enum(["comment", "tip", "report", "praise", "question"]);
     CommentStatusSchema = z7.enum(["open", "resolved"]);
     CommentSchema = z7.object({
       id: UuidSchema,
@@ -417,7 +428,7 @@ var init_comment = __esm({
       is_deleted: z7.boolean(),
       created_at: IsoDateTimeSchema,
       /**
-       * Web permalink (`https://kordis.store/p/<full_slug>#comment-<id>`). Server
+       * Web permalink (`https://kordis.store/<full_slug>#comment-<id>`). Server
        * populates whenever it has the package slug at serialization time —
        * always on create + list paths; absent on update/status paths that don't
        * carry the slug. Old API responses (pre-0.6.4) omit it; new clients use
@@ -474,12 +485,12 @@ var init_auth = __esm({
       from: z8.enum(["web", "cli"]).default("web")
     });
     DeviceCodeRequestSchema = z8.object({
-      provider: OAuthProviderSchema.default("discord")
+      provider: OAuthProviderSchema.default("google")
     });
     DeviceCodeResponseSchema = z8.object({
       device_code: z8.string().min(16),
-      user_code: z8.string().length(8),
-      // shown to the user: e.g. "KORDIS-AB12"
+      user_code: z8.string().regex(/^KORDIS-[0-9A-Z]{4}-[0-9A-Z]{4}$/),
+      // shown to the user: e.g. "KORDIS-7QFX-2M9K"
       verification_url: z8.string().url(),
       expires_in: z8.number().int().positive(),
       // seconds
@@ -515,7 +526,7 @@ var init_auth = __esm({
 
 // ../../packages/contracts/src/api.ts
 import { z as z9 } from "zod";
-var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, AssetSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageRequestSchema, PullPackageResponseSchema, YankRequestSchema, YankResponseSchema, ResolveVersionQuerySchema, ResolveVersionResponseSchema, GetPackageQuerySchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema, ListUserPackagesResponseSchema, ListUserStarsResponseSchema, FollowResponseSchema, ListFollowersQuerySchema, ListFollowersResponseSchema;
+var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, AssetSchema, LineageEdgeInputSchema, LineageRelativeSchema, LineageStatsSchema, LineageGraphResponseSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageRequestSchema, PullPackageResponseSchema, YankRequestSchema, YankResponseSchema, ResolveVersionQuerySchema, ResolveVersionResponseSchema, GetPackageQuerySchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema, ListUserPackagesResponseSchema, ListUserStarsResponseSchema, FollowResponseSchema, ListFollowersQuerySchema, ListFollowersResponseSchema;
 var init_api = __esm({
   "../../packages/contracts/src/api.ts"() {
     "use strict";
@@ -556,9 +567,41 @@ var init_api = __esm({
     });
     AssetSchema = z9.object({
       path: z9.string().min(1).max(255),
-      content: z9.string(),
+      // Schema-level backstop only: publish-service enforces the real 2 MB
+      // BYTE cap (utf8 chars can be multi-byte, base64 inflates 4/3). The
+      // char ceiling here just keeps non-core-api consumers of the contract
+      // from accepting unbounded strings.
+      content: z9.string().max(3e6),
       encoding: z9.enum(["utf8", "base64"]).default("utf8")
     });
+    LineageEdgeInputSchema = z9.object({
+      to_full_slug: FullSlugSchema,
+      to_version: SemverSchema.optional(),
+      kind: LineageKindSchema
+    });
+    LineageRelativeSchema = z9.object({
+      full_slug: FullSlugSchema,
+      title: z9.string(),
+      type: HarnessTypeSchema,
+      kind: LineageKindSchema,
+      /** Version snapshot recorded on the edge (the side facing this relative). */
+      version: SemverSchema.nullable(),
+      declared: z9.boolean()
+    });
+    LineageStatsSchema = z9.object({
+      /** Longest ancestor chain depth (capped traversal). */
+      lineage_depth: z9.number().int(),
+      /** Distinct packages derived FROM this one (the trust count). */
+      descendant_count: z9.number().int(),
+      /** Descendants whose edge kind is `absorption`. */
+      absorption_count: z9.number().int()
+    });
+    LineageGraphResponseSchema = z9.object({
+      full_slug: FullSlugSchema,
+      ancestors: z9.array(LineageRelativeSchema),
+      descendants: z9.array(LineageRelativeSchema),
+      stats: LineageStatsSchema
+    });
     PublishPackageRequestSchema = z9.object({
       /**
        * Raw source content — YAML frontmatter + markdown body. Server parses and
@@ -585,6 +628,12 @@ var init_api = __esm({
       changelog: z9.string().max(2e3).optional(),
       depends: z9.array(z9.string()).optional(),
       recommends: z9.array(z9.string()).optional(),
+      /**
+       * Declared provenance: sources this package was adapted / forked / absorbed /
+       * remixed from (`kordis push --adapted-from`). Recorded as `lineage_edges`;
+       * unresolved sources are skipped fail-open, never blocking the publish.
+       */
+      lineage: z9.array(LineageEdgeInputSchema).max(20).optional(),
       visibility: VisibilitySchema.optional(),
       /**
        * Skip draft validation (preview mode) — only allowed in dev builds.
@@ -621,6 +670,15 @@ var init_api = __esm({
         version_from: SemverSchema.nullable(),
         version_to: SemverSchema
       }).nullable(),
+      /**
+       * Declared-lineage outcome, present only when the publish supplied `lineage`.
+       * `skipped` lists sources that could not be resolved (recorded fail-open, not
+       * an error) so the agent can fix a typo or publish the source first.
+       */
+      lineage: z9.object({
+        recorded: z9.number().int().nonnegative(),
+        skipped: z9.array(FullSlugSchema)
+      }).optional(),
       published_at: z9.string().datetime()
     });
     PackagePathParamsSchema = z9.object({
@@ -679,7 +737,23 @@ var init_api = __esm({
        * the schema for backwards compatibility with pre-0.2.3 servers; the
        * current server always populates it (empty array when no assets).
        */
-      bundled_assets: z9.array(z9.string()).optional()
+      bundled_assets: z9.array(z9.string()).optional(),
+      /**
+       * 0.11.x+ — soft-yank signal. An explicitly pinned yanked version is
+       * still served (reproducibility, mirroring pull), but the reading agent
+       * must be told so it can decide whether to trust the content. Optional
+       * for backwards compatibility with older servers; the current server
+       * always populates `yanked`.
+       */
+      yanked: z9.boolean().optional(),
+      yank_reason: z9.string().nullable().optional(),
+      /**
+       * v2.1+ — derived evidence trust tier (see TrustTierSchema). Non-null only
+       * for the `judgment` family, so a reading agent can weight a self-reported
+       * claim differently from a community-corroborated one. Optional for
+       * backwards compatibility with pre-0.12 servers.
+       */
+      trust_tier: TrustTierSchema.nullable().optional()
     });
     PullPackageRequestSchema = z9.object({
       /**
@@ -1088,6 +1162,9 @@ var init_errors2 = __esm({
 });
 
 // ../../packages/api-client/src/client.ts
+function seg(value) {
+  return encodeURIComponent(value);
+}
 var KordisClient;
 var init_client = __esm({
   "../../packages/api-client/src/client.ts"() {
@@ -1139,10 +1216,11 @@ var init_client = __esm({
         const retryable = method === "GET";
         const debug = typeof process !== "undefined" && process.env && (process.env["KORDIS_DEBUG"] === "1" || process.env["KORDIS_DEBUG"]?.toLowerCase() === "true");
         const debugStart = debug ? Date.now() : 0;
+        const timeoutMs = this.config.requestTimeoutMs ?? 6e4;
         let lastErr;
         for (let attempt = 0; attempt < (retryable ? 2 : 1); attempt++) {
           try {
-            res = await this.fetchImpl(url, init);
+            res = await this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
             lastErr = void 0;
             break;
           } catch (err) {
@@ -1153,7 +1231,7 @@ var init_client = __esm({
                   `[kordis] api: ${method} ${url.pathname}${url.search} \u2192 fetch failed, retrying in 150ms (${err.message})`
                 );
               }
-              await new Promise((resolve2) => setTimeout(resolve2, 150));
+              await new Promise((resolve3) => setTimeout(resolve3, 150));
               continue;
             }
           }
@@ -1178,7 +1256,12 @@ var init_client = __esm({
         }
         if (res.status === 204) return void 0;
         const text = await res.text();
-        const parsed = text ? JSON.parse(text) : void 0;
+        let parsed;
+        try {
+          parsed = text ? JSON.parse(text) : void 0;
+        } catch {
+          parsed = void 0;
+        }
         if (!res.ok) {
           const envelope = normalizeErrorEnvelope(res.status, parsed, text);
           throw new KordisApiError(res.status, envelope, requestId);
@@ -1235,22 +1318,22 @@ var init_client = __esm({
         });
       }
       update(username, slug, body) {
-        return this.request(`/api/packages/${username}/${slug}`, {
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}`, {
           method: "PUT",
           body
         });
       }
       getPackage(username, slug, opts = {}) {
-        return this.request(`/api/packages/${username}/${slug}`, {
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}`, {
           query: opts
         });
       }
       deletePackage(username, slug) {
-        return this.request(`/api/packages/${username}/${slug}`, { method: "DELETE" });
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}`, { method: "DELETE" });
       }
       getContent(username, slug, opts = {}) {
         return this.request(
-          `/api/packages/${username}/${slug}/content`,
+          `/api/packages/${seg(username)}/${seg(slug)}/content`,
           { query: opts }
         );
       }
@@ -1260,15 +1343,15 @@ var init_client = __esm({
        */
       resolveVersion(username, slug, range) {
         return this.request(
-          `/api/packages/${username}/${slug}/resolve`,
+          `/api/packages/${seg(username)}/${seg(slug)}/resolve`,
           { query: { range } }
         );
       }
       pull(username, slug, opts = {}) {
-        return this.request(
-          `/api/packages/${username}/${slug}/pull`,
-          { method: "POST", body: opts }
-        );
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}/pull`, {
+          method: "POST",
+          body: opts
+        });
       }
       /**
        * JIT read — fetch the canonical body into agent context. Plan v1.1.
@@ -1276,10 +1359,10 @@ var init_client = __esm({
        * (passed-only unless `allow_pending=true`).
        */
       jitRead(username, slug, body = {}) {
-        return this.request(
-          `/api/packages/${username}/${slug}/read`,
-          { method: "POST", body }
-        );
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}/read`, {
+          method: "POST",
+          body
+        });
       }
       search(query) {
         return this.request("/api/packages/search", {
@@ -1324,18 +1407,24 @@ var init_client = __esm({
         });
       }
       star(username, slug) {
-        return this.request(`/api/packages/${username}/${slug}/star`, {
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}/star`, {
           method: "POST"
         });
       }
       unstar(username, slug) {
-        return this.request(`/api/packages/${username}/${slug}/star`, {
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}/star`, {
           method: "DELETE"
         });
       }
       versions(username, slug) {
         return this.request(
-          `/api/packages/${username}/${slug}/versions`
+          `/api/packages/${seg(username)}/${seg(slug)}/versions`
+        );
+      }
+      /** Provenance graph (Phase 2): ancestors + direct descendants + trust stats. */
+      lineage(username, slug) {
+        return this.request(
+          `/api/packages/${seg(username)}/${seg(slug)}/lineage`
         );
       }
       /**
@@ -1346,31 +1435,31 @@ var init_client = __esm({
       yankVersion(username, slug, version, body = {}, opts = {}) {
         const query = opts.asAdmin ? { as: "admin" } : void 0;
         return this.request(
-          `/api/packages/${username}/${slug}/versions/${version}/yank`,
+          `/api/packages/${seg(username)}/${seg(slug)}/versions/${seg(version)}/yank`,
           { method: "POST", body, ...query ? { query } : {} }
         );
       }
       unyankVersion(username, slug, version, opts = {}) {
         const query = opts.asAdmin ? { as: "admin" } : void 0;
         return this.request(
-          `/api/packages/${username}/${slug}/versions/${version}/yank`,
+          `/api/packages/${seg(username)}/${seg(slug)}/versions/${seg(version)}/yank`,
           { method: "DELETE", ...query ? { query } : {} }
         );
       }
       diff(username, slug, from, to) {
-        return this.request(`/api/packages/${username}/${slug}/diff`, {
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}/diff`, {
           query: { from, to }
         });
       }
       // ─── comments ──────────────────────────────────────────────────────────
       listComments(username, slug, query = {}) {
         return this.request(
-          `/api/packages/${username}/${slug}/comments`,
+          `/api/packages/${seg(username)}/${seg(slug)}/comments`,
           { query }
         );
       }
       createComment(username, slug, body) {
-        return this.request(`/api/packages/${username}/${slug}/comments`, {
+        return this.request(`/api/packages/${seg(username)}/${seg(slug)}/comments`, {
           method: "POST",
           body
         });
@@ -1396,9 +1485,7 @@ var init_client = __esm({
         return this.request(`/api/comments/${id}`, { method: "DELETE" });
       }
       listReplies(id) {
-        return this.request(
-          `/api/comments/${id}/replies`
-        );
+        return this.request(`/api/comments/${id}/replies`);
       }
       // ─── telemetry ─────────────────────────────────────────────────────────
       /**
@@ -1432,10 +1519,9 @@ var init_client = __esm({
       }
       /** Cursor-paginated packages that `username` has starred. */
       listUserStars(username, query = {}) {
-        return this.request(
-          `/api/users/${encodeURIComponent(username)}/stars`,
-          { query }
-        );
+        return this.request(`/api/users/${encodeURIComponent(username)}/stars`, {
+          query
+        });
       }
       /** Auth-required. Idempotent (re-follow is a no-op). Returns post-mutation counter. */
       followUser(username) {
@@ -1485,7 +1571,7 @@ var init_src2 = __esm({
 
 // src/index.ts
 init_src2();
-import { Command as Command25 } from "commander";
+import { Command as Command26 } from "commander";
 
 // src/commands/login.ts
 import { Command } from "commander";
@@ -1523,7 +1609,7 @@ async function loadCliConfig() {
 }
 async function saveCliConfig(cfg) {
   await mkdir(configDir(), { recursive: true });
-  await writeFile(configPath(), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+  await writeFile(configPath(), JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 384 });
 }
 
 // src/keychain.ts
@@ -1919,7 +2005,7 @@ async function reportError(kind, err, extras = {}) {
     });
     await Promise.race([
       client.recordTelemetryError(payload),
-      new Promise((resolve2) => setTimeout(resolve2, REPORT_TIMEOUT_MS))
+      new Promise((resolve3) => setTimeout(resolve3, REPORT_TIMEOUT_MS))
     ]);
   } catch {
   }
@@ -1947,7 +2033,7 @@ async function readPending() {
 }
 async function savePending(file) {
   await mkdir3(dir(), { recursive: true });
-  await writeFile3(path(), JSON.stringify(file, null, 2) + "\n", "utf8");
+  await writeFile3(path(), JSON.stringify(file, null, 2) + "\n", { encoding: "utf8", mode: 384 });
 }
 async function clearPending() {
   try {
@@ -2105,16 +2191,31 @@ function spinner(text) {
 var c = kleur;
 
 // src/commands/login.ts
+function assertSafeVerificationUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`registry returned an invalid verification URL: ${JSON.stringify(raw)}`);
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new Error(
+      `registry returned a verification URL with unexpected scheme "${url.protocol}" \u2014 refusing to open it. Check KORDIS_API_URL.`
+    );
+  }
+}
 function loginCommand() {
-  return new Command("login").description("authenticate with the Kordis registry").option("--provider <name>", "OAuth provider", "discord").option("--no-browser", "don't auto-open the browser; print the URL instead").option(
+  return new Command("login").description("authenticate with the Kordis registry").option("--provider <name>", "OAuth provider", "google").option("--no-browser", "don't auto-open the browser; print the URL instead").option(
     "--emit-only",
     "start device flow, open browser, save pending state, exit immediately \u2014 for non-interactive (agent) contexts where the 10-min poll would exceed the bash timeout"
   ).action(async (opts) => {
     const bundle = await useClient();
     const started = spinner("Requesting device code");
-    const provider = opts.provider ?? "discord";
+    const provider = opts.provider ?? "google";
     const device = await bundle.api.startDeviceFlow(provider);
     started.succeed();
+    assertSafeVerificationUrl(device.verification_url);
     printHuman("");
     printHuman(c.bold("Confirm the code in your browser:"));
     printHuman("  " + c.yellow(device.user_code));
@@ -2187,7 +2288,10 @@ function loginCommand() {
         const cfg = await loadCliConfig();
         await saveCliConfig({ ...cfg, username: me.username, sessionId: tokens.session_id });
         printDual({
-          json: { status: "logged_in", username: me.username, session_id: tokens.session_id },
+          // session_id intentionally omitted: stdout in JSON mode flows
+          // into scripts, CI logs, and agent transcripts. Sessions stay
+          // enumerable via GET /auth/sessions with the stored token.
+          json: { status: "logged_in", username: me.username },
           human: () => printHuman(c.green(`
 \u2713 Logged in as ${c.bold(me.username)}.`))
         });
@@ -2328,12 +2432,21 @@ var TOOL_ALIASES = {
   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(
+  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(
+  ).option("--tier <tier>", "filter by portability tier (A|B|C|D)").option(
+    "--tag <slug>",
+    "filter by tag (e.g. aws, fastapi, llm); tags also boost free-text ranking now"
+  ).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) => {
@@ -2372,6 +2485,7 @@ function searchCommand() {
         type: opts.type ? [opts.type] : void 0,
         tool: resolvedTool ? [resolvedTool] : void 0,
         tier: opts.tier,
+        ...opts.tag ? { tag: opts.tag } : {},
         ...opts.author ? { author: opts.author } : {},
         ...opts.cursor ? { cursor: opts.cursor } : {},
         sort: opts.sort ?? "relevance",
@@ -2379,7 +2493,7 @@ function searchCommand() {
       });
     }
     const queryProvided = query.length > 0;
-    const emptyHint = opts.type ? `no packages of type "${opts.type}" match. Try without --type, or list everything: kordis search --type ${opts.type} --sort recent --limit 25` : queryProvided ? "try `--type skill` (or mcp-server / project-rules / custom-agent / hook) to narrow, or broader keywords" : 'try keywords (e.g. `kordis search "topic"`) or `kordis search --trending`';
+    const emptyHint = opts.type ? `no packages of type "${opts.type}" match. Try without --type, or list everything: kordis search --type ${opts.type} --sort recent --limit 25` : queryProvided ? "narrow with `--type skill|mcp-server|project-rules|custom-agent|hook|judgment-pattern` or `--tag <topic>` (e.g. aws, fastapi), broaden the keywords, or browse `--sort trending`" : 'try keywords (e.g. `kordis search "topic"`), `--tag <topic>`, or `kordis search --trending`';
     printDual({
       json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
@@ -2415,10 +2529,10 @@ function searchCommand() {
         if (res.next_cursor) {
           printHuman(c.gray(`(more available \u2014 pass --cursor ${res.next_cursor})`));
         }
-        if (queryProvided && !opts.type && res.results.length > 3) {
+        if (queryProvided && !opts.type && !opts.tag && res.results.length > 3) {
           printHuman(
             c.gray(
-              "  \u2192 narrow further with `--type skill|mcp-server|project-rules|custom-agent|hook`"
+              "  \u2192 narrow with `--type skill|mcp-server|project-rules|custom-agent|hook|judgment-pattern` or `--tag <topic>`"
             )
           );
         }
@@ -2505,8 +2619,8 @@ function normaliseDep(entry, idx) {
       );
     }
     return {
-      full_slug: m[1],
-      version_range: (m[4] ?? "*").trim()
+      full_slug: FullSlugSchema.parse(m[1]),
+      version_range: SemverRangeSchema.parse((m[4] ?? "*").trim())
     };
   }
   if (typeof entry === "object" && entry !== null) {
@@ -2682,6 +2796,53 @@ var HookFrontmatterSchema = z18.object({
   license: z18.string().max(64).optional()
 }).strict();
 
+// ../../packages/harness-schema/src/types/judgment-pattern.ts
+init_src();
+import { z as z19 } from "zod";
+var FailureModeSchema = z19.object({
+  symptom: z19.string().min(1).max(600).describe("the observable sign the judgment was ignored"),
+  correction: z19.string().min(1).max(1200).describe("what to do once the symptom shows")
+}).strict();
+var AdaptHintsSchema = z19.object({
+  /** Parts that transplant verbatim into ANY harness — the invariant core. */
+  universal: z19.array(z19.string().min(1).max(400)).max(20).optional(),
+  /** Parts the adapting agent must re-express in the host's stack/conventions. */
+  context_specific: z19.array(z19.string().min(1).max(400)).max(20).optional()
+}).strict();
+var JudgmentPatternFrontmatterSchema = z19.object({
+  name: z19.string().min(1).max(64).regex(
+    /^[a-z0-9]+(-[a-z0-9]+)*$/,
+    'name must be lowercase-with-hyphens, e.g. "additive-only-migrations"'
+  ),
+  description: z19.string().min(1).max(2048),
+  version: SemverSchema.optional(),
+  title: z19.string().min(1).max(200).optional(),
+  /** The recurring situation / trap this judgment addresses. */
+  problem: z19.string().min(1).max(4e3),
+  /**
+   * The judgment itself — free-form Markdown. The agent is the interpreter,
+   * so this stays unstructured prose (decision tree, heuristics, rationale).
+   * This is the part that gets transplanted.
+   */
+  decision_logic: z19.string().min(1).max(2e4),
+  /** Triggers — when this judgment should fire. At least one. */
+  when_to_apply: z19.array(z19.string().min(1).max(400)).min(1).max(12),
+  /** Counter-triggers — when applying it would be wrong. */
+  when_not_to_apply: z19.array(z19.string().min(1).max(400)).max(12).optional(),
+  /** How it fails in practice, and how to recover — the hard-won part. */
+  failure_modes: z19.array(FailureModeSchema).max(12).optional(),
+  /** Transplant steering — the field unique to judgment-pattern. */
+  adapt_hints: AdaptHintsSchema.optional(),
+  /** Where this judgment came from (project, incident, paper). Provenance. */
+  origin: z19.string().min(1).max(600).optional(),
+  /** Proof it works (anti-spam lever for AI review). */
+  evidence: z19.string().min(1).max(2e3).optional(),
+  // Kordis-forwarded cross-type fields (kept minimal, like skill).
+  tags: z19.array(TagSchema).max(16).optional(),
+  tools: z19.array(ToolSlugSchema).optional(),
+  license: z19.string().max(64).optional()
+}).strict();
+
 // ../../packages/harness-schema/src/validator.ts
 function flag(code, message, extra = {}) {
   return { code, message, ...extra };
@@ -2713,7 +2874,7 @@ function validatePackageSource(source) {
     return earlyExit(
       flag("missing_required_frontmatter", "`type` is required in frontmatter", {
         field: "type",
-        hint: "Add  type: skill  (or one of: mcp-server, project-rules, custom-agent, hook)"
+        hint: "Add  type: skill  (or one of: mcp-server, project-rules, custom-agent, hook, judgment-pattern)"
       })
     );
   }
@@ -2722,7 +2883,7 @@ function validatePackageSource(source) {
     return earlyExit(
       flag("unknown_type", `type "${typeValue}" is not a recognised Harness type`, {
         field: "type",
-        hint: "Allowed types: skill, mcp-server, project-rules, custom-agent, hook"
+        hint: "Allowed types: skill, mcp-server, project-rules, custom-agent, hook, judgment-pattern"
       })
     );
   }
@@ -2731,7 +2892,7 @@ function validatePackageSource(source) {
     flags.push(
       flag("type_not_phase1", `type "${type}" is planned for Phase 2+ and is not yet accepted`, {
         field: "type",
-        hint: "Use one of the Phase 1 types: skill, mcp-server, project-rules, custom-agent, hook"
+        hint: "Use one of the Phase 1 types: skill, mcp-server, project-rules, custom-agent, hook, judgment-pattern"
       })
     );
     return earlyExit(null, { flags, body });
@@ -2920,6 +3081,11 @@ function dispatchValidation(type, raw) {
       if (!r.success) return zodFail(r.error.issues);
       return { ok: true, frontmatter: { type, data: r.data }, flags: [] };
     }
+    case "judgment-pattern": {
+      const r = JudgmentPatternFrontmatterSchema.safeParse(raw);
+      if (!r.success) return zodFail(r.error.issues);
+      return { ok: true, frontmatter: { type, data: r.data }, flags: [] };
+    }
     default:
       return {
         ok: false,
@@ -2927,7 +3093,7 @@ function dispatchValidation(type, raw) {
         flags: [
           flag("type_not_phase1", `type "${type}" not accepted in Phase 1`, {
             field: "type",
-            hint: "Use one of the Phase 1 types: skill, mcp-server, project-rules, custom-agent, hook"
+            hint: "Use one of the Phase 1 types: skill, mcp-server, project-rules, custom-agent, hook, judgment-pattern"
           })
         ]
       };
@@ -2962,7 +3128,7 @@ var ASSET_MAX_COUNT = 50;
 var SAFE_PATH_RE = /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/;
 function isAssetPathSafe(p) {
   if (!SAFE_PATH_RE.test(p)) return false;
-  return !p.split("/").some((seg) => seg === "..");
+  return p.split("/").every((seg2) => seg2.length > 0 && seg2 !== "." && seg2 !== "..");
 }
 function validateAssets(assets) {
   const flags = [];
@@ -2987,14 +3153,211 @@ function validateAssets(assets) {
   return { ok: flags.length === 0, flags };
 }
 
+// ../../packages/harness-schema/src/sections.ts
+var JUDGMENT_FIELDS = [
+  { key: "problem", label: "Problem" },
+  { key: "decision_logic", label: "Decision logic" },
+  { key: "when_to_apply", label: "When to apply" },
+  { key: "when_not_to_apply", label: "When NOT to apply" },
+  { key: "failure_modes", label: "Failure modes" },
+  { key: "adapt_hints", label: "Adapt hints" },
+  { key: "origin", label: "Origin" },
+  { key: "evidence", label: "Evidence" }
+];
+function slugifyHeading(h) {
+  return h.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function fieldToMarkdown(key, value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value.trim() || null;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+    if (key === "failure_modes") {
+      return value.map((fm) => {
+        const o = fm ?? {};
+        const symptom = typeof o["symptom"] === "string" ? o["symptom"] : "";
+        const correction = typeof o["correction"] === "string" ? o["correction"] : "";
+        return `- **${symptom}**
+  \u2192 ${correction}`;
+      }).join("\n");
+    }
+    return value.map((v) => `- ${String(v)}`).join("\n");
+  }
+  if (typeof value === "object") {
+    const o = value;
+    const parts = [];
+    if (Array.isArray(o["universal"]) && o["universal"].length > 0) {
+      parts.push("**Universal**\n" + o["universal"].map((v) => `- ${String(v)}`).join("\n"));
+    }
+    if (Array.isArray(o["context_specific"]) && o["context_specific"].length > 0) {
+      parts.push(
+        "**Context-specific**\n" + o["context_specific"].map((v) => `- ${String(v)}`).join("\n")
+      );
+    }
+    return parts.length > 0 ? parts.join("\n\n") : null;
+  }
+  return null;
+}
+function splitByHeadings(body) {
+  const lines = body.split("\n");
+  const sections = [];
+  const intro = [];
+  let cur = null;
+  const flush = () => {
+    if (cur) {
+      sections.push({
+        name: slugifyHeading(cur.label) || `section-${sections.length + 1}`,
+        label: cur.label,
+        body: cur.body.join("\n").trim()
+      });
+    }
+  };
+  for (const line of lines) {
+    const m = /^(#{2,3})\s+(.+?)\s*$/.exec(line);
+    if (m) {
+      flush();
+      cur = { label: m[2], body: [] };
+    } else if (cur) {
+      cur.body.push(line);
+    } else {
+      intro.push(line);
+    }
+  }
+  flush();
+  return { intro: intro.join("\n").trim(), sections };
+}
+function outlineOf(source) {
+  let fm = null;
+  let body = source;
+  try {
+    const parsed = parseFrontmatter(source);
+    fm = parsed.frontmatter;
+    body = parsed.body;
+  } catch {
+  }
+  const description = fm && typeof fm["description"] === "string" ? fm["description"] : null;
+  const type = fm && typeof fm["type"] === "string" ? fm["type"] : null;
+  if (type === "judgment-pattern" && fm) {
+    const sections2 = [];
+    for (const { key, label } of JUDGMENT_FIELDS) {
+      const md = fieldToMarkdown(key, fm[key]);
+      if (md !== null) sections2.push({ name: key, label, body: md });
+    }
+    return { description, type, intro: body.trim(), sections: sections2 };
+  }
+  const { intro, sections } = splitByHeadings(body);
+  return { description, type, intro, sections };
+}
+function sectionOf(source, name) {
+  const q = name.trim().toLowerCase();
+  const { sections } = outlineOf(source);
+  return sections.find((s) => s.name === q) ?? sections.find((s) => s.label.toLowerCase() === q) ?? sections.find((s) => s.name === slugifyHeading(name)) ?? null;
+}
+
+// src/lib/parse-username.ts
+init_src();
+var SORT_KEYWORDS = ["latest", "popular", "recent", "updated", "stars", "downloads"];
+function usernameError(message, hint) {
+  const e = new Error(message);
+  e.hint = hint;
+  return e;
+}
+function parseUsername(raw) {
+  if (SORT_KEYWORDS.includes(raw.toLowerCase())) {
+    throw usernameError(
+      `"${raw}" is a sort keyword \u2014 did you mean \`--sort ${raw}\`? Username arguments must follow the Kordis username shape (lowercase alphanumeric, hyphens allowed).`,
+      `Pass it as the sort flag instead, e.g. \`--sort ${raw}\`, or supply an actual username argument.`
+    );
+  }
+  const parsed = UsernameSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw usernameError(
+      `invalid username "${raw}" \u2014 must be 3-32 chars, lowercase alphanumeric with single hyphens (e.g. "alice", "my-team")`,
+      "Usernames are lowercase alphanumeric with single hyphens. Browse existing users with `kordis search` or look one up with `kordis profile <username>`."
+    );
+  }
+  return parsed.data;
+}
+
+// src/lib/parse-slug-version.ts
+var SUFFIX_CHARS = /[\^~*]/;
+function slugError(message, hint) {
+  const e = new Error(message);
+  e.hint = hint;
+  return e;
+}
+function parseSlugAtVersion(raw) {
+  if (!raw.includes("/")) {
+    let username2;
+    try {
+      username2 = parseUsername(raw);
+    } catch {
+      username2 = void 0;
+    }
+    if (username2) {
+      throw slugError(
+        `"${raw}" looks like a username, not a package`,
+        `Try \`kordis profile ${username2}\` for user details, or pass a full slug like "{username}/{slug}".`
+      );
+    }
+    throw slugError(
+      `"${raw}" is missing the "{username}/{slug}" form`,
+      'Use the form "{username}/{slug}", e.g. "alice/json-pretty".'
+    );
+  }
+  const atIdx = raw.indexOf("@");
+  const slugPart = atIdx === -1 ? raw : raw.slice(0, atIdx);
+  const versionPart = atIdx === -1 ? "" : raw.slice(atIdx + 1);
+  const [username, slug] = slugPart.split("/");
+  if (!username || !slug) {
+    throw slugError(
+      'full_slug must be "{username}/{slug}"',
+      'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.'
+    );
+  }
+  if (atIdx !== -1 && versionPart.length === 0) {
+    throw slugError(
+      `"${raw}" has a trailing "@" with no version`,
+      `Drop the "@" or append a version/range, e.g. "${slugPart}@1.0.0" or "${slugPart}@^1".`
+    );
+  }
+  const out = {
+    fullSlug: slugPart,
+    username,
+    slug
+  };
+  if (versionPart.length > 0) {
+    if (SUFFIX_CHARS.test(versionPart)) {
+      out.range = versionPart;
+    } else {
+      out.version = versionPart;
+    }
+  }
+  return out;
+}
+
 // src/commands/push.ts
+var collect = (val, acc) => acc.concat(val);
+function toLineage(raws, kind) {
+  return (raws ?? []).map((raw) => {
+    const p = parseSlugAtVersion(raw);
+    return {
+      to_full_slug: `${p.username}/${p.slug}`,
+      ...p.version ? { to_version: p.version } : {},
+      kind
+    };
+  });
+}
 var ASSET_MAX_BYTES = 2 * 1024 * 1024;
 var BUNDLE_MAX_BYTES = 5 * 1024 * 1024;
 function pushCommand() {
-  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option(
-    "--slug <slug>",
-    'override slug; accepts "user/slug" to point at a specific package'
-  ).option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").action(
+  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option("--slug <slug>", 'override slug; accepts "user/slug" to point at a specific package').option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").option(
+    "--adapted-from <slug>",
+    "source this package was adapted from (repeatable); records lineage",
+    collect,
+    []
+  ).option("--forked-from <slug>", "source this package was forked from (repeatable)", collect, []).option("--absorbs <slug>", "source this package absorbs (repeatable)", collect, []).option("--remixes <slug>", "source this package remixes (repeatable)", collect, []).action(
     async (path2, opts) => {
       const bundle = await useClient();
       const abs = resolve(process.cwd(), path2);
@@ -3076,6 +3439,12 @@ function pushCommand() {
       const spin = spinner(
         opts.dryRun ? "Validating" : targetFullSlug ? `Publishing update to ${targetFullSlug}` : "Publishing"
       );
+      const lineage = [
+        ...toLineage(opts.adaptedFrom, "adaptation"),
+        ...toLineage(opts.forkedFrom, "fork"),
+        ...toLineage(opts.absorbs, "absorption"),
+        ...toLineage(opts.remixes, "remix")
+      ];
       const res = await bundle.authedRequest(
         (api) => api.publish(
           {
@@ -3086,6 +3455,7 @@ function pushCommand() {
             target_full_slug: targetFullSlug,
             type: opts.type,
             changelog: opts.changelog,
+            lineage: lineage.length > 0 ? lineage : void 0,
             dry_run: !!opts.dryRun
           },
           {
@@ -3104,6 +3474,21 @@ function pushCommand() {
             printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
           }
           printHuman(`  ${c.cyan(res.url)}`);
+          if (res.lineage) {
+            printHuman(c.gray(`  lineage: ${res.lineage.recorded} edge(s) recorded`));
+            if (res.lineage.skipped.length > 0) {
+              printHuman(
+                c.yellow(
+                  `  ! lineage source(s) not found, skipped: ${res.lineage.skipped.join(", ")}`
+                )
+              );
+              printHuman(
+                c.gray(
+                  "    Publish the source first or fix the slug, then re-push to record it."
+                )
+              );
+            }
+          }
           if (res.status === "pending") {
             printHuman(
               c.yellow(
@@ -3174,9 +3559,7 @@ async function runDryRun(args) {
           );
         }
         if (assets.length > 0) printHuman(c.gray(`  + ${assets.length} bundled file(s)`));
-        printHuman(
-          c.gray("  (AI review only runs on the real push; not performed here)")
-        );
+        printHuman(c.gray("  (AI review only runs on the real push; not performed here)"));
         return;
       }
       printHuman(c.red(`\u2717 dry-run validation failed (${allFlags.length} flag(s))`));
@@ -3240,7 +3623,9 @@ async function bundleDirectory(dir2) {
   await walkDir(dir2, "", all);
   const skillEntry = all.find((f) => f.rel === "SKILL.md");
   if (!skillEntry) {
-    throw new Error(`No SKILL.md found in directory ${dir2}. Push a directory that has SKILL.md at its root.`);
+    throw new Error(
+      `No SKILL.md found in directory ${dir2}. Push a directory that has SKILL.md at its root.`
+    );
   }
   const content = await readFile6(skillEntry.abs, "utf8");
   const assets = [];
@@ -3255,7 +3640,11 @@ async function bundleSkillZip(zipPath) {
   const buf = await readFile6(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");
+  if (entries.length === 0) {
+    const e = new Error(".skill file is empty");
+    e.hint = "The .skill archive contains no files. Re-export the .skill from skill-creator, or push the unpacked skill directory instead (the dir containing SKILL.md).";
+    throw e;
+  }
   const firstParts = entries[0].split("/");
   const prefix = firstParts.length > 1 ? firstParts[0] + "/" : "";
   const stripped = entries.map((k) => ({
@@ -3264,7 +3653,9 @@ async function bundleSkillZip(zipPath) {
   })).filter((f) => f.rel.length > 0 && !shouldExclude(f.rel, false));
   const skillEntry = stripped.find((f) => f.rel === "SKILL.md");
   if (!skillEntry) {
-    throw new Error(`.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`);
+    const e = new Error(`.skill ZIP has no SKILL.md at its root (prefix="${prefix}")`);
+    e.hint = "SKILL.md must sit at <skill-name>/SKILL.md at the archive root. Re-package so the single top-level directory contains SKILL.md (skill-creator does this by default).";
+    throw e;
   }
   const content = await zip.files[skillEntry.zipKey].async("string");
   const assets = [];
@@ -3287,7 +3678,8 @@ async function bundleSkillZip(zipPath) {
 // src/commands/pull.ts
 import { Command as Command5 } from "commander";
 import { mkdir as mkdir6, writeFile as writeFile6 } from "fs/promises";
-import { dirname as dirname2, join as join9 } from "path";
+import { dirname as dirname2, join as join9, resolve as resolve2, sep as sep2 } from "path";
+init_src();
 
 // ../../packages/translators/src/skill/identity.ts
 function buildSkillFile(input, outputPath) {
@@ -3522,7 +3914,7 @@ var mcpToCodex = (input) => {
 var mcpToContinue = (input) => {
   const name = getName(input);
   const t = getTransport(input);
-  const lines = [`name: ${name}`];
+  const lines = [`name: ${JSON.stringify(name)}`];
   if (t.type === "stdio") {
     lines.push("type: stdio", `command: ${JSON.stringify(t.command)}`);
     if (t.args && t.args.length > 0) {
@@ -3531,13 +3923,13 @@ var mcpToContinue = (input) => {
     }
     if (t.env && Object.keys(t.env).length > 0) {
       lines.push("env:");
-      for (const [k, v] of Object.entries(t.env)) lines.push(`  ${k}: ${JSON.stringify(v)}`);
+      for (const [k, v] of Object.entries(t.env)) lines.push(`  ${JSON.stringify(k)}: ${JSON.stringify(v)}`);
     }
   } else {
     lines.push(`type: ${t.type}`, `url: ${JSON.stringify(t.url)}`);
     if (t.headers && Object.keys(t.headers).length > 0) {
       lines.push("headers:");
-      for (const [k, v] of Object.entries(t.headers)) lines.push(`  ${k}: ${JSON.stringify(v)}`);
+      for (const [k, v] of Object.entries(t.headers)) lines.push(`  ${JSON.stringify(k)}: ${JSON.stringify(v)}`);
     }
   }
   return {
@@ -3581,9 +3973,13 @@ var customAgentToClaude = (input) => {
   const context = typeof fm["context"] === "string" ? fm["context"] : null;
   const allowed = Array.isArray(fm["allowed_tools"]) ? fm["allowed_tools"] : [];
   const disallowed = Array.isArray(fm["disallowed_tools"]) ? fm["disallowed_tools"] : [];
-  const lines = ["---", `name: ${name}`, `description: ${JSON.stringify(description)}`];
+  const lines = [
+    "---",
+    `name: ${JSON.stringify(name)}`,
+    `description: ${JSON.stringify(description)}`
+  ];
   if (model) lines.push(`model: ${JSON.stringify(model)}`);
-  if (context) lines.push(`context: ${context}`);
+  if (context) lines.push(`context: ${JSON.stringify(context)}`);
   if (allowed.length > 0) {
     lines.push("allowed_tools:");
     for (const t of allowed) lines.push(`  - ${JSON.stringify(t)}`);
@@ -3666,6 +4062,70 @@ var hookCanonical = (input) => {
   return res;
 };
 
+// ../../packages/translators/src/judgment-pattern/identity.ts
+function yamlScalar(v) {
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return JSON.stringify(String(v));
+}
+function emitNode(key, value, indent) {
+  if (value === void 0 || value === null) return [];
+  const pad = "  ".repeat(indent);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [];
+    const lines = [`${pad}${key}:`];
+    for (const item of value) {
+      if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+        const entries = Object.entries(item).filter(
+          ([, v]) => v !== void 0 && v !== null
+        );
+        if (entries.length === 0) {
+          lines.push(`${pad}  - {}`);
+          continue;
+        }
+        entries.forEach(([k, v], i) => {
+          const prefix = i === 0 ? `${pad}  - ` : `${pad}    `;
+          lines.push(`${prefix}${k}: ${yamlScalar(v)}`);
+        });
+      } else {
+        lines.push(`${pad}  - ${yamlScalar(item)}`);
+      }
+    }
+    return lines;
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value).filter(
+      ([, v]) => v !== void 0 && v !== null
+    );
+    if (entries.length === 0) return [];
+    const lines = [`${pad}${key}:`];
+    for (const [k, v] of entries) lines.push(...emitNode(k, v, indent + 1));
+    return lines;
+  }
+  if (typeof value === "string" && value.includes("\n")) {
+    const lines = [`${pad}${key}: |`];
+    for (const ln of value.replace(/\n+$/, "").split("\n")) lines.push(`${pad}  ${ln}`);
+    return lines;
+  }
+  return [`${pad}${key}: ${yamlScalar(value)}`];
+}
+function buildJudgmentFile(input, outputPath) {
+  const fm = input.frontmatter["version"] === void 0 && input.version ? { ...input.frontmatter, version: input.version } : input.frontmatter;
+  const name = typeof fm["name"] === "string" ? fm["name"] : input.fullSlug.split("/")[1] ?? input.fullSlug;
+  const lines = ["---", "type: judgment-pattern"];
+  for (const [k, v] of Object.entries(fm)) lines.push(...emitNode(k, v, 0));
+  lines.push("---");
+  const body = input.body.trim();
+  const content = lines.join("\n") + (body.length > 0 ? "\n\n" + body + "\n" : "\n");
+  const resolvedPath = outputPath.replace("{name}", String(name));
+  return {
+    files: [{ path: resolvedPath, content, mergeable: false, format: "markdown" }],
+    notes: [],
+    format: "kordis-judgment-pattern"
+  };
+}
+var judgmentToClaude = (input) => buildJudgmentFile(input, ".claude/judgments/{name}.md");
+var judgmentCanonical = (input) => buildJudgmentFile(input, `kordis/judgment-patterns/${input.fullSlug.replace("/", "__")}.md`);
+
 // ../../packages/translators/src/registry.ts
 var REGISTRY = {
   skill: {
@@ -3707,6 +4167,13 @@ var REGISTRY = {
   hook: {
     canonical: hookCanonical,
     "claude-code": hookToClaude
+  },
+  // Judgment is canonical Markdown — no per-tool wiring, so both targets are
+  // identity. `read`/`adapt` (JIT) is the primary path; this is the local-copy
+  // fallback. `toolsForType` will report only 'claude-code' as compatible.
+  "judgment-pattern": {
+    canonical: judgmentCanonical,
+    "claude-code": judgmentToClaude
   }
 };
 REGISTRY["project-rules"]["gemini-cli"] = projectRulesToGemini;
@@ -3753,7 +4220,10 @@ async function readLockfile() {
 }
 async function writeLockfile(lf) {
   await mkdir5(kordisHome2(), { recursive: true });
-  await writeFile5(lockfilePath(), JSON.stringify(lf, null, 2) + "\n", "utf8");
+  await writeFile5(lockfilePath(), JSON.stringify(lf, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 384
+  });
 }
 async function recordInstalled(fullSlug, entry) {
   const lf = await readLockfile();
@@ -3761,85 +4231,14 @@ async function recordInstalled(fullSlug, entry) {
   await writeLockfile(lf);
 }
 
-// src/lib/parse-username.ts
-init_src();
-var SORT_KEYWORDS = ["latest", "popular", "recent", "updated", "stars", "downloads"];
-function parseUsername(raw) {
-  if (SORT_KEYWORDS.includes(raw.toLowerCase())) {
-    throw new Error(
-      `"${raw}" is a sort keyword \u2014 did you mean \`--sort ${raw}\`? Username arguments must follow the Kordis username shape (lowercase alphanumeric, hyphens allowed).`
-    );
-  }
-  const parsed = UsernameSchema.safeParse(raw);
-  if (!parsed.success) {
-    throw new Error(
-      `invalid username "${raw}" \u2014 must be 3-32 chars, lowercase alphanumeric with single hyphens (e.g. "alice", "my-team")`
-    );
-  }
-  return parsed.data;
-}
-
-// src/lib/parse-slug-version.ts
-var SUFFIX_CHARS = /[\^~*]/;
-function slugError(message, hint) {
-  const e = new Error(message);
-  e.hint = hint;
-  return e;
-}
-function parseSlugAtVersion(raw) {
-  if (!raw.includes("/")) {
-    let username2;
-    try {
-      username2 = parseUsername(raw);
-    } catch {
-      username2 = void 0;
-    }
-    if (username2) {
-      throw slugError(
-        `"${raw}" looks like a username, not a package`,
-        `Try \`kordis profile ${username2}\` for user details, or pass a full slug like "{username}/{slug}".`
-      );
-    }
-    throw slugError(
-      `"${raw}" is missing the "{username}/{slug}" form`,
-      'Use the form "{username}/{slug}", e.g. "alice/json-pretty".'
-    );
-  }
-  const atIdx = raw.indexOf("@");
-  const slugPart = atIdx === -1 ? raw : raw.slice(0, atIdx);
-  const versionPart = atIdx === -1 ? "" : raw.slice(atIdx + 1);
-  const [username, slug] = slugPart.split("/");
-  if (!username || !slug) {
-    throw slugError(
-      'full_slug must be "{username}/{slug}"',
-      'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.'
-    );
-  }
-  if (atIdx !== -1 && versionPart.length === 0) {
-    throw slugError(
-      `"${raw}" has a trailing "@" with no version`,
-      `Drop the "@" or append a version/range, e.g. "${slugPart}@1.0.0" or "${slugPart}@^1".`
-    );
-  }
-  const out = {
-    fullSlug: slugPart,
-    username,
-    slug
-  };
-  if (versionPart.length > 0) {
-    if (SUFFIX_CHARS.test(versionPart)) {
-      out.range = versionPart;
-    } else {
-      out.version = versionPart;
-    }
-  }
-  return out;
-}
-
 // src/commands/pull.ts
 async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
   const [username, slug] = fullSlug.split("/");
-  if (!username || !slug) throw new Error('full_slug must be "{username}/{slug}"');
+  if (!username || !slug) {
+    const e = new Error('full_slug must be "{username}/{slug}"');
+    e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+    throw e;
+  }
   const bundle = await useClient();
   const pullRes = await bundle.api.pull(username, slug, {
     ...opts.version ? { version: opts.version } : {},
@@ -3854,7 +4253,9 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
   });
   const parsed = validatePackageSource(contentRes.content);
   if (!parsed.ok || !parsed.type || !parsed.frontmatter) {
-    throw new Error("package stored content is not currently valid");
+    const e = new Error("package stored content is not currently valid");
+    e.hint = `This version's stored bytes no longer pass validation. Try another version via \`kordis versions ${fullSlug}\` (then pull a specific \`@<version>\`), or re-push a corrected version if you authored it.`;
+    throw e;
   }
   const written = [];
   const notes = [];
@@ -3869,7 +4270,7 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
       assets: contentRes.assets
     });
     for (const f of result.files) {
-      const abs = join9(installRoot, f.path);
+      const abs = safeInstallPath(installRoot, f.path);
       await mkdir6(dirname2(abs), { recursive: true });
       await writeEmittedFile(abs, f.content, f.encoding);
       written.push(abs);
@@ -3889,7 +4290,7 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
         `Tool "${format}" is not supported for type "${parsed.type}"; installed canonical form instead.`
       );
       for (const f of result.files) {
-        const abs = join9(installRoot, f.path);
+        const abs = safeInstallPath(installRoot, f.path);
         await mkdir6(dirname2(abs), { recursive: true });
         await writeEmittedFile(abs, f.content, f.encoding);
         written.push(abs);
@@ -3960,6 +4361,13 @@ function pullCommand() {
         ...opts.withRecommends ? result.plan?.recommended.map((n) => ({ ...n, kind: "recommended" })) ?? [] : []
       ];
       for (const node of installPlan) {
+        if (!FullSlugSchema.safeParse(node.full_slug).success) {
+          const e = new Error(
+            `registry returned a malformed dependency slug: ${JSON.stringify(node.full_slug)}`
+          );
+          e.hint = "Refusing to install it. Report this package to the registry operator.";
+          throw e;
+        }
         const subSpin = spinner(
           `  \u21B3 ${node.kind === "required" ? "dep" : "rec"} ${node.full_slug}@${node.version}`
         );
@@ -4052,6 +4460,27 @@ async function detectTool(root) {
   }
   return null;
 }
+function safeInstallPath(installRoot, relPath) {
+  const windowsAbsolute = /^[A-Za-z]:/.test(relPath) || relPath.startsWith("\\\\");
+  if (relPath.startsWith("/") || windowsAbsolute || resolve2(relPath) === relPath) {
+    const e = new Error(
+      `refusing to write absolute path "${relPath}" outside the install root`
+    );
+    e.hint = "Package emitted an absolute file path. Re-push the package with relative paths only; report it to the author if you did not publish it.";
+    throw e;
+  }
+  const abs = join9(installRoot, relPath);
+  const resolvedRoot = resolve2(installRoot);
+  const resolvedAbs = resolve2(abs);
+  if (resolvedAbs !== resolvedRoot && !resolvedAbs.startsWith(resolvedRoot + sep2)) {
+    const e = new Error(
+      `refusing to write "${relPath}" \u2014 resolves outside the install root`
+    );
+    e.hint = "Package tried to write outside the install directory (path traversal). Re-push the package with relative in-tree paths only; report it to the author if you did not publish it.";
+    throw e;
+  }
+  return abs;
+}
 async function writeEmittedFile(abs, content, encoding) {
   if (encoding === "base64") {
     await writeFile6(abs, Buffer.from(content, "base64"));
@@ -4063,7 +4492,7 @@ async function writeEmittedFile(abs, content, encoding) {
 // src/commands/read.ts
 import { Command as Command6 } from "commander";
 function readCommand() {
-  return new Command6("read").description("fetch a package body into the agent context (no install)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--pin <semver>", "pin to an exact version (overrides @suffix)").action(
+  return new Command6("read").description("fetch a package body into the agent context (no install)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--pin <semver>", "pin to an exact version (overrides @suffix)").option("--outline", "print only the section map (skeleton) \u2014 cheap on context", false).option("--section <name>", "print only one section (see names with --outline)").action(
     async (rawSlug, opts) => {
       const parsed = parseSlugAtVersion(rawSlug);
       const pin = opts.pin ?? parsed.version ?? parsed.range;
@@ -4071,11 +4500,7 @@ function readCommand() {
       const bundle = await useClient();
       let resolvedVersion;
       if (pin && pinIsRange) {
-        const resolved = await bundle.api.resolveVersion(
-          parsed.username,
-          parsed.slug,
-          pin
-        );
+        const resolved = await bundle.api.resolveVersion(parsed.username, parsed.slug, pin);
         resolvedVersion = resolved.resolved_version;
       }
       const versionForRead = resolvedVersion ?? pin;
@@ -4083,6 +4508,79 @@ function readCommand() {
         allow_pending: opts.allowPending,
         ...versionForRead ? { version: versionForRead } : {}
       });
+      if (opts.outline) {
+        const o = outlineOf(res.body);
+        if (isJsonMode()) {
+          printJson({
+            full_slug: res.full_slug,
+            version: res.version,
+            type: res.type,
+            tier: res.tier,
+            trust_tier: res.trust_tier ?? null,
+            description: o.description,
+            sections: o.sections.map((s) => ({ name: s.name, label: s.label })),
+            bundled_assets: res.bundled_assets ?? []
+          });
+          return;
+        }
+        process.stdout.write(
+          `${c.bold(res.full_slug)}${c.gray("@")}${res.version} ${c.gray("\xB7")} ${res.type} (tier ${res.tier})
+`
+        );
+        if (o.description) process.stdout.write(`${o.description}
+`);
+        process.stdout.write("\n");
+        if (o.sections.length > 0) {
+          process.stdout.write(
+            `Sections \u2014 read one with ${c.cyan(`kordis read ${res.full_slug} --section <name>`)}:
+`
+          );
+          for (const s of o.sections) {
+            process.stdout.write(`  ${c.gray("-")} ${s.name}
+`);
+          }
+        } else {
+          process.stdout.write(
+            `No sub-sections \u2014 read the whole body with ${c.cyan(`kordis read ${res.full_slug}`)}.
+`
+          );
+        }
+        const assets = res.bundled_assets ?? [];
+        if (assets.length > 0) {
+          process.stdout.write(
+            `
+Bundled files \u2014 fetch with ${c.cyan(`kordis pull ${res.full_slug}`)}:
+`
+          );
+          for (const p of assets) process.stdout.write(`  ${c.gray("-")} ${p}
+`);
+        }
+        return;
+      }
+      if (opts.section) {
+        const sec = sectionOf(res.body, opts.section);
+        if (!sec) {
+          const names = outlineOf(res.body).sections.map((s) => s.name).join(", ");
+          process.stderr.write(
+            `${c.red("\u2717")} section "${opts.section}" not found. Available: ${names || "(none \u2014 this package has no sub-sections)"}
+  See the map with ${c.cyan(`kordis read ${res.full_slug} --outline`)}.
+`
+          );
+          process.exitCode = 2;
+          return;
+        }
+        if (isJsonMode()) {
+          printJson({ full_slug: res.full_slug, version: res.version, section: sec });
+          return;
+        }
+        process.stdout.write(sec.body);
+        if (!sec.body.endsWith("\n")) process.stdout.write("\n");
+        process.stderr.write(
+          `${c.gray("\u2014")} ${c.bold(res.full_slug)}${c.gray("@")}${res.version} ${c.gray("\xA7")} ${sec.label} ${c.gray("\xB7")} ${c.cyan(res.attribution)}
+`
+        );
+        return;
+      }
       if (isJsonMode()) {
         printJson(res);
         return;
@@ -4101,8 +4599,9 @@ function readCommand() {
         }
       }
       const resolvedNote = pinIsRange && resolvedVersion ? ` ${c.gray("(resolved")} ${c.gray("@" + pin)} ${c.gray("\u2192")} ${resolvedVersion}${c.gray(")")}` : "";
+      const trustNote = res.trust_tier ? ` ${c.gray("\xB7")} trust: ${res.trust_tier}` : "";
       process.stderr.write(
-        `${c.gray("\u2014")} ${c.bold(res.full_slug)}${c.gray("@")}${res.version}${resolvedNote} ${c.gray("\xB7")} ${res.type} (tier ${res.tier}) ${c.gray("\xB7")} ${c.cyan(res.attribution)}
+        `${c.gray("\u2014")} ${c.bold(res.full_slug)}${c.gray("@")}${res.version}${resolvedNote} ${c.gray("\xB7")} ${res.type} (tier ${res.tier})${trustNote} ${c.gray("\xB7")} ${c.cyan(res.attribution)}
 `
       );
       printHuman("");
@@ -4110,11 +4609,175 @@ function readCommand() {
   );
 }
 
+// src/commands/adapt.ts
+import { Command as Command7 } from "commander";
+
+// src/context/harness-reader.ts
+import { access as access3, readFile as readFile8 } from "fs/promises";
+import { homedir as homedir8 } from "os";
+import { join as join10 } from "path";
+var PER_FILE_CAP = 16 * 1024;
+var TOTAL_CAP = 48 * 1024;
+async function pathExists3(p) {
+  try {
+    await access3(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function capContent(raw, cap) {
+  if (Buffer.byteLength(raw, "utf8") <= cap) return { content: raw, truncated: false };
+  const lines = raw.split("\n");
+  let acc = 0;
+  let lastHeadingIdx = -1;
+  let cutIdx = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const lineBytes = Buffer.byteLength(`${line}
+`, "utf8");
+    if (acc + lineBytes > cap) {
+      cutIdx = i;
+      break;
+    }
+    acc += lineBytes;
+    if (/^#{1,6}\s/.test(line)) lastHeadingIdx = i;
+  }
+  const cut = lastHeadingIdx > cutIdx / 2 ? lastHeadingIdx : cutIdx;
+  const kept = lines.slice(0, cut).join("\n");
+  return {
+    content: `${kept}
+
+[truncated \u2014 ${cut}/${lines.length} lines shown]`,
+    truncated: true
+  };
+}
+function extractHeadings(content) {
+  return content.split("\n").filter((l) => /^#{2,3}\s/.test(l)).map((l) => l.replace(/^#{2,3}\s+/, "").trim()).slice(0, 40);
+}
+async function readHarnessContext(cwd = process.cwd(), home = homedir8()) {
+  const candidates = [
+    { path: join10(cwd, "CLAUDE.md"), display: "CLAUDE.md", scope: "project" },
+    { path: join10(cwd, "AGENTS.md"), display: "AGENTS.md", scope: "project" },
+    { path: join10(cwd, "GEMINI.md"), display: "GEMINI.md", scope: "project" },
+    { path: join10(cwd, ".cursorrules"), display: ".cursorrules", scope: "project" },
+    {
+      path: join10(cwd, ".github", "copilot-instructions.md"),
+      display: ".github/copilot-instructions.md",
+      scope: "project"
+    },
+    { path: join10(cwd, ".claude", "CLAUDE.md"), display: ".claude/CLAUDE.md", scope: "project" },
+    { path: join10(home, ".claude", "CLAUDE.md"), display: "~/.claude/CLAUDE.md", scope: "global" }
+  ];
+  const files = [];
+  let totalBytes = 0;
+  for (const cand of candidates) {
+    if (totalBytes >= TOTAL_CAP) break;
+    if (!await pathExists3(cand.path)) continue;
+    let raw;
+    try {
+      raw = await readFile8(cand.path, "utf8");
+    } catch {
+      continue;
+    }
+    const cap = Math.min(PER_FILE_CAP, TOTAL_CAP - totalBytes);
+    const { content, truncated } = capContent(raw, cap);
+    totalBytes += Buffer.byteLength(content, "utf8");
+    files.push({
+      path: cand.display,
+      scope: cand.scope,
+      content,
+      truncated,
+      headings: extractHeadings(content)
+    });
+  }
+  return { files, found: files.length > 0 };
+}
+
+// src/commands/adapt.ts
+var TRANSPLANT_INSTRUCTIONS = `1. Extract the *judgment* from \xA71 \u2014 the decision logic / discipline it encodes, not its surface wording.
+2. Fit it to the harness in \xA72: keep universal parts verbatim; re-express context-specific parts in THIS harness's own conventions, stack, and section structure. Never duplicate a rule the harness already has \u2014 reconcile instead.
+3. For EVERY proposed change, write a plain-language explanation of what changes and WHY. The deliverable is understanding transfer, not a paste.
+4. PROPOSE, do not apply. Present a reviewable diff/edit for the user to approve. Kordis wrote nothing to disk and neither should you without approval.
+5. Cite attribution (the "following \u2026" line below) in whatever you add.
+6. If the user approves and wants to share their variation back, offer to run \`kordis push --adapted-from <slug@version>\` so the lineage is recorded \u2014 do not do this silently.`;
+function renderBrief(res, harness) {
+  const out = [];
+  out.push("# TRANSPLANT BRIEF");
+  out.push(
+    "> You (the agent) fit the judgment below into the user's existing harness. Propose changes WITH explanations; do not apply them automatically."
+  );
+  out.push("");
+  out.push(`## 1. THE JUDGMENT \u2014 ${res.full_slug}@${res.version}  (${res.type}, tier ${res.tier})`);
+  out.push("");
+  out.push(res.body.trimEnd());
+  out.push("");
+  out.push("## 2. THE USER'S EXISTING HARNESS");
+  if (!harness.found) {
+    out.push("");
+    out.push(
+      "_No harness file found in this project or globally._ Propose a NEW minimal placement (e.g. create or extend `CLAUDE.md`) \u2014 do not invent structure that is not there."
+    );
+  } else {
+    for (const f of harness.files) {
+      out.push("");
+      out.push(`### ${f.path}  (${f.scope}${f.truncated ? ", truncated" : ""})`);
+      if (f.headings.length > 0) out.push(`Sections: ${f.headings.join(" \xB7 ")}`);
+      out.push("");
+      out.push("```md");
+      out.push(f.content.trimEnd());
+      out.push("```");
+    }
+  }
+  out.push("");
+  out.push("## 3. TRANSPLANT INSTRUCTIONS");
+  out.push(TRANSPLANT_INSTRUCTIONS);
+  out.push("");
+  out.push(`\u2014 ${res.attribution}`);
+  out.push("");
+  return out.join("\n");
+}
+function adaptCommand() {
+  return new Command7("adapt").description(
+    "fit a judgment pattern to your existing harness (prints a transplant brief; writes nothing)"
+  ).argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--pin <semver>", "pin to an exact version (overrides @suffix)").action(async (rawSlug, opts) => {
+    const parsed = parseSlugAtVersion(rawSlug);
+    const pin = opts.pin ?? parsed.version ?? parsed.range;
+    const pinIsRange = pin ? /[\^~*]/.test(pin) : false;
+    const bundle = await useClient();
+    let resolvedVersion;
+    if (pin && pinIsRange) {
+      const resolved = await bundle.api.resolveVersion(parsed.username, parsed.slug, pin);
+      resolvedVersion = resolved.resolved_version;
+    }
+    const versionForRead = resolvedVersion ?? pin;
+    const res = await bundle.api.jitRead(parsed.username, parsed.slug, {
+      allow_pending: opts.allowPending,
+      ...versionForRead ? { version: versionForRead } : {}
+    });
+    const harness = await readHarnessContext();
+    if (isJsonMode()) {
+      printJson({
+        full_slug: res.full_slug,
+        version: res.version,
+        type: res.type,
+        tier: res.tier,
+        attribution: res.attribution,
+        judgment_body: res.body,
+        host_harness: harness,
+        transplant_instructions: TRANSPLANT_INSTRUCTIONS
+      });
+      return;
+    }
+    process.stdout.write(renderBrief(res, harness));
+  });
+}
+
 // src/commands/info.ts
 init_src();
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 function infoCommand() {
-  return new Command7("info").description("show details about a package").argument(
+  return new Command8("info").description("show details about a package").argument(
     "<full_slug>",
     "package identifier {username}/{slug} or {username}/{slug}@{version|range}"
   ).option("--pin <semver>", "pin to an exact version or range (overrides @suffix)").action(async (fullSlug, opts) => {
@@ -4178,9 +4841,9 @@ function infoCommand() {
 }
 
 // src/commands/logout.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 function logoutCommand() {
-  return new Command8("logout").description("revoke the current session and clear local credentials").action(async () => {
+  return new Command9("logout").description("revoke the current session and clear local credentials").action(async () => {
     const bundle = await useClient();
     if (!bundle.username) {
       printHuman(c.yellow("Not logged in; nothing to do."));
@@ -4203,11 +4866,11 @@ 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 homedir8 } from "os";
-import { join as join10, dirname as dirname3 } from "path";
+import { readFile as readFile9, writeFile as writeFile7, mkdir as mkdir7, access as access4 } from "fs/promises";
+import { homedir as homedir9 } from "os";
+import { join as join11, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 import prompts from "prompts";
 var MARKER_START = "<!-- kordis-start -->";
 var MARKER_END = "<!-- kordis-end -->";
@@ -4230,7 +4893,7 @@ var SKILL_TARGETS = [
 ];
 async function exists(path2) {
   try {
-    await access3(path2);
+    await access4(path2);
     return true;
   } catch {
     return false;
@@ -4240,18 +4903,18 @@ function assetRoots() {
   const __dir2 = dirname3(fileURLToPath2(import.meta.url));
   return {
     // Built binary: bin/kordis.js → assets/ is one level up
-    bundled: join10(__dir2, "..", "assets"),
+    bundled: join11(__dir2, "..", "assets"),
     // Dev mode: src/commands/setup.ts → 4 levels up to repo root, then packages/skills/
-    source: join10(__dir2, "..", "..", "..", "..", "packages", "skills")
+    source: join11(__dir2, "..", "..", "..", "..", "packages", "skills")
   };
 }
 async function pickAssetRoot() {
   const { bundled, source } = assetRoots();
-  return await exists(join10(bundled, "KORDIS.md")) ? bundled : source;
+  return await exists(join11(bundled, "KORDIS.md")) ? bundled : source;
 }
 async function loadHubContent() {
   const root = await pickAssetRoot();
-  const raw = await readFile8(join10(root, "KORDIS.md"), "utf-8");
+  const raw = await readFile9(join11(root, "KORDIS.md"), "utf-8");
   if (raw.startsWith("---")) {
     const end = raw.indexOf("\n---", 4);
     if (end !== -1) return raw.slice(end + 4).trimStart();
@@ -4260,7 +4923,7 @@ async function loadHubContent() {
 }
 async function loadSubSkillContent(name) {
   const root = await pickAssetRoot();
-  return readFile8(join10(root, name, "SKILL.md"), "utf-8");
+  return readFile9(join11(root, name, "SKILL.md"), "utf-8");
 }
 async function injectBlock(filePath, content, dryRun) {
   const block = `${MARKER_START}
@@ -4269,7 +4932,7 @@ ${MARKER_END}`;
   let existing = "";
   let fileExists = true;
   try {
-    existing = await readFile8(filePath, "utf-8");
+    existing = await readFile9(filePath, "utf-8");
   } catch {
     fileExists = false;
   }
@@ -4299,7 +4962,7 @@ ${MARKER_END}`;
 async function copyBundledSkill(filePath, content, dryRun) {
   let existing = null;
   try {
-    existing = await readFile8(filePath, "utf-8");
+    existing = await readFile9(filePath, "utf-8");
   } catch {
   }
   if (existing === content) return "unchanged";
@@ -4310,14 +4973,14 @@ async function copyBundledSkill(filePath, content, dryRun) {
   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").option(
+  return new Command10("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 = homedir8();
+    const home = homedir9();
     const dryRun = opts.dryRun ?? false;
     if (opts.personalization !== void 0) {
       const v = opts.personalization.toLowerCase();
@@ -4376,8 +5039,8 @@ function setupCommand() {
     let anyFound = false;
     const changedTools = /* @__PURE__ */ new Set();
     for (const target of HUB_TARGETS) {
-      const dirPath = join10(home, target.dir);
-      const filePath = join10(home, target.file);
+      const dirPath = join11(home, target.dir);
+      const filePath = join11(home, target.file);
       if (!await exists(dirPath)) {
         if (!opts.silent) {
           printHuman(c.gray(`  - ${target.tool.padEnd(12)} not installed, skipped`));
@@ -4404,10 +5067,10 @@ function setupCommand() {
       }
     }
     for (const target of SKILL_TARGETS) {
-      const dirPath = join10(home, target.dir);
+      const dirPath = join11(home, target.dir);
       if (!await exists(dirPath)) continue;
       for (const subName of SUB_SKILLS) {
-        const filePath = join10(home, target.skillsDir, subName, "SKILL.md");
+        const filePath = join11(home, target.skillsDir, subName, "SKILL.md");
         const dest = `~/${target.skillsDir}/${subName}/SKILL.md`;
         try {
           const result = await copyBundledSkill(filePath, subSkillContents[subName], dryRun);
@@ -4495,7 +5158,7 @@ function setupCommand() {
 }
 
 // src/commands/comment.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 var KINDS = [
   "comment",
   "tip",
@@ -4506,7 +5169,7 @@ var KINDS = [
 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(
+  return new Command11("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) => {
       if (!KINDS.includes(opts.kind)) {
         throw new Error(`--kind must be one of ${KINDS.join(", ")}`);
@@ -4542,14 +5205,16 @@ function commentCommand() {
   );
 }
 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(
+  return new Command11("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}"');
+        const e = new Error('full_slug must be "{username}/{slug}"');
+        e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+        throw e;
       }
       if (opts.kind && !KINDS.includes(opts.kind)) {
         throw new Error(`--kind must be one of ${KINDS.join(", ")}`);
@@ -4564,14 +5229,13 @@ function commentsCommand() {
         ...opts.kind ? { kind: opts.kind } : {},
         ...opts.sort ? { sort: opts.sort } : {}
       });
+      const emptyHint = "no comments yet \u2014 be the first: kordis comment " + rawSlug + ' --body "..."';
       printDual({
-        json: res,
+        json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
         human: () => {
           if (res.results.length === 0) {
             printHuman(c.yellow("(no comments)"));
-            printHuman(
-              c.gray("  \u2192 be the first: kordis comment " + rawSlug + ' --body "..."')
-            );
+            printHuman(c.gray("  \u2192 " + emptyHint));
             return;
           }
           printHuman(
@@ -4615,7 +5279,7 @@ function renderCommentNode(node, depth) {
   }
 }
 function uncommentCommand() {
-  return new Command10("uncomment").description("delete one of your comments by id").argument("<id>", "comment id (uuid v4)").action(async (id) => {
+  return new Command11("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"
@@ -4634,12 +5298,14 @@ function uncommentCommand() {
 }
 
 // src/commands/star.ts
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 function starCommand() {
-  return new Command11("star").description("star a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (rawSlug) => {
+  return new Command12("star").description("star a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (rawSlug) => {
     const [username, slug] = rawSlug.split("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     requireAuth(bundle);
@@ -4654,10 +5320,12 @@ function starCommand() {
   });
 }
 function unstarCommand() {
-  return new Command11("unstar").description("remove your star from a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (rawSlug) => {
+  return new Command12("unstar").description("remove your star from a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (rawSlug) => {
     const [username, slug] = rawSlug.split("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     requireAuth(bundle);
@@ -4675,13 +5343,15 @@ function unstarCommand() {
 }
 
 // src/commands/delete.ts
-import { Command as Command12 } from "commander";
+import { Command as Command13 } from "commander";
 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) => {
+  return new Command13("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("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     const detail = await bundle.api.getPackage(username, slug);
@@ -4714,10 +5384,10 @@ function deleteCommand() {
 }
 
 // src/commands/yank.ts
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 import prompts3 from "prompts";
 function yankCommand() {
-  return new Command13("yank").description("soft-mark a specific version of your package as yanked").argument(
+  return new Command14("yank").description("soft-mark a specific version of your package as yanked").argument(
     "<full_slug>",
     'package identifier \u2014 bare slug yanks current version (e.g. "user/slug"), or pin: "user/slug@1.2.3"'
   ).option("--reason <text>", "optional reason shown to consumers (\u2264280 chars)").option("--force", "skip the confirmation prompt").action(
@@ -4798,9 +5468,9 @@ function yankCommand() {
 }
 
 // src/commands/unyank.ts
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 function unyankCommand() {
-  return new Command14("unyank").description("reverse a yank on a specific version").argument(
+  return new Command15("unyank").description("reverse a yank on a specific version").argument(
     "<full_slug>",
     'package identifier with explicit version, e.g. "user/slug@1.2.3"'
   ).action(async (fullSlugArg) => {
@@ -4841,9 +5511,9 @@ function unyankCommand() {
 }
 
 // src/commands/list.ts
-import { Command as Command15 } from "commander";
+import { Command as Command16 } from "commander";
 function listCommand() {
-  return new Command15("list").description("list packages \u2014 your own (no arg) or a public user\u2019s (with <username>)").argument("[username]", "kordis username to list (omit for self)").option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "self-mode page number (1-based)", (v) => parseInt(v, 10), 1).option("--cursor <token>", "public-mode pagination cursor").option("--sort <mode>", "sort: latest|popular (self) or stars|downloads|recent|updated (public)", "latest").action(async (rawUsername, opts) => {
+  return new Command16("list").description("list packages \u2014 your own (no arg) or a public user\u2019s (with <username>)").argument("[username]", "kordis username to list (omit for self)").option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "self-mode page number (1-based)", (v) => parseInt(v, 10), 1).option("--cursor <token>", "public-mode pagination cursor").option("--sort <mode>", "sort: latest|popular (self) or stars|downloads|recent|updated (public)", "latest").action(async (rawUsername, opts) => {
     const bundle = await useClient();
     if (rawUsername === void 0) {
       requireAuth(bundle);
@@ -4889,11 +5559,13 @@ function listCommand() {
       sort: publicSort,
       ...opts.cursor ? { cursor: opts.cursor } : {}
     });
+    const emptyHint = `no public packages for ${username} \u2014 verify the username via \`kordis profile ${username}\`, or browse the registry via \`kordis search\``;
     printDual({
-      json: res,
+      json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.results.length === 0) {
           printHuman(c.yellow(`(no public packages for ${username})`));
+          printHuman(c.gray(`  \u2192 ${emptyHint}`));
           return;
         }
         for (const p of res.results) {
@@ -4914,12 +5586,14 @@ function listCommand() {
 }
 
 // src/commands/versions.ts
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 function versionsCommand() {
-  return new Command16("versions").description("list all versions of a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (fullSlug) => {
+  return new Command17("versions").description("list all versions of a package").argument("<full_slug>", "package identifier {username}/{slug}").action(async (fullSlug) => {
     const [username, slug] = fullSlug.split("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     const spin = spinner(`Fetching versions for ${fullSlug}`);
@@ -4975,13 +5649,13 @@ function relativeTime(isoString) {
 }
 
 // src/commands/outdated.ts
-import { Command as Command17 } from "commander";
+import { Command as Command18 } from "commander";
 import semver from "semver";
 function effectiveRange(entry) {
   return entry.requestedRange ?? `^${entry.version}`;
 }
 function outdatedCommand() {
-  return new Command17("outdated").description("check installed packages for available updates").action(async () => {
+  return new Command18("outdated").description("check installed packages for available updates").action(async () => {
     const lf = await readLockfile();
     const slugs = Object.keys(lf.packages);
     if (slugs.length === 0) {
@@ -5079,13 +5753,13 @@ function outdatedCommand() {
 }
 
 // src/commands/update.ts
-import { Command as Command18 } from "commander";
+import { Command as Command19 } from "commander";
 import semver2 from "semver";
 function effectiveRange2(entry) {
   return entry.requestedRange ?? `^${entry.version}`;
 }
 function updateCommand() {
-  return new Command18("update").description("update installed packages to their latest versions").argument("[full_slug]", "package identifier {username}/{slug} (omit to update all)").option("--dry-run", "show what would be updated without doing it", false).action(async (fullSlugArg, opts) => {
+  return new Command19("update").description("update installed packages to their latest versions").argument("[full_slug]", "package identifier {username}/{slug} (omit to update all)").option("--dry-run", "show what would be updated without doing it", false).action(async (fullSlugArg, opts) => {
     const lf = await readLockfile();
     let slugs = Object.keys(lf.packages);
     if (slugs.length === 0) {
@@ -5219,9 +5893,9 @@ function updateCommand() {
 }
 
 // src/commands/diff.ts
-import { Command as Command19 } from "commander";
+import { Command as Command20 } from "commander";
 function diffCommand() {
-  return new Command19("diff").description("show changes between two versions of a package").argument("<full_slug>", "package identifier: {username}/{slug}, or {username}/{slug}@{from}..{to}").argument("[from]", "older version (omit to use second-latest)").argument("[to]", "newer version (omit to use latest)").action(async (fullSlugArg, fromArg, toArg) => {
+  return new Command20("diff").description("show changes between two versions of a package").argument("<full_slug>", "package identifier: {username}/{slug}, or {username}/{slug}@{from}..{to}").argument("[from]", "older version (omit to use second-latest)").argument("[to]", "newer version (omit to use latest)").action(async (fullSlugArg, fromArg, toArg) => {
     let fullSlug = fullSlugArg;
     let from = fromArg;
     let to = toArg;
@@ -5233,7 +5907,9 @@ function diffCommand() {
     }
     const [username, slug] = fullSlug.split("/");
     if (!username || !slug) {
-      throw new Error('full_slug must be "{username}/{slug}"');
+      const e = new Error('full_slug must be "{username}/{slug}"');
+      e.hint = 'Pass both parts, e.g. "alice/json-pretty". Browse with `kordis search` if unsure.';
+      throw e;
     }
     const bundle = await useClient();
     if (!from || !to) {
@@ -5292,10 +5968,10 @@ function diffCommand() {
 }
 
 // src/commands/recommend.ts
-import { Command as Command20 } from "commander";
+import { Command as Command21 } from "commander";
 import prompts4 from "prompts";
 function recommendCommand() {
-  return new Command20("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) => {
+  return new Command21("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 prompts4({
@@ -5326,8 +6002,9 @@ function recommendCommand() {
     spin.succeed();
     await writeCache(res.items, res.generated_at);
     await markSeen();
+    const emptyHint = !res.personalized ? "personalization is OFF, so the server ranks on popularity alone \u2014 likely empty pool. Enable for stack-aware matches: `kordis setup --personalization on`, or broaden via `kordis search <topic>` / `kordis search --trending`." : "personalization is ON but no matches for your stack \u2014 registry may be sparse for this profile. Try `kordis search <topic>` or `kordis search --trending`.";
     printDual({
-      json: res,
+      json: res.items.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.items.length === 0) {
           printHuman(c.yellow("(no recommendations available right now)"));
@@ -5403,9 +6080,9 @@ function renderItem(idx, it, verbose) {
 }
 
 // src/commands/profile.ts
-import { Command as Command21 } from "commander";
+import { Command as Command22 } from "commander";
 function profileCommand() {
-  return new Command21("profile").description("inspect a user\u2019s public profile").argument("<username>", "kordis username").action(async (raw) => {
+  return new Command22("profile").description("inspect a user\u2019s public profile").argument("<username>", "kordis username").action(async (raw) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     const profile = await bundle.api.getUserProfile(username);
@@ -5440,21 +6117,22 @@ function profileCommand() {
 }
 
 // src/commands/stars.ts
-import { Command as Command22 } from "commander";
+import { Command as Command23 } from "commander";
 function starsCommand() {
-  return new Command22("stars").description("list packages a user has starred").argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
+  return new Command23("stars").description("list packages a user has starred").argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     const res = await bundle.api.listUserStars(username, {
       limit: opts.limit,
       ...opts.cursor ? { cursor: opts.cursor } : {}
     });
+    const emptyHint = `no public stars for ${username} \u2014 they may have none, or keep them private`;
     printDual({
-      json: res,
+      json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.results.length === 0) {
           printHuman(c.yellow(`(no stars yet for ${username})`));
-          printHuman(c.gray(`  \u2192 they may not have starred any public packages, or have set stars to private`));
+          printHuman(c.gray(`  \u2192 ${emptyHint}`));
           return;
         }
         for (const p of res.results) {
@@ -5474,9 +6152,9 @@ function starsCommand() {
 }
 
 // src/commands/follow.ts
-import { Command as Command23 } from "commander";
+import { Command as Command24 } from "commander";
 function followCommand() {
-  return new Command23("follow").description("follow a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+  return new Command24("follow").description("follow a kordis user").argument("<username>", "kordis username").action(async (raw) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     requireAuth(bundle);
@@ -5491,7 +6169,7 @@ function followCommand() {
   });
 }
 function unfollowCommand() {
-  return new Command23("unfollow").description("stop following a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+  return new Command24("unfollow").description("stop following a kordis user").argument("<username>", "kordis username").action(async (raw) => {
     const username = parseUsername(raw);
     const bundle = await useClient();
     requireAuth(bundle);
@@ -5507,9 +6185,9 @@ function unfollowCommand() {
 }
 
 // src/commands/followers.ts
-import { Command as Command24 } from "commander";
+import { Command as Command25 } from "commander";
 function makeListing(name) {
-  return new Command24(name).description(
+  return new Command25(name).description(
     name === "followers" ? "list users following <username>" : "list users that <username> follows"
   ).argument("<username>", "kordis username").option("--limit <n>", "max results per page (1-100, default 50)", (v) => parseInt(v, 10), 50).option("--cursor <token>", "pagination cursor returned by a prior response").action(async (raw, opts) => {
     const username = parseUsername(raw);
@@ -5519,12 +6197,14 @@ function makeListing(name) {
       limit: opts.limit,
       ...opts.cursor ? { cursor: opts.cursor } : {}
     });
+    const emptyHint = name === "followers" ? `no followers yet for ${username} \u2014 verify the username via \`kordis profile ${username}\`, or this account simply has no followers` : `${username} isn't following anyone yet \u2014 verify the username via \`kordis profile ${username}\``;
     printDual({
-      json: res,
+      json: res.results.length === 0 ? { ...res, hint: emptyHint } : res,
       human: () => {
         if (res.results.length === 0) {
           const noun = name === "followers" ? "followers yet" : "one yet";
           printHuman(c.yellow(`(no ${noun} for ${username})`));
+          printHuman(c.gray(`  \u2192 ${emptyHint}`));
           return;
         }
         for (const u of res.results) {
@@ -5554,10 +6234,12 @@ function followingCommand() {
 
 // src/index.ts
 function buildProgram() {
-  const program = new Command25("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 Command26("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", `
+  }).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)
@@ -5566,7 +6248,8 @@ Environment variables (see README.md "Privacy & environment variables"):
   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());
@@ -5574,6 +6257,7 @@ Environment variables (see README.md "Privacy & environment variables"):
   program.addCommand(pushCommand());
   program.addCommand(pullCommand());
   program.addCommand(readCommand());
+  program.addCommand(adaptCommand());
   program.addCommand(infoCommand());
   program.addCommand(commentCommand());
   program.addCommand(commentsCommand());
@@ -5604,10 +6288,10 @@ async function main(argv) {
     const cleaned = argv.filter((a, i) => !(a === "--" && i >= 2));
     await program.parseAsync(cleaned);
   } catch (err) {
-    handleError(err);
+    await handleError(err);
   }
 }
-function handleError(err) {
+async function handleError(err) {
   if (err instanceof KordisApiError) {
     if (isJsonMode()) {
       printJson({
@@ -5654,7 +6338,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);
+    await reportError("network_unreachable", err);
     process.exit(err.exitCode());
   }
   if (err instanceof Error) {
@@ -5674,7 +6358,7 @@ function handleError(err) {
         for (const line of hintStr.split("\n")) printHuman(c.gray(`      \u2192 ${line}`));
       }
     }
-    void reportError("unhandled_error", err);
+    await reportError("unhandled_error", err);
     process.exit(1);
   }
   if (isJsonMode()) printJson({ error: { code: "generic_failure", message: String(err) } });