skilld 1.7.4 → 2.0.0

package/dist/_chunks/semver.mjs

@@ -1,4 +1,2758 @@
+import { D as getCrawlUrl, E as getBlogPreset, O as getDocOverride } from "./prompts.mjs";
+import { a as GIT_PROTOCOL_PREFIX_RE, c as NPM_SCOPE_PREFIX_RE, g as V_PREFIX_RE, h as VERSION_RANGE_PREFIX_RE, i as GIT_PLUS_PREFIX_RE, l as NPM_SCOPE_WITH_SLASH_RE, m as TRAILING_SLASH_RE, o as GIT_SUFFIX_RE, r as GITHUB_SSH_URL_PREFIX_RE, s as LEADING_SLASH_RE, u as README_FILENAME_RE } from "./regex.mjs";
+import { t as yamlEscape } from "./yaml.mjs";
+import { s as getCacheDir } from "./prepare.mjs";
+import { i as readPackageJsonSafe } from "./package-json.mjs";
+import "./cache.mjs";
+import { t as mapInsert } from "./map.mjs";
+import { i as parseFrontmatter, n as extractLinks, r as extractTitle, t as extractDescription } from "./markdown.mjs";
+import { createRequire } from "node:module";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import pLimit from "p-limit";
+import { basename, dirname, join, resolve } from "pathe";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { glob } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { htmlToMarkdown } from "mdream";
+import { ofetch } from "ofetch";
+import { crawlAndGenerate } from "@mdream/crawl";
+import { downloadTemplate } from "giget";
+import { Writable } from "node:stream";
 import { diff, gt, valid } from "semver";
+const STATIC_REGEX_1$9 = /```[\s\S]*?```/;
+const STATIC_REGEX_2$4 = /`[^`]+`/;
+const BOT_USERS = new Set([
+	"renovate[bot]",
+	"dependabot[bot]",
+	"renovate-bot",
+	"dependabot",
+	"github-actions[bot]"
+]);
+const isoDate = (iso) => iso.split("T")[0];
+function buildFrontmatter(fields) {
+	const lines = ["---"];
+	for (const [k, v] of Object.entries(fields)) if (v !== void 0) lines.push(`${k}: ${typeof v === "string" ? yamlEscape(v) : v}`);
+	lines.push("---");
+	return lines.join("\n");
+}
+function hasCodeBlock(text) {
+	return STATIC_REGEX_1$9.test(text) || STATIC_REGEX_2$4.test(text);
+}
+const COMMENT_NOISE_RE = /^(?:\+1|👍|same here|any update|bump|following|is there any progress|when will this|me too|i have the same|same issue|thanks|thank you)[\s!?.]*$/i;
+function truncateBody(body, limit) {
+	if (body.length <= limit) return body;
+	const codeBlockRe = /```[\s\S]*?```/g;
+	let lastSafeEnd = limit;
+	let match;
+	while ((match = codeBlockRe.exec(body)) !== null) {
+		const blockStart = match.index;
+		const blockEnd = blockStart + match[0].length;
+		if (blockStart < limit && blockEnd > limit) {
+			if (blockEnd <= limit + 500) lastSafeEnd = blockEnd;
+			else lastSafeEnd = blockStart;
+			break;
+		}
+	}
+	const slice = body.slice(0, lastSafeEnd);
+	const lastParagraph = slice.lastIndexOf("\n\n");
+	if (lastParagraph > lastSafeEnd * .6) return `${slice.slice(0, lastParagraph)}\n\n...`;
+	return `${slice}...`;
+}
+let _ghToken;
+function getGitHubToken() {
+	if (_ghToken !== void 0) return _ghToken;
+	try {
+		const { stdout } = spawnSync("gh", ["auth", "token"], {
+			encoding: "utf-8",
+			timeout: 5e3,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		_ghToken = stdout?.trim() || null;
+	} catch {
+		_ghToken = null;
+	}
+	return _ghToken;
+}
+const _needsAuth = /* @__PURE__ */ new Set();
+function markRepoPrivate(owner, repo) {
+	_needsAuth.add(`${owner}/${repo}`);
+}
+function isKnownPrivateRepo(owner, repo) {
+	return _needsAuth.has(`${owner}/${repo}`);
+}
+async function fetchUnghOrApi(owner, repo, ungh, api) {
+	if (!isKnownPrivateRepo(owner, repo)) {
+		const r = await ungh().catch(() => null);
+		if (r) return r;
+	}
+	const r = await api();
+	if (r) markRepoPrivate(owner, repo);
+	return r;
+}
+const GH_API = "https://api.github.com";
+const ghApiFetch = ofetch.create({
+	retry: 2,
+	retryDelay: 500,
+	timeout: 15e3,
+	headers: { "User-Agent": "skilld/1.0" }
+});
+const LINK_NEXT_RE = /<([^>]+)>;\s*rel="next"/;
+function parseLinkNext(header) {
+	if (!header) return null;
+	return header.match(LINK_NEXT_RE)?.[1] ?? null;
+}
+async function ghApi(endpoint) {
+	const token = getGitHubToken();
+	if (!token) return null;
+	return ghApiFetch(`${GH_API}/${endpoint}`, { headers: { Authorization: `token ${token}` } }).catch(() => null);
+}
+async function ghApiPaginated(endpoint) {
+	const token = getGitHubToken();
+	if (!token) return [];
+	const headers = { Authorization: `token ${token}` };
+	const results = [];
+	let url = `${GH_API}/${endpoint}`;
+	while (url) {
+		const res = await ghApiFetch.raw(url, { headers }).catch(() => null);
+		if (!res?.ok || !Array.isArray(res._data)) break;
+		results.push(...res._data);
+		url = parseLinkNext(res.headers.get("link"));
+	}
+	return results;
+}
+const SKILLD_USER_AGENT = "skilld/1.0 (+https://github.com/harlan-zw/skilld)";
+const $fetch = ofetch.create({
+	retry: 3,
+	retryDelay: 1e3,
+	retryStatusCodes: [
+		408,
+		429,
+		500,
+		502,
+		503,
+		504
+	],
+	timeout: 15e3,
+	headers: { "User-Agent": SKILLD_USER_AGENT }
+});
+function createRateLimitedRunner(intervalMs) {
+	let queue = Promise.resolve();
+	let lastRunAt = 0;
+	return async function runRateLimited(task) {
+		const run = async () => {
+			const waitMs = intervalMs - (Date.now() - lastRunAt);
+			if (waitMs > 0) await new Promise((resolve) => setTimeout(resolve, waitMs));
+			lastRunAt = Date.now();
+			return task();
+		};
+		const request = queue.then(run, run);
+		queue = request.then(() => void 0, () => void 0);
+		return request;
+	};
+}
+async function fetchText(url) {
+	return $fetch(url, { responseType: "text" }).catch(() => null);
+}
+const RAW_GH_RE = /raw\.githubusercontent\.com\/([^/]+)\/([^/]+)/;
+function extractGitHubRepo(url) {
+	const match = url.match(RAW_GH_RE);
+	return match ? {
+		owner: match[1],
+		repo: match[2]
+	} : null;
+}
+async function fetchGitHubRaw(url) {
+	const gh = extractGitHubRepo(url);
+	if (!(gh ? isKnownPrivateRepo(gh.owner, gh.repo) : false)) {
+		const content = await fetchText(url);
+		if (content) return content;
+	}
+	if (!gh) return null;
+	const token = getGitHubToken();
+	if (!token) return null;
+	const content = await $fetch(url, {
+		responseType: "text",
+		headers: { Authorization: `token ${token}` }
+	}).catch(() => null);
+	if (content) markRepoPrivate(gh.owner, gh.repo);
+	return content;
+}
+async function verifyUrl(url) {
+	const res = await $fetch.raw(url, { method: "HEAD" }).catch(() => null);
+	if (!res) return false;
+	return !(res.headers.get("content-type") || "").includes("text/html");
+}
+const STATIC_REGEX_2$3 = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+const STATIC_REGEX_3$3 = /^\d+\.\d+\.\d+-.+/;
+const STATIC_REGEX_4$1 = /changelog\.md/i;
+function parseSemver(version) {
+	const clean = version.replace(V_PREFIX_RE, "");
+	const match = clean.match(STATIC_REGEX_2$3);
+	if (!match) return null;
+	return {
+		major: +match[1],
+		minor: match[2] ? +match[2] : 0,
+		patch: match[3] ? +match[3] : 0,
+		raw: clean
+	};
+}
+function extractVersion(tag, packageName) {
+	if (packageName) {
+		const atMatch = tag.match(new RegExp(`^${escapeRegex(packageName)}@(.+)$`));
+		if (atMatch) return atMatch[1];
+		const dashMatch = tag.match(new RegExp(`^${escapeRegex(packageName)}-v?(.+)$`));
+		if (dashMatch) return dashMatch[1];
+	}
+	return tag.replace(V_PREFIX_RE, "");
+}
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function tagMatchesPackage(tag, packageName) {
+	return tag.startsWith(`${packageName}@`) || tag.startsWith(`${packageName}-v`) || tag.startsWith(`${packageName}-`);
+}
+function isPrerelease(version) {
+	return STATIC_REGEX_3$3.test(version.replace(V_PREFIX_RE, ""));
+}
+function compareSemver(a, b) {
+	if (a.major !== b.major) return a.major - b.major;
+	if (a.minor !== b.minor) return a.minor - b.minor;
+	return a.patch - b.patch;
+}
+function mapApiRelease(r) {
+	return {
+		id: r.id,
+		tag: r.tag_name,
+		name: r.name,
+		prerelease: r.prerelease,
+		createdAt: r.created_at,
+		publishedAt: r.published_at,
+		markdown: r.body
+	};
+}
+async function fetchAllReleases(owner, repo) {
+	const apiReleases = await ghApiPaginated(`repos/${owner}/${repo}/releases`);
+	if (apiReleases.length > 0) return apiReleases.map(mapApiRelease);
+	return (await $fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`, { signal: AbortSignal.timeout(15e3) }).catch(() => null))?.releases ?? [];
+}
+function selectReleases(releases, packageName, installedVersion, fromDate) {
+	const hasMonorepoTags = packageName && releases.some((r) => tagMatchesPackage(r.tag, packageName));
+	const installedSv = installedVersion ? parseSemver(installedVersion) : null;
+	const installedIsPrerelease = installedVersion ? isPrerelease(installedVersion) : false;
+	const fromTs = fromDate ? new Date(fromDate).getTime() : null;
+	const sorted = releases.filter((r) => {
+		const ver = extractVersion(r.tag, hasMonorepoTags ? packageName : void 0);
+		if (!ver) return false;
+		const sv = parseSemver(ver);
+		if (!sv) return false;
+		if (hasMonorepoTags && packageName && !tagMatchesPackage(r.tag, packageName)) return false;
+		if (fromTs) {
+			const pubDate = r.publishedAt || r.createdAt;
+			if (pubDate && new Date(pubDate).getTime() < fromTs) return false;
+		}
+		if (r.prerelease) {
+			if (!installedIsPrerelease || !installedSv) return false;
+			return sv.major === installedSv.major && sv.minor === installedSv.minor;
+		}
+		if (installedSv && compareSemver(sv, installedSv) > 0) return false;
+		return true;
+	}).sort((a, b) => {
+		const verA = extractVersion(a.tag, hasMonorepoTags ? packageName : void 0);
+		const verB = extractVersion(b.tag, hasMonorepoTags ? packageName : void 0);
+		if (!verA || !verB) return 0;
+		return compareSemver(parseSemver(verB), parseSemver(verA));
+	});
+	return fromDate ? sorted : sorted.slice(0, 20);
+}
+function formatRelease(release, packageName) {
+	const date = isoDate(release.publishedAt || release.createdAt);
+	const version = extractVersion(release.tag, packageName) || release.tag;
+	const fm = [
+		"---",
+		`tag: ${yamlEscape(release.tag)}`,
+		`version: ${yamlEscape(version)}`,
+		`published: ${date}`
+	];
+	if (release.name && release.name !== release.tag) fm.push(`name: ${yamlEscape(release.name)}`);
+	fm.push("---");
+	return `${fm.join("\n")}\n\n# ${release.name || release.tag}\n\n${release.markdown}`;
+}
+function generateReleaseIndex(releasesOrOpts, packageName) {
+	const opts = Array.isArray(releasesOrOpts) ? {
+		releases: releasesOrOpts,
+		packageName
+	} : releasesOrOpts;
+	const { releases, blogReleases, hasChangelog } = opts;
+	const pkg = opts.packageName;
+	const lines = [
+		[
+			"---",
+			`total: ${releases.length + (blogReleases?.length ?? 0)}`,
+			`latest: ${yamlEscape(releases[0]?.tag || "unknown")}`,
+			"---"
+		].join("\n"),
+		"",
+		"# Releases Index",
+		""
+	];
+	if (blogReleases && blogReleases.length > 0) {
+		lines.push("## Blog Releases", "");
+		for (const b of blogReleases) lines.push(`- [${b.version}](./blog-${b.version}.md): ${b.title} (${b.date})`);
+		lines.push("");
+	}
+	if (releases.length > 0) {
+		if (blogReleases && blogReleases.length > 0) lines.push("## Release Notes", "");
+		for (const r of releases) {
+			const date = isoDate(r.publishedAt || r.createdAt);
+			const filename = r.tag.includes("@") || r.tag.startsWith("v") ? r.tag : `v${r.tag}`;
+			const sv = parseSemver(extractVersion(r.tag, pkg) || 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("");
+	}
+	if (hasChangelog) {
+		lines.push("## Changelog", "");
+		lines.push("- [CHANGELOG.md](./CHANGELOG.md)");
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+function isStubRelease(release) {
+	const body = (release.markdown || "").trim();
+	return body.length < 500 && STATIC_REGEX_4$1.test(body);
+}
+async function fetchChangelog(owner, repo, ref, packageName) {
+	const paths = [];
+	if (packageName) {
+		const shortName = packageName.replace(NPM_SCOPE_WITH_SLASH_RE, "");
+		const scopeless = packageName.replace(NPM_SCOPE_PREFIX_RE, "").replace("/", "-");
+		const candidates = [...new Set([shortName, scopeless])];
+		for (const name of candidates) paths.push(`packages/${name}/CHANGELOG.md`);
+	}
+	paths.push("CHANGELOG.md", "changelog.md", "CHANGES.md");
+	for (const path of paths) {
+		const content = await fetchGitHubRaw(`https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path}`);
+		if (content) return content;
+	}
+	return null;
+}
+async function fetchReleaseNotes(owner, repo, installedVersion, gitRef, packageName, fromDate, changelogRef) {
+	const selected = selectReleases(await fetchAllReleases(owner, repo), packageName, installedVersion, fromDate);
+	if (selected.length > 0) {
+		const docs = selected.filter((r) => !isStubRelease(r)).map((r) => {
+			return {
+				path: `releases/${r.tag.includes("@") || r.tag.startsWith("v") ? r.tag : `v${r.tag}`}.md`,
+				content: formatRelease(r, packageName)
+			};
+		});
+		const changelog = await fetchChangelog(owner, repo, changelogRef || gitRef || selected[0].tag, packageName);
+		if (changelog && changelog.length < 5e5) docs.push({
+			path: "releases/CHANGELOG.md",
+			content: changelog
+		});
+		return docs;
+	}
+	const changelog = await fetchChangelog(owner, repo, changelogRef || gitRef || "main", packageName);
+	if (!changelog) return [];
+	return [{
+		path: "releases/CHANGELOG.md",
+		content: changelog
+	}];
+}
+const STATIC_REGEX_1$8 = /<h1[^>]*>([^<]+)<\/h1>/;
+const STATIC_REGEX_2$2 = /<title>([^<]+)<\/title>/;
+function formatBlogRelease(release) {
+	return `${[
+		"---",
+		`version: ${yamlEscape(release.version)}`,
+		`title: ${yamlEscape(release.title)}`,
+		`date: ${release.date}`,
+		`url: ${yamlEscape(release.url)}`,
+		`source: blog-release`,
+		"---"
+	].join("\n")}\n\n# ${release.title}\n\n${release.markdown}`;
+}
+async function fetchBlogPost(entry) {
+	try {
+		const html = await $fetch(entry.url, {
+			responseType: "text",
+			signal: AbortSignal.timeout(1e4)
+		}).catch(() => null);
+		if (!html) return null;
+		let title = "";
+		const titleMatch = html.match(STATIC_REGEX_1$8);
+		if (titleMatch) title = titleMatch[1].trim();
+		if (!title) {
+			const metaTitleMatch = html.match(STATIC_REGEX_2$2);
+			if (metaTitleMatch) title = metaTitleMatch[1].trim();
+		}
+		const markdown = htmlToMarkdown(html);
+		if (!markdown) return null;
+		return {
+			version: entry.version,
+			title: title || entry.title || `Release ${entry.version}`,
+			date: entry.date,
+			markdown,
+			url: entry.url
+		};
+	} catch {
+		return null;
+	}
+}
+function filterBlogsByVersion(entries, installedVersion) {
+	const installedSv = parseSemver(installedVersion);
+	if (!installedSv) return entries;
+	return entries.filter((entry) => {
+		const entrySv = parseSemver(entry.version);
+		if (!entrySv) return false;
+		return compareSemver(entrySv, installedSv) <= 0;
+	});
+}
+async function fetchBlogReleases(packageName, installedVersion) {
+	const preset = getBlogPreset(packageName);
+	if (!preset) return [];
+	const filteredReleases = filterBlogsByVersion(preset.releases, installedVersion);
+	if (filteredReleases.length === 0) return [];
+	const limit = pLimit(3);
+	const releases = (await Promise.all(filteredReleases.map((entry) => limit(() => fetchBlogPost(entry))))).filter((r) => r !== null);
+	if (releases.length === 0) return [];
+	releases.sort((a, b) => {
+		const aVer = a.version.split(".").map(Number);
+		const bVer = b.version.split(".").map(Number);
+		for (let i = 0; i < Math.max(aVer.length, bVer.length); i++) {
+			const diff = (bVer[i] ?? 0) - (aVer[i] ?? 0);
+			if (diff !== 0) return diff;
+		}
+		return 0;
+	});
+	return releases.map((r) => ({
+		path: `releases/blog-${r.version}.md`,
+		content: formatBlogRelease(r)
+	}));
+}
+const STATIC_REGEX_1$7 = /github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:[/#]|$)/;
+const STATIC_REGEX_3$2 = /#.*$/;
+const STATIC_REGEX_7 = /^git@github\.com:/;
+const STATIC_REGEX_8 = /^(?:127\.|10\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.|169\.254\.)/;
+const STATIC_REGEX_9 = /^\[(?:f[cd]|fe[89ab]|::ffff:)/i;
+function parseGitHubUrl(url) {
+	const match = url.match(STATIC_REGEX_1$7);
+	if (!match) return null;
+	return {
+		owner: match[1],
+		repo: match[2]
+	};
+}
+function parseGitHubRepoSlug(url) {
+	if (!url) return void 0;
+	const parsed = parseGitHubUrl(url);
+	return parsed ? `${parsed.owner}/${parsed.repo}` : void 0;
+}
+function parsePackageSpec(spec) {
+	if (spec.startsWith("@")) {
+		const slashIdx = spec.indexOf("/");
+		if (slashIdx !== -1) {
+			const atIdx = spec.indexOf("@", slashIdx + 1);
+			if (atIdx !== -1) return {
+				name: spec.slice(0, atIdx),
+				tag: spec.slice(atIdx + 1)
+			};
+		}
+		return { name: spec };
+	}
+	const atIdx = spec.indexOf("@");
+	if (atIdx !== -1) return {
+		name: spec.slice(0, atIdx),
+		tag: spec.slice(atIdx + 1)
+	};
+	return { name: spec };
+}
+function normalizeRepoUrl(url) {
+	return url.replace(GIT_PLUS_PREFIX_RE, "").replace(STATIC_REGEX_3$2, "").replace(GIT_SUFFIX_RE, "").replace(GIT_PROTOCOL_PREFIX_RE, "https://").replace(GITHUB_SSH_URL_PREFIX_RE, "https://github.com").replace(STATIC_REGEX_7, "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;
+}
+function isGitHubRepoUrl(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.hostname === "github.com" || parsed.hostname === "www.github.com";
+	} catch {
+		return false;
+	}
+}
+function isLikelyCodeHostUrl(url) {
+	if (!url) return false;
+	try {
+		const parsed = new URL(url);
+		return [
+			"github.com",
+			"www.github.com",
+			"gitlab.com",
+			"www.gitlab.com"
+		].includes(parsed.hostname);
+	} catch {
+		return false;
+	}
+}
+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 isSafeUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "https:") return false;
+		const host = parsed.hostname;
+		if (host === "localhost" || host === "0.0.0.0" || host === "[::1]") return false;
+		if (STATIC_REGEX_8.test(host)) return false;
+		if (STATIC_REGEX_9.test(host)) return false;
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function listFilesAtRef(owner, repo, ref) {
+	return await fetchUnghOrApi(owner, repo, async () => {
+		const data = await $fetch(`https://ungh.cc/repos/${owner}/${repo}/files/${ref}`);
+		return data.files?.length ? data.files.map((f) => f.path) : null;
+	}, async () => {
+		const tree = await ghApi(`repos/${owner}/${repo}/git/trees/${ref}?recursive=1`);
+		return tree?.tree?.length ? tree.tree.map((f) => f.path) : null;
+	}) ?? [];
+}
+async function findGitTag(owner, repo, version, packageName, branchHint) {
+	const candidates = [`v${version}`, version];
+	if (packageName) candidates.push(`${packageName}@${version}`);
+	for (const tag of candidates) {
+		const files = await listFilesAtRef(owner, repo, tag);
+		if (files.length > 0) return {
+			ref: tag,
+			files
+		};
+	}
+	if (packageName) {
+		const latestTag = await findLatestReleaseTag(owner, repo, packageName);
+		if (latestTag) {
+			const files = await listFilesAtRef(owner, repo, latestTag);
+			if (files.length > 0) return {
+				ref: latestTag,
+				files
+			};
+		}
+	}
+	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,
+			files,
+			fallback: true
+		};
+	}
+	return null;
+}
+async function fetchUnghReleases(owner, repo) {
+	return await fetchUnghOrApi(owner, repo, async () => {
+		const data = await $fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`);
+		return data.releases?.length ? data.releases : null;
+	}, async () => {
+		const raw = await ghApiPaginated(`repos/${owner}/${repo}/releases`);
+		return raw.length > 0 ? raw.map((r) => ({
+			tag: r.tag_name,
+			publishedAt: r.published_at
+		})) : null;
+	}) ?? [];
+}
+async function findLatestReleaseTag(owner, repo, packageName) {
+	const prefix = `${packageName}@`;
+	return (await fetchUnghReleases(owner, repo)).find((r) => r.tag.startsWith(prefix))?.tag ?? null;
+}
+const STATIC_REGEX_1$6 = /\.(?:md|mdx)$/;
+const isShallowGitDocs = (n) => n > 0 && n < 5;
+function filterDocFiles(files, pathPrefix) {
+	return files.filter((f) => f.startsWith(pathPrefix) && STATIC_REGEX_1$6.test(f));
+}
+const FRAMEWORK_NAMES = new Set([
+	"vue",
+	"react",
+	"solid",
+	"angular",
+	"svelte",
+	"preact",
+	"lit",
+	"qwik"
+]);
+function filterFrameworkDocs(files, packageName) {
+	if (!packageName) return files;
+	const shortName = packageName.replace(NPM_SCOPE_WITH_SLASH_RE, "");
+	const targetFramework = [...FRAMEWORK_NAMES].find((fw) => shortName.includes(fw));
+	if (!targetFramework) return files;
+	const otherFrameworks = [...FRAMEWORK_NAMES].filter((fw) => fw !== targetFramework);
+	const excludePattern = new RegExp(`\\b(?:${otherFrameworks.join("|")})\\b`);
+	return files.filter((f) => !excludePattern.test(f));
+}
+const NOISE_PATTERNS = [
+	/^\.changeset\//,
+	/CHANGELOG\.md$/i,
+	/CONTRIBUTING\.md$/i,
+	/^\.github\//
+];
+const EXCLUDE_DIRS = new Set([
+	"test",
+	"tests",
+	"__tests__",
+	"fixtures",
+	"fixture",
+	"examples",
+	"example",
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	"coverage",
+	"e2e",
+	"spec",
+	"mocks",
+	"__mocks__"
+]);
+const DOC_DIR_BONUS = new Set([
+	"docs",
+	"documentation",
+	"pages",
+	"content",
+	"website",
+	"guide",
+	"guides",
+	"wiki",
+	"manual",
+	"api"
+]);
+function hasExcludedDir(path) {
+	return path.split("/").some((p) => EXCLUDE_DIRS.has(p.toLowerCase()));
+}
+function getPathDepth(path) {
+	return path.split("/").filter(Boolean).length;
+}
+function hasDocDirBonus(path) {
+	return path.split("/").some((p) => DOC_DIR_BONUS.has(p.toLowerCase()));
+}
+function scoreDocDir(dir, fileCount) {
+	const depth = getPathDepth(dir) || 1;
+	return fileCount * (hasDocDirBonus(dir) ? 1.5 : 1) / depth;
+}
+function discoverDocFiles(allFiles, packageName) {
+	const mdFiles = allFiles.filter((f) => STATIC_REGEX_1$6.test(f)).filter((f) => !NOISE_PATTERNS.some((p) => p.test(f))).filter((f) => f.includes("/"));
+	if (packageName?.includes("/")) {
+		const subPkgPrefix = `packages/${packageName.split("/").pop().toLowerCase()}/`;
+		const subPkgFiles = mdFiles.filter((f) => f.startsWith(subPkgPrefix));
+		if (subPkgFiles.length >= 3) return {
+			files: subPkgFiles,
+			prefix: subPkgPrefix
+		};
+	}
+	const docsGroups = /* @__PURE__ */ new Map();
+	for (const file of mdFiles) {
+		const docsIdx = file.lastIndexOf("/docs/");
+		if (docsIdx === -1) continue;
+		mapInsert(docsGroups, file.slice(0, docsIdx + 6), () => []).push(file);
+	}
+	if (docsGroups.size > 0) {
+		const largest = [...docsGroups.entries()].sort((a, b) => b[1].length - a[1].length)[0];
+		if (largest[1].length >= 3) {
+			const fullPrefix = largest[0];
+			const docsIdx = fullPrefix.lastIndexOf("docs/");
+			const stripPrefix = docsIdx > 0 ? fullPrefix.slice(0, docsIdx) : "";
+			return {
+				files: largest[1],
+				prefix: stripPrefix
+			};
+		}
+	}
+	const dirGroups = /* @__PURE__ */ new Map();
+	for (const file of mdFiles) {
+		if (hasExcludedDir(file)) continue;
+		const lastSlash = file.lastIndexOf("/");
+		if (lastSlash === -1) continue;
+		mapInsert(dirGroups, file.slice(0, lastSlash + 1), () => []).push(file);
+	}
+	if (dirGroups.size === 0) return null;
+	const scored = Array.from(dirGroups.entries(), ([dir, files]) => ({
+		dir,
+		files,
+		score: scoreDocDir(dir, files.length)
+	})).filter((d) => d.files.length >= 5).sort((a, b) => b.score - a.score);
+	if (scored.length === 0) return null;
+	const best = scored[0];
+	return {
+		files: best.files,
+		prefix: best.dir
+	};
+}
+async function listDocsAtRef(owner, repo, ref, pathPrefix = "docs/") {
+	return filterDocFiles(await listFilesAtRef(owner, repo, ref), pathPrefix);
+}
+async function fetchGitDocs(owner, repo, version, packageName, repoUrl) {
+	const override = packageName ? getDocOverride(packageName) : void 0;
+	if (override) {
+		const ref = override.ref || "main";
+		const fallback = !override.ref;
+		const files = await listDocsAtRef(override.owner, override.repo, ref, `${override.path}/`);
+		if (files.length === 0) return null;
+		return {
+			baseUrl: `https://raw.githubusercontent.com/${override.owner}/${override.repo}/${ref}`,
+			ref,
+			files,
+			fallback,
+			docsPrefix: `${override.path}/` !== "docs/" ? `${override.path}/` : void 0
+		};
+	}
+	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, packageName);
+		if (discovered) {
+			docs = discovered.files;
+			docsPrefix = discovered.prefix || void 0;
+			allFiles = tag.files;
+		}
+	}
+	docs = filterFrameworkDocs(docs, packageName);
+	if (docs.length === 0) return null;
+	return {
+		baseUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${tag.ref}`,
+		ref: tag.ref,
+		files: docs,
+		docsPrefix,
+		allFiles,
+		fallback: tag.fallback
+	};
+}
+function normalizePath(p) {
+	return p.replace(LEADING_SLASH_RE, "").replace(STATIC_REGEX_1$6, "");
+}
+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
+	};
+}
+const STATIC_REGEX_1$5 = /\b(?:love|thank|awesome|great work)\b/i;
+const STATIC_REGEX_2$1 = /\broadmap\b/i;
+const STATIC_REGEX_3$1 = /roadmap/i;
+const STATIC_REGEX_4 = /(?:fixed|landed|released|available|shipped|resolved|included)\s+in\s+v?(\d+\.\d+(?:\.\d+)?)/i;
+const STATIC_REGEX_5 = /\bv?(\d+\.\d+\.\d+)\b/;
+let _ghAvailable;
+function isGhAvailable() {
+	if (_ghAvailable !== void 0) return _ghAvailable;
+	const { status } = spawnSync("gh", ["auth", "status"], { stdio: "ignore" });
+	return _ghAvailable = status === 0;
+}
+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"
+]);
+const labelRegexCache = /* @__PURE__ */ new WeakMap();
+function getLabelRegex(keywords) {
+	let re = labelRegexCache.get(keywords);
+	if (!re) {
+		const escaped = Array.from(keywords, (k) => k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+		re = new RegExp(`\\b(?:${escaped.join("|")})\\b`);
+		labelRegexCache.set(keywords, re);
+	}
+	return re;
+}
+function labelMatchesAny(label, keywords) {
+	if (keywords.has(label)) return true;
+	return getLabelRegex(keywords).test(label);
+}
+function classifyIssue(labels) {
+	const lower = labels.map((l) => l.toLowerCase());
+	if (lower.some((l) => labelMatchesAny(l, BUG_LABELS))) return "bug";
+	if (lower.some((l) => labelMatchesAny(l, QUESTION_LABELS))) return "question";
+	if (lower.some((l) => labelMatchesAny(l, DOCS_LABELS))) return "docs";
+	if (lower.some((l) => labelMatchesAny(l, FEATURE_LABELS))) return "feature";
+	return "other";
+}
+function isNoiseIssue(issue) {
+	if (issue.labels.map((l) => l.toLowerCase()).some((l) => labelMatchesAny(l, NOISE_LABELS))) return true;
+	if (issue.title.startsWith("☂️") || issue.title.startsWith("[META]") || issue.title.startsWith("[Tracking]")) return true;
+	return false;
+}
+function isNonTechnical(issue) {
+	const body = (issue.body || "").trim();
+	if (body.length < 200 && !hasCodeBlock(body) && issue.reactions > 50) return true;
+	if (STATIC_REGEX_1$5.test(issue.title) && !hasCodeBlock(body)) return true;
+	return false;
+}
+function freshnessScore(reactions, createdAt) {
+	return reactions * (1 / (1 + (Date.now() - new Date(createdAt).getTime()) / (365.25 * 24 * 60 * 60 * 1e3) * .6));
+}
+function applyTypeQuotas(issues, limit) {
+	const byType = /* @__PURE__ */ new Map();
+	for (const issue of issues) mapInsert(byType, issue.type, () => []).push(issue);
+	for (const group of byType.values()) group.sort((a, b) => b.score - a.score);
+	const quotas = [
+		["bug", Math.ceil(limit * .4)],
+		["question", Math.ceil(limit * .3)],
+		["docs", Math.ceil(limit * .15)],
+		["feature", Math.ceil(limit * .1)],
+		["other", Math.ceil(limit * .05)]
+	];
+	const selected = [];
+	const used = /* @__PURE__ */ new Set();
+	let remaining = limit;
+	for (const [type, quota] of quotas) {
+		const group = byType.get(type) || [];
+		const take = Math.min(quota, group.length, remaining);
+		for (let i = 0; i < take; i++) {
+			selected.push(group[i]);
+			used.add(group[i].number);
+			remaining--;
+		}
+	}
+	if (remaining > 0) {
+		const unused = issues.filter((i) => !used.has(i.number) && i.type !== "feature").sort((a, b) => b.score - a.score);
+		for (const issue of unused) {
+			if (remaining <= 0) break;
+			selected.push(issue);
+			remaining--;
+		}
+	}
+	return selected.sort((a, b) => b.score - a.score);
+}
+function bodyLimit(reactions) {
+	if (reactions >= 10) return 2e3;
+	if (reactions >= 5) return 1500;
+	return 800;
+}
+function fetchIssuesByState(owner, repo, state, count, releasedAt, fromDate) {
+	const fetchCount = Math.min(count * 3, 100);
+	let datePart = "";
+	if (fromDate) datePart = state === "closed" ? `+closed:>=${fromDate}` : `+created:>=${fromDate}`;
+	else if (state === "closed") if (releasedAt) {
+		datePart = `+closed:>=${isoDate(releasedAt)}`;
+		const cap = new Date(releasedAt);
+		cap.setMonth(cap.getMonth() + 6);
+		if (cap < /* @__PURE__ */ new Date()) datePart += `+closed:<=${isoDate(cap.toISOString())}`;
+	} else datePart = `+closed:>${oneYearAgo()}`;
+	else if (releasedAt) {
+		const date = new Date(releasedAt);
+		date.setMonth(date.getMonth() + 6);
+		datePart = `+created:<=${isoDate(date.toISOString())}`;
+	}
+	const { stdout: result } = spawnSync("gh", [
+		"api",
+		`search/issues?q=${`repo:${owner}/${repo}+is:issue+is:${state}${datePart}`}&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, authorAssociation: .author_association}"
+	], {
+		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)).filter((issue) => !isNonTechnical(issue)).map(({ user: _, userType: __, authorAssociation, ...issue }) => {
+		const isMaintainer = [
+			"OWNER",
+			"MEMBER",
+			"COLLABORATOR"
+		].includes(authorAssociation);
+		const isRoadmap = STATIC_REGEX_2$1.test(issue.title) || issue.labels.some((l) => STATIC_REGEX_3$1.test(l));
+		return {
+			...issue,
+			type: classifyIssue(issue.labels),
+			topComments: [],
+			score: freshnessScore(issue.reactions, issue.createdAt) * (isMaintainer && isRoadmap ? 5 : 1)
+		};
+	}).sort((a, b) => b.score - a.score).slice(0, count);
+}
+function oneYearAgo() {
+	const d = /* @__PURE__ */ new Date();
+	d.setFullYear(d.getFullYear() - 1);
+	return isoDate(d.toISOString());
+}
+function enrichWithComments(owner, repo, issues, topN = 15) {
+	const worth = issues.filter((i) => i.comments > 0 && (i.type === "bug" || i.type === "question" || i.reactions >= 3)).sort((a, b) => b.score - a.score).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: 10) { nodes { body author { login } authorAssociation reactions { totalCount } } } }`).join(" ")} } }`;
+	try {
+		const { stdout: result } = spawnSync("gh", [
+			"api",
+			"graphql",
+			"-f",
+			`query=${query}`,
+			"-f",
+			`owner=${owner}`,
+			"-f",
+			`repo=${repo}`
+		], {
+			encoding: "utf-8",
+			maxBuffer: 10 * 1024 * 1024
+		});
+		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;
+			const issue = worth[i];
+			const comments = nodes.filter((c) => c.author && !BOT_USERS.has(c.author.login)).filter((c) => !COMMENT_NOISE_RE.test((c.body || "").trim())).map((c) => {
+				const isMaintainer = [
+					"OWNER",
+					"MEMBER",
+					"COLLABORATOR"
+				].includes(c.authorAssociation);
+				const body = c.body || "";
+				const reactions = c.reactions?.totalCount || 0;
+				const _score = (isMaintainer ? 3 : 1) * (hasCodeBlock(body) ? 2 : 1) * (1 + reactions);
+				return {
+					body,
+					author: c.author.login,
+					reactions,
+					isMaintainer,
+					_score
+				};
+			}).sort((a, b) => b._score - a._score);
+			issue.topComments = comments.slice(0, 3).map(({ _score: _, ...c }) => c);
+			if (issue.state === "closed") issue.resolvedIn = detectResolvedVersion(comments);
+		}
+	} catch {}
+}
+function detectResolvedVersion(comments) {
+	const maintainerComments = comments.filter((c) => c.isMaintainer);
+	for (const c of maintainerComments.reverse()) {
+		const match = c.body.match(STATIC_REGEX_4);
+		if (match) return match[1];
+		if (c.body.length < 100) {
+			const vMatch = c.body.match(STATIC_REGEX_5);
+			if (vMatch) return vMatch[1];
+		}
+	}
+}
+async function fetchGitHubIssues(owner, repo, limit = 30, releasedAt, fromDate) {
+	if (!isGhAvailable()) return [];
+	const openCount = Math.ceil(limit * .75);
+	const closedCount = limit - openCount;
+	try {
+		const open = fetchIssuesByState(owner, repo, "open", Math.min(openCount * 2, 100), releasedAt, fromDate);
+		const closed = fetchIssuesByState(owner, repo, "closed", Math.min(closedCount * 2, 50), releasedAt, fromDate);
+		const selected = applyTypeQuotas([...open, ...closed], limit);
+		enrichWithComments(owner, repo, selected);
+		return selected;
+	} catch {
+		return [];
+	}
+}
+function formatIssueAsMarkdown(issue) {
+	const limit = bodyLimit(issue.reactions);
+	const fmFields = {
+		number: issue.number,
+		title: issue.title,
+		type: issue.type,
+		state: issue.state,
+		created: isoDate(issue.createdAt),
+		url: issue.url,
+		reactions: issue.reactions,
+		comments: issue.comments
+	};
+	if (issue.resolvedIn) fmFields.resolvedIn = issue.resolvedIn;
+	if (issue.labels.length > 0) fmFields.labels = `[${issue.labels.join(", ")}]`;
+	const lines = [
+		buildFrontmatter(fmFields),
+		"",
+		`# ${issue.title}`
+	];
+	if (issue.body) {
+		const body = truncateBody(issue.body, limit);
+		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 maintainer = c.isMaintainer ? " [maintainer]" : "";
+			const commentBody = truncateBody(c.body, 600);
+			lines.push("", `**@${c.author}**${maintainer}${reactions}:`, "", commentBody);
+		}
+	}
+	return lines.join("\n");
+}
+function generateIssueIndex(issues) {
+	const byType = /* @__PURE__ */ new Map();
+	for (const issue of issues) mapInsert(byType, issue.type, () => []).push(issue);
+	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]";
+			const resolved = issue.resolvedIn ? ` [fixed in ${issue.resolvedIn}]` : "";
+			const date = isoDate(issue.createdAt);
+			sections.push(`- [#${issue.number}](./issue-${issue.number}.md): ${issue.title}${reactions}${state}${resolved} (${date})`);
+		}
+		sections.push("");
+	}
+	return sections.join("\n");
+}
+async function fetchLlmsUrl(docsUrl) {
+	const llmsUrl = `${new URL(docsUrl).origin}/llms.txt`;
+	if (await verifyUrl(llmsUrl)) return llmsUrl;
+	return null;
+}
+async function fetchLlmsTxt(url) {
+	const content = await fetchText(url);
+	if (!content || content.length < 50) return null;
+	return {
+		raw: content,
+		links: parseMarkdownLinks(content)
+	};
+}
+function parseMarkdownLinks(content) {
+	return extractLinks(content).filter((l) => l.url.endsWith(".md"));
+}
+async function downloadLlmsDocs(llmsContent, baseUrl, onProgress) {
+	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(TRAILING_SLASH_RE, "")}${link.url.startsWith("/") ? "" : "/"}${link.url}`;
+		if (!isSafeUrl(url)) return null;
+		const content = await fetchText(url);
+		onProgress?.(link.url, ++completed, llmsContent.links.length);
+		if (content && content.length > 100) return {
+			url: link.url.startsWith("http") ? new URL(link.url).pathname : link.url,
+			title: link.title,
+			content
+		};
+		return null;
+	})))).filter((d) => d !== null);
+}
+function normalizeLlmsLinks(content, baseUrl) {
+	let normalized = content;
+	if (baseUrl) {
+		const escaped = baseUrl.replace(TRAILING_SLASH_RE, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		normalized = normalized.replace(new RegExp(`\\]\\(${escaped}(/[^)]+\\.md)\\)`, "g"), "](./docs$1)");
+	}
+	normalized = normalized.replace(/\]\(\/([^)]+\.md)\)/g, "](./docs/$1)");
+	return normalized;
+}
+async function verifyNpmRepo(owner, repo, packageName) {
+	const base = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD`;
+	const paths = [
+		"package.json",
+		`packages/${packageName.replace(NPM_SCOPE_WITH_SLASH_RE, "")}/package.json`,
+		`packages/${packageName.replace(NPM_SCOPE_PREFIX_RE, "").replace("/", "-")}/package.json`
+	];
+	for (const path of paths) {
+		const text = await fetchGitHubRaw(`${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(NPM_SCOPE_WITH_SLASH_RE, "");
+	for (const candidate of [packageName.replace(NPM_SCOPE_PREFIX_RE, "").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(NPM_SCOPE_PREFIX_RE, "");
+	if (isGhAvailable()) try {
+		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(`/${shortName.toLowerCase()}`));
+		if (match) return `https://github.com/${match.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 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(`/${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 };
+	const data = await ghApi(`repos/${owner}/${repo}`) ?? await $fetch(`https://api.github.com/repos/${owner}/${repo}`).catch(() => null);
+	return data?.homepage ? { homepage: data.homepage } : null;
+}
+async function fetchReadme(owner, repo, subdir, ref) {
+	const branch = ref || "main";
+	if (!isKnownPrivateRepo(owner, repo)) {
+		const unghUrl = subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/${branch}/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme${ref ? `?ref=${ref}` : ""}`;
+		if ((await $fetch.raw(unghUrl).catch(() => null))?.ok) return `ungh://${owner}/${repo}${subdir ? `/${subdir}` : ""}${ref ? `@${ref}` : ""}`;
+	}
+	const basePath = subdir ? `${subdir}/` : "";
+	const branches = ref ? [ref] : ["main", "master"];
+	const token = isKnownPrivateRepo(owner, repo) ? getGitHubToken() : null;
+	const authHeaders = token ? { Authorization: `token ${token}` } : {};
+	for (const b of branches) for (const filename of [
+		"README.md",
+		"Readme.md",
+		"readme.md"
+	]) {
+		const readmeUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${b}/${basePath}${filename}`;
+		if ((await $fetch.raw(readmeUrl, { headers: authHeaders }).catch(() => null))?.ok) return readmeUrl;
+	}
+	const refParam = ref ? `?ref=${ref}` : "";
+	const apiData = await ghApi(subdir ? `repos/${owner}/${repo}/contents/${subdir}/README.md${refParam}` : `repos/${owner}/${repo}/readme${refParam}`);
+	if (apiData?.download_url) {
+		markRepoPrivate(owner, repo);
+		return apiData.download_url;
+	}
+	return null;
+}
+async function fetchReadmeContent(url) {
+	if (url.startsWith("file://")) {
+		const filePath = fileURLToPath(url);
+		if (!existsSync(filePath)) return null;
+		return readFileSync(filePath, "utf-8");
+	}
+	if (url.startsWith("ungh://")) {
+		let path = url.replace("ungh://", "");
+		let ref = "main";
+		const atIdx = path.lastIndexOf("@");
+		if (atIdx !== -1) {
+			ref = path.slice(atIdx + 1);
+			path = path.slice(0, atIdx);
+		}
+		const parts = path.split("/");
+		const owner = parts[0];
+		const repo = parts[1];
+		const subdir = parts.slice(2).join("/");
+		const text = await $fetch(subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/${ref}/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme?ref=${ref}`, { responseType: "text" }).catch(() => null);
+		if (!text) return null;
+		try {
+			const json = JSON.parse(text);
+			return json.markdown || json.file?.contents || null;
+		} catch {
+			return text;
+		}
+	}
+	if (url.includes("raw.githubusercontent.com")) return fetchGitHubRaw(url);
+	return fetchText(url);
+}
+async function resolveGitHubRepo(owner, repo, onProgress) {
+	onProgress?.("Fetching repo metadata");
+	const repoUrl = `https://github.com/${owner}/${repo}`;
+	const meta = await ghApi(`repos/${owner}/${repo}`) ?? await $fetch(`https://api.github.com/repos/${owner}/${repo}`).catch(() => null);
+	const homepage = meta?.homepage || void 0;
+	const description = meta?.description || void 0;
+	onProgress?.("Fetching latest release");
+	const releases = await fetchUnghReleases(owner, repo);
+	let version = "main";
+	let releasedAt;
+	const latestRelease = releases[0];
+	if (latestRelease) {
+		version = latestRelease.tag.replace(V_PREFIX_RE, "");
+		releasedAt = latestRelease.publishedAt;
+	}
+	onProgress?.("Resolving docs");
+	const gitDocs = await fetchGitDocs(owner, repo, version);
+	const gitDocsUrl = gitDocs ? `${repoUrl}/tree/${gitDocs.ref}/docs` : void 0;
+	const gitRef = gitDocs?.ref;
+	onProgress?.("Fetching README");
+	const readmeUrl = await fetchReadme(owner, repo);
+	let llmsUrl;
+	if (homepage) {
+		onProgress?.("Checking llms.txt");
+		llmsUrl = await fetchLlmsUrl(homepage).catch(() => null) ?? void 0;
+	}
+	if (!gitDocsUrl && !readmeUrl && !llmsUrl) return null;
+	return {
+		name: repo,
+		version: latestRelease ? version : void 0,
+		releasedAt,
+		description,
+		repoUrl,
+		docsUrl: homepage,
+		gitDocsUrl,
+		gitRef,
+		gitDocsFallback: gitDocs?.fallback,
+		readmeUrl: readmeUrl ?? void 0,
+		llmsUrl
+	};
+}
+const VALID_CRATE_NAME = /^[a-z0-9][\w-]*$/;
+const runCratesApiRateLimited = createRateLimitedRunner(1e3);
+function selectCrateVersion(data, requestedVersion) {
+	const versions = data.versions || [];
+	if (requestedVersion) {
+		const exact = versions.find((v) => v.num === requestedVersion && !v.yanked);
+		if (exact?.num) return {
+			version: exact.num,
+			entry: exact
+		};
+	}
+	const crate = data.crate;
+	const preferred = [
+		crate?.max_stable_version,
+		crate?.newest_version,
+		crate?.max_version,
+		crate?.default_version
+	].find(Boolean);
+	if (preferred) {
+		const match = versions.find((v) => v.num === preferred && !v.yanked);
+		if (match?.num) return {
+			version: preferred,
+			entry: match
+		};
+		if (versions.length === 0) return { version: preferred };
+	}
+	const firstStable = versions.find((v) => !v.yanked && v.num);
+	if (firstStable?.num) return {
+		version: firstStable.num,
+		entry: firstStable
+	};
+	return null;
+}
+function pickPreferredUrl(...urls) {
+	return urls.map((v) => v?.trim()).find((v) => !!v);
+}
+async function fetchCratesApi(url) {
+	return runCratesApiRateLimited(() => $fetch(url).catch(() => null));
+}
+async function resolveCrateDocsWithAttempts(crateName, options = {}) {
+	const attempts = [];
+	const onProgress = options.onProgress;
+	const normalizedName = crateName.trim().toLowerCase();
+	if (!normalizedName || !VALID_CRATE_NAME.test(normalizedName)) {
+		attempts.push({
+			source: "crates",
+			status: "error",
+			message: `Invalid crate name: ${crateName}`
+		});
+		return {
+			package: null,
+			attempts
+		};
+	}
+	onProgress?.("crates.io metadata");
+	const apiUrl = `https://crates.io/api/v1/crates/${encodeURIComponent(normalizedName)}`;
+	const data = await fetchCratesApi(apiUrl);
+	if (!data?.crate) {
+		attempts.push({
+			source: "crates",
+			url: apiUrl,
+			status: "not-found",
+			message: "Crate not found on crates.io"
+		});
+		return {
+			package: null,
+			attempts
+		};
+	}
+	attempts.push({
+		source: "crates",
+		url: apiUrl,
+		status: "success",
+		message: `Found crate: ${data.crate.name || normalizedName}`
+	});
+	const selected = selectCrateVersion(data, options.version);
+	if (!selected) {
+		attempts.push({
+			source: "crates",
+			url: apiUrl,
+			status: "error",
+			message: "No usable crate versions found"
+		});
+		return {
+			package: null,
+			attempts
+		};
+	}
+	const version = selected.version;
+	const versionEntry = selected.entry;
+	const docsRsUrl = `https://docs.rs/${encodeURIComponent(normalizedName)}/${encodeURIComponent(version)}`;
+	const repositoryRaw = pickPreferredUrl(versionEntry?.repository, data.crate.repository);
+	const homepage = pickPreferredUrl(versionEntry?.homepage, data.crate.homepage);
+	const documentation = pickPreferredUrl(versionEntry?.documentation, data.crate.documentation);
+	const normalizedRepo = repositoryRaw ? normalizeRepoUrl(repositoryRaw) : void 0;
+	const repoUrl = normalizedRepo && isLikelyCodeHostUrl(normalizedRepo) ? normalizedRepo : isLikelyCodeHostUrl(homepage) ? homepage : void 0;
+	let resolved = {
+		name: normalizedName,
+		version,
+		releasedAt: versionEntry?.created_at || data.crate.updated_at || void 0,
+		description: versionEntry?.description || data.crate.description,
+		docsUrl: (() => {
+			if (documentation && !isUselessDocsUrl(documentation) && !isLikelyCodeHostUrl(documentation)) return documentation;
+			if (homepage && !isUselessDocsUrl(homepage) && !isLikelyCodeHostUrl(homepage)) return homepage;
+			return docsRsUrl;
+		})(),
+		repoUrl
+	};
+	const gh = repoUrl ? parseGitHubUrl(repoUrl) : null;
+	if (gh) {
+		onProgress?.("GitHub enrichment");
+		const ghResolved = await resolveGitHubRepo(gh.owner, gh.repo);
+		if (ghResolved) {
+			attempts.push({
+				source: "github-meta",
+				url: repoUrl,
+				status: "success",
+				message: "Enriched via GitHub repo metadata"
+			});
+			resolved = {
+				...ghResolved,
+				name: normalizedName,
+				version,
+				releasedAt: resolved.releasedAt || ghResolved.releasedAt,
+				description: resolved.description || ghResolved.description,
+				docsUrl: resolved.docsUrl || ghResolved.docsUrl,
+				repoUrl,
+				readmeUrl: ghResolved.readmeUrl || resolved.readmeUrl
+			};
+		} else attempts.push({
+			source: "github-meta",
+			url: repoUrl,
+			status: "not-found",
+			message: "GitHub enrichment failed, using crates.io metadata"
+		});
+	}
+	if (!resolved.llmsUrl && resolved.docsUrl) {
+		onProgress?.("llms.txt discovery");
+		resolved.llmsUrl = await fetchLlmsUrl(resolved.docsUrl).catch(() => null) ?? void 0;
+		if (resolved.llmsUrl) attempts.push({
+			source: "llms.txt",
+			url: resolved.llmsUrl,
+			status: "success"
+		});
+	}
+	return {
+		package: resolved,
+		attempts
+	};
+}
+const STATIC_REGEX_2 = /[_.:-]/;
+const STATIC_REGEX_3 = /\/+$/;
+async function fetchCrawledDocs(url, onProgress, maxPages = 200) {
+	const outputDir = join(tmpdir(), "skilld-crawl", Date.now().toString());
+	onProgress?.(`Crawling ${url}`);
+	const userLang = getUserLang();
+	const foreignUrls = /* @__PURE__ */ new Set();
+	const doCrawl = () => crawlAndGenerate({
+		urls: [url],
+		outputDir,
+		driver: "http",
+		generateLlmsTxt: false,
+		generateIndividualMd: true,
+		maxRequestsPerCrawl: maxPages,
+		onPage: (page) => {
+			const lang = extractHtmlLang(page.html);
+			if (lang && !lang.startsWith("en") && !lang.startsWith(userLang)) foreignUrls.add(page.url);
+		}
+	}, (progress) => {
+		if (progress.crawling.status === "processing" && progress.crawling.total > 0) onProgress?.(`Crawling ${progress.crawling.processed}/${progress.crawling.total} pages`);
+	});
+	let results = await doCrawl().catch((err) => {
+		onProgress?.(`Crawl failed: ${err?.message || err}`);
+		return [];
+	});
+	if (results.length === 0) {
+		onProgress?.("Retrying crawl");
+		results = await doCrawl().catch(() => []);
+	}
+	rmSync(outputDir, {
+		recursive: true,
+		force: true
+	});
+	const docs = [];
+	let localeFiltered = 0;
+	for (const result of results) {
+		if (!result.success || !result.content) continue;
+		if (foreignUrls.has(result.url)) {
+			localeFiltered++;
+			continue;
+		}
+		const segments = (new URL(result.url).pathname.replace(TRAILING_SLASH_RE, "") || "/index").split("/").filter(Boolean);
+		if (isForeignPathPrefix(segments[0], userLang)) {
+			localeFiltered++;
+			continue;
+		}
+		const path = `docs/${segments.join("/")}.md`;
+		docs.push({
+			path,
+			content: result.content
+		});
+	}
+	if (localeFiltered > 0) onProgress?.(`Filtered ${localeFiltered} foreign locale pages`);
+	onProgress?.(`Crawled ${docs.length} pages`);
+	return docs;
+}
+const HTML_LANG_RE = /<html[^>]*\slang=["']([^"']+)["']/i;
+function extractHtmlLang(html) {
+	return HTML_LANG_RE.exec(html)?.[1]?.toLowerCase();
+}
+const LOCALE_CODES = new Set([
+	"ar",
+	"de",
+	"es",
+	"fr",
+	"id",
+	"it",
+	"ja",
+	"ko",
+	"nl",
+	"pl",
+	"pt",
+	"pt-br",
+	"ru",
+	"th",
+	"tr",
+	"uk",
+	"vi",
+	"zh",
+	"zh-cn",
+	"zh-tw"
+]);
+function isForeignPathPrefix(segment, userLang) {
+	if (!segment) return false;
+	const lower = segment.toLowerCase();
+	if (lower === "en" || lower.startsWith(userLang)) return false;
+	return LOCALE_CODES.has(lower);
+}
+function getUserLang() {
+	const code = (process.env.LC_ALL || process.env.LANG || process.env.LANGUAGE || "").split(STATIC_REGEX_2)[0]?.toLowerCase() || "";
+	return code.length >= 2 ? code.slice(0, 2) : "en";
+}
+function toCrawlPattern(docsUrl) {
+	return `${docsUrl.replace(STATIC_REGEX_3, "")}/**`;
+}
+const HIGH_VALUE_CATEGORIES = new Set([
+	"q&a",
+	"help",
+	"troubleshooting",
+	"support"
+]);
+const LOW_VALUE_CATEGORIES = new Set([
+	"show and tell",
+	"ideas",
+	"polls"
+]);
+const TITLE_NOISE_RE = /looking .*(?:developer|engineer|freelanc)|hiring|job post|guide me to (?:complete|finish|build)|help me (?:complete|finish|build)|seeking .* tutorial|recommend.* course/i;
+const MIN_DISCUSSION_SCORE = 3;
+function scoreComment(c) {
+	return (c.isMaintainer ? 3 : 1) * (hasCodeBlock(c.body) ? 2 : 1) * (1 + c.reactions);
+}
+function scoreDiscussion(d) {
+	if (TITLE_NOISE_RE.test(d.title)) return -1;
+	let score = 0;
+	if (d.isMaintainer) score += 3;
+	if (hasCodeBlock([
+		d.body,
+		d.answer || "",
+		...d.topComments.map((c) => c.body)
+	].join("\n"))) score += 3;
+	score += Math.min(d.upvoteCount, 5);
+	if (d.answer) {
+		score += 2;
+		if (d.answer.length > 100) score += 1;
+	}
+	if (d.topComments.some((c) => c.isMaintainer)) score += 2;
+	if (d.topComments.some((c) => c.reactions > 0)) score += 1;
+	return score;
+}
+async function fetchGitHubDiscussions(owner, repo, limit = 20, releasedAt, fromDate) {
+	if (!isGhAvailable()) return [];
+	if (!fromDate && releasedAt) {
+		const cutoff = new Date(releasedAt);
+		cutoff.setMonth(cutoff.getMonth() + 6);
+		if (cutoff < /* @__PURE__ */ new Date()) return [];
+	}
+	try {
+		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: 10) { totalCount nodes { body author { login } authorAssociation reactions { totalCount } } } answer { body author { login } authorAssociation } author { login } authorAssociation } } } }`}`,
+			"-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 fromTs = fromDate ? new Date(fromDate).getTime() : null;
+		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);
+		}).filter((d) => !fromTs || new Date(d.createdAt).getTime() >= fromTs).map((d) => {
+			let answer;
+			if (d.answer?.body) {
+				const isMaintainer = [
+					"OWNER",
+					"MEMBER",
+					"COLLABORATOR"
+				].includes(d.answer.authorAssociation);
+				const author = d.answer.author?.login;
+				answer = `${isMaintainer && author ? `**@${author}** [maintainer]:\n\n` : ""}${d.answer.body}`;
+			}
+			const comments = (d.comments?.nodes || []).filter((c) => c.author && !BOT_USERS.has(c.author.login)).filter((c) => !COMMENT_NOISE_RE.test((c.body || "").trim())).map((c) => {
+				const isMaintainer = [
+					"OWNER",
+					"MEMBER",
+					"COLLABORATOR"
+				].includes(c.authorAssociation);
+				return {
+					body: c.body || "",
+					author: c.author.login,
+					reactions: c.reactions?.totalCount || 0,
+					isMaintainer
+				};
+			}).sort((a, b) => scoreComment(b) - scoreComment(a)).slice(0, 3);
+			return {
+				number: d.number,
+				title: d.title,
+				body: d.body || "",
+				category: d.category?.name || "",
+				createdAt: d.createdAt,
+				url: d.url,
+				upvoteCount: d.upvoteCount || 0,
+				comments: d.comments?.totalCount || 0,
+				isMaintainer: [
+					"OWNER",
+					"MEMBER",
+					"COLLABORATOR"
+				].includes(d.authorAssociation),
+				answer,
+				topComments: comments
+			};
+		}).map((d) => ({
+			d,
+			score: scoreDiscussion(d)
+		})).filter(({ score }) => score >= MIN_DISCUSSION_SCORE).sort((a, b) => {
+			const aHigh = HIGH_VALUE_CATEGORIES.has(a.d.category.toLowerCase()) ? 1 : 0;
+			const bHigh = HIGH_VALUE_CATEGORIES.has(b.d.category.toLowerCase()) ? 1 : 0;
+			if (aHigh !== bHigh) return bHigh - aHigh;
+			return b.score - a.score;
+		}).slice(0, limit).map(({ d }) => d);
+	} catch {
+		return [];
+	}
+}
+function formatDiscussionAsMarkdown(d) {
+	const fm = buildFrontmatter({
+		number: d.number,
+		title: d.title,
+		category: d.category,
+		created: isoDate(d.createdAt),
+		url: d.url,
+		upvotes: d.upvoteCount,
+		comments: d.comments,
+		answered: !!d.answer
+	});
+	const bodyLimit = d.upvoteCount >= 5 ? 1500 : 800;
+	const lines = [
+		fm,
+		"",
+		`# ${d.title}`
+	];
+	if (d.body) lines.push("", truncateBody(d.body, bodyLimit));
+	if (d.answer) lines.push("", "---", "", "## Accepted Answer", "", truncateBody(d.answer, 1e3));
+	else if (d.topComments.length > 0) {
+		lines.push("", "---", "", "## Top Comments");
+		for (const c of d.topComments) {
+			const reactions = c.reactions > 0 ? ` (+${c.reactions})` : "";
+			const maintainer = c.isMaintainer ? " [maintainer]" : "";
+			lines.push("", `**@${c.author}**${maintainer}${reactions}:`, "", truncateBody(c.body, 600));
+		}
+	}
+	return lines.join("\n");
+}
+function generateDiscussionIndex(discussions) {
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const d of discussions) mapInsert(byCategory, d.category || "Uncategorized", () => []).push(d);
+	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]" : "";
+			const date = isoDate(d.createdAt);
+			sections.push(`- [#${d.number}](./discussion-${d.number}.md): ${d.title}${upvotes}${answered} (${date})`);
+		}
+		sections.push("");
+	}
+	return sections.join("\n");
+}
+const STATIC_REGEX_1$4 = /\.md$/;
+function generateDocsIndex(docs) {
+	const docFiles = docs.filter((d) => d.path.startsWith("docs/") && d.path.endsWith(".md") && !d.path.endsWith("_INDEX.md")).sort((a, b) => a.path.localeCompare(b.path));
+	if (docFiles.length === 0) return "";
+	const rootFiles = [];
+	const byDir = /* @__PURE__ */ new Map();
+	for (const doc of docFiles) {
+		const rel = doc.path.slice(5);
+		const dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+		if (!dir) rootFiles.push(doc);
+		else {
+			const list = byDir.get(dir);
+			if (list) list.push(doc);
+			else byDir.set(dir, [doc]);
+		}
+	}
+	const sections = [
+		"---",
+		`total: ${docFiles.length}`,
+		"---",
+		"",
+		"# Docs Index",
+		""
+	];
+	for (const file of rootFiles) {
+		const rel = file.path.slice(5);
+		const title = extractTitle(file.content) || rel.replace(STATIC_REGEX_1$4, "");
+		const desc = extractDescription(file.content);
+		const descPart = desc ? `: ${desc}` : "";
+		sections.push(`- [${title}](./${rel})${descPart}`);
+	}
+	if (rootFiles.length > 0) sections.push("");
+	for (const [dir, files] of byDir) {
+		sections.push(`## ${dir} (${files.length})`, "");
+		for (const file of files) {
+			const rel = file.path.slice(5);
+			const title = extractTitle(file.content) || rel.replace(STATIC_REGEX_1$4, "").split("/").pop();
+			const desc = extractDescription(file.content);
+			const descPart = desc ? `: ${desc}` : "";
+			sections.push(`- [${title}](./${rel})${descPart}`);
+		}
+		sections.push("");
+	}
+	return sections.join("\n");
+}
+const SKIP_DIRS = [
+	"node_modules",
+	"_vendor",
+	"__tests__",
+	"__mocks__",
+	"__fixtures__",
+	"test",
+	"tests",
+	"fixture",
+	"fixtures",
+	"locales",
+	"locale",
+	"i18n",
+	".git"
+];
+const SKIP_PATTERNS = [
+	"*.min.*",
+	"*.prod.*",
+	"*.global.*",
+	"*.browser.*",
+	"*.map",
+	"*.map.js",
+	"CHANGELOG*",
+	"LICENSE*",
+	"README*"
+];
+const MAX_FILE_SIZE = 500 * 1024;
+async function resolveEntryFiles(packageDir) {
+	if (!existsSync(join(packageDir, "package.json"))) return [];
+	const skipDirSet = new Set(SKIP_DIRS);
+	const isSkipPattern = (name) => SKIP_PATTERNS.some((p) => {
+		const star = p.indexOf("*");
+		if (star === -1) return name === p;
+		const prefix = p.slice(0, star);
+		const suffix = p.slice(star + 1);
+		return name.startsWith(prefix) && name.endsWith(suffix);
+	});
+	const files = [];
+	for await (const file of glob(["**/*.d.{ts,mts,cts}"], {
+		cwd: packageDir,
+		exclude: (p) => {
+			const segs = p.split("/");
+			const last = segs[segs.length - 1];
+			if (isSkipPattern(last)) return true;
+			return segs.some((s) => skipDirSet.has(s));
+		}
+	})) files.push(file);
+	const entries = [];
+	for (const file of files) {
+		const absPath = join(packageDir, file);
+		let content;
+		try {
+			content = readFileSync(absPath, "utf-8");
+		} catch {
+			continue;
+		}
+		if (content.length > MAX_FILE_SIZE) continue;
+		entries.push({
+			path: file,
+			content,
+			type: "types"
+		});
+	}
+	return entries;
+}
+const STATIC_REGEX_1$3 = /^[\w.-]+\/[\w.-]+$/;
+function parseGitSkillInput(input) {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("@")) return null;
+	if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("/") || trimmed.startsWith("~")) return {
+		type: "local",
+		localPath: trimmed.startsWith("~") ? resolve(process.env.HOME || "", trimmed.slice(1)) : resolve(trimmed)
+	};
+	if (trimmed.startsWith("git@")) {
+		const gh = parseGitHubUrl(normalizeRepoUrl(trimmed));
+		if (gh) return {
+			type: "github",
+			owner: gh.owner,
+			repo: gh.repo
+		};
+		return null;
+	}
+	if (trimmed.startsWith("https://") || trimmed.startsWith("http://")) return parseGitUrl(trimmed);
+	if (STATIC_REGEX_1$3.test(trimmed)) return {
+		type: "github",
+		owner: trimmed.split("/")[0],
+		repo: trimmed.split("/")[1]
+	};
+	return null;
+}
+function parseGitUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (parsed.hostname === "github.com" || parsed.hostname === "www.github.com") {
+			const parts = parsed.pathname.replace(LEADING_SLASH_RE, "").replace(GIT_SUFFIX_RE, "").split("/");
+			const owner = parts[0];
+			const repo = parts[1];
+			if (!owner || !repo) return null;
+			if (parts[2] === "tree" && parts.length >= 4) return {
+				type: "github",
+				owner,
+				repo,
+				ref: parts[3],
+				skillPath: parts.length > 4 ? parts.slice(4).join("/") : void 0
+			};
+			return {
+				type: "github",
+				owner,
+				repo
+			};
+		}
+		if (parsed.hostname === "gitlab.com") {
+			const parts = parsed.pathname.replace(LEADING_SLASH_RE, "").replace(GIT_SUFFIX_RE, "").split("/");
+			const owner = parts[0];
+			const repo = parts[1];
+			if (!owner || !repo) return null;
+			return {
+				type: "gitlab",
+				owner,
+				repo
+			};
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+function parseSkillFrontmatterName(content) {
+	const fm = parseFrontmatter(content);
+	return {
+		name: fm.name,
+		description: fm.description
+	};
+}
+function findSkillDirs(root, prefix = "") {
+	const out = [];
+	if (!existsSync(root)) return out;
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const dir = resolve(root, entry.name);
+		const repoPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+		if (existsSync(resolve(dir, "SKILL.md"))) out.push({
+			dir,
+			repoPath
+		});
+		else out.push(...findSkillDirs(dir, repoPath));
+	}
+	return out;
+}
+function collectFiles(dir, prefix = "") {
+	const files = [];
+	if (!existsSync(dir)) return files;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+		const fullPath = resolve(dir, entry.name);
+		if (entry.isDirectory()) files.push(...collectFiles(fullPath, relPath));
+		else if (entry.isFile()) files.push({
+			path: relPath,
+			content: readFileSync(fullPath, "utf-8")
+		});
+	}
+	return files;
+}
+async function fetchGitSkills(source, onProgress) {
+	if (source.type === "local") return fetchLocalSkills(source);
+	if (source.type === "github") return fetchGitHubSkills(source, onProgress);
+	if (source.type === "gitlab") return fetchGitLabSkills(source, onProgress);
+	return { skills: [] };
+}
+function fetchLocalSkills(source) {
+	const base = source.localPath;
+	if (!existsSync(base)) return { skills: [] };
+	const skills = [];
+	const skillsDir = resolve(base, "skills");
+	if (existsSync(skillsDir)) for (const { dir, repoPath } of findSkillDirs(skillsDir, "skills")) {
+		const skill = readLocalSkill(dir, repoPath);
+		if (skill) skills.push(skill);
+	}
+	if (skills.length === 0) {
+		const skill = readLocalSkill(base, "");
+		if (skill) skills.push(skill);
+	}
+	return { skills };
+}
+function readLocalSkill(dir, repoPath) {
+	const skillMdPath = resolve(dir, "SKILL.md");
+	if (!existsSync(skillMdPath)) return null;
+	const content = readFileSync(skillMdPath, "utf-8");
+	const frontmatter = parseSkillFrontmatterName(content);
+	const dirName = dir.split("/").pop();
+	const name = frontmatter.name || dirName;
+	const files = collectFiles(dir).filter((f) => f.path !== "SKILL.md");
+	return {
+		name,
+		description: frontmatter.description || "",
+		path: repoPath,
+		content,
+		files
+	};
+}
+async function fetchGitHubSkills(source, onProgress) {
+	const { owner, repo } = source;
+	if (!owner || !repo) return { skills: [] };
+	const ref = source.ref || "main";
+	const refs = ref === "main" ? ["main", "master"] : [ref];
+	for (const tryRef of refs) {
+		const skills = await downloadGitHubSkills(owner, repo, tryRef, source.skillPath, onProgress);
+		if (skills.length > 0) return { skills };
+	}
+	return { skills: [] };
+}
+async function downloadGitHubSkills(owner, repo, ref, skillPath, onProgress) {
+	const tempDir = join(tmpdir(), `skilld-${Date.now()}`);
+	try {
+		if (skillPath) {
+			onProgress?.(`Downloading ${owner}/${repo}/${skillPath}@${ref}`);
+			const { dir } = await downloadTemplate(`github:${owner}/${repo}/${skillPath}#${ref}`, {
+				dir: tempDir,
+				force: true,
+				auth: getGitHubToken() || void 0
+			});
+			const skill = readLocalSkill(dir, skillPath);
+			return skill ? [skill] : [];
+		}
+		onProgress?.(`Downloading ${owner}/${repo}/skills@${ref}`);
+		try {
+			const { dir } = await downloadTemplate(`github:${owner}/${repo}/skills#${ref}`, {
+				dir: tempDir,
+				force: true,
+				auth: getGitHubToken() || void 0
+			});
+			const skills = [];
+			for (const { dir: skillDir, repoPath } of findSkillDirs(dir, "skills")) {
+				const skill = readLocalSkill(skillDir, repoPath);
+				if (skill) skills.push(skill);
+			}
+			if (skills.length > 0) {
+				onProgress?.(`Found ${skills.length} skill(s)`);
+				return skills;
+			}
+		} catch {}
+		const content = await fetchGitHubRaw(`https://raw.githubusercontent.com/${owner}/${repo}/${ref}/SKILL.md`);
+		if (content) {
+			const fm = parseSkillFrontmatterName(content);
+			onProgress?.("Found 1 skill");
+			return [{
+				name: fm.name || repo,
+				description: fm.description || "",
+				path: "",
+				content,
+				files: []
+			}];
+		}
+		return [];
+	} catch {
+		return [];
+	} finally {
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function fetchGitLabSkills(source, onProgress) {
+	const { owner, repo } = source;
+	if (!owner || !repo) return { skills: [] };
+	const ref = source.ref || "main";
+	const tempDir = join(tmpdir(), `skilld-gitlab-${Date.now()}`);
+	try {
+		const subdir = source.skillPath || "skills";
+		onProgress?.(`Downloading ${owner}/${repo}/${subdir}@${ref}`);
+		const { dir } = await downloadTemplate(`gitlab:${owner}/${repo}/${subdir}#${ref}`, {
+			dir: tempDir,
+			force: true
+		});
+		if (source.skillPath) {
+			const skill = readLocalSkill(dir, source.skillPath);
+			return { skills: skill ? [skill] : [] };
+		}
+		const skills = [];
+		for (const { dir: skillDir, repoPath } of findSkillDirs(dir, "skills")) {
+			const skill = readLocalSkill(skillDir, repoPath);
+			if (skill) skills.push(skill);
+		}
+		if (skills.length > 0) {
+			onProgress?.(`Found ${skills.length} skill(s)`);
+			return { skills };
+		}
+		const content = await $fetch(`https://gitlab.com/${owner}/${repo}/-/raw/${ref}/SKILL.md`, { responseType: "text" }).catch(() => null);
+		if (content) {
+			const fm = parseSkillFrontmatterName(content);
+			return { skills: [{
+				name: fm.name || repo,
+				description: fm.description || "",
+				path: "",
+				content,
+				files: []
+			}] };
+		}
+		return { skills: [] };
+	} catch {
+		return { skills: [] };
+	} finally {
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+const STATIC_REGEX_1$2 = /^[\^~>=<\d]/;
+function parseVersionSpecifier(name, version, cwd) {
+	if (version.startsWith("link:")) {
+		const linkedPkg = readPackageJsonSafe(join(resolve(cwd, version.slice(5)), "package.json"));
+		if (linkedPkg) return {
+			name: linkedPkg.parsed.name || name,
+			version: linkedPkg.parsed.version || "0.0.0"
+		};
+		return null;
+	}
+	if (version.startsWith("npm:")) {
+		const specifier = version.slice(4);
+		const atIndex = specifier.startsWith("@") ? specifier.indexOf("@", 1) : specifier.indexOf("@");
+		const realName = atIndex > 0 ? specifier.slice(0, atIndex) : specifier;
+		return {
+			name: realName,
+			version: resolveInstalledVersion(realName, cwd) || "*"
+		};
+	}
+	if (version.startsWith("file:") || version.startsWith("git:") || version.startsWith("git+")) return null;
+	const installed = resolveInstalledVersion(name, cwd);
+	if (installed) return {
+		name,
+		version: installed
+	};
+	if (STATIC_REGEX_1$2.test(version)) return {
+		name,
+		version: version.replace(VERSION_RANGE_PREFIX_RE, "")
+	};
+	if (version.startsWith("catalog:") || version.startsWith("workspace:")) return {
+		name,
+		version: "*"
+	};
+	return null;
+}
+function resolveInstalledVersion(name, cwd) {
+	const direct = readPackageJsonSafe(join(cwd, "node_modules", ...name.split("/"), "package.json"));
+	if (direct) return direct.parsed.version || null;
+	const req = createRequire(join(cwd, "package.json"));
+	try {
+		return readPackageJsonSafe(req.resolve(`${name}/package.json`))?.parsed.version || null;
+	} catch {
+		try {
+			let dir = dirname(req.resolve(name));
+			while (dir && basename(dir) !== "node_modules") {
+				const pkg = readPackageJsonSafe(join(dir, "package.json"));
+				if (pkg) return pkg.parsed.version || null;
+				const parent = dirname(dir);
+				if (parent === dir) break;
+				dir = parent;
+			}
+		} catch {}
+		return null;
+	}
+}
+async function readLocalDependencies(cwd) {
+	const result = readPackageJsonSafe(join(cwd, "package.json"));
+	if (!result) throw new Error("No package.json found in current directory");
+	const pkg = result.parsed;
+	const deps = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	};
+	const results = [];
+	for (const [name, version] of Object.entries(deps)) {
+		const parsed = parseVersionSpecifier(name, version, cwd);
+		if (parsed) results.push(parsed);
+	}
+	return results;
+}
+function readLocalPackageInfo(localPath) {
+	const result = readPackageJsonSafe(join(localPath, "package.json"));
+	if (!result) return null;
+	const pkg = result.parsed;
+	let repoUrl;
+	if (pkg.repository?.url) repoUrl = normalizeRepoUrl(pkg.repository.url);
+	else if (typeof pkg.repository === "string") repoUrl = normalizeRepoUrl(pkg.repository);
+	return {
+		name: pkg.name,
+		version: pkg.version || "0.0.0",
+		description: pkg.description,
+		repoUrl,
+		localPath
+	};
+}
+async function resolveLocalPackageDocs(localPath) {
+	const info = readLocalPackageInfo(localPath);
+	if (!info) return null;
+	const result = {
+		name: info.name,
+		version: info.version,
+		description: info.description,
+		repoUrl: info.repoUrl
+	};
+	if (info.repoUrl?.includes("github.com")) {
+		const gh = parseGitHubUrl(info.repoUrl);
+		if (gh) {
+			const gitDocs = await fetchGitDocs(gh.owner, gh.repo, info.version, info.name);
+			if (gitDocs) {
+				result.gitDocsUrl = gitDocs.baseUrl;
+				result.gitRef = gitDocs.ref;
+				result.gitDocsFallback = gitDocs.fallback;
+			}
+			const readmeUrl = await fetchReadme(gh.owner, gh.repo, void 0, result.gitRef);
+			if (readmeUrl) result.readmeUrl = readmeUrl;
+		}
+	}
+	if (!result.readmeUrl && !result.gitDocsUrl) {
+		const readmeFile = readdirSync(localPath).find((f) => README_FILENAME_RE.test(f));
+		if (readmeFile) result.readmeUrl = pathToFileURL(join(localPath, readmeFile)).href;
+	}
+	if (!result.readmeUrl && !result.gitDocsUrl) return null;
+	return result;
+}
+async function resolveLocalDep(packageName, cwd) {
+	const result = readPackageJsonSafe(join(cwd, "package.json"));
+	if (!result) return null;
+	const pkg = result.parsed;
+	const depVersion = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	}[packageName];
+	if (!depVersion?.startsWith("link:")) return null;
+	return resolveLocalPackageDocs(resolve(cwd, depVersion.slice(5)));
+}
+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) {
+	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 { name: barePackageName } = parsePackageSpec(packageName);
+	const data = await $fetch(`https://registry.npmjs.org/${barePackageName}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } }).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]
+	}])) : void 0;
+	return {
+		releasedAt: data.time?.[version] || void 0,
+		distTags
+	};
+}
+async function fetchPkgDist(name, version) {
+	const cacheDir = getCacheDir(name, version);
+	const pkgDir = join(cacheDir, "pkg");
+	if (existsSync(join(pkgDir, "package.json"))) return pkgDir;
+	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_USER_AGENT } }).catch(() => null);
+	if (!tarballRes?.ok || !tarballRes.body) return null;
+	mkdirSync(pkgDir, { recursive: true });
+	const tmpTarball = join(cacheDir, "_pkg.tgz");
+	const fileStream = createWriteStream(tmpTarball);
+	const fileClosed = new Promise((resolve) => fileStream.once("close", resolve));
+	const reader = tarballRes.body.getReader();
+	try {
+		await new Promise((res, reject) => {
+			const writable = new Writable({ write(chunk, _encoding, callback) {
+				fileStream.write(chunk, callback);
+			} });
+			writable.on("finish", () => {
+				fileStream.end();
+			});
+			fileStream.on("close", () => res());
+			writable.on("error", reject);
+			fileStream.on("error", reject);
+			function pump() {
+				reader.read().then(({ done, value }) => {
+					if (done) {
+						writable.end();
+						return;
+					}
+					writable.write(value, () => pump());
+				}).catch(reject);
+			}
+			pump();
+		});
+		const { status } = spawnSync("tar", [
+			"xzf",
+			tmpTarball,
+			"--strip-components=1",
+			"-C",
+			pkgDir
+		], { stdio: "ignore" });
+		if (status !== 0) {
+			rmSync(pkgDir, {
+				recursive: true,
+				force: true
+			});
+			return null;
+		}
+		return pkgDir;
+	} catch {
+		rmSync(pkgDir, {
+			recursive: true,
+			force: true
+		});
+		return null;
+	} finally {
+		reader.cancel().catch(() => {});
+		fileStream.destroy();
+		await fileClosed;
+		try {
+			rmSync(tmpTarball, { force: true });
+		} catch {}
+	}
+}
+async function fetchLatestVersion(packageName) {
+	const data = await $fetch(`https://unpkg.com/${packageName}/package.json`).catch(() => null);
+	if (data?.version) return data.version;
+	return (await $fetch(`https://registry.npmjs.org/${packageName}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } }).catch(() => null))?.["dist-tags"]?.latest || null;
+}
+const STATIC_REGEX_1$1 = /^[\w.-]+\/[\w.-]+/;
+function parseSkillInput(input) {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("npm:")) {
+		const { name, tag } = splitPackageTag(trimmed.slice(4));
+		return {
+			type: "npm",
+			package: name,
+			tag
+		};
+	}
+	if (trimmed.startsWith("crate:")) {
+		const rest = trimmed.slice(6).trim();
+		const atIdx = rest.indexOf("@");
+		return {
+			type: "crate",
+			package: (atIdx === -1 ? rest : rest.slice(0, atIdx)).toLowerCase(),
+			version: atIdx === -1 ? void 0 : rest.slice(atIdx + 1) || void 0
+		};
+	}
+	if (trimmed.startsWith("gh:") || trimmed.startsWith("github:")) {
+		const rest = trimmed.startsWith("gh:") ? trimmed.slice(3) : trimmed.slice(7);
+		const gitSource = parseGitSkillInput(rest);
+		if (gitSource) return {
+			type: "git",
+			source: gitSource
+		};
+		if (STATIC_REGEX_1$1.test(rest)) {
+			const [owner, repo] = rest.split("/");
+			return {
+				type: "git",
+				source: {
+					type: "github",
+					owner,
+					repo
+				}
+			};
+		}
+		return {
+			type: "bare",
+			package: rest
+		};
+	}
+	if (trimmed.startsWith("@")) {
+		const rest = trimmed.slice(1);
+		if (rest.indexOf("/") === -1) return {
+			type: "curator",
+			handle: rest
+		};
+		const { name, tag } = splitPackageTag(trimmed);
+		return {
+			type: "bare",
+			package: name,
+			tag
+		};
+	}
+	const gitSource = parseGitSkillInput(trimmed);
+	if (gitSource) return {
+		type: "git",
+		source: gitSource
+	};
+	const { name, tag } = splitPackageTag(trimmed);
+	return {
+		type: "bare",
+		package: name,
+		tag
+	};
+}
+function resolveSkillName(input) {
+	const source = parseSkillInput(input);
+	switch (source.type) {
+		case "npm":
+		case "bare": return source.package;
+		case "crate": return `crate:${source.package}`;
+		case "git":
+			if (source.source.type === "github" && source.source.repo) return source.source.repo;
+			return null;
+		case "curator":
+		case "collection": return null;
+		default: throw new Error(`Unhandled SkillSource type: ${JSON.stringify(source)}`);
+	}
+}
+function toStoragePackageName(identityName) {
+	if (identityName.startsWith("crate:")) return `@skilld-crate/${identityName.slice(6)}`;
+	return identityName;
+}
+function isCrateSpec(spec) {
+	return spec.startsWith("crate:");
+}
+function toCrateIdentity(crateName) {
+	return `crate:${crateName}`;
+}
+function splitPackageTag(spec) {
+	if (spec.startsWith("@")) {
+		const slashIdx = spec.indexOf("/");
+		if (slashIdx !== -1) {
+			const afterSlash = spec.indexOf("@", slashIdx);
+			if (afterSlash !== -1) return {
+				name: spec.slice(0, afterSlash),
+				tag: spec.slice(afterSlash + 1) || void 0
+			};
+		}
+		return { name: spec };
+	}
+	const atIdx = spec.indexOf("@");
+	if (atIdx !== -1) return {
+		name: spec.slice(0, atIdx),
+		tag: spec.slice(atIdx + 1) || void 0
+	};
+	return { name: spec };
+}
+const crawlUrlResolver = defineResolver({
+	id: "crawl",
+	canResolve: (ctx) => !!ctx.result,
+	async run(ctx) {
+		const crawlUrl = getCrawlUrl(ctx.packageName);
+		if (crawlUrl) ctx.result.crawlUrl = crawlUrl;
+		return { kind: "ok" };
+	}
+});
+const gitTagResolver = defineResolver({
+	id: "github-docs",
+	canResolve: (ctx) => !!ctx.result?.repoUrl?.includes("github.com"),
+	async run(ctx) {
+		const result = ctx.result;
+		const gh = parseGitHubUrl(result.repoUrl);
+		if (!gh) return { kind: "skip" };
+		const targetVersion = ctx.options.version || ctx.npm?.version;
+		if (!targetVersion) return { kind: "skip" };
+		ctx.options.onProgress?.("github-docs");
+		const gitDocs = await fetchGitDocs(gh.owner, gh.repo, targetVersion, ctx.packageName, ctx.rawRepoUrl);
+		if (gitDocs) {
+			result.gitDocsUrl = gitDocs.baseUrl;
+			result.gitRef = gitDocs.ref;
+			result.gitDocsFallback = gitDocs.fallback;
+			ctx.gitDocsAllFiles = gitDocs.allFiles;
+			ctx.attempts.push({
+				source: "github-docs",
+				url: gitDocs.baseUrl,
+				status: "success",
+				message: gitDocs.fallback ? `Found ${gitDocs.files.length} docs at ${gitDocs.ref} (no tag for v${targetVersion})` : `Found ${gitDocs.files.length} docs at ${gitDocs.ref}`
+			});
+			return { kind: "ok" };
+		}
+		ctx.attempts.push({
+			source: "github-docs",
+			url: `${result.repoUrl}/tree/v${targetVersion}/docs`,
+			status: "not-found",
+			message: "No docs/ folder found at version tag"
+		});
+		return { kind: "skip" };
+	}
+});
+const githubMetaResolver = defineResolver({
+	id: "github-meta",
+	canResolve: (ctx) => !!ctx.result?.repoUrl?.includes("github.com") && !ctx.result.docsUrl,
+	async run(ctx) {
+		const result = ctx.result;
+		const gh = parseGitHubUrl(result.repoUrl);
+		if (!gh) return { kind: "skip" };
+		ctx.options.onProgress?.("github-meta");
+		const repoMeta = await fetchGitHubRepoMeta(gh.owner, gh.repo, ctx.packageName);
+		if (repoMeta?.homepage && !isUselessDocsUrl(repoMeta.homepage)) {
+			result.docsUrl = repoMeta.homepage;
+			ctx.attempts.push({
+				source: "github-meta",
+				url: result.repoUrl,
+				status: "success",
+				message: `Found homepage: ${repoMeta.homepage}`
+			});
+			return { kind: "ok" };
+		}
+		ctx.attempts.push({
+			source: "github-meta",
+			url: result.repoUrl,
+			status: "not-found",
+			message: "No homepage in repo metadata"
+		});
+		return { kind: "skip" };
+	}
+});
+const githubReadmeResolver = defineResolver({
+	id: "readme",
+	canResolve: (ctx) => !!ctx.result?.repoUrl?.includes("github.com"),
+	async run(ctx) {
+		const result = ctx.result;
+		const gh = parseGitHubUrl(result.repoUrl);
+		if (!gh) return { kind: "skip" };
+		ctx.options.onProgress?.("readme");
+		const readmeUrl = await fetchReadme(gh.owner, gh.repo, ctx.subdir, result.gitRef);
+		if (readmeUrl) {
+			result.readmeUrl = readmeUrl;
+			ctx.attempts.push({
+				source: "readme",
+				url: readmeUrl,
+				status: "success"
+			});
+			return { kind: "ok" };
+		}
+		ctx.attempts.push({
+			source: "readme",
+			url: `${result.repoUrl}/README.md`,
+			status: "not-found",
+			message: "No README found"
+		});
+		return { kind: "skip" };
+	}
+});
+const githubSearchResolver = defineResolver({
+	id: "github-search",
+	canResolve: (ctx) => !!ctx.result && !ctx.result.repoUrl,
+	async run(ctx) {
+		const result = ctx.result;
+		ctx.options.onProgress?.("github-search");
+		const searchedUrl = await searchGitHubRepo(ctx.packageName);
+		if (searchedUrl) {
+			result.repoUrl = searchedUrl;
+			ctx.attempts.push({
+				source: "github-search",
+				url: searchedUrl,
+				status: "success",
+				message: `Found via GitHub search: ${searchedUrl}`
+			});
+			return { kind: "ok" };
+		}
+		ctx.attempts.push({
+			source: "github-search",
+			status: "not-found",
+			message: "No repository URL in package.json and GitHub search found no match"
+		});
+		return { kind: "skip" };
+	}
+});
+const llmsTxtResolver = defineResolver({
+	id: "llms.txt",
+	canResolve: (ctx) => !!ctx.result?.docsUrl,
+	async run(ctx) {
+		const result = ctx.result;
+		ctx.options.onProgress?.("llms.txt");
+		const llmsUrl = await fetchLlmsUrl(result.docsUrl);
+		if (llmsUrl) {
+			result.llmsUrl = llmsUrl;
+			ctx.attempts.push({
+				source: "llms.txt",
+				url: llmsUrl,
+				status: "success"
+			});
+		} else ctx.attempts.push({
+			source: "llms.txt",
+			url: `${new URL(result.docsUrl).origin}/llms.txt`,
+			status: "not-found",
+			message: "No llms.txt at docs URL"
+		});
+		if (result.gitDocsUrl && result.llmsUrl && ctx.gitDocsAllFiles) {
+			const llmsContent = await fetchLlmsTxt(result.llmsUrl);
+			if (llmsContent && llmsContent.links.length > 0) {
+				const validation = validateGitDocsWithLlms(llmsContent.links, ctx.gitDocsAllFiles);
+				if (!validation.isValid) {
+					ctx.attempts.push({
+						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`
+					});
+					result.gitDocsUrl = void 0;
+					result.gitRef = void 0;
+				}
+			}
+		}
+		return { kind: "ok" };
+	}
+});
+const localReadmeResolver = defineResolver({
+	id: "local",
+	canResolve: (ctx) => {
+		const r = ctx.result;
+		return !!r && !!ctx.options.cwd && !r.docsUrl && !r.llmsUrl && !r.readmeUrl && !r.gitDocsUrl;
+	},
+	async run(ctx) {
+		const result = ctx.result;
+		ctx.options.onProgress?.("local");
+		const pkgDir = join(ctx.options.cwd, "node_modules", ctx.packageName);
+		const readmeFile = existsSync(pkgDir) && readdirSync(pkgDir).find((f) => README_FILENAME_RE.test(f));
+		if (readmeFile) {
+			const readmePath = join(pkgDir, readmeFile);
+			result.readmeUrl = pathToFileURL(readmePath).href;
+			ctx.attempts.push({
+				source: "readme",
+				url: readmePath,
+				status: "success",
+				message: "Found local readme in node_modules"
+			});
+			return { kind: "ok" };
+		}
+		return { kind: "skip" };
+	}
+});
+const STATIC_REGEX_1 = /^github:/;
+const defaultResolvers = [
+	defineResolver({
+		id: "npm",
+		async run(ctx) {
+			ctx.options.onProgress?.("npm");
+			const pkg = await fetchNpmPackage(ctx.packageName);
+			if (!pkg) {
+				ctx.attempts.push({
+					source: "npm",
+					url: `https://registry.npmjs.org/${ctx.packageName}/latest`,
+					status: "not-found",
+					message: "Package not found on npm registry"
+				});
+				return { kind: "fatal" };
+			}
+			ctx.attempts.push({
+				source: "npm",
+				url: `https://registry.npmjs.org/${ctx.packageName}/latest`,
+				status: "success",
+				message: `Found ${pkg.name}@${pkg.version}`
+			});
+			const registryMeta = pkg.version ? await fetchNpmRegistryMeta(ctx.packageName, pkg.version) : {};
+			const result = {
+				name: pkg.name,
+				version: pkg.version,
+				releasedAt: registryMeta.releasedAt,
+				description: pkg.description,
+				dependencies: pkg.dependencies,
+				distTags: registryMeta.distTags
+			};
+			if (typeof pkg.repository === "object" && pkg.repository?.url) {
+				ctx.rawRepoUrl = pkg.repository.url;
+				const normalized = normalizeRepoUrl(pkg.repository.url);
+				if (!normalized.includes("://") && normalized.includes("/") && !normalized.includes(":")) result.repoUrl = `https://github.com/${normalized}`;
+				else result.repoUrl = normalized;
+				ctx.subdir = pkg.repository.directory;
+			} 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(STATIC_REGEX_1, "");
+				if (repo.includes("/") && !repo.includes(":")) result.repoUrl = `https://github.com/${repo}`;
+			}
+			if (pkg.homepage && !isGitHubRepoUrl(pkg.homepage) && !isUselessDocsUrl(pkg.homepage)) result.docsUrl = pkg.homepage;
+			ctx.npm = pkg;
+			ctx.result = result;
+			return { kind: "ok" };
+		}
+	}),
+	githubSearchResolver,
+	gitTagResolver,
+	githubMetaResolver,
+	githubReadmeResolver,
+	crawlUrlResolver,
+	llmsTxtResolver,
+	localReadmeResolver
+];
+function defineResolver(r) {
+	return r;
+}
+function createContentResolver(opts) {
+	return { async resolve(packageName, options = {}) {
+		const ctx = {
+			packageName,
+			options,
+			result: null,
+			attempts: []
+		};
+		let registryVersion;
+		for (const resolver of opts.resolvers) {
+			if (resolver.canResolve && !resolver.canResolve(ctx)) continue;
+			const outcome = await resolver.run(ctx);
+			if (outcome.kind === "fatal") return {
+				package: null,
+				attempts: ctx.attempts,
+				registryVersion: outcome.registryVersion ?? registryVersion
+			};
+		}
+		registryVersion = ctx.npm?.version;
+		const r = ctx.result;
+		if (!r || !r.docsUrl && !r.llmsUrl && !r.readmeUrl && !r.gitDocsUrl) return {
+			package: null,
+			attempts: ctx.attempts,
+			registryVersion
+		};
+		return {
+			package: r,
+			attempts: ctx.attempts,
+			registryVersion
+		};
+	} };
+}
+const defaultContentResolver = createContentResolver({ resolvers: defaultResolvers });
+async function resolvePackageDocs(packageName, options = {}) {
+	return (await defaultContentResolver.resolve(packageName, options)).package;
+}
+async function resolvePackageDocsWithAttempts(packageName, options = {}) {
+	return defaultContentResolver.resolve(packageName, options);
+}
+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"
+};
+async function resolvePackageOrCrate(packageSpec, opts) {
+	const { cwd, onProgress } = opts;
+	const isCrate = isCrateSpec(packageSpec);
+	const normalizedSpec = isCrate ? packageSpec.slice(6).trim() : packageSpec;
+	const { name: parsedName, tag: requestedTag } = parsePackageSpec(normalizedSpec);
+	const packageName = isCrate ? parsedName.toLowerCase() : parsedName;
+	const identityPackageName = isCrate ? toCrateIdentity(packageName) : packageName;
+	const storagePackageName = toStoragePackageName(identityPackageName);
+	const localDeps = isCrate ? [] : await readLocalDependencies(cwd).catch(() => []);
+	const localVersion = isCrate ? void 0 : localDeps.find((d) => d.name === packageName)?.version;
+	const resolveResult = isCrate ? await resolveCrateDocsWithAttempts(packageName, {
+		version: requestedTag,
+		onProgress
+	}) : await resolvePackageDocsWithAttempts(requestedTag ? normalizedSpec : packageName, {
+		version: localVersion,
+		cwd,
+		onProgress: (step) => onProgress?.(RESOLVE_STEP_LABELS[step] ?? step)
+	});
+	let resolved = resolveResult.package;
+	if (!resolved && !isCrate) {
+		onProgress?.(RESOLVE_STEP_LABELS.local);
+		resolved = await resolveLocalDep(packageName, cwd);
+	}
+	return {
+		packageName,
+		identityPackageName,
+		storagePackageName,
+		isCrate,
+		requestedTag,
+		localVersion,
+		resolved,
+		attempts: resolveResult.attempts,
+		registryVersion: resolveResult.registryVersion
+	};
+}
 function semverValid(v) {
 	return valid(v, true);
 }
@@ -8,6 +2762,6 @@ function semverGt(a, b) {
 function semverDiff(a, b) {
 	return diff(a, b);
 }
-export { semverGt as n, semverValid as r, semverDiff as t };
+export { fetchGitHubIssues as A, fetchBlogReleases as B, fetchCrawledDocs as C, downloadLlmsDocs as D, resolveGitHubRepo as E, filterFrameworkDocs as F, generateReleaseIndex as H, isShallowGitDocs as I, parseGitHubRepoSlug as L, generateIssueIndex as M, isGhAvailable as N, fetchLlmsTxt as O, fetchGitDocs as P, parseGitHubUrl as R, generateDiscussionIndex as S, fetchReadmeContent as T, isPrerelease as U, fetchReleaseNotes as V, fetchGitHubRaw as W, fetchGitSkills as _, resolvePackageDocs as a, fetchGitHubDiscussions as b, resolveSkillName as c, fetchNpmPackage as d, fetchNpmRegistryMeta as f, readLocalPackageInfo as g, readLocalDependencies as h, resolvePackageOrCrate as i, formatIssueAsMarkdown as j, normalizeLlmsLinks as k, toStoragePackageName as l, searchNpmPackages as m, semverGt as n, isCrateSpec as o, fetchPkgDist as p, semverValid as r, parseSkillInput as s, semverDiff as t, fetchLatestVersion as u, resolveEntryFiles as v, toCrawlPattern as w, formatDiscussionAsMarkdown as x, generateDocsIndex as y, parsePackageSpec as z };
 
 //# sourceMappingURL=semver.mjs.map