skilld 1.7.4 → 2.0.0

package/dist/_chunks/{sync-pipeline.mjs → pipeline.mjs}

@@ -1,20 +1,19 @@
-import { l as getPackageDbPath, p as skillInternalDir, u as getRepoCacheDir } from "./paths.mjs";
-import { L as updateConfig, P as readConfig, b as writeToRepoCache, h as listReferenceFiles, k as defaultFeatures, t as createReferenceCache, y as writeToCache } from "./cache.mjs";
-import { t as getCacheDir } from "./version.mjs";
-import { r as resolvePkgDir } from "./prepare.mjs";
+import { a as getModelName, i as getModelLabel, o as createToolProgress, r as getAvailableModels, t as optimizeDocs } from "./agent.mjs";
+import { C as SECTION_OUTPUT_FILES, E as getBlogPreset, S as SECTION_MERGE_ORDER, T as maxLines, _ as buildAllSectionPrompts, k as getPrereleaseChangelogRef, t as writeGeneratedSkillMd, w as maxItems, x as wrapSection } from "./prompts.mjs";
+import { d as getRepoCacheDir, m as skillInternalDir, u as getPackageDbPath } from "./paths.mjs";
 import { n as sanitizeMarkdown } from "./sanitize.mjs";
+import { a as resolvePkgDir, s as getCacheDir } from "./prepare.mjs";
+import { a as writeToRepoCache, d as readConfig, i as listReferenceFiles, m as updateConfig, o as defaultFeatures, t as createReferenceCache } from "./cache.mjs";
+import { t as isInteractive } from "./env.mjs";
+import { r as pickModel, t as NO_MODELS_MESSAGE } from "./model-picker.mjs";
+import { A as fetchGitHubIssues, B as fetchBlogReleases, C as fetchCrawledDocs, D as downloadLlmsDocs, F as filterFrameworkDocs, H as generateReleaseIndex, I as isShallowGitDocs, M as generateIssueIndex, N as isGhAvailable, O as fetchLlmsTxt, P as fetchGitDocs, R as parseGitHubUrl, S as generateDiscussionIndex, T as fetchReadmeContent, U as isPrerelease, V as fetchReleaseNotes, W as fetchGitHubRaw, b as fetchGitHubDiscussions, d as fetchNpmPackage, j as formatIssueAsMarkdown, k as normalizeLlmsLinks, t as semverDiff, v as resolveEntryFiles, w as toCrawlPattern, x as formatDiscussionAsMarkdown, y as generateDocsIndex } from "./semver.mjs";
 import { i as parseFrontmatter } from "./markdown.mjs";
-import { o as listIndexIds, r as createIndex, t as SearchDepsUnavailableError } from "./retriv.mjs";
-import { o as getPrereleaseChangelogRef, t as getBlogPreset } from "./package-registry.mjs";
-import { $ as fetchReleaseNotes, C as resolveEntryFiles, D as generateDiscussionIndex, E as formatDiscussionAsMarkdown, F as downloadLlmsDocs, H as formatIssueAsMarkdown, J as isShallowGitDocs, K as fetchGitDocs, L as fetchLlmsTxt, N as fetchReadmeContent, O as fetchCrawledDocs, T as fetchGitHubDiscussions, U as generateIssueIndex, V as fetchGitHubIssues, W as isGhAvailable, Z as fetchBlogReleases, at as fetchGitHubRaw, et as generateReleaseIndex, k as toCrawlPattern, q as filterFrameworkDocs, s as fetchNpmPackage, tt as isPrerelease, ut as parseGitHubUrl, w as generateDocsIndex, z as normalizeLlmsLinks } from "./sources.mjs";
-import { a as getModelName, i as getModelLabel, o as createToolProgress, r as getAvailableModels, t as optimizeDocs } from "./agent.mjs";
-import { D as maxItems, E as SECTION_OUTPUT_FILES, O as maxLines, T as SECTION_MERGE_ORDER, n as writeGeneratedSkillMd, w as wrapSection, y as buildAllSectionPrompts } from "./prompts.mjs";
-import { g as pickModel, n as NO_MODELS_MESSAGE, p as isInteractive } from "./cli-helpers.mjs";
 import { c as readLock, t as buildPackageDirMap } from "./lockfile.mjs";
-import { t as semverDiff } from "./semver.mjs";
+import { a as listIndexIds, r as createIndex, t as SearchDepsUnavailableError } from "./retriv2.mjs";
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
-import { join, relative } from "pathe";
+import { styleText } from "node:util";
 import * as p from "@clack/prompts";
+import { join, relative } from "pathe";
 const RATE_LIMIT_RE = /\b429\b|rate.?limit|exhausted.*capacity|quota.*reset/i;
 async function runSkillEnhancement(ctx, run, onProgress) {
 	const { packageName, cachePackageName, version, skillDir, dirName, resolved, relatedSkills, references, packages, features, overheadLines } = ctx;
@@ -81,8 +80,8 @@ async function enhanceSkillWithLLM(ctx, run) {
 		const costSuffix = costParts.length > 0 ? ` (${costParts.join(", ")})` : "";
 		llmLog.success(`Generated best practices${costSuffix}`);
 		if (debugLogsDir) p.log.info(`Debug logs: ${relative(process.cwd(), debugLogsDir)}`);
-		if (error) p.log.warn(`\x1B[33mPartial failure: ${error}\x1B[0m`);
-		if (warnings?.length) for (const w of warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
+		if (error) p.log.warn(styleText("yellow", `Partial failure: ${error}`));
+		if (warnings?.length) for (const w of warnings) p.log.warn(styleText("yellow", w));
 	} else if (error && RATE_LIMIT_RE.test(error)) llmLog.error(`Rate limited by LLM provider. Try again shortly or use a different model via \`skilld config\``);
 	else llmLog.error(`Enhancement failed${error ? `: ${error}` : ""}`);
 }
@@ -156,7 +155,7 @@ function writePromptFiles(ctx, run) {
 		const relDir = relative(process.cwd(), skillDir);
 		const promptFiles = written.map((s) => `PROMPT_${s}.md`).join(", ");
 		const outputFileList = written.map((s) => SECTION_OUTPUT_FILES[s]).join(", ");
-		p.log.info(`Prompt files written to ${relDir}/.skilld/\n\x1B[2m\x1B[3m  Read each prompt file (${promptFiles}) in ${relDir}/.skilld/, read the\n  referenced files, then write your output to the matching file (${outputFileList}).\n  When done, run: skilld assemble\x1B[0m`);
+		p.log.info(`Prompt files written to ${relDir}/.skilld/\n${styleText(["dim", "italic"], `  Read each prompt file (${promptFiles}) in ${relDir}/.skilld/, read the\n  referenced files, then write your output to the matching file (${outputFileList}).\n  When done, run: skilld assemble`)}`);
 	}
 	return written;
 }
@@ -265,7 +264,7 @@ async function selectLlmConfig(presetModel, message, updateCtx) {
 	let defaultModel;
 	if (config.model && available.some((m) => m.id === config.model)) defaultModel = config.model;
 	else {
-		if (config.model) p.log.warn(`Configured model \x1B[36m${config.model}\x1B[0m is unavailable — using auto-selected fallback`);
+		if (config.model) p.log.warn(`Configured model ${styleText("cyan", config.model)} is unavailable — using auto-selected fallback`);
 		defaultModel = available.find((m) => m.recommended)?.id ?? available[0].id;
 	}
 	const defaultModelName = getModelName(defaultModel);
@@ -288,7 +287,7 @@ async function selectLlmConfig(presetModel, message, updateCtx) {
 		}
 		if (updateCtx.wasEnhanced) ageParts.push("LLM-enhanced");
 		const hint = [updateCtx.oldVersion && updateCtx.newVersion ? `${updateCtx.oldVersion} → ${updateCtx.newVersion}` : null, ...ageParts].filter(Boolean).join(" · ");
-		if (hint) enhanceMessage = `Enhance SKILL.md? \x1B[90m(${hint})\x1B[0m`;
+		if (hint) enhanceMessage = `Enhance SKILL.md? ${styleText("gray", `(${hint})`)}`;
 		if (updateCtx.wasEnhanced && isSmallBump) defaultToSkip = true;
 	}
 	const choice = await p.select({
@@ -448,241 +447,374 @@ async function indexResources(opts) {
 		else throw err;
 	}
 }
-async function resolveContentDocs(opts) {
-	const { packageName, resolved, version, onProgress } = opts;
-	const docs = [];
-	const docsToIndex = [];
-	const warnings = [];
-	let docSource = resolved.readmeUrl || "readme";
-	let docsType = "readme";
-	const isFrameworkDoc = (path) => filterFrameworkDocs([path], packageName).length > 0;
-	if (resolved.gitDocsUrl && resolved.repoUrl) {
-		const gh = parseGitHubUrl(resolved.repoUrl);
-		if (gh) {
-			const r = await tryGitDocs({
-				owner: gh.owner,
-				repo: gh.repo,
-				version,
-				packageName,
-				repoUrl: resolved.repoUrl,
-				llmsUrl: resolved.llmsUrl,
-				docsUrl: resolved.docsUrl,
-				onProgress
-			});
-			if (r) {
-				docs.push(...r.docs);
-				docsToIndex.push(...r.docsToIndex);
-				if (r.warning) warnings.push(r.warning);
-				if (r.kind === "git") {
-					docSource = r.docSource;
-					docsType = "docs";
+function defineStep(step) {
+	return step;
+}
+async function walkSteps(steps, ctx) {
+	for (const step of steps) {
+		if (step.canResolve && !step.canResolve(ctx)) continue;
+		await step.run(ctx);
+	}
+}
+const crawlUrlStep = defineStep({
+	id: "crawl-url",
+	canResolve: (ctx) => !!ctx.resolved.crawlUrl && ctx.docs.length === 0,
+	async run(ctx) {
+		const crawlUrl = ctx.resolved.crawlUrl;
+		ctx.onProgress("Crawling website");
+		const crawled = await fetchCrawledDocs(crawlUrl, ctx.onProgress).catch((err) => {
+			ctx.warnings.push(`Crawl failed for ${crawlUrl}: ${err?.message || err}`);
+			return [];
+		});
+		if (crawled.length === 0) ctx.warnings.push(`Crawl returned 0 docs from ${crawlUrl}`);
+		let added = 0;
+		for (const doc of crawled) {
+			if (!ctx.isFrameworkDoc(doc.path)) continue;
+			ctx.docs.push(doc);
+			ctx.docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: ctx.packageName,
+					source: doc.path,
+					type: "doc"
 				}
-			}
+			});
+			added++;
+		}
+		if (added > 0) {
+			ctx.docSource = crawlUrl;
+			ctx.docsType = "docs";
 		}
 	}
-	if (resolved.crawlUrl && docs.length === 0) {
-		onProgress("Crawling website");
-		const crawled = await fetchCrawledDocs(resolved.crawlUrl, onProgress).catch((err) => {
-			warnings.push(`Crawl failed for ${resolved.crawlUrl}: ${err?.message || err}`);
+});
+const docsCrawlStep = defineStep({
+	id: "docs-crawl",
+	canResolve: (ctx) => !!ctx.resolved.docsUrl && !ctx.docs.some((d) => d.path.startsWith("docs/")),
+	async run(ctx) {
+		const crawlPattern = ctx.resolved.crawlUrl || toCrawlPattern(ctx.resolved.docsUrl);
+		ctx.onProgress("Crawling docs site");
+		const maxPages = ctx.resolved.crawlUrl ? 200 : 400;
+		const crawled = await fetchCrawledDocs(crawlPattern, ctx.onProgress, maxPages).catch((err) => {
+			ctx.warnings.push(`Crawl failed for ${crawlPattern}: ${err?.message || err}`);
 			return [];
 		});
-		if (crawled.length === 0) warnings.push(`Crawl returned 0 docs from ${resolved.crawlUrl}`);
+		let added = 0;
 		for (const doc of crawled) {
-			if (!isFrameworkDoc(doc.path)) continue;
-			docs.push(doc);
-			docsToIndex.push({
+			if (!ctx.isFrameworkDoc(doc.path)) continue;
+			ctx.docs.push(doc);
+			ctx.docsToIndex.push({
 				id: doc.path,
 				content: doc.content,
 				metadata: {
-					package: packageName,
+					package: ctx.packageName,
 					source: doc.path,
 					type: "doc"
 				}
 			});
+			added++;
 		}
-		if (docs.length > 0) {
-			docSource = resolved.crawlUrl;
-			docsType = "docs";
+		if (added > 0) {
+			ctx.docSource = crawlPattern;
+			ctx.docsType = "docs";
 		}
 	}
-	if (resolved.llmsUrl && docs.length === 0) {
-		onProgress("Fetching llms.txt");
-		const llmsContent = await fetchLlmsTxt(resolved.llmsUrl);
-		if (llmsContent) {
-			docSource = resolved.llmsUrl;
-			docsType = "llms.txt";
-			const baseUrl = resolved.docsUrl || new URL(resolved.llmsUrl).origin;
-			docs.push({
+});
+const BATCH_SIZE = 20;
+const defaultContentSteps = [
+	defineStep({
+		id: "git-docs",
+		canResolve: (ctx) => !!ctx.resolved.gitDocsUrl && !!ctx.resolved.repoUrl,
+		async run(ctx) {
+			const gh = parseGitHubUrl(ctx.resolved.repoUrl);
+			if (!gh) return;
+			ctx.onProgress("Fetching git docs");
+			const gitDocs = await fetchGitDocs(gh.owner, gh.repo, ctx.version, ctx.packageName);
+			if (!gitDocs || gitDocs.files.length === 0) return;
+			if (gitDocs.fallback) ctx.warnings.push(`Docs fetched from ${gitDocs.ref} branch (no tag found for v${ctx.version})`);
+			const results = [];
+			for (let i = 0; i < gitDocs.files.length; i += BATCH_SIZE) {
+				const batch = gitDocs.files.slice(i, i + BATCH_SIZE);
+				ctx.onProgress(`Downloading docs ${Math.min(i + BATCH_SIZE, gitDocs.files.length)}/${gitDocs.files.length} from ${gitDocs.ref}`);
+				const batchResults = await Promise.all(batch.map(async (file) => {
+					const content = await fetchGitHubRaw(`${gitDocs.baseUrl}/${file}`);
+					return content ? {
+						file,
+						content
+					} : null;
+				}));
+				results.push(...batchResults);
+			}
+			const docs = [];
+			const docsToIndex = [];
+			for (const r of results) {
+				if (!r) continue;
+				const stripped = gitDocs.docsPrefix ? r.file.replace(gitDocs.docsPrefix, "") : r.file;
+				const cachePath = stripped.startsWith("docs/") ? stripped : `docs/${stripped}`;
+				docs.push({
+					path: cachePath,
+					content: r.content
+				});
+				docsToIndex.push({
+					id: cachePath,
+					content: r.content,
+					metadata: {
+						package: ctx.packageName,
+						source: cachePath,
+						type: "doc"
+					}
+				});
+			}
+			if (isShallowGitDocs(docs.length) && ctx.resolved.llmsUrl) {
+				ctx.onProgress(`Shallow git-docs (${docs.length} files), trying llms.txt`);
+				return;
+			}
+			ctx.docs.push(...docs);
+			ctx.docsToIndex.push(...docsToIndex);
+			ctx.docSource = `${ctx.resolved.repoUrl}/tree/${gitDocs.ref}/docs`;
+			ctx.docsType = "docs";
+			if (ctx.resolved.llmsUrl) {
+				ctx.onProgress("Caching supplementary llms.txt");
+				const llmsContent = await fetchLlmsTxt(ctx.resolved.llmsUrl);
+				if (llmsContent) {
+					const baseUrl = ctx.resolved.docsUrl || new URL(ctx.resolved.llmsUrl).origin;
+					ctx.docs.push({
+						path: "llms.txt",
+						content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+					});
+					if (llmsContent.links.length > 0) {
+						ctx.onProgress(`Downloading ${llmsContent.links.length} supplementary docs`);
+						const supplementary = await downloadLlmsDocs(llmsContent, baseUrl, (_url, done, total) => {
+							ctx.onProgress(`Downloading supplementary doc ${done + 1}/${total}`);
+						});
+						for (const doc of supplementary) {
+							if (!ctx.isFrameworkDoc(doc.url)) continue;
+							const localPath = doc.url.startsWith("/") ? doc.url.slice(1) : doc.url;
+							ctx.docs.push({
+								path: join("llms-docs", ...localPath.split("/")),
+								content: doc.content
+							});
+						}
+					}
+				}
+			}
+		}
+	}),
+	crawlUrlStep,
+	defineStep({
+		id: "llms.txt",
+		canResolve: (ctx) => !!ctx.resolved.llmsUrl && ctx.docs.length === 0,
+		async run(ctx) {
+			const llmsUrl = ctx.resolved.llmsUrl;
+			ctx.onProgress("Fetching llms.txt");
+			const llmsContent = await fetchLlmsTxt(llmsUrl);
+			if (!llmsContent) return;
+			ctx.docSource = llmsUrl;
+			ctx.docsType = "llms.txt";
+			const baseUrl = ctx.resolved.docsUrl || new URL(llmsUrl).origin;
+			ctx.docs.push({
 				path: "llms.txt",
 				content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
 			});
 			if (llmsContent.links.length > 0) {
-				onProgress(`Downloading ${llmsContent.links.length} linked docs`);
+				ctx.onProgress(`Downloading ${llmsContent.links.length} linked docs`);
 				const linked = await downloadLlmsDocs(llmsContent, baseUrl, (_url, done, total) => {
-					onProgress(`Downloading linked doc ${done + 1}/${total}`);
+					ctx.onProgress(`Downloading linked doc ${done + 1}/${total}`);
 				});
 				for (const doc of linked) {
-					if (!isFrameworkDoc(doc.url)) continue;
+					if (!ctx.isFrameworkDoc(doc.url)) continue;
 					const cachePath = join("docs", ...(doc.url.startsWith("/") ? doc.url.slice(1) : doc.url).split("/"));
-					docs.push({
+					ctx.docs.push({
 						path: cachePath,
 						content: doc.content
 					});
-					docsToIndex.push({
+					ctx.docsToIndex.push({
 						id: doc.url,
 						content: doc.content,
 						metadata: {
-							package: packageName,
+							package: ctx.packageName,
 							source: cachePath,
 							type: "doc"
 						}
 					});
 				}
-				if (linked.length > 0) docsType = "docs";
+				if (linked.length > 0) ctx.docsType = "docs";
 			}
 		}
-	}
-	if (resolved.docsUrl && !docs.some((d) => d.path.startsWith("docs/"))) {
-		const crawlPattern = resolved.crawlUrl || toCrawlPattern(resolved.docsUrl);
-		onProgress("Crawling docs site");
-		const crawled = await fetchCrawledDocs(crawlPattern, onProgress, resolved.crawlUrl ? 200 : 400).catch((err) => {
-			warnings.push(`Crawl failed for ${crawlPattern}: ${err?.message || err}`);
-			return [];
-		});
-		let added = 0;
-		for (const doc of crawled) {
-			if (!isFrameworkDoc(doc.path)) continue;
-			docs.push(doc);
-			docsToIndex.push({
-				id: doc.path,
-				content: doc.content,
-				metadata: {
-					package: packageName,
-					source: doc.path,
-					type: "doc"
-				}
-			});
-			added++;
-		}
-		if (added > 0) {
-			docSource = crawlPattern;
-			docsType = "docs";
-		}
-	}
-	if (resolved.readmeUrl && docs.length === 0) {
-		onProgress("Fetching README");
-		const content = await fetchReadmeContent(resolved.readmeUrl);
-		if (content) {
-			docs.push({
+	}),
+	docsCrawlStep,
+	defineStep({
+		id: "readme",
+		canResolve: (ctx) => !!ctx.resolved.readmeUrl && ctx.docs.length === 0,
+		async run(ctx) {
+			ctx.onProgress("Fetching README");
+			const content = await fetchReadmeContent(ctx.resolved.readmeUrl);
+			if (!content) return;
+			ctx.docs.push({
 				path: "docs/README.md",
 				content
 			});
-			docsToIndex.push({
+			ctx.docsToIndex.push({
 				id: "README.md",
 				content,
 				metadata: {
-					package: packageName,
+					package: ctx.packageName,
 					source: "docs/README.md",
 					type: "doc"
 				}
 			});
 		}
-	}
+	})
+];
+async function resolveContentDocs(opts) {
+	const { packageName, resolved, version, onProgress } = opts;
+	const ctx = {
+		packageName,
+		resolved,
+		version,
+		onProgress,
+		isFrameworkDoc: (path) => filterFrameworkDocs([path], packageName).length > 0,
+		docs: [],
+		docsToIndex: [],
+		warnings: [],
+		docSource: resolved.readmeUrl || "readme",
+		docsType: "readme"
+	};
+	await walkSteps(defaultContentSteps, ctx);
 	return {
-		docs,
-		docsToIndex,
-		docSource,
-		docsType,
-		warnings
+		docs: ctx.docs,
+		docsToIndex: ctx.docsToIndex,
+		docSource: ctx.docSource,
+		docsType: ctx.docsType,
+		warnings: ctx.warnings
 	};
 }
-async function tryGitDocs(opts) {
-	const { owner, repo, version, packageName, repoUrl, llmsUrl, docsUrl, onProgress } = opts;
-	onProgress("Fetching git docs");
-	const gitDocs = await fetchGitDocs(owner, repo, version, packageName);
-	if (!gitDocs || gitDocs.files.length === 0) return null;
-	let warning;
-	if (gitDocs.fallback) warning = `Docs fetched from ${gitDocs.ref} branch (no tag found for v${version})`;
-	const BATCH_SIZE = 20;
-	const results = [];
-	for (let i = 0; i < gitDocs.files.length; i += BATCH_SIZE) {
-		const batch = gitDocs.files.slice(i, i + BATCH_SIZE);
-		onProgress(`Downloading docs ${Math.min(i + BATCH_SIZE, gitDocs.files.length)}/${gitDocs.files.length} from ${gitDocs.ref}`);
-		const batchResults = await Promise.all(batch.map(async (file) => {
-			const content = await fetchGitHubRaw(`${gitDocs.baseUrl}/${file}`);
-			return content ? {
-				file,
-				content
-			} : null;
-		}));
-		results.push(...batchResults);
-	}
-	const docs = [];
-	const docsToIndex = [];
-	for (const r of results) {
-		if (!r) continue;
-		const stripped = gitDocs.docsPrefix ? r.file.replace(gitDocs.docsPrefix, "") : r.file;
-		const cachePath = stripped.startsWith("docs/") ? stripped : `docs/${stripped}`;
-		docs.push({
-			path: cachePath,
-			content: r.content
-		});
-		docsToIndex.push({
-			id: cachePath,
-			content: r.content,
+const discussionsStep = defineStep({
+	id: "discussions",
+	canResolve: (ctx) => ctx.features.discussions && !!ctx.repoInfo && isGhAvailable() && !existsSync(ctx.discussionsDir),
+	async run(ctx) {
+		const { owner, repo } = ctx.repoInfo;
+		ctx.onProgress("Fetching discussions via GitHub API");
+		const discussions = await fetchGitHubDiscussions(owner, repo, 20, ctx.resolved.releasedAt, ctx.from).catch(() => []);
+		if (discussions.length === 0) return;
+		ctx.onProgress(`Caching ${discussions.length} discussions`);
+		writeToRepoCache(owner, repo, [...discussions.map((d) => ({
+			path: `discussions/discussion-${d.number}.md`,
+			content: formatDiscussionAsMarkdown(d)
+		})), {
+			path: "discussions/_INDEX.md",
+			content: generateDiscussionIndex(discussions)
+		}]);
+		for (const d of discussions) ctx.docsToIndex.push({
+			id: `discussion-${d.number}`,
+			content: sanitizeMarkdown(`#${d.number}: ${d.title}\n\n${d.body || ""}`),
 			metadata: {
-				package: packageName,
-				source: cachePath,
-				type: "doc"
+				package: ctx.packageName,
+				source: `discussions/discussion-${d.number}.md`,
+				type: "discussion",
+				number: d.number
 			}
 		});
 	}
-	if (isShallowGitDocs(docs.length) && llmsUrl) {
-		onProgress(`Shallow git-docs (${docs.length} files), trying llms.txt`);
-		return {
-			kind: "discarded",
-			docs: [],
-			docsToIndex: [],
-			docSource: "",
-			warning
-		};
+});
+const issuesStep = defineStep({
+	id: "issues",
+	canResolve: (ctx) => ctx.features.issues && !!ctx.repoInfo && isGhAvailable() && !existsSync(ctx.issuesDir),
+	async run(ctx) {
+		const { owner, repo } = ctx.repoInfo;
+		ctx.onProgress("Fetching issues via GitHub API");
+		const issues = await fetchGitHubIssues(owner, repo, 30, ctx.resolved.releasedAt, ctx.from).catch(() => []);
+		if (issues.length === 0) return;
+		ctx.onProgress(`Caching ${issues.length} issues`);
+		writeToRepoCache(owner, repo, [...issues.map((issue) => ({
+			path: `issues/issue-${issue.number}.md`,
+			content: formatIssueAsMarkdown(issue)
+		})), {
+			path: "issues/_INDEX.md",
+			content: generateIssueIndex(issues)
+		}]);
+		for (const issue of issues) ctx.docsToIndex.push({
+			id: `issue-${issue.number}`,
+			content: sanitizeMarkdown(`#${issue.number}: ${issue.title}\n\n${issue.body || ""}`),
+			metadata: {
+				package: ctx.packageName,
+				source: `issues/issue-${issue.number}.md`,
+				type: "issue",
+				number: issue.number
+			}
+		});
 	}
-	if (llmsUrl) {
-		onProgress("Caching supplementary llms.txt");
-		const llmsContent = await fetchLlmsTxt(llmsUrl);
-		if (llmsContent) {
-			const baseUrl = docsUrl || new URL(llmsUrl).origin;
-			docs.push({
-				path: "llms.txt",
-				content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+});
+const BLOG_VERSION_RE = /blog-(.+)\.md$/;
+const defaultTimelineSteps = [
+	issuesStep,
+	discussionsStep,
+	defineStep({
+		id: "releases",
+		canResolve: (ctx) => ctx.features.releases && !!ctx.repoInfo && isGhAvailable() && !existsSync(ctx.releasesPath),
+		async run(ctx) {
+			const { owner, repo } = ctx.repoInfo;
+			const { packageName, version, resolved, from } = ctx;
+			ctx.onProgress("Fetching releases via GitHub API");
+			const changelogRef = isPrerelease(version) ? getPrereleaseChangelogRef(packageName) : void 0;
+			const releaseDocs = await fetchReleaseNotes(owner, repo, version, resolved.gitRef, packageName, from, changelogRef).catch(() => []);
+			let blogDocs = [];
+			if (getBlogPreset(packageName)) {
+				ctx.onProgress("Fetching blog release notes");
+				blogDocs = await fetchBlogReleases(packageName, version).catch(() => []);
+			}
+			const allDocs = [...releaseDocs, ...blogDocs];
+			const blogEntries = blogDocs.filter((d) => !d.path.endsWith("_INDEX.md")).map((d) => {
+				const versionMatch = d.path.match(BLOG_VERSION_RE);
+				const fm = parseFrontmatter(d.content);
+				return {
+					version: versionMatch?.[1] ?? "",
+					title: fm.title ?? `Release ${versionMatch?.[1]}`,
+					date: fm.date ?? ""
+				};
+			}).filter((b) => b.version);
+			const ghReleases = releaseDocs.filter((d) => d.path.startsWith("releases/") && !d.path.endsWith("CHANGELOG.md")).map((d) => {
+				const fm = parseFrontmatter(d.content);
+				const tag = fm.tag ?? "";
+				const name = fm.name ?? tag;
+				const published = fm.published ?? "";
+				return {
+					id: 0,
+					tag,
+					name,
+					prerelease: false,
+					createdAt: published,
+					publishedAt: published,
+					markdown: ""
+				};
+			}).filter((r) => r.tag);
+			const hasChangelog = allDocs.some((d) => d.path === "releases/CHANGELOG.md");
+			if (ghReleases.length > 0 || blogEntries.length > 0) allDocs.push({
+				path: "releases/_INDEX.md",
+				content: generateReleaseIndex({
+					releases: ghReleases,
+					packageName,
+					blogReleases: blogEntries,
+					hasChangelog
+				})
 			});
-			if (llmsContent.links.length > 0) {
-				onProgress(`Downloading ${llmsContent.links.length} supplementary docs`);
-				const supplementary = await downloadLlmsDocs(llmsContent, baseUrl, (_url, done, total) => {
-					onProgress(`Downloading supplementary doc ${done + 1}/${total}`);
-				});
-				for (const doc of supplementary) {
-					if (filterFrameworkDocs([doc.url], packageName).length === 0) continue;
-					const localPath = doc.url.startsWith("/") ? doc.url.slice(1) : doc.url;
-					docs.push({
-						path: join("llms-docs", ...localPath.split("/")),
-						content: doc.content
-					});
+			if (allDocs.length === 0) return;
+			ctx.onProgress(`Caching ${allDocs.length} releases`);
+			writeToRepoCache(owner, repo, allDocs);
+			for (const doc of allDocs) ctx.docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: packageName,
+					source: doc.path,
+					type: "release"
 				}
-			}
+			});
 		}
-	}
-	return {
-		kind: "git",
-		docs,
-		docsToIndex,
-		docSource: `${repoUrl}/tree/${gitDocs.ref}/docs`,
-		warning
-	};
-}
+	})
+];
 async function resolveTimelineReferences(opts) {
 	const { packageName, resolved, version, features, from, onProgress } = opts;
-	const docsToIndex = [];
 	const gh = resolved.repoUrl ? parseGitHubUrl(resolved.repoUrl) : null;
 	const repoInfo = gh ? {
 		owner: gh.owner,
@@ -690,125 +822,25 @@ async function resolveTimelineReferences(opts) {
 	} : void 0;
 	const repoCacheDir = repoInfo ? getRepoCacheDir(repoInfo.owner, repoInfo.repo) : null;
 	const cacheDir = getCacheDir(packageName, version);
-	const issuesDir = repoCacheDir ? join(repoCacheDir, "issues") : join(cacheDir, "issues");
-	const discussionsDir = repoCacheDir ? join(repoCacheDir, "discussions") : join(cacheDir, "discussions");
-	const releasesPath = repoCacheDir ? join(repoCacheDir, "releases") : join(cacheDir, "releases");
-	if (features.issues && gh && isGhAvailable() && !existsSync(issuesDir)) {
-		onProgress("Fetching issues via GitHub API");
-		const issues = await fetchGitHubIssues(gh.owner, gh.repo, 30, resolved.releasedAt, from).catch(() => []);
-		if (issues.length > 0) {
-			onProgress(`Caching ${issues.length} issues`);
-			const issueDocs = [...issues.map((issue) => ({
-				path: `issues/issue-${issue.number}.md`,
-				content: formatIssueAsMarkdown(issue)
-			})), {
-				path: "issues/_INDEX.md",
-				content: generateIssueIndex(issues)
-			}];
-			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, issueDocs);
-			else writeToCache(packageName, version, issueDocs);
-			for (const issue of issues) docsToIndex.push({
-				id: `issue-${issue.number}`,
-				content: sanitizeMarkdown(`#${issue.number}: ${issue.title}\n\n${issue.body || ""}`),
-				metadata: {
-					package: packageName,
-					source: `issues/issue-${issue.number}.md`,
-					type: "issue",
-					number: issue.number
-				}
-			});
-		}
-	}
-	if (features.discussions && gh && isGhAvailable() && !existsSync(discussionsDir)) {
-		onProgress("Fetching discussions via GitHub API");
-		const discussions = await fetchGitHubDiscussions(gh.owner, gh.repo, 20, resolved.releasedAt, from).catch(() => []);
-		if (discussions.length > 0) {
-			onProgress(`Caching ${discussions.length} discussions`);
-			const discussionDocs = [...discussions.map((d) => ({
-				path: `discussions/discussion-${d.number}.md`,
-				content: formatDiscussionAsMarkdown(d)
-			})), {
-				path: "discussions/_INDEX.md",
-				content: generateDiscussionIndex(discussions)
-			}];
-			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, discussionDocs);
-			else writeToCache(packageName, version, discussionDocs);
-			for (const d of discussions) docsToIndex.push({
-				id: `discussion-${d.number}`,
-				content: sanitizeMarkdown(`#${d.number}: ${d.title}\n\n${d.body || ""}`),
-				metadata: {
-					package: packageName,
-					source: `discussions/discussion-${d.number}.md`,
-					type: "discussion",
-					number: d.number
-				}
-			});
-		}
-	}
-	if (features.releases && gh && isGhAvailable() && !existsSync(releasesPath)) {
-		onProgress("Fetching releases via GitHub API");
-		const changelogRef = isPrerelease(version) ? getPrereleaseChangelogRef(packageName) : void 0;
-		const releaseDocs = await fetchReleaseNotes(gh.owner, gh.repo, version, resolved.gitRef, packageName, from, changelogRef).catch(() => []);
-		let blogDocs = [];
-		if (getBlogPreset(packageName)) {
-			onProgress("Fetching blog release notes");
-			blogDocs = await fetchBlogReleases(packageName, version).catch(() => []);
-		}
-		const allDocs = [...releaseDocs, ...blogDocs];
-		const blogEntries = blogDocs.filter((d) => !d.path.endsWith("_INDEX.md")).map((d) => {
-			const versionMatch = d.path.match(/blog-(.+)\.md$/);
-			const fm = parseFrontmatter(d.content);
-			return {
-				version: versionMatch?.[1] ?? "",
-				title: fm.title ?? `Release ${versionMatch?.[1]}`,
-				date: fm.date ?? ""
-			};
-		}).filter((b) => b.version);
-		const ghReleases = releaseDocs.filter((d) => d.path.startsWith("releases/") && !d.path.endsWith("CHANGELOG.md")).map((d) => {
-			const fm = parseFrontmatter(d.content);
-			const tag = fm.tag ?? "";
-			const name = fm.name ?? tag;
-			const published = fm.published ?? "";
-			return {
-				id: 0,
-				tag,
-				name,
-				prerelease: false,
-				createdAt: published,
-				publishedAt: published,
-				markdown: ""
-			};
-		}).filter((r) => r.tag);
-		const hasChangelog = allDocs.some((d) => d.path === "releases/CHANGELOG.md");
-		if (ghReleases.length > 0 || blogEntries.length > 0) allDocs.push({
-			path: "releases/_INDEX.md",
-			content: generateReleaseIndex({
-				releases: ghReleases,
-				packageName,
-				blogReleases: blogEntries,
-				hasChangelog
-			})
-		});
-		if (allDocs.length > 0) {
-			onProgress(`Caching ${allDocs.length} releases`);
-			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, allDocs);
-			else writeToCache(packageName, version, allDocs);
-			for (const doc of allDocs) docsToIndex.push({
-				id: doc.path,
-				content: doc.content,
-				metadata: {
-					package: packageName,
-					source: doc.path,
-					type: "release"
-				}
-			});
-		}
-	}
+	const ctx = {
+		packageName,
+		version,
+		resolved,
+		features,
+		from,
+		onProgress,
+		repoInfo,
+		issuesDir: repoCacheDir ? join(repoCacheDir, "issues") : join(cacheDir, "issues"),
+		discussionsDir: repoCacheDir ? join(repoCacheDir, "discussions") : join(cacheDir, "discussions"),
+		releasesPath: repoCacheDir ? join(repoCacheDir, "releases") : join(cacheDir, "releases"),
+		docsToIndex: []
+	};
+	await walkSteps(defaultTimelineSteps, ctx);
 	return {
-		docsToIndex,
-		hasIssues: features.issues && existsSync(issuesDir),
-		hasDiscussions: features.discussions && existsSync(discussionsDir),
-		hasReleases: features.releases && existsSync(releasesPath),
+		docsToIndex: ctx.docsToIndex,
+		hasIssues: features.issues && existsSync(ctx.issuesDir),
+		hasDiscussions: features.discussions && existsSync(ctx.discussionsDir),
+		hasReleases: features.releases && existsSync(ctx.releasesPath),
 		repoInfo
 	};
 }
@@ -902,11 +934,12 @@ async function fetchAndCacheResources(opts) {
 	};
 }
 async function prepareSkillReferences(opts) {
-	const { packageName, version, cwd, skillDir, resources, features, baseDir, onIndexProgress } = opts;
+	const { packageName, version, cwd, skillDir, resources, features, baseDir, extraPackages, onIndexProgress } = opts;
 	const cache = createReferenceCache(packageName, version);
 	cache.linkInto(skillDir, cwd, resources.docsType, {
 		features,
-		repoInfo: resources.repoInfo
+		repoInfo: resources.repoInfo,
+		extraPackages
 	});
 	if (features.search) await indexResources({
 		packageName,
@@ -947,6 +980,6 @@ function buildSkillContext(opts) {
 		overheadLines: opts.overheadLines
 	};
 }
-export { prepareSkillReferences as a, resolveAutoModel as c, applyCachedSections as d, enhanceSkillWithLLM as f, writePromptFiles as h, findRelatedSkills as i, selectLlmConfig as l, writeBaseSkill as m, detectChangelog as n, indexResources as o, runSkillEnhancement as p, fetchAndCacheResources as r, DEFAULT_SECTIONS as s, buildSkillContext as t, selectSkillSections as u };
+export { prepareSkillReferences as a, selectLlmConfig as c, runSkillEnhancement as d, writeBaseSkill as f, findRelatedSkills as i, applyCachedSections as l, detectChangelog as n, DEFAULT_SECTIONS as o, writePromptFiles as p, fetchAndCacheResources as r, resolveAutoModel as s, buildSkillContext as t, enhanceSkillWithLLM as u };
 
-//# sourceMappingURL=sync-pipeline.mjs.map
+//# sourceMappingURL=pipeline.mjs.map