skilld 1.4.0 → 1.5.1

package/dist/_chunks/sync.mjs

@@ -1,1061 +1,27 @@
-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 { a as getModelLabel, i as getAvailableModels, s as optimizeDocs, t as detectImportedPackages } from "./agent.mjs";
+import { c as getVersionKey, o as getCacheDir, t as CACHE_DIR } from "./config.mjs";
+import { r as resolvePkgDir } from "./prepare.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, 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 { a as hasShippedDocs, f as listReferenceFiles, i as getPkgKeyFiles, l as linkPkgNamed, m as readCachedSection, o as isCached, r as ensureCacheDir } from "./cache.mjs";
 import { i as parseFrontmatter } from "./markdown.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 semverDiff, n as getSharedSkillsDir, t as SHARED_SKILLS_DIR } from "./shared.mjs";
+import { A as parseGitSkillInput, f as resolvePackageDocsWithAttempts, i as fetchPkgDist, k as fetchGitSkills, nt as parsePackageSpec, p as searchNpmPackages, q as isPrerelease, s as readLocalDependencies, x as resolveGitHubRepo } 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, 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 { a as sanitizeName, c as SECTION_OUTPUT_FILES, 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 { A as registerProject, D as hasCompletedWizard, T as defaultFeatures, b as sharedArgs, d as introLine, f as isInteractive, g as promptForAgent, k as readConfig, o as getInstalledGenerators, x as suggestPrepareHook, y as resolveAgent } from "./cli-helpers.mjs";
+import { a as removeLockEntry, i as readLock, n as parsePackages, s as writeLock } from "./lockfile.mjs";
+import { t as getProjectState } 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 { 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 { n as shutdownWorker } from "./pool2.mjs";
 import { dirname, join, relative, resolve } from "pathe";
-import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { isCI } from "std-env";
 import pLimit from "p-limit";
 import * as p from "@clack/prompts";
 import { defineCommand } from "citty";
 import logUpdate from "log-update";
-//#region src/commands/sync-shared.ts
-/** Max docs sent to the embedding pipeline to prevent oversized indexes */
-const MAX_INDEX_DOCS = 250;
-const RESOLVE_STEP_LABELS = {
-	"npm": "npm registry",
-	"github-docs": "GitHub docs",
-	"github-meta": "GitHub meta",
-	"github-search": "GitHub search",
-	"readme": "README",
-	"llms.txt": "llms.txt",
-	"crawl": "website crawl",
-	"local": "node_modules"
-};
-/** Classify a cached doc path into the right metadata type */
-function classifyCachedDoc(path) {
-	const issueMatch = path.match(/^issues\/issue-(\d+)\.md$/);
-	if (issueMatch) return {
-		type: "issue",
-		number: Number(issueMatch[1])
-	};
-	const discussionMatch = path.match(/^discussions\/discussion-(\d+)\.md$/);
-	if (discussionMatch) return {
-		type: "discussion",
-		number: Number(discussionMatch[1])
-	};
-	if (path.startsWith("releases/")) return { type: "release" };
-	return { type: "doc" };
-}
-async function findRelatedSkills(packageName, skillsDir) {
-	const related = [];
-	const npmInfo = await fetchNpmPackage(packageName);
-	if (!npmInfo?.dependencies) return related;
-	const deps = new Set(Object.keys(npmInfo.dependencies));
-	if (!existsSync(skillsDir)) return related;
-	const lock = readLock(skillsDir);
-	const pkgToDirName = /* @__PURE__ */ new Map();
-	if (lock) for (const [dirName, info] of Object.entries(lock.skills)) {
-		if (info.packageName) pkgToDirName.set(info.packageName, dirName);
-		for (const pkg of parsePackages(info.packages)) pkgToDirName.set(pkg.name, dirName);
-	}
-	const installedSkills = readdirSync(skillsDir);
-	const installedSet = new Set(installedSkills);
-	for (const dep of deps) {
-		const dirName = pkgToDirName.get(dep);
-		if (dirName && installedSet.has(dirName)) related.push(dirName);
-	}
-	return related.slice(0, 5);
-}
-/** Clear cache + db for --force flag */
-function forceClearCache(packageName, version, repoInfo) {
-	clearCache(packageName, version);
-	const forcedDbPath = getPackageDbPath(packageName, version);
-	if (existsSync(forcedDbPath)) rmSync(forcedDbPath, {
-		recursive: true,
-		force: true
-	});
-	if (repoInfo) {
-		const repoDir = getRepoCacheDir(repoInfo.owner, repoInfo.repo);
-		if (existsSync(repoDir)) rmSync(repoDir, {
-			recursive: true,
-			force: true
-		});
-	}
-}
-/** Link all reference symlinks (pkg, docs, issues, discussions, releases) */
-function linkAllReferences(skillDir, packageName, cwd, version, docsType, extraPackages, features, repoInfo) {
-	const f = features ?? readConfig().features ?? defaultFeatures;
-	try {
-		linkPkg(skillDir, packageName, cwd, version);
-		linkPkgNamed(skillDir, packageName, cwd, version);
-		if (!hasShippedDocs(packageName, cwd, version) && docsType !== "readme") linkCachedDir(skillDir, packageName, version, "docs");
-		if (f.issues) if (repoInfo) linkRepoCachedDir(skillDir, repoInfo.owner, repoInfo.repo, "issues");
-		else linkCachedDir(skillDir, packageName, version, "issues");
-		if (f.discussions) if (repoInfo) linkRepoCachedDir(skillDir, repoInfo.owner, repoInfo.repo, "discussions");
-		else linkCachedDir(skillDir, packageName, version, "discussions");
-		if (f.releases) if (repoInfo) linkRepoCachedDir(skillDir, repoInfo.owner, repoInfo.repo, "releases");
-		else linkCachedDir(skillDir, packageName, version, "releases");
-		linkCachedDir(skillDir, packageName, version, "sections");
-		if (extraPackages) {
-			for (const pkg of extraPackages) if (pkg.name !== packageName) linkPkgNamed(skillDir, pkg.name, cwd, pkg.version);
-		}
-	} catch {}
-}
-/** Detect docs type from cached directory contents */
-function detectDocsType(packageName, version, repoUrl, llmsUrl) {
-	const cacheDir = getCacheDir(packageName, version);
-	if (existsSync(join(cacheDir, "docs", "index.md")) || existsSync(join(cacheDir, "docs", "guide"))) return {
-		docsType: "docs",
-		docSource: repoUrl ? `${repoUrl}/tree/v${version}/docs` : "git"
-	};
-	if (existsSync(join(cacheDir, "llms.txt"))) return {
-		docsType: "llms.txt",
-		docSource: llmsUrl || "llms.txt"
-	};
-	if (existsSync(join(cacheDir, "docs", "README.md"))) return { docsType: "readme" };
-	return { docsType: "readme" };
-}
-/** Link shipped skills, write lock entries, register project. Returns result or null if no shipped skills. */
-function handleShippedSkills(packageName, version, cwd, agent, global) {
-	const shippedSkills = getShippedSkills(packageName, cwd, version);
-	if (shippedSkills.length === 0) return null;
-	const baseDir = resolveBaseDir(cwd, agent, global);
-	mkdirSync(baseDir, { recursive: true });
-	for (const shipped of shippedSkills) {
-		linkShippedSkill(baseDir, shipped.skillName, shipped.skillDir);
-		writeLock(baseDir, shipped.skillName, {
-			packageName,
-			version,
-			source: "shipped",
-			syncedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
-			generator: "skilld"
-		});
-	}
-	if (!global) registerProject(cwd);
-	return {
-		shipped: shippedSkills,
-		baseDir
-	};
-}
-/** Resolve the base skills directory for an agent */
-function resolveBaseDir(cwd, agent, global) {
-	if (global) return targets[agent].globalSkillsDir;
-	const shared = getSharedSkillsDir(cwd);
-	if (shared) return shared;
-	const agentConfig = targets[agent];
-	return join(cwd, agentConfig.skillsDir);
-}
-/** Try resolving a `link:` dependency to local package docs. Returns null if not a link dep or resolution fails. */
-async function resolveLocalDep(packageName, cwd) {
-	const pkgPath = join(cwd, "package.json");
-	if (!existsSync(pkgPath)) return null;
-	const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-	const depVersion = {
-		...pkg.dependencies,
-		...pkg.devDependencies
-	}[packageName];
-	if (!depVersion?.startsWith("link:")) return null;
-	return resolveLocalPackageDocs(resolve(cwd, depVersion.slice(5)));
-}
-/** Detect CHANGELOG.md in a package directory or cached releases */
-function detectChangelog(pkgDir, cacheDir) {
-	if (pkgDir) {
-		const found = ["CHANGELOG.md", "changelog.md"].find((f) => existsSync(join(pkgDir, f)));
-		if (found) return `pkg/${found}`;
-	}
-	if (cacheDir && existsSync(join(cacheDir, "releases", "CHANGELOG.md"))) return "releases/CHANGELOG.md";
-	return false;
-}
-/** Fetch and cache all resources for a package (docs cascade + issues + discussions + releases) */
-async function fetchAndCacheResources(opts) {
-	const { packageName, resolved, version, onProgress } = opts;
-	const features = opts.features ?? readConfig().features ?? defaultFeatures;
-	const cacheInvalidated = opts.useCache && resolved.crawlUrl && detectDocsType(packageName, version, resolved.repoUrl, resolved.llmsUrl).docsType === "readme";
-	const useCache = opts.useCache && !cacheInvalidated;
-	let docSource = resolved.readmeUrl || "readme";
-	let docsType = "readme";
-	const docsToIndex = [];
-	const warnings = [];
-	if (cacheInvalidated) warnings.push(`Retrying crawl for ${resolved.crawlUrl} (previous attempt only cached README)`);
-	if (!useCache) {
-		const cachedDocs = [];
-		const isFrameworkDoc = (path) => filterFrameworkDocs([path], packageName).length > 0;
-		if (resolved.gitDocsUrl && resolved.repoUrl) {
-			const gh = parseGitHubUrl(resolved.repoUrl);
-			if (gh) {
-				onProgress("Fetching git docs");
-				const gitDocs = await fetchGitDocs(gh.owner, gh.repo, version, packageName);
-				if (gitDocs?.fallback) warnings.push(`Docs fetched from ${gitDocs.ref} branch (no tag found for v${version})`);
-				if (gitDocs && gitDocs.files.length > 0) {
-					const BATCH_SIZE = 20;
-					const results = [];
-					for (let i = 0; i < gitDocs.files.length; i += BATCH_SIZE) {
-						const batch = gitDocs.files.slice(i, i + BATCH_SIZE);
-						onProgress(`Downloading docs ${Math.min(i + BATCH_SIZE, gitDocs.files.length)}/${gitDocs.files.length} from ${gitDocs.ref}`);
-						const batchResults = await Promise.all(batch.map(async (file) => {
-							const content = await fetchGitHubRaw(`${gitDocs.baseUrl}/${file}`);
-							if (!content) return null;
-							return {
-								file,
-								content
-							};
-						}));
-						results.push(...batchResults);
-					}
-					for (const r of results) if (r) {
-						const stripped = gitDocs.docsPrefix ? r.file.replace(gitDocs.docsPrefix, "") : r.file;
-						const cachePath = stripped.startsWith("docs/") ? stripped : `docs/${stripped}`;
-						cachedDocs.push({
-							path: cachePath,
-							content: r.content
-						});
-						docsToIndex.push({
-							id: cachePath,
-							content: r.content,
-							metadata: {
-								package: packageName,
-								source: cachePath,
-								type: "doc"
-							}
-						});
-					}
-					const downloaded = results.filter(Boolean).length;
-					if (downloaded > 0) if (isShallowGitDocs(downloaded) && resolved.llmsUrl) {
-						onProgress(`Shallow git-docs (${downloaded} files), trying llms.txt`);
-						cachedDocs.length = 0;
-						docsToIndex.length = 0;
-					} else {
-						docSource = `${resolved.repoUrl}/tree/${gitDocs.ref}/docs`;
-						docsType = "docs";
-						writeToCache(packageName, version, cachedDocs);
-						if (resolved.llmsUrl) {
-							onProgress("Caching supplementary llms.txt");
-							const llmsContent = await fetchLlmsTxt(resolved.llmsUrl);
-							if (llmsContent) {
-								const baseUrl = resolved.docsUrl || new URL(resolved.llmsUrl).origin;
-								const supplementary = [{
-									path: "llms.txt",
-									content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
-								}];
-								if (llmsContent.links.length > 0) {
-									onProgress(`Downloading ${llmsContent.links.length} supplementary docs`);
-									const docs = await downloadLlmsDocs(llmsContent, baseUrl, (url, done, total) => {
-										onProgress(`Downloading supplementary doc ${done + 1}/${total}`);
-									});
-									for (const doc of docs) {
-										if (!isFrameworkDoc(doc.url)) continue;
-										const localPath = doc.url.startsWith("/") ? doc.url.slice(1) : doc.url;
-										supplementary.push({
-											path: join("llms-docs", ...localPath.split("/")),
-											content: doc.content
-										});
-									}
-								}
-								writeToCache(packageName, version, supplementary);
-							}
-						}
-					}
-				}
-			}
-		}
-		if (resolved.crawlUrl && cachedDocs.length === 0) {
-			onProgress("Crawling website");
-			const crawledDocs = await fetchCrawledDocs(resolved.crawlUrl, onProgress).catch((err) => {
-				warnings.push(`Crawl failed for ${resolved.crawlUrl}: ${err?.message || err}`);
-				return [];
-			});
-			if (crawledDocs.length === 0 && resolved.crawlUrl) warnings.push(`Crawl returned 0 docs from ${resolved.crawlUrl}`);
-			if (crawledDocs.length > 0) {
-				for (const doc of crawledDocs) {
-					if (!isFrameworkDoc(doc.path)) continue;
-					cachedDocs.push(doc);
-					docsToIndex.push({
-						id: doc.path,
-						content: doc.content,
-						metadata: {
-							package: packageName,
-							source: doc.path,
-							type: "doc"
-						}
-					});
-				}
-				docSource = resolved.crawlUrl;
-				docsType = "docs";
-				writeToCache(packageName, version, cachedDocs);
-			}
-		}
-		if (resolved.llmsUrl && cachedDocs.length === 0) {
-			onProgress("Fetching llms.txt");
-			const llmsContent = await fetchLlmsTxt(resolved.llmsUrl);
-			if (llmsContent) {
-				docSource = resolved.llmsUrl;
-				docsType = "llms.txt";
-				const baseUrl = resolved.docsUrl || new URL(resolved.llmsUrl).origin;
-				cachedDocs.push({
-					path: "llms.txt",
-					content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
-				});
-				if (llmsContent.links.length > 0) {
-					onProgress(`Downloading ${llmsContent.links.length} linked docs`);
-					const docs = await downloadLlmsDocs(llmsContent, baseUrl, (url, done, total) => {
-						onProgress(`Downloading linked doc ${done + 1}/${total}`);
-					});
-					for (const doc of docs) {
-						if (!isFrameworkDoc(doc.url)) continue;
-						const cachePath = join("docs", ...(doc.url.startsWith("/") ? doc.url.slice(1) : doc.url).split("/"));
-						cachedDocs.push({
-							path: cachePath,
-							content: doc.content
-						});
-						docsToIndex.push({
-							id: doc.url,
-							content: doc.content,
-							metadata: {
-								package: packageName,
-								source: cachePath,
-								type: "doc"
-							}
-						});
-					}
-					if (docs.length > 0) docsType = "docs";
-				}
-				writeToCache(packageName, version, cachedDocs);
-			}
-		}
-		if (resolved.docsUrl && !cachedDocs.some((d) => d.path.startsWith("docs/"))) {
-			const crawlPattern = resolved.crawlUrl || toCrawlPattern(resolved.docsUrl);
-			onProgress("Crawling docs site");
-			const crawledDocs = await fetchCrawledDocs(crawlPattern, onProgress, resolved.crawlUrl ? 200 : 400).catch((err) => {
-				warnings.push(`Crawl failed for ${crawlPattern}: ${err?.message || err}`);
-				return [];
-			});
-			if (crawledDocs.length > 0) {
-				for (const doc of crawledDocs) {
-					if (!isFrameworkDoc(doc.path)) continue;
-					cachedDocs.push(doc);
-					docsToIndex.push({
-						id: doc.path,
-						content: doc.content,
-						metadata: {
-							package: packageName,
-							source: doc.path,
-							type: "doc"
-						}
-					});
-				}
-				docSource = crawlPattern;
-				docsType = "docs";
-				writeToCache(packageName, version, cachedDocs);
-			}
-		}
-		if (resolved.readmeUrl && cachedDocs.length === 0) {
-			onProgress("Fetching README");
-			const content = await fetchReadmeContent(resolved.readmeUrl);
-			if (content) {
-				cachedDocs.push({
-					path: "docs/README.md",
-					content
-				});
-				docsToIndex.push({
-					id: "README.md",
-					content,
-					metadata: {
-						package: packageName,
-						source: "docs/README.md",
-						type: "doc"
-					}
-				});
-				writeToCache(packageName, version, cachedDocs);
-			}
-		}
-		if (docsType !== "readme" && cachedDocs.filter((d) => d.path.startsWith("docs/") && d.path.endsWith(".md")).length > 1) {
-			const docsIndex = generateDocsIndex(cachedDocs);
-			if (docsIndex) writeToCache(packageName, version, [{
-				path: "docs/_INDEX.md",
-				content: docsIndex
-			}]);
-		}
-	} else {
-		onProgress("Loading cached docs");
-		const detected = detectDocsType(packageName, version, resolved.repoUrl, resolved.llmsUrl);
-		docsType = detected.docsType;
-		if (detected.docSource) docSource = detected.docSource;
-		if (!existsSync(getPackageDbPath(packageName, version))) {
-			onProgress("Reading cached docs for indexing");
-			const cached = readCachedDocs(packageName, version);
-			for (const doc of cached) docsToIndex.push({
-				id: doc.path,
-				content: doc.content,
-				metadata: {
-					package: packageName,
-					source: doc.path,
-					...classifyCachedDoc(doc.path)
-				}
-			});
-		}
-		if (docsType !== "readme" && !existsSync(join(getCacheDir(packageName, version), "docs", "_INDEX.md"))) {
-			onProgress("Generating docs index");
-			const cached = readCachedDocs(packageName, version);
-			if (cached.filter((d) => d.path.startsWith("docs/") && d.path.endsWith(".md")).length > 1) {
-				const docsIndex = generateDocsIndex(cached);
-				if (docsIndex) writeToCache(packageName, version, [{
-					path: "docs/_INDEX.md",
-					content: docsIndex
-				}]);
-			}
-		}
-	}
-	const gh = resolved.repoUrl ? parseGitHubUrl(resolved.repoUrl) : null;
-	const repoInfo = gh ? {
-		owner: gh.owner,
-		repo: gh.repo
-	} : void 0;
-	const repoCacheDir = repoInfo ? getRepoCacheDir(repoInfo.owner, repoInfo.repo) : null;
-	const cacheDir = getCacheDir(packageName, version);
-	const issuesDir = repoCacheDir ? join(repoCacheDir, "issues") : join(cacheDir, "issues");
-	const discussionsDir = repoCacheDir ? join(repoCacheDir, "discussions") : join(cacheDir, "discussions");
-	const releasesPath = repoCacheDir ? join(repoCacheDir, "releases") : join(cacheDir, "releases");
-	if (features.issues && gh && isGhAvailable() && !existsSync(issuesDir)) {
-		onProgress("Fetching issues via GitHub API");
-		const issues = await fetchGitHubIssues(gh.owner, gh.repo, 30, resolved.releasedAt, opts.from).catch(() => []);
-		if (issues.length > 0) {
-			onProgress(`Caching ${issues.length} issues`);
-			const issueDocs = [...issues.map((issue) => ({
-				path: `issues/issue-${issue.number}.md`,
-				content: formatIssueAsMarkdown(issue)
-			})), {
-				path: "issues/_INDEX.md",
-				content: generateIssueIndex(issues)
-			}];
-			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, issueDocs);
-			else writeToCache(packageName, version, issueDocs);
-			for (const issue of issues) docsToIndex.push({
-				id: `issue-${issue.number}`,
-				content: sanitizeMarkdown(`#${issue.number}: ${issue.title}\n\n${issue.body || ""}`),
-				metadata: {
-					package: packageName,
-					source: `issues/issue-${issue.number}.md`,
-					type: "issue",
-					number: issue.number
-				}
-			});
-		}
-	}
-	if (features.discussions && gh && isGhAvailable() && !existsSync(discussionsDir)) {
-		onProgress("Fetching discussions via GitHub API");
-		const discussions = await fetchGitHubDiscussions(gh.owner, gh.repo, 20, resolved.releasedAt, opts.from).catch(() => []);
-		if (discussions.length > 0) {
-			onProgress(`Caching ${discussions.length} discussions`);
-			const discussionDocs = [...discussions.map((d) => ({
-				path: `discussions/discussion-${d.number}.md`,
-				content: formatDiscussionAsMarkdown(d)
-			})), {
-				path: "discussions/_INDEX.md",
-				content: generateDiscussionIndex(discussions)
-			}];
-			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, discussionDocs);
-			else writeToCache(packageName, version, discussionDocs);
-			for (const d of discussions) docsToIndex.push({
-				id: `discussion-${d.number}`,
-				content: sanitizeMarkdown(`#${d.number}: ${d.title}\n\n${d.body || ""}`),
-				metadata: {
-					package: packageName,
-					source: `discussions/discussion-${d.number}.md`,
-					type: "discussion",
-					number: d.number
-				}
-			});
-		}
-	}
-	if (features.releases && gh && isGhAvailable() && !existsSync(releasesPath)) {
-		onProgress("Fetching releases via GitHub API");
-		const changelogRef = isPrerelease(version) ? getPrereleaseChangelogRef(packageName) : void 0;
-		const releaseDocs = await fetchReleaseNotes(gh.owner, gh.repo, version, resolved.gitRef, packageName, opts.from, changelogRef).catch(() => []);
-		let blogDocs = [];
-		if (getBlogPreset(packageName)) {
-			onProgress("Fetching blog release notes");
-			blogDocs = await fetchBlogReleases(packageName, version).catch(() => []);
-		}
-		const allDocs = [...releaseDocs, ...blogDocs];
-		const blogEntries = blogDocs.filter((d) => !d.path.endsWith("_INDEX.md")).map((d) => {
-			const versionMatch = d.path.match(/blog-(.+)\.md$/);
-			const fm = parseFrontmatter(d.content);
-			return {
-				version: versionMatch?.[1] ?? "",
-				title: fm.title ?? `Release ${versionMatch?.[1]}`,
-				date: fm.date ?? ""
-			};
-		}).filter((b) => b.version);
-		const ghReleases = releaseDocs.filter((d) => d.path.startsWith("releases/") && !d.path.endsWith("CHANGELOG.md")).map((d) => {
-			const fm = parseFrontmatter(d.content);
-			const tag = fm.tag ?? "";
-			const name = fm.name ?? tag;
-			const published = fm.published ?? "";
-			return {
-				id: 0,
-				tag,
-				name,
-				prerelease: false,
-				createdAt: published,
-				publishedAt: published,
-				markdown: ""
-			};
-		}).filter((r) => r.tag);
-		const hasChangelog = allDocs.some((d) => d.path === "releases/CHANGELOG.md");
-		if (ghReleases.length > 0 || blogEntries.length > 0) allDocs.push({
-			path: "releases/_INDEX.md",
-			content: generateReleaseIndex({
-				releases: ghReleases,
-				packageName,
-				blogReleases: blogEntries,
-				hasChangelog
-			})
-		});
-		if (allDocs.length > 0) {
-			onProgress(`Caching ${allDocs.length} releases`);
-			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, allDocs);
-			else writeToCache(packageName, version, allDocs);
-			for (const doc of allDocs) docsToIndex.push({
-				id: doc.path,
-				content: doc.content,
-				metadata: {
-					package: packageName,
-					source: doc.path,
-					type: "release"
-				}
-			});
-		}
-	}
-	return {
-		docSource,
-		docsType,
-		docsToIndex,
-		hasIssues: features.issues && existsSync(issuesDir),
-		hasDiscussions: features.discussions && existsSync(discussionsDir),
-		hasReleases: features.releases && existsSync(releasesPath),
-		warnings,
-		repoInfo,
-		usedCache: useCache
-	};
-}
-/**
-* 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);
-	const dbExists = existsSync(dbPath);
-	const allDocs = [...opts.docsToIndex];
-	const pkgDir = resolvePkgDir(packageName, cwd, version);
-	if (features.search && pkgDir) {
-		onProgress("Scanning exports");
-		const entryFiles = await resolveEntryFiles(pkgDir);
-		for (const e of entryFiles) allDocs.push({
-			id: e.path,
-			content: e.content,
-			metadata: {
-				package: packageName,
-				source: `pkg/${e.path}`,
-				type: e.type
-			}
-		});
-	}
-	if (allDocs.length === 0) return;
-	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;
-	}
-	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(newDocs, {
-			dbPath,
-			removeIds,
-			onProgress: ({ phase, current, total }) => {
-				if (phase === "storing") {
-					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})`);
-			}
-		});
-	} catch (err) {
-		if (err instanceof SearchDepsUnavailableError) onProgress("Search indexing skipped (native deps unavailable)");
-		else throw err;
-	}
-}
-/**
-* Eject references: copy cached files as real files into references/ dir.
-* Used for portable skills (git repos, sharing). Replaces symlinks with copies.
-* Does NOT copy pkg files — those reference node_modules directly.
-*/
-function ejectReferences(skillDir, packageName, cwd, version, docsType, features, repoInfo) {
-	const f = features ?? readConfig().features ?? defaultFeatures;
-	const cacheDir = getCacheDir(packageName, version);
-	const refsDir = join(skillDir, "references");
-	const repoDir = repoInfo ? getRepoCacheDir(repoInfo.owner, repoInfo.repo) : cacheDir;
-	if (!hasShippedDocs(packageName, cwd, version) && docsType !== "readme") copyCachedSubdir(cacheDir, refsDir, "docs");
-	if (f.issues) copyCachedSubdir(repoDir, refsDir, "issues");
-	if (f.discussions) copyCachedSubdir(repoDir, refsDir, "discussions");
-	if (f.releases) copyCachedSubdir(repoDir, refsDir, "releases");
-}
-/** Recursively copy a cached subdirectory into the references dir */
-function copyCachedSubdir(cacheDir, refsDir, subdir) {
-	const srcDir = join(cacheDir, subdir);
-	if (!existsSync(srcDir)) return;
-	const destDir = join(refsDir, subdir);
-	mkdirSync(destDir, { recursive: true });
-	function walk(dir, rel) {
-		for (const entry of readdirSync(dir, { withFileTypes: true })) {
-			const srcPath = join(dir, entry.name);
-			const destPath = join(destDir, rel ? `${rel}/${entry.name}` : entry.name);
-			if (entry.isDirectory()) {
-				mkdirSync(destPath, { recursive: true });
-				walk(srcPath, rel ? `${rel}/${entry.name}` : entry.name);
-			} else copyFileSync(srcPath, destPath);
-		}
-	}
-	walk(srcDir, "");
-}
-/**
-* Check if .gitignore has `.skilld` entry.
-* If missing, prompt to add it. Skipped for global installs.
-*/
-async function ensureGitignore(skillsDir, cwd, isGlobal) {
-	if (isGlobal) return;
-	const gitignorePath = join(cwd, ".gitignore");
-	const pattern = ".skilld";
-	if (existsSync(gitignorePath)) {
-		if (readFileSync(gitignorePath, "utf-8").split("\n").some((line) => line.trim() === pattern)) return;
-	}
-	if (!isInteractive()) {
-		const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
-		if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
-		else writeFileSync(gitignorePath, entry);
-		return;
-	}
-	const relSkillsDir = relative(cwd, skillsDir) || ".";
-	p.log.info(`\x1B[1mGit guidance:\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${relSkillsDir}/*/SKILL.md\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${relSkillsDir}/skilld-lock.yaml\x1B[0m\n  \x1B[31m✗\x1B[0m Ignore: \x1B[36m${pattern}\x1B[0m \x1B[90m(recreated by \`skilld install\`)\x1B[0m`);
-	const add = await p.confirm({
-		message: `Add \`${pattern}\` to .gitignore?`,
-		initialValue: true
-	});
-	if (p.isCancel(add) || !add) return;
-	const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
-	if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
-	else writeFileSync(gitignorePath, entry);
-	p.log.success("Updated .gitignore");
-}
-const SKILLD_MARKER_START = "<!-- skilld -->";
-const SKILLD_MARKER_END = "<!-- /skilld -->";
-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.
-*/
-async function ensureAgentInstructions(agent, cwd, isGlobal) {
-	if (isGlobal) return;
-	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${getSkillInstructions(agent)}\n`);
-		else writeFileSync(filePath, `${getSkillInstructions(agent)}\n`);
-		return;
-	}
-	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: `${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${getSkillInstructions(agent)}\n`);
-	else writeFileSync(filePath, `${getSkillInstructions(agent)}\n`);
-	p.log.success(`Updated ${agentConfig.instructionFile}`);
-}
-/** Default sections when model is pre-set (non-interactive) */
-const DEFAULT_SECTIONS = ["best-practices", "api-changes"];
-async function selectSkillSections(message = "Enhance SKILL.md") {
-	p.log.info("Budgets adapt to package release density.");
-	const selected = await p.multiselect({
-		message,
-		options: [
-			{
-				label: "API changes",
-				value: "api-changes",
-				hint: "new/deprecated APIs from version history"
-			},
-			{
-				label: "Best practices",
-				value: "best-practices",
-				hint: "gotchas, pitfalls, patterns"
-			},
-			{
-				label: "Custom section",
-				value: "custom",
-				hint: "add your own section"
-			}
-		],
-		initialValues: DEFAULT_SECTIONS,
-		required: false
-	});
-	if (p.isCancel(selected)) return {
-		sections: [],
-		cancelled: true
-	};
-	const sections = selected;
-	if (sections.length === 0) return {
-		sections: [],
-		cancelled: false
-	};
-	if (sections.length > 1) {
-		const n = sections.length;
-		const budgetLines = [];
-		for (const s of sections) switch (s) {
-			case "api-changes":
-				budgetLines.push(`  API changes     ${maxItems(6, 12, n)}–${maxItems(6, Math.round(12 * 1.6), n)} items (adapts to release churn)`);
-				break;
-			case "best-practices":
-				budgetLines.push(`  Best practices  ${maxItems(4, 10, n)}–${maxItems(4, Math.round(10 * 1.3), n)} items`);
-				break;
-			case "custom":
-				budgetLines.push(`  Custom          ≤${maxLines(50, 80, n)} lines`);
-				break;
-		}
-		p.log.info(`Budget (${n} sections):\n${budgetLines.join("\n")}`);
-	}
-	let customPrompt;
-	if (sections.includes("custom")) {
-		const heading = await p.text({
-			message: "Section heading",
-			placeholder: "e.g. \"Migration from v2\" or \"SSR Patterns\""
-		});
-		if (p.isCancel(heading)) return {
-			sections: [],
-			cancelled: true
-		};
-		const body = await p.text({
-			message: "Instructions for this section",
-			placeholder: "e.g. \"Document breaking changes and migration steps from v2 to v3\""
-		});
-		if (p.isCancel(body)) return {
-			sections: [],
-			cancelled: true
-		};
-		customPrompt = {
-			heading,
-			body
-		};
-	}
-	return {
-		sections,
-		customPrompt,
-		cancelled: false
-	};
-}
-/**
-* Resolve sections + model for LLM enhancement.
-* If presetModel is provided, uses DEFAULT_SECTIONS without prompting.
-* Returns null if cancelled or no sections/model selected.
-*/
-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 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: enhanceMessage,
-		options: [
-			{
-				label: defaultModelName,
-				value: "default",
-				hint: defaultHint
-			},
-			{
-				label: "Different model",
-				value: "pick",
-				hint: "choose another enhancement model"
-			},
-			{
-				label: "Prompt only",
-				value: "prompt",
-				hint: "write prompts for manual use"
-			},
-			{
-				label: "Skip",
-				value: "skip",
-				hint: "base skill with docs, issues, and types"
-			}
-		],
-		...defaultToSkip ? { initialValue: "skip" } : {}
-	});
-	if (p.isCancel(choice)) return null;
-	if (choice === "skip") return null;
-	if (choice === "prompt") {
-		const { sections, customPrompt, cancelled } = await selectSkillSections(message ? `${message} (prompt only)` : "Select sections for prompt generation");
-		if (cancelled || sections.length === 0) return null;
-		return {
-			model: defaultModel,
-			sections,
-			customPrompt,
-			promptOnly: true
-		};
-	}
-	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})` : `Enhance SKILL.md with ${modelName}`);
-	if (cancelled || sections.length === 0) return null;
-	return {
-		model,
-		sections,
-		customPrompt
-	};
-}
-async function enhanceSkillWithLLM(opts) {
-	const { packageName, version, skillDir, dirName, model, resolved, relatedSkills, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs: shippedDocs, pkgFiles, force, debug, sections, customPrompt, packages, features, eject } = opts;
-	const effectiveFeatures = features;
-	const llmLog = p.taskLog({ title: `Agent exploring ${packageName}` });
-	const docFiles = listReferenceFiles(skillDir);
-	const { optimized, wasOptimized, usage, cost, warnings, error, debugLogsDir } = await optimizeDocs({
-		packageName,
-		skillDir,
-		model,
-		version,
-		hasGithub: hasIssues || hasDiscussions,
-		hasReleases,
-		hasChangelog,
-		docFiles,
-		docsType,
-		hasShippedDocs: shippedDocs,
-		noCache: force,
-		debug,
-		sections,
-		customPrompt,
-		features: effectiveFeatures,
-		pkgFiles,
-		onProgress: createToolProgress(llmLog)
-	});
-	if (wasOptimized) {
-		const costParts = [];
-		if (usage) {
-			const totalK = Math.round(usage.totalTokens / 1e3);
-			costParts.push(`${totalK}k tokens`);
-		}
-		if (cost) costParts.push(`$${cost.toFixed(2)}`);
-		const costSuffix = costParts.length > 0 ? ` (${costParts.join(", ")})` : "";
-		llmLog.success(`Generated best practices${costSuffix}`);
-		if (debugLogsDir) p.log.info(`Debug logs: ${relative(process.cwd(), debugLogsDir)}`);
-		if (error) p.log.warn(`\x1B[33mPartial failure: ${error}\x1B[0m`);
-		if (warnings?.length) for (const w of warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
-		const skillMd = generateSkillMd({
-			name: packageName,
-			version,
-			releasedAt: resolved.releasedAt,
-			dependencies: resolved.dependencies,
-			distTags: resolved.distTags,
-			body: optimized,
-			relatedSkills,
-			hasIssues,
-			hasDiscussions,
-			hasReleases,
-			hasChangelog,
-			docsType,
-			hasShippedDocs: shippedDocs,
-			pkgFiles,
-			generatedBy: getModelLabel(model),
-			dirName,
-			packages,
-			repoUrl: resolved.repoUrl,
-			features,
-			eject
-		});
-		writeFileSync(join(skillDir, "SKILL.md"), skillMd);
-	} else llmLog.error(`Enhancement failed${error ? `: ${error}` : ""}`);
-}
-/**
-* Build and write PROMPT_*.md files for manual LLM use.
-* Returns the list of sections that had prompts written.
-*/
-function writePromptFiles(opts) {
-	const { skillDir, sections, customPrompt, features } = opts;
-	const docFiles = listReferenceFiles(skillDir);
-	const prompts = buildAllSectionPrompts({
-		packageName: opts.packageName,
-		skillDir,
-		version: opts.version,
-		hasIssues: opts.hasIssues,
-		hasDiscussions: opts.hasDiscussions,
-		hasReleases: opts.hasReleases,
-		hasChangelog: opts.hasChangelog,
-		docFiles,
-		docsType: opts.docsType,
-		hasShippedDocs: opts.hasShippedDocs,
-		pkgFiles: opts.pkgFiles,
-		customPrompt,
-		features,
-		sections
-	});
-	const skilldDir = join(skillDir, ".skilld");
-	mkdirSync(skilldDir, { recursive: true });
-	for (const [section, prompt] of prompts) writeFileSync(join(skilldDir, `PROMPT_${section}.md`), prompt);
-	const written = [...prompts.keys()];
-	if (written.length > 0) {
-		const relDir = relative(process.cwd(), skillDir);
-		const promptFiles = written.map((s) => `PROMPT_${s}.md`).join(", ");
-		const outputFileList = written.map((s) => SECTION_OUTPUT_FILES[s]).join(", ");
-		p.log.info(`Prompt files written to ${relDir}/.skilld/\n\x1B[2m\x1B[3m  Read each prompt file (${promptFiles}) in ${relDir}/.skilld/, read the\n  referenced files, then write your output to the matching file (${outputFileList}).\n  When done, run: skilld assemble\x1B[0m`);
-	}
-	return written;
-}
-//#endregion
 //#region src/telemetry.ts
 /**
 * Anonymous telemetry — fire-and-forget GET to add-skill.vercel.sh/t
@@ -1419,7 +385,6 @@ async function syncPackagesParallel(config) {
 				name: resolvedName,
 				version: data.version,
 				releasedAt: data.resolved.releasedAt,
-				dependencies: data.resolved.dependencies,
 				distTags: data.resolved.distTags,
 				body: cachedBody,
 				relatedSkills: data.relatedSkills,
@@ -1499,7 +464,8 @@ async function syncPackagesParallel(config) {
 				pkgFiles: data.pkgFiles,
 				sections: llmConfig.sections,
 				customPrompt: llmConfig.customPrompt,
-				features: data.features
+				features: data.features,
+				overheadLines: data.overheadLines
 			});
 		}
 		else if (llmConfig) {
@@ -1523,12 +489,18 @@ async function syncPackagesParallel(config) {
 	await ensureAgentInstructions(config.agent, cwd, config.global);
 	await shutdownWorker();
 	p.outro(`${pastVerb} ${successfulPkgs.length}/${packages.length} packages`);
+	const { suggestPrepareHook } = await import("./cli-helpers2.mjs");
+	try {
+		await suggestPrepareHook(cwd);
+	} catch (err) {
+		p.log.warn(`Failed to suggest prepare hook: ${err instanceof Error ? err.message : String(err)}`);
+	}
 }
 /** Phase 1: Generate base skill (no LLM). Returns 'shipped' if shipped skill was linked, or BaseSkillData. */
 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 } = await resolvePackageDocsWithAttempts(requestedTag ? packageSpec : packageName, {
+	const { package: resolvedPkg, attempts, registryVersion } = await resolvePackageDocsWithAttempts(requestedTag ? packageSpec : packageName, {
 		version: localVersion,
 		cwd,
 		onProgress: (step) => update(packageName, "resolving", RESOLVE_STEP_LABELS[step])
@@ -1539,6 +511,14 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 		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";
+		}
 		const npmAttempt = attempts.find((a) => a.source === "npm");
 		let reason;
 		if (npmAttempt?.status === "not-found") {
@@ -1629,7 +609,6 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 		version,
 		releasedAt: resolved.releasedAt,
 		description: resolved.description,
-		dependencies: resolved.dependencies,
 		distTags: resolved.distTags,
 		relatedSkills,
 		hasIssues: resources.hasIssues,
@@ -1645,6 +624,7 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 		features
 	});
 	writeFileSync(join(skillDir, "SKILL.md"), skillMd);
+	const overheadLines = skillMd.split("\n").length;
 	const shared = !config.global && getSharedSkillsDir(cwd);
 	if (shared) linkSkillToAgents(skillDirName, shared, cwd, config.agent);
 	if (!config.global) registerProject(cwd);
@@ -1667,7 +647,8 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 		usedCache: resources.usedCache,
 		oldVersion: preLock?.version,
 		oldSyncedAt: preLock?.syncedAt,
-		wasEnhanced: preEnhanced
+		wasEnhanced: preEnhanced,
+		overheadLines
 	};
 }
 /** Phase 2: Enhance skill with LLM */
@@ -1694,6 +675,7 @@ async function enhanceWithLLM(packageName, data, config, cwd, update, 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}] ` : "";
@@ -1709,7 +691,6 @@ async function enhanceWithLLM(packageName, data, config, cwd, update, sections,
 			name: packageName,
 			version: data.version,
 			releasedAt: data.resolved.releasedAt,
-			dependencies: data.resolved.dependencies,
 			distTags: data.resolved.distTags,
 			body: optimized,
 			relatedSkills: data.relatedSkills,
@@ -1856,6 +837,16 @@ async function syncSinglePackage(packageSpec, config) {
 		resolved = await resolveLocalDep(packageName, cwd);
 	}
 	if (!resolved) {
+		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 (suggestions.length > 0) {
@@ -2010,14 +1001,25 @@ async function syncSinglePackage(packageSpec, config) {
 	const pkgFiles = getPkgKeyFiles(packageName, cwd, version);
 	const repoSlug = resolved.repoUrl?.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?(?:[/#]|$)/)?.[1];
 	if (!config.eject) linkPkgNamed(skillDir, packageName, cwd, version);
-	if (!config.eject) writeLock(baseDir, skillDirName, {
-		packageName,
-		version,
-		repo: repoSlug,
-		source: resources.docSource,
-		syncedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
-		generator: "skilld"
-	});
+	if (!config.eject) {
+		writeLock(baseDir, skillDirName, {
+			packageName,
+			version,
+			repo: repoSlug,
+			source: resources.docSource,
+			syncedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+			generator: "skilld"
+		});
+		const lock = readLock(baseDir);
+		if (lock) for (const [name, info] of Object.entries(lock.skills)) {
+			if (name === skillDirName) continue;
+			if (info.packageName === packageName || parsePackages(info.packages).some((p) => p.name === packageName)) {
+				removeLockEntry(baseDir, name);
+				const staleDir = join(baseDir, name);
+				if (existsSync(staleDir)) rmSync(staleDir, { recursive: true });
+			}
+		}
+	}
 	const allPackages = parsePackages((config.eject ? void 0 : readLock(baseDir)?.skills[skillDirName])?.packages).map((p) => ({ name: p.name }));
 	const isEject = !!config.eject;
 	const baseSkillMd = generateSkillMd({
@@ -2025,7 +1027,6 @@ async function syncSinglePackage(packageSpec, config) {
 		version,
 		releasedAt: resolved.releasedAt,
 		description: resolved.description,
-		dependencies: resolved.dependencies,
 		distTags: resolved.distTags,
 		relatedSkills,
 		hasIssues: resources.hasIssues,
@@ -2042,6 +1043,7 @@ async function syncSinglePackage(packageSpec, config) {
 		eject: isEject
 	});
 	writeFileSync(join(skillDir, "SKILL.md"), baseSkillMd);
+	const overheadLines = baseSkillMd.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];
@@ -2061,7 +1063,6 @@ async function syncSinglePackage(packageSpec, config) {
 			version,
 			releasedAt: resolved.releasedAt,
 			description: resolved.description,
-			dependencies: resolved.dependencies,
 			distTags: resolved.distTags,
 			body: cachedBody,
 			relatedSkills,
@@ -2104,7 +1105,8 @@ async function syncSinglePackage(packageSpec, config) {
 			pkgFiles,
 			sections: llmConfig.sections,
 			customPrompt: llmConfig.customPrompt,
-			features
+			features,
+			overheadLines
 		});
 		else if (llmConfig) {
 			p.log.step(getModelLabel(llmConfig.model));
@@ -2129,7 +1131,8 @@ async function syncSinglePackage(packageSpec, config) {
 				customPrompt: llmConfig.customPrompt,
 				packages: allPackages.length > 1 ? allPackages : void 0,
 				features,
-				eject: isEject
+				eject: isEject,
+				overheadLines
 			});
 		}
 	}
@@ -2152,6 +1155,11 @@ async function syncSinglePackage(packageSpec, config) {
 	const ejectMsg = isEject ? " (ejected)" : "";
 	const relDir = relative(cwd, skillDir);
 	p.outro(config.mode === "update" ? `Updated ${packageName}${ejectMsg}` : `Synced ${packageName} → ${relDir}${ejectMsg}`);
+	try {
+		await suggestPrepareHook(cwd);
+	} catch (err) {
+		p.log.warn(`Failed to suggest prepare hook: ${err instanceof Error ? err.message : String(err)}`);
+	}
 }
 const addCommandDef = defineCommand({
 	meta: {
@@ -2464,7 +1472,6 @@ async function exportPortablePrompts(packageSpec, opts) {
 		version,
 		releasedAt: resolved.releasedAt,
 		description: resolved.description,
-		dependencies: resolved.dependencies,
 		distTags: resolved.distTags,
 		relatedSkills,
 		hasIssues: resources.hasIssues,
@@ -2503,6 +1510,6 @@ async function exportPortablePrompts(packageSpec, opts) {
 	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`);
 }
 //#endregion
-export { selectLlmConfig as a, addCommandDef, ejectCommandDef, indexResources as i, SKILLD_MARKER_START as n, writePromptFiles as o, classifyCachedDoc as r, syncCommand, SKILLD_MARKER_END as t, updateCommandDef };
+export { updateCommandDef as a, syncCommand as i, ejectCommandDef as n, exportPortablePrompts as r, addCommandDef as t };
 
 //# sourceMappingURL=sync.mjs.map