@csark0812/skeleton 1.0.0 → 1.1.0

package/README.md

@@ -1,7 +1,138 @@
 # Skeleton
 
-**Source of truth for** the Skeleton agent harness package overview.
+Single source of truth (SSOT) linter for agent-enabled repos.
 
-<!-- doc-meta: owner=eng | last-reviewed=2026-07-11 -->
+Agent repos accumulate skills, rules, registries, and cross-linked docs faster than anyone can keep them straight by hand. Code repos solved this decades ago with ESLint — deterministic checks, CI gates, fix what you can before merge. Skeleton does the same job for documentation architecture: what's canonical, what links where, what must not exist, and whether your skill overrides are wired correctly.
 
-Thin SSOT audit CLI for agent-enabled repos. See [authoring conventions](docs/authoring.md).
+Skeleton is **not** a runtime agent harness. It does not execute tools, enforce permissions, or manage agent memory. It is a CLI that audits docs, skills, and registries, and fails CI when invariants break.
+
+## Why
+
+Code has linters. Agent repos need the same thing for docs and SSOT.
+
+| Code repos                                              | Agent repos                                                                            |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| ESLint catches broken imports, unused vars, style drift | Skeleton catches broken links, missing registry rows, stale doc-meta, banned artifacts |
+| `eslint --fix` on changed files                         | `skeleton validate changed` on changed docs and skills                                 |
+| Pre-commit + CI gate                                    | `--staged` pre-commit + `--base` CI gate                                               |
+
+Skill linters (skillmark, agentlint, skillscheck) answer: _"Is this SKILL.md well-formed?"_ Skeleton answers: _"Does this repo's documentation system hold together?"_
+
+## Quick start
+
+```bash
+npm install -D @csark0812/skeleton
+npx skeleton init --skills
+```
+
+Init writes `.skeleton/`, merges validate scripts into `package.json`, and wires customize hooks for Cursor, Claude Code, and Codex.
+
+Edit `.skeleton/config.yaml` for your repo layout, then verify:
+
+```bash
+npx skeleton audit self
+```
+
+See [install](docs/developer/install.md) for flags and options.
+
+## What it checks
+
+- **Registry integrity** — `.skeleton/registry.md` topic → canonical file pointers; banner format on registered docs
+- **Link audit** — broken refs, skill links, anchors in scanned markdown
+- **Skill index** — disk matches taxonomy READMEs in detected skill roots
+- **Banned paths** — session artifacts and other files that must not exist
+- **Coverage gaps** — markdown outside the scan perimeter (warn-only)
+- **Doc meta + stale dates** — owner and `last-reviewed` on index and registry-listed files
+- **Shell / JSON syntax** — lightweight checks on changed `.sh` and `.json` files
+
+Code validation (TypeScript, Python, Nx, pytest) stays in your repo. Skeleton handles SSOT-adjacent paths only.
+
+## The `.skeleton/` contract
+
+```
+.skeleton/
+├── config.yaml      # scan perimeter (required)
+├── registry.md      # topic → canonical file (required)
+└── customize/       # project-specific skill overrides (optional)
+    └── code-review.md
+```
+
+Every canonical doc carries a banner:
+
+```markdown
+**Source of truth for** Backend API conventions.
+```
+
+Register it:
+
+```bash
+skeleton register docs/developer/api.md
+```
+
+Synced toolbox skills stay pristine. Project overrides live in `.skeleton/customize/<slug>.md` and inject via IDE hooks on skill read — no editing synced `SKILL.md` files.
+
+## Commands
+
+```bash
+skeleton init [--skills] [--force-hooks]
+skeleton register <path> [--topic=…]
+skeleton audit docs|skills|self [--strict] [--paths=a,b]
+skeleton validate changed [--staged | --base <ref>] [paths…]
+skeleton customize resolve <slug>
+```
+
+**Validate changed** routes git diffs to the right audit:
+
+| Path                                         | Action                      |
+| -------------------------------------------- | --------------------------- |
+| Docs/skills in scan perimeter                | path-scoped audit           |
+| `.sh`, `.bash`, `.zsh`                       | shellcheck or `bash -n`     |
+| Other `.json`                                | JSONC-tolerant syntax check |
+| `.ts`, `.py`, `package.json`, `project.json` | skip                        |
+
+Pre-commit: `skeleton validate changed --staged` (path-scoped, fast).
+CI: `skeleton validate changed --base origin/main` (global rules first, then changed files).
+
+## Ecosystem
+
+Skeleton is the shared validation layer in a three-tier setup:
+
+| Repo                 | Role                                               |
+| -------------------- | -------------------------------------------------- |
+| **skeleton**         | SSOT audit CLI (this repo)                         |
+| **toolbox**          | Team skills + public agent preferences             |
+| **personal-toolbox** | Private skills + personal preferences              |
+| **Consumer apps**    | Call skeleton for SSOT; keep code validation local |
+
+Skeleton never calls Nx or other task runners — consumers call skeleton for doc and skill paths, then handle code paths themselves.
+
+See [tiers](docs/tiers.md).
+
+## Distribution
+
+| Channel                                              | Installs                                                |
+| ---------------------------------------------------- | ------------------------------------------------------- |
+| `npm install -D @csark0812/skeleton`                 | CLI, schemas, audit engine, hook script                 |
+| `npx skills add csark0812/skeleton --skill skeleton` | `/skeleton` agent skill (ops manual, not the installer) |
+
+One command for humans: `npx skeleton init --skills`.
+
+## Docs
+
+- [Install](docs/developer/install.md)
+- [Doc system](docs/developer/doc-system.md)
+- [Validation](docs/developer/validation.md)
+- [Audit rules](docs/developer/audit.md)
+- [Customize](docs/developer/customize.md)
+- [Authoring conventions](docs/authoring.md)
+
+## Development
+
+Requires Node ≥ 22. Uses Bun for dev and tests.
+
+```bash
+bun install
+bun test
+bun run build
+bun run audit:self
+```

package/dist/cli.js

@@ -28582,6 +28582,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 +28640,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 +28714,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 +28936,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,16 +29021,16 @@ 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 { join as join11, relative as relative8 } from "node:path";
 var CUSTOMIZE_PREFIX = "Customize: ";
 function customizePathForSlug(root2, slug2) {
-  return join9(root2, REGISTRY_DIR_REL, "customize", `${slug2}.md`);
+  return join11(root2, REGISTRY_DIR_REL, "customize", `${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;
     }
   }
@@ -28798,19 +29038,19 @@ function findCustomizeViaRegistry(root2, slug2) {
 }
 function resolveCustomize(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
     };
   }
@@ -28823,37 +29063,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 +29105,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 +29119,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 +29130,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 +29141,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 +29164,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 +29277,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 +29293,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 +29353,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 +29459,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 +29468,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 +29493,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 +29560,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 +29572,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 +29588,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 +29609,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 basename2, extname, join as join17 } from "node:path";
 import { spawnSync as spawnSync4 } from "node:child_process";
 
 // src/validate/git-diff.ts
@@ -29437,9 +29677,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 +29687,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 +29722,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 +29787,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 +29944,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 +30030,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@csark0812/skeleton",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "SSOT audit CLI for agent harness repos",
 	"type": "module",
 	"bin": {