🏗️ ZSHAND Architecture¶

🎯 This document describes how the framework is structured, how it boots, how bundles work, and how user configuration integrates. Read this first if you're new to the codebase.

!!! abstract "🧠 Design Principles" - ⚡ Performance first — target <50ms cold start, <10ms warm - 🧩 Modular — every directory is independently compilable - 🔄 Override-friendly — users can replace any framework file - 🛡️ Fail-safe — graceful degradation at every layer - 📐 Convention-driven — numbered prefixes enforce load order

📁 Directory Structure¶

zshand/
├── 🎯 zshrc.zsh                 Entry point (sourced by ~/.zshrc)
├── 🎯 setup.zsh                 First-time bootstrap & OS setup
├── 📦 build/                    Build system & profiling tools
│   ├── compile_full_bundle.zsh  Full bundle compiler
│   ├── compile_profile_bundle.zsh  Profiling-instrumented compiler
│   ├── profile_bundle_report.zsh   Performance report generator
│   └── ...                      Benchmarking, optimization, loading
├── ⚙️ core/                     Framework core (numbered 02–90)
│   ├── 02_vars.zsh              Variables & identity (FIRST loaded)
│   ├── 04_path.zsh              PATH construction
│   ├── 06_engine.zsh            Execution engine (zprime, zrun)
│   ├── 08_audit.zsh             System integrity & telemetry
│   ├── 10_options.zsh           Zsh options (setopt)
│   ├── 12_completions.zsh       Completion system
│   ├── 14_aliases.zsh           Shell aliases
│   ├── 16_widgets.zsh           ZLE widget registration
│   ├── 18_hooks.zsh             Hook classification & loading
│   ├── 20_plugins.zsh           Plugin management
│   └── 90_functions.zsh         Function autoloading
├── 🧱 shared_functions/         Low-level utilities (01–18)
│   ├── 01_stderr_error.zsh      Error output to stderr
│   ├── 06_time_millis.zsh       Millisecond timing
│   ├── 11_source_with_zwc.zsh   Bytecode-aware sourcing
│   ├── 15_load_file_timed.zsh   Timed file loading with budget
│   ├── 16_zrun.zsh              Telemetry logging
│   ├── 17_clipboard_copy.zsh    Wayland clipboard abstraction
│   └── ...                      Assertions, debug helpers, cache
├── 🚀 startup/                  Early startup scripts (05–28)
│   ├── 05_az_dev_mode_check.zsh Auto-rebuild in dev mode
│   ├── 21_az_health_validate_tools.zsh  Dependency validation
│   ├── 24_az_safe_mode.zsh      Emergency recovery
│   └── ...                      TOML config, keybindings, profiling
├── 🛠️ functions/                User-facing shell functions
│   ├── dcopy.zsh                Copy directory path to clipboard
│   ├── zopt.zsh                 Zsh option management
│   └── ...                      ~25 utility functions
├── ⌨️ widgets/                   ZLE widgets (keybinding-driven)
│   ├── aicmit.zsh              AI-assisted git commit
│   ├── aidebug.zsh             AI debugging assistant
│   └── ...                      ~20 interactive widgets
├── 🪨 hooks/                    Tool integration hooks (01–81)
│   ├── 01_mise.zsh             Polyglot runtime manager
│   ├── 02_atuin.zsh            Shell history sync
│   ├── 05_ssh-agent.zsh        SSH agent management
│   └── ...                      Docker, zoxide, git identity
├── 📟 bin/                      Executable CLI tools (on $PATH)
│   ├── aicontext                AI context generator
│   ├── zr                       Framework rebuild shortcut
│   └── ...                      ~30 standalone scripts
├── 🔐 private_functions/        Internal framework functions
├── 📚 lib/                      Library support modules
│   └── rebuild/                 Incremental rebuild logic
├── ⚙️ config/                   Framework-level configuration
│   └── profile-exceptions.conf  Performance exception rules
├── 📥 installers/               OS-specific system installers
├── 🧪 tests/                    ShellSpec test suites
├── 📖 docs/                     Documentation (this file lives here)
└── 📂 samples/                  Example user config templates

📏 Numbering Convention¶

Files are numbered with 2-digit prefixes to enforce deterministic load order:

Range	Purpose	Example
`01–09`	🧱 Foundation / bootstrap	`02_vars.zsh`, `01_mise.zsh`
`10–19`	⚙️ Core configuration	`10_options.zsh`, `14_aliases.zsh`
`20–29`	🔌 Plugins & integrations	`20_plugins.zsh`, `20_docker.zsh`
`30–49`	🛠️ Mid-priority tools	`30_zoxide.zsh`
`50–79`	📦 Optional / less critical	`50_gitid.zsh`
`80–89`	🧹 Cleanup & maintenance	`80_archclean.zsh`
`90–99`	🏁 Late-stage / finalization	`90_functions.zsh`

💬 Even numbers are used by the framework. Odd numbers are reserved for user insertion (e.g., user can place 03_my_vars.zsh in rc.d/).

🚀 Boot Sequence¶

The boot process is orchestrated by zshrc.zsh and follows a strict phase order. Multiple loading strategies exist depending on the mode:

┌─────────────────────────────────────────────────────────────────┐
│                    zshrc.zsh Entry Point                        │
├─────────────────────────────────────────────────────────────────┤
│  0. 🚫 Non-interactive check (early exit for scripts/cron)     │
│  1. 📁 Path & cache initialization                             │
│  2. 🔀 Loading strategy selection (see below)                  │
│  3. 🎨 P10k instant prompt (zero-latency visual)               │
│  4. 🛡️ Safe mode check (emergency recovery)                    │
│  5. ✅ Health validation (system dependencies)                  │
│  6. ⚙️ Core config loading (02→04→06→08→...→90)                │
│  7. 🪨 Hook integration (critical sync, then lazy/deferred)    │
│  8. 🔍 Staleness check & auto-recompile                        │
│  9. 👤 User post.d/ scripts                                    │
│ 10. 📊 Debug summary & cleanup                                 │
└─────────────────────────────────────────────────────────────────┘

🔀 Loading Strategies¶

The framework picks the fastest available strategy at boot:

Priority	Strategy	Trigger	Speed	Use Case
1️⃣	Profile Bundle	`ZSHAND_PROFILE_BUNDLE=1`	~100ms	Performance analysis
2️⃣	Full Bundle (fast path)	`ZSHAND_AUTO_FULL=1` + bundle exists	⚡ <50ms	Production (fastest)
3️⃣	Full Bundle (auto-compile)	`ZSHAND_AUTO_FULL=1` + no bundle	~200ms first, then ⚡	First run
4️⃣	Monolithic Bundle	`ZSHAND_USE_MONOLITHIC=1`	~60ms	Framework-only bundle
5️⃣	Hybrid	Production default	~80ms	Pre-compiled per-dir bundles
6️⃣	Individual Files	`ZSHAND_DEV_MODE=1` or fallback	~200ms	Development / debugging

Which mode am I in?

Check echo $ZSHAND_DEV_MODE and echo $ZSHAND_AUTO_FULL. In production, the fast path loads a single .zsh file from cache — everything in one read.

📦 Bundle System¶

Bundles are the core performance optimization. The build system concatenates framework + user files into a single source file, then zcompiles it to .zwc bytecode for instant loading.

📊 Bundle Types¶

Bundle	File	Contains	Built By
🏗️ Full	`zshand-full.zsh` / `.zwc`	Framework + user config	`compile_full_bundle.zsh`
📊 Profile	`zshand-profile.zsh` / `.zwc`	Full + timing instrumentation	`compile_profile_bundle.zsh`
📂 Per-directory	`<dir>/.compiled/<dir>-all.zsh`	Single directory contents	`compile_single_directory.zsh`

🔄 Bundle Compilation Flow¶

Source Files  ──→  Merge (user overrides)  ──→  Concatenate  ──→  .zsh  ──→  zcompile  ──→  .zwc
                         ↑                                                        │
              User config dir files                                    Bytecode (instant load)
              override framework files
              with same basename

⚡ Compilation Commands¶

Command	What It Does
`zprime`	Compile all directories + reload shell
`zprime --quiet` / `zrq`	Background compilation (no output)
`zprime --full` / `zfull`	Compile full bundle
`zprime-dir <dir>`	Rebuild single directory
`zr`	Alias for `zprime` (convenience)

Bundle staleness

Bundles are checked for staleness at boot. If source files are newer than the compiled bundle, you'll see a warning. Run zprime to rebuild.

🔄 Override System¶

Users can override any framework file by placing a file with the same basename in their config directory. The merge resolution is:

Framework: $ZSHAND/core/14_aliases.zsh
User:      $ZSHAND_CONFIG_DIR/rc.d/14_aliases.zsh   ← wins (replaces framework)

📁 User Config Directory¶

~/.config/zshand/                   ($ZSHAND_CONFIG_DIR)
├── env.zsh           🌍 Environment variables (auto-exported)
├── secrets.zsh       🔒 API keys and tokens (chmod 600)
├── aliases.zsh       📝 Custom aliases
├── path.txt          🛤️ Additional PATH entries (one per line)
├── config.toml       ⚙️ Framework behavior settings
├── bin/              📟 Personal scripts (added to $PATH)
├── functions/        🛠️ Custom functions (override or extend)
├── widgets/          ⌨️ Custom ZLE widgets
├── hooks/            🪨 Custom integration hooks
├── rc.d/             ⚙️ Core config overrides (same numbering as core/)
├── init.d/           🚀 Pre-initialization (before framework loads)
└── post.d/           🏁 Post-initialization (after everything)

📊 User File Load Order¶

1. init.d/*.zsh          Before framework (early overrides)
2. env.zsh + secrets.zsh Environment variables
3. path.txt + bin/       PATH configuration
4. Framework core (merged with rc.d/ overrides)
5. Framework hooks, functions, widgets
6. User hooks/, functions/, widgets/
7. aliases.zsh           Custom aliases (can override framework)
8. post.d/*.zsh          Final tweaks

⚙️ Key Subsystems¶

🔧 Engine (`core/06_engine.zsh`)¶

The engine is the largest and most critical core module. It provides:

zprime — Framework compilation and shell reload
zrun — Telemetry-aware command execution wrapper
_z_system_init — System initialization (Atuin, security, terminal title)
Incremental rebuilds — Only recompile changed directories
Completion generation — Atomic completion for external tools

🧱 Shared Functions (`shared_functions/`)¶

These are the lowest-level building blocks, loaded before everything else. They provide the primitives that all other code depends on:

Function	Purpose
`stderr_error` / `stderr_warn`	Colored error/warning output
`echo_info` / `echo_ok`	Status messages
`time_millis`	Millisecond-precision timing
`assert_dir_exists` / `assert_file_exists` / `assert_function_exists`	Guard assertions
`source_with_zwc`	Bytecode-aware file sourcing
`load_file_timed`	Source file with timing + performance budget
`_zrun`	Low-level telemetry logging
`clipboard_copy` / `clipboard_paste`	Wayland clipboard abstraction

🛡️ Safe Mode (`startup/24_az_safe_mode.zsh`)¶

Emergency recovery when the framework fails to initialize:

Triggered by ZSHAND_SAFE_MODE=1 exec zsh or auto-detected via failure count
Provides minimal shell with basic PATH and no framework
Recovery menu for diagnostics and repair

📊 Profiling Pipeline¶

ZSHAND_PROFILE_BUNDLE=1 exec zsh     ← Start profiled shell
      │
      ▼
compile_profile_bundle.zsh            ← Builds instrumented bundle
      │
      ▼
profile-timing.log                    ← Raw timing data (TYPE|NAME|START|END)
      │
      ▼
profile_bundle_report.zsh            ← Generates graded performance report
      │
      ▼
Terminal output with grades A–F       ← Human-readable with bar charts

🪨 Hook Classification¶

Hooks are classified by core/18_hooks.zsh into two categories:

Type	Loading	Purpose	Examples
⚡ Critical	Synchronous (immediate)	Must be ready at first prompt	`01_mise`, `02_atuin`, `05_ssh-agent`
🕐 Lazy	Deferred (1s delay) or sync	Can wait until after prompt	`20_docker`, `30_zoxide`, `50_gitid`

When ZSHAND_LAZY_LOAD=1, non-critical hooks load in a background subshell after a 1-second delay, keeping the prompt responsive.

🧪 Testing Architecture¶

tests/
├── run_all.zsh              Master test runner
├── bootstrap_env.zsh        Test environment setup
├── bin/                     bin/* tool tests
├── build/                   Build system tests
├── core/                    Core module tests
└── dependencies/            Dependency validation tests

Framework: ShellSpec (BDD-style Describe/It blocks)
Coverage: Kcov via CI
Runner: just test or just test spec/path/
Spec mirroring: functions/dcopy.zsh → spec/functions/dcopy_spec.sh

🌍 Environment Variables¶

🎛️ Framework Controls¶

Variable	Type	Default	Purpose
`ZSHAND`	string	auto-detected	Framework root directory
`ZSHAND_CONFIG_DIR`	string	`$XDG_CONFIG_HOME/zshand`	User config directory
`ZSHAND_CACHE_DIR`	string	`$XDG_CACHE_HOME/zshand`	Cache & compiled bundles
`ZSHAND_LOG_DIR`	string	`$HOME/logs/zshand`	Log file directory
`ZSHAND_DEV_MODE`	bool	`0`	Enable development mode
`ZSHAND_AUTO_FULL`	bool	`0`	Auto-compile full bundle
`ZSHAND_DEBUG`	bool	`0`	Verbose debug output
`ZSHAND_PROFILE_BUNDLE`	bool	`0`	Enable profiling
`ZSHAND_LAZY_LOAD`	bool	`0`	Defer non-critical hooks
`ZSHAND_SAFE_MODE`	bool	`0`	Emergency recovery mode
`ZSHAND_AUDIT_MODE`	bool	`0`	Full audit (recompile + test)
`ZSHAND_PERF_BUDGET`	int	`100`	Max ms per file before warning

🔑 XDG Compliance¶

The framework follows the XDG Base Directory Specification:

XDG Variable	ZSHAND Maps To	Default
`XDG_CONFIG_HOME`	`ZSHAND_CONFIG_DIR`	`~/.config/zshand`
`XDG_CACHE_HOME`	`ZSHAND_CACHE_DIR`	`~/.cache/zshand`
`XDG_DATA_HOME`	—	(not currently used)

📐 Dependency Graph¶

zshrc.zsh
  ├── shared_functions/*    (loaded FIRST — primitives for everything)
  ├── startup/*             (loaded with shared_functions, alphabetically merged)
  ├── build/detect_dev_mode.zsh  (if not using bundle)
  ├── core/02_vars.zsh      ← no deps (self-sufficient bootstrap)
  │   └── core/04_path.zsh  ← depends on 02_vars (ZSHAND, config paths)
  │       └── core/06_engine.zsh  ← depends on 02, 04 (paths, vars)
  │           └── core/08_audit.zsh  ← depends on 02, 06 (LOG_DIR, _zrun)
  │               └── core/10_options.zsh → 12 → 14 → 16 → 18 → 20 → 90
  ├── hooks/*               (after core; classified by 18_hooks.zsh)
  ├── P10k theme            (after bundles, before user config)
  └── post.d/*              (last — user final overrides)

Circular dependency prevention

shared_functions/ and startup/ are loaded before any core/ files. Core files load in strict numeric order. No file may depend on a higher-numbered file in the same directory.

Document	Purpose
📐 HEADER_STANDARD.md	Documentation header conventions
📖 README.md	Project overview and quick start
🏗️ build/README.md	Build system documentation
📂 samples/user-config/README.md	Example user configuration

🏗️ ZSHAND Architecture¶

📁 Directory Structure¶

📏 Numbering Convention¶

🚀 Boot Sequence¶

🔀 Loading Strategies¶

📦 Bundle System¶

📊 Bundle Types¶

🔄 Bundle Compilation Flow¶

⚡ Compilation Commands¶

🔄 Override System¶

📁 User Config Directory¶

📊 User File Load Order¶

⚙️ Key Subsystems¶

🔧 Engine (core/06_engine.zsh)¶

🧱 Shared Functions (shared_functions/)¶

🛡️ Safe Mode (startup/24_az_safe_mode.zsh)¶

📊 Profiling Pipeline¶

🪨 Hook Classification¶

🧪 Testing Architecture¶

🌍 Environment Variables¶

🎛️ Framework Controls¶

🔑 XDG Compliance¶

📐 Dependency Graph¶

🔗 Related Documents¶

🔧 Engine (`core/06_engine.zsh`)¶

🧱 Shared Functions (`shared_functions/`)¶

🛡️ Safe Mode (`startup/24_az_safe_mode.zsh`)¶