@csark0812/skeleton 1.0.0 → 1.1.1

package/dist/cli.js

@@ -16536,7 +16536,8 @@ var $visitAsync = visit.visitAsync;
 // src/audit/config/load.ts
 var SCHEMA_CANDIDATES = [
   join(dirname2(fileURLToPath2(import.meta.url)), "../../../schemas/config.schema.json"),
-  join(dirname2(fileURLToPath2(import.meta.url)), "../schemas/config.schema.json")
+  join(dirname2(fileURLToPath2(import.meta.url)), "../schemas/config.schema.json"),
+  join(dirname2(fileURLToPath2(import.meta.url)), "../../schemas/config.schema.json")
 ];
 function resolveSchemaPath() {
   for (const candidate of SCHEMA_CANDIDATES) {
@@ -28582,6 +28583,28 @@ var scanRootsRule = { id: "scan-roots", run: runScanRootsRule };
 // src/audit/rules/skill-index.ts
 import { existsSync as existsSync8, readFileSync as readFileSync7, readdirSync as readdirSync3 } from "node:fs";
 import { join as join8, relative as relative5 } from "node:path";
+
+// src/references/constants.ts
+var CANONICAL_REFS_DIR = ".skeleton/references";
+var GENERATED_MARKER_START = "<!-- skeleton: generated-reference";
+var GENERATED_MARKER_RE = /<!-- skeleton: generated-reference\s*\nsource: ([^\n]+)\s*\nredundancy: intentional\s*\n-->\s*\n?/;
+var SHARED_REF_LINK_RE = /\((?:\.\.\/)+references\/([^)]+)\)/g;
+function formatGeneratedHeader(sourceRelPath) {
+  return `${GENERATED_MARKER_START}
+source: ${sourceRelPath}
+redundancy: intentional
+-->
+
+`;
+}
+function stripGeneratedHeader(content3) {
+  return content3.replace(GENERATED_MARKER_RE, "");
+}
+function isGeneratedReference(content3) {
+  return content3.startsWith(GENERATED_MARKER_START);
+}
+
+// src/audit/rules/skill-index.ts
 var NON_PUBLIC_SLUGS = new Set(["align-commands"]);
 function walkSkillMarkdown(dir) {
   const files = [];
@@ -28618,6 +28641,8 @@ function scanFileForSkillLinks(ctx, filePath, index2) {
   const issues = [];
   const rel = relative5(ctx.root, filePath).replace(/\\/g, "/");
   const content3 = readFileSync7(filePath, "utf8");
+  if (isGeneratedReference(content3))
+    return issues;
   for (const match of content3.matchAll(SKILL_LINK_RE)) {
     const slug2 = match[1];
     if (!slug2)
@@ -28690,6 +28715,219 @@ function skillCountOnDisk(ctx) {
   return listSkillSlugs(ctx.skillIndex).length;
 }
 
+// src/references/check.ts
+import { existsSync as existsSync10, readFileSync as readFileSync9, readdirSync as readdirSync5 } from "node:fs";
+import { join as join10, relative as relative7 } from "node:path";
+
+// src/references/discover.ts
+import { existsSync as existsSync9, readdirSync as readdirSync4, readFileSync as readFileSync8 } from "node:fs";
+import { join as join9, relative as relative6 } from "node:path";
+function walkMarkdownFiles(dir, root2) {
+  const files = [];
+  if (!existsSync9(dir))
+    return files;
+  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith("."))
+      continue;
+    const fullPath = join9(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkMarkdownFiles(fullPath, root2));
+      continue;
+    }
+    if (entry.name.endsWith(".md")) {
+      files.push(normalizeRelPath(relative6(root2, fullPath)));
+    }
+  }
+  return files;
+}
+function canonicalExists(root2, refPath) {
+  return existsSync9(join9(root2, CANONICAL_REFS_DIR, refPath));
+}
+function findSharedRefLinks(content3, sourceFile) {
+  const links = [];
+  for (const match of content3.matchAll(SHARED_REF_LINK_RE)) {
+    const refPath = match[1];
+    if (!refPath)
+      continue;
+    links.push({ refPath: normalizeRelPath(refPath), sourceFile });
+  }
+  return links;
+}
+function findLocalCanonicalLinks(root2, content3, sourceFile) {
+  const links = [];
+  const localRefRe = /\((?:\.\/)?references\/([^)]+)\)/g;
+  for (const match of content3.matchAll(localRefRe)) {
+    const refPath = normalizeRelPath(match[1] ?? "");
+    if (!refPath || !canonicalExists(root2, refPath))
+      continue;
+    links.push({ refPath, sourceFile });
+  }
+  const inReferencesDir = /\/references\//.test(sourceFile);
+  if (inReferencesDir) {
+    const siblingRe = /\((?!https?:|#|\.\.\/)([a-z0-9./_-]+\.md)\)/gi;
+    for (const match of content3.matchAll(siblingRe)) {
+      const refPath = normalizeRelPath(match[1] ?? "");
+      if (!refPath || !canonicalExists(root2, refPath))
+        continue;
+      links.push({ refPath, sourceFile });
+    }
+  }
+  return links;
+}
+function discoverSkillReferencePlans(root2) {
+  const index2 = buildSkillIndex(root2);
+  const plans = [];
+  for (const slug2 of index2.slugs) {
+    const skillDir = join9(root2, slug2);
+    if (!existsSync9(join9(skillDir, "SKILL.md")))
+      continue;
+    const refPaths = new Set;
+    const links = [];
+    for (const relFile of walkMarkdownFiles(skillDir, root2)) {
+      const content3 = readFileSync8(join9(root2, relFile), "utf8");
+      if (isGeneratedReference(content3))
+        continue;
+      for (const link2 of findSharedRefLinks(content3, relFile)) {
+        refPaths.add(link2.refPath);
+        links.push(link2);
+      }
+      for (const link2 of findLocalCanonicalLinks(root2, content3, relFile)) {
+        refPaths.add(link2.refPath);
+        links.push(link2);
+      }
+    }
+    if (refPaths.size > 0) {
+      plans.push({ skill: slug2, refPaths, links });
+    }
+  }
+  return plans.sort((a, b) => a.skill.localeCompare(b.skill));
+}
+function generatedRefPath(skill, refPath) {
+  return normalizeRelPath(join9(skill, "references", refPath));
+}
+function rewriteSharedRefTarget(sourceFile, skill, refPath) {
+  const sourceDir = sourceFile.slice(0, sourceFile.lastIndexOf("/"));
+  const target = generatedRefPath(skill, refPath);
+  if (!sourceDir)
+    return target;
+  const fromParts = sourceDir.split("/");
+  const toParts = target.split("/");
+  let i = 0;
+  while (i < fromParts.length && i < toParts.length && fromParts[i] === toParts[i]) {
+    i++;
+  }
+  const ups = fromParts.length - i;
+  const down = toParts.slice(i);
+  const rel = [...Array(ups).fill(".."), ...down].join("/");
+  return rel || (toParts.at(-1) ?? refPath);
+}
+function rewriteSharedRefLinks(content3, sourceFile, skill) {
+  return content3.replace(SHARED_REF_LINK_RE, (_match, refPath) => {
+    const rewritten = rewriteSharedRefTarget(sourceFile, skill, normalizeRelPath(refPath));
+    return `(${rewritten})`;
+  });
+}
+
+// src/references/check.ts
+function listAllGeneratedFiles(root2) {
+  const files = [];
+  const walk = (dir) => {
+    if (!existsSync10(dir))
+      return;
+    for (const entry of readdirSync5(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith("."))
+        continue;
+      const fullPath = join10(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+      if (!entry.name.endsWith(".md"))
+        continue;
+      const content3 = readFileSync9(fullPath, "utf8");
+      if (isGeneratedReference(content3)) {
+        files.push(normalizeRelPath(relative7(root2, fullPath)));
+      }
+    }
+  };
+  walk(root2);
+  return files;
+}
+function runGeneratedReferencesCheck(root2) {
+  const issues = [];
+  const canonicalDir = join10(root2, CANONICAL_REFS_DIR);
+  if (!existsSync10(canonicalDir))
+    return issues;
+  const plans = discoverSkillReferencePlans(root2);
+  const needed = new Set;
+  for (const plan of plans) {
+    for (const refPath of plan.refPaths) {
+      needed.add(generatedRefPath(plan.skill, refPath));
+    }
+  }
+  for (const targetRel of needed) {
+    const targetPath = join10(root2, targetRel);
+    if (!existsSync10(targetPath)) {
+      issues.push(issue("generated-references", targetRel, "missing generated copy — run skeleton references sync"));
+      continue;
+    }
+    const generated = readFileSync9(targetPath, "utf8");
+    if (!isGeneratedReference(generated)) {
+      issues.push(issue("generated-references", targetRel, "expected generated-reference provenance header"));
+      continue;
+    }
+    const body = stripGeneratedHeader(generated);
+    const sourceRel = normalizeRelPath(generated.match(/source: ([^\n]+)/)?.[1] ?? join10(CANONICAL_REFS_DIR, targetRel.split("/references/")[1] ?? ""));
+    const canonicalPath = join10(root2, sourceRel);
+    if (!existsSync10(canonicalPath)) {
+      issues.push(issue("generated-references", targetRel, `canonical source missing: ${sourceRel}`));
+      continue;
+    }
+    const canonical = readFileSync9(canonicalPath, "utf8");
+    if (body !== canonical) {
+      issues.push(issue("generated-references", targetRel, "stale generated copy — run skeleton references sync"));
+    }
+  }
+  for (const generatedRel of listAllGeneratedFiles(root2)) {
+    if (!needed.has(generatedRel)) {
+      issues.push(issue("generated-references", generatedRel, "orphaned generated copy — run skeleton references sync"));
+    }
+  }
+  for (const plan of plans) {
+    const skillDir = join10(root2, plan.skill);
+    if (!existsSync10(skillDir))
+      continue;
+    const walk = (dir) => {
+      for (const entry of readdirSync5(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith("."))
+          continue;
+        const fullPath = join10(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+          continue;
+        }
+        if (!entry.name.endsWith(".md"))
+          continue;
+        const relFile = normalizeRelPath(relative7(root2, fullPath));
+        const content3 = readFileSync9(fullPath, "utf8");
+        if (content3.match(SHARED_REF_LINK_RE)) {
+          issues.push(issue("generated-references", relFile, "still links to shared root references/ — run skeleton references sync"));
+        }
+      }
+    };
+    walk(skillDir);
+  }
+  return issues;
+}
+function runGeneratedReferencesRule(ctx) {
+  return runGeneratedReferencesCheck(ctx.root);
+}
+var generatedReferencesRule = {
+  id: "generated-references",
+  global: true,
+  run: runGeneratedReferencesRule
+};
+
 // src/audit/rules/index.ts
 var docsRules = [
   { ...scanRootsRule, global: true },
@@ -28699,7 +28937,10 @@ var docsRules = [
   docMetaRule,
   { ...bannedRule, global: true }
 ];
-var skillsRules = [{ ...skillIndexRule, global: true }];
+var skillsRules = [
+  { ...skillIndexRule, global: true },
+  { ...generatedReferencesRule, global: true }
+];
 var allRules = [...docsRules, ...skillsRules];
 function rulesForSuite(suite) {
   switch (suite) {
@@ -28781,40 +29022,94 @@ function runAudit(options) {
 }
 
 // src/customize/resolve.ts
-import { existsSync as existsSync9, readFileSync as readFileSync8 } from "node:fs";
-import { join as join9, relative as relative6 } from "node:path";
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "node:fs";
+import { basename as basename2, join as join11, relative as relative8 } from "node:path";
 var CUSTOMIZE_PREFIX = "Customize: ";
+function customizeDir(root2) {
+  return join11(root2, REGISTRY_DIR_REL, "customize");
+}
 function customizePathForSlug(root2, slug2) {
-  return join9(root2, REGISTRY_DIR_REL, "customize", `${slug2}.md`);
+  return join11(customizeDir(root2), `${slug2}.md`);
 }
 function findCustomizeViaRegistry(root2, slug2) {
   for (const rel of parseRegistryPaths(root2)) {
     const expected = `${REGISTRY_DIR_REL}/customize/${slug2}.md`;
-    if (normalizeRelPath(rel) === expected && existsSync9(join9(root2, rel))) {
+    if (normalizeRelPath(rel) === expected && existsSync11(join11(root2, rel))) {
       return rel;
     }
   }
   return null;
 }
-function resolveCustomize(root2, slug2) {
+function resolveSlugFile(root2, slug2) {
   const direct = customizePathForSlug(root2, slug2);
-  if (existsSync9(direct)) {
+  if (existsSync11(direct)) {
     return {
-      slug: slug2,
-      content: readFileSync8(direct, "utf8"),
-      path: normalizeRelPath(relative6(root2, direct))
+      content: readFileSync10(direct, "utf8"),
+      path: normalizeRelPath(relative8(root2, direct))
     };
   }
   const registryPath = findCustomizeViaRegistry(root2, slug2);
   if (registryPath) {
-    const abs = join9(root2, registryPath);
+    const abs = join11(root2, registryPath);
     return {
-      slug: slug2,
-      content: readFileSync8(abs, "utf8"),
+      content: readFileSync10(abs, "utf8"),
       path: registryPath
     };
   }
-  return { slug: slug2, content: null, path: null };
+  return { content: null, path: null };
+}
+function alwaysIncludeBasenames(root2) {
+  try {
+    const config = loadConfig(root2);
+    return config.customize?.alwaysInclude ?? [];
+  } catch {
+    return [];
+  }
+}
+function readAlwaysInclude(root2, basenames, skipBasename) {
+  const parts = [];
+  const paths = [];
+  const dir = customizeDir(root2);
+  for (const name of basenames) {
+    const file = basename2(name);
+    if (skipBasename && file === skipBasename)
+      continue;
+    const abs = join11(dir, file);
+    if (!existsSync11(abs))
+      continue;
+    parts.push(readFileSync10(abs, "utf8").trimEnd());
+    paths.push(normalizeRelPath(relative8(root2, abs)));
+  }
+  return { parts, paths };
+}
+function resolveCustomize(root2, slug2) {
+  const slugFile = resolveSlugFile(root2, slug2);
+  const alwaysNames = alwaysIncludeBasenames(root2);
+  const skip = slugFile.path != null ? basename2(slugFile.path) : null;
+  const always = readAlwaysInclude(root2, alwaysNames, skip);
+  const parts = [];
+  const included = [];
+  if (slugFile.content != null && slugFile.content.trim().length > 0) {
+    parts.push(slugFile.content.trimEnd());
+    if (slugFile.path)
+      included.push(slugFile.path);
+  }
+  parts.push(...always.parts);
+  included.push(...always.paths);
+  if (parts.length === 0) {
+    return { slug: slug2, content: null, path: slugFile.path, included: [] };
+  }
+  return {
+    slug: slug2,
+    content: parts.join(`
+
+---
+
+`) + `
+`,
+    path: slugFile.path ?? always.paths[0] ?? null,
+    included
+  };
 }
 function resolveCustomizeFromRoot(slug2, startDir) {
   const root2 = findRepoRoot(startDir);
@@ -28823,37 +29118,37 @@ function resolveCustomizeFromRoot(slug2, startDir) {
 
 // src/init/init.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { copyFileSync, existsSync as existsSync13, mkdirSync as mkdirSync2, readFileSync as readFileSync10 } from "node:fs";
-import { join as join13 } from "node:path";
+import { copyFileSync, existsSync as existsSync15, mkdirSync as mkdirSync2, readFileSync as readFileSync12 } from "node:fs";
+import { join as join15 } from "node:path";
 
 // src/init/merge-hooks.ts
-import { existsSync as existsSync12, mkdirSync, readFileSync as readFileSync9, writeFileSync } from "node:fs";
-import { dirname as dirname6, join as join12 } from "node:path";
+import { existsSync as existsSync14, mkdirSync, readFileSync as readFileSync11, writeFileSync } from "node:fs";
+import { dirname as dirname6, join as join14 } from "node:path";
 
 // src/init/resolve-hook-command.ts
-import { existsSync as existsSync11 } from "node:fs";
+import { existsSync as existsSync13 } from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
-import { dirname as dirname5, join as join11, relative as relative7, resolve as resolve5 } from "node:path";
+import { dirname as dirname5, join as join13, relative as relative9, resolve as resolve5 } from "node:path";
 
 // src/init/package-paths.ts
-import { existsSync as existsSync10 } from "node:fs";
-import { dirname as dirname4, join as join10 } from "node:path";
+import { existsSync as existsSync12 } from "node:fs";
+import { dirname as dirname4, join as join12 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 var MODULE_DIR = dirname4(fileURLToPath4(import.meta.url));
 var PACKAGE_ROOT_CANDIDATES = [
-  join10(MODULE_DIR, "../.."),
-  join10(MODULE_DIR, "..")
+  join12(MODULE_DIR, "../.."),
+  join12(MODULE_DIR, "..")
 ];
 function resolvePackageRoot() {
   for (const candidate of PACKAGE_ROOT_CANDIDATES) {
-    if (existsSync10(join10(candidate, "package.json")))
+    if (existsSync12(join12(candidate, "package.json")))
       return candidate;
   }
   throw new Error("Could not resolve @csark0812/skeleton package root");
 }
 function resolveTemplatesDir() {
-  const dir = join10(resolvePackageRoot(), "templates/skeleton-init");
-  if (!existsSync10(dir)) {
+  const dir = join12(resolvePackageRoot(), "templates/skeleton-init");
+  if (!existsSync12(dir)) {
     throw new Error("Missing templates/skeleton-init in package");
   }
   return dir;
@@ -28865,12 +29160,12 @@ var HOOK_DIST = "dist/hooks/customize-on-skill-read.js";
 var HOOK_SRC = "src/hooks/customize-on-skill-read.ts";
 var PACKAGE_ROOT = resolvePackageRoot();
 function toRepoRelative(cwd, absPath) {
-  const rel = relative7(cwd, absPath).replace(/\\/g, "/");
+  const rel = relative9(cwd, absPath).replace(/\\/g, "/");
   return rel.startsWith("..") ? absPath.replace(/\\/g, "/") : rel;
 }
 function tryResolvePublished(cwd) {
   try {
-    const req = createRequire3(join11(cwd, "package.json"));
+    const req = createRequire3(join13(cwd, "package.json"));
     return req.resolve(`${PACKAGE_NAME}/${HOOK_DIST}`);
   } catch {
     return null;
@@ -28879,8 +29174,8 @@ function tryResolvePublished(cwd) {
 function walkNodeModules(cwd) {
   let dir = cwd;
   while (true) {
-    const candidate = join11(dir, "node_modules", PACKAGE_NAME, HOOK_DIST);
-    if (existsSync11(candidate))
+    const candidate = join13(dir, "node_modules", PACKAGE_NAME, HOOK_DIST);
+    if (existsSync13(candidate))
       return candidate;
     const parent = dirname5(dir);
     if (parent === dir)
@@ -28890,7 +29185,7 @@ function walkNodeModules(cwd) {
   return null;
 }
 function isInsidePackageRoot(cwd) {
-  const rel = relative7(PACKAGE_ROOT, resolve5(cwd)).replace(/\\/g, "/");
+  const rel = relative9(PACKAGE_ROOT, resolve5(cwd)).replace(/\\/g, "/");
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 }
 function resolveHookCommand(cwd) {
@@ -28901,11 +29196,11 @@ function resolveHookCommand(cwd) {
   if (hoisted)
     return toRepoRelative(cwd, hoisted);
   if (isInsidePackageRoot(cwd)) {
-    const distHook = join11(PACKAGE_ROOT, HOOK_DIST);
-    if (existsSync11(distHook))
+    const distHook = join13(PACKAGE_ROOT, HOOK_DIST);
+    if (existsSync13(distHook))
       return toRepoRelative(cwd, distHook);
-    const srcHook = join11(PACKAGE_ROOT, HOOK_SRC);
-    if (existsSync11(srcHook)) {
+    const srcHook = join13(PACKAGE_ROOT, HOOK_SRC);
+    if (existsSync13(srcHook)) {
       const rel = toRepoRelative(cwd, srcHook);
       return rel.includes("/") ? `bun ${rel}` : `bun ./${rel}`;
     }
@@ -28924,14 +29219,14 @@ function identityKey(platform, event, matcher) {
   return `skeleton:customize:${platform}:${event}:${matcher}`;
 }
 function loadFragment(name, hookCommand) {
-  const raw = readFileSync9(join12(TEMPLATES_DIR, name), "utf8");
+  const raw = readFileSync11(join14(TEMPLATES_DIR, name), "utf8");
   return JSON.parse(raw.replaceAll("{{HOOK_COMMAND}}", hookCommand));
 }
 function readJson(path2) {
-  if (!existsSync12(path2))
+  if (!existsSync14(path2))
     return null;
   try {
-    return JSON.parse(readFileSync9(path2, "utf8"));
+    return JSON.parse(readFileSync11(path2, "utf8"));
   } catch (error) {
     throw new Error(`Invalid JSON in ${path2}: ${error}`);
   }
@@ -29037,14 +29332,14 @@ function mergeNestedHooks(platform, targetPath, fragment, eventName, opts) {
 }
 function mergeHookConfigs(opts) {
   const results = [];
-  const cursorPath = join12(opts.cwd, ".cursor/hooks.json");
+  const cursorPath = join14(opts.cwd, ".cursor/hooks.json");
   const cursorFragment = loadFragment("cursor-hooks.fragment.json", opts.hookCommand);
   results.push(mergeCursorHooks(cursorPath, cursorFragment, opts));
-  const claudePath = join12(opts.cwd, ".claude/settings.json");
+  const claudePath = join14(opts.cwd, ".claude/settings.json");
   const claudeFragment = loadFragment("claude-settings.fragment.json", opts.hookCommand);
   results.push(mergeNestedHooks("claude", claudePath, claudeFragment, "PostToolUse", opts));
-  const codexPath = join12(opts.cwd, ".codex/hooks.json");
-  if (existsSync12(join12(opts.cwd, ".codex"))) {
+  const codexPath = join14(opts.cwd, ".codex/hooks.json");
+  if (existsSync14(join14(opts.cwd, ".codex"))) {
     const codexFragment = loadFragment("codex-hooks.fragment.json", opts.hookCommand);
     results.push(mergeNestedHooks("codex", codexPath, codexFragment, "PostToolUse", opts));
   } else {
@@ -29053,11 +29348,11 @@ function mergeHookConfigs(opts) {
   return results;
 }
 function mergePackageJsonScripts(cwd) {
-  const pkgPath = join12(cwd, "package.json");
-  if (!existsSync12(pkgPath))
+  const pkgPath = join14(cwd, "package.json");
+  if (!existsSync14(pkgPath))
     return "skipped";
-  const fragment = JSON.parse(readFileSync9(join12(TEMPLATES_DIR, "package.json.scripts.fragment.json"), "utf8"));
-  const pkg = JSON.parse(readFileSync9(pkgPath, "utf8"));
+  const fragment = JSON.parse(readFileSync11(join14(TEMPLATES_DIR, "package.json.scripts.fragment.json"), "utf8"));
+  const pkg = JSON.parse(readFileSync11(pkgPath, "utf8"));
   pkg.scripts ??= {};
   let changed = false;
   for (const [key, value] of Object.entries(fragment)) {
@@ -29113,27 +29408,27 @@ function skillsAddArgs(options = {}) {
 // src/init/init.ts
 var TEMPLATES_DIR2 = resolveTemplatesDir();
 function writeScaffold(cwd) {
-  const skeletonDir = join13(cwd, ".skeleton");
+  const skeletonDir = join15(cwd, ".skeleton");
   mkdirSync2(skeletonDir, { recursive: true });
   let created = false;
-  const configPath = join13(skeletonDir, "config.yaml");
-  if (!existsSync13(configPath)) {
-    copyFileSync(join13(TEMPLATES_DIR2, "config.yaml"), configPath);
+  const configPath = join15(skeletonDir, "config.yaml");
+  if (!existsSync15(configPath)) {
+    copyFileSync(join15(TEMPLATES_DIR2, "config.yaml"), configPath);
     created = true;
   }
-  const registryPath = join13(skeletonDir, "registry.md");
-  if (!existsSync13(registryPath)) {
-    copyFileSync(join13(TEMPLATES_DIR2, "registry.md"), registryPath);
+  const registryPath = join15(skeletonDir, "registry.md");
+  if (!existsSync15(registryPath)) {
+    copyFileSync(join15(TEMPLATES_DIR2, "registry.md"), registryPath);
     created = true;
   }
-  mkdirSync2(join13(skeletonDir, "customize"), { recursive: true });
+  mkdirSync2(join15(skeletonDir, "customize"), { recursive: true });
   return created ? "created" : "skipped";
 }
 function assertPackageResolvable(cwd) {
-  const pkgPath = join13(cwd, "package.json");
-  if (!existsSync13(pkgPath))
+  const pkgPath = join15(cwd, "package.json");
+  if (!existsSync15(pkgPath))
     return;
-  const pkg = JSON.parse(readFileSync10(pkgPath, "utf8"));
+  const pkg = JSON.parse(readFileSync12(pkgPath, "utf8"));
   const hasDep = pkg.devDependencies?.["@csark0812/skeleton"] || pkg.dependencies?.["@csark0812/skeleton"];
   if (!hasDep) {
     try {
@@ -29219,8 +29514,8 @@ function parseInitArgs(argv) {
 }
 
 // src/register.ts
-import { existsSync as existsSync14, readFileSync as readFileSync11, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname7, join as join14, relative as relative8 } from "node:path";
+import { existsSync as existsSync16, readFileSync as readFileSync13, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname7, join as join16, relative as relative10 } from "node:path";
 var REGISTRY_TABLE_ROW_RE2 = /^\|\s*([^|]+)\|\s*\[[^\]]*\]\(([^)]+)\)\s*\|/;
 var REGISTRY_TABLE_HEADER = "| Topic | Canonical file |";
 function extractTopic(content3) {
@@ -29228,8 +29523,8 @@ function extractTopic(content3) {
   return match?.[1]?.trim().replace(/\s+$/, "") ?? null;
 }
 function toRegistryLink(root2, absPath) {
-  const fromRegistry = join14(root2, REGISTRY_DIR_REL);
-  return normalizeRelPath(relative8(fromRegistry, absPath));
+  const fromRegistry = join16(root2, REGISTRY_DIR_REL);
+  return normalizeRelPath(relative10(fromRegistry, absPath));
 }
 function inferSection(registryLink) {
   return registryLink.startsWith("customize/") ? "Customizations" : "Documentation";
@@ -29253,12 +29548,12 @@ function parseRegistryRows(content3) {
   return rows;
 }
 function pathFromRegistryLink(root2, link2) {
-  return normalizeRelPath(relative8(root2, join14(root2, REGISTRY_DIR_REL, link2)));
+  return normalizeRelPath(relative10(root2, join16(root2, REGISTRY_DIR_REL, link2)));
 }
 function isOutsideScan(root2, relPath2) {
   const config = loadConfig(root2);
   const skillIndex = buildSkillIndex(root2);
-  const scanned = collectScanFiles(config, root2, skillIndex).map((abs) => normalizeRelPath(relative8(root2, abs)));
+  const scanned = collectScanFiles(config, root2, skillIndex).map((abs) => normalizeRelPath(relative10(root2, abs)));
   if (scanned.includes(relPath2))
     return false;
   return !config.scan.include.some((pattern) => matchesGlobScope(relPath2, pattern));
@@ -29320,11 +29615,11 @@ ${newLine}
 function registerPath(options) {
   const root2 = options.root ?? findRepoRoot();
   const relPath2 = normalizeRelPath(options.path);
-  const absPath = join14(root2, relPath2);
-  if (!existsSync14(absPath)) {
+  const absPath = join16(root2, relPath2);
+  if (!existsSync16(absPath)) {
     throw new Error(`File not found: ${relPath2}`);
   }
-  const content3 = readFileSync11(absPath, "utf8");
+  const content3 = readFileSync13(absPath, "utf8");
   let topic = options.topic ?? extractTopic(content3);
   if (!topic) {
     throw new Error(`No **Source of truth for** banner in ${relPath2} — add banner or pass --topic`);
@@ -29332,9 +29627,9 @@ function registerPath(options) {
   const registryLink = toRegistryLink(root2, absPath);
   topic = ensureCustomizeTopic(topic, registryLink);
   const section = inferSection(registryLink);
-  const registryAbs = join14(root2, REGISTRY_REL_PATH);
-  let registryContent = existsSync14(registryAbs) ? readFileSync11(registryAbs, "utf8") : defaultRegistryContent();
-  if (!existsSync14(registryAbs) && !existsSync14(join14(root2, ".skeleton/config.yaml"))) {
+  const registryAbs = join16(root2, REGISTRY_REL_PATH);
+  let registryContent = existsSync16(registryAbs) ? readFileSync13(registryAbs, "utf8") : defaultRegistryContent();
+  if (!existsSync16(registryAbs) && !existsSync16(join16(root2, ".skeleton/config.yaml"))) {
     throw new Error("Missing .skeleton/config.yaml — run skeleton init first");
   }
   const { content: updated, action } = upsertRow(registryContent, topic, registryLink, section, root2);
@@ -29348,7 +29643,7 @@ function registerPath(options) {
   };
   if (!options.dryRun && action !== "noop") {
     const dir = dirname7(registryAbs);
-    if (!existsSync14(dir)) {
+    if (!existsSync16(dir)) {
       throw new Error(`Missing ${REGISTRY_DIR_REL}/ directory`);
     }
     writeFileSync2(registryAbs, registryContent, "utf8");
@@ -29369,8 +29664,8 @@ function registerPath(options) {
 }
 
 // src/validate/changed.ts
-import { existsSync as existsSync15, readFileSync as readFileSync12 } from "node:fs";
-import { basename as basename2, extname, join as join15 } from "node:path";
+import { existsSync as existsSync17, readFileSync as readFileSync14 } from "node:fs";
+import { basename as basename3, extname, join as join17 } from "node:path";
 import { spawnSync as spawnSync4 } from "node:child_process";
 
 // src/validate/git-diff.ts
@@ -29401,7 +29696,7 @@ var COMMAND_CONFIG_NAMES = new Set(["package.json", "project.json"]);
 function bucketFor(relPath2, root2) {
   const normalized = normalizeRelPath(relPath2);
   const ext = extname(normalized).toLowerCase();
-  const name = basename2(normalized);
+  const name = basename3(normalized);
   if (SKIP_EXTENSIONS.has(ext))
     return "skip";
   if (COMMAND_CONFIG_NAMES.has(name))
@@ -29437,9 +29732,9 @@ function parseJsonContent(content3) {
   }
 }
 function validateJson(relPath2, root2) {
-  const abs = join15(root2, relPath2);
+  const abs = join17(root2, relPath2);
   try {
-    parseJsonContent(readFileSync12(abs, "utf8"));
+    parseJsonContent(readFileSync14(abs, "utf8"));
     return 0;
   } catch (error) {
     console.error(`validate changed: invalid JSON in ${relPath2}: ${error}`);
@@ -29447,7 +29742,7 @@ function validateJson(relPath2, root2) {
   }
 }
 function validateShell(relPath2, root2) {
-  const abs = join15(root2, relPath2);
+  const abs = join17(root2, relPath2);
   const shellcheck = spawnSync4("shellcheck", [abs], { encoding: "utf8" });
   if (shellcheck.status === 0)
     return 0;
@@ -29482,8 +29777,8 @@ function runValidateChanged(options = {}) {
   };
   let skipped = 0;
   for (const relPath2 of relPaths) {
-    const abs = join15(root2, relPath2);
-    if (!existsSync15(abs))
+    const abs = join17(root2, relPath2);
+    if (!existsSync17(abs))
       continue;
     const bucket = bucketFor(relPath2, root2);
     if (bucket === "skip") {
@@ -29547,6 +29842,154 @@ function runValidateChanged(options = {}) {
   return exitCode;
 }
 
+// src/references/sync.ts
+import {
+  existsSync as existsSync18,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync15,
+  readdirSync as readdirSync6,
+  unlinkSync,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { dirname as dirname8, join as join18, relative as relative11 } from "node:path";
+function walkMarkdownFiles2(dir, root2) {
+  const files = [];
+  if (!existsSync18(dir))
+    return files;
+  for (const entry of readdirSync6(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith("."))
+      continue;
+    const fullPath = join18(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkMarkdownFiles2(fullPath, root2));
+      continue;
+    }
+    if (entry.name.endsWith(".md")) {
+      files.push(normalizeRelPath(relative11(root2, fullPath)));
+    }
+  }
+  return files;
+}
+function listGeneratedReferenceFiles(skillDir, skill) {
+  const refsDir = join18(skillDir, "references");
+  if (!existsSync18(refsDir))
+    return [];
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync6(dir, { withFileTypes: true })) {
+      const fullPath = join18(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+      if (!entry.name.endsWith(".md"))
+        continue;
+      const content3 = readFileSync15(fullPath, "utf8");
+      if (isGeneratedReference(content3)) {
+        const refPath = normalizeRelPath(relative11(refsDir, fullPath));
+        files.push(generatedRefPath(skill, refPath));
+      }
+    }
+  };
+  walk(refsDir);
+  return files;
+}
+function syncReferences(options = {}) {
+  const root2 = options.root ?? process.cwd();
+  const canonicalDir = join18(root2, CANONICAL_REFS_DIR);
+  if (!existsSync18(canonicalDir)) {
+    throw new Error(`canonical references dir not found: ${CANONICAL_REFS_DIR}`);
+  }
+  const result = {
+    written: [],
+    rewritten: [],
+    removed: [],
+    skipped: []
+  };
+  const plans = discoverSkillReferencePlans(root2);
+  for (const plan of plans) {
+    const skillDir = join18(root2, plan.skill);
+    for (const refPath of plan.refPaths) {
+      const sourceRel = normalizeRelPath(join18(CANONICAL_REFS_DIR, refPath));
+      const canonicalPath = join18(root2, sourceRel);
+      if (!existsSync18(canonicalPath)) {
+        throw new Error(`canonical reference missing: ${sourceRel}`);
+      }
+      const targetRel = generatedRefPath(plan.skill, refPath);
+      const targetPath = join18(root2, targetRel);
+      const canonicalContent = readFileSync15(canonicalPath, "utf8");
+      const nextContent = formatGeneratedHeader(sourceRel) + canonicalContent;
+      if (!options.dryRun) {
+        mkdirSync3(dirname8(targetPath), { recursive: true });
+      }
+      const existing = existsSync18(targetPath) ? readFileSync15(targetPath, "utf8") : null;
+      if (existing !== nextContent) {
+        if (!options.dryRun)
+          writeFileSync3(targetPath, nextContent, "utf8");
+        result.written.push(targetRel);
+      } else {
+        result.skipped.push(targetRel);
+      }
+    }
+    if (options.rewriteLinks !== false) {
+      for (const relFile of walkMarkdownFiles2(skillDir, root2)) {
+        const filePath = join18(root2, relFile);
+        const content3 = readFileSync15(filePath, "utf8");
+        const next = rewriteSharedRefLinks(content3, relFile, plan.skill);
+        if (next !== content3) {
+          if (!options.dryRun)
+            writeFileSync3(filePath, next, "utf8");
+          result.rewritten.push(relFile);
+        }
+      }
+    }
+    for (const generatedRel of listGeneratedReferenceFiles(skillDir, plan.skill)) {
+      const refPath = generatedRel.slice(`${plan.skill}/references/`.length);
+      if (!plan.refPaths.has(refPath)) {
+        const fullPath = join18(root2, generatedRel);
+        if (!options.dryRun)
+          unlinkSync(fullPath);
+        result.removed.push(generatedRel);
+      }
+    }
+  }
+  return result;
+}
+
+// src/references/run.ts
+function runReferencesSync(options = {}) {
+  return syncReferences(options);
+}
+function runReferencesCheck(options = {}) {
+  const root2 = options.root ?? process.cwd();
+  const issues = runGeneratedReferencesCheck(root2);
+  return printReport(issues, {
+    strict: options.strict,
+    json: options.json,
+    label: "References check"
+  });
+}
+function printSyncResult(result) {
+  if (result.written.length > 0) {
+    console.log(`references sync: wrote ${result.written.length} file(s)`);
+    for (const file of result.written)
+      console.log(`  + ${file}`);
+  }
+  if (result.rewritten.length > 0) {
+    console.log(`references sync: rewrote links in ${result.rewritten.length} file(s)`);
+    for (const file of result.rewritten)
+      console.log(`  ~ ${file}`);
+  }
+  if (result.removed.length > 0) {
+    console.log(`references sync: removed ${result.removed.length} stale file(s)`);
+    for (const file of result.removed)
+      console.log(`  - ${file}`);
+  }
+  if (result.written.length === 0 && result.rewritten.length === 0 && result.removed.length === 0) {
+    console.log(`references sync: up to date (${result.skipped.length} file(s) checked)`);
+  }
+}
+
 // src/cli.ts
 function usage() {
   console.error(`Usage: skeleton <command>
@@ -29556,7 +29999,9 @@ Commands:
   audit docs|self|skills [--strict] [--json] [--paths=a,b] [--only=rule]
   validate changed [paths…] [--staged] [--base <ref>]
   register <path> [--topic=…] [--dry-run] [--json]
-  customize resolve <slug> [--json]`);
+  customize resolve <slug> [--json]
+  references sync [--dry-run] [--no-rewrite-links]
+  references check [--json] [--strict]`);
 }
 function parseRegisterArgs(argv) {
   let path2 = null;
@@ -29640,6 +30085,24 @@ function main() {
       runInit(parsed);
       process.exit(0);
     }
+    if (command === "references") {
+      const sub = argv[1];
+      if (sub === "sync") {
+        const dryRun = argv.includes("--dry-run");
+        const rewriteLinks = !argv.includes("--no-rewrite-links");
+        const result = runReferencesSync({ dryRun, rewriteLinks });
+        printSyncResult(result);
+        process.exit(0);
+      }
+      if (sub === "check") {
+        process.exit(runReferencesCheck({
+          json: argv.includes("--json"),
+          strict: argv.includes("--strict")
+        }));
+      }
+      usage();
+      process.exit(1);
+    }
     usage();
     process.exit(1);
   } catch (error) {