skillshelf 0.2.0 → 0.3.0

package/src/commands/retag.ts

@@ -0,0 +1,58 @@
+// `skl retag <old-domain> <new-domain>` — deterministically rename a domain across
+// the WHOLE library taxonomy (every skill tagged <old> becomes <new>). This is the
+// pure rename the AI `infer` pass can't promise (it re-reasons every tag); retag
+// touches nothing but the named domain. Fixes a domain typo in one pass instead of a
+// hand-edit of taxonomy.json or a silently-failing `sed` loop over frontmatter.
+//
+//   skl retag <old-domain> <new-domain> [--json]
+
+import type { Ctx } from "../types.ts";
+import { renameDomainAcrossLibrary } from "../core/taxonomy.ts";
+import { reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "retag",
+  summary: "Rename a domain across the whole library taxonomy (deterministic)",
+  usage: "skl retag <old-domain> <new-domain> [--json]",
+} as const;
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  const unknownFlag = argv.find((a) => a.startsWith("--") && a !== "--json");
+  if (unknownFlag) {
+    ctx.error(`skl retag: unknown argument: ${unknownFlag}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const [oldDomain, newDomain] = positional;
+  if (!oldDomain || !newDomain) {
+    ctx.error("skl retag: an <old-domain> and a <new-domain> are required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (!SLUG_RE.test(newDomain)) {
+    ctx.error(`skl retag: invalid domain "${newDomain}" — use lowercase letters, digits, and hyphens`);
+    return 1;
+  }
+
+  try {
+    const changed = await renameDomainAcrossLibrary(ctx.libraryPath, oldDomain, newDomain);
+    if (changed.length > 0) await reindexLibrary(ctx.libraryPath);
+
+    if (json) {
+      ctx.json({ ok: true, from: oldDomain, to: newDomain, changed });
+    } else if (changed.length === 0) {
+      ctx.log(`No skills tagged '${oldDomain}' in the taxonomy — nothing to rename.`);
+    } else {
+      ctx.log(`retagged '${oldDomain}' -> '${newDomain}' across ${changed.length} skill(s):`);
+      for (const n of changed) ctx.log(`  ${n}`);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl retag: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/retire.ts

@@ -0,0 +1,39 @@
+// `skl retire <name>` — soft-delete a skill into <library>/_retired/<name>/. The
+// read layer already renders retired skills (struck-through in INDEX.md, "(retired)"
+// in `ls --all`, excluded from bundles/deploys) but had no WRITE primitive to enter
+// that state — forcing a hand `mkdir _retired && mv`. This is the reversible first
+// step of the removal lifecycle (retire -> optionally `rm`); undo with `skl unretire`.
+//
+//   skl retire <name> [--json]
+
+import type { Ctx } from "../types.ts";
+import { retireSkill, reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "retire",
+  summary: "Soft-delete a skill into library/_retired/ (reversible; excluded from deploys)",
+  usage: "skl retire <name> [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const name = argv.find((a) => !a.startsWith("--"));
+  if (!name) {
+    ctx.error("skl retire: a <name> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  try {
+    const dest = await retireSkill(ctx.libraryPath, name);
+    await reindexLibrary(ctx.libraryPath);
+    if (json) ctx.json({ ok: true, name, retiredTo: dest });
+    else {
+      ctx.log(`retired ${name} -> _retired/${name}`);
+      ctx.log("  (excluded from bundles/deploys; restore with `skl unretire`, purge with `skl rm`)");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl retire: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/rm.test.ts

@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm as fsRm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as rmRun } from "./rm.ts";
+import { run as retireRun } from "./retire.ts";
+import { run as unretireRun } from "./unretire.ts";
+import { loadLibrary } from "../core/library.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const errors: string[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    loadLibrary: () => loadLibrary(libraryPath),
+    log: () => {},
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json, errors };
+}
+
+async function writeSkill(library: string, name: string) {
+  const dir = join(library, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${name}\n---\n\nbody\n`);
+  return dir;
+}
+
+describe("skl rm/retire/unretire — removal lifecycle (friction #1)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-rm-")));
+    library = join(tmp, "library");
+    await writeSkill(library, "alpha");
+    await writeFile(
+      join(library, "taxonomy.json"),
+      JSON.stringify({ version: 1, skills: { alpha: ["bio"] } }),
+    );
+  });
+  afterEach(async () => {
+    await fsRm(tmp, { recursive: true, force: true });
+  });
+
+  test("rm refuses a live OWNED skill without --force", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await rmRun(["alpha"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("live skill");
+    expect(existsSync(join(library, "alpha"))).toBe(true); // untouched
+  });
+
+  test("rm --dry-run previews without deleting", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await rmRun(["alpha", "--force", "--dry-run", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { dryRun: boolean }).dryRun).toBe(true);
+    expect(existsSync(join(library, "alpha"))).toBe(true); // still there
+  });
+
+  test("retire -> rm purges and drops taxonomy", async () => {
+    await retireRun(["alpha"], makeCtx(library).ctx);
+    expect(existsSync(join(library, "_retired", "alpha"))).toBe(true);
+
+    const { ctx, json } = makeCtx(library);
+    const code = await rmRun(["alpha", "--json"], ctx); // retired -> no --force needed
+    expect(code).toBe(0);
+    expect((json[0] as { taxonomyDropped: boolean }).taxonomyDropped).toBe(true);
+    expect(existsSync(join(library, "_retired", "alpha"))).toBe(false);
+    // _retired pruned when empty
+    expect(existsSync(join(library, "_retired"))).toBe(false);
+  });
+
+  test("retire then unretire round-trips", async () => {
+    await retireRun(["alpha"], makeCtx(library).ctx);
+    const { ctx } = makeCtx(library);
+    const code = await unretireRun(["alpha"], ctx);
+    expect(code).toBe(0);
+    expect(existsSync(join(library, "alpha"))).toBe(true);
+    expect(existsSync(join(library, "_retired", "alpha"))).toBe(false);
+  });
+
+  test("rm a LINKED entry without --force is a safe unlink (dev repo untouched)", async () => {
+    const dev = join(tmp, "dev", "linkedskill");
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: linkedskill\n---\n\nbody\n");
+    await symlink(dev, join(library, "linkedskill"));
+
+    const { ctx, json } = makeCtx(library);
+    const code = await rmRun(["linkedskill", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { wasLink: boolean }).wasLink).toBe(true);
+    expect(existsSync(join(library, "linkedskill"))).toBe(false); // symlink gone
+    expect(existsSync(join(dev, "SKILL.md"))).toBe(true); // dev repo intact
+  });
+
+  test("rm a missing skill errors", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await rmRun(["ghost", "--force"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not in the library");
+  });
+
+  test("rm refuses a path-traversal name (no escape outside the library)", async () => {
+    // a sibling dir outside the library that must NOT be deletable via `../`
+    const victim = join(tmp, "victim");
+    await mkdir(victim, { recursive: true });
+    await writeFile(join(victim, "keep.txt"), "x");
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await rmRun(["../victim", "--force"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("path separators");
+    expect(existsSync(join(victim, "keep.txt"))).toBe(true); // untouched
+  });
+
+  test("rm of a skill present in BOTH active and _retired still refuses the live copy without --force", async () => {
+    // manufacture the twin state (active alpha already exists; add a retired twin)
+    await mkdir(join(library, "_retired", "alpha"), { recursive: true });
+    await writeFile(join(library, "_retired", "alpha", "SKILL.md"), "---\nname: alpha\n---\n\nold\n");
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await rmRun(["alpha"], ctx); // no --force
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("live skill");
+    expect(existsSync(join(library, "alpha"))).toBe(true); // active copy survives
+  });
+});

package/src/commands/rm.ts

@@ -0,0 +1,107 @@
+// `skl rm <name>` — delete a skill from the library entirely: remove its dir (or, for
+// a LINKED entry, just the symlink — the dev repo it points at is never touched, so
+// this doubles as `unlink`) AND drop its taxonomy + lockfile entries, then re-index.
+// Before this, the ONLY delete path was an unguarded `rm -rf` against the library —
+// no safety rail for the most destructive lifecycle step.
+//
+//   skl rm <name> [--force] [--dry-run] [--json]
+//
+// Safety (mirrors `link --at` refuse-by-default + named escape hatch): a LIVE (active,
+// non-retired) skill is refused without --force — retire it first (reversible) or pass
+// --force to hard-purge. A retired skill is already in the reversible holding area, so
+// it purges without --force. --dry-run previews exactly what would be removed.
+
+import type { Ctx } from "../types.ts";
+import { locateEntry, removeSkill, reindexLibrary } from "../core/lifecycle.ts";
+import { readTaxonomy } from "../core/taxonomy.ts";
+import { readLockfile } from "../core/provenance.ts";
+
+export const meta = {
+  name: "rm",
+  summary: "Delete a skill from the library (dir/symlink + taxonomy + lock), re-index",
+  usage: "skl rm <name> [--force] [--dry-run] [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const force = argv.includes("--force");
+  const dryRun = argv.includes("--dry-run");
+  const unknown = argv.find(
+    (a) => a.startsWith("--") && !["--json", "--force", "--dry-run"].includes(a),
+  );
+  if (unknown) {
+    ctx.error(`skl rm: unknown argument: ${unknown}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const name = argv.find((a) => !a.startsWith("--"));
+  if (!name) {
+    ctx.error("skl rm: a <name> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+
+  try {
+    const loc = locateEntry(ctx.libraryPath, name);
+    if (!loc.path) {
+      ctx.error(`skl rm: '${name}' is not in the library`);
+      return 1;
+    }
+    // Refuse only a live OWNED skill unless forced — that destroys real bytes. A
+    // LINKED entry is just a symlink: removing it loses nothing (the dev repo stays
+    // canonical), so `skl rm <linked>` is the safe `unlink` and needs no --force. A
+    // purely-retired skill is already in the reversible holding area, so it purges
+    // freely. NOTE: gate on `loc.active` itself (the resolved path IS the active copy
+    // when active), NOT on the absence of a retired twin — a skill present in BOTH
+    // active and _retired still resolves `path` to the active copy, so a `!loc.retired`
+    // term would wrongly drop the guard and delete the live copy without --force.
+    if (loc.active && !loc.isLink && !force) {
+      if (json) {
+        ctx.json({ ok: false, name, refused: true, reason: "live-owned-needs-force" });
+      } else {
+        ctx.error(`skl rm: '${name}' is a live skill — this destroys real bytes.`);
+        ctx.error("Retire it first (reversible):  skl retire " + name);
+        ctx.error("Or hard-purge now:             skl rm " + name + " --force");
+      }
+      return 1;
+    }
+
+    // Preview what would be dropped (for --dry-run and richer reporting).
+    const tax = await readTaxonomy(ctx.libraryPath);
+    const lock = await readLockfile(ctx.libraryPath);
+    const plan = {
+      name,
+      path: loc.path,
+      mode: loc.isLink ? ("linked" as const) : ("owned" as const),
+      wasRetired: loc.retired && !loc.active,
+      taxonomyEntry: name in tax.skills,
+      lockEntry: name in lock.entries,
+    };
+
+    if (dryRun) {
+      if (json) ctx.json({ ok: true, dryRun: true, plan });
+      else {
+        ctx.log(`DRY RUN — would remove '${name}':`);
+        ctx.log(`  path:     ${plan.path}${plan.mode === "linked" ? " (symlink only — dev repo untouched)" : ""}`);
+        ctx.log(`  taxonomy: ${plan.taxonomyEntry ? "drop entry" : "none"}`);
+        ctx.log(`  lockfile: ${plan.lockEntry ? "drop entry" : "none"}`);
+        ctx.log("Re-run without --dry-run to apply.");
+      }
+      return 0;
+    }
+
+    const result = await removeSkill(ctx.libraryPath, name);
+    await reindexLibrary(ctx.libraryPath);
+    if (json) {
+      ctx.json({ ok: true, ...result });
+    } else {
+      ctx.log(`removed ${name}${result.wasLink ? " (symlink only — dev repo untouched)" : ""}`);
+      if (result.taxonomyDropped) ctx.log("  dropped taxonomy entry");
+      if (result.lockDropped) ctx.log("  dropped lockfile entry");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl rm: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/roots.ts

@@ -0,0 +1,41 @@
+// `skl roots` — list the persisted scan roots. A pure read of config.json, with NO
+// disk crawl (unlike `skl scan`, which crawls every root). Lets a human or agent see
+// the registered roots cheaply, and emit a minimal {"roots":[...]} for scripting
+// without piping a heavy `scan --json` through jq.
+//
+//   skl roots [--json]
+//
+// Mutate the set with `skl scan --add-root <path>` / `skl scan --remove-root <path>`.
+
+import type { Ctx } from "../types.ts";
+
+export const meta = {
+  name: "roots",
+  summary: "List the persisted scan roots (read-only; no crawl)",
+  usage: "skl roots [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const unknown = argv.find((a) => a.startsWith("-") && a !== "--json");
+  if (unknown) {
+    ctx.error(`skl roots: unknown argument: ${unknown}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+
+  const roots = ctx.roots;
+  if (json) {
+    ctx.json({ roots });
+    return 0;
+  }
+
+  if (roots.length === 0) {
+    ctx.log("No scan roots configured.");
+    ctx.log("Add one with:  skl scan --add-root <path>");
+    return 0;
+  }
+  ctx.log(`Scan roots (${roots.length}):`);
+  for (const r of roots) ctx.log(`  ${r}`);
+  return 0;
+}

package/src/commands/scan.ts

@@ -1,8 +1,10 @@
 // `skl scan [roots…]` — read-only discovery pass over scan roots.
 //
 // Crawls each root (see core/crawl.ts) and reports:
-//   - per-root candidate counts and a total
-//   - every candidate (a discovered skill — see CONTEXT.md) with its location
+//   - per-root candidate counts and a total, split into new vs already-in-library
+//   - every candidate (a discovered skill — see CONTEXT.md) with its location and
+//     an `imported` flag (already managed by the library, or symlinks into it)
+//   - the actionable list of NEW candidates (not yet imported) to feed `skl import`
 //   - duplicate / drift groups (via core/dedupe.ts) with their locations and a
 //     recommendation for the human/agent to act on
 //
@@ -21,6 +23,7 @@ import {
   findDuplicates,
   driftedGroups,
   exactDuplicateGroups,
+  genuineConflictGroups,
 } from "../core/dedupe.ts";
 import { realpathOrSelf } from "../lib/fs.ts";
 
@@ -28,17 +31,18 @@ export const meta = {
   name: "scan",
   summary: "Read-only discovery of skill candidates across roots (counts, duplicates, drift)",
   usage:
-    "skl scan [roots…] [--add-root <path>] [--json]",
+    "skl scan [roots…] [--add-root <path>] [--remove-root <path>] [--json]",
 } as const;
 
 interface Args {
   roots: string[];
   addRoot: string | null;
+  removeRoot: string | null;
   json: boolean;
 }
 
 function parseArgs(argv: string[]): { args: Args } | { error: string } {
-  const args: Args = { roots: [], addRoot: null, json: false };
+  const args: Args = { roots: [], addRoot: null, removeRoot: null, json: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
     if (a === "--json") {
@@ -50,29 +54,36 @@ function parseArgs(argv: string[]): { args: Args } | { error: string } {
     } else if (a.startsWith("--add-root=")) {
       args.addRoot = a.slice("--add-root=".length);
       if (args.addRoot === "") return { error: "--add-root requires a <path>" };
+    } else if (a === "--remove-root" || a === "--rm-root") {
+      const p = argv[++i];
+      if (!p) return { error: "--remove-root requires a <path>" };
+      args.removeRoot = p;
+    } else if (a.startsWith("--remove-root=")) {
+      args.removeRoot = a.slice("--remove-root=".length);
+      if (args.removeRoot === "") return { error: "--remove-root requires a <path>" };
+    } else if (a.startsWith("--rm-root=")) {
+      args.removeRoot = a.slice("--rm-root=".length);
+      if (args.removeRoot === "") return { error: "--remove-root requires a <path>" };
     } else if (a.startsWith("--")) {
       return { error: `unknown argument: ${a}` };
     } else {
       args.roots.push(a);
     }
   }
+  if (args.addRoot != null && args.removeRoot != null) {
+    return { error: "--add-root and --remove-root are mutually exclusive" };
+  }
   return { args };
 }
 
-/** True if a discovered skill dir lives under `root` (by realpath prefix). */
-function underRoot(skillPath: string, root: string): boolean {
-  const r = realpathOrSelf(root);
-  const p = realpathOrSelf(skillPath);
-  if (p === r) return true;
-  return p.startsWith(r.endsWith(sep) ? r : r + sep);
-}
-
-/** Attribute a discovered skill to the first matching scan root (else null). */
-function rootOf(skill: Skill, roots: string[]): string | null {
-  for (const root of roots) {
-    if (underRoot(skill.path, root)) return root;
-  }
-  return null;
+/**
+ * Attribute a discovered skill to the scan root it was crawled under. crawl records
+ * this at discovery time (`Skill.discoveredRoot`); we must NOT re-derive it via
+ * realpath, because a skill reached through a symlink resolves OUTSIDE its declared
+ * root and would be mis-attributed to no root (the per-root undercount bug).
+ */
+function rootOf(skill: Skill): string | null {
+  return skill.discoveredRoot ?? null;
 }
 
 interface CandidateView {
@@ -82,16 +93,34 @@ interface CandidateView {
   root: string | null;
   retired: boolean;
   mirror: boolean;
+  /** true if this candidate already lives in (or symlinks into) the library */
+  imported: boolean;
 }
 
-function toCandidate(s: Skill, roots: string[]): CandidateView {
+function toCandidate(s: Skill, imported: boolean): CandidateView {
   return {
     name: s.name,
     description: s.description,
     path: s.path,
-    root: rootOf(s, roots),
+    root: rootOf(s),
     retired: s.retired,
     mirror: s.mirrorOf != null,
+    imported,
+  };
+}
+
+/**
+ * Decide whether a discovered candidate is already managed by the library.
+ * A candidate counts as imported if a library skill shares its name (the usual
+ * case after `skl import`, including the symlink-back left at the old path) OR
+ * its real path resolves inside the library tree (a symlink pointing into it).
+ */
+function makeIsImported(libNames: Set<string>, libraryRealPath: string) {
+  const prefix = libraryRealPath.endsWith(sep) ? libraryRealPath : libraryRealPath + sep;
+  return (s: Skill): boolean => {
+    if (libNames.has(s.name)) return true;
+    const real = realpathOrSelf(s.path);
+    return real === libraryRealPath || real.startsWith(prefix);
   };
 }
 
@@ -170,6 +199,20 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       return 0;
     }
 
+    // --remove-root: de-register (inverse of --add-root), then report. Idempotent —
+    // a not-registered path reports removed:false and is not an error.
+    if (args.removeRoot != null) {
+      const { roots, removed } = await ctx.removeRoot(args.removeRoot);
+      if (args.json) {
+        ctx.json({ removed, target: args.removeRoot, roots });
+        return 0;
+      }
+      ctx.log(removed ? `Removed root: ${args.removeRoot}` : `Not a registered root: ${args.removeRoot}`);
+      ctx.log(`Roots (${roots.length}):`);
+      for (const r of roots) ctx.log(`  ${r}`);
+      return 0;
+    }
+
     // Roots: explicit args win; else fall back to configured roots.
     const roots = args.roots.length > 0 ? args.roots : ctx.roots;
     if (roots.length === 0) {
@@ -180,17 +223,45 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     // need every copy in one set.
     const { skills, dedupedRoots } = await crawl(roots);
 
+    // Which candidates are already in the library? Compare against the live
+    // library so scan can flag what's NEW (worth importing) vs already managed.
+    const lib = await ctx.loadLibrary();
+    const isImported = makeIsImported(
+      new Set(lib.map((s) => s.name)),
+      realpathOrSelf(ctx.libraryPath),
+    );
+
     // Per-root counts (a candidate is a discovered skill; mirrors counted too so
-    // the count matches what's physically on disk under each root).
+    // the count matches what's physically on disk under each root). `new` =
+    // candidates not yet in the library.
     const perRoot = new Map<string, number>();
-    for (const r of roots) perRoot.set(r, 0);
+    const perRootNew = new Map<string, number>();
+    for (const r of roots) {
+      perRoot.set(r, 0);
+      perRootNew.set(r, 0);
+    }
     for (const s of skills) {
-      const r = rootOf(s, roots);
-      if (r != null) perRoot.set(r, (perRoot.get(r) ?? 0) + 1);
+      const r = rootOf(s);
+      if (r != null) {
+        perRoot.set(r, (perRoot.get(r) ?? 0) + 1);
+        if (!isImported(s)) perRootNew.set(r, (perRootNew.get(r) ?? 0) + 1);
+      }
     }
 
-    const candidates = skills.map((s) => toCandidate(s, roots));
-    const allGroups = findDuplicates(skills);
+    const candidates = skills.map((s) => toCandidate(s, isImported(s)));
+    // New candidates worth importing: not yet in the library, de-duped by name
+    // (drop bridge mirrors and aliased copies), sorted for a stable report.
+    const newByName = new Map<string, CandidateView>();
+    for (const c of candidates) {
+      if (c.imported || c.mirror) continue;
+      if (!newByName.has(c.name)) newByName.set(c.name, c);
+    }
+    const newCandidates = [...newByName.values()].sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    );
+    // Surface only genuine conflicts: faithful `.agents`/`.claude` bridge mirrors are
+    // a known, intended relationship, not a decision the user has to resolve.
+    const allGroups = genuineConflictGroups(findDuplicates(skills));
     const drifted = driftedGroups(allGroups);
     const exact = exactDuplicateGroups(allGroups);
     const reported = [...drifted, ...exact].sort((a, b) =>
@@ -204,13 +275,19 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         totals: {
           roots: roots.length,
           candidates: candidates.length,
+          new: newCandidates.length,
           duplicateGroups: groupViews.length,
           driftGroups: drifted.length,
           exactDuplicateGroups: exact.length,
         },
-        perRoot: roots.map((r) => ({ root: r, candidates: perRoot.get(r) ?? 0 })),
+        perRoot: roots.map((r) => ({
+          root: r,
+          candidates: perRoot.get(r) ?? 0,
+          new: perRootNew.get(r) ?? 0,
+        })),
         dedupedRoots,
         candidates,
+        newCandidates,
         duplicateGroups: groupViews,
       });
       return 0;
@@ -219,16 +296,31 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     // --- Human report ----------------------------------------------------
     ctx.log(`Scanned ${roots.length} root${roots.length === 1 ? "" : "s"}:`);
     for (const r of roots) {
-      ctx.log(`  ${r} — ${perRoot.get(r) ?? 0} candidate${(perRoot.get(r) ?? 0) === 1 ? "" : "s"}`);
+      const c = perRoot.get(r) ?? 0;
+      const n = perRootNew.get(r) ?? 0;
+      const breakdown = c === 0 ? "" : n === 0 ? " (all in library)" : ` (${n} new, ${c - n} in library)`;
+      ctx.log(`  ${r} — ${c} candidate${c === 1 ? "" : "s"}${breakdown}`);
     }
     if (dedupedRoots.length) {
       ctx.log(`  (skipped ${dedupedRoots.length} aliased root${dedupedRoots.length === 1 ? "" : "s"}: ${dedupedRoots.join(", ")})`);
     }
     ctx.log("");
-    ctx.log(`Total candidates: ${candidates.length}`);
+    ctx.log(`Total candidates: ${candidates.length} (${newCandidates.length} new, not yet in library)`);
+
+    // New candidates: the actionable list — what you'd `skl import` next.
+    if (newCandidates.length > 0) {
+      ctx.log("");
+      ctx.log(`New (not in library) — ${newCandidates.length}:`);
+      for (const c of newCandidates) {
+        ctx.log(`  ${c.name}${c.retired ? " [retired]" : ""}`);
+        ctx.log(`    ${c.path}`);
+      }
+      ctx.log("");
+      ctx.log("Import one with:  skl import <name> --from <path>");
+    }
 
     if (groupViews.length === 0) {
-      ctx.log("No duplicates or drift detected.");
+      if (newCandidates.length === 0) ctx.log("No duplicates or drift detected.");
       return 0;
     }
 

package/src/commands/show.ts

@@ -4,7 +4,7 @@
 // progressive disclosure: cheap by default, deep on demand.
 
 import type { Ctx, Skill } from "../types.ts";
-import { findByName } from "../core/library.ts";
+import { findByName, entryModeInfo } from "../core/library.ts";
 import { parseFrontmatter } from "../lib/frontmatter.ts";
 
 export const meta = {
@@ -40,6 +40,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     const body = await bodyOf(skill);
 
     if (json) {
+      const { mode, linkTarget } = entryModeInfo(ctx.libraryPath, skill.name);
       ctx.json({
         name: skill.name,
         description: skill.description,
@@ -51,6 +52,8 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         refFiles: skill.refFiles,
         retired: skill.retired,
         source: skill.source,
+        mode,
+        linkTarget,
       });
       return 0;
     }