⚡ Auto-Full Bundle Mode¶

📋 Auto-Full mode (ZSHAND_AUTO_FULL=1) automatically compiles and loads a single bundle containing all framework + user code. No manual compilation steps — it just works.

🚀 Quick Setup¶

Add to ~/.zshenv (not env.zsh or .zshrc):

export ZSHAND_AUTO_FULL=1

Or use the template:

cp ~/code/zshand/samples/zshenv/zshenv.template ~/.zshenv

Start a new shell. First run auto-compiles:

🔨 Auto-compiling full bundle (first run)...
→ Compiling zshand-full.zwc...
✓ Full bundle compiled successfully

Every subsequent shell start loads the cached bundle silently.

This flag must be set in ~/.zshenv because it's checked before the framework loads. Setting it in ~/.config/zshand/env.zsh creates a circular dependency (that file is inside the bundle).

🔄 How It Works¶

Shell starts → zshrc.zsh
  │
  ├─ FAST PATH (bundle cached)
  │    Check ZSHAND_AUTO_FULL=1 + bundle file exists?
  │    → YES: source bundle → done (~15-40ms)
  │
  └─ STANDARD PATH (first run or bundle missing)
       Load build functions → compile bundle → source bundle (~200-500ms)
       │
       └─ FALLBACK (compile fails)
            Standard hybrid loading proceeds → shell still works

Guard conditions (all must be true for auto-full):

• ZSHAND_AUTO_FULL=1
• ZSHAND_DEV_MODE=0 (not in dev mode)
• ZSHAND_AUDIT_MODE=0 (not in audit mode)

📦 What's in the Bundle¶

The compiled bundle includes everything in the correct load order:

🔀 Override Semantics¶

User files with the same basename completely replace framework files:

~/.config/zshand/functions/seek.zsh  →  overrides $ZSHAND/functions/seek.zsh
~/.config/zshand/widgets/aicmit.zsh  →  overrides $ZSHAND/widgets/aicmit.zsh
~/.config/zshand/rc.d/14_aliases.zsh →  overrides $ZSHAND/core/14_aliases.zsh

Files with unique basenames are added alongside framework files.

⚡ Performance¶

The fast path skips loading build infrastructure entirely when the bundle is already cached, saving ~10ms per shell start.

🔄 When to Recompile¶

The bundle is compiled once and reused. Recompile when you change anything:

# After modifying user config (aliases, functions, hooks, etc.)
zrecompile user

# After updating the framework (git pull)
zrecompile framework

# After changing both
zrecompile both

# Full manual rebuild
zfull

Or delete the cache and let auto-full recompile on next start:

rm ~/.cache/zshand/zshand-full.{zsh,zwc}
exec zsh

📊 Comparison with Other Modes¶

🚫 When It's Skipped¶

Auto-full is automatically bypassed in these situations:

• Dev mode — ZSHAND_DEV_MODE=1 or .dev file exists (you want raw file loading)
• Audit mode — ZSHAND_AUDIT_MODE=1 (needs full recompile + test cycle)
• Explicitly disabled — ZSHAND_AUTO_FULL=0 or unset

🔧 Troubleshooting¶

Bundle fails to compile¶

✗ Auto-compilation failed. Falling back to standard loading.

Causes: Missing config directory, syntax errors in user files, disk full.

Fix:

1. Check config dir exists: ls -la ~/.config/zshand
2. Test compilation manually: zfull
3. Check syntax: zsh -n ~/.config/zshand/rc.d/*.zsh

Functions missing after adding new files¶

The bundle was compiled before you added the files. Recompile:

zrecompile user    # or: zfull
exec zsh

Want fresh bundle every start¶

Don't use auto-full. Instead:

# In ~/.zshenv
export ZSHAND_USE_MONOLITHIC=1

# Then manually run before each session:
zfull && exec zsh

🔗 Related Documents¶