create-zudo-doc 5.18.1 → 5.19.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.19.0] - 2026-09-07
+
+### Features
+
+- The first positional argument is now a **destination path**, not just a project name. `create-zudo-doc sub/ref-doc` creates `sub/ref-doc` and derives the project name from the final segment (`ref-doc`); previously it failed with a project-name validation error because the one argument meant both the directory to create and the name written into the generated `package.json`. Relative (`../ref-doc`) and absolute destinations are accepted; `.`, `..`, and a filesystem root are rejected because they name no final segment. `--name` still takes a bare package name and now acts as an explicit override of the derived name while the positional continues to supply the directory. The resolved destination is followed consistently by dependency install, `git init`, and the printed `cd <dest>` hint. The programmatic `CreateOptions` API is unchanged — there `projectName` still doubles as the directory. (5a928d51e)
+
+### Bug Fixes
+
+- The printed `cd` target is quoted when the destination contains whitespace, which a path destination may now legally do, and an empty destination no longer resolves the target directory to the current working directory. (134248eba)
+
+### Other Changes
+
+- The EN and JA `create-zudo-doc` reference pages and the package README document the destination argument: an accepted-forms table, both verbatim error messages, the `--name` override, a scaffolding-into-a-subdirectory example, and a note that the programmatic API has no `destination`. (dc83c4615)
+
+## [5.18.2] - 2026-09-06
+
+### Bug Fixes
+
+- `@takazudo/zdtp` is added to a generated project only when the Design Token Panel is enabled. It had been an unconditional direct dependency of every scaffold — which is how generated projects avoided the `@takazudo/zudo-doc` bundling bug fixed in this same release — so every project without the panel installed and carried a package it never used. With that bug fixed upstream, the dependency is now gated on `designTokenPanel`. (a93ff2293)
+- Six feature flags now default on, matching the FEATURES catalog: `--sidebar-resizer`, `--sidebar-toggle`, `--toc-toggle`, `--doc-history`, `--llms-txt`, and `--asset-viewer`. A scaffold created without explicit flags now includes these features; pass the matching `--no-` flag to opt out. (6d0d3bfb9)
+
+### Other Changes
+
+- The CLI reference table was contradicted by the change above and has been corrected: the default column now matches the catalog, and the previously-missing `--[no-]asset-viewer` row was added in catalog position. The package README's feature list was corrected the same way. (c908f7f9a, f006d4ada)
+
 ## [5.18.1] - 2026-09-06
 
 ### Other Changes

package/README.md

@@ -42,6 +42,42 @@ pnpm create zudo-doc my-docs \
   --install
 ```
 
+### Destination paths
+
+The positional argument is the **destination** — the directory to scaffold
+into, not just a bare name. It may be a path (relative, `../`-prefixed, or
+absolute), and its **last segment** becomes the project name written to the
+generated `package.json`:
+
+```bash
+# Creates ./sub/ref-doc with the package name "ref-doc"
+pnpm create zudo-doc sub/ref-doc --yes
+```
+
+Only that last segment has to satisfy the project-name grammar (starts with a
+lowercase letter or digit; lowercase letters, digits, dots, underscores, and
+hyphens only; 214 characters max) — the directories leading up to it are just a
+path. `.`, `..`, and a filesystem root are rejected, because they name no last
+segment to derive the project name from.
+
+Use `--name` to override the derived name while the positional argument keeps
+supplying the directory:
+
+```bash
+# Creates ./sub/My-Docs with the package name "ref-doc"
+pnpm create zudo-doc sub/My-Docs --name ref-doc --yes
+```
+
+This makes side-by-side scaffolding straightforward — for example, comparing
+two template versions by generating both into one scratch directory and
+diffing them:
+
+```bash
+pnpm create zudo-doc@5.17.0 /tmp/tpl-check/v5.17 --yes
+pnpm create zudo-doc@5.18.0 /tmp/tpl-check/v5.18 --yes
+diff -r /tmp/tpl-check/v5.17 /tmp/tpl-check/v5.18
+```
+
 ### Locales and translations
 
 `--lang` selects the primary locale. Its pages use the unprefixed
@@ -84,7 +120,8 @@ Built-in UI translations resolve in this order:
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `[project-name]` | Project name (positional arg or `--name`) | prompted |
+| `[destination]` | Directory to scaffold into; may be a path whose last segment becomes the project name | prompted |
+| `--name <name>` | Project name written to `package.json`; overrides the name derived from the destination | destination's last segment |
 | `--lang <code>` | Default language: `en`, `ja`, `zh-cn`, `zh-tw`, `ko`, `es`, `fr`, `de`, `pt` | `en` |
 | `--additional-langs <a,b>` | Ordered additional locale codes; implies i18n and replaces a preset list | none |
 | `--pm <manager>` | Package manager: `pnpm`, `npm`, `yarn`, `bun` | detected |
@@ -113,18 +150,19 @@ Each feature has a `--[no-]<flag>` form. Passing `--feature` enables it; `--no-f
 | `--[no-]search` | Full-text search | on |
 | `--[no-]sidebar-filter` | Real-time sidebar filter | on |
 | `--[no-]image-enlarge` | Click-to-enlarge for oversized images | on |
-| `--[no-]asset-viewer` | Viewer pages for files under `public/assets/` | off |
+| `--[no-]asset-viewer` | Viewer pages for files under `public/assets/` | on |
 | `--[no-]tag-governance` | Vocabulary-aware tag audit + suggest scripts | off |
 | `--[no-]claude-resources` | Auto-generate Claude Code docs from `.claude/` | off |
 | `--[no-]codex-resources` | Auto-generate Codex docs from `.codex/` + `AGENTS.md` | off |
 | `--[no-]claude-skills` | Ship zudo-doc Claude Code skills (design-system, translate, version-bump) | off |
 | `--[no-]design-token-panel` | Interactive panel for tweaking spacing, font, color tokens | off |
-| `--[no-]sidebar-resizer` | Draggable sidebar width handle | off |
-| `--[no-]sidebar-toggle` | Show/hide desktop sidebar button | off |
+| `--[no-]sidebar-resizer` | Draggable sidebar width handle | on |
+| `--[no-]sidebar-toggle` | Show/hide desktop sidebar button | on |
+| `--[no-]toc-toggle` | Show/hide the desktop table of contents (edge chevron, xl screens) | on |
 | `--[no-]versioning` | Multi-version documentation support | off |
-| `--[no-]doc-history` | Show per-page document edit history | off |
+| `--[no-]doc-history` | Show per-page document edit history | on |
 | `--[no-]body-foot-util` | Right-aligned strip below each doc (history trigger + GitHub source link) | off |
-| `--[no-]llms-txt` | Generate `llms.txt` for LLM consumption | off |
+| `--[no-]llms-txt` | Generate `llms.txt` for LLM consumption | on |
 | `--[no-]skill-symlinker` | Symlink documentation skills into `.claude/` | off |
 | `--[no-]tauri` | Tauri desktop app — Mode 1 offline reader | off |
 | `--[no-]tauri-dev` | Tauri dev wrapper — Mode 2 configurable dev wrapper | off |

package/dist/api.js

@@ -1,8 +1,7 @@
-import path from "path";
 import { SINGLE_SCHEMES, THEME_PACKS } from "./constants.js";
 import { parseChangelogPackages, validateChangelogPackages, validateHeaderRightItems, validateMetaTags, } from "./preset.js";
 import { scaffold } from "./scaffold.js";
-import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
+import { initGitRepo, installDependencies, resolveTargetDir, validateProjectName, } from "./utils.js";
 import { resolveLocalePlan } from "./locale-plan.js";
 export { resolveLocalePlan, } from "./locale-plan.js";
 export async function createZudoDoc(options) {
@@ -69,7 +68,9 @@ export async function createZudoDoc(options) {
         changelogPackages,
     };
     await scaffold(choices);
-    const targetDir = path.resolve(process.cwd(), choices.projectName);
+    // No `destination` on CreateOptions — the programmatic API keeps the
+    // project name doubling as the directory, so the resolver falls back to it.
+    const targetDir = resolveTargetDir(choices);
     if (install) {
         installDependencies(targetDir, choices.packageManager);
     }

package/dist/cli.d.ts

@@ -1,5 +1,14 @@
 export interface CliArgs {
+    /**
+     * The `--name` flag: a bare package name. Kept separate from `destination`
+     * so the locked project-name grammar still rejects a path here.
+     */
     name?: string;
+    /**
+     * The first positional argument: the directory to scaffold into. May be a
+     * path; its final segment becomes the project name unless `--name` overrides.
+     */
+    destination?: string;
     lang?: string;
     additionalLangs?: string[];
     colorSchemeMode?: "single" | "light-dark";

package/dist/cli.js

@@ -2,7 +2,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";
+import { normalizeDestination, splitDestination, validateProjectName, } from "./utils.js";
 import { resolveLocalePlan } from "./locale-plan.js";
 /** Presets are the base layer; an explicitly supplied CLI list replaces it. */
 export function layerAdditionalLangs(presetValue, cliValue) {
@@ -39,12 +39,12 @@ export function parseArgs(argv = process.argv.slice(2)) {
         return argv.some((a) => a === `--${flag}` || a === `--no-${flag}`);
     }
     const args = {};
-    // Project name: first positional arg or --name
-    if (raw.name) {
+    // Destination: first positional arg. Project name: --name (a bare name), or
+    // the destination's final segment when --name is absent.
+    if (raw.name)
         args.name = raw.name;
-    }
-    else if (raw._.length > 0 && typeof raw._[0] === "string") {
-        args.name = raw._[0];
+    if (raw._.length > 0 && typeof raw._[0] === "string") {
+        args.destination = raw._[0];
     }
     if (raw.lang)
         args.lang = raw.lang;
@@ -100,10 +100,15 @@ export function printHelp() {
     const themePackList = THEME_PACKS.map((t) => t.slug).join(", ");
     const featureHelp = FEATURES.map((f) => `  --[no-]${f.cliFlag.padEnd(22)} ${f.hint}`).join("\n");
     console.log(`
-${pc.bold("Usage:")} create-zudo-doc [project-name] [options]
+${pc.bold("Usage:")} create-zudo-doc [destination] [options]
+
+${pc.dim("  destination")}                  Directory to create the project in; may be a path
+                               (e.g. sub/my-docs). Its last segment becomes the
+                               project name. Default: my-docs
 
 ${pc.bold("Options:")}
-  --name <name>                Project name (or first positional arg)
+  --name <name>                Project name written to package.json. Overrides
+                               the name derived from the destination's last segment
   --lang <code>                Default language (${langList})
                                Default: en
   --additional-langs <a,b>     Additional locale codes (ordered; implies i18n)
@@ -137,6 +142,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("# Scaffold into a subdirectory (package name: ref-doc)")}
+  create-zudo-doc sub/ref-doc --yes
+
   ${pc.dim("# Per-package changelog pages")}
   create-zudo-doc my-docs --changelog-packages core,cli --yes
 `);
@@ -203,5 +211,15 @@ export function validateArgs(args) {
         if (nameError)
             return nameError;
     }
+    if (args.destination !== undefined) {
+        // With --name present the derived segment is overridden, so the final
+        // segment only has to be a legal *directory* name — but a destination that
+        // names no final segment at all (".", "..", "/") is still refused.
+        const result = args.name
+            ? normalizeDestination(args.destination)
+            : splitDestination(args.destination);
+        if (!result.ok)
+            return result.error;
+    }
     return null;
 }

package/dist/constants.js

@@ -251,21 +251,21 @@ export const FEATURES = [
         value: "sidebarResizer",
         label: "Sidebar resizer",
         hint: "Draggable sidebar width",
-        default: false,
+        default: true,
         cliFlag: "sidebar-resizer",
     },
     {
         value: "sidebarToggle",
         label: "Sidebar toggle",
         hint: "Show/hide desktop sidebar",
-        default: false,
+        default: true,
         cliFlag: "sidebar-toggle",
     },
     {
         value: "tocToggle",
         label: "TOC toggle",
         hint: "Show/hide the desktop table of contents",
-        default: false,
+        default: true,
         cliFlag: "toc-toggle",
     },
     {
@@ -279,7 +279,7 @@ export const FEATURES = [
         value: "docHistory",
         label: "Document history",
         hint: "Show document edit history",
-        default: false,
+        default: true,
         cliFlag: "doc-history",
     },
     {
@@ -293,7 +293,7 @@ export const FEATURES = [
         value: "llmsTxt",
         label: "llms.txt",
         hint: "Generate llms.txt for LLM consumption",
-        default: false,
+        default: true,
         cliFlag: "llms-txt",
     },
     {
@@ -335,7 +335,7 @@ export const FEATURES = [
         value: "assetViewer",
         label: "Asset viewer",
         hint: "Viewer pages for files under public/assets",
-        default: false,
+        default: true,
         cliFlag: "asset-viewer",
     },
     {

package/dist/index.js

@@ -1,4 +1,3 @@
-import path from "path";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { layerAdditionalLangs, parseArgs, printHelp, validateArgs, } from "./cli.js";
@@ -6,7 +5,7 @@ import { FEATURES } from "./constants.js";
 import { loadPreset } from "./preset.js";
 import { runPrompts } from "./prompts.js";
 import { scaffold } from "./scaffold.js";
-import { installDependencies, initGitRepo, pmRunCommand } from "./utils.js";
+import { destinationLabel, initGitRepo, installDependencies, normalizeDestination, pmRunCommand, resolveTargetDir, } from "./utils.js";
 async function main() {
     const args = parseArgs();
     // Handle --help
@@ -36,6 +35,17 @@ async function main() {
         }
     }
     // CLI args override preset values
+    if (args.destination !== undefined) {
+        // validateArgs() already rejected a destination with no usable final
+        // segment, so this only fails on an input that never reaches here.
+        const dest = normalizeDestination(args.destination);
+        if (dest.ok) {
+            prefilled.destination = dest.destination;
+            prefilled.projectName = dest.finalSegment;
+        }
+    }
+    // --name is a deliberate override of the name derived from the destination's
+    // last segment; the positional keeps supplying the directory either way.
     if (args.name)
         prefilled.projectName = args.name;
     if (args.lang)
@@ -111,7 +121,11 @@ async function main() {
         prefilled.features = { ...featureDefaults, ...prefilled.features };
     }
     const choices = await runPrompts(prefilled);
-    const targetDir = path.resolve(process.cwd(), choices.projectName);
+    const targetDir = resolveTargetDir(choices);
+    const destination = destinationLabel(choices);
+    // A destination may now contain spaces (only its LAST segment goes through
+    // the project-name grammar), so the `cd` we print has to stay copy-pastable.
+    const cdTarget = /\s/.test(destination) ? `"${destination}"` : destination;
     const s = p.spinner();
     s.start("Scaffolding project...");
     try {
@@ -138,7 +152,7 @@ async function main() {
             initialValue: true,
         });
         if (p.isCancel(result)) {
-            p.outro(`Done! cd ${choices.projectName} and install dependencies manually.`);
+            p.outro(`Done! cd ${cdTarget} and install dependencies manually.`);
             return;
         }
         shouldInstall = result;
@@ -179,10 +193,10 @@ async function main() {
                 break;
         }
     }
-    p.outro(`${pc.green("Done!")} Your project is ready at ${pc.cyan(choices.projectName)}`);
+    p.outro(`${pc.green("Done!")} Your project is ready at ${pc.cyan(destination)}`);
     console.log();
     console.log(`  ${pc.bold("Next steps:")}`);
-    console.log(`  cd ${choices.projectName}`);
+    console.log(`  cd ${cdTarget}`);
     console.log(`  ${pmRunCommand(choices.packageManager, "dev")}`);
     console.log();
 }

package/dist/prompts.d.ts

@@ -1,6 +1,7 @@
 import { type PresetHeaderRightItem, type PresetMetaTagsConfig } from "./preset.js";
 export interface UserChoices {
     projectName: string;
+    destination?: string;
     defaultLang: string;
     additionalLangs?: string[];
     colorSchemeMode: "single" | "light-dark";
@@ -22,6 +23,8 @@ export interface UserChoices {
 }
 export interface PartialChoices {
     projectName?: string;
+    /** See `UserChoices.destination` — CLI-supplied, never prompted for. */
+    destination?: string;
     defaultLang?: string;
     additionalLangs?: string[];
     colorSchemeMode?: "single" | "light-dark";

package/dist/prompts.js

@@ -240,6 +240,7 @@ export async function runPrompts(prefilled = {}) {
         : features.filter((feature) => feature !== "i18n");
     return {
         projectName,
+        destination: prefilled.destination,
         defaultLang: localePlan.defaultLang,
         additionalLangs: prefilled.additionalLangs === undefined
             ? undefined

package/dist/scaffold.d.ts

@@ -31,5 +31,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.18.1";
+export declare const ZUDO_DOC_PIN = "^5.19.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, hasAncestorPnpmWorkspace, pmRunCommand, } from "./utils.js";
+import { capitalize, destinationLabel, hasAncestorPnpmWorkspace, pmRunCommand, resolveTargetDir, } from "./utils.js";
 import { resolveLocalePlan, } from "./locale-plan.js";
 // Kept as a compatibility export from the pre-list API. Internal scaffold
 // emitters consume the resolved LocalePlan directly; see utils.ts for the
@@ -47,7 +47,7 @@ export function deriveDocSkillName(projectName) {
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^5.18.1";
+export const ZUDO_DOC_PIN = "^5.19.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -262,11 +262,11 @@ export async function scaffold(choices) {
     if (localePlan.overridesExplicitDisable) {
         console.warn("additional-langs requires i18n; enabling it despite --no-i18n");
     }
-    const targetDir = path.resolve(process.cwd(), choices.projectName);
+    const targetDir = resolveTargetDir(choices);
     if (await fs.pathExists(targetDir)) {
         const contents = await fs.readdir(targetDir);
         if (contents.length > 0) {
-            throw new Error(`Directory "${choices.projectName}" already exists and is not empty`);
+            throw new Error(`Directory "${destinationLabel(choices)}" already exists and is not empty`);
         }
     }
     // body-foot-util-area.tsx ships the DocHistory component inline (byte-
@@ -821,26 +821,20 @@ function generatePackageJson(choices, localePlan) {
         // missing copy produces no `pnpm install` warning — which is why this gap
         // shipped silently and only surfaced at build time.
         diff: "^8.0.3",
-        // @takazudo/zdtp — SAME "unconditional at build time despite being an
-        // optional peer" class as `diff` above, discovered empirically while
-        // verifying this generator's own barebone (designTokenPanel: OFF) output
-        // (epic zudolab/zudo-doc#2651, #2660 self-review — a genuine package-level
-        // coupling, not a generator bug; flagged loudly on #2660's completion
-        // comment for a package-side follow-up). Since the #2658 gate-2 fix,
-        // `chrome/derive.tsx`'s `deriveBodyEndIslands` statically imports the REAL
-        // `DesignTokenPanelBootstrap` as the default for EVERY `createChrome`
-        // consumer (so the island auto-mounts with zero host wiring when the
-        // setting is on) — and that component imports `@takazudo/zdtp` at module
-        // scope. So every page that goes through `createChrome` — which is every
-        // page in this project — pulls the zdtp import into the esbuild bundle
-        // graph, `designTokenPanel` setting or not; only RENDERING is gated on
-        // the setting, not the import. Without this dep, `zfb build` fails with
-        // "Could not resolve '@takazudo/zdtp'" even on a fully barebone project.
-        // `preact ^10.29.1` (see the floor comment above) is required for the
-        // same reason. This is the ACCEPTED, permanent contract per #2668 — see
-        // the "@takazudo/zdtp dep implication" note in
-        // packages/zudo-doc/docs/adr/route-injection-seam.md.
-        "@takazudo/zdtp": "0.5.1",
+        // (@takazudo/zdtp is NOT here — it is gated on the designTokenPanel
+        // feature, see the block below. It WAS unconditional from #2660 through
+        // #4018: `chrome/derive.tsx`'s `deriveBodyEndIslands` statically imports
+        // the REAL `DesignTokenPanelBootstrap` for EVERY `createChrome` consumer
+        // (zero host wiring when the setting is on), and that component used to
+        // import `@takazudo/zdtp/constants` at module scope — so a barebone
+        // designTokenPanel:OFF project still died with "Could not resolve
+        // '@takazudo/zdtp/constants'". #4018 vendored those constants into
+        // @takazudo/zudo-doc, leaving only a rejection-handled
+        // `import("@takazudo/zdtp")` that esbuild tolerates when the package is
+        // absent, so the dep is now genuinely conditional (#4009).
+        // `preact` stays unconditional (the app needs it regardless); its
+        // ^10.29.1 floor is still chosen so a designTokenPanel-ON project shares
+        // one preact instance with zdtp — see the floor comment above.)
         // (@takazudo/zudo-doc-history-server is NOT here — it is gated on the
         // docHistory or assetViewer features, see the block below. It was briefly unconditional
         // (#3080) to work around doc-history-area importing its `/exclude` subpath
@@ -868,6 +862,15 @@ function generatePackageJson(choices, localePlan) {
     // search ships as @takazudo/zudo-doc's own self-contained generated
     // search-widget script (custom word-match scorer) — no third-party search
     // engine dependency is needed here. Do not re-add minisearch/pagefind.
+    if (choices.features.includes("designTokenPanel")) {
+        // Only the design-token-panel feature graph reaches @takazudo/zdtp: the
+        // panel payload loads through a rejection-handled `import("@takazudo/zdtp")`
+        // at first toggle, and this feature's global.css injection is what pulls in
+        // `@takazudo/zdtp/styles.css` (see features/design-token-panel.ts). Both are
+        // no-ops with the feature off, so an OFF project must not carry the dep
+        // (#4009 / #4018 — it was unconditional until then, see the `deps` block).
+        deps["@takazudo/zdtp"] = "0.5.1";
+    }
     if (choices.features.includes("docHistory") ||
         choices.features.includes("assetViewer")) {
         // (`diff` remains an unconditional base dep — see the `deps` block above:
@@ -889,7 +892,7 @@ function generatePackageJson(choices, localePlan) {
         // `/exclude` at module scope from the always-bundled chrome graph; #3110
         // moved compileExclude into @takazudo/zudo-doc, so projects with both
         // docHistory and assetViewer off no longer need the package at all.
-        deps["@takazudo/zudo-doc-history-server"] = "^5.18.1";
+        deps["@takazudo/zudo-doc-history-server"] = "^5.19.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

@@ -6,6 +6,63 @@
  * programmatic API.
  */
 export declare function validateProjectName(name: string): string | null;
+export type DestinationPath = {
+    ok: true;
+    destination: string;
+    finalSegment: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type DestinationSplit = {
+    ok: true;
+    destination: string;
+    projectName: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Normalize a destination path and expose its final segment.
+ *
+ * Upward traversal (`../ref-doc`) is **allowed** — `..` is simply a relative
+ * way to name a directory outside the cwd, and absolute destinations are
+ * accepted too, so rejecting it would be inconsistent. `.`, `..`, and a
+ * filesystem root are rejected because they name no final segment.
+ *
+ * `path.resolve()` is deliberately NOT applied before extracting the segment:
+ * resolving `"."` first would turn the *current* directory's basename into an
+ * apparently valid project name and scaffold into the cwd.
+ */
+export declare function normalizeDestination(raw: string): DestinationPath;
+/**
+ * Split a CLI destination argument into the directory to scaffold into and the
+ * package name written to the generated `package.json`.
+ *
+ * The final path segment becomes the project name and goes through the
+ * unchanged `validateProjectName`; everything before it is just a directory
+ * path and is deliberately not validated as a package name. Callers that
+ * supply the name separately (`--name`) use `normalizeDestination` instead, so
+ * a directory segment that is not a legal package name stays acceptable.
+ */
+export declare function splitDestination(raw: string): DestinationSplit;
+/** The two destination-bearing fields every target-dir consumer needs. */
+export interface DestinationChoices {
+    projectName: string;
+    /**
+     * Directory to scaffold into, as given on the CLI. Absent on the
+     * programmatic/preset paths, where the project name is also the directory.
+     */
+    destination?: string;
+}
+/** The destination as the user expressed it — for messages and `cd` output. */
+export declare function destinationLabel(choices: DestinationChoices): string;
+/**
+ * The single source of truth for the absolute directory a scaffold is written
+ * to. Every caller that needs it (scaffold.ts, api.ts, index.ts) must use this
+ * rather than re-deriving it — that is how the three sites used to drift.
+ */
+export declare function resolveTargetDir(choices: DestinationChoices): string;
 export declare function installDependencies(dir: string, pm: string): void;
 export type GitInitResult = {
     status: "ok";

package/dist/utils.js

@@ -3,8 +3,13 @@ import fs from "fs-extra";
 import path from "path";
 import { resolveLocalePlan } from "./locale-plan.js";
 // 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.
+// /^[a-z0-9][a-z0-9._-]*$/, max 214 chars, unscoped. Mirrors npm's
+// unscoped-name rules + max path safety.
+//
+// This grammar covers the *package name* only — the value written to the
+// generated package.json's `name`. The directory the project is written to is
+// a separate concept (`UserChoices.destination`, see `splitDestination` below)
+// and may be any path; only its final segment is checked against this grammar.
 const PROJECT_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
 const PROJECT_NAME_MAX = 214;
 /**
@@ -27,6 +32,81 @@ export function validateProjectName(name) {
     }
     return null;
 }
+/** Trailing path separators, platform-aware (Windows accepts both). */
+const TRAILING_SEPARATORS = path.sep === "\\" ? /[\\/]+$/ : /\/+$/;
+/**
+ * Normalize a destination path and expose its final segment.
+ *
+ * Upward traversal (`../ref-doc`) is **allowed** — `..` is simply a relative
+ * way to name a directory outside the cwd, and absolute destinations are
+ * accepted too, so rejecting it would be inconsistent. `.`, `..`, and a
+ * filesystem root are rejected because they name no final segment.
+ *
+ * `path.resolve()` is deliberately NOT applied before extracting the segment:
+ * resolving `"."` first would turn the *current* directory's basename into an
+ * apparently valid project name and scaffold into the cwd.
+ */
+export function normalizeDestination(raw) {
+    const given = raw.trim();
+    if (given === "") {
+        return { ok: false, error: "Destination path is required" };
+    }
+    // `sub/ref-doc/` and `sub/ref-doc` name the same directory; keep the rest of
+    // the string as the user typed it so messages and `cd` output echo it back.
+    const destination = given.replace(TRAILING_SEPARATORS, "") || given;
+    const finalSegment = path.basename(path.normalize(destination));
+    if (finalSegment === "" || finalSegment === "." || finalSegment === "..") {
+        return {
+            ok: false,
+            error: `Destination "${given}" has no final path segment to name the project. ` +
+                `Pass a destination whose last segment names the project, e.g. "sub/my-docs"`,
+        };
+    }
+    return { ok: true, destination, finalSegment };
+}
+/**
+ * Split a CLI destination argument into the directory to scaffold into and the
+ * package name written to the generated `package.json`.
+ *
+ * The final path segment becomes the project name and goes through the
+ * unchanged `validateProjectName`; everything before it is just a directory
+ * path and is deliberately not validated as a package name. Callers that
+ * supply the name separately (`--name`) use `normalizeDestination` instead, so
+ * a directory segment that is not a legal package name stays acceptable.
+ */
+export function splitDestination(raw) {
+    const normalized = normalizeDestination(raw);
+    if (!normalized.ok)
+        return normalized;
+    const nameError = validateProjectName(normalized.finalSegment);
+    if (nameError) {
+        return {
+            ok: false,
+            error: `Invalid project name "${normalized.finalSegment}" — the last segment of ` +
+                `destination "${raw.trim()}" is used as the package name. ${nameError}`,
+        };
+    }
+    return {
+        ok: true,
+        destination: normalized.destination,
+        projectName: normalized.finalSegment,
+    };
+}
+/** The destination as the user expressed it — for messages and `cd` output. */
+export function destinationLabel(choices) {
+    // `||`, not `??`: an empty destination is as absent as an undefined one, and
+    // letting `""` through would resolve the target directory to the cwd and
+    // scaffold on top of it.
+    return choices.destination || choices.projectName;
+}
+/**
+ * The single source of truth for the absolute directory a scaffold is written
+ * to. Every caller that needs it (scaffold.ts, api.ts, index.ts) must use this
+ * rather than re-deriving it — that is how the three sites used to drift.
+ */
+export function resolveTargetDir(choices) {
+    return path.resolve(process.cwd(), destinationLabel(choices));
+}
 export function installDependencies(dir, pm) {
     const commands = {
         pnpm: "pnpm install",

package/package.json

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