create-zudo-doc 0.2.0-next.7 → 0.2.0-next.8

package/dist/scaffold.js

@@ -273,7 +273,7 @@ function generatePackageJson(choices) {
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
         // version moves, so a fresh scaffold pulls the version we just published.
-        "@takazudo/zudo-doc": "^0.2.0-next.7",
+        "@takazudo/zudo-doc": "^0.2.0-next.8",
         // zod — used by the generated zfb.config.ts. zfb-config-gen emits
         // `import { z } from "zod"` for the content-collection schema +
         // `z.toJSONSchema(...)` conversion. Without this dep, the consumer
@@ -331,7 +331,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^0.2.0-next.7";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.0-next.8";
         // W7A (#1736): doc-history-plugin.mjs spawns `tsx -e <inline-script>` to
         // run the v2 runtime in a TS-aware Node subprocess; without tsx the
         // plugin's preBuild step exits with ENOENT before zfb finishes config

package/dist/zfb-config-gen.js

@@ -71,6 +71,8 @@ export function generateZfbConfig(choices) {
     lines.push(`    standalone: z.boolean().optional(),`);
     lines.push(`    slug: z.string().optional(),`);
     lines.push(`    generated: z.boolean().optional(),`);
+    lines.push(`    category_no_page: z.boolean().optional(),`);
+    lines.push(`    category_sort_order: z.enum(["asc", "desc"]).optional(),`);
     lines.push(`  })`);
     lines.push(`  .passthrough();`);
     lines.push(``);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "0.2.0-next.7",
+  "version": "0.2.0-next.8",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/docs/[[...slug]].tsx

@@ -90,6 +90,11 @@ export function paths(): Array<{
 
   // Regular doc pages
   for (const entry of docs) {
+    // A `category_no_page` index.mdx carries category metadata only — keep it
+    // in the nav tree (built above, used for breadcrumbs) but emit NO route for
+    // it. zfb's walker retains every .mdx as a collection entry, so without
+    // this explicit skip the metadata file would silently add a route.
+    if (entry.data.category_no_page === true) continue;
     const slug = entry.data.slug ?? toRouteSlug(entry.slug);
     const navSection = getNavSectionForSlug(slug);
     const subtree = getNavSubtree(tree, navSection);

package/templates/base/pages/index.tsx

@@ -46,8 +46,10 @@ export default function IndexPage(): JSX.Element {
   const categoryOrder = getCategoryOrder();
   const groupedTree = groupSatelliteNodes(tree, categoryOrder);
 
+  // Drop category_no_page index files so the count matches the number of tag
+  // pages actually built (the tag routes exclude them too).
   const tagCount = collectTags(
-    navDocs,
+    navDocs.filter((d) => !d.data.category_no_page),
     (id, data) => data.slug ?? toRouteSlug(id),
   ).size;
 

package/templates/base/pages/lib/_category-nav.tsx

@@ -21,9 +21,9 @@ import type { NavNode as V2NavNode } from "@takazudo/zudo-doc/nav-indexing/types
 import {
   buildNavTree,
   findNode,
+  firstRoutedHref,
 } from "@/utils/docs";
 import { defaultLocale, type Locale } from "@/config/i18n";
-import { docsUrl } from "@/utils/base";
 import { resolveNavSource } from "./_nav-source-docs";
 
 export interface CategoryNavWrapperProps {
@@ -39,8 +39,9 @@ export interface CategoryNavWrapperProps {
    * of "claude", not children). Each slug is resolved to its nav node; nodes
    * not found in the tree are silently skipped.
    *
-   * For nodes with noPage=true (no index.mdx), the href falls back to the
-   * auto-generated category index URL via docsUrl(slug, lang).
+   * A `category_no_page` category has no route of its own, so its card links to
+   * the first routed descendant page (via firstRoutedHref); categories with no
+   * reachable page are skipped rather than emitting a dead link.
    */
   categories?: string[];
   /**
@@ -61,8 +62,8 @@ export interface CategoryNavWrapperProps {
  * - `categories`: resolves an explicit list of top-level slugs as cards.
  *   Use this when the target categories are siblings in the nav tree rather
  *   than children of a common parent (e.g. claude-md / claude-skills are
- *   top-level peers of claude, not children of it). Nodes with noPage=true
- *   get their href computed via docsUrl() since auto-index pages exist.
+ *   top-level peers of claude, not children of it). A noPage category card
+ *   links to its first routed descendant page (it has no route of its own).
  *
  * Returns null when no visible children are resolved.
  */
@@ -85,14 +86,17 @@ export function CategoryNavWrapper({
   let children: V2NavNode[];
 
   if (categories !== undefined) {
-    // Explicit slug list mode: resolve each slug to its nav node and build
-    // a card for it. noPage nodes have no href in the tree but their
-    // auto-generated category index page is reachable via docsUrl().
+    // Explicit slug list mode: resolve each slug to its nav node and build a
+    // card for it. A `category_no_page` category has no route of its own
+    // (collectAutoIndexNodes skips noPage nodes), so its card links to the
+    // first routed descendant page; categories with no reachable page are
+    // skipped rather than emitting a dead link.
     children = categories
       .map((slug): V2NavNode | null => {
         const node = findNode(tree, slug);
         if (!node) return null;
-        const href = node.href ?? docsUrl(slug, locale);
+        const href = node.href ?? firstRoutedHref(node);
+        if (!href) return null;
         return {
           label: node.label,
           description: node.description,

package/templates/base/pages/lib/_doc-history-area.tsx

@@ -67,6 +67,17 @@ interface DocHistoryAreaProps {
    * view-source GitHub URL. Omit to suppress the view-source link.
    */
   contentDir?: string;
+  /**
+   * True when this locale page falls back to the base EN collection
+   * (i.e. the slug has no translation for the active locale). When true,
+   * the history data-path derivations use defaultLocale so the island
+   * fetches the correct bare-slug JSON and the SSR manifest lookup hits
+   * the bare key — both of which only exist for EN-origin files.
+   * Display labels (t() calls) still use the active locale so JA users
+   * see JA labels on fallback pages. Omit (or false) for translated pages
+   * and all other call sites (EN route, tag pages) — behavior unchanged.
+   */
+  isFallback?: boolean;
 }
 
 /**
@@ -93,6 +104,7 @@ export function DocHistoryArea({
   locale,
   entrySlug,
   contentDir,
+  isFallback,
 }: DocHistoryAreaProps): VNode | null {
   if (!settings.docHistory) return null;
 
@@ -106,11 +118,18 @@ export function DocHistoryArea({
   // collectContentFiles walk in packages/doc-history-server. (#1891)
   const historySlug = toHistorySlug(slug);
 
+  // On EN-fallback locale pages the history data exists only at the bare
+  // (non-locale-prefixed) path — the prebuild/server writes locale-prefixed
+  // keys/paths only for files physically present in the locale collection.
+  // Use defaultLocale for data lookups when isFallback is true; keep locale
+  // for all display label calls (t()) so JA users see JA labels.
+  const effectiveHistoryLocale = isFallback ? defaultLocale : locale;
+
   // Look up the build-time manifest entry for this page. The composedSlug
   // matches the key written by the prebuild step: bare slug for the default
   // locale, "<localeKey>/<slug>" for non-default locales.
   const composedSlug =
-    locale === defaultLocale ? historySlug : `${locale}/${historySlug}`;
+    effectiveHistoryLocale === defaultLocale ? historySlug : `${effectiveHistoryLocale}/${historySlug}`;
   type MetaEntry = { author: string; createdDate: string; updatedDate: string };
   const meta = (docHistoryMeta as Record<string, MetaEntry>)[composedSlug];
 
@@ -120,7 +139,8 @@ export function DocHistoryArea({
   const historyLabel = t("doc.history", locale);
 
   // Real-component props — locale omitted for the default locale.
-  const docHistoryLocale = locale === defaultLocale ? undefined : locale;
+  // Use effectiveHistoryLocale so fallback pages fetch the bare (non-ja/) path.
+  const docHistoryLocale = effectiveHistoryLocale === defaultLocale ? undefined : effectiveHistoryLocale;
   const docHistoryBasePath = settings.base ?? "/";
 
   // Build the SSR fallback with only the sr-only metadata block so the

package/templates/base/pages/lib/_footer-with-defaults.tsx

@@ -113,20 +113,26 @@ export function FooterWithDefaults({
     // Load docs synchronously (zfb ADR-004 — synchronous content snapshot).
     let docs: DocsEntry[];
     if (lang === defaultLocale) {
-      docs = loadDocs("docs").filter((d) => !d.data.draft && !d.data.unlisted);
+      // category_no_page index files build no route — drop them so the footer
+      // taglist matches the tag-route pages (which all now filter too).
+      docs = loadDocs("docs").filter(
+        (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
+      );
     } else {
       // Apply the default-locale-only filter so the footer taglist only counts
       // tags that have a locale-routable tag page — matching the tag-route
       // pages ([tag].tsx / tags/index.tsx) and enumerateTagsRoutes, which all
       // now filter. Without this, the footer would link to /{locale}/docs/tags/
       // pages that are never built for tags living only on default-locale-only
-      // prefix pages.
+      // prefix pages. category_no_page is dropped for the same reason — AFTER
+      // the merge, so a locale override carrying the flag first wins the merge
+      // (pre-merge filtering would let the unflagged base doc resurface).
       const result = mergeLocaleDocs({
         baseDocs: loadDocs("docs").filter((d) => !d.data.draft),
         localeDocs: loadDocs(`docs-${lang}`).filter((d) => !d.data.draft),
         applyDefaultLocaleOnlyFilter: true,
       });
-      docs = result.docs;
+      docs = result.docs.filter((d) => !d.data.category_no_page);
     }
 
     const tagMap = collectTags(

package/templates/base/pages/lib/_head-with-defaults.tsx

@@ -97,7 +97,10 @@ export function HeadWithDefaults({
       <OgTags
         title={composeMetaTitle(title)}
         description={description}
+        ogType="website"
+        ogUrl={canonical}
         ogImage={ogImageUrl}
+        ogSiteName={settings.siteName}
       />
       {/* og:image:width / og:image:height / og:image:alt — not in OgTags API;
           emitted here directly to avoid expanding the shared HeadProps surface.

package/templates/base/pages/lib/route-enumerators.ts

@@ -60,6 +60,10 @@ export function enumerateDocsRoutes(locale: string): string[] {
   const tree = buildNavTree(navDocs, locale as Locale, categoryMeta);
 
   for (const doc of allDocs) {
+    // A `category_no_page` index.mdx is metadata-only — no route, so no sitemap
+    // URL. Same exclusion the doc-route paths() apply (zfb retains every .mdx
+    // as a collection entry, so the skip must be explicit).
+    if (doc.data.category_no_page === true) continue;
     // Canonical route slug via the one shared rule (@/utils/slug). `doc.id` is
     // already `toRouteSlug(doc.slug)` (bridged through stripIndexSuffix in
     // pages/_data.ts), so a bare root index.mdx is "" here → `/docs/` — the
@@ -100,17 +104,24 @@ export function enumerateTagsRoutes(locale: string): string[] {
   urls.push(withBase(tagsBase));
 
   // Collect tags from the same merged doc set the tag pages use.
-  // Filter unlisted + draft — mirrors the tag [tag].tsx pages which do the same.
+  // Filter unlisted + draft + category_no_page — mirrors the tag [tag].tsx
+  // pages so the sitemap lists exactly the tag pages that get built (a
+  // category_no_page index has no route, so a tag it carries must not coin a
+  // tag page that links back to it). The category_no_page drop happens AFTER
+  // the locale merge so a locale override carrying the flag first wins the
+  // merge — pre-merge filtering would let the unflagged base doc resurface.
   let docs: DocsEntry[];
   if (locale === defaultLocale) {
-    docs = loadDocs("docs").filter((d) => !d.data.unlisted && !d.data.draft);
+    docs = loadDocs("docs").filter(
+      (d) => !d.data.unlisted && !d.data.draft && !d.data.category_no_page,
+    );
   } else {
     const result = mergeLocaleDocs({
       baseDocs: loadDocs("docs").filter((d) => !d.data.draft),
       localeDocs: loadDocs(`docs-${locale}`).filter((d) => !d.data.draft),
       applyDefaultLocaleOnlyFilter: true,
     });
-    docs = result.docs;
+    docs = result.docs.filter((d) => !d.data.category_no_page);
   }
 
   const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
@@ -157,6 +168,8 @@ export function enumerateVersionedRoutes(
     const tree = buildNavTree(navDocs, "en", categoryMeta);
 
     for (const doc of allDocs) {
+      // category_no_page index.mdx → no route, no sitemap URL (see paths()).
+      if (doc.data.category_no_page === true) continue;
       const slug = doc.data.slug ?? toRouteSlug(doc.id);
       urls.push(versionedDocsUrl(slug, version.slug));
     }
@@ -178,6 +191,8 @@ export function enumerateVersionedRoutes(
     const tree = buildNavTree(navDocs, locale as Locale, categoryMeta);
 
     for (const doc of allDocs) {
+      // category_no_page index.mdx → no route, no sitemap URL (see paths()).
+      if (doc.data.category_no_page === true) continue;
       const slug = doc.data.slug ?? toRouteSlug(doc.id);
       urls.push(versionedDocsUrl(slug, version.slug, locale as string));
     }

package/templates/base/src/components/client-router-bootstrap.tsx

@@ -1,14 +1,64 @@
-// W6A stub — no-op default export.
+"use client";
+
+// Client-side bootstrap for the @takazudo/zfb-runtime ClientRouter.
+//
+// Why this exists (zudolab/zudo-doc#1524, W7A verification):
+// `<ClientRouter />` (mounted in doc-layout.tsx) emits SSR meta tags + CSS
+// for the SPA soft-swap router, but the actual click/form intercept
+// registration runs as a top-of-module side effect inside
+// `@takazudo/zfb-runtime/src/client-router.ts`:
+//
+//   if (typeof document !== "undefined") { init(); }
+//
+// The host's existing `import { ClientRouter } from "@takazudo/zfb-runtime"`
+// in doc-layout.tsx happens during SSR (where typeof document ===
+// "undefined"), so the side effect is silently skipped — the router
+// module never reaches the client bundle and every navigation falls
+// through to a full page load. W7A's Playwright harness confirmed this:
+// pageswap.viewTransition is null, getAnimations() is empty during nav,
+// and the sidebar DOM identity is destroyed on every click.
+//
+// The fix is a minimal "use client" island whose only job is to
+// side-effect-import `@takazudo/zfb-runtime/client-router` so the same
+// guard fires in the browser. The `init()` is idempotent (guarded by an
+// `initialized` flag in router.ts), so even if the import path is
+// reached again later the registration runs exactly once.
 //
-// The host installs a tiny client-side router bootstrap that re-runs
-// island lifecycle code across zfb navigations. Generated projects ship
-// the no-op so unconditional page imports (`pages/lib/_body-end-islands`)
-// resolve without dragging the routing bridge into every scaffold.
+// Bundle cost: the only thing this island ships to the client is the
+// client-router subgraph (router.ts + swap-functions.ts + events.ts +
+// types.ts + cssesc.ts) plus its single dep on `@takazudo/zfb/runtime`'s
+// island manager. The server-only zfb-runtime modules
+// (createPageRouter, snapshot, framework adapter) are not transitively
+// reachable from the client-router barrel and stay out of the bundle.
+//
+// Why not call init() in useEffect instead of a side-effect import:
+// useEffect fires after Preact mounts, which is after the islands
+// runtime fetches and executes the bundle. Module top-level code runs
+// as soon as the bundle is parsed by the browser — earlier than mount,
+// closer to Astro's <script type="module"> emission timing. The first
+// click on a fresh page typically arrives 100ms+ after parse, so this
+// timing is what makes the SPA-router actually intercept.
+
+// Side-effect import — running this file's bundle in the browser
+// triggers the `if (typeof document !== "undefined") { init(); }` guard
+// at the top of `@takazudo/zfb-runtime/src/client-router.ts`.
+import "@takazudo/zfb-runtime/client-router";
+
 import type { JSX } from "preact";
 
+/**
+ * Renders nothing. The island marker exists only so zfb's island scanner
+ * walks page → BodyEndIslands → ClientRouterBootstrap and includes the
+ * client-router barrel in the per-island bundle, where the side-effect
+ * import above can fire on the client.
+ */
 function ClientRouterBootstrap(): JSX.Element | null {
   return null;
 }
+
+// Stable marker name across SSR / scanner / hydration manifest. Required
+// for production minification per the existing pattern in
+// `pages/lib/_body-end-islands.tsx` (zfb PR #150 marker-name alignment).
 ClientRouterBootstrap.displayName = "ClientRouterBootstrap";
 
 export default ClientRouterBootstrap;

package/templates/base/src/components/sidebar-toggle.tsx

@@ -1,11 +1,55 @@
-import { useState, useEffect } from "preact/compat";
-import type { ComponentChildren } from "preact";
+"use client";
+
+// Use preact hook entrypoints directly — the "react" → "preact/compat" alias
+// lets us consume React-typed components in this Preact app (configured
+// project-wide). Same pattern as src/components/sidebar-tree.tsx and
+// packages/zudo-doc/src/theme/theme-toggle.tsx. Type references via
+// the global React namespace still resolve via @types/react.
+import { useState, useEffect } from "preact/hooks";
+import clsx from "clsx";
+// After zudolab/zudo-doc#1335 (E2 task 2 half B) the host components
+// pull lifecycle event names from the v2 transitions module rather
+// than hard-coding `astro:*` literals.
+import { AFTER_NAVIGATE_EVENT } from "@takazudo/zudo-doc/transitions";
+import SidebarTree from "@/components/sidebar-tree";
+import type { NavNode } from "@/utils/docs";
+import type { LocaleLink } from "@/types/locale";
+// Types-only subpath (`./sidebar/types`) sidesteps the JSX type-graph
+// pulled in by `./sidebar`'s runtime barrel.
+import type { SidebarRootMenuItem } from "@takazudo/zudo-doc/sidebar/types";
+
+// Mobile drawer hosts the SidebarTree directly (rather than receiving it as
+// JSX children) so the tree's data props ride across the SSR → hydrate
+// boundary inside the Island marker's `data-props` attribute. zfb's
+// `Island()` only serialises a child component's *own* props (excluding
+// `children`); when SidebarTree was passed as `children`, its data was
+// dropped during hydration and Preact wiped the SSR-rendered tree DOM.
+// Mirroring the desktop `<Sidebar treeComponent={SidebarTree} ...>` shape
+// keeps the data attached to the wrapping island. zudolab/zudo-doc#1355
+// wave 13.5.
 
 interface SidebarToggleProps {
-  children: ComponentChildren;
+  nodes: NavNode[];
+  currentSlug?: string;
+  rootMenuItems?: SidebarRootMenuItem[];
+  backToMenuLabel?: string;
+  localeLinks?: LocaleLink[];
+  themeDefaultMode?: "light" | "dark";
 }
 
-export default function SidebarToggle({ children }: SidebarToggleProps) {
+export default function SidebarToggle({
+  nodes,
+  currentSlug,
+  rootMenuItems,
+  backToMenuLabel,
+  localeLinks,
+  themeDefaultMode,
+}: SidebarToggleProps) {
+  // Initial state must match SSR (`open=false`) so the hydration DOM
+  // matches the SSG output byte-for-byte. The backdrop and toggle-icon
+  // are rendered unconditionally below so the hydration tree has the
+  // same shape regardless of `open`, preventing Preact from re-mounting
+  // the subtree (which can drop click handlers on the hamburger button).
   const [open, setOpen] = useState(false);
 
   useEffect(() => {
@@ -24,61 +68,68 @@ export default function SidebarToggle({ children }: SidebarToggleProps) {
     function handleSwap() {
       setOpen(false);
     }
-    // zfb's `<ViewTransitions />` does a real page load on every
-    // navigation, so `DOMContentLoaded` is the post-navigate signal.
-    document.addEventListener("DOMContentLoaded", handleSwap);
-    return () => document.removeEventListener("DOMContentLoaded", handleSwap);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, handleSwap);
+    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, handleSwap);
   }, []);
 
   return (
     <>
-      {/* Hamburger button - visible only on mobile */}
+      {/* Hamburger button - visible only on mobile.
+          Both icons are always rendered so the SSR output has the same
+          DOM shape as the post-hydration tree. The closed-state icon is
+          hidden via `hidden` when open=true, and vice versa, so Preact's
+          hydration walk sees byte-stable markup and keeps the click
+          handler attached. */}
       <button
         type="button"
         onClick={() => setOpen(!open)}
         className="lg:hidden px-hsp-sm py-vsp-xs -ml-hsp-sm mr-hsp-sm text-muted hover:text-fg"
         aria-label={open ? "Close sidebar" : "Open sidebar"}
+        aria-expanded={open}
       >
-        {open ? (
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            className="h-icon-lg w-icon-lg"
-            fill="none"
-            viewBox="0 0 24 24"
-            stroke="currentColor"
-            strokeWidth={2}
-          >
-            <path
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              d="M6 18L18 6M6 6l12 12"
-            />
-          </svg>
-        ) : (
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            className="h-icon-lg w-icon-lg"
-            fill="none"
-            viewBox="0 0 24 24"
-            stroke="currentColor"
-            strokeWidth={2}
-          >
-            <path
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              d="M4 6h16M4 12h16M4 18h16"
-            />
-          </svg>
-        )}
+        {/* X icon — visible only when open */}
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          className={clsx("h-icon-lg w-icon-lg", !open && "hidden")}
+          aria-hidden="true"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M6 18L18 6M6 6l12 12"
+          />
+        </svg>
+        {/* Hamburger icon — visible only when closed */}
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          className={clsx("h-icon-lg w-icon-lg", open && "hidden")}
+          aria-hidden="true"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M4 6h16M4 12h16M4 18h16"
+          />
+        </svg>
       </button>
 
-      {/* Backdrop overlay - mobile only */}
-      {open && (
-        <div
-          className="fixed inset-0 z-30 bg-overlay/30 lg:hidden"
-          onClick={() => setOpen(false)}
-        />
-      )}
+      {/* Backdrop overlay - mobile only.
+          Rendered unconditionally; CSS `hidden` toggles visibility so
+          the SSR DOM tree matches the hydrated tree (no subtree
+          mount/unmount across the hydration boundary). */}
+      <div
+        className={clsx("fixed inset-0 z-30 bg-overlay/30 lg:hidden", !open && "hidden")}
+        aria-hidden={!open}
+        onClick={() => setOpen(false)}
+      />
 
       {/* Sidebar panel - mobile only (desktop sidebar is in doc-layout) */}
       <aside
@@ -90,7 +141,14 @@ export default function SidebarToggle({ children }: SidebarToggleProps) {
         `}
       >
         <div className="flex-1 overflow-y-auto">
-          {children}
+          <SidebarTree
+            nodes={nodes}
+            currentSlug={currentSlug}
+            rootMenuItems={rootMenuItems}
+            backToMenuLabel={backToMenuLabel}
+            localeLinks={localeLinks}
+            themeDefaultMode={themeDefaultMode}
+          />
         </div>
       </aside>
     </>

package/templates/base/src/components/theme-toggle.tsx

@@ -1,4 +1,9 @@
-import { useState, useEffect } from "preact/compat";
+"use client";
+
+// Use preact hook entrypoints directly — the "react" → "preact/compat" alias
+// lets us consume React-typed components in this Preact app (configured
+// project-wide). Same pattern as packages/zudo-doc/src/theme/theme-toggle.tsx.
+import { useState, useEffect } from "preact/hooks";
 
 const STORAGE_KEY = "zudo-doc-theme";
 
@@ -91,3 +96,12 @@ export default function ThemeToggle({ defaultMode = "dark" }: ThemeToggleProps)
     </button>
   );
 }
+// Pin the island marker name to "ThemeToggle" regardless of esbuild's
+// identifier deduplication. Both this host component and the v2 package's
+// ThemeToggleInner share the plain name "ThemeToggle"; when both land in the
+// same SSR bundle esbuild renames one to "ThemeToggle2", making
+// captureComponentName() emit "ThemeToggle2" — a name that has no entry in
+// the island manifest. Setting displayName explicitly ensures Island() reads
+// the attribute-level name (displayName is preferred over .name) and emits
+// the correct data-zfb-island="ThemeToggle" marker. zudolab/zudo-doc#1446.
+ThemeToggle.displayName = "ThemeToggle";

package/templates/base/src/config/frontmatter-preview-defaults.ts

@@ -21,4 +21,6 @@ export const DEFAULT_FRONTMATTER_IGNORE_KEYS: string[] = [
   "standalone",
   "slug",
   "generated",
+  "category_no_page",
+  "category_sort_order",
 ];

package/templates/base/src/styles/global.css

@@ -1,6 +1,28 @@
 @import "tailwindcss/preflight";
 @import "tailwindcss/utilities";
 
+/* ========================================
+ * @takazudo/zudo-doc package safelist
+ *
+ * The package ships a build-generated safelist at `dist/safelist.css`
+ * (zudolab/zudo-doc#1993). Importing it via the module resolver is
+ * reliable across all consumer environments — same code path as the
+ * existing `@import "@takazudo/zdtp/styles.css"` below.
+ *
+ * Why not @source the package dist/ glob? The old approach
+ * (`@source "../../node_modules/@takazudo/zudo-doc/dist/**"`) was
+ * unreliable: pnpm stores packages in a content-addressable store and
+ * surfaces them to node_modules via symlinks. Tailwind v4's file
+ * scanner does not reliably traverse those symlinks, so arbitrary-value
+ * candidates (e.g. `w-[var(--zd-sidebar-w)]`, `h-[calc(100vh-3.5rem)]`)
+ * were intermittently dropped across rebuilds (zudolab/zudo-doc#1971,
+ * #1989). The package-generated `@source inline()` in dist/safelist.css
+ * contains the full set, extracted at package build time — no drift, no
+ * symlink traversal, auto-syncs on package upgrade (zudolab/zudo-doc#1994).
+ * ======================================== */
+
+@import "@takazudo/zudo-doc/safelist.css";
+
 /* ========================================
  * Tailwind v4 content sources
  *
@@ -8,16 +30,10 @@
  * scanner falls back to explicit @source directives for class detection.
  * Builds that run outside a git checkout (E2E fixtures, CI containers
  * that copy the source tree without history, etc.) hit this fallback,
- * and zfb's default content roots only cover `pages/`. Components and
- * shared package code that hold responsive variants (`lg:hidden`,
- * `lg:block`, `xl:hidden`), design-token utilities (`h-icon-lg`,
- * `bg-bg`, `text-fg`), and absolute-position primitives (`sticky`,
- * `inset-0`, `top-[3.5rem]`) live outside pages/, so without these
- * directives Tailwind drops every utility class those modules emit and
- * the dist stylesheet collapses — breaking mobile-sidebar visibility,
- * desktop-sidebar reveal, and mobile-toc accordion at non-git build
- * targets. Keep these in sync with `src/styles/global.css` in the host
- * repo (zudolab/zudo-doc#1355 wave 13 topic 2; pages/ added in #1444).
+ * and zfb's default content roots only cover `pages/`. Components live
+ * outside pages/, so these directives ensure the consumer's own code is
+ * always scanned for utility classes. The package's utilities are now
+ * covered by the @import above — these directives cover consumer code only.
  * ======================================== */
 
 @source "src/components/**/*.{tsx,ts,jsx,js,mdx,md}";
@@ -114,7 +130,8 @@
   --spacing-hsp-xl: 1.5rem;     /* 24px — generous padding */
   --spacing-hsp-2xl: 2rem;      /* 32px — large padding */
 
-  /* Vertical spacing (7 steps) */
+  /* Vertical spacing (8 steps) */
+  --spacing-vsp-3xs: 0.25rem;     /* 4px — hairline gap */
   --spacing-vsp-2xs: 0.4375rem;   /* 7px — tight gap */
   --spacing-vsp-xs: 0.875rem;    /* 14px — small gap */
   --spacing-vsp-sm: 1.25rem;     /* 20px — compact gap */
@@ -134,6 +151,16 @@
   /* Image overlay button chrome */
   --spacing-image-overlay-inset: 0.5rem;  /* 8px — overlay button corner inset + internal padding */
 
+  /* ========================================
+   * Elevation — the tight `@import "tailwindcss/utilities"` (no default
+   * @theme) drops Tailwind's default shadow scale, so `shadow-*` utilities
+   * generate nothing. Re-add the one elevation the components use: header
+   * and version-switcher dropdown panels apply `shadow-lg`. Value is
+   * Tailwind v4's default shadow-lg; the black is intentionally
+   * theme-independent (a drop shadow is absence of light, not a themed color).
+   * ======================================== */
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+
   /* ========================================
    * Typography
    * ======================================== */

package/templates/base/src/types/docs-entry.ts

@@ -33,6 +33,13 @@ export interface DocsEntry {
     standalone?: boolean;
     slug?: string;
     generated?: boolean;
+    /** Category metadata on a directory's index.mdx (frontmatter form of
+     *  `_category_.json` `noPage`): non-linked sidebar header + excluded from
+     *  routes/sitemap/search. Frontmatter wins over the sidecar. */
+    category_no_page?: boolean;
+    /** Frontmatter form of `_category_.json` `sortOrder` — child sort
+     *  direction. Frontmatter wins over the sidecar. */
+    category_sort_order?: "asc" | "desc";
   };
   rendered?: RenderedContent;
   filePath?: string;

package/templates/base/src/utils/docs.ts

@@ -70,8 +70,17 @@ function navTreeCacheKey(
     : "_";
   return `${lang}:${metaKey}:${docs
     .map((d) => {
-      const { sidebar_position, sidebar_label, title, description, unlisted, standalone, slug } =
-        d.data;
+      const {
+        sidebar_position,
+        sidebar_label,
+        title,
+        description,
+        unlisted,
+        standalone,
+        slug,
+        category_no_page,
+        category_sort_order,
+      } = d.data;
       return JSON.stringify([
         d.id,
         sidebar_position,
@@ -81,6 +90,8 @@ function navTreeCacheKey(
         unlisted,
         standalone,
         slug,
+        category_no_page,
+        category_sort_order,
       ]);
     })
     .sort()
@@ -197,7 +208,9 @@ function toNavNodes(
   for (const child of parent.children.values()) {
     const doc = child.doc;
     const meta = categoryMeta?.get(child.fullPath);
-    const sortOrder = meta?.sortOrder ?? "asc";
+    // Frontmatter wins over the `_category_.json` sidecar when both exist.
+    const noPage = doc?.data.category_no_page ?? meta?.noPage;
+    const sortOrder = doc?.data.category_sort_order ?? meta?.sortOrder ?? "asc";
     const children = toNavNodes(child, lang, categoryMeta, sortOrder);
 
     nodes.push({
@@ -206,12 +219,16 @@ function toNavNodes(
         doc?.data.sidebar_label ?? doc?.data.title ?? meta?.label ?? toTitleCase(child.segment),
       description: doc?.data.description ?? meta?.description,
       position: doc?.data.sidebar_position ?? meta?.position ?? 999,
-      href: meta?.noPage
+      href: noPage
         ? undefined
         : doc || children.length > 0
           ? docsUrl(child.fullPath, lang)
           : undefined,
-      hasPage: !!doc,
+      // A `category_no_page` index.mdx is metadata-only — force hasPage false so
+      // it matches a `_category_.json` noPage category (no backing file): a
+      // non-linked header that flattenTree drops from prev/next. Otherwise the
+      // route-excluded slug would surface as a 404 pagination target.
+      hasPage: !!doc && noPage !== true,
       children,
       sortOrder,
     });
@@ -304,6 +321,25 @@ export function findNode(nodes: NavNode[], slug: string): NavNode | undefined {
   return undefined;
 }
 
+/**
+ * Return the href of the first routed descendant (a node with `hasPage` and an
+ * `href`), walking children depth-first in order. Returns undefined when the
+ * subtree has no routed page.
+ *
+ * Used by CategoryNav's `categories=` mode to give a `category_no_page` card a
+ * real destination: such a category has no route of its own (collectAutoIndexNodes
+ * skips noPage nodes), so a card linking to its own slug URL would be a dead
+ * link. Linking to the first child page keeps the route surface unchanged.
+ */
+export function firstRoutedHref(node: NavNode): string | undefined {
+  for (const child of node.children) {
+    if (child.hasPage && child.href) return child.href;
+    const nested = firstRoutedHref(child);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
 export interface BreadcrumbItem {
   label: string;
   href?: string;

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

@@ -91,7 +91,7 @@ describe("generateClaudeResourcesDocs", () => {
       expect(fs.existsSync(path.join(docsDir, "claude-agents"))).toBe(true);
     });
 
-    it("generates _category_.json with noPage for sub-categories", () => {
+    it("generates index.mdx with category_no_page for sub-categories", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
@@ -100,14 +100,14 @@ describe("generateClaudeResourcesDocs", () => {
 
       const dirs = ["claude-md", "claude-commands", "claude-skills", "claude-agents"];
       for (const dir of dirs) {
-        const catPath = path.join(docsDir, dir, "_category_.json");
-        expect(fs.existsSync(catPath)).toBe(true);
-
-        const cat = JSON.parse(fs.readFileSync(catPath, "utf8"));
-        expect(cat).toHaveProperty("label");
-        expect(cat).toHaveProperty("position");
-        expect(cat).toHaveProperty("description");
-        expect(cat.noPage).toBe(true);
+        const indexPath = path.join(docsDir, dir, "index.mdx");
+        expect(fs.existsSync(indexPath)).toBe(true);
+
+        const parsed = matter(fs.readFileSync(indexPath, "utf8"));
+        expect(parsed.data).toHaveProperty("title");
+        expect(parsed.data).toHaveProperty("sidebar_position");
+        expect(parsed.data).toHaveProperty("description");
+        expect(parsed.data.category_no_page).toBe(true);
       }
     });
 
@@ -332,7 +332,7 @@ describe("generateClaudeResourcesDocs", () => {
   // ---------------------------------------------------------------------------
 
   describe("category metadata", () => {
-    it("_category_.json positions are ordered correctly", () => {
+    it("index.mdx sidebar_position values are ordered correctly", () => {
       generateClaudeResourcesDocs({
         claudeDir,
         projectRoot: tmpDir,
@@ -340,10 +340,10 @@ describe("generateClaudeResourcesDocs", () => {
       });
 
       const readPos = (dir: string) => {
-        const cat = JSON.parse(
-          fs.readFileSync(path.join(docsDir, dir, "_category_.json"), "utf8"),
+        const parsed = matter(
+          fs.readFileSync(path.join(docsDir, dir, "index.mdx"), "utf8"),
         );
-        return cat.position;
+        return parsed.data.sidebar_position;
       };
 
       expect(readPos("claude-md")).toBe(900);
@@ -351,6 +351,26 @@ describe("generateClaudeResourcesDocs", () => {
       expect(readPos("claude-skills")).toBe(902);
       expect(readPos("claude-agents")).toBe(903);
     });
+
+    it("index.mdx has correct label as title for each sub-category", () => {
+      generateClaudeResourcesDocs({
+        claudeDir,
+        projectRoot: tmpDir,
+        docsDir,
+      });
+
+      const readTitle = (dir: string) => {
+        const parsed = matter(
+          fs.readFileSync(path.join(docsDir, dir, "index.mdx"), "utf8"),
+        );
+        return parsed.data.title;
+      };
+
+      expect(readTitle("claude-md")).toBe("CLAUDE.md");
+      expect(readTitle("claude-commands")).toBe("Commands");
+      expect(readTitle("claude-skills")).toBe("Skills");
+      expect(readTitle("claude-agents")).toBe("Agents");
+    });
   });
 
   // ---------------------------------------------------------------------------
@@ -373,4 +393,143 @@ describe("generateClaudeResourcesDocs", () => {
       });
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Slug collision detection tests
+  // ---------------------------------------------------------------------------
+
+  describe("slug collision detection", () => {
+    it("throws when two CLAUDE.md paths produce the same slug", () => {
+      // foo/bar/CLAUDE.md → slug "foo--bar"
+      // foo--bar/CLAUDE.md → slug "foo--bar"  (collision)
+      fs.mkdirSync(path.join(tmpDir, "foo", "bar"), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, "foo", "bar", "CLAUDE.md"),
+        "# foo/bar instructions",
+      );
+      fs.mkdirSync(path.join(tmpDir, "foo--bar"), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, "foo--bar", "CLAUDE.md"),
+        "# foo--bar instructions",
+      );
+
+      expect(() =>
+        generateClaudeResourcesDocs({
+          claudeDir,
+          projectRoot: tmpDir,
+          docsDir,
+        }),
+      ).toThrow(/slug collision/);
+    });
+
+    it("names both colliding source paths in the error", () => {
+      fs.mkdirSync(path.join(tmpDir, "foo", "bar"), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, "foo", "bar", "CLAUDE.md"),
+        "# foo/bar instructions",
+      );
+      fs.mkdirSync(path.join(tmpDir, "foo--bar"), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, "foo--bar", "CLAUDE.md"),
+        "# foo--bar instructions",
+      );
+
+      let caughtMessage = "";
+      try {
+        generateClaudeResourcesDocs({
+          claudeDir,
+          projectRoot: tmpDir,
+          docsDir,
+        });
+      } catch (e) {
+        caughtMessage = (e as Error).message;
+      }
+
+      expect(caughtMessage).toContain("foo--bar");
+      // Both source paths must appear in the message
+      expect(caughtMessage).toMatch(/foo.bar.CLAUDE\.md/);
+      expect(caughtMessage).toMatch(/foo--bar.CLAUDE\.md/);
+    });
+
+    it("does not throw for a clean tree (no collisions)", () => {
+      // The default fixture has only root/CLAUDE.md — no collision
+      expect(() =>
+        generateClaudeResourcesDocs({
+          claudeDir,
+          projectRoot: tmpDir,
+          docsDir,
+        }),
+      ).not.toThrow();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Reserved "index" slug guard tests
+  // ---------------------------------------------------------------------------
+
+  describe("reserved index slug guard", () => {
+    it("throws when a CLAUDE.md directory maps to the reserved index slug", () => {
+      // index/CLAUDE.md → slug "index" — reserved for category index.mdx
+      fs.mkdirSync(path.join(tmpDir, "index"), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, "index", "CLAUDE.md"),
+        "# index dir instructions",
+      );
+
+      expect(() =>
+        generateClaudeResourcesDocs({
+          claudeDir,
+          projectRoot: tmpDir,
+          docsDir,
+        }),
+      ).toThrow(/reserved slug "index"/);
+    });
+
+    it("throws when a command file is named index.md", () => {
+      fs.writeFileSync(
+        path.join(claudeDir, "commands", "index.md"),
+        '---\ndescription: "Index command"\n---\n\nIndex body.',
+      );
+
+      expect(() =>
+        generateClaudeResourcesDocs({
+          claudeDir,
+          projectRoot: tmpDir,
+          docsDir,
+        }),
+      ).toThrow(/reserved name "index"/);
+    });
+
+    it("throws when a skill directory is named index", () => {
+      const indexSkillDir = path.join(claudeDir, "skills", "index");
+      fs.mkdirSync(indexSkillDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(indexSkillDir, "SKILL.md"),
+        '---\nname: index\ndescription: "Index skill"\n---\n\nIndex skill body.',
+      );
+
+      expect(() =>
+        generateClaudeResourcesDocs({
+          claudeDir,
+          projectRoot: tmpDir,
+          docsDir,
+        }),
+      ).toThrow(/reserved name "index"/);
+    });
+
+    it("throws when an agent file is named index.md", () => {
+      fs.writeFileSync(
+        path.join(claudeDir, "agents", "index.md"),
+        '---\nname: index-agent\ndescription: "Index agent"\nmodel: sonnet\n---\n\nIndex agent body.',
+      );
+
+      expect(() =>
+        generateClaudeResourcesDocs({
+          claudeDir,
+          projectRoot: tmpDir,
+          docsDir,
+        }),
+      ).toThrow(/reserved name "index"/);
+    });
+  });
 });

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

@@ -76,19 +76,21 @@ function listFiles(dir: string): string[] {
     .sort();
 }
 
-function writeCategoryMeta(
+function writeCategoryIndex(
   outputDir: string,
   label: string,
   position: number,
   description: string,
-  noPage = true,
 ) {
-  const meta: Record<string, unknown> = { label, position, description };
-  if (noPage) meta.noPage = true;
-  fs.writeFileSync(
-    path.join(outputDir, "_category_.json"),
-    JSON.stringify(meta, null, 2) + "\n",
-  );
+  const mdx = `---
+title: "${escapeTitle(label)}"
+description: "${escapeTitle(description)}"
+sidebar_position: ${position}
+category_no_page: true
+generated: true
+---
+`;
+  fs.writeFileSync(path.join(outputDir, "index.mdx"), mdx);
 }
 
 // ---------------------------------------------------------------------------
@@ -174,6 +176,11 @@ function generateClaudemdDocs(
 
   const emittedSlugs = new Map<string, string>();
   items.forEach((item, index) => {
+    if (item.slug === "index") {
+      throw new Error(
+        `claude-resources: "${item.relPath}" maps to the reserved slug "index", which is used for the category metadata file. Rename the directory to resolve the conflict.`,
+      );
+    }
     const previous = emittedSlugs.get(item.slug);
     if (previous !== undefined) {
       throw new Error(
@@ -197,7 +204,7 @@ ${escapeForMdx(content.trim())}
     fs.writeFileSync(path.join(outputDir, `${item.slug}.mdx`), mdx);
   });
 
-  writeCategoryMeta(outputDir, "CLAUDE.md", 900, "Project-specific instructions");
+  writeCategoryIndex(outputDir, "CLAUDE.md", 900, "Project-specific instructions");
   return items;
 }
 
@@ -225,6 +232,11 @@ function generateCommandsDocs(config: ClaudeResourcesConfig): CommandItem[] {
     if (!parsed) continue;
 
     const name = file.replace(/\.md$/, "");
+    if (name === "index") {
+      throw new Error(
+        `claude-resources: ".claude/commands/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the command file to resolve the conflict.`,
+      );
+    }
     const description = (parsed.data.description as string) || "";
 
     items.push({ name, description });
@@ -243,7 +255,7 @@ ${escapeForMdx(parsed.content.trim())}
 
   items.sort((a, b) => a.name.localeCompare(b.name));
 
-  writeCategoryMeta(outputDir, "Commands", 901, "Custom slash commands");
+  writeCategoryIndex(outputDir, "Commands", 901, "Custom slash commands");
   return items;
 }
 
@@ -345,6 +357,11 @@ function generateSkillsDocs(config: ClaudeResourcesConfig): SkillItem[] {
   const items: SkillItem[] = [];
 
   for (const dir of dirs) {
+    if (dir === "index") {
+      throw new Error(
+        `claude-resources: skill directory ".claude/skills/index/" uses the reserved name "index", which is used for the category metadata file. Rename the skill directory to resolve the conflict.`,
+      );
+    }
     const content = fs.readFileSync(
       path.join(skillsDir, dir, "SKILL.md"),
       "utf8",
@@ -474,7 +491,7 @@ ${escapeForMdx(ref.content.trim())}
 
   items.sort((a, b) => a.name.localeCompare(b.name));
 
-  writeCategoryMeta(outputDir, "Skills", 902, "Skill packages");
+  writeCategoryIndex(outputDir, "Skills", 902, "Skill packages");
   return items;
 }
 
@@ -505,6 +522,11 @@ function generateAgentsDocs(config: ClaudeResourcesConfig): AgentItem[] {
     const description = (parsed.data.description as string) || "";
     const model = (parsed.data.model as string) || "";
     const fileSlug = file.replace(/\.md$/, "");
+    if (fileSlug === "index") {
+      throw new Error(
+        `claude-resources: ".claude/agents/index.md" uses the reserved name "index", which is used for the category metadata file. Rename the agent file to resolve the conflict.`,
+      );
+    }
 
     items.push({ name, file: fileSlug, description, model });
 
@@ -525,7 +547,7 @@ ${escapeForMdx(parsed.content.trim())}
 
   items.sort((a, b) => a.name.localeCompare(b.name));
 
-  writeCategoryMeta(outputDir, "Agents", 903, "Custom subagents");
+  writeCategoryIndex(outputDir, "Agents", 903, "Custom subagents");
   return items;
 }
 

package/templates/features/designTokenPanel/files/src/config/design-tokens-manifest.ts

@@ -39,6 +39,7 @@ export const SPACING_TOKENS: readonly TokenDef[] = [
   { id: "hsp-2xl", cssVar: "--spacing-hsp-2xl", label: "hsp-2xl", group: "hsp", default: "2rem",     step: 0.025, unit: "rem" },
 
   // --- Vertical spacing ---
+  { id: "vsp-3xs", cssVar: "--spacing-vsp-3xs", label: "vsp-3xs", group: "vsp", default: "0.25rem",   step: 0.025, unit: "rem" },
   { id: "vsp-2xs", cssVar: "--spacing-vsp-2xs", label: "vsp-2xs", group: "vsp", default: "0.4375rem", step: 0.025, unit: "rem" },
   { id: "vsp-xs",  cssVar: "--spacing-vsp-xs",  label: "vsp-xs",  group: "vsp", default: "0.875rem",  step: 0.025, unit: "rem" },
   { id: "vsp-sm",  cssVar: "--spacing-vsp-sm",  label: "vsp-sm",  group: "vsp", default: "1.25rem",   step: 0.025, unit: "rem" },

package/templates/features/docHistory/files/plugins/doc-history-plugin.mjs

@@ -9,8 +9,10 @@
 //               directly. Honours `SKIP_DOC_HISTORY=1` via `env: process.env`.
 //
 //   postBuild — invokes `runDocHistoryPostBuild` to write
-//               `<outDir>/doc-history/<slug>.json` files. Also honours
-//               `SKIP_DOC_HISTORY=1` (the runner returns early when set).
+//               `<outDir>/doc-history/<slug>.json` files. Skipped by default
+//               on local builds (opt in with `GEN_DOC_HISTORY=1`); always runs
+//               in CI; `SKIP_DOC_HISTORY=1` suppresses it everywhere. The
+//               gating lives in `shouldGeneratePostBuild` (#1986).
 //
 //   devMiddleware — reverse-proxies `/doc-history/*` requests to the
 //               standalone `@takazudo/zudo-doc-history-server` on port 4322.

package/templates/features/docTags/files/pages/[locale]/docs/tags/[tag].tsx

@@ -48,11 +48,17 @@ export function paths(): Array<{
   }> = [];
 
   for (const locale of Object.keys(settings.locales)) {
-    const { docs } = mergeLocaleDocs({
+    const { docs: mergedDocs } = mergeLocaleDocs({
       baseDocs: loadDocs("docs").filter((d) => !d.data.draft),
       localeDocs: loadDocs(`docs-${locale}`).filter((d) => !d.data.draft),
       applyDefaultLocaleOnlyFilter: true,
     });
+    // category_no_page index files build no route — drop them AFTER the merge
+    // so a locale override carrying the flag first wins the merge (suppressing
+    // the base doc); pre-merge filtering would drop it from localeSlugSet and
+    // the unflagged base doc would resurface as a card linking to a locale
+    // route the docs route never builds.
+    const docs = mergedDocs.filter((d) => !d.data.category_no_page);
     const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
 
     for (const [tag, tagInfo] of tagMap.entries()) {

package/templates/features/docTags/files/pages/[locale]/docs/tags/index.tsx

@@ -53,11 +53,17 @@ export default function LocaleTagsIndexPage({
   const { locale } = params;
   const pageTitle = t("doc.allTags", locale);
 
-  const { docs } = mergeLocaleDocs({
+  const { docs: mergedDocs } = mergeLocaleDocs({
     baseDocs: loadDocs("docs").filter((d) => !d.data.draft),
     localeDocs: loadDocs(`docs-${locale}`).filter((d) => !d.data.draft),
     applyDefaultLocaleOnlyFilter: true,
   });
+  // category_no_page index files build no route — drop them AFTER the merge
+  // so a locale override carrying the flag first wins the merge (suppressing
+  // the base doc); pre-merge filtering would drop it from localeSlugSet and
+  // the unflagged base doc would resurface as a card linking to a locale
+  // route the docs route never builds.
+  const docs = mergedDocs.filter((d) => !d.data.category_no_page);
   const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
 
   const labels: TagNavLabels = {

package/templates/features/docTags/files/pages/docs/tags/[tag].tsx

@@ -42,7 +42,12 @@ export function paths(): Array<{
   props: { tagInfo: TagInfo };
 }> {
   const allDocs = bridgeDocsEntries(getCollection<ZfbDocsData>("docs"), "docs");
-  const docs = allDocs.filter((doc) => !doc.data.unlisted && !doc.data.draft);
+  // category_no_page index.mdx builds no route — drop it so a tag it carries
+  // doesn't render a DocCard linking to a non-existent /docs/<cat>/ page.
+  const docs = allDocs.filter(
+    (doc) =>
+      !doc.data.unlisted && !doc.data.draft && !doc.data.category_no_page,
+  );
   const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
 
   return [...tagMap.entries()].map(([tag, tagInfo]) => ({

package/templates/features/docTags/files/pages/docs/tags/index.tsx

@@ -39,7 +39,12 @@ export default function DocsTagsIndexPage(): JSX.Element {
   const pageTitle = t("doc.allTags", locale);
 
   const allDocs = bridgeDocsEntries(getCollection<ZfbDocsData>("docs"), "docs");
-  const docs = allDocs.filter((doc) => !doc.data.unlisted && !doc.data.draft);
+  // category_no_page index.mdx builds no route — drop it so a tag it carries
+  // doesn't inflate the tag list with a card linking to a non-existent page.
+  const docs = allDocs.filter(
+    (doc) =>
+      !doc.data.unlisted && !doc.data.draft && !doc.data.category_no_page,
+  );
   const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
 
   const labels: TagNavLabels = {

package/templates/features/i18n/files/pages/[locale]/docs/[[...slug]].tsx

@@ -118,6 +118,10 @@ export function paths(): Array<{
 
     // Regular doc pages
     for (const entry of allDocs) {
+      // A `category_no_page` index.mdx is metadata-only — kept in the nav tree
+      // for breadcrumbs but emits no route (zfb retains every .mdx as a
+      // collection entry, so the skip must be explicit).
+      if (entry.data.category_no_page === true) continue;
       // Canonical route slug via the one shared rule (@/utils/slug). `entry.id`
       // is already `toRouteSlug(entry.slug)` (bridgeEntries → stripIndexSuffix →
       // toRouteSlug), so this is identical to the previous `entry.id` form for
@@ -259,6 +263,7 @@ export default function LocaleDocsPage(props: PageArgs): JSX.Element {
             locale={locale}
             entrySlug={props.entry.slug}
             contentDir={contentDir}
+            isFallback={isFallback}
           />
         ) : null
       }

package/templates/features/i18n/files/pages/[locale]/index.tsx

@@ -84,8 +84,10 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
   const categoryOrder = getCategoryOrder();
   const groupedTree = groupSatelliteNodes(tree, categoryOrder);
 
+  // Drop category_no_page index files so the count matches the number of tag
+  // pages actually built (the tag routes exclude them too).
   const tagCount = collectTags(
-    navDocs,
+    navDocs.filter((d) => !d.data.category_no_page),
     (id, data) => data.slug ?? toRouteSlug(id),
   ).size;
 

package/templates/features/versioning/files/pages/v/[version]/[locale]/docs/[[...slug]].tsx

@@ -128,6 +128,10 @@ export function paths(): Array<{
 
       // Regular doc pages
       for (const entry of allDocs) {
+        // A `category_no_page` index.mdx is metadata-only — kept in the nav
+        // tree for breadcrumbs but emits no route (zfb retains every .mdx as a
+        // collection entry, so the skip must be explicit).
+        if (entry.data.category_no_page === true) continue;
         const slug = entry.data.slug ?? toRouteSlug(entry.slug);
         const isFallback = fallbackSlugs.has(slug);
         const entryContentDir = isFallback ? version.docsDir : (localeDir ?? version.docsDir);

package/templates/features/versioning/files/pages/v/[version]/docs/[[...slug]].tsx

@@ -106,6 +106,10 @@ export function paths(): Array<{
 
     // Regular doc pages
     for (const entry of allDocs) {
+      // A `category_no_page` index.mdx is metadata-only — kept in the nav tree
+      // for breadcrumbs but emits no route (zfb retains every .mdx as a
+      // collection entry, so the skip must be explicit).
+      if (entry.data.category_no_page === true) continue;
       const slug = entry.data.slug ?? toRouteSlug(entry.slug);
       const navSection = getNavSectionForSlug(slug);
       const subtree = getNavSubtree(tree, navSection);