@sebastienrousseau/dotfiles 0.2.501 → 0.2.502

package/docs/security/SCORECARD.md

@@ -30,7 +30,7 @@ Regressions are triaged within one Monday cycle: identify the check
 that dropped, either remediate or file an exception entry below with
 a rationale and an expiry date.
 
-## Per-check posture (snapshot)
+## Per-check posture (snapshot, master HEAD)
 
 The checks below come from OpenSSF Scorecard's published rubric. Tick
 marks reflect this repo's posture at the time of writing — the
@@ -38,30 +38,75 @@ marks reflect this repo's posture at the time of writing — the
 
 | Check | Status | Notes |
 |---|---|---|
-| Branch-Protection | ✓ | `master` requires signed commits, linear history, required checks. Codified at `.github/rulesets/master.json` and `.github/branch-protection-config.json`. |
-| Code-Review | ✓ | Every PR requires at least one approval; CODEOWNERS in place. |
+| Branch-Protection | ⚠ | `master` requires signed commits, linear history, required checks (`.github/rulesets/master.json`). Scorecard can't read classic protection rules without a fine-grained PAT, so this check reports as `-1` ("internal error"). |
+| Code-Review | ⚠ | Single-maintainer repo; PRs are self-merged after CI. Scorecard scores 0/30 here by design — see `Open findings` below. |
 | Signed-Commits | ✓ | Enforced by pre-push hook (`scripts/git-hooks/pre-push`) and at-push by branch protection (#853 + #857). |
 | Dependency-Update-Tool | ✓ | Dependabot configured for github-actions / npm / docker / devcontainers / uv. |
-| Fuzzing | ⚠ | `install.sh` fuzz harness lives under `tests/fuzz/` (closes #881). Coverage is the script's CLI surface plus chaos input fixtures — not full corpus fuzzing yet. |
+| Fuzzing | ⚠ | `install.sh` fuzz harness lives under `tests/fuzz/` (closes #881), but it's shell-based and Scorecard's heuristic only recognizes OSS-Fuzz / ClusterFuzzLite / native Go fuzz / libFuzzer / Atheris. None support shell. Property tests under `tests/unit/functions/test_property_*.sh` cover the closest equivalent surface. |
 | License | ✓ | Apache-2.0 at repo root. |
-| Maintained | ✓ | Active commit cadence; the [README](../../README.md) lists the current `dotfiles_version` (v0.2.501). |
-| Pinned-Dependencies | ✓ | Every workflow action is pinned to a 40-char commit SHA; the lint rule under `actionlint` enforces this on PR. |
+| Maintained | ✓ | Active commit cadence; the [README](../../README.md) lists the current `dotfiles_version`. |
+| Pinned-Dependencies | ⚠ | Closed 8 of 14 findings this cycle (every Dockerfile base + every workflow action + 2 `curl \| sh` installers + the `npm install -g npm` upgrade step). 5 residual findings stay open by design — see `Open findings`. |
 | SAST | ✓ | CodeQL (`.github/workflows/codeql.yml`) + Checkov + Grype. |
 | SBOM | ✓ | Generated per PR by `sbom-diff.yml` and per release by `security-release.yml`. |
 | Security-Policy | ✓ | `.github/SECURITY.md` + this page + `docs/security/THREAT_MODEL.md`. |
-| Token-Permissions | ✓ | Workflows use least-privilege `permissions:` blocks. `harden-runner` adoption (#878) tightens this further. |
+| Token-Permissions | ✓ | Top-level `permissions:` blocks restricted to `contents: read`. `write` scopes scoped to the jobs that need them (#886). |
 | Vulnerabilities | ✓ | Grype gate hard-fails on `high` / `critical` on `master` (#852). |
 | Webhooks | n/a | No external webhooks configured. |
-| CI-Tests | ✓ | Comprehensive CI matrix (Linux + macOS Intel + Apple Silicon, optional Windows). |
-| CII-Best-Practices | ☐ | Not applied yet — see "Open work" below. |
+| CI-Tests | ✓ | Linux + macOS Intel + Apple Silicon matrix; optional Windows. |
+| CII-Best-Practices | ☐ | Not applied yet — see `Open work` below. |
 | Dangerous-Workflow | ✓ | No `pull_request_target` with checkout-PR-code anti-pattern. |
 | Packaging | ✓ | `npm publish --provenance` via OIDC (`.github/workflows/npm-publish.yml`); `policy-bundle-release.yml` for the policy artifact. |
+| Signed-Releases | ⚠ | SLSA provenance + minisig attached via `security-release.yml`; Cosign keyless signing tracked at #876. |
+
+## Open findings
+
+The eight items below are surfaced as alerts at
+<https://github.com/sebastienrousseau/dotfiles/security/code-scanning>.
+Each row gives the dismissal **reason** and the exact **comment text**
+to paste when triaging.
+
+### Bucket 1 — Dismiss in the UI (5 items)
+
+Scorecard flags every `npm install`, `pip install`, `go install`, and
+`curl | sh` invocation under the `Pinned-Dependencies` check. The five
+below either belong to user-facing "update everything" aliases or are
+false positives in Scorecard's regex.
+
+| Path | Reason | Comment to paste |
+|---|---|---|
+| `.chezmoitemplates/aliases/legal/legal.aliases.sh:64` | **Won't fix** | User-facing convenience alias — `go install <fortune-style joke command>@latest`. Pinning by SHA would require users to update the alias manually on every upstream change. Intentional. |
+| `.chezmoitemplates/aliases/update/update.aliases.sh:173` | **Won't fix** | User-facing convenience alias — bulk-update wrapper around `npm`. The alias's purpose is to update everything; pinning defeats it. Intentional. |
+| `dot_local/bin/executable_update:99` | **Won't fix** | `dot_local/bin/executable_update` is the user-invoked "update everything" command. The literal point of `npm update -g` is to update to whatever's latest. Pinning defeats it. Intentional. |
+| `scripts/dot/commands/tools.sh:121` | **False positive** | `npm install --package-lock-only --ignore-scripts --silent` generates a lockfile and does NOT fetch packages. Scorecard's regex matches `npm install` blindly; this invocation has no supply-chain surface. |
+| `install/provision/run_onchange_10-linux-packages.sh.tmpl:369` | **Won't fix** | Already exact-version-pins `aider-chat==0.86.2`. Scorecard wants sha256-hash pinning, which would require a ~2,700-line lockfile covering all 108 transitive deps and re-generated on every aider release — disproportionate maintenance for a single optional provisioning install. |
+
+### Bucket 2 — Architectural (1 item)
+
+| Alert | Why architectural |
+|---|---|
+| `CodeReviewID` (high) — score 0 | Scorecard requires every merged PR to record an approval review by a different GitHub user than the author. This repo is single-maintainer; PRs are self-merged after CI. The fix path is either (a) onboard a co-maintainer who reviews PRs before merge, or (b) accept the finding. Dismiss as **Won't fix** with comment: "Single-maintainer project — no second reviewer available. CI gates (47 required checks per PR) substitute for human review." |
+
+### Bucket 3 — External action (2 items)
+
+| Alert | Action |
+|---|---|
+| `FuzzingID` (medium) | Dismiss as **Won't fix** with comment: "Repo is bash + Go-template + Lua. ClusterFuzzLite / OSS-Fuzz / native Go fuzz / libFuzzer / Atheris (the frameworks Scorecard recognises) all target compiled languages, none support shell. The `tests/fuzz/fuzz_install.sh` harness + property tests under `tests/unit/functions/test_property_*.sh` cover the equivalent surface." |
+| `CIIBestPracticesID` (low) | Apply at <https://www.bestpractices.dev/projects/new>. ~67 self-attested questions, free, 1-2 hours. After silver-tier approval, paste the badge into `README.md` next to the existing Scorecard badge. Most criteria already met (signed commits, CI, security policy, license). |
+
+## Closed this cycle
+
+| Date | Score | Alerts open | Change |
+|---|---|---|---|
+| 2026-05-14 | 6.5 | 28 | First clean publish after fixing the scorecard.yml `uses:`-only restriction (#885). Findings had been hidden by publish-step 400s until then. |
+| 2026-05-14 | 6.5 | 11 | Closed 17 of 28: 10× TokenPermissions (#886), 6× Dockerfile bases (#886), 1× gitleaks fixture (#884). |
+| 2026-05-14 | 6.5 | 9 | Closed 2× `curl \| sh` installers (#888). |
+| 2026-05-14 | 6.5 | 8 | Closed 1× `npm install -g npm@…` via Node 24 bump (#889). |
 
 ## Open work
 
-- Apply for the [OpenSSF Best Practices badge (CII)](https://www.bestpractices.dev/) and embed it next to the Scorecard badge. (Maintainer action — needs the project to register with the BestPractices.dev site.)
-- Once `harden-runner` is in `block` mode across all jobs (#878), the **Token-Permissions** check should hit its maximum.
-- Once Cosign keyless signing is wired into the release pipeline (#876), the **Signed-Releases** check should hit its maximum.
+- **Apply for the OpenSSF Best Practices Badge** — see Bucket 3 above.
+- **Wire Cosign keyless signing into the release pipeline (#876)** — should push `Signed-Releases` to its maximum.
+- **`harden-runner` block-mode adoption (#878)** — should tighten the `Token-Permissions` check further.
 
 ## Exceptions
 
@@ -72,9 +117,24 @@ marks reflect this repo's posture at the time of writing — the
 If you add an exception, include the check name, an expiry date
 (don't allow indefinite), and the rationale. Re-evaluate every quarter.
 
+## Refreshing this document
+
+```bash
+# Re-count open alerts:
+gh api 'repos/sebastienrousseau/dotfiles/code-scanning/alerts?state=open&per_page=50' \
+  --jq '[.[].rule.id] | group_by(.) | map({rule: .[0], count: length})'
+
+# Trigger Scorecard manually:
+gh workflow run scorecard.yml --ref master
+```
+
+If a new category appears, add a row to the matching bucket. If a
+remediation closes one of the rows above, delete the row.
+
 ## References
 
-- `.github/workflows/scorecard.yml` — the scanner.
+- `.github/workflows/scorecard.yml` — the scanner workflow (split into
+  `analysis` + `track-regression` jobs per #885).
 - [Scorecard project](https://github.com/ossf/scorecard).
 - [Scorecard checks reference](https://github.com/ossf/scorecard/blob/main/docs/checks.md).
-- Issue [#869](https://github.com/sebastienrousseau/dotfiles/issues/869).
+- Tracking issue [#869](https://github.com/sebastienrousseau/dotfiles/issues/869).

package/docs/security/security-pubkey.asc

@@ -0,0 +1,15 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEagg20hYJKwYBBAHaRw8BAQdAk2HMi5IFTHBGhCtSFzqwsyuVb7mO0iIhoUXR
+mTv/PNK0R1NlYmFzdGllbiBSb3Vzc2VhdSAoRG90ZmlsZXMgU2VjdXJpdHkpIDxz
+ZWN1cml0eUBzZWJhc3RpZW5yb3Vzc2VhdS5jb20+iLUEExYKAF0WIQRVr602T9nb
+OBnmHwyNaI+vqRRGkwUCagg20hsUgAAAAAAEAA5tYW51MiwyLjUrMS4xMiwwLDMC
+GwMFCQWjmoAFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AACgkQjWiPr6kURpOH
+qQEA4gl4pfhkR9Y3IM6oMHydavrx3CE6mX4YRIkYJ7fYj4UA/iO/54bdjG+wmIrE
+cQ077+ijTTCMnHrosn3E13oQ6NIJuDgEagg20hIKKwYBBAGXVQEFAQEHQKdKJLxe
+xsXBXELbxGHUz2asoTuOnsKk8WEdOyESH3dnAwEIB4iUBBgWCgA8FiEEVa+tNk/Z
+2zgZ5h8MjWiPr6kURpMFAmoINtIbFIAAAAAABAAObWFudTIsMi41KzEuMTIsMCwz
+AhsMAAoJEI1oj6+pFEaTUw0A/14oNMWsx1gcyx9wl/vy+OgEXoOksxSV+FetAI2Q
+Q7qOAP9pohjVAi40dqfBXv3vet7CV0V4p2kQ+qpQTOPTVafkDA==
+=UtsL
+-----END PGP PUBLIC KEY BLOCK-----

package/dot_config/fish/conf.d/direnv.fish

@@ -0,0 +1,4 @@
+# Shadow vendor `/opt/homebrew/share/fish/vendor_conf.d/direnv.fish`.
+# fish dedupes conf.d files by basename — user conf.d wins. Direnv is
+# loaded lazily by `_dotfiles_async_init` in init.fish via `_cached_eval
+# direnv hook fish`, avoiding the unconditional cost on every shell start.

package/dot_config/fish/conf.d/mise-activate.fish

@@ -0,0 +1,5 @@
+# Shadow vendor `/opt/homebrew/share/fish/vendor_conf.d/mise-activate.fish`.
+# fish dedupes conf.d files by basename — user conf.d wins. Mise is loaded
+# lazily by `_dotfiles_async_init` in init.fish via `_cached_eval mise
+# activate fish`, which is ~10× faster than the vendor's eager hook-env
+# call on every shell start (saves ~140ms in fish startup).

package/dot_config/git/hooks/executable_commit-msg

@@ -106,7 +106,7 @@ detect_ai_agent() {
 }
 
 # ── Branding Signature ────────────────────────────────────────────────
-sig_file="/Users/seb/.euxis/data/config/branding/signature.txt"
+sig_file="${HOME}/.euxis/data/config/branding/signature.txt"
 msg_file="${1:-}"
 
 [[ -n "$msg_file" && -f "$msg_file" ]] || exit 0

package/dot_config/shell/00-core-paths.sh.tmpl

@@ -41,7 +41,14 @@ path_prepend() {
 }
 
 # 1. System Paths (Prepend, but will be pushed down by later prepends)
-PATH="/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH}"
+# Use path_prepend so existing entries are removed first — avoids the
+# duplicate-system-path bloat that `PATH="...:${PATH}"` produces when
+# the parent shell already had these (e.g. macOS launchd default PATH).
+path_prepend "/sbin"
+path_prepend "/usr/sbin"
+path_prepend "/bin"
+path_prepend "/usr/bin"
+path_prepend "/usr/local/bin"
 
 # 2. Homebrew Paths (Prepend -> Higher Priority)
 path_prepend "/opt/homebrew/sbin"

package/dot_config/shell/README.md

@@ -27,7 +27,7 @@ Welcome to your universally compatible, high-performance dotfiles configuration,
 To install these dotfiles on a new machine, run:
 
 ```bash
-sh -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.501/install.sh)"
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.502/install.sh)"
 ```
 
 This command will:

package/dot_config/zsh/dot_zshrc.tmpl

@@ -217,11 +217,17 @@ _cached_eval_impl() {
     return 1
   fi
 
-  print -r -- "$init_output" > "${cache}.tmp.$$"
-  mv "${cache}.tmp.$$" "$cache"
+  # `mktemp` instead of `${cache}.tmp.$$` — under PID recycling (very
+  # rare but possible) two concurrent shells with the same $$ could
+  # otherwise race on the same temp file. mktemp gives a unique name.
+  # Use `>|` so we overwrite the just-created mktemp file even when the
+  # user has `setopt noclobber` (see dot_config/shell/05-core-safety.sh).
+  local _tmp _tmp_pin
+  _tmp="$(mktemp "${cache}.XXXXXX")" || return 1
+  print -r -- "$init_output" >| "$_tmp" && mv "$_tmp" "$cache" || { rm -f "$_tmp"; return 1; }
   if [[ -n "$real_bin" ]]; then
-    print -r -- "$real_bin" > "${pin}.tmp.$$"
-    mv "${pin}.tmp.$$" "$pin"
+    _tmp_pin="$(mktemp "${pin}.XXXXXX")" || return 1
+    print -r -- "$real_bin" >| "$_tmp_pin" && mv "$_tmp_pin" "$pin" || { rm -f "$_tmp_pin"; return 1; }
   fi
   source "$cache"
   { zcompile "$cache" } &!
@@ -245,6 +251,48 @@ _cached_eval_clear() {
   printf 'Cleared %d cached eval file(s) from %s\n' "$count" "$cache_dir"
 }
 
+# Lazy-load helper for user-supplied slow tools.
+#
+# Usage in ~/.config/zsh/rc.d/99-local.zsh:
+#   _dot_lazy nvm nvm node npm npx               # nvm.sh sourced on first nvm/node/npm/npx call
+#   _dot_lazy pyenv pyenv python python3 pip pip3
+#   _dot_lazy conda conda
+#
+# First arg is the "trigger" — also the function name that bootstraps
+# the real tool. Remaining args are the commands that, when invoked,
+# bootstrap the trigger then re-exec the command. Bootstrap functions
+# must export `_DOT_LAZY_<TRIGGER>_LOADED` so subsequent calls bypass
+# the stub.
+#
+# Why this matters: every `eval "$(slowtool init zsh)"` at startup
+# costs 50-200ms; lazy-load defers that to first use, keeping
+# `dot version` cold-start under 100ms.
+_dot_lazy() {
+  local trigger="$1"; shift || return 1
+  local cmd
+  for cmd in "$trigger" "$@"; do
+    # shellcheck disable=SC2139,SC2140
+    eval "$cmd() {
+      local _trigger=\"$trigger\"
+      local _loaded_var=\"_DOT_LAZY_\${(U)_trigger//[^A-Z0-9]/_}_LOADED\"
+      if [[ -z \${(P)_loaded_var} ]]; then
+        # Unset every stub so the real binary takes over.
+        local _c
+        for _c in \"$trigger\" $@; do
+          unset -f -- \"\$_c\" 2>/dev/null
+        done
+        # User must define a __dot_lazy_init_<trigger> bootstrap.
+        local _init=\"__dot_lazy_init_\${_trigger//-/_}\"
+        if (( \${+functions[\$_init]} )); then
+          \"\$_init\" || return \$?
+        fi
+        export \"\$_loaded_var=1\"
+      fi
+      command \"$cmd\" \"\$@\"
+    }"
+  done
+}
+
 # Lightweight precmd hook manager (faster than add-zsh-hook)
 _dotfiles_add_precmd() {
   local fn="$1"
@@ -603,6 +651,11 @@ _dotfiles_async_init() {
       esac
     fi
   done
+  # mise/atuin/etc emit `export PATH=...` which bypasses zsh's -U flag on
+  # the `path` array — re-apply uniqueness to drop any duplicates baked
+  # into the cached output (e.g. system paths inherited from a dirty
+  # parent shell).
+  typeset -U path
 }
 
 # Deferred Hydration for Zero-Jank Experience

package/dot_config/zsh/rc.d/30-options.zsh.tmpl

@@ -64,7 +64,7 @@ fi
 {{- end }}
 {{- /* When node_manager = "mise", Node.js is handled by mise activate in dot_zshrc.tmpl */}}
 
-# Completions: pre-warmed by `dot prewarm`, generated on-demand as fallback
+# Completions: generated on-demand on first interactive shell and cached
 if [[ "${DOTFILES_FAST:-0}" != "1" ]] && [[ "${DOTFILES_ULTRA_FAST:-0}" != "1" ]]; then
   [[ ! -f "${ZSH_COMPLETIONS_DIR}/_gh" ]] && command -v gh >/dev/null &&
     command gh completion -s zsh >| "${ZSH_COMPLETIONS_DIR}/_gh"

package/dot_local/bin/executable_dot

@@ -3,7 +3,7 @@
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
 set -euo pipefail
 
-# Dotfiles CLI Entry Point - v0.2.501
+# Dotfiles CLI Entry Point - v0.2.502
 
 # Ensure XDG Base Directory variables are set
 export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
@@ -21,7 +21,7 @@ if [ -e "${HOME}/.nix-profile/etc/profile.d/nix.sh" ]; then
   . "${HOME}/.nix-profile/etc/profile.d/nix.sh"
 fi
 
-VERSION="0.2.501"
+VERSION="0.2.502"
 
 COMMAND="${1:-}"
 if [ -n "${1:-}" ]; then
@@ -160,6 +160,7 @@ Start Here|sync|Apply dotfiles to this machine.|Use after clone or after changes
 Start Here|doctor|Check the environment and surface issues.|Use when something feels off.
 Start Here|learn|Open the guided tour.|Best first stop for new users.
 Start Here|help|Show the overview or help for one command.|Use `dot help <command>` for detail.
+Daily Use|init|Bootstrap a foreign dotfiles repo through chezmoi + dot.|Usage: `dot init <github-user>`.
 Daily Use|status|Show local drift.|See what changed since the last apply.
 Daily Use|diff|Preview pending changes.|Safe way to inspect before applying.
 Daily Use|edit|Open the source directory.|Use the configured editor.
@@ -172,6 +173,8 @@ AI and Agents|ai|Show installed AI tools.|Launches the AI status view.
 AI and Agents|mcp|Inspect MCP policy and registry.|Supports `--strict|-s` and `--json|-j`.
 AI and Agents|mode|Show or set the agent profile.|Profiles: ask, plan, apply, audit.
 AI and Agents|agent|Show agent metadata, logs, checkpoints, and conformance.|Use for card, log, checkpoint, and conformance.
+AI and Agents|agents|Multi-harness agent context (AGENTS.md sync, Cursor/Codex stubs).|Subcommands: list, check, render.
+Fleet|registry|Browse reusable dotfile modules from the dot registry.|Subcommands: list, search, info, install, url, set-url.
 Fleet|fleet|Show fleet node status, drift, and namespace.|Enterprise fleet management.
 Configuration|env|Show managed tool versions.|Backed by mise.
 Configuration|profile|Show or switch the active profile.|Use for machine-specific behavior.
@@ -269,7 +272,6 @@ health|Run the health dashboard with optional fixes.|dot health -v\ndot health -
 perf|Measure shell performance and emit structured timing.|dot perf -j -r 1\ndot perf -p\ndot perf -t 200
 security-score|Assess workstation security posture.|dot security-score -j\ndot security-score -q
 snapshot|Capture the current workstation snapshot.|dot snapshot -b\ndot snapshot -b -f
-verify|Run post-change verification checks.|dot verify\ndot verify -s
 restore|Restore from a backup or git ref.|dot restore -l\ndot restore -L\ndot restore -g HEAD~1
 rollback|Restore a previous configuration snapshot.|dot rollback
 lint|Run shell quality checks for the repo.|dot lint\ndot lint -c\ndot lint -f
@@ -304,15 +306,14 @@ _dot_command_routes() {
   cat <<'EOF'
 sync|core
 apply|core
+init|init
 update|core
 add|core
 diff|core
 status|core
-remove|core
 cd|core
 edit|core
 commit|core
-clean-cache|core
 doctor|diagnostics
 scorecard|diagnostics
 score|diagnostics
@@ -328,12 +329,10 @@ heal|diagnostics
 health|diagnostics
 health-check|diagnostics
 smoke-test|diagnostics
-verify|diagnostics
 attest|diagnostics
 attestation|diagnostics
 security-score|diagnostics
 drift|diagnostics
-benchmark|diagnostics
 intelligence|diagnostics
 conflicts|diagnostics
 locks|diagnostics
@@ -385,7 +384,6 @@ lock-screen|security
 usb-safety|security
 upgrade|meta
 cache-refresh|meta
-prewarm|meta
 docs|meta
 learn|meta
 keys|meta
@@ -393,7 +391,9 @@ sandbox|meta
 mcp|meta
 mode|meta
 agent|meta
+agents|agents
 fleet|fleet
+registry|registry
 patterns|patterns
 manual|manual
 search|search
@@ -539,6 +539,8 @@ if [[ -z "$COMMAND" ]]; then
   exit 0
 fi
 
+# `|| true` is intentional: an unknown command yields an empty route, which falls
+# through the case below into the user-command path that emits the proper error.
 route="$(_dot_command_route "$COMMAND" || true)"
 
 case "$route" in
@@ -546,6 +548,42 @@ case "$route" in
     _dispatch "$route" "$@"
     ;;
 
+  agents)
+    if [[ -n "$_SOURCE_DIR" ]] && [[ -f "$_SOURCE_DIR/scripts/dot/commands/agents.sh" ]]; then
+      # shellcheck disable=SC1091
+      source "$_SOURCE_DIR/scripts/dot/commands/agents.sh"
+      cmd_agents "$@"
+      exit $?
+    else
+      ui_fail "agents.sh not found"
+      exit 1
+    fi
+    ;;
+
+  init)
+    if [[ -n "$_SOURCE_DIR" ]] && [[ -f "$_SOURCE_DIR/scripts/dot/commands/init.sh" ]]; then
+      # shellcheck disable=SC1091
+      source "$_SOURCE_DIR/scripts/dot/commands/init.sh"
+      cmd_init "$@"
+      exit $?
+    else
+      ui_fail "init.sh not found"
+      exit 1
+    fi
+    ;;
+
+  registry)
+    if [[ -n "$_SOURCE_DIR" ]] && [[ -f "$_SOURCE_DIR/scripts/dot/commands/registry.sh" ]]; then
+      # shellcheck disable=SC1091
+      source "$_SOURCE_DIR/scripts/dot/commands/registry.sh"
+      cmd_registry "$@"
+      exit $?
+    else
+      ui_fail "registry.sh not found"
+      exit 1
+    fi
+    ;;
+
   manual)
     if [[ -n "$_SOURCE_DIR" ]] && [[ -f "$_SOURCE_DIR/scripts/dot/commands/manual.sh" ]]; then
       exec bash "$_SOURCE_DIR/scripts/dot/commands/manual.sh" "$@"
@@ -586,7 +624,9 @@ case "$route" in
   *)
     _user_cmd="${XDG_CONFIG_HOME:-$HOME/.config}/dotfiles/commands/${COMMAND}.sh"
     if [[ -f "$_user_cmd" ]]; then
-      source "$_user_cmd" "$@"
+      # Run in a subshell so a user `exit` doesn't kill the dot CLI.
+      (source "$_user_cmd" "$@")
+      exit $?
     else
       echo "Unknown command: ${COMMAND:-}" >&2
       echo "Run 'dot help' for available commands." >&2

package/dot_local/bin/executable_dot-bootstrap

@@ -30,7 +30,6 @@ step "Starting Deterministic Bootstrap (v0.2.493 Frontier)"
 # 1. Install Nix (if not present)
 if ! command -v nix >/dev/null 2>&1; then
   step "Installing Nix Package Manager..."
-  local nix_installer
   nix_installer=$(umask 077 && mktemp)
   if ! curl -fsSL -o "$nix_installer" https://nixos.org/nix/install; then
     rm -f "$nix_installer"

package/dot_local/bin/executable_dot-theme-sync

@@ -466,14 +466,14 @@ reload_desktop() {
     local highlight_color
     case "$accent" in
       -1) highlight_color="0.847059 0.847059 0.862745 Graphite" ;;
-      0)  highlight_color="0.968627 0.831373 0.792157 Red" ;;
-      1)  highlight_color="0.968627 0.890196 0.745098 Orange" ;;
-      2)  highlight_color="1.000000 0.937255 0.690196 Yellow" ;;
-      3)  highlight_color="0.752941 0.964706 0.678431 Green" ;;
-      4)  highlight_color="0.698039 0.843137 1.000000 Blue" ;;
-      5)  highlight_color="0.968627 0.831373 1.000000 Purple" ;;
-      6)  highlight_color="1.000000 0.749020 0.823529 Pink" ;;
-      *)  highlight_color="0.698039 0.843137 1.000000 Blue" ;;
+      0) highlight_color="0.968627 0.831373 0.792157 Red" ;;
+      1) highlight_color="0.968627 0.890196 0.745098 Orange" ;;
+      2) highlight_color="1.000000 0.937255 0.690196 Yellow" ;;
+      3) highlight_color="0.752941 0.964706 0.678431 Green" ;;
+      4) highlight_color="0.698039 0.843137 1.000000 Blue" ;;
+      5) highlight_color="0.968627 0.831373 1.000000 Purple" ;;
+      6) highlight_color="1.000000 0.749020 0.823529 Pink" ;;
+      *) highlight_color="0.698039 0.843137 1.000000 Blue" ;;
     esac
 
     if defaults write -g AppleAccentColor -int "$accent" >/dev/null 2>&1 &&

package/dot_local/bin/executable_tour

@@ -1,6 +1,6 @@
 #!/bin/sh
 # Interactive Tour using Gum
-# Part of Dotfiles v0.2.501
+# Part of Dotfiles v0.2.502
 
 set -eu
 
@@ -39,7 +39,7 @@ banner='██████╗  ██████╗ ████████╗
 ██████╔╝╚██████╔╝   ██║   ██║     ██║███████╗███████╗███████║
 ╚═════╝  ╚═════╝    ╚═╝   ╚═╝     ╚═╝╚══════╝╚══════╝╚══════╝
 
-v0.2.501 · Infrastructure‑grade shell environment'
+v0.2.502 · Infrastructure‑grade shell environment'
 
 gum style \
   --foreground 212 --border-foreground 212 --border double \

package/dot_local/share/man/man1/dot.1

@@ -1,4 +1,4 @@
-.TH DOT 1 "April 2026" "dotfiles v0.2.500" "User Commands"
+.TH DOT 1 "May 2026" "dotfiles v0.2.502" "User Commands"
 .SH NAME
 dot \- dotfiles management CLI
 .SH SYNOPSIS

package/dot_local/share/zsh/completions/_dot

@@ -29,6 +29,10 @@ _dot() {
     'edit:Open chezmoi source in \$EDITOR'
     'commit:AI-powered conventional commit'
     'patterns:Manage AI steering patterns'
+    'init:Bootstrap a foreign dotfiles repo through chezmoi + dot'
+    'agents:Multi-harness agent context (AGENTS.md sync, Cursor/Codex stubs)'
+    'manual:Open or download the multi-format manual'
+    'search:Find commands by keyword'
 
     # Diagnostics
     'doctor:Check system health and configuration'

package/install.sh

@@ -52,7 +52,7 @@ show_help() {
 Usage: install.sh [version] [options]
 
 Arguments:
-  version       The version (tag or branch) to install (default: v0.2.501)
+  version       The version (tag or branch) to install (default: v0.2.502)
 
 Options:
   --help        Show this help message
@@ -64,7 +64,7 @@ EOF
 }
 
 main() {
-  local version="v0.2.501"
+  local version="v0.2.502"
   local version_set=0
   local minimal=0
   local _cleanup_files=()
@@ -92,7 +92,7 @@ main() {
         # like `foobar` doesn't trigger a 30s+ network download attempt.
         # Caught by the install.sh fuzz harness (#881).
         if [[ ! "$arg" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+([-+][a-zA-Z0-9.-]+)?$ ]]; then
-          error "Unrecognized positional argument '$arg' — expected a semver version (e.g. v0.2.501)."
+          error "Unrecognized positional argument '$arg' — expected a semver version (e.g. v0.2.502)."
         fi
         version="$arg"
         version_set=1
@@ -135,10 +135,29 @@ main() {
       sudo mkdir -p /etc/apt/keyrings
       curl -fsSL https://repo.charm.sh/apt/gpg.key |
         sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/charm.gpg
-      # Verify Charm GPG key fingerprint
-      if ! gpg --no-default-keyring --keyring /etc/apt/keyrings/charm.gpg \
-        --list-keys --with-colons 2>/dev/null | grep -q "fid:"; then
-        echo "Warning: Could not verify Charm GPG key" >&2
+      # Pin the Charm GPG key fingerprint — a DNS attacker swapping
+      # repo.charm.sh/apt/gpg.key for a forged key with the same uid
+      # would otherwise pass the prior "any fid: present" check.
+      # Pinned value taken from https://repo.charm.sh/apt/gpg.key on
+      # 2026-05-16. If Charm rotates, update this and call it out in
+      # CHANGELOG.md.
+      CHARM_GPG_EXPECTED_FPR="C026D31B92F9BBE91D5DB75AB07AE17C9E0A6585"
+      charm_actual_fpr="$(gpg --no-default-keyring \
+        --keyring /etc/apt/keyrings/charm.gpg \
+        --with-colons --fingerprint 2>/dev/null |
+        awk -F: '/^fpr:/{print $10; exit}')"
+      if [[ -z "$charm_actual_fpr" ]]; then
+        echo "Error: Could not extract Charm GPG fingerprint — aborting" >&2
+        sudo rm -f /etc/apt/keyrings/charm.gpg
+        return 1
+      fi
+      if [[ "$charm_actual_fpr" != "$CHARM_GPG_EXPECTED_FPR" ]]; then
+        echo "Error: Charm GPG fingerprint mismatch" >&2
+        echo "  expected: $CHARM_GPG_EXPECTED_FPR" >&2
+        echo "  got:      $charm_actual_fpr" >&2
+        echo "  aborting (possible DNS / keyserver hijack)" >&2
+        sudo rm -f /etc/apt/keyrings/charm.gpg
+        return 1
       fi
       echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
       sudo apt-get update && sudo apt-get install gum -y >/dev/null 2>&1
@@ -160,43 +179,31 @@ main() {
       mkdir -p "$bin_dir"
       echo "   Installing chezmoi via binary download..."
 
-      # Prefer verified installer with SHA256 checksum when available
+      # Prefer verified installer with SHA256 checksum when available.
+      # When verification fails or the verified installer isn't present
+      # we refuse to bootstrap rather than silently downloading and
+      # executing an unverified script (the previous fall-back to
+      # `get.chezmoi.io` was an unsigned bootstrap and a security hole).
       local verified_installer
       verified_installer="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scripts/ci/install-chezmoi-verified.sh"
       if [[ -x "$verified_installer" ]] || [[ -f "$verified_installer" ]]; then
         echo "   Using checksum-verified installer..."
         if ! bash "$verified_installer" "${CHEZMOI_VERSION:-2.47.1}" "$bin_dir"; then
-          echo "   Verified installer failed, falling back to get.chezmoi.io" >&2
-        else
-          return 0
+          echo "" >&2
+          echo "   The verified chezmoi installer failed." >&2
+          echo "   Refusing to fall back to an unverified bootstrap path." >&2
+          echo "   Install chezmoi manually from a trusted source, then re-run install.sh:" >&2
+          echo "     macOS:  brew install chezmoi" >&2
+          echo "     Linux:  see https://www.chezmoi.io/install/" >&2
+          return 1
         fi
+        return 0
       fi
-
-      # Fallback: download installer with size/shebang validation
-      local installer
-      installer=$(umask 077 && mktemp)
-      if ! curl -fsSL -o "$installer" https://get.chezmoi.io; then
-        rm -f "$installer"
-        echo "   Failed to download chezmoi installer" >&2
-        return 1
-      fi
-      # Validate: must be a shell script and not suspiciously large
-      if [[ "$(wc -c <"$installer")" -gt 102400 ]]; then
-        rm -f "$installer"
-        echo "   Chezmoi installer suspiciously large. Aborting." >&2
-        return 1
-      fi
-      if ! head -1 "$installer" | grep -q '^#!/'; then
-        rm -f "$installer"
-        echo "   Chezmoi installer doesn't look like a shell script. Aborting." >&2
-        return 1
-      fi
-      if ! BINDIR="$bin_dir" sh "$installer"; then
-        rm -f "$installer"
-        echo "   chezmoi binary installer failed" >&2
-        return 1
-      fi
-      rm -f "$installer"
+      echo "" >&2
+      echo "   scripts/ci/install-chezmoi-verified.sh is missing; cannot verify chezmoi bootstrap." >&2
+      echo "   Install chezmoi manually (brew install chezmoi / official binary)" >&2
+      echo "   and re-run install.sh." >&2
+      return 1
     fi
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebastienrousseau/dotfiles",
-  "version": "0.2.501",
+  "version": "0.2.502",
   "description": "The Trusted Shell Platform — Universal dotfiles managed by Chezmoi. Features Bash & Zsh for macOS, Linux & WSL. Rust modern tooling & enterprise-grade security.",
   "main": "install.sh",
   "bin": {