skillrepo 4.4.0 → 4.5.0

package/README.md

@@ -179,14 +179,48 @@ One-shot fetch. Does NOT mutate your library or the server — just reads
 `GET /api/v1/skills/{owner}/{name}` and writes the skill to disk. Use
 this to preview or pin a specific skill without adding it to your library.
 
-### `list` — show what's in your library
+### `list` — show what's in your library and what needs syncing
 
 ```sh
 skillrepo list [--json]
 ```
 
-Renders your library as a table: owner, name, version, description. Uses
-the same cached ETag as `update`.
+Renders your library as a table with a per-row `Local` column showing
+on-disk drift state for each detected vendor:
+
+- `OK` — local copy matches the last sync.
+- `STALE` — library has a newer version than what's on disk.
+- `MISS` — library has the skill but no on-disk placement (or no sync
+  history yet — run `skillrepo update` to establish a baseline).
+- `EDIT` — local files have been modified since the last sync (different
+  SHA than what was persisted).
+
+When multiple vendors are detected, the column shows a worst-state-wins
+rollup (`missing > edited > stale > current`). The `--json` output
+includes a `placements[]` array per item with per-vendor states for
+scripts that want the full breakdown.
+
+A footer reports library-level sync state:
+
+- `library in sync — local skills up to date` — everything is current.
+- `library in sync — but N skills show local drift` — library hasn't
+  changed but some local placements need attention.
+- `library has changed since last sync` — registry has new content; run
+  `skillrepo update`.
+- `No sync history on this machine` — fresh install or
+  baseline-less state; run `skillrepo update`.
+
+Glyphs (`✓` / `⚠`) are used in TTY contexts; ASCII fallbacks (`OK` /
+`[!]` / `STALE` / `MISS` / `EDIT`) appear when stdout is not a TTY or
+`NO_COLOR` is set, so piped output stays clean.
+
+`--json` is a bare array of skill objects with the additional fields
+`state` (rollup) and `placements[]`. Existing scripts that consume
+the pre-#1555 `--json` shape keep working — the additions are purely
+per-item, no top-level wrapper.
+
+Uses the same cached ETag as `update` for the library-level footer
+state.
 
 ### `search` — explore the registry
 
@@ -474,8 +508,28 @@ Two scenarios worth calling out:
 | `SKILLREPO_ACCESS_KEY` | Access key for any command. Takes precedence over the config file but not CLI flags. |
 | `SKILLREPO_URL` | Server URL. Same precedence as above. |
 | `SKILLREPO_TIMEOUT_MS` | Per-request fetch timeout in milliseconds (default 30000). Set to `0` to disable. |
+| `SKILLREPO_NO_UPDATE_CHECK` | Set to any non-empty truthy value (`1`, `yes`, `true`) to disable the post-command npm-registry self-staleness check. The check otherwise runs at most once per 24 hours, hits `registry.npmjs.org/skillrepo/latest`, and prints a one-line upgrade hint to stderr if a newer version is available. Auto-disabled when `CI=true`. |
 | `NO_COLOR` | Set any non-empty value to disable ANSI color in CLI output. |
 
+### Update nudge
+
+After every command that isn't `--json`, the CLI does a best-effort
+check against `https://registry.npmjs.org/skillrepo/latest` and prints
+a one-line hint on stderr when a newer version is available:
+
+```
+  A newer skillrepo is available: 4.3.0 → 4.5.0
+  Upgrade: npm install -g skillrepo@latest
+```
+
+The check is cached at `~/.claude/skillrepo/.npm-version-check` for
+24 hours on success and 1 hour on failure, has a 2-second fetch
+timeout, and is fire-and-forget — every failure mode (network error,
+non-2xx, parse failure, read-only FS) is swallowed silently. Set
+`SKILLREPO_NO_UPDATE_CHECK=1` to disable. `CI=true` auto-disables.
+Output is suppressed entirely when `--json` is on the parent command,
+so structured pipelines aren't disturbed.
+
 ### Skill placement
 
 Skills land at one of two project paths, depending on the agent:

package/bin/skillrepo.mjs

@@ -35,6 +35,8 @@ import { runSearch } from "../src/commands/search.mjs";
 import { runUninstall } from "../src/commands/uninstall.mjs";
 import { runSessionSync } from "../src/commands/session-sync.mjs";
 import { CliError, EXIT_OK, EXIT_VALIDATION } from "../src/lib/errors.mjs";
+import { checkForCliUpdate } from "../src/lib/npm-update-check.mjs";
+import { getCliVersion } from "../src/lib/cli-version.mjs";
 
 // ── Command registry ────────────────────────────────────────────────────
 
@@ -151,6 +153,49 @@ async function main(command, fullArgv) {
   }
 
   await COMMANDS[command].run(rest);
+
+  // After the primary command completes, do a best-effort npm-registry
+  // staleness check (#1554). Never blocks exit beyond a single tick:
+  // `Promise.race` against `setTimeout(0)` means if the fetch hasn't
+  // completed yet, we drop it and the user gets the nudge on the next
+  // invocation (when the cache file is more likely to be fresh).
+  //
+  // Suppressed entirely when the parent argv carries `--json` so we
+  // never inject text into a structured stream — not even on stderr,
+  // because some pipelines tee both streams.
+  if (!rest.includes("--json")) {
+    await runUpdateCheck();
+  }
+}
+
+/**
+ * Best-effort update check. On a CACHE HIT this resolves synchronously
+ * (within a microtask) and we emit the nudge before the 0ms timer
+ * fires — that's the steady-state behavior after the first invocation.
+ *
+ * On a cache miss we race against `setTimeout(0)` so the user's primary
+ * command exit isn't held up by the nudge logic when they don't have
+ * a cached answer yet. The in-flight fetch is INTENTIONALLY left
+ * running after the race resolves: it has its own 2s `AbortController`
+ * (inside `checkForCliUpdate`) and is silent on failure, so the worst
+ * case is the process appearing to take slightly longer on its very
+ * first invocation while the cache warms. Every subsequent invocation
+ * benefits from the 24h positive cache and exits immediately.
+ *
+ * Errors are swallowed at the source by `checkForCliUpdate` itself; the
+ * outer `.catch` is belt-and-braces for the rare case where loading
+ * the module synchronously throws.
+ */
+async function runUpdateCheck() {
+  let currentVersion;
+  try {
+    currentVersion = getCliVersion();
+  } catch {
+    return;
+  }
+  const checker = checkForCliUpdate({ currentVersion }).catch(() => {});
+  const yieldOnce = new Promise((resolve) => setTimeout(resolve, 0));
+  await Promise.race([checker, yieldOnce]);
 }
 
 // ── Help printing ───────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {
@@ -26,6 +26,7 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "cli-table3": "^0.6.5",
-    "gray-matter": "^4.0.3"
+    "gray-matter": "^4.0.3",
+    "semver": "^7.6.3"
   }
 }

package/src/commands/list.mjs

@@ -1,21 +1,36 @@
 /**
- * `skillrepo list` (#679).
+ * `skillrepo list` — list library skills with per-row local drift state (#1555).
  *
- * Lists the authenticated account's library contents. Default output
- * is a human-readable table via `cli-table3`. `--json` flag prints
- * the raw metadata array for piping into `jq` or other tools.
+ * Historically (#679) this only showed the server-side library. As of
+ * #1555 the table adds a `Local` column showing how each skill's
+ * on-disk placement stacks up against the library + last-sync
+ * baseline: `current` / `stale` / `missing` / `edited`. A footer
+ * reports the library-level ETag state ("library in sync" vs
+ * "library has changed since last sync").
  *
- * Calls GET /api/v1/library and ignores the inlined file content —
- * we only need metadata for display. There is no metadata-only
- * endpoint; reading the full library payload is the cost of reusing
- * the same route the sync engine uses.
+ * Pipeline:
+ *   1. `getLibrary` returns the current registry skills + ETag.
+ *   2. `readLastSync` reads the v2 `.last-sync` map (per-skill SHAs +
+ *      versions) for the on-disk-vs-synced comparison.
+ *   3. `detectAgents` identifies which vendors actually have footprint
+ *      on this machine / in this project — we only report drift
+ *      against vendors the user uses.
+ *   4. `walkDetectedPlacements` reads each detected vendor's
+ *      placement dir and computes SHAs from disk.
+ *   5. `computeSkillState` + `rollupState` from `drift.mjs` turn the
+ *      three axes into a per-vendor state and a per-skill rollup.
  *
  * Flags:
- *   --json           Pipe-friendly JSON output
- *   --key/--url      Override credentials
+ *   --json           Pipe-friendly JSON output (bare array preserved
+ *                    from #679 — purely additive: new `state` and
+ *                    `placements[]` fields per item, no top-level
+ *                    wrapper).
+ *   --key/--url      Override credentials.
  *
- * No --global / --agent flags — `list` is a library-state inspector,
- * not a writer.
+ * No `--global`, `--detail`, `--vendor`, or `--include-extra` flags
+ * in v1 — YAGNI per the epic's decisions log. Project-scope
+ * placement only; extra-on-disk skills (in placement but not in
+ * library) are hidden by default.
  */
 
 import Table from "cli-table3";
@@ -23,6 +38,11 @@ import Table from "cli-table3";
 import { getLibrary } from "../lib/http.mjs";
 import { resolveFlags } from "../lib/cli-config.mjs";
 import { formatIdentifier } from "../lib/identifier.mjs";
+import { readLastSync } from "../lib/sync.mjs";
+import { detectAgents } from "../lib/detect-agents.mjs";
+import { walkDetectedPlacements } from "../lib/placement-walk.mjs";
+import { getAgentByKey } from "../lib/agent-registry.mjs";
+import { computeSkillState, rollupState, SKILL_STATE } from "../lib/drift.mjs";
 
 /**
  * Run `list`. Throws CliError on any failure.
@@ -36,59 +56,165 @@ export async function runList(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const flags = resolveFlags(argv);
 
-  const result = await getLibrary(flags.serverUrl, flags.apiKey);
+  const libraryResponse = await getLibrary(flags.serverUrl, flags.apiKey);
 
-  // `list` does not care about removals or sync state — we just want
-  // the current set. Skills are returned by the same endpoint as the
-  // sync, but with full file content we discard.
-  //
   // Defensive guard: `list` calls getLibrary without an If-None-Match
   // header so it can't legitimately receive a 304 today. But getLibrary's
   // contract documents `notModified: true` as a possible return shape,
   // and a future refactor that adds caching at this layer could
-  // accidentally start sending the header. Treat `result.skills` as
-  // possibly empty rather than possibly undefined.
-  const skills = Array.isArray(result.skills) ? result.skills : [];
+  // accidentally start sending the header.
+  const skills = Array.isArray(libraryResponse.skills) ? libraryResponse.skills : [];
+
+  // Detect agents + walk placements regardless of skill count — we
+  // need this info for both the table and the JSON shape.
+  const detected = detectAgents().filter((d) => d.detected);
+
+  // Pre-resolve the detected vendor entries ONCE. `getAgentByKey` is
+  // O(N) over the registry; doing this per-skill across 50+ skills
+  // was wasted work. We also filter to vendors with a non-null
+  // projectTarget here so the per-skill loop only iterates vendors
+  // that actually contribute a placement.
+  const detectedVendorEntries = detected
+    .map((d) => getAgentByKey(d.key))
+    .filter((entry) => entry !== null && entry.projectTarget !== null);
+  const detectedKeys = detectedVendorEntries.map((e) => e.key);
+
+  const placementsMap = walkDetectedPlacements(detectedKeys);
+
+  // Read `.last-sync` ONCE. Direct map access on the parsed
+  // `skills` payload — no per-skill helper indirection — for both
+  // wasted-I/O reasons (N reads of the same file otherwise) AND
+  // a within-run snapshot-consistency window (a concurrent
+  // `skillrepo update` writing the file mid-list would otherwise
+  // produce inconsistent classifications across skills in the
+  // same render).
+  const lastSync = readLastSync();
+  const lastSyncSkillsMap =
+    lastSync && lastSync.skills && typeof lastSync.skills === "object"
+      ? lastSync.skills
+      : {};
+
+  // Build the augmented per-skill state for every library skill. This
+  // is the canonical shape both the table renderer and JSON formatter
+  // project from.
+  const augmented = skills.map((skill) =>
+    augmentSkill(skill, detectedVendorEntries, placementsMap, lastSyncSkillsMap),
+  );
 
   if (flags.json) {
-    stdout.write(JSON.stringify(formatJson(skills), null, 2) + "\n");
+    stdout.write(JSON.stringify(formatJson(augmented), null, 2) + "\n");
     return;
   }
 
-  if (skills.length === 0) {
+  if (augmented.length === 0) {
     stdout.write(
       "\n  Your library is empty.\n  Use `skillrepo add <@owner/name>` to add a skill.\n\n",
     );
     return;
   }
 
-  printTable(skills, stdout);
+  printTable(augmented, detected, stdout);
+  printFooter(augmented, libraryResponse.etag, lastSync, stdout, canUseGlyphs(stdout));
 }
 
+// ── Per-skill augmentation ─────────────────────────────────────────────
+
 /**
- * Read the column width from the active output stream, falling back
- * to process.stdout's TTY column count if the injected stream
- * doesn't carry one (e.g., a test capture stream), then to a 100-col
- * default for non-TTY contexts. Reading from `out.columns` first
- * means a future test that injects a stream advertising a specific
- * width will be honored.
+ * Compute `state` (rollup) + `placements[]` for a library skill.
+ *
+ * For each detected vendor (pre-resolved by the caller) look up the
+ * on-disk placement and the last-sync baseline, classify the state,
+ * and emit a placement entry. Then roll the per-vendor states up to
+ * a single `state` for the table column.
+ *
+ * Baseline lookups go through the caller-provided `lastSyncSkillsMap`
+ * to avoid re-reading `.last-sync` per skill — both a wasted-I/O
+ * concern and a within-run snapshot consistency concern (an
+ * in-flight `skillrepo update` could otherwise change the file
+ * between our N reads).
+ *
+ * @param {object} skill - Library skill from `getLibrary` response.
+ * @param {import("../lib/agent-registry.mjs").AgentEntry[]} detectedVendorEntries
+ *   Pre-resolved registry entries for the detected vendors that
+ *   contribute a project placement. Computed once in `runList` so
+ *   the registry lookup doesn't happen per skill.
+ * @param {Map<string, import("../lib/placement-walk.mjs").LocalPlacement>} placementsMap
+ * @param {Record<string, import("../lib/sync.mjs").SyncedSkillEntry>} lastSyncSkillsMap
+ *   The `skills` map from `.last-sync` v2, captured once before the
+ *   per-skill loop. Lookup is a direct dictionary access, not a
+ *   re-read of the file.
  */
-function streamColumns(out) {
-  if (out && typeof out.columns === "number" && out.columns > 0) {
-    return out.columns;
+function augmentSkill(skill, detectedVendorEntries, placementsMap, lastSyncSkillsMap) {
+  const baselineKey = `${skill.owner}/${skill.name}`;
+  const baseline = validateBaselineShape(lastSyncSkillsMap[baselineKey]);
+  const placements = [];
+
+  for (const entry of detectedVendorEntries) {
+    const placementKey = `${entry.key}::project::${skill.name}`;
+    const onDisk = placementsMap.get(placementKey) ?? null;
+
+    const localPlacement = onDisk
+      ? {
+          present: true,
+          skillMdSha256: onDisk.skillMdSha256,
+          filesSha256: onDisk.filesSha256,
+        }
+      : { present: false, skillMdSha256: null, filesSha256: null };
+
+    const state = computeSkillState({
+      libraryVersion: skill.version ?? null,
+      lastSyncEntry: baseline,
+      localPlacement,
+    });
+
+    placements.push({
+      vendor: entry.key,
+      scope: "project",
+      state,
+      // `localVersion` is the version that was synced (from
+      // `.last-sync`) — NOT a version pulled from on-disk
+      // frontmatter, which the spec doesn't mandate. When there's no
+      // baseline, this is null and the `state` will already be
+      // `missing`, so the field is honest about what we know.
+      localVersion: baseline?.version ?? null,
+    });
   }
-  if (process.stdout.columns && process.stdout.columns > 0) {
-    return process.stdout.columns;
+
+  const state = rollupState(placements.map((p) => p.state));
+
+  return { ...skill, state, placements };
+}
+
+/**
+ * Reject a `.last-sync` entry that's missing required string fields.
+ * A tampered or partially-written entry returns null, which
+ * `computeSkillState` treats as "no baseline → missing" — the
+ * conservative verdict for cache state we can't trust.
+ */
+function validateBaselineShape(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  if (
+    typeof entry.version !== "string" ||
+    typeof entry.skillMdSha256 !== "string" ||
+    typeof entry.filesSha256 !== "string"
+  ) {
+    return null;
   }
-  return 100;
+  return entry;
 }
 
+// ── JSON formatter ─────────────────────────────────────────────────────
+
 /**
- * Strip file content and reduce to the JSON shape that scripts care
- * about. Kept stable as a public-ish contract for `--json` consumers.
+ * Pipe-friendly bare array, additive on top of the #679 shape.
+ * Existing scripts that read `[0].owner`, etc. keep working. New
+ * fields: `state` (rollup) and `placements[]` (per-vendor truth).
+ *
+ * The footer never appears in JSON — `list --json` is consumed by
+ * scripts, and the ETag-state footer is a human-only signal.
  */
-function formatJson(skills) {
-  return skills
+function formatJson(augmented) {
+  return augmented
     .slice()
     .sort(sortByOwnerAndName)
     .map((s) => ({
@@ -98,17 +224,34 @@ function formatJson(skills) {
       description: s.description,
       updatedAt: s.updatedAt,
       filesIncomplete: s.filesIncomplete ?? false,
+      state: s.state,
+      placements: s.placements,
     }));
 }
 
-function printTable(skills, out) {
-  const sorted = skills.slice().sort(sortByOwnerAndName);
+// ── Human-output rendering ─────────────────────────────────────────────
+
+function printTable(augmented, detected, out) {
+  const useGlyphs = canUseGlyphs(out);
+
+  // "Detected:" line uses displayName for polish. Empty when no
+  // vendors detected; that situation also produces all-`missing`
+  // states, which the footer covers.
+  if (detected.length > 0) {
+    const detectedLabel = detected
+      .map((d) => `${d.displayName} (project)`)
+      .join(", ");
+    out.write(`\n  Detected: ${detectedLabel}\n`);
+  } else {
+    out.write(
+      "\n  No agents detected in this project — drift cannot be reported.\n",
+    );
+  }
+
+  const sorted = augmented.slice().sort(sortByOwnerAndName);
 
-  // cli-table3 supports word wrapping but we manually truncate
-  // descriptions so the table stays readable on standard 80-col
-  // terminals. The full description is available via --json.
   const table = new Table({
-    head: ["Skill", "Version", "Updated", "Description"],
+    head: ["Skill", "Library", "Local", "Updated", "Description"],
     colWidths: computeColWidths(streamColumns(out)),
     wordWrap: true,
     style: { head: ["bold"] },
@@ -118,26 +261,156 @@ function printTable(skills, out) {
     table.push([
       formatIdentifier(s),
       s.version || "—",
+      renderLocalCell(s.state, useGlyphs),
       formatRelativeDate(s.updatedAt),
       truncate(s.description || "", 60),
     ]);
   }
 
   out.write("\n" + table.toString() + "\n\n");
-  out.write(`  ${sorted.length} skill${sorted.length === 1 ? "" : "s"} in your library.\n\n`);
+
+  const driftCount = sorted.filter((s) => s.state !== SKILL_STATE.CURRENT).length;
+  if (driftCount === 0) {
+    out.write(
+      `  ${sorted.length} skill${sorted.length === 1 ? "" : "s"} in your library.\n`,
+    );
+  } else {
+    out.write(
+      `  ${sorted.length} skill${sorted.length === 1 ? "" : "s"} in your library. ` +
+        `${driftCount} need${driftCount === 1 ? "s" : ""} attention.\n`,
+    );
+  }
+}
+
+/**
+ * Library footer — answers "is my local copy in sync with the
+ * registry's manifest right now?" Distinct from per-row drift,
+ * which answers "is each individual skill's on-disk content
+ * current?"
+ *
+ * Four cases — order matters for the "least confusing precedence":
+ *
+ *   - No `.last-sync` at all → "no sync history." The user has
+ *     never run `update`; per-row drift is all `missing` anyway.
+ *     A clear "you need to run update" line is the right message.
+ *
+ *   - ETag matches AND every skill is current → fully in sync.
+ *     The reassuring case.
+ *
+ *   - ETag matches BUT some rows show drift → library hasn't
+ *     changed but local placements have. User ran update at some
+ *     point but then either edited files or has missing
+ *     placements. "Library in sync, run update to refresh"
+ *     reflects this without lying about what's wrong.
+ *
+ *   - ETag differs → library has new content since last sync.
+ *     "Library has changed, run update."
+ *
+ * The footer NEVER appears in `--json` output (caller already
+ * handles that in `runList`).
+ */
+function printFooter(augmented, libraryEtag, lastSync, out, useGlyphs) {
+  if (augmented.length === 0) return; // Empty-library branch already wrote its own message.
+
+  // Match the renderLocalCell glyph/ASCII policy. Pre-#1555 the footer
+  // used Unicode unconditionally even when the table fell back to
+  // ASCII for non-TTY / NO_COLOR. Inconsistency made piped output
+  // half-styled.
+  const ok = useGlyphs ? "✓" : "[ok]";
+  const warn = useGlyphs ? "⚠" : "[!]";
+
+  const driftCount = augmented.filter((s) => s.state !== SKILL_STATE.CURRENT).length;
+
+  if (!lastSync || !lastSync.etag) {
+    out.write(
+      "\n  No sync history on this machine — run `skillrepo update` to fetch your skills.\n\n",
+    );
+    return;
+  }
+
+  const etagMatches =
+    typeof libraryEtag === "string" && libraryEtag !== "" && libraryEtag === lastSync.etag;
+
+  if (etagMatches && driftCount === 0) {
+    out.write(`\n  ${ok} library in sync — local skills up to date.\n\n`);
+    return;
+  }
+
+  if (etagMatches && driftCount > 0) {
+    out.write(
+      `\n  ${warn} library in sync — but ${driftCount} skill${
+        driftCount === 1 ? "" : "s"
+      } show${driftCount === 1 ? "s" : ""} local drift.\n` +
+        "    Run `skillrepo update` to refresh.\n\n",
+    );
+    return;
+  }
+
+  // ETag differs (or one side is missing the etag — treat as differs,
+  // since we can't claim sync).
+  out.write(
+    `\n  ${warn} library has changed since last sync — run \`skillrepo update\`.\n\n`,
+  );
+}
+
+// ── Rendering helpers ──────────────────────────────────────────────────
+
+/** Glyphs vs ASCII tokens, per NO_COLOR / non-TTY. */
+function canUseGlyphs(stream) {
+  if (process.env.NO_COLOR) return false;
+  // `isTTY` is undefined on capture streams; treat as "no TTY → ASCII"
+  // since CI and pipe consumers would otherwise see escape codes /
+  // glyphs they can't render uniformly.
+  return stream && stream.isTTY === true;
+}
+
+function renderLocalCell(state, useGlyphs) {
+  switch (state) {
+    case SKILL_STATE.CURRENT:
+      return useGlyphs ? "✓" : "OK";
+    case SKILL_STATE.STALE:
+      return useGlyphs ? "⚠ stale" : "STALE";
+    case SKILL_STATE.MISSING:
+      return useGlyphs ? "✗ miss" : "MISS";
+    case SKILL_STATE.EDITED:
+      return useGlyphs ? "✎ edit" : "EDIT";
+    default:
+      return useGlyphs ? "?" : "?";
+  }
+}
+
+/**
+ * Read the column width from the active output stream, falling back
+ * to process.stdout's TTY column count if the injected stream
+ * doesn't carry one (e.g., a test capture stream), then to a 100-col
+ * default for non-TTY contexts.
+ */
+function streamColumns(out) {
+  if (out && typeof out.columns === "number" && out.columns > 0) {
+    return out.columns;
+  }
+  if (process.stdout.columns && process.stdout.columns > 0) {
+    return process.stdout.columns;
+  }
+  return 100;
 }
 
 function computeColWidths(terminalColumns) {
-  // Cap at 120 so the table doesn't get unreadably wide on
-  // ultra-wide terminals; floor at 100 so the description still has
-  // room when the terminal is narrower than typical.
+  // Cap at 120 so the table doesn't get unreadably wide on ultra-
+  // wide terminals; floor at 100 so the description still has room.
+  // The Local column is fixed-width (10 chars — biggest glyph cell
+  // is "✎ edit" plus padding).
   const total = terminalColumns > 60 ? Math.min(terminalColumns, 120) : 100;
-  // Skill ~30, version ~10, updated ~14, description gets the rest
-  const skillCol = 32;
-  const versionCol = 12;
-  const updatedCol = 14;
-  const descCol = Math.max(20, total - skillCol - versionCol - updatedCol - 6); // -6 for borders
-  return [skillCol, versionCol, updatedCol, descCol];
+  const skillCol = 30;
+  const libraryCol = 10;
+  const localCol = 10;
+  const updatedCol = 12;
+  // -8 accounts for the 6 between-column borders
+  const descCol = Math.max(
+    20,
+    total - skillCol - libraryCol - localCol - updatedCol - 8,
+  );
+  return [skillCol, libraryCol, localCol, updatedCol, descCol];
 }
 
 function truncate(s, n) {
@@ -164,7 +437,6 @@ function formatRelativeDate(iso) {
   if (days < 7) return `${days}d ago`;
   const weeks = Math.floor(days / 7);
   if (weeks < 26) return `${weeks}w ago`;
-  // Older than ~6 months: fall back to a date
   return new Date(iso).toISOString().slice(0, 10);
 }