docs(audit): generator discovers references in *.md, README, and txt

Scope: small Phase B improvement to the discovery heuristic so the
audit table stops false-flagging documented user-CLI tools as unused.

The generator now grep -r searches *.md, *.txt, *.sample alongside
*.nix / *.conf / *.sh, and explicitly walks README.md. SCRIPTS.md,
ROADMAP.md, and AGENT.md are excluded from the search (they document
the scripts but aren't callers — including them would promote every
script to `kept`).

Status histogram: 158 → 163 kept, 45 → 40 unused?, 75 → 85 missing
(the missing bump comes from grepping aspirational scripts named in
ROADMAP — wait, that doc is excluded — so the new missing rows are
references in MIGRATION/STRUCTURE/creating-themes that name scripts
which don't exist).

Per-script triage of the remaining 40 unused? rows is the next Phase
B batch.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

bin/utils/nomarchy-docs-scripts

@@ -48,19 +48,35 @@ done
 # Find every nomarchy-* token referenced anywhere outside the script dirs.
 # (We exclude the script files themselves so they don't list themselves as
 # their own caller.)
+# File types we search for references. *.md catches docs and README;
+# branding/hook/extension files have varied or no extensions.
+grep_includes=(
+  --include='*.nix' --include='*.conf' --include='*.sh' --include='*.md'
+  --include='nomarchy-*' --include='*.jsonc' --include='*.toml'
+  --include='*.txt' --include='*.sample'
+)
+search_dirs=(core features themes installer hosts bin lib README.md)
+
+# Files whose mentions of nomarchy-* are documentation about the scripts,
+# not real callers. Excluded from caller discovery so they don't promote
+# every script to `kept`.
+self_refs=(docs/SCRIPTS.md docs/ROADMAP.md docs/AGENT.md)
+
 ref_files_per_cmd() {
   local cmd="$1"
+  local self_pattern
+  self_pattern=$(IFS='|'; echo "${self_refs[*]}")
   grep -rlE "\\b${cmd}\\b" \
-    --include='*.nix' --include='*.conf' --include='*.sh' \
-    --include='nomarchy-*' --include='*.jsonc' --include='*.toml' \
-    core features themes installer hosts bin lib 2>/dev/null \
+    "${grep_includes[@]}" \
+    "${search_dirs[@]}" 2>/dev/null \
     | grep -vE "^(features/scripts/utils|core/system/scripts|themes/engine/scripts)/${cmd}$" \
+    | grep -vE "^(${self_pattern})$" \
     | sort -u
 }
 
 # All distinct nomarchy-* tokens we see anywhere in the repo.
 all_refs=$(grep -rohE 'nomarchy-[a-z0-9][a-z0-9-]+' \
-            core features themes installer hosts bin lib 2>/dev/null \
+            "${search_dirs[@]}" 2>/dev/null \
           | sort -u)
 
 # --- Render: header --------------------------------------------------------
@@ -134,10 +150,11 @@ HEADER
     [[ -z "$token" ]] && continue
     [[ -n "${script_loc[$token]:-}" ]] && continue
     local refs
+    self_pattern=$(IFS='|'; echo "${self_refs[*]}")
     refs=$(grep -rlE "\\b${token}\\b" \
-            --include='*.nix' --include='*.conf' --include='*.sh' \
-            --include='nomarchy-*' --include='*.jsonc' --include='*.toml' \
-            core features themes installer hosts bin lib 2>/dev/null \
+            "${grep_includes[@]}" \
+            "${search_dirs[@]}" 2>/dev/null \
+          | grep -vE "^(${self_pattern})$" \
           | sort -u)
     [[ -z "$refs" ]] && continue
     local count refs_str