@rayul/kordis 0.7.0 → 0.8.0

package/assets/kordis-search/SKILL.md

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

package/assets/kordis-social/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: kordis-social
-description: Use whenever the user wants to log into Kordis, log out, check identity, post a typed comment on a Kordis package, or star/unstar a package. Triggers include "log into Kordis", "kordis login", "who am I logged in as on Kordis", "log me out of Kordis", "leave a tip on <slug>", "report a bug on <slug>", "comment on <slug>", "star <slug>", "unstar <slug>", "favourite <slug>".
+description: Use whenever the user wants to log into Kordis, log out, check identity, post a typed comment on a Kordis package, star/unstar a package, view a user's public profile, list their packages or stars, or follow/unfollow another user. Triggers include "log into Kordis", "kordis login", "who am I logged in as on Kordis", "log me out of Kordis", "leave a tip on <slug>", "report a bug on <slug>", "comment on <slug>", "star <slug>", "unstar <slug>", "favourite <slug>", "follow <username>", "unfollow <username>", "팔로우", "팔로워", "show me <username>'s profile", "프로필", "what has <username> starred", "who follows <username>", "who does <username> follow".
 type: skill
 allowed-tools: ["Bash(kordis:*)"]
 ---
 
-# Kordis: Identity, Comments, & Stars
+# Kordis: Identity, Comments, Stars, & Social
 
 ## Goal
 Drive the user's login state and the social actions Kordis exposes — typed
-comments and stars.
+comments, stars, public profiles, and follow/unfollow (0.8.0+).
 
 ## Identity commands
 
@@ -127,9 +127,72 @@ User: "unstar foo/bar"
 - show updated count
 </example>
 
+## Profile & follow commands (0.8.0+)
+
+### `kordis profile <username>`
+Anonymous-OK. Shows display name, bio, follower count, package count,
+total stars, total downloads, first/last published timestamps.
+
+### `kordis list <username>` (extended)
+With no argument → your own packages (auth required, offset pagination).
+With a username → public packages of that user (anonymous-OK, cursor
+pagination via `--cursor`).
+
+### `kordis stars <username>`
+Anonymous-OK. Lists packages this user has starred. Cursor-paginated.
+
+### `kordis follow <username>` / `kordis unfollow <username>`
+Auth required. Idempotent (re-following is a no-op, no double-count).
+Self-follow is rejected with `usage_error`. Response carries the
+post-mutation `follower_count` so you don't need a separate GET.
+
+### `kordis followers <username>` / `kordis following <username>`
+Anonymous-OK, cursor-paginated. Returns `PublicUser` rows.
+
+<example>
+User: "show me alice's profile"
+- kordis profile alice --json
+- render display_name, bio, package_count, follower_count, joined date
+</example>
+
+<example>
+User: "follow alice"
+- ALWAYS check the user is logged in first (`kordis whoami --json`); if
+  not authenticated, prompt them to run `kordis login --emit-only`
+- kordis follow alice --json
+- report the updated follower_count from the response
+</example>
+
+<example>
+User: "what has bob starred?" / "bob이 별 누른거 보여줘"
+- kordis stars bob --json
+- render top results; offer `--cursor` for the next page if `next_cursor` is non-null
+</example>
+
+<example>
+User: "who follows alice?"
+- kordis followers alice --json
+- list users; for each, display username + display_name + follower_count
+</example>
+
+<example>
+User: "i don't want to follow alice anymore"
+- ALWAYS confirm the user intent before destructive social actions (unfollow IS reversible — re-following is one command — but a courtesy confirm avoids surprises)
+- kordis unfollow alice --json
+- report the new follower_count
+</example>
+
+<example>
+User: "kordis list popular"
+- this is a sort-keyword collision — `popular` is NOT a username
+- the CLI catches this client-side and points the user at `--sort popular`
+- show the error message verbatim; don't try to "fix" it by guessing
+</example>
+
 ## Limitations
 
-The CLI does NOT yet expose follow, listing comments, replies, editing or
-moderating comments, or notifications. If the user asks for any of those, tell
-them truthfully that the CLI verb is not implemented yet — do NOT fabricate a
-command. For now direct them to `https://kordis.store`.
+The CLI now exposes follow/unfollow + profile + public list/stars
+(0.8.0+). Still NOT exposed: listing comments per user (use `kordis
+comments <full_slug>` for per-package), per-user blocklists,
+notifications, friend recommendations. For those direct the user to
+`https://kordis.store` or wait for the next minor.

package/dist/index.js

@@ -486,7 +486,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, PullPackageResponseSchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema;
+var SearchQuerySchema, SearchResponseSchema, TrendingQuerySchema, RisingQuerySchema, StarResponseSchema, AssetSchema, PublishPackageRequestSchema, PublishWaitQuerySchema, PublishPackageResponseSchema, PackagePathParamsSchema, ContentQuerySchema, PackageContentResponseSchema, JitReadRequestSchema, JitReadResponseSchema, PullPackageResponseSchema, ListVersionsResponseSchema, VersionDiffQuerySchema, ListCommentsQuerySchema, ListCommentsResponseSchema, UserProfileResponseSchema, UserPackagesQuerySchema, ListUserPackagesResponseSchema, ListUserStarsResponseSchema, FollowResponseSchema, ListFollowersQuerySchema, ListFollowersResponseSchema;
 var init_api = __esm({
   "../../packages/contracts/src/api.ts"() {
     "use strict";
@@ -709,6 +709,26 @@ var init_api = __esm({
       limit: z9.coerce.number().int().min(1).max(100).default(20),
       cursor: CursorSchema.optional()
     });
+    ListUserPackagesResponseSchema = z9.object({
+      results: PackageSummarySchema.array(),
+      next_cursor: z9.string().nullable()
+    });
+    ListUserStarsResponseSchema = z9.object({
+      results: PackageSummarySchema.array(),
+      next_cursor: z9.string().nullable()
+    });
+    FollowResponseSchema = z9.object({
+      following: z9.boolean(),
+      follower_count: z9.number().int().nonnegative()
+    });
+    ListFollowersQuerySchema = z9.object({
+      limit: z9.coerce.number().int().min(1).max(100).default(50),
+      cursor: CursorSchema.optional()
+    });
+    ListFollowersResponseSchema = z9.object({
+      results: PublicUserSchema.array(),
+      next_cursor: z9.string().nullable()
+    });
   }
 });
 
@@ -912,6 +932,34 @@ var init_src = __esm({
 });
 
 // ../../packages/api-client/src/errors.ts
+function httpStatusToCode(status) {
+  if (status === 401) return "not_authenticated";
+  if (status === 403) return "not_authorized";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "internal_error";
+  if (status >= 400) return "usage_error";
+  return "generic_failure";
+}
+function normalizeErrorEnvelope(status, parsed, fallbackText) {
+  const isObject = (v) => typeof v === "object" && v !== null;
+  if (isObject(parsed) && isObject(parsed.error) && typeof parsed.error.code === "string" && typeof parsed.error.message === "string") {
+    return parsed;
+  }
+  let message;
+  if (isObject(parsed) && typeof parsed.message === "string") {
+    message = parsed.message;
+  } else if (fallbackText) {
+    message = fallbackText.slice(0, 500);
+  }
+  return {
+    error: {
+      code: httpStatusToCode(status),
+      message: message ?? `HTTP ${status}`
+    }
+  };
+}
 var KordisApiError, KordisNetworkError;
 var init_errors2 = __esm({
   "../../packages/api-client/src/errors.ts"() {
@@ -993,26 +1041,42 @@ var init_client = __esm({
         };
         if (opts.body !== void 0) headers["content-type"] = "application/json";
         let res;
-        try {
-          const init = {
-            method: opts.method ?? "GET",
-            headers,
-            cache: "no-store"
-          };
-          if (opts.body !== void 0) init.body = JSON.stringify(opts.body);
-          res = await this.fetchImpl(url, init);
-        } catch (err) {
+        const init = {
+          method: opts.method ?? "GET",
+          headers,
+          cache: "no-store"
+        };
+        if (opts.body !== void 0) init.body = JSON.stringify(opts.body);
+        const method = (init.method ?? "GET").toUpperCase();
+        const retryable = method === "GET";
+        let lastErr;
+        for (let attempt = 0; attempt < (retryable ? 2 : 1); attempt++) {
+          try {
+            res = await this.fetchImpl(url, init);
+            lastErr = void 0;
+            break;
+          } catch (err) {
+            lastErr = err;
+            if (attempt === 0 && retryable) {
+              await new Promise((resolve2) => setTimeout(resolve2, 150));
+              continue;
+            }
+          }
+        }
+        if (lastErr !== void 0) {
           throw new KordisNetworkError(
-            `cannot reach ${url.hostname}: ${err.message}`,
-            err
+            `cannot reach ${url.hostname}: ${lastErr.message}`,
+            lastErr
           );
         }
+        res = res;
         const requestId = res.headers.get("x-request-id") ?? void 0;
         if (res.status === 204) return void 0;
         const text = await res.text();
         const parsed = text ? JSON.parse(text) : void 0;
         if (!res.ok) {
-          throw new KordisApiError(res.status, parsed, requestId);
+          const envelope = normalizeErrorEnvelope(res.status, parsed, text);
+          throw new KordisApiError(res.status, envelope, requestId);
         }
         return parsed;
       }
@@ -1218,6 +1282,51 @@ var init_client = __esm({
           body: payload
         });
       }
+      // ─── social (0.8.0+) ───────────────────────────────────────────────────
+      /** Public profile + aggregated stats. Anonymous-OK. */
+      getUserProfile(username) {
+        return this.request(`/api/users/${encodeURIComponent(username)}`);
+      }
+      /** Cursor-paginated public package list authored by `username`. */
+      listUserPackages(username, query = {}) {
+        return this.request(
+          `/api/users/${encodeURIComponent(username)}/packages`,
+          { query }
+        );
+      }
+      /** Cursor-paginated packages that `username` has starred. */
+      listUserStars(username, 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) {
+        return this.request(`/api/users/${encodeURIComponent(username)}/follow`, {
+          method: "POST"
+        });
+      }
+      /** Auth-required. Idempotent (unfollow of non-edge is a no-op). */
+      unfollowUser(username) {
+        return this.request(`/api/users/${encodeURIComponent(username)}/follow`, {
+          method: "DELETE"
+        });
+      }
+      /** Cursor-paginated followers of `username`. Anonymous-OK. */
+      listUserFollowers(username, query = {}) {
+        return this.request(
+          `/api/users/${encodeURIComponent(username)}/followers`,
+          { query }
+        );
+      }
+      /** Cursor-paginated users that `username` follows. Anonymous-OK. */
+      listUserFollowing(username, query = {}) {
+        return this.request(
+          `/api/users/${encodeURIComponent(username)}/following`,
+          { query }
+        );
+      }
     };
   }
 });
@@ -1227,7 +1336,8 @@ var src_exports = {};
 __export(src_exports, {
   KordisApiError: () => KordisApiError,
   KordisClient: () => KordisClient,
-  KordisNetworkError: () => KordisNetworkError
+  KordisNetworkError: () => KordisNetworkError,
+  normalizeErrorEnvelope: () => normalizeErrorEnvelope
 });
 var init_src2 = __esm({
   "../../packages/api-client/src/index.ts"() {
@@ -1239,7 +1349,7 @@ var init_src2 = __esm({
 
 // src/index.ts
 init_src2();
-import { Command as Command19 } from "commander";
+import { Command as Command23 } from "commander";
 
 // src/commands/login.ts
 import { Command } from "commander";
@@ -1774,7 +1884,7 @@ async function useClient() {
             username = null;
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(
-              `[kordis] auto-finalize: server issued tokens but local persistence failed (${msg}). Run \`kordis login --emit-only\` again to retry.
+              `[kordis] auto-finalize: server issued tokens but local persistence failed (${msg}). Run \`kordis login --emit-only\` again to retry. If this keeps happening on macOS, the OS keychain prompt may be timing out \u2014 set \`KORDIS_NO_KEYCHAIN=1\` to fall back to a plaintext file at ~/.kordis/.tokens.json (mode 0600). Set \`KORDIS_DEBUG=1\` for full auto-finalize stage output.
 `
             );
             void reportError("auto_finalize_stage2_fail", err);
@@ -1968,7 +2078,7 @@ function requireAuth(bundle) {
     error: {
       code: "not_authenticated",
       message: "authentication required",
-      hint: "Run `kordis login --emit-only` to start browser sign-in (exits immediately, no blocking poll), then re-run this command \u2014 the next CLI call auto-claims the token. For interactive shells, plain `kordis login` (10-min poll) also works."
+      hint: "Run `kordis login --emit-only` to start browser sign-in (exits immediately, no blocking poll), then re-run this command \u2014 the next CLI call auto-claims the token. For interactive shells, plain `kordis login` (10-min poll) also works. If you DID login but auth keeps failing, run with `KORDIS_DEBUG=1` to surface auto-finalize stages (Round 12 F1 \u2014 diagnostic moment-of-need)."
     }
   });
 }
@@ -4279,44 +4389,91 @@ function deleteCommand() {
 
 // src/commands/list.ts
 import { Command as Command13 } from "commander";
+
+// 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/commands/list.ts
 function listCommand() {
-  return new Command13("list").description("list your own packages (requires login)").option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10), 1).option("--sort <mode>", "sort: latest|popular", "latest").action(async (opts) => {
-    const sort = opts.sort === "popular" ? "popular" : "latest";
+  return new Command13("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();
-    requireAuth(bundle);
-    const spin = spinner("Fetching your packages");
-    const res = await bundle.authedRequest(
-      (api) => api.listMyPackages({ page: opts.page, limit: opts.limit, sort })
-    );
-    spin.succeed();
+    if (rawUsername === void 0) {
+      requireAuth(bundle);
+      const sort = opts.sort === "popular" ? "popular" : "latest";
+      const spin = spinner("Fetching your packages");
+      const res2 = await bundle.authedRequest(
+        (api) => api.listMyPackages({ page: opts.page, limit: opts.limit, sort })
+      );
+      spin.succeed();
+      printDual({
+        json: res2,
+        human: () => {
+          if (res2.packages.length === 0) {
+            printHuman(c.yellow("(no packages yet \u2014 use `kordis push` to publish your first)"));
+            return;
+          }
+          printHuman(
+            c.gray(
+              `Showing ${res2.packages.length} of ${res2.total} package${res2.total !== 1 ? "s" : ""} (page ${res2.page})`
+            )
+          );
+          printHuman("");
+          for (const p of res2.packages) {
+            const desc = p.description.length > 60 ? p.description.slice(0, 57) + "..." : p.description;
+            printHuman(
+              `${c.bold(p.full_slug)} ${c.gray(`v${p.current_version}`)} ${c.cyan(`[${p.type}]`)}`
+            );
+            printHuman(`  ${desc}`);
+            printHuman(c.gray(`  \u2605 ${p.stars}  \u21E3 ${p.downloads}  ${p.visibility}`));
+            printHuman("");
+          }
+          if (res2.page * res2.limit < res2.total) {
+            printHuman(c.gray(`(more available \u2014 pass --page ${res2.page + 1})`));
+          }
+        }
+      });
+      return;
+    }
+    const username = parseUsername(rawUsername);
+    const publicSort = ["stars", "downloads", "recent", "updated"].includes(opts.sort) ? opts.sort : "stars";
+    const res = await bundle.api.listUserPackages(username, {
+      limit: opts.limit,
+      sort: publicSort,
+      ...opts.cursor ? { cursor: opts.cursor } : {}
+    });
     printDual({
       json: res,
       human: () => {
-        if (res.packages.length === 0) {
-          printHuman(c.yellow("(no packages yet \u2014 use `kordis push` to publish your first)"));
+        if (res.results.length === 0) {
+          printHuman(c.yellow(`(no public packages for ${username})`));
           return;
         }
-        printHuman(
-          c.gray(
-            `Showing ${res.packages.length} of ${res.total} package${res.total !== 1 ? "s" : ""} (page ${res.page})`
-          )
-        );
-        printHuman("");
-        for (const p of res.packages) {
+        for (const p of res.results) {
           const desc = p.description.length > 60 ? p.description.slice(0, 57) + "..." : p.description;
           printHuman(
-            `${c.bold(p.full_slug)} ${c.gray(`v${p.current_version}`)} ${c.cyan(`[${p.type}]`)}`
+            `${c.bold(p.full_slug)} ${c.gray("v" + p.current_version)} ${c.cyan("[" + p.type + "]")}`
           );
           printHuman(`  ${desc}`);
-          printHuman(
-            c.gray(`  \u2605 ${p.stars}  \u21E3 ${p.downloads}  ${p.visibility}`)
-          );
+          printHuman(c.gray(`  \u2605 ${p.stars}  \u21E3 ${p.downloads}`));
           printHuman("");
         }
-        if (res.page * res.limit < res.total) {
-          printHuman(
-            c.gray(`(more available \u2014 pass --page ${res.page + 1})`)
-          );
+        if (res.next_cursor) {
+          printHuman(c.gray(`(more available \u2014 kordis list ${username} --cursor ${res.next_cursor})`));
         }
       }
     });
@@ -4778,12 +4935,171 @@ function renderItem(idx, it, verbose) {
   printHuman("");
 }
 
+// src/commands/profile.ts
+import { Command as Command19 } from "commander";
+function profileCommand() {
+  return new Command19("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);
+    printDual({
+      json: profile,
+      human: () => {
+        const verified = profile.is_verified ? c.cyan(" \u2713") : "";
+        const displayLine = profile.display_name ? `${c.bold(profile.username)}${verified}  ${c.gray("(" + profile.display_name + ")")}` : `${c.bold(profile.username)}${verified}`;
+        printHuman(displayLine);
+        if (profile.bio) printHuman(c.gray(profile.bio));
+        printHuman("");
+        printHuman(
+          `  ${c.bold(String(profile.stats.package_count))} packages  \xB7  ${c.bold(String(profile.stats.total_stars))} \u2605 across all  \xB7  ${c.bold(String(profile.stats.total_downloads))} downloads`
+        );
+        printHuman(
+          `  ${c.bold(String(profile.follower_count))} follower${profile.follower_count === 1 ? "" : "s"}  \xB7  joined ${profile.created_at.split("T")[0]}`
+        );
+        if (profile.stats.last_published_at) {
+          printHuman(
+            c.gray(
+              `  last published: ${profile.stats.last_published_at.split("T")[0]}`
+            )
+          );
+        }
+        printHuman("");
+        printHuman(c.gray(`  \u2192 list packages: kordis list ${profile.username}`));
+        printHuman(c.gray(`  \u2192 list stars:    kordis stars ${profile.username}`));
+        printHuman(c.gray(`  \u2192 follow:        kordis follow ${profile.username}`));
+      }
+    });
+  });
+}
+
+// src/commands/stars.ts
+import { Command as Command20 } from "commander";
+function starsCommand() {
+  return new Command20("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 } : {}
+    });
+    printDual({
+      json: 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`));
+          return;
+        }
+        for (const p of res.results) {
+          printHuman(
+            `${c.bold(p.full_slug)} ${c.gray("v" + p.current_version)} ${c.cyan("[" + p.type + "]")}`
+          );
+          printHuman(`  ${p.description}`);
+          printHuman(c.gray(`  \u2605 ${p.stars}  \xB7  \u21E3 ${p.downloads}`));
+          printHuman("");
+        }
+        if (res.next_cursor) {
+          printHuman(c.gray(`(more available \u2014 kordis stars ${username} --cursor ${res.next_cursor})`));
+        }
+      }
+    });
+  });
+}
+
+// src/commands/follow.ts
+import { Command as Command21 } from "commander";
+function followCommand() {
+  return new Command21("follow").description("follow a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+    const username = parseUsername(raw);
+    const bundle = await useClient();
+    requireAuth(bundle);
+    const res = await bundle.authedRequest((api) => api.followUser(username));
+    printDual({
+      json: res,
+      human: () => {
+        printHuman(c.green(`\u2713 following ${username}`));
+        printHuman(c.gray(`  total followers: ${res.follower_count}`));
+      }
+    });
+  });
+}
+function unfollowCommand() {
+  return new Command21("unfollow").description("stop following a kordis user").argument("<username>", "kordis username").action(async (raw) => {
+    const username = parseUsername(raw);
+    const bundle = await useClient();
+    requireAuth(bundle);
+    const res = await bundle.authedRequest((api) => api.unfollowUser(username));
+    printDual({
+      json: res,
+      human: () => {
+        printHuman(c.gray(`\u2717 unfollowed ${username}`));
+        printHuman(c.gray(`  total followers: ${res.follower_count}`));
+      }
+    });
+  });
+}
+
+// src/commands/followers.ts
+import { Command as Command22 } from "commander";
+function makeListing(name) {
+  return new Command22(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);
+    const bundle = await useClient();
+    const fn = name === "followers" ? bundle.api.listUserFollowers.bind(bundle.api) : bundle.api.listUserFollowing.bind(bundle.api);
+    const res = await fn(username, {
+      limit: opts.limit,
+      ...opts.cursor ? { cursor: opts.cursor } : {}
+    });
+    printDual({
+      json: res,
+      human: () => {
+        if (res.results.length === 0) {
+          const noun = name === "followers" ? "followers yet" : "one yet";
+          printHuman(c.yellow(`(no ${noun} for ${username})`));
+          return;
+        }
+        for (const u of res.results) {
+          const verified = u.is_verified ? c.cyan(" \u2713") : "";
+          const display = u.display_name ? ` ${c.gray("(" + u.display_name + ")")}` : "";
+          printHuman(`${c.bold(u.username)}${verified}${display}`);
+          printHuman(
+            c.gray(
+              `  ${u.follower_count} follower${u.follower_count === 1 ? "" : "s"}  \xB7  joined ${u.created_at.split("T")[0]}`
+            )
+          );
+          printHuman("");
+        }
+        if (res.next_cursor) {
+          printHuman(c.gray(`(more available \u2014 kordis ${name} ${username} --cursor ${res.next_cursor})`));
+        }
+      }
+    });
+  });
+}
+function followersCommand() {
+  return makeListing("followers");
+}
+function followingCommand() {
+  return makeListing("following");
+}
+
 // src/index.ts
 function buildProgram() {
-  const program = new Command19("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
+  const program = new Command23("kordis").version(VERSION).description("Kordis \u2014 registry for agentic-coding packages").option("--json", "emit JSON output to stdout (default: human)", false).hook("preAction", (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
     if (opts.json) setJsonMode(true);
-  });
+  }).addHelpText("after", `
+Environment variables (see README.md "Privacy & environment variables"):
+  KORDIS_API_URL=<url>     override registry endpoint (default: https://api.kordis.store)
+  KORDIS_HOME=<dir>        override config + token fallback dir (default: ~/.kordis)
+  KORDIS_NO_CONTEXT=1      suppress personalization header even if opted in
+  KORDIS_NO_TELEMETRY=1    suppress anonymized error telemetry even if opted in
+  KORDIS_NO_KEYCHAIN=1     force plaintext token storage at ~/.kordis/.tokens.json
+                           (escape hatch for macOS keychain-prompt fatigue)
+  KORDIS_DEBUG=1           surface auto-finalize stage outcomes to stderr (diagnostic)
+`);
   program.addCommand(loginCommand());
   program.addCommand(logoutCommand());
   program.addCommand(whoamiCommand());
@@ -4797,6 +5113,12 @@ function buildProgram() {
   program.addCommand(uncommentCommand());
   program.addCommand(starCommand());
   program.addCommand(unstarCommand());
+  program.addCommand(profileCommand());
+  program.addCommand(starsCommand());
+  program.addCommand(followCommand());
+  program.addCommand(unfollowCommand());
+  program.addCommand(followersCommand());
+  program.addCommand(followingCommand());
   program.addCommand(deleteCommand());
   program.addCommand(listCommand());
   program.addCommand(versionsCommand());

package/package.json

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