Maintenance and Verification

init.zsh sets the shared options, then sources modules in this order:

The numbered filenames define load order. 50-completion.zsh assumes an earlier layer already ran compinit; 66-compdefs.zsh becomes a silent no-op when compdef is unavailable.

The repo-local functions/ztheme, functions/_fbr_format_entry, lib/functions-*.zsh, lib/command-registry.zsh, lib/ui-width-data.zsh, lib/theme-*.zsh, lib/help-catalogue.zsh, and lib/tips-catalogue.zsh files are lazy implementation helpers rather than startup modules. The fbr row formatter requires an explicit canonical branch reference and rejects malformed identities. Their numbered modules register fixed loaders, while general command implementations, package workflows, command-only swatch/export logic, catalogues, fbr row formatting, palette data, validation, and color conversion code are parsed on first use. lib/upkg-registry.zsh is instead a lightweight registry sourced during startup by 60-functions.zsh and reused by 66-compdefs.zsh when compdef is available. A configured custom or colored non-default startup loads the theme pieces it needs before composing finder options.

Captured package queries execute the fixed trusted lib/query-supervisor.zsh entrypoint; its allowed callbacks and helper sources stay inside the repository.

General helpers load their fixed domain on first use: files/search, system diagnostics/network, Git, package orchestration/backend adapters, or Nix. Shared presentation fallbacks load once. Calling mkcd or path leaves package implementations unloaded; later calls use installed implementations directly. All paths remain fixed beneath the repository. Disk scanners collect records plus explicit state, diagnostics, and exit status before choosing a rich or plain renderer; both preserve partial-scan failures. lib/command-registry.zsh is data-only and shared by help and command-name completion; it records canonical names and descriptive mutation categories without authorizing any operation.

Keep each surface at one level:

Completed design plans and audits are retained in Git history; use this guide for current behavior.

When user-facing behavior changes, update every affected surface without copying long explanations between them.

• Startup-time dependency guards use (( $+commands[tool] )).
• Guards inside functions use command -v ... >/dev/null 2>&1 so PATH changes and test stubs are visible.
• Keep external integrations guarded and preserve fallbacks.
• Keep 50-completion.zsh lightweight and 80-tips.zsh hook-free.
• Never add a plaintext CGM fallback, value-retrieving completion, or eval-based secret export.
• Treat aliases in 20-aliases.zsh as high-impact changes.

Nix attribute completion reuses parsed names and the final ordered, deduplicated candidate list in the current session while the eligible file set and each file’s device, inode, size, and modification time match. These identities use filesystem timestamp granularity; same-size edits with preserved identities and timestamps are not content-hash checked. Replacing, adding, or removing cache files is reflected on the next completion. It never refreshes the index over the network.

Run the repository-owned ordered sequence:

zsh scripts/run-tests.zsh

The runner owns the syntax checks, regression suites, and fixed-install-path smoke test used by CI. Maintainers can regenerate width intervals with python3 scripts/generate-width-data.py; review the recorded Unicode version when doing so. A separate CI job runs python3 scripts/test-fzf-pty.py against real fzf 0.68.0 and 0.74.3. It covers shared picker arguments and actual fbr with one/two branches across all three layouts at 50/80/99/100/101/110/120 columns, including initial row visibility, filtering, preview toggles, and live resizing. Normal selection changes detached HEAD to the chosen branch; worktree selection changes directory; cancellation preserves the starting state. Unicode/ASCII, NO_COLOR, multi-selection, and measured frame sizing at 12/16/24 terminal rows are also checked. Preview-free widget/completion frame sizing is exercised through exported defaults; host keybinding and completion wiring remains part of manual QA. run-tests.zsh also runs it whenever python3 and fzf are installed and prints a skip line otherwise; set FZF_BIN when running the script directly to test another binary. Each PTY case isolates HOME, cache storage, and host finder options, including FZF_DEFAULT_OPTS_FILE; a hostile-options self-check covers both harnesses. These checks use fixture rows and perform no package mutations. run-tests.zsh also runs python3 scripts/test-upkg-pty.py whenever python3 is installed; it uses stubbed managers in a real PTY to check that upkg elapsed time includes a delayed answer to a native prompt and survives terminal Ctrl-C. skills-lock.json records maintainer skill provenance and is not a runtime dependency or package-manager lockfile.

The environment check is optional because it reflects the current machine rather than repository correctness:

$HOME/.config/zsh/scripts/check-deps.sh

Performance measurement is also optional and never a pass/fail gate. zsh scripts/benchmark-startup.zsh [iterations] measures warm command and interactive startup and requires the checkout at $HOME/.config/zsh. python3 scripts/benchmark-workloads.py times synthetic helper workloads: package parsing and search tables (plain, forced-rich, and real PTY), text width/truncation/padding, scan-record collection, Nix completion preparation, and fresh-shell startup from a private install copy. Each sample runs a fresh child with an allowlisted environment and private HOME/XDG directories; it uses no package manager, network, or Secret Service, and validates helper output before accepting timings: exact expected text for parser and width/truncation/padding workloads, and row, record, or candidate checks for the others. Use --baseline-ref REF to alternate an archived revision with the working tree on the same host and require identical helper output hashes (startup groups check only the exit status), --output FILE to keep raw JSON samples, and --self-test to check cleanup after failure, timeout, and interrupt. Compare only paired same-host runs:

python3 scripts/benchmark-workloads.py --workload parser --size 1000 --baseline-ref HEAD

For a full stable-release manual pass, use the ignored qa-features.csv checklist described in AGENTS.md.