Migrate devboost's default zsh plugin manager from znap to zinit

[rolfsormo]

Motivation

Discovered while debugging a slow real-machine zsh startup: the machine had both
devboost's own znap (loading zsh-users/zsh-autosuggestions and
zsh-users/zsh-syntax-highlighting) and a separately pre-existing zinit setup
(loading zdharma-continuum/fast-syntax-highlighting, zsh-users/zsh-autosuggestions,
zsh-users/zsh-completions, plus several zinit annexes) active at the same time.

zprof showed zinit-related plugin loading at ~55% of total (already-fast, ~60ms)
shell init time, with znap's own loading on top of that — clearly redundant, and a
plausible contributor to the user's still-not-instant shell startup.

Decision from conversation: zinit is the more feature-complete option (the user's
own hand-tuned setup already relies on it, including zsh-completions and multiple
annexes that znap doesn't have equivalents for) — so rather than just detecting the
conflict and asking the user to pick one, devboost should migrate its own default to
zinit, matching what real users are already reaching for.

Scope

This is a real default-behavior change, not a quick swap:

• Rewrite modules/module_znap.sh → modules/module_zinit.sh (different install
  method: zinit self-installs via its own bootstrap, not a plain git clone like
  znap).
• Update modules/module_zsh.sh's generated .zshrc.devboost content — zinit's
  config style (zinit light, ice-modifiers like zinit ice wait lucid, etc.) is
  meaningfully different from znap's simpler znap source API. Need to decide how
  much of zinit's turbo-mode/lazy-loading features devboost should turn on by default
  (could itself reduce startup time further, e.g. wait lucid deferred loading).
• Update .devboost.yaml.example (currently has znap_path, znap_git config keys
  under zsh:).
• Update README's tool list and ARCHITECTURE.md.
• Update/add tests (currently tests/test-macos.sh etc. don't specifically assert on
  which plugin manager is used, but any config-content assertions may need updates).
• Decide: does devboost detect an existing znap install on a user's machine (from a
  previous devboost version) and migrate it, or is this a clean cutover with a
  migration note in CHANGELOG/README for existing users?
• Add a doctor check (in the health-check module, once it exists — see related issue)
  that warns if another zsh plugin manager (oh-my-zsh, antidote, zplug, or a stray
  znap left over from before this migration) is active alongside zinit, same pattern
  as the oh-my-zsh detection.

Relates to

• module_health.sh environment health checks issue
• zsh startup slowness investigation issue

[rolfsormo]

Update (2026-08-05): scope correction + new detail from re-investigation

Re-read this issue against a closer look at the actual machine's ~/.zshrc /
~/.zshrc.devboost. One framing correction and a couple of new details worth folding
into the eventual implementation:

Framing correction: the original description frames this as "devboost's znap"
vs. "a separately pre-existing zinit" as two peer plugin managers in conflict. In
practice the pre-existing zinit setup isn't a peer devboost needs to defer to or
detect-and-ask-about — it's literally loading the same two plugins znap already
loads (zsh-users/zsh-autosuggestions, and a syntax-highlighting plugin — zinit's is
zdharma-continuum/fast-syntax-highlighting, znap's is
zsh-users/zsh-syntax-highlighting, different forks of the same feature). So this
isn't "which manager does the user prefer," it's "this specific machine has dead
weight left over from before devboost was adopted, running before devboost's own
managed block even starts."

New detail — this isn't just a plugin-manager problem: the same pre-existing
~/.zshrc also runs asdf (. /opt/homebrew/opt/asdf/libexec/asdf.sh) alongside
devboost's own mise activate zsh. Two version managers, redundant PATH/shim setup,
same shape of problem as the plugin managers. Worth deciding whether the tool this
issue produces should be scoped narrowly to "zsh plugin managers" or broadened to
"legacy shell tooling that devboost's own modules already superseded" (version
managers being the obvious second case, prompt frameworks a likely third).

On implementation approach (per conversation just now): this needs to be a
different kind of module than devboost's existing ones — existing modules only
write to devboost-managed blocks/files, they don't need to reach into and modify
arbitrary pre-existing user config outside those markers. A "detect legacy tooling
predating devboost adoption and offer/perform migration" capability is closer to what
the oh-my-zsh removal path already does (migrate-from-oh-my-zsh) than to a normal
db_module_*_apply. Worth checking whether this can reuse that migration
infrastructure/pattern rather than inventing a new one — and whether it belongs under
the module_health.sh doctor-check umbrella (detection) with a separate opt-in
migration command (action), same split as oh-my-zsh.

Decision needed before implementation: fix this specific machine by hand first and
learn from that, or build the general detect-and-fix tool first and test it against
this machine as the first real target (safe either way since it can also be tested
against a throwaway fixture $HOME, same pattern as oh-my-zsh testing). Leaning
toward the latter — build general, validate against this machine — see issue
discussion.

Relates to #5 (startup slowness) and #3 (health-check module — likely home for the
detection half of this).

[rolfsormo]

Update: benchmark data contradicts this issue's core premise

A periodic adversarial re-review of devboost's tool choices (2026-08-08, see docs/tool-choice-review-2026-08.md) specifically re-examined this proposal against reproducible benchmark data, not just the conflict investigation that originally motivated it.

The problem: this issue's premise — "the user's own hand-tuned setup already relies on zinit, so zinit must be the better/faster choice" — is contradicted by controlled speed benchmarks. Two independent, reproducible suites:

• rossmacarthur/zsh-plugin-manager-benchmark (Docker + hyperfine, 23 real plugins, no turbo-mode tricks): antidote and sheldon land in the top, statistically-indistinguishable tier. zinit lands in the "notably bad load time" tier, alongside zplug.
• zsh-bench: zinit can match antidote's first-prompt latency, but only with every plugin hand-annotated with wait/lucid ice-modifiers — not the naive/easy configuration path a devboost-generated config would take by default.

znap itself appears in neither benchmark suite — there's no third-party-verified speed number for it at all, only its own README claims. So the honest state is: znap's speed is unverified, and zinit (as this issue currently scopes the migration) would likely be slower than znap in practice, not faster — unless devboost also implements per-plugin turbo-mode config generation, which is materially more scope than this issue currently accounts for.

Recommendation from the review: don't migrate to zinit as currently scoped. If devboost migrates away from znap at all, evaluate antidote first (static-bundle architecture — generates a plain .zsh_plugins.zsh once, zero runtime plugin-manager parsing overhead, hard to accidentally misconfigure into slowness, which matters a lot for a tool generating config unattended) or sheldon as an equally defensible second choice (Rust binary, TOML config, easy to template from Go).

This issue's motivation section (the real conflict/dedup problem — znap and a pre-existing zinit setup both loading redundant plugins) is still valid and already addressed separately by the zinit/znap dedup module. What's not still valid is the specific "migrate to zinit" recommendation — that should be revised to "migrate to antidote or sheldon" (or re-scoped to include turbo-mode generation if zinit is preferred for other reasons), pending a maintainer decision.