create-zudo-doc 5.9.0 → 5.11.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `create-zudo-doc` are documented in this file.
+
+The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
+
+## [5.11.0] - 2026-08-23
+
+### Other Changes
+
+- Updated newly generated projects to use the zfb 2.10.0 package family and the 5.11.0 zudo-doc package family. (`acaa01cf`)

package/README.md

@@ -20,6 +20,10 @@ bunx create-zudo-doc
 
 Running without arguments starts the **interactive mode**: the CLI prompts for project name, language, color scheme, and which optional features to enable, then scaffolds the project and optionally installs dependencies.
 
+Release history is shipped as `CHANGELOG.md` in the npm package. The file is
+generated from the repository's changelog MDX pages; edit those source pages
+instead of editing the generated markdown directly.
+
 ## Non-Interactive Usage
 
 Pass `--yes` to accept all defaults and skip prompts, or provide flags to pre-answer specific questions:
@@ -91,6 +95,7 @@ Each feature has a `--[no-]<flag>` form. Passing `--feature` enables it; `--no-f
 | `--[no-]footer-copyright` | Copyright notice in the footer | on |
 | `--[no-]footer-taglist` | Grouped tag index in the footer (requires tag-governance) | off |
 | `--[no-]changelog` | Changelog page | off |
+| `--changelog-packages <a,b>` | Per-package changelog pages and a Changelog dropdown (implies `--changelog`) | none |
 
 ### Advanced
 
@@ -121,6 +126,9 @@ pnpm create zudo-doc my-docs \
 
 # Fully featured site from a preset file
 pnpm create zudo-doc my-docs --preset ./my-preset.json --install
+
+# Per-package changelog pages
+pnpm create zudo-doc my-docs --changelog-packages core,cli --yes
 ```
 
 ## Programmatic API
@@ -134,6 +142,7 @@ await createZudoDoc({
   colorSchemeMode: "single",
   singleScheme: "Default Dark",
   features: ["search", "sidebarFilter", "tagGovernance"],
+  changelogPackages: ["core", "cli"],
   packageManager: "pnpm",
   install: true,
 });

package/dist/api.d.ts

@@ -13,6 +13,8 @@ export interface CreateOptions {
     /** Theme pack slug (ADR #2818 Decision 7), validated against THEME_PACKS. Default: "default". */
     themePack?: string;
     features: string[];
+    /** Package slugs for the nested changelog layout; implies `changelog`. */
+    changelogPackages?: string[];
     /** GitHub repository URL — drives the header GitHub link and body-foot
      *  "View source on GitHub" link. Empty = disabled. */
     githubUrl?: string;

package/dist/api.js

@@ -1,6 +1,6 @@
 import path from "path";
 import { SINGLE_SCHEMES, THEME_PACKS } from "./constants.js";
-import { validateHeaderRightItems, validateMetaTags } from "./preset.js";
+import { parseChangelogPackages, validateChangelogPackages, validateHeaderRightItems, validateMetaTags, } from "./preset.js";
 import { scaffold } from "./scaffold.js";
 import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
 export async function createZudoDoc(options) {
@@ -45,7 +45,18 @@ export async function createZudoDoc(options) {
         if (err)
             throw new Error(err);
     }
-    const choices = { ...rest, defaultLang: rest.defaultLang ?? "en" };
+    let changelogPackages = rest.changelogPackages;
+    if (changelogPackages !== undefined) {
+        const err = validateChangelogPackages(changelogPackages);
+        if (err)
+            throw new Error(err);
+        changelogPackages = parseChangelogPackages(changelogPackages);
+    }
+    const choices = {
+        ...rest,
+        defaultLang: rest.defaultLang ?? "en",
+        changelogPackages,
+    };
     await scaffold(choices);
     const targetDir = path.resolve(process.cwd(), choices.projectName);
     if (install) {

package/dist/claude-md-gen.js

@@ -128,7 +128,9 @@ export function generateCLAUDEFile(choices) {
         llmsTxt: "Generates llms.txt for LLM consumption",
         claudeResources: "Auto-generated docs for Claude Code resources",
         codexResources: "Auto-generated docs for Codex resources (.codex/, AGENTS.md)",
-        changelog: "Changelog page at `/docs/changelog`",
+        changelog: choices.changelogPackages && choices.changelogPackages.length > 0
+            ? `Changelog pages at \`/docs/changelog/<slug>\` — one per package: ${choices.changelogPackages.join(", ")}`
+            : "Changelog page at `/docs/changelog`",
         tauri: "Desktop app wrapper (`cargo tauri dev` / `cargo tauri build`) — Cmd/Ctrl+F find bar via the package-owned `FindInPageInit` island (`findInPage: true` in `zfb.config.ts`)",
         tagGovernance: "Vocabulary-aware tag audit (`tags:audit`) / suggest (`tags:suggest`) scripts",
     };

package/dist/cli.d.ts

@@ -29,6 +29,7 @@ export interface CliArgs {
     dynamicPageTransition?: boolean;
     footerCopyright?: boolean;
     changelog?: boolean;
+    changelogPackages?: string[];
     tagGovernance?: boolean;
     footerTaglist?: boolean;
     bodyFootUtil?: boolean;

package/dist/cli.js

@@ -1,6 +1,7 @@
 import minimist from "minimist";
 import pc from "picocolors";
 import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
+import { parseChangelogPackages, validateChangelogPackages, } from "./preset.js";
 import { validateProjectName } from "./utils.js";
 export function parseArgs(argv = process.argv.slice(2)) {
     const raw = minimist(argv, {
@@ -13,6 +14,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
             "dark-scheme",
             "default-mode",
             "theme-pack",
+            "changelog-packages",
             "github-url",
             "preset",
             "pm",
@@ -52,6 +54,11 @@ export function parseArgs(argv = process.argv.slice(2)) {
         args.defaultMode = raw["default-mode"];
     if (raw["theme-pack"])
         args.themePack = raw["theme-pack"];
+    if (raw["changelog-packages"] !== undefined) {
+        args.changelogPackages = parseChangelogPackages(typeof raw["changelog-packages"] === "string"
+            ? raw["changelog-packages"]
+            : String(raw["changelog-packages"] ?? ""));
+    }
     if (raw.preset)
         args.preset = raw.preset;
     if (raw.pm)
@@ -99,6 +106,7 @@ ${pc.bold("Options:")}
   --theme-pack <slug>          Theme pack (${themePackList})
                                Default: default
 ${featureHelp}
+  --changelog-packages <a,b>  Per-package changelog pages (implies changelog)
   --github-url <url>           GitHub repository URL (drives header link + source link)
   --preset <path>              Load settings from a JSON preset file (use "-" for stdin)
   --pm <manager>               pnpm | npm | yarn | bun
@@ -117,6 +125,9 @@ ${pc.bold("Examples:")}
 
   ${pc.dim("# Fully specified")}
   create-zudo-doc my-docs --lang ja --scheme "Default Dark" --no-i18n --pm pnpm --install
+
+  ${pc.dim("# Per-package changelog pages")}
+  create-zudo-doc my-docs --changelog-packages core,cli --yes
 `);
 }
 export function validateArgs(args) {
@@ -148,6 +159,11 @@ export function validateArgs(args) {
     if (args.pm && !["pnpm", "npm", "yarn", "bun"].includes(args.pm)) {
         return `Invalid package manager "${args.pm}". Must be pnpm, npm, yarn, or bun`;
     }
+    if (args.changelogPackages !== undefined) {
+        const changelogError = validateChangelogPackages(args.changelogPackages);
+        if (changelogError)
+            return changelogError;
+    }
     // Validate scheme combinations
     if (args.colorSchemeMode === "single" && (args.lightScheme || args.darkScheme)) {
         return `--light-scheme and --dark-scheme are only valid with --color-scheme-mode light-dark`;

package/dist/index.js

@@ -61,6 +61,9 @@ async function main() {
         prefilled.packageManager = args.pm;
     if (args.githubUrl !== undefined)
         prefilled.githubUrl = args.githubUrl;
+    if (args.changelogPackages !== undefined) {
+        prefilled.changelogPackages = args.changelogPackages;
+    }
     // Build feature overrides from explicit flags — driven by FEATURES constant
     const featureFlags = {};
     for (const f of FEATURES) {
@@ -96,6 +99,9 @@ async function main() {
         prefilled.themePack ??= "default";
         prefilled.packageManager ??= "pnpm";
         prefilled.githubUrl ??= "";
+        // A blank package list is the explicit non-interactive choice for the
+        // existing single-page changelog. A non-empty CLI/preset list above wins.
+        prefilled.changelogPackages ??= [];
         // For features: set defaults for any not explicitly specified
         const featureDefaults = {};
         for (const f of FEATURES) {

package/dist/preset.d.ts

@@ -26,6 +26,18 @@ export interface PresetMetaTagsConfig {
     twitterSite?: string;
     twitterCreator?: string;
 }
+/**
+ * Parse the comma-separated CLI form (or normalize the array form used by
+ * presets and the programmatic API). Empty entries are ignored so a trailing
+ * comma is harmless; validation below still rejects an entirely empty list.
+ */
+export declare function parseChangelogPackages(value: string | readonly string[]): string[];
+/**
+ * Shared changelog-package validation for CLI, JSON presets, and the
+ * programmatic API. Keeping this next to the parser prevents the three entry
+ * points from accepting different slug grammars or duplicate lists.
+ */
+export declare function validateChangelogPackages(list: unknown): string | null;
 /**
  * Validates a `headerRightItems` value against the v1 preset allowlist.
  * Shared by `validatePreset()` (JSON preset path) and `createZudoDoc()`
@@ -50,6 +62,8 @@ export interface PresetJson {
     /** Theme pack slug (ADR #2818 Decision 7), validated against THEME_PACKS. */
     themePack?: string;
     features?: string[];
+    /** Package slugs for the nested changelog layout. */
+    changelogPackages?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;
     minifyHtml?: boolean;

package/dist/preset.js

@@ -12,6 +12,46 @@ const VALID_HEADER_RIGHT_TRIGGERS = new Set([
     "design-token-panel",
     "ai-chat",
 ]);
+const CHANGELOG_PACKAGE_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Parse the comma-separated CLI form (or normalize the array form used by
+ * presets and the programmatic API). Empty entries are ignored so a trailing
+ * comma is harmless; validation below still rejects an entirely empty list.
+ */
+export function parseChangelogPackages(value) {
+    const values = typeof value === "string" ? value.split(",") : value;
+    return values.map((slug) => slug.trim()).filter(Boolean);
+}
+/**
+ * Shared changelog-package validation for CLI, JSON presets, and the
+ * programmatic API. Keeping this next to the parser prevents the three entry
+ * points from accepting different slug grammars or duplicate lists.
+ */
+export function validateChangelogPackages(list) {
+    if (!Array.isArray(list)) {
+        return `"changelogPackages" must be an array`;
+    }
+    for (let i = 0; i < list.length; i++) {
+        if (typeof list[i] !== "string") {
+            return `changelogPackages[${i}] must be a string`;
+        }
+    }
+    const packages = parseChangelogPackages(list);
+    if (packages.length === 0) {
+        return `"changelogPackages" must contain at least one package`;
+    }
+    const seen = new Set();
+    for (const slug of packages) {
+        if (!CHANGELOG_PACKAGE_SLUG_RE.test(slug)) {
+            return `Invalid changelog package slug "${slug}". Slugs must match /^[a-z0-9][a-z0-9-]*$/`;
+        }
+        if (seen.has(slug)) {
+            return `Duplicate changelog package "${slug}"`;
+        }
+        seen.add(slug);
+    }
+    return null;
+}
 /**
  * Validates a `headerRightItems` value against the v1 preset allowlist.
  * Shared by `validatePreset()` (JSON preset path) and `createZudoDoc()`
@@ -131,6 +171,17 @@ export function validatePreset(json) {
     if (p.features !== undefined && !Array.isArray(p.features)) {
         return `"features" must be an array in preset`;
     }
+    if (p.changelogPackages !== undefined) {
+        if (!Array.isArray(p.changelogPackages)) {
+            return `"changelogPackages" must be an array in preset`;
+        }
+        const changelogPackages = p.changelogPackages.every((slug) => typeof slug === "string")
+            ? parseChangelogPackages(p.changelogPackages)
+            : p.changelogPackages;
+        const err = validateChangelogPackages(changelogPackages);
+        if (err)
+            return err;
+    }
     if (p.defaultLang && !VALID_LANGS.has(p.defaultLang)) {
         return `Invalid language "${p.defaultLang}" in preset`;
     }
@@ -215,6 +266,9 @@ export function presetToChoices(json) {
         choices.cjkFriendly = json.cjkFriendly;
     if (json.minifyHtml !== undefined)
         choices.minifyHtml = json.minifyHtml;
+    if (json.changelogPackages !== undefined) {
+        choices.changelogPackages = parseChangelogPackages(json.changelogPackages);
+    }
     if (json.headerRightItems !== undefined) {
         choices.headerRightItems = json.headerRightItems;
     }

package/dist/prompts.d.ts

@@ -1,4 +1,4 @@
-import type { PresetHeaderRightItem, PresetMetaTagsConfig } from "./preset.js";
+import { type PresetHeaderRightItem, type PresetMetaTagsConfig } from "./preset.js";
 export interface UserChoices {
     projectName: string;
     defaultLang: string;
@@ -10,6 +10,7 @@ export interface UserChoices {
     defaultMode?: "light" | "dark";
     themePack?: string;
     features: string[];
+    changelogPackages?: string[];
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;
@@ -29,6 +30,7 @@ export interface PartialChoices {
     defaultMode?: "light" | "dark";
     themePack?: string;
     features?: Partial<Record<string, boolean>>;
+    changelogPackages?: string[];
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;

package/dist/prompts.js

@@ -1,5 +1,6 @@
 import * as p from "@clack/prompts";
 import { SINGLE_SCHEMES, FEATURES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
+import { parseChangelogPackages, validateChangelogPackages, } from "./preset.js";
 import { validateProjectName } from "./utils.js";
 export async function runPrompts(prefilled = {}) {
     // 1. Project name
@@ -170,6 +171,26 @@ export async function runPrompts(prefilled = {}) {
             process.exit(0);
         features = result;
     }
+    // 4.5 Changelog package layout. A blank answer deliberately preserves the
+    // existing single-page starter. CLI/preset/--yes callers prefill this value
+    // so they remain non-interactive.
+    let changelogPackages = prefilled.changelogPackages;
+    if (features.includes("changelog") && changelogPackages === undefined) {
+        const result = await p.text({
+            message: "Package changelogs (comma-separated slugs; leave empty for a single changelog):",
+            placeholder: "core,cli",
+            defaultValue: "",
+            validate(value) {
+                if (!value.trim())
+                    return;
+                const parsed = parseChangelogPackages(value);
+                return validateChangelogPackages(parsed) ?? undefined;
+            },
+        });
+        if (p.isCancel(result))
+            process.exit(0);
+        changelogPackages = parseChangelogPackages(result);
+    }
     // 5. GitHub URL (drives header GitHub icon + view-source link)
     let githubUrl = prefilled.githubUrl;
     if (githubUrl === undefined) {
@@ -218,6 +239,7 @@ export async function runPrompts(prefilled = {}) {
         defaultMode,
         themePack,
         features,
+        changelogPackages,
         explicitlyDisabledFeatures: prefilled.explicitlyDisabledFeatures,
         githubUrl,
         cjkFriendly: prefilled.cjkFriendly,

package/dist/scaffold.d.ts

@@ -32,5 +32,5 @@ export declare function deriveDocSkillName(projectName: string): string;
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^5.9.0";
+export declare const ZUDO_DOC_PIN = "^5.11.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -43,7 +43,7 @@ export function deriveDocSkillName(projectName) {
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^5.9.0";
+export const ZUDO_DOC_PIN = "^5.11.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -186,8 +186,6 @@ title: Changelog
 sidebar_position: 99
 ---
 
-# Changelog
-
 ## Unreleased
 
 - Initial release
@@ -197,7 +195,45 @@ title: 変更履歴
 sidebar_position: 99
 ---
 
-# 変更履歴
+## 未リリース
+
+- 初回リリース
+`;
+const CHANGELOG_LANDING_CONTENT_EN = () => `---
+title: Changelog
+description: Release notes for each package.
+sidebar_position: 99
+---
+
+Release notes for each package.
+
+<CategoryNav category="changelog" />
+`;
+const CHANGELOG_LANDING_CONTENT_JA = () => `---
+title: 変更履歴
+description: パッケージごとのリリースノート。
+sidebar_position: 99
+---
+
+パッケージごとのリリースノート。
+
+<CategoryNav category="changelog" />
+`;
+const CHANGELOG_PACKAGE_CONTENT_EN = (slug, position) => `---
+title: "${slug}"
+description: Release notes for ${slug}.
+sidebar_position: ${position}
+---
+
+## Unreleased
+
+- Initial release
+`;
+const CHANGELOG_PACKAGE_CONTENT_JA = (slug, position) => `---
+title: "${slug}"
+description: ${slug} のリリースノート。
+sidebar_position: ${position}
+---
 
 ## 未リリース
 
@@ -222,6 +258,16 @@ export async function scaffold(choices) {
         }
         choices.features = [...choices.features, "docHistory"];
     }
+    // A non-empty package list implies the changelog feature. Warn when the
+    // CLI explicitly disabled it, then honor the package-layout request.
+    if (choices.changelogPackages !== undefined &&
+        choices.changelogPackages.length > 0 &&
+        !choices.features.includes("changelog")) {
+        if (choices.explicitlyDisabledFeatures?.includes("changelog")) {
+            console.warn("changelog-packages requires changelog; enabling it despite --no-changelog");
+        }
+        choices.features = [...choices.features, "changelog"];
+    }
     // Resolve template directories
     const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
     const templatesDir = path.join(pkgRoot, "templates");
@@ -324,14 +370,44 @@ export async function scaffold(choices) {
     }
     // When changelog is ON, create a starter changelog page
     if (choices.features.includes("changelog")) {
-        const changelogContent = defaultLang === "ja" ? CHANGELOG_CONTENT_JA() : CHANGELOG_CONTENT_EN();
-        await fs.outputFile(path.join(targetDir, "src/content/docs/changelog/index.mdx"), changelogContent);
+        const packageSlugs = choices.changelogPackages ?? [];
+        if (packageSlugs.length === 0) {
+            const changelogContent = defaultLang === "ja" ? CHANGELOG_CONTENT_JA() : CHANGELOG_CONTENT_EN();
+            await fs.outputFile(path.join(targetDir, "src/content/docs/changelog/index.mdx"), changelogContent);
+        }
+        else {
+            const landingContent = defaultLang === "ja"
+                ? CHANGELOG_LANDING_CONTENT_JA()
+                : CHANGELOG_LANDING_CONTENT_EN();
+            await fs.outputFile(path.join(targetDir, "src/content/docs/changelog/index.mdx"), landingContent);
+            for (const [index, slug] of packageSlugs.entries()) {
+                const packageContent = defaultLang === "ja"
+                    ? CHANGELOG_PACKAGE_CONTENT_JA(slug, index + 1)
+                    : CHANGELOG_PACKAGE_CONTENT_EN(slug, index + 1);
+                await fs.outputFile(path.join(targetDir, `src/content/docs/changelog/${slug}/index.mdx`), packageContent);
+            }
+        }
         if (choices.features.includes("i18n")) {
             const secondaryLang = getSecondaryLang(defaultLang);
-            const secondaryChangelogContent = secondaryLang === "ja"
-                ? CHANGELOG_CONTENT_JA()
-                : CHANGELOG_CONTENT_EN();
-            await fs.outputFile(path.join(targetDir, `src/content/docs-${secondaryLang}/changelog/index.mdx`), secondaryChangelogContent);
+            if (packageSlugs.length === 0) {
+                const secondaryChangelogContent = secondaryLang === "ja"
+                    ? CHANGELOG_CONTENT_JA()
+                    : CHANGELOG_CONTENT_EN();
+                await fs.outputFile(path.join(targetDir, `src/content/docs-${secondaryLang}/changelog/index.mdx`), secondaryChangelogContent);
+            }
+            else {
+                const secondaryLandingContent = secondaryLang === "ja"
+                    ? CHANGELOG_LANDING_CONTENT_JA()
+                    : CHANGELOG_LANDING_CONTENT_EN();
+                const secondaryDir = `src/content/docs-${secondaryLang}/changelog`;
+                await fs.outputFile(path.join(targetDir, `${secondaryDir}/index.mdx`), secondaryLandingContent);
+                for (const [index, slug] of packageSlugs.entries()) {
+                    const secondaryPackageContent = secondaryLang === "ja"
+                        ? CHANGELOG_PACKAGE_CONTENT_JA(slug, index + 1)
+                        : CHANGELOG_PACKAGE_CONTENT_EN(slug, index + 1);
+                    await fs.outputFile(path.join(targetDir, `${secondaryDir}/${slug}/index.mdx`), secondaryPackageContent);
+                }
+            }
         }
     }
     // 3. Generate the one config file. There is no more src/config/settings.ts —
@@ -624,9 +700,11 @@ function generatePackageJson(choices) {
         // default, so a fresh scaffold needs no config change to pick it up.
         // Also fixes the client router to tolerate about:srcdoc history
         // restrictions. No generator-side migration.
-        "@takazudo/zfb": "2.7.1",
-        "@takazudo/zfb-runtime": "2.7.1",
-        "@takazudo/zfb-md-wasm": "2.7.1",
+        // 2.10.0: routine toolchain bump from 2.9.0, adopted in lockstep with the
+        // root package.json pins. No generator-side migration.
+        "@takazudo/zfb": "2.10.0",
+        "@takazudo/zfb-runtime": "2.10.0",
+        "@takazudo/zfb-md-wasm": "2.10.0",
         // @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
@@ -748,7 +826,7 @@ function generatePackageJson(choices) {
         // `/exclude` at module scope from the always-bundled chrome graph; #3110
         // moved compileExclude into @takazudo/zudo-doc, so docHistory-OFF projects
         // no longer need the package at all.
-        deps["@takazudo/zudo-doc-history-server"] = "^5.9.0";
+        deps["@takazudo/zudo-doc-history-server"] = "^5.11.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/zfb-config-gen.js

@@ -309,11 +309,26 @@ function buildDesiredConfig(choices) {
         });
     }
     if (choices.features.includes("changelog")) {
-        headerNav.push({
-            label: "Changelog",
-            path: "/docs/changelog",
-            categoryMatch: "changelog",
-        });
+        if (choices.changelogPackages && choices.changelogPackages.length > 0) {
+            headerNav.push({
+                label: "Changelog",
+                path: "/docs/changelog",
+                categoryMatch: "changelog",
+                // nav-scope matches the first slug segment only; nested children
+                // highlight by path and must not carry a multi-segment categoryMatch.
+                children: choices.changelogPackages.map((slug) => ({
+                    label: slug,
+                    path: `/docs/changelog/${slug}`,
+                })),
+            });
+        }
+        else {
+            headerNav.push({
+                label: "Changelog",
+                path: "/docs/changelog",
+                categoryMatch: "changelog",
+            });
+        }
     }
     desired.headerNav = headerNav;
     if (choices.headerRightItems !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "5.9.0",
+  "version": "5.11.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",
@@ -40,7 +40,8 @@
     "bin",
     "dist",
     "templates",
-    "!dist/__tests__"
+    "!dist/__tests__",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",

package/templates/features/claudeSkills/files/.claude/skills/zudo-doc-version-bump/SKILL.md

@@ -103,32 +103,61 @@ which package manager (`<pm>`) the project otherwise uses. `--no-git-tag-version
 also creating a commit/tag — this skill handles that later, once everything else is ready. A
 direct edit of the `"version"` field in `package.json` works identically if preferred.
 
+The project has **one root version**. All packages represented in a multi-package changelog move
+to `{NEW_VERSION}` in lockstep; independent per-package versions are out of scope for this skill.
+
 ## Update the changelog (if enabled)
 
-Check whether the project has a changelog page:
+First check whether the default-language changelog exists:
 
 ```bash
 test -f src/content/docs/changelog/index.mdx && echo "changelog present"
 ```
 
-If that file does not exist, the changelog feature is not in use — skip this whole section and
-go straight to "Archive docs as a versioned snapshot".
+If `src/content/docs/changelog/index.mdx` does not exist, the changelog feature is not in use —
+skip this whole section and go straight to "Archive docs as a versioned snapshot".
 
-Unlike a per-version file, a scaffolded changelog is a single `index.mdx` page. Add the new
-release as a section **above** the existing ones (newest first), using only the categories that
-have entries.
+### Discover package and page layouts
 
-### Default-language changelog (`src/content/docs/changelog/index.mdx`)
+Treat `src/content/docs/changelog/` as the primary changelog root. List every immediate child
+directory that contains an `index.mdx`; each directory name is a package slug:
 
-This is the project's PRIMARY changelog page. It was seeded in whichever language the project's
-`defaultLang` setting is, so use whichever heading set below already matches the page — don't
-assume English.
+```bash
+find src/content/docs/changelog -mindepth 2 -maxdepth 2 -type f -name index.mdx \
+  -print | sed 's#/index\.mdx$##; s#.*/##' | sort
+```
 
-**If the page uses English headings:**
+Then follow exactly one branch:
 
-```mdx
-## {NEW_VERSION}
+1. **One or more package directories:** the root `index.mdx` is a landing page and must never be
+   edited. Show the package slugs to the user and ask which packages this release touches. Default
+   to **all packages**; accept a comma-separated list. Reject names that are not in the discovered
+   list. Apply the per-directory procedure below to each selected package directory.
+2. **No package directories:** apply the per-directory procedure to the changelog root itself.
+
+For every selected directory, detect its layout independently, before making changes:
+
+```bash
+find "<changelog-directory>" -maxdepth 1 -type f -name '*.mdx' ! -name index.mdx \
+  -print -quit
+```
+
+- Any output means **per-version-file layout**. Create a new version file; never insert a version
+  section into that directory's `index.mdx`.
+- No output means **single-page layout**. Edit that directory's `index.mdx` using the existing
+  section procedure.
+
+This per-directory check is mandatory: packages in one project may use different layouts.
+
+### Choose the language-specific headings
+
+The primary content directory was seeded in the project's `defaultLang`, so do not assume it is
+English. For a single-page directory, inspect its `index.mdx`. For a per-version-file directory,
+inspect its existing sibling version entries. Use the heading set already used by those files.
 
+**English heading set:**
+
+```mdx
 ### Breaking Changes
 
 - Description (commit-hash)
@@ -146,14 +175,9 @@ assume English.
 - Description (commit-hash)
 ```
 
-On the very first bump, the page still has the scaffold's starter `## Unreleased` section —
-replace that heading with `## {NEW_VERSION}` rather than adding a second heading.
-
-**If the page uses Japanese headings:**
+**Japanese heading set:**
 
 ```mdx
-## {NEW_VERSION}
-
 ### 破壊的変更
 
 - Description (commit-hash)
@@ -171,8 +195,44 @@ replace that heading with `## {NEW_VERSION}` rather than adding a second heading
 - Description (commit-hash)
 ```
 
-On the very first bump, the page still has the scaffold's starter `## 未リリース` section —
-replace that heading with `## {NEW_VERSION}` the same way.
+In either language, include only categories that have entries. Each entry is the commit subject
+with its short hash in parentheses.
+
+### Update a single-page directory
+
+Add this release above all existing release sections in the directory's `index.mdx` (newest
+first):
+
+```mdx
+## {NEW_VERSION}
+
+<!-- categories and entries from the matching heading set above -->
+```
+
+On the first bump, replace the starter `## Unreleased` or `## 未リリース` heading with
+`## {NEW_VERSION}` instead of adding a second release heading.
+
+### Update a per-version-file directory
+
+Create `<changelog-directory>/<version>.mdx`, where `<version>` is `{NEW_VERSION}` without a
+leading `v`. Never section-edit this directory's `index.mdx`. Determine the greatest numeric
+`sidebar_position` in the existing sibling version files and use that value plus one. The new file
+must have localized frontmatter and body text matching its siblings, in this shape:
+
+```mdx
+---
+title: "{NEW_VERSION}"
+description: Release notes for {NEW_VERSION}.
+sidebar_position: {MAX_EXISTING_PLUS_ONE}
+---
+
+Released: {YYYY-MM-DD}
+
+<!-- categories and entries from the matching heading set above -->
+```
+
+Use a concise Japanese `description` when the sibling entries are Japanese, but keep the required
+`Released: {YYYY-MM-DD}` line in either language. Use today's date for `{YYYY-MM-DD}`.
 
 ### Other-locale changelog
 
@@ -180,17 +240,13 @@ Only applies when i18n is enabled — i.e. a second content directory exists alo
 one. Which locale that is depends on the project's `defaultLang`: for an English-default project
 this is the Japanese changelog at `src/content/docs-ja/changelog/index.mdx`; for a
 Japanese-default project this is the English changelog under the `docs-en` directory instead. If
-the other-locale changelog page doesn't exist, skip this file.
-
-Use the OTHER heading set from above (the one you didn't use for the default-language page —
-English primary means Japanese secondary, and vice versa), following the same "add a new
-`## {NEW_VERSION}` section above the existing ones" rule, and replace that page's own starter
-heading on the very first bump.
+the other-locale changelog root doesn't exist, skip mirroring.
 
-Rules:
-
-- Only include sections that have entries
-- Each entry should be the commit subject with the short hash in parentheses
+Mirror exactly the selected primary targets by relative path under the other-locale root, detect
+each mirror directory's layout independently, and apply the matching single-page or
+per-version-file procedure. Use the other language's heading set. In a multi-package layout,
+never edit either locale's landing `changelog/index.mdx`. If a selected package has no matching
+other-locale directory, report it and stop instead of silently creating a divergent layout.
 
 ## Archive docs as a versioned snapshot (if enabled, major bumps only)
 
@@ -253,7 +309,7 @@ Stage and commit **all** version bump changes:
 
 ```bash
 git add package.json
-git add src/content/docs/changelog/index.mdx src/content/docs-ja/changelog/index.mdx 2>/dev/null
+git add src/content/docs*/changelog/ 2>/dev/null
 git add src/content/docs-v* 2>/dev/null
 # Also stage any other modified files (e.g. formatting fixes from the build/test step)
 git diff --name-only | xargs -r git add
@@ -288,14 +344,44 @@ git tag v{NEW_VERSION}
 git push --tags
 ```
 
-After pushing the tag, create a GitHub release. If the changelog feature is enabled, pull the
-section you just wrote out of the single changelog page as the release notes:
+After pushing the tag, create a GitHub release. If a root single-page changelog was updated, pull
+the section you just wrote out as before:
 
 ```bash
 NOTES=$(awk -v ver="## {NEW_VERSION}" '$0==ver{f=1;next} f&&/^## /{f=0} f' src/content/docs/changelog/index.mdx)
 gh release create v{NEW_VERSION} --title "v{NEW_VERSION}" --notes "$NOTES"
 ```
 
+For a root per-version-file layout, remove the frontmatter from the new entry and use the rest of
+its body as `NOTES`:
+
+```bash
+NOTES=$(awk 'NR==1&&$0=="---"{fm=1;next} fm&&$0=="---"{fm=0;next} !fm{print}' "src/content/docs/changelog/{NEW_VERSION}.mdx")
+gh release create v{NEW_VERSION} --title "v{NEW_VERSION}" --notes "$NOTES"
+```
+
+For a multi-package changelog, concatenate the primary-language notes for every selected package,
+in the same order shown to the user, under a `## <slug>` heading. This concrete loop handles a mix
+of single-page and per-version-file package directories:
+
+```bash
+NOTES=""
+for slug in $SELECTED_PACKAGES; do
+  dir="src/content/docs/changelog/$slug"
+  if test -f "$dir/{NEW_VERSION}.mdx"; then
+    body=$(awk 'NR==1&&$0=="---"{fm=1;next} fm&&$0=="---"{fm=0;next} !fm{print}' "$dir/{NEW_VERSION}.mdx")
+  else
+    body=$(awk -v ver="## {NEW_VERSION}" '$0==ver{f=1;next} f&&/^## /{f=0} f' "$dir/index.mdx")
+  fi
+  printf -v NOTES '%s## %s\n\n%s\n\n' "$NOTES" "$slug" "$body"
+done
+gh release create v{NEW_VERSION} --title "v{NEW_VERSION}" --notes "$NOTES"
+```
+
+Set `SELECTED_PACKAGES` to the validated, space-separated package slugs chosen earlier. Build
+release notes from the primary-language files only; the other-locale mirror is not duplicated in
+the GitHub release body.
+
 If the changelog feature is off, write the release notes directly from the categorized commit
 analysis instead:
 
@@ -326,7 +412,7 @@ Package is marked as private — skipping npm publish.
 Report the summary:
 
 - Version bumped: `{OLD_VERSION}` → `{NEW_VERSION}`
-- Changelog updated (EN + JA, if the changelog feature is enabled)
+- Changelog layout(s) and selected package(s) updated (EN + JA, if enabled)
 - Docs snapshot created (if the versioning feature is enabled and a snapshot was taken)
 - Git tag: `v{NEW_VERSION}`
 - GitHub release: link to the release