docs: add plugin manager entrypoint injection notes

Co-authored-by: mcornella <1441704+mcornella@users.noreply.github.com>

README.md

@@ -361,7 +361,8 @@ source "$ZSH/lib/bootstrap.zsh"
 
 #### Bootstrap compatibility contract
 
-`lib/bootstrap.zsh` is idempotent and guarantees:
+`lib/bootstrap.zsh` is idempotent and is the only required pre-load step for plugin-manager setups.
+It guarantees:
 
 - `ZSH`, `ZSH_CUSTOM`, and `ZSH_CACHE_DIR` defaults
 - writable cache fallback to `${XDG_CACHE_HOME:-$HOME/.cache}/oh-my-zsh`
@@ -372,7 +373,7 @@ source "$ZSH/lib/bootstrap.zsh"
   - `$ZSH_CUSTOM/functions`
   - `$ZSH_CUSTOM/completions`
   - `$ZSH_CACHE_DIR/completions`
-- public signal: `OMZ_IS_BOOTSTRAPPED=true`
+- public signal: `OMZ_IS_BOOTSTRAPPED=true` (for one-time hook guards)
 
 What still requires `oh-my-zsh.sh`:
 
@@ -386,10 +387,61 @@ What still requires `oh-my-zsh.sh`:
 
 Run bootstrap once, before any OMZ plugin/theme load:
 
-- **Antigen:** add a one-time pre-bundle hook to source `lib/bootstrap.zsh`.
+```zsh
-- **Zinit:** use a pre-load/`atinit` hook for OMZ snippets/plugins.
+[[ -n "${OMZ_IS_BOOTSTRAPPED:-}" ]] || source "$ZSH/lib/bootstrap.zsh"
-- **zplug:** use a load hook (`hook-load`) before OMZ plugin/theme sourcing.
+```
-- **zgen / zulu:** source `lib/bootstrap.zsh` immediately before OMZ plugin/theme load lines.
+
+- **Antigen** (pre-bundle hook pattern):
+
+  ```zsh
+  omz_preload() { [[ -n "${OMZ_IS_BOOTSTRAPPED:-}" ]] || source "$ZSH/lib/bootstrap.zsh"; }
+  omz_preload
+  antigen bundle OMZ::plugins/git
+  antigen apply
+  ```
+
+- **Zinit** (`atinit` pre-load hook):
+
+  ```zsh
+  zinit ice atinit'[[ -n "${OMZ_IS_BOOTSTRAPPED:-}" ]] || source "$ZSH/lib/bootstrap.zsh"'
+  zinit snippet OMZ::plugins/git/git.plugin.zsh
+  ```
+
+- **zgen** (pre-load hook function called before OMZ loads):
+
+  ```zsh
+  omz_preload() { [[ -n "${OMZ_IS_BOOTSTRAPPED:-}" ]] || source "$ZSH/lib/bootstrap.zsh"; }
+  omz_preload
+  zgen load ohmyzsh/ohmyzsh plugins/git
+  ```
+
+- **zplug** (run pre-load hook immediately before OMZ entries):
+
+  ```zsh
+  omz_preload() { [[ -n "${OMZ_IS_BOOTSTRAPPED:-}" ]] || source "$ZSH/lib/bootstrap.zsh"; }
+  omz_preload
+  zplug "plugins/git", from:oh-my-zsh
+  zplug load
+  ```
+
+- **antibody** (run pre-load hook before `antibody bundle`/`source` output):
+
+  ```zsh
+  omz_preload() { [[ -n "${OMZ_IS_BOOTSTRAPPED:-}" ]] || source "$ZSH/lib/bootstrap.zsh"; }
+  omz_preload
+  source <(antibody bundle <<'EOF'
+  ohmyzsh/ohmyzsh path:plugins/git
+  EOF
+  )
+  ```
+
+- **zulu** (run pre-load hook before OMZ module loads):
+
+  ```zsh
+  omz_preload() { [[ -n "${OMZ_IS_BOOTSTRAPPED:-}" ]] || source "$ZSH/lib/bootstrap.zsh"; }
+  omz_preload
+  zulu install oh-my-zsh
+  ```
 
 Compatibility matrix:
 
@@ -398,6 +450,20 @@ Compatibility matrix:
 | `source $ZSH/oh-my-zsh.sh` | ✅ | ✅ | Full OMZ framework features |
 | `source $ZSH/lib/bootstrap.zsh` + manager-loaded OMZ plugins/themes | ✅ | ❌ | Plugin/theme prerequisites only |
 
+#### Manager entrypoints and OMZ-side auto-injection limits
+
+Most plugin managers load OMZ by directly sourcing selected plugin/theme/lib entrypoints, not by sourcing
+`oh-my-zsh.sh`, so OMZ cannot universally inject bootstrap on its own.
+
+| Manager | Typical OMZ entrypoint(s) it loads | Can OMZ auto-inject bootstrap without user hook? |
+| :-- | :-- | :--: |
+| Antigen | `antigen bundle ...` targets after `antigen use oh-my-zsh` | ❌ |
+| Zinit | `OMZ::`, `OMZL::`, `OMZP::`, `OMZT::` snippets | ❌ |
+| zgen | `zgen oh-my-zsh ...` selected OMZ paths | ❌ |
+| zplug | `from:oh-my-zsh` selected OMZ entries | ❌ |
+| antibody | `ohmyzsh/ohmyzsh path:...` selected OMZ paths | ❌ |
+| zulu | OMZ package/module entries selected by zulu | ❌ |
+
 ### Enable GNU ls In macOS And FreeBSD Systems
 
 <a name="enable-gnu-ls"></a>

plugins/docker/docker.plugin.zsh

@@ -48,10 +48,6 @@ fi
 0="${${ZERO:-${0:#$ZSH_ARGZERO}}:-${(%):-%N}}"
 0="${${(M)0:#/*}:-$PWD/$0}"
 
-# Ensure cache completions dir exists when the plugin is loaded directly
-# (e.g. antigen, where oh-my-zsh.sh might not run).
-command mkdir -p "$ZSH_CACHE_DIR/completions"
-
 # If the completion file doesn't exist yet, we need to autoload it and
 # bind it to `docker`. Otherwise, compinit will have already done that.
 if [[ ! -f "$ZSH_CACHE_DIR/completions/_docker" ]]; then