skilld 1.2.2 → 1.3.0

package/dist/_chunks/sync.mjs

@@ -1,16 +1,17 @@
+import { a as getModelLabel, i as getAvailableModels, o as getModelName, r as createToolProgress, s as optimizeDocs, t as detectImportedPackages } from "./agent.mjs";
 import { a as getRepoCacheDir, c as getVersionKey, i as getPackageDbPath, o as getCacheDir, t as CACHE_DIR } from "./config.mjs";
 import { n as sanitizeMarkdown } from "./sanitize.mjs";
-import { _ as resolvePkgDir, a as getShippedSkills, b as writeToRepoCache, c as linkCachedDir, d as linkRepoCachedDir, f as linkShippedSkill, h as readCachedDocs, i as getPkgKeyFiles, l as linkPkg, m as listReferenceFiles, n as clearCache, o as hasShippedDocs, r as ensureCacheDir, s as isCached, u as linkPkgNamed, y as writeToCache } from "./cache.mjs";
+import { _ as resolvePkgDir, a as getShippedSkills, b as writeToRepoCache, c as linkCachedDir, d as linkRepoCachedDir, f as linkShippedSkill, g as readCachedSection, h as readCachedDocs, i as getPkgKeyFiles, l as linkPkg, m as listReferenceFiles, n as clearCache, o as hasShippedDocs, r as ensureCacheDir, s as isCached, u as linkPkgNamed, y as writeToCache } from "./cache.mjs";
 import "./yaml.mjs";
 import { i as parseFrontmatter } from "./markdown.mjs";
-import { SearchDepsUnavailableError, createIndex } from "../retriv/index.mjs";
-import { f as getPrereleaseChangelogRef, n as getSharedSkillsDir, s as getBlogPreset, t as SHARED_SKILLS_DIR } from "./shared.mjs";
+import { SearchDepsUnavailableError, createIndex, listIndexIds } from "../retriv/index.mjs";
+import { a as semverDiff, c as getBlogPreset, n as getSharedSkillsDir, p as getPrereleaseChangelogRef, t as SHARED_SKILLS_DIR } from "./shared.mjs";
 import { A as parseGitSkillInput, B as isGhAvailable, C as downloadLlmsDocs, D as normalizeLlmsLinks, F as formatDiscussionAsMarkdown, G as fetchReleaseNotes, H as toCrawlPattern, I as generateDiscussionIndex, K as generateReleaseIndex, L as fetchGitHubIssues, M as resolveEntryFiles, N as generateDocsIndex, P as fetchGitHubDiscussions, R as formatIssueAsMarkdown, T as fetchLlmsTxt, U as fetchBlogReleases, V as fetchCrawledDocs, Z as fetchGitHubRaw, b as isShallowGitDocs, f as resolvePackageDocsWithAttempts, h as fetchGitDocs, i as fetchPkgDist, k as fetchGitSkills, n as fetchNpmPackage, nt as parsePackageSpec, p as searchNpmPackages, q as isPrerelease, s as readLocalDependencies, tt as parseGitHubUrl, u as resolveLocalPackageDocs, v as fetchReadmeContent, x as resolveGitHubRepo, y as filterFrameworkDocs, z as generateIssueIndex } from "./sources.mjs";
 import { a as targets } from "./detect.mjs";
-import { a as sanitizeName, c as SECTION_OUTPUT_FILES, g as maxLines, h as maxItems, i as linkSkillToAgents, l as buildAllSectionPrompts, n as computeSkillDirName, p as portabilizePrompt, t as generateSkillMd } from "./prompts.mjs";
-import { a as getModelLabel, i as getAvailableModels, o as getModelName, r as createToolProgress, s as optimizeDocs, t as detectImportedPackages } from "./agent.mjs";
-import { C as hasCompletedWizard, E as registerProject, O as updateConfig, T as readConfig, d as getInstalledGenerators, h as promptForAgent, l as timedSpinner, m as isInteractive, n as formatDuration, p as introLine, v as resolveAgent, x as defaultFeatures, y as sharedArgs } from "./formatting.mjs";
+import { a as sanitizeName, c as SECTION_OUTPUT_FILES, g as maxLines, h as maxItems, i as linkSkillToAgents, l as buildAllSectionPrompts, m as wrapSection, n as computeSkillDirName, p as portabilizePrompt, s as SECTION_MERGE_ORDER, t as generateSkillMd } from "./prompts.mjs";
+import { C as registerProject, S as readConfig, T as updateConfig, b as hasCompletedWizard, c as isInteractive, d as pickModel, f as promptForAgent, g as sharedArgs, h as resolveAgent, i as getInstalledGenerators, s as introLine, t as NO_MODELS_MESSAGE, v as defaultFeatures } from "./cli-helpers.mjs";
 import { o as parsePackages, s as readLock, t as getProjectState, u as writeLock } from "./skills.mjs";
+import { l as timedSpinner, n as formatDuration } from "./formatting.mjs";
 import { t as runWizard } from "../cli.mjs";
 import { n as shutdownWorker } from "./pool.mjs";
 import { dirname, join, relative, resolve } from "pathe";
@@ -121,9 +122,7 @@ function detectDocsType(packageName, version, repoUrl, llmsUrl) {
 function handleShippedSkills(packageName, version, cwd, agent, global) {
 	const shippedSkills = getShippedSkills(packageName, cwd, version);
 	if (shippedSkills.length === 0) return null;
-	const shared = getSharedSkillsDir(cwd);
-	const agentConfig = targets[agent];
-	const baseDir = global ? join(CACHE_DIR, "skills") : shared || join(cwd, agentConfig.skillsDir);
+	const baseDir = resolveBaseDir(cwd, agent, global);
 	mkdirSync(baseDir, { recursive: true });
 	for (const shipped of shippedSkills) {
 		linkShippedSkill(baseDir, shipped.skillName, shipped.skillDir);
@@ -143,7 +142,7 @@ function handleShippedSkills(packageName, version, cwd, agent, global) {
 }
 /** Resolve the base skills directory for an agent */
 function resolveBaseDir(cwd, agent, global) {
-	if (global) return join(CACHE_DIR, "skills");
+	if (global) return targets[agent].globalSkillsDir;
 	const shared = getSharedSkillsDir(cwd);
 	if (shared) return shared;
 	const agentConfig = targets[agent];
@@ -321,6 +320,7 @@ async function fetchAndCacheResources(opts) {
 							}
 						});
 					}
+					if (docs.length > 0) docsType = "docs";
 				}
 				writeToCache(packageName, version, cachedDocs);
 			}
@@ -541,13 +541,41 @@ async function fetchAndCacheResources(opts) {
 		usedCache: useCache
 	};
 }
-/** Index all resources into the search database (single batch) */
+/**
+* Extract the parent document ID from a chunk ID.
+* Chunk IDs have the form "docId#chunk-N"; non-chunk IDs return as-is.
+*/
+function parentDocId(id) {
+	const idx = id.indexOf("#chunk-");
+	return idx === -1 ? id : id.slice(0, idx);
+}
+/** Cap and sort docs by type priority, mutates and truncates allDocs in place */
+function capDocs(allDocs, max, onProgress) {
+	if (allDocs.length <= max) return;
+	const TYPE_PRIORITY = {
+		doc: 0,
+		issue: 1,
+		discussion: 2,
+		release: 3,
+		source: 4,
+		types: 5
+	};
+	allDocs.sort((a, b) => {
+		const ta = TYPE_PRIORITY[a.metadata?.type || "doc"] ?? 3;
+		const tb = TYPE_PRIORITY[b.metadata?.type || "doc"] ?? 3;
+		if (ta !== tb) return ta - tb;
+		return a.id.localeCompare(b.id);
+	});
+	onProgress(`Indexing capped at ${max}/${allDocs.length} docs (prioritized by type)`);
+	allDocs.length = max;
+}
+/** Index all resources into the search database, with incremental support */
 async function indexResources(opts) {
 	const { packageName, version, cwd, onProgress } = opts;
 	const features = opts.features ?? readConfig().features ?? defaultFeatures;
 	if (!features.search) return;
 	const dbPath = getPackageDbPath(packageName, version);
-	if (existsSync(dbPath)) return;
+	const dbExists = existsSync(dbPath);
 	const allDocs = [...opts.docsToIndex];
 	const pkgDir = resolvePkgDir(packageName, cwd, version);
 	if (features.search && pkgDir) {
@@ -564,31 +592,54 @@ async function indexResources(opts) {
 		});
 	}
 	if (allDocs.length === 0) return;
-	if (allDocs.length > MAX_INDEX_DOCS) {
-		const TYPE_PRIORITY = {
-			doc: 0,
-			issue: 1,
-			discussion: 2,
-			release: 3,
-			source: 4,
-			types: 5
-		};
-		allDocs.sort((a, b) => {
-			const ta = TYPE_PRIORITY[a.metadata?.type || "doc"] ?? 3;
-			const tb = TYPE_PRIORITY[b.metadata?.type || "doc"] ?? 3;
-			if (ta !== tb) return ta - tb;
-			return a.id.localeCompare(b.id);
-		});
-		onProgress(`Indexing capped at ${MAX_INDEX_DOCS}/${allDocs.length} docs (prioritized by type)`);
-		allDocs.length = MAX_INDEX_DOCS;
+	capDocs(allDocs, MAX_INDEX_DOCS, onProgress);
+	if (!dbExists) {
+		onProgress(`Building search index (${allDocs.length} docs)`);
+		try {
+			await createIndex(allDocs, {
+				dbPath,
+				onProgress: ({ phase, current, total }) => {
+					if (phase === "storing") {
+						const d = allDocs[current - 1];
+						onProgress(`Storing ${d?.metadata?.type === "source" || d?.metadata?.type === "types" ? "code" : d?.metadata?.type || "doc"} (${current}/${total})`);
+					} else if (phase === "embedding") onProgress(`Creating embeddings (${current}/${total})`);
+				}
+			});
+		} catch (err) {
+			if (err instanceof SearchDepsUnavailableError) onProgress("Search indexing skipped (native deps unavailable)");
+			else throw err;
+		}
+		return;
+	}
+	let existingIds;
+	try {
+		existingIds = await listIndexIds({ dbPath });
+	} catch (err) {
+		if (err instanceof SearchDepsUnavailableError) {
+			onProgress("Search indexing skipped (native deps unavailable)");
+			return;
+		}
+		throw err;
+	}
+	const existingParentIds = new Set(existingIds.map(parentDocId));
+	const incomingIds = new Set(allDocs.map((d) => d.id));
+	const newDocs = allDocs.filter((d) => !existingParentIds.has(d.id));
+	const removeIds = existingIds.filter((id) => !incomingIds.has(parentDocId(id)));
+	if (newDocs.length === 0 && removeIds.length === 0) {
+		onProgress("Search index up to date");
+		return;
 	}
-	onProgress(`Building search index (${allDocs.length} docs)`);
+	const parts = [];
+	if (newDocs.length > 0) parts.push(`+${newDocs.length} new`);
+	if (removeIds.length > 0) parts.push(`-${removeIds.length} stale`);
+	onProgress(`Updating search index (${parts.join(", ")})`);
 	try {
-		await createIndex(allDocs, {
+		await createIndex(newDocs, {
 			dbPath,
+			removeIds,
 			onProgress: ({ phase, current, total }) => {
 				if (phase === "storing") {
-					const d = allDocs[current - 1];
+					const d = newDocs[current - 1];
 					onProgress(`Storing ${d?.metadata?.type === "source" || d?.metadata?.type === "types" ? "code" : d?.metadata?.type || "doc"} (${current}/${total})`);
 				} else if (phase === "embedding") onProgress(`Creating embeddings (${current}/${total})`);
 			}
@@ -662,10 +713,13 @@ async function ensureGitignore(skillsDir, cwd, isGlobal) {
 }
 const SKILLD_MARKER_START = "<!-- skilld -->";
 const SKILLD_MARKER_END = "<!-- /skilld -->";
-const SKILLD_INSTRUCTIONS = `${SKILLD_MARKER_START}
-Before modifying code, evaluate each installed skill against the current task.
-For each skill, determine YES/NO relevance and invoke all YES skills before proceeding.
-${SKILLD_MARKER_END}`;
+const DEFAULT_SKILL_HINT = "Before modifying code, evaluate each installed skill against the current task.\nFor each skill, determine YES/NO relevance and invoke all YES skills before proceeding.";
+function getSkillInstructions(agent) {
+	return `${SKILLD_MARKER_START}\n${targets[agent].skillActivationHint || DEFAULT_SKILL_HINT}\n${SKILLD_MARKER_END}`;
+}
+function getMdcSkillInstructions(agent) {
+	return `---\ndescription: "Activates installed skilld skills before code changes"\nalwaysApply: true\n---\n\n${targets[agent].skillActivationHint || DEFAULT_SKILL_HINT}`;
+}
 /**
 * Check if agent instruction file has skilld skill-activation snippet.
 * If missing, prompt to add it. Skipped for global installs or agents without an instructionFile.
@@ -675,55 +729,55 @@ async function ensureAgentInstructions(agent, cwd, isGlobal) {
 	const agentConfig = targets[agent];
 	if (!agentConfig.instructionFile) return;
 	const filePath = join(cwd, agentConfig.instructionFile);
+	if (agentConfig.instructionFile.endsWith(".mdc")) {
+		if (existsSync(filePath)) return;
+		const content = `${getMdcSkillInstructions(agent)}\n`;
+		if (!isInteractive()) {
+			mkdirSync(join(filePath, ".."), { recursive: true });
+			writeFileSync(filePath, content);
+			return;
+		}
+		p.note(`This tells your agent to check installed skills before making
+code changes. Without it, skills are available but may not
+activate automatically.
+
+\x1B[90m${getMdcSkillInstructions(agent)}\x1B[0m`, `Create ${agentConfig.instructionFile}`);
+		const add = await p.confirm({
+			message: `Create ${agentConfig.instructionFile} with skill activation instructions?`,
+			initialValue: true
+		});
+		if (p.isCancel(add) || !add) return;
+		mkdirSync(join(filePath, ".."), { recursive: true });
+		writeFileSync(filePath, content);
+		p.log.success(`Created ${agentConfig.instructionFile}`);
+		return;
+	}
 	if (existsSync(filePath)) {
 		if (readFileSync(filePath, "utf-8").includes("<!-- skilld -->")) return;
 	}
 	if (!isInteractive()) {
-		if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${SKILLD_INSTRUCTIONS}\n`);
-		else writeFileSync(filePath, `${SKILLD_INSTRUCTIONS}\n`);
+		if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${getSkillInstructions(agent)}\n`);
+		else writeFileSync(filePath, `${getSkillInstructions(agent)}\n`);
 		return;
 	}
-	p.note(SKILLD_INSTRUCTIONS, `Will be added to ${agentConfig.instructionFile}`);
+	const action = existsSync(filePath) ? "Append to" : "Create";
+	p.note(`This tells your agent to check installed skills before making
+code changes. Without it, skills are available but may not
+activate automatically.
+
+\x1B[90m${getSkillInstructions(agent).replace(/\n/g, "\n")}\x1B[0m`, `${action} ${agentConfig.instructionFile}`);
 	const add = await p.confirm({
-		message: `Add skill activation instructions to ${agentConfig.instructionFile}?`,
+		message: `${action} ${agentConfig.instructionFile} with skill activation instructions?`,
 		initialValue: true
 	});
 	if (p.isCancel(add) || !add) return;
-	if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${SKILLD_INSTRUCTIONS}\n`);
-	else writeFileSync(filePath, `${SKILLD_INSTRUCTIONS}\n`);
+	if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${getSkillInstructions(agent)}\n`);
+	else writeFileSync(filePath, `${getSkillInstructions(agent)}\n`);
 	p.log.success(`Updated ${agentConfig.instructionFile}`);
 }
-/** Select LLM model for SKILL.md generation (independent of target agent) */
-async function selectModel(skipPrompt) {
-	const config = readConfig();
-	const available = await getAvailableModels();
-	if (available.length === 0) {
-		p.log.warn("No LLM CLIs found (claude, gemini, codex)");
-		return null;
-	}
-	if (skipPrompt) {
-		if (config.model && available.some((m) => m.id === config.model)) return config.model;
-		return available.find((m) => m.recommended)?.id ?? available[0].id;
-	}
-	const modelChoice = await p.select({
-		message: "Model for SKILL.md generation",
-		options: available.map((m) => ({
-			label: m.recommended ? `${m.name} (Recommended)` : m.name,
-			value: m.id,
-			hint: `${m.agentName} · ${m.hint}`
-		})),
-		initialValue: available.find((m) => m.recommended)?.id ?? available[0].id
-	});
-	if (p.isCancel(modelChoice)) {
-		p.cancel("Cancelled");
-		return null;
-	}
-	updateConfig({ model: modelChoice });
-	return modelChoice;
-}
 /** Default sections when model is pre-set (non-interactive) */
 const DEFAULT_SECTIONS = ["best-practices", "api-changes"];
-async function selectSkillSections(message = "Generate SKILL.md with LLM") {
+async function selectSkillSections(message = "Enhance SKILL.md") {
 	p.log.info("Budgets adapt to package release density.");
 	const selected = await p.multiselect({
 		message,
@@ -806,27 +860,62 @@ async function selectSkillSections(message = "Generate SKILL.md with LLM") {
 * If presetModel is provided, uses DEFAULT_SECTIONS without prompting.
 * Returns null if cancelled or no sections/model selected.
 */
-async function selectLlmConfig(presetModel, message) {
-	if (presetModel) return {
-		model: presetModel,
-		sections: DEFAULT_SECTIONS
-	};
+async function selectLlmConfig(presetModel, message, updateCtx) {
+	if (presetModel) {
+		if ((await getAvailableModels()).some((m) => m.id === presetModel)) return {
+			model: presetModel,
+			sections: DEFAULT_SECTIONS
+		};
+		if (!isInteractive()) return null;
+	}
 	if (!isInteractive()) return null;
-	const defaultModel = await selectModel(true);
-	if (!defaultModel) return null;
+	const config = readConfig();
+	const available = await getAvailableModels();
+	if (available.length === 0) {
+		p.log.warn(NO_MODELS_MESSAGE);
+		return null;
+	}
+	let defaultModel;
+	if (config.model && available.some((m) => m.id === config.model)) defaultModel = config.model;
+	else {
+		if (config.model) p.log.warn(`Configured model \x1B[36m${config.model}\x1B[0m is unavailable — using auto-selected fallback`);
+		defaultModel = available.find((m) => m.recommended)?.id ?? available[0].id;
+	}
 	const defaultModelName = getModelName(defaultModel);
+	const providerHint = available.find((m) => m.id === defaultModel)?.providerName ?? "";
+	const sourceHint = config.model === defaultModel ? "configured" : "recommended";
+	const defaultHint = providerHint ? `${providerHint} · ${sourceHint}` : sourceHint;
+	let enhanceMessage = "Enhance SKILL.md?";
+	let defaultToSkip = false;
+	if (updateCtx) {
+		const diff = updateCtx.bumpType ?? (updateCtx.oldVersion && updateCtx.newVersion ? semverDiff(updateCtx.oldVersion, updateCtx.newVersion) : null);
+		const isSmallBump = diff === "patch" || diff === "prerelease" || diff === "prepatch" || diff === "preminor" || diff === "premajor";
+		const ageParts = [];
+		if (diff) ageParts.push(diff);
+		if (updateCtx.syncedAt) {
+			const syncedAtMs = new Date(updateCtx.syncedAt).getTime();
+			if (Number.isFinite(syncedAtMs)) {
+				const days = Math.floor((Date.now() - syncedAtMs) / 864e5);
+				ageParts.push(days === 0 ? "today" : days === 1 ? "1d ago" : `${days}d ago`);
+			}
+		}
+		if (updateCtx.wasEnhanced) ageParts.push("LLM-enhanced");
+		const hint = [updateCtx.oldVersion && updateCtx.newVersion ? `${updateCtx.oldVersion} → ${updateCtx.newVersion}` : null, ...ageParts].filter(Boolean).join(" · ");
+		if (hint) enhanceMessage = `Enhance SKILL.md? \x1B[90m(${hint})\x1B[0m`;
+		if (updateCtx.wasEnhanced && isSmallBump) defaultToSkip = true;
+	}
 	const choice = await p.select({
-		message: "Generate enhanced SKILL.md?",
+		message: enhanceMessage,
 		options: [
 			{
 				label: defaultModelName,
 				value: "default",
-				hint: "configured default"
+				hint: defaultHint
 			},
 			{
 				label: "Different model",
 				value: "pick",
-				hint: "choose another model"
+				hint: "choose another enhancement model"
 			},
 			{
 				label: "Prompt only",
@@ -836,9 +925,10 @@ async function selectLlmConfig(presetModel, message) {
 			{
 				label: "Skip",
 				value: "skip",
-				hint: "base skill only"
+				hint: "base skill with docs, issues, and types"
 			}
-		]
+		],
+		...defaultToSkip ? { initialValue: "skip" } : {}
 	});
 	if (p.isCancel(choice)) return null;
 	if (choice === "skip") return null;
@@ -852,10 +942,16 @@ async function selectLlmConfig(presetModel, message) {
 			promptOnly: true
 		};
 	}
-	const model = choice === "pick" ? await selectModel(false) : defaultModel;
+	let model;
+	if (choice === "pick") {
+		const picked = await pickModel(available);
+		if (!picked) return null;
+		updateConfig({ model: picked });
+		model = picked;
+	} else model = defaultModel;
 	if (!model) return null;
 	const modelName = getModelName(model);
-	const { sections, customPrompt, cancelled } = await selectSkillSections(message ? `${message} (${modelName})` : `Generate SKILL.md with ${modelName}`);
+	const { sections, customPrompt, cancelled } = await selectSkillSections(message ? `${message} (${modelName})` : `Enhance SKILL.md with ${modelName}`);
 	if (cancelled || sections.length === 0) return null;
 	return {
 		model,
@@ -922,7 +1018,7 @@ async function enhanceSkillWithLLM(opts) {
 			eject
 		});
 		writeFileSync(join(skillDir, "SKILL.md"), skillMd);
-	} else llmLog.error(`LLM optimization failed${error ? `: ${error}` : ""}`);
+	} else llmLog.error(`Enhancement failed${error ? `: ${error}` : ""}`);
 }
 /**
 * Build and write PROMPT_*.md files for manual LLM use.
@@ -1302,10 +1398,93 @@ async function syncPackagesParallel(config) {
 	p.log.success(skillMsg);
 	for (const [, data] of skillData) for (const w of data.warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
 	if (errors.length > 0) for (const { pkg, reason } of errors) p.log.error(`  ${pkg}: ${reason}`);
+	const cachedPkgs = [];
+	if (!config.force) for (const pkg of successfulPkgs) {
+		const data = skillData.get(pkg);
+		const resolvedName = data.resolved.name;
+		if (DEFAULT_SECTIONS.every((s) => {
+			const outputFile = SECTION_OUTPUT_FILES[s];
+			return readCachedSection(resolvedName, data.version, outputFile) !== null;
+		})) {
+			const skillDir = join(resolveBaseDir(cwd, config.agent, config.global), data.skillDirName);
+			const cachedParts = [];
+			for (const s of SECTION_MERGE_ORDER) {
+				if (!DEFAULT_SECTIONS.includes(s)) continue;
+				const outputFile = SECTION_OUTPUT_FILES[s];
+				const content = readCachedSection(resolvedName, data.version, outputFile);
+				if (content) cachedParts.push(wrapSection(s, content));
+			}
+			const cachedBody = cachedParts.join("\n\n");
+			const skillMd = generateSkillMd({
+				name: resolvedName,
+				version: data.version,
+				releasedAt: data.resolved.releasedAt,
+				dependencies: data.resolved.dependencies,
+				distTags: data.resolved.distTags,
+				body: cachedBody,
+				relatedSkills: data.relatedSkills,
+				hasIssues: data.hasIssues,
+				hasDiscussions: data.hasDiscussions,
+				hasReleases: data.hasReleases,
+				hasChangelog: data.hasChangelog,
+				docsType: data.docsType,
+				hasShippedDocs: data.shippedDocs,
+				pkgFiles: data.pkgFiles,
+				generatedBy: "cached",
+				dirName: data.skillDirName,
+				packages: data.packages,
+				repoUrl: data.resolved.repoUrl,
+				features: data.features
+			});
+			writeFileSync(join(skillDir, "SKILL.md"), skillMd);
+			cachedPkgs.push(pkg);
+		}
+	}
+	const uncachedPkgs = successfulPkgs.filter((pkg) => !cachedPkgs.includes(pkg));
+	if (cachedPkgs.length > 0) p.log.success(`Applied cached SKILL.md sections for ${cachedPkgs.join(", ")}`);
 	const globalConfig = readConfig();
-	if (successfulPkgs.length > 0 && !globalConfig.skipLlm && !(config.yes && !config.model)) {
-		const llmConfig = await selectLlmConfig(config.model);
-		if (llmConfig?.promptOnly) for (const pkg of successfulPkgs) {
+	let resolvedModel = config.model || (config.yes && !globalConfig.skipLlm ? globalConfig.model : void 0);
+	if (!resolvedModel && config.yes && !globalConfig.skipLlm) {
+		const { getAvailableModels } = await import("../agent/index.mjs");
+		const available = await getAvailableModels();
+		const auto = available.find((m) => m.recommended)?.id ?? available[0]?.id;
+		if (auto) resolvedModel = auto;
+	}
+	if (uncachedPkgs.length > 0 && !globalConfig.skipLlm && !(config.yes && !resolvedModel)) {
+		const DIFF_RANK = {
+			major: 5,
+			premajor: 4,
+			minor: 3,
+			preminor: 2,
+			patch: 1,
+			prepatch: 1,
+			prerelease: 0
+		};
+		let parallelUpdateCtx;
+		if (config.mode === "update") {
+			let maxDiff = "";
+			let allEnhanced = true;
+			let anySyncedAt;
+			for (const pkg of successfulPkgs) {
+				const data = skillData.get(pkg);
+				if (!data.wasEnhanced) allEnhanced = false;
+				if (data.oldSyncedAt && (!anySyncedAt || data.oldSyncedAt < anySyncedAt)) anySyncedAt = data.oldSyncedAt;
+				if (data.oldVersion) {
+					const diff = semverDiff(data.oldVersion, data.version);
+					if (diff && (DIFF_RANK[diff] ?? 0) > (DIFF_RANK[maxDiff] ?? -1)) maxDiff = diff;
+				}
+			}
+			const first = skillData.get(successfulPkgs[0]);
+			parallelUpdateCtx = {
+				oldVersion: successfulPkgs.length === 1 ? first.oldVersion : void 0,
+				newVersion: successfulPkgs.length === 1 ? first.version : void 0,
+				syncedAt: anySyncedAt,
+				wasEnhanced: allEnhanced,
+				bumpType: maxDiff || void 0
+			};
+		}
+		const llmConfig = await selectLlmConfig(resolvedModel, void 0, parallelUpdateCtx);
+		if (llmConfig?.promptOnly) for (const pkg of uncachedPkgs) {
 			const data = skillData.get(pkg);
 			writePromptFiles({
 				packageName: pkg,
@@ -1325,19 +1504,19 @@ async function syncPackagesParallel(config) {
 		}
 		else if (llmConfig) {
 			p.log.step(getModelLabel(llmConfig.model));
-			for (const pkg of successfulPkgs) states.set(pkg, {
+			for (const pkg of uncachedPkgs) states.set(pkg, {
 				name: pkg,
 				status: "pending",
 				message: "Waiting..."
 			});
 			render();
-			const llmResults = await Promise.allSettled(successfulPkgs.map((pkg) => limit(() => enhanceWithLLM(pkg, skillData.get(pkg), {
+			const llmResults = await Promise.allSettled(uncachedPkgs.map((pkg) => limit(() => enhanceWithLLM(pkg, skillData.get(pkg), {
 				...config,
 				model: llmConfig.model
 			}, cwd, update, llmConfig.sections, llmConfig.customPrompt))));
 			logUpdate.done();
 			const llmSucceeded = llmResults.filter((r) => r.status === "fulfilled").length;
-			p.log.success(`Enhanced ${llmSucceeded}/${successfulPkgs.length} skills with LLM`);
+			p.log.success(`Enhanced ${llmSucceeded}/${uncachedPkgs.length} skills with LLM`);
 		}
 	}
 	await ensureGitignore(getSharedSkillsDir(cwd) ? SHARED_SKILLS_DIR : agent.skillsDir, cwd, config.global);
@@ -1388,9 +1567,25 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 	if (useCache) update(packageName, "downloading", "Using cache", versionKey);
 	else update(packageName, "downloading", config.force ? "Re-fetching docs..." : "Fetching docs...", versionKey);
 	const baseDir = resolveBaseDir(cwd, config.agent, config.global);
-	const skillDirName = computeSkillDirName(packageName);
+	let skillDirName = computeSkillDirName(packageName);
+	if (config.mode === "update") {
+		const lock = readLock(baseDir);
+		if (lock) {
+			for (const [name, info] of Object.entries(lock.skills)) if (info.packageName === packageName || parsePackages(info.packages).some((p) => p.name === packageName)) {
+				skillDirName = name;
+				break;
+			}
+		}
+	}
 	const skillDir = join(baseDir, skillDirName);
 	mkdirSync(skillDir, { recursive: true });
+	const preLock = config.mode === "update" ? readLock(baseDir)?.skills[skillDirName] : void 0;
+	const preEnhanced = (() => {
+		if (!preLock) return false;
+		const skillMdPath = join(skillDir, "SKILL.md");
+		if (!existsSync(skillMdPath)) return false;
+		return !!parseFrontmatter(readFileSync(skillMdPath, "utf-8")).generated_by;
+	})();
 	const features = readConfig().features ?? defaultFeatures;
 	const resources = await fetchAndCacheResources({
 		packageName,
@@ -1469,7 +1664,10 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 		packages: allPackages.length > 1 ? allPackages : void 0,
 		warnings: resources.warnings,
 		features,
-		usedCache: resources.usedCache
+		usedCache: resources.usedCache,
+		oldVersion: preLock?.version,
+		oldSyncedAt: preLock?.syncedAt,
+		wasEnhanced: preEnhanced
 	};
 }
 /** Phase 2: Enhance skill with LLM */
@@ -1533,13 +1731,23 @@ async function enhanceWithLLM(packageName, data, config, cwd, update, sections,
 }
 //#endregion
 //#region src/commands/sync.ts
+const RESOLVE_SOURCE_LABELS = {
+	"npm": "npm registry",
+	"github-docs": "GitHub versioned docs",
+	"github-meta": "GitHub metadata",
+	"github-search": "GitHub search",
+	"readme": "README fallback",
+	"llms.txt": "llms.txt convention",
+	"crawl": "website crawl",
+	"local": "local node_modules"
+};
 function showResolveAttempts(attempts) {
 	if (attempts.length === 0) return;
-	p.log.message("\x1B[90mResolution attempts:\x1B[0m");
+	p.log.message("\x1B[90mDoc resolution:\x1B[0m");
 	for (const attempt of attempts) {
 		const icon = attempt.status === "success" ? "\x1B[32m✓\x1B[0m" : "\x1B[90m✗\x1B[0m";
-		const source = `\x1B[90m${attempt.source}\x1B[0m`;
-		const msg = attempt.message ? ` - ${attempt.message}` : "";
+		const source = `\x1B[90m${RESOLVE_SOURCE_LABELS[attempt.source] ?? attempt.source}\x1B[0m`;
+		const msg = attempt.message ? ` \x1B[90m— ${attempt.message}\x1B[0m` : "";
 		p.log.message(`  ${icon} ${source}${msg}`);
 	}
 }
@@ -1696,11 +1904,31 @@ async function syncSinglePackage(packageSpec, config) {
 	}
 	ensureCacheDir();
 	const baseDir = resolveBaseDir(cwd, config.agent, config.global);
-	const skillDirName = config.name ? sanitizeName(config.name) : computeSkillDirName(packageName);
+	let skillDirName = config.name ? sanitizeName(config.name) : computeSkillDirName(packageName);
+	if (config.mode === "update" && !config.name) {
+		const lock = readLock(baseDir);
+		if (lock) {
+			for (const [name, info] of Object.entries(lock.skills)) if (info.packageName === packageName || parsePackages(info.packages).some((p) => p.name === packageName)) {
+				skillDirName = name;
+				break;
+			}
+		}
+	}
 	const skillDir = config.eject ? typeof config.eject === "string" ? join(resolve(cwd, config.eject), skillDirName) : join(cwd, "skills", skillDirName) : join(baseDir, skillDirName);
 	mkdirSync(skillDir, { recursive: true });
 	const existingLock = config.eject ? void 0 : readLock(baseDir)?.skills[skillDirName];
-	if (existingLock && existingLock.packageName && existingLock.packageName !== packageName) {
+	const isMerge = existingLock && existingLock.packageName && existingLock.packageName !== packageName;
+	const updateCtx = config.mode === "update" && existingLock ? {
+		oldVersion: existingLock.version,
+		newVersion: version,
+		syncedAt: existingLock.syncedAt,
+		wasEnhanced: (() => {
+			const skillMdPath = join(skillDir, "SKILL.md");
+			if (!existsSync(skillMdPath)) return false;
+			return !!parseFrontmatter(readFileSync(skillMdPath, "utf-8")).generated_by;
+		})()
+	} : void 0;
+	if (isMerge) {
 		spin.stop(`Merging ${packageName} into ${skillDirName}`);
 		linkPkgNamed(skillDir, packageName, cwd, version);
 		const repoSlug = resolved.repoUrl?.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?(?:[/#]|$)/)?.[1];
@@ -1815,8 +2043,54 @@ async function syncSinglePackage(packageSpec, config) {
 	});
 	writeFileSync(join(skillDir, "SKILL.md"), baseSkillMd);
 	p.log.success(config.mode === "update" ? `Updated skill: ${relative(cwd, skillDir)}` : `Created base skill: ${relative(cwd, skillDir)}`);
-	if (!readConfig().skipLlm && (!config.yes || config.model)) {
-		const llmConfig = await selectLlmConfig(config.model);
+	const allSectionsCached = !config.force && DEFAULT_SECTIONS.every((s) => {
+		const outputFile = SECTION_OUTPUT_FILES[s];
+		return readCachedSection(packageName, version, outputFile) !== null;
+	});
+	if (allSectionsCached) {
+		const cachedParts = [];
+		for (const s of SECTION_MERGE_ORDER) {
+			if (!DEFAULT_SECTIONS.includes(s)) continue;
+			const outputFile = SECTION_OUTPUT_FILES[s];
+			const content = readCachedSection(packageName, version, outputFile);
+			if (content) cachedParts.push(wrapSection(s, content));
+		}
+		const cachedBody = cachedParts.join("\n\n");
+		const skillMd = generateSkillMd({
+			name: packageName,
+			version,
+			releasedAt: resolved.releasedAt,
+			description: resolved.description,
+			dependencies: resolved.dependencies,
+			distTags: resolved.distTags,
+			body: cachedBody,
+			relatedSkills,
+			hasIssues: resources.hasIssues,
+			hasDiscussions: resources.hasDiscussions,
+			hasReleases: resources.hasReleases,
+			hasChangelog,
+			docsType: resources.docsType,
+			hasShippedDocs: shippedDocs,
+			pkgFiles,
+			generatedBy: "cached",
+			dirName: skillDirName,
+			packages: allPackages.length > 1 ? allPackages : void 0,
+			repoUrl: resolved.repoUrl,
+			features,
+			eject: isEject
+		});
+		writeFileSync(join(skillDir, "SKILL.md"), skillMd);
+		p.log.success("Applied cached SKILL.md sections");
+	}
+	const globalConfig = readConfig();
+	let resolvedModel = config.model || (config.yes && !globalConfig.skipLlm ? globalConfig.model : void 0);
+	if (!resolvedModel && config.yes && !globalConfig.skipLlm) {
+		const available = await getAvailableModels();
+		const auto = available.find((m) => m.recommended)?.id ?? available[0]?.id;
+		if (auto) resolvedModel = auto;
+	}
+	if (!allSectionsCached && !globalConfig.skipLlm && !(config.yes && !resolvedModel)) {
+		const llmConfig = await selectLlmConfig(resolvedModel, void 0, updateCtx);
 		if (llmConfig?.promptOnly) writePromptFiles({
 			packageName,
 			skillDir,
@@ -1876,7 +2150,8 @@ async function syncSinglePackage(packageSpec, config) {
 	}
 	await shutdownWorker();
 	const ejectMsg = isEject ? " (ejected)" : "";
-	p.outro(config.mode === "update" ? `Updated ${packageName}${ejectMsg}` : `Synced ${packageName} to ${relative(cwd, skillDir)}${ejectMsg}`);
+	const relDir = relative(cwd, skillDir);
+	p.outro(config.mode === "update" ? `Updated ${packageName}${ejectMsg}` : `Synced ${packageName} → ${relDir}${ejectMsg}`);
 }
 const addCommandDef = defineCommand({
 	meta: {
@@ -1913,7 +2188,7 @@ const addCommandDef = defineCommand({
 			});
 			return;
 		}
-		if (!hasCompletedWizard()) await runWizard();
+		if (!hasCompletedWizard()) await runWizard({ agent });
 		const gitSources = [];
 		const npmTokens = [];
 		for (const input of rawInputs) {
@@ -1937,7 +2212,10 @@ const addCommandDef = defineCommand({
 		if (npmTokens.length > 0) {
 			const packages = [...new Set(npmTokens.flatMap((s) => s.split(/[,\s]+/)).map((s) => s.trim()).filter(Boolean))];
 			const state = await getProjectState(cwd);
-			p.intro(introLine({ state }));
+			p.intro(introLine({
+				state,
+				agentId: agent || void 0
+			}));
 			return syncCommand(state, {
 				packages,
 				global: args.global,
@@ -1986,9 +2264,12 @@ const ejectCommandDef = defineCommand({
 		const cwd = process.cwd();
 		const resolved = resolveAgent(args.agent);
 		const agent = resolved && resolved !== "none" ? resolved : "claude-code";
-		if (!hasCompletedWizard()) await runWizard();
+		if (!hasCompletedWizard()) await runWizard({ agent });
 		const state = await getProjectState(cwd);
-		p.intro(introLine({ state }));
+		p.intro(introLine({
+			state,
+			agentId: agent || void 0
+		}));
 		return syncCommand(state, {
 			packages: [args.package],
 			global: args.global,
@@ -2066,7 +2347,8 @@ const updateCommandDef = defineCommand({
 			p.intro(introLine({
 				state,
 				generators,
-				modelId: config.model
+				modelId: config.model,
+				agentId: config.agent || agent || void 0
 			}));
 		}
 		if (args.package) return syncCommand(state, {
@@ -2126,7 +2408,7 @@ async function exportPortablePrompts(packageSpec, opts) {
 	ensureCacheDir();
 	const skillDirName = computeSkillDirName(packageName);
 	const features = readConfig().features ?? defaultFeatures;
-	const agent = opts.agent === "none" ? null : opts.agent ?? await import("./detect.mjs").then((n) => n.r).then((m) => m.detectTargetAgent());
+	const agent = opts.agent === "none" ? null : opts.agent ?? await import("./detect2.mjs").then((m) => m.detectTargetAgent());
 	const baseDir = agent ? resolveBaseDir(cwd, agent, false) : join(cwd, ".claude", "skills");
 	const skillDir = opts.out ? resolve(cwd, opts.out) : join(baseDir, skillDirName);
 	if (existsSync(skillDir) && !opts.force) {