From b68623a782e0848ff1dea78b8603ebba1bcf12da Mon Sep 17 00:00:00 2001
From: alvinlollo <alvin.vilaythong@gmail.com>
Date: Sun, 11 Oct 2026 18:08:30 +1100
Subject: [PATCH] docs: Document the zsh-autocomplete partial-load error and
 fixes

Adds a Troubleshooting entry (symptom, cause, drop-or-keep fixes). The
keep path removes grml-zsh-config instead of setting
skip_global_compinit=1: grml's /etc/zsh/zshrc runs compinit
unconditionally and ignores that Debian/Ubuntu variable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                 | 52 ++++++++++++++++++++++++++++++++++++++-
 airootfs/root/.zshrc-skel |  5 ++--
 2 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index abeabdb..98f93d3 100644
--- a/README.md
+++ b/README.md
@@ -230,7 +230,7 @@ Cross-shell prompt config for [Starship](https://starship.rs/). Works with both
 
 ### **.zshrc / .fzf.zsh**
 
-Zsh configuration adapted for oh-my-zsh (installed by `customize_airootfs.sh`) and fzf shell integration.
+Zsh configuration adapted for oh-my-zsh (installed by `customize_airootfs.sh`) and fzf shell integration. fish is the default login shell; zsh is there if you `chsh` to it. The `.zshrc` source lives at `airootfs/root/.zshrc-skel`, because grml-zsh-config owns `/etc/skel/.zshrc` and shipping it under `airootfs/etc/skel/` would abort the build. zsh-autocomplete is cloned but disabled; see [Troubleshooting](#zsh-autocomplete-partial-load-error).
 
 ---
 
@@ -437,6 +437,56 @@ The following dotfiles are not yet included but are planned for future versions:
 - `customize_airootfs.sh` clones repos at build time — requires network access during `mkarchiso`
 - Check build logs for git clone failures
 
+### zsh-autocomplete partial-load error
+
+Symptom:
+
+```
+_autocomplete__history_lines: function not defined
+_autocomplete__unambiguous: function not defined
+```
+
+Cause: zsh-autocomplete was loaded after `compinit` (e.g. via oh-my-zsh
+`plugins=(...)`), a stale completion dump, or a conflict with
+zsh-autosuggestions / zsh-history-substring-search. On this ISO `compinit`
+always runs first: grml-zsh-config's global `/etc/zsh/zshrc` calls it
+unconditionally before `~/.zshrc` is read.
+
+The shipped `~/.zshrc` leaves zsh-autocomplete out of `plugins=(...)`. The
+plugin stays cloned at `~/.oh-my-zsh/custom/plugins/zsh-autocomplete/`
+either way, just disabled by default.
+
+**Fix: drop autocomplete (recommended)**
+
+```bash
+# 1. Edit ~/.zshrc, remove this line from plugins=(...):
+#    zsh-autocomplete
+
+# 2. Clear stale dumps (bash avoids zsh's nomatch abort on the glob):
+bash -c 'rm -f ~/.zcompdump* ~/.cache/zsh/zcompdump*'
+
+# 3. Restart the shell and verify:
+exec zsh
+typeset -f _autocomplete__history_lines >/dev/null && echo "still loaded" || echo "clean"
+```
+
+**Fix: keep autocomplete instead**
+
+```bash
+# 1. Remove zsh-autocomplete, zsh-autosuggestions and
+#    zsh-history-substring-search from plugins=(...) in ~/.zshrc.
+
+# 2. Stop the global compinit. `skip_global_compinit=1` in ~/.zshenv does
+#    NOT work here (that is a Debian/Ubuntu /etc/zsh/zshrc convention; grml
+#    ignores it), so remove the package that ships the global zshrc:
+sudo pacman -R grml-zsh-config
+
+# 3. At the very top of ~/.zshrc, before oh-my-zsh is sourced:
+source ~/.oh-my-zsh/custom/plugins/zsh-autocomplete/zsh-autocomplete.plugin.zsh
+
+# 4. Clear dumps as above, then: exec zsh
+```
+
 ---
 
 ## Acknowledgements
diff --git a/airootfs/root/.zshrc-skel b/airootfs/root/.zshrc-skel
index 9e61eba..95773cb 100644
--- a/airootfs/root/.zshrc-skel
+++ b/airootfs/root/.zshrc-skel
@@ -7,8 +7,9 @@ zstyle ':omz:update' mode reminder # never auto-pull on startup
 
 # Plugins are pre-cloned into $ZSH/custom/plugins at ISO build time.
 # zsh-syntax-highlighting must load before zsh-history-substring-search.
-# zsh-autocomplete is cloned too but left off: it fights grml's compinit
-# and zsh-autosuggestions - add it here only if you drop those.
+# zsh-autocomplete is cloned too but left off: it must load before compinit,
+# which grml's /etc/zsh/zshrc already ran, and it fights zsh-autosuggestions.
+# To use it anyway, see README.md "zsh-autocomplete partial-load error".
 plugins=(
   git
   fzf-zsh-plugin