create-zudo-doc 1.1.0 → 1.3.0

package/dist/api.d.ts

@@ -16,5 +16,11 @@ export interface CreateOptions {
     packageManager: "pnpm" | "npm" | "yarn" | "bun";
     /** Install dependencies after scaffolding (default: false) */
     install?: boolean;
+    /**
+     * Initialize a git repository + initial commit after scaffolding
+     * (default: false). The CLI defaults this on; the programmatic API defaults
+     * it off so automation / test callers never create unexpected repos.
+     */
+    git?: boolean;
 }
 export declare function createZudoDoc(options: CreateOptions): Promise<string>;

package/dist/api.js

@@ -1,8 +1,8 @@
 import path from "path";
 import { scaffold } from "./scaffold.js";
-import { installDependencies, validateProjectName } from "./utils.js";
+import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
 export async function createZudoDoc(options) {
-    const { install = false, ...rest } = options;
+    const { install = false, git = false, ...rest } = options;
     const nameError = validateProjectName(rest.projectName);
     if (nameError)
         throw new Error(`Invalid projectName: ${nameError}`);
@@ -12,5 +12,8 @@ export async function createZudoDoc(options) {
     if (install) {
         installDependencies(targetDir, choices.packageManager);
     }
+    if (git) {
+        initGitRepo(targetDir);
+    }
     return targetDir;
 }

package/dist/cli.d.ts

@@ -33,6 +33,8 @@ export interface CliArgs {
     preset?: string;
     pm?: "pnpm" | "npm" | "yarn" | "bun";
     install?: boolean;
+    /** Initialize a git repository + initial commit after scaffolding (default on). */
+    git?: boolean;
     yes?: boolean;
     help?: boolean;
 }

package/dist/cli.js

@@ -67,6 +67,8 @@ export function parseArgs(argv = process.argv.slice(2)) {
     }
     if (wasPassed("install"))
         args.install = raw["install"] !== false;
+    if (wasPassed("git"))
+        args.git = raw["git"] !== false;
     if (raw.yes || raw.y)
         args.yes = true;
     if (raw.help || raw.h)
@@ -95,6 +97,8 @@ ${featureHelp}
   --preset <path>              Load settings from a JSON preset file (use "-" for stdin)
   --pm <manager>               pnpm | npm | yarn | bun
   --[no-]install               Install dependencies after scaffolding
+  --[no-]git                   Initialize a git repository + initial commit
+                               (default: on; enables doc-history metadata)
   -y, --yes                    Use defaults for unspecified options, skip prompts
   -h, --help                   Show this help message
 

package/dist/index.js

@@ -6,7 +6,7 @@ import { FEATURES } from "./constants.js";
 import { loadPreset } from "./preset.js";
 import { runPrompts } from "./prompts.js";
 import { scaffold } from "./scaffold.js";
-import { installDependencies } from "./utils.js";
+import { installDependencies, initGitRepo } from "./utils.js";
 async function main() {
     const args = parseArgs();
     // Handle --help
@@ -144,6 +144,31 @@ async function main() {
             s2.stop("Installation failed. Run install manually.");
         }
     }
+    // Initialize a git repository (default on; --no-git to opt out). doc-history
+    // reads `git log` for each page's Created/Updated/Author block, so a project
+    // without git renders empty history. Runs after install so the lockfile is
+    // part of the initial commit; auto-skips if the target is already inside a
+    // repo or if git is unavailable.
+    const shouldInitGit = args.git ?? true;
+    if (shouldInitGit) {
+        const s3 = p.spinner();
+        s3.start("Initializing git repository...");
+        const result = initGitRepo(targetDir);
+        switch (result.status) {
+            case "ok":
+                s3.stop("Initialized git repository with an initial commit.");
+                break;
+            case "skipped-existing-repo":
+                s3.stop("Already inside a git repository — skipped git init.");
+                break;
+            case "skipped-no-git":
+                s3.stop("git not found — skipped git init.");
+                break;
+            case "failed":
+                s3.stop("Could not initialize git — continuing without it.");
+                break;
+        }
+    }
     p.outro(`${pc.green("Done!")} Your project is ready at ${pc.cyan(choices.projectName)}`);
     console.log();
     console.log(`  ${pc.bold("Next steps:")}`);

package/dist/scaffold.d.ts

@@ -11,5 +11,5 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^1.1.0";
+export declare const ZUDO_DOC_PIN = "^1.3.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -18,7 +18,7 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^1.1.0";
+export const ZUDO_DOC_PIN = "^1.3.0";
 /**
  * Files in `templates/base/**` that must never be copied into a generated
  * project. Each entry is matched against the path relative to `templates/base/`
@@ -475,13 +475,19 @@ function generatePackageJson(choices) {
         // (e.g. `@/*`) into its synthetic tsconfig (zfb#1238) — fixes silent island
         // hydration failure under route injection. Unblocks packageOwnedRoutes.
         // No consumer-facing / CLI breaking change.
-        // next.67 (current pin): routine toolchain bump from next.65, adopted in
+        // next.68: routine toolchain bump from next.67, adopted in
         // lockstep with the root package.json pins. No consumer-facing / CLI change.
-        "@takazudo/zfb": "0.1.0-next.67",
-        "@takazudo/zfb-runtime": "0.1.0-next.67",
+        // next.69: routine toolchain bump from next.68, adopted in
+        // lockstep with the root package.json pins. No consumer-facing / CLI change.
+        // next.70 (current pin): routine toolchain bump from next.69, re-aligned
+        // with the root package.json pins (root was bumped in b5489acf; this
+        // scaffold pin lagged at next.69 and broke check-pin-parity). No
+        // consumer-facing / CLI change.
+        "@takazudo/zfb": "0.1.0-next.70",
+        "@takazudo/zfb-runtime": "0.1.0-next.70",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.67",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.70",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
@@ -564,7 +570,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^1.1.0";
+        deps["@takazudo/zudo-doc-history-server"] = "^1.3.0";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).

package/dist/utils.d.ts

@@ -7,6 +7,33 @@
  */
 export declare function validateProjectName(name: string): string | null;
 export declare function installDependencies(dir: string, pm: string): void;
+export type GitInitResult = {
+    status: "ok";
+} | {
+    status: "skipped-existing-repo";
+} | {
+    status: "skipped-no-git";
+} | {
+    status: "failed";
+    message: string;
+};
+/**
+ * Initialize a git repository in `dir` and create an initial commit.
+ *
+ * Why: zudo-doc's doc-history feature reads `git log` for each page's
+ * Created/Updated/Author block. A scaffolded project with no git repo renders
+ * empty history — and on older `@takazudo/zudo-doc-history-server` it crashed
+ * `pnpm dev` outright (the preBuild hook ran `git rev-parse` and threw).
+ * Initializing git here makes the feature work out of the box.
+ *
+ * Safe by construction:
+ * - `skipped-no-git` when git is not installed;
+ * - `skipped-existing-repo` when `dir` is already inside a git work tree (e.g.
+ *   scaffolding into an existing monorepo) — never nest repositories;
+ * - the initial commit only falls back to a neutral identity when the user has
+ *   none configured, so a normal user's commit keeps their own identity.
+ */
+export declare function initGitRepo(dir: string): GitInitResult;
 export declare function capitalize(str: string): string;
 /** Get a short uppercase label for a language code (e.g. "en" → "EN", "zh-cn" → "ZH-CN"). */
 export declare function getLangLabel(langCode: string): string;

package/dist/utils.js

@@ -1,4 +1,4 @@
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import fs from "fs-extra";
 // Project-name grammar (locked by F4 — S4 #2013):
 // /^[a-z0-9][a-z0-9._-]*$/, max 214 chars, unscoped, used as both directory
@@ -36,6 +36,77 @@ export function installDependencies(dir, pm) {
     // Use pipe to avoid garbled output when used alongside spinner
     execSync(cmd, { cwd: dir, stdio: "pipe" });
 }
+/**
+ * Initialize a git repository in `dir` and create an initial commit.
+ *
+ * Why: zudo-doc's doc-history feature reads `git log` for each page's
+ * Created/Updated/Author block. A scaffolded project with no git repo renders
+ * empty history — and on older `@takazudo/zudo-doc-history-server` it crashed
+ * `pnpm dev` outright (the preBuild hook ran `git rev-parse` and threw).
+ * Initializing git here makes the feature work out of the box.
+ *
+ * Safe by construction:
+ * - `skipped-no-git` when git is not installed;
+ * - `skipped-existing-repo` when `dir` is already inside a git work tree (e.g.
+ *   scaffolding into an existing monorepo) — never nest repositories;
+ * - the initial commit only falls back to a neutral identity when the user has
+ *   none configured, so a normal user's commit keeps their own identity.
+ */
+export function initGitRepo(dir) {
+    // Is git available at all?
+    try {
+        execFileSync("git", ["--version"], { stdio: "ignore" });
+    }
+    catch {
+        return { status: "skipped-no-git" };
+    }
+    // Already inside a git work tree? Don't create a nested repository.
+    try {
+        const inside = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: dir,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (inside === "true")
+            return { status: "skipped-existing-repo" };
+    }
+    catch {
+        // git exits non-zero when `dir` is not inside a repo — the expected case.
+    }
+    const COMMIT_MESSAGE = "Initial commit from create-zudo-doc";
+    try {
+        execFileSync("git", ["init", "-q"], { cwd: dir, stdio: "ignore" });
+        execFileSync("git", ["add", "-A"], { cwd: dir, stdio: "ignore" });
+        try {
+            execFileSync("git", ["commit", "-q", "-m", COMMIT_MESSAGE], {
+                cwd: dir,
+                stdio: "ignore",
+            });
+        }
+        catch {
+            // No git identity configured on this machine — retry with a neutral
+            // fallback so the initial commit still succeeds. Users with a configured
+            // identity never reach this branch (their identity is used above).
+            execFileSync("git", [
+                "-c",
+                "user.name=create-zudo-doc",
+                "-c",
+                "user.email=create-zudo-doc@users.noreply.github.com",
+                "commit",
+                "-q",
+                "-m",
+                COMMIT_MESSAGE,
+            ], { cwd: dir, stdio: "ignore" });
+        }
+        return { status: "ok" };
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 export function capitalize(str) {
     return str.replace(/\b\w/g, (c) => c.toUpperCase());
 }

package/dist/zfb-config-gen.js

@@ -28,6 +28,8 @@ export function generateZfbConfig(_choices) {
     lines.push(`import { zudoDocPreset } from "@takazudo/zudo-doc/preset";`);
     lines.push(`import { settings } from "./src/config/settings";`);
     lines.push(`import { buildDocsSchema } from "./src/config/docs-schema";`);
+    lines.push(`import { translations } from "./src/config/i18n";`);
+    lines.push(`import { colorSchemes } from "./src/config/color-schemes";`);
     lines.push(``);
     // --- Directive vocabulary ---
     // The seven canonical directives registered in pages/_mdx-components.ts.
@@ -54,7 +56,7 @@ export function generateZfbConfig(_choices) {
     lines.push(`  base: settings.base,`);
     lines.push(``);
     lines.push(`  // ── Preset-owned fields (content collections, plugins, markdown, …) ────────`);
-    lines.push(`  ...zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary }),`);
+    lines.push(`  ...zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary, translations, colorSchemes }),`);
     lines.push(`});`);
     return lines.join("\n") + "\n";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/src/config/i18n.ts

@@ -55,7 +55,7 @@ export function detectLocaleFromPath(path: string): Locale {
 }
 
 /** UI string translations */
-const translations: Record<string, Record<string, string>> = {
+export const translations: Record<string, Record<string, string>> = {
   en: {
     "nav.gettingStarted": "Getting Started",
     "nav.learn": "Learn",

package/templates/features/claudeResources/files/src/integrations/claude-resources/__tests__/generate.test.ts

@@ -111,15 +111,20 @@ describe("generateClaudeResourcesDocs", () => {
       }
     });
 
-    it("generates skill as flat .mdx file", () => {
+    it("generates skill page as <dir>/index.mdx", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
+      // The skill page is the directory index so `./ref-<name>` links resolve
+      // against the source file path (#2411) — NOT a flat `<dir>.mdx`.
+      const indexPath = path.join(docsDir, "claude-skills", "test-skill", "index.mdx");
+      expect(fs.existsSync(indexPath)).toBe(true);
+
       const flatPath = path.join(docsDir, "claude-skills", "test-skill.mdx");
-      expect(fs.existsSync(flatPath)).toBe(true);
+      expect(fs.existsSync(flatPath)).toBe(false);
     });
   });
 
@@ -150,7 +155,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
       const parsed = matter(skillPage);
@@ -168,7 +173,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
 
@@ -179,7 +184,7 @@ describe("generateClaudeResourcesDocs", () => {
       expect(skillPage).toContain("SKILL.md");
     });
 
-    it("skill page has links to sub-files that resolve correctly from the page URL", () => {
+    it("skill page has links to sub-files that resolve to sibling nested files", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
@@ -187,12 +192,12 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
 
-      // Links use ./<subpage> format (relative to the skill page URL which
-      // already includes the skill dir, e.g. /docs/claude-skills/test-skill/)
+      // Links use ./<subpage>; the skill page is <dir>/index.mdx so these
+      // resolve against the file path to the sibling <dir>/<subpage>.mdx (#2411).
       expect(skillPage).toContain("./ref-guide");
       expect(skillPage).toContain("./asset-template");
 
@@ -200,8 +205,9 @@ describe("generateClaudeResourcesDocs", () => {
       expect(skillPage).not.toContain("./test-skill/ref-guide");
       expect(skillPage).not.toContain("./test-skill/asset-template");
 
-      // Each linked sub-page must exist as a generated flat .mdx file
-      // The file is flat (test-skill--ref-guide.mdx) but slug is nested
+      // Each linked sub-page must exist as a sibling nested file inside <dir>/,
+      // i.e. claude-skills/test-skill/<subpage>.mdx — which is exactly where the
+      // ./<subpage> relative link resolves to.
       const linkPattern = /\]\(\.\/([\w-]+)\)/g;
       let match;
       while ((match = linkPattern.exec(skillPage)) !== null) {
@@ -209,11 +215,12 @@ describe("generateClaudeResourcesDocs", () => {
         const targetFile = path.join(
           docsDir,
           "claude-skills",
-          `test-skill--${subPage}.mdx`,
+          "test-skill",
+          `${subPage}.mdx`,
         );
         expect(
           fs.existsSync(targetFile),
-          `Link target "test-skill--${subPage}.mdx" should exist`,
+          `Link target "test-skill/${subPage}.mdx" should exist`,
         ).toBe(true);
       }
     });
@@ -226,7 +233,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const skillPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "index.mdx"),
         "utf8",
       );
 
@@ -255,28 +262,28 @@ describe("generateClaudeResourcesDocs", () => {
   // ---------------------------------------------------------------------------
 
   describe("sub-file pages", () => {
-    it("generates unlisted reference page", () => {
+    it("generates unlisted reference page as a nested file", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
-      const refPage = path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx");
+      const refPage = path.join(docsDir, "claude-skills", "test-skill", "ref-guide.mdx");
       expect(fs.existsSync(refPage)).toBe(true);
 
       const parsed = matter(fs.readFileSync(refPage, "utf8"));
       expect(parsed.data.unlisted).toBe(true);
     });
 
-    it("generates unlisted asset page for .md files", () => {
+    it("generates unlisted asset page for .md files as a nested file", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
-      const assetPage = path.join(docsDir, "claude-skills", "test-skill--asset-template.mdx");
+      const assetPage = path.join(docsDir, "claude-skills", "test-skill", "asset-template.mdx");
       expect(fs.existsSync(assetPage)).toBe(true);
 
       const parsed = matter(fs.readFileSync(assetPage, "utf8"));
@@ -290,23 +297,26 @@ describe("generateClaudeResourcesDocs", () => {
         docsDir,
       });
 
-      const scriptPage = path.join(docsDir, "claude-skills", "test-skill--script-run.mdx");
+      const scriptPage = path.join(docsDir, "claude-skills", "test-skill", "script-run.mdx");
       expect(fs.existsSync(scriptPage)).toBe(false);
     });
 
-    it("sub-pages have custom slug for nested breadcrumbs", () => {
+    it("sub-pages derive their route from the file path (no explicit slug)", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
         docsDir,
       });
 
+      // The page lives at claude-skills/test-skill/ref-guide.mdx, so its route
+      // is claude-skills/test-skill/ref-guide — nested breadcrumbs come from the
+      // file path, not an explicit slug (which zfb's link resolver ignores, #2411).
       const refPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "ref-guide.mdx"),
         "utf8",
       );
       const parsed = matter(refPage);
-      expect(parsed.data.slug).toBe("claude-skills/test-skill/ref-guide");
+      expect(parsed.data.slug).toBeUndefined();
     });
 
     it("reference page content is correct", () => {
@@ -317,7 +327,7 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const refPage = fs.readFileSync(
-        path.join(docsDir, "claude-skills", "test-skill--ref-guide.mdx"),
+        path.join(docsDir, "claude-skills", "test-skill", "ref-guide.mdx"),
         "utf8",
       );
       const parsed = matter(refPage);
@@ -532,4 +542,109 @@ describe("generateClaudeResourcesDocs", () => {
       ).toThrow(/reserved name "index"/);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // projectRoot default scope regression test
+  // ---------------------------------------------------------------------------
+
+  describe("projectRoot default scope", () => {
+    it("walks claudeDir (not its parent) when projectRoot is omitted", () => {
+      // The fixture already writes tmpDir/CLAUDE.md (outside claudeDir).
+      // With the old bug (projectRoot = path.dirname(claudeDir) = tmpDir), the
+      // walk starts at tmpDir and picks up tmpDir/CLAUDE.md. With the fix
+      // (projectRoot = claudeDir), the walk starts inside claudeDir and does NOT
+      // reach tmpDir/CLAUDE.md (parent dirs are never walked upward).
+      //
+      // To distinguish, we write a CLAUDE.md inside claudeDir with unique content
+      // and verify the generated page body matches IT, not the outside one.
+      fs.writeFileSync(
+        path.join(claudeDir, "CLAUDE.md"),
+        "# Claude dir unique content xyz123",
+      );
+
+      // Call with NO projectRoot.
+      generateClaudeResourcesDocs({ claudeDir, docsDir });
+
+      // The generated root.mdx body must contain the inside-claudeDir content.
+      const claudeMdDir = path.join(docsDir, "claude-md");
+      const rootMdx = fs.readFileSync(path.join(claudeMdDir, "root.mdx"), "utf8");
+      expect(rootMdx).toContain("xyz123");
+
+      // And must NOT contain the outside content (from tmpDir/CLAUDE.md).
+      expect(rootMdx).not.toContain("Project instructions");
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // CLAUDE.md repo-relative link downgrade (#2411, Class B)
+  // ---------------------------------------------------------------------------
+
+  describe("CLAUDE.md repo-relative link downgrade", () => {
+    const claudeMdBody = [
+      "# Project",
+      "",
+      "See [wrangler.toml](./wrangler.toml) and [schema](../../schema/photos.sql).",
+      "Also a [workflow](../../.github/workflows/deploy.yml) and a [bare](docs/guide.md) link.",
+      "External [site](https://example.com), [anchor](#section), [site-abs](/docs/getting-started), [mail](mailto:x@y.com).",
+      "Image: ![diagram](./diagram.png)",
+      "",
+      "Inline code stays: `[x](./y)`",
+      "",
+      "```",
+      "[code](./should-not-change.md)",
+      "```",
+      "",
+      "~~~",
+      "[tilde-code](./also-should-not-change.md)",
+      "~~~",
+      "",
+    ].join("\n");
+
+    function genRoot() {
+      fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), claudeMdBody);
+      generateClaudeResourcesDocs({ claudeDir, projectRoot: tmpDir, docsDir });
+      return fs.readFileSync(
+        path.join(docsDir, "claude-md", "root.mdx"),
+        "utf8",
+      );
+    }
+
+    it("downgrades repo-relative file links to inline code", () => {
+      const rootMdx = genRoot();
+      expect(rootMdx).toContain("`wrangler.toml`");
+      expect(rootMdx).toContain("`schema`");
+      expect(rootMdx).toContain("`workflow`");
+      expect(rootMdx).toContain("`bare`");
+      // The dangling hrefs must be gone.
+      expect(rootMdx).not.toContain("](./wrangler.toml)");
+      expect(rootMdx).not.toContain("](../../schema/photos.sql)");
+      expect(rootMdx).not.toContain("](../../.github/workflows/deploy.yml)");
+      expect(rootMdx).not.toContain("](docs/guide.md)");
+    });
+
+    it("preserves resolvable links (external, anchor, site-absolute, scheme)", () => {
+      const rootMdx = genRoot();
+      expect(rootMdx).toContain("](https://example.com)");
+      expect(rootMdx).toContain("](#section)");
+      expect(rootMdx).toContain("](/docs/getting-started)");
+      expect(rootMdx).toContain("](mailto:x@y.com)");
+    });
+
+    it("downgrades repo-relative image links without leaving a stray '!'", () => {
+      const rootMdx = genRoot();
+      expect(rootMdx).toContain("`diagram`");
+      expect(rootMdx).not.toContain("](./diagram.png)");
+      expect(rootMdx).not.toContain("!`diagram`");
+    });
+
+    it("does not rewrite links inside inline code or fenced code blocks", () => {
+      const rootMdx = genRoot();
+      // Inline-code span is preserved verbatim.
+      expect(rootMdx).toContain("`[x](./y)`");
+      // Backtick-fenced code block content is preserved verbatim.
+      expect(rootMdx).toContain("[code](./should-not-change.md)");
+      // Tilde-fenced code block content is preserved verbatim too.
+      expect(rootMdx).toContain("[tilde-code](./also-should-not-change.md)");
+    });
+  });
 });

package/templates/features/claudeResources/files/src/integrations/claude-resources/generate.ts

@@ -96,18 +96,24 @@ generated: true
 }
 
 /**
- * Writes an unlisted sub-page MDX file (flat file with a custom nested slug).
- * Used for skill references, scripts, and assets.
+ * Writes an unlisted sub-page MDX file. Used for skill references, scripts,
+ * and assets.
+ *
+ * The route is derived from the file's path within the content collection —
+ * deliberately NOT from an explicit `slug:`. zfb's `resolveMarkdownLinks`
+ * resolves relative links against the *source file path*, so the on-disk
+ * location of these pages must match the URL the skill page links to. Writing
+ * them at `<dir>/ref-<name>.mdx` (siblings of the skill's `index.mdx`) is what
+ * makes the `./ref-<name>` links resolve (#2411).
  */
 function writeUnlistedSubPage(
   outputPath: string,
   title: string,
-  slug: string,
   body: string,
 ) {
   fs.writeFileSync(
     outputPath,
-    `---\ntitle: "${escapeTitle(title)}"\nslug: "${slug}"\nunlisted: true\ngenerated: true\n---\n\n${body}\n`,
+    `---\ntitle: "${escapeTitle(title)}"\nunlisted: true\ngenerated: true\n---\n\n${body}\n`,
   );
 }
 
@@ -124,6 +130,82 @@ function assertNotIndexReserved(
   }
 }
 
+/**
+ * Whether a markdown link target is a repo-relative file reference
+ * (`./wrangler.toml`, `../../schema/photos.sql`, `foo/bar.md`) rather than
+ * something the doc site can resolve: an absolute URL (`https://…`), a
+ * protocol-relative URL (`//…`), a site-absolute path (`/docs/…`), a pure
+ * anchor (`#…`), or a scheme (`mailto:`, `tel:`).
+ */
+function isRepoRelativeLink(url: string): boolean {
+  const trimmed = url.trim();
+  if (trimmed === "") return false;
+  if (trimmed.startsWith("#")) return false; // anchor
+  if (trimmed.startsWith("/")) return false; // site-absolute or protocol-relative (//host)
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) return false; // has a scheme (http:, mailto:, …)
+  return true;
+}
+
+/**
+ * Downgrade repo-relative markdown links in a mirrored `CLAUDE.md` body to
+ * inline code so they don't dangle in the flattened mirror tree (#2411).
+ *
+ * A `CLAUDE.md`'s relative links point at real repo files (correct for an
+ * in-repo reader), but the mirror flattens each file into a single
+ * `claude-md/<name>.mdx` page with no counterpart for those targets — left as
+ * links they surface as `broken link:` warnings on every affected page. Inline
+ * code keeps the reference legible (`` `wrangler.toml` ``) without a href.
+ *
+ * Code spans are preserved verbatim: a `[x](./y)` inside a fenced block or an
+ * inline-code span is literal text, not a link, and must not be rewritten.
+ */
+function downgradeRepoRelativeLinks(content: string): string {
+  const blockPlaceholder = "\x00CRLINK_BLOCK_";
+  const inlinePlaceholder = "\x00CRLINK_INLINE_";
+
+  // Extract fenced code blocks so their contents are untouched. Both backtick
+  // (```) and tilde (~~~) fences are recognised; the `\1` backreference makes
+  // the closing fence match the same delimiter the block opened with.
+  const codeBlocks: string[] = [];
+  const withBlocks = content.replace(/(`{3,}|~{3,})[^\n]*\n[\s\S]*?\1/g, (match) => {
+    codeBlocks.push(match);
+    return `${blockPlaceholder}${codeBlocks.length - 1}\x00`;
+  });
+
+  const transformed = withBlocks
+    .split(new RegExp(`(${blockPlaceholder}\\d+\x00)`, "g"))
+    .map((part) => {
+      if (new RegExp(`^${blockPlaceholder}\\d+\x00$`).test(part)) return part;
+
+      // Preserve inline-code spans, then rewrite links in the remaining text.
+      const inlineCodes: string[] = [];
+      const withInline = part.replace(
+        /(`{1,3})(?!`)([\s\S]*?[^`])\1(?!`)/g,
+        (match) => {
+          inlineCodes.push(match);
+          return `${inlinePlaceholder}${inlineCodes.length - 1}\x00`;
+        },
+      );
+
+      const rewritten = withInline.replace(
+        /!?\[([^\]]*)\]\(([^)]+)\)/g,
+        (match, text: string, url: string) =>
+          isRepoRelativeLink(url) ? `\`${text}\`` : match,
+      );
+
+      return rewritten.replace(
+        new RegExp(`${inlinePlaceholder}(\\d+)\x00`, "g"),
+        (_, idx: string) => inlineCodes[Number(idx)] ?? "",
+      );
+    })
+    .join("");
+
+  return transformed.replace(
+    new RegExp(`${blockPlaceholder}(\\d+)\x00`, "g"),
+    (_, idx: string) => codeBlocks[Number(idx)] ?? "",
+  );
+}
+
 // ---------------------------------------------------------------------------
 // CLAUDE.md discovery
 // ---------------------------------------------------------------------------
@@ -164,7 +246,7 @@ function findClaudeMdFiles(dir: string, excludeDirs: string[]): string[] {
 function generateClaudemdDocs(
   config: ClaudeResourcesConfig,
 ): ClaudeMdItem[] {
-  const projectRoot = config.projectRoot ?? path.dirname(config.claudeDir);
+  const projectRoot = config.projectRoot ?? config.claudeDir;
   const outputDir = path.join(config.docsDir, "claude-md");
 
   cleanDir(outputDir);
@@ -229,7 +311,7 @@ generated: true
 
 **Path:** \`${item.relPath}\`
 
-${escapeForMdx(content.trim())}
+${escapeForMdx(downgradeRepoRelativeLinks(content.trim()))}
 `;
     fs.writeFileSync(path.join(outputDir, `${item.slug}.mdx`), mdx);
   });
@@ -309,6 +391,7 @@ function getSkillFileTree(
 
   for (let i = 0; i < entries.length; i++) {
     const entry = entries[i];
+    if (!entry) continue;
     const isLast = i === entries.length - 1;
     const prefix = isLast ? "└── " : "├── ";
 
@@ -318,6 +401,7 @@ function getSkillFileTree(
       lines.push(`${prefix}${entry.name}/`);
       for (let j = 0; j < entry.children.length; j++) {
         const child = entry.children[j];
+        if (!child) continue;
         const childIsLast = j === entry.children.length - 1;
         const continuation = isLast ? "    " : "│   ";
         const childPrefix = childIsLast ? "└── " : "├── ";
@@ -333,9 +417,10 @@ function getScriptDescription(filePath: string): string {
   try {
     const topLines = fs.readFileSync(filePath, "utf8").split("\n", 2);
     // Skip shebang, use second line if available
-    const commentLine = topLines[0].startsWith("#!")
-      ? topLines[1] || ""
-      : topLines[0];
+    const firstLine = topLines[0] ?? "";
+    const commentLine = firstLine.startsWith("#!")
+      ? topLines[1] ?? ""
+      : firstLine;
     // Match # comments (shell/python) or // comments (JS/TS)
     const match = commentLine.match(/^(?:#|\/\/)\s*(.+)/);
     return match ? ` — ${match[1]}` : "";
@@ -358,7 +443,7 @@ function getSkillReferences(
       const content = fs.readFileSync(path.join(refsDir, f), "utf8");
       const name = f.replace(/\.md$/, "");
       const h1Match = content.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : name;
+      const title = h1Match?.[1] ?? name;
       return { name, title, content };
     })
     .sort((a, b) => a.name.localeCompare(b.name));
@@ -418,9 +503,9 @@ function generateSkillsDocs(config: ClaudeResourcesConfig): SkillItem[] {
     if (subDirs.length > 0) {
       const tree = `\`\`\`\n${getSkillFileTree(dir, subDirs)}\n\`\`\``;
 
-      // Collect links to all .md sub-files that get pages
-      // Links use ./<subpage> which resolves correctly from the skill page URL
-      // (the page URL already includes the dir, e.g. /docs/claude-skills/<dir>/)
+      // Collect links to all .md sub-files that get pages. Links use
+      // ./<subpage>; because the skill page is written as `<dir>/index.mdx`,
+      // these resolve to the sibling `<dir>/<subpage>.mdx` files (#2411).
       const links: string[] = [];
       for (const ref of references) {
         links.push(`- [references/${ref.name}.md](./ref-${ref.name})`);
@@ -465,18 +550,22 @@ generated: true
 
 ${body}`;
 
-    // Write skill page as flat file
-    fs.writeFileSync(path.join(outputDir, `${dir}.mdx`), mdx);
-
-    // Generate unlisted sub-pages (flat files with custom slug for nested breadcrumbs)
-    // File: <dir>--ref-<name>.mdx, slug: claude-skills/<dir>/ref-<name>
-    const skillSlugBase = `claude-skills/${dir}`;
-
+    // Write the skill page as the directory index (`<dir>/index.mdx`) so its
+    // route is `claude-skills/<dir>` served at URL `.../claude-skills/<dir>/`.
+    // This makes the reference/script/asset pages genuine siblings inside
+    // `<dir>/`, which is what lets the `./ref-<name>` links above resolve.
+    const skillDirOut = path.join(outputDir, dir);
+    ensureDir(skillDirOut);
+    fs.writeFileSync(path.join(skillDirOut, "index.mdx"), mdx);
+
+    // Generate unlisted sub-pages as nested files inside `<dir>/`. Their routes
+    // (`claude-skills/<dir>/ref-<name>`, …) are derived from these file paths
+    // and therefore match the `./ref-<name>` / `./script-<name>` /
+    // `./asset-<name>` links emitted above (#2411).
     for (const ref of references) {
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--ref-${ref.name}.mdx`),
+        path.join(skillDirOut, `ref-${ref.name}.mdx`),
         ref.title,
-        `${skillSlugBase}/ref-${ref.name}`,
         escapeForMdx(ref.content.trim()),
       );
     }
@@ -488,11 +577,10 @@ ${body}`;
         "utf8",
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--script-${slug}.mdx`),
+        path.join(skillDirOut, `script-${slug}.mdx`),
         title,
-        `${skillSlugBase}/script-${slug}`,
         escapeForMdx(raw.trim()),
       );
     }
@@ -504,11 +592,10 @@ ${body}`;
         "utf8",
       );
       const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match ? h1Match[1] : slug;
+      const title = h1Match?.[1] ?? slug;
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--asset-${slug}.mdx`),
+        path.join(skillDirOut, `asset-${slug}.mdx`),
         title,
-        `${skillSlugBase}/asset-${slug}`,
         escapeForMdx(raw.trim()),
       );
     }