create-zudo-doc 4.0.0 → 4.2.0

package/dist/api.d.ts

@@ -1,3 +1,4 @@
+import type { PresetHeaderRightItem, PresetMetaTagsConfig } from "./preset.js";
 export type { UserChoices } from "./prompts.js";
 export interface CreateOptions {
     projectName: string;
@@ -15,7 +16,17 @@ export interface CreateOptions {
     /** GitHub repository URL — drives the header GitHub link and body-foot
      *  "View source on GitHub" link. Empty = disabled. */
     githubUrl?: string;
+    /** Enable remark-cjk-friendly plugin (intelligent spacing around CJK text). Default: false. */
+    cjkFriendly?: boolean;
+    /** Minify production HTML output. Default: true. */
+    minifyHtml?: boolean;
     packageManager: "pnpm" | "npm" | "yarn" | "bun";
+    /** Header-right items override, validated against the v1 preset allowlist
+     *  (see `validateHeaderRightItems`). When omitted, keeps the package default. */
+    headerRightItems?: PresetHeaderRightItem[];
+    /** Meta tags config, validated against the v1 preset shape
+     *  (see `validateMetaTags`). When omitted, keeps the package defaults. */
+    metaTags?: PresetMetaTagsConfig;
     /** Install dependencies after scaffolding (default: false) */
     install?: boolean;
     /**

package/dist/api.js

@@ -1,5 +1,6 @@
 import path from "path";
 import { SINGLE_SCHEMES, THEME_PACKS } from "./constants.js";
+import { validateHeaderRightItems, validateMetaTags } from "./preset.js";
 import { scaffold } from "./scaffold.js";
 import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
 export async function createZudoDoc(options) {
@@ -30,6 +31,20 @@ export async function createZudoDoc(options) {
         const catalog = THEME_PACKS.map((t) => t.slug).join(", ");
         throw new Error(`Unknown theme pack "${rest.themePack}". Available: ${catalog}`);
     }
+    // Validate headerRightItems/metaTags shape like the preset (preset.ts) path
+    // does (#2922) — the two validators are shared via preset.ts so this can
+    // never drift from `validatePreset()`'s rules. Booleans (cjkFriendly,
+    // minifyHtml) need no validation.
+    if (rest.headerRightItems !== undefined) {
+        const err = validateHeaderRightItems(rest.headerRightItems);
+        if (err)
+            throw new Error(err);
+    }
+    if (rest.metaTags !== undefined) {
+        const err = validateMetaTags(rest.metaTags);
+        if (err)
+            throw new Error(err);
+    }
     const choices = { ...rest, defaultLang: rest.defaultLang ?? "en" };
     await scaffold(choices);
     const targetDir = path.resolve(process.cwd(), choices.projectName);

package/dist/claude-md-gen.d.ts

@@ -4,7 +4,7 @@ import type { UserChoices } from "./prompts.js";
  * zudolab/zudo-doc#2651, Wave 6 #2660). Rewritten from scratch — the old
  * generator described a 64-file project (`src/components/admonitions/`,
  * `src/layouts/`, `src/utils/`, per-page `pages/lib/*` wiring) that no
- * longer exists. The scaffolded project is now ~12 files; almost
+ * longer exists. The scaffolded project is now ~13 files; almost
  * everything referenced here lives in `node_modules/@takazudo/zudo-doc`.
  */
 export declare function generateCLAUDEFile(choices: UserChoices): string;

package/dist/claude-md-gen.js

@@ -4,7 +4,7 @@ import { capitalize, pmRunCommand } from "./utils.js";
  * zudolab/zudo-doc#2651, Wave 6 #2660). Rewritten from scratch — the old
  * generator described a 64-file project (`src/components/admonitions/`,
  * `src/layouts/`, `src/utils/`, per-page `pages/lib/*` wiring) that no
- * longer exists. The scaffolded project is now ~12 files; almost
+ * longer exists. The scaffolded project is now ~13 files; almost
  * everything referenced here lives in `node_modules/@takazudo/zudo-doc`.
  */
 export function generateCLAUDEFile(choices) {
@@ -28,7 +28,14 @@ export function generateCLAUDEFile(choices) {
     lines.push(`## Commands`);
     lines.push(``);
     const pm = choices.packageManager;
-    lines.push(`- \`${pmRunCommand(pm, "dev")}\` — zfb dev server (port 4321)`);
+    if (choices.features.includes("docHistory")) {
+        lines.push(`- \`${pmRunCommand(pm, "dev")}\` — runs the zfb dev server (port 4321) and the doc-history API server (port 4322) concurrently via \`run-p\` (\`${pmRunCommand(pm, "dev:zfb")}\` / \`${pmRunCommand(pm, "dev:history")}\` individually)`);
+        lines.push(`- \`${pmRunCommand(pm, "dev:network")}\` — same, but zfb binds \`--host 0.0.0.0\` for LAN access (\`${pmRunCommand(pm, "dev:zfb:network")}\` individually); the doc-history server stays loopback-only and LAN clients reach it through zfb's \`/doc-history/*\` dev proxy`);
+        lines.push(`- \`run-p\` swallows trailing args, so other zfb flags don't forward through \`${pmRunCommand(pm, "dev")}\` — pass them directly instead: \`${pm} run dev:zfb -- <flags>\``);
+    }
+    else {
+        lines.push(`- \`${pmRunCommand(pm, "dev")}\` — zfb dev server (port 4321)`);
+    }
     lines.push(`- \`${pmRunCommand(pm, "build")}\` — static HTML export to \`dist/\``);
     lines.push(`- \`${pmRunCommand(pm, "check")}\` — TypeScript type checking`);
     lines.push(`- \`${pmRunCommand(pm, "preview")}\` — serve the built \`dist/\``);

package/dist/preset.d.ts

@@ -26,6 +26,18 @@ export interface PresetMetaTagsConfig {
     twitterSite?: string;
     twitterCreator?: string;
 }
+/**
+ * Validates a `headerRightItems` value against the v1 preset allowlist.
+ * Shared by `validatePreset()` (JSON preset path) and `createZudoDoc()`
+ * (programmatic API path, #2922) so the two entry points can never drift.
+ */
+export declare function validateHeaderRightItems(items: unknown): string | null;
+/**
+ * Validates a `metaTags` value's sub-field types. Shared by `validatePreset()`
+ * (JSON preset path) and `createZudoDoc()` (programmatic API path, #2922) so
+ * the two entry points can never drift.
+ */
+export declare function validateMetaTags(metaTags: unknown): string | null;
 export interface PresetJson {
     projectName?: string;
     defaultLang?: string;

package/dist/preset.js

@@ -12,6 +12,88 @@ const VALID_HEADER_RIGHT_TRIGGERS = new Set([
     "design-token-panel",
     "ai-chat",
 ]);
+/**
+ * Validates a `headerRightItems` value against the v1 preset allowlist.
+ * Shared by `validatePreset()` (JSON preset path) and `createZudoDoc()`
+ * (programmatic API path, #2922) so the two entry points can never drift.
+ */
+export function validateHeaderRightItems(items) {
+    if (!Array.isArray(items)) {
+        return `"headerRightItems" must be an array`;
+    }
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            return `headerRightItems[${i}] must be an object`;
+        }
+        const t = item.type;
+        if (t === "link" || t === "html") {
+            return `headerRightItems[${i}] type "${t}" is not supported in presets (v1) — edit zfb.config.ts after scaffold`;
+        }
+        if (t === "component") {
+            const component = item.component;
+            if (typeof component !== "string") {
+                return `headerRightItems[${i}].component must be a string`;
+            }
+            if (!VALID_HEADER_RIGHT_COMPONENTS.has(component)) {
+                return `headerRightItems[${i}] unknown component "${component}". Allowed: ${[
+                    ...VALID_HEADER_RIGHT_COMPONENTS,
+                ].join(", ")}`;
+            }
+        }
+        else if (t === "trigger") {
+            const trigger = item.trigger;
+            if (typeof trigger !== "string") {
+                return `headerRightItems[${i}].trigger must be a string`;
+            }
+            if (!VALID_HEADER_RIGHT_TRIGGERS.has(trigger)) {
+                return `headerRightItems[${i}] unknown trigger "${trigger}". Allowed: ${[
+                    ...VALID_HEADER_RIGHT_TRIGGERS,
+                ].join(", ")}`;
+            }
+        }
+        else {
+            return `headerRightItems[${i}] must have type "component" or "trigger" (got ${JSON.stringify(t)})`;
+        }
+    }
+    return null;
+}
+/**
+ * Validates a `metaTags` value's sub-field types. Shared by `validatePreset()`
+ * (JSON preset path) and `createZudoDoc()` (programmatic API path, #2922) so
+ * the two entry points can never drift.
+ */
+export function validateMetaTags(metaTags) {
+    if (typeof metaTags !== "object" || metaTags === null || Array.isArray(metaTags)) {
+        return `"metaTags" must be an object`;
+    }
+    const mt = metaTags;
+    if (mt.description !== undefined && typeof mt.description !== "boolean") {
+        return `"metaTags.description" must be a boolean`;
+    }
+    if (mt.keywords !== undefined && mt.keywords !== false && typeof mt.keywords !== "string") {
+        return `"metaTags.keywords" must be a string or false`;
+    }
+    if (mt.ogImage !== undefined && mt.ogImage !== false && typeof mt.ogImage !== "string") {
+        return `"metaTags.ogImage" must be a string or false`;
+    }
+    if (mt.ogSiteName !== undefined && typeof mt.ogSiteName !== "boolean") {
+        return `"metaTags.ogSiteName" must be a boolean`;
+    }
+    if (mt.twitterCard !== undefined &&
+        mt.twitterCard !== false &&
+        mt.twitterCard !== "summary" &&
+        mt.twitterCard !== "summary_large_image") {
+        return `"metaTags.twitterCard" must be "summary", "summary_large_image", or false`;
+    }
+    if (mt.twitterSite !== undefined && typeof mt.twitterSite !== "string") {
+        return `"metaTags.twitterSite" must be a string`;
+    }
+    if (mt.twitterCreator !== undefined && typeof mt.twitterCreator !== "string") {
+        return `"metaTags.twitterCreator" must be a string`;
+    }
+    return null;
+}
 export function loadPreset(pathOrStdin) {
     let raw;
     if (pathOrStdin === "-") {
@@ -85,74 +167,14 @@ export function validatePreset(json) {
         return `"minifyHtml" must be a boolean in preset`;
     }
     if (p.headerRightItems !== undefined) {
-        if (!Array.isArray(p.headerRightItems)) {
-            return `"headerRightItems" must be an array in preset`;
-        }
-        for (let i = 0; i < p.headerRightItems.length; i++) {
-            const item = p.headerRightItems[i];
-            if (item === null || typeof item !== "object" || Array.isArray(item)) {
-                return `headerRightItems[${i}] must be an object`;
-            }
-            const t = item.type;
-            if (t === "link" || t === "html") {
-                return `headerRightItems[${i}] type "${t}" is not supported in presets (v1) — edit settings.ts after scaffold`;
-            }
-            if (t === "component") {
-                const component = item.component;
-                if (typeof component !== "string") {
-                    return `headerRightItems[${i}].component must be a string`;
-                }
-                if (!VALID_HEADER_RIGHT_COMPONENTS.has(component)) {
-                    return `headerRightItems[${i}] unknown component "${component}". Allowed: ${[
-                        ...VALID_HEADER_RIGHT_COMPONENTS,
-                    ].join(", ")}`;
-                }
-            }
-            else if (t === "trigger") {
-                const trigger = item.trigger;
-                if (typeof trigger !== "string") {
-                    return `headerRightItems[${i}].trigger must be a string`;
-                }
-                if (!VALID_HEADER_RIGHT_TRIGGERS.has(trigger)) {
-                    return `headerRightItems[${i}] unknown trigger "${trigger}". Allowed: ${[
-                        ...VALID_HEADER_RIGHT_TRIGGERS,
-                    ].join(", ")}`;
-                }
-            }
-            else {
-                return `headerRightItems[${i}] must have type "component" or "trigger" (got ${JSON.stringify(t)})`;
-            }
-        }
+        const err = validateHeaderRightItems(p.headerRightItems);
+        if (err)
+            return err;
     }
     if (p.metaTags !== undefined) {
-        if (typeof p.metaTags !== "object" || p.metaTags === null || Array.isArray(p.metaTags)) {
-            return `"metaTags" must be an object in preset`;
-        }
-        const mt = p.metaTags;
-        if (mt.description !== undefined && typeof mt.description !== "boolean") {
-            return `"metaTags.description" must be a boolean`;
-        }
-        if (mt.keywords !== undefined && mt.keywords !== false && typeof mt.keywords !== "string") {
-            return `"metaTags.keywords" must be a string or false`;
-        }
-        if (mt.ogImage !== undefined && mt.ogImage !== false && typeof mt.ogImage !== "string") {
-            return `"metaTags.ogImage" must be a string or false`;
-        }
-        if (mt.ogSiteName !== undefined && typeof mt.ogSiteName !== "boolean") {
-            return `"metaTags.ogSiteName" must be a boolean`;
-        }
-        if (mt.twitterCard !== undefined &&
-            mt.twitterCard !== false &&
-            mt.twitterCard !== "summary" &&
-            mt.twitterCard !== "summary_large_image") {
-            return `"metaTags.twitterCard" must be "summary", "summary_large_image", or false`;
-        }
-        if (mt.twitterSite !== undefined && typeof mt.twitterSite !== "string") {
-            return `"metaTags.twitterSite" must be a string`;
-        }
-        if (mt.twitterCreator !== undefined && typeof mt.twitterCreator !== "string") {
-            return `"metaTags.twitterCreator" must be a string`;
-        }
+        const err = validateMetaTags(p.metaTags);
+        if (err)
+            return err;
     }
     // Cross-field validation
     if (p.colorSchemeMode === "single" && (p.lightScheme || p.darkScheme)) {

package/dist/scaffold.d.ts

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

package/dist/scaffold.js

@@ -5,7 +5,7 @@ import { generateZfbConfig } from "./zfb-config-gen.js";
 import { generateCLAUDEFile } from "./claude-md-gen.js";
 import { composeFeatures } from "./compose.js";
 import { featureModules } from "./features/index.js";
-import { capitalize, getSecondaryLang, pmRunCommand } from "./utils.js";
+import { capitalize, getSecondaryLang, hasAncestorPnpmWorkspace, pmRunCommand, } from "./utils.js";
 export { getSecondaryLang };
 /**
  * Pinned `@takazudo/zudo-doc` version used by `generatePackageJson()`.
@@ -24,7 +24,7 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^4.0.0";
+export const ZUDO_DOC_PIN = "^4.2.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -208,8 +208,6 @@ export async function scaffold(choices) {
     const templatesDir = path.join(pkgRoot, "templates");
     const baseDir = path.join(templatesDir, "base");
     const featuresDir = path.join(templatesDir, "features");
-    // Still needed for source-checkout-only assets such as Claude skills.
-    const monorepoRoot = path.resolve(pkgRoot, "../..");
     await fs.ensureDir(targetDir);
     // 1. Copy base template
     // Honour EXCLUDE_FROM_MIRROR so paths like `pages/api/**` (worker-only SSR
@@ -227,19 +225,31 @@ export async function scaffold(choices) {
     }
     // 2b. Copy user-facing Claude Code skills when enabled
     // Ships the curated zudo-doc-* skills (design-system, translate, version-bump)
-    // from the monorepo's .claude/skills/ into the user's .claude/skills/.
+    // from the package's own templates/ (npm `files` cannot reach outside the
+    // package dir, so these are committed, scaffold-authored variants of the
+    // monorepo's .claude/skills/, not read from there directly and not
+    // byte-identical to it — each was rewritten to describe the scaffold-real
+    // flow (no monorepo-only paths/scripts) instead of the monorepo's own
+    // flow — see #2921 (original copy step) and epic #2946 (variant
+    // conversion, #2947/#2948).
     if (choices.features.includes("claudeSkills")) {
         const userFacingSkills = [
             "zudo-doc-design-system",
             "zudo-doc-translate",
             "zudo-doc-version-bump",
         ];
+        const skillsTemplateDir = path.join(featuresDir, "claudeSkills/files/.claude/skills");
         for (const skill of userFacingSkills) {
-            const skillSrc = path.join(monorepoRoot, ".claude/skills", skill);
+            const skillSrc = path.join(skillsTemplateDir, skill);
             const skillDest = path.join(targetDir, ".claude/skills", skill);
             if (await fs.pathExists(skillSrc)) {
                 await fs.copy(skillSrc, skillDest);
             }
+            else {
+                // Defensive only — unreachable in a healthy publish, since the
+                // template files are committed alongside this source.
+                console.warn(`claudeSkills: missing template source for "${skill}", skipping`);
+            }
         }
     }
     const defaultLang = choices.defaultLang;
@@ -305,6 +315,7 @@ export async function scaffold(choices) {
         "node_modules",
         "dist",
         ".zfb",
+        ".zfb-build/",
         "",
         "# macOS",
         ".DS_Store",
@@ -356,6 +367,33 @@ export async function scaffold(choices) {
     // under a strict trust policy without disabling the guard wholesale. Pinned to
     // the exact known-safe version so a future undici-types bump is re-reviewed.
     await fs.outputFile(path.join(targetDir, ".npmrc"), "trust-policy-exclude[]=undici-types@6.21.0\n");
+    // Emit a pnpm-workspace.yaml disabling pnpm 11's minimumReleaseAge gate.
+    // pnpm >= 11 defaults minimumReleaseAge to 1440 (1 day), which blocks
+    // `pnpm install`/CI from resolving a freshly-published @takazudo bump for
+    // a full day; the built-in minimumReleaseAgeExclude matcher can't be
+    // pointed at this project's peer-nested lockfile keys (upstream pnpm
+    // limitation), so the gate is disabled outright rather than excluded
+    // per-package. As of pnpm 11, non-auth/registry settings like this one
+    // live in pnpm-workspace.yaml, not .npmrc (.npmrc is auth/registry only).
+    // Skipped when an ANCESTOR directory already has a pnpm-workspace.yaml
+    // (e.g. scaffolding into `apps/docs/` under an existing pnpm monorepo) —
+    // pnpm resolves the nearest pnpm-workspace.yaml upward from cwd as the
+    // workspace root, so writing a new one here would carve the generated
+    // project out of the parent workspace instead of joining it. Mirrors
+    // `initGitRepo`'s "never nest" precedent (see utils.ts).
+    if (!hasAncestorPnpmWorkspace(targetDir)) {
+        await fs.outputFile(path.join(targetDir, "pnpm-workspace.yaml"), "# pnpm 11 defaults minimumReleaseAge to 1440min; its exclude matcher can't match this project's peer-nested lockfile keys (upstream pnpm bug), so disable the gate outright.\nminimumReleaseAge: 0\n");
+    }
+    else {
+        // Ancestor already has a pnpm-workspace.yaml: we deliberately do NOT write
+        // our own (it would carve this project out of the parent workspace — see
+        // above). But then pnpm applies the PARENT workspace's minimumReleaseAge
+        // (1440min by default in pnpm 11), so freshly-published @takazudo bumps
+        // still can't install for a day — the exact failure this file guards
+        // against. We can't safely edit the parent's config, so instruct the user
+        // to disable the gate there instead of silently leaving them blocked.
+        console.warn("pnpm-workspace.yaml exists in an ancestor directory — skipping the generated one to avoid nesting a second workspace. If `pnpm install` blocks freshly-published @takazudo releases, add `minimumReleaseAge: 0` to your parent pnpm-workspace.yaml.");
+    }
     const claudeContent = generateCLAUDEFile(choices);
     await fs.outputFile(path.join(targetDir, "CLAUDE.md"), claudeContent);
     // 4. Compose features (copy feature files + inject into shared files)
@@ -512,12 +550,12 @@ function generatePackageJson(choices) {
         // singleton across host-callable wiring (zfb#1652/#1653). The zfb family
         // must stay in lockstep because the WASM browser entry depends on its
         // resource-aware island pipeline.
-        "@takazudo/zfb": "0.1.0-next.87",
-        "@takazudo/zfb-runtime": "0.1.0-next.87",
+        "@takazudo/zfb": "0.1.0-next.89",
+        "@takazudo/zfb-runtime": "0.1.0-next.89",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.87",
-        "@takazudo/zfb-md-wasm": "0.1.0-next.87",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.89",
+        "@takazudo/zfb-md-wasm": "0.1.0-next.89",
         // @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
@@ -622,10 +660,16 @@ function generatePackageJson(choices) {
         // doc-history helpers, which in turn import
         // @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"] = "^4.0.0";
+        deps["@takazudo/zudo-doc-history-server"] = "^4.2.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).
+        // npm-run-all2 provides `run-p`, used by the docHistory `dev` script
+        // (below) to run the zfb dev server and the doc-history API server
+        // concurrently — otherwise the :4322 proxy target never starts and the
+        // feature silently looks broken (#2926). Same maintained fork/pin this
+        // monorepo's own root package.json uses.
+        devDeps["npm-run-all2"] = "^7.0.2";
     }
     // claudeResources: tsx is no longer needed. The relocated package plugin
     // (@takazudo/zudo-doc/plugins/claude-resources) imports the runner directly
@@ -644,6 +688,38 @@ function generatePackageJson(choices) {
         preview: "zfb preview",
         check: "zfb check",
     };
+    if (choices.features.includes("docHistory")) {
+        // A docHistory-enabled project needs the zfb dev server AND the
+        // doc-history API server (:4322, proxied by the zfb doc-history plugin)
+        // running concurrently — otherwise the Created/Updated/Author block
+        // silently never appears in dev (#2926). `doc-history-server` is the bin
+        // shipped by the @takazudo/zudo-doc-history-server dep added above;
+        // `run-p` (npm-run-all2, added to devDependencies above) runs both.
+        scripts.dev = "run-p dev:zfb dev:history";
+        scripts["dev:zfb"] = "zfb dev";
+        // run-p swallows trailing args and npm-run-all2 v7's `{@}` placeholder
+        // strips flag names, so `pnpm dev -- --host 0.0.0.0` is silently ignored
+        // (verified in issue #2940) — dev:network is a dedicated LAN-bound script
+        // instead. Only zfb binds 0.0.0.0; the history server stays loopback-only
+        // and LAN clients reach it through zfb's `/doc-history/*` dev proxy.
+        scripts["dev:zfb:network"] = "zfb dev --host 0.0.0.0";
+        scripts["dev:network"] = "run-p dev:zfb:network dev:history";
+        // Relative --content-dir/--locale paths are resolved by resolveContentPath
+        // (packages/doc-history-server/src/args.ts) against INIT_CWD (falling back
+        // to process.cwd()) — correct for the supported invocation (`<pm> dev` /
+        // `<pm> run dev` from the project root, which is what run-p's child
+        // processes inherit). It resolves against the WRONG directory only if this
+        // generated project is itself nested inside a larger pnpm/npm workspace
+        // and dev:history is invoked via `<pm> --filter <this-package> ...` from
+        // that outer workspace root — an unsupported, non-generator invocation
+        // path, not the default `<pm> dev`.
+        let devHistoryScript = "doc-history-server --port 4322 --content-dir src/content/docs";
+        if (choices.features.includes("i18n")) {
+            const secondaryLang = getSecondaryLang(choices.defaultLang);
+            devHistoryScript += ` --locale ${secondaryLang}:src/content/docs-${secondaryLang}`;
+        }
+        scripts["dev:history"] = devHistoryScript;
+    }
     if (choices.features.includes("tagGovernance")) {
         // Both package-owned bins load the same explicit project config. `--`
         // supplied by pnpm/npm is preserved by the runners for forwarded options.

package/dist/utils.d.ts

@@ -34,6 +34,18 @@ export type GitInitResult = {
  *   none configured, so a normal user's commit keeps their own identity.
  */
 export declare function initGitRepo(dir: string): GitInitResult;
+/**
+ * Whether an ANCESTOR of `dir` (walking up from `dir`'s parent, not `dir`
+ * itself — `dir` is the fresh project root and never has one yet) already
+ * has a `pnpm-workspace.yaml`. Mirrors `initGitRepo`'s "never nest"
+ * precedent above: pnpm resolves the nearest `pnpm-workspace.yaml` upward
+ * from cwd as the workspace root, so writing a new one inside an existing
+ * pnpm monorepo (e.g. scaffolding into `apps/docs/` under a parent
+ * workspace) would carve the generated project out of that parent
+ * workspace's install/lockfile instead of joining it (codex-review finding,
+ * #2923).
+ */
+export declare function hasAncestorPnpmWorkspace(dir: string): boolean;
 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,5 +1,6 @@
 import { execSync, execFileSync } from "child_process";
 import fs from "fs-extra";
+import path from "path";
 // Project-name grammar (locked by F4 — S4 #2013):
 // /^[a-z0-9][a-z0-9._-]*$/, max 214 chars, unscoped, used as both directory
 // name and package name. Mirrors npm's unscoped-name rules + max path safety.
@@ -107,6 +108,28 @@ export function initGitRepo(dir) {
         };
     }
 }
+/**
+ * Whether an ANCESTOR of `dir` (walking up from `dir`'s parent, not `dir`
+ * itself — `dir` is the fresh project root and never has one yet) already
+ * has a `pnpm-workspace.yaml`. Mirrors `initGitRepo`'s "never nest"
+ * precedent above: pnpm resolves the nearest `pnpm-workspace.yaml` upward
+ * from cwd as the workspace root, so writing a new one inside an existing
+ * pnpm monorepo (e.g. scaffolding into `apps/docs/` under a parent
+ * workspace) would carve the generated project out of that parent
+ * workspace's install/lockfile instead of joining it (codex-review finding,
+ * #2923).
+ */
+export function hasAncestorPnpmWorkspace(dir) {
+    let current = path.dirname(path.resolve(dir));
+    while (true) {
+        if (fs.existsSync(path.join(current, "pnpm-workspace.yaml")))
+            return true;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false; // reached the filesystem root
+        current = parent;
+    }
+}
 export function capitalize(str) {
     return str.replace(/\b\w/g, (c) => c.toUpperCase());
 }

package/package.json

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

package/templates/base/scripts/setup-doc-skill.sh

@@ -74,6 +74,16 @@ fi
 # Use the main worktree path so symlinks survive worktree removal
 REPO_ROOT="$(git -C "$ROOT_DIR" worktree list | head -1 | awk '{print $1}')"
 
+# Path from the repository root to the project directory: "" at the repo
+# root, "doc/" (trailing slash) when the project lives in a subdirectory
+# (nested layout, #2918). `rev-parse --show-prefix` is relative to the
+# CURRENT worktree's top level, so combining it with REPO_ROOT (the MAIN
+# worktree root, above) reconstructs the equivalent path there even when
+# running from inside a different worktree.
+PROJECT_PREFIX="$(git -C "$ROOT_DIR" rev-parse --show-prefix)"
+REPO_DOCS_DIR="$REPO_ROOT/${PROJECT_PREFIX}src/content/docs"
+REPO_DOCS_JA_DIR="$REPO_ROOT/${PROJECT_PREFIX}src/content/docs-ja"
+
 DOCS_DIR="$ROOT_DIR/src/content/docs"
 
 # Validate docs directory exists
@@ -107,6 +117,33 @@ for dir in "$DOCS_DIR"/*/; do
 "
 done
 
+# The SKILL.md "Format"/"Verify" steps must only reference commands that
+# actually exist on the running project's package.json — a fresh
+# create-zudo-doc scaffold has no format script at all, while this repo's own
+# showcase exposes `format` (there is no `format:md` script anywhere, #2918).
+# `format:md` is checked too in case a downstream project defines its own
+# script under that literal name.
+FORMAT_SCRIPT="$(node -e "
+const scripts = (require('$ROOT_DIR/package.json').scripts) || {};
+console.log(
+  scripts.format ? 'format'
+  : scripts['format:mdx'] ? 'format:mdx'
+  : scripts['format:md'] ? 'format:md'
+  : ''
+);
+")"
+if [ -n "$FORMAT_SCRIPT" ]; then
+  FORMAT_STEP="Run \`pnpm $FORMAT_SCRIPT\` to format the new/changed MDX files."
+else
+  FORMAT_STEP="No format script is configured for this project; formatting is optional."
+fi
+
+# Name the project directory explicitly so the instruction resolves correctly
+# even when the project is nested inside a larger git repo (running `pnpm
+# build` from the outer repo root would otherwise invoke the wrong
+# package.json, #2918).
+VERIFY_STEP="Run \`pnpm build\` from \`$ROOT_DIR\` to confirm the site builds correctly."
+
 resolve_targets() {
   case "$TARGET_MODE" in
     claude) echo "claude" ;;
@@ -145,12 +182,12 @@ generate_skill() {
 
   mkdir -p "$skill_dir"
 
-  ensure_symlink "$skill_dir/docs" "$REPO_ROOT/src/content/docs"
-  echo "  [$target] Created docs symlink -> $REPO_ROOT/src/content/docs"
+  ensure_symlink "$skill_dir/docs" "$REPO_DOCS_DIR"
+  echo "  [$target] Created docs symlink -> $REPO_DOCS_DIR"
 
   if [ "$HAS_JA" = "true" ]; then
-    ensure_symlink "$skill_dir/docs-ja" "$REPO_ROOT/src/content/docs-ja"
-    echo "  [$target] Created docs-ja symlink -> $REPO_ROOT/src/content/docs-ja"
+    ensure_symlink "$skill_dir/docs-ja" "$REPO_DOCS_JA_DIR"
+    echo "  [$target] Created docs-ja symlink -> $REPO_DOCS_JA_DIR"
   fi
 
   cat > "$skill_dir/SKILL.md" << SKILLEOF
@@ -167,7 +204,7 @@ argument-hint: "[-u|--update] [topic keyword, e.g., 'configuration', 'sidebar',
 # $PROJECT_NAME Documentation Reference
 
 Look up documentation from the $PROJECT_NAME project for $assistant_label.
-Documentation base path: \`src/content/docs\` (relative to repo root)
+Documentation base path: \`src/content/docs\` (relative to the project root: \`$ROOT_DIR\`)
 
 ## Mode Detection
 
@@ -197,7 +234,7 @@ The user has new information and wants to add or update documentation in this re
    the topic. Read them to understand what is already covered.
 3. **Decide create vs update**: If an existing article covers the topic, update
    it. Otherwise, create a new \`.mdx\` file in the appropriate subdirectory.
-4. **Write the content**: Follow the doc-authoring rules in the root CLAUDE.md:
+4. **Write the content**: Follow the doc-authoring rules in this project's CLAUDE.md (\`$ROOT_DIR/CLAUDE.md\`):
    - Required frontmatter: \`title\` (string). Always set \`sidebar_position\`.
      Optional: \`description\`, \`sidebar_label\`, \`tags\`, etc.
    - Do NOT use \`# h1\` in content — the frontmatter \`title\` renders as h1.
@@ -210,8 +247,8 @@ The user has new information and wants to add or update documentation in this re
    \`docs-ja/\` mirroring the English directory structure. Keep code blocks,
    Mermaid diagrams, and \`<HtmlPreview>\` blocks identical — only translate
    surrounding prose. Exception: pages with \`generated: true\` skip translation.
-6. **Format**: Run \`pnpm format:md\` to format the new/changed MDX files.
-7. **Verify**: Run \`pnpm build\` to confirm the site builds correctly.
+6. **Format**: ${FORMAT_STEP}
+7. **Verify**: ${VERIFY_STEP}
 
 ## Documentation Structure
 

package/templates/features/claudeSkills/files/.claude/skills/zudo-doc-design-system/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: zudo-doc-design-system
+description: "Project-specific CSS and component rules for zudo-doc. Must be consulted before writing or editing CSS, Tailwind classes, color tokens, or component markup in this project. Covers: component-first strategy, design token system, three-tier color architecture, and palette index convention. Triggered by 'design system', 'zudo-doc-design-system', 'zudo-doc-css-wisdom' (old name)."
+user-invocable: true
+argument-hint: "[topic: tokens, colors, component-first, palette]"
+---
+
+# zudo-doc CSS & Component Rules
+
+**IMPORTANT**: These rules are mandatory for all code changes in this project that touch CSS, Tailwind classes, color tokens, or component markup. Read the relevant section before making changes.
+
+## How to Use
+
+Based on the topic, read the specific reference doc. These pages aren't
+scaffolded into a fresh project — they're the published zudo-doc showcase
+docs, kept up to date at the source:
+
+| Topic | Where to look |
+|-------|------|
+| Spacing, typography, layout tokens | https://zudo-doc.takazudomodular.com/docs/reference/design-system |
+| Component-first methodology | https://zudo-doc.takazudomodular.com/docs/reference/component-first |
+| Color tokens, palette, schemes | https://zudo-doc.takazudomodular.com/docs/reference/color |
+
+For the actual token values in THIS project, the source of truth is local:
+`src/styles/global.css` (the `@theme` override block) plus the shipped
+`@takazudo/zudo-doc/theme.css` and `@takazudo/zudo-doc/content.css` (imported
+by `global.css` — read them via `node_modules/@takazudo/zudo-doc/dist/` for
+the resolved token names/values).
+
+Read ONLY the section relevant to your task. Apply its rules strictly.
+
+## Quick Rules (always apply)
+
+### Component First (no custom CSS classes)
+
+- **NEVER** create CSS module files, custom class names, or separate stylesheets
+- **ALWAYS** use Tailwind utility classes directly in component markup
+- The component itself is the abstraction — `.card`, `.btn-primary` are forbidden
+- Use props for variants, not CSS modifiers
+
+### Design Tokens (no arbitrary values)
+
+- **NEVER** use Tailwind default colors (`bg-gray-500`, `text-blue-600`) — they are reset to `initial`
+- **NEVER** use arbitrary values (`text-[0.875rem]`, `p-[1.2rem]`) when a token exists
+- **ALWAYS** use project tokens: `text-fg`, `bg-surface`, `border-muted`, `p-hsp-md`, `text-small`
+- Spacing: `hsp-*` (horizontal), `vsp-*` (vertical) — see the design-system reference doc above for the full list
+- Typography: `text-caption`, `text-small`, `text-body`, `text-heading` etc.
+
+### Color Tokens (three-tier system)
+
+- **Tier 1** (ramps): shared `base` (5 stops), `accent` (3 stops), and `state` (`danger`/`success`/`warning`/`info`) OKLCH ramps — no Tailwind utility reaches these directly (no `p0`–`p15`-style classes); they only feed Tier 2
+- **Tier 2** (semantic): `text-fg`, `bg-surface`, `border-muted`, `text-accent` — the only Tailwind-facing color tokens; prefer these always
+- **NEVER** use hardcoded hex values in components
+- Both bundled schemes (`Default Light`, `Default Dark`) share the same ramps; only their per-mode wiring (`map`) differs. This project doesn't own a copy of the ramp/map definitions — they're package-owned, shipped compiled under `node_modules/@takazudo/zudo-doc/dist/color-schemes-defaults/`. Only override the `@theme` tokens you actually need to change, in `src/styles/global.css`
+
+### Search & highlight tokens (role-split)
+
+Highlight roles are deliberately split across dedicated semantic tokens — do **not** share one token across unrelated highlight UIs.
+
+- `matched-keyword-bg` / `matched-keyword-fg` — background and foreground of the search panel `<mark>` element. Driven by `--color-matched-keyword-bg` / `--color-matched-keyword-fg`; live-editable in the Design Token Panel, if that feature is enabled. This is the single source of truth for "why is this color yellow in the search results" — the panel swatch matches the rendered highlight 1:1.
+- `warning` — drives admonitions (`:::warning`), find-in-page (`.find-match`, `.find-match-active`), and any UI that is semantically a warning. Do **not** reuse it for new UI-chrome highlights.
+
+**Rule**: when a new highlight role appears (new kind of mark, new pill, new callout), add a dedicated semantic token rather than bolting it onto `--color-warning` or another existing token. Each visible highlight color should map to exactly one panel swatch.
+
+### Hover-state underline for link-like elements
+
+Any element that navigates (rendered as `<a href>` or behaves as a link) MUST have `hover:underline focus-visible:underline`. Keyboard users need the same affordance as mouse users — never add `hover:underline` without the `focus-visible:underline` pair.
+
+- **Links (do underline)**: doc content links, sidebar items, header main-nav, header overflow menu items, color-tweak panel unselected tabs, search result rows, footer links, doc history entries, breadcrumb trails, mobile TOC entries.
+- **Controls (do NOT underline)**: buttons, toggles, sidebar resizer, palette selectors, color swatches, close icons. These use border/bg hover instead.
+
+Precedent to copy the pattern from: every package-owned interactive
+component already follows it (sidebar tree nav, header nav, breadcrumb
+trail, and more, all shipped from `@takazudo/zudo-doc`) — see the live
+showcase at https://zudo-doc.takazudomodular.com for a working reference.
+Match the same hover/focus pairing in any new component you add under
+`src/components/`, or in a package component you swizzle out via
+`zudo-doc eject <component>`.
+
+### Light-mode / dark-mode contrast
+
+- Every color token must resolve to a legible foreground/background pairing
+  in BOTH bundled schemes (`Default Light`, `Default Dark`) — never
+  hardcode a value that only works in one mode.
+- Prefer the Tier 2 semantic tokens (`text-fg`, `bg-surface`, `border-muted`,
+  ...) over any raw color — they're the only values guaranteed to be
+  re-mapped per scheme.
+- When adding a new token, define it for both scheme `map`s (or as a
+  scheme-agnostic ramp value) so light/dark parity is never accidental.
+
+### Server-rendered Preact vs client islands
+
+- All components in this project are Preact `.tsx` — there are no `.astro`
+  files.
+- Default to **server-rendered Preact `.tsx`** (no `client:*` directive) —
+  emits zero JS.
+- Promote to a **client island** only when interactivity is needed
+- Both follow the same utility-class approach

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

@@ -0,0 +1,99 @@
+---
+name: zudo-doc-translate
+description: Translate zudo-doc documentation between English and Japanese with project-specific conventions.
+triggers:
+  - translate
+  - 翻訳
+  - i18n
+  - en to ja
+  - ja to en
+  - translate docs
+  - ドキュメント翻訳
+---
+
+# zudo-doc Translation Skill
+
+Translate documentation between English and Japanese following project-specific conventions.
+
+## i18n Structure
+
+This skill only applies when this project's i18n feature is enabled. A
+non-i18n scaffold has no secondary-locale content directory (e.g. no
+`docs-ja/`) and no locale-prefixed routes — there's nothing to translate.
+Check `zfb.config.ts`'s `zudoDoc({...})` call: if it sets a non-empty
+`locales` field, i18n is on.
+
+- Default-locale docs: `src/content/docs/` — routes at `/docs/...` (the
+  default locale is never prefixed)
+- Secondary-locale docs: `src/content/docs-<locale>/` — routes at
+  `/<locale>/docs/...`. For the common preset (English default, Japanese
+  secondary) this is `src/content/docs-ja/` at `/ja/docs/...`; the rest of
+  this skill assumes that pairing, but confirm the actual locale code and
+  directory from `zfb.config.ts` if this project uses a different one
+- Directory structures must mirror each other exactly (same filenames, same folder hierarchy)
+- Locale configuration lives in this project's `zfb.config.ts`, inside the
+  `zudoDoc({...})` call: `defaultLocale` (the default locale code — always
+  unprefixed, no separate flag needed) and `locales` (a map of additional
+  locale code → `{ label, dir }`; each entry becomes a `/<code>/docs/...`
+  route tree)
+
+## Translation Rules
+
+### Keep in English (do NOT translate)
+
+- Component names: `<Note>`, `<Tip>`, `<Info>`, `<Warning>`, `<Danger>`, `<Tabs>`, `<TabItem>`, `<Details>`
+- Code blocks — code is universal
+- File paths: `src/content/docs/...`, `.claude/skills/...`, etc.
+- CLI commands: `<pm> run dev`, `<pm> run build`, etc. (`<pm>` = this project's package manager)
+- Technical terms that are standard in English (e.g., component, props, frontmatter, slug)
+- Frontmatter field keys (`title`, `description`, `sidebar_position`, `category`)
+
+### Translate
+
+- Frontmatter field values (e.g., the `title` value, the `description` value)
+- The `title` prop of admonition components (e.g., `<Note title="注意">`)
+- Prose content, headings, list items, table cells (except as noted below)
+
+### Table conventions
+
+- In tables with a "Required" column: use **"Yes"** / **"No"** directly, NOT "はい" / "いいえ" — Japanese conversational yes/no is unnatural in technical documentation
+
+### Internal links
+
+- Adjust link paths when translating:
+  - En→Ja: `/docs/getting-started` → `/ja/docs/getting-started`
+  - Ja→En: `/ja/docs/getting-started` → `/docs/getting-started`
+
+## File Naming
+
+- Japanese files use the **same filenames** as English (e.g., `writing-docs.mdx`)
+- Only the parent directory differs: `docs/` vs `docs-ja/`
+- Example: `src/content/docs/guides/writing-docs.mdx` → `src/content/docs-ja/guides/writing-docs.mdx`
+
+## Workflow
+
+### En→Ja Translation
+
+1. Read the English source file from `src/content/docs/`
+2. Check if the corresponding Japanese file already exists in `src/content/docs-ja/`
+   - If it exists, read it first — use it as a base and update from the English source rather than overwriting from scratch
+   - If it does not exist, create the file at the equivalent path in `src/content/docs-ja/`
+3. Translate the content following the rules above
+4. Verify internal links point to `/ja/docs/...`
+
+### Ja→En Translation
+
+1. Read the Japanese source file from `src/content/docs-ja/`
+2. Check if the corresponding English file already exists in `src/content/docs/`
+   - If it exists, read it first — use it as a base and update from the Japanese source rather than overwriting from scratch
+   - If it does not exist, create the file at the equivalent path in `src/content/docs/`
+3. Translate the content following the rules above
+4. Verify internal links point to `/docs/...` (no `/ja/` prefix)
+
+### Post-Translation Checks
+
+- Frontmatter keys are unchanged (only values translated)
+- All admonition component names remain in English
+- Code blocks are untouched
+- Internal links use the correct locale prefix
+- Directory structure mirrors the source language

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

@@ -0,0 +1,315 @@
+---
+name: zudo-doc-version-bump
+description: >-
+  Bump package version, update changelog and versioned docs snapshot (if those features are
+  enabled), commit, tag, and create a GitHub release. Use when: (1) User says 'version bump',
+  'bump version', 'release', or 'zudo-doc-version-bump', (2) User wants to create a new release
+  of this project.
+user-invocable: true
+disable-model-invocation: true
+argument-description: "Optional: major, minor, or patch to skip the proposal step"
+---
+
+# /zudo-doc-version-bump
+
+Bump the version, update changelog content (if the changelog feature is enabled), optionally
+archive the current docs as a versioned snapshot (if the versioning feature is enabled), commit,
+tag, and create a GitHub release.
+
+## Preconditions
+
+Before doing anything else, verify ALL of the following. If any check fails, stop and tell the
+user.
+
+1. Current branch is `main` (or your project's default branch)
+2. Working tree is clean (`git status --porcelain` returns empty)
+
+Find the latest version tag, if any:
+
+```bash
+git tag -l 'v*' --sort=-v:refname | head -1
+```
+
+A freshly scaffolded project has no tags yet — that's expected on the first release. If no tag
+is found, do NOT ask the user to create one first; proceed straight to analyzing the full commit
+history in the next step instead.
+
+## Analyze changes since last tag
+
+If a previous tag was found, diff against it:
+
+```bash
+git log <last-tag>..HEAD --oneline
+git diff <last-tag>..HEAD --stat
+```
+
+If no tag exists yet (first release), analyze the whole history instead:
+
+```bash
+git log --oneline
+```
+
+Categorize each commit by its conventional-commit prefix:
+
+- **Breaking Changes**: commits with an exclamation mark suffix (e.g. `feat!:`) or BREAKING CHANGE in body
+- **Features**: `feat:` prefix
+- **Bug Fixes**: `fix:` prefix
+- **Other Changes**: everything else (`docs:`, `chore:`, `refactor:`, `ci:`, `test:`, `style:`, `perf:`, etc.)
+
+## Propose version bump
+
+Based on the changes:
+
+- If there are breaking changes → propose **major** bump
+- If there are features (no breaking) → propose **minor** bump
+- Otherwise → propose **patch** bump
+
+If the user passed an argument (`major`, `minor`, or `patch`), use that directly instead of proposing.
+
+Present the proposal to the user:
+
+```
+Proposed bump: {current} → {new} ({type})
+
+Breaking Changes:
+- description (hash)
+
+Features:
+- description (hash)
+
+Bug Fixes:
+- description (hash)
+
+Other Changes:
+- description (hash)
+```
+
+Only show sections that have entries. **Wait for user confirmation before proceeding.**
+
+If this is a **major** version bump and the project has the versioning feature enabled (see
+"Archive docs as a versioned snapshot" below), ask the user whether they want to archive the
+current docs as a versioned snapshot before continuing.
+
+## Bump the version
+
+A `create-zudo-doc` scaffold has no bundled version-bump script — bump `package.json` directly:
+
+```bash
+npm version {NEW_VERSION} --no-git-tag-version
+```
+
+`npm version` is a plain `npm` CLI feature (Node always ships `npm`), so this works no matter
+which package manager (`<pm>`) the project otherwise uses. `--no-git-tag-version` stops it from
+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.
+
+## Update the changelog (if enabled)
+
+Check whether the project has a changelog page:
+
+```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".
+
+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.
+
+### English changelog (`src/content/docs/changelog/index.mdx`)
+
+```mdx
+## {NEW_VERSION}
+
+### Breaking Changes
+
+- Description (commit-hash)
+
+### Features
+
+- Description (commit-hash)
+
+### Bug Fixes
+
+- Description (commit-hash)
+
+### Other Changes
+
+- 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.
+
+### Japanese changelog (`src/content/docs-ja/changelog/index.mdx`)
+
+Only applies when i18n is enabled (the `docs-ja` directory exists). If it doesn't, skip this file.
+
+```mdx
+## {NEW_VERSION}
+
+### 破壊的変更
+
+- Description (commit-hash)
+
+### 機能
+
+- Description (commit-hash)
+
+### バグ修正
+
+- Description (commit-hash)
+
+### その他の変更
+
+- Description (commit-hash)
+```
+
+On the first bump, replace the starter `## 未リリース` heading the same way.
+
+Rules:
+
+- Only include sections that have entries
+- Each entry should be the commit subject with the short hash in parentheses
+
+## Archive docs as a versioned snapshot (if enabled, major bumps only)
+
+Only relevant when the project has the versioning feature enabled — check for a `versions`
+array in `zfb.config.ts`'s `zudoDoc({...})` call. If `versions` is absent, `false`, or the user
+declined the snapshot offer above, skip this whole section.
+
+1. Derive the old version's slug by dropping the patch component, e.g. `0.1.0` → `0.1`,
+   `1.2.3` → `1.2`.
+2. Copy the current docs into a versioned directory:
+
+   ```bash
+   cp -r src/content/docs src/content/docs-v{OLD_SLUG}
+   ```
+
+3. If i18n is enabled (a `docs-ja` directory exists), also copy the Japanese docs:
+
+   ```bash
+   cp -r src/content/docs-ja src/content/docs-v{OLD_SLUG}-ja
+   ```
+
+4. Add an entry to the `versions` array in `zfb.config.ts`:
+
+   ```ts
+   versions: [
+     {
+       slug: "{OLD_SLUG}",
+       label: "{OLD_VERSION}",
+       docsDir: "src/content/docs-v{OLD_SLUG}",
+       locales: {
+         ja: { dir: "src/content/docs-v{OLD_SLUG}-ja" },
+       },
+       banner: "unmaintained",
+     },
+     // ...existing versions
+   ],
+   ```
+
+   Drop the `locales` block entirely when i18n is not enabled.
+
+5. `src/content/docs/` (and `src/content/docs-ja/`) now represent the new, latest version —
+   no further action needed there. The version switcher and versions listing page pick up the
+   new entry automatically at build time; nothing else needs wiring.
+
+## Build and test
+
+Run the project's pre-push validation script:
+
+```bash
+<pm> run b4push
+```
+
+If anything fails, fix the issue and re-run. Do not proceed with committing until all checks
+pass. (In a freshly scaffolded project this script may just be a `check`-then-`build` stub —
+that's fine; expand it into a richer pipeline as the project's testing needs grow.)
+
+## Commit changes
+
+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-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
+git commit -m "chore: Bump version to v{NEW_VERSION}"
+```
+
+## Push and wait for CI (if configured)
+
+Push the commits first (without the tag):
+
+```bash
+git push
+```
+
+If the project has CI configured (e.g. a GitHub Actions workflow), wait for it to pass. Use
+`gh run list --branch main --limit 1 --json status,conclusion,headSha` and verify the `headSha`
+matches the pushed commit. Poll every 30 seconds, with a **maximum of 10 minutes**. If CI is
+still running after 10 minutes, ask the user whether to keep waiting or proceed. If the project
+has no CI workflow, skip straight to tagging.
+
+If CI fails, investigate the failure with `gh run view <run-id> --log-failed`, fix the issue,
+commit, and push again.
+
+**Do not tag or publish until CI is green (or there is no CI to wait for).**
+
+## Tag, push tag, and create GitHub release
+
+**Ask the user for confirmation before tagging.**
+
+```bash
+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:
+
+```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"
+```
+
+If the changelog feature is off, write the release notes directly from the categorized commit
+analysis instead:
+
+```bash
+gh release create v{NEW_VERSION} --title "v{NEW_VERSION}" --notes "..."
+```
+
+## Publish to npm (if applicable)
+
+If the package is **not** marked as `"private": true` in `package.json`, tell the user to publish:
+
+```
+The package is ready for npm publishing. Run:
+
+  <pm> publish
+
+(This requires browser-based 2FA and must be done manually.)
+```
+
+If the package is `"private": true`, skip this step and inform the user:
+
+```
+Package is marked as private — skipping npm publish.
+```
+
+## Done
+
+Report the summary:
+
+- Version bumped: `{OLD_VERSION}` → `{NEW_VERSION}`
+- Changelog updated (EN + JA, if the changelog feature is 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
+- npm publish status (published / skipped for private package)

package/templates/features/tauri/files/src-tauri/tauri.conf.json

@@ -10,7 +10,7 @@
   "app": {
     "windows": [],
     "security": {
-      "csp": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; img-src 'self' data:; font-src 'self' data: https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; script-src 'self' 'unsafe-inline' https://esm.sh; connect-src 'self' https://esm.sh https://cdn.jsdelivr.net"
+      "csp": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; img-src 'self' data:; font-src 'self' data: https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; script-src 'self' 'unsafe-inline' https://esm.sh https://cdn.jsdelivr.net; connect-src 'self' https://esm.sh https://cdn.jsdelivr.net"
     }
   },
   "bundle": {