chore(audit): refine docs-scripts detector and lock in via pre-commit

Two detector bugs fixed:

1. grep_includes missed *.lua, *.ini, *.desktop, *.json — so callers in
   elephant providers (lua), mako on-button-* hooks (ini), and any future
   MimeType-registered URL handlers (.desktop) were invisible. Adding them
   reclassifies nomarchy-notification-dismiss and nomarchy-theme-bg-set
   from `unused?` to `kept` (true callers in mako/core.ini and the
   elephant background_selector lua).

2. The all_refs regex `nomarchy-[a-z0-9][a-z0-9-]+` greedily captured
   trailing dashes, producing junk missing-tokens like `nomarchy-pkg-`,
   `nomarchy-cmd-`, `nomarchy-restart-`, etc. from glob references like
   `for c in nomarchy-pkg-*`. Tightened to require an alphanumeric end
   character. Also restricted to grep_includes so the binary tmpfile
   path `nomarchy-menu-rows` no longer leaks in.

New .githooks/pre-commit re-runs the generator and stages docs/SCRIPTS.md
whenever a nomarchy-* script changes. Enable per clone with
`git config core.hooksPath .githooks` (now mentioned in docs/AGENT.md).

Net audit shift after regen: unused? scripts 31→29, missing tokens 30→28,
no false-positive prefix tokens remain.

.githooks/pre-commit

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Nomarchy pre-commit hook.
+#
+# Enable per-clone with:
+#   git config core.hooksPath .githooks
+#
+# Re-runs the script audit generator when any nomarchy-* script in the three
+# script directories is added, modified, or deleted in this commit, then
+# stages the refreshed docs/SCRIPTS.md so it lands together with the change.
+
+set -e
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+script_dirs_re='^(features/scripts/utils|core/system/scripts|themes/engine/scripts)/nomarchy-'
+
+if git diff --cached --name-only --diff-filter=ACMRD | grep -qE "$script_dirs_re"; then
+  echo "pre-commit: regenerating docs/SCRIPTS.md (script change detected)…"
+  ./bin/utils/nomarchy-docs-scripts --out docs/SCRIPTS.md
+  git add docs/SCRIPTS.md
+fi

bin/utils/nomarchy-docs-scripts

@@ -50,10 +50,13 @@ done
 # their own caller.)
 # File types we search for references. *.md catches docs and README;
 # branding/hook/extension files have varied or no extensions.
+# *.lua catches elephant providers; *.ini catches mako on-button-* hooks;
+# *.desktop catches MimeType-registered URL handlers.
 grep_includes=(
   --include='*.nix' --include='*.conf' --include='*.sh' --include='*.md'
-  --include='nomarchy-*' --include='*.jsonc' --include='*.toml'
+  --include='nomarchy-*' --include='*.jsonc' --include='*.json'
-  --include='*.txt' --include='*.sample'
+  --include='*.toml' --include='*.ini' --include='*.lua'
+  --include='*.desktop' --include='*.txt' --include='*.sample'
 )
 search_dirs=(core features themes installer hosts bin lib README.md)
 
@@ -75,7 +78,11 @@ ref_files_per_cmd() {
 }
 
 # All distinct nomarchy-* tokens we see anywhere in the repo.
-all_refs=$(grep -rohE 'nomarchy-[a-z0-9][a-z0-9-]+' \
+# Final char must be alphanumeric — dropping trailing-dash matches like
+# `nomarchy-pkg-` that come from glob references (`for c in nomarchy-pkg-*`).
+# Restrict to grep_includes so binaries / tmpfiles don't pollute the set.
+all_refs=$(grep -rohE 'nomarchy-[a-z0-9]([a-z0-9-]*[a-z0-9])?' \
+            "${grep_includes[@]}" \
             "${search_dirs[@]}" 2>/dev/null \
           | sort -u)
 

docs/AGENT.md

@@ -127,6 +127,10 @@ Steps you should follow for any non-trivial change:
    nix --extra-experimental-features 'nix-command flakes' flake check --no-build
    bash -n installer/install.sh   # if you touched it
    ```
+   First clone? Enable the repo's pre-commit hook so `docs/SCRIPTS.md` regenerates whenever you add/modify/remove a `nomarchy-*` script:
+   ```bash
+   git config core.hooksPath .githooks
+   ```
    For installer changes, also do a dry-run end-to-end:
    ```bash
    sudo /etc/install.sh --dry-run    # in the live ISO or VM

docs/SCRIPTS.md

@@ -80,7 +80,7 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-launch-bluetooth` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/waybar/config/config.jsonc, +1 more | `kept` |  |
 | `nomarchy-launch-browser` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/plain-bindings.conf,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
 | `nomarchy-launch-editor` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/plain-bindings.conf,features/desktop/hyprland/config/bindings.conf, +2 more | `kept` |  |
-| `nomarchy-launch-floating-terminal-with-presentation` | `features/scripts/utils` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-night/config.jsonc, +2 more | `kept` |  |
+| `nomarchy-launch-floating-terminal-with-presentation` | `features/scripts/utils` | core/home/config/nomarchy/default/mako/core.ini,features/desktop/waybar/config/config.jsonc, +3 more | `kept` |  |
 | `nomarchy-launch-or-focus` | `features/scripts/utils` | core/home/config/nomarchy/extensions/menu.sh,features/desktop/hyprland/config/bindings.conf, +7 more | `kept` |  |
 | `nomarchy-launch-or-focus-tui` | `features/scripts/utils` | core/home/config/nomarchy/extensions/menu.sh,features/desktop/waybar/config/config.jsonc, +4 more | `kept` |  |
 | `nomarchy-launch-or-focus-webapp` | `features/scripts/utils` | features/desktop/hyprland/config/bindings.conf | `kept` |  |
@@ -88,13 +88,13 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-launch-tui` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/hyprland/config/bindings.conf, +2 more | `kept` |  |
 | `nomarchy-launch-walker` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/clipboard.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +1 more | `kept` |  |
 | `nomarchy-launch-webapp` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/plain-bindings.conf,features/desktop/hyprland/config/bindings.conf, +7 more | `kept` |  |
-| `nomarchy-launch-wifi` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,features/desktop/waybar/config/config.jsonc, +3 more | `kept` |  |
+| `nomarchy-launch-wifi` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy/default/mako/core.ini, +4 more | `kept` |  |
 | `nomarchy-lock-screen` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy/extensions/menu.sh, +3 more | `kept` |  |
 | `nomarchy-manual` | `features/scripts/utils` | features/scripts/utils/nomarchy-menu,themes/engine/scripts/nomarchy-theme-install | `kept` |  |
-| `nomarchy-menu` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +9 more | `kept` |  |
+| `nomarchy-menu` | `features/scripts/utils` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +10 more | `kept` |  |
-| `nomarchy-menu-keybindings` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy-skill/SKILL.md, +1 more | `kept` |  |
+| `nomarchy-menu-keybindings` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy/default/mako/core.ini, +2 more | `kept` |  |
 | `nomarchy-migrate-state` | `features/scripts/utils` | — | `unused?` |  |
-| `nomarchy-notification-dismiss` | `features/scripts/utils` | — | `unused?` |  |
+| `nomarchy-notification-dismiss` | `features/scripts/utils` | core/home/config/nomarchy/default/mako/core.ini | `kept` |  |
 | `nomarchy-npx-install` | `features/scripts/utils` | — | `unused?` |  |
 | `nomarchy-on-boot` | `features/scripts/utils` | core/home/config/nomarchy/default/hypr/autostart.conf | `kept` |  |
 | `nomarchy-pkg-add` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-pkg-install, +2 more | `kept` |  |
@@ -149,16 +149,16 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-test-installer` | `features/scripts/utils` | features/scripts/utils/nomarchy-test-vm,README.md | `kept` |  |
 | `nomarchy-test-live-iso` | `features/scripts/utils` | hosts/live-iso.nix | `kept` |  |
 | `nomarchy-test-vm` | `features/scripts/utils` | features/scripts/utils/nomarchy-test-live-iso | `kept` |  |
-| `nomarchy-theme` | `features/scripts/utils` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu, +14 more | `kept` |  |
+| `nomarchy-theme` | `features/scripts/utils` | core/home/config/nomarchy/default/elephant/nomarchy_background_selector.lua,core/home/config/nomarchy/default/elephant/nomarchy_themes.lua, +16 more | `kept` |  |
 | `nomarchy-theme-bg-install` | `themes/engine/scripts` | — | `unused?` |  |
 | `nomarchy-theme-bg-next` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-wallpaper, +1 more | `kept` |  |
-| `nomarchy-theme-bg-set` | `themes/engine/scripts` | — | `unused?` |  |
+| `nomarchy-theme-bg-set` | `themes/engine/scripts` | core/home/config/nomarchy/default/elephant/nomarchy_background_selector.lua | `kept` |  |
 | `nomarchy-theme-current` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-theme-install` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md | `kept` |  |
 | `nomarchy-theme-list` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-theme, +1 more | `kept` |  |
 | `nomarchy-theme-refresh` | `themes/engine/scripts` | — | `unused?` |  |
 | `nomarchy-theme-remove` | `themes/engine/scripts` | — | `unused?` |  |
-| `nomarchy-theme-set` | `themes/engine/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-on-boot, +8 more | `kept` |  |
+| `nomarchy-theme-set` | `themes/engine/scripts` | core/home/config/nomarchy/default/elephant/nomarchy_themes.lua,core/home/config/nomarchy-skill/SKILL.md, +9 more | `kept` |  |
 | `nomarchy-theme-set-keyboard` | `themes/engine/scripts` | features/scripts/utils/nomarchy-on-boot | `kept` |  |
 | `nomarchy-theme-set-keyboard-asus-rog` | `themes/engine/scripts` | features/scripts/utils/nomarchy-on-boot,themes/engine/scripts/nomarchy-theme-set-keyboard | `kept` |  |
 | `nomarchy-theme-set-keyboard-f16` | `themes/engine/scripts` | features/scripts/utils/nomarchy-on-boot,themes/engine/scripts/nomarchy-theme-set-keyboard | `kept` |  |
@@ -177,7 +177,7 @@ Phase B (per-batch PRs) refines those into `port-from-omarchy`,
 | `nomarchy-tui-remove` | `features/scripts/utils` | — | `unused?` |  |
 | `nomarchy-tui-remove-all` | `features/scripts/utils` | — | `unused?` |  |
 | `nomarchy-tz-select` | `core/system/scripts` | features/desktop/waybar/config/config.jsonc,features/scripts/utils/nomarchy-menu | `kept` |  |
-| `nomarchy-update` | `core/system/scripts` | core/home/config/nomarchy-skill/SKILL.md,features/desktop/waybar/config/config.jsonc, +3 more | `kept` |  |
+| `nomarchy-update` | `core/system/scripts` | core/home/config/nomarchy/default/mako/core.ini,core/home/config/nomarchy-skill/SKILL.md, +4 more | `kept` |  |
 | `nomarchy-update-available` | `features/scripts/utils` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-night/config.jsonc | `kept` |  |
 | `nomarchy-update-firmware` | `features/scripts/utils` | features/scripts/utils/nomarchy-menu | `kept` |  |
 | `nomarchy-update-time` | `core/system/scripts` | features/scripts/utils/nomarchy-menu | `kept` |  |
@@ -204,32 +204,30 @@ Tokens grepped from `core/`, `features/`, `themes/`, `installer/`, `hosts/`, `bi
 
 | Token | Referenced in | Status |
 | --- | --- | --- |
-| `nomarchy-cmd-` | core/home/config/nomarchy/default/hypr/bindings/media.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +14 more | `missing` |
+| `nomarchy-brightness` | core/home/config/nomarchy/default/hypr/bindings/media.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +3 more | `missing` |
+| `nomarchy-cmd` | core/home/config/nomarchy/default/hypr/bindings/media.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +14 more | `missing` |
+| `nomarchy-dev` | core/home/config/nomarchy-skill/SKILL.md | `missing` |
 | `nomarchy-dryrun` | installer/install.sh | `missing` |
 | `nomarchy-font-selector` | features/scripts/utils/nomarchy-font,themes/engine/switcher.nix | `missing` |
-| `nomarchy-install-` | core/home/config/nomarchy-skill/SKILL.md | `missing` |
+| `nomarchy-launch` | core/home/config/nomarchy/default/hypr/bindings/clipboard.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +24 more | `missing` |
-| `nomarchy-launch-` | core/home/config/nomarchy/default/hypr/bindings/clipboard.conf,core/home/config/nomarchy/default/hypr/bindings/utilities.conf, +23 more | `missing` |
 | `nomarchy-luks` | installer/disko-golden.nix,installer/install.sh | `missing` |
 | `nomarchy-menu-rows` | bin/utils/nomarchy-docs-scripts,features/scripts/utils/nomarchy-docs-scripts | `missing` |
-| `nomarchy-nopasswd-` | core/system/scripts/nomarchy-sudo-passwordless-toggle | `missing` |
+| `nomarchy-nopasswd` | core/system/scripts/nomarchy-sudo-passwordless-toggle | `missing` |
-| `nomarchy-pkg` | core/home/config/nomarchy-skill/SKILL.md,core/system/scripts/nomarchy-pkg-add, +6 more | `missing` |
+| `nomarchy-nopasswd-expire` | core/system/scripts/nomarchy-sudo-passwordless-toggle | `missing` |
-| `nomarchy-pkg-` | core/home/config/nomarchy-skill/SKILL.md,core/system/scripts/nomarchy-pkg-add, +6 more | `missing` |
+| `nomarchy-pkg` | bin/utils/nomarchy-docs-scripts,core/home/config/nomarchy-skill/SKILL.md, +8 more | `missing` |
 | `nomarchy-plymouth` | themes/engine/plymouth.nix | `missing` |
-| `nomarchy-refresh-` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-refresh-config, +1 more | `missing` |
+| `nomarchy-refresh` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-refresh-config, +1 more | `missing` |
 | `nomarchy-restart` | core/home/config/nomarchy-skill/SKILL.md,core/system/scripts/nomarchy-restart-xcompose, +10 more | `missing` |
-| `nomarchy-restart-` | core/home/config/nomarchy-skill/SKILL.md,core/system/scripts/nomarchy-restart-xcompose, +10 more | `missing` |
 | `nomarchy-screenrecord-filename` | features/scripts/utils/nomarchy-cmd-screenrecord | `missing` |
 | `nomarchy-scripts` | core/system/scripts/nomarchy-preflight-migration,features/scripts/battery-monitor.nix, +1 more | `missing` |
 | `nomarchy-sddm-theme` | themes/engine/sddm.nix | `missing` |
-| `nomarchy-setup-` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu | `missing` |
+| `nomarchy-setup` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu | `missing` |
 | `nomarchy-system-scripts` | core/system/hardware.nix,core/system/scripts-derivation.nix, +1 more | `missing` |
-| `nomarchy-theme-` | core/home/config/nomarchy-skill/SKILL.md,features/scripts/utils/nomarchy-menu, +15 more | `missing` |
 | `nomarchy-theme-engine-scripts` | themes/engine/scripts.nix | `missing` |
 | `nomarchy-theme-next` | core/home/config/nomarchy-skill/SKILL.md | `missing` |
 | `nomarchy-theme-selector` | features/scripts/utils/nomarchy-theme,themes/engine/switcher.nix | `missing` |
 | `nomarchy-themes-no-images` | themes/engine/files.nix | `missing` |
-| `nomarchy-toggle-` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy-skill/SKILL.md, +3 more | `missing` |
+| `nomarchy-toggle` | core/home/config/nomarchy/default/hypr/bindings/utilities.conf,core/home/config/nomarchy-skill/SKILL.md, +3 more | `missing` |
-| `nomarchy-update-` | features/desktop/waybar/config/config.jsonc,features/desktop/waybar/themes/summer-night/config.jsonc, +1 more | `missing` |
 | `nomarchy-vm` | features/scripts/utils/nomarchy-test-vm | `missing` |
 | `nomarchy-wallpaper-selector` | features/scripts/utils/nomarchy-wallpaper,themes/engine/switcher.nix | `missing` |
 | `nomarchy-webapp-handler` | features/scripts/utils/nomarchy-webapp-remove,features/scripts/utils/nomarchy-webapp-remove-all | `missing` |

features/scripts/utils/nomarchy-docs-scripts

@@ -50,10 +50,13 @@ done
 # their own caller.)
 # File types we search for references. *.md catches docs and README;
 # branding/hook/extension files have varied or no extensions.
+# *.lua catches elephant providers; *.ini catches mako on-button-* hooks;
+# *.desktop catches MimeType-registered URL handlers.
 grep_includes=(
   --include='*.nix' --include='*.conf' --include='*.sh' --include='*.md'
-  --include='nomarchy-*' --include='*.jsonc' --include='*.toml'
+  --include='nomarchy-*' --include='*.jsonc' --include='*.json'
-  --include='*.txt' --include='*.sample'
+  --include='*.toml' --include='*.ini' --include='*.lua'
+  --include='*.desktop' --include='*.txt' --include='*.sample'
 )
 search_dirs=(core features themes installer hosts bin lib README.md)
 
@@ -75,7 +78,11 @@ ref_files_per_cmd() {
 }
 
 # All distinct nomarchy-* tokens we see anywhere in the repo.
-all_refs=$(grep -rohE 'nomarchy-[a-z0-9][a-z0-9-]+' \
+# Final char must be alphanumeric — dropping trailing-dash matches like
+# `nomarchy-pkg-` that come from glob references (`for c in nomarchy-pkg-*`).
+# Restrict to grep_includes so binaries / tmpfiles don't pollute the set.
+all_refs=$(grep -rohE 'nomarchy-[a-z0-9]([a-z0-9-]*[a-z0-9])?' \
+            "${grep_includes[@]}" \
             "${search_dirs[@]}" 2>/dev/null \
           | sort -u)