skillshelf 0.2.0 → 0.3.0

package/src/commands/use.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as useRun } from "./use.ts";
+import { run as dropRun } from "./drop.ts";
+import { loadLibrary } from "../core/library.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    loadLibrary: () => loadLibrary(libraryPath),
+    log: () => {},
+    error: () => {},
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json };
+}
+
+async function writeSkill(library: string, name: string, domain: string) {
+  const dir = join(library, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${name}\ndomains: [${domain}]\n---\n\nbody\n`);
+}
+
+describe("skl use/drop — single-skill deploy (friction #2)", () => {
+  let tmp: string;
+  let library: string;
+  let project: string;
+  let prevCwd: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-use-")));
+    library = join(tmp, "library");
+    project = join(tmp, "project");
+    await mkdir(project, { recursive: true });
+    await writeSkill(library, "alpha", "bio");
+    await writeSkill(library, "beta", "bio");
+    prevCwd = process.cwd();
+    process.chdir(project);
+  });
+  afterEach(async () => {
+    process.chdir(prevCwd);
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("`use <skill>` deploys exactly one skill (kind: skill)", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await useRun(["alpha", "--json"], ctx);
+    expect(code).toBe(0);
+    const out = json[0] as { kind: string; linked: Array<{ name: string; status: string }> };
+    expect(out.kind).toBe("skill");
+    expect(out.linked).toHaveLength(1);
+    expect(out.linked[0]!.name).toBe("alpha");
+  });
+
+  test("`use <bundle>` still resolves the whole tag query (kind: bundle)", async () => {
+    const { ctx, json } = makeCtx(library);
+    await useRun(["bio", "--json"], ctx);
+    const out = json[0] as { kind: string; linked: unknown[] };
+    expect(out.kind).toBe("bundle");
+    expect(out.linked).toHaveLength(2);
+  });
+
+  test("a skill name shadows bundle resolution (skill-first)", async () => {
+    // name a skill the same as no domain — exact-name match wins
+    const { ctx, json } = makeCtx(library);
+    await useRun(["beta", "--json"], ctx);
+    expect((json[0] as { kind: string }).kind).toBe("skill");
+  });
+
+  test("`drop <skill>` undoes `use <skill>` symmetrically", async () => {
+    const { ctx } = makeCtx(library);
+    await useRun(["alpha", "--json"], ctx);
+    const { ctx: ctx2, json } = makeCtx(library);
+    const code = await dropRun(["alpha", "--json"], ctx2);
+    expect(code).toBe(0);
+    const out = json[0] as { results: Array<{ status: string }>; removed: number };
+    expect(out.removed).toBe(1);
+    expect(out.results[0]!.status).toBe("removed");
+  });
+
+  test("unknown name is a clean empty-bundle error, not a crash", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await useRun(["does-not-exist", "--json"], ctx);
+    expect(code).toBe(1);
+    expect((json[0] as { error: string }).error).toBe("empty-bundle");
+  });
+});

package/src/commands/use.ts

@@ -3,15 +3,17 @@
 // links without error. Reports what was linked (and is JSON-parseable on --json).
 
 import { join } from "node:path";
-import type { Ctx } from "../types.ts";
+import { mkdir } from "node:fs/promises";
+import type { Ctx, Skill } from "../types.ts";
 import { resolveBundle } from "../core/bundle.ts";
-import { activeSkills } from "../core/library.ts";
+import { activeSkills, findByName } from "../core/library.ts";
+import { parseDeployTarget } from "../core/agents.ts";
 import { safeSymlink, isSymlink, realpathOrSelf, realpathOrSelfAsync } from "../lib/fs.ts";
 
 export const meta = {
   name: "use",
-  summary: "Symlink a bundle's skills into ./.claude/skills/ (hot-loads)",
-  usage: "skl use <bundle> [--json]",
+  summary: "Symlink a bundle (or skill) into an agent's skills dir (default: ./.claude/skills/)",
+  usage: "skl use <bundle|skill> [--agent <id>] [--global | --project <name>] [--json]",
 } as const;
 
 interface LinkResult {
@@ -21,15 +23,17 @@ interface LinkResult {
   status: "linked" | "already" | "conflict";
 }
 
-/** Project skills dir for the cwd. */
-function projectSkillsDir(): string {
-  return join(process.cwd(), ".claude", "skills");
-}
-
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   try {
     const json = argv.includes("--json");
-    const bundleName = argv.find((a) => !a.startsWith("-"));
+    const parsed = parseDeployTarget(argv);
+    if ("error" in parsed) {
+      ctx.error(`skl use: ${parsed.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const { positionals, target } = parsed;
+    const bundleName = positionals[0];
 
     if (!bundleName) {
       ctx.error("usage: " + meta.usage);
@@ -37,53 +41,72 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     }
 
     const skills = await ctx.loadLibrary();
-    const bundle = await resolveBundle(activeSkills(skills), bundleName);
+    const active = activeSkills(skills);
+
+    // Resolve the arg as a SINGLE SKILL first (exact name), then fall back to a
+    // bundle (a domain tag query). This makes `skl use <skill>` a first-class
+    // single-skill deploy instead of erroring 'empty-bundle' and forcing a hand
+    // `ln -s` — the exact manual symlink skillshelf exists to eliminate.
+    let resolved: { name: string; kind: "skill" | "bundle"; skills: Skill[] };
+    const single = findByName(active, bundleName);
+    if (single) {
+      resolved = { name: single.name, kind: "skill", skills: [single] };
+    } else {
+      const bundle = await resolveBundle(active, bundleName);
+      resolved = { name: bundle.name, kind: "bundle", skills: bundle.skills };
+    }
 
-    if (bundle.skills.length === 0) {
+    if (resolved.skills.length === 0) {
       if (json) {
-        ctx.json({ bundle: bundleName, linked: [], skillsDir: projectSkillsDir(), error: "empty-bundle" });
+        ctx.json({ bundle: bundleName, kind: "bundle", linked: [], skillsDir: target.dir, error: "empty-bundle" });
       } else {
-        ctx.error(`No active skills match bundle '${bundleName}'.`);
+        ctx.error(`No active skill or bundle matches '${bundleName}'.`);
       }
       return 1;
     }
 
-    const skillsDir = projectSkillsDir();
+    const bundle = { name: resolved.name, skills: resolved.skills };
+    const skillsDir = target.dir;
+    // The target agent's skills dir may not exist yet (e.g. a fresh ~/.codex/skills).
+    await mkdir(skillsDir, { recursive: true });
     const results: LinkResult[] = [];
 
     for (const s of bundle.skills) {
       const link = join(skillsDir, s.name);
-      const target = s.path;
+      const skillPath = s.path;
       let status: LinkResult["status"] = "linked";
 
       // Determine prior state for accurate reporting before we touch it.
       if (isSymlink(link)) {
         const cur = realpathOrSelf(link);
-        const want = await realpathOrSelfAsync(target);
+        const want = await realpathOrSelfAsync(skillPath);
         if (cur === want) status = "already";
       } else if (await pathTakenNonLink(link)) {
         // A real (non-symlink) file/dir occupies the slot — don't clobber it.
-        results.push({ name: s.name, target, link, status: "conflict" });
+        results.push({ name: s.name, target: skillPath, link, status: "conflict" });
         continue;
       }
 
-      await safeSymlink(target, link);
-      results.push({ name: s.name, target, link, status });
+      await safeSymlink(skillPath, link);
+      results.push({ name: s.name, target: skillPath, link, status });
     }
 
     const conflicts = results.filter((r) => r.status === "conflict");
 
     if (json) {
-      ctx.json({ bundle: bundle.name, skillsDir, linked: results });
+      ctx.json({ bundle: bundle.name, kind: resolved.kind, skillsDir, agent: target.agentId, scope: target.scope, linked: results });
     } else {
-      ctx.log(`Bundle '${bundle.name}' -> ${skillsDir}`);
+      const label = resolved.kind === "skill" ? `Skill '${bundle.name}'` : `Bundle '${bundle.name}'`;
+      ctx.log(`${label} -> ${skillsDir}`);
       for (const r of results) {
         const tag =
           r.status === "linked" ? "linked" : r.status === "already" ? "ok" : "SKIP (real file present)";
         ctx.log(`  ${r.name}  [${tag}]`);
       }
       ctx.log("");
-      ctx.log("Reminder: add '.claude/skills/' to this project's .gitignore so these symlinks aren't committed.");
+      if (target.scope !== "Global") {
+        ctx.log(`Reminder: add '${target.agentId === "claude" ? ".claude" : "." + target.agentId}/skills/' to this project's .gitignore so these symlinks aren't committed.`);
+      }
     }
 
     return conflicts.length > 0 ? 1 : 0;

package/src/commands/where.ts

@@ -0,0 +1,232 @@
+// `skl where [name]` — the deployment map: where is each library skill actually
+// deployed across every surface tools read skills from, and what's a mess?
+//
+// Skillshelf's founding job: many skills × many tools (Claude Code, Codex, …) that
+// scatter copies/symlinks nobody can track. `status` only sees the cwd project;
+// `scan` is root-centric. `where` is skill-centric across all surfaces, computed
+// from reality (no stored state). It only REPORTS — it never mutates.
+//
+//   skl where              full map + a flagged "problems" section with fixes
+//   skl where <name>        one skill: every place it's deployed, classified
+//   skl where --problems    only the non-clean rows
+//   skl where --json        structured DeploymentReport
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Ctx, DeploymentSite } from "../types.ts";
+import {
+  inventoryDeployments,
+  suggestionFor,
+  remediationFor,
+  type RemediationAction,
+} from "../core/deployments.ts";
+import { knownAgentSurfacePaths } from "../core/surfaces.ts";
+import { resolveReadTarget } from "../core/agents.ts";
+import { safeSymlink, removeSymlink } from "../lib/fs.ts";
+
+export const meta = {
+  name: "where",
+  summary: "Show where each library skill is deployed across all surfaces (copies, symlinks, drift)",
+  // NB: --project is read-only on its own, but `--project <dir> --fix/--prune`
+  // WILL remediate problems found in that injected surface (intended: verify-and-fix
+  // a deploy you just made).
+  usage: "skl where [name] [--agent <id>] [--project <dir>] [--problems] [--prune | --fix] [--dry-run] [--json]",
+} as const;
+
+const HOME = homedir();
+/** Shorten an absolute path under $HOME to ~ for display. */
+function tilde(p: string): string {
+  return p === HOME ? "~" : p.startsWith(HOME + "/") ? "~" + p.slice(HOME.length) : p;
+}
+
+/** Short human label for a site's classification. */
+function labelFor(s: DeploymentSite): string {
+  switch (s.kind) {
+    case "linked":
+      return "✓ linked";
+    case "source":
+      return "✓ source";
+    case "dead":
+      return "✗ dead link";
+    case "foreign-link":
+      return "⚠ 2nd-source";
+    case "aliased":
+      return "⚠ aliased link";
+    case "copy":
+      if (!s.inLibrary) return "⚠ untracked copy";
+      return s.drift ? "⚠ drifted copy" : "⚠ redundant copy";
+  }
+}
+
+interface Args {
+  name: string | null;
+  problems: boolean;
+  prune: boolean;
+  fix: boolean;
+  dryRun: boolean;
+  json: boolean;
+}
+
+function parseArgs(argv: string[]): { args: Args } | { error: string } {
+  const args: Args = { name: null, problems: false, prune: false, fix: false, dryRun: false, json: false };
+  for (const a of argv) {
+    if (a === "--problems") args.problems = true;
+    else if (a === "--prune") args.prune = true;
+    else if (a === "--fix") args.fix = true;
+    else if (a === "--dry-run") args.dryRun = true;
+    else if (a === "--json") args.json = true;
+    else if (a.startsWith("--")) return { error: `unknown argument: ${a}` };
+    else if (args.name === null) args.name = a;
+    else return { error: `unexpected extra argument: ${a}` };
+  }
+  if (args.prune && args.fix) {
+    return { error: "--prune and --fix are mutually exclusive (--fix includes --prune's dead-link cleanup)" };
+  }
+  return { args };
+}
+
+export interface FixOutcome {
+  name: string;
+  path: string;
+  action: RemediationAction;
+  applied: boolean;
+  note: string;
+}
+
+/**
+ * Apply where's own remediation to the flagged sites and return per-site outcomes.
+ * --prune handles only dead links; --fix also dedupes content-identical copies to a
+ * symlink into the library. `manual` problems (drift / 2nd-source / untracked) are
+ * NEVER auto-resolved — they carry a real decision; we report them with the existing
+ * suggestion so the loop is closed but judgment stays with the human/agent.
+ */
+export async function remediate(
+  sites: DeploymentSite[],
+  libraryPath: string,
+  opts: { fix: boolean; dryRun: boolean },
+): Promise<FixOutcome[]> {
+  const out: FixOutcome[] = [];
+  for (const s of sites) {
+    const action = remediationFor(s);
+    if (action === "remove-dead") {
+      if (!opts.dryRun) await removeSymlink(s.path, { force: true });
+      out.push({ name: s.name, path: s.path, action, applied: !opts.dryRun, note: opts.dryRun ? "would remove dead link" : "removed dead link" });
+    } else if (action === "dedupe-copy" && opts.fix) {
+      if (!opts.dryRun) await safeSymlink(join(libraryPath, s.name), s.path, { force: true });
+      out.push({ name: s.name, path: s.path, action, applied: !opts.dryRun, note: opts.dryRun ? "would replace identical copy with a symlink into the library" : "deduped copy -> symlink into library" });
+    } else {
+      // manual (or dedupe-copy under --prune): not auto-applied.
+      out.push({ name: s.name, path: s.path, action: "manual", applied: false, note: suggestionFor(s) });
+    }
+  }
+  return out;
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  // Extract --agent/--project first (read-side targeting), then parse where's own
+  // flags from what remains.
+  const rt = resolveReadTarget(argv);
+  if ("error" in rt) {
+    ctx.error(`skl where: ${rt.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const parsed = parseArgs(rt.rest);
+  if ("error" in parsed) {
+    ctx.error(`skl where: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const { name, problems, json } = parsed.args;
+
+  try {
+    const lib = await ctx.loadLibrary();
+    // Surfaces = configured roots + the global-core target + the well-known
+    // cross-agent global skill dirs (claude, codex, …) so sprawl across agents
+    // shows up without manual `skl scan --add-root`. Plus any --project surfaces
+    // injected for THIS invocation only (verify a deploy you just made).
+    // inventoryDeployments realpath-de-duplicates and skips missing dirs.
+    const surfaces = [...ctx.roots, ctx.config.globalCoreTarget, ...knownAgentSurfacePaths(), ...rt.extraSurfaces];
+    const report = await inventoryDeployments(surfaces, ctx.libraryPath, lib);
+
+    // --- remediation (--prune / --fix) -----------------------------------
+    if (parsed.args.prune || parsed.args.fix) {
+      const targets = name !== null ? report.problems.filter((s) => s.name === name) : report.problems;
+      const outcomes = await remediate(targets, ctx.libraryPath, {
+        fix: parsed.args.fix,
+        dryRun: parsed.args.dryRun,
+      });
+      const applied = outcomes.filter((o) => o.applied).length;
+      const manual = outcomes.filter((o) => o.action === "manual");
+      if (json) {
+        ctx.json({ dryRun: parsed.args.dryRun, mode: parsed.args.fix ? "fix" : "prune", applied, outcomes });
+        return 0;
+      }
+      const verb = parsed.args.dryRun ? "Would apply" : "Applied";
+      ctx.log(`${verb} ${parsed.args.fix ? "fix" : "prune"} to ${outcomes.length} problem site(s):`);
+      for (const o of outcomes) {
+        const flag = o.action === "manual" ? "•" : parsed.args.dryRun ? "?" : "✓";
+        ctx.log(`  ${flag} ${o.name}  ${tilde(o.path)}`);
+        ctx.log(`      ${o.note}`);
+      }
+      ctx.log("");
+      ctx.log(`${applied} ${parsed.args.dryRun ? "would be " : ""}auto-fixed, ${manual.length} need a manual decision.`);
+      return 0;
+    }
+
+    // --- single skill ----------------------------------------------------
+    if (name !== null) {
+      const sites = report.sites.filter((s) => s.name === name);
+      const inLibrary = lib.some((s) => s.name === name);
+      if (json) {
+        ctx.json({ name, inLibrary, sites });
+        return 0;
+      }
+      if (sites.length === 0) {
+        ctx.log(
+          inLibrary
+            ? `${name}: in the library, but not deployed to any scanned surface.`
+            : `${name}: not in the library and not found in any scanned surface.`,
+        );
+        return 0;
+      }
+      ctx.log(`${name} — deployed at ${sites.length} site${sites.length === 1 ? "" : "s"}:`);
+      for (const s of sites) {
+        ctx.log(`  ${labelFor(s)}  ${tilde(s.path)}`);
+        if (s.kind === "foreign-link" && s.target) ctx.log(`      → ${tilde(s.target)}`);
+        const fix = suggestionFor(s);
+        if (fix) ctx.log(`      ${fix}`);
+      }
+      return 0;
+    }
+
+    // --- full map / problems --------------------------------------------
+    if (json) {
+      ctx.json(problems ? { surfaces: report.surfaces, problems: report.problems } : report);
+      return 0;
+    }
+
+    const linked = report.sites.filter((s) => s.kind === "linked");
+    ctx.log(`Scanned ${report.surfaces.length} surface${report.surfaces.length === 1 ? "" : "s"}:`);
+    for (const s of report.surfaces) ctx.log(`  ${tilde(s)}`);
+    ctx.log("");
+    ctx.log(`Clean: ${linked.length} linked deployment${linked.length === 1 ? "" : "s"}.`);
+
+    if (report.problems.length === 0) {
+      ctx.log("No deployment problems. ✨");
+      return 0;
+    }
+
+    ctx.log("");
+    ctx.log(`Problems (${report.problems.length}):`);
+    for (const s of report.problems) {
+      ctx.log(`  ${s.name}  [${labelFor(s)}]`);
+      ctx.log(`    ${tilde(s.path)}${s.kind === "foreign-link" && s.target ? ` → ${tilde(s.target)}` : ""}`);
+      ctx.log(`    → ${suggestionFor(s)}`);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl where failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveConfig, addRoot, removeRoot, loadContext } from "./config.ts";
+
+describe("config: SKILLSHELF_CONFIG isolation + root registry inverse", () => {
+  let tmp: string;
+  let cfg: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "skl-config-"));
+    cfg = join(tmp, "config.json");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("SKILLSHELF_CONFIG env redirects the config file path", async () => {
+    const config = await resolveConfig({ env: { SKILLSHELF_CONFIG: cfg } as NodeJS.ProcessEnv });
+    expect(config.configFilePath).toBe(cfg);
+  });
+
+  test("addRoot then removeRoot is a clean round-trip", async () => {
+    await addRoot(cfg, [], "/tmp/alpha");
+    const after = await addRoot(cfg, ["/tmp/alpha"], "/tmp/beta");
+    expect(after).toEqual(["/tmp/alpha", "/tmp/beta"]);
+
+    const { roots, removed } = await removeRoot(cfg, "/tmp/alpha");
+    expect(removed).toBe(true);
+    expect(roots).toEqual(["/tmp/beta"]);
+
+    const onDisk = JSON.parse(await readFile(cfg, "utf8"));
+    expect(onDisk.roots).toEqual(["/tmp/beta"]);
+  });
+
+  test("removeRoot on a non-registered path is idempotent (removed:false)", async () => {
+    await addRoot(cfg, [], "/tmp/alpha");
+    const { roots, removed } = await removeRoot(cfg, "/tmp/nope");
+    expect(removed).toBe(false);
+    expect(roots).toEqual(["/tmp/alpha"]);
+  });
+
+  test("removeRoot preserves annotated RootEntry siblings", async () => {
+    await Bun.write(
+      cfg,
+      JSON.stringify({
+        roots: [{ path: "/tmp/keep", notes: "important" }, "/tmp/drop"],
+      }),
+    );
+    const { roots, removed } = await removeRoot(cfg, "/tmp/drop");
+    expect(removed).toBe(true);
+    expect(roots).toEqual(["/tmp/keep"]);
+    const onDisk = JSON.parse(await readFile(cfg, "utf8"));
+    // annotation on the surviving entry is preserved
+    expect(onDisk.roots).toEqual([{ path: "/tmp/keep", notes: "important" }]);
+  });
+
+  test("ctx.removeRoot persists and keeps the live roots view in sync", async () => {
+    const ctx = await loadContext({ env: { SKILLSHELF_CONFIG: cfg } as NodeJS.ProcessEnv });
+    await ctx.addRoot("/tmp/one");
+    await ctx.addRoot("/tmp/two");
+    const res = await ctx.removeRoot("/tmp/one");
+    expect(res.removed).toBe(true);
+    expect(ctx.roots).toEqual(["/tmp/two"]);
+    expect(existsSync(cfg)).toBe(true);
+  });
+});

package/src/config.ts

@@ -8,7 +8,7 @@
 import { homedir } from "node:os";
 import { join, resolve, isAbsolute } from "node:path";
 import { existsSync } from "node:fs";
-import type { Config, ConfigFile, Ctx, Skill } from "./types.ts";
+import type { Config, ConfigFile, Ctx, RootEntry, Skill } from "./types.ts";
 
 export const DEFAULT_CONFIG_FILE = join(homedir(), ".skillshelf", "config.json");
 export const DEFAULT_LIBRARY = join(homedir(), ".skillshelf", "library");
@@ -45,7 +45,15 @@ export async function resolveConfig(opts: {
   configFilePath?: string;
 } = {}): Promise<Config> {
   const env = opts.env ?? process.env;
-  const configFilePath = opts.configFilePath ?? DEFAULT_CONFIG_FILE;
+  // Config-file resolution: explicit opt override (tests) → SKILLSHELF_CONFIG env →
+  // default ~/.skillshelf/config.json. The env override lets an experiment redirect
+  // ALL persisted state (roots especially) into a sandbox without touching the real
+  // config — `skl scan --add-root` otherwise writes the real file regardless of
+  // SKILLSHELF_LIBRARY (the isolation gap this closes).
+  const envCfg = env.SKILLSHELF_CONFIG;
+  const configFilePath =
+    opts.configFilePath ??
+    (envCfg && envCfg.trim() !== "" ? abs(envCfg.trim()) : DEFAULT_CONFIG_FILE);
 
   const fileCfg = await readConfigFile(configFilePath);
   const usedConfigFile = fileCfg ? configFilePath : null;
@@ -84,14 +92,25 @@ export async function resolveConfig(opts: {
   };
 }
 
-/** Expand ~, absolutize, and de-duplicate a list of root paths (order-preserving). */
+/**
+ * Expand ~, absolutize, and de-duplicate a list of scan roots (order-preserving).
+ * Each entry may be a bare path string OR an annotated {path, layout?, notes?}
+ * object (see RootEntry); both normalize to an absolute path string here.
+ * layout/notes are informational only and dropped — crawl auto-detects layout and
+ * nothing consumes them programmatically.
+ */
 function normalizeRoots(input: unknown): string[] {
   if (!Array.isArray(input)) return [];
   const out: string[] = [];
   const seen = new Set<string>();
   for (const r of input) {
-    if (typeof r !== "string" || r.trim() === "") continue;
-    const a = abs(r.trim());
+    let raw: string | null = null;
+    if (typeof r === "string") raw = r;
+    else if (r && typeof r === "object" && typeof (r as { path?: unknown }).path === "string") {
+      raw = (r as { path: string }).path;
+    }
+    if (raw === null || raw.trim() === "") continue;
+    const a = abs(raw.trim());
     if (seen.has(a)) continue;
     seen.add(a);
     out.push(a);
@@ -102,7 +121,10 @@ function normalizeRoots(input: unknown): string[] {
 /**
  * Persist a new scan root into the config file (`configFilePath`), expanding ~,
  * absolutizing, and de-duplicating against existing roots. Preserves the rest of
- * the config file (library / globalCore). Returns the full updated roots list.
+ * the config file (library / globalCore) AND any annotations on existing root
+ * entries ({path, layout?, notes?}): we only APPEND a new bare-path entry when the
+ * resolved path is absent. Returns the full updated roots list as resolved
+ * absolute path strings (the in-memory Config.roots form).
  */
 export async function addRoot(
   configFilePath: string,
@@ -110,13 +132,53 @@ export async function addRoot(
   path: string,
 ): Promise<string[]> {
   const a = abs(path.trim());
-  const roots = [...existingRoots];
-  if (!roots.includes(a)) roots.push(a);
 
+  // Preserve the on-disk roots verbatim (including RootEntry annotations); only
+  // append the new path if it is not already present (compared after resolution).
   const current = (await readConfigFile(configFilePath)) ?? {};
-  const next: ConfigFile = { ...current, roots };
+  const persisted: Array<string | RootEntry> = Array.isArray(current.roots)
+    ? [...current.roots]
+    : [];
+  const resolvedOf = (entry: string | RootEntry): string | null => {
+    const raw = typeof entry === "string" ? entry : entry?.path;
+    return typeof raw === "string" && raw.trim() !== "" ? abs(raw.trim()) : null;
+  };
+  if (!persisted.some((e) => resolvedOf(e) === a)) persisted.push(a);
+
+  const next: ConfigFile = { ...current, roots: persisted };
   await Bun.write(configFilePath, JSON.stringify(next, null, 2) + "\n");
-  return roots;
+
+  // Return the resolved, de-duped absolute path list (Config.roots stays string[]).
+  return normalizeRoots(persisted);
+}
+
+/**
+ * Remove a scan root from the config file (`configFilePath`) — the inverse of
+ * addRoot. Matches by resolved absolute path, so the caller may pass a bare/`~`/
+ * relative form of an already-persisted root. Preserves the rest of the config and
+ * any annotations on the surviving root entries. Returns the updated roots list as
+ * resolved absolute path strings, plus whether anything was actually removed.
+ */
+export async function removeRoot(
+  configFilePath: string,
+  path: string,
+): Promise<{ roots: string[]; removed: boolean }> {
+  const target = abs(path.trim());
+  const current = (await readConfigFile(configFilePath)) ?? {};
+  const persisted: Array<string | RootEntry> = Array.isArray(current.roots)
+    ? [...current.roots]
+    : [];
+  const resolvedOf = (entry: string | RootEntry): string | null => {
+    const raw = typeof entry === "string" ? entry : entry?.path;
+    return typeof raw === "string" && raw.trim() !== "" ? abs(raw.trim()) : null;
+  };
+  const kept = persisted.filter((e) => resolvedOf(e) !== target);
+  const removed = kept.length !== persisted.length;
+  if (removed) {
+    const next: ConfigFile = { ...current, roots: kept };
+    await Bun.write(configFilePath, JSON.stringify(next, null, 2) + "\n");
+  }
+  return { roots: normalizeRoots(kept), removed };
 }
 
 /**
@@ -146,6 +208,13 @@ export async function loadContext(opts: {
       config.roots = roots;
       return roots;
     },
+    removeRoot: async (path: string): Promise<{ roots: string[]; removed: boolean }> => {
+      const res = await removeRoot(config.configFilePath, path);
+      roots = res.roots;
+      ctx.roots = roots;
+      config.roots = roots;
+      return res;
+    },
     log: (...args: unknown[]) => {
       console.log(...args);
     },