skilld 1.2.3 → 1.4.0

package/dist/cli.mjs

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
+import { c as getOAuthProviderList, i as getAvailableModels, l as loginOAuthProvider, o as getModelName, t as detectImportedPackages, u as logoutOAuthProvider } from "./_chunks/agent.mjs";
 import { i as getPackageDbPath, o as getCacheDir, t as CACHE_DIR } from "./_chunks/config.mjs";
 import "./_chunks/sanitize.mjs";
 import "./_chunks/cache.mjs";
 import "./_chunks/yaml.mjs";
 import "./_chunks/markdown.mjs";
-import { a as semverGt, n as getSharedSkillsDir, r as mapInsert } from "./_chunks/shared.mjs";
+import { n as getSharedSkillsDir, o as semverGt, r as mapInsert } from "./_chunks/shared.mjs";
 import { r as fetchNpmRegistryMeta, t as fetchLatestVersion } from "./_chunks/sources.mjs";
-import { a as targets, i as getAgentVersion } from "./_chunks/detect.mjs";
+import { a as targets, i as getAgentVersion, r as detectTargetAgent, t as detectInstalledAgents } from "./_chunks/detect.mjs";
 import { o as unlinkSkillFromAgents } from "./_chunks/prompts.mjs";
-import { i as getAvailableModels, t as detectImportedPackages } from "./_chunks/agent.mjs";
-import { C as hasCompletedWizard, O as updateConfig, T as readConfig, _ as requireInteractive, b as version, c as timeAgo, d as getInstalledGenerators, f as getRepoHint, g as relativeTime, h as promptForAgent, i as formatSource, l as timedSpinner, m as isInteractive, p as introLine, u as formatStatus, v as resolveAgent, w as hasConfig, x as defaultFeatures, y as sharedArgs } from "./_chunks/formatting.mjs";
+import { S as readConfig, T as updateConfig, _ as version, a as getRepoHint, b as hasCompletedWizard, c as isInteractive, d as pickModel, f as promptForAgent, g as sharedArgs, h as resolveAgent, i as getInstalledGenerators, l as isRunningInsideAgent, m as requireInteractive, n as OAUTH_NOTE, o as guard, p as relativeTime, r as formatStatus, s as introLine, t as NO_MODELS_MESSAGE, u as menuLoop, v as defaultFeatures, x as hasConfig } from "./_chunks/cli-helpers.mjs";
 import { c as removeLockEntry, i as iterateSkills, n as getSkillsDir, o as parsePackages, r as isOutdated, t as getProjectState } from "./_chunks/skills.mjs";
+import { c as timeAgo, i as formatSource, l as timedSpinner } from "./_chunks/formatting.mjs";
 import { join, resolve } from "pathe";
 import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
@@ -19,117 +20,214 @@ import * as p from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
 //#region src/commands/config.ts
 async function configCommand() {
-	const config = readConfig();
-	const features = config.features ?? defaultFeatures;
-	const enabledCount = Object.values(features).filter(Boolean).length;
-	const action = await p.select({
+	const initConfig = readConfig();
+	const agentId = initConfig.agent || detectTargetAgent() || void 0;
+	const cyan = (s) => `\x1B[36m${s}\x1B[90m`;
+	const modelLabel = initConfig.skipLlm ? "skip" : initConfig.model ? cyan(getModelName(initConfig.model)) : "auto";
+	const agentLabel = agentId && targets[agentId] ? cyan(targets[agentId].displayName) : "auto-detect";
+	p.note(`\x1B[90mFetch docs → Enhance with ${modelLabel} → Install to ${agentLabel}\x1B[0m`, "How skilld works");
+	await menuLoop({
 		message: "Settings",
-		options: [
-			{
-				label: "Change features",
-				value: "features",
-				hint: `${enabledCount}/4 enabled`
-			},
-			{
-				label: "Change model",
-				value: "model",
-				hint: config.model || "auto"
-			},
-			{
-				label: "Change agent",
-				value: "agent",
-				hint: config.agent || "auto-detect"
+		options: () => {
+			const config = readConfig();
+			const features = config.features ?? defaultFeatures;
+			const enabledCount = Object.values(features).filter(Boolean).length;
+			const modelHint = config.skipLlm ? "disabled" : config.model ? getModelName(config.model) : "auto";
+			const connectedOAuth = getOAuthProviderList().filter((pr) => pr.loggedIn).length;
+			const oauthHint = connectedOAuth > 0 ? `${connectedOAuth} connected` : "none";
+			return [
+				{
+					label: "Data sources",
+					value: "features",
+					hint: `${enabledCount}/4 enabled · issues, releases, search, discussions`
+				},
+				{
+					label: "OAuth providers",
+					value: "oauth",
+					hint: `${oauthHint} · pi-ai direct API`
+				},
+				{
+					label: "Enhancement model",
+					value: "model",
+					hint: `${modelHint} · rewrites SKILL.md with best practices`
+				},
+				{
+					label: "Target agent",
+					value: "agent",
+					hint: `${config.agent || "auto-detect"} · where skills are installed`
+				}
+			];
+		},
+		onSelect: async (action) => {
+			switch (action) {
+				case "features": {
+					const features = readConfig().features ?? defaultFeatures;
+					const selected = guard(await p.multiselect({
+						message: "Data sources",
+						options: [
+							{
+								label: "Semantic + token search",
+								value: "search",
+								hint: "local query engine to cut token costs and speed up grep"
+							},
+							{
+								label: "Release notes",
+								value: "releases",
+								hint: "track changelogs for installed packages"
+							},
+							{
+								label: "GitHub issues",
+								value: "issues",
+								hint: "surface common problems and solutions"
+							},
+							{
+								label: "GitHub discussions",
+								value: "discussions",
+								hint: "include Q&A and community knowledge"
+							}
+						],
+						initialValues: Object.entries(features).filter(([, v]) => v).map(([k]) => k),
+						required: false
+					}));
+					updateConfig({ features: {
+						search: selected.includes("search"),
+						issues: selected.includes("issues"),
+						discussions: selected.includes("discussions"),
+						releases: selected.includes("releases")
+					} });
+					p.log.success(`Data sources updated: ${selected.length} enabled`);
+					break;
+				}
+				case "oauth":
+					await configureOAuth();
+					break;
+				case "model":
+					await configureModel();
+					break;
+				case "agent": {
+					const config = readConfig();
+					const agentChoice = guard(await p.select({
+						message: "Target agent — where should skills be installed?",
+						options: [{
+							label: "Auto-detect",
+							value: ""
+						}, ...Object.entries(targets).map(([id, a]) => ({
+							label: a.displayName,
+							value: id,
+							hint: a.skillsDir
+						}))],
+						initialValue: config.agent || ""
+					}));
+					updateConfig({ agent: agentChoice || void 0 });
+					p.log.success(agentChoice ? `Target agent set to ${agentChoice}` : "Target agent will be auto-detected");
+					break;
+				}
 			}
-		]
-	});
-	if (p.isCancel(action)) {
-		p.cancel("Cancelled");
-		return;
-	}
-	switch (action) {
-		case "features": {
-			const selected = await p.multiselect({
-				message: "Enable features",
-				options: [
-					{
-						label: "Semantic + token search",
-						value: "search",
-						hint: "local query engine to cut token costs and speed up grep"
-					},
-					{
-						label: "Release notes",
-						value: "releases",
-						hint: "track changelogs for installed packages"
-					},
-					{
-						label: "GitHub issues",
-						value: "issues",
-						hint: "surface common problems and solutions"
-					},
-					{
-						label: "GitHub discussions",
-						value: "discussions",
-						hint: "include Q&A and community knowledge"
-					}
-				].map((f) => ({
-					label: f.label,
-					value: f.value,
-					hint: f.hint
-				})),
-				initialValues: Object.entries(features).filter(([, v]) => v).map(([k]) => k),
-				required: false
-			});
-			if (p.isCancel(selected)) return;
-			updateConfig({ features: {
-				search: selected.includes("search"),
-				issues: selected.includes("issues"),
-				discussions: selected.includes("discussions"),
-				releases: selected.includes("releases")
-			} });
-			p.log.success(`Features updated: ${selected.length} enabled`);
-			break;
 		}
-		case "model": {
-			const available = await getAvailableModels();
-			if (available.length === 0) {
-				p.log.warn("No LLM CLIs found");
+	});
+}
+async function configureOAuth() {
+	p.note(OAUTH_NOTE, "How OAuth works");
+	await menuLoop({
+		message: "OAuth providers",
+		options: () => {
+			return getOAuthProviderList().map((pr) => ({
+				label: pr.name,
+				value: pr.id,
+				hint: pr.loggedIn ? "\x1B[32mconnected\x1B[0m" : "not connected"
+			}));
+		},
+		onSelect: async (providerId) => {
+			const pr = getOAuthProviderList().find((p2) => p2.id === providerId);
+			if (!pr) return;
+			if (pr.loggedIn) {
+				if (guard(await p.select({
+					message: pr.name,
+					options: [{
+						label: "Disconnect",
+						value: "disconnect"
+					}, {
+						label: "Back",
+						value: "back"
+					}]
+				})) === "disconnect") {
+					logoutOAuthProvider(providerId);
+					p.log.success(`Disconnected from ${pr.name}`);
+				}
 				return;
 			}
-			const model = await p.select({
-				message: "Select default model",
-				options: [{
-					label: "Auto (prompt each time)",
-					value: ""
-				}, ...available.map((m) => ({
-					label: m.recommended ? `${m.name} (Recommended)` : m.name,
-					value: m.id,
-					hint: m.hint
-				}))],
-				initialValue: config.model || ""
+			const spinner = p.spinner();
+			spinner.start("Connecting...");
+			const success = await loginOAuthProvider(providerId, {
+				onAuth: (url, instructions) => {
+					spinner.stop("Open this URL in your browser:");
+					p.log.info(`  \x1B[36m${url}\x1B[0m`);
+					if (instructions) p.log.info(`  \x1B[90m${instructions}\x1B[0m`);
+					spinner.start("Waiting for authentication...");
+				},
+				onPrompt: async (message, placeholder) => {
+					const value = await p.text({
+						message,
+						placeholder
+					});
+					if (p.isCancel(value)) return "";
+					return value;
+				},
+				onProgress: (msg) => p.log.step(msg)
+			}).catch((err) => {
+				spinner.stop(`Login failed: ${err.message}`);
+				return false;
 			});
-			if (p.isCancel(model)) return;
-			updateConfig({ model: model || void 0 });
-			p.log.success(model ? `Default model set to ${model}` : "Model will be prompted each time");
-			break;
+			spinner.stop();
+			if (success) p.log.success(`Connected to ${pr.name}`);
+		}
+	});
+}
+async function configureModel() {
+	while (true) {
+		const available = await getAvailableModels();
+		if (available.length === 0) p.log.warn(NO_MODELS_MESSAGE);
+		const choice = await pickModel(available, {
+			before: available.length > 0 ? [{
+				label: "Auto",
+				value: "_auto",
+				hint: "picks best available model from connected providers"
+			}] : [],
+			after: [{
+				label: "Connect OAuth provider...",
+				value: "_connect",
+				hint: "use existing Claude Pro, ChatGPT Plus, etc."
+			}, {
+				label: "Skip enhancement",
+				value: "_skip",
+				hint: "base skill with docs, issues, and types"
+			}]
+		});
+		if (!choice) return;
+		if (choice === "_connect") {
+			await configureOAuth();
+			continue;
 		}
-		case "agent": {
-			const agentChoice = await p.select({
-				message: "Select default agent",
-				options: [{
-					label: "Auto-detect",
-					value: ""
-				}, ...Object.entries(targets).map(([id, a]) => ({
-					label: a.displayName,
-					value: id,
-					hint: a.skillsDir
-				}))],
-				initialValue: config.agent || ""
+		if (choice === "_skip") {
+			updateConfig({
+				model: void 0,
+				skipLlm: true
 			});
-			if (p.isCancel(agentChoice)) return;
-			updateConfig({ agent: agentChoice || void 0 });
-			p.log.success(agentChoice ? `Default agent set to ${agentChoice}` : "Agent will be auto-detected");
-			break;
+			p.log.success("Enhancement disabled - skills will use raw docs only");
+		} else if (choice === "_auto") {
+			updateConfig({
+				model: void 0,
+				skipLlm: false
+			});
+			p.log.success("Enhancement model will be auto-selected");
+		} else {
+			updateConfig({
+				model: choice,
+				skipLlm: false
+			});
+			p.log.success(`Enhancement model set to ${getModelName(choice)}`);
 		}
+		return;
 	}
 }
 const configCommandDef = defineCommand({
@@ -141,13 +239,7 @@ const configCommandDef = defineCommand({
 	async run() {
 		requireInteractive("config");
 		const state = await getProjectState(process.cwd());
-		const generators = getInstalledGenerators();
-		const config = readConfig();
-		p.intro(introLine({
-			state,
-			generators,
-			modelId: config.model
-		}));
+		p.intro(introLine({ state }));
 		return configCommand();
 	}
 });
@@ -239,7 +331,8 @@ const removeCommandDef = defineCommand({
 		const intro = {
 			state,
 			generators,
-			modelId: config.model
+			modelId: config.model,
+			agentId: agent || config.agent || void 0
 		};
 		p.intro(`${introLine(intro)} · remove (${scope})`);
 		return removeCommand(state, {
@@ -429,35 +522,50 @@ function hasGhCli() {
 		return false;
 	}
 }
-async function runWizard() {
-	if (!isInteractive()) return;
-	p.note("Skilld gives your AI agent skill knowledge on your NPM\ndependencies gathered from versioned docs, source code\nand GitHub issues.", "Welcome to skilld");
+async function runWizard(opts = {}) {
+	if (!isInteractive()) return false;
+	const agentLabel = opts.agent ? targets[opts.agent].displayName : null;
+	const skillsDir = opts.agent ? targets[opts.agent].skillsDir : ".claude/skills";
+	const agentLine = agentLabel ? `\n\x1B[90mTarget agent: ${agentLabel}\x1B[0m` : "";
+	p.note(`Your AI agent reads docs from its training data - but APIs change,
+versions drift, and patterns go stale. Skilld fixes this.
+
+It generates a SKILL.md - a markdown reference card built from
+the actual docs, issues, and release notes for the exact
+package versions in your project. Your agent reads this file
+every session - no hallucinated APIs.
+
+How it works:
+  1. Fetch docs, issues, and types for your packages
+  2. Optionally compress with an LLM into a concise cheat sheet
+
+\x1B[90mExample: \`skilld add vue\` creates ${skillsDir}/vue-skilld/SKILL.md\nYour agent then knows the right APIs, gotchas, and patterns\nfor your exact version.\x1B[0m${agentLine}`, "Welcome to skilld");
 	const ghInstalled = hasGhCli();
 	if (ghInstalled) p.log.success("GitHub CLI detected — will use it to pull issues and discussions.");
-	else p.log.warn("GitHub CLI not found. Install it to enable issues/discussions:\n  \x1B[36mhttps://cli.github.com\x1B[0m");
+	else p.log.info("\x1B[90mGitHub CLI not installed — issues and discussions disabled.\n  Install later to enable: \x1B[36mhttps://cli.github.com\x1B[0m");
 	const selected = await p.multiselect({
-		message: "Which features would you like to enable?",
+		message: "What data sources should skills include?",
 		options: [
 			{
-				label: "Semantic + token search",
+				label: "Local search",
 				value: "search",
-				hint: "local query engine to cut token costs and speed up grep"
+				hint: "query engine for `skilld search` across all skill docs"
 			},
 			{
 				label: "Release notes",
 				value: "releases",
-				hint: "track changelogs for installed packages"
+				hint: "changelogs and migration notes per version"
 			},
 			{
 				label: "GitHub issues",
 				value: "issues",
-				hint: "surface common problems and solutions",
+				hint: "common bugs, workarounds, and solutions",
 				disabled: !ghInstalled
 			},
 			{
 				label: "GitHub discussions",
 				value: "discussions",
-				hint: "include Q&A and community knowledge",
+				hint: "community Q&A and usage examples",
 				disabled: !ghInstalled
 			}
 		],
@@ -466,7 +574,7 @@ async function runWizard() {
 	});
 	if (p.isCancel(selected)) {
 		p.cancel("Setup cancelled");
-		process.exit(0);
+		return false;
 	}
 	const features = {
 		search: selected.includes("search"),
@@ -474,43 +582,112 @@ async function runWizard() {
 		discussions: selected.includes("discussions"),
 		releases: selected.includes("releases")
 	};
-	const allModels = process.env.SKILLD_NO_AGENTS ? [] : await getAvailableModels();
+	p.note("An LLM can optionally summarize raw docs into a focused reference\nhighlighting best practices, gotchas, and migrations.\n\n\x1B[1mWithout LLM:\x1B[0m  ~2 KB skill with package metadata, types, and links\n\x1B[1mWith LLM:\x1B[0m     ~5 KB skill with curated gotchas, patterns, and migration notes\n\n\x1B[1mThis is a one-time build step\x1B[0m - it generates the SKILL.md, then your\ncoding agent reads the result every session. Can be a different model.\n\n\x1B[90mWorks with API keys, existing subscriptions (Claude Pro, ChatGPT Plus,\nCopilot, Gemini) via OAuth, or CLI tools (claude, gemini, codex).\x1B[0m", "Enhancement model (optional)");
 	let modelId;
-	if (allModels.length > 0) {
-		p.note("Skills work without an LLM, but one can rewrite your\nSKILL.md files with best practices and better structure.\n\x1B[90mThis is separate from the agent where skills are installed —\nthe target agent is auto-detected from your project files.\x1B[0m", "Optional: LLM optimization");
-		const modelChoice = await p.select({
-			message: "Model for generating SKILL.md",
-			options: [{
-				label: "Skip",
-				value: "",
-				hint: "use raw docs, no LLM needed"
-			}, ...allModels.map((m) => ({
-				label: m.recommended ? `${m.name} (Recommended)` : m.name,
-				value: m.id,
-				hint: `${m.agentName} · ${m.hint}`
-			}))]
-		});
-		if (p.isCancel(modelChoice)) {
-			p.cancel("Setup cancelled");
-			process.exit(0);
+	let skippedEnhancement = false;
+	let oauthJustConnected = false;
+	while (true) {
+		const allModels = process.env.SKILLD_NO_AGENTS ? [] : await getAvailableModels();
+		if (allModels.length === 0) p.log.warn(NO_MODELS_MESSAGE);
+		else if (oauthJustConnected) p.log.step(`${allModels.length} models now available. Select one below.`);
+		else {
+			const providers = /* @__PURE__ */ new Set();
+			for (const m of allModels) {
+				const vendor = m.vendorGroup ?? m.providerName;
+				if (!m.id.startsWith("pi:")) providers.add(`${vendor} via CLI`);
+				else if (m.hint?.includes("API key")) providers.add(`${vendor} via API key`);
+				else if (m.hint?.includes("OAuth")) providers.add(`${vendor} via OAuth`);
+			}
+			if (providers.size > 0) p.log.success(`Found: ${[...providers].join(", ")}`);
 		}
-		modelId = modelChoice || void 0;
-	} else {
-		p.log.warn("No supported LLM CLIs detected (claude, gemini, codex).\n  Skills will still work, but won't be LLM-optimized.");
-		const proceed = await p.confirm({
-			message: "Continue without LLM optimization?",
-			initialValue: true
+		const choice = await pickModel(allModels, {
+			before: allModels.length > 0 ? [{
+				label: "Auto",
+				value: "_auto",
+				hint: "picks best available model from connected providers"
+			}] : [],
+			after: [{
+				label: "Connect OAuth provider...",
+				value: "_connect",
+				hint: "use existing Claude Pro, ChatGPT Plus, etc."
+			}, {
+				label: "Skip enhancement",
+				value: "_skip",
+				hint: "base skill with docs, issues, and types - add LLM later via `skilld config`"
+			}]
 		});
-		if (p.isCancel(proceed) || !proceed) {
+		if (choice === null) {
 			p.cancel("Setup cancelled");
-			process.exit(0);
+			return false;
+		}
+		if (choice === "_connect") {
+			await wizardConnectProvider();
+			oauthJustConnected = true;
+			continue;
 		}
+		if (choice === "_skip") {
+			skippedEnhancement = true;
+			break;
+		}
+		if (choice === "_auto") break;
+		modelId = choice;
+		break;
 	}
 	updateConfig({
 		features,
-		...modelId ? { model: modelId } : { skipLlm: true }
+		...modelId ? {
+			model: modelId,
+			skipLlm: false
+		} : {
+			model: void 0,
+			skipLlm: skippedEnhancement
+		}
 	});
-	p.outro("Thanks, you're all set! Change config anytime with `skilld config`.");
+	const modelSummary = modelId ? getModelName(modelId) : skippedEnhancement ? "none (raw docs)" : "auto";
+	const featureList = Object.entries(features).filter(([, v]) => v).map(([k]) => k).join(", ") || "none";
+	p.log.success(`Model: ${modelSummary} · Features: ${featureList}`);
+	if (opts.showOutro !== false) p.note("Run \x1B[36mskilld add <pkg>\x1B[0m to generate skills for specific packages\nRun \x1B[36mskilld\x1B[0m to scan your project and pick packages interactively\nRun \x1B[36mskilld config\x1B[0m to change settings later", "Setup complete");
+	return true;
+}
+async function wizardConnectProvider() {
+	p.note(OAUTH_NOTE, "How OAuth works");
+	const providers = getOAuthProviderList();
+	const provider = await p.select({
+		message: "Connect provider",
+		options: providers.map((pr) => ({
+			label: pr.name,
+			value: pr.id,
+			hint: pr.loggedIn ? "connected" : void 0
+		}))
+	});
+	if (p.isCancel(provider)) return;
+	const spinner = p.spinner();
+	spinner.start("Connecting...");
+	const success = await loginOAuthProvider(provider, {
+		onAuth: (url, instructions) => {
+			spinner.stop("Open this URL in your browser:");
+			p.log.info(`  \x1B[36m${url}\x1B[0m`);
+			if (instructions) p.log.info(`  \x1B[90m${instructions}\x1B[0m`);
+			spinner.start("Waiting for authentication...");
+		},
+		onPrompt: async (message, placeholder) => {
+			const value = await p.text({
+				message,
+				placeholder
+			});
+			if (p.isCancel(value)) return "";
+			return value;
+		},
+		onProgress: (msg) => p.log.step(msg)
+	}).catch((err) => {
+		spinner.stop(`Login failed: ${err.message}`);
+		return false;
+	});
+	spinner.stop();
+	if (success) {
+		const name = providers.find((pr) => pr.id === provider)?.name ?? provider;
+		p.log.success(`Connected to ${name}`);
+	}
 }
 //#endregion
 //#region src/cli.ts
@@ -616,7 +793,8 @@ const SUBCOMMAND_NAMES = [
 	"search",
 	"cache",
 	"validate",
-	"assemble"
+	"assemble",
+	"setup"
 ];
 runMain(defineCommand({
 	meta: {
@@ -638,7 +816,8 @@ runMain(defineCommand({
 		search: () => import("./_chunks/search.mjs").then((m) => m.searchCommandDef),
 		cache: () => import("./_chunks/cache2.mjs").then((m) => m.cacheCommandDef),
 		validate: () => import("./_chunks/validate.mjs").then((m) => m.validateCommandDef),
-		assemble: () => import("./_chunks/assemble.mjs").then((m) => m.assembleCommandDef)
+		assemble: () => import("./_chunks/assemble.mjs").then((m) => m.assembleCommandDef),
+		setup: () => import("./_chunks/setup.mjs").then((m) => m.setupCommandDef)
 	},
 	async run({ args }) {
 		const firstArg = process.argv[2];
@@ -648,6 +827,7 @@ runMain(defineCommand({
 			const state = await getProjectState(cwd);
 			const status = formatStatus(state.synced.length, state.outdated.length);
 			console.log(`skilld v${version} · ${status}`);
+			if (isRunningInsideAgent()) console.log("Interactive wizard requires a standalone terminal (detected agent session).\nUse `skilld add <pkg>` to add skills non-interactively, or run `npx skilld` in a separate terminal.");
 			return;
 		}
 		let currentAgent = resolveAgent(args.agent);
@@ -656,11 +836,14 @@ runMain(defineCommand({
 			if (!currentAgent) return;
 		}
 		if (currentAgent === "none") {
-			p.log.info("No agent selected. Use `skilld add <pkg>` to export portable prompts.");
+			if (!hasCompletedWizard()) {
+				if (!await runWizard()) return;
+			}
+			p.log.info("No agent selected - skills export as portable PROMPT_*.md files.\n  Run \x1B[36mskilld add <pkg>\x1B[0m to generate prompts for any package.\n  Run \x1B[36mskilld config\x1B[0m to set a target agent later.");
 			return;
 		}
 		const agent = currentAgent;
-		const { state, selfUpdate } = await brandLoader(async () => {
+		let { state, selfUpdate } = await brandLoader(async () => {
 			const config = readConfig();
 			const state = await getProjectState(cwd);
 			let selfUpdate = null;
@@ -702,14 +885,19 @@ runMain(defineCommand({
 			p.note(`\x1B[90m${version}\x1B[0m → \x1B[1m\x1B[32m${selfUpdate.latest}\x1B[0m${released}\n\x1B[36m${cmd}\x1B[0m`, "\x1B[33mUpdate available\x1B[0m");
 		}
 		if (state.skills.length === 0) {
-			if (!hasCompletedWizard()) await runWizard();
+			if (!hasCompletedWizard()) {
+				if (!await runWizard({
+					agent,
+					showOutro: false
+				})) return;
+			} else p.log.step("No skills installed yet - pick some packages to get started.");
 			const pkgJsonPath = join(cwd, "package.json");
 			const hasPkgJson = existsSync(pkgJsonPath);
 			const projectName = hasPkgJson ? JSON.parse(readFileSync(pkgJsonPath, "utf-8")).name : void 0;
 			const projectLabel = projectName ? `Generating skills for \x1B[36m${projectName}\x1B[0m` : "Generating skills for current directory";
 			p.log.step(projectLabel);
-			if (!hasPkgJson) p.log.warn("No package.json found — enter package names manually or run inside a project");
-			p.log.info("Tip: Only generate skills for packages your agent struggles with.\n     The fewer skills, the more context you have for everything else :)");
+			if (!hasPkgJson) p.log.warn("No package.json found - enter npm package names manually.\n  For best results, run skilld inside a JS/TS project directory.");
+			p.log.info("Tip: Add skills for packages with complex APIs or frequent breaking changes - not every dependency needs one.");
 			let setupComplete = false;
 			while (!setupComplete) {
 				const source = hasPkgJson ? await p.select({
@@ -718,16 +906,21 @@ runMain(defineCommand({
 						{
 							label: "Scan source files",
 							value: "imports",
-							hint: "Find actually used imports"
+							hint: "find actually used imports"
 						},
 						{
 							label: "Use package.json",
 							value: "deps",
-							hint: `All ${state.deps.size} dependencies`
+							hint: `all ${state.deps.size} dependencies`
 						},
 						{
 							label: "Enter manually",
 							value: "manual"
+						},
+						{
+							label: "Skip for now",
+							value: "skip",
+							hint: "add skills later with `skilld add <pkg>`"
 						}
 					]
 				}) : "manual";
@@ -735,6 +928,10 @@ runMain(defineCommand({
 					p.cancel("Setup cancelled");
 					return;
 				}
+				if (source === "skip") {
+					p.log.info("Run \x1B[36mskilld add <pkg>\x1B[0m or \x1B[36mskilld\x1B[0m anytime to add skills.");
+					return;
+				}
 				let selected;
 				if (source === "manual") {
 					const input = await p.text({
@@ -788,6 +985,23 @@ runMain(defineCommand({
 					}
 					const sourceMap = new Map(usages.map((u) => [u.name, u.source]));
 					const maxLen = Math.max(...packages.map((n) => n.length));
+					const preselect = packages.filter((name) => {
+						if (sourceMap.get(name) === "preset") return true;
+						return new Set([
+							"vue",
+							"nuxt",
+							"react",
+							"next",
+							"svelte",
+							"@sveltejs/kit",
+							"astro",
+							"solid-js",
+							"angular",
+							"typescript",
+							"vite",
+							"vitest"
+						]).has(name);
+					});
 					const choice = await p.multiselect({
 						message: `Select packages (${packages.length} found)`,
 						options: packages.map((name) => {
@@ -805,7 +1019,7 @@ runMain(defineCommand({
 								value: name
 							};
 						}),
-						initialValues: packages
+						initialValues: preselect
 					});
 					if (p.isCancel(choice)) continue;
 					if (choice.length === 0) {
@@ -814,191 +1028,268 @@ runMain(defineCommand({
 					}
 					selected = choice;
 				}
+				const wizardConfig = readConfig();
 				const { syncCommand } = await import("./_chunks/sync.mjs");
 				await syncCommand(state, {
 					packages: selected,
 					global: false,
 					agent,
-					yes: false
+					model: wizardConfig.model,
+					yes: !wizardConfig.skipLlm
 				});
 				setupComplete = true;
 			}
+			const previewSkill = (await getProjectState(cwd)).skills[0];
+			if (previewSkill) {
+				const previewPath = join(cwd, targets[agent].skillsDir, previewSkill.name, "SKILL.md");
+				if (existsSync(previewPath)) {
+					const previewContent = readFileSync(previewPath, "utf-8");
+					const previewLines = previewContent.split("\n").slice(0, 20).join("\n").replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "").replace(/\x1B\].*?(?:\x07|\x1B\\)/g, "");
+					const fileSize = (Buffer.byteLength(previewContent) / 1024).toFixed(1);
+					p.note(`\x1B[90m${previewLines}\n...\x1B[0m`, `${targets[agent].skillsDir}/${previewSkill.name}/SKILL.md (${fileSize} KB)`);
+				}
+			}
+			const agentName = targets[agent].displayName;
+			const verifyLine = detectInstalledAgents().includes(agent) ? {
+				"claude-code": "Start a new Claude Code session - skills load automatically.\nOr type /skill-name to invoke a specific skill.",
+				"cursor": "Restart Cursor to pick up new skills.\nSkills appear in Settings > Cursor Rules.",
+				"github-copilot": "Restart your editor to pick up new skills.\nCopilot discovers skills from .github/skills/ at startup.",
+				"gemini-cli": "Start a new Gemini CLI session.\nVerify with /skills list.",
+				"codex": "Start a new Codex session.\nSkills in .agents/skills/ are discovered at startup.",
+				"windsurf": "Restart Windsurf to pick up new skills.\nSkills auto-invoke when their description matches your prompt.",
+				"cline": "Restart your editor. Cline reads skill descriptions at startup.\nFull content loads on-demand when the agent invokes use_skill.",
+				"goose": "Start a new Goose session.\nSkills are discovered automatically at startup.",
+				"amp": "Start a new Amp session.\nReads skill descriptions at startup, full content on invocation.",
+				"opencode": "Start a new OpenCode session.\nSkills are discovered automatically at startup.",
+				"roo": "Restart your editor. Roo reads skill descriptions at startup."
+			}[agent] ?? "" : `Skills are ready in ${targets[agent].skillsDir}/.\n\x1B[90m${agentName} was not detected on this machine.\nInstall it to use these skills, or run \`skilld config\` to change agents.\x1B[0m`;
+			const firstPkg = previewSkill?.info?.packageName || previewSkill?.name;
+			const trySuggestion = firstPkg ? `\n\n\x1B[36mTry it:\x1B[0m ask your agent "What are the gotchas or breaking changes in ${firstPkg}?"` : "";
+			p.note(`${verifyLine}${trySuggestion}\n\nRun \x1B[36mskilld info\x1B[0m to see installed skills.\nRun \x1B[36mskilld\x1B[0m again to add more, update, or search.`, `${agentName} - next steps`);
+			if (hasPkgJson) {
+				const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+				if (!pkgJson.scripts?.prepare?.includes("skilld")) {
+					const prepareCmd = pkgJson.scripts?.prepare ? `${pkgJson.scripts.prepare} && skilld update -b` : "skilld update -b";
+					p.log.info(`\x1B[90mKeep skills fresh by adding to package.json scripts:\n  \x1B[36m"prepare": "${prepareCmd}"\x1B[0m\n  \x1B[90mRefreshes docs on install. Run \`skilld update\` to regenerate LLM enhancements.\n  Commit skilld-lock.yaml so teammates can run \`skilld install\`.\x1B[0m`);
+				}
+			}
 			return;
 		}
 		const status = formatStatus(state.synced.length, state.outdated.length);
 		p.log.info(status);
-		while (true) {
-			const options = [];
-			options.push({
-				label: "Add new skills",
-				value: "install"
-			});
-			if (state.outdated.length > 0) options.push({
-				label: "Update skills",
-				value: "update",
-				hint: `\x1B[33m${state.outdated.length} outdated\x1B[0m`
-			});
-			options.push({
-				label: "Remove skills",
-				value: "remove"
-			}, {
-				label: "Search docs",
-				value: "search"
-			}, {
-				label: "Info",
-				value: "info"
-			}, {
-				label: "Configure",
-				value: "config"
-			});
-			const action = await p.select({
-				message: "What would you like to do?",
-				options
-			});
-			if (p.isCancel(action)) {
-				p.cancel("Cancelled");
-				return;
-			}
-			switch (action) {
-				case "install": {
-					const installedNames = new Set(state.skills.map((s) => s.packageName || s.name));
-					const uninstalledDeps = [...state.deps.keys()].filter((d) => !installedNames.has(d));
-					const allDepsInstalled = uninstalledDeps.length === 0;
-					const source = existsSync(join(cwd, "package.json")) ? await p.select({
-						message: "How should I find packages?",
-						options: [
-							{
-								label: "Scan source files",
-								value: "imports",
-								hint: allDepsInstalled ? "all installed" : "find actually used imports",
-								disabled: allDepsInstalled
-							},
-							{
-								label: "Use package.json",
-								value: "deps",
-								hint: allDepsInstalled ? "all installed" : `${uninstalledDeps.length} uninstalled`,
-								disabled: allDepsInstalled
-							},
-							{
-								label: "Enter manually",
-								value: "manual"
+		const refreshState = async () => {
+			state = await getProjectState(cwd);
+		};
+		await menuLoop({
+			message: "What would you like to do?",
+			options: () => {
+				const opts = [];
+				opts.push({
+					label: "Add new skills",
+					value: "install"
+				});
+				if (state.outdated.length > 0) opts.push({
+					label: "Update skills",
+					value: "update",
+					hint: `\x1B[33m${state.outdated.length} outdated\x1B[0m`
+				});
+				opts.push({
+					label: "Remove skills",
+					value: "remove"
+				}, {
+					label: "Search docs",
+					value: "search"
+				}, {
+					label: "Info",
+					value: "info"
+				}, {
+					label: "Configure",
+					value: "config"
+				});
+				return opts;
+			},
+			onSelect: async (action) => {
+				switch (action) {
+					case "install": {
+						const installedNames = new Set([...state.synced.map((s) => s.packageName), ...state.outdated.map((s) => s.packageName)].filter(Boolean));
+						const uninstalledDeps = [...state.deps.keys()].filter((d) => !installedNames.has(d));
+						const allDepsInstalled = uninstalledDeps.length === 0;
+						const source = existsSync(join(cwd, "package.json")) ? guard(await p.select({
+							message: "How should I find packages?",
+							options: [
+								{
+									label: "Scan source files",
+									value: "imports",
+									hint: allDepsInstalled ? "all installed" : "find actually used imports",
+									disabled: allDepsInstalled
+								},
+								{
+									label: "Use package.json",
+									value: "deps",
+									hint: allDepsInstalled ? "all installed" : `${uninstalledDeps.length} uninstalled`,
+									disabled: allDepsInstalled
+								},
+								{
+									label: "Enter manually",
+									value: "manual"
+								}
+							]
+						})) : "manual";
+						let selected;
+						if (source === "manual") {
+							const input = guard(await p.text({
+								message: "Enter package names (space or comma-separated)",
+								placeholder: "vue nuxt pinia"
+							}));
+							if (!input) return;
+							selected = input.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+							if (selected.length === 0) return;
+						} else {
+							let usages;
+							if (source === "imports") {
+								const spinner = timedSpinner();
+								spinner.start("Scanning imports...");
+								const result = await detectImportedPackages(cwd);
+								if (result.packages.length === 0) {
+									spinner.stop("No imports found, falling back to package.json");
+									usages = uninstalledDeps.map((name) => ({
+										name,
+										count: 0
+									}));
+								} else {
+									const depSet = new Set(state.deps.keys());
+									const matched = result.packages.filter((pkg) => depSet.has(pkg.name) || pkg.source === "preset");
+									const alreadyInstalled = matched.filter((pkg) => installedNames.has(pkg.name));
+									usages = matched.filter((pkg) => !installedNames.has(pkg.name));
+									if (usages.length === 0) {
+										spinner.stop("All detected imports already have skills");
+										return;
+									} else {
+										spinner.stop(`Found ${matched.length} imported packages`);
+										if (alreadyInstalled.length > 0) p.log.info(`${alreadyInstalled.length} already have skills installed`);
+									}
+								}
+							} else usages = uninstalledDeps.map((name) => ({
+								name,
+								count: 0
+							}));
+							const packages = usages.map((u) => u.name);
+							if (packages.length === 0) {
+								p.log.warn("No packages found");
+								return;
 							}
-						]
-					}) : "manual";
-					if (p.isCancel(source)) continue;
-					let selected;
-					if (source === "manual") {
-						const input = await p.text({
-							message: "Enter package names (space or comma-separated)",
-							placeholder: "vue nuxt pinia"
+							const usageMap = new Map(usages.map((u) => [u.name, u]));
+							const sourceMap = new Map(usages.map((u) => [u.name, u.source]));
+							const frameworks = new Set([
+								"vue",
+								"nuxt",
+								"react",
+								"next",
+								"svelte",
+								"@sveltejs/kit",
+								"astro",
+								"solid-js",
+								"angular",
+								"typescript",
+								"vite",
+								"vitest"
+							]);
+							const maxLen = Math.max(...packages.map((n) => n.length));
+							const choice = guard(await p.multiselect({
+								message: `Select packages your agent struggles with or that are new to you (${packages.length} found)`,
+								options: packages.map((name) => {
+									const ver = state.deps.get(name)?.replace(/^[\^~>=<]/, "") || "";
+									const repo = getRepoHint(name, cwd);
+									const hint = sourceMap.get(name) === "preset" ? "nuxt module" : frameworks.has(name) ? "framework" : (usageMap.get(name)?.count ?? 0) >= 5 ? `${usageMap.get(name).count} imports` : void 0;
+									const pad = " ".repeat(maxLen - name.length + 2);
+									const meta = [
+										ver,
+										hint,
+										repo
+									].filter(Boolean).join("  ");
+									return {
+										label: meta ? `${name}${pad}\x1B[90m${meta}\x1B[39m` : name,
+										value: name
+									};
+								}),
+								initialValues: []
+							}));
+							if (choice.length === 0) return;
+							selected = choice;
+						}
+						const { syncCommand: sync } = await import("./_chunks/sync.mjs");
+						await sync(state, {
+							packages: selected,
+							global: false,
+							agent,
+							yes: false
 						});
-						if (p.isCancel(input) || !input) continue;
-						selected = input.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
-						if (selected.length === 0) continue;
-					} else {
-						let usages;
-						if (source === "imports") {
-							const spinner = timedSpinner();
-							spinner.start("Scanning imports...");
-							const result = await detectImportedPackages(cwd);
-							if (result.packages.length === 0) {
-								spinner.stop("No imports found, falling back to package.json");
-								usages = uninstalledDeps.map((name) => ({
-									name,
-									count: 0
-								}));
-							} else {
-								const depSet = new Set(state.deps.keys());
-								usages = result.packages.filter((pkg) => depSet.has(pkg.name) || pkg.source === "preset").filter((pkg) => !installedNames.has(pkg.name));
-								if (usages.length === 0) {
-									spinner.stop("All detected imports already have skills");
-									continue;
-								} else spinner.stop(`Found ${usages.length} imported packages`);
-							}
-						} else usages = uninstalledDeps.map((name) => ({
-							name,
-							count: 0
-						}));
-						const packages = usages.map((u) => u.name);
-						if (packages.length === 0) {
-							p.log.warn("No packages found");
-							continue;
+						await refreshState();
+						return true;
+					}
+					case "update": {
+						if (state.outdated.length === 0) {
+							p.log.success("All skills up to date");
+							return true;
 						}
-						const sourceMap = new Map(usages.map((u) => [u.name, u.source]));
-						const maxLen = Math.max(...packages.map((n) => n.length));
-						const choice = await p.multiselect({
-							message: `Select packages (${packages.length} found)`,
-							options: packages.map((name) => {
-								const ver = state.deps.get(name)?.replace(/^[\^~>=<]/, "") || "";
-								const repo = getRepoHint(name, cwd);
-								const hint = sourceMap.get(name) === "preset" ? "nuxt module" : void 0;
-								const pad = " ".repeat(maxLen - name.length + 2);
-								const meta = [
-									ver,
-									hint,
-									repo
-								].filter(Boolean).join("  ");
-								return {
-									label: meta ? `${name}${pad}\x1B[90m${meta}\x1B[39m` : name,
-									value: name
-								};
-							}),
-							initialValues: packages
+						const selected = guard(await p.multiselect({
+							message: "Select packages to update",
+							options: state.outdated.map((s) => ({
+								label: s.name,
+								value: s.packageName || s.name,
+								hint: `${s.info?.version ?? "unknown"} → ${s.latestVersion}`
+							})),
+							initialValues: state.outdated.map((s) => s.packageName || s.name)
+						}));
+						if (selected.length === 0) return;
+						const { syncCommand: syncUpdate } = await import("./_chunks/sync.mjs");
+						await syncUpdate(state, {
+							packages: selected,
+							global: false,
+							agent,
+							yes: false,
+							mode: "update"
 						});
-						if (p.isCancel(choice) || choice.length === 0) continue;
-						selected = choice;
+						await refreshState();
+						return true;
 					}
-					const { syncCommand: sync } = await import("./_chunks/sync.mjs");
-					return sync(state, {
-						packages: selected,
-						global: false,
-						agent,
-						yes: false
-					});
-				}
-				case "update": {
-					if (state.outdated.length === 0) {
-						p.log.success("All skills up to date");
-						return;
+					case "remove": {
+						const globalSkills = [...iterateSkills({ scope: "global" })];
+						let removeGlobal = false;
+						if (globalSkills.length > 0) removeGlobal = guard(await p.select({
+							message: "Which skills?",
+							options: [{
+								label: "Project skills",
+								value: "local"
+							}, {
+								label: "Global skills",
+								value: "global",
+								hint: `${globalSkills.length} installed`
+							}]
+						})) === "global";
+						await removeCommand(state, {
+							global: removeGlobal,
+							agent,
+							yes: false
+						});
+						await refreshState();
+						break;
 					}
-					const selected = await p.multiselect({
-						message: "Select packages to update",
-						options: state.outdated.map((s) => ({
-							label: s.name,
-							value: s.packageName || s.name,
-							hint: `${s.info?.version ?? "unknown"} → ${s.latestVersion}`
-						})),
-						initialValues: state.outdated.map((s) => s.packageName || s.name)
-					});
-					if (p.isCancel(selected) || selected.length === 0) continue;
-					const { syncCommand: syncUpdate } = await import("./_chunks/sync.mjs");
-					return syncUpdate(state, {
-						packages: selected,
-						global: false,
-						agent,
-						yes: false
-					});
-				}
-				case "remove":
-					await removeCommand(state, {
-						global: false,
-						agent,
-						yes: false
-					});
-					continue;
-				case "search": {
-					const { interactiveSearch } = await import("./_chunks/search-interactive.mjs");
-					await interactiveSearch();
-					continue;
+					case "search": {
+						const { interactiveSearch } = await import("./_chunks/search-interactive.mjs");
+						await interactiveSearch();
+						break;
+					}
+					case "info":
+						await statusCommand({ global: false });
+						break;
+					case "config":
+						await configCommand();
+						await refreshState();
+						break;
 				}
-				case "info":
-					await statusCommand({ global: false });
-					continue;
-				case "config":
-					await configCommand();
-					continue;
 			}
-		}
+		});
 	}
 }));
 //#endregion