fix(loader): harden install and align XDG paths

.github/workflows/check-linux.yml

@@ -64,5 +64,3 @@ jobs:
           zmodload zi/zpmod
           zpmod source-study -l
         shell: zsh {0}
-      - name: "⚙️ Check: init.zsh sync drift"
-        run: sh public/sh/sync-init.sh --local ./public/zsh/init.zsh --remote ./public/zsh/init.zsh --checksum-url ./public/checksum.txt

.github/workflows/loader-drift.yml

@@ -0,0 +1,47 @@
+---
+name: Loader Drift
+# Verify that the published loader endpoint serves the same bytes as the
+# loader source on main.
+#
+# The former "init.zsh sync drift" step in check-linux.yml passed
+# --local and --remote as the same checked-out file, so it could never
+# detect drift. The meaningful comparison is repository source against the
+# published artifact, which only exists after a deployment.
+on:
+  workflow_run:
+    workflows: ["GitHub Pages"]
+    types: [completed]
+  schedule:
+    # Daily, offset off the hour to avoid the scheduler peak.
+    - cron: "17 6 * * *"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  published-loader:
+    name: Published loader matches source
+    if: github.repository == 'z-shell/src'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: ⤵️ Check out code from GitHub
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+      - name: "⚙️ Check: published loader endpoint"
+        run: |
+          sh ./public/sh/sync-init.sh \
+            --local ./public/zsh/init.zsh \
+            --remote https://init.zshell.dev \
+            --checksum-url ./public/checksum.txt
+      - name: "⚙️ Check: raw main loader endpoint"
+        run: |
+          sh ./public/sh/sync-init.sh \
+            --local ./public/zsh/init.zsh \
+            --checksum-url ./public/checksum.txt

docs/README.md

@@ -53,6 +53,42 @@
 - **Installer**: [get.zshell.dev](https://get.zshell.dev)
 - **jsDeliver CDN**: [cdn.jsdelivr.net/gh/z-shell/src@main/](https://cdn.jsdelivr.net/gh/z-shell/src@main/)
 
+### Loader configuration
+
+`public/zsh/init.zsh` defines `zzinit()`. Sourcing the file only declares the
+function and applies defaults; nothing is cloned, sourced, or written until
+`zzinit` is called.
+
+The loader owns only the settings that must exist before Zi does:
+
+| Setting             | Default                                      | Purpose                      |
+| ------------------- | -------------------------------------------- | ---------------------------- |
+| `ZI[REPOSITORY]`    | `https://github.com/z-shell/zi.git`          | Clone source                 |
+| `ZI[STREAM]`        | `main`                                       | Branch or tag to clone       |
+| `ZI[HOME_DIR]`      | Legacy home, otherwise XDG data `zi` root    | Working-directory root       |
+| `ZI[BIN_DIR]`       | `${ZI[HOME_DIR]}/bin`                        | Where `zi.zsh` is cloned     |
+| `ZI[MUTE_WARNINGS]` | `0`                                          | Loader warning control       |
+
+The loader mirrors Zi core's home-resolution contract because it must find or
+clone `zi.zsh` before core can run. An explicit `ZI[HOME_DIR]` wins. A
+recognized legacy `$HOME/.zi` installation stays active. Otherwise the loader
+uses `${XDG_DATA_HOME}/zi` when `XDG_DATA_HOME` is absolute, or
+`$HOME/.local/share/zi` when it is unset, empty, or relative. When both homes
+contain Zi data, an explicit or unique existing `BIN_DIR` identity selects the
+matching home; otherwise the conservative fallback is the legacy home. No
+automatic move or merge occurs.
+
+`ZI[CACHE_DIR]`, `ZI[CONFIG_DIR]`, and every other Zi path are owned and
+derived by `zi.zsh`. Set one in `.zshrc` before sourcing the loader to override
+it; do not add a duplicate default to the loader. See the
+[customization guide](https://wiki.zshell.dev/docs/guides/customization#customizing-paths).
+
+One loader-only toggle exists:
+
+| Setting               | Default | Purpose                                                     |
+| --------------------- | ------- | ----------------------------------------------------------- |
+| `ZI[LOADER_HISTORY]`  | `1`     | Set to `0` to leave `HISTFILE`/`SAVEHIST`/`HISTSIZE` alone   |
+
 ### Maintainer — Verify and Sync Loader
 
 Check whether the local `public/zsh/init.zsh` matches the canonical GitHub raw `main` copy:

public/checksum.txt

@@ -1,4 +1,4 @@
 6de66efba021ebcf462e7672577d9f6876f13db55691f04e7009ff7e78d658b8 public/sh/install_zpmod.sh
-6ee1ced1b73ab9d6f8a17e26505dd5de588b2a0af2832603ae04eb2866763ed9 public/sh/install.sh
+6e753a0314ba9f2e4f0a2c429798ca3767af4fb94c669e6923d161d6af7aa745 public/sh/install.sh
 08cc893ceb982fc99d17db1966c6c30790cc571e16e4f5392352d995f5252952 public/sh/sync-init.sh
-424d66dca9bc26dd225afa45ccf15e42c8cf1f9e5e68fa51b469969bb5d51901 public/zsh/init.zsh
+e5db3eb099daf0098bed263f4f1960adc9d3d0074a19260fae7ab3df8bf08573 public/zsh/init.zsh

public/sh/install.sh

@@ -102,8 +102,27 @@ fetch_to_file() {
   return 1
 }
 
+is_absolute_path() {
+  case "${1-}" in
+    /*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+zi_home_has_installation() {
+  [ -f "$1/bin/zi.zsh" ] ||
+    [ -d "$1/plugins" ] ||
+    [ -d "$1/snippets" ] ||
+    [ -d "$1/completions" ] ||
+    [ -d "$1/zmodules" ]
+}
+
 if [ "${AOPT}" = loader ]; then
-  ZI_CONFIG_DIR="${XDG_CONFIG_HOME:-${HOME}/.config}/zi"
+  if is_absolute_path "${XDG_CONFIG_HOME-}"; then
+    ZI_CONFIG_DIR="${XDG_CONFIG_HOME}/zi"
+  else
+    ZI_CONFIG_DIR="${HOME}/.config/zi"
+  fi
   loader_tmp="${WORKDIR}/init.zsh.tmp"
   command mkdir -p "${ZI_CONFIG_DIR}"
   set +e
@@ -124,7 +143,30 @@ if [ "${AOPT}" = loader ]; then
 fi
 
 if [ -z "${ZI_HOME-}" ]; then
-  ZI_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zi"
+  if is_absolute_path "${XDG_DATA_HOME-}"; then
+    _zi_data_base="${XDG_DATA_HOME}"
+  else
+    _zi_data_base="${HOME}/.local/share"
+  fi
+  _zi_legacy_home="${HOME}/.zi"
+  _zi_xdg_home="${_zi_data_base}/zi"
+  _zi_legacy_present=0
+  _zi_xdg_present=0
+  zi_home_has_installation "${_zi_legacy_home}" && _zi_legacy_present=1
+  zi_home_has_installation "${_zi_xdg_home}" && _zi_xdg_present=1
+
+  if [ "${_zi_legacy_present}" -eq 1 ] && [ "${_zi_xdg_present}" -eq 1 ]; then
+    if [ -f "${_zi_xdg_home}/bin/zi.zsh" ] && [ ! -f "${_zi_legacy_home}/bin/zi.zsh" ]; then
+      ZI_HOME="${_zi_xdg_home}"
+    else
+      ZI_HOME="${_zi_legacy_home}"
+      printf '%s\n' "Zi installer: both legacy and XDG homes were detected; retaining ${ZI_HOME}. Set ZI_HOME explicitly to select another root. No data was moved." >&2
+    fi
+  elif [ "${_zi_legacy_present}" -eq 1 ]; then
+    ZI_HOME="${_zi_legacy_home}"
+  else
+    ZI_HOME="${_zi_xdg_home}"
+  fi
 fi
 
 if [ -z "${ZI_BIN_DIR_NAME-}" ]; then
@@ -133,7 +175,7 @@ fi
 
 if ! test -d "${ZI_HOME}"; then
   command mkdir -p "${ZI_HOME}"
-  command chmod go-w "${ZI_HOME}"
+  command chmod 700 "${ZI_HOME}"
 fi
 
 if ! command -v git >/dev/null 2>&1; then
@@ -207,7 +249,7 @@ MAIN_PROFILE() {
 if [[ ! -f ${ZI_HOME}/${ZI_BIN_DIR_NAME}/zi.zsh ]]; then
   print -P "%F{33}▓▒░ %F{160}Installing (%F{33}z-shell/zi%F{160})…%f"
   command mkdir -p "${ZI_HOME}" && command chmod go-rwX "${ZI_HOME}"
-  command git clone -q --depth=1 --branch "${BOPT}" https://github.com/z-shell/zi "${ZI_HOME}/${ZI_BIN_DIR_NAME}" && \\
+  command git clone -q --filter=blob:none --single-branch --branch "${BOPT}" https://github.com/z-shell/zi "${ZI_HOME}/${ZI_BIN_DIR_NAME}" && \\
     print -P "%F{33}▓▒░ %F{34}Installation successful.%f%b" || \\
     print -P "%F{160}▓▒░ The clone has failed.%f%b"
 fi
@@ -221,9 +263,15 @@ EOF
   fi
   if [ "${AOPT}" = loader ] && [ "${ZOPT}" != skip ]; then
     command cat <<-EOF >>"${THE_ZDOTDIR}/.zshrc"
-if [[ -r "\${XDG_CONFIG_HOME:-\${HOME}/.config}/zi/init.zsh" ]]; then
-  source "\${XDG_CONFIG_HOME:-\${HOME}/.config}/zi/init.zsh" && zzinit
+if [[ -n \${XDG_CONFIG_HOME:-} && \${XDG_CONFIG_HOME} == /* ]]; then
+  ZI_LOADER_CONFIG_HOME="\${XDG_CONFIG_HOME}/zi"
+else
+  ZI_LOADER_CONFIG_HOME="\${HOME}/.config/zi"
+fi
+if [[ -r "\${ZI_LOADER_CONFIG_HOME}/init.zsh" ]]; then
+  source "\${ZI_LOADER_CONFIG_HOME}/init.zsh" && zzinit
 fi
+unset ZI_LOADER_CONFIG_HOME
 EOF
     printf '%s\n' "▓▒░ Loader added"
   fi