skilld 0.1.2 → 0.2.0

package/dist/_chunks/releases.mjs

@@ -1,62 +1,267 @@
 import { a as getCacheDir } from "./config.mjs";
-import { join, resolve } from "node:path";
-import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, unlinkSync } from "node:fs";
-import { execSync } from "node:child_process";
+import { basename, dirname, join, resolve } from "pathe";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { globby } from "globby";
+import { ofetch } from "ofetch";
+import pLimit from "p-limit";
 import { Writable } from "node:stream";
 import { pathToFileURL } from "node:url";
+import { resolvePathSync } from "mlly";
 let _ghAvailable;
 function isGhAvailable() {
 	if (_ghAvailable !== void 0) return _ghAvailable;
-	try {
-		execSync("gh auth status", { stdio: "ignore" });
-		return _ghAvailable = true;
-	} catch {
-		return _ghAvailable = false;
-	}
+	const { status } = spawnSync("gh", ["auth", "status"], { stdio: "ignore" });
+	return _ghAvailable = status === 0;
 }
-async function fetchGitHubIssues(owner, repo, limit = 20) {
-	if (!isGhAvailable()) return [];
+const BOT_USERS = new Set([
+	"renovate[bot]",
+	"dependabot[bot]",
+	"renovate-bot",
+	"dependabot",
+	"github-actions[bot]"
+]);
+const NOISE_LABELS = new Set([
+	"duplicate",
+	"stale",
+	"invalid",
+	"wontfix",
+	"won't fix",
+	"spam",
+	"off-topic",
+	"needs triage",
+	"triage"
+]);
+const FEATURE_LABELS = new Set([
+	"enhancement",
+	"feature",
+	"feature request",
+	"feature-request",
+	"proposal",
+	"rfc",
+	"idea",
+	"suggestion"
+]);
+const BUG_LABELS = new Set([
+	"bug",
+	"defect",
+	"regression",
+	"error",
+	"crash",
+	"fix",
+	"confirmed",
+	"verified"
+]);
+const QUESTION_LABELS = new Set([
+	"question",
+	"help wanted",
+	"support",
+	"usage",
+	"how-to",
+	"help",
+	"assistance"
+]);
+const DOCS_LABELS = new Set([
+	"documentation",
+	"docs",
+	"doc",
+	"typo"
+]);
+function classifyIssue(labels) {
+	const lower = labels.map((l) => l.toLowerCase());
+	if (lower.some((l) => BUG_LABELS.has(l))) return "bug";
+	if (lower.some((l) => QUESTION_LABELS.has(l))) return "question";
+	if (lower.some((l) => DOCS_LABELS.has(l))) return "docs";
+	if (lower.some((l) => FEATURE_LABELS.has(l))) return "feature";
+	return "other";
+}
+function isNoiseIssue(issue) {
+	if (issue.labels.map((l) => l.toLowerCase()).some((l) => NOISE_LABELS.has(l))) return true;
+	if (issue.title.startsWith("☂️") || issue.title.startsWith("[META]") || issue.title.startsWith("[Tracking]")) return true;
+	return false;
+}
+function bodyLimit(reactions) {
+	if (reactions >= 10) return 2e3;
+	if (reactions >= 5) return 1500;
+	return 800;
+}
+function fetchIssuesByState(owner, repo, state, count) {
+	const fetchCount = Math.min(count * 3, 100);
+	const { stdout: result } = spawnSync("gh", [
+		"api",
+		`search/issues?q=${`repo:${owner}/${repo}+is:issue+is:${state}${state === "closed" ? `+closed:>${oneYearAgo()}` : ""}`}&sort=reactions&order=desc&per_page=${fetchCount}`,
+		"-q",
+		".items[] | {number, title, state, labels: [.labels[]?.name], body, createdAt: .created_at, url: .html_url, reactions: .reactions[\"+1\"], comments: .comments, user: .user.login, userType: .user.type}"
+	], {
+		encoding: "utf-8",
+		maxBuffer: 10 * 1024 * 1024
+	});
+	if (!result) return [];
+	return result.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line)).filter((issue) => !BOT_USERS.has(issue.user) && issue.userType !== "Bot").filter((issue) => !isNoiseIssue(issue)).map(({ user: _, userType: __, ...issue }) => ({
+		...issue,
+		type: classifyIssue(issue.labels),
+		topComments: []
+	})).sort((a, b) => (a.type === "feature" ? 1 : 0) - (b.type === "feature" ? 1 : 0)).slice(0, count);
+}
+function oneYearAgo() {
+	const d = /* @__PURE__ */ new Date();
+	d.setFullYear(d.getFullYear() - 1);
+	return d.toISOString().split("T")[0];
+}
+function enrichWithComments(owner, repo, issues, topN = 10) {
+	const worth = issues.filter((i) => i.comments > 0 && (i.type === "bug" || i.type === "question" || i.reactions >= 3)).sort((a, b) => b.reactions - a.reactions).slice(0, topN);
+	if (worth.length === 0) return;
+	const query = `query($owner: String!, $repo: String!) { repository(owner: $owner, name: $repo) { ${worth.map((issue, i) => `i${i}: issue(number: ${issue.number}) { comments(first: 3) { nodes { body author { login } reactions { totalCount } } } }`).join(" ")} } }`;
 	try {
-		const result = execSync(`gh api "repos/${owner}/${repo}/issues?per_page=${Math.min(limit * 3, 100)}&state=all" -q '.[] | {number, title, state, labels: [.labels[].name], body, createdAt: .created_at, url: .html_url, isPr: (.pull_request != null), user: .user.login, userType: .user.type}'`, {
+		const { stdout: result } = spawnSync("gh", [
+			"api",
+			"graphql",
+			"-f",
+			`query=${query}`,
+			"-f",
+			`owner=${owner}`,
+			"-f",
+			`repo=${repo}`
+		], {
 			encoding: "utf-8",
 			maxBuffer: 10 * 1024 * 1024
 		});
-		const BOT_USERS = new Set([
-			"renovate[bot]",
-			"dependabot[bot]",
-			"renovate-bot",
-			"dependabot",
-			"github-actions[bot]"
-		]);
-		return result.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line)).filter((issue) => !issue.isPr && !BOT_USERS.has(issue.user) && issue.userType !== "Bot").slice(0, limit).map(({ isPr: _, user: __, userType: ___, ...issue }) => issue);
+		if (!result) return;
+		const repo_ = JSON.parse(result)?.data?.repository;
+		if (!repo_) return;
+		for (let i = 0; i < worth.length; i++) {
+			const nodes = repo_[`i${i}`]?.comments?.nodes;
+			if (!Array.isArray(nodes)) continue;
+			worth[i].topComments = nodes.filter((c) => c.author && !BOT_USERS.has(c.author.login)).map((c) => ({
+				body: c.body || "",
+				author: c.author.login,
+				reactions: c.reactions?.totalCount || 0
+			}));
+		}
+	} catch {}
+}
+async function fetchGitHubIssues(owner, repo, limit = 30) {
+	if (!isGhAvailable()) return [];
+	const openCount = Math.ceil(limit * .75);
+	const closedCount = limit - openCount;
+	try {
+		const open = fetchIssuesByState(owner, repo, "open", openCount);
+		const closed = fetchIssuesByState(owner, repo, "closed", closedCount);
+		const all = [...open, ...closed];
+		enrichWithComments(owner, repo, all);
+		return all;
 	} catch {
 		return [];
 	}
 }
-function formatIssuesAsMarkdown(issues) {
-	if (issues.length === 0) return "";
-	const lines = ["# Recent Issues\n"];
-	for (const issue of issues) {
-		const labels = issue.labels.length > 0 ? ` [${issue.labels.join(", ")}]` : "";
-		lines.push(`## #${issue.number}: ${issue.title}${labels}`);
-		lines.push(`State: ${issue.state} | Created: ${issue.createdAt.split("T")[0]}`);
-		lines.push(`URL: ${issue.url}\n`);
-		if (issue.body) {
-			const body = issue.body.length > 500 ? `${issue.body.slice(0, 500)}...` : issue.body;
-			lines.push(body);
+function formatIssueAsMarkdown(issue) {
+	const limit = bodyLimit(issue.reactions);
+	const fm = [
+		"---",
+		`number: ${issue.number}`,
+		`title: "${issue.title.replace(/"/g, "\\\"")}"`,
+		`type: ${issue.type}`,
+		`state: ${issue.state}`,
+		`created: ${issue.createdAt.split("T")[0]}`,
+		`url: ${issue.url}`,
+		`reactions: ${issue.reactions}`,
+		`comments: ${issue.comments}`
+	];
+	if (issue.labels.length > 0) fm.push(`labels: [${issue.labels.join(", ")}]`);
+	fm.push("---");
+	const lines = [
+		fm.join("\n"),
+		"",
+		`# ${issue.title}`
+	];
+	if (issue.body) {
+		const body = issue.body.length > limit ? `${issue.body.slice(0, limit)}...` : issue.body;
+		lines.push("", body);
+	}
+	if (issue.topComments.length > 0) {
+		lines.push("", "---", "", "## Top Comments");
+		for (const c of issue.topComments) {
+			const reactions = c.reactions > 0 ? ` (+${c.reactions})` : "";
+			const commentBody = c.body.length > 600 ? `${c.body.slice(0, 600)}...` : c.body;
+			lines.push("", `**@${c.author}**${reactions}:`, "", commentBody);
 		}
-		lines.push("\n---\n");
 	}
 	return lines.join("\n");
 }
+function generateIssueIndex(issues) {
+	const byType = /* @__PURE__ */ new Map();
+	for (const issue of issues) {
+		const list = byType.get(issue.type) || [];
+		list.push(issue);
+		byType.set(issue.type, list);
+	}
+	const typeLabels = {
+		bug: "Bugs & Regressions",
+		question: "Questions & Usage Help",
+		docs: "Documentation",
+		feature: "Feature Requests",
+		other: "Other"
+	};
+	const typeOrder = [
+		"bug",
+		"question",
+		"docs",
+		"other",
+		"feature"
+	];
+	const sections = [
+		[
+			"---",
+			`total: ${issues.length}`,
+			`open: ${issues.filter((i) => i.state === "open").length}`,
+			`closed: ${issues.filter((i) => i.state !== "open").length}`,
+			"---"
+		].join("\n"),
+		"",
+		"# Issues Index",
+		""
+	];
+	for (const type of typeOrder) {
+		const group = byType.get(type);
+		if (!group?.length) continue;
+		sections.push(`## ${typeLabels[type]} (${group.length})`, "");
+		for (const issue of group) {
+			const reactions = issue.reactions > 0 ? ` (+${issue.reactions})` : "";
+			const state = issue.state === "open" ? "" : " [closed]";
+			sections.push(`- [#${issue.number}](./issue-${issue.number}.md): ${issue.title}${reactions}${state}`);
+		}
+		sections.push("");
+	}
+	return sections.join("\n");
+}
+const HIGH_VALUE_CATEGORIES = new Set([
+	"q&a",
+	"help",
+	"troubleshooting",
+	"support"
+]);
+const LOW_VALUE_CATEGORIES = new Set([
+	"show and tell",
+	"ideas",
+	"polls"
+]);
 async function fetchGitHubDiscussions(owner, repo, limit = 20) {
 	if (!isGhAvailable()) return [];
 	try {
-		const result = execSync(`gh api graphql -f query='${`query { repository(owner: "${owner}", name: "${repo}") { discussions(first: ${Math.min(limit * 2, 50)}, orderBy: {field: CREATED_AT, direction: DESC}) { nodes { number title body category { name } createdAt url upvoteCount comments { totalCount } author { login } } } } }`}'`, {
+		const { stdout: result } = spawnSync("gh", [
+			"api",
+			"graphql",
+			"-f",
+			`query=${`query($owner: String!, $repo: String!) { repository(owner: $owner, name: $repo) { discussions(first: ${Math.min(limit * 3, 80)}, orderBy: {field: CREATED_AT, direction: DESC}) { nodes { number title body category { name } createdAt url upvoteCount comments(first: 3) { totalCount nodes { body author { login } } } answer { body } author { login } } } } }`}`,
+			"-f",
+			`owner=${owner}`,
+			"-f",
+			`repo=${repo}`
+		], {
 			encoding: "utf-8",
 			maxBuffer: 10 * 1024 * 1024
 		});
+		if (!result) return [];
 		const nodes = JSON.parse(result)?.data?.repository?.discussions?.nodes;
 		if (!Array.isArray(nodes)) return [];
 		const BOT_USERS = new Set([
@@ -66,7 +271,10 @@ async function fetchGitHubDiscussions(owner, repo, limit = 20) {
 			"dependabot",
 			"github-actions[bot]"
 		]);
-		return nodes.filter((d) => d.author && !BOT_USERS.has(d.author.login)).slice(0, limit).map((d) => ({
+		return nodes.filter((d) => d.author && !BOT_USERS.has(d.author.login)).filter((d) => {
+			const cat = (d.category?.name || "").toLowerCase();
+			return !LOW_VALUE_CATEGORIES.has(cat);
+		}).map((d) => ({
 			number: d.number,
 			title: d.title,
 			body: d.body || "",
@@ -74,33 +282,93 @@ async function fetchGitHubDiscussions(owner, repo, limit = 20) {
 			createdAt: d.createdAt,
 			url: d.url,
 			upvoteCount: d.upvoteCount || 0,
-			comments: d.comments?.totalCount || 0
-		}));
+			comments: d.comments?.totalCount || 0,
+			answer: d.answer?.body || void 0,
+			topComments: (d.comments?.nodes || []).filter((c) => c.author && !BOT_USERS.has(c.author.login)).map((c) => ({
+				body: c.body || "",
+				author: c.author.login
+			}))
+		})).sort((a, b) => {
+			const aHigh = HIGH_VALUE_CATEGORIES.has(a.category.toLowerCase()) ? 1 : 0;
+			const bHigh = HIGH_VALUE_CATEGORIES.has(b.category.toLowerCase()) ? 1 : 0;
+			if (aHigh !== bHigh) return bHigh - aHigh;
+			return b.upvoteCount + b.comments - (a.upvoteCount + a.comments);
+		}).slice(0, limit);
 	} catch {
 		return [];
 	}
 }
-function formatDiscussionsAsMarkdown(discussions) {
-	if (discussions.length === 0) return "";
-	const lines = ["# Recent Discussions\n"];
-	for (const d of discussions) {
-		const meta = [
-			d.category && `Category: ${d.category}`,
-			`Created: ${d.createdAt.split("T")[0]}`,
-			d.upvoteCount > 0 && `Upvotes: ${d.upvoteCount}`,
-			d.comments > 0 && `Comments: ${d.comments}`
-		].filter(Boolean).join(" | ");
-		lines.push(`## #${d.number}: ${d.title}`);
-		lines.push(meta);
-		lines.push(`URL: ${d.url}\n`);
-		if (d.body) {
-			const body = d.body.length > 500 ? `${d.body.slice(0, 500)}...` : d.body;
-			lines.push(body);
+function formatDiscussionAsMarkdown(d) {
+	const fm = [
+		"---",
+		`number: ${d.number}`,
+		`title: "${d.title.replace(/"/g, "\\\"")}"`,
+		`category: ${d.category}`,
+		`created: ${d.createdAt.split("T")[0]}`,
+		`url: ${d.url}`,
+		`upvotes: ${d.upvoteCount}`,
+		`comments: ${d.comments}`,
+		`answered: ${!!d.answer}`,
+		"---"
+	];
+	const bodyLimit = d.upvoteCount >= 5 ? 1500 : 800;
+	const lines = [
+		fm.join("\n"),
+		"",
+		`# ${d.title}`
+	];
+	if (d.body) {
+		const body = d.body.length > bodyLimit ? `${d.body.slice(0, bodyLimit)}...` : d.body;
+		lines.push("", body);
+	}
+	if (d.answer) {
+		const answerLimit = 1e3;
+		const answer = d.answer.length > answerLimit ? `${d.answer.slice(0, answerLimit)}...` : d.answer;
+		lines.push("", "---", "", "## Accepted Answer", "", answer);
+	} else if (d.topComments.length > 0) {
+		lines.push("", "---", "", "## Top Comments");
+		for (const c of d.topComments) {
+			const commentBody = c.body.length > 600 ? `${c.body.slice(0, 600)}...` : c.body;
+			lines.push("", `**@${c.author}:**`, "", commentBody);
 		}
-		lines.push("\n---\n");
 	}
 	return lines.join("\n");
 }
+function generateDiscussionIndex(discussions) {
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const d of discussions) {
+		const cat = d.category || "Uncategorized";
+		const list = byCategory.get(cat) || [];
+		list.push(d);
+		byCategory.set(cat, list);
+	}
+	const answered = discussions.filter((d) => d.answer).length;
+	const sections = [
+		[
+			"---",
+			`total: ${discussions.length}`,
+			`answered: ${answered}`,
+			"---"
+		].join("\n"),
+		"",
+		"# Discussions Index",
+		""
+	];
+	const cats = [...byCategory.keys()].sort((a, b) => {
+		return (HIGH_VALUE_CATEGORIES.has(a.toLowerCase()) ? 0 : 1) - (HIGH_VALUE_CATEGORIES.has(b.toLowerCase()) ? 0 : 1) || a.localeCompare(b);
+	});
+	for (const cat of cats) {
+		const group = byCategory.get(cat);
+		sections.push(`## ${cat} (${group.length})`, "");
+		for (const d of group) {
+			const upvotes = d.upvoteCount > 0 ? ` (+${d.upvoteCount})` : "";
+			const answered = d.answer ? " [answered]" : "";
+			sections.push(`- [#${d.number}](./discussion-${d.number}.md): ${d.title}${upvotes}${answered}`);
+		}
+		sections.push("");
+	}
+	return sections.join("\n");
+}
 const SKIP_DIRS = [
 	"node_modules",
 	"_vendor",
@@ -153,29 +421,67 @@ async function resolveEntryFiles(packageDir) {
 	}
 	return entries;
 }
-const DOC_OVERRIDES = { vue: {
-	owner: "vuejs",
-	repo: "docs",
-	path: "src",
-	homepage: "https://vuejs.org"
-} };
+const DOC_OVERRIDES = {
+	"vue": {
+		owner: "vuejs",
+		repo: "docs",
+		path: "src",
+		homepage: "https://vuejs.org"
+	},
+	"tailwindcss": {
+		owner: "tailwindlabs",
+		repo: "tailwindcss.com",
+		path: "src/docs",
+		homepage: "https://tailwindcss.com"
+	},
+	"astro": {
+		owner: "withastro",
+		repo: "docs",
+		path: "src/content/docs/en",
+		homepage: "https://docs.astro.build"
+	},
+	"@vueuse/core": {
+		owner: "vueuse",
+		repo: "vueuse",
+		path: "packages"
+	}
+};
 function getDocOverride(packageName) {
 	return DOC_OVERRIDES[packageName];
 }
-const USER_AGENT = "skilld/1.0";
+const $fetch = ofetch.create({
+	retry: 3,
+	retryDelay: 500,
+	timeout: 15e3,
+	headers: { "User-Agent": "skilld/1.0" }
+});
 async function fetchText(url) {
-	const res = await fetch(url, { headers: { "User-Agent": USER_AGENT } }).catch(() => null);
-	if (!res?.ok) return null;
-	return res.text();
+	return $fetch(url, { responseType: "text" }).catch(() => null);
 }
 async function verifyUrl(url) {
-	const res = await fetch(url, {
-		method: "HEAD",
-		headers: { "User-Agent": USER_AGENT }
-	}).catch(() => null);
-	if (!res?.ok) return false;
+	const res = await $fetch.raw(url, { method: "HEAD" }).catch(() => null);
+	if (!res) return false;
 	return !(res.headers.get("content-type") || "").includes("text/html");
 }
+const USELESS_HOSTS = new Set([
+	"twitter.com",
+	"x.com",
+	"facebook.com",
+	"linkedin.com",
+	"youtube.com",
+	"instagram.com",
+	"npmjs.com",
+	"www.npmjs.com",
+	"yarnpkg.com"
+]);
+function isUselessDocsUrl(url) {
+	try {
+		const { hostname } = new URL(url);
+		return USELESS_HOSTS.has(hostname);
+	} catch {
+		return false;
+	}
+}
 function isGitHubRepoUrl(url) {
 	try {
 		const parsed = new URL(url);
@@ -185,7 +491,7 @@ function isGitHubRepoUrl(url) {
 	}
 }
 function parseGitHubUrl(url) {
-	const match = url.match(/github\.com\/([^/]+)\/([^/]+)/);
+	const match = url.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:[/#]|$)/);
 	if (!match) return null;
 	return {
 		owner: match[1],
@@ -193,14 +499,21 @@ function parseGitHubUrl(url) {
 	};
 }
 function normalizeRepoUrl(url) {
-	return url.replace(/^git\+/, "").replace(/\.git$/, "").replace(/^git:\/\//, "https://").replace(/^ssh:\/\/git@github\.com/, "https://github.com");
+	return url.replace(/^git\+/, "").replace(/#.*$/, "").replace(/\.git$/, "").replace(/^git:\/\//, "https://").replace(/^ssh:\/\/git@github\.com/, "https://github.com").replace(/^git@github\.com:/, "https://github.com/");
+}
+function extractBranchHint(url) {
+	const hash = url.indexOf("#");
+	if (hash === -1) return void 0;
+	const fragment = url.slice(hash + 1);
+	if (!fragment || fragment === "readme") return void 0;
+	return fragment;
 }
+const MIN_GIT_DOCS = 5;
+const isShallowGitDocs = (n) => n > 0 && n < MIN_GIT_DOCS;
 async function listFilesAtRef(owner, repo, ref) {
-	const res = await fetch(`https://ungh.cc/repos/${owner}/${repo}/files/${ref}`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return [];
-	return (await res.json().catch(() => null))?.files?.map((f) => f.path) ?? [];
+	return (await $fetch(`https://ungh.cc/repos/${owner}/${repo}/files/${ref}`).catch(() => null))?.files?.map((f) => f.path) ?? [];
 }
-async function findGitTag(owner, repo, version, packageName) {
+async function findGitTag(owner, repo, version, packageName, branchHint) {
 	const candidates = [`v${version}`, version];
 	if (packageName) candidates.push(`${packageName}@${version}`);
 	for (const tag of candidates) {
@@ -220,7 +533,8 @@ async function findGitTag(owner, repo, version, packageName) {
 			};
 		}
 	}
-	for (const branch of ["main", "master"]) {
+	const branches = branchHint ? [branchHint, ...["main", "master"].filter((b) => b !== branchHint)] : ["main", "master"];
+	for (const branch of branches) {
 		const files = await listFilesAtRef(owner, repo, branch);
 		if (files.length > 0) return {
 			ref: branch,
@@ -230,9 +544,7 @@ async function findGitTag(owner, repo, version, packageName) {
 	return null;
 }
 async function findLatestReleaseTag(owner, repo, packageName) {
-	const res = await fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return null;
-	const data = await res.json().catch(() => null);
+	const data = await $fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`).catch(() => null);
 	const prefix = `${packageName}@`;
 	return data?.releases?.find((r) => r.tag.startsWith(prefix))?.tag ?? null;
 }
@@ -337,7 +649,7 @@ function discoverDocFiles(allFiles) {
 async function listDocsAtRef(owner, repo, ref, pathPrefix = "docs/") {
 	return filterDocFiles(await listFilesAtRef(owner, repo, ref), pathPrefix);
 }
-async function fetchGitDocs(owner, repo, version, packageName) {
+async function fetchGitDocs(owner, repo, version, packageName, repoUrl) {
 	const override = packageName ? getDocOverride(packageName) : void 0;
 	if (override) {
 		const ref = override.ref || "main";
@@ -349,15 +661,17 @@ async function fetchGitDocs(owner, repo, version, packageName) {
 			files
 		};
 	}
-	const tag = await findGitTag(owner, repo, version, packageName);
+	const tag = await findGitTag(owner, repo, version, packageName, repoUrl ? extractBranchHint(repoUrl) : void 0);
 	if (!tag) return null;
 	let docs = filterDocFiles(tag.files, "docs/");
 	let docsPrefix;
+	let allFiles;
 	if (docs.length === 0) {
 		const discovered = discoverDocFiles(tag.files);
 		if (discovered) {
 			docs = discovered.files;
 			docsPrefix = discovered.prefix || void 0;
+			allFiles = tag.files;
 		}
 	}
 	if (docs.length === 0) return null;
@@ -365,51 +679,127 @@ async function fetchGitDocs(owner, repo, version, packageName) {
 		baseUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${tag.ref}`,
 		ref: tag.ref,
 		files: docs,
-		docsPrefix
+		docsPrefix,
+		allFiles
+	};
+}
+function normalizePath(p) {
+	return p.replace(/^\//, "").replace(/\.(?:md|mdx)$/, "");
+}
+function validateGitDocsWithLlms(llmsLinks, repoFiles) {
+	if (llmsLinks.length === 0) return {
+		isValid: true,
+		matchRatio: 1
+	};
+	const sample = llmsLinks.slice(0, 10);
+	const normalizedLinks = sample.map((link) => {
+		let path = link.url;
+		if (path.startsWith("http")) try {
+			path = new URL(path).pathname;
+		} catch {}
+		return normalizePath(path);
+	});
+	const repoNormalized = new Set(repoFiles.map(normalizePath));
+	let matches = 0;
+	for (const linkPath of normalizedLinks) for (const repoPath of repoNormalized) if (repoPath === linkPath || repoPath.endsWith(`/${linkPath}`)) {
+		matches++;
+		break;
+	}
+	const matchRatio = matches / sample.length;
+	return {
+		isValid: matchRatio >= .3,
+		matchRatio
 	};
 }
+async function verifyNpmRepo(owner, repo, packageName) {
+	const base = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD`;
+	const paths = [
+		"package.json",
+		`packages/${packageName.replace(/^@.*\//, "")}/package.json`,
+		`packages/${packageName.replace(/^@/, "").replace("/", "-")}/package.json`
+	];
+	for (const path of paths) {
+		const text = await fetchText(`${base}/${path}`);
+		if (!text) continue;
+		try {
+			if (JSON.parse(text).name === packageName) return true;
+		} catch {}
+	}
+	return false;
+}
 async function searchGitHubRepo(packageName) {
+	const shortName = packageName.replace(/^@.*\//, "");
+	for (const candidate of [packageName.replace(/^@/, "").replace("/", "/"), shortName]) {
+		if (!candidate.includes("/")) {
+			if ((await $fetch.raw(`https://ungh.cc/repos/${shortName}/${shortName}`).catch(() => null))?.ok) return `https://github.com/${shortName}/${shortName}`;
+			continue;
+		}
+		if ((await $fetch.raw(`https://ungh.cc/repos/${candidate}`).catch(() => null))?.ok) return `https://github.com/${candidate}`;
+	}
+	const searchTerm = packageName.replace(/^@/, "");
 	if (isGhAvailable()) try {
-		const json = execSync(`gh search repos "${packageName}" --json fullName --limit 5`, {
+		const { stdout: json } = spawnSync("gh", [
+			"search",
+			"repos",
+			searchTerm,
+			"--json",
+			"fullName",
+			"--limit",
+			"5"
+		], {
 			encoding: "utf-8",
 			timeout: 15e3
 		});
+		if (!json) throw new Error("no output");
 		const repos = JSON.parse(json);
-		const match = repos.find((r) => r.fullName.toLowerCase().endsWith(`/${packageName.toLowerCase()}`) || r.fullName.toLowerCase().endsWith(`/${packageName.replace(/^@.*\//, "").toLowerCase()}`));
+		const match = repos.find((r) => r.fullName.toLowerCase().endsWith(`/${packageName.toLowerCase()}`) || r.fullName.toLowerCase().endsWith(`/${shortName.toLowerCase()}`));
 		if (match) return `https://github.com/${match.fullName}`;
-		if (repos.length > 0) return `https://github.com/${repos[0].fullName}`;
+		for (const candidate of repos) {
+			const gh = parseGitHubUrl(`https://github.com/${candidate.fullName}`);
+			if (gh && await verifyNpmRepo(gh.owner, gh.repo, packageName)) return `https://github.com/${candidate.fullName}`;
+		}
 	} catch {}
-	const query = encodeURIComponent(`${packageName} in:name`);
-	const res = await fetch(`https://api.github.com/search/repositories?q=${query}&per_page=5`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return null;
-	const data = await res.json().catch(() => null);
+	const data = await $fetch(`https://api.github.com/search/repositories?q=${encodeURIComponent(`${searchTerm} in:name`)}&per_page=5`).catch(() => null);
 	if (!data?.items?.length) return null;
-	const match = data.items.find((r) => r.full_name.toLowerCase().endsWith(`/${packageName.toLowerCase()}`) || r.full_name.toLowerCase().endsWith(`/${packageName.replace(/^@.*\//, "").toLowerCase()}`));
-	return match ? `https://github.com/${match.full_name}` : `https://github.com/${data.items[0].full_name}`;
+	const match = data.items.find((r) => r.full_name.toLowerCase().endsWith(`/${packageName.toLowerCase()}`) || r.full_name.toLowerCase().endsWith(`/${shortName.toLowerCase()}`));
+	if (match) return `https://github.com/${match.full_name}`;
+	for (const candidate of data.items) {
+		const gh = parseGitHubUrl(`https://github.com/${candidate.full_name}`);
+		if (gh && await verifyNpmRepo(gh.owner, gh.repo, packageName)) return `https://github.com/${candidate.full_name}`;
+	}
+	return null;
 }
 async function fetchGitHubRepoMeta(owner, repo, packageName) {
 	const override = packageName ? getDocOverride(packageName) : void 0;
 	if (override?.homepage) return { homepage: override.homepage };
 	if (isGhAvailable()) try {
-		const json = execSync(`gh api "repos/${owner}/${repo}" -q '{homepage}'`, {
+		const { stdout: json } = spawnSync("gh", [
+			"api",
+			`repos/${owner}/${repo}`,
+			"-q",
+			"{homepage}"
+		], {
 			encoding: "utf-8",
 			timeout: 1e4
 		});
+		if (!json) throw new Error("no output");
 		const data = JSON.parse(json);
 		return data?.homepage ? { homepage: data.homepage } : null;
 	} catch {}
-	const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return null;
-	const data = await res.json().catch(() => null);
+	const data = await $fetch(`https://api.github.com/repos/${owner}/${repo}`).catch(() => null);
 	return data?.homepage ? { homepage: data.homepage } : null;
 }
 async function fetchReadme(owner, repo, subdir) {
 	const unghUrl = subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/main/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme`;
-	if ((await fetch(unghUrl, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null))?.ok) return `ungh://${owner}/${repo}${subdir ? `/${subdir}` : ""}`;
+	if ((await $fetch.raw(unghUrl).catch(() => null))?.ok) return `ungh://${owner}/${repo}${subdir ? `/${subdir}` : ""}`;
 	const basePath = subdir ? `${subdir}/` : "";
-	for (const branch of ["main", "master"]) for (const filename of ["README.md", "readme.md"]) {
+	for (const branch of ["main", "master"]) for (const filename of [
+		"README.md",
+		"Readme.md",
+		"readme.md"
+	]) {
 		const readmeUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${basePath}${filename}`;
-		if (await verifyUrl(readmeUrl)) return readmeUrl;
+		if ((await $fetch.raw(readmeUrl).catch(() => null))?.ok) return readmeUrl;
 	}
 	return null;
 }
@@ -426,10 +816,8 @@ async function fetchReadmeContent(url) {
 		const owner = parts[0];
 		const repo = parts[1];
 		const subdir = parts.slice(2).join("/");
-		const unghUrl = subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/main/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme`;
-		const res = await fetch(unghUrl, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-		if (!res?.ok) return null;
-		const text = await res.text();
+		const text = await $fetch(subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/main/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme`, { responseType: "text" }).catch(() => null);
+		if (!text) return null;
 		try {
 			const json = JSON.parse(text);
 			return json.markdown || json.file?.contents || null;
@@ -440,7 +828,7 @@ async function fetchReadmeContent(url) {
 	return fetchText(url);
 }
 async function fetchLlmsUrl(docsUrl) {
-	const llmsUrl = `${docsUrl.replace(/\/$/, "")}/llms.txt`;
+	const llmsUrl = `${new URL(docsUrl).origin}/llms.txt`;
 	if (await verifyUrl(llmsUrl)) return llmsUrl;
 	return null;
 }
@@ -468,19 +856,35 @@ function parseMarkdownLinks(content) {
 	}
 	return links;
 }
+function isSafeUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "https:") return false;
+		const host = parsed.hostname;
+		if (host === "localhost" || host === "127.0.0.1" || host === "::1") return false;
+		if (host === "169.254.169.254") return false;
+		if (/^(?:10\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.)/.test(host)) return false;
+		if (host.startsWith("[")) return false;
+		return true;
+	} catch {
+		return false;
+	}
+}
 async function downloadLlmsDocs(llmsContent, baseUrl, onProgress) {
-	const docs = [];
-	for (let i = 0; i < llmsContent.links.length; i++) {
-		const link = llmsContent.links[i];
-		onProgress?.(link.url, i, llmsContent.links.length);
-		const content = await fetchText(link.url.startsWith("http") ? link.url : `${baseUrl.replace(/\/$/, "")}${link.url.startsWith("/") ? "" : "/"}${link.url}`);
-		if (content && content.length > 100) docs.push({
+	const limit = pLimit(5);
+	let completed = 0;
+	return (await Promise.all(llmsContent.links.map((link) => limit(async () => {
+		const url = link.url.startsWith("http") ? link.url : `${baseUrl.replace(/\/$/, "")}${link.url.startsWith("/") ? "" : "/"}${link.url}`;
+		if (!isSafeUrl(url)) return null;
+		onProgress?.(link.url, completed++, llmsContent.links.length);
+		const content = await fetchText(url);
+		if (content && content.length > 100) return {
 			url: link.url,
 			title: link.title,
 			content
-		});
-	}
-	return docs;
+		};
+		return null;
+	})))).filter((d) => d !== null);
 }
 function normalizeLlmsLinks(content, baseUrl) {
 	let normalized = content;
@@ -506,16 +910,23 @@ function extractSections(content, patterns) {
 	if (sections.length === 0) return null;
 	return sections.join("\n\n---\n\n");
 }
+async function searchNpmPackages(query, size = 5) {
+	const data = await $fetch(`https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${size}`).catch(() => null);
+	if (!data?.objects?.length) return [];
+	return data.objects.map((o) => ({
+		name: o.package.name,
+		description: o.package.description,
+		version: o.package.version
+	}));
+}
 async function fetchNpmPackage(packageName) {
-	let res = await fetch(`https://unpkg.com/${packageName}/package.json`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) res = await fetch(`https://registry.npmjs.org/${packageName}/latest`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return null;
-	return res.json();
+	const data = await $fetch(`https://unpkg.com/${packageName}/package.json`).catch(() => null);
+	if (data) return data;
+	return $fetch(`https://registry.npmjs.org/${packageName}/latest`).catch(() => null);
 }
 async function fetchNpmRegistryMeta(packageName, version) {
-	const res = await fetch(`https://registry.npmjs.org/${packageName}`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return {};
-	const data = await res.json();
+	const data = await $fetch(`https://registry.npmjs.org/${packageName}`).catch(() => null);
+	if (!data) return {};
 	const distTags = data["dist-tags"] ? Object.fromEntries(Object.entries(data["dist-tags"]).map(([tag, ver]) => [tag, {
 		version: ver,
 		releasedAt: data.time?.[ver]
@@ -560,24 +971,34 @@ async function resolvePackageDocsWithAttempts(packageName, options = {}) {
 		dependencies: pkg.dependencies,
 		distTags: registryMeta.distTags
 	};
+	let gitDocsAllFiles;
 	let subdir;
+	let rawRepoUrl;
 	if (typeof pkg.repository === "object" && pkg.repository?.url) {
-		result.repoUrl = normalizeRepoUrl(pkg.repository.url);
+		rawRepoUrl = pkg.repository.url;
+		const normalized = normalizeRepoUrl(rawRepoUrl);
+		if (!normalized.includes("://") && normalized.includes("/") && !normalized.includes(":")) result.repoUrl = `https://github.com/${normalized}`;
+		else result.repoUrl = normalized;
 		subdir = pkg.repository.directory;
-	} else if (typeof pkg.repository === "string") {
+	} else if (typeof pkg.repository === "string") if (pkg.repository.includes("://")) {
+		const gh = parseGitHubUrl(pkg.repository);
+		if (gh) result.repoUrl = `https://github.com/${gh.owner}/${gh.repo}`;
+	} else {
 		const repo = pkg.repository.replace(/^github:/, "");
 		if (repo.includes("/") && !repo.includes(":")) result.repoUrl = `https://github.com/${repo}`;
 	}
+	if (pkg.homepage && !isGitHubRepoUrl(pkg.homepage) && !isUselessDocsUrl(pkg.homepage)) result.docsUrl = pkg.homepage;
 	if (result.repoUrl?.includes("github.com")) {
 		const gh = parseGitHubUrl(result.repoUrl);
 		if (gh) {
 			const targetVersion = options.version || pkg.version;
 			if (targetVersion) {
 				onProgress?.("github-docs");
-				const gitDocs = await fetchGitDocs(gh.owner, gh.repo, targetVersion, pkg.name);
+				const gitDocs = await fetchGitDocs(gh.owner, gh.repo, targetVersion, pkg.name, rawRepoUrl);
 				if (gitDocs) {
 					result.gitDocsUrl = gitDocs.baseUrl;
 					result.gitRef = gitDocs.ref;
+					gitDocsAllFiles = gitDocs.allFiles;
 					attempts.push({
 						source: "github-docs",
 						url: gitDocs.baseUrl,
@@ -594,7 +1015,7 @@ async function resolvePackageDocsWithAttempts(packageName, options = {}) {
 			if (!result.docsUrl) {
 				onProgress?.("github-meta");
 				const repoMeta = await fetchGitHubRepoMeta(gh.owner, gh.repo, pkg.name);
-				if (repoMeta?.homepage) {
+				if (repoMeta?.homepage && !isUselessDocsUrl(repoMeta.homepage)) {
 					result.docsUrl = repoMeta.homepage;
 					attempts.push({
 						source: "github-meta",
@@ -645,6 +1066,7 @@ async function resolvePackageDocsWithAttempts(packageName, options = {}) {
 					if (gitDocs) {
 						result.gitDocsUrl = gitDocs.baseUrl;
 						result.gitRef = gitDocs.ref;
+						gitDocsAllFiles = gitDocs.allFiles;
 						attempts.push({
 							source: "github-docs",
 							url: gitDocs.baseUrl,
@@ -656,7 +1078,7 @@ async function resolvePackageDocsWithAttempts(packageName, options = {}) {
 				if (!result.docsUrl) {
 					onProgress?.("github-meta");
 					const repoMeta = await fetchGitHubRepoMeta(gh.owner, gh.repo, pkg.name);
-					if (repoMeta?.homepage) result.docsUrl = repoMeta.homepage;
+					if (repoMeta?.homepage && !isUselessDocsUrl(repoMeta.homepage)) result.docsUrl = repoMeta.homepage;
 				}
 				onProgress?.("readme");
 				const readmeUrl = await fetchReadme(gh.owner, gh.repo);
@@ -668,7 +1090,6 @@ async function resolvePackageDocsWithAttempts(packageName, options = {}) {
 			message: "No repository URL in package.json and GitHub search found no match"
 		});
 	}
-	if (pkg.homepage && !isGitHubRepoUrl(pkg.homepage)) result.docsUrl = pkg.homepage;
 	if (result.docsUrl) {
 		onProgress?.("llms.txt");
 		const llmsUrl = await fetchLlmsUrl(result.docsUrl);
@@ -681,28 +1102,42 @@ async function resolvePackageDocsWithAttempts(packageName, options = {}) {
 			});
 		} else attempts.push({
 			source: "llms.txt",
-			url: `${result.docsUrl}/llms.txt`,
+			url: `${new URL(result.docsUrl).origin}/llms.txt`,
 			status: "not-found",
 			message: "No llms.txt at docs URL"
 		});
 	}
-	if (!result.docsUrl && !result.llmsUrl && !result.readmeUrl && !result.gitDocsUrl && options.cwd) {
-		onProgress?.("local");
-		const pkgDir = join(options.cwd, "node_modules", packageName);
-		for (const filename of ["README.md", "readme.md"]) {
-			const readmePath = join(pkgDir, filename);
-			if (existsSync(readmePath)) {
-				result.readmeUrl = pathToFileURL(readmePath).href;
+	if (result.gitDocsUrl && result.llmsUrl && gitDocsAllFiles) {
+		const llmsContent = await fetchLlmsTxt(result.llmsUrl);
+		if (llmsContent && llmsContent.links.length > 0) {
+			const validation = validateGitDocsWithLlms(llmsContent.links, gitDocsAllFiles);
+			if (!validation.isValid) {
 				attempts.push({
-					source: "readme",
-					url: readmePath,
-					status: "success",
-					message: "Found local readme in node_modules"
+					source: "github-docs",
+					url: result.gitDocsUrl,
+					status: "not-found",
+					message: `Heuristic git docs don't match llms.txt links (${Math.round(validation.matchRatio * 100)}% match), preferring llms.txt`
 				});
-				break;
+				result.gitDocsUrl = void 0;
+				result.gitRef = void 0;
 			}
 		}
 	}
+	if (!result.docsUrl && !result.llmsUrl && !result.readmeUrl && !result.gitDocsUrl && options.cwd) {
+		onProgress?.("local");
+		const pkgDir = join(options.cwd, "node_modules", packageName);
+		const readmeFile = existsSync(pkgDir) && readdirSync(pkgDir).find((f) => /^readme\.md$/i.test(f));
+		if (readmeFile) {
+			const readmePath = join(pkgDir, readmeFile);
+			result.readmeUrl = pathToFileURL(readmePath).href;
+			attempts.push({
+				source: "readme",
+				url: readmePath,
+				status: "success",
+				message: "Found local readme in node_modules"
+			});
+		}
+	}
 	if (!result.docsUrl && !result.llmsUrl && !result.readmeUrl && !result.gitDocsUrl) return {
 		package: null,
 		attempts
@@ -724,27 +1159,46 @@ function parseVersionSpecifier(name, version, cwd) {
 		}
 		return null;
 	}
-	if (version.startsWith("workspace:")) return {
-		name,
-		version: version.slice(10).replace(/^[\^~*]/, "") || "*"
-	};
 	if (version.startsWith("npm:")) {
 		const specifier = version.slice(4);
 		const atIndex = specifier.startsWith("@") ? specifier.indexOf("@", 1) : specifier.indexOf("@");
-		if (atIndex > 0) return {
-			name: specifier.slice(0, atIndex),
-			version: specifier.slice(atIndex + 1)
-		};
+		const realName = atIndex > 0 ? specifier.slice(0, atIndex) : specifier;
 		return {
-			name: specifier,
-			version: "*"
+			name: realName,
+			version: resolveInstalledVersion(realName, cwd) || "*"
 		};
 	}
 	if (version.startsWith("file:") || version.startsWith("git:") || version.startsWith("git+")) return null;
-	return {
+	const installed = resolveInstalledVersion(name, cwd);
+	if (installed) return {
+		name,
+		version: installed
+	};
+	if (/^[\^~>=<\d]/.test(version)) return {
 		name,
 		version: version.replace(/^[\^~>=<]/, "")
 	};
+	if (version.startsWith("catalog:") || version.startsWith("workspace:")) return {
+		name,
+		version: "*"
+	};
+	return null;
+}
+function resolveInstalledVersion(name, cwd) {
+	try {
+		const resolved = resolvePathSync(`${name}/package.json`, { url: cwd });
+		return JSON.parse(readFileSync(resolved, "utf-8")).version || null;
+	} catch {
+		try {
+			let dir = dirname(resolvePathSync(name, { url: cwd }));
+			while (dir && basename(dir) !== "node_modules") {
+				const pkgPath = join(dir, "package.json");
+				if (existsSync(pkgPath)) return JSON.parse(readFileSync(pkgPath, "utf-8")).version || null;
+				dir = dirname(dir);
+			}
+		} catch {}
+		return null;
+	}
 }
 async function readLocalDependencies(cwd) {
 	const pkgPath = join(cwd, "package.json");
@@ -805,8 +1259,8 @@ async function resolveLocalPackageDocs(localPath) {
 		}
 	}
 	if (!result.readmeUrl && !result.gitDocsUrl) {
-		const localReadme = join(localPath, "README.md");
-		if (existsSync(localReadme)) result.readmeUrl = pathToFileURL(localReadme).href;
+		const readmeFile = readdirSync(localPath).find((f) => /^readme\.md$/i.test(f));
+		if (readmeFile) result.readmeUrl = pathToFileURL(join(localPath, readmeFile)).href;
 	}
 	if (!result.readmeUrl && !result.gitDocsUrl) return null;
 	return result;
@@ -815,9 +1269,9 @@ async function fetchPkgDist(name, version) {
 	const cacheDir = getCacheDir(name, version);
 	const pkgDir = join(cacheDir, "pkg");
 	if (existsSync(join(pkgDir, "package.json"))) return pkgDir;
-	const res = await fetch(`https://registry.npmjs.org/${name}/${version}`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return null;
-	const tarballUrl = (await res.json()).dist?.tarball;
+	const data = await $fetch(`https://registry.npmjs.org/${name}/${version}`).catch(() => null);
+	if (!data) return null;
+	const tarballUrl = data.dist?.tarball;
 	if (!tarballUrl) return null;
 	const tarballRes = await fetch(tarballUrl, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
 	if (!tarballRes?.ok || !tarballRes.body) return null;
@@ -845,9 +1299,14 @@ async function fetchPkgDist(name, version) {
 		}
 		pump();
 	});
-	try {
-		execSync(`tar xzf "${tmpTarball}" --strip-components=1 -C "${pkgDir}"`, { stdio: "ignore" });
-	} catch {
+	const { status } = spawnSync("tar", [
+		"xzf",
+		tmpTarball,
+		"--strip-components=1",
+		"-C",
+		pkgDir
+	], { stdio: "ignore" });
+	if (status !== 0) {
 		rmSync(pkgDir, {
 			recursive: true,
 			force: true
@@ -859,9 +1318,7 @@ async function fetchPkgDist(name, version) {
 	return pkgDir;
 }
 async function fetchLatestVersion(packageName) {
-	const res = await fetch(`https://unpkg.com/${packageName}/package.json`, { headers: { "User-Agent": "skilld/1.0" } }).catch(() => null);
-	if (!res?.ok) return null;
-	return (await res.json()).version || null;
+	return (await $fetch(`https://unpkg.com/${packageName}/package.json`).catch(() => null))?.version || null;
 }
 function getInstalledSkillVersion(skillDir) {
 	const skillPath = join(skillDir, "SKILL.md");
@@ -901,7 +1358,12 @@ function compareSemver(a, b) {
 }
 function fetchReleasesViaGh(owner, repo) {
 	try {
-		const json = execSync(`gh api "repos/${owner}/${repo}/releases?per_page=100" --jq '[.[] | {id: .id, tag: .tag_name, name: .name, prerelease: .prerelease, createdAt: .created_at, publishedAt: .published_at, markdown: .body}]'`, {
+		const { stdout: json } = spawnSync("gh", [
+			"api",
+			`repos/${owner}/${repo}/releases?per_page=100`,
+			"--jq",
+			"[.[] | {id: .id, tag: .tag_name, name: .name, prerelease: .prerelease, createdAt: .created_at, publishedAt: .published_at, markdown: .body}]"
+		], {
 			encoding: "utf-8",
 			timeout: 15e3,
 			stdio: [
@@ -910,18 +1372,14 @@ function fetchReleasesViaGh(owner, repo) {
 				"ignore"
 			]
 		});
+		if (!json) return [];
 		return JSON.parse(json);
 	} catch {
 		return [];
 	}
 }
 async function fetchReleasesViaUngh(owner, repo) {
-	const res = await fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`, {
-		headers: { "User-Agent": "skilld/1.0" },
-		signal: AbortSignal.timeout(15e3)
-	}).catch(() => null);
-	if (!res?.ok) return [];
-	return (await res.json().catch(() => null))?.releases ?? [];
+	return (await $fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`, { signal: AbortSignal.timeout(15e3) }).catch(() => null))?.releases ?? [];
 }
 async function fetchAllReleases(owner, repo) {
 	if (isGhAvailable()) {
@@ -947,9 +1405,48 @@ function selectReleases(releases, packageName) {
 		return compareSemver(parseSemver(verB), parseSemver(verA));
 	}).slice(0, 20);
 }
-function formatRelease(release) {
+function formatRelease(release, packageName) {
 	const date = (release.publishedAt || release.createdAt).split("T")[0];
-	return `# ${release.name || release.tag}\n\nTag: ${release.tag} | Published: ${date}\n\n${release.markdown}`;
+	const version = extractVersion(release.tag, packageName) || release.tag;
+	const fm = [
+		"---",
+		`tag: ${release.tag}`,
+		`version: ${version}`,
+		`published: ${date}`
+	];
+	if (release.name && release.name !== release.tag) fm.push(`name: "${release.name.replace(/"/g, "\\\"")}"`);
+	fm.push("---");
+	return `${fm.join("\n")}\n\n# ${release.name || release.tag}\n\n${release.markdown}`;
+}
+function generateReleaseIndex(releases, packageName) {
+	const lines = [
+		[
+			"---",
+			`total: ${releases.length}`,
+			`latest: ${releases[0]?.tag || "unknown"}`,
+			"---"
+		].join("\n"),
+		"",
+		"# Releases Index",
+		""
+	];
+	for (const r of releases) {
+		const date = (r.publishedAt || r.createdAt).split("T")[0];
+		const filename = r.tag.includes("@") || r.tag.startsWith("v") ? r.tag : `v${r.tag}`;
+		const sv = parseSemver(extractVersion(r.tag, packageName) || r.tag);
+		const label = sv?.patch === 0 && sv.minor === 0 ? " **[MAJOR]**" : sv?.patch === 0 ? " **[MINOR]**" : "";
+		lines.push(`- [${r.tag}](./${filename}.md): ${r.name || r.tag} (${date})${label}`);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+function isChangelogRedirectPattern(releases) {
+	const sample = releases.slice(0, 3);
+	if (sample.length === 0) return false;
+	return sample.every((r) => {
+		const body = (r.markdown || "").trim();
+		return body.length < 500 && /changelog\.md/i.test(body);
+	});
 }
 async function fetchChangelog(owner, repo, ref) {
 	for (const filename of [
@@ -957,23 +1454,36 @@ async function fetchChangelog(owner, repo, ref) {
 		"changelog.md",
 		"CHANGES.md"
 	]) {
-		const url = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${filename}`;
-		const res = await fetch(url, {
-			headers: { "User-Agent": "skilld/1.0" },
+		const content = await $fetch(`https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${filename}`, {
+			responseType: "text",
 			signal: AbortSignal.timeout(1e4)
 		}).catch(() => null);
-		if (res?.ok) return res.text();
+		if (content) return content;
 	}
 	return null;
 }
 async function fetchReleaseNotes(owner, repo, installedVersion, gitRef, packageName) {
 	const selected = selectReleases(await fetchAllReleases(owner, repo), packageName);
-	if (selected.length > 0) return selected.map((r) => {
-		return {
-			path: `releases/${r.tag.includes("@") || r.tag.startsWith("v") ? r.tag : `v${r.tag}`}.md`,
-			content: formatRelease(r)
-		};
-	});
+	if (selected.length > 0) {
+		if (isChangelogRedirectPattern(selected)) {
+			const changelog = await fetchChangelog(owner, repo, gitRef || selected[0].tag);
+			if (changelog) return [{
+				path: "CHANGELOG.md",
+				content: changelog
+			}];
+		}
+		const docs = selected.map((r) => {
+			return {
+				path: `releases/${r.tag.includes("@") || r.tag.startsWith("v") ? r.tag : `v${r.tag}`}.md`,
+				content: formatRelease(r, packageName)
+			};
+		});
+		docs.push({
+			path: "releases/_INDEX.md",
+			content: generateReleaseIndex(selected, packageName)
+		});
+		return docs;
+	}
 	const changelog = await fetchChangelog(owner, repo, gitRef || "main");
 	if (!changelog) return [];
 	return [{
@@ -981,6 +1491,6 @@ async function fetchReleaseNotes(owner, repo, installedVersion, gitRef, packageN
 		content: changelog
 	}];
 }
-export { resolveEntryFiles as A, fetchText as C, verifyUrl as D, parseGitHubUrl as E, isGhAvailable as F, formatDiscussionsAsMarkdown as M, fetchGitHubIssues as N, DOC_OVERRIDES as O, formatIssuesAsMarkdown as P, fetchReadmeContent as S, normalizeRepoUrl as T, normalizeLlmsLinks as _, fetchPkgDist as a, fetchGitHubRepoMeta as b, readLocalDependencies as c, resolvePackageDocs as d, resolvePackageDocsWithAttempts as f, fetchLlmsUrl as g, fetchLlmsTxt as h, fetchNpmRegistryMeta as i, fetchGitHubDiscussions as j, getDocOverride as k, readLocalPackageInfo as l, extractSections as m, fetchLatestVersion as n, getInstalledSkillVersion as o, downloadLlmsDocs as p, fetchNpmPackage as r, parseVersionSpecifier as s, fetchReleaseNotes as t, resolveLocalPackageDocs as u, parseMarkdownLinks as v, isGitHubRepoUrl as w, fetchReadme as x, fetchGitDocs as y };
+export { extractBranchHint as A, formatDiscussionAsMarkdown as B, fetchGitDocs as C, isShallowGitDocs as D, fetchReadmeContent as E, verifyUrl as F, isGhAvailable as G, fetchGitHubIssues as H, DOC_OVERRIDES as I, getDocOverride as L, isGitHubRepoUrl as M, normalizeRepoUrl as N, validateGitDocsWithLlms as O, parseGitHubUrl as P, resolveEntryFiles as R, MIN_GIT_DOCS as S, fetchReadme as T, formatIssueAsMarkdown as U, generateDiscussionIndex as V, generateIssueIndex as W, extractSections as _, fetchNpmRegistryMeta as a, normalizeLlmsLinks as b, parseVersionSpecifier as c, resolveInstalledVersion as d, resolveLocalPackageDocs as f, downloadLlmsDocs as g, searchNpmPackages as h, fetchNpmPackage as i, fetchText as j, $fetch as k, readLocalDependencies as l, resolvePackageDocsWithAttempts as m, generateReleaseIndex as n, fetchPkgDist as o, resolvePackageDocs as p, fetchLatestVersion as r, getInstalledSkillVersion as s, fetchReleaseNotes as t, readLocalPackageInfo as u, fetchLlmsTxt as v, fetchGitHubRepoMeta as w, parseMarkdownLinks as x, fetchLlmsUrl as y, fetchGitHubDiscussions as z };
 
 //# sourceMappingURL=releases.mjs.map