@klhapp/skillmux 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0](https://github.com/klhq/skillmux/compare/v0.5.0...v0.6.0) (2026-07-24)
+
+
+### Added
+
+* **cli:** add line-oriented selection prompts ([b8579a4](https://github.com/klhq/skillmux/commit/b8579a47513a722c76d8826b80ca08155f2229f6))
+* **init:** add guided client and project setup ([c426502](https://github.com/klhq/skillmux/commit/c426502693755185a7d83f3c4b8c2b6b502bbb90))
+* **init:** detect installed clients for setup ([0c529f3](https://github.com/klhq/skillmux/commit/0c529f310de8bc96d18ddb6b25174d375478d9fa))
+* **init:** launch guided client setup in terminals ([9bd15ac](https://github.com/klhq/skillmux/commit/9bd15acfbad088732ad6d92927f0e16a2f57f44d))
+* **project:** add direct project management commands ([132e8af](https://github.com/klhq/skillmux/commit/132e8af0124ee75163161df16af83dc774b773a8))
+* **project:** add direct project management commands ([f36e2b3](https://github.com/klhq/skillmux/commit/f36e2b356f5f170c887734367cebb838acacc2e4))
+* **project:** add project init command ([3cf8ecc](https://github.com/klhq/skillmux/commit/3cf8ecc94fb16f0f8ed807976e36935e09918a4e))
+* **project:** harden project setup planning ([faff0e1](https://github.com/klhq/skillmux/commit/faff0e14a6d0a6268da3e01a33553efd9ede7d58))
+* **project:** upsert project setup state ([7a92e03](https://github.com/klhq/skillmux/commit/7a92e03e281b517dff45d11eef5714d0512fd952))
+* **setup:** guide machine and project choices ([2ef1010](https://github.com/klhq/skillmux/commit/2ef1010e8cb0d42b20a6f60980e7be0e28bf1e5f))
+* **target:** add advanced target management commands ([bde2069](https://github.com/klhq/skillmux/commit/bde206981bcb93c0b1be317ef7f1c8d6f6ece34c))
+* **target:** add advanced target management commands ([9e6a993](https://github.com/klhq/skillmux/commit/9e6a993643865b2134be05ba7306c671023f38ff))
+
+
+### Fixed
+
+* **cli:** keep guided init interactive and legacy-safe ([f6ae405](https://github.com/klhq/skillmux/commit/f6ae40564ed26b19ac464847b455d840d78daa93))
+* **project:** validate guided project inputs ([0bed954](https://github.com/klhq/skillmux/commit/0bed9543897e83860038d83620a7c3638540ca95))
+* **setup:** report client target prerequisites ([62fd8b8](https://github.com/klhq/skillmux/commit/62fd8b80444a37c8bcde403be95d8224b9776b0b))
+
 ## [0.5.0](https://github.com/klhq/skillmux/compare/v0.4.5...v0.5.0) (2026-07-24)
 
 

package/README.md

@@ -186,6 +186,11 @@ bun run src/cli.ts serve
 
 Optional — skip this if `resolve_skill` alone is enough (most setups). Use it once you want a small set of skills loaded *statically* in every agent that reads from a given directory, instead of routed on demand — see [Tiers](#tiers-routed-vs-pinned).
 
+Run `skillmux init` with no arguments in a terminal for guided setup. It checks
+the vault, preselects clients with concrete filesystem evidence, asks for core
+skills, shows one review, and applies after one confirmation. The wizard uses
+line-oriented prompts and does not take over the terminal screen.
+
 ### 1. Check the plan
 
 ```sh
@@ -213,10 +218,13 @@ skillmux init --client claude-code --client codex --core csv-formatter --yes
 ```
 
 Skillmux writes `skillmux.toml`, adds host-scoped targets, adopts each selected
-directory, and installs one managed discovery block in each client's durable
-instruction file. Existing manifest entries and instruction text stay intact.
-Without `--yes`, an interactive terminal asks about each change; a pipe or CI
-job must pass `--yes`.
+directory, and installs one managed discovery block for each client with a
+known safe durable instruction file. Other clients report manual setup.
+Existing manifest entries and instruction text stay intact.
+Explicit flags keep the command deterministic. Without `--yes`, an interactive
+terminal reviews the plan before applying; a pipe or CI job must pass `--yes`.
+Use `--no-instructions` to leave instruction files untouched or `--no-sync` to
+save setup for a later `skillmux sync`.
 
 Use direct targets when you want paths rather than clients:
 
@@ -244,7 +252,29 @@ skillmux init --client claude-code --migrate-full-vault \
 After conversion and `skillmux sync`, the client sees the selected core pins
 instead of every vault skill.
 
-### 3. Add or remove pins later
+### 3. Set up project-scoped skills
+
+From a project directory:
+
+```sh
+skillmux project init
+```
+
+The guided flow detects the Git root, suggests a project-group name, asks which
+configured clients should receive the group, and accepts project skill IDs.
+For automation:
+
+```sh
+skillmux project init ~/code/skillmux --name skillmux \
+  --client claude-code --client codex \
+  --skill sdd-tdd --skill code-context --yes
+```
+
+Re-running the command adds missing paths, skills, and target attachments
+without duplicating existing entries. Project setup runs `sync` unless
+`--no-sync` is supplied.
+
+### 4. Add or remove pins later
 
 `--core` seeds only the skill IDs you name. Without it, `init` preserves
 existing core pins and makes no guesses. Add another pin with:

package/docs/configuration.md

@@ -118,7 +118,7 @@ project_groups = ["repo1"]           # which [project.*] groups materialize into
 - `[project.<group>].paths` can list the same project's checkout on more than one machine (e.g. `["/home/alice/code/repo1", "/Users/alice/code/repo1"]`) — `sync` silently skips any entry that doesn't exist on the machine it's running on (see below), so one shared manifest can span machines with different checkout locations without needing per-machine manifests.
 - `[targets.<name>]` — one entry per adopted surface. `skillmux init --target <name> --yes` writes these and scopes newly added targets to the current hostname. Hand-editing is fine as long as `sync` is still allowed to own the directory (see below). An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean — a target only receives the specific groups it names, never every group in the manifest.
 
-**Pin/unpin without hand-editing.** `skillmux manifest pin`/`unpin` mutate `[core]`/`[project.*]` for you, validating with the same rules `sync`/`doctor` enforce (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
+**Pin/unpin without hand-editing.** `skillmux manifest pin`/`unpin` mutate `[core]`/`[project.*]` for you, validating with the same rules `sync` enforces (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
 
 ```sh
 skillmux manifest pin csv-formatter --core                                   # add to [core]
@@ -134,7 +134,7 @@ skillmux manifest unpin pdf-extractor --project repo1                        # r
 >
 > **Breaking change:** `[project.<group>].repos` has been renamed to `paths` — it was never required to be a git repository, just a local directory, and the old name collided in meaning with `skillmux install <repo>`'s unrelated git-source `repo` concept. A manifest still using `repos` fails to parse with an error pointing at `paths`; migrate by renaming the key (values are unchanged).
 
-Every `[core]`/`[project.*]` skill_id must resolve from the canonical `vault_path` — pinning a skill that only exists in a `local_vault_paths` entry (see below) fails `sync`/`doctor` with a distinct error, since the manifest is meant to be portable across machines and a machine-local override wouldn't exist elsewhere.
+Every `[core]`/`[project.*]` skill_id must resolve from the canonical `vault_path` — pinning a skill that only exists in a `local_vault_paths` entry (see below) fails `sync` with a distinct error, since the manifest is meant to be portable across machines and a machine-local override wouldn't exist elsewhere. `doctor` does not validate the manifest yet.
 
 ### Ownership marker
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Local read-only MCP server routing natural-language task queries to skills in a SKILL.md vault, with zero-loss delivery",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, rmSync } from "node:fs";
 import { hostname } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { generateDataset } from "./dataset-generator";
 
@@ -13,8 +13,10 @@ import { diagnose } from "./doctor";
 import { evalVault } from "./eval";
 import {
   assessClientReadiness,
+  detectInstalledClients,
   planClientSurfaces,
   resolveBuiltInTarget,
+  SUPPORTED_CLIENT_IDS,
   type ClientId,
   type ReadinessAxis,
 } from "./init-clients";
@@ -47,9 +49,15 @@ import {
   serializeManifest,
   unpinCore,
   unpinProject,
+  upsertProject,
+  updateProjectPaths,
+  updateProjectTargets,
   validateManifest,
+  writeManifestAtomic,
 } from "./manifest";
 import { downloadLocalModels } from "./models";
+import { resolveProjectDirectory, suggestProjectName } from "./project-setup";
+import { parseCommaList, promptMultiSelect, promptText, shouldUseWizard } from "./prompts";
 import { backfillEmbeddings, configure, rebuildIndex } from "./router-core";
 import { renderScanJson, renderScanText, scanExitCode, scanPath, type ScanSeverity } from "./scan";
 import {
@@ -91,6 +99,8 @@ const KNOWN_COMMANDS = [
   "index",
   "sync",
   "init",
+  "project",
+  "target",
   "report",
   "scan",
   "install",
@@ -191,6 +201,12 @@ async function main() {
       case "init":
         await runInit(rawArgv.slice(1), { isJson, dryRun: isDryRun });
         break;
+      case "project":
+        await runProject(subCommand, commandArgs, { isJson, dryRun: isDryRun });
+        break;
+      case "target":
+        await runTarget(subCommand, commandArgs, { isJson, dryRun: isDryRun });
+        break;
       case "report":
         await runReport(rawArgv.slice(1));
         break;
@@ -224,7 +240,7 @@ async function main() {
         const suggestion = suggestCorrection(command, KNOWN_COMMANDS);
         const msg = suggestion
           ? `Unknown command "${command}". Did you mean "${suggestion}"?`
-          : `usage: skillmux <serve|index|sync|init|report|scan|install|eval|doctor|which|manifest pin/unpin|local-vault init|config show|models download|calibrate generate-dataset>`;
+          : `usage: skillmux <serve|index|sync|init|project|target|report|scan|install|eval|doctor|which|manifest pin/unpin|local-vault init|config show|models download|calibrate generate-dataset>`;
         throw new Error(msg);
       }
     }
@@ -603,7 +619,13 @@ Setup:
   skillmux config init --vault <path> --yes
   skillmux init [--client <name>...] [--target <name>...] [--path <dir>]
                 [--vault <path>] [--core <skill_id>...]
-                [--migrate-full-vault] [--yes|--dry-run] [--json]
+                [--migrate-full-vault] [--no-instructions] [--no-sync]
+                [--interactive|--yes|--dry-run] [--json]
+  skillmux project init [path] [--name <group>] [--skill <skill_id>...]
+                [--client <name>...] [--target <name>...] [--no-sync]
+                [--interactive|--yes|--dry-run] [--json]
+  skillmux project <list|show|add-path|remove-path|pin|unpin|attach|detach>
+  skillmux target <list|show|add|remove>
 
 Init clients:
   claude-code, codex, gemini-cli, opencode, github-copilot, windsurf,
@@ -613,7 +635,7 @@ Init targets:
   agent-skills, claude-code, codex, custom
 
 Commands:
-  serve, index, sync, init, report, scan, install, eval, doctor, which,
+  serve, index, sync, init, project, target, report, scan, install, eval, doctor, which,
   manifest, local-vault, config, models, calibrate, context, completions`);
 }
 
@@ -713,6 +735,429 @@ async function runWhich(args: string[]): Promise<void> {
 }
 
 const MANIFEST_USAGE = "usage: skillmux manifest <pin|unpin> <skill_id> (--core | --project <group> [--path <path>...])";
+const PROJECT_INIT_USAGE =
+  "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--client <id>...] [--target <name>...] [--yes] [--no-sync]";
+
+interface ProjectInitArgs {
+  path: string;
+  name: string;
+  skills: string[];
+  clients: string[];
+  targets: string[];
+  yes: boolean;
+  sync: boolean;
+}
+
+function configuredTargetForSurface(
+  manifest: ReturnType<typeof parseManifest>,
+  surface: { targetName: string; path: string },
+): string | undefined {
+  if (manifest.targets[surface.targetName]) return surface.targetName;
+  return Object.entries(manifest.targets).find(
+    ([, target]) => expandHome(target.dir) === surface.path,
+  )?.[0];
+}
+
+function configuredTargetsForClients(
+  manifest: ReturnType<typeof parseManifest>,
+  clients: readonly string[],
+): string[] {
+  return planClientSurfaces(clients).surfaces.map((surface) => {
+    const target = configuredTargetForSurface(manifest, surface);
+    if (target) return target;
+    const client = surface.clients[0]!;
+    throw new Error(
+      `client target for "${client}" is not configured; run "skillmux init --client ${client} --yes" first`,
+    );
+  });
+}
+
+function parseProjectInitArgs(args: string[]): ProjectInitArgs {
+  let projectPath: string | undefined;
+  let name: string | undefined;
+  const skills: string[] = [];
+  const clients: string[] = [];
+  const targets: string[] = [];
+  let yes = false;
+  let sync = true;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--name") {
+      name = args[++i];
+      if (!name) throw new Error("--name requires a group name");
+    } else if (arg === "--skill") {
+      const skill = args[++i];
+      if (!skill) throw new Error("--skill requires a skill_id");
+      skills.push(skill);
+    } else if (arg === "--target") {
+      const target = args[++i];
+      if (!target) throw new Error("--target requires a name");
+      targets.push(target);
+    } else if (arg === "--client") {
+      const client = args[++i];
+      if (!client) throw new Error("--client requires a name");
+      clients.push(client);
+    } else if (arg === "--yes") {
+      yes = true;
+    } else if (arg === "--no-sync") {
+      sync = false;
+    } else if (arg === "--dry-run" || arg === "--json" || arg === "--interactive") {
+      continue;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`unknown project init option: ${arg}`);
+    } else if (projectPath) {
+      throw new Error(PROJECT_INIT_USAGE);
+    } else {
+      projectPath = arg;
+    }
+  }
+
+  const path = resolveProjectDirectory(projectPath ? expandHome(projectPath) : undefined);
+  return { path, name: name ?? suggestProjectName(basename(path)), skills, clients, targets, yes, sync };
+}
+
+async function runProject(
+  subCommand: string,
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): Promise<void> {
+  if (subCommand === "list" || subCommand === "show") {
+    const config = await loadConfig();
+    const vaultPath = expandHome(config.vault_path);
+    const manifestPath = resolveManifestPath(vaultPath);
+    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
+    const manifest = parseManifest(await Bun.file(manifestPath).text());
+    const names = subCommand === "show"
+      ? [args[0] ?? ""]
+      : Object.keys(manifest.project ?? {});
+    if (subCommand === "show" && !manifest.project?.[names[0]!]) {
+      throw new Error(`[project.${names[0]}] does not exist`);
+    }
+    const projects = names.map((name) => ({
+      name,
+      paths: manifest.project?.[name]!.paths ?? [],
+      skills: manifest.project?.[name]!.skills ?? [],
+      targets: Object.entries(manifest.targets)
+        .filter(([, target]) => target.project_groups.includes(name))
+        .map(([target]) => target),
+    }));
+    if (options.isJson) {
+      console.log(JSON.stringify({ schema_version: 1, projects }));
+    } else if (projects.length === 0) {
+      console.log("no project groups configured");
+    } else {
+      for (const project of projects) {
+        console.log(`${project.name}:`);
+        console.log(`  paths: ${project.paths.join(", ") || "(none)"}`);
+        console.log(`  skills: ${project.skills.join(", ") || "(none)"}`);
+        console.log(`  targets: ${project.targets.join(", ") || "(none)"}`);
+      }
+    }
+    return;
+  }
+  if (subCommand === "add-path" || subCommand === "remove-path") {
+    const group = args[0];
+    if (!group) throw new Error(`usage: skillmux project ${subCommand} <group> [path] --yes`);
+    const rawPath = args[1]?.startsWith("-") ? undefined : args[1];
+    const projectPath = resolveProjectDirectory(rawPath ? expandHome(rawPath) : undefined);
+    const yes = args.includes("--yes");
+    if (!existsSync(projectPath) || !lstatSync(projectPath).isDirectory()) {
+      throw new Error(`project path is not a directory: ${projectPath}`);
+    }
+    const config = await loadConfig();
+    const vaultPath = expandHome(config.vault_path);
+    const manifestPath = resolveManifestPath(vaultPath);
+    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
+    const manifest = parseManifest(await Bun.file(manifestPath).text());
+    const updated = updateProjectPaths(manifest, group, {
+      ...(subCommand === "add-path" ? { add: [projectPath] } : { remove: [projectPath] }),
+    });
+    validateManifest(updated, vaultPath, config.local_vault_paths.map(expandHome));
+    if (options.dryRun) {
+      console.log(`${subCommand}: [project.${group}] ${projectPath} (dry-run)`);
+      return;
+    }
+    if (!yes) {
+      if (!options.isJson && isInteractive()) {
+        if (!(await confirmAction(`${subCommand} ${projectPath} in [project.${group}]?`))) return;
+      } else {
+        throw new Error(`skillmux project ${subCommand} requires --yes when run non-interactively`);
+      }
+    }
+    writeManifestAtomic(manifestPath, updated);
+    console.log(`${subCommand}: [project.${group}] ${projectPath}`);
+    return;
+  }
+  if (subCommand === "pin" || subCommand === "unpin") {
+    const group = args[0];
+    const skills = args.slice(1).filter((arg) => !arg.startsWith("-"));
+    if (!group || skills.length === 0) {
+      throw new Error(`usage: skillmux project ${subCommand} <group> <skill_id>... --yes`);
+    }
+    const yes = args.includes("--yes");
+    const config = await loadConfig();
+    const vaultPath = expandHome(config.vault_path);
+    const manifestPath = resolveManifestPath(vaultPath);
+    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
+    let updated = parseManifest(await Bun.file(manifestPath).text());
+    for (const skill of skills) {
+      updated = subCommand === "pin"
+        ? pinProject(updated, skill, group)
+        : unpinProject(updated, skill, group);
+    }
+    validateManifest(updated, vaultPath, config.local_vault_paths.map(expandHome));
+    if (options.dryRun) {
+      console.log(`${subCommand}: [project.${group}] ${skills.join(", ")} (dry-run)`);
+      return;
+    }
+    if (!yes) {
+      if (!options.isJson && isInteractive()) {
+        if (!(await confirmAction(`${subCommand} ${skills.join(", ")} in [project.${group}]?`))) return;
+      } else {
+        throw new Error(`skillmux project ${subCommand} requires --yes when run non-interactively`);
+      }
+    }
+    writeManifestAtomic(manifestPath, updated);
+    console.log(`${subCommand}: [project.${group}] ${skills.join(", ")}`);
+    return;
+  }
+  if (subCommand === "attach" || subCommand === "detach") {
+    const group = args[0];
+    if (!group) throw new Error(`usage: skillmux project ${subCommand} <group> (--client <id>... | --target <name>...) --yes`);
+    const clients: string[] = [];
+    const requestedTargets: string[] = [];
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--client") {
+        const value = args[++i];
+        if (!value) throw new Error("--client requires a name");
+        clients.push(value);
+      } else if (args[i] === "--target") {
+        const value = args[++i];
+        if (!value) throw new Error("--target requires a name");
+        requestedTargets.push(value);
+      } else if (args[i] !== "--yes" && args[i] !== "--dry-run" && args[i] !== "--json") {
+        throw new Error(`unknown project ${subCommand} option: ${args[i]}`);
+      }
+    }
+    const config = await loadConfig();
+    const vaultPath = expandHome(config.vault_path);
+    const manifestPath = resolveManifestPath(vaultPath);
+    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
+    const manifest = parseManifest(await Bun.file(manifestPath).text());
+    const clientTargets = configuredTargetsForClients(manifest, clients);
+    const targets = [...new Set([...requestedTargets, ...clientTargets])];
+    if (targets.length === 0) {
+      throw new Error(`project ${subCommand} requires --client or --target`);
+    }
+    const updated = updateProjectTargets(manifest, group, {
+      ...(subCommand === "attach" ? { attach: targets } : { detach: targets }),
+    });
+    validateManifest(updated, vaultPath, config.local_vault_paths.map(expandHome));
+    if (options.dryRun) {
+      console.log(`${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`);
+      return;
+    }
+    if (!args.includes("--yes")) {
+      if (!options.isJson && isInteractive()) {
+        if (!(await confirmAction(`${subCommand} [project.${group}] to ${targets.join(", ")}?`))) return;
+      } else {
+        throw new Error(`skillmux project ${subCommand} requires --yes when run non-interactively`);
+      }
+    }
+    writeManifestAtomic(manifestPath, updated);
+    console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`);
+    return;
+  }
+  if (subCommand !== "init") throw new Error(PROJECT_INIT_USAGE);
+  let request = parseProjectInitArgs(args);
+  const guided = shouldUseWizard(args, {
+    interactive: isInteractive(),
+    json: options.isJson,
+    dryRun: options.dryRun,
+  });
+  if (!existsSync(request.path)) throw new Error(`project path does not exist: ${request.path}`);
+  if (!lstatSync(request.path).isDirectory()) {
+    throw new Error(`project path is not a directory: ${request.path}`);
+  }
+
+  const config = await loadConfig();
+  const vaultPath = expandHome(config.vault_path);
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  const manifestPath = resolveManifestPath(vaultPath);
+  if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
+  const manifest = parseManifest(await Bun.file(manifestPath).text());
+  if (guided) {
+    const name = await promptText("Project group", request.name);
+    const availableClients = SUPPORTED_CLIENT_IDS.filter((client) => {
+      const surface = planClientSurfaces([client]).surfaces[0];
+      return surface !== undefined && configuredTargetForSurface(manifest, surface) !== undefined;
+    });
+    const clients = await promptMultiSelect(
+      "Which clients should receive project skills?",
+      availableClients.map((client) => ({
+        value: client,
+        label: client,
+        selected: request.clients.length === 0 || request.clients.includes(client),
+      })),
+    );
+    const skills = parseCommaList(
+      await promptText("Project skill IDs, comma-separated", request.skills.join(",")),
+    );
+    request = { ...request, name, clients, skills };
+  }
+  const clientTargets = configuredTargetsForClients(manifest, request.clients);
+  const targets = [...new Set([...request.targets, ...clientTargets])];
+  const updated = upsertProject(manifest, {
+    name: request.name,
+    paths: [request.path],
+    skills: request.skills,
+    targets,
+  });
+  const { notes } = validateManifest(updated, vaultPath, localVaultPaths);
+  const plan = {
+    mode: "project",
+    project: request.name,
+    path: request.path,
+    skills: request.skills,
+    clients: request.clients,
+    targets,
+    sync: request.sync,
+    notes,
+  };
+
+  if (options.dryRun) {
+    console.log(options.isJson ? JSON.stringify({ schema_version: 1, plan }) : `project plan: ${JSON.stringify(plan)}`);
+    return;
+  }
+  if (!request.yes) {
+    if (!options.isJson && isInteractive()) {
+      if (guided) {
+        console.log("\nReview");
+        console.log(`  project: ${request.name}`);
+        console.log(`  path: ${request.path}`);
+        console.log(`  clients: ${request.clients.join(", ") || "(none)"}`);
+        console.log(`  skills: ${request.skills.join(", ") || "(none)"}`);
+        console.log(`  sync: ${request.sync ? "yes" : "no"}`);
+      }
+      if (!(await confirmAction(`Apply project setup for ${request.name} at ${request.path}?`))) {
+        console.log("project setup cancelled");
+        return;
+      }
+    } else {
+      throw new Error("skillmux project init requires --yes when run non-interactively");
+    }
+  }
+
+  writeManifestAtomic(manifestPath, updated);
+  if (request.sync) {
+    try {
+      await runSync([]);
+    } catch (error) {
+      throw new Error(
+        `project configuration was saved, but sync failed; fix the reported issue and run "skillmux sync": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+  if (options.isJson) {
+    console.log(JSON.stringify({ schema_version: 1, result: plan }));
+  } else {
+    console.log(`project "${request.name}" ready at ${request.path}`);
+  }
+}
+
+async function runTarget(
+  subCommand: string,
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): Promise<void> {
+  const config = await loadConfig();
+  const vaultPath = expandHome(config.vault_path);
+  const manifestPath = resolveManifestPath(vaultPath);
+  if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
+  const manifest = parseManifest(await Bun.file(manifestPath).text());
+
+  if (subCommand === "list" || subCommand === "show") {
+    const names = subCommand === "show" ? [args[0] ?? ""] : Object.keys(manifest.targets);
+    if (subCommand === "show" && !manifest.targets[names[0]!]) {
+      throw new Error(`target "${names[0]}" does not exist`);
+    }
+    const targets = names.map((name) => {
+      const target = manifest.targets[name]!;
+      const clients = SUPPORTED_CLIENT_IDS.filter((client) => {
+        const surface = planClientSurfaces([client]).surfaces[0];
+        return surface !== undefined && surface.path === expandHome(target.dir);
+      });
+      return { name, ...target, clients };
+    });
+    if (options.isJson) {
+      console.log(JSON.stringify({ schema_version: 1, targets }));
+    } else if (targets.length === 0) {
+      console.log("no targets configured");
+    } else {
+      for (const target of targets) {
+        console.log(`${target.name}:`);
+        console.log(`  dir: ${target.dir}`);
+        console.log(`  host: ${target.host ?? "(global)"}`);
+        console.log(`  clients: ${target.clients.join(", ") || "(custom)"}`);
+        console.log(`  projects: ${target.project_groups.join(", ") || "(none)"}`);
+      }
+    }
+    return;
+  }
+
+  if (subCommand === "add") {
+    const name = args[0];
+    const pathIndex = args.indexOf("--path");
+    const rawPath = pathIndex === -1 ? undefined : args[pathIndex + 1];
+    if (!name || !rawPath) throw new Error("usage: skillmux target add <name> --path <dir> --yes");
+    const path = expandHome(rawPath);
+    if (options.dryRun) {
+      const planned = planInitManifest(vaultPath, [{ name, dir: path }], []);
+      console.log(options.isJson
+        ? JSON.stringify({ schema_version: 1, target: planned.targets[name] })
+        : `target add: ${name} -> ${path} (dry-run)`);
+      return;
+    }
+    if (!args.includes("--yes")) {
+      if (!options.isJson && isInteractive()) {
+        if (!(await confirmAction(`Adopt target ${name} at ${path}?`))) return;
+      } else {
+        throw new Error("skillmux target add requires --yes when run non-interactively");
+      }
+    }
+    applyInit(vaultPath, [{ name, dir: path }]);
+    console.log(`target "${name}" added at ${path}`);
+    return;
+  }
+
+  if (subCommand === "remove") {
+    const name = args[0];
+    if (!name || !manifest.targets[name]) {
+      throw new Error(name ? `target "${name}" does not exist` : "usage: skillmux target remove <name> --yes");
+    }
+    if (options.dryRun) {
+      console.log(`target remove: ${name} (files preserved, dry-run)`);
+      return;
+    }
+    if (!args.includes("--yes")) {
+      if (!options.isJson && isInteractive()) {
+        if (!(await confirmAction(`Remove target ${name} from the manifest and preserve its files?`))) return;
+      } else {
+        throw new Error("skillmux target remove requires --yes when run non-interactively");
+      }
+    }
+    const targets = { ...manifest.targets };
+    delete targets[name];
+    writeManifestAtomic(manifestPath, { ...manifest, targets });
+    console.log(`target "${name}" removed from the manifest; files preserved at ${manifest.targets[name]!.dir}`);
+    return;
+  }
+
+  throw new Error("usage: skillmux target <list|show|add|remove>");
+}
 
 function parseManifestPinArgs(args: string[]): { skillId: string; core: boolean; project?: string; paths: string[] } {
   const skillId = args[0];
@@ -873,6 +1318,8 @@ function parseInitArgs(args: string[]): {
   coreSkillIds: string[];
   customPath?: string;
   migrateFullVault: boolean;
+  skipInstructions: boolean;
+  sync: boolean;
   vaultPath?: string;
   yes: boolean;
 } {
@@ -881,6 +1328,8 @@ function parseInitArgs(args: string[]): {
   const coreSkillIds: string[] = [];
   let customPath: string | undefined;
   let migrateFullVault = false;
+  let skipInstructions = false;
+  let sync = true;
   let vaultPath: string | undefined;
   let yes = false;
   for (let i = 0; i < args.length; i++) {
@@ -910,17 +1359,31 @@ function parseInitArgs(args: string[]): {
       if (!value) throw new Error("--core requires a skill_id");
       coreSkillIds.push(value);
       i++;
-    } else if (option === "--dry-run" || option === "--json") {
+    } else if (option === "--dry-run" || option === "--json" || option === "--interactive") {
       continue;
     } else if (option === "--migrate-full-vault") {
       migrateFullVault = true;
+    } else if (option === "--no-instructions") {
+      skipInstructions = true;
+    } else if (option === "--no-sync") {
+      sync = false;
     } else if (option === "--yes") {
       yes = true;
     } else {
       throw new Error(`unknown init option: ${option}`);
     }
   }
-  return { targets, clients, coreSkillIds, customPath, migrateFullVault, vaultPath, yes };
+  return {
+    targets,
+    clients,
+    coreSkillIds,
+    customPath,
+    migrateFullVault,
+    skipInstructions,
+    sync,
+    vaultPath,
+    yes,
+  };
 }
 
 async function runInit(
@@ -933,9 +1396,16 @@ async function runInit(
     coreSkillIds,
     customPath,
     migrateFullVault,
+    skipInstructions,
+    sync,
     vaultPath: requestedVaultPath,
     yes,
   } = parseInitArgs(args);
+  const guided = shouldUseWizard(args, {
+    interactive: isInteractive(),
+    json: options.isJson,
+    dryRun: options.dryRun,
+  });
   migrateLegacyPaths();
   const configPath = resolveConfigPath();
   let configPlan: ConfigInitPlan | undefined;
@@ -966,10 +1436,33 @@ async function runInit(
     throw new Error(vaultHealth.message);
   }
 
-  const clientPlan = planClientSurfaces(requestedClients, {
+  let selectedClients = requestedClients;
+  if (guided) {
+    const detected = detectInstalledClients({
+      codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
+    });
+    const evidence = new Map(detected.map((item) => [item.client, item.evidence]));
+    selectedClients = await promptMultiSelect(
+      "Which clients do you use?",
+      SUPPORTED_CLIENT_IDS.map((client) => ({
+        value: client,
+        label: client,
+        detail: evidence.has(client) ? `detected: ${evidence.get(client)}` : undefined,
+        selected: evidence.has(client) || requestedClients.includes(client),
+      })),
+    );
+  }
+  let selectedCoreSkillIds = coreSkillIds;
+  if (guided) {
+    selectedCoreSkillIds = parseCommaList(
+      await promptText("Core skill IDs to add, comma-separated", coreSkillIds.join(",")),
+    );
+  }
+
+  const clientPlan = planClientSurfaces(selectedClients, {
     codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
   });
-  const instructionPlan = planInstructionSetup(clientPlan.clients.map((client) => client.id), {
+  const instructionPlan = planInstructionSetup(skipInstructions ? [] : clientPlan.clients.map((client) => client.id), {
     codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
   });
   const instructionReadiness: Partial<Record<ClientId, ReadinessAxis>> = {};
@@ -1002,8 +1495,19 @@ async function runInit(
   const targetByPath = new Map(
     explicitSurfaceTargets.map((target) => [target.path, target.targetName] as const),
   );
+  const existingManifestPath = resolveManifestPath(vaultPath);
+  const existingManifest = existingManifestPath
+    ? parseManifest(await Bun.file(existingManifestPath).text())
+    : undefined;
   for (const surface of clientPlan.surfaces) {
-    if (!targetByPath.has(surface.path)) targetByPath.set(surface.path, surface.targetName);
+    if (!targetByPath.has(surface.path)) {
+      targetByPath.set(
+        surface.path,
+        existingManifest
+          ? configuredTargetForSurface(existingManifest, surface) ?? surface.targetName
+          : surface.targetName,
+      );
+    }
   }
   const candidatePaths = [
     ...new Set([
@@ -1068,7 +1572,7 @@ async function runInit(
   const hasChanges = !(
     requestedTargets.length === 0 &&
     !hasInstructionWrites &&
-    coreSkillIds.length === 0 &&
+    selectedCoreSkillIds.length === 0 &&
     !hasConfigWrite
   );
 
@@ -1108,7 +1612,7 @@ async function runInit(
       ...(candidate.state === "full-vault" ? { migrateFullVault: true } : {}),
     };
   });
-  const plannedManifest = planInitManifest(vaultPath, confirmedTargets, coreSkillIds);
+  const plannedManifest = planInitManifest(vaultPath, confirmedTargets, selectedCoreSkillIds);
   const serializedPlan = {
     vault_path: vaultPath,
     config: configPlan
@@ -1171,19 +1675,38 @@ async function runInit(
 
   if (!yes) {
     if (!options.isJson && isInteractive()) {
-      const prompts = [
-        ...confirmedTargets.map((target) => `Adopt ${target.name} at ${target.dir}?`),
-        ...instructionPlan.changes
-          .filter((change) => change.status !== "unchanged")
-          .map((change) => `${change.status} instruction file ${change.path}?`),
-        ...(hasConfigWrite ? [`Create machine config ${configPath}?`] : []),
-        ...(coreSkillIds.length > 0 ? [`Pin core skills: ${coreSkillIds.join(", ")}?`] : []),
-      ];
-      for (const prompt of prompts) {
-        if (!(await confirmAction(prompt))) {
-          console.log("init cancelled; nothing written");
+      if (guided) {
+        console.log("\nReview");
+        console.log(`  clients: ${selectedClients.join(", ") || "(none)"}`);
+        console.log(
+          `  targets: ${confirmedTargets.map((target) => `${target.name} -> ${target.dir}`).join(", ") || "(none)"}`,
+        );
+        console.log(
+          `  instructions: ${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} file(s)`,
+        );
+        console.log(`  core: ${plannedManifest.core.skills.join(", ") || "(none)"}`);
+        console.log(`  sync: ${sync ? "yes" : "no"}`);
+        if (!(await confirmAction("Apply this setup plan?"))) {
+          console.log("init cancelled");
           return;
         }
+      } else {
+        const prompts = [
+          ...confirmedTargets.map((target) => `Adopt ${target.name} at ${target.dir}?`),
+          ...instructionPlan.changes
+            .filter((change) => change.status !== "unchanged")
+            .map((change) => `${change.status} instruction file ${change.path}?`),
+          ...(hasConfigWrite ? [`Create machine config ${configPath}?`] : []),
+          ...(selectedCoreSkillIds.length > 0
+            ? [`Pin core skills: ${selectedCoreSkillIds.join(", ")}?`]
+            : []),
+        ];
+        for (const prompt of prompts) {
+          if (!(await confirmAction(prompt))) {
+            console.log("init cancelled; nothing written");
+            return;
+          }
+        }
       }
     } else {
       throw new Error(
@@ -1214,7 +1737,7 @@ async function runInit(
     if (configCreated && configPlan) rollbackConfigInit(configPlan);
   };
 
-  if (confirmedTargets.length === 0 && coreSkillIds.length === 0) {
+  if (confirmedTargets.length === 0 && selectedCoreSkillIds.length === 0) {
     applyAdditional();
   } else {
     applyInit(
@@ -1226,7 +1749,7 @@ async function runInit(
             rollback: rollbackAdditional,
           }
         : undefined,
-      coreSkillIds,
+      selectedCoreSkillIds,
     );
   }
 
@@ -1253,16 +1776,17 @@ async function runInit(
   if (configCreated) console.log(`created ${configPath}`);
   if (confirmedTargets.length > 0) {
     console.log(`\nwrote ${join(vaultPath, "skillmux.toml")}, adopted: ${confirmedTargets.map((t) => t.name).join(", ")}`);
-  } else if (coreSkillIds.length > 0) {
+  } else if (selectedCoreSkillIds.length > 0) {
     console.log(`\nwrote ${join(vaultPath, "skillmux.toml")}`);
   }
   if (plannedManifest.core.skills.length === 0 && confirmedTargets.length > 0) {
     console.log("next: skillmux manifest pin <skill_id> --core");
   }
   if (confirmedTargets.length > 0) console.log("next: skillmux sync");
-  if (requestedClients.length === 0 || requestedClients.includes("skillmux-mcp")) {
+  if (selectedClients.length === 0 || selectedClients.includes("skillmux-mcp")) {
     console.log(`\n${printLastMile()}`);
   }
+  if (guided && sync && confirmedTargets.length > 0) await runSync([]);
 }
 
 function parseReportArgs(args: string[]): { server?: string; db?: string; since?: string } {

package/src/completions.ts

@@ -8,7 +8,7 @@ _skillmux_completions() {
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
-    opts="context config calibrate serve index sync init report scan install eval doctor which manifest local-vault models completions --context --server --json --allow-insecure --verbose --dry-run --help"
+    opts="context config calibrate serve index sync init project target report scan install eval doctor which manifest local-vault models completions --context --server --json --allow-insecure --verbose --dry-run --help"
 
     if [ "$COMP_CWORD" -eq 1 ]; then
         COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
@@ -31,6 +31,12 @@ _skillmux_completions() {
         manifest)
             COMPREPLY=( $(compgen -W "pin unpin" -- "$cur") )
             ;;
+        project)
+            COMPREPLY=( $(compgen -W "init list show add-path remove-path pin unpin attach detach" -- "$cur") )
+            ;;
+        target)
+            COMPREPLY=( $(compgen -W "list show add remove" -- "$cur") )
+            ;;
         local-vault)
             COMPREPLY=( $(compgen -W "init" -- "$cur") )
             ;;
@@ -42,7 +48,10 @@ _skillmux_completions() {
             ;;
     esac
     if [ "\${COMP_WORDS[1]}" = "init" ] && [ "\${#COMPREPLY[@]}" -eq 0 ]; then
-        COMPREPLY=( $(compgen -W "--client --target --path --vault --core --migrate-full-vault --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--client --target --path --vault --core --migrate-full-vault --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+    fi
+    if [ "\${COMP_WORDS[1]}" = "project" ] && [ "\${COMP_WORDS[2]}" = "init" ]; then
+        COMPREPLY=( $(compgen -W "--name --skill --client --target --no-sync --interactive --yes --dry-run --json" -- "$cur") )
     fi
 }
 complete -F _skillmux_completions skillmux
@@ -61,6 +70,8 @@ _skillmux() {
         'index:Rebuild local search index'
         'sync:Synchronize vault skills'
         'init:Initialize project targets'
+        'project:Configure project-scoped skills'
+        'target:Manage advanced skill-delivery targets'
         'report:Generate usage stats'
         'scan:Audit skills for issues'
         'install:Install skills into vault'
@@ -82,9 +93,28 @@ _skillmux() {
           '--vault[vault directory]:directory:_directories' \
           '*--core[seed a core skill]:skill id:' \
           '--migrate-full-vault[convert a full-vault symlink to managed pins]' \
+          '--no-instructions[skip managed instruction files]' \
+          '--no-sync[save setup without synchronizing targets]' \
+          '--interactive[force guided setup]' \
+          '--yes[apply without prompts]' \
+          '--dry-run[print the plan without writing]' \
+          '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "project" && "$words[3]" == "init" ]]; then
+        _arguments \
+          '1:project directory:_directories' \
+          '--name[project group name]:group:' \
+          '*--skill[project skill]:skill id:' \
+          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \
+          '*--target[select an advanced target]:target:' \
+          '--no-sync[save setup without synchronizing targets]' \
+          '--interactive[force guided setup]' \
           '--yes[apply without prompts]' \
           '--dry-run[print the plan without writing]' \
           '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "project" && CURRENT == 3 ]]; then
+        _values 'project command' init list show add-path remove-path pin unpin attach detach
+    elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
+        _values 'target command' list show add remove
     fi
 }
 _skillmux "$@"
@@ -98,6 +128,9 @@ complete -c skillmux -n "__fish_use_subcommand" -a context -d "Manage connection
 complete -c skillmux -n "__fish_use_subcommand" -a config -d "Manage configuration"
 complete -c skillmux -n "__fish_use_subcommand" -a calibrate -d "Manage policy calibration"
 complete -c skillmux -n "__fish_use_subcommand" -a serve -d "Start MCP server"
+complete -c skillmux -n "__fish_use_subcommand" -a init -d "Configure this machine and its clients"
+complete -c skillmux -n "__fish_use_subcommand" -a project -d "Configure project-scoped skills"
+complete -c skillmux -n "__fish_use_subcommand" -a target -d "Manage advanced skill-delivery targets"
 complete -c skillmux -n "__fish_use_subcommand" -a completions -d "Generate shell completions"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -d "Select a client"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a target"
@@ -105,9 +138,21 @@ complete -c skillmux -n "__fish_seen_subcommand_from init" -l path -r -d "Custom
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l vault -r -d "Vault directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l core -x -d "Seed a core skill"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l migrate-full-vault -d "Convert a full-vault symlink"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-instructions -d "Skip managed instruction files"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-sync -d "Save without synchronizing"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l interactive -d "Force guided setup"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l yes -d "Apply without prompts"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l dry-run -d "Print the plan without writing"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l json -d "Emit a JSON envelope"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -a "init list show add-path remove-path pin unpin attach detach" -d "Manage projects"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l name -x -d "Project group name"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l skill -x -d "Project skill"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity" -d "Select a client"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced target"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l no-sync -d "Save without synchronizing"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l interactive -d "Force guided setup"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
 `;
   }
 

package/src/init-clients.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -17,6 +18,11 @@ export const SUPPORTED_CLIENT_IDS = [
 export type ClientId = (typeof SUPPORTED_CLIENT_IDS)[number];
 export type DeliveryMode = "managed-pins" | "full-vault" | "mcp";
 
+export interface DetectedClient {
+  client: ClientId;
+  evidence: string;
+}
+
 interface ClientDefinition {
   id: ClientId;
   surfaceId?: "agent-skills" | "claude-code" | "codex" | "antigravity";
@@ -69,6 +75,31 @@ const CLIENTS: Record<ClientId, ClientDefinition> = {
   "skillmux-mcp": { id: "skillmux-mcp", deliveryMode: "mcp" },
 };
 
+export function detectInstalledClients(
+  options: {
+    home?: string;
+    codexHome?: string;
+    exists?: (path: string) => boolean;
+  } = {},
+): DetectedClient[] {
+  const home = options.home ?? homedir();
+  const codexHome = options.codexHome ?? join(home, ".codex");
+  const exists = options.exists ?? existsSync;
+  const candidates: Array<[ClientId, string]> = [
+    ["claude-code", join(home, ".claude")],
+    ["codex", codexHome],
+    ["gemini-cli", join(home, ".gemini")],
+    ["opencode", join(home, ".config", "opencode")],
+    ["github-copilot", join(home, ".config", "github-copilot")],
+    ["windsurf", join(home, ".codeium", "windsurf")],
+    ["goose", join(home, ".config", "goose")],
+    ["hermes", join(home, ".hermes")],
+  ];
+  return candidates
+    .filter(([, evidence]) => exists(evidence))
+    .map(([client, evidence]) => ({ client, evidence }));
+}
+
 function surfacePath(
   surfaceId: NonNullable<ClientDefinition["surfaceId"]>,
   options: { home: string; codexHome?: string },

package/src/manifest.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { expandHome } from "./config";
@@ -32,7 +32,7 @@ const targetSchema = z.object({
 const manifestSchema = z.object({
   core: z.object({ skills: z.array(skillIdSchema) }).strict(),
   project: z.record(groupNameSchema, projectGroupSchema).optional(),
-  targets: z.record(groupNameSchema, targetSchema),
+  targets: z.record(groupNameSchema, targetSchema).default({}),
 }).strict();
 
 export type ProjectGroup = z.infer<typeof projectGroupSchema>;
@@ -94,6 +94,16 @@ export function serializeManifest(manifest: Manifest): string {
   return `${sections.join("\n\n")}\n`;
 }
 
+export function writeManifestAtomic(path: string, manifest: Manifest): void {
+  const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, serializeManifest(manifest), "utf8");
+    renameSync(temporaryPath, path);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}
+
 function findExistingPin(manifest: Manifest, skillId: string): string | null {
   if (manifest.core.skills.includes(skillId)) return "[core]";
   for (const [groupName, group] of Object.entries(manifest.project ?? {})) {
@@ -167,6 +177,95 @@ export function unpinProject(manifest: Manifest, skillId: string, group: string)
   };
 }
 
+export interface UpsertProjectOptions {
+  name: string;
+  paths: string[];
+  skills: string[];
+  targets: string[];
+}
+
+export function upsertProject(manifest: Manifest, options: UpsertProjectOptions): Manifest {
+  if (!groupNameSchema.safeParse(options.name).success) {
+    throw new Error(
+      `invalid group name "${options.name}" — must match /^[a-z][a-z0-9_-]*$/ (max 64 chars)`,
+    );
+  }
+
+  const existingGroup = manifest.project?.[options.name] ?? { paths: [], skills: [] };
+  for (const skillId of options.skills) {
+    if (!skillIdSchema.safeParse(skillId).success) {
+      throw new Error(`invalid skill ID "${skillId}"`);
+    }
+    if (existingGroup.skills.includes(skillId)) continue;
+    const existing = findExistingPin(manifest, skillId);
+    if (existing) throw new Error(`skill "${skillId}" already pinned in ${existing}`);
+  }
+
+  const targets = { ...manifest.targets };
+  for (const targetName of options.targets) {
+    const target = targets[targetName];
+    if (!target) throw new Error(`target "${targetName}" does not exist`);
+    targets[targetName] = {
+      ...target,
+      project_groups: [...new Set([...target.project_groups, options.name])],
+    };
+  }
+
+  return {
+    ...manifest,
+    project: {
+      ...manifest.project,
+      [options.name]: {
+        paths: [...new Set([...existingGroup.paths, ...options.paths])],
+        skills: [...new Set([...existingGroup.skills, ...options.skills])],
+      },
+    },
+    targets,
+  };
+}
+
+export function updateProjectPaths(
+  manifest: Manifest,
+  group: string,
+  changes: { add?: string[]; remove?: string[] },
+): Manifest {
+  const existingGroup = manifest.project?.[group];
+  if (!existingGroup) throw new Error(`[project.${group}] does not exist`);
+  const removed = new Set(changes.remove ?? []);
+  const paths = [...new Set([...existingGroup.paths, ...(changes.add ?? [])])]
+    .filter((path) => !removed.has(path));
+  return {
+    ...manifest,
+    project: {
+      ...manifest.project,
+      [group]: { ...existingGroup, paths },
+    },
+  };
+}
+
+export function updateProjectTargets(
+  manifest: Manifest,
+  group: string,
+  changes: { attach?: string[]; detach?: string[] },
+): Manifest {
+  if (!manifest.project?.[group]) throw new Error(`[project.${group}] does not exist`);
+  const attach = new Set(changes.attach ?? []);
+  const detach = new Set(changes.detach ?? []);
+  const requested = new Set([...attach, ...detach]);
+  for (const target of requested) {
+    if (!manifest.targets[target]) throw new Error(`target "${target}" does not exist`);
+  }
+  return {
+    ...manifest,
+    targets: Object.fromEntries(Object.entries(manifest.targets).map(([name, target]) => {
+      let groups = target.project_groups;
+      if (attach.has(name)) groups = [...new Set([...groups, group])];
+      if (detach.has(name)) groups = groups.filter((item) => item !== group);
+      return [name, { ...target, project_groups: groups }];
+    })),
+  };
+}
+
 export interface ManifestValidationResult {
   notes: string[];
 }

package/src/output.ts

@@ -110,12 +110,11 @@ export function suggestCorrection(input: string, candidates: string[]): string |
   return bestMatch;
 }
 
-export function isInteractive(): boolean {
-  return (
-    process.stdout.isTTY === true &&
-    !process.env.NO_COLOR &&
-    process.env.TERM !== "dumb"
-  );
+export function isInteractive(
+  env: NodeJS.ProcessEnv = process.env,
+  stdoutIsTTY = process.stdout.isTTY,
+): boolean {
+  return stdoutIsTTY === true && env.TERM !== "dumb";
 }
 
 export function renderTargetBanner(target: ResolvedTarget): void {

package/src/project-setup.ts

@@ -0,0 +1,36 @@
+import { resolve } from "node:path";
+
+interface ResolveProjectDirectoryOptions {
+  cwd?: string;
+  findGitRoot?: (cwd: string) => string | null;
+}
+
+function findGitRoot(cwd: string): string | null {
+  const result = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return null;
+  const root = result.stdout.toString().trim();
+  return root || null;
+}
+
+export function resolveProjectDirectory(
+  explicitPath?: string,
+  options: ResolveProjectDirectoryOptions = {},
+): string {
+  const cwd = options.cwd ?? process.cwd();
+  if (explicitPath) return resolve(explicitPath);
+  const gitRoot = (options.findGitRoot ?? findGitRoot)(cwd);
+  return resolve(gitRoot ?? cwd);
+}
+
+export function suggestProjectName(directoryName: string): string {
+  const slug = directoryName
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  const prefixed = /^[a-z]/.test(slug) ? slug : `project-${slug || "workspace"}`;
+  return prefixed.slice(0, 64).replace(/-+$/g, "");
+}

package/src/prompts.ts

@@ -0,0 +1,69 @@
+import { createInterface } from "node:readline/promises";
+
+export interface SelectOption<T extends string> {
+  value: T;
+  label: string;
+  detail?: string;
+  selected?: boolean;
+}
+
+export function parseNumberSelection(input: string, optionCount: number): number[] {
+  if (input.trim() === "") return [];
+  const indexes = input.split(",").map((part) => {
+    const choice = Number(part.trim());
+    if (!Number.isInteger(choice) || choice < 1 || choice > optionCount) {
+      throw new Error(`select numbers between 1 and ${optionCount}, separated by commas`);
+    }
+    return choice - 1;
+  });
+  return [...new Set(indexes)].sort((a, b) => a - b);
+}
+
+export function parseCommaList(input: string): string[] {
+  return [...new Set(input.split(",").map((value) => value.trim()).filter(Boolean))];
+}
+
+export function shouldUseWizard(
+  args: readonly string[],
+  mode: { interactive: boolean; json: boolean; dryRun: boolean },
+): boolean {
+  if (!mode.interactive || mode.json || mode.dryRun || args.includes("--yes")) return false;
+  if (args.includes("--interactive")) return true;
+  return args.length === 0;
+}
+
+export async function promptMultiSelect<T extends string>(
+  question: string,
+  options: readonly SelectOption<T>[],
+): Promise<T[]> {
+  console.log(`\n${question}`);
+  options.forEach((option, index) => {
+    const checked = option.selected ? "x" : " ";
+    const detail = option.detail ? `  ${option.detail}` : "";
+    console.log(`  ${index + 1}. [${checked}] ${option.label}${detail}`);
+  });
+  const defaults = options
+    .map((option, index) => option.selected ? String(index + 1) : "")
+    .filter(Boolean)
+    .join(",");
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaults ? ` [${defaults}]` : "";
+    const answer = await readline.question(`Select numbers, comma-separated${suffix}: `);
+    const selection = answer.trim() === "" && defaults ? defaults : answer;
+    return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
+  } finally {
+    readline.close();
+  }
+}
+
+export async function promptText(question: string, defaultValue = ""): Promise<string> {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    const answer = (await readline.question(`${question}${suffix}: `)).trim();
+    return answer || defaultValue;
+  } finally {
+    readline.close();
+  }
+}