FAQ and Troubleshooting

FAQ & Troubleshooting

Common questions and the gotchas most likely to bite. For day-to-day commands, run core-help (alias cheat) and core-doctor in any shell.

FAQ

Why subtree instead of submodule or chezmoi?

Subtree vendors the actual files, so every repo is clone-and-go (a submodule clone is empty until git submodule update --init). chezmoi would be more DRY but trades the nine-repo portfolio for one repo. Full reasoning: Architecture & the Three-Layer Model.

Where does a given piece of config belong?

If it changes with the OS → the OS repo. If it changes with you as an operator → dotfiles-Kali. If it's identical everywhere → Core. See the layer model.

Why isn't scripts/ symlinked onto my machine?

bin/ is shipped (the clip shims, in core.manifest); scripts/ is dev tooling that runs in the Core repo only and is never vendored out. See the shipped-vs-tooling split.

How do I know which Core version a machine has?

Run core-version inside the OS repo — it reads the vendored core.version.

How do I add a new tool/alias/function to Core?

Follow the Contributing checklist: drop it in, strip OS-specific bits, add to core.manifest, audit, sync.

Troubleshooting

bat / fd print "command not found" (Debian/Kali/Ubuntu)

Debian-family ships bat as batcat and fd-find as fdfind. Core resolves both to $BAT_BIN / $FD_BIN in tools.zsh, so aliases and fzf previews work unchanged. If you still see this, run core-doctor to confirm detection and that ~/.local/bin is on PATH.

A modern tool isn't being used (I get the classic command)

That's by design — every alias is guarded by a HAVE_* flag and degrades to the classic command when the tool is absent. Install the tool, open a new shell, and confirm with core-doctor. See Tools, Aliases & Functions.

My keybindings (Ctrl-F / Ctrl-R / Alt-Z) do nothing

These are zle widgets bound through zsh-vi-mode's zvm_after_init hook, and most need a tool present (fzf, atuin, zoxide, sesh). Check core-help — rows are dimmed and tagged "needs <cmd>" when their tool is missing. The module load order also matters: fzf must load before bindings/plugins. See The Zsh Module System.

:checkhealth says clipboard / "+y and "+p fail in Neovim

Run :checkhealth gerrrt. It runs the same clip/clip-paste ladder Neovim's provider uses and names the missing backend (Wayland: wl-clipboard; X11: xclip/xsel; macOS: built in; WSL: clip.exe). If clip/clip-paste aren't on PATH, re-run the OS repo's bootstrap (it symlinks them into ~/.local/bin).

Alpine: a downloaded binary won't run

Alpine is musl libc, not glibc — glibc-linked prebuilt binaries won't run. Prefer apk packages or musl-target builds (and cargo builds for unpackaged tools). See Porting to a New Distro.

Kali/WSL2: my listener/reverse shell isn't reachable

WSL2 is NAT'd. Enable mirrored networking in the Windows-side %UserProfile%\.wslconfig (networkingMode=mirrored, Win11 22H2+) — not /etc/wsl.conf.

CI is red but the code looks fine

CI runs scripts/audit-core.sh. Reproduce locally with make audit (or make audit-changed). Common causes: a new file not added to core.manifest, a wrong executable bit, or a pre-commit hygiene issue (trailing whitespace, missing final newline). See The Audit (Quality Gate).

The freshness workflow went red

A pinned zsh or nvim plugin is behind upstream. Run make check-pins to confirm, then make update-plugins / make update-nvim-plugins to roll forward, review, and commit. See Maintenance & Updates.

sync-core.sh refuses to run

It gates the fan-out: it won't vendor a red tree (fix the audit), warns when local HEAD differs from the remote tip being fanned out (push/pull to align), and skips OS repos with a dirty tree (commit/stash first). SYNC_SKIP_AUDIT=1 is the documented escape hatch. See Consuming Core in an OS Repo.

See also

• Tools, Aliases & Functions
• The Zsh Module System
• The Audit (Quality Gate)