⚙️ ZSHAND Core Modules¶

📋 Core modules are the heart of the framework — they run after startup and before user post.d. They configure PATH, shell options, completions, aliases, widgets, hooks, plugins, and function autoloading. Load order is strictly numeric (02 → 04 → … → 90).

🔗 Related documents¶

In this doc: Module reference → Numbering → Module details → User overrides (rc.d/)

Generated docs for each file (dependencies, usage) live under Source → api (e.g. source/core/06_engine.md). Run just docs-api after changing headers.

Put a file in ~/.config/zshand/rc.d/ with the same basename (e.g. 14_aliases.zsh) to replace a core module. Different name = add in order. Full layout: Config.

📂 Module Reference¶

🔢 Numbering Scheme¶

Gaps between even numbers allow user scripts to interleave:

02_vars.zsh        ← framework
03_my_early.zsh    ← user (rc.d/)
04_path.zsh        ← framework
05_my_paths.zsh    ← user (rc.d/)
06_engine.zsh      ← framework

📊 Module Details¶

02_vars.zsh — Variables & Config¶

First module loaded. Establishes:

• Core paths (ZSHAND, PROJECT_ROOT)
• XDG directories (XDG_CONFIG_HOME, XDG_CACHE_HOME, etc.)
• User config loading (config.toml, env.zsh, secrets.zsh)
• Shell defaults and framework flags
• Self-sufficient — no dependencies on other core modules

04_path.zsh — PATH Construction¶

Builds $PATH from:

• Framework bin/ directory
• User bin/ directory
• Entries from path.txt (one per line)
• System defaults

06_engine.zsh — Build & Runtime Engine¶

The framework's engine. Provides:

• zprime / zr — Rebuild and compile framework bundles
• zrun — Telemetry-aware command execution with logging
• _z_system_init — Security enforcement, terminal titles
• Atuin daemon lifecycle management
• .zwc bytecode compilation

08_audit.zsh — Integrity & Telemetry¶

System integrity and telemetry:

• zcheck — Framework health audit (bundles, permissions, deps)
• zfail — Query recent failures from telemetry
• zsearch — Search telemetry by pattern
• zpulse — Session summary (commands, success rate)

10_options.zsh — Shell Options¶

Sets zsh behavior:

• AUTO_CD, CORRECT, EXTENDED_GLOB
• History configuration (size, dedup, sharing)
• Completion options

12_completions.zsh — Tab Completion¶

Configures the completion system:

• compinit initialization
• Completion styles (menu, matching, grouping)
• Cache directory setup

14_aliases.zsh — Aliases¶

Built-in aliases for common operations. User aliases in ~/.config/zshand/aliases.zsh load after this and can override.

16_widgets.zsh — Widget Loader¶

Loads ZLE widgets from widgets/ and user widgets/. Applies keybindings from config.toml via _az_bindkey_from_toml.

18_hooks.zsh — Hook Classifier¶

Classifies hooks as critical (sync) or lazy (deferred) and loads them. See HOOKS.md for details.

20_plugins.zsh — Plugin Manager¶

Loads Powerlevel10k theme, zsh-syntax-highlighting, and zsh-autosuggestions.

90_functions.zsh — Function Loader¶

Loads all function files from functions/ and user functions/, with override semantics (user files replace framework files with the same basename).

🔀 User Overrides (rc.d/)¶

Place files in ~/.config/zshand/rc.d/:

• Same filename → replaces framework module entirely
• Different filename → both load in numeric order

# Override framework aliases completely
~/.config/zshand/rc.d/14_aliases.zsh

# Add custom options between vars and path
~/.config/zshand/rc.d/03_my_options.zsh

🔗 Related Documents¶