create-zudo-doc 3.3.0 → 4.1.0

package/README.md

@@ -72,7 +72,7 @@ Each feature has a `--[no-]<flag>` form. Passing `--feature` enables it; `--no-f
 | `--[no-]search` | Pagefind full-text search | on |
 | `--[no-]sidebar-filter` | Real-time sidebar filter | on |
 | `--[no-]image-enlarge` | Click-to-enlarge for oversized images | on |
-| `--[no-]tag-governance` | Vocabulary-aware tag audit + suggest scripts | on |
+| `--[no-]tag-governance` | Vocabulary-aware tag audit + suggest scripts | off |
 | `--[no-]claude-resources` | Auto-generate Claude Code docs (`CLAUDE.md`, `llms.txt`) | 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 |
@@ -86,7 +86,8 @@ Each feature has a `--[no-]<flag>` form. Passing `--feature` enables it; `--no-f
 | `--[no-]tauri` | Tauri desktop app — Mode 1 offline reader | off |
 | `--[no-]tauri-dev` | Tauri dev wrapper — Mode 2 configurable dev wrapper | off |
 | `--[no-]footer-nav-group` | Navigation links in the footer | off |
-| `--[no-]footer-copyright` | Copyright notice in the footer | off |
+| `--[no-]dynamic-page-transition` | SPA-style page transition with history handling | on |
+| `--[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 |
 

package/dist/api.d.ts

@@ -9,6 +9,8 @@ export interface CreateOptions {
     darkScheme?: string;
     respectPrefersColorScheme?: boolean;
     defaultMode?: "light" | "dark";
+    /** Theme pack slug (ADR #2818 Decision 7), validated against THEME_PACKS. Default: "default". */
+    themePack?: string;
     features: string[];
     /** GitHub repository URL — drives the header GitHub link and body-foot
      *  "View source on GitHub" link. Empty = disabled. */

package/dist/api.js

@@ -1,5 +1,5 @@
 import path from "path";
-import { SINGLE_SCHEMES } from "./constants.js";
+import { SINGLE_SCHEMES, THEME_PACKS } from "./constants.js";
 import { scaffold } from "./scaffold.js";
 import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
 export async function createZudoDoc(options) {
@@ -22,6 +22,14 @@ export async function createZudoDoc(options) {
             throw new Error(`Unknown ${label} "${value}"`);
         }
     }
+    // Validate the theme pack slug like the CLI (cli.ts) and preset (preset.ts)
+    // paths do (ADR #2818 Decision 7 / #2823 codex-review follow-up) — an
+    // unvalidated slug here would be written verbatim into zfb.config.ts and
+    // only fail when the generated site's build reaches plugin setup.
+    if (rest.themePack && !THEME_PACKS.some((t) => t.slug === rest.themePack)) {
+        const catalog = THEME_PACKS.map((t) => t.slug).join(", ");
+        throw new Error(`Unknown theme pack "${rest.themePack}". Available: ${catalog}`);
+    }
     const choices = { ...rest, defaultLang: rest.defaultLang ?? "en" };
     await scaffold(choices);
     const targetDir = path.resolve(process.cwd(), choices.projectName);

package/dist/claude-md-gen.js

@@ -21,7 +21,7 @@ export function generateCLAUDEFile(choices) {
     lines.push(`- **MDX** — content format, authored under \`src/content/\``);
     lines.push(`- **Tailwind CSS v4** — via \`@tailwindcss/vite\``);
     lines.push(`- **Preact** — for interactive islands only (with compat mode for React API)`);
-    lines.push(`- **syntect** — built-in code highlighting, run by zfb's Rust pipeline at build time (dual light/dark theme, follows the site's color-mode toggle)`);
+    lines.push(`- **Shiki** — package-owned code highlighting with the configured light/dark theme pair`);
     lines.push(`- **@takazudo/zudo-doc** — the package that owns everything: layout, chrome, islands, default \`@theme\` design tokens, and (via \`packageOwnedRoutes\`, on by default) the doc routes themselves`);
     lines.push(``);
     // Commands
@@ -45,6 +45,7 @@ export function generateCLAUDEFile(choices) {
         lines.push(`  [locale]/docs/[[...slug]].tsx  # same, for non-default locales`);
     }
     lines.push(`src/`);
+    lines.push(`├── chrome-bindings.tsx   # optional typed primary chrome / named header / MDX bindings`);
     lines.push(`├── content/`);
     lines.push(`│   └── docs/             # MDX content (this project's showcase docs)`);
     if (choices.features.includes("i18n")) {
@@ -55,7 +56,7 @@ export function generateCLAUDEFile(choices) {
     lines.push(`    └── global.css        # @import chain + a token-override slot — that's it`);
     lines.push("```");
     lines.push(``);
-    lines.push(`Everything else — layout, header, sidebar, footer, doc chrome, islands, and the default design tokens — lives in \`node_modules/@takazudo/zudo-doc\`. To customize a specific piece, use the eject CLI: \`npx zudo-doc eject <component>\` copies one package component into this project so you can edit it (see \`@takazudo/zudo-doc\`'s eject-contract docs). Settings you didn't set explicitly in \`zfb.config.ts\` use the package's documented defaults — hover \`zudoDoc\`'s \`ZudoDocConfig\` argument in your editor to see every field and its \`@default\`.`);
+    lines.push(`Everything else — layout, header, sidebar, footer, doc chrome, islands, and the default design tokens — lives in \`node_modules/@takazudo/zudo-doc\`. For supported markup replacement, create \`src/chrome-bindings.tsx\` with \`defineChromeBindings\`, set \`chromeBindingsModule\`, and use the primary \`Header\` / \`Footer\` / \`Sidebar\` / \`Toc\` / \`Breadcrumb\` / \`DocPager\` slots or the named \`headerRightComponents\` registry. The generated default, locale, and doc-history route shapes already consume the same binding object; do not fork a route stub for presentational customization. \`npx zudo-doc eject <component>\` only copies source: heed its primary, nested-chrome, or content-layer remediation before expecting the copy to render. Settings you didn't set explicitly in \`zfb.config.ts\` use the package's documented defaults — hover \`zudoDoc\`'s \`ZudoDocConfig\` argument in your editor to see every field and its \`@default\`.`);
     lines.push(``);
     // Content conventions
     lines.push(`## Content Conventions`);

package/dist/cli.d.ts

@@ -7,6 +7,8 @@ export interface CliArgs {
     darkScheme?: string;
     defaultMode?: "light" | "dark";
     respectSystemPreference?: boolean;
+    /** Theme pack slug (ADR #2818 Decision 7). Validated against THEME_PACKS. */
+    themePack?: string;
     i18n?: boolean;
     search?: boolean;
     sidebarFilter?: boolean;

package/dist/cli.js

@@ -1,6 +1,6 @@
 import minimist from "minimist";
 import pc from "picocolors";
-import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS } from "./constants.js";
+import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
 import { validateProjectName } from "./utils.js";
 export function parseArgs(argv = process.argv.slice(2)) {
     const raw = minimist(argv, {
@@ -12,6 +12,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
             "light-scheme",
             "dark-scheme",
             "default-mode",
+            "theme-pack",
             "github-url",
             "preset",
             "pm",
@@ -49,6 +50,8 @@ export function parseArgs(argv = process.argv.slice(2)) {
         args.darkScheme = raw["dark-scheme"];
     if (raw["default-mode"])
         args.defaultMode = raw["default-mode"];
+    if (raw["theme-pack"])
+        args.themePack = raw["theme-pack"];
     if (raw.preset)
         args.preset = raw.preset;
     if (raw.pm)
@@ -77,6 +80,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
 }
 export function printHelp() {
     const langList = SUPPORTED_LANGS.map((l) => l.value).join(", ");
+    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]
@@ -92,6 +96,8 @@ ${pc.bold("Options:")}
   --default-mode <mode>        light | dark (light-dark mode)
   --[no-]respect-system-preference
                                Respect OS color scheme preference
+  --theme-pack <slug>          Theme pack (${themePackList})
+                               Default: default
 ${featureHelp}
   --github-url <url>           GitHub repository URL (drives header link + source link)
   --preset <path>              Load settings from a JSON preset file (use "-" for stdin)
@@ -135,6 +141,10 @@ export function validateArgs(args) {
     if (args.defaultMode && !["light", "dark"].includes(args.defaultMode)) {
         return `Invalid default-mode "${args.defaultMode}". Must be "light" or "dark"`;
     }
+    if (args.themePack && !THEME_PACKS.some((t) => t.slug === args.themePack)) {
+        const catalog = THEME_PACKS.map((t) => t.slug).join(", ");
+        return `Unknown theme pack "${args.themePack}". Available: ${catalog}`;
+    }
     if (args.pm && !["pnpm", "npm", "yarn", "bun"].includes(args.pm)) {
         return `Invalid package manager "${args.pm}". Must be pnpm, npm, yarn, or bun`;
     }

package/dist/constants.d.ts

@@ -11,6 +11,12 @@ export interface SupportedLang {
     label: string;
 }
 export declare const SUPPORTED_LANGS: SupportedLang[];
+export interface ThemePackOption {
+    slug: string;
+    label: string;
+    hint: string;
+}
+export declare const THEME_PACKS: ThemePackOption[];
 export interface Feature {
     value: string;
     label: string;

package/dist/constants.js

@@ -18,6 +18,121 @@ export const SUPPORTED_LANGS = [
     { value: "de", label: "German" },
     { value: "pt", label: "Portuguese" },
 ];
+// Hand-kept mirror of the bundled theme-pack registry
+// (packages/zudo-doc/src/theme-packs/<slug>/meta.json — theme pack ADR
+// #2818, census landed by #2819, full catalog synced by the Finalize epic's
+// catalog-sync sub-issue #2855). Same convention as DEFAULT_MIRROR in
+// zfb-config-gen.ts: create-zudo-doc cannot import @takazudo/zudo-doc at
+// generator-build time, so the CLI/prompt catalog is a local copy. Order
+// mirrors the package's own default enablement order (resolveEnabledPacks):
+// "default" first, then the rest alphabetically by slug.
+export const THEME_PACKS = [
+    {
+        slug: "default",
+        label: "Default",
+        hint: "Stock zudo-doc look — no extra stylesheet loaded",
+    },
+    {
+        slug: "beacon",
+        label: "Beacon",
+        hint: "WCAG-AAA high contrast — 7:1+ ink, 3px focus rings, always-underlined links",
+    },
+    {
+        slug: "broadsheet",
+        label: "Broadsheet",
+        hint: "Newspaper editorial — Playfair masthead, Oxford ink rules, a red drop cap",
+    },
+    {
+        slug: "brutalist",
+        label: "Brutalist",
+        hint: "Raw concrete web — stark black on white, 4px slab borders, hazard-orange tape",
+    },
+    {
+        slug: "drift",
+        label: "Drift",
+        hint: "Floaty slate-blue comfort dark for long reading, relaxed Plex type",
+    },
+    {
+        slug: "fjord",
+        label: "Fjord",
+        hint: "Polar-night blue under a faint aurora — frost-cyan accents, icy borders",
+    },
+    {
+        slug: "foundry",
+        label: "Foundry",
+        hint: "GitHub-neutral baseline — white paper, Primer-blue accents",
+    },
+    {
+        slug: "futura-editorial",
+        label: "Futura Editorial",
+        hint: "Geometric Futura headings over Noto Sans body, one restrained red accent",
+    },
+    {
+        slug: "hearth",
+        label: "Hearth",
+        hint: "Warm cream & brick-red fireside docs — Fraunces headings, ember-glow dark mode",
+    },
+    {
+        slug: "hollow",
+        label: "Hollow",
+        hint: "Dark violet space — neon pink headings, violet links, a quiet starfield",
+    },
+    {
+        slug: "ledger",
+        label: "Ledger",
+        hint: "Cream academic serif in the Tufte tradition — warm paper, oxblood links",
+    },
+    {
+        slug: "manuscript",
+        label: "Manuscript",
+        hint: "A quiet Garamond book page — warm paper, soft ink, sepia rubrication",
+    },
+    {
+        slug: "matcha",
+        label: "Matcha",
+        hint: "Green tea ceremony — deep matcha on warm cream, mincho headings, zen whitespace",
+    },
+    {
+        slug: "nocturne",
+        label: "Nocturne",
+        hint: "Purple midnight — velvet aubergine depths, lavender links, muted gold hairlines",
+    },
+    {
+        slug: "observatory",
+        label: "Observatory",
+        hint: "Night-sky atlas — star-field depth, nebula violet and comet gold over navy",
+    },
+    {
+        slug: "onyx",
+        label: "Onyx",
+        hint: "Luxury noir — jet black, champagne serif headings, a single gold hairline accent",
+    },
+    {
+        slug: "phosphor",
+        label: "Phosphor",
+        hint: "Green CRT terminal — phosphor glow, scanlines, inverse-video nav",
+    },
+    {
+        slug: "solar",
+        label: "Solar",
+        hint: "Solarized precision — low-eyestrain paper tones, blue/cyan/orange accents",
+    },
+    {
+        slug: "sumi",
+        label: "Sumi",
+        hint: "Sumi-e ink on washi — bold mincho brush headings, one vermillion hanko seal accent",
+    },
+    {
+        slug: "swissgrid",
+        label: "Swissgrid",
+        hint: "International Typographic Style — grid discipline, one hot Swiss-red accent",
+    },
+    {
+        slug: "washi",
+        label: "Washi",
+        hint: "Warm washi paper, sumi ink, and ai-iro indigo seals for calm documentation",
+    },
+];
 export const FEATURES = [
     {
         value: "i18n",
@@ -61,6 +176,13 @@ export const FEATURES = [
         default: false,
         cliFlag: "design-token-panel",
     },
+    {
+        value: "themePackSwitcher",
+        label: "Theme pack switcher",
+        hint: "Bottom-right flyout to switch between installed theme packs",
+        default: false,
+        cliFlag: "theme-pack-switcher",
+    },
     {
         value: "sidebarResizer",
         label: "Sidebar resizer",
@@ -149,7 +271,7 @@ export const FEATURES = [
         value: "footerCopyright",
         label: "Footer copyright",
         hint: "Copyright notice in the footer",
-        default: false,
+        default: true,
         cliFlag: "footer-copyright",
     },
     {

package/dist/features/claude-resources.d.ts

@@ -4,11 +4,8 @@ import type { FeatureModule } from "../compose.js";
  *
  * Fully plugin-owned (`@takazudo/zudo-doc/plugins/claude-resources`,
  * `zudoDocPreset()` wires it whenever `settings.claudeResources` is
- * truthy). The old `src/integrations/claude-resources/*` host copy
- * (escape-for-mdx.ts / generate.ts + tests) was a pre-package-first
- * duplicate implementation nothing imported — deleted in the minimal-scaffold
- * cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660). This feature's touch
- * points are now just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
+ * truthy). Generation is package-owned. This feature's touch points are now
+ * just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
  * (`zfb-config-gen.ts`).
  */
 export declare const claudeResourcesFeature: FeatureModule;

package/dist/features/claude-resources.js

@@ -3,11 +3,8 @@
  *
  * Fully plugin-owned (`@takazudo/zudo-doc/plugins/claude-resources`,
  * `zudoDocPreset()` wires it whenever `settings.claudeResources` is
- * truthy). The old `src/integrations/claude-resources/*` host copy
- * (escape-for-mdx.ts / generate.ts + tests) was a pre-package-first
- * duplicate implementation nothing imported — deleted in the minimal-scaffold
- * cutover (epic zudolab/zudo-doc#2651, Wave 6 #2660). This feature's touch
- * points are now just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
+ * truthy). Generation is package-owned. This feature's touch points are now
+ * just: `claudeResources` + `defaultLocaleOnlyPrefixes` fields
  * (`zfb-config-gen.ts`).
  */
 export const claudeResourcesFeature = () => ({

package/dist/features/doc-history.d.ts

@@ -12,13 +12,14 @@ import type { FeatureModule } from "../compose.js";
  *
  * What's left to wire: the self-contained doc-route stub(s)
  * (`pages/docs/[[...slug]].tsx`, and its i18n locale sibling when i18n is
- * also selected) call `createChrome(routeCtx)` with NO hostBindings — unlike
+ * also selected) always thread the host's `chromeBindings`. Unlike
  * `DesignTokenPanelBootstrap` (auto-defaulted at the chrome-derive seam,
  * #2658 gate-2 fix), `DocHistory`'s derive-level default is a deliberate
  * no-op stub (see `routes/_chrome.tsx`'s comment on why — its own island
  * needs the REAL host binding to hydrate). So when docHistory is selected,
  * this feature patches the stub(s) to statically import the real
- * `DocHistory` component and thread it through — the same #2480 chain
- * `routes/_chrome.tsx` uses for the package's own routes.
+ * `DocHistory` component and merge it over those bindings — preserving every
+ * configured host slot while maintaining the same #2480 scanner-reachability
+ * chain `routes/_chrome.tsx` uses for the package's own routes.
  */
 export declare const docHistoryFeature: FeatureModule;

package/dist/features/doc-history.js

@@ -13,14 +13,15 @@ import path from "path";
  *
  * What's left to wire: the self-contained doc-route stub(s)
  * (`pages/docs/[[...slug]].tsx`, and its i18n locale sibling when i18n is
- * also selected) call `createChrome(routeCtx)` with NO hostBindings — unlike
+ * also selected) always thread the host's `chromeBindings`. Unlike
  * `DesignTokenPanelBootstrap` (auto-defaulted at the chrome-derive seam,
  * #2658 gate-2 fix), `DocHistory`'s derive-level default is a deliberate
  * no-op stub (see `routes/_chrome.tsx`'s comment on why — its own island
  * needs the REAL host binding to hydrate). So when docHistory is selected,
  * this feature patches the stub(s) to statically import the real
- * `DocHistory` component and thread it through — the same #2480 chain
- * `routes/_chrome.tsx` uses for the package's own routes.
+ * `DocHistory` component and merge it over those bindings — preserving every
+ * configured host slot while maintaining the same #2480 scanner-reachability
+ * chain `routes/_chrome.tsx` uses for the package's own routes.
  */
 export const docHistoryFeature = () => ({
     name: "docHistory",
@@ -45,7 +46,10 @@ export const docHistoryFeature = () => ({
             content = content.replace(`import { createChrome } from "@takazudo/zudo-doc/chrome";`, `import { createChrome } from "@takazudo/zudo-doc/chrome";
 ${importMarker}
 import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";`);
-            content = content.replace(`const { renderDocPage } = createChrome(routeCtx);`, `const { renderDocPage } = createChrome(routeCtx, defineChromeBindings({ DocHistory }));`);
+            content = content.replace(`const { renderDocPage } = createChrome(routeCtx, chromeBindings);`, `const { renderDocPage } = createChrome(routeCtx, {
+  ...chromeBindings,
+  ...defineChromeBindings({ DocHistory }),
+});`);
             await fs.writeFile(stubPath, content);
         }
     },

package/dist/features/index.js

@@ -14,6 +14,7 @@ import { docHistoryFeature } from "./doc-history.js";
 import { llmsTxtFeature } from "./llms-txt.js";
 import { claudeResourcesFeature } from "./claude-resources.js";
 import { designTokenPanelFeature } from "./design-token-panel.js";
+import { themePackSwitcherFeature } from "./theme-pack-switcher.js";
 import { i18nFeature } from "./i18n.js";
 import { versioningFeature } from "./versioning.js";
 import { tauriFeature } from "./tauri.js";
@@ -35,6 +36,7 @@ export const featureModules = {
     // sidebarFilter — built into sidebar-tree.tsx, stays in base
     claudeResources: claudeResourcesFeature,
     designTokenPanel: designTokenPanelFeature,
+    themePackSwitcher: themePackSwitcherFeature,
     sidebarResizer: sidebarResizerFeature,
     sidebarToggle: sidebarToggleFeature,
     versioning: versioningFeature,

package/dist/features/tag-governance.d.ts

@@ -2,20 +2,8 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Tag governance feature.
  *
- * Ships `scripts/tags-audit.ts` / `scripts/tags-suggest.ts` (unconditional
- * feature-file copy, `templates/features/tagGovernance/files/`) plus the
- * settings fields (`tagGovernance`, `tagVocabulary`, `tagVocabularyEntries`)
- * `zfb-config-gen.ts` writes straight into `zfb.config.ts`.
- *
- * One genuine remaining coupling (minimal-scaffold cutover, epic
- * zudolab/zudo-doc#2651): `@takazudo/zudo-doc`'s `tags-audit` bin
- * (`packages/zudo-doc/bin/tags-audit-runner.ts`) still dynamically
- * `import()`s `src/config/settings.ts` and `src/config/tag-vocabulary.ts`
- * BY PATH — a legacy contract that predates the single-`zfb.config.ts`
- * model and hasn't been updated for it (out of this generator's scope; a
- * package-level follow-up could remove it). So `tagGovernance` is the one
- * feature that still needs a tiny `src/config/` pair — this postProcess
- * writes both, sourced from the SAME `choices` the main `zfb.config.ts`
- * generation reads, so the two can't drift.
+ * Writes one project-owned tag vocabulary module. Its named vocabulary export
+ * feeds zfb while its default TagCliConfig export feeds both package-owned
+ * bins through an explicit `--config` package-script argument.
  */
 export declare const tagGovernanceFeature: FeatureModule;

package/dist/features/tag-governance.js

@@ -4,21 +4,9 @@ import { getSecondaryLang } from "../utils.js";
 /**
  * Tag governance feature.
  *
- * Ships `scripts/tags-audit.ts` / `scripts/tags-suggest.ts` (unconditional
- * feature-file copy, `templates/features/tagGovernance/files/`) plus the
- * settings fields (`tagGovernance`, `tagVocabulary`, `tagVocabularyEntries`)
- * `zfb-config-gen.ts` writes straight into `zfb.config.ts`.
- *
- * One genuine remaining coupling (minimal-scaffold cutover, epic
- * zudolab/zudo-doc#2651): `@takazudo/zudo-doc`'s `tags-audit` bin
- * (`packages/zudo-doc/bin/tags-audit-runner.ts`) still dynamically
- * `import()`s `src/config/settings.ts` and `src/config/tag-vocabulary.ts`
- * BY PATH — a legacy contract that predates the single-`zfb.config.ts`
- * model and hasn't been updated for it (out of this generator's scope; a
- * package-level follow-up could remove it). So `tagGovernance` is the one
- * feature that still needs a tiny `src/config/` pair — this postProcess
- * writes both, sourced from the SAME `choices` the main `zfb.config.ts`
- * generation reads, so the two can't drift.
+ * Writes one project-owned tag vocabulary module. Its named vocabulary export
+ * feeds zfb while its default TagCliConfig export feeds both package-owned
+ * bins through an explicit `--config` package-script argument.
  */
 export const tagGovernanceFeature = (choices) => ({
     name: "tagGovernance",
@@ -26,34 +14,30 @@ export const tagGovernanceFeature = (choices) => ({
     postProcess: async (targetDir) => {
         const vocabPath = path.join(targetDir, "src/config/tag-vocabulary.ts");
         if (!(await fs.pathExists(vocabPath))) {
-            await fs.outputFile(vocabPath, `import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
+            const contentDirs = choices.features.includes("i18n")
+                ? `[
+  "src/content/docs",
+  "src/content/docs-${getSecondaryLang(choices.defaultLang)}",
+]`
+                : `["src/content/docs"]`;
+            await fs.outputFile(vocabPath, `import type { TagCliConfig } from "@takazudo/zudo-doc/tags-audit";
+import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
 
 // Starter (empty) tag vocabulary — add an entry per tag you use in doc
-// frontmatter so \`pnpm tags:audit\` can validate it. Shared by
-// zfb.config.ts (tagVocabularyEntries) and scripts/tags-audit.ts /
-// scripts/tags-suggest.ts — this file is the single source of truth.
+// frontmatter so \`pnpm tags:audit\` can validate it. This named export is
+// also consumed by zfb.config.ts as tagVocabularyEntries.
 export const tagVocabulary: TagVocabularyEntry[] = [];
-`);
-        }
-        const settingsPath = path.join(targetDir, "src/config/settings.ts");
-        if (!(await fs.pathExists(settingsPath))) {
-            const locales = choices.features.includes("i18n")
-                ? `{ ${getSecondaryLang(choices.defaultLang)}: { dir: "src/content/docs-${getSecondaryLang(choices.defaultLang)}" } }`
-                : `{}`;
-            await fs.outputFile(settingsPath, `// Minimal settings mirror consumed ONLY by @takazudo/zudo-doc's
-// tags-audit bin (packages/zudo-doc/bin/tags-audit-runner.ts), which
-// dynamically imports this exact path — a legacy coupling that predates the
-// single zfb.config.ts model (see the tagGovernance feature module for the
-// full note). Keep these four fields in sync with the matching zudoDoc({...})
-// fields in zfb.config.ts — both are generated from the same choices at
-// scaffold time, so a fresh scaffold never drifts; hand-edit both if you
-// change either one later.
-export const settings = {
-  docsDir: "src/content/docs",
-  tagGovernance: "warn" as const,
-  tagVocabulary: true,
-  locales: ${locales},
-};
+
+// Package scripts pass this module to the package-owned audit/suggest bins.
+// Paths are resolved from the project root.
+const tagCliConfig = {
+  contentDirs: ${contentDirs},
+  vocabulary: tagVocabulary,
+  governance: "warn",
+  vocabularyActive: true,
+} satisfies TagCliConfig;
+
+export default tagCliConfig;
 `);
         }
     },

package/dist/features/theme-pack-switcher.d.ts

@@ -0,0 +1,11 @@
+import type { FeatureModule } from "../compose.js";
+/**
+ * themePackSwitcher feature (theme pack ADR #2818).
+ *
+ * Purely a `zudoDoc({ themePackSwitcher: true })` field (see
+ * `zfb-config-gen.ts`) — the bottom-right switcher flyout and its browse-all
+ * dialog are PACKAGE-INJECTED (`@takazudo/zudo-doc`'s theme-pack-provider /
+ * theme-pack-sync + the flyout/dialog islands), gated on
+ * `settings.themePackSwitcher`. There is nothing to copy or postProcess.
+ */
+export declare const themePackSwitcherFeature: FeatureModule;

package/dist/features/theme-pack-switcher.js

@@ -0,0 +1,13 @@
+/**
+ * themePackSwitcher feature (theme pack ADR #2818).
+ *
+ * Purely a `zudoDoc({ themePackSwitcher: true })` field (see
+ * `zfb-config-gen.ts`) — the bottom-right switcher flyout and its browse-all
+ * dialog are PACKAGE-INJECTED (`@takazudo/zudo-doc`'s theme-pack-provider /
+ * theme-pack-sync + the flyout/dialog islands), gated on
+ * `settings.themePackSwitcher`. There is nothing to copy or postProcess.
+ */
+export const themePackSwitcherFeature = () => ({
+    name: "themePackSwitcher",
+    injections: [],
+});

package/dist/index.js

@@ -55,6 +55,8 @@ async function main() {
     if (args.respectSystemPreference !== undefined) {
         prefilled.respectPrefersColorScheme = args.respectSystemPreference;
     }
+    if (args.themePack)
+        prefilled.themePack = args.themePack;
     if (args.pm)
         prefilled.packageManager = args.pm;
     if (args.githubUrl !== undefined)
@@ -91,6 +93,7 @@ async function main() {
         else {
             prefilled.singleScheme ??= "Default Dark";
         }
+        prefilled.themePack ??= "default";
         prefilled.packageManager ??= "pnpm";
         prefilled.githubUrl ??= "";
         // For features: set defaults for any not explicitly specified

package/dist/preset.d.ts

@@ -35,6 +35,8 @@ export interface PresetJson {
     darkScheme?: string;
     defaultMode?: "light" | "dark";
     respectPrefersColorScheme?: boolean;
+    /** Theme pack slug (ADR #2818 Decision 7), validated against THEME_PACKS. */
+    themePack?: string;
     features?: string[];
     githubUrl?: string;
     cjkFriendly?: boolean;

package/dist/preset.js

@@ -1,5 +1,5 @@
 import fs from "fs";
-import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS } from "./constants.js";
+import { FEATURES, SINGLE_SCHEMES, SUPPORTED_LANGS, THEME_PACKS } from "./constants.js";
 import { validateProjectName } from "./utils.js";
 const VALID_HEADER_RIGHT_COMPONENTS = new Set([
     "theme-toggle",
@@ -30,6 +30,7 @@ export function loadPreset(pathOrStdin) {
 const VALID_LANGS = new Set(SUPPORTED_LANGS.map((l) => l.value));
 const VALID_SCHEMES = new Set(SINGLE_SCHEMES);
 const VALID_PMS = new Set(["pnpm", "npm", "yarn", "bun"]);
+const VALID_THEME_PACKS = new Set(THEME_PACKS.map((t) => t.slug));
 export function validatePreset(json) {
     if (json === null || typeof json !== "object" || Array.isArray(json)) {
         return "Preset must be a JSON object";
@@ -66,6 +67,14 @@ export function validatePreset(json) {
     if (p.defaultMode && !["light", "dark"].includes(p.defaultMode)) {
         return `Invalid defaultMode "${p.defaultMode}" in preset`;
     }
+    if (p.themePack !== undefined) {
+        if (typeof p.themePack !== "string") {
+            return `"themePack" must be a string in preset`;
+        }
+        if (!VALID_THEME_PACKS.has(p.themePack)) {
+            return `Unknown theme pack "${p.themePack}" in preset. Available: ${[...VALID_THEME_PACKS].join(", ")}`;
+        }
+    }
     if (p.packageManager && !VALID_PMS.has(p.packageManager)) {
         return `Invalid packageManager "${p.packageManager}" in preset`;
     }
@@ -174,6 +183,8 @@ export function presetToChoices(json) {
     if (json.respectPrefersColorScheme !== undefined) {
         choices.respectPrefersColorScheme = json.respectPrefersColorScheme;
     }
+    if (json.themePack)
+        choices.themePack = json.themePack;
     if (json.packageManager)
         choices.packageManager = json.packageManager;
     if (json.githubUrl !== undefined)

package/dist/prompts.d.ts

@@ -8,6 +8,7 @@ export interface UserChoices {
     darkScheme?: string;
     respectPrefersColorScheme?: boolean;
     defaultMode?: "light" | "dark";
+    themePack?: string;
     features: string[];
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;
@@ -26,6 +27,7 @@ export interface PartialChoices {
     darkScheme?: string;
     respectPrefersColorScheme?: boolean;
     defaultMode?: "light" | "dark";
+    themePack?: string;
     features?: Partial<Record<string, boolean>>;
     explicitlyDisabledFeatures?: string[];
     githubUrl?: string;