@sebastienrousseau/dotfiles 0.2.502 → 0.2.503

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,7 +59,7 @@ 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.503)
 
 Options:
   --help        Show this help message
@@ -64,7 +71,7 @@ EOF
 }
 
 main() {
-  local version="v0.2.502"
+  local version="v0.2.503"
   local version_set=0
   local minimal=0
   local _cleanup_files=()
@@ -92,7 +99,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.503)."
         fi
         version="$arg"
         version_set=1
@@ -185,7 +192,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 +207,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
@@ -297,6 +304,21 @@ main() {
   # 6. Initialize & Apply
   step "Applying Configuration..."
 
+  # ── Auto-migration for v0.2.503 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.503 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"

package/package.json

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

package/scripts/README.md

@@ -0,0 +1,123 @@
+# `scripts/` — Framework Code
+
+Everything in this directory is **framework code**. Nothing here
+deploys to `~/`; chezmoi ignores the whole tree (see
+`.chezmoiignore`). Scripts are invoked by the `dot` CLI, by CI
+workflows, by `chezmoi apply` hooks, or by hand.
+
+## Subtree map
+
+Per the v0.2.503 reorg (RFC `docs/operations/RFC_v0_2_503_reorganization.md`),
+**repo-only ops** (CI, release, maintenance, docs-generation) have
+moved to the top-level `tools/` tree. `scripts/` retains the
+**runtime-invoked** scripts that the `dot` CLI dispatches to plus a
+few specialised subtrees.
+
+### `scripts/` (CLI dispatch + specialised subtrees)
+
+| Path | Purpose | Touched by |
+|---|---|---|
+| `scripts/dot/commands/` | Per-subcommand handlers for the `dot` CLI. Sources `lib/dot/*.sh` (moved out of this tree in v0.2.503 Phase 1). | Dispatched by `bin/dot` |
+| `scripts/dot/powershell/` | Native PowerShell module (`Dot.psm1`) exporting `Get-DotVersion` / `Invoke-DotHelp` / `Test-DotAgentsSync`. | `bin/dot.ps1` |
+| `scripts/dot/data/` | Per-command static data (registry seeds, palette tables). | `scripts/dot/commands/*` |
+| `scripts/lib/` | Cross-cutting library helpers reused across multiple scripts. Example: `secrets_provider.sh` (keychain / pass / age dispatch). | `scripts/dot/commands/*`, ops scripts |
+| `scripts/diagnostics/` | `doctor.sh` and its helpers — long-form environment health check. | `dot doctor` |
+| `scripts/security/` | Security-domain ops: `check-disclosure-key-expiry.sh`, `lock-configs.sh`, etc. | `dot security`, CI |
+| `scripts/secrets/` | Secret-bucket utilities (rotation, audit). | `dot secrets` subcommands |
+| `scripts/theme/` | Wallpaper-to-palette extraction logic. | `dot theme rebuild` |
+| `scripts/tools/` | Tool-helpers shipped via `dot tools` (e.g. `cmatrix.sh`, `emoji-picker.sh`, `figlet-banner.sh`, `log-rotate.sh`). Runtime-invoked. | `dot tools`, `dot env` |
+| `scripts/tuning/` | Opt-in OS tuning scripts (`macos.sh`, `linux.sh`). | `dot tune`, manual invocation |
+| `scripts/ops/` | Repo-wide ops: `rollback.sh`, etc. | `dot rollback`, maintenance |
+| `scripts/fonts/` | Nerd Font install helpers. | `dot fonts` |
+| `scripts/git-hooks/` | Git hooks not managed by chezmoi (kept here for portable install). | `install/provision/*` |
+| `scripts/qa/` | Quality-assurance helpers (PowerShell contract tests, version-consistency checks, scorecard snapshot, etc). | `.github/workflows/pr-signature.yml`, `powershell-contract.yml`, doc-drift |
+| `scripts/demo/` | Demonstration helpers (recordings, screenshots). | Manual |
+| `scripts/version-sync.sh` | Bulk version-string propagator (`scripts/qa/check-version-consistency.sh` is the verifier). | Release flow |
+| `scripts/uninstall.sh` | Reverse-of-`install.sh` — user-invoked. | Manual |
+
+### `tools/` (repo-only ops, not distributable)
+
+| Path | Purpose | Touched by |
+|---|---|---|
+| `tools/ci/` | CI-only helpers: `dot-cli-startup-bench.sh`, `install-chezmoi-verified.sh`, `windows-smoke-test.ps1`, `run-coverage.sh`, etc. | `.github/workflows/*` |
+| `tools/release/` | Release-time tasks. | Release workflow |
+| `tools/maintenance/` | Recurring upkeep: `check-updates.sh`, etc. | Cron, manual |
+| `tools/docs/` | Documentation-generation helpers (manual builds, screenshot CI, `generate-command-index.sh`). | `manual-publish.yml`, `dot manual`, doc-drift |
+
+## `scripts/dot/` breakdown
+
+The `dot` CLI is implemented as `bin/dot`
+(dispatcher) + `scripts/dot/commands/<cmd>.sh` (per-command
+handlers) + `lib/dot/*.sh` (shared helpers — moved out of
+`scripts/dot/lib/` in v0.2.503 Phase 1 per the
+[reorganisation RFC](../docs/operations/RFC_v0_2_503_reorganization.md)).
+
+| Path | Purpose |
+|---|---|
+| `scripts/dot/commands/` | One file per `dot <cmd>` subcommand. Each defines a `cmd_<name>()` function the dispatcher calls. Sources the library via `$SCRIPT_DIR/../../../lib/dot/<X>.sh`. |
+| `scripts/dot/powershell/` | Native PowerShell module — see top-level table. |
+| **`lib/dot/utils.sh`** | Common helpers (resolve_source_dir, validate_name, die, run_script, etc.). |
+| **`lib/dot/ui.sh`** | Single source of truth for CLI output (ui_ok/warn/err/info, ui_header, ui_table_*, ui_spinner_*, ui_confirm, ...). |
+| **`lib/dot/platform.sh`** | OS / shell / WSL detection, path translation. |
+| **`lib/dot/log.sh`** | Structured logging (JSONL audit log when `DOTFILES_AUDIT_LOG=1`). |
+| **`lib/dot/bento.sh`** | The "bento box" layout primitive used by `dot health` and friends. |
+
+## Adding a new subcommand
+
+1. Create `scripts/dot/commands/<name>.sh`:
+
+   ```bash
+   #!/usr/bin/env bash
+   # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+   set -euo pipefail
+   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+   # shellcheck source=../lib/utils.sh
+   source "$SCRIPT_DIR/../lib/utils.sh"
+
+   dot_ui_command_banner "<Title>" "${1:-}"
+
+   cmd_<name>() {
+     # ...
+   }
+
+   cmd_<name>_help() {
+     cat <<-EOF
+     Usage: dot <name> [args]
+     # ...
+   EOF
+   }
+   ```
+
+2. Add a dispatch arm in `bin/dot`:
+
+   ```bash
+   <name>) load_commands "<name>"; cmd_<name> "$@" ;;
+   ```
+
+3. Document it in `docs/manual/03-reference/01-dot-cli.md` and add
+   to `docs/manual/command-index.md`.
+
+4. Add a help-table entry in `bin/dot`'s
+   help renderer.
+
+5. Add a unit test under `tests/unit/<domain>/test_<name>.sh`
+   (run with `./tests/framework/test_runner.sh`).
+
+## Conventions
+
+- **Shell style**: 2-space indent, `set -euo pipefail`, shellcheck-clean
+  with the project's flags (`--severity=error -e SC1091 -e SC2030 -e SC2031`).
+- **Formatting**: `shfmt -i 2 -ci`.
+- **Output**: NEVER `printf` raw ANSI. Source `scripts/dot/lib/ui.sh`
+  and use `ui_ok`, `ui_table_*`, etc.
+- **Exit codes**: 1 = bad usage, 2 = no provider / dependency missing,
+  3 = empty result / not found, ≥4 = provider-specific. Document
+  per-command in the help text.
+- **Validation**: Always `validate_name "$arg" "tool name"` before
+  passing user input to `mise`, `gh`, `ssh`, etc.
+
+## See also
+
+- `../docs/STRUCTURE.md` — full repository map.
+- `docs/manual/03-reference/01-dot-cli.md` — every `dot <cmd>` documented.
+- `scripts/dot/lib/ui.sh` — the UI primitive library (always source this for output).

package/scripts/ci/check-copyright-headers.sh

@@ -1,96 +1,7 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
-# Copyright header validator (zero-tolerance policy).
-#
-# Scans source files for a copyright header in the first 10 lines. Patterns
-# are deliberately narrow to avoid false positives on C-style `(c)` comments
-# or the word "token" appearing in running text.
-#
-# Usage:
-#   check-copyright-headers.sh [--extensions=sh,lua,nix,...] [--excludes=REGEX]
-#
-# Exit codes:
-#   0  all files have a valid header
-#   1  one or more files are missing a header
-#   2  invalid invocation
-
+# Compat shim: the canonical script moved to tools/ci/ in v0.2.503.
+# Pinned reusable workflows on master still reference the old path;
+# this delegates so they keep working until the next pin bump.
 set -euo pipefail
-
-EXTENSIONS_DEFAULT="sh,lua,nix,py,js,ts,go,rs,java,cpp,c,h,hpp"
-EXCLUDES_DEFAULT='(^|/)(node_modules|\.git|vendor|target|build)/|\.tmpl$|(^|/)\.chezmoitemplates/'
-
-EXTENSIONS="$EXTENSIONS_DEFAULT"
-EXCLUDES="$EXCLUDES_DEFAULT"
-
-for arg in "$@"; do
-  case "$arg" in
-    --extensions=*) EXTENSIONS="${arg#*=}" ;;
-    --excludes=*) EXCLUDES="${arg#*=}" ;;
-    -h | --help)
-      sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'
-      exit 0
-      ;;
-    *)
-      echo "Unknown argument: $arg" >&2
-      exit 2
-      ;;
-  esac
-done
-
-# Narrow patterns — each must be specific enough that running prose cannot match.
-# Deliberately DROPPED: bare "(c) " (false-positives in C comments),
-# bare "All rights reserved" (often appears in vendored prose).
-# Matched by `grep -F`, so these are literal strings.
-PATTERNS=(
-  "Copyright (c)"
-  "Copyright ©"
-  "SPDX-License-Identifier:"
-  "© "
-)
-
-# Build a ripgrep glob like `{*.sh,*.lua,*.nix}` from the comma list.
-IFS=',' read -r -a exts <<<"$EXTENSIONS"
-glob="{"
-for i in "${!exts[@]}"; do
-  [[ $i -gt 0 ]] && glob+=","
-  glob+="*.${exts[$i]}"
-done
-glob+="}"
-
-mapfile -t all_files < <(rg --files -g "$glob" 2>/dev/null || true)
-
-if [[ "${#all_files[@]}" -eq 0 ]]; then
-  echo "::notice::No files matched extensions: $EXTENSIONS"
-  exit 0
-fi
-
-missing=()
-for file in "${all_files[@]}"; do
-  if [[ "$file" =~ $EXCLUDES ]]; then
-    continue
-  fi
-
-  found=false
-  # Read the first 10 lines once; search each pattern against that buffer.
-  head_buf="$(head -n 10 "$file" 2>/dev/null || true)"
-  for pattern in "${PATTERNS[@]}"; do
-    if grep -qF -- "$pattern" <<<"$head_buf"; then
-      found=true
-      break
-    fi
-  done
-
-  $found || missing+=("$file")
-done
-
-if [[ "${#missing[@]}" -gt 0 ]]; then
-  echo "::error::Copyright header validation failed — ${#missing[@]} file(s) missing header"
-  echo "Files missing a recognised copyright header:"
-  printf '  - %s\n' "${missing[@]}"
-  echo
-  echo "Add ONE of the following to the first 10 lines:"
-  printf '  - %s\n' "${PATTERNS[@]}"
-  exit 1
-fi
-
-echo "::notice::All ${#all_files[@]} file(s) have a valid copyright header"
+exec bash "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/tools/ci/check-copyright-headers.sh" "$@"