skilld 0.9.5 → 0.10.0

package/dist/_chunks/detect-imports.mjs

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk.mjs";
 import { _ as writeSections, b as sanitizeMarkdown, h as readCachedSection, y as repairMarkdown } from "./storage.mjs";
-import { d as getPackageRules, o as mapInsert, t as yamlEscape, u as getFilePatterns } from "./yaml.mjs";
+import { o as getFilePatterns, s as getPackageRules, t as yamlEscape } from "./yaml.mjs";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "pathe";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
@@ -8,6 +8,7 @@ import { exec, spawn, spawnSync } from "node:child_process";
 import { globby } from "globby";
 import { findDynamicImports, findStaticImports } from "mlly";
 import { createHash } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
 import { promisify } from "node:util";
 import { readFile } from "node:fs/promises";
 import { parseSync } from "oxc-parser";
@@ -610,7 +611,15 @@ function apiChangesSection({ packageName, version, hasReleases, hasChangelog, ha
 		useFor: "Skip unless searching a specific removed API"
 	});
 	const releaseGuidance = hasReleases ? `\n\n**Scan release history:** Read \`./.skilld/releases/_INDEX.md\` for a timeline. Focus on [MAJOR] and [MINOR] releases — these contain breaking changes and renamed/deprecated APIs that LLMs trained on older data will get wrong.` : "";
-	const versionGuidance = major && minor ? `\n\n**New APIs in recent releases are the highest-priority gaps** — the LLM was trained on older data and will use outdated or non-existent APIs instead. Search for recent version tags and "Features" in releases/changelog to find new composables, components, hooks, or utilities added in recent major/minor versions.` : "";
+	const versionGuidance = major && minor ? `\n\n**Item scoring** — include only items scoring ≥ 3:
+
+| Change type | v${major}.x | v${Number(major) - 1}.x | Older |
+|-------------|:---:|:---:|:---:|
+| Silent breakage (compiles, wrong result) | 5 | 4 | 2 |
+| Removed/breaking API | 5 | 3 | 0 |
+| New API unknown to LLMs | 4 | 1 | 0 |
+| Deprecated (still works) | 3 | 1 | 0 |
+| Renamed/moved | 3 | 1 | 0 |` : "";
 	return {
 		referenceWeights,
 		task: `**Find new, deprecated, and renamed APIs from version history.** Focus exclusively on APIs that changed between versions — LLMs trained on older data will use the wrong names, wrong signatures, or non-existent functions.
@@ -621,26 +630,24 @@ Find from releases/changelog:
 - **Signature changes** where old code compiles but behaves wrong (changed parameter order, return types, default values)
 - **Breaking changes** in recent versions (v2 → v3 migrations, major version bumps)
 ${searchHints.length ? `\nSearch: ${searchHints.join(", ")}` : ""}${releaseGuidance}${versionGuidance}`,
-		format: `## API Changes
+		format: `<format-example note="Illustrative structure only — replace placeholder names with real ${packageName} APIs">
+## API Changes
 
 This section documents version-specific API changes — prioritize recent major/minor releases.
 
-\`\`\`
-## API Changes
-
-⚠️ \`createClient(url, key)\` — v2 changed to \`createClient({ url, key })\`, old positional args silently ignored [source](./.skilld/releases/v2.0.0.md)
+- BREAKING: \`createClient(url, key)\` — v2 changed to \`createClient({ url, key })\`, old positional args silently ignored [source](./.skilld/releases/v2.0.0.md)
 
-✨ \`useTemplateRef()\` — new in v3.5, replaces \`$refs\` pattern [source](./.skilld/releases/v3.5.0.md)
+- NEW: \`useTemplateRef()\` — new in v3.5, replaces \`$refs\` pattern [source](./.skilld/releases/v3.5.0.md)
 
-⚠️ \`db.query()\` — returns \`{ rows }\` not raw array since v4 [source](./.skilld/docs/migration.md)
-\`\`\`
+- BREAKING: \`db.query()\` — returns \`{ rows }\` not raw array since v4 [source](./.skilld/docs/migration.md)
+</format-example>
 
-Each item: ⚠️ (breaking/deprecated) or ✨ (new) + API name + what changed + source link.`,
+Each item: BREAKING/DEPRECATED/NEW label + API name + what changed + source link. All source links MUST use \`./.skilld/\` prefix (e.g., \`[source](./.skilld/releases/v2.0.0.md)\`). Do NOT use emoji — use plain text markers only.`,
 		rules: [
 			`- **API Changes:** ${maxItems(6, 12, enabledSectionCount)} items from version history, MAX ${maxLines(50, 80, enabledSectionCount)} lines`,
 			"- Prioritize recent major/minor releases over old patch versions",
 			"- Focus on APIs that CHANGED, not general conventions or gotchas",
-			"- New APIs get ✨, deprecated/breaking get ⚠️",
+			"- New APIs get NEW: prefix, deprecated/breaking get BREAKING: or DEPRECATED: prefix",
 			hasReleases ? "- Start with `./.skilld/releases/_INDEX.md` to identify recent major/minor releases, then read specific release files" : "",
 			hasChangelog ? "- Scan CHANGELOG.md for version headings, focus on Features/Breaking Changes sections" : ""
 		].filter(Boolean)
@@ -659,14 +666,14 @@ function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasRelea
 	if (hasDiscussions) referenceWeights.push({
 		name: "Discussions",
 		path: "./.skilld/discussions/_INDEX.md",
-		score: 8,
-		useFor: "Q&A with accepted answers reveal \"the right way\""
+		score: 5,
+		useFor: "Only maintainer-confirmed patterns — community workarounds are lower confidence"
 	});
 	if (hasIssues) referenceWeights.push({
 		name: "Issues",
 		path: "./.skilld/issues/_INDEX.md",
-		score: 7,
-		useFor: "Questions reveal what users find confusing"
+		score: 4,
+		useFor: "Only workarounds confirmed by maintainers or with broad adoption"
 	});
 	if (hasReleases) referenceWeights.push({
 		name: "Releases",
@@ -682,33 +689,38 @@ function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasRelea
 	});
 	return {
 		referenceWeights,
-		task: `**Extract non-obvious best practices from the references.** Focus on recommended patterns Claude wouldn't already know: idiomatic usage, preferred configurations, performance tips, patterns that differ from what a developer would assume. Surface new patterns from recent minor releases that may post-date training data. Every item must link to a verified source file.
+		task: `**Extract non-obvious best practices from the references.** Focus on recommended patterns the LLM wouldn't already know: idiomatic usage, preferred configurations, performance tips, patterns that differ from what a developer would assume. Surface new patterns from recent minor releases that may post-date training data.
 
-Skip: obvious API usage, installation steps, general TypeScript/programming patterns, anything a developer would naturally write without reading the docs.
+Skip: obvious API usage, installation steps, general TypeScript/programming patterns not specific to this package, anything a developer would naturally write without reading the docs. Every item must be specific to ${packageName} — reject general programming advice that applies to any project.
 ${searchHints.length ? `\nSearch: ${searchHints.join(", ")}` : ""}`,
-		format: `\`\`\`
+		format: `<format-example note="Illustrative structure only — replace placeholder names with real ${packageName} APIs">
+\`\`\`
 ## Best Practices
 
-✅ Pass \`AbortSignal\` to long-lived operations — enables caller-controlled cancellation [source](./.skilld/docs/api.md)
+- Use ${packageName}'s built-in \`createX()\` helper over manual wiring — handles cleanup and edge cases automatically [source](./.skilld/docs/api.md)
 
 \`\`\`ts
-async function fetchUser(id: string, signal?: AbortSignal) {
-  return fetch(\`/api/users/\${id}\`, { signal })
-}
-\`\`\`
+// Preferred
+const instance = createX({ ... })
 
-✅ Use \`satisfies\` for config objects — preserves literal types while validating shape [source](./.skilld/docs/config.md)
+// Avoid — misses cleanup, error boundaries
+const instance = new X()
+instance.init({ ... })
+\`\`\`
 
-✅ Prefer \`structuredClone()\` over spread for deep copies — handles nested objects, Maps, Sets [source](./.skilld/docs/utilities.md)
+- Pass config through \`defineConfig()\` — enables type inference and plugin merging [source](./.skilld/docs/config.md)
 
-✅ Set \`isolatedDeclarations: true\` — enables parallel .d.ts emit without full type-checking [source](./.skilld/docs/typescript.md)
+- Prefer \`useComposable()\` over direct imports in reactive contexts — ensures proper lifecycle binding [source](./.skilld/docs/composables.md)
 \`\`\`
+</format-example>
 
-Each item: ✅ + pattern name + why it's preferred + source link. Code block only when the pattern isn't obvious from the title. Use the most relevant language tag (ts, vue, css, json, etc).`,
+Each item: markdown list item (-) + ${packageName}-specific pattern + why it's preferred + source link. Code block only when the pattern isn't obvious from the title. Use the most relevant language tag (ts, vue, css, json, etc). Every example must be specific to ${packageName} — never generic TypeScript/JS advice. All source links MUST use \`./.skilld/\` prefix (e.g., \`[source](./.skilld/docs/guide.md)\`). Do NOT use emoji — use plain text markers only.`,
 		rules: [
 			`- **${maxItems(4, 10, enabledSectionCount)} best practice items**`,
 			`- **MAX ${maxLines(80, 150, enabledSectionCount)} lines** for best practices section`,
-			"- **Only link files confirmed to exist** via Glob or Read — no guessed paths"
+			"- **Verify before including:** Confirm file paths exist via Glob/Read before linking. Confirm functions/composables are real exports in `./.skilld/pkg/` `.d.ts` files before documenting",
+			"- **Diversity:** Cover at least 3 distinct areas of the library. No single feature should have more than 40% of items",
+			"- **Experimental APIs:** Mark unstable/experimental features with `(experimental)` in the description. Prioritize stable patterns"
 		]
 	};
 }
@@ -813,8 +825,11 @@ function formatDocTree(files) {
 	}
 	return [...dirs.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([dir, count]) => `- \`${dir}/\` (${count} .md files)`).join("\n");
 }
-function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs, skillDir, features }) {
-	const rows = [["Docs", hasShippedDocs ? `\`${skillDir}/.skilld/pkg/docs/\` or \`${skillDir}/.skilld/pkg/README.md\`` : docsType === "llms.txt" ? `\`${skillDir}/.skilld/docs/llms.txt\`` : docsType === "readme" ? `\`${skillDir}/.skilld/pkg/README.md\`` : `\`${skillDir}/.skilld/docs/\``], ["Package", `\`${skillDir}/.skilld/pkg/\``]];
+function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs, skillDir, features, pkgFiles }) {
+	const docsPath = hasShippedDocs ? `\`${skillDir}/.skilld/pkg/docs/\` or \`${skillDir}/.skilld/pkg/README.md\`` : docsType === "llms.txt" ? `\`${skillDir}/.skilld/docs/llms.txt\`` : docsType === "readme" ? `\`${skillDir}/.skilld/pkg/README.md\`` : `\`${skillDir}/.skilld/docs/\``;
+	const typesFile = pkgFiles?.find((f) => f.endsWith(".d.ts"));
+	const rows = [["Docs", docsPath], ["Package", `\`${skillDir}/.skilld/pkg/\``]];
+	if (typesFile) rows.push(["Types", `\`${skillDir}/.skilld/pkg/${typesFile}\` — **read this file directly** to verify exports`]);
 	if (hasIssues) rows.push(["Issues", `\`${skillDir}/.skilld/issues/\``]);
 	if (hasDiscussions) rows.push(["Discussions", `\`${skillDir}/.skilld/discussions/\``]);
 	if (hasChangelog) rows.push(["Changelog", `\`${skillDir}/.skilld/${hasChangelog}\``]);
@@ -857,18 +872,10 @@ ${generateImportantBlock({
 		docsType,
 		hasShippedDocs,
 		skillDir,
-		features: opts.features
+		features: opts.features,
+		pkgFiles: opts.pkgFiles
 	})}
-${docsSection ? `${docsSection}\n` : ""}
-
-## Skill Quality Principles
-
-The context window is a shared resource. Skills share it with system prompt, conversation history, other skills, and the user request.
-
-- **Only add what Claude doesn't know.** Claude already knows general programming, popular APIs, common patterns. Challenge every line: "Does this justify its token cost?"
-- **Prefer concise examples over verbose explanations.** A 2-line code example beats a paragraph.
-- **Skip:** API signatures, installation steps, tutorials, marketing, general programming knowledge, anything in the package README that's obvious
-- **Include:** Non-obvious gotchas, surprising defaults, version-specific breaking changes, pitfalls from issues, patterns that differ from what Claude would assume`;
+${docsSection ? `${docsSection}\n` : ""}`;
 }
 function getSectionDef(section, ctx, customPrompt) {
 	switch (section) {
@@ -901,14 +908,14 @@ function buildSectionPrompt(opts) {
 	const packageRules = getPackageRules(packageName);
 	const rules = [
 		...sectionDef.rules ?? [],
-		"- Link to exact source file where you found info",
-		"- TypeScript only",
 		...packageRules.map((r) => `- ${r}`),
-		"- Imperative voice (\"Use X\" not \"You should use X\")",
 		`- **NEVER fetch external URLs.** All information is in the local \`./.skilld/\` directory. Use Read, Glob${opts.features?.search !== false ? ", and `skilld search`" : ""} only.`,
 		"- **Do NOT use Task tool or spawn subagents.** Work directly.",
 		"- **Do NOT re-read files** you have already read in this session.",
-		"- **Read `_INDEX.md` first** in issues/releases/discussions — only drill into files that look relevant. Skip stub/placeholder files."
+		"- **Read `_INDEX.md` first** in issues/releases/discussions — only drill into files that look relevant. Skip stub/placeholder files.",
+		"- **Skip files starting with `PROMPT_`** — these are generation prompts, not reference material.",
+		"- **Stop exploring once you have enough high-quality items** to fill the budget. Do not read additional files just to be thorough.",
+		"- **To verify API exports:** Read the `.d.ts` file directly (see Types row in references). Do NOT use search with relative paths or `include` filters on package directories — they may silently return no results."
 	];
 	return `${preamble}${sectionDef.referenceWeights?.length ? `\n\n## Reference Priority\n\n| Reference | Path | Score | Use For |\n|-----------|------|:-----:|--------|\n${sectionDef.referenceWeights.map((w) => `| ${w.name} | [\`${w.path.split("/").pop()}\`](${w.path}) | ${w.score}/10 | ${w.useFor} |`).join("\n")}` : ""}
 
@@ -1003,23 +1010,28 @@ function unlinkSkillFromAgents(skillName, cwd) {
 function generateSkillMd(opts) {
 	const header = generatePackageHeader(opts);
 	const search = !opts.eject && opts.features?.search !== false ? generateSearchBlock(opts.name, opts.hasIssues, opts.hasReleases) : "";
-	const content = opts.body ? search ? `${header}\n\n${search}\n\n${opts.body}` : `${header}\n\n${opts.body}` : search ? `${header}\n\n${search}` : header;
+	const body = opts.body && opts.eject ? opts.body.replace(/\.\/\.skilld\//g, "./references/") : opts.body;
+	const content = body ? search ? `${header}\n\n${search}\n\n${body}` : `${header}\n\n${body}` : search ? `${header}\n\n${search}` : header;
 	const footer = generateFooter(opts.relatedSkills);
 	return sanitizeMarkdown(repairMarkdown(`${generateFrontmatter(opts)}${content}\n${footer}`));
 }
-function formatRelativeDate(isoDate) {
+function formatShortDate(isoDate) {
 	const date = new Date(isoDate);
-	const diffMs = (/* @__PURE__ */ new Date()).getTime() - date.getTime();
-	const diffDays = Math.floor(diffMs / (1e3 * 60 * 60 * 24));
-	if (diffDays === 0) return "today";
-	if (diffDays === 1) return "yesterday";
-	if (diffDays < 7) return `${diffDays} day${diffDays === 1 ? "" : "s"} ago`;
-	const weeks = Math.floor(diffDays / 7);
-	if (diffDays < 30) return `${weeks} week${weeks === 1 ? "" : "s"} ago`;
-	const months = Math.floor(diffDays / 30);
-	if (diffDays < 365) return `${months} month${months === 1 ? "" : "s"} ago`;
-	const years = Math.floor(diffDays / 365);
-	return `${years} year${years === 1 ? "" : "s"} ago`;
+	if (Number.isNaN(date.getTime())) return "";
+	return `${[
+		"Jan",
+		"Feb",
+		"Mar",
+		"Apr",
+		"May",
+		"Jun",
+		"Jul",
+		"Aug",
+		"Sep",
+		"Oct",
+		"Nov",
+		"Dec"
+	][date.getUTCMonth()]} ${date.getUTCFullYear()}`;
 }
 function generatePackageHeader({ name, description, version, releasedAt, dependencies, distTags, repoUrl, hasIssues, hasDiscussions, hasReleases, pkgFiles, packages, eject }) {
 	let title = `# ${name}`;
@@ -1030,8 +1042,8 @@ function generatePackageHeader({ name, description, version, releasedAt, depende
 	const lines = [title];
 	if (description) lines.push("", `> ${description}`);
 	if (version) {
-		const relativeDate = releasedAt ? formatRelativeDate(releasedAt) : "";
-		const versionStr = relativeDate ? `${version} (${relativeDate})` : version;
+		const dateStr = releasedAt ? formatShortDate(releasedAt) : "";
+		const versionStr = dateStr ? `${version} (${dateStr})` : version;
 		lines.push("", `**Version:** ${versionStr}`);
 	}
 	if (dependencies && Object.keys(dependencies).length > 0) {
@@ -1040,7 +1052,7 @@ function generatePackageHeader({ name, description, version, releasedAt, depende
 	}
 	if (distTags && Object.keys(distTags).length > 0) {
 		const tags = Object.entries(distTags).map(([tag, info]) => {
-			const relDate = info.releasedAt ? ` (${formatRelativeDate(info.releasedAt)})` : "";
+			const relDate = info.releasedAt ? ` (${formatShortDate(info.releasedAt)})` : "";
 			return `${tag}: ${info.version}${relDate}`;
 		}).join(", ");
 		lines.push(`**Tags:** ${tags}`);
@@ -1359,11 +1371,17 @@ function parseLine(line) {
 		if (obj.type === "message" && obj.role === "assistant" && obj.content) return obj.delta ? { textDelta: obj.content } : { fullText: obj.content };
 		if (obj.type === "tool_use" || obj.type === "tool_call") {
 			const name = obj.tool_name || obj.name || obj.tool || "tool";
-			if (name === "write_file" && obj.args?.content) return {
+			const params = obj.parameters || obj.args || obj.input || {};
+			const hint = params.file_path || params.path || params.dir_path || params.pattern || params.query || params.command || "";
+			if (name === "write_file" && params.content) return {
 				toolName: name,
-				writeContent: obj.args.content
+				toolHint: hint || void 0,
+				writeContent: params.content
+			};
+			return {
+				toolName: name,
+				toolHint: hint || void 0
 			};
-			return { toolName: name };
 		}
 		if (obj.type === "result") {
 			const s = obj.stats;
@@ -1392,58 +1410,39 @@ const TOOL_VERBS = {
 	search_file_content: "Searching"
 };
 function createToolProgress(log) {
-	const pending = /* @__PURE__ */ new Map();
-	let timer = null;
-	let lastEmitted = "";
-	function flush() {
-		const parts = [];
-		for (const [section, { verb, path, count }] of pending) {
-			const suffix = count > 1 ? ` \x1B[90m(+${count - 1})\x1B[0m` : "";
-			parts.push(`\x1B[90m[${section}]\x1B[0m ${verb} ${path}${suffix}`);
-		}
-		const msg = parts.join("  ");
-		if (msg && msg !== lastEmitted) {
+	let lastMsg = "";
+	let repeatCount = 0;
+	function emit(msg) {
+		if (msg === lastMsg) {
+			repeatCount++;
+			log.message(`${msg} \x1B[90m(+${repeatCount})\x1B[0m`);
+		} else {
+			lastMsg = msg;
+			repeatCount = 0;
 			log.message(msg);
-			lastEmitted = msg;
 		}
-		pending.clear();
-		timer = null;
 	}
 	return ({ type, chunk, section }) => {
 		if (type === "text") {
-			log.message(`${section ? `\x1B[90m[${section}]\x1B[0m ` : ""}Writing...`);
+			emit(`${section ? `\x1B[90m[${section}]\x1B[0m ` : ""}Writing...`);
 			return;
 		}
 		if (type !== "reasoning" || !chunk.startsWith("[")) return;
-		const key = section ?? "";
-		const match = chunk.match(/^\[(\w+)(?:,\s\w+)*(?::\s(.+))?\]$/);
+		const match = chunk.match(/^\[([^:[\]]+)(?::\s(.+))?\]$/);
 		if (!match) return;
-		const rawName = match[1];
-		const hint = match[2] ?? "";
-		let verb = TOOL_VERBS[rawName] ?? rawName;
-		let path = hint || "...";
-		if (rawName === "Bash" && hint) {
-			const searchMatch = hint.match(/skilld search\s+"([^"]+)"/);
-			if (searchMatch) {
-				verb = "skilld search:";
-				path = searchMatch[1];
-			} else path = hint.length > 60 ? `${hint.slice(0, 57)}...` : hint;
-		} else path = shortenPath(path);
-		if (rawName === "Write") {
-			if (timer) flush();
+		const names = match[1].split(",").map((n) => n.trim());
+		const hints = match[2]?.split(",").map((h) => h.trim()) ?? [];
+		for (let i = 0; i < names.length; i++) {
+			const rawName = names[i];
+			const hint = hints[i] ?? hints[0] ?? "";
+			const verb = TOOL_VERBS[rawName] ?? rawName;
 			const prefix = section ? `\x1B[90m[${section}]\x1B[0m ` : "";
-			log.message(`${prefix}Writing ${path}`);
-			return;
+			if (rawName === "Bash" && hint) {
+				const searchMatch = hint.match(/skilld search\s+"([^"]+)"/);
+				if (searchMatch) emit(`${prefix}Searching \x1B[36m"${searchMatch[1]}"\x1B[0m`);
+				else emit(`${prefix}Running ${hint.length > 50 ? `${hint.slice(0, 47)}...` : hint}`);
+			} else emit(`${prefix}${verb} \x1B[90m${shortenPath(hint || "...")}\x1B[0m`);
 		}
-		const entry = mapInsert(pending, key, () => ({
-			verb,
-			path,
-			count: 0
-		}));
-		entry.verb = verb;
-		entry.path = path;
-		entry.count++;
-		if (!timer) timer = setTimeout(flush, 400);
 	};
 }
 const CLI_DEFS = [
@@ -1622,13 +1621,16 @@ function optimizeSection(opts) {
 				} catch {}
 			}
 			const raw = (existsSync(outputPath) ? readFileSync(outputPath, "utf-8") : lastWriteContent || accumulatedText).trim();
+			const logsDir = join(skilldDir, "logs");
+			const logName = section.toUpperCase().replace(/-/g, "_");
+			if (debug || stderr && (!raw || code !== 0)) {
+				mkdirSync(logsDir, { recursive: true });
+				if (stderr) writeFileSync(join(logsDir, `${logName}.stderr.log`), stderr);
+			}
 			if (debug) {
-				const logsDir = join(skilldDir, "logs");
 				mkdirSync(logsDir, { recursive: true });
-				const logName = section.toUpperCase().replace(/-/g, "_");
 				if (rawLines.length) writeFileSync(join(logsDir, `${logName}.jsonl`), rawLines.join("\n"));
 				if (raw) writeFileSync(join(logsDir, `${logName}.md`), raw);
-				if (stderr) writeFileSync(join(logsDir, `${logName}.stderr.log`), stderr);
 			}
 			if (!raw && code !== 0) {
 				resolve({
@@ -1662,7 +1664,7 @@ function optimizeSection(opts) {
 	});
 }
 async function optimizeDocs(opts) {
-	const { packageName, skillDir, model = "sonnet", version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 18e4, debug, noCache, sections, customPrompt, features } = opts;
+	const { packageName, skillDir, model = "sonnet", version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 18e4, debug, noCache, sections, customPrompt, features, pkgFiles } = opts;
 	const sectionPrompts = buildAllSectionPrompts({
 		packageName,
 		skillDir,
@@ -1676,6 +1678,7 @@ async function optimizeDocs(opts) {
 		hasShippedDocs,
 		customPrompt,
 		features,
+		pkgFiles,
 		sections: sections ?? [
 			"api-changes",
 			"best-practices",
@@ -1739,10 +1742,22 @@ async function optimizeDocs(opts) {
 	}
 	const skilldDir = join(skillDir, ".skilld");
 	mkdirSync(skilldDir, { recursive: true });
+	for (const entry of readdirSync(skilldDir)) {
+		const entryPath = join(skilldDir, entry);
+		try {
+			if (lstatSync(entryPath).isSymbolicLink() && !existsSync(entryPath)) onProgress?.({
+				chunk: `[warn: broken symlink .skilld/${entry}]`,
+				type: "reasoning",
+				text: "",
+				reasoning: ""
+			});
+		} catch {}
+	}
 	const preExistingFiles = new Set(readdirSync(skilldDir));
-	const spawnResults = uncachedSections.length > 0 ? await Promise.allSettled(uncachedSections.map(({ section, prompt }) => {
+	const STAGGER_MS = 3e3;
+	const spawnResults = uncachedSections.length > 0 ? await Promise.allSettled(uncachedSections.map(({ section, prompt }, i) => {
 		const outputFile = SECTION_OUTPUT_FILES[section];
-		return optimizeSection({
+		const run = () => optimizeSection({
 			section,
 			prompt,
 			outputFile,
@@ -1754,32 +1769,71 @@ async function optimizeDocs(opts) {
 			debug,
 			preExistingFiles
 		});
+		if (i === 0) return run();
+		return setTimeout(i * STAGGER_MS).then(run);
 	})) : [];
 	const allResults = [...cachedResults];
 	let totalUsage;
 	let totalCost = 0;
+	const retryQueue = [];
 	for (let i = 0; i < spawnResults.length; i++) {
 		const r = spawnResults[i];
 		const { section, prompt } = uncachedSections[i];
-		if (r.status === "fulfilled") {
-			const result = r.value;
-			allResults.push(result);
-			if (result.wasOptimized && !noCache) setCache(prompt, model, section, result.content);
-			if (result.usage) {
+		if (r.status === "fulfilled" && r.value.wasOptimized) {
+			allResults.push(r.value);
+			if (r.value.usage) {
 				totalUsage = totalUsage ?? {
 					input: 0,
 					output: 0
 				};
-				totalUsage.input += result.usage.input;
-				totalUsage.output += result.usage.output;
+				totalUsage.input += r.value.usage.input;
+				totalUsage.output += r.value.usage.output;
 			}
-			if (result.cost != null) totalCost += result.cost;
-		} else allResults.push({
+			if (r.value.cost != null) totalCost += r.value.cost;
+			if (!noCache) setCache(prompt, model, section, r.value.content);
+		} else retryQueue.push({
+			index: i,
+			section,
+			prompt
+		});
+	}
+	for (const { section, prompt } of retryQueue) {
+		onProgress?.({
+			chunk: `[${section}: retrying...]`,
+			type: "reasoning",
+			text: "",
+			reasoning: "",
+			section
+		});
+		await setTimeout(STAGGER_MS);
+		const result = await optimizeSection({
+			section,
+			prompt,
+			outputFile: SECTION_OUTPUT_FILES[section],
+			skillDir,
+			model,
+			packageName,
+			onProgress,
+			timeout,
+			debug,
+			preExistingFiles
+		}).catch((err) => ({
 			section,
 			content: "",
 			wasOptimized: false,
-			error: String(r.reason)
-		});
+			error: err.message
+		}));
+		allResults.push(result);
+		if (result.wasOptimized && !noCache) setCache(prompt, model, section, result.content);
+		if (result.usage) {
+			totalUsage = totalUsage ?? {
+				input: 0,
+				output: 0
+			};
+			totalUsage.input += result.usage.input;
+			totalUsage.output += result.usage.output;
+		}
+		if (result.cost != null) totalCost += result.cost;
 	}
 	if (version) {
 		const sectionFiles = allResults.filter((r) => r.wasOptimized && r.content).map((r) => ({
@@ -1841,7 +1895,12 @@ function validateSectionOutput(content, section) {
 	return warnings;
 }
 function cleanSectionOutput(content) {
-	let cleaned = content.replace(/^```markdown\n?/m, "").replace(/\n?```$/m, "").trim();
+	let cleaned = content.trim();
+	const wrapMatch = cleaned.match(/^```(?:markdown|md)?[^\S\n]*\n([\s\S]+)\n```[^\S\n]*$/);
+	if (wrapMatch) {
+		const inner = wrapMatch[1].trim();
+		if (/^```(?:markdown|md)/.test(cleaned) || /^##\s/m.test(inner) || /^- (?:BREAKING|DEPRECATED|NEW): /m.test(inner)) cleaned = inner;
+	}
 	const fmMatch = cleaned.match(/^-{3,}\n/);
 	if (fmMatch) {
 		const afterOpen = fmMatch[0].length;
@@ -1849,13 +1908,23 @@ function cleanSectionOutput(content) {
 		if (closeMatch) cleaned = cleaned.slice(afterOpen + closeMatch.index + closeMatch[0].length).trim();
 		else cleaned = cleaned.slice(afterOpen).trim();
 	}
-	const firstMarker = cleaned.match(/^(##\s|⚠️|✅)/m);
+	const firstMarker = cleaned.match(/^(##\s|- (?:BREAKING|DEPRECATED|NEW): )/m);
 	if (firstMarker?.index && firstMarker.index > 0) {
 		const preamble = cleaned.slice(0, firstMarker.index);
 		if (/\b(?:function|const |let |var |export |return |import |async |class )\b/.test(preamble)) cleaned = cleaned.slice(firstMarker.index).trim();
 	}
+	const headingMatch = cleaned.match(/^(## .+)\n/);
+	if (headingMatch) {
+		const heading = headingMatch[1];
+		const afterFirst = headingMatch[0].length;
+		const secondIdx = cleaned.indexOf(heading, afterFirst);
+		if (secondIdx !== -1) {
+			if (secondIdx - afterFirst < 200) cleaned = cleaned.slice(secondIdx).trim();
+		}
+	}
+	cleaned = cleaned.replace(/\[source\]\(\.\/((docs|issues|discussions|releases|pkg|guide)\/)/g, "[source](./.skilld/$1");
 	cleaned = sanitizeMarkdown(cleaned);
-	if (!/^##\s/m.test(cleaned) && !/⚠️|✅|✨/.test(cleaned)) return "";
+	if (!/^##\s/m.test(cleaned) && !/^- (?:BREAKING|DEPRECATED|NEW): /m.test(cleaned) && !/\[source\]/.test(cleaned)) return "";
 	return cleaned;
 }
 const NUXT_CONFIG_FILES = [