skilld 0.11.3 → 0.12.0

package/dist/cache/index.d.mts

@@ -1,2 +1,2 @@
-import { C as CacheConfig, D as REFERENCES_DIR, E as CACHE_DIR, O as getPackageDbPath, S as writeToCache, T as CachedPackage, _ as listReferenceFiles, a as clearAllCache, b as resolvePkgDir, c as getPkgKeyFiles, d as isCached, f as linkCachedDir, g as listCached, h as linkShippedSkill, i as ShippedSkill, l as getShippedSkills, m as linkPkgNamed, n as getCacheKey, o as clearCache, p as linkPkg, r as getVersionKey, s as ensureCacheDir, t as getCacheDir, u as hasShippedDocs, v as readCachedDocs, w as CachedDoc, x as writeSections, y as readCachedSection } from "../_chunks/version.mjs";
-export { CACHE_DIR, type CacheConfig, type CachedDoc, type CachedPackage, REFERENCES_DIR, type ShippedSkill, clearAllCache, clearCache, ensureCacheDir, getCacheDir, getCacheKey, getPackageDbPath, getPkgKeyFiles, getShippedSkills, getVersionKey, hasShippedDocs, isCached, linkCachedDir, linkPkg, linkPkgNamed, linkShippedSkill, listCached, listReferenceFiles, readCachedDocs, readCachedSection, resolvePkgDir, writeSections, writeToCache };
+import { A as REPOS_DIR, C as writeToCache, D as CachedPackage, E as CachedDoc, M as getRepoCacheDir, O as CACHE_DIR, S as writeSections, T as CacheConfig, _ as listCached, a as clearAllCache, b as readCachedSection, c as getPkgKeyFiles, d as isCached, f as linkCachedDir, g as linkShippedSkill, h as linkRepoCachedDir, i as ShippedSkill, j as getPackageDbPath, k as REFERENCES_DIR, l as getShippedSkills, m as linkPkgNamed, n as getCacheKey, o as clearCache, p as linkPkg, r as getVersionKey, s as ensureCacheDir, t as getCacheDir, u as hasShippedDocs, v as listReferenceFiles, w as writeToRepoCache, x as resolvePkgDir, y as readCachedDocs } from "../_chunks/version.mjs";
+export { CACHE_DIR, type CacheConfig, type CachedDoc, type CachedPackage, REFERENCES_DIR, REPOS_DIR, type ShippedSkill, clearAllCache, clearCache, ensureCacheDir, getCacheDir, getCacheKey, getPackageDbPath, getPkgKeyFiles, getRepoCacheDir, getShippedSkills, getVersionKey, hasShippedDocs, isCached, linkCachedDir, linkPkg, linkPkgNamed, linkRepoCachedDir, linkShippedSkill, listCached, listReferenceFiles, readCachedDocs, readCachedSection, resolvePkgDir, writeSections, writeToCache, writeToRepoCache };

package/dist/cache/index.mjs

@@ -1,3 +1,3 @@
-import { a as getCacheKey, i as getCacheDir, n as REFERENCES_DIR, o as getVersionKey, r as getPackageDbPath, t as CACHE_DIR } from "../_chunks/config.mjs";
-import { _ as writeSections, a as getShippedSkills, c as linkCachedDir, d as linkShippedSkill, f as listCached, g as resolvePkgDir, h as readCachedSection, i as getPkgKeyFiles, l as linkPkg, m as readCachedDocs, n as clearCache, o as hasShippedDocs, p as listReferenceFiles, r as ensureCacheDir, s as isCached, t as clearAllCache, u as linkPkgNamed, v as writeToCache } from "../_chunks/storage.mjs";
-export { CACHE_DIR, REFERENCES_DIR, clearAllCache, clearCache, ensureCacheDir, getCacheDir, getCacheKey, getPackageDbPath, getPkgKeyFiles, getShippedSkills, getVersionKey, hasShippedDocs, isCached, linkCachedDir, linkPkg, linkPkgNamed, linkShippedSkill, listCached, listReferenceFiles, readCachedDocs, readCachedSection, resolvePkgDir, writeSections, writeToCache };
+import { a as getRepoCacheDir, c as getVersionKey, i as getPackageDbPath, n as REFERENCES_DIR, o as getCacheDir, r as REPOS_DIR, s as getCacheKey, t as CACHE_DIR } from "../_chunks/config.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, p as listCached, r as ensureCacheDir, s as isCached, t as clearAllCache, u as linkPkgNamed, v as writeSections, y as writeToCache } from "../_chunks/storage.mjs";
+export { CACHE_DIR, REFERENCES_DIR, REPOS_DIR, clearAllCache, clearCache, ensureCacheDir, getCacheDir, getCacheKey, getPackageDbPath, getPkgKeyFiles, getRepoCacheDir, getShippedSkills, getVersionKey, hasShippedDocs, isCached, linkCachedDir, linkPkg, linkPkgNamed, linkRepoCachedDir, linkShippedSkill, listCached, listReferenceFiles, readCachedDocs, readCachedSection, resolvePkgDir, writeSections, writeToCache, writeToRepoCache };

package/dist/cli.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { t as __exportAll } from "./_chunks/chunk.mjs";
-import { i as getCacheDir, n as REFERENCES_DIR, o as getVersionKey, r as getPackageDbPath, t as CACHE_DIR } from "./_chunks/config.mjs";
-import { a as getShippedSkills, b as sanitizeMarkdown, c as linkCachedDir, d as linkShippedSkill, g as resolvePkgDir, i as getPkgKeyFiles, l as linkPkg, m as readCachedDocs, n as clearCache, o as hasShippedDocs, p as listReferenceFiles, r as ensureCacheDir, s as isCached, u as linkPkgNamed, v as writeToCache } from "./_chunks/storage.mjs";
+import { a as getRepoCacheDir, c as getVersionKey, i as getPackageDbPath, n as REFERENCES_DIR, o as getCacheDir, t as CACHE_DIR } from "./_chunks/config.mjs";
+import { S as sanitizeMarkdown, _ as resolvePkgDir, a as getShippedSkills, b as writeToRepoCache, c as linkCachedDir, d as linkRepoCachedDir, f as linkShippedSkill, h as readCachedDocs, i as getPkgKeyFiles, l as linkPkg, m as listReferenceFiles, n as clearCache, o as hasShippedDocs, r as ensureCacheDir, s as isCached, u as linkPkgNamed, y as writeToCache } from "./_chunks/storage.mjs";
 import "./cache/index.mjs";
 import { n as yamlParseKV, r as yamlUnescape, t as yamlEscape } from "./_chunks/yaml.mjs";
 import { i as parseFrontmatter } from "./_chunks/markdown.mjs";
 import { n as clearEmbeddingCache } from "./_chunks/embedding-cache.mjs";
 import { closePool, createIndex, openPool, searchPooled, searchSnippets } from "./retriv/index.mjs";
-import { a as getPrereleaseChangelogRef, t as getBlogPreset } from "./_chunks/package-registry.mjs";
-import { $ as isGhAvailable, B as isPrerelease, E as normalizeLlmsLinks, F as generateDiscussionIndex, H as $fetch, I as fetchBlogReleases, J as parsePackageSpec, M as generateDocsIndex, N as fetchGitHubDiscussions, O as fetchGitSkills, P as formatDiscussionAsMarkdown, Q as generateIssueIndex, R as fetchReleaseNotes, S as downloadLlmsDocs, X as fetchGitHubIssues, Z as formatIssueAsMarkdown, b as resolveGitHubRepo, d as resolvePackageDocs, et as SHARED_SKILLS_DIR, f as resolvePackageDocsWithAttempts, h as fetchGitDocs, i as fetchPkgDist, j as resolveEntryFiles, k as parseGitSkillInput, n as fetchNpmPackage, nt as mapInsert, p as searchNpmPackages, q as parseGitHubUrl, r as fetchNpmRegistryMeta, rt as semverGt, s as readLocalDependencies, t as fetchLatestVersion, tt as getSharedSkillsDir, u as resolveLocalPackageDocs, v as fetchReadmeContent, w as fetchLlmsTxt, y as isShallowGitDocs, z as generateReleaseIndex } from "./_chunks/npm.mjs";
+import { o as getPrereleaseChangelogRef, t as getBlogPreset } from "./_chunks/package-registry.mjs";
+import { $ as formatIssueAsMarkdown, B as fetchReleaseNotes, E as normalizeLlmsLinks, F as generateDiscussionIndex, H as isPrerelease, I as fetchCrawledDocs, L as toCrawlPattern, M as generateDocsIndex, N as fetchGitHubDiscussions, O as fetchGitSkills, P as formatDiscussionAsMarkdown, Q as fetchGitHubIssues, R as fetchBlogReleases, S as downloadLlmsDocs, V as generateReleaseIndex, W as $fetch, X as parsePackageSpec, Y as parseGitHubUrl, at as semverGt, b as resolveGitHubRepo, d as resolvePackageDocs, et as generateIssueIndex, f as resolvePackageDocsWithAttempts, h as fetchGitDocs, i as fetchPkgDist, it as mapInsert, j as resolveEntryFiles, k as parseGitSkillInput, n as fetchNpmPackage, nt as SHARED_SKILLS_DIR, p as searchNpmPackages, r as fetchNpmRegistryMeta, rt as getSharedSkillsDir, s as readLocalDependencies, t as fetchLatestVersion, tt as isGhAvailable, u as resolveLocalPackageDocs, v as fetchReadmeContent, w as fetchLlmsTxt, y as isShallowGitDocs } from "./_chunks/npm.mjs";
 import "./sources/index.mjs";
 import { S as targets, _ as maxItems, a as getModelName, b as detectTargetAgent, c as computeSkillDirName, d as sanitizeName, f as unlinkSkillFromAgents, i as getModelLabel, n as createToolProgress, o as optimizeDocs, r as getAvailableModels, s as generateSkillMd, t as detectImportedPackages, u as linkSkillToAgents, v as maxLines, x as getAgentVersion, y as detectInstalledAgents } from "./_chunks/detect-imports.mjs";
 import "./agent/index.mjs";
@@ -563,7 +563,7 @@ async function getProjectState(cwd = process.cwd()) {
 	const matchedSkillNames = /* @__PURE__ */ new Set();
 	for (const [pkgName, version] of deps) {
 		const normalizedName = pkgName.replace(/^@/, "").replace(/\//g, "-");
-		const skill = skillByName.get(normalizedName) || skillByName.get(pkgName) || skillByPkgName.get(pkgName);
+		const skill = skillByName.get(`${normalizedName}-skilld`) || skillByName.get(normalizedName) || skillByName.get(pkgName) || skillByPkgName.get(pkgName);
 		if (!skill) missing.push(pkgName);
 		else {
 			matchedSkillNames.add(skill.name);
@@ -807,6 +807,7 @@ const RESOLVE_STEP_LABELS = {
 	"github-search": "GitHub search",
 	"readme": "README",
 	"llms.txt": "llms.txt",
+	"crawl": "website crawl",
 	"local": "node_modules"
 };
 function classifyCachedDoc(path) {
@@ -843,23 +844,33 @@ async function findRelatedSkills(packageName, skillsDir) {
 	}
 	return related.slice(0, 5);
 }
-function forceClearCache(packageName, version) {
+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
+		});
+	}
 }
-function linkAllReferences(skillDir, packageName, cwd, version, docsType, extraPackages, features) {
+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) linkCachedDir(skillDir, packageName, version, "issues");
-		if (f.discussions) linkCachedDir(skillDir, packageName, version, "discussions");
-		if (f.releases) linkCachedDir(skillDir, packageName, version, "releases");
+		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);
@@ -1014,6 +1025,27 @@ async function fetchAndCacheResources(opts) {
 				}
 			}
 		}
+		if (resolved.crawlUrl && cachedDocs.length === 0) {
+			onProgress("Crawling website");
+			const crawledDocs = await fetchCrawledDocs(resolved.crawlUrl, onProgress).catch(() => []);
+			if (crawledDocs.length > 0) {
+				for (const doc of crawledDocs) {
+					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);
@@ -1050,6 +1082,28 @@ async function fetchAndCacheResources(opts) {
 				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).catch(() => []);
+			if (crawledDocs.length > 0) {
+				for (const doc of crawledDocs) {
+					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);
@@ -1104,125 +1158,125 @@ async function fetchAndCacheResources(opts) {
 			}
 		}
 	}
+	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 = join(cacheDir, "issues");
-	if (features.issues && resolved.repoUrl && isGhAvailable() && !existsSync(issuesDir)) {
-		const gh = parseGitHubUrl(resolved.repoUrl);
-		if (gh) {
-			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`);
-				writeToCache(packageName, version, issues.map((issue) => ({
-					path: `issues/issue-${issue.number}.md`,
-					content: formatIssueAsMarkdown(issue)
-				})));
-				writeToCache(packageName, version, [{
-					path: "issues/_INDEX.md",
-					content: generateIssueIndex(issues)
-				}]);
-				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
-					}
-				});
-			}
+	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
+				}
+			});
 		}
 	}
-	const discussionsDir = join(cacheDir, "discussions");
-	if (features.discussions && resolved.repoUrl && isGhAvailable() && !existsSync(discussionsDir)) {
-		const gh = parseGitHubUrl(resolved.repoUrl);
-		if (gh) {
-			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`);
-				writeToCache(packageName, version, discussions.map((d) => ({
-					path: `discussions/discussion-${d.number}.md`,
-					content: formatDiscussionAsMarkdown(d)
-				})));
-				writeToCache(packageName, version, [{
-					path: "discussions/_INDEX.md",
-					content: generateDiscussionIndex(discussions)
-				}]);
-				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.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
+				}
+			});
 		}
 	}
-	const releasesPath = join(cacheDir, "releases");
-	if (features.releases && resolved.repoUrl && isGhAvailable() && !existsSync(releasesPath)) {
-		const gh = parseGitHubUrl(resolved.repoUrl);
-		if (gh) {
-			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 (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"
+				}
 			});
-			if (allDocs.length > 0) {
-				onProgress(`Caching ${allDocs.length} releases`);
-				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 {
@@ -1232,7 +1286,8 @@ async function fetchAndCacheResources(opts) {
 		hasIssues: features.issues && existsSync(issuesDir),
 		hasDiscussions: features.discussions && existsSync(discussionsDir),
 		hasReleases: features.releases && existsSync(releasesPath),
-		warnings
+		warnings,
+		repoInfo
 	};
 }
 async function indexResources(opts) {
@@ -1268,14 +1323,15 @@ async function indexResources(opts) {
 		}
 	});
 }
-function ejectReferences(skillDir, packageName, cwd, version, docsType, features) {
+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(cacheDir, refsDir, "issues");
-	if (f.discussions) copyCachedSubdir(cacheDir, refsDir, "discussions");
-	if (f.releases) copyCachedSubdir(cacheDir, refsDir, "releases");
+	if (f.issues) copyCachedSubdir(repoDir, refsDir, "issues");
+	if (f.discussions) copyCachedSubdir(repoDir, refsDir, "discussions");
+	if (f.releases) copyCachedSubdir(repoDir, refsDir, "releases");
 }
 function copyCachedSubdir(cacheDir, refsDir, subdir) {
 	const srcDir = join(cacheDir, subdir);
@@ -1374,7 +1430,7 @@ async function selectModel(skipPrompt) {
 }
 const DEFAULT_SECTIONS = ["best-practices", "api-changes"];
 async function selectSkillSections(message = "Generate SKILL.md with LLM") {
-	p.log.info("More sections = less budget each. Fewer sections = deeper coverage.");
+	p.log.info("Budgets adapt to package release density.");
 	const selected = await p.multiselect({
 		message,
 		options: [
@@ -1411,10 +1467,10 @@ async function selectSkillSections(message = "Generate SKILL.md with LLM") {
 		const budgetLines = [];
 		for (const s of sections) switch (s) {
 			case "api-changes":
-				budgetLines.push(`  API changes     ≤${maxLines(50, 80, n)} lines, ${maxItems(6, 12, n)} items`);
+				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  ≤${maxLines(80, 150, n)} lines, ${maxItems(4, 10, n)} items`);
+				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`);
@@ -1909,7 +1965,7 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 	if (useCache) update(packageName, "downloading", "Using cache", versionKey);
 	else update(packageName, "downloading", config.force ? "Re-fetching docs..." : "Fetching docs...", versionKey);
 	const baseDir = resolveBaseDir(cwd, config.agent, config.global);
-	const skillDirName = computeSkillDirName(packageName, resolved.repoUrl);
+	const skillDirName = computeSkillDirName(packageName);
 	const skillDir = join(baseDir, skillDirName);
 	mkdirSync(skillDir, { recursive: true });
 	const features = readConfig().features ?? defaultFeatures;
@@ -1922,7 +1978,7 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 		onProgress: (msg) => update(packageName, "downloading", msg, versionKey)
 	});
 	update(packageName, "downloading", "Linking references...", versionKey);
-	linkAllReferences(skillDir, packageName, cwd, version, resources.docsType, void 0, features);
+	linkAllReferences(skillDir, packageName, cwd, version, resources.docsType, void 0, features, resources.repoInfo);
 	if (features.search) {
 		update(packageName, "embedding", "Indexing docs", versionKey);
 		await indexResources({
@@ -2307,7 +2363,7 @@ async function syncSinglePackage(packageSpec, config) {
 	spin.stop(`Resolved ${packageName}@${useCache ? versionKey : version}${config.force ? " (force)" : useCache ? " (cached)" : ""}`);
 	ensureCacheDir();
 	const baseDir = resolveBaseDir(cwd, config.agent, config.global);
-	const skillDirName = config.name ? sanitizeName(config.name) : computeSkillDirName(packageName, resolved.repoUrl);
+	const skillDirName = config.name ? sanitizeName(config.name) : computeSkillDirName(packageName);
 	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];
@@ -2372,7 +2428,7 @@ async function syncSinglePackage(packageSpec, config) {
 	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);
+	linkAllReferences(skillDir, packageName, cwd, version, resources.docsType, void 0, features, resources.repoInfo);
 	if (features.search && !config.eject) {
 		const idxSpin = timedSpinner();
 		idxSpin.start("Creating search index");
@@ -2460,7 +2516,7 @@ async function syncSinglePackage(packageSpec, config) {
 			recursive: true,
 			force: true
 		});
-		ejectReferences(skillDir, packageName, cwd, version, resources.docsType, features);
+		ejectReferences(skillDir, packageName, cwd, version, resources.docsType, features, resources.repoInfo);
 	}
 	if (!isEject) {
 		const shared = !config.global && getSharedSkillsDir(cwd);
@@ -2748,21 +2804,26 @@ async function installCommand(opts) {
 				if (existsSync(docsLink)) unlinkSync(docsLink);
 				if (existsSync(cachedDocs)) symlinkSync(cachedDocs, docsLink, "junction");
 			}
+			const repoGh = info.repo ? parseGitHubUrl(`https://github.com/${info.repo}`) : null;
+			const repoCachePath = repoGh ? getRepoCacheDir(repoGh.owner, repoGh.repo) : null;
 			if (features.issues) {
 				const issuesLink = join(referencesPath, "issues");
-				const cachedIssues = join(globalCachePath, "issues");
+				const repoIssues = repoCachePath ? join(repoCachePath, "issues") : null;
+				const cachedIssues = repoIssues && existsSync(repoIssues) ? repoIssues : join(globalCachePath, "issues");
 				if (existsSync(issuesLink)) unlinkSync(issuesLink);
 				if (existsSync(cachedIssues)) symlinkSync(cachedIssues, issuesLink, "junction");
 			}
 			if (features.discussions) {
 				const discussionsLink = join(referencesPath, "discussions");
-				const cachedDiscussions = join(globalCachePath, "discussions");
+				const repoDiscussions = repoCachePath ? join(repoCachePath, "discussions") : null;
+				const cachedDiscussions = repoDiscussions && existsSync(repoDiscussions) ? repoDiscussions : join(globalCachePath, "discussions");
 				if (existsSync(discussionsLink)) unlinkSync(discussionsLink);
 				if (existsSync(cachedDiscussions)) symlinkSync(cachedDiscussions, discussionsLink, "junction");
 			}
 			if (features.releases) {
 				const releasesLink = join(referencesPath, "releases");
-				const cachedReleases = join(globalCachePath, "releases");
+				const repoReleases = repoCachePath ? join(repoCachePath, "releases") : null;
+				const cachedReleases = repoReleases && existsSync(repoReleases) ? repoReleases : join(globalCachePath, "releases");
 				if (existsSync(releasesLink)) unlinkSync(releasesLink);
 				if (existsSync(cachedReleases)) symlinkSync(cachedReleases, releasesLink, "junction");
 			}