skilld 1.7.2 → 1.7.4

package/dist/_chunks/sync.mjs

@@ -1,28 +1,26 @@
-import { a as getModelLabel, i as getAvailableModels, s as optimizeDocs, t as detectImportedPackages } from "./agent.mjs";
-import { i as CACHE_DIR, r as getVersionKey, t as getCacheDir } from "./version.mjs";
-import { r as resolvePkgDir } from "./prepare.mjs";
+import { d as getSharedSkillsDir, g as skillRefsSection, t as CACHE_DIR } from "./paths.mjs";
+import { A as getActiveFeatures, M as hasCompletedWizard, P as readConfig, h as listReferenceFiles, i as ensureCacheDir, t as createReferenceCache } from "./cache.mjs";
+import { r as getVersionKey } from "./version.mjs";
 import { n as sanitizeMarkdown } from "./sanitize.mjs";
-import { a as hasShippedDocs, d as linkPkgNamed, g as readCachedSection, i as getPkgKeyFiles, m as listReferenceFiles, r as ensureCacheDir, s as isCached } from "./cache.mjs";
 import { i as parseFrontmatter } from "./markdown.mjs";
-import { a as semverDiff, n as getSharedSkillsDir, t as SHARED_SKILLS_DIR } from "./shared.mjs";
-import { J as isPrerelease, M as resolveGitHubRepo, f as resolvePackageDocsWithAttempts, i as fetchPkgDist, it as parsePackageSpec, m as fetchGitSkills, nt as parseGitHubRepoSlug, p as searchNpmPackages, s as readLocalDependencies, w as resolveCrateDocsWithAttempts } from "./sources.mjs";
+import { P as resolveGitHubRepo, a as toStoragePackageName, b as fetchGitSkills, dt as parsePackageSpec, i as resolveSkillName, l as fetchPkgDist, lt as parseGitHubRepoSlug, n as isCrateSpec, r as parseSkillInput, t as resolvePackageOrCrate, tt as isPrerelease, v as searchNpmPackages } from "./sources.mjs";
 import { a as targets } from "./detect.mjs";
-import { c as wrapSection, n as SECTION_OUTPUT_FILES, r as buildAllSectionPrompts, s as portabilizePrompt, t as SECTION_MERGE_ORDER } from "./prompts.mjs";
-import { _ as timedSpinner, i as computeSkillDirName, n as writeGeneratedSkillMd, o as linkSkillToAgents, r as writeSkillMd, s as sanitizeName, u as formatDuration, v as todayIsoDate } from "./skill.mjs";
-import { a as readConfig, o as registerProject, r as hasCompletedWizard, t as defaultFeatures } from "./config.mjs";
+import { i as getModelLabel, n as detectImportedPackages } from "./agent.mjs";
+import { C as portabilizePrompt, E as SECTION_OUTPUT_FILES, _ as timedSpinner, i as computeSkillDirName, n as writeGeneratedSkillMd, o as linkSkillToAgents, r as writeSkillMd, s as sanitizeName, u as formatDuration, v as todayIsoDate, y as buildAllSectionPrompts } from "./prompts.mjs";
 import { S as suggestPrepareHook, _ as promptForAgent, b as resolveAgent, f as introLine, o as getInstalledGenerators, p as isInteractive, x as sharedArgs } from "./cli-helpers.mjs";
-import { a as readLock, c as writeLock, n as parsePackageNames, o as removeLockEntry, r as parsePackages } from "./lockfile.mjs";
+import { a as parsePackageNames, c as readLock, d as writeLock, n as findSkillDirByPackage } from "./lockfile.mjs";
+import { t as semverDiff } from "./semver.mjs";
 import { t as getProjectState } from "./skills.mjs";
-import { n as resolveSkillName, r as toStoragePackageName, t as parseSkillInput } from "./prefix.mjs";
 import { t as runWizard } from "./wizard.mjs";
-import { S as writePromptFiles, _ as linkAllReferences, b as selectLlmConfig, c as ejectReferences, d as ensureGitignore, f as fetchAndCacheResources, g as indexResources, h as handleShippedSkills, l as enhanceSkillWithLLM, m as forceClearCache, n as RESOLVE_STEP_LABELS, o as detectChangelog, p as findRelatedSkills, t as DEFAULT_SECTIONS, u as ensureAgentInstructions, v as resolveBaseDir, y as resolveLocalDep } from "./sync-shared2.mjs";
+import { a as ensureProjectFiles, c as linkShippedToAgents, i as ensureGitignore, l as resolveBaseDir, o as handleShippedSkills, s as installSkill } from "./skill-installer2.mjs";
+import { a as prepareSkillReferences, c as resolveAutoModel, d as applyCachedSections, h as writePromptFiles, i as findRelatedSkills, l as selectLlmConfig, m as writeBaseSkill, p as runSkillEnhancement, r as fetchAndCacheResources, s as DEFAULT_SECTIONS, t as buildSkillContext } from "./sync-pipeline.mjs";
 import { n as shutdownWorker } from "./pool2.mjs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "pathe";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import pLimit from "p-limit";
-import { isCI } from "std-env";
 import * as p from "@clack/prompts";
 import { defineCommand } from "citty";
+import { isCI } from "std-env";
 import logUpdate from "log-update";
 const TELEMETRY_URL = "https://add-skill.vercel.sh/t";
 const SKILLS_VERSION = "1.3.9";
@@ -39,6 +37,374 @@ function track(data) {
 		fetch(`${TELEMETRY_URL}?${params.toString()}`).catch(() => {});
 	} catch {}
 }
+const npmResolver = async (spec, opts) => {
+	const resolution = await resolvePackageOrCrate(spec, {
+		cwd: opts.cwd,
+		onProgress: (msg) => opts.onProgress(`${spec}: ${msg}`)
+	});
+	const { isCrate, packageName, identityPackageName, storagePackageName, requestedTag, localVersion, attempts, registryVersion } = resolution;
+	if (!resolution.resolved) {
+		const result = {
+			identityName: identityPackageName,
+			attempts,
+			registryVersion
+		};
+		if (!isCrate) {
+			const shipped = handleShippedSkills(packageName, localVersion || registryVersion || "latest", opts.cwd, opts.agent, opts.global);
+			if (shipped) result.shipped = shipped.shipped;
+		}
+		return result;
+	}
+	const resolved = resolution.resolved;
+	return {
+		identityName: identityPackageName,
+		storageName: storagePackageName,
+		version: isCrate ? resolved.version || requestedTag || "latest" : localVersion || resolved.version || "latest",
+		resolved,
+		kind: isCrate ? "crate" : "npm",
+		requestedTag,
+		localVersion
+	};
+};
+function createGithubResolver(owner, repo) {
+	return async (_spec, opts) => {
+		const resolved = await resolveGitHubRepo(owner, repo, (msg) => opts.onProgress(msg));
+		if (!resolved) return {
+			identityName: `${owner}-${repo}`,
+			attempts: [{
+				source: "github-meta",
+				status: "not-found",
+				message: `Could not find docs for ${owner}/${repo}`
+			}]
+		};
+		const repoUrl = `https://github.com/${owner}/${repo}`;
+		const name = `${owner}-${repo}`;
+		return {
+			identityName: name,
+			storageName: name,
+			version: resolved.version || "main",
+			resolved: {
+				...resolved,
+				repoUrl
+			},
+			kind: "github"
+		};
+	};
+}
+const RATE_LIMIT_RE = /\b429\b|rate.?limit|exhausted.*capacity|quota.*reset/i;
+async function runBaseSync(spec, config, ui, resolver, cwd, defaultSections) {
+	ui.resolveStart(spec);
+	const resolverResult = await resolver(spec, {
+		cwd,
+		agent: config.agent,
+		global: config.global,
+		onProgress: (msg) => ui.resolveProgress(msg)
+	});
+	if (!("resolved" in resolverResult)) {
+		if (resolverResult.shipped && resolverResult.shipped.length > 0) {
+			for (const s of resolverResult.shipped) ui.shippedInstalled(s.skillName, relative(cwd, s.skillDir));
+			return { kind: "shipped" };
+		}
+		ui.resolveFailed(resolverResult.identityName);
+		return {
+			kind: "unresolved",
+			unresolved: resolverResult
+		};
+	}
+	const { identityName, storageName, version, resolved, kind, requestedTag, localVersion } = resolverResult;
+	const cache = createReferenceCache(storageName, version);
+	if (config.force) cache.clearForce();
+	const useCache = cache.has();
+	if (kind !== "crate" && !existsSync(join(cwd, "node_modules", identityName))) {
+		ui.downloadingDist();
+		await fetchPkgDist(identityName, version);
+	}
+	if (kind !== "crate") {
+		const shipped = handleShippedSkills(identityName, version, cwd, config.agent, config.global);
+		if (shipped) {
+			linkShippedToAgents(shipped.shipped, cwd, config.agent, config.global);
+			for (const s of shipped.shipped) ui.shippedInstalled(s.skillName, relative(cwd, s.skillDir));
+			return { kind: "shipped" };
+		}
+	}
+	ui.resolveDone(version, {
+		cached: useCache,
+		force: config.force
+	});
+	if (kind === "npm" && !localVersion && !requestedTag && !isPrerelease(version)) {
+		const nextTag = resolved.distTags?.next ?? resolved.distTags?.beta ?? resolved.distTags?.alpha;
+		if (nextTag && (!resolved.releasedAt || !nextTag.releasedAt || nextTag.releasedAt > resolved.releasedAt)) ui.warn(`No local dependency found — using latest stable (${version}). Prerelease ${nextTag.version} available: skilld add ${identityName}@beta`);
+	}
+	cache.ensure();
+	const isEject = !!config.eject;
+	const baseDir = resolveBaseDir(cwd, config.agent, config.global);
+	let skillDirName = config.name ? sanitizeName(config.name) : computeSkillDirName(storageName);
+	if (config.mode === "update" && !config.name && !isEject) {
+		const lock = readLock(baseDir);
+		const found = lock ? findSkillDirByPackage(lock, identityName) : null;
+		if (found) skillDirName = found;
+	}
+	const skillDir = isEject ? typeof config.eject === "string" ? join(resolve(cwd, config.eject), skillDirName) : join(cwd, "skills", skillDirName) : join(baseDir, skillDirName);
+	mkdirSync(skillDir, { recursive: true });
+	const existingLock = isEject ? void 0 : readLock(baseDir)?.skills[skillDirName];
+	if (existingLock && existingLock.packageName && existingLock.packageName !== identityName) return {
+		kind: "merge-needed",
+		state: {
+			identityName,
+			storageName,
+			version,
+			resolved,
+			baseDir,
+			skillDir,
+			skillDirName,
+			existingLock
+		}
+	};
+	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;
+	const features = getActiveFeatures(config.noSearch ? { search: false } : void 0);
+	ui.fetchStart();
+	const resources = await fetchAndCacheResources({
+		packageName: storageName,
+		resolved,
+		version,
+		useCache,
+		features,
+		from: config.from,
+		onProgress: (msg) => ui.fetchProgress(msg)
+	});
+	const parts = [];
+	if (resources.docsToIndex.length > 0) {
+		const docCount = resources.docsToIndex.filter((d) => d.metadata?.type === "doc").length;
+		if (docCount > 0) parts.push(`${docCount} docs`);
+	}
+	if (resources.hasIssues) parts.push("issues");
+	if (resources.hasDiscussions) parts.push("discussions");
+	if (resources.hasReleases) parts.push("releases");
+	ui.fetchDone(parts, resources.usedCache);
+	for (const w of resources.warnings) ui.warn(w);
+	if (features.search) ui.indexStart();
+	const prepared = await prepareSkillReferences({
+		packageName: storageName,
+		version,
+		cwd,
+		skillDir,
+		resources,
+		features,
+		baseDir,
+		onIndexProgress: (msg) => ui.indexProgress(msg)
+	});
+	if (features.search) ui.indexDone();
+	if (!isEject) {
+		const repoSlug = parseGitHubRepoSlug(resolved.repoUrl);
+		cache.linkPkgNamed(skillDir, cwd);
+		const lock = {
+			packageName: identityName,
+			version,
+			repo: repoSlug,
+			source: resources.docSource,
+			syncedAt: todayIsoDate(),
+			generator: "skilld"
+		};
+		installSkill({
+			cwd,
+			agent: config.agent,
+			global: config.global,
+			baseDir,
+			skillDirName,
+			lock,
+			dedupePackageName: identityName,
+			skipLinkAgents: true
+		});
+	}
+	const allPackages = parsePackageNames((isEject ? void 0 : readLock(baseDir)?.skills[skillDirName])?.packages);
+	const ctx = buildSkillContext({
+		packageName: identityName,
+		cachePackageName: storageName,
+		version,
+		skillDir,
+		skillDirName,
+		resources,
+		prepared,
+		resolved,
+		packages: allPackages,
+		features
+	});
+	ctx.overheadLines = writeBaseSkill(ctx, { eject: isEject }).split("\n").length;
+	ui.baseDone(relative(cwd, skillDir), config.mode === "update" ? "update" : "add");
+	const allSectionsCached = !config.force && applyCachedSections(ctx, defaultSections, { eject: isEject });
+	if (allSectionsCached) ui.sectionsCached();
+	return {
+		kind: "ready",
+		state: {
+			ctx,
+			skillDir,
+			skillDirName,
+			baseDir,
+			updateCtx,
+			allSectionsCached,
+			identityName,
+			storageName,
+			version,
+			docsType: resources.docsType,
+			repoInfo: resources.repoInfo
+		}
+	};
+}
+async function runEnhancePhase(state, llmConfig, config, ui, cwd) {
+	const isEject = !!config.eject;
+	if (llmConfig?.promptOnly) writePromptFiles({
+		...state.ctx,
+		packageName: state.ctx.cachePackageName ?? state.ctx.packageName,
+		cachePackageName: void 0
+	}, {
+		sections: llmConfig.sections,
+		customPrompt: llmConfig.customPrompt
+	});
+	else if (llmConfig) await enhanceWithUi(state.ctx, llmConfig, {
+		...config,
+		eject: isEject
+	}, ui);
+	if (isEject) {
+		const cache = createReferenceCache(state.storageName, state.version);
+		if (!config.debug) cache.clearSkillInternal(state.skillDir);
+		cache.eject(state.skillDir, cwd, state.docsType, {
+			features: state.ctx.features ?? getActiveFeatures(),
+			repoInfo: state.repoInfo
+		});
+		return;
+	}
+	const shared = config.global ? false : getSharedSkillsDir(cwd) ?? false;
+	if (shared) linkSkillToAgents(state.skillDirName, shared, cwd, config.agent);
+	await ensureProjectFiles({
+		cwd,
+		agent: config.agent,
+		global: config.global,
+		shared
+	});
+}
+async function enhanceWithUi(ctx, llmConfig, config, ui) {
+	ui.llmStart(getModelLabel(llmConfig.model));
+	const result = await runSkillEnhancement(ctx, {
+		model: llmConfig.model,
+		force: config.force,
+		debug: config.debug,
+		sections: llmConfig.sections,
+		customPrompt: llmConfig.customPrompt,
+		eject: !!config.eject
+	}, (progress) => ui.llmProgress(progress));
+	if (result.wasOptimized) ui.llmDone({
+		usage: result.usage ? { totalTokens: result.usage.totalTokens } : void 0,
+		cost: result.cost,
+		debugLogsDir: result.debugLogsDir,
+		error: result.error,
+		warnings: result.warnings
+	});
+	else ui.llmFailed(result.error ?? "", { rateLimited: !!result.error && RATE_LIMIT_RE.test(result.error) });
+}
+function createClackUi({ cwd }) {
+	let spinner = null;
+	let resourceSpinner = null;
+	let indexSpinner = null;
+	let llmLog = null;
+	let currentSpec = "";
+	return {
+		resolveStart(spec) {
+			currentSpec = spec;
+			spinner = timedSpinner();
+			spinner.start(`Resolving ${spec}`);
+		},
+		resolveProgress(msg) {
+			spinner?.message(msg);
+		},
+		resolveDone(version, opts) {
+			const suffix = opts.force ? " (force)" : opts.cached ? " (cached)" : "";
+			spinner?.stop(`Resolved ${currentSpec}@${version}${suffix}`);
+			spinner = null;
+		},
+		resolveFailed(identityName) {
+			spinner?.stop(`Could not find docs for: ${identityName}`);
+			spinner = null;
+		},
+		downloadingDist() {
+			spinner?.message("Downloading dist");
+		},
+		fetchStart() {
+			resourceSpinner = timedSpinner();
+			resourceSpinner.start("Finding resources");
+		},
+		fetchProgress(msg) {
+			resourceSpinner?.message(msg);
+		},
+		fetchDone(parts, cached) {
+			const summary = parts.length > 0 ? parts.join(", ") : "resources";
+			resourceSpinner?.stop(cached ? `Loaded ${summary} (cached)` : `Fetched ${summary}`);
+			resourceSpinner = null;
+		},
+		indexStart() {
+			indexSpinner = timedSpinner();
+			indexSpinner.start("Creating search index");
+		},
+		indexProgress(msg) {
+			indexSpinner?.message(msg);
+		},
+		indexDone() {
+			indexSpinner?.stop("Search index ready");
+			indexSpinner = null;
+		},
+		warn(msg) {
+			p.log.warn(`\x1B[33m${msg}\x1B[0m`);
+		},
+		baseDone(relPath, mode) {
+			p.log.success(mode === "update" ? `Updated skill: ${relPath}` : `Created base skill: ${relPath}`);
+		},
+		sectionsCached() {
+			p.log.success("Applied cached SKILL.md sections");
+		},
+		llmStart(modelLabel) {
+			p.log.step(modelLabel);
+			llmLog = p.taskLog({
+				title: `Agent exploring ${currentSpec}`,
+				limit: 3
+			});
+		},
+		llmProgress(progress) {
+			if (!llmLog) return;
+			const sectionPrefix = progress.section ? `[${progress.section}] ` : "";
+			const line = progress.chunk.startsWith("[") ? `${sectionPrefix}${progress.chunk}` : `${sectionPrefix}${progress.chunk}`;
+			llmLog.message(line);
+		},
+		llmDone(info) {
+			if (!llmLog) return;
+			const parts = [];
+			if (info.usage) parts.push(`${Math.round(info.usage.totalTokens / 1e3)}k tokens`);
+			if (info.cost) parts.push(`$${info.cost.toFixed(2)}`);
+			const suffix = parts.length > 0 ? ` (${parts.join(", ")})` : "";
+			llmLog.success(`Generated best practices${suffix}`);
+			llmLog = null;
+			if (info.debugLogsDir) p.log.info(`Debug logs: ${relative(cwd, info.debugLogsDir)}`);
+			if (info.error) p.log.warn(`\x1B[33mPartial failure: ${info.error}\x1B[0m`);
+			if (info.warnings) for (const w of info.warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
+		},
+		llmFailed(error, opts) {
+			if (!llmLog) return;
+			if (opts.rateLimited) llmLog.error(`Rate limited by LLM provider. Try again shortly or use a different model via \`skilld config\``);
+			else llmLog.error(`Enhancement failed${error ? `: ${error}` : ""}`);
+			llmLog = null;
+		},
+		shippedInstalled(skillName, relPath) {
+			p.log.success(`Using published SKILL.md: ${skillName} → ${relPath}`);
+		}
+	};
+}
 async function syncGitSkills(opts) {
 	const { source, agent, global: isGlobal, yes } = opts;
 	const cwd = process.cwd();
@@ -93,16 +459,23 @@ async function syncGitSkills(opts) {
 			writeFileSync(filePath, f.content);
 		}
 		const sourceType = source.type === "local" ? "local" : source.type;
-		writeLock(baseDir, skill.name, {
-			source: sourceType,
-			repo: source.type === "local" ? source.localPath : `${source.owner}/${source.repo}`,
-			path: skill.path || void 0,
-			ref: source.ref || "main",
-			syncedAt: todayIsoDate(),
-			generator: "external"
+		installSkill({
+			cwd,
+			agent,
+			global: isGlobal,
+			baseDir,
+			skillDirName: skill.name,
+			lock: {
+				source: sourceType,
+				repo: source.type === "local" ? source.localPath : `${source.owner}/${source.repo}`,
+				path: skill.path || void 0,
+				ref: source.ref || "main",
+				syncedAt: todayIsoDate(),
+				generator: "external"
+			},
+			skipLinkAgents: true
 		});
 	}
-	if (!isGlobal) registerProject(cwd);
 	if (source.type !== "local" && source.owner && source.repo) track({
 		event: "install",
 		source: `${source.owner}/${source.repo}`,
@@ -111,156 +484,92 @@ async function syncGitSkills(opts) {
 		...isGlobal && { global: "1" },
 		sourceType: source.type
 	});
-	const names = selected.map((s) => `\x1B[36m${s.name}\x1B[0m`).join(", ");
-	p.log.success(`Installed ${names}`);
+	for (const skill of selected) {
+		const skillRel = relative(cwd, join(baseDir, skill.name));
+		const fileLines = ["SKILL.md", ...skill.files.map((f) => f.path)].map((f) => `  \x1B[90m└\x1B[0m ${f}`).join("\n");
+		p.log.success(`Installed \x1B[36m${skill.name}\x1B[0m \x1B[90m→ ${skillRel}\x1B[0m\n${fileLines}`);
+	}
 }
 async function syncGitHubRepo(opts) {
 	const { source, agent, global: isGlobal, yes } = opts;
 	const owner = source.owner;
 	const repo = source.repo;
 	const cwd = process.cwd();
-	const spin = timedSpinner();
-	spin.start(`Resolving ${owner}/${repo}`);
-	const resolved = await resolveGitHubRepo(owner, repo, (msg) => spin.message(msg));
-	if (!resolved) {
-		spin.stop(`Could not find docs for ${owner}/${repo}`);
-		return;
-	}
-	const repoUrl = `https://github.com/${owner}/${repo}`;
-	const packageName = `${owner}-${repo}`;
-	const version = resolved.version || "main";
-	const versionKey = getVersionKey(version);
-	const useCache = isCached(packageName, version);
-	spin.stop(`Resolved ${owner}/${repo}@${useCache ? versionKey : version}${useCache ? " (cached)" : ""}`);
-	ensureCacheDir();
-	const baseDir = resolveBaseDir(cwd, agent, isGlobal);
-	const skillDirName = sanitizeName(`${owner}-${repo}`);
-	const skillDir = join(baseDir, skillDirName);
-	mkdirSync(skillDir, { recursive: true });
-	const features = readConfig().features ?? defaultFeatures;
-	const resSpin = timedSpinner();
-	resSpin.start("Finding resources");
-	const resources = await fetchAndCacheResources({
-		packageName,
-		resolved,
-		version,
-		useCache,
-		features,
-		from: opts.from,
-		onProgress: (msg) => resSpin.message(msg)
+	const ui = createClackUi({ cwd });
+	const spec = `${owner}/${repo}`;
+	const result = await runBaseSync(spec, {
+		agent,
+		global: isGlobal,
+		force: opts.force,
+		from: opts.from
+	}, ui, createGithubResolver(owner, repo), cwd, DEFAULT_SECTIONS);
+	if (result.kind !== "ready") return;
+	const { state } = result;
+	const globalConfig = readConfig();
+	let llmConfig = null;
+	if (!state.allSectionsCached && !globalConfig.skipLlm && (!yes || opts.model)) llmConfig = await selectLlmConfig(opts.model);
+	await runEnhancePhase(state, llmConfig, {
+		agent,
+		global: isGlobal,
+		force: opts.force,
+		debug: opts.debug
+	}, ui, cwd);
+	await shutdownWorker();
+	track({
+		event: "install",
+		source: spec,
+		skills: state.skillDirName,
+		agents: agent,
+		...isGlobal && { global: "1" },
+		sourceType: "github-generated"
 	});
-	const resParts = [];
-	if (resources.docsToIndex.length > 0) {
-		const docCount = resources.docsToIndex.filter((d) => d.metadata?.type === "doc").length;
-		if (docCount > 0) resParts.push(`${docCount} docs`);
-	}
-	if (resources.hasIssues) resParts.push("issues");
-	if (resources.hasDiscussions) resParts.push("discussions");
-	if (resources.hasReleases) resParts.push("releases");
-	resSpin.stop(`Fetched ${resParts.length > 0 ? resParts.join(", ") : "resources"}`);
-	for (const w of resources.warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
-	linkAllReferences(skillDir, packageName, cwd, version, resources.docsType, void 0, features);
-	if (features.search) {
-		const idxSpin = timedSpinner();
-		idxSpin.start("Creating search index");
-		await indexResources({
-			packageName,
+	p.outro(`Synced ${spec} to ${relative(cwd, state.skillDir)}`);
+}
+async function handleMerge(state, config, cwd) {
+	const { identityName, storageName, version, resolved, baseDir, skillDir, skillDirName, existingLock } = state;
+	p.log.step(`Merging ${identityName} into ${skillDirName}`);
+	createReferenceCache(storageName, version).linkPkgNamed(skillDir, cwd);
+	const repoSlug = parseGitHubRepoSlug(resolved.repoUrl);
+	installSkill({
+		cwd,
+		agent: config.agent,
+		global: config.global,
+		baseDir,
+		skillDirName,
+		lock: {
+			packageName: identityName,
 			version,
-			cwd,
-			docsToIndex: resources.docsToIndex,
-			features,
-			onProgress: (msg) => idxSpin.message(msg)
-		});
-		idxSpin.stop("Search index ready");
-	}
-	const hasChangelog = detectChangelog(resolvePkgDir(packageName, cwd, version), getCacheDir(packageName, version));
-	const shippedDocs = hasShippedDocs(packageName, cwd, version);
-	const pkgFiles = getPkgKeyFiles(packageName, cwd, version);
-	writeLock(baseDir, skillDirName, {
-		packageName,
-		version,
-		repo: `${owner}/${repo}`,
-		source: resources.docSource,
-		syncedAt: todayIsoDate(),
-		generator: "skilld"
+			repo: repoSlug,
+			source: existingLock.source,
+			syncedAt: todayIsoDate(),
+			generator: "skilld"
+		},
+		skipLinkAgents: true
 	});
+	const updatedLock = readLock(baseDir)?.skills[skillDirName];
+	const allPackages = parsePackageNames(updatedLock?.packages);
+	const relatedSkills = await findRelatedSkills(storageName, baseDir);
+	const existingCache = createReferenceCache(toStoragePackageName(existingLock.packageName), existingLock.version);
+	const pkgFiles = existingCache.keyFiles(cwd);
+	const shippedDocs = existingCache.hasShipped(cwd);
+	const features = getActiveFeatures();
 	writeGeneratedSkillMd(skillDir, {
-		name: packageName,
-		version,
-		releasedAt: resolved.releasedAt,
-		description: resolved.description,
-		relatedSkills: [],
-		hasIssues: resources.hasIssues,
-		hasDiscussions: resources.hasDiscussions,
-		hasReleases: resources.hasReleases,
-		hasChangelog,
-		docsType: resources.docsType,
+		name: existingLock.packageName,
+		version: existingLock.version,
+		relatedSkills,
+		hasIssues: features.issues && existsSync(skillRefsSection(skillDir, "issues")),
+		hasDiscussions: features.discussions && existsSync(skillRefsSection(skillDir, "discussions")),
+		hasReleases: features.releases && existsSync(skillRefsSection(skillDir, "releases")),
+		docsType: existingLock.source?.includes("llms.txt") ? "llms.txt" : "docs",
 		hasShippedDocs: shippedDocs,
 		pkgFiles,
 		dirName: skillDirName,
-		repoUrl,
+		packages: allPackages,
 		features
 	});
-	p.log.success(`Created base skill: ${relative(cwd, skillDir)}`);
-	if (!readConfig().skipLlm && (!yes || opts.model)) {
-		const llmConfig = await selectLlmConfig(opts.model);
-		if (llmConfig?.promptOnly) writePromptFiles({
-			packageName,
-			skillDir,
-			version,
-			hasIssues: resources.hasIssues,
-			hasDiscussions: resources.hasDiscussions,
-			hasReleases: resources.hasReleases,
-			hasChangelog,
-			docsType: resources.docsType,
-			hasShippedDocs: shippedDocs,
-			pkgFiles,
-			sections: llmConfig.sections,
-			customPrompt: llmConfig.customPrompt,
-			features
-		});
-		else if (llmConfig) {
-			p.log.step(getModelLabel(llmConfig.model));
-			await enhanceSkillWithLLM({
-				packageName,
-				version,
-				skillDir,
-				dirName: skillDirName,
-				model: llmConfig.model,
-				resolved,
-				relatedSkills: [],
-				hasIssues: resources.hasIssues,
-				hasDiscussions: resources.hasDiscussions,
-				hasReleases: resources.hasReleases,
-				hasChangelog,
-				docsType: resources.docsType,
-				hasShippedDocs: shippedDocs,
-				pkgFiles,
-				force: opts.force,
-				debug: opts.debug,
-				sections: llmConfig.sections,
-				customPrompt: llmConfig.customPrompt,
-				features
-			});
-		}
-	}
-	const shared = !isGlobal && getSharedSkillsDir(cwd);
-	if (shared) linkSkillToAgents(skillDirName, shared, cwd, agent);
-	if (!isGlobal) {
-		registerProject(cwd);
-		await ensureGitignore(shared || targets[agent].skillsDir, cwd, isGlobal);
-		await ensureAgentInstructions(agent, cwd, isGlobal);
-	}
-	await shutdownWorker();
-	track({
-		event: "install",
-		source: `${owner}/${repo}`,
-		skills: skillDirName,
-		agents: agent,
-		...isGlobal && { global: "1" },
-		sourceType: "github-generated"
-	});
-	p.outro(`Synced ${owner}/${repo} to ${relative(cwd, skillDir)}`);
+	const sharedDir = !config.global && getSharedSkillsDir(cwd);
+	if (sharedDir) linkSkillToAgents(skillDirName, sharedDir, cwd, config.agent);
+	p.outro(`Merged ${identityName} into ${skillDirName}`);
 }
 const STATUS_ICONS = {
 	pending: "○",
@@ -284,196 +593,250 @@ const STATUS_COLORS = {
 	done: "\x1B[32m",
 	error: "\x1B[31m"
 };
-async function syncPackagesParallel(config) {
-	const { packages, concurrency = 5 } = config;
-	const agent = targets[config.agent];
-	const states = /* @__PURE__ */ new Map();
-	const cwd = process.cwd();
-	for (const pkg of packages) states.set(pkg, {
-		name: pkg,
-		status: "pending",
-		message: "Waiting..."
+function renderParallel(r) {
+	const maxNameLen = Math.max(...[...r.states.keys()].map((n) => n.length), 20);
+	const lines = [...r.states.values()].map((s) => {
+		const icon = STATUS_ICONS[s.status];
+		const color = STATUS_COLORS[s.status];
+		const reset = "\x1B[0m";
+		const dim = "\x1B[90m";
+		const name = s.name.padEnd(maxNameLen);
+		const version = s.version ? `${dim}${s.version}${reset} ` : "";
+		const elapsed = (s.status === "done" || s.status === "error") && s.startedAt && s.completedAt ? ` ${dim}(${formatDuration(s.completedAt - s.startedAt)})${reset}` : "";
+		const preview = s.streamPreview ? ` ${dim}${s.streamPreview}${reset}` : "";
+		return `  ${color}${icon}${reset} ${name} ${version}${s.message}${elapsed}${preview}`;
 	});
-	function render() {
-		const maxNameLen = Math.max(...packages.map((p) => p.length), 20);
-		const lines = Array.from(states.values(), (s) => {
-			const icon = STATUS_ICONS[s.status];
-			const color = STATUS_COLORS[s.status];
-			const reset = "\x1B[0m";
-			const dim = "\x1B[90m";
-			const name = s.name.padEnd(maxNameLen);
-			const version = s.version ? `${dim}${s.version}${reset} ` : "";
-			const elapsed = (s.status === "done" || s.status === "error") && s.startedAt && s.completedAt ? ` ${dim}(${formatDuration(s.completedAt - s.startedAt)})${reset}` : "";
-			const preview = s.streamPreview ? ` ${dim}${s.streamPreview}${reset}` : "";
-			return `  ${color}${icon}${reset} ${name} ${version}${s.message}${elapsed}${preview}`;
-		});
-		const doneCount = [...states.values()].filter((s) => s.status === "done").length;
-		const errorCount = [...states.values()].filter((s) => s.status === "error").length;
-		logUpdate(`\x1B[1m${config.mode === "update" ? "Updating" : "Syncing"} ${packages.length} packages\x1B[0m (${doneCount} done${errorCount > 0 ? `, ${errorCount} failed` : ""})\n` + lines.join("\n"));
-	}
-	function update(pkg, status, message, version) {
-		const state = states.get(pkg);
+	const doneCount = [...r.states.values()].filter((s) => s.status === "done").length;
+	const errorCount = [...r.states.values()].filter((s) => s.status === "error").length;
+	logUpdate(`\x1B[1m${r.verb} ${r.total} packages\x1B[0m (${doneCount} done${errorCount > 0 ? `, ${errorCount} failed` : ""})\n` + lines.join("\n"));
+}
+function createParallelUi(name, render, version) {
+	const state = render.states.get(name);
+	if (!state) throw new Error(`createParallelUi: no state slot for "${name}"`);
+	function update(status, message, ver) {
 		if (!state.startedAt && status !== "pending") state.startedAt = performance.now();
 		if ((status === "done" || status === "error") && !state.completedAt) state.completedAt = performance.now();
 		state.status = status;
 		state.message = message;
 		state.streamPreview = void 0;
-		if (version) state.version = version;
-		render();
+		if (ver) state.version = ver;
+		renderParallel(render);
 	}
+	if (version) state.version = version;
+	return {
+		resolveStart() {
+			update("resolving", "Resolving...");
+		},
+		resolveProgress(msg) {
+			update("resolving", msg);
+		},
+		resolveDone(ver, opts) {
+			update("downloading", opts.cached ? "Using cache" : opts.force ? "Re-fetching docs..." : "Fetching docs...", ver);
+		},
+		resolveFailed(_identityName) {},
+		downloadingDist() {
+			update("downloading", "Downloading dist...");
+		},
+		fetchStart() {},
+		fetchProgress(msg) {
+			update("downloading", msg);
+		},
+		fetchDone(_parts, _cached) {
+			update("downloading", "Linking references...");
+		},
+		indexStart() {
+			update("embedding", "Indexing docs");
+		},
+		indexProgress(msg) {
+			update("embedding", msg);
+		},
+		indexDone() {},
+		warn(_msg) {},
+		baseDone(_relPath, mode) {
+			update("done", mode === "update" ? "Skill updated" : "Base skill created");
+		},
+		sectionsCached() {},
+		llmStart(modelLabel) {
+			update("generating", modelLabel);
+		},
+		llmProgress(progress) {
+			const status = progress.type === "reasoning" ? "exploring" : "generating";
+			const sectionPrefix = progress.section ? `[${progress.section}] ` : "";
+			update(status, progress.chunk.startsWith("[") ? `${sectionPrefix}${progress.chunk}` : `${sectionPrefix}${progress.chunk}`);
+		},
+		llmDone(_info) {
+			update("done", "Skill optimized");
+		},
+		llmFailed(error, _opts) {
+			update("error", error);
+		},
+		shippedInstalled(_skillName, _relPath) {
+			update("done", "Published SKILL.md");
+		}
+	};
+}
+const DIFF_RANK = {
+	major: 5,
+	premajor: 4,
+	minor: 3,
+	preminor: 2,
+	patch: 1,
+	prepatch: 1,
+	prerelease: 0
+};
+async function syncPackagesParallel(config) {
+	const { packages, concurrency = 5 } = config;
+	const cwd = process.cwd();
+	const states = /* @__PURE__ */ new Map();
+	for (const spec of packages) states.set(spec, {
+		name: spec,
+		status: "pending",
+		message: "Waiting..."
+	});
+	const render = {
+		states,
+		verb: config.mode === "update" ? "Updating" : "Syncing",
+		total: packages.length
+	};
 	ensureCacheDir();
-	render();
+	renderParallel(render);
 	const limit = pLimit(concurrency);
-	const skillData = /* @__PURE__ */ new Map();
-	const baseResults = await Promise.allSettled(packages.map((pkg) => limit(() => syncBaseSkill(pkg, config, cwd, update))));
+	const baseConfig = {
+		agent: config.agent,
+		global: config.global,
+		mode: config.mode,
+		force: config.force
+	};
+	const baseResults = await Promise.allSettled(packages.map((spec) => limit(async () => {
+		const { name } = parsePackageSpec(spec);
+		return runBaseSync(spec, baseConfig, createParallelUi(name, render), npmResolver, cwd, DEFAULT_SECTIONS);
+	})));
 	logUpdate.done();
-	const successfulPkgs = [];
-	const shippedPkgs = [];
+	const ready = [];
+	const shippedCount = [];
 	const errors = [];
+	const aggregatedWarnings = [];
 	for (let i = 0; i < baseResults.length; i++) {
+		const spec = packages[i];
 		const r = baseResults[i];
-		if (r.status === "fulfilled" && r.value !== "shipped") {
-			successfulPkgs.push(packages[i]);
-			skillData.set(packages[i], r.value);
-		} else if (r.status === "fulfilled" && r.value === "shipped") shippedPkgs.push(packages[i]);
-		else if (r.status === "rejected") {
+		if (r.status === "rejected") {
 			const err = r.reason;
-			const reason = err instanceof Error ? `${err.message}\n${err.stack}` : String(err);
+			const reason = err instanceof Error ? err.message : String(err);
+			const slot = states.get(spec);
+			if (slot) slot.status = "error";
 			errors.push({
-				pkg: packages[i],
+				spec,
 				reason
 			});
+			continue;
 		}
-	}
-	const pastVerb = config.mode === "update" ? "Updated" : "Created";
-	const skillMsg = `${pastVerb} ${successfulPkgs.length} base skills${shippedPkgs.length > 1 ? ` (Skipping ${shippedPkgs.length})` : ""}`;
-	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 result = r.value;
+		if (result.kind === "shipped") {
+			shippedCount.push(spec);
+			continue;
+		}
+		if (result.kind === "unresolved") {
+			const npmAttempt = result.unresolved.attempts.find((a) => a.source === "npm");
+			let reason;
+			if (npmAttempt?.status === "not-found") {
+				const suggestions = await searchNpmPackages(result.unresolved.identityName, 3);
+				const hint = suggestions.length > 0 ? ` (try: ${suggestions.map((s) => s.name).join(", ")})` : "";
+				reason = (npmAttempt.message || "Not on npm") + hint;
+			} else reason = result.unresolved.attempts.filter((a) => a.status !== "success").map((a) => a.message || a.source).join("; ") || "No docs found";
+			const slot = states.get(spec);
+			if (slot) {
+				slot.status = "error";
+				slot.message = reason;
 			}
-			const cachedBody = cachedParts.join("\n\n");
-			writeGeneratedSkillMd(skillDir, {
-				name: resolvedName,
-				version: data.version,
-				releasedAt: data.resolved.releasedAt,
-				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
+			errors.push({
+				spec,
+				reason
 			});
-			cachedPkgs.push(pkg);
+			continue;
 		}
+		if (result.kind === "merge-needed") {
+			errors.push({
+				spec,
+				reason: `Skill dir already holds ${result.state.existingLock.packageName} — run sequentially to merge`
+			});
+			continue;
+		}
+		ready.push({
+			spec,
+			state: result.state
+		});
 	}
-	const uncachedPkgs = successfulPkgs.filter((pkg) => !cachedPkgs.includes(pkg));
+	renderParallel(render);
+	logUpdate.done();
+	const pastVerb = config.mode === "update" ? "Updated" : "Created";
+	p.log.success(`${pastVerb} ${ready.length} base skills${shippedCount.length > 0 ? ` (${shippedCount.length} shipped)` : ""}`);
+	for (const w of aggregatedWarnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
+	for (const { spec, reason } of errors) p.log.error(`  ${spec}: ${reason}`);
+	const cachedPkgs = [];
+	const uncached = [];
+	for (const r of ready) if (r.state.allSectionsCached) cachedPkgs.push(r.spec);
+	else uncached.push(r);
 	if (cachedPkgs.length > 0) p.log.success(`Applied cached SKILL.md sections for ${cachedPkgs.join(", ")}`);
 	const globalConfig = readConfig();
-	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 resolvedModel = await resolveAutoModel(config.model, config.yes);
+	if (uncached.length > 0 && !globalConfig.skipLlm && !(config.yes && !resolvedModel)) {
+		const llmConfig = await selectLlmConfig(resolvedModel, void 0, config.mode === "update" ? aggregateUpdateCtx(uncached) : void 0);
+		if (llmConfig?.promptOnly) {
+			for (const r of uncached) {
+				const slot = states.get(r.spec);
+				if (slot) {
+					slot.status = "done";
+					slot.message = "Prompts written";
 				}
 			}
-			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,
-				skillDir: join(resolveBaseDir(cwd, config.agent, config.global), data.skillDirName),
-				version: data.version,
-				hasIssues: data.hasIssues,
-				hasDiscussions: data.hasDiscussions,
-				hasReleases: data.hasReleases,
-				hasChangelog: data.hasChangelog,
-				docsType: data.docsType,
-				hasShippedDocs: data.shippedDocs,
-				pkgFiles: data.pkgFiles,
-				sections: llmConfig.sections,
-				customPrompt: llmConfig.customPrompt,
-				features: data.features,
-				overheadLines: data.overheadLines
-			});
-		}
-		else if (llmConfig) {
+			renderParallel(render);
+			for (const r of uncached) {
+				const ui = createParallelUi(r.spec, render, getVersionKey(r.state.version));
+				await runEnhancePhase(r.state, llmConfig, {
+					agent: config.agent,
+					global: config.global,
+					force: config.force,
+					debug: config.debug
+				}, ui, cwd);
+			}
+		} else if (llmConfig) {
 			p.log.step(getModelLabel(llmConfig.model));
-			for (const pkg of uncachedPkgs) states.set(pkg, {
-				name: pkg,
+			for (const r of uncached) states.set(r.spec, {
+				name: r.spec,
 				status: "pending",
-				message: "Waiting..."
+				message: "Waiting...",
+				version: getVersionKey(r.state.version)
 			});
-			render();
-			const llmResults = await Promise.allSettled(uncachedPkgs.map((pkg) => limit(() => enhanceWithLLM(pkg, skillData.get(pkg), {
-				...config,
-				model: llmConfig.model
-			}, cwd, update, llmConfig.sections, llmConfig.customPrompt))));
+			renderParallel(render);
+			const llmResults = await Promise.allSettled(uncached.map((r) => limit(async () => {
+				const ui = createParallelUi(r.spec, render, getVersionKey(r.state.version));
+				await runEnhancePhase(r.state, llmConfig, {
+					agent: config.agent,
+					global: config.global,
+					force: config.force,
+					debug: config.debug
+				}, ui, cwd);
+			})));
 			logUpdate.done();
-			const llmSucceeded = llmResults.filter((r) => r.status === "fulfilled").length;
-			p.log.success(`Enhanced ${llmSucceeded}/${uncachedPkgs.length} skills with LLM`);
+			const llmSucceeded = llmResults.filter((x) => x.status === "fulfilled").length;
+			p.log.success(`Enhanced ${llmSucceeded}/${uncached.length} skills with LLM`);
 		}
+	} else for (const r of ready) {
+		const ui = createParallelUi(r.spec, render, getVersionKey(r.state.version));
+		await runEnhancePhase(r.state, null, {
+			agent: config.agent,
+			global: config.global,
+			force: config.force,
+			debug: config.debug
+		}, ui, cwd);
 	}
-	await ensureGitignore(getSharedSkillsDir(cwd) ? SHARED_SKILLS_DIR : agent.skillsDir, cwd, config.global);
-	await ensureAgentInstructions(config.agent, cwd, config.global);
+	await ensureProjectFiles({
+		cwd,
+		agent: config.agent,
+		global: config.global
+	});
 	await shutdownWorker();
-	p.outro(`${pastVerb} ${successfulPkgs.length}/${packages.length} packages`);
+	p.outro(`${pastVerb} ${ready.length}/${packages.length} packages`);
 	const { suggestPrepareHook } = await import("./cli-helpers2.mjs");
 	try {
 		await suggestPrepareHook(cwd);
@@ -481,213 +844,28 @@ async function syncPackagesParallel(config) {
 		p.log.warn(`Failed to suggest prepare hook: ${err instanceof Error ? err.message : String(err)}`);
 	}
 }
-async function syncBaseSkill(packageSpec, config, cwd, update) {
-	const { name: packageName, tag: requestedTag } = parsePackageSpec(packageSpec);
-	const localVersion = (await readLocalDependencies(cwd).catch(() => [])).find((d) => d.name === packageName)?.version;
-	const { package: resolvedPkg, attempts, registryVersion } = await resolvePackageDocsWithAttempts(requestedTag ? packageSpec : packageName, {
-		version: localVersion,
-		cwd,
-		onProgress: (step) => update(packageName, "resolving", RESOLVE_STEP_LABELS[step])
-	});
-	let resolved = resolvedPkg;
-	if (!resolved) {
-		update(packageName, "resolving", "Local package...");
-		resolved = await resolveLocalDep(packageName, cwd);
-	}
-	if (!resolved) {
-		const shippedVersion = localVersion || registryVersion || "latest";
-		const earlyShipped = handleShippedSkills(packageName, shippedVersion, cwd, config.agent, config.global);
-		if (earlyShipped) {
-			const shared = !config.global && getSharedSkillsDir(cwd);
-			if (shared) for (const shipped of earlyShipped.shipped) linkSkillToAgents(shipped.skillName, shared, cwd, config.agent);
-			update(packageName, "done", "Published SKILL.md", getVersionKey(shippedVersion));
-			return "shipped";
+function aggregateUpdateCtx(ready) {
+	let maxDiff = "";
+	let allEnhanced = true;
+	let anySyncedAt;
+	for (const r of ready) {
+		const u = r.state.updateCtx;
+		if (!u?.wasEnhanced) allEnhanced = false;
+		if (u?.syncedAt && (!anySyncedAt || u.syncedAt < anySyncedAt)) anySyncedAt = u.syncedAt;
+		if (u?.oldVersion && u.newVersion) {
+			const diff = semverDiff(u.oldVersion, u.newVersion);
+			if (diff && (DIFF_RANK[diff] ?? 0) > (DIFF_RANK[maxDiff] ?? -1)) maxDiff = diff;
 		}
-		const npmAttempt = attempts.find((a) => a.source === "npm");
-		let reason;
-		if (npmAttempt?.status === "not-found") {
-			const suggestions = await searchNpmPackages(packageName, 3);
-			const hint = suggestions.length > 0 ? ` (try: ${suggestions.map((s) => s.name).join(", ")})` : "";
-			reason = (npmAttempt.message || "Not on npm") + hint;
-		} else reason = attempts.filter((a) => a.status !== "success").map((a) => a.message || a.source).join("; ") || "No docs found";
-		update(packageName, "error", reason);
-		throw new Error(`Could not find docs for: ${packageName}`);
-	}
-	const version = localVersion || resolved.version || "latest";
-	const versionKey = getVersionKey(version);
-	if (!existsSync(join(cwd, "node_modules", packageName))) {
-		update(packageName, "downloading", "Downloading dist...", versionKey);
-		await fetchPkgDist(packageName, version);
-	}
-	const shippedResult = handleShippedSkills(packageName, version, cwd, config.agent, config.global);
-	if (shippedResult) {
-		const shared = !config.global && getSharedSkillsDir(cwd);
-		if (shared) for (const shipped of shippedResult.shipped) linkSkillToAgents(shipped.skillName, shared, cwd, config.agent);
-		update(packageName, "done", "Published SKILL.md", versionKey);
-		return "shipped";
-	}
-	if (config.force) forceClearCache(packageName, version);
-	const useCache = isCached(packageName, version);
-	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);
-	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,
-		resolved,
-		version,
-		useCache,
-		features,
-		onProgress: (msg) => update(packageName, "downloading", msg, versionKey)
-	});
-	update(packageName, "downloading", "Linking references...", versionKey);
-	linkAllReferences(skillDir, packageName, cwd, version, resources.docsType, void 0, features, resources.repoInfo);
-	if (features.search) {
-		update(packageName, "embedding", "Indexing docs", versionKey);
-		await indexResources({
-			packageName,
-			version,
-			cwd,
-			docsToIndex: resources.docsToIndex,
-			features,
-			onProgress: (msg) => update(packageName, "embedding", msg, versionKey)
-		});
 	}
-	const hasChangelog = detectChangelog(resolvePkgDir(packageName, cwd, version), getCacheDir(packageName, version));
-	const relatedSkills = await findRelatedSkills(packageName, baseDir);
-	const shippedDocs = hasShippedDocs(packageName, cwd, version);
-	const pkgFiles = getPkgKeyFiles(packageName, cwd, version);
-	const repoSlug = parseGitHubRepoSlug(resolved.repoUrl);
-	linkPkgNamed(skillDir, packageName, cwd, version);
-	writeLock(baseDir, skillDirName, {
-		packageName,
-		version,
-		repo: repoSlug,
-		source: resources.docSource,
-		syncedAt: todayIsoDate(),
-		generator: "skilld"
-	});
-	const updatedLock = readLock(baseDir)?.skills[skillDirName];
-	const allPackages = parsePackageNames(updatedLock?.packages);
-	const overheadLines = writeGeneratedSkillMd(skillDir, {
-		name: packageName,
-		version,
-		releasedAt: resolved.releasedAt,
-		description: resolved.description,
-		distTags: resolved.distTags,
-		relatedSkills,
-		hasIssues: resources.hasIssues,
-		hasDiscussions: resources.hasDiscussions,
-		hasReleases: resources.hasReleases,
-		hasChangelog,
-		docsType: resources.docsType,
-		hasShippedDocs: shippedDocs,
-		pkgFiles,
-		dirName: skillDirName,
-		packages: allPackages.length > 1 ? allPackages : void 0,
-		repoUrl: resolved.repoUrl,
-		features
-	}).split("\n").length;
-	const shared = !config.global && getSharedSkillsDir(cwd);
-	if (shared) linkSkillToAgents(skillDirName, shared, cwd, config.agent);
-	if (!config.global) registerProject(cwd);
-	update(packageName, "done", config.mode === "update" ? "Skill updated" : "Base skill created", versionKey);
+	const first = ready[0]?.state.updateCtx;
 	return {
-		resolved,
-		version,
-		skillDirName,
-		docsType: resources.docsType,
-		hasIssues: resources.hasIssues,
-		hasDiscussions: resources.hasDiscussions,
-		hasReleases: resources.hasReleases,
-		hasChangelog,
-		shippedDocs,
-		pkgFiles,
-		relatedSkills,
-		packages: allPackages.length > 1 ? allPackages : void 0,
-		warnings: resources.warnings,
-		features,
-		usedCache: resources.usedCache,
-		oldVersion: preLock?.version,
-		oldSyncedAt: preLock?.syncedAt,
-		wasEnhanced: preEnhanced,
-		overheadLines
+		oldVersion: ready.length === 1 ? first?.oldVersion : void 0,
+		newVersion: ready.length === 1 ? first?.newVersion : void 0,
+		syncedAt: anySyncedAt,
+		wasEnhanced: allEnhanced,
+		bumpType: maxDiff || void 0
 	};
 }
-async function enhanceWithLLM(packageName, data, config, cwd, update, sections, customPrompt) {
-	const versionKey = getVersionKey(data.version);
-	const skillDir = join(resolveBaseDir(cwd, config.agent, config.global), data.skillDirName);
-	const hasGithub = data.hasIssues || data.hasDiscussions;
-	const docFiles = listReferenceFiles(skillDir);
-	update(packageName, "generating", config.model, versionKey);
-	const { optimized, wasOptimized, error } = await optimizeDocs({
-		packageName,
-		skillDir,
-		model: config.model,
-		version: data.version,
-		hasGithub,
-		hasReleases: data.hasReleases,
-		hasChangelog: data.hasChangelog,
-		docFiles,
-		docsType: data.docsType,
-		hasShippedDocs: data.shippedDocs,
-		noCache: config.force,
-		debug: config.debug,
-		sections,
-		customPrompt,
-		features: data.features,
-		pkgFiles: data.pkgFiles,
-		overheadLines: data.overheadLines,
-		onProgress: (progress) => {
-			const status = progress.type === "reasoning" ? "exploring" : "generating";
-			const sectionPrefix = progress.section ? `[${progress.section}] ` : "";
-			update(packageName, status, progress.chunk.startsWith("[") ? `${sectionPrefix}${progress.chunk}` : `${sectionPrefix}${config.model}`, versionKey);
-		}
-	});
-	if (error) {
-		update(packageName, "error", error, versionKey);
-		throw new Error(error);
-	}
-	if (wasOptimized) writeGeneratedSkillMd(skillDir, {
-		name: packageName,
-		version: data.version,
-		releasedAt: data.resolved.releasedAt,
-		distTags: data.resolved.distTags,
-		body: optimized,
-		relatedSkills: data.relatedSkills,
-		hasIssues: data.hasIssues,
-		hasDiscussions: data.hasDiscussions,
-		hasReleases: data.hasReleases,
-		hasChangelog: data.hasChangelog,
-		docsType: data.docsType,
-		hasShippedDocs: data.shippedDocs,
-		pkgFiles: data.pkgFiles,
-		dirName: data.skillDirName,
-		packages: data.packages,
-		repoUrl: data.resolved.repoUrl,
-		features: data.features
-	});
-	update(packageName, "done", "Skill optimized", versionKey);
-}
 const RESOLVE_SOURCE_LABELS = {
 	"npm": "npm registry",
 	"github-docs": "GitHub versioned docs",
@@ -708,12 +886,6 @@ function showResolveAttempts(attempts) {
 		p.log.message(`  ${icon} ${source}${msg}`);
 	}
 }
-function isCrateSpec(spec) {
-	return spec.startsWith("crate:");
-}
-function toCrateIdentity(crateName) {
-	return `crate:${crateName}`;
-}
 async function syncCommand(state, opts) {
 	if (opts.packages && opts.packages.length > 0) {
 		const crateSpecs = opts.packages.filter(isCrateSpec);
@@ -805,52 +977,30 @@ async function pickFromList(packages, state) {
 	}
 	return selected;
 }
-async function syncSinglePackage(packageSpec, config) {
-	const isCrate = isCrateSpec(packageSpec);
-	const normalizedSpec = isCrate ? packageSpec.slice(6).trim() : packageSpec;
-	if (isCrate && !normalizedSpec) {
-		p.log.error("Invalid crate spec. Use format: crate:<name>");
-		return;
-	}
-	const { name: parsedName, tag: requestedTag } = parsePackageSpec(normalizedSpec);
-	const packageName = isCrate ? parsedName.toLowerCase() : parsedName;
-	const identityPackageName = isCrate ? toCrateIdentity(packageName) : packageName;
-	const storagePackageName = toStoragePackageName(identityPackageName);
-	const spin = timedSpinner();
-	spin.start(`Resolving ${packageSpec}`);
+async function runSimpleSync(packageSpec, config) {
 	const cwd = process.cwd();
-	const localDeps = isCrate ? [] : await readLocalDependencies(cwd).catch(() => []);
-	const localVersion = isCrate ? void 0 : localDeps.find((d) => d.name === packageName)?.version;
-	const resolveResult = isCrate ? await resolveCrateDocsWithAttempts(packageName, {
-		version: requestedTag,
-		onProgress: (step) => spin.message(`${identityPackageName}: ${step}`)
-	}) : await resolvePackageDocsWithAttempts(requestedTag ? normalizedSpec : packageName, {
-		version: localVersion,
-		cwd,
-		onProgress: (step) => spin.message(`${packageName}: ${RESOLVE_STEP_LABELS[step]}`)
-	});
-	let resolved = resolveResult.package;
-	if (!resolved && !isCrate) {
-		spin.message(`Resolving local package: ${packageName}`);
-		resolved = await resolveLocalDep(packageName, cwd);
+	const ui = createClackUi({ cwd });
+	const isEject = !!config.eject;
+	const result = await runBaseSync(packageSpec, {
+		agent: config.agent,
+		global: config.global,
+		mode: config.mode,
+		force: config.force,
+		noSearch: config.noSearch,
+		name: config.name,
+		from: config.from,
+		eject: config.eject
+	}, ui, npmResolver, cwd, DEFAULT_SECTIONS);
+	if (result.kind === "shipped") {
+		p.outro(`Synced ${packageSpec}`);
+		return;
 	}
-	if (!resolved) {
-		if (!isCrate) {
-			const earlyShipped = handleShippedSkills(packageName, localVersion || resolveResult.registryVersion || "latest", cwd, config.agent, config.global);
-			if (earlyShipped) {
-				const shared = !config.global && getSharedSkillsDir(cwd);
-				for (const shipped of earlyShipped.shipped) {
-					if (shared) linkSkillToAgents(shipped.skillName, shared, cwd, config.agent);
-					p.log.success(`Using published SKILL.md: ${shipped.skillName} → ${relative(cwd, shipped.skillDir)}`);
-				}
-				spin.stop(`Using published SKILL.md(s) from ${packageName}`);
-				return;
-			}
-			spin.message(`Searching npm for "${packageName}"...`);
-			const suggestions = await searchNpmPackages(packageName);
+	if (result.kind === "unresolved") {
+		const { unresolved } = result;
+		if (!isCrateSpec(packageSpec)) {
+			const suggestions = await searchNpmPackages(unresolved.identityName);
 			if (suggestions.length > 0) {
-				spin.stop(`Package "${packageName}" not found on npm`);
-				showResolveAttempts(resolveResult.attempts);
+				showResolveAttempts(unresolved.attempts);
 				const selected = await p.select({
 					message: "Did you mean one of these?",
 					options: [...suggestions.map((s) => ({
@@ -866,299 +1016,45 @@ async function syncSinglePackage(packageSpec, config) {
 				return;
 			}
 		}
-		spin.stop(`Could not find docs for: ${identityPackageName}`);
-		showResolveAttempts(resolveResult.attempts);
-		return;
-	}
-	const version = isCrate ? resolved.version || requestedTag || "latest" : localVersion || resolved.version || "latest";
-	const versionKey = getVersionKey(version);
-	if (config.force) forceClearCache(storagePackageName, version);
-	const useCache = isCached(storagePackageName, version);
-	if (!isCrate && !existsSync(join(cwd, "node_modules", packageName))) {
-		spin.message(`Downloading ${packageName}@${version} dist`);
-		await fetchPkgDist(packageName, version);
-	}
-	const shippedResult = isCrate ? null : handleShippedSkills(packageName, version, cwd, config.agent, config.global);
-	if (shippedResult) {
-		const shared = !config.global && getSharedSkillsDir(cwd);
-		for (const shipped of shippedResult.shipped) {
-			if (shared) linkSkillToAgents(shipped.skillName, shared, cwd, config.agent);
-			p.log.success(`Using published SKILL.md: ${shipped.skillName} → ${relative(cwd, shipped.skillDir)}`);
-		}
-		spin.stop(`Using published SKILL.md(s) from ${packageName}`);
+		showResolveAttempts(unresolved.attempts);
 		return;
 	}
-	spin.stop(`Resolved ${identityPackageName}@${useCache ? versionKey : version}${config.force ? " (force)" : useCache ? " (cached)" : ""}`);
-	if (!isCrate && !localVersion && !requestedTag && !isPrerelease(version)) {
-		const nextTag = resolved.distTags?.next ?? resolved.distTags?.beta ?? resolved.distTags?.alpha;
-		if (nextTag && (!resolved.releasedAt || !nextTag.releasedAt || nextTag.releasedAt > resolved.releasedAt)) p.log.warn(`\x1B[33mNo local dependency found — using latest stable (${version}). Prerelease ${nextTag.version} available: skilld add ${packageName}@beta\x1B[0m`);
-	}
-	ensureCacheDir();
-	const baseDir = resolveBaseDir(cwd, config.agent, config.global);
-	let skillDirName = config.name ? sanitizeName(config.name) : computeSkillDirName(storagePackageName);
-	if (config.mode === "update" && !config.name) {
-		const lock = readLock(baseDir);
-		if (lock) {
-			for (const [name, info] of Object.entries(lock.skills)) if (info.packageName === identityPackageName || parsePackages(info.packages).some((p) => p.name === identityPackageName)) {
-				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];
-	const isMerge = existingLock && existingLock.packageName && existingLock.packageName !== identityPackageName;
-	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 ${identityPackageName} into ${skillDirName}`);
-		linkPkgNamed(skillDir, storagePackageName, cwd, version);
-		const repoSlug = parseGitHubRepoSlug(resolved.repoUrl);
-		writeLock(baseDir, skillDirName, {
-			packageName: identityPackageName,
-			version,
-			repo: repoSlug,
-			source: existingLock.source,
-			syncedAt: todayIsoDate(),
-			generator: "skilld"
-		});
-		const updatedLock = readLock(baseDir)?.skills[skillDirName];
-		const allPackages = parsePackageNames(updatedLock?.packages);
-		const relatedSkills = await findRelatedSkills(storagePackageName, baseDir);
-		const existingStorageName = toStoragePackageName(existingLock.packageName);
-		const pkgFiles = getPkgKeyFiles(existingStorageName, cwd, existingLock.version);
-		const shippedDocs = hasShippedDocs(existingStorageName, cwd, existingLock.version);
-		const mergeFeatures = readConfig().features ?? defaultFeatures;
-		writeGeneratedSkillMd(skillDir, {
-			name: existingLock.packageName,
-			version: existingLock.version,
-			relatedSkills,
-			hasIssues: mergeFeatures.issues && existsSync(join(skillDir, ".skilld", "issues")),
-			hasDiscussions: mergeFeatures.discussions && existsSync(join(skillDir, ".skilld", "discussions")),
-			hasReleases: mergeFeatures.releases && existsSync(join(skillDir, ".skilld", "releases")),
-			docsType: existingLock.source?.includes("llms.txt") ? "llms.txt" : "docs",
-			hasShippedDocs: shippedDocs,
-			pkgFiles,
-			dirName: skillDirName,
-			packages: allPackages,
-			features: mergeFeatures
-		});
-		const mergeShared = !config.global && getSharedSkillsDir(cwd);
-		if (mergeShared) linkSkillToAgents(skillDirName, mergeShared, cwd, config.agent);
-		if (!config.global) registerProject(cwd);
-		p.outro(`Merged ${identityPackageName} into ${skillDirName}`);
+	if (result.kind === "merge-needed") {
+		await handleMerge(result.state, {
+			agent: config.agent,
+			global: config.global
+		}, cwd);
 		return;
 	}
-	const features = { ...readConfig().features ?? defaultFeatures };
-	if (config.noSearch) features.search = false;
-	const resSpin = timedSpinner();
-	resSpin.start("Finding resources");
-	const resources = await fetchAndCacheResources({
-		packageName: storagePackageName,
-		resolved,
-		version,
-		useCache,
-		features,
-		from: config.from,
-		onProgress: (msg) => resSpin.message(msg)
-	});
-	const resParts = [];
-	if (resources.docsToIndex.length > 0) {
-		const docCount = resources.docsToIndex.filter((d) => d.metadata?.type === "doc").length;
-		if (docCount > 0) resParts.push(`${docCount} docs`);
-	}
-	if (resources.hasIssues) resParts.push("issues");
-	if (resources.hasDiscussions) resParts.push("discussions");
-	if (resources.hasReleases) resParts.push("releases");
-	resSpin.stop(resources.usedCache ? `Loaded ${resParts.length > 0 ? resParts.join(", ") : "resources"} (cached)` : `Fetched ${resParts.length > 0 ? resParts.join(", ") : "resources"}`);
-	for (const w of resources.warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
-	linkAllReferences(skillDir, storagePackageName, cwd, version, resources.docsType, void 0, features, resources.repoInfo);
-	if (features.search) {
-		const idxSpin = timedSpinner();
-		idxSpin.start("Creating search index");
-		await indexResources({
-			packageName: storagePackageName,
-			version,
-			cwd,
-			docsToIndex: resources.docsToIndex,
-			features,
-			onProgress: (msg) => idxSpin.message(msg)
-		});
-		idxSpin.stop("Search index ready");
-	}
-	const hasChangelog = detectChangelog(resolvePkgDir(storagePackageName, cwd, version), getCacheDir(storagePackageName, version));
-	const relatedSkills = await findRelatedSkills(storagePackageName, baseDir);
-	const shippedDocs = hasShippedDocs(storagePackageName, cwd, version);
-	const pkgFiles = getPkgKeyFiles(storagePackageName, cwd, version);
-	const repoSlug = parseGitHubRepoSlug(resolved.repoUrl);
-	if (!config.eject) linkPkgNamed(skillDir, storagePackageName, cwd, version);
-	if (!config.eject) {
-		writeLock(baseDir, skillDirName, {
-			packageName: identityPackageName,
-			version,
-			repo: repoSlug,
-			source: resources.docSource,
-			syncedAt: todayIsoDate(),
-			generator: "skilld"
-		});
-		const lock = readLock(baseDir);
-		if (lock) for (const [name, info] of Object.entries(lock.skills)) {
-			if (name === skillDirName) continue;
-			if (info.packageName === identityPackageName || parsePackages(info.packages).some((p) => p.name === identityPackageName)) {
-				removeLockEntry(baseDir, name);
-				const staleDir = join(baseDir, name);
-				if (existsSync(staleDir)) rmSync(staleDir, { recursive: true });
-			}
-		}
-	}
-	const allPackages = parsePackageNames((config.eject ? void 0 : readLock(baseDir)?.skills[skillDirName])?.packages);
-	const isEject = !!config.eject;
-	const overheadLines = writeGeneratedSkillMd(skillDir, {
-		name: identityPackageName,
-		version,
-		releasedAt: resolved.releasedAt,
-		description: resolved.description,
-		distTags: resolved.distTags,
-		relatedSkills,
-		hasIssues: resources.hasIssues,
-		hasDiscussions: resources.hasDiscussions,
-		hasReleases: resources.hasReleases,
-		hasChangelog,
-		docsType: resources.docsType,
-		hasShippedDocs: shippedDocs,
-		pkgFiles,
-		dirName: skillDirName,
-		packages: allPackages.length > 1 ? allPackages : void 0,
-		repoUrl: resolved.repoUrl,
-		features,
-		eject: isEject
-	}).split("\n").length;
-	p.log.success(config.mode === "update" ? `Updated skill: ${relative(cwd, skillDir)}` : `Created base skill: ${relative(cwd, skillDir)}`);
-	const allSectionsCached = !config.force && DEFAULT_SECTIONS.every((s) => {
-		const outputFile = SECTION_OUTPUT_FILES[s];
-		return readCachedSection(storagePackageName, 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(storagePackageName, version, outputFile);
-			if (content) cachedParts.push(wrapSection(s, content));
-		}
-		const cachedBody = cachedParts.join("\n\n");
-		writeGeneratedSkillMd(skillDir, {
-			name: identityPackageName,
-			version,
-			releasedAt: resolved.releasedAt,
-			description: resolved.description,
-			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
-		});
-		p.log.success("Applied cached SKILL.md sections");
-	}
+	const { state } = result;
 	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: storagePackageName,
-			skillDir,
-			version,
-			hasIssues: resources.hasIssues,
-			hasDiscussions: resources.hasDiscussions,
-			hasReleases: resources.hasReleases,
-			hasChangelog,
-			docsType: resources.docsType,
-			hasShippedDocs: shippedDocs,
-			pkgFiles,
-			sections: llmConfig.sections,
-			customPrompt: llmConfig.customPrompt,
-			features,
-			overheadLines
-		});
-		else if (llmConfig) {
-			p.log.step(getModelLabel(llmConfig.model));
-			await enhanceSkillWithLLM({
-				packageName: identityPackageName,
-				cachePackageName: storagePackageName,
-				version,
-				skillDir,
-				dirName: skillDirName,
-				model: llmConfig.model,
-				resolved,
-				relatedSkills,
-				hasIssues: resources.hasIssues,
-				hasDiscussions: resources.hasDiscussions,
-				hasReleases: resources.hasReleases,
-				hasChangelog,
-				docsType: resources.docsType,
-				hasShippedDocs: shippedDocs,
-				pkgFiles,
-				force: config.force,
-				debug: config.debug,
-				sections: llmConfig.sections,
-				customPrompt: llmConfig.customPrompt,
-				packages: allPackages.length > 1 ? allPackages : void 0,
-				features,
-				eject: isEject,
-				overheadLines
-			});
-		}
-	}
-	if (isEject) {
-		const skilldDir = join(skillDir, ".skilld");
-		if (existsSync(skilldDir) && !config.debug) rmSync(skilldDir, {
-			recursive: true,
-			force: true
-		});
-		ejectReferences(skillDir, storagePackageName, cwd, version, resources.docsType, features, resources.repoInfo);
-	}
-	if (!isEject) {
-		const shared = !config.global && getSharedSkillsDir(cwd);
-		if (shared) linkSkillToAgents(skillDirName, shared, cwd, config.agent);
-		if (!config.global) registerProject(cwd);
-		await ensureGitignore(shared ? SHARED_SKILLS_DIR : targets[config.agent].skillsDir, cwd, config.global);
-		await ensureAgentInstructions(config.agent, cwd, config.global);
-	}
+	const resolvedModel = await resolveAutoModel(config.model, config.yes);
+	let llmConfig = null;
+	if (!state.allSectionsCached && !globalConfig.skipLlm && !(config.yes && !resolvedModel)) llmConfig = await selectLlmConfig(resolvedModel, void 0, state.updateCtx);
+	await runEnhancePhase(state, llmConfig, {
+		agent: config.agent,
+		global: config.global,
+		force: config.force,
+		debug: config.debug,
+		eject: config.eject
+	}, ui, cwd);
 	await shutdownWorker();
 	const ejectMsg = isEject ? " (ejected)" : "";
-	const relDir = relative(cwd, skillDir);
-	p.outro(config.mode === "update" ? `Updated ${identityPackageName}${ejectMsg}` : `Synced ${identityPackageName} → ${relDir}${ejectMsg}`);
+	const relDir = relative(cwd, state.skillDir);
+	p.outro(config.mode === "update" ? `Updated ${state.identityName}${ejectMsg}` : `Synced ${state.identityName} → ${relDir}${ejectMsg}`);
 	try {
 		await suggestPrepareHook(cwd);
 	} catch (err) {
 		p.log.warn(`Failed to suggest prepare hook: ${err instanceof Error ? err.message : String(err)}`);
 	}
 }
+async function syncSinglePackage(packageSpec, config) {
+	if (isCrateSpec(packageSpec) && !packageSpec.slice(6).trim()) {
+		p.log.error("Invalid crate spec. Use format: crate:<name>");
+		return;
+	}
+	return runSimpleSync(packageSpec, config);
+}
 const addCommandDef = defineCommand({
 	meta: {
 		name: "add",
@@ -1464,36 +1360,29 @@ const updateCommandDef = defineCommand({
 	}
 });
 async function exportPortablePrompts(packageSpec, opts) {
-	const { name: packageName } = parsePackageSpec(packageSpec);
 	const sections = opts.sections ?? DEFAULT_SECTIONS;
 	const spin = timedSpinner();
 	spin.start(`Resolving ${packageSpec}`);
 	const cwd = process.cwd();
-	const localVersion = (await readLocalDependencies(cwd).catch(() => [])).find((d) => d.name === packageName)?.version;
-	let resolved = (await resolvePackageDocsWithAttempts(packageName, {
-		version: localVersion,
+	const { packageName, localVersion, resolved } = await resolvePackageOrCrate(packageSpec, {
 		cwd,
-		onProgress: (step) => spin.message(`${packageName}: ${RESOLVE_STEP_LABELS[step]}`)
-	})).package;
-	if (!resolved) {
-		spin.message(`Resolving local package: ${packageName}`);
-		resolved = await resolveLocalDep(packageName, cwd);
-	}
+		onProgress: (label) => spin.message(`${packageSpec}: ${label}`)
+	});
 	if (!resolved) {
-		spin.stop(`Could not find docs for: ${packageName}`);
+		spin.stop(`Could not find docs for: ${packageSpec}`);
 		return;
 	}
 	const version = localVersion || resolved.version || "latest";
-	const versionKey = getVersionKey(version);
-	const useCache = !opts.force && isCached(packageName, version);
+	const cache = createReferenceCache(packageName, version);
+	const useCache = !opts.force && cache.has();
 	if (!existsSync(join(cwd, "node_modules", packageName))) {
 		spin.message(`Downloading ${packageName}@${version} dist`);
 		await fetchPkgDist(packageName, version);
 	}
-	spin.stop(`Resolved ${packageName}@${useCache ? versionKey : version}`);
-	ensureCacheDir();
+	spin.stop(`Resolved ${packageName}@${useCache ? cache.versionKey : version}`);
+	cache.ensure();
 	const skillDirName = computeSkillDirName(packageName);
-	const features = readConfig().features ?? defaultFeatures;
+	const features = getActiveFeatures();
 	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);
@@ -1514,10 +1403,15 @@ async function exportPortablePrompts(packageSpec, opts) {
 	});
 	resSpin.stop("Resources ready");
 	for (const w of resources.warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
-	linkAllReferences(skillDir, packageName, cwd, version, resources.docsType, void 0, features, resources.repoInfo);
-	const hasChangelog = detectChangelog(resolvePkgDir(packageName, cwd, version), getCacheDir(packageName, version));
-	const shippedDocs = hasShippedDocs(packageName, cwd, version);
-	const pkgFiles = getPkgKeyFiles(packageName, cwd, version);
+	const { hasChangelog, shippedDocs, pkgFiles, relatedSkills } = await prepareSkillReferences({
+		packageName,
+		version,
+		cwd,
+		skillDir,
+		resources,
+		features,
+		baseDir: join(skillDir, "..")
+	});
 	const docFiles = listReferenceFiles(skillDir);
 	const prompts = buildAllSectionPrompts({
 		packageName,
@@ -1534,17 +1428,15 @@ async function exportPortablePrompts(packageSpec, opts) {
 		features,
 		sections
 	});
-	ejectReferences(skillDir, packageName, cwd, version, resources.docsType, features, resources.repoInfo);
-	const skilldDir = join(skillDir, ".skilld");
-	if (existsSync(skilldDir)) rmSync(skilldDir, {
-		recursive: true,
-		force: true
+	cache.eject(skillDir, cwd, resources.docsType, {
+		features,
+		repoInfo: resources.repoInfo
 	});
+	cache.clearSkillInternal(skillDir);
 	for (const [section, prompt] of prompts) {
 		const portable = portabilizePrompt(prompt, section);
 		writeFileSync(join(skillDir, `PROMPT_${section}.md`), portable);
 	}
-	const relatedSkills = await findRelatedSkills(packageName, join(skillDir, ".."));
 	writeGeneratedSkillMd(skillDir, {
 		name: packageName,
 		version,
@@ -1563,21 +1455,40 @@ async function exportPortablePrompts(packageSpec, opts) {
 		features,
 		eject: true
 	});
-	writeLock(baseDir, skillDirName, {
-		packageName,
-		version,
-		repo: parseGitHubRepoSlug(resolved.repoUrl),
-		source: resources.docSource,
-		syncedAt: todayIsoDate(),
-		generator: "skilld"
-	});
+	const repoSlug = parseGitHubRepoSlug(resolved.repoUrl);
 	if (agent) {
-		const shared = getSharedSkillsDir(cwd);
-		if (shared) linkSkillToAgents(skillDirName, shared, cwd, agent);
-		await ensureGitignore(shared ? SHARED_SKILLS_DIR : targets[agent].skillsDir, cwd, false);
-		await ensureAgentInstructions(agent, cwd, false);
-		registerProject(cwd);
-	} else await ensureGitignore(".claude/skills", cwd, false);
+		const { shared } = installSkill({
+			cwd,
+			agent,
+			global: false,
+			baseDir,
+			skillDirName,
+			lock: {
+				packageName,
+				version,
+				repo: repoSlug,
+				source: resources.docSource,
+				syncedAt: todayIsoDate(),
+				generator: "skilld"
+			}
+		});
+		await ensureProjectFiles({
+			cwd,
+			agent,
+			global: false,
+			shared
+		});
+	} else {
+		writeLock(baseDir, skillDirName, {
+			packageName,
+			version,
+			repo: repoSlug,
+			source: resources.docSource,
+			syncedAt: todayIsoDate(),
+			generator: "skilld"
+		});
+		await ensureGitignore(".claude/skills", cwd, false);
+	}
 	const relDir = relative(cwd, skillDir);
 	const sectionList = [...prompts.keys()];
 	p.log.success(`Skill installed to ${relDir}`);
@@ -1585,6 +1496,6 @@ async function exportPortablePrompts(packageSpec, opts) {
 	const outputFileList = sectionList.map((s) => SECTION_OUTPUT_FILES[s]).join(", ");
 	p.log.info(`Have your agent enhance the skill. Give it this prompt:\n\x1B[2m\x1B[3m  Read each prompt file (${promptFiles}) in ${relDir}/, read the\n  referenced files, then write your output to the matching file (${outputFileList}).\n  When done, run: skilld assemble\x1B[0m`);
 }
-export { syncCommand as a, isCrateSpec as i, ejectCommandDef as n, updateCommandDef as o, exportPortablePrompts as r, addCommandDef as t };
+export { updateCommandDef as a, syncCommand as i, ejectCommandDef as n, exportPortablePrompts as r, addCommandDef as t };
 
 //# sourceMappingURL=sync.mjs.map