@dastyaresocial/ds-cs 0.1.2 → 0.2.1

package/README.md

@@ -13,15 +13,74 @@ DS-CS already speaks two agent protocols — a REST API and an MCP server — bu
 
 Skills are that knowledge, in the form agents actually load. This CLI installs them.
 
+## The interactive flow
+
+Run it with no flags and `ds-cs` asks, in this order:
+
+```
+? Where should ds-cs install skills?
+❯ This project                    committed, shared with your team
+  Global (every project)           your user directory — OpenCode, Claude Code
+
+? Which agents should read these skills?
+  type to filter · space toggle · a all · enter confirm
+  ❯ ◉ Select all
+    ◉ OpenCode          .agents/skills
+    ◉ Cursor            .agents/skills
+    ◉ Codex             .agents/skills
+    ◉ Claude Code       .claude/skills
+    ○ Windsurf          .windsurf/skills
+  … 8 more
+
+(15 selected: opencode, claude-code, cursor, codex, …)
+
+? How should the files be shared between agents?
+❯ Symlink                          one copy, updates land everywhere
+  Copy                              independent files per agent
+
+? Which skills would you like to install?
+  type to filter · space toggle · a all · enter install
+  ❯ ◉ Select all
+    ○ add-component     skills/dev/add-component/
+    ○ add-orpc-endpoint skills/dev/add-orpc-endpoint/
+  …
+```
+
+Scope first, because it decides which directories exist; then which agents read
+the skills; then how those agents share one copy; then what to install.
+
+Both multi-selects open on a **Select all** row — space on it, or `a` anywhere,
+takes everything; pressing it again clears the selection. That is what you want
+on a first run and never again.
+
+**Your last choices are remembered** in `~/.config/ds-cs/preferences.json`, so
+the next run preselects them and you can just hit enter three times. Delete the
+file to reset. It lives in your user directory, not the repo — scope and agent
+choice are habits, not project configuration.
+
+In the skill picker, typing filters against names, paths **and descriptions**, so
+`webh` finds `webhooks` and `manage-stories` (both mention webhooks). Space
+toggles, so you can take several at once.
+
+Without a terminal — CI, a pipe, an agent — nothing prompts. `ds-cs add` prints
+a listing, and flags decide:
+
+```bash
+ds-cs add --global                     # scope
+ds-cs add brand-config -a opencode     # agent (repeatable, or a directory path)
+ds-cs add --copy                       # independent copies
+ds-cs add -y                           # accept defaults, no prompts
+```
+
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `ds-cs init` | Create skills directories, optionally write MCP config |
+| `ds-cs init` | Prepare skills directories, optionally write MCP config |
 | `ds-cs add <skill\|source>` | Install skills from DS-CS or anywhere else |
 | `ds-cs list` | Show what is installed and where it came from |
 | `ds-cs update [skill…]` | Re-fetch skills that changed upstream |
-| `ds-cs remove <skill…>` | Uninstall from every agent |
+| `ds-cs remove <skill…]` | Uninstall skills from every agent |
 | `ds-cs search [query]` | Search installed skills |
 | `ds-cs mcp [agent]` | Print, or write, MCP server config |
 | `ds-cs login` | Store a channel URL and API key |
@@ -124,10 +183,26 @@ Set `metadata.internal: true` to hide a skill from discovery until `INSTALL_INTE
 ## Development
 
 ```bash
-npm test          # node:test, no dependencies
+npm test                    # node:test, no dependencies
+npm run sync-skills         # refresh the bundled registry copy
 npm run dev -- --help
 ```
 
+The prompts are hand-rolled keypress handling, which cannot be exercised without
+a terminal — every automated check would otherwise stop at `isInteractive()` and
+test the non-interactive path instead. `test/pty_harness.py` runs the real
+binary under a pty, sends keystrokes, and prints the final screen.
+
+It splits the raw stream into repaint frames rather than counting occurrences of
+a menu in it. A prompt redraws by emitting cursor-up and erase sequences, so the
+byte stream contains every frame ever drawn; counting them there would report a
+correctly-repainting prompt as one that duplicates its menu:
+
+```bash
+python3 test/pty_harness.py "ENTER,SPACE,ENTER,ENTER,s,t,o,SPACE,ENTER" \
+  node bin/ds-cs.mjs add
+```
+
 While working inside a DS-CS checkout, `ds-cs add` prefers the local `skills/` directory over the published registry, so edits reinstall immediately. Pass a source path explicitly to bypass that.
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dastyaresocial/ds-cs",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "CLI for Dastyare Social — CS. Install DS-CS skills and third-party agent skills, wire up MCP, and authenticate to a channel.",
   "license": "MIT",
   "type": "module",

package/skills/README.md

@@ -3,11 +3,14 @@
 First-party skills for [Dastyare Social — CS](https://cs.dastyare.social). Install them with:
 
 ```bash
-npx @dastyaresocial/ds-cs init
-npx @dastyaresocial/ds-cs add                  # browse everything
-npx @dastyaresocial/ds-cs add post-with-media  # or install one by name
+npx @dastyaresocial/ds-cs init   # project or global? which agents? symlink or copy?
+npx @dastyaresocial/ds-cs add   # searchable picker over every skill
 ```
 
+Both are interactive and remember your last choices. To skip the prompts, pass a
+skill name (`ds-cs add post-with-media`) or flags (`--global`, `-a opencode`,
+`--copy`, `-y`).
+
 ## What is here
 
 ### Working on the codebase — `dev/`

package/src/agents.mjs

@@ -14,21 +14,21 @@ import { exists, isDirectory } from "./utils/fs.mjs";
  * `--agent-dir <path>`.
  */
 export const AGENTS = [
-  { name: "opencode", project: ".agents/skills", global: ".config/opencode/skills", detect: ".opencode" },
-  { name: "cursor", project: ".agents/skills", global: ".cursor/skills", detect: ".cursor" },
-  { name: "codex", project: ".agents/skills", global: ".codex/skills", detect: ".codex" },
-  { name: "claude-code", project: ".claude/skills", global: ".claude/skills", detect: ".claude" },
-  { name: "windsurf", project: ".windsurf/skills", global: ".codeium/windsurf/skills", detect: ".windsurf" },
-  { name: "amp", project: ".agents/skills", global: ".config/agents/skills", detect: ".amp" },
-  { name: "gemini-cli", project: ".agents/skills", global: ".gemini/skills", detect: ".gemini" },
-  { name: "github-copilot", project: ".agents/skills", global: ".copilot/skills", detect: ".github" },
-  { name: "goose", project: ".goose/skills", global: ".config/goose/skills", detect: ".goose" },
-  { name: "devin", project: ".devin/skills", global: ".config/devin/skills", detect: ".devin" },
-  { name: "kilo-code", project: ".agents/skills", global: ".kilocode/skills", detect: ".kilocode" },
-  { name: "cline", project: ".agents/skills", global: ".cline/skills", detect: ".cline" },
-  { name: "roo", project: ".roo/skills", global: ".roo/skills", detect: ".roo" },
-  { name: "crush", project: ".crush/skills", global: ".config/crush/skills", detect: ".crush" },
-  { name: "aider-desk", project: ".aider-desk/skills", global: ".aider-desk/skills", detect: ".aider-desk" },
+  { name: "opencode", label: "OpenCode", project: ".agents/skills", global: ".config/opencode/skills", detect: ".opencode", globalRoot: ".config/opencode" },
+  { name: "cursor", label: "Cursor", project: ".agents/skills", global: ".cursor/skills", detect: ".cursor", globalRoot: ".cursor" },
+  { name: "codex", label: "Codex", project: ".agents/skills", global: ".codex/skills", detect: ".codex", globalRoot: ".codex" },
+  { name: "claude-code", label: "Claude Code", project: ".claude/skills", global: ".claude/skills", detect: ".claude", globalRoot: ".claude" },
+  { name: "windsurf", label: "Windsurf", project: ".windsurf/skills", global: ".codeium/windsurf/skills", detect: ".windsurf", globalRoot: ".codeium" },
+  { name: "gemini-cli", label: "Gemini CLI", project: ".agents/skills", global: ".gemini/skills", detect: ".gemini", globalRoot: ".gemini" },
+  { name: "github-copilot", label: "GitHub Copilot", project: ".agents/skills", global: ".copilot/skills", detect: ".github", globalRoot: ".copilot" },
+  { name: "amp", label: "Amp", project: ".agents/skills", global: ".config/agents/skills", detect: ".amp", globalRoot: ".config/agents" },
+  { name: "goose", label: "Goose", project: ".goose/skills", global: ".config/goose/skills", detect: ".goose", globalRoot: ".config/goose" },
+  { name: "devin", label: "Devin", project: ".devin/skills", global: ".config/devin/skills", detect: ".devin", globalRoot: ".config/devin" },
+  { name: "kilo-code", label: "Kilo Code", project: ".agents/skills", global: ".kilocode/skills", detect: ".kilocode", globalRoot: ".kilocode" },
+  { name: "cline", label: "Cline", project: ".agents/skills", global: ".cline/skills", detect: ".cline", globalRoot: ".cline" },
+  { name: "roo", label: "Roo Code", project: ".roo/skills", global: ".roo/skills", detect: ".roo", globalRoot: ".roo" },
+  { name: "crush", label: "Crush", project: ".crush/skills", global: ".config/crush/skills", detect: ".crush", globalRoot: ".config/crush" },
+  { name: "aider-desk", label: "AiderDesk", project: ".aider-desk/skills", global: ".aider-desk/skills", detect: ".aider-desk", globalRoot: ".aider-desk" },
 ];
 
 /**

package/src/commands/add.mjs

@@ -1,70 +1,71 @@
 import path from "node:path";
 
-import {
-  CANONICAL_AGENT,
-  dedupeDirectories,
-  detectAgents,
-  getAgent,
-  skillsDirFor,
-} from "../agents.mjs";
+import { dedupeDirectories } from "../agents.mjs";
 import { installSkills } from "../install.mjs";
 import { lockfilePath } from "../lockfile.mjs";
+import { agentDirectories, resolveInstallTarget } from "../setup.mjs";
 import { discoverSkills } from "../skills/discover.mjs";
-import { toArray } from "../args.mjs";
-import { CliError } from "../utils/errors.mjs";
-import { cyan, log, table } from "../utils/log.mjs";
+import { resolveSource } from "../registry/sources.mjs";
+import { cyan, dim, log, table } from "../utils/log.mjs";
 import { isInteractive } from "../utils/prompt.mjs";
 import { resolveRequest } from "./target.mjs";
 
 export async function addCommand(positional, flags, { projectRoot }) {
   const { source, names } = resolveRequest(positional, flags);
 
-  // `ds-cs add` on its own means "show me what there is" — the interactive
-  // picker when there is a terminal, the plain listing when there is not (CI, a
-  // pipe, an agent shell). Erroring on a missing TTY would make the documented
-  // "browse everything" form fail in exactly the places people run it.
-  if (flags.list || (names.length === 0 && !isInteractive())) {
+  // `ds-cs add` on its own means "show me what there is": the searchable picker
+  // on a terminal, a plain listing without one. Erroring on a missing TTY would
+  // make the documented "browse everything" form fail in exactly the places
+  // people run it — CI, a pipe, an agent shell.
+  const browsing = flags.list || (names.length === 0 && !isInteractive());
+  if (browsing) {
     await listSource(source, projectRoot);
     return;
   }
 
-  const global = Boolean(flags.global);
-  const targets = resolveTargets(flags, { projectRoot, global });
+  const target = await resolveInstallTarget(flags, { projectRoot });
+  const directories = dedupeDirectories(
+    agentDirectories(target.agents, { projectRoot, global: target.global })
+  );
 
   const { installed, resolved } = await installSkills({
     source,
     names,
     projectRoot,
-    targets,
-    global,
-    copy: Boolean(flags.copy),
-    yes: Boolean(flags.yes),
+    targets: directories,
+    global: target.global,
+    copy: target.copy,
+    interactive: target.interactive,
   });
 
-  log.success(`Installed ${installed.length} skill${installed.length === 1 ? "" : "s"} from ${resolved.describe()}`);
+  log.success(
+    `Installed ${installed.length} skill${installed.length === 1 ? "" : "s"} from ${resolved.describe()}`
+  );
 
   for (const entry of installed) {
     log.plain(`  ${cyan(entry.skill.name)}  ${entry.skill.description}`);
     log.plain(`    ${display(entry.destination)}`);
     for (const link of entry.links) {
-      log.plain(`    → ${display(link.target)} (${link.linked ? "linked" : "copied — symlinks unavailable"})`);
+      log.plain(
+        `    → ${display(link.target)} (${link.linked ? "linked" : "copied — symlinks unavailable"})`
+      );
     }
   }
 
-  log.plain(`\n  Recorded in ${display(lockfilePath(projectRoot))}`);
+  log.plain("");
+  log.plain(
+    dim(
+      `  Recorded in ${display(lockfilePath(projectRoot))}${target.global ? dim("  (global install)") : ""}`
+    )
+  );
 }
 
-/**
- * Show paths relative to the current directory, but fall back to absolute when
- * the relative form would be a chain of `../` — nobody can place that.
- */
 function display(target) {
   const relative = path.relative(process.cwd(), target);
   return relative === "" || relative.startsWith("..") ? target : relative;
 }
 
 async function listSource(sourceSpec, projectRoot) {
-  const { resolveSource } = await import("../registry/sources.mjs");
   const resolved = await resolveSource(sourceSpec, { cwd: projectRoot });
   const skills = (await discoverSkills(resolved.root)).filter(
     (skill) => process.env.INSTALL_INTERNAL_SKILLS === "1" || !skill.internal
@@ -88,36 +89,6 @@ async function listSource(sourceSpec, projectRoot) {
       { key: "description", title: "DESCRIPTION", flex: true },
     ]
   );
-}
-
-function resolveTargets(flags, { projectRoot, global }) {
-  const requested = toArray(flags.agent);
-  if (requested.includes("*")) return [canonicalDir(projectRoot, global)];
-
-  if (requested.length === 0) {
-    return detectAgents({ projectRoot, global }).then((agents) =>
-      dedupeDirectories(
-        agents.map((agent) => skillsDirFor(agent, { projectRoot, global }))
-      )
-    );
-  }
-
-  return requested.map((name) => {
-    try {
-      return skillsDirFor(getAgent(name).name, { projectRoot, global });
-    } catch {
-      // `--agent` accepts a literal directory too, so an agent this CLI does not
-      // know about can still be targeted without waiting to be added here.
-      if (name.startsWith(".") || path.isAbsolute(name)) {
-        return path.isAbsolute(name) ? name : path.join(projectRoot, name);
-      }
-      throw new CliError(`Unknown agent "${name}"`, {
-        hint: "Run `ds-cs init --list-agents`, or pass a directory starting with \".\" or \"/\".",
-      });
-    }
-  });
-}
-
-function canonicalDir(projectRoot, global) {
-  return skillsDirFor(CANONICAL_AGENT, { projectRoot, global });
+  log.plain("");
+  log.plain(dim("  Install one or more:  ds-cs add <name> [name…]  ·  browse interactively:  ds-cs add"));
 }

package/src/commands/init.mjs

@@ -1,11 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { CANONICAL_AGENT, detectAgents, skillsDirFor } from "../agents.mjs";
-import { toArray } from "../args.mjs";
 import { MCP_TARGETS, buildMcpConfig } from "../mcp-config.mjs";
+import { agentDirectories, resolveInstallTarget } from "../setup.mjs";
 import { exists, ensureDir } from "../utils/fs.mjs";
-import { cyan, log } from "../utils/log.mjs";
+import { bold, cyan, dim, log } from "../utils/log.mjs";
 import { printAgents } from "./list.mjs";
 
 const GITIGNORE_BLOCK = `# ds-cs
@@ -17,10 +16,11 @@ const GITIGNORE_BLOCK = `# ds-cs
 /**
  * Prepare a project for DS-CS skills.
  *
- * `init` deliberately installs nothing by itself. It creates the directories and
- * optionally the MCP wiring, then prints what to run next — a new user who has
- * not asked for a specific skill should not silently end up with forty of them
- * in their repository.
+ * Interactive: asks where to install, which agents read them, and how files are
+ * shared. Non-interactive: flags and detection decide, so CI is unchanged.
+ *
+ * `init` deliberately installs no skills. A user who has not asked for a
+ * specific one should not silently end up with forty in their repository.
  */
 export async function initCommand(positional, flags, { projectRoot }) {
   if (flags.listAgents) {
@@ -28,21 +28,21 @@ export async function initCommand(positional, flags, { projectRoot }) {
     return;
   }
 
-  const global = Boolean(flags.global);
-  const detected = await detectAgents({ projectRoot, global });
-  const requested = toArray(flags.agent);
-  const agents = requested.length > 0 ? requested : detected;
+  const target = await resolveInstallTarget(flags, { projectRoot });
+  const { global, agents, copy } = target;
 
-  for (const agent of agents) {
-    const directory = skillsDirFor(agent, { projectRoot, global });
+  const directories = agentDirectories(agents, { projectRoot, global });
+  for (const directory of directories) {
     await ensureDir(directory);
   }
 
-  // Many agents share one directory (OpenCode, Cursor and Codex all read
-  // `.agents/skills`), so report each real directory once.
-  for (const directory of new Set(agents.map((agent) => skillsDirFor(agent, { projectRoot, global })))) {
-    log.success(`Skills directory ready: ${display(directory)}`);
+  const scopeLabel = global ? "global" : "project";
+  log.success(`Skills will install to the ${bold(scopeLabel)} scope.`);
+  for (const directory of directories) {
+    const relative = display(directory);
+    log.plain(`  ${cyan("→")} ${relative}`);
   }
+  log.plain(dim(`  ${copy ? "copied into each agent" : "symlinked from one canonical copy"}`));
 
   if (!global) {
     await explainGitignore(projectRoot);
@@ -60,7 +60,8 @@ export async function initCommand(positional, flags, { projectRoot }) {
 }
 
 function display(target) {
-  return path.relative(process.cwd(), target) || ".";
+  const relative = path.relative(process.cwd(), target);
+  return relative === "" || relative.startsWith("..") ? target : relative;
 }
 
 /**
@@ -102,5 +103,3 @@ async function writeMcpConfigs(projectRoot, flags) {
     log.success(`MCP server "ds-cs" written to ${display(file)}`);
   }
 }
-
-export { CANONICAL_AGENT };

package/src/install.mjs

@@ -12,7 +12,7 @@ import {
   hashDirectory,
   removeDirectory,
 } from "./utils/fs.mjs";
-import { select } from "./utils/prompt.mjs";
+import { pickSkills } from "./setup.mjs";
 
 /**
  * Install skills from a source into one or more agents.
@@ -30,6 +30,7 @@ export async function installSkills({
   global = false,
   copy = false,
   yes = false,
+  interactive = false,
   preferLocal = true,
 }) {
   const resolved = await resolveSource(sourceSpec, { cwd: projectRoot, preferLocal });
@@ -44,7 +45,7 @@ export async function installSkills({
     });
   }
 
-  const chosen = await chooseSkills(available, names, resolved, { yes });
+  const chosen = await chooseSkills(available, names, resolved, { yes, interactive });
   if (chosen.length === 0) return { installed: [], resolved };
 
   const canonicalDir = skillsDirFor(CANONICAL_AGENT, { projectRoot, global });
@@ -90,22 +91,22 @@ function isSameDirectory(source, destination) {
   return path.resolve(source) === path.resolve(destination);
 }
 
-async function chooseSkills(available, names, resolved, { yes }) {
+async function chooseSkills(available, names, resolved, { yes, interactive }) {
   if (names.includes("*")) return available;
 
   if (names.length > 0) {
     return names.map((name) => assertSkillExists(available, name));
   }
 
-  if (yes) return [available[0]];
-
-  const picked = await select(`Which skills from ${resolved.describe()}?`, available.map((skill) => ({
-    label: skill.name,
-    value: skill,
-    description: skill.description,
-  })));
+  // Interactive with no names means "browse": let the user search and take as
+  // many as they want. `addCommand` routes the no-TTY case to the plain
+  // listing before it ever reaches here.
+  if (interactive && !yes) {
+    const picked = await pickSkills(available);
+    return picked.map((name) => assertSkillExists(available, name));
+  }
 
-  return picked.map((choice) => choice.value);
+  return [available[0]];
 }
 
 /**

package/src/preferences.mjs

@@ -0,0 +1,66 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { exists } from "./utils/fs.mjs";
+
+/**
+ * User-level preferences: which scope you normally install into, which agents
+ * you normally target, and symlink vs copy.
+ *
+ * Stored per user rather than per project on purpose. Scope and agent choice
+ * are habits, not project configuration — writing them into someone's repo
+ * would be litter, and a committed "install globally" would quietly change
+ * behaviour on every other machine that cloned it.
+ */
+function preferencesPath() {
+  const base =
+    process.env.DS_CS_CONFIG_DIR ??
+    (process.env.XDG_CONFIG_HOME
+      ? path.join(process.env.XDG_CONFIG_HOME, "ds-cs")
+      : path.join(os.homedir(), ".config", "ds-cs"));
+  return path.join(base, "preferences.json");
+}
+
+export const DEFAULTS = {
+  scope: "project",
+  method: "symlink",
+  agents: ["opencode", "claude-code"],
+};
+
+export async function readPreferences() {
+  const file = preferencesPath();
+  if (!(await exists(file))) return { ...DEFAULTS };
+
+  try {
+    const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+    return {
+      scope: parsed.scope === "global" ? "global" : "project",
+      method: parsed.method === "copy" ? "copy" : "symlink",
+      agents: Array.isArray(parsed.agents) && parsed.agents.length > 0 ? parsed.agents : [...DEFAULTS.agents],
+    };
+  } catch {
+    // A corrupt preferences file must never block an install — fall back to
+    // defaults rather than making the user hand-edit JSON.
+    return { ...DEFAULTS };
+  }
+}
+
+export async function writePreferences(patch) {
+  const file = preferencesPath();
+  const current = await readPreferences();
+  const next = { ...current, ...patch };
+
+  try {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  } catch {
+    // Preferences are a convenience. Failing to persist them is not worth
+    // failing an install over.
+  }
+  return next;
+}
+
+export function preferencesLocation() {
+  return preferencesPath();
+}

package/src/setup.mjs

@@ -0,0 +1,202 @@
+import path from "node:path";
+
+import { AGENTS, CANONICAL_AGENT, getAgent, skillsDirFor } from "./agents.mjs";
+import { readPreferences, writePreferences } from "./preferences.mjs";
+import { isInteractive, multiselect, select } from "./utils/prompt.mjs";
+
+/**
+ * The interactive setup flow, shared by `init` and `add`.
+ *
+ * Order matters and mirrors what an installer is actually asking: scope first
+ * (it decides which directories exist), then which agents to write into (it
+ * decides what gets created), then how the files are shared between them.
+ */
+
+function agentLabel(agent) {
+  return AGENTS.find((candidate) => candidate.name === agent)?.label ?? agent;
+}
+
+export async function detectInstalledAgents({ projectRoot, global }) {
+  const found = [];
+  for (const agent of AGENTS) {
+    const marker = global
+      ? agent.globalRoot
+      : path.join(projectRoot, agent.detect);
+    if (marker && (await hasPath(marker))) found.push(agent.name);
+  }
+  return found;
+}
+
+async function hasPath(target) {
+  const fs = await import("node:fs/promises");
+  try {
+    await fs.stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Choice list for the agent picker, detected agents marked. */
+function agentChoices(detected) {
+  return AGENTS.map((agent) => ({
+    value: agent.name,
+    label: agent.label,
+    description: `${detected.includes(agent.name) ? "detected" : ""} ${agent.project}`.trim(),
+  }));
+}
+
+/**
+ * Ask where to install, which agents, and how to share files — unless the
+ * caller already decided via flags or there is no terminal.
+ *
+ * Returns `{ global, agents, copy, interactive }`. When nothing was prompted
+ * the flags and detection decide, so CI behaviour is unchanged.
+ */
+export async function resolveInstallTarget(flags, { projectRoot }) {
+  const preferences = await readPreferences();
+  const detected = await detectInstalledAgents({ projectRoot, global: false });
+  const interactive = isInteractive();
+
+  // ---- scope -------------------------------------------------------------
+  let global = Boolean(flags.global);
+  let scopeAsked = false;
+
+  if (interactive && !flags.project && flags.global === undefined) {
+    scopeAsked = true;
+    const [choice] = await select({
+      message: "Where should ds-cs install skills?",
+      choices: [
+        {
+          value: "project",
+          label: "This project",
+          description: "committed, shared with your team",
+        },
+        {
+          value: "global",
+          label: "Global (every project)",
+          description: `your user directory — ${preferences.agents.map(agentLabel).join(", ") || "all agents"}`,
+        },
+      ],
+      initialIndex: preferences.scope === "global" ? 1 : 0,
+    });
+    global = choice.value === "global";
+  }
+
+  // ---- agents ------------------------------------------------------------
+  let agents;
+  const requestedAgents = toArray(flags.agent);
+
+  if (requestedAgents.length > 0) {
+    agents = requestedAgents.includes("*") ? [CANONICAL_AGENT] : requestedAgents;
+  } else if (interactive && !flags.yes) {
+    // Pre-select whatever we last chose, falling back to what is detected,
+    // falling back to the canonical agent. Remembering the last choice is the
+    // single biggest time-saver in a prompt you answer on every new project.
+    // The canonical agent is not special-cased here: it is a real agent with a
+    // real directory, and dropping it would silently deselect it for everyone.
+    const seed =
+      preferences.agents.length > 0
+        ? preferences.agents
+        : detected.length > 0
+          ? detected
+          : [CANONICAL_AGENT];
+
+    const picked = await multiselect({
+      message: "Which agents should read these skills?",
+      choices: agentChoices(detected),
+      initialSelected: seed,
+      hint: "type to filter · space toggle · a all · enter confirm",
+      required: true,
+    });
+    agents = picked.map((choice) => choice.value);
+  } else {
+    agents = detected.length > 0 ? detected : [CANONICAL_AGENT];
+  }
+
+  agents = [...new Set(agents.map((agent) => (agent === "*" ? CANONICAL_AGENT : agent)))];
+
+  // ---- install method ----------------------------------------------------
+  let copy = Boolean(flags.copy);
+
+  if (interactive && !flags.yes && flags.copy === undefined) {
+    const [choice] = await select({
+      message: "How should the files be shared between agents?",
+      choices: [
+        {
+          value: "symlink",
+          label: "Symlink",
+          description: "one copy, updates land everywhere",
+        },
+        {
+          value: "copy",
+          label: "Copy",
+          description: "independent files per agent",
+        },
+      ],
+      initialIndex: preferences.method === "copy" ? 1 : 0,
+    });
+    copy = choice.value === "copy";
+  }
+
+  // Remember the choices only when the user actually made them.
+  if (interactive) {
+    await writePreferences({
+      scope: global ? "global" : "project",
+      agents,
+      method: copy ? "copy" : "symlink",
+    });
+  }
+
+  return { global, agents, copy, interactive, scopeAsked, detected };
+}
+
+function toArray(value) {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Searchable skill picker.
+ *
+ * A numbered single-select is the wrong shape for an installer: you should be
+ * able to take three skills at once and filter a long registry by typing.
+ *
+ * The list stays compact (name + path), but filtering also runs against the
+ * full description — which is where the words a user would actually search for
+ * live ("webhook", "migrate", "release"), not in a directory name.
+ */
+export async function pickSkills(skills) {
+  const picked = await multiselect({
+    message: "Which skills would you like to install?",
+    choices: skills.map((skill) => ({
+      value: skill.name,
+      label: skill.name,
+      description: skill.skillPath.replace(/SKILL\.md$/, ""),
+      keywords: `${skill.name} ${skill.skillPath} ${skill.description ?? ""}`,
+    })),
+    hint: "type to filter · space toggle · a all · enter install",
+    required: true,
+  });
+  return picked.map((choice) => choice.value);
+}
+
+/**
+ * Turn agent names into concrete skills directories, resolving custom
+ * directories the same way the flag parser does.
+ */
+export function agentDirectories(agentNames, { projectRoot, global }) {
+  const directories = [];
+  for (const agent of agentNames) {
+    if (agent.startsWith(".") || path.isAbsolute(agent)) {
+      directories.push(path.isAbsolute(agent) ? agent : path.join(projectRoot, agent));
+      continue;
+    }
+    try {
+      directories.push(skillsDirFor(getAgent(agent).name, { projectRoot, global }));
+    } catch (error) {
+      throw error;
+    }
+  }
+  return [...new Set(directories)];
+}

package/src/utils/prompt.mjs

@@ -1,69 +1,433 @@
-import readline from "node:readline/promises";
+import readline from "node:readline";
 import { stdin, stdout } from "node:process";
 
 import { CliError } from "./errors.mjs";
-import { bold, cyan, dim } from "./log.mjs";
+import { bold, cyan, dim, yellow } from "./log.mjs";
 
 /**
- * Non-interactive contexts (CI, piped stdin, --yes) must never hang waiting for
- * a keypress. Every prompt has a documented non-interactive fallback instead.
+ * Interactive prompts.
+ *
+ * Hand-rolled rather than pulled from a prompt library, because the CLI ships
+ * with zero runtime dependencies.
+ */
+
+const KEY = {
+  up: "up",
+  down: "down",
+  space: "space",
+  enter: "enter",
+  escape: "escape",
+  ctrlC: "c",
+  backspace: "backspace",
+};
+
+/**
+ * A repainting region of the terminal.
+ *
+ * The previous implementation moved the cursor up, cleared a single line, and
+ * wrote the menu again — which appended a fresh copy on every keypress and
+ * scrolled the real menu off screen. Repainting has to be stateless: each frame
+ * is measured, the last one is fully erased, and the new one is written at a
+ * known position.
+ */
+function createScreen(write) {
+  let lastHeight = 0;
+
+  return {
+    paint(lines) {
+      if (lastHeight > 0) write(`\x1B[${lastHeight}A`);
+      write("\x1B[0J"); // erase from the cursor to the end of the screen
+      for (const line of lines) write(`${line}\n`);
+      lastHeight = lines.length;
+    },
+    erase() {
+      if (lastHeight === 0) return;
+      write(`\x1B[${lastHeight}A`);
+      write("\x1B[0J");
+      lastHeight = 0;
+    },
+  };
+}
+
+function readKeys() {
+  readline.emitKeypressEvents(stdin);
+  if (stdin.isTTY) stdin.setRawMode(true);
+  return () => {
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.pause();
+  };
+}
+
+function keyOf(key) {
+  if (!key) return null;
+  switch (key.name) {
+    case "up":
+      return KEY.up;
+    case "k":
+      return KEY.up;
+    case "down":
+      return KEY.down;
+    case "j":
+      return KEY.down;
+    case "space":
+      return KEY.space;
+    case "return":
+    case "enter":
+      return KEY.enter;
+    case "escape":
+      return KEY.escape;
+    case "backspace":
+      return KEY.backspace;
+    default:
+      break;
+  }
+  if (key.ctrl && key.name === KEY.ctrlC) return KEY.ctrlC;
+  return null;
+}
+
+/**
+ * True when we can actually prompt.
+ *
+ * CI, a pipe, and an agent's shell are all non-interactive. Every prompt below
+ * has a documented non-interactive fallback instead of hanging.
  */
 export function isInteractive() {
   return Boolean(stdin.isTTY && stdout.isTTY) && process.env.CI !== "true";
 }
 
-async function question(prompt) {
-  const rl = readline.createInterface({ input: stdin, output: stdout });
-  try {
-    return (await rl.question(prompt)).trim();
-  } finally {
-    rl.close();
-  }
+function stripAnsi(text) {
+  return text.replace(/\u001B\[[0-9;]*m/g, "");
 }
 
-export async function confirm(message, { defaultYes = true } = {}) {
-  if (!isInteractive()) return defaultYes;
-  const suffix = defaultYes ? "[Y/n]" : "[y/N]";
-  const answer = (await question(`${message} ${dim(suffix)} `)).toLowerCase();
-  if (answer === "") return defaultYes;
-  return answer === "y" || answer === "yes";
+function visibleWidth(text) {
+  return stripAnsi(text).length;
 }
 
-export async function promptText(message, fallback = "") {
-  if (!isInteractive()) return fallback;
-  const suffix = fallback ? dim(` (${fallback})`) : "";
-  const answer = await question(`${message}${suffix} `);
-  return answer || fallback;
+function pad(text, width) {
+  const gap = width - visibleWidth(text);
+  return gap > 0 ? text + " ".repeat(gap) : text;
+}
+
+function termWidth() {
+  return stdout.columns || 80;
+}
+
+function termRows() {
+  return stdout.rows || 24;
 }
 
 /**
- * Numbered single-select. Returning an empty list means "nothing chosen", which
- * callers treat as a clean no-op rather than an error.
+ * Search-and-multi-select over a list of choices.
+ *
+ * The prompt an installer lives or dies by: typing filters, space toggles,
+ * enter confirms. A leading "Select all" row — and the `a` shortcut — make the
+ * whole registry selectable without fifteen space presses, which is what you
+ * want on a first run and never again.
  */
-export async function select(message, choices) {
+export function multiselect({ message, choices, initialSelected = [], hint, required = false }) {
+  if (!isInteractive()) {
+    throw new CliError(`"${message}" needs an interactive terminal`, {
+      hint: "Pass the choice explicitly instead, e.g. --skill <name> or --agent <name>.",
+    });
+  }
+  if (choices.length === 0) return [];
+
+  const ALL = Symbol("select-all");
+  const selected = new Set(
+    initialSelected.filter((value) => choices.some((choice) => choice.value === value))
+  );
+
+  let cursor = 0;
+  let filter = "";
+  let offset = 0;
+  let status = "";
+
+  const write = (line) => stdout.write(line);
+  const screen = createScreen(write);
+  const stop = readKeys();
+  const pageSize = Math.min(8, Math.max(3, termRows() - 9));
+
+  const visibleChoices = () =>
+    filter === ""
+      ? choices
+      : choices.filter((choice) =>
+          // `keywords` carries extra searchable text — a skill's full
+          // description, say — without widening what the list displays.
+          (choice.keywords ?? `${choice.label} ${choice.description ?? ""}`)
+            .toLowerCase()
+            .includes(filter.toLowerCase())
+        );
+
+  const rows = () => [
+    { value: ALL, label: "Select all" },
+    ...visibleChoices().map((choice) => ({ value: choice.value, label: choice.label, choice })),
+  ];
+
+  const paint = () => {
+    const all = rows();
+    if (cursor >= all.length) cursor = all.length - 1;
+    if (cursor < 0) cursor = 0;
+    if (cursor < offset) offset = cursor;
+    if (cursor >= offset + pageSize) offset = cursor - pageSize + 1;
+
+    const window = all.slice(offset, offset + pageSize);
+    const labelWidth = Math.min(
+      28,
+      Math.max(0, ...all.map((row) => visibleWidth(row.label)))
+    );
+    const pathWidth = Math.max(
+      0,
+      ...all.map((row) => visibleWidth(row.choice?.description ?? ""))
+    );
+    const lines = [];
+    lines.push(`${bold("?")} ${bold(message)}`);
+    if (hint) lines.push(`  ${dim(hint)}`);
+    lines.push(filter === "" ? "" : `  ${dim("filter:")} ${filter}${cyan("▌")}`);
+    if (lines[lines.length - 1] === "") lines.pop();
+
+    for (const row of window) {
+      const index = offset + window.indexOf(row);
+      const isCursor = index === cursor;
+
+      if (row.value === ALL) {
+        const every = visibleChoices().length > 0 && visibleChoices().every((c) => selected.has(c.value));
+        const marker = every ? cyan("◉") : dim("○");
+        lines.push(
+          `  ${isCursor ? cyan("❯") : " "} ${marker} ${isCursor ? bold("Select all") : "Select all"}`
+        );
+        continue;
+      }
+
+      const isSelected = selected.has(row.value);
+      const marker = isSelected ? cyan("◉") : dim("○");
+      const label = isCursor ? bold(pad(row.label, labelWidth)) : pad(row.label, labelWidth);
+      const path = row.choice?.description ? dim(`  ${row.choice.description}`) : "";
+      lines.push(
+        `  ${isCursor ? cyan("❯") : " "} ${marker} ${label}${path}`.slice(0, termWidth()).padEnd(
+          Math.min(termWidth(), labelWidth + pathWidth + 6)
+        )
+      );
+    }
+
+    if (all.length > window.length) {
+      lines.push(dim(`  … ${all.length - window.length} more`));
+    }
+    lines.push("");
+    lines.push(
+      status ||
+        dim(
+          selected.size === 0
+            ? "(none selected)"
+            : `(${selected.size} selected: ${[...selected].slice(0, 4).join(", ")}${selected.size > 4 ? ", …" : ""})`
+        )
+    );
+    screen.paint(lines);
+  };
+
+  const finish = (error) => {
+    stop();
+    screen.erase();
+    stdout.write("\x1B[?25h");
+    if (error) throw error;
+  };
+
+  stdout.write("\x1B[?25l"); // hide the cursor while navigating
+  paint();
+
+  return new Promise((resolve) => {
+    const toggleAll = () => {
+      const shown = visibleChoices();
+      const everySelected = shown.every((choice) => selected.has(choice.value));
+      if (everySelected) for (const choice of shown) selected.delete(choice.value);
+      else for (const choice of shown) selected.add(choice.value);
+    };
+
+    const onKeypress = (str, key) => {
+      const name = keyOf(key);
+      const all = rows();
+
+      if (name === KEY.ctrlC) {
+        finish();
+        process.exit(130);
+      }
+      if (name === KEY.escape) {
+        finish(new CliError("Aborted."));
+        return;
+      }
+      if (name === KEY.enter) {
+        if (required && selected.size === 0) {
+          status = yellow("! select at least one (enter to confirm)");
+          paint();
+          return;
+        }
+        finish();
+        resolve(choices.filter((choice) => selected.has(choice.value)));
+        return;
+      }
+      if (name === KEY.up || name === KEY.down) {
+        cursor = name === KEY.up ? cursor - 1 : cursor + 1;
+        if (cursor < 0) cursor = all.length - 1;
+        if (cursor >= all.length) cursor = 0;
+        status = "";
+        paint();
+        return;
+      }
+      if (name === KEY.space) {
+        const row = all[cursor];
+        if (row) {
+          if (row.value === ALL) toggleAll();
+          else if (selected.has(row.value)) selected.delete(row.value);
+          else selected.add(row.value);
+        }
+        status = "";
+        paint();
+        return;
+      }
+      if (name === KEY.backspace) {
+        filter = filter.slice(0, -1);
+        cursor = 0;
+        offset = 0;
+        status = "";
+        paint();
+        return;
+      }
+
+      // `a` toggles everything; anything else is filter input.
+      if (str === "a" && !key.ctrl && !key.meta) {
+        toggleAll();
+        status = "";
+        paint();
+        return;
+      }
+      if (str && !key.ctrl && !key.meta && visibleWidth(str) > 0) {
+        filter += str;
+        cursor = 0;
+        offset = 0;
+        status = "";
+        paint();
+      }
+    };
+
+    stdin.on("keypress", onKeypress);
+    stdin.resume();
+  });
+}
+
+/** Single-select, same repaint model with enter choosing the cursor row. */
+export function select({ message, choices, initialIndex = 0, hint }) {
   if (choices.length === 0) return [];
+
   if (!isInteractive()) {
-    throw new CliError(`${message} needs an interactive terminal`, {
-      hint: "Pass the choice explicitly instead, e.g. --skill <name> or <source>@<name>.",
+    throw new CliError(`"${message}" needs an interactive terminal`, {
+      hint: "Pass the choice explicitly as a flag instead.",
     });
   }
-  console.log(`\n${bold(message)}`);
-  choices.forEach((choice, index) => {
-    console.log(`  ${cyan(String(index + 1).padStart(2))}  ${choice.label}`);
+
+  let cursor = Math.min(Math.max(0, initialIndex), choices.length - 1);
+  let offset = 0;
+
+  const write = (line) => stdout.write(line);
+  const screen = createScreen(write);
+  const stop = readKeys();
+  const pageSize = Math.min(8, Math.max(3, termRows() - 8));
+
+  const paint = () => {
+    if (cursor >= choices.length) cursor = choices.length - 1;
+    if (cursor < offset) offset = cursor;
+    if (cursor >= offset + pageSize) offset = cursor - pageSize + 1;
+
+    const window = choices.slice(offset, offset + pageSize);
+    const labelWidth = Math.min(28, Math.max(0, ...choices.map((choice) => visibleWidth(choice.label))));
+
+    const lines = [`${bold("?")} ${bold(message)}`];
+    if (hint) lines.push(`  ${dim(hint)}`);
+
+    for (const choice of window) {
+      const index = offset + window.indexOf(choice);
+      const isCursor = index === cursor;
+      const label = isCursor ? bold(pad(choice.label, labelWidth)) : pad(choice.label, labelWidth);
+      const description = choice.description ? dim(`  ${choice.description}`) : "";
+      lines.push(`  ${isCursor ? cyan("❯") : " "} ${label}${description}`);
+    }
+
+    if (choices.length > window.length) {
+      lines.push(dim(`  … ${choices.length - window.length} more`));
+    }
+    lines.push("");
+    lines.push(dim(hint ? "" : "↑/↓ move · enter select"));
+    if (lines[lines.length - 1] === "") lines.pop();
+
+    screen.paint(lines);
+  };
+
+  stdout.write("\x1B[?25l");
+  paint();
+
+  return new Promise((resolve, reject) => {
+    const onKeypress = (str, key) => {
+      const name = keyOf(key);
+
+      if (name === KEY.ctrlC) {
+        stop();
+        screen.erase();
+        stdout.write("\x1B[?25h");
+        process.exit(130);
+      }
+      if (name === KEY.escape) {
+        stop();
+        screen.erase();
+        stdout.write("\x1B[?25h");
+        reject(new CliError("Aborted."));
+        return;
+      }
+      if (name === KEY.enter) {
+        stop();
+        screen.erase();
+        stdout.write("\x1B[?25h");
+        resolve([choices[cursor]]);
+        return;
+      }
+      if (name === KEY.up || name === KEY.down) {
+        cursor = name === KEY.up ? cursor - 1 : cursor + 1;
+        if (cursor < 0) cursor = choices.length - 1;
+        if (cursor >= choices.length) cursor = 0;
+        paint();
+      }
+    };
+
+    stdin.on("keypress", onKeypress);
+    stdin.resume();
   });
-  const answer = await question(`\nSelect (1-${choices.length}, comma-separated, blank to skip): `);
-  if (answer === "") return [];
-  const indices = answer
-    .split(",")
-    .map((part) => Number(part.trim()))
-    .filter((value) => Number.isInteger(value) && value >= 1 && value <= choices.length);
-  if (indices.length === 0) {
-    throw new CliError(`"${answer}" is not one of the listed options`);
+}
+
+/**
+ * Yes/no. Defaults to `defaultYes` on enter, and to that same value when there
+ * is no terminal at all.
+ */
+export async function confirm(message, { defaultYes = true } = {}) {
+  if (!isInteractive()) return defaultYes;
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+    const answer = (await rl.question(`${bold("?")} ${message} ${dim(suffix)} `)).trim().toLowerCase();
+    if (answer === "") return defaultYes;
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
   }
-  return indices.map((index) => choices[index - 1]);
 }
 
-/** Multi-select with a numbered header, used by `ds-cs add`. */
-export async function selectAll(message, choices) {
-  return select(message, choices);
+export async function promptText(message, fallback = "") {
+  if (!isInteractive()) return fallback;
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const suffix = fallback ? dim(` (${fallback})`) : "";
+    const answer = (await rl.question(`${bold("?")} ${message}${suffix} `)).trim();
+    return answer || fallback;
+  } finally {
+    rl.close();
+  }
 }
+
+export { select as selectOne, multiselect as selectMany };