create-zudo-doc 4.4.13 → 5.0.0

package/dist/claude-md-gen.js

@@ -19,7 +19,7 @@ export function generateCLAUDEFile(choices) {
     lines.push(``);
     lines.push(`- **zfb** — documentation build framework`);
     lines.push(`- **MDX** — content format, authored under \`src/content/\``);
-    lines.push(`- **Tailwind CSS v4** — via \`@tailwindcss/vite\``);
+    lines.push(`- **Tailwind CSS v4** — compiled by zfb's embedded Tailwind engine (no \`@tailwindcss/vite\` plugin, no \`tailwindcss\` dependency); \`src/styles/global.css\` imports \`tailwindcss/preflight\` + \`tailwindcss/utilities\` and zfb's internal resolver serves both`);
     lines.push(`- **Preact** — for interactive islands only (with compat mode for React API)`);
     lines.push("- **zfb semantic highlighting** — native build-time fenced-code rendering plus lazy `@takazudo/zfb-md-wasm` for HtmlPreview; both emit `hi-*` classes resolved through `--zd-syntax-*` design tokens");
     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`);

package/dist/constants.js

@@ -247,6 +247,13 @@ export const FEATURES = [
         default: false,
         cliFlag: "sidebar-toggle",
     },
+    {
+        value: "tocToggle",
+        label: "TOC toggle",
+        hint: "Show/hide the desktop table of contents",
+        default: false,
+        cliFlag: "toc-toggle",
+    },
     {
         value: "versioning",
         label: "Versioning",

package/dist/features/index.js

@@ -10,6 +10,7 @@ import { searchFeature } from "./search.js";
 import { footerFeature } from "./footer.js";
 import { sidebarResizerFeature } from "./sidebar-resizer.js";
 import { sidebarToggleFeature } from "./sidebar-toggle.js";
+import { tocToggleFeature } from "./toc-toggle.js";
 import { docHistoryFeature } from "./doc-history.js";
 import { llmsTxtFeature } from "./llms-txt.js";
 import { claudeResourcesFeature } from "./claude-resources.js";
@@ -39,6 +40,7 @@ export const featureModules = {
     themePackSwitcher: themePackSwitcherFeature,
     sidebarResizer: sidebarResizerFeature,
     sidebarToggle: sidebarToggleFeature,
+    tocToggle: tocToggleFeature,
     versioning: versioningFeature,
     docHistory: docHistoryFeature,
     bodyFootUtil: bodyFootUtilFeature,

package/dist/features/toc-toggle.d.ts

@@ -0,0 +1,11 @@
+import type { FeatureModule } from "../compose.js";
+/**
+ * TOC-toggle feature.
+ *
+ * Purely a `zudoDoc({ tocToggle: true })` field (see `zfb-config-gen.ts`).
+ * `DesktopTocToggle` is fully package-owned
+ * (`@takazudo/zudo-doc/desktop-toc-toggle-island`, wired into the doc-page
+ * shell directly) and its CSS ships unconditionally from
+ * `@takazudo/zudo-doc/features.css` — nothing to inject or copy.
+ */
+export declare const tocToggleFeature: FeatureModule;

package/dist/features/toc-toggle.js

@@ -0,0 +1,13 @@
+/**
+ * TOC-toggle feature.
+ *
+ * Purely a `zudoDoc({ tocToggle: true })` field (see `zfb-config-gen.ts`).
+ * `DesktopTocToggle` is fully package-owned
+ * (`@takazudo/zudo-doc/desktop-toc-toggle-island`, wired into the doc-page
+ * shell directly) and its CSS ships unconditionally from
+ * `@takazudo/zudo-doc/features.css` — nothing to inject or copy.
+ */
+export const tocToggleFeature = () => ({
+    name: "tocToggle",
+    injections: [],
+});

package/dist/scaffold.d.ts

@@ -1,6 +1,20 @@
 import type { UserChoices } from "./prompts.js";
 import { getSecondaryLang } from "./utils.js";
 export { getSecondaryLang };
+/**
+ * TypeScript mirror of `DEFAULT_SKILL_NAME` in `scripts/setup-doc-skill.sh`
+ * (`DEFAULT_SKILL_NAME="${PROJECT_NAME}-wisdom"`, suffix-aware since #3154).
+ * The generator cannot import the shell script, so this rule is duplicated
+ * here; the two are kept from drifting apart by the committed cross-artifact
+ * parity test (#3158).
+ *
+ * If `projectName` already ends in `-wisdom` (or is exactly `wisdom`), it is
+ * used verbatim — appending `-wisdom` again would double the suffix (e.g.
+ * `zudo-test-wisdom` → `zudo-test-wisdom-wisdom`), which matches no
+ * `.gitignore` entry and leaves the generated skill directory untracked.
+ * Otherwise `-wisdom` is appended.
+ */
+export declare function deriveDocSkillName(projectName: string): string;
 /**
  * Pinned `@takazudo/zudo-doc` version used by `generatePackageJson()`.
  * Hoisted as a shared constant (kept even though it now has a single
@@ -18,5 +32,5 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^4.4.13";
+export declare const ZUDO_DOC_PIN = "^5.0.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -7,6 +7,25 @@ import { composeFeatures } from "./compose.js";
 import { featureModules } from "./features/index.js";
 import { capitalize, getSecondaryLang, hasAncestorPnpmWorkspace, pmRunCommand, } from "./utils.js";
 export { getSecondaryLang };
+/**
+ * TypeScript mirror of `DEFAULT_SKILL_NAME` in `scripts/setup-doc-skill.sh`
+ * (`DEFAULT_SKILL_NAME="${PROJECT_NAME}-wisdom"`, suffix-aware since #3154).
+ * The generator cannot import the shell script, so this rule is duplicated
+ * here; the two are kept from drifting apart by the committed cross-artifact
+ * parity test (#3158).
+ *
+ * If `projectName` already ends in `-wisdom` (or is exactly `wisdom`), it is
+ * used verbatim — appending `-wisdom` again would double the suffix (e.g.
+ * `zudo-test-wisdom` → `zudo-test-wisdom-wisdom`), which matches no
+ * `.gitignore` entry and leaves the generated skill directory untracked.
+ * Otherwise `-wisdom` is appended.
+ */
+export function deriveDocSkillName(projectName) {
+    if (projectName === "wisdom" || projectName.endsWith("-wisdom")) {
+        return projectName;
+    }
+    return `${projectName}-wisdom`;
+}
 /**
  * Pinned `@takazudo/zudo-doc` version used by `generatePackageJson()`.
  * Hoisted as a shared constant (kept even though it now has a single
@@ -24,7 +43,7 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^4.4.13";
+export const ZUDO_DOC_PIN = "^5.0.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -343,16 +362,17 @@ export async function scaffold(choices) {
     // on the same feature above), so only emit its ignore entries then —
     // otherwise they would be dead rules that could silently hide an unrelated
     // skill a user later installs under a matching name. The skill name is
-    // deterministic (always `<projectName>-wisdom`, matching DEFAULT_SKILL_NAME
-    // in scripts/setup-doc-skill.sh and the package name), so these entries match
-    // the directory the script creates. The setup script can target either
-    // .claude or .codex, so ignore both possible generated directories. The
-    // docs-ja symlink only exists for i18n projects (the script creates it
-    // conditionally), so gate those lines on i18n.
+    // deterministic (deriveDocSkillName(), matching DEFAULT_SKILL_NAME in
+    // scripts/setup-doc-skill.sh), so these entries match the directory the
+    // script creates. The setup script can target either .claude or .codex, so
+    // ignore both possible generated directories. The docs-ja symlink only
+    // exists for i18n projects (the script creates it conditionally), so gate
+    // those lines on i18n.
     if (choices.features.includes("skillSymlinker")) {
-        gitignoreLines.push("# Generated doc-lookup skill", `.claude/skills/${choices.projectName}-wisdom/SKILL.md`, `.claude/skills/${choices.projectName}-wisdom/docs`, `.codex/skills/${choices.projectName}-wisdom/SKILL.md`, `.codex/skills/${choices.projectName}-wisdom/docs`);
+        const skillName = deriveDocSkillName(choices.projectName);
+        gitignoreLines.push("# Generated doc-lookup skill", `.claude/skills/${skillName}/SKILL.md`, `.claude/skills/${skillName}/docs`, `.codex/skills/${skillName}/SKILL.md`, `.codex/skills/${skillName}/docs`);
         if (choices.features.includes("i18n")) {
-            gitignoreLines.push(`.claude/skills/${choices.projectName}-wisdom/docs-ja`, `.codex/skills/${choices.projectName}-wisdom/docs-ja`);
+            gitignoreLines.push(`.claude/skills/${skillName}/docs-ja`, `.codex/skills/${skillName}/docs-ja`);
         }
         gitignoreLines.push("");
     }
@@ -550,9 +570,18 @@ function generatePackageJson(choices) {
         // singleton across host-callable wiring (zfb#1652/#1653). The zfb family
         // must stay in lockstep because the WASM browser entry depends on its
         // resource-aware island pipeline.
-        "@takazudo/zfb": "0.1.0-next.99",
-        "@takazudo/zfb-runtime": "0.1.0-next.99",
-        "@takazudo/zfb-md-wasm": "0.1.0-next.99",
+        // 1.1.0: container-directive fixes (multi-block bodies, unclosed-opener
+        // diagnostics) plus highlighting for fences nested in MDX JSX bodies and
+        // directives. Content-rendering fixes, additive.
+        // 2.0.0: BREAKING — the `githubAutolinks` markdown feature was removed
+        // (`GithubAutolinksConfig` is gone from `zfb/config`, and a config still
+        // setting it hard-errors at load). A fresh scaffold never emitted it, so
+        // there is no generator-side migration. Additive alongside it:
+        // `strictContentBridge`, a build-only gate that fails `zfb build` when a
+        // collection entry falls back to `<pre data-zfb-content-fallback>`.
+        "@takazudo/zfb": "2.1.0",
+        "@takazudo/zfb-runtime": "2.1.0",
+        "@takazudo/zfb-md-wasm": "2.1.0",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
@@ -587,10 +616,6 @@ function generatePackageJson(choices) {
         // compiles. Same pin as host. Caught by W6B (#1735) consumer-build
         // verification.
         "preact-render-to-string": "^6.6.6",
-        "gray-matter": "^4.0.0",
-        mermaid: "^11.12.3",
-        "remark-cjk-friendly": "^2.0.1",
-        "remark-directive": "^3.0.0",
         // katex — server-side LaTeX renderer used by the always-on
         // pages/lib/_math-block.tsx (called from pages/_mdx-components.ts
         // for `$…$` and `$$…$$` math nodes). Caught by W6B (#1735)
@@ -640,11 +665,17 @@ function generatePackageJson(choices) {
         // packages/zudo-doc/src/__tests__/optional-peer-reachability.test.ts.)
     };
     const devDeps = {
-        "@tailwindcss/vite": "^4.2.0",
-        tailwindcss: "^4.2.0",
         typescript: "^5.9.0",
         "@types/node": "^22.0.0",
-        "@types/react": "^19.2.0", // needed for preact/compat type resolution
+        // @types/react is intentionally ABSENT (#3181/#3183). tsconfig.base.json
+        // now sets `jsx: "react-jsx"` + `jsxImportSource: "preact"`, so TypeScript
+        // resolves `JSX.IntrinsicElements` from preact/jsx-runtime's own types —
+        // not from a global @types/react namespace. Ejected components (e.g.
+        // `src/components/zudo-doc/theme-toggle/`) typecheck cleanly under
+        // `zfb check` without it; verified by the create-zudo-doc `test:slow`
+        // post-eject build. Do not re-add this dep to work around a typecheck
+        // failure — that would mean the react-jsx flip regressed, which is worth
+        // reporting against #3181, not papering over here.
         // html-validate dropped — check:html is no longer a default script
         // (see the scripts block below; `.htmlvalidate.json` no longer ships).
     };
@@ -672,7 +703,7 @@ function generatePackageJson(choices) {
         // `/exclude` at module scope from the always-bundled chrome graph; #3110
         // moved compileExclude into @takazudo/zudo-doc, so docHistory-OFF projects
         // no longer need the package at all.
-        deps["@takazudo/zudo-doc-history-server"] = "^4.4.13";
+        deps["@takazudo/zudo-doc-history-server"] = "^5.0.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).
@@ -741,6 +772,11 @@ function generatePackageJson(choices) {
             "tags-suggest --config src/config/tag-vocabulary.ts";
     }
     if (choices.features.includes("skillSymlinker")) {
+        // Deliberately omit --no-link-tracked-skills here: automatic tracked-skill
+        // linking (#3152) is the intended default for generated projects. Only the
+        // zudo-doc monorepo's own root package.json passes the opt-out, because it
+        // has 20 directories under `.claude/skills/` and a blanket loop would export
+        // 19 project-specific skills into the maintainer's global skills dir (#3157).
         scripts["setup:doc-skill"] = "bash scripts/setup-doc-skill.sh";
         scripts["setup:doc-skill-silent"] =
             "bash scripts/setup-doc-skill.sh --silent";

package/dist/zfb-config-gen.js

@@ -56,6 +56,7 @@ export const DEFAULT_MIRROR = {
     designTokenPanel: false,
     sidebarResizer: false,
     sidebarToggle: false,
+    tocToggle: false,
     imageEnlarge: false,
     findInPage: false,
     dynamicPageTransition: false,
@@ -219,6 +220,7 @@ function buildDesiredConfig(choices) {
     desired.designTokenPanel = choices.features.includes("designTokenPanel");
     desired.sidebarResizer = choices.features.includes("sidebarResizer");
     desired.sidebarToggle = choices.features.includes("sidebarToggle");
+    desired.tocToggle = choices.features.includes("tocToggle");
     desired.imageEnlarge = choices.features.includes("imageEnlarge");
     // findInPage rides the existing tauri feature (#2690) — the Cmd/Ctrl+F find
     // bar only makes sense inside the Tauri desktop shell, so it has no CLI
@@ -358,6 +360,7 @@ const FIELD_ORDER = [
     "designTokenPanel",
     "sidebarResizer",
     "sidebarToggle",
+    "tocToggle",
     "imageEnlarge",
     "findInPage",
     "dynamicPageTransition",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "4.4.13",
+  "version": "5.0.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",
@@ -61,7 +61,6 @@
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^22.0.0",
-    "gray-matter": "^4.0.3",
     "typescript": "^5.9.0",
     "vitest": "^4.1.0"
   }

package/templates/base/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="6" fill="#7c3aed"/>
+  <text x="16" y="23" font-family="system-ui,sans-serif" font-size="20" font-weight="700" fill="white" text-anchor="middle">Z</text>
+</svg>

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

@@ -10,6 +10,13 @@ set -euo pipefail
 
 TARGET_MODE="auto"
 
+# Tracked-skill linking (zudolab/zudo-doc#3156) is default-ON: #3152 asked for
+# automatic linking of a site's own hand-written skills, not just the
+# generated one. --no-link-tracked-skills opts out (e.g. this monorepo's own
+# npm scripts, which would otherwise export ~20 project-specific skills into
+# the user's global skills dir -- see zudolab/zudo-doc#3157).
+LINK_TRACKED_SKILLS="true"
+
 # Accept --silent (alias -y) for parity with the consuming-site convention:
 # scaffolded sites expose `setup:doc-skill-silent` = `bash scripts/setup-doc-skill.sh
 # --silent`. This script is already non-interactive (the skill name is deterministic
@@ -31,6 +38,7 @@ while [ $# -gt 0 ]; do
       TARGET_MODE="${1#--target=}"
       shift
       ;;
+    --no-link-tracked-skills) LINK_TRACKED_SKILLS="false"; shift ;;
     --) shift; break ;;
     -*) echo "Error: unknown flag '$1'" >&2; exit 1 ;;
     *) break ;;
@@ -49,16 +57,29 @@ ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 
 # Read project name from package.json
 PROJECT_NAME=$(node -e "console.log(require('$ROOT_DIR/package.json').name || 'my-project')")
-DEFAULT_SKILL_NAME="${PROJECT_NAME}-wisdom"
+
+# Pre-#3154 default: always `<projectName>-wisdom`, which doubles the suffix
+# when PROJECT_NAME already ends in "-wisdom" (e.g. "zudo-test-wisdom" ->
+# "zudo-test-wisdom-wisdom"). Kept around only to detect leftover legacy
+# directories from that behavior -- see the migration-warning block below.
+LEGACY_DEFAULT_SKILL_NAME="${PROJECT_NAME}-wisdom"
+if [[ "$PROJECT_NAME" == *-wisdom ]] || [[ "$PROJECT_NAME" == "wisdom" ]]; then
+  DEFAULT_SKILL_NAME="$PROJECT_NAME"
+else
+  DEFAULT_SKILL_NAME="$LEGACY_DEFAULT_SKILL_NAME"
+fi
 
 echo ""
 echo "=== zudo-doc Skill Setup ==="
 echo ""
 
-# Skill name is DETERMINISTIC: always `<projectName>-wisdom`. The scaffolded
-# .gitignore (emitted by create-zudo-doc) hard-codes this exact name, so the
-# generated skill directory must match it — an interactive prompt would let the
-# name drift from the gitignore entry and leave the skill showing as untracked
+# Skill name is DETERMINISTIC and suffix-aware: verbatim when PROJECT_NAME
+# already ends in "-wisdom" (or is exactly "wisdom"), otherwise
+# "<projectName>-wisdom" (zudolab/zudo-doc#3154). The scaffolded .gitignore
+# (emitted by create-zudo-doc's packages/create-zudo-doc/src/scaffold.ts,
+# which computes the same name) hard-codes this exact rule, so the generated
+# skill directory must match it — an interactive prompt would let the name
+# drift from the gitignore entry and leave the skill showing as untracked
 # (zudolab/zudo-doc#2173). An explicit override is still allowed via the first
 # CLI arg or the SKILL_NAME env var (consumers who override must also update
 # their .gitignore), but never via an interactive prompt.
@@ -70,6 +91,92 @@ if [[ ! "$SKILL_NAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
   exit 1
 fi
 
+# Migration warning (zudolab/zudo-doc#3154, D3): the suffix-aware rule above is
+# a BREAKING change for existing "*-wisdom" projects. Their .gitignore pins the
+# old, doubled name, so after picking up this fix they get a NEW, unignored
+# skill directory while the stale doubled one remains on disk -- the symptom
+# moves rather than disappears. Detect that and tell the user what to do by
+# hand; never delete anything automatically, it is the user's tree.
+# Three independent symptoms are checked, and ANY one of them fires the
+# warning: stale ignore rules (the .gitignore still names the doubled skill --
+# on its own that already means the NEW directory is unignored, which is the
+# whole problem, even when the legacy directory was never generated or has
+# already been deleted), a leftover legacy directory, and a leftover global
+# symlink. Only the steps for the symptoms actually found are printed.
+# Only fires when SKILL_NAME still equals DEFAULT_SKILL_NAME -- an explicit
+# $1/SKILL_NAME override means the derived name (and this guidance about it)
+# doesn't apply to what the script is actually about to create.
+if [ "$SKILL_NAME" = "$DEFAULT_SKILL_NAME" ] && [ "$DEFAULT_SKILL_NAME" != "$LEGACY_DEFAULT_SKILL_NAME" ]; then
+  # The ignore rules are repo-level, so this is checked once rather than per
+  # target -- both ".claude/skills/<name>/" and ".codex/skills/<name>/" entries
+  # live in the same file (create-zudo-doc emits it at the project root).
+  # -F: PROJECT_NAME comes from package.json and may contain regex characters.
+  legacy_gitignore=""
+  if [ -f "$ROOT_DIR/.gitignore" ] &&
+    grep -qF "skills/$LEGACY_DEFAULT_SKILL_NAME/" "$ROOT_DIR/.gitignore"; then
+    legacy_gitignore="$ROOT_DIR/.gitignore"
+  fi
+
+  legacy_dirs=()
+  legacy_links=()
+  for target in claude codex; do
+    legacy_dir="$ROOT_DIR/.$target/skills/$LEGACY_DEFAULT_SKILL_NAME"
+    if [ -d "$legacy_dir" ]; then
+      legacy_dirs+=("$legacy_dir")
+    fi
+    # -L only (which also catches a dangling link): this script only ever
+    # creates SYMLINKS in the global skills dir, so a real file or directory
+    # sitting at that path is user-owned and none of our business -- calling it
+    # a "stale global symlink" and suggesting `rm -f` would advise deleting
+    # someone else's file (and would simply fail for a directory).
+    legacy_global_link="$HOME/.$target/skills/$LEGACY_DEFAULT_SKILL_NAME"
+    if [ -L "$legacy_global_link" ]; then
+      legacy_links+=("$legacy_global_link")
+    fi
+  done
+
+  if [ -n "$legacy_gitignore" ] ||
+    [ "${#legacy_dirs[@]}" -gt 0 ] ||
+    [ "${#legacy_links[@]}" -gt 0 ]; then
+    echo "WARNING: stale references to the legacy skill name '$LEGACY_DEFAULT_SKILL_NAME' detected."
+    echo "  The skill-name derivation rule changed; this project's skill now resolves to:"
+    echo "  $DEFAULT_SKILL_NAME"
+    echo "  Found:"
+    if [ -n "$legacy_gitignore" ]; then
+      echo "  - stale ignore rules in $legacy_gitignore"
+    fi
+    if [ "${#legacy_dirs[@]}" -gt 0 ]; then
+      for legacy_dir in "${legacy_dirs[@]}"; do
+        echo "  - legacy skill directory: $legacy_dir"
+      done
+    fi
+    if [ "${#legacy_links[@]}" -gt 0 ]; then
+      for legacy_global_link in "${legacy_links[@]}"; do
+        echo "  - stale global symlink: $legacy_global_link"
+      done
+    fi
+    echo "  Manual steps:"
+    step=1
+    if [ -n "$legacy_gitignore" ]; then
+      echo "  $step. Update the ignore rules for '$LEGACY_DEFAULT_SKILL_NAME' to '$DEFAULT_SKILL_NAME' in $legacy_gitignore."
+      step=$((step + 1))
+    fi
+    if [ "${#legacy_dirs[@]}" -gt 0 ]; then
+      for legacy_dir in "${legacy_dirs[@]}"; do
+        echo "  $step. Delete the stale directory once migrated: rm -rf \"$legacy_dir\""
+        step=$((step + 1))
+      done
+    fi
+    if [ "${#legacy_links[@]}" -gt 0 ]; then
+      for legacy_global_link in "${legacy_links[@]}"; do
+        echo "  $step. Remove the stale global symlink: rm -f \"$legacy_global_link\""
+        step=$((step + 1))
+      done
+    fi
+    echo ""
+  fi
+fi
+
 # Resolve the main repo root (handles git worktrees correctly)
 # Use the main worktree path so symlinks survive worktree removal
 REPO_ROOT="$(git -C "$ROOT_DIR" worktree list | head -1 | awk '{print $1}')"
@@ -104,6 +211,46 @@ ensure_symlink() {
   ln -s "$target" "$link_path"
 }
 
+# Helper: link a single tracked (hand-written) skill into the global skills
+# dir WITHOUT ever deleting something this script doesn't own
+# (zudolab/zudo-doc#3156, D4). Unlike ensure_symlink (rm -rf-based -- safe
+# only for the generated skill, whose global name this project owns),
+# tracked-skill names are arbitrary and could collide with a user-owned
+# global skill or a name already claimed by another project, so an existing
+# entry that isn't already our own correct link is left untouched, with a
+# warning.
+safe_link_tracked_skill() {
+  local link_path="$1"
+  local link_target="$2"
+  local skill_name="$3"
+  local target="$4"
+
+  if [ -L "$link_path" ]; then
+    local current_target
+    current_target="$(readlink "$link_path")"
+    if [ "$current_target" = "$link_target" ]; then
+      return 0 # already correct -> no-op
+    fi
+    if [ -e "$link_path" ]; then
+      echo "WARNING: [$target] skipping tracked skill '$skill_name': $link_path already links to $current_target"
+      return 0
+    fi
+    # Dangling symlink (broken target) -> safe to replace.
+    rm -f "$link_path"
+    ln -s "$link_target" "$link_path"
+    echo "  [$target] Linked tracked skill '$skill_name' -> $link_target"
+    return 0
+  fi
+
+  if [ -e "$link_path" ]; then
+    echo "WARNING: [$target] skipping tracked skill '$skill_name': $link_path is a real file/directory, not a symlink"
+    return 0
+  fi
+
+  ln -s "$link_target" "$link_path"
+  echo "  [$target] Linked tracked skill '$skill_name' -> $link_target"
+}
+
 DOCS_JA_DIR="$ROOT_DIR/src/content/docs-ja"
 HAS_JA=""
 if [ -d "$DOCS_JA_DIR" ]; then
@@ -283,18 +430,60 @@ JAEOF
   echo "  [$target] Global symlink: $global_skills_dir/$SKILL_NAME"
 }
 
+# Symlink the site's OWN hand-written skills into the global skills dir
+# (zudolab/zudo-doc#3156). Discovery walks the target's own project skills
+# directory dynamically -- not a hard-coded list, so it stays correct as
+# sites add skills. Sources resolve through MAIN_PROJECT_DIR, not ROOT_DIR,
+# the same way the generated skill's docs/docs-ja symlinks do (see the
+# REPO_ROOT/MAIN_PROJECT_DIR comment above) so the links survive worktree
+# removal. Target-local only: each target walks only its own
+# ".$target/skills/" -- a missing directory is a silent no-op, and there is
+# no ".claude" -> ".codex" fallback.
+link_tracked_skills() {
+  local target="$1"
+  local skills_root="$MAIN_PROJECT_DIR/.$target/skills"
+  local global_skills_dir="$HOME/.$target/skills"
+
+  [ -d "$skills_root" ] || return 0
+
+  mkdir -p "$global_skills_dir"
+
+  local dir name
+  for dir in "$skills_root"/*/; do
+    [ -d "$dir" ] || continue
+    name="$(basename "$dir")"
+
+    # Skip the just-generated skill (already linked above via ensure_symlink)
+    # and the legacy doubled-suffix name (zudolab/zudo-doc#3154) -- otherwise
+    # a stale leftover directory left by that rename gets misread as a
+    # hand-written skill and exported globally, compounding both bugs.
+    [ "$name" = "$SKILL_NAME" ] && continue
+    [ "$name" = "$LEGACY_DEFAULT_SKILL_NAME" ] && continue
+
+    # A candidate qualifies only if it contains SKILL.md -- iterating every
+    # directory does not prove it is a skill.
+    [ -f "${dir}SKILL.md" ] || continue
+
+    safe_link_tracked_skill "$global_skills_dir/$name" "${dir%/}" "$name" "$target"
+  done
+}
+
 read -r -a TARGETS <<< "$(resolve_targets)"
 echo "Target: $TARGET_MODE -> ${TARGETS[*]}"
 echo ""
 
 for target in "${TARGETS[@]}"; do
   generate_skill "$target"
+  if [ "$LINK_TRACKED_SKILLS" = "true" ]; then
+    link_tracked_skills "$target"
+  fi
 done
 
 echo ""
 echo "Done! Skill '$SKILL_NAME' is ready."
 echo ""
 echo "Use --target claude, --target codex, or --target both to override auto-detection."
+echo "Use --no-link-tracked-skills to skip linking this project's own hand-written skills."
 echo "In Claude Code, use: /$SKILL_NAME <topic>"
 echo "In Codex, mention the skill by name when asking about this documentation."
 echo ""