@sebastienrousseau/dotfiles 0.2.502 → 0.2.504

package/docs/security/SCORECARD.md

@@ -11,6 +11,33 @@ narrative behind it.
 
 ## Live score
 
+<!-- BEGIN scorecard-snapshot (auto-generated, do not edit by hand) -->
+Aggregate score **7.6 / 10** at 2026-05-17T08:11:51Z.
+
+| Check | Score | Reason |
+|---|---:|---|
+| Binary-Artifacts | 10 | no binaries found in the repo |
+| Branch-Protection | -1 | internal error: error during branchesHandler.setup: internal error: some github tokens can't read cl |
+| CI-Tests | 10 | 15 out of 15 merged PRs checked by a CI test -- score normalized to 10 |
+| CII-Best-Practices | 2 | badge detected: InProgress |
+| Code-Review | 0 | Found 0/30 approved changesets -- score normalized to 0 |
+| Contributors | 0 | project has 0 contributing companies or organizations -- score normalized to 0 |
+| Dangerous-Workflow | 10 | no dangerous workflow patterns detected |
+| Dependency-Update-Tool | 10 | update tool detected |
+| Fuzzing | 0 | project is not fuzzed |
+| License | 9 | license file detected |
+| Maintained | 10 | 30 commit(s) and 30 issue activity found in the last 90 days -- score normalized to 10 |
+| Packaging | 10 | packaging workflow detected |
+| Pinned-Dependencies | 9 | dependency not pinned by hash detected -- score normalized to 9 |
+| SAST | 10 | SAST tool is run on all commits |
+| Security-Policy | 10 | security policy file detected |
+| Signed-Releases | 3 | 1 out of the last 3 releases have a total of 2 signed artifacts. |
+| Token-Permissions | 10 | GitHub workflow tokens follow principle of least privilege |
+| Vulnerabilities | 10 | 0 existing vulnerabilities detected |
+
+*Refresh: `scripts/qa/scorecard-snapshot.sh` · CI check: `lint/scorecard-snapshot` (planned).*
+<!-- END scorecard-snapshot -->
+
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/sebastienrousseau/dotfiles/badge)](https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles)
 
 The badge above is regenerated every Monday at 06:00 UTC and on every
@@ -43,7 +70,7 @@ marks reflect this repo's posture at the time of writing — the
 | 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), 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. |
+| License | ✓ | MIT at repo root (`LICENSE`). |
 | 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. |
@@ -101,12 +128,40 @@ false positives in Scorecard's regex.
 | 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). |
+| 2026-05-17 | 7.6 | 7 | v0.2.502 released; Cosign keyless signing live (#876 implementation landed in `security-release.yml` sbom job). |
+| 2026-05-17 | 7.6 | 6 | SLSA Release Attestation pipeline unblocked (PR #894 — 6 prior releases had failed identically). v0.2.502 backfilled with `.intoto.jsonl` + `.sig` + `.pem` triplet. `Signed-Releases` should bump from 3 to ~10 on next Scorecard re-scrape. |
+| 2026-05-17 | 7.6 | — | Added `MAINTAINERS.md` + `GOVERNANCE.md` at repo root. Provides the formal context for the `Code-Review` 0/30 score (solo maintainer) and unblocks the CII Best Practices badge application. |
 
 ## Open work
 
-- **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.
+- **Apply for the OpenSSF Best Practices Badge** — see Bucket 3 above. All passing-tier criteria are now met (signed commits, CI, security policy, MIT license, MAINTAINERS.md, GOVERNANCE.md, RFC process documented).
+- **Re-trigger Scorecard after SLSA backfill propagates** — expected `Signed-Releases` 3 → 10.
 - **`harden-runner` block-mode adoption (#878)** — should tighten the `Token-Permissions` check further.
+- **Investigate `License` 9/10 false-positive** — repo is MIT (SPDX-compliant), Scorecard's penalty should not apply.
+- **Investigate `Branch-Protection` `-1`** — scanner internal error; manually verify with `gh api repos/:owner/:repo/branches/master/protection` and document.
+
+### Enabling Branch-Protection + Webhooks checks (one-time PAT setup)
+
+Scorecard's `Branch-Protection` and `Webhooks` checks require a
+fine-grained Personal Access Token with `Administration: read`
+scope. Without it both checks return `-1` ("internal error"). The
+workflow already wires this up — only the secret needs to be created.
+
+Steps (one-time, repo owner):
+
+1. Go to <https://github.com/settings/personal-access-tokens/new>
+2. **Resource owner**: `sebastienrousseau` · **Repository access**: only `sebastienrousseau/dotfiles`
+3. **Repository permissions** → `Administration: read-only` and `Metadata: read-only`
+4. **Expiration**: 1 year (set a calendar reminder to rotate; document the rotation in this file when done)
+5. Generate the token, copy it once
+6. Add as a secret named `SCORECARD_TOKEN` at <https://github.com/sebastienrousseau/dotfiles/settings/secrets/actions/new>
+7. Next Scorecard run (manual via `gh workflow run scorecard.yml` or weekly cron) picks it up automatically
+8. Expected effect: `Branch-Protection` `-1` → 10/10 if all rules are correctly configured; `Webhooks` `-1` → 10/10 (no webhooks present).
+
+The PAT secret is **optional**. When absent, the workflow falls back
+to `${{ github.token }}` and Scorecard continues to run, only with
+those two checks at `-1`. Adding the PAT cannot reduce any other check's
+score — it's a strict improvement.
 
 ## Exceptions
 

package/docs/security/SHELL_EXEMPTIONS.md

@@ -7,7 +7,7 @@ render_with_liquid: false
 Every bash script in this repo must include `set -euo pipefail` (or
 `set -eu` for POSIX `sh`) within its first 50 lines. The rule is
 enforced by
-[`scripts/ci/check-shell-preamble.sh`](../../scripts/ci/check-shell-preamble.sh),
+[`tools/ci/check-shell-preamble.sh`](../../tools/ci/check-shell-preamble.sh),
 wired into `pre-commit` and the `reusable-shell-lint.yml` CI job.
 Tests pin the contract under
 [`tests/unit/security/test_shell_preamble_lint.sh`](../../tests/unit/security/test_shell_preamble_lint.sh).
@@ -115,14 +115,14 @@ When you need to mark a new file:
 3. **Run the checker:**
 
    ```bash
-   ./scripts/ci/check-shell-preamble.sh path/to/file.sh
+   ./tools/ci/check-shell-preamble.sh path/to/file.sh
    ```
 
    Exit 0 = lint passes.
 
 4. **If you're adding a new entire directory of fragments**
    (rare — alias buckets, plugin trees), edit the path-skip rule
-   in `scripts/ci/check-shell-preamble.sh` and document it in this
+   in `tools/ci/check-shell-preamble.sh` and document it in this
    page's "Bulk-sourced fragments" table above.
 
 ## CI integration
@@ -138,7 +138,7 @@ this page in the same PR.
 
 ## References
 
-- `scripts/ci/check-shell-preamble.sh` — the lint.
+- `tools/ci/check-shell-preamble.sh` — the lint.
 - `tests/unit/security/test_shell_preamble_lint.sh` — contract test.
 - `config/pre-commit-config.yaml` (`shell-preamble-check` hook).
 - `.github/workflows/reusable-shell-lint.yml` — CI invocation.

package/docs/security/VERIFY_RELEASE.md

@@ -0,0 +1,201 @@
+---
+title: "Verify a Release"
+date: 2026-05-17
+---
+
+# Verifying a Release
+
+Every release of the framework ships four independent attestations.
+Verify any of them, they're orthogonal and each rules out a
+different class of attack.
+
+| Artefact | Format | Tool | Threat covered |
+|----------|--------|------|----------------|
+| **SBOM** (`dotfiles-sbom.spdx.json`) | SPDX 2.3 JSON | any SBOM viewer | "what's in the release?", full component inventory |
+| **Cosign signature** (`.sig` + `.pem`) | sigstore keyless | `cosign verify-blob` | "did our CI actually produce this SBOM?", short-lived Fulcio cert + Rekor transparency-log entry |
+| **SLSA provenance** (`.intoto.jsonl`) | in-toto v1 / SLSA L3 | `slsa-verifier` | "what build process produced this?", workflow ID, source ref, builder identity |
+| **Unified manifest** (`ALL_SHA256SUMS` + `.sig` + `.pem`) | text + sigstore keyless | `cosign verify-blob` then `sha256sum -c` | "is every other asset on this release the one our CI produced?", one signed line per asset |
+
+All four are attached to every GitHub Release as assets, from v0.2.503 forward.
+Releases v0.2.500 through v0.2.502 carry the SBOM bundle only: the unified
+manifest landed in v0.2.503 and is forward-only (re-tagging earlier releases
+would break consumer pins on existing SHAs).
+
+---
+
+## TL;DR — verify v0.2.503+ end-to-end
+
+```sh
+# 0. Pick the release to verify
+TAG=v0.2.503
+REPO=sebastienrousseau/dotfiles
+
+# 1. Download every attestation artefact
+gh release download "$TAG" --repo "$REPO" \
+  --pattern dotfiles-sbom.spdx.json \
+  --pattern dotfiles-sbom.spdx.json.sig \
+  --pattern dotfiles-sbom.spdx.json.pem \
+  --pattern dotfiles-sbom.spdx.json.intoto.jsonl \
+  --pattern ALL_SHA256SUMS \
+  --pattern ALL_SHA256SUMS.sig \
+  --pattern ALL_SHA256SUMS.pem
+
+# 2. Verify Cosign signature on the SBOM (binds SBOM to CI workflow identity)
+cosign verify-blob \
+  --certificate dotfiles-sbom.spdx.json.pem \
+  --signature  dotfiles-sbom.spdx.json.sig \
+  --certificate-identity-regexp "^https://github.com/$REPO/" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  dotfiles-sbom.spdx.json
+
+# 3. Verify SLSA provenance (binds SBOM to exact source tag + builder)
+slsa-verifier verify-artifact dotfiles-sbom.spdx.json \
+  --provenance-path dotfiles-sbom.spdx.json.intoto.jsonl \
+  --source-uri "github.com/$REPO" \
+  --source-tag "$TAG"
+
+# 4. Verify the unified manifest, then verify every other asset against it.
+#    One signed file covers all release artefacts in one shot.
+cosign verify-blob \
+  --certificate ALL_SHA256SUMS.pem \
+  --signature  ALL_SHA256SUMS.sig \
+  --certificate-identity-regexp "^https://github.com/$REPO/" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  ALL_SHA256SUMS
+
+gh release download "$TAG" --repo "$REPO" --dir .  # pull every other asset
+sha256sum -c ALL_SHA256SUMS                        # one line per asset
+```
+
+All four commands should print "Verified" / "PASSED" / "OK" and
+exit 0. If any fails, **the release was tampered with**: open
+an issue at <https://github.com/sebastienrousseau/dotfiles/issues>
+and do **not** install.
+
+---
+
+## Tool installation
+
+| Tool | macOS | Linux | Windows |
+|------|-------|-------|---------|
+| `gh` (GitHub CLI) | `brew install gh` | `apt install gh` / [release page](https://github.com/cli/cli/releases) | `scoop install gh` |
+| `cosign` | `brew install cosign` | `curl -sSfL https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 -o /usr/local/bin/cosign && chmod +x /usr/local/bin/cosign` | `scoop install cosign` |
+| `slsa-verifier` | `brew install slsa-verifier` | `go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest` | `scoop install slsa-verifier` |
+
+If you don't have Go installed, fetch the pre-built `slsa-verifier`
+binary from <https://github.com/slsa-framework/slsa-verifier/releases>
+(SHA256-verify per their release notes).
+
+---
+
+## What each verification actually proves
+
+### `cosign verify-blob` succeeds
+
+- The SBOM was signed by a workflow run **on this repository** (the
+  `--certificate-identity-regexp` enforces it).
+- The signing OIDC token was issued by **GitHub Actions** (the
+  `--certificate-oidc-issuer` enforces it).
+- The signature is recorded in the **Rekor public transparency log**
+  (cosign queries this automatically) — anyone can audit it.
+- The Cosign cert was issued by **Fulcio** (the sigstore CA) and
+  was valid at the time of signing.
+
+This **does not** prove what the build process did — only that
+"the file you have is the file CI produced." For "what did CI do",
+see SLSA verification below.
+
+### `slsa-verifier verify-artifact` succeeds
+
+- The SBOM digest matches a provenance statement.
+- The provenance was generated by the **SLSA-Generator** running on
+  **GitHub-hosted runners** for **this exact repository**.
+- The build was triggered by the named tag (`--source-tag $TAG`).
+- The provenance is anchored in Rekor (immutable, third-party-auditable).
+
+SLSA Level 3 is achieved because: (a) the provenance is generated
+by a *trusted, isolated* builder (slsa-github-generator), not by
+us; (b) the builder runs with hermetic, non-falsifiable inputs;
+(c) the provenance is signed by the builder's own identity, not
+ours.
+
+### What none of this proves
+
+The framework's source code is **not formally verified**. SBOM +
+SLSA + Cosign protect the *supply chain* (you got what we shipped)
+— not the *correctness* (what we shipped does what we claim).
+
+For correctness review:
+
+- Code is open under MIT — read it. Start at `bin/dot`.
+- CI runs ~75 checks per PR (shellcheck, shfmt, CodeQL, Semgrep, Codacy, etc.).
+- Pre-commit hooks reject typos, unsigned commits, raw secrets.
+- See `docs/security/SCORECARD.md` for the OpenSSF score posture.
+
+---
+
+## In-shell one-liner for ongoing verification
+
+If you intend to install or update from a release tag, add this to
+your shell startup (already in `dot_config/shell/*` for users who
+run `chezmoi apply`):
+
+```sh
+verify-dot-release() {
+  local tag="${1:-$(gh release view --json tagName --jq .tagName \
+    --repo sebastienrousseau/dotfiles)}"
+  local tmp
+  tmp="$(mktemp -d)"
+  ( cd "$tmp" \
+    && gh release download "$tag" --repo sebastienrousseau/dotfiles \
+      --pattern 'dotfiles-sbom.*' \
+    && cosign verify-blob \
+      --certificate dotfiles-sbom.spdx.json.pem \
+      --signature  dotfiles-sbom.spdx.json.sig \
+      --certificate-identity-regexp '^https://github.com/sebastienrousseau/dotfiles/' \
+      --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+      dotfiles-sbom.spdx.json \
+    && slsa-verifier verify-artifact dotfiles-sbom.spdx.json \
+      --provenance-path dotfiles-sbom.spdx.json.intoto.jsonl \
+      --source-uri github.com/sebastienrousseau/dotfiles \
+      --source-tag "$tag"
+  )
+  local rc=$?
+  rm -rf "$tmp"
+  return $rc
+}
+```
+
+Usage:
+
+```sh
+verify-dot-release             # verify latest
+verify-dot-release v0.2.502    # verify specific tag
+```
+
+---
+
+## If verification fails
+
+1. **Don't install.** Stop the bootstrap script. `^C` any in-flight
+   `chezmoi apply`.
+2. **Compare assets**. The release page shows file sizes — if
+   yours don't match what's on
+   <https://github.com/sebastienrousseau/dotfiles/releases>, you
+   downloaded from a man-in-the-middle.
+3. **Report**: open an issue and email
+   `security@sebastienrousseau.com` (encrypted to the WKD-published
+   GPG key — fingerprint
+   `55AFAD364FD9DB3819E61F0C8D688FAFA9144693`). Acknowledgement
+   SLA: 72 hours per `.github/SECURITY.md`.
+
+---
+
+## See also
+
+- `.github/SECURITY.md` — coordinated disclosure policy.
+- `docs/security/KEY_ROTATION.md` — disclosure-key rotation procedure.
+- `docs/security/SCORECARD.md` — OpenSSF Scorecard posture.
+- `docs/operations/HARD_AUDIT_2026.md` Part 7 — the GPG key generation + WKD publication record.
+- [Sigstore Cosign docs](https://docs.sigstore.dev/cosign/signing/overview/)
+- [SLSA verifier docs](https://github.com/slsa-framework/slsa-verifier)

package/install.sh

@@ -6,6 +6,13 @@
 
 set -euo pipefail
 
+# Restrict the permissions of any file/dir we create during bootstrap.
+# The installer writes secret-adjacent artifacts (chezmoi config, age
+# keys, ssh tooling, downloaded archives) under $HOME — 077 prevents
+# other local accounts from reading them. Individual call sites can
+# still relax with `chmod` when a file is meant to be world-readable.
+umask 077
+
 # ANSI Colors
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -52,21 +59,26 @@ show_help() {
 Usage: install.sh [version] [options]
 
 Arguments:
-  version       The version (tag or branch) to install (default: v0.2.502)
+  version       The version (tag or branch) to install (default: v0.2.504)
 
 Options:
   --help        Show this help message
   --force       Non-interactive mode (sets DOTFILES_NONINTERACTIVE=1)
   --silent      Quiet mode (sets DOTFILES_SILENT=1)
   --minimal     Minimal profile (disable nvim, tmux, zellij)
+  --provision   After applying configs, install the toolchain (packages,
+                fonts, language tools) via the install/provision scripts.
+                Also enabled by DOTFILES_PROVISION=1. Opt-in because it
+                installs packages and may change OS defaults.
 
 EOF
 }
 
 main() {
-  local version="v0.2.502"
+  local version="v0.2.504"
   local version_set=0
   local minimal=0
+  local provision="${DOTFILES_PROVISION:-0}"
   local _cleanup_files=()
   trap 'set +u; rm -f "${_cleanup_files[@]}" 2>/dev/null; set -u' EXIT
 
@@ -79,6 +91,7 @@ main() {
       --silent) export DOTFILES_SILENT=1 ;;
       --force) export DOTFILES_NONINTERACTIVE=1 ;;
       --minimal) minimal=1 ;;
+      --provision) provision=1 ;;
       -*)
         # Catch single-dash and double-dash unknowns the same way.
         error "Unknown option: $arg"
@@ -92,7 +105,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.502)."
+          error "Unrecognized positional argument '$arg' — expected a semver version (e.g. v0.2.504)."
         fi
         version="$arg"
         version_set=1
@@ -185,7 +198,7 @@ main() {
       # 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"
+      verified_installer="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/tools/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
@@ -200,7 +213,7 @@ main() {
         return 0
       fi
       echo "" >&2
-      echo "   scripts/ci/install-chezmoi-verified.sh is missing; cannot verify chezmoi bootstrap." >&2
+      echo "   tools/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
@@ -250,6 +263,35 @@ main() {
     sed_in_place 's/^zellij = true/zellij = false/' "$data_file"
   }
 
+  # Carry the user's existing global git identity into chezmoi's data.
+  #
+  # This installer sets up chezmoi via sourceDir rather than `chezmoi init`,
+  # so the config template's prompts for git_name / git_email never run. The
+  # gitconfig template coalesces git_name->name->"" (likewise email,
+  # signingkey) and only emits a [user] block when non-empty — so without
+  # this, a fresh install produces a ~/.gitconfig with no identity at all,
+  # and commits fail with "Author identity unknown". Seed name/email/
+  # signingkey from `git config --global` when present. Idempotent: skips if
+  # the config already carries a [data] block.
+  toml_escape() { printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'; }
+  seed_git_identity() {
+    local cfg="$CHEZMOI_CONFIG_FILE"
+    [[ -f "$cfg" ]] || return 0
+    grep -q '^\[data\]' "$cfg" 2>/dev/null && return 0
+    local gname gemail gkey
+    gname="$(git config --global user.name 2>/dev/null || true)"
+    gemail="$(git config --global user.email 2>/dev/null || true)"
+    gkey="$(git config --global user.signingkey 2>/dev/null || true)"
+    [[ -z "$gname" && -z "$gemail" ]] && return 0
+    {
+      printf '\n[data]\n'
+      [[ -n "$gname" ]] && printf 'name = "%s"\n' "$(toml_escape "$gname")"
+      [[ -n "$gemail" ]] && printf 'email = "%s"\n' "$(toml_escape "$gemail")"
+      [[ -n "$gkey" ]] && printf 'signingkey = "%s"\n' "$(toml_escape "$gkey")"
+    } >>"$cfg"
+    echo "   Seeded git identity ($gname <$gemail>) into chezmoi data."
+  }
+
   # 5. Backup existing dotfiles that chezmoi will overwrite
   step "Backing up existing dotfiles..."
   BACKUP_DIR="$HOME/.dotfiles.bak.$(date +"%Y%m%d_%H%M%S")"
@@ -266,6 +308,17 @@ main() {
   if command -v chezmoi >/dev/null && [[ -f "$CHEZMOI_CONFIG_FILE" ]]; then
     while IFS= read -r file; do
       [[ -z "$file" ]] && continue
+      # Skip managed *directories*: chezmoi apply never clobbers a
+      # directory's existing contents, so they don't need backing up, and
+      # `cp -a` on one recurses into things it can't copy — e.g. the live
+      # ssh-agent sockets under ~/.ssh/agent, which spew
+      # "is a socket (not copied)" warnings. The managed files chezmoi
+      # would actually overwrite are listed (and backed up) individually.
+      # `-d` without `-L` excludes only real dirs; symlinks are copied as
+      # links by `cp -a`, so they never recurse.
+      if [[ -d "$file" && ! -L "$file" ]]; then
+        continue
+      fi
       if [[ -e "$file" ]]; then
         rel="${file#"$HOME"/}"
         mkdir -p "$BACKUP_DIR/$(dirname "$rel")"
@@ -297,10 +350,26 @@ main() {
   # 6. Initialize & Apply
   step "Applying Configuration..."
 
+  # ── Auto-migration for v0.2.504 reorg ─────────────────────────────────
+  # If the user is upgrading from a pre-0.2.503 install, run the
+  # migration script BEFORE `chezmoi apply` so the reorg's source-
+  # path moves don't cause chezmoi to delete deployed files.
+  # The script is idempotent + silent-by-default; safe to run on
+  # every install (fresh installs detect "no prior state" and exit 0).
+  for migrate_src in "$SOURCE_DIR" "$LEGACY_SOURCE_DIR"; do
+    migrate_script="$migrate_src/install/migrate/migrate-v0_2-to-v0_2_503.sh"
+    if [[ -x "$migrate_script" ]]; then
+      echo "   Running v0.2.504 migration (idempotent; safe on fresh installs)..."
+      "$migrate_script" || echo "   migration exited non-zero — continuing apply"
+      break
+    fi
+  done
+
   # If we are running from a local source, just apply
   if [[ -d "$SOURCE_DIR/.git" ]]; then
     echo "   Applying from local source: $SOURCE_DIR"
     ensure_chezmoi_source "$SOURCE_DIR"
+    seed_git_identity
     APPLY_FLAGS=()
     if [[ "${DOTFILES_NONINTERACTIVE:-0}" = "1" ]]; then
       APPLY_FLAGS=(--force --no-tty)
@@ -310,6 +379,7 @@ main() {
     echo "   Migrating from legacy source: $LEGACY_SOURCE_DIR"
     mv "$LEGACY_SOURCE_DIR" "$SOURCE_DIR"
     ensure_chezmoi_source "$SOURCE_DIR"
+    seed_git_identity
     APPLY_FLAGS=()
     if [[ "${DOTFILES_NONINTERACTIVE:-0}" = "1" ]]; then
       APPLY_FLAGS=(--force --no-tty)
@@ -340,6 +410,7 @@ main() {
     fi
 
     ensure_chezmoi_source "$SOURCE_DIR"
+    seed_git_identity
     APPLY_FLAGS=()
     if [[ "${DOTFILES_NONINTERACTIVE:-0}" = "1" ]]; then
       APPLY_FLAGS=(--force --no-tty)
@@ -347,7 +418,49 @@ main() {
     chezmoi apply "${APPLY_FLAGS[@]}"
   fi
 
+  # Toolchain provisioning (opt-in). The install/provision/ scripts (package
+  # managers, fonts, language + AI tools) are chezmoi run_ scripts, but they
+  # live OUTSIDE the .chezmoiroot source dir (defaults/), so `chezmoi apply`
+  # never runs them — a fresh install otherwise ships configs but zero tools.
+  # Run them here only when explicitly requested: they install packages and
+  # can change OS defaults, so we never do it implicitly (CI / Docker /
+  # unattended automation must opt in via --provision or DOTFILES_PROVISION=1).
+  if [[ "$provision" = "1" && $minimal -eq 0 ]]; then
+    step "Provisioning toolchain (packages, fonts, tools)..."
+    local prov_dir="$SOURCE_DIR/install/provision"
+    if [[ -d "$prov_dir" ]]; then
+      local script
+      # run_once_install_* (shells) first, then numbered run_onchange_* in order.
+      while IFS= read -r script; do
+        [[ -f "$script" ]] || continue
+        echo "   → $(basename "$script")"
+        if [[ "$script" == *.tmpl ]]; then
+          chezmoi execute-template <"$script" | bash ||
+            echo "     (step exited non-zero — continuing)"
+        else
+          bash "$script" || echo "     (step exited non-zero — continuing)"
+        fi
+      done < <(ls "$prov_dir"/run_once_install_* "$prov_dir"/run_onchange_* 2>/dev/null | sort)
+    fi
+  elif [[ $minimal -eq 0 ]]; then
+    step "Configs deployed. To also install the toolchain (packages, fonts, tools):"
+    echo "   bash \"$SOURCE_DIR/install.sh\" --provision    # or DOTFILES_PROVISION=1"
+    echo "   (or: brew bundle --file ~/.config/shell/Brewfile.cli)"
+  fi
+
   success "Configuration loaded. Please restart your shell."
+
+  # If no git identity ended up configured, commits will fail with
+  # "Author identity unknown". Point the user at the one-line fix rather
+  # than letting them discover it on their first commit.
+  if [[ -z "$(git config --global user.email 2>/dev/null || true)" ]] &&
+    ! grep -q '^email' "$CHEZMOI_CONFIG_FILE" 2>/dev/null; then
+    step "No git identity detected. Set yours so commits are attributed:"
+    echo "   git config --global user.name  \"Your Name\""
+    echo "   git config --global user.email \"you@example.com\""
+    echo "   then re-run: chezmoi apply"
+  fi
+
   step "Run 'dot learn' for an interactive tour of your new dotfiles."
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebastienrousseau/dotfiles",
-  "version": "0.2.502",
+  "version": "0.2.504",
   "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": {