nuxt-skill-hub 0.0.7 → 0.1.0

package/dist/module.mjs

@@ -1,6 +1,7 @@
 import { useLogger, defineNuxtModule } from '@nuxt/kit';
 import { isAgent, agent, isCI, isTest } from 'std-env';
 import { promises, existsSync, lstatSync, writeFileSync, readFileSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
 import { join, basename, resolve, dirname, relative, isAbsolute } from 'pathe';
 import { fileURLToPath } from 'mlly';
 import { homedir } from 'node:os';
@@ -8,15 +9,16 @@ import matter from 'gray-matter';
 import { readPackageJSON, findWorkspaceDir, resolvePackageJSON, resolveLockfile } from 'pkg-types';
 import { transform } from 'automd';
 import { downloadTemplate } from 'giget';
-import { detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds, getAgentConfig } from 'unagent/env';
+import { getAgentConfig, detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds } from 'unagent/env';
 import { ofetch } from 'ofetch';
 import { createHash } from 'node:crypto';
+import { isIP } from 'node:net';
 import { hash } from 'ohash';
 import { glob } from 'tinyglobby';
 import { createConsola } from 'consola';
 import { colorize } from 'consola/utils';
 
-const version = "0.0.7";
+const version = "0.1.0";
 const packageJson = {
 	version: version};
 
@@ -146,6 +148,8 @@ function getSourceLabel(sourceKind) {
       return "Installed package skill";
     case "github":
       return "Resolved module skill";
+    case "wellKnown":
+      return "Docs-discovered skill";
     case "generated":
       return "Metadata-routed skill";
   }
@@ -175,14 +179,14 @@ function resolveMetadataRouterSkillName(packageName) {
 }
 function createMetadataRouterSkillFiles(input) {
   const description = input.description?.trim() || `Metadata-routed module skill for ${input.packageName}. Use it to reach the official docs and upstream source.`;
-  const linkLines = createCompactMetadataRouterContent(input).trim();
+  const body = createMetadataRouterContent(input).trim();
   return {
     "SKILL.md": `---
 name: ${yamlString(input.skillName)}
 description: ${yamlString(description)}
 ---
 
-${linkLines || "Docs: unavailable\nSource code: unavailable"}
+${body}
 `
   };
 }
@@ -206,8 +210,9 @@ function relativeModuleLink(entry, prefix) {
 function groupModuleEntries(entries) {
   const officialUpstream = entries.filter((entry) => entry.sourceKind === "dist");
   const githubResolved = entries.filter((entry) => entry.sourceKind === "github");
+  const wellKnownResolved = entries.filter((entry) => entry.sourceKind === "wellKnown");
   const metadataRouted = entries.filter((entry) => entry.sourceKind === "generated");
-  return { officialUpstream, githubResolved, metadataRouted };
+  return { officialUpstream, githubResolved, wellKnownResolved, metadataRouted };
 }
 function hasModuleGuidance(entries, skipped = []) {
   return entries.length > 0 || skipped.length > 0;
@@ -241,6 +246,43 @@ function renderSkippedEntries(skipped) {
 ${lines.join("\n")}
 `;
 }
+function renderModuleSummary(entries, skipped) {
+  if (!hasModuleGuidance(entries, skipped)) {
+    return "";
+  }
+  const grouped = groupModuleEntries(entries);
+  const counts = [
+    ["installed", grouped.officialUpstream.length],
+    ["resolved", grouped.githubResolved.length],
+    ["docs-discovered", grouped.wellKnownResolved.length],
+    ["metadata-routed", grouped.metadataRouted.length],
+    ["skipped", skipped.length]
+  ];
+  const coverage = counts.filter(([, count]) => count > 0).map(([label, count]) => `${count} ${label}`).join(", ");
+  return `## Module guides
+Module guidance exists for installed packages. Keep it scoped to module-owned APIs, config, runtime behavior, plugins, composables, components, hooks, and owned files.
+
+- Inventory: [Module guide index](./references/modules/index.md)
+- Coverage: ${coverage || "none"}`;
+}
+function createModuleIndex(entries, skipped = []) {
+  if (!hasModuleGuidance(entries, skipped)) {
+    return "";
+  }
+  const grouped = groupModuleEntries(entries);
+  const moduleSections = [
+    renderModuleGroup("Official upstream skills", grouped.officialUpstream, "./"),
+    renderModuleGroup("Resolved module skills", grouped.githubResolved, "./"),
+    renderModuleGroup("Docs-discovered skills", grouped.wellKnownResolved, "./"),
+    renderModuleGroup("Metadata-routed skills", grouped.metadataRouted, "./"),
+    renderSkippedEntries(skipped)
+  ].filter(Boolean);
+  return `# Module Guide Index
+
+Use a module entry only when an installed module owns the surface. Module guidance is delta-only and should not replace broad Nuxt rules outside that module.
+
+${moduleSections.join("\n")}`;
+}
 function findPack(metadata, id) {
   return metadata.packs.find((pack) => pack.id === id) || metadata.packs[0];
 }
@@ -325,24 +367,12 @@ function createRoutingExamples(metadata, includeModuleAuthoring = false) {
 ${lines.join("\n")}`;
 }
 function createSkillMapSections(metadata, entries, skipped = [], includeModuleAuthoring = false) {
-  const includeModuleSections = hasModuleGuidance(entries, skipped);
-  const grouped = groupModuleEntries(entries);
-  const moduleSections = [
-    renderModuleGroup("Official upstream skills", grouped.officialUpstream, "./references/modules/"),
-    renderModuleGroup("Resolved module skills", grouped.githubResolved, "./references/modules/"),
-    renderModuleGroup("Metadata-routed skills", grouped.metadataRouted, "./references/modules/"),
-    renderSkippedEntries(skipped)
-  ].filter(Boolean);
-  const moduleGuidesSection = includeModuleSections ? `## Module guides
-Use a module entry only when an installed module owns the surface. Module guidance is delta-only and should not replace broad Nuxt rules outside that module.
-
-${moduleSections.join("\n")}` : "";
   return [
     "## Routing",
     "Load one matching guide first. Open more guides only when the first guide points you there or the task clearly crosses boundaries.",
     createRoutingTable(metadata, includeModuleAuthoring),
     createRoutingExamples(metadata, includeModuleAuthoring),
-    moduleGuidesSection
+    renderModuleSummary(entries, skipped)
   ].filter(Boolean).join("\n\n");
 }
 function createSkillEntrypoint(skillName, metadata, monorepoScopePath, includeModuleAuthoring = false, entries = [], skipped = []) {
@@ -421,6 +451,23 @@ function createCompactMetadataRouterContent(entry) {
   })}
 `;
 }
+function createMetadataRouterContent(entry) {
+  const links = createCompactMetadataRouterContent(entry).trim();
+  const sourceSection = links || "Docs: unavailable\n\nSource code: unavailable";
+  return `# ${entry.packageName} Module Router
+
+Use this module router only when the task directly involves \`${entry.packageName}\` APIs, config, runtime behavior, plugins, composables, components, hooks, or owned files.
+
+## Source of truth
+${sourceSection}
+
+## Context rules
+1. Start with the relevant route in the parent Nuxt skill before using this module router.
+2. Use the docs link for exact APIs, options, and examples instead of guessing from generic Nuxt or Vue patterns.
+3. Use the source link when behavior is version-sensitive or the docs are ambiguous.
+4. Keep this module guidance scoped to \`${entry.packageName}\`; do not replace broader Nuxt rules outside module-owned surfaces.
+`;
+}
 
 async function loadSkillFilesFromDir(dir, skip) {
   const skipSet = skip ? new Set(skip) : void 0;
@@ -494,24 +541,15 @@ function resolveSkillsDir(target, config) {
   }
   return void 0;
 }
-function normalizeTarget(target) {
-  return target.trim();
-}
-function getRawTargetConfig(target) {
-  return getAgentConfig(target);
-}
 function getSupportedTargets() {
-  return getAgentIds().filter((target) => {
-    const config = getRawTargetConfig(target);
-    return Boolean(resolveSkillsDir(target, config));
-  }).sort((a, b) => a.localeCompare(b));
+  return getAgentIds().filter((target) => Boolean(resolveSkillsDir(target, getAgentConfig(target)))).sort((a, b) => a.localeCompare(b));
 }
 function resolveAgentTargetConfig(target) {
-  const normalized = normalizeTarget(target);
+  const normalized = target.trim();
   if (!normalized) {
     return void 0;
   }
-  const config = getRawTargetConfig(normalized);
+  const config = getAgentConfig(normalized);
   const skillsDir = resolveSkillsDir(normalized, config);
   if (!config || !skillsDir) {
     return void 0;
@@ -523,11 +561,11 @@ function resolveAgentTargetConfig(target) {
   };
 }
 function validateTargets(targets) {
-  const uniqueTargets = Array.from(new Set(targets.map(normalizeTarget).filter(Boolean)));
+  const uniqueTargets = Array.from(new Set(targets.map((target) => target.trim()).filter(Boolean)));
   const valid = [];
   const invalid = [];
   for (const target of uniqueTargets) {
-    const config = getRawTargetConfig(target);
+    const config = getAgentConfig(target);
     if (!config) {
       invalid.push({
         target,
@@ -562,6 +600,24 @@ const MANAGED_HINT_START = "<!-- nuxt-skill-hub:start -->";
 const MANAGED_HINT_END = "<!-- nuxt-skill-hub:end -->";
 const SKILL_NAME_MAX_LENGTH = 64;
 const SKILL_NAME_PATTERN = /^[a-z0-9-]+$/;
+async function mapWithConcurrency(items, concurrency, mapper) {
+  if (!items.length) {
+    return [];
+  }
+  const results = [];
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (true) {
+      const index = nextIndex++;
+      if (index >= items.length) {
+        return;
+      }
+      results[index] = await mapper(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
 async function pathExists(path) {
   try {
     await promises.access(path);
@@ -725,6 +781,22 @@ function readRepositoryUrl(repository) {
   if (repository && typeof repository.url === "string") return repository.url;
   return void 0;
 }
+function readUrlValues(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap(readUrlValues);
+  }
+  if (typeof value === "string" && value.trim()) {
+    return [value.trim()];
+  }
+  if (value && typeof value === "object" && "url" in value) {
+    const url = value.url;
+    return typeof url === "string" && url.trim() ? [url.trim()] : [];
+  }
+  return [];
+}
+function dedupe$1(values) {
+  return [...new Set(values.filter((value) => Boolean(value)))];
+}
 async function discoverInstalledPackageFromSpecifier(specifier, rootDir) {
   if (!isPackageSpecifier(specifier)) {
     return null;
@@ -746,8 +818,29 @@ async function discoverInstalledPackageFromDirectory(directory) {
   }
   return readInstalledPackageMetadata(packageJsonPath);
 }
+async function collectInstalledModulePackages(modules, rootDir) {
+  const specifiers = Array.from(new Set(
+    (modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry))
+  ));
+  const resolved = await Promise.all(
+    specifiers.map((specifier) => discoverInstalledPackageFromSpecifier(specifier, rootDir))
+  );
+  const seenPackageRoots = /* @__PURE__ */ new Set();
+  const packages = [];
+  for (const pkg of resolved) {
+    if (!pkg || seenPackageRoots.has(pkg.packageRoot)) continue;
+    seenPackageRoots.add(pkg.packageRoot);
+    packages.push(pkg);
+  }
+  return packages;
+}
 async function readInstalledPackageMetadata(packageJsonPath, fallbackSpecifier) {
   const pkg = await readPackageJSON(packageJsonPath);
+  const docsUrls = dedupe$1([
+    ...readUrlValues(pkg.docs),
+    ...readUrlValues(pkg.documentation),
+    ...readUrlValues(pkg.homepage)
+  ]);
   return {
     packageName: pkg.name || (fallbackSpecifier ? packageNameFromSpecifier(fallbackSpecifier) : basename(dirname(packageJsonPath))),
     version: pkg.version,
@@ -755,6 +848,7 @@ async function readInstalledPackageMetadata(packageJsonPath, fallbackSpecifier)
     packageRoot: dirname(packageJsonPath),
     repository: readRepositoryUrl(pkg.repository),
     homepage: pkg.homepage,
+    docsUrls,
     packageData: pkg
   };
 }
@@ -863,15 +957,15 @@ async function validateContribution(contribution) {
   };
 }
 async function validateResolvedContributions(contributions) {
+  const validations = await Promise.all(contributions.map(validateContribution));
   const valid = [];
   const issues = [];
-  for (const contribution of contributions) {
-    const validation = await validateContribution(contribution);
-    if (!validation.issues.length) {
-      valid.push(validation.contribution);
+  for (const validation of validations) {
+    if (validation.issues.length) {
+      issues.push(...validation.issues);
       continue;
     }
-    issues.push(...validation.issues);
+    valid.push(validation.contribution);
   }
   return {
     contributions: sortAndDedupeContributions(valid),
@@ -1040,7 +1134,7 @@ function formatConflictWarning(conflict) {
   return `Found ${conflict.skillNames.length} standalone skill(s) that may conflict with nuxt-skill-hub: ${conflict.skillNames.join(", ")} (global: ${conflict.globalDir}). Remove with: npx skills remove --global`;
 }
 
-const GITHUB_OVERRIDES = [
+const PACKAGE_OVERRIDES = [
   {
     packageName: "@nuxt/ui",
     repo: "nuxt/ui",
@@ -1054,10 +1148,15 @@ const GITHUB_OVERRIDES = [
     ref: "main",
     path: "skills/vueuse-functions",
     skillName: "vueuse-functions"
+  },
+  {
+    packageName: "docus",
+    repo: "nuxt-content/docus",
+    docsUrls: ["https://docus.dev/"]
   }
 ];
-function findGitHubOverride(packageName) {
-  return GITHUB_OVERRIDES.find((entry) => entry.packageName === packageName);
+function findPackageOverride(packageName) {
+  return PACKAGE_OVERRIDES.find((entry) => entry.packageName === packageName);
 }
 
 const GITHUB_API_BASE = "https://api.github.com";
@@ -1065,6 +1164,8 @@ const UNGH_API_BASE = "https://ungh.cc";
 const githubDirectoryCache = /* @__PURE__ */ new Map();
 const githubDefaultBranchCache = /* @__PURE__ */ new Map();
 const githubFileTextCache = /* @__PURE__ */ new Map();
+const urlTextCache = /* @__PURE__ */ new Map();
+const urlBytesCache = /* @__PURE__ */ new Map();
 function githubFetchOptions(timeoutMs) {
   return {
     timeout: timeoutMs,
@@ -1074,6 +1175,9 @@ function githubFetchOptions(timeoutMs) {
     }
   };
 }
+function fetchStatus(error) {
+  return typeof error === "object" && error && "status" in error ? Number(error.status) : void 0;
+}
 function encodeGitHubPath(path) {
   return path.split("/").filter(Boolean).map((segment) => encodeURIComponent(segment)).join("/");
 }
@@ -1180,16 +1284,591 @@ async function fetchGitHubFileText(repo, ref, filePath, timeoutMs) {
       );
       return { ok: true, data };
     } catch (error) {
-      const status = typeof error === "object" && error && "status" in error ? Number(error.status) : void 0;
       return {
         ok: false,
-        status,
+        status: fetchStatus(error),
+        error: error.message
+      };
+    }
+  });
+}
+async function fetchUrlText(url, timeoutMs) {
+  return await memoize(urlTextCache, url, async () => {
+    try {
+      const data = await ofetch(url, {
+        ...githubFetchOptions(timeoutMs),
+        responseType: "text"
+      });
+      return { ok: true, data };
+    } catch (error) {
+      return {
+        ok: false,
+        status: fetchStatus(error),
+        error: error.message
+      };
+    }
+  });
+}
+async function fetchUrlJson(url, timeoutMs) {
+  const text = await fetchUrlText(url, timeoutMs);
+  if (!text.ok) {
+    return {
+      ok: false,
+      status: text.status,
+      error: text.error
+    };
+  }
+  try {
+    return {
+      ok: true,
+      data: JSON.parse(text.data || "")
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error.message
+    };
+  }
+}
+async function fetchUrlBytes(url, timeoutMs) {
+  return await memoize(urlBytesCache, url, async () => {
+    try {
+      const data = await ofetch(url, {
+        ...githubFetchOptions(timeoutMs),
+        responseType: "arrayBuffer"
+      });
+      return {
+        ok: true,
+        data: new Uint8Array(data)
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        status: fetchStatus(error),
         error: error.message
       };
     }
   });
 }
 
+const DEFAULT_SKILL_HUB_GENERATION_MODE = "prepare";
+const DEFAULT_REMOTE_TIMEOUT_MS = 1500;
+const DEFAULT_REMOTE_CACHE_TTL_MS = 1e3 * 60 * 60 * 24;
+const DEFAULT_REMOTE_CONCURRENCY = 8;
+const DEFAULT_WELL_KNOWN_MAX_FILES = 40;
+const DEFAULT_WELL_KNOWN_MAX_BYTES = 512 * 1024;
+const DEFAULT_WELL_KNOWN_MAX_FILE_BYTES = 128 * 1024;
+function normalizeGenerationMode(value) {
+  return value === "manual" ? "manual" : DEFAULT_SKILL_HUB_GENERATION_MODE;
+}
+function positiveNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function nonNegativeNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function positiveInteger(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function normalizeRemoteOptions(value) {
+  const options = typeof value === "object" && value ? value : {};
+  const enabled = typeof value === "boolean" ? value : options.enabled !== false;
+  return {
+    enabled,
+    timeoutMs: positiveNumber(options.timeoutMs, DEFAULT_REMOTE_TIMEOUT_MS),
+    concurrency: positiveInteger(options.concurrency, DEFAULT_REMOTE_CONCURRENCY),
+    refresh: options.refresh === true,
+    cacheTtlMs: nonNegativeNumber(options.cacheTtlMs, DEFAULT_REMOTE_CACHE_TTL_MS),
+    githubHeuristics: options.githubHeuristics === true,
+    timings: options.timings === true,
+    maxFiles: positiveNumber(options.maxFiles, DEFAULT_WELL_KNOWN_MAX_FILES),
+    maxBytes: positiveNumber(options.maxBytes, DEFAULT_WELL_KNOWN_MAX_BYTES),
+    maxFileBytes: positiveNumber(options.maxFileBytes, DEFAULT_WELL_KNOWN_MAX_FILE_BYTES)
+  };
+}
+
+const WELL_KNOWN_DISCOVERY_V2_SCHEMA = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+const WELL_KNOWN_DISCOVERY_V2_INDEX_PATH = "/.well-known/agent-skills/index.json";
+const WELL_KNOWN_SKILLS_INDEX_PATH = "/.well-known/skills/index.json";
+const WELL_KNOWN_ENTRY_CONCURRENCY = 4;
+const WELL_KNOWN_FILE_CONCURRENCY = 8;
+function normalizeLimits(limits = {}) {
+  return {
+    maxFiles: typeof limits.maxFiles === "number" && Number.isFinite(limits.maxFiles) && limits.maxFiles > 0 ? limits.maxFiles : DEFAULT_WELL_KNOWN_MAX_FILES,
+    maxBytes: typeof limits.maxBytes === "number" && Number.isFinite(limits.maxBytes) && limits.maxBytes > 0 ? limits.maxBytes : DEFAULT_WELL_KNOWN_MAX_BYTES,
+    maxFileBytes: typeof limits.maxFileBytes === "number" && Number.isFinite(limits.maxFileBytes) && limits.maxFileBytes > 0 ? limits.maxFileBytes : DEFAULT_WELL_KNOWN_MAX_FILE_BYTES
+  };
+}
+function makeSkip$1(packageName, skillName, reason) {
+  return {
+    packageName,
+    skillName,
+    reason,
+    sourceKind: "wellKnown"
+  };
+}
+function normalizeHttpUrl$1(url) {
+  const trimmed = url?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.toString() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function normalizeHostname(hostname) {
+  return hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+}
+function parseIpv4(hostname) {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const octets = parts.map((part) => {
+    if (!/^\d+$/.test(part)) {
+      return Number.NaN;
+    }
+    return Number(part);
+  });
+  if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+    return null;
+  }
+  return octets;
+}
+function isPrivateIpv4(hostname) {
+  const octets = parseIpv4(normalizeHostname(hostname));
+  if (!octets) {
+    return false;
+  }
+  const [a, b] = octets;
+  return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a >= 224 && a <= 239 || a >= 240;
+}
+function isPrivateIpv6(hostname) {
+  const normalized = normalizeHostname(hostname);
+  return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb");
+}
+function isUnsafeHostname(hostname) {
+  const normalized = normalizeHostname(hostname);
+  if (normalized === "localhost" || normalized.endsWith(".localhost")) {
+    return true;
+  }
+  const ipVersion = isIP(normalized);
+  if (ipVersion === 4) {
+    return isPrivateIpv4(normalized);
+  }
+  if (ipVersion === 6) {
+    return isPrivateIpv6(normalized);
+  }
+  return false;
+}
+function isPublicDiscoveryBase(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.hostname === "github.com" || parseGitHubRepo(url) || isUnsafeHostname(parsed.hostname)) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isSameOriginUrl(url, baseUrl) {
+  return new URL(url).origin === new URL(baseUrl).origin;
+}
+function resolveSameOriginUrl(rawUrl, baseUrl) {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    const resolved = new URL(trimmed, baseUrl);
+    if (!isSameOriginUrl(resolved.toString(), baseUrl) || isUnsafeHostname(resolved.hostname)) {
+      return null;
+    }
+    return resolved.toString();
+  } catch {
+    return null;
+  }
+}
+function docsBaseCandidates(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
+  const candidates = [
+    ...override?.docsUrls || [],
+    ...packageInfo.docsUrls || [],
+    packageInfo.homepage || ""
+  ];
+  return [...new Set(candidates.map(normalizeHttpUrl$1).filter((url) => Boolean(url)).filter(isPublicDiscoveryBase))];
+}
+function normalizeDigest(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return /^sha256:[a-f0-9]{64}$/.test(trimmed) ? trimmed : null;
+}
+function sha256(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function normalizeSkillFilePath(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim().replaceAll("\\", "/");
+  if (!trimmed || trimmed.startsWith("/") || trimmed.includes("\0")) {
+    return null;
+  }
+  const segments = trimmed.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    return null;
+  }
+  return trimmed;
+}
+function isSupportedSkillContextFile(path) {
+  return path === "SKILL.md" || path.endsWith(".md") || path.endsWith(".json");
+}
+async function writeSkillFile(root, relativePath, bytes) {
+  const destination = join(root, relativePath);
+  await ensureDir(dirname(destination));
+  await promises.writeFile(destination, bytes);
+}
+function contributionFor(input) {
+  const sourceRepo = parseGitHubRepo(input.packageInfo.repository);
+  return normalizeContribution({
+    packageName: input.packageInfo.packageName,
+    version: input.packageInfo.version,
+    sourceDir: input.targetDir,
+    skillName: input.skillName,
+    description: input.description,
+    sourceKind: "wellKnown",
+    sourceRepo: sourceRepo || void 0,
+    sourcePath: input.indexUrl,
+    repoUrl: sourceRepo ? `https://github.com/${sourceRepo}` : void 0,
+    docsUrl: input.docsUrl,
+    official: true,
+    resolver: input.resolver,
+    forceIncludeScripts: true
+  }, input.targetDir, join(input.targetDir, ".."));
+}
+async function materializeSkillsIndexEntry(input) {
+  const skillName = typeof input.entry.name === "string" ? input.entry.name.trim() : "";
+  if (!isValidSkillName(skillName)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName || "entry", "well-known skill name is invalid") };
+  }
+  const description = typeof input.entry.description === "string" ? input.entry.description.trim() : "";
+  if (!description) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill is missing a description") };
+  }
+  if (!Array.isArray(input.entry.files)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill is missing a files array") };
+  }
+  const files = [...new Set(input.entry.files.map(normalizeSkillFilePath).filter((file) => Boolean(file)))];
+  if (!files.includes("SKILL.md")) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill must list SKILL.md") };
+  }
+  if (files.length !== input.entry.files.length) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill includes an unsafe file path") };
+  }
+  if (files.some((file) => !isSupportedSkillContextFile(file))) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill includes a non-context file; only .md and .json files are supported") };
+  }
+  if (files.length > input.limits.maxFiles) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known skill lists ${files.length} files, exceeding the limit of ${input.limits.maxFiles}`) };
+  }
+  const origin = new URL(input.docsUrl).origin;
+  const targetDir = join(
+    input.cacheRoot,
+    "well-known",
+    "skills",
+    sanitizeSegment(origin),
+    sanitizeSegment(input.packageInfo.packageName),
+    sanitizeSegment(input.packageInfo.version || "unknown"),
+    sanitizeSegment(skillName)
+  );
+  const fileUrls = files.map((file) => {
+    const fileUrl = resolveSameOriginUrl(`${skillName}/${file}`, new URL("./", input.indexUrl).toString());
+    if (!fileUrl) {
+      return null;
+    }
+    return { file, fileUrl };
+  });
+  if (fileUrls.includes(null)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known skill file URL must stay on the discovery origin") };
+  }
+  const fetchedFiles = [];
+  let totalBytes = 0;
+  const responses = await mapWithConcurrency(
+    fileUrls,
+    WELL_KNOWN_FILE_CONCURRENCY,
+    async ({ file, fileUrl }) => ({
+      file,
+      response: await fetchUrlBytes(fileUrl, input.timeoutMs)
+    })
+  );
+  for (const { file, response } of responses) {
+    if (!response.ok || !response.data) {
+      return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `failed to fetch well-known skill file ${file}`) };
+    }
+    if (response.data.byteLength > input.limits.maxFileBytes) {
+      return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known skill file ${file} exceeds the per-file limit of ${input.limits.maxFileBytes} bytes`) };
+    }
+    totalBytes += response.data.byteLength;
+    if (totalBytes > input.limits.maxBytes) {
+      return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known skill files exceed the total limit of ${input.limits.maxBytes} bytes`) };
+    }
+    fetchedFiles.push({ path: file, bytes: response.data });
+  }
+  await emptyDir(targetDir);
+  for (const file of fetchedFiles) {
+    await writeSkillFile(targetDir, file.path, file.bytes);
+  }
+  return {
+    contribution: contributionFor({
+      packageInfo: input.packageInfo,
+      targetDir,
+      skillName,
+      description,
+      docsUrl: input.docsUrl,
+      resolver: "wellKnownSkills",
+      indexUrl: input.indexUrl
+    })
+  };
+}
+async function materializeV2Skill(input) {
+  const skillName = typeof input.entry.name === "string" ? input.entry.name.trim() : "";
+  if (!isValidSkillName(skillName)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName || "entry", "well-known v2 skill name is invalid") };
+  }
+  const description = typeof input.entry.description === "string" ? input.entry.description.trim() : "";
+  if (!description) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a description") };
+  }
+  const type = typeof input.entry.type === "string" ? input.entry.type.trim() : "";
+  if (type === "archive") {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "archive artifacts are not supported yet") };
+  }
+  if (type !== "skill-md") {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `unsupported well-known v2 skill type "${type || "unknown"}"`) };
+  }
+  if (typeof input.entry.url !== "string" || !input.entry.url.trim()) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a URL") };
+  }
+  const digest = normalizeDigest(input.entry.digest);
+  if (!digest) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a valid sha256 digest") };
+  }
+  const skillUrl = resolveSameOriginUrl(input.entry.url, input.indexUrl);
+  if (!skillUrl) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill URL must stay on the discovery origin") };
+  }
+  const response = await fetchUrlBytes(skillUrl, input.timeoutMs);
+  if (!response.ok || !response.data) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "failed to fetch well-known v2 skill artifact") };
+  }
+  if (sha256(response.data) !== digest) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill digest mismatch") };
+  }
+  if (response.data.byteLength > input.limits.maxFileBytes || response.data.byteLength > input.limits.maxBytes) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `well-known v2 skill exceeds the file size limit of ${Math.min(input.limits.maxFileBytes, input.limits.maxBytes)} bytes`) };
+  }
+  const origin = new URL(input.docsUrl).origin;
+  const targetDir = join(
+    input.cacheRoot,
+    "well-known",
+    "rfc",
+    sanitizeSegment(origin),
+    sanitizeSegment(input.packageInfo.packageName),
+    sanitizeSegment(input.packageInfo.version || "unknown"),
+    sanitizeSegment(skillName)
+  );
+  await emptyDir(targetDir);
+  await writeSkillFile(targetDir, "SKILL.md", response.data);
+  return {
+    contribution: contributionFor({
+      packageInfo: input.packageInfo,
+      targetDir,
+      skillName,
+      description,
+      docsUrl: input.docsUrl,
+      resolver: "wellKnownV2",
+      indexUrl: input.indexUrl
+    })
+  };
+}
+async function resolveSkillsIndex(input) {
+  const skipped = [];
+  const contributions = [];
+  if (!Array.isArray(input.index.skills)) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known skills index is missing a skills array")]
+    };
+  }
+  const materializedEntries = await mapWithConcurrency(
+    input.index.skills,
+    WELL_KNOWN_ENTRY_CONCURRENCY,
+    async (rawEntry) => {
+      if (!rawEntry || typeof rawEntry !== "object") {
+        return { skipped: makeSkip$1(input.packageInfo.packageName, "entry", "well-known skill entry must be an object") };
+      }
+      return await materializeSkillsIndexEntry({
+        packageInfo: input.packageInfo,
+        entry: rawEntry,
+        indexUrl: input.indexUrl,
+        docsUrl: input.docsUrl,
+        cacheRoot: input.cacheRoot,
+        timeoutMs: input.timeoutMs,
+        limits: input.limits
+      });
+    }
+  );
+  for (const materialized of materializedEntries) {
+    if (materialized?.contribution) {
+      contributions.push(materialized.contribution);
+    }
+    if (materialized?.skipped) {
+      skipped.push(materialized.skipped);
+    }
+  }
+  return { contributions, issues: [], skipped };
+}
+async function resolveV2Index(input) {
+  const skipped = [];
+  const contributions = [];
+  if (!Array.isArray(input.index.skills)) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known v2 index is missing a skills array")]
+    };
+  }
+  const materializedEntries = await mapWithConcurrency(
+    input.index.skills,
+    WELL_KNOWN_ENTRY_CONCURRENCY,
+    async (rawEntry) => {
+      if (!rawEntry || typeof rawEntry !== "object") {
+        return { skipped: makeSkip$1(input.packageInfo.packageName, "entry", "well-known v2 skill entry must be an object") };
+      }
+      return await materializeV2Skill({
+        packageInfo: input.packageInfo,
+        entry: rawEntry,
+        indexUrl: input.indexUrl,
+        docsUrl: input.docsUrl,
+        cacheRoot: input.cacheRoot,
+        timeoutMs: input.timeoutMs,
+        limits: input.limits
+      });
+    }
+  );
+  for (const materialized of materializedEntries) {
+    if (materialized?.contribution) {
+      contributions.push(materialized.contribution);
+    }
+    if (materialized?.skipped) {
+      skipped.push(materialized.skipped);
+    }
+  }
+  return { contributions, issues: [], skipped };
+}
+async function resolveIndex(input) {
+  const response = await fetchUrlJson(input.indexUrl, input.timeoutMs);
+  if (!response.ok) {
+    if (response.status === 404) {
+      return null;
+    }
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, `failed to fetch well-known index ${input.indexUrl}`)]
+    };
+  }
+  const index = response.data;
+  if (!index || typeof index !== "object") {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known index must be an object")]
+    };
+  }
+  if (index.$schema === WELL_KNOWN_DISCOVERY_V2_SCHEMA) {
+    return await resolveV2Index({
+      ...input,
+      index
+    });
+  }
+  if (new URL(input.indexUrl).pathname === WELL_KNOWN_SKILLS_INDEX_PATH && !index.$schema) {
+    return await resolveSkillsIndex({
+      ...input,
+      index
+    });
+  }
+  if (typeof index.$schema === "string" && index.$schema) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, `unsupported well-known schema "${index.$schema}"`)]
+    };
+  }
+  return {
+    contributions: [],
+    issues: [],
+    skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known index is missing the v2 schema")]
+  };
+}
+async function resolveViaWellKnown(packageInfo, cacheRoot, timeoutMs, rawLimits) {
+  const bases = docsBaseCandidates(packageInfo);
+  const skipped = [];
+  const issues = [];
+  const limits = normalizeLimits(rawLimits);
+  const attempts = bases.flatMap((docsUrl) => {
+    return [
+      new URL(WELL_KNOWN_DISCOVERY_V2_INDEX_PATH, docsUrl).toString(),
+      new URL(WELL_KNOWN_SKILLS_INDEX_PATH, docsUrl).toString()
+    ].map((indexUrl) => ({ docsUrl, indexUrl }));
+  });
+  const results = await Promise.all(
+    attempts.map(async ({ docsUrl, indexUrl }) => ({
+      result: await resolveIndex({
+        packageInfo,
+        indexUrl,
+        docsUrl,
+        cacheRoot,
+        timeoutMs,
+        limits
+      })
+    }))
+  );
+  for (const { result } of results) {
+    if (!result) {
+      continue;
+    }
+    issues.push(...result.issues);
+    skipped.push(...result.skipped);
+    if (result.contributions.length) {
+      return {
+        contributions: result.contributions,
+        issues,
+        skipped
+      };
+    }
+  }
+  if (!bases.length) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: []
+    };
+  }
+  return {
+    contributions: [],
+    issues,
+    skipped
+  };
+}
+
 function makeSkip(packageName, skillName, reason, sourceKind) {
   return {
     packageName,
@@ -1231,8 +1910,15 @@ function normalizeHttpUrl(url) {
     return void 0;
   }
 }
+function resolveDocsUrl(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
+  const overrideDocsUrl = override?.docsUrls?.map(normalizeHttpUrl).find(Boolean);
+  const packageDocsUrl = packageInfo.docsUrls?.map(normalizeHttpUrl).find(Boolean);
+  return overrideDocsUrl || packageDocsUrl || normalizeHttpUrl(packageInfo.homepage);
+}
 function resolveRepositoryUrl(packageInfo) {
-  const sourceRepo = parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
+  const override = findPackageOverride(packageInfo.packageName);
+  const sourceRepo = override?.repo || parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
   if (sourceRepo) {
     return {
       sourceRepo,
@@ -1304,18 +1990,9 @@ async function materializeCandidate(packageInfo, candidate, cacheRoot) {
     forceIncludeScripts: true
   }, targetDir, join(targetDir, ".."));
 }
-async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
-  const issues = [];
-  const skipped = [];
-  const override = findGitHubOverride(packageInfo.packageName);
+function createGitHubResolveContext(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
   const repo = override?.repo || parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
-  if (!repo) {
-    return {
-      contributions: [],
-      issues,
-      skipped: [makeSkip(packageInfo.packageName, override?.skillName || packageInfo.packageName, "No GitHub repository metadata found", "github")]
-    };
-  }
   const refs = dedupe([
     override?.ref || "",
     packageInfo.version ? `v${packageInfo.version}` : "",
@@ -1335,35 +2012,89 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
       ];
     })
   ]);
-  const tryResolveForRef = async (ref, allowTreeLookup) => {
-    const packageJson = await fetchGitHubFileText(repo, ref, "package.json", timeoutMs);
-    if (packageJson.ok && packageJson.data) {
-      try {
-        const parsed = JSON.parse(packageJson.data);
-        const remoteSkills = parseAgentSkillDeclarations(parsed, packageInfo.packageName, "github");
-        issues.push(...remoteSkills.issues);
-        for (const skill of remoteSkills.skills) {
-          const resolved = await materializeCandidate(packageInfo, {
-            skillName: skill.name,
-            sourcePath: skill.path,
-            sourceKind: "github",
-            sourceRepo: repo,
-            sourceRef: ref,
-            official: true,
-            resolver: "agentsField"
-          }, cacheRoot);
-          if (resolved) {
-            return [resolved];
-          }
-        }
-      } catch {
-        issues.push(createValidationIssue(packageInfo.packageName, packageInfo.packageName, "Failed to parse remote package.json", "github"));
+  return {
+    issues: [],
+    skipped: [],
+    override,
+    repo: repo || void 0,
+    refs,
+    pathCandidates
+  };
+}
+async function resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs) {
+  if (!context.repo) {
+    return null;
+  }
+  const packageJson = await fetchGitHubFileText(context.repo, ref, "package.json", timeoutMs);
+  if (!packageJson.ok || !packageJson.data) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(packageJson.data);
+    const remoteSkills = parseAgentSkillDeclarations(parsed, packageInfo.packageName, "github");
+    context.issues.push(...remoteSkills.issues);
+    for (const skill of remoteSkills.skills) {
+      const resolved = await materializeCandidate(packageInfo, {
+        skillName: skill.name,
+        sourcePath: skill.path,
+        sourceKind: "github",
+        sourceRepo: context.repo,
+        sourceRef: ref,
+        official: true,
+        resolver: "agentsField"
+      }, cacheRoot);
+      if (resolved) {
+        return [resolved];
       }
     }
-    if (!allowTreeLookup) {
-      return null;
+  } catch {
+    context.issues.push(createValidationIssue(packageInfo.packageName, packageInfo.packageName, "Failed to parse remote package.json", "github"));
+  }
+  return null;
+}
+async function resolveViaGitHubAgents(packageInfo, cacheRoot, timeoutMs) {
+  const context = createGitHubResolveContext(packageInfo);
+  if (!context.repo) {
+    return {
+      contributions: [],
+      issues: context.issues,
+      skipped: []
+    };
+  }
+  for (const ref of context.refs) {
+    const resolved = await resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
+    }
+  }
+  const fallbackRefs = dedupe([
+    await fetchGitHubDefaultBranch(context.repo, timeoutMs) || "",
+    "main",
+    "master"
+  ]);
+  for (const ref of fallbackRefs) {
+    const resolved = await resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
     }
-    const skillsDirs = await listGitHubDirectory(repo, ref, "skills", timeoutMs);
+  }
+  return {
+    contributions: [],
+    issues: context.issues,
+    skipped: context.skipped
+  };
+}
+async function resolveViaGitHubHeuristics(packageInfo, cacheRoot, timeoutMs) {
+  const context = createGitHubResolveContext(packageInfo);
+  if (!context.repo) {
+    return {
+      contributions: [],
+      issues: context.issues,
+      skipped: [makeSkip(packageInfo.packageName, context.override?.skillName || packageInfo.packageName, "No GitHub repository metadata found", "github")]
+    };
+  }
+  const tryResolveForRef = async (ref, allowTreeLookup) => {
+    const skillsDirs = await listGitHubDirectory(context.repo, ref, "skills", timeoutMs) ;
     if (skillsDirs.length) {
       const contributions = [];
       for (const skillName of skillsDirs) {
@@ -1371,7 +2102,7 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
           skillName,
           sourcePath: `skills/${skillName}`,
           sourceKind: "github",
-          sourceRepo: repo,
+          sourceRepo: context.repo,
           sourceRef: ref,
           official: true,
           resolver: "githubHeuristic"
@@ -1384,13 +2115,13 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
         return contributions;
       }
     }
-    for (const path of pathCandidates) {
-      const candidateSkillName = override?.path && path === override.path ? override.skillName || path.split("/").pop() || packageInfo.packageName : path.split("/").pop() || packageInfo.packageName;
+    for (const path of context.pathCandidates) {
+      const candidateSkillName = context.override?.path && path === context.override.path ? context.override.skillName || path.split("/").pop() || packageInfo.packageName : path.split("/").pop() || packageInfo.packageName;
       const resolved = await materializeCandidate(packageInfo, {
         skillName: candidateSkillName,
         sourcePath: path,
         sourceKind: "github",
-        sourceRepo: repo,
+        sourceRepo: context.repo,
         sourceRef: ref,
         official: true,
         resolver: "githubHeuristic"
@@ -1401,39 +2132,33 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
     }
     return null;
   };
-  for (const ref of refs) {
-    const resolved = await tryResolveForRef(ref, false);
-    if (resolved?.length) {
-      return { contributions: resolved, issues, skipped };
-    }
-  }
   const fallbackRefs = dedupe([
-    await fetchGitHubDefaultBranch(repo, timeoutMs) || "",
+    await fetchGitHubDefaultBranch(context.repo, timeoutMs) || "",
     "main",
     "master"
   ]);
   for (const ref of fallbackRefs) {
-    const resolved = await tryResolveForRef(ref, true);
+    const resolved = await tryResolveForRef(ref);
     if (resolved?.length) {
-      return { contributions: resolved, issues, skipped };
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
     }
   }
-  for (const ref of refs) {
-    const resolved = await tryResolveForRef(ref, true);
+  for (const ref of context.refs) {
+    const resolved = await tryResolveForRef(ref);
     if (resolved?.length) {
-      return { contributions: resolved, issues, skipped };
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
     }
   }
-  skipped.push(makeSkip(packageInfo.packageName, override?.skillName || packageInfo.packageName, "No GitHub skill found using configured refs and path heuristics", "github"));
+  context.skipped.push(makeSkip(packageInfo.packageName, context.override?.skillName || packageInfo.packageName, "No GitHub skill found using configured refs and path heuristics", "github"));
   return {
     contributions: [],
-    issues,
-    skipped
+    issues: context.issues,
+    skipped: context.skipped
   };
 }
 async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
   const { repoUrl, sourceRepo } = resolveRepositoryUrl(packageInfo);
-  const docsUrl = normalizeHttpUrl(packageInfo.homepage);
+  const docsUrl = resolveDocsUrl(packageInfo);
   if (!repoUrl && !docsUrl) {
     return {
       contributions: [],
@@ -1505,34 +2230,57 @@ async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
   };
 }
 async function resolveRemoteContributionsForPackage(packageInfo, options) {
-  const githubResult = options.enableGithubLookup ? await resolveViaGitHub(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+  const githubAgentsPromise = options.enableGithubLookup ? resolveViaGitHubAgents(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
     contributions: [],
     issues: [],
     skipped: []
   };
-  if (githubResult.contributions.length) {
-    return githubResult;
+  const wellKnownPromise = options.enableWellKnownLookup === false ? {
+    contributions: [],
+    issues: [],
+    skipped: []
+  } : resolveViaWellKnown(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs, options.wellKnownLimits);
+  const [githubAgentsResult, wellKnownResult] = await Promise.all([
+    githubAgentsPromise,
+    wellKnownPromise
+  ]);
+  if (githubAgentsResult.contributions.length) {
+    return githubAgentsResult;
+  }
+  if (wellKnownResult.contributions.length) {
+    return {
+      contributions: wellKnownResult.contributions,
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues],
+      skipped: wellKnownResult.skipped
+    };
+  }
+  const githubHeuristicResult = options.enableGithubLookup && options.enableGithubHeuristics ? await resolveViaGitHubHeuristics(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+    contributions: [],
+    issues: [],
+    skipped: []
+  };
+  if (githubHeuristicResult.contributions.length) {
+    return {
+      contributions: githubHeuristicResult.contributions,
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues],
+      skipped: wellKnownResult.skipped
+    };
   }
   const generatedResult = await resolveViaMetadataRouter(packageInfo, options.cacheRoot);
   if (generatedResult.contributions.length) {
     return {
       contributions: generatedResult.contributions,
-      issues: [...githubResult.issues, ...generatedResult.issues],
-      skipped: generatedResult.skipped
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues, ...generatedResult.issues],
+      skipped: [...wellKnownResult.skipped, ...generatedResult.skipped]
     };
   }
   return {
     contributions: [],
-    issues: [...githubResult.issues, ...generatedResult.issues],
-    skipped: [...githubResult.skipped, ...generatedResult.skipped]
+    issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues, ...generatedResult.issues],
+    skipped: [...wellKnownResult.skipped, ...githubHeuristicResult.skipped, ...generatedResult.skipped]
   };
 }
 
-const DEFAULT_SKILL_HUB_GENERATION_MODE = "prepare";
-function normalizeGenerationMode(value) {
-  return value === "manual" ? "manual" : DEFAULT_SKILL_HUB_GENERATION_MODE;
-}
-
 async function resolveLockfileInfo(exportRoot) {
   let lockfilePath;
   try {
@@ -1569,7 +2317,8 @@ async function createGenerationFingerprint(input) {
       skillName: input.options.skillName?.trim() || null,
       targets: [...input.options.targets || []].sort(),
       moduleAuthoring: Boolean(input.options.moduleAuthoring),
-      generationMode: normalizeGenerationMode(input.options.generationMode)
+      generationMode: normalizeGenerationMode(input.options.generationMode),
+      remote: normalizeRemoteOptions(input.options.remote)
     }
   });
 }
@@ -1582,6 +2331,7 @@ async function hashFileIfExists(path) {
   }
 }
 
+const HASH_READ_CONCURRENCY = 16;
 async function resolveManualContribution(rootDir, contribution) {
   const sourceDir = isAbsolute(contribution.sourceDir) ? contribution.sourceDir : resolve(rootDir, contribution.sourceDir);
   return normalizeContribution(contribution, sourceDir, sourceDir);
@@ -1633,8 +2383,6 @@ async function hashDirectoryTreeIfExists(rootPath) {
   if (!rootStat.isDirectory()) {
     return null;
   }
-  const hash = createHash("sha256");
-  hash.update("dir:.\n");
   const entries = await glob("**/*", {
     cwd: rootPath,
     dot: true,
@@ -1643,30 +2391,20 @@ async function hashDirectoryTreeIfExists(rootPath) {
     onlyFiles: false
   });
   entries.sort((a, b) => a.localeCompare(b));
-  for (const entry of entries) {
+  const chunkGroups = await mapWithConcurrency(entries, HASH_READ_CONCURRENCY, async (entry) => {
     const currentPath = join(rootPath, entry);
     const stat = await promises.lstat(currentPath);
-    const relativePath = relative(rootPath, currentPath).replaceAll("\\", "/");
-    if (stat.isSymbolicLink()) {
-      hash.update(`symlink:${relativePath}:`);
-      hash.update(await promises.readlink(currentPath));
-      hash.update("\n");
-      continue;
-    }
-    if (stat.isDirectory()) {
-      hash.update(`dir:${relativePath}
-`);
-      continue;
-    }
-    if (stat.isFile()) {
-      hash.update(`file:${relativePath}:`);
-      hash.update(await promises.readFile(currentPath));
-      hash.update("\n");
-      continue;
-    }
-    hash.update(`other:${relativePath}:${stat.mode}
-`);
-  }
+    const rel = relative(rootPath, currentPath).replaceAll("\\", "/");
+    if (stat.isSymbolicLink()) return [`symlink:${rel}:`, await promises.readlink(currentPath), "\n"];
+    if (stat.isDirectory()) return [`dir:${rel}
+`];
+    if (stat.isFile()) return [`file:${rel}:`, await promises.readFile(currentPath), "\n"];
+    return [`other:${rel}:${stat.mode}
+`];
+  });
+  const hash = createHash("sha256");
+  hash.update("dir:.\n");
+  for (const chunks of chunkGroups) for (const chunk of chunks) hash.update(chunk);
   return hash.digest("hex");
 }
 
@@ -1694,16 +2432,29 @@ async function writeGenerationState(generatedSkillRoot, fingerprint) {
   await writeFileIfChanged(getGenerationStatePath(generatedSkillRoot), `${JSON.stringify(state, null, 2)}
 `);
 }
-async function isGeneratedSkillFresh(generatedSkillRoot, fingerprint) {
+async function isGeneratedSkillFreshWithOptions(generatedSkillRoot, fingerprint, options = {}) {
+  if (options.refresh) {
+    return false;
+  }
   const [state, entryExists] = await Promise.all([
     readGenerationState(generatedSkillRoot),
     pathExists(join(generatedSkillRoot, "SKILL.md"))
   ]);
-  return Boolean(entryExists && state?.fingerprint === fingerprint);
+  if (!entryExists || state?.fingerprint !== fingerprint) {
+    return false;
+  }
+  if (typeof options.cacheTtlMs === "number" && Number.isFinite(options.cacheTtlMs)) {
+    if (options.cacheTtlMs <= 0) {
+      return false;
+    }
+    const generatedAt = Date.parse(state.generatedAt);
+    if (!Number.isFinite(generatedAt) || Date.now() - generatedAt > options.cacheTtlMs) {
+      return false;
+    }
+  }
+  return true;
 }
 
-const GITHUB_LOOKUP_TIMEOUT_MS = 1500;
-const REMOTE_RESOLUTION_CONCURRENCY = 4;
 function resolveStableSkillBuildDir(rootDir, buildDir) {
   const rel = relative(resolve(rootDir), resolve(buildDir)).replaceAll("\\", "/");
   if (rel === ".nuxt" || rel.startsWith(".nuxt/")) {
@@ -1727,23 +2478,30 @@ function getPersistentCacheRoot(exportRoot) {
 function getCachedGeneratedSkillRoot(cacheRoot, skillName) {
   return join(cacheRoot, "generated", skillName);
 }
-async function mapWithConcurrency(items, concurrency, mapper) {
-  if (!items.length) {
-    return [];
+function roundMs(value) {
+  return Math.round(value * 10) / 10;
+}
+function formatMs(value) {
+  return value >= 1e3 ? `${(value / 1e3).toFixed(1)}s` : `${Math.round(value)}ms`;
+}
+function shouldLogTimings(nuxt, explicit) {
+  return explicit || Boolean(nuxt.options.debug);
+}
+function startPerfPhase(nuxt, name) {
+  nuxt._perf?.startPhase(name);
+}
+function endPerfPhase(nuxt, name) {
+  nuxt._perf?.endPhase(name);
+}
+function countResolvers(contributions) {
+  const counts = {};
+  for (const contribution of contributions) {
+    counts[contribution.resolver] = (counts[contribution.resolver] || 0) + 1;
   }
-  const results = [];
-  let nextIndex = 0;
-  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-    while (true) {
-      const index = nextIndex++;
-      if (index >= items.length) {
-        return;
-      }
-      results[index] = await mapper(items[index], index);
-    }
-  });
-  await Promise.all(workers);
-  return results;
+  return counts;
+}
+function formatResolverCounts(counts) {
+  return Object.entries(counts).map(([resolver, count]) => `${count} ${resolver}`).join(", ");
 }
 function mergeSkipped(entries, keyFn) {
   const byKey = /* @__PURE__ */ new Map();
@@ -1760,6 +2518,10 @@ function mergeSkipped(entries, keyFn) {
   }
   return Array.from(byKey.values()).sort((a, b) => `${a.packageName}::${a.skillName}`.localeCompare(`${b.packageName}::${b.skillName}`));
 }
+function filterResolvedSkipped(entries, contributions) {
+  const resolvedKeys = new Set(contributions.map((contribution) => `${contribution.packageName}::${contribution.skillName}`));
+  return entries.filter((entry) => !resolvedKeys.has(`${entry.packageName}::${entry.skillName}`));
+}
 async function removeLegacyRootArtifacts(skillRoot) {
   await Promise.all([
     promises.rm(join(skillRoot, "references"), { recursive: true, force: true }),
@@ -1781,17 +2543,13 @@ async function collectInstalledPackages(nuxt) {
       discoveries.push(discovered);
     }
   };
-  const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
-  const seenSpecifiers = Array.from(new Set(moduleSpecifiers));
-  for (const specifier of seenSpecifiers) {
-    addInstalledPackage(await discoverInstalledPackageFromSpecifier(specifier, nuxt.options.rootDir));
-  }
+  const modulePackages = await collectInstalledModulePackages(nuxt.options.modules, nuxt.options.rootDir);
+  for (const pkg of modulePackages) addInstalledPackage(pkg);
   const layerDirectories = Array.from(new Set(
     nuxt.options._layers.map((layer) => resolve(layer.cwd || layer.config.rootDir || "")).filter((layerDir) => layerDir && layerDir !== resolve(nuxt.options.rootDir))
   ));
-  for (const layerDirectory of layerDirectories) {
-    addInstalledPackage(await discoverInstalledPackageFromDirectory(layerDirectory));
-  }
+  const layerPackages = await Promise.all(layerDirectories.map((dir) => discoverInstalledPackageFromDirectory(dir)));
+  for (const pkg of layerPackages) addInstalledPackage(pkg);
   const localPackageSkills = await discoverLocalPackageSkills(nuxt.options.rootDir);
   if (localPackageSkills) {
     discoveries.push(localPackageSkills);
@@ -1830,6 +2588,7 @@ async function generateSkillTree(input) {
   const modulesRoot = join(referencesRoot, "modules");
   const monorepoScopePath = resolveMonorepoScopePath(nuxt.options.rootDir, exportRoot);
   const manualContributions = [];
+  const remoteOptions = normalizeRemoteOptions(options.remote);
   const contributionContext = {
     add: (contribution) => {
       manualContributions.push(contribution);
@@ -1837,6 +2596,9 @@ async function generateSkillTree(input) {
   };
   const callSkillContributeHook = nuxt.callHook;
   await callSkillContributeHook("skill-hub:contribute", contributionContext);
+  const callResolveStartHook = nuxt.callHook;
+  const callResolvePackageHook = nuxt.callHook;
+  const callResolveDoneHook = nuxt.callHook;
   const { discoveries, installedPackages } = await collectInstalledPackages(nuxt);
   const discoveredContributions = await resolveContributions(discoveries);
   const workspaceDiscoverySources = collectWorkspaceDiscoverySources(nuxt.options.rootDir, discoveries);
@@ -1856,7 +2618,10 @@ async function generateSkillTree(input) {
       ...sortAndDedupeContributions(resolvedManual)
     ])
   });
-  if (generationMode === "prepare" && await isGeneratedSkillFresh(cachedGeneratedSkillRoot, fingerprint)) {
+  if (generationMode === "prepare" && await isGeneratedSkillFreshWithOptions(cachedGeneratedSkillRoot, fingerprint, {
+    refresh: remoteOptions.refresh,
+    cacheTtlMs: remoteOptions.cacheTtlMs
+  })) {
     await copySkillTree(cachedGeneratedSkillRoot, generatedSkillRoot, true);
     logger.info(`Restored cached ${skillName} skill from ${cachedGeneratedSkillRoot}`);
     return;
@@ -1869,23 +2634,89 @@ async function generateSkillTree(input) {
   await ensureDir(remoteCacheRoot);
   const packagesToResolve = installedPackages.filter((pkg) => pkg.packageName !== "nuxt-skill-hub" && !distResolvedPackages.has(pkg.packageName));
   const totalToResolve = packagesToResolve.length;
-  const remoteResults = await mapWithConcurrency(
-    packagesToResolve,
-    REMOTE_RESOLUTION_CONCURRENCY,
-    async (pkg, index) => {
-      logger.start(`Resolving skills for ${pkg.packageName} (${index + 1}/${totalToResolve})...`);
-      return await resolveRemoteContributionsForPackage(pkg, {
-        cacheRoot: remoteCacheRoot,
-        githubLookupTimeoutMs: GITHUB_LOOKUP_TIMEOUT_MS,
-        enableGithubLookup: true
-      });
+  const remoteStart = performance.now();
+  const logTimings = shouldLogTimings(nuxt, remoteOptions.timings);
+  await callResolveStartHook("skill-hub:resolve:start", {
+    skillName,
+    packageCount: totalToResolve,
+    concurrency: remoteOptions.concurrency,
+    remoteEnabled: remoteOptions.enabled,
+    githubHeuristics: remoteOptions.githubHeuristics
+  });
+  startPerfPhase(nuxt, "skill-hub:resolve");
+  const remoteResults = await (async () => {
+    try {
+      return await mapWithConcurrency(
+        packagesToResolve,
+        remoteOptions.concurrency,
+        async (pkg, index) => {
+          logger.start(`Resolving skills for ${pkg.packageName} (${index + 1}/${totalToResolve})...`);
+          const packageStart = performance.now();
+          const phaseName = `skill-hub:resolve:${pkg.packageName}`;
+          startPerfPhase(nuxt, phaseName);
+          try {
+            const result = await resolveRemoteContributionsForPackage(pkg, {
+              cacheRoot: remoteCacheRoot,
+              githubLookupTimeoutMs: remoteOptions.timeoutMs,
+              enableGithubLookup: remoteOptions.enabled,
+              enableWellKnownLookup: remoteOptions.enabled,
+              enableGithubHeuristics: remoteOptions.enabled && remoteOptions.githubHeuristics,
+              wellKnownLimits: {
+                maxFiles: remoteOptions.maxFiles,
+                maxBytes: remoteOptions.maxBytes,
+                maxFileBytes: remoteOptions.maxFileBytes
+              }
+            });
+            const durationMs = roundMs(performance.now() - packageStart);
+            const firstContribution = result.contributions[0];
+            await callResolvePackageHook("skill-hub:resolve:package", {
+              skillName,
+              packageName: pkg.packageName,
+              packageIndex: index,
+              packageCount: totalToResolve,
+              durationMs,
+              resolver: firstContribution?.resolver,
+              sourceKind: firstContribution?.sourceKind,
+              contributionCount: result.contributions.length,
+              skippedCount: result.skipped.length
+            });
+            if (logTimings) {
+              const outcome = firstContribution ? `${firstContribution.resolver}/${firstContribution.sourceKind}` : "unresolved";
+              logger.info(`Resolved ${pkg.packageName} via ${outcome} in ${formatMs(durationMs)}`);
+            }
+            return result;
+          } finally {
+            endPerfPhase(nuxt, phaseName);
+          }
+        }
+      );
+    } finally {
+      endPerfPhase(nuxt, "skill-hub:resolve");
     }
-  );
+  })();
   for (const remote of remoteResults) {
     remoteIssues.push(...remote.issues);
     remoteSkipped.push(...remote.skipped);
     remoteContributions.push(...remote.contributions);
   }
+  const remoteDurationMs = roundMs(performance.now() - remoteStart);
+  const resolverCounts = countResolvers(remoteContributions);
+  await callResolveDoneHook("skill-hub:resolve:done", {
+    skillName,
+    packageCount: totalToResolve,
+    concurrency: remoteOptions.concurrency,
+    remoteEnabled: remoteOptions.enabled,
+    githubHeuristics: remoteOptions.githubHeuristics,
+    durationMs: remoteDurationMs,
+    contributionCount: remoteContributions.length,
+    skippedCount: remoteSkipped.length,
+    issueCount: remoteIssues.length,
+    resolverCounts
+  });
+  if (totalToResolve) {
+    const summary = formatResolverCounts(resolverCounts);
+    logger.info(`Resolved ${totalToResolve} module skill sources in ${formatMs(remoteDurationMs)}${summary ? ` (${summary})` : ""}.`);
+  }
   const validatedRemote = await validateResolvedContributions(sortAndDedupeContributions(remoteContributions));
   const validatedManual = await validateResolvedContributions(sortAndDedupeContributions(resolvedManual));
   const contributions = sortAndDedupeContributions([
@@ -1903,10 +2734,10 @@ async function generateSkillTree(input) {
     validationIssues.map((issue) => ({ packageName: issue.packageName, skillName: issue.skillName, reason: issue.reason, sourceKind: issue.sourceKind })),
     (entry) => `${entry.packageName}::${entry.skillName}`
   );
-  const skipped = mergeSkipped(
+  const skipped = filterResolvedSkipped(mergeSkipped(
     [...issuesToSkipped, ...remoteSkipped],
     (entry) => `${entry.packageName}::${entry.skillName}::${entry.sourceKind || ""}`
-  );
+  ), contributions);
   for (const issue of validationIssues) {
     logger.warn(`[validation] ${issue.packageName}/${issue.skillName}: ${issue.reason}`);
   }
@@ -1954,6 +2785,10 @@ async function generateSkillTree(input) {
       resolver: contribution.resolver
     });
   }
+  const moduleIndex = createModuleIndex(generatedEntries, skipped);
+  if (moduleIndex) {
+    await writeFileIfChanged(join(modulesRoot, "index.md"), moduleIndex);
+  }
   const nuxtMetadata = await loadNuxtMetadata();
   await writeFileIfChanged(join(generatedSkillRoot, "SKILL.md"), createSkillEntrypoint(
     skillName,
@@ -1971,24 +2806,31 @@ async function generateSkillTree(input) {
 function isCancelled(value) {
   return value === null || typeof value === "symbol";
 }
-const AI_AGENT_TARGET_MAP = {
-  codex: "codex",
-  claude: "claude-code",
-  gemini: "gemini-code-assist",
-  replit: "replit-agent"
-};
-function resolveAIGuidanceTarget(currentTarget, detectedAgent) {
-  if (currentTarget) {
-    return currentTarget;
-  }
-  if (!detectedAgent) {
-    return void 0;
+function normalizeTargetSelection(value) {
+  if (!Array.isArray(value)) {
+    return [];
   }
-  return AI_AGENT_TARGET_MAP[detectedAgent];
-}
-function buildAIGuidance(currentTarget, detectedAgent) {
-  const target = resolveAIGuidanceTarget(currentTarget, detectedAgent);
+  return value.map((entry) => {
+    if (typeof entry === "string") return entry;
+    if (entry && typeof entry === "object" && typeof entry.value === "string") {
+      return entry.value;
+    }
+    return "";
+  }).filter(Boolean);
+}
+function buildAIGuidance(currentTarget, detectedAgent, skillName = "nuxt") {
+  const agentTargetMap = {
+    codex: "codex",
+    claude: "claude-code",
+    gemini: "gemini-code-assist",
+    replit: "replit-agent"
+  };
+  const target = currentTarget || (detectedAgent ? agentTargetMap[detectedAgent] : void 0);
   const sourceLabel = detectedAgent ? ` (${detectedAgent})` : "";
+  const hintFile = target === "claude-code" ? "CLAUDE.md" : "AGENTS.md";
+  const hint = `${MANAGED_HINT_START}
+Use the \`${skillName}\` skill as the Nuxt router/entrypoint for tasks in this repository.
+${MANAGED_HINT_END}`;
   const snippetLines = [
     "export default defineNuxtConfig({",
     "  skillHub: {",
@@ -2000,17 +2842,25 @@ function buildAIGuidance(currentTarget, detectedAgent) {
   return {
     intro: `Install wizard skipped because nuxt-skill-hub was installed by an AI agent${sourceLabel}. Add this to your nuxt.config.ts:`,
     snippet: snippetLines.join("\n"),
+    hintFile,
+    hint,
+    nextStep: `Add the managed hint to ${hintFile}, then run \`npx nuxi prepare\` to generate the Nuxt skill tree.`,
     optionalFlags: target ? "Optional flags: set `skillHub.skillName`, enable `skillHub.moduleAuthoring`, or switch to `skillHub.generationMode: 'manual'` if needed." : "Optional flags: add `skillHub.targets` to pin an agent target, set `skillHub.skillName`, enable `skillHub.moduleAuthoring`, or switch to `skillHub.generationMode: 'manual'` if needed."
   };
 }
 async function runInstallWizard(nuxt) {
   const logger = useLogger("nuxt-skill-hub");
   if (isAgent) {
-    const guidance = buildAIGuidance(detectCurrentTarget(), agent);
+    const guidance = buildAIGuidance(detectCurrentTarget(), agent, await deriveSkillName(nuxt.options.rootDir));
     logger.info(guidance.intro);
     logger.info(`\`\`\`ts
 ${guidance.snippet}
 \`\`\``);
+    logger.info(`Add this to ${guidance.hintFile}:
+\`\`\`md
+${guidance.hint}
+\`\`\``);
+    logger.info(guidance.nextStep);
     logger.info(guidance.optionalFlags);
     return;
   }
@@ -2042,6 +2892,20 @@ Let's configure AI agent skills for your Nuxt project.`
     }
     consola.info(`Detected agents: ${detectedTargets.length ? detectedTargets.join(", ") : "none"}`);
     selectedTargets = detectedTargets;
+    if (!selectedTargets.length) {
+      const chosen = await consola.prompt("Select agents to generate skills for:", {
+        type: "multiselect",
+        options: allTargets.map((t) => ({ label: t, value: t })),
+        initial: allTargets.includes("codex") ? ["codex"] : allTargets.slice(0, 1),
+        required: true,
+        cancel: "null"
+      });
+      if (isCancelled(chosen)) {
+        consola.info("Setup cancelled.");
+        return;
+      }
+      selectedTargets = normalizeTargetSelection(chosen);
+    }
     if (detectedTargets.length > 1) {
       const keepAll = await consola.prompt("Generate skills for all detected agents?", {
         type: "confirm",
@@ -2064,19 +2928,11 @@ Let's configure AI agent skills for your Nuxt project.`
           consola.info("Setup cancelled.");
           return;
         }
-        selectedTargets = chosen.map((c) => c.value);
+        selectedTargets = normalizeTargetSelection(chosen);
       }
     }
   }
-  const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
-  const uniqueSpecifiers = Array.from(new Set(moduleSpecifiers));
-  const installedModulePackages = [];
-  for (const specifier of uniqueSpecifiers) {
-    const pkg = await discoverInstalledPackageFromSpecifier(specifier, rootDir);
-    if (!pkg || pkg.packageName === "nuxt-skill-hub")
-      continue;
-    installedModulePackages.push(pkg.packageName);
-  }
+  const installedModulePackages = (await collectInstalledModulePackages(nuxt.options.modules, rootDir)).map((pkg) => pkg.packageName).filter((name) => name !== "nuxt-skill-hub");
   if (installedModulePackages.length) {
     consola.info(`Detected ${installedModulePackages.length} installed module package(s):`);
     for (const packageName of installedModulePackages) {