@sebastienrousseau/dotfiles 0.2.511 → 0.2.513

package/docs/operations/ROADMAP_V0_2_503.md

@@ -1,134 +1,10 @@
 ---
-title: "v0.2.503 Roadmap — Enterprise-Ready, Cross-Platform"
-date: 2026-05-17
+title: "v0.2.503 Roadmap - Historical"
 ---
 
-# v0.2.503 — Enterprise-Ready Cross-Platform Polish
+# v0.2.503 Roadmap
 
-## Why this release
+This v0.2.503 planning document is historical. Active roadmap content has been
+consolidated into [`../../ROADMAP.md`](../../ROADMAP.md).
 
-The R4 audit (`HARD_AUDIT_2026.md` Part 8) ranked the framework
-9.0/10 on internal quality but only 7.5/10 on adoption readiness.
-The gap is **distribution + cross-platform polish + visible
-organisation** — not feature surface. v0.2.503 closes that gap
-without breaking existing user installs.
-
-Reference target: <https://github.com/Debian/aws-cli> — the Debian
-packaging of AWS CLI, often cited as a model of simple, focused
-top-level structure. We will not blindly copy its layout (it ships
-a Python project, we ship a chezmoi-managed shell framework), but
-we will adopt its discipline: every top-level path has a clear
-purpose, contributors orient in under 30 seconds.
-
-## Scope (non-breaking; v0.2.503)
-
-### A — Visible structure (no file moves)
-
-| | |
-|---|---|
-| `STRUCTURE.md` at root | Single-page map of every top-level path, why it exists, and what it deploys to. Answers "what is `dot_config/`?", "why are there 25 root files?", "where is the CLI?" — in under 30 seconds. |
-| `scripts/README.md` | Map of `scripts/{ci,diagnostics,dot,lib,maintenance,ops,security,tools,tuning}` subtrees. |
-| Root `dot_*` files explained | The 20+ `dot_*` / `executable_*` / `private_*` prefixed files at root are not clutter — they are required by chezmoi to render at the corresponding `~/.X` path. STRUCTURE.md makes this contract visible. |
-
-### B — UX polish
-
-| | |
-|---|---|
-| Sweep remaining tabular `dot` commands through `ui_table_begin/add/end` | Already done: `dot env`, `dot agents list`, `dot registry list/search`, `dot aliases list/search`. Identify any other listing commands not yet on the helper and convert. |
-| `dot doctor` rendering | Today emits 100+ lines of `ui_ok / ui_warn / ui_err`. Group into bordered sections with totals at the foot. |
-| `dot help` two-column table | The grouped help index could become a gum-table by section. |
-| `dot fleet status` widening | Use the table helper for the per-node status block. |
-
-### C — Performance
-
-| | |
-|---|---|
-| `_cached_eval` coverage audit | Find every `eval "$(<tool> init <shell>)"` in `rc.d/` not already wrapped; add to cache layer. |
-| Shell startup p50/p95 in CI | New `dot-cli-bench` workflow exists for the CLI cold-start gate; add an equivalent zsh/bash/fish startup-time gate (sub-150ms cold). |
-| Cross-shell `_cached_eval` parity | bash + fish + nu implementations exist; confirm they all do the realpath sidecar pin + suspicious-output check that zsh added. |
-
-### D — Cross-platform CI parity
-
-| | |
-|---|---|
-| Windows-native smoke test expansion | `tools/ci/windows-smoke-test.ps1` exists but only covers a few commands. Add `dot version / dot help / dot agents check / dot doctor` Windows-native runs. |
-| Real `ubuntu-latest` + `macos-latest` + `windows-latest` matrix for the test runner | Currently `ubuntu` + `macos` only; add `windows-latest` to the regular test workflow. |
-| `chezmoi apply --dry-run` on all three OSes | Verify our templates render on every platform on every PR. |
-
-### E — Code dedup + refactor (in-place)
-
-| | |
-|---|---|
-| Audit `scripts/dot/lib/*` for cross-file duplication | Many small helpers may exist in 2+ places. Consolidate. |
-| Consistent error-exit codes | Document the canonical exit-code map (1 = bad usage, 2 = no provider, 3 = empty, etc. — `dot secrets` already follows this). Audit other commands for drift. |
-| `set -euo pipefail` header lint | Make sure every script under `scripts/` has the canonical header. |
-
-### F — Distribution + discoverability (R4 Top-5 work)
-
-| | |
-|---|---|
-| Homebrew tap stub | Create `install/homebrew/dot.rb` formula scaffold. Real publication still needs the v0.3 reorganization. |
-| Scoop manifest stub | Same for `install/scoop/dot.json`. |
-| `awesome-dotfiles` PR draft | One-line entry + screenshot. Land it after v0.2.503 ships. |
-
-### G — OpenSSF Scorecard 10/10 across every check
-
-Target the [public Scorecard report](https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles) and drive every check to 10/10:
-
-| Check | Today (baseline) | Path to 10 |
-|---|---|---|
-| **Binary-Artifacts** | 10 (no binaries committed) | Maintain — pre-commit guard rejecting any committed binary. |
-| **Branch-Protection** | needs token | Already configured on `main` (required reviews, signed commits, status-check gating, linear history). Verify in `gh api repos/.../branches/main/protection` and document in `docs/security/`. |
-| **CI-Tests** | 10 (CI passes on every PR) | Maintain — current 75-check matrix is comprehensive. |
-| **CII-Best-Practices** / OpenSSF Best Practices badge | not present | Apply for the badge at [bestpractices.coreinfrastructure.org](https://www.bestpractices.dev/) and embed the badge in README. |
-| **Code-Review** | needs verification | Already enforced via branch protection; document in CONTRIBUTING.md. |
-| **Contributors** | low (solo) | Acknowledge — solo-maintained framework. Add `MAINTAINERS.md` + `GOVERNANCE.md` documenting the single-maintainer model and contribution path. |
-| **Dangerous-Workflow** | 10 (no `pull_request_target` with checkout-then-build) | Maintain — `.github/workflows/` is already audited. |
-| **Dependency-Update-Tool** | 10 (Dependabot + Renovate configured) | Maintain. |
-| **Fuzzing** | partial (1 fuzz harness for `install.sh`) | Add OSS-Fuzz integration **OR** expand `tests/fuzz/` coverage (URL parsers, manifest validators, secret-bucket loaders). |
-| **License** | 10 (MIT, top-level `LICENSE`) | Maintain. |
-| **Maintained** | high (active commits weekly) | Maintain. |
-| **Packaging** | low (no distro package) | Address via the Homebrew tap / Scoop manifest / AUR PKGBUILD in §F. SLSA-attested release artefacts now exist (v0.2.502 backfill confirmed). |
-| **Pinned-Dependencies** | 9 (one tag-pinned reusable workflow — SLSA, documented exception) | Already documented; verify Scorecard accepts the SLSA exception. |
-| **SAST** | 10 (CodeQL + Semgrep + Codacy in CI) | Maintain. |
-| **Security-Policy** | 10 (`.github/SECURITY.md` + WKD-published GPG key + disclosure-key-expiry monitor) | Maintain. |
-| **Signed-Releases** | 8–10 (Cosign-signed SBOM + SLSA provenance now landing per v0.2.502 backfill) | Verify Scorecard re-scrapes the v0.2.502 release post-backfill; should bump to 10. |
-| **Token-Permissions** | 10 (top-level `permissions: contents: read`; per-job overrides) | Maintain — set during R3 hardening. |
-| **Vulnerabilities** | 10 (osv-scanner + Dependabot keep open count at 0) | Maintain. |
-| **Webhooks** | n/a | No org-level webhooks; check not applicable. |
-
-**Action items:**
-
-1. Run `scorecard` locally with the official Docker image, snapshot current scores into `docs/security/SCORECARD.md`.
-2. Apply for OpenSSF Best Practices badge (≤30-min form).
-3. Add `MAINTAINERS.md` + `GOVERNANCE.md`.
-4. Re-trigger Scorecard workflow after v0.2.502 backfill so the dashboard reflects the fixed Signed-Releases score.
-5. Track every sub-10 score with a follow-up issue tagged `scorecard`.
-
-## Reorganisation now in-scope (was deferred — see RFC)
-
-Pulled forward from v0.3.0 into this PR per maintainer request.
-The R4 audit identified the framework / user-config intermingling
-as the highest-leverage structural gap. Implementation is phased
-per `RFC_v0_2_503_reorganization.md`; each phase is independently
-atomic.
-
-| Move | Why it's breaking |
-|------|-------------------|
-| `dot_config/` → `defaults/` (with chezmoi `.chezmoiroot`) | Every existing user's chezmoi source-state would need to re-bootstrap. |
-| `bin/dot` → `bin/dot` | Same; `~/.local/bin/dot` would be removed before the new path is installed. |
-| Split `framework/` (CLI + lib) from user-facing defaults | Major restructuring; needs RFC + migration tool + 2-version deprecation window. |
-
-These will land in v0.2.503 as a coordinated single PR with a
-`migrate-v0_2-to-v0_3.sh` script.
-
-## Success criteria (v0.2.503)
-
-- [ ] New contributor can answer "where is the CLI?" / "what is `dot_config/`?" / "how do I add a new command?" in under 30 seconds using only the root `STRUCTURE.md` + `scripts/README.md`.
-- [ ] `dot lint` reports 328+ files clean.
-- [ ] Shell startup p50 ≤ 100ms in CI on all three OSes.
-- [ ] `dot env list` / `dot agents list` / `dot registry list` render with gorgeous gum tables (already done — bake into screenshot for README).
-- [ ] `windows-latest` is in the regular test matrix.
-- [ ] Pre-existing CI infrastructure failures (SLSA, etc.) stay green after the v0.2.502 fix series.
-- [ ] **OpenSSF Scorecard reports 10/10 on every applicable check** at <https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles>.
-- [ ] OpenSSF Best Practices badge displayed in README.
+Release history remains in [`../../CHANGELOG.md`](../../CHANGELOG.md).

package/docs/reference/POWERSHELL_PARITY.md

@@ -12,9 +12,9 @@ This document tracks what is supported on Windows-native PowerShell 7.4 LTS / 7.
 
 | Tier | Meaning | Examples |
 |---|---|---|
-| **Full** | Native PowerShell path; tested in CI on `windows-latest`. | `dot version`, `dot help`, `dot agents check` (via WSL-bash fallback). |
+| **Full** | Native PowerShell path; tested in CI on `windows-latest`. | `dot version`, `dot help`, `dot agents check`. |
 | **WSL-bridged** | Runs under WSL2 bash with the same UX as Linux. | All `dot` subcommands, the test suite, the cold-start bench. |
-| **Stub** | The command exists as a PowerShell entry-point but delegates to bash. | `dot init`, `dot fleet apply` (require chezmoi/ssh; both Windows-installable). |
+| **Bash-bridged** | The PowerShell dispatcher delegates to Git Bash or WSL bash and fails clearly when bash is unavailable. | `dot registry`, `dot fleet apply`, Unix-specific diagnostics. |
 | **N/A** | The command targets a Unix-only surface and is not exposed on PowerShell. | Wallpaper-driven theming via macOS `defaults`; Linux-only `lock-configs.sh`. |
 
 ## Command-by-command matrix
@@ -22,26 +22,24 @@ This document tracks what is supported on Windows-native PowerShell 7.4 LTS / 7.
 | Command | Windows-native | WSL2 | macOS | Linux |
 |---|---|---|---|---|
 | `dot version` | **Full (native)** — `Get-DotVersion` cmdlet in `scripts/dot/powershell/Dot.psm1`; reads `.chezmoidata.toml` directly, no bash | Full | Full | Full |
-| `dot help` | **Full (native)** — `Invoke-DotHelp` cmdlet; `dot help <subcmd>` still bash-bridged | Full | Full | Full |
-| `dot doctor` | Full (subset of checks; some Unix-only checks return N/A) | Full | Full | Full |
-| `dot init <user>` | Full (requires `chezmoi` on PATH — install via `scoop install chezmoi`) | Full | Full | Full |
+| `dot help` | **Full (native)** — `Invoke-DotHelp`; detailed Unix command help remains bash-bridged | Full | Full | Full |
+| `dot status` | **Full (native)** — structured clean/drifted result from chezmoi | Full | Full | Full |
+| `dot diff` / `apply` / `sync` / `update` | **Full (native)** — direct, exit-code-checked chezmoi operations | Full | Full | Full |
+| `dot add` / `remove` / `init` / `cd` | **Full (native)** — direct chezmoi operations and source-path lookup | Full | Full | Full |
+| `dot doctor` | **Full (native baseline)** — PowerShell, chezmoi, git, repo data, and module checks; Unix-only diagnostics are bash-bridged | Full | Full | Full |
 | `dot agents check` | **Full (native)** — `Test-DotAgentsSync` cmdlet; CI smoke test runs the cmdlet directly | Full | Full | Full |
-| `dot agents render` / `list` | Stub (bash-bridged — `render` is a multi-harness mustache-equivalent rewrite, tracked as a separate ticket) | Full | Full | Full |
-| `dot fleet status` / `drift` / `events` | Full | Full | Full | Full |
-| `dot fleet apply` | Stub (bash-bridged + requires Windows OpenSSH `ssh.exe` on PATH; no native pwsh-side test in CI yet — tracked in ROADMAP §C5 follow-up) | Full | Full | Full |
-| `dot fleet namespace set` | Full | Full | Full | Full |
-| `dot registry list` / `search` / `info` | Full | Full | Full | Full |
-| `dot registry install <name>` | Scaffold (no behavior yet on any platform) | Scaffold | Scaffold | Scaffold |
-| `dot agent` / `dot mode` | Full | Full | Full | Full |
-| `dot ai` / `dot ai-setup` / `dot ai-query` | Full | Full | Full | Full |
-| AI bridges (`cl`, `codex`, `copilot`, `gemini`, `goose`, etc.) | Full when the underlying AI CLI is installed (scoop / winget / native) | Full | Full | Full |
+| `dot agents list` | **Full (native)** — structured harness/path/rendered records | Full | Full | Full |
+| `dot agents render` | Bash-bridged | Full | Full | Full |
+| `dot env list` | **Full (native)** — mise text or JSON inventory | Full | Full | Full |
+| `dot env emit` | Bash-bridged | Full | Full | Full |
+| `dot fleet status` | **Full (native)** — node, version, OS, architecture, and drift | Full | Full | Full |
+| `dot fleet drift` / `events` / `apply` / `namespace` | Bash-bridged | Full | Full | Full |
+| `dot registry list` / `search` / `info` / `install` | Bash-bridged; Unix path is verified, checksum-pinned, and preview-first | Full | Full | Full |
+| `dot agent` / `mode` / AI commands | Bash-bridged | Full | Full | Full |
 | `dot lint` | WSL-bridged (shellcheck/shfmt are Unix-native) | Full | Full | Full |
-| `dot perf` | Full (uses pwsh `Measure-Command` on the PS path) | Full | Full | Full |
-| `dot health` | Full | Full | Full | Full |
-| `dot tools` | Full (uses winget/scoop on Windows; brew/apt elsewhere) | Full | Full | Full |
-| `dot theme` (wallpaper-driven) | Stub (Windows wallpaper API needs additional work) | Stub (X11 only — Wayland support pending) | Full | Full (X11 only) |
-| `dot wallpaper` | Stub | Stub | Full | Full |
-| `dot security firewall` | Full (Windows Defender Firewall via `Set-NetFirewallProfile`) | N/A | Full (pf) | Full (ufw/firewalld) |
+| `dot perf` / `health` / `tools` | Bash-bridged | Full | Full | Full |
+| `dot theme` / `wallpaper` | N/A on native Windows | Limited | Full | Full (desktop-dependent) |
+| `dot security firewall` | Bash-bridged; no native Defender mutation | N/A | Full (pf) | Full (ufw/firewalld) |
 | `dot security lock-configs` | N/A (Windows ACL model differs; tracked) | N/A | Full (`chflags uchg`) | Full (`chattr +i`) |
 | Shell startup integration | Full (`Microsoft.PowerShell_profile.ps1` ships) | Full (zsh, bash, fish) | Full (zsh, bash, fish, nu) | Full (zsh, bash, fish, nu) |
 
@@ -51,27 +49,30 @@ This document tracks what is supported on Windows-native PowerShell 7.4 LTS / 7.
 |---|---|
 | `dot version` exits 0 | windows-latest, ubuntu-latest, macos-latest, macos-14 |
 | `dot help` exits 0 | windows-latest, ubuntu-latest, macos-latest, macos-14 |
-| `dot agents check` exits 0 | windows-latest (via bash on PATH), ubuntu-latest, macos-latest, macos-14 |
+| `dot agents check` exits 0 | windows-latest (native), ubuntu-latest, macos-latest, macos-14 |
+| Native module import, agent-body sync, harness inventory, doctor baseline, and chezmoi diff | windows-latest |
+| Native dispatcher version, help, and agents check | windows-latest |
 | PowerShell ≥ 7.4 | windows-latest (smoke test at `tools/ci/windows-smoke-test.ps1`) |
 | PSScriptAnalyzer Error-level findings | windows-latest |
 | `chezmoi --version` exits 0 | windows-latest (via scoop), all Unix matrices |
 | `bash tools/ci/dot-cli-startup-bench.sh` median < 200ms | macos-latest |
 | `bash tools/ci/dot-cli-startup-bench.sh` median < 150ms | ubuntu-latest |
 
-## Known parity gaps (deferred to follow-up PRs)
+## Known parity gaps
 
 These are scoped in [`ROADMAP_2026 §C5`](../operations/ROADMAP_2026.md) but not in this PR's scope:
 
-1. **Native PowerShell `dot.ps1` dispatcher.** Today the Windows path either uses `bash dot` (when bash is on PATH via Git for Windows / WSL) or shells out via `pwsh -Command`. A truly idiomatic PowerShell dispatcher with native cmdlet semantics (verb-noun naming, `[CmdletBinding()]`, pipeline support) is a separate effort.
-2. **Wallpaper-driven theming on Windows.** Requires SystemParametersInfo W32 API or `Set-ItemProperty HKCU:\Control Panel\Desktop`. macOS-native today.
-3. **`dot security lock-configs` for Windows.** Needs an ACL/EFS-based equivalent of `chattr +i` / `chflags uchg`. Not in this PR's scope; documented here so it doesn't get re-discovered.
-4. **Native Windows installer signing.** The repo signs the bootstrap tarball via Cosign keyless; a SignTool-signed `install.ps1` for code-signing-enforced enterprises is a future enhancement.
+1. **Registry and fleet mutation.** Verified registry installation and multi-node fleet application still use the explicit bash bridge.
+2. **Wallpaper-driven theming.** Native Windows wallpaper extraction and application are not implemented.
+3. **Windows config locking.** There is no ACL/EFS equivalent of the Unix immutable-file operation.
+4. **Authenticode signing.** Release provenance covers the archive, but `install.ps1` and `dot.ps1` are not Authenticode-signed for enterprise execution policies.
 
 ## Source-of-truth files
 
 - `.github/workflows/ci.yml` — `test-windows` job (pwsh + scoop + chezmoi + smoke)
 - `tools/ci/windows-smoke-test.ps1` — the actual gate
-- `dot_config/powershell/Microsoft.PowerShell_profile.ps1` — the deployed PowerShell profile (if present)
+- `bin/dot.ps1` and `scripts/dot/powershell/Dot.psm1` — native dispatcher and cmdlets
+- `defaults/dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl` — deployed profile
 - `scripts/dot/lib/platform.sh` — the dot_path_to_unix/native bridge (H9 audit fix)
 
 ## Why this matters

package/docs/reference/THEMES.md

@@ -54,7 +54,7 @@ Examples (depend on what's present on your system):
 |:---|:---|
 | `~/Pictures/Wallpapers/tahoe.heic` (dynamic HEIC, 2 frames) | `tahoe-dark`, `tahoe-light` |
 | `/System/Library/Desktop Pictures/Sonoma.heic` | `sonoma-dark`, `sonoma-light` |
-| `/System/Library/Desktop Pictures/.thumbnails/Dome Dark.heic` + `Dome Light.heic` | `dome-dark`, `dome-light` |
+| `/System/Library/Desktop Pictures/.thumbnails/Monterey Dark.heic` + `Monterey Light.heic` | `monterey-dark`, `monterey-light` |
 
 Only paired themes (with both dark and light variants) appear in `dot theme` and `dot theme list`.
 

package/docs/reference/TOOLS.md

@@ -98,6 +98,7 @@ Detailed guide: [AI.md](../AI.md).
 | **Aider** | Git-native AI pair programming |
 | **Claude CLI** | Anthropic's terminal assistant |
 | **Copilot CLI** | GitHub Copilot in the terminal |
+| **Kimi CLI** | Moonshot AI Kimi Code terminal coding agent |
 | **Kiro CLI** | Agentic AI terminal assistant |
 | **Antigravity CLI** | Google's Antigravity CLI (`agy`) |
 | **Mods/Fabric** | Pipeline-friendly AI processing |

package/docs/reference/UTILS.md

@@ -124,6 +124,7 @@ prints a one-line hint. See [AI.md](../AI.md) for the full surface.
 |---------|-------------|
 | `dot cl` | Claude Code with context injection — use `dot ai claude` |
 | `dot copilot` | GitHub Copilot CLI — use `dot ai copilot` |
+| `dot kimi` | Kimi CLI — use `dot ai kimi` |
 | `dot agy` | Antigravity CLI — use `dot ai agy` |
 | `dot kiro` | Kiro CLI — use `dot ai kiro` |
 | `dot sgpt` | Shell-GPT — use `dot ai sgpt` |

package/docs/schema/dot-registry-v1.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sebastienrousseau.github.io/dotfiles/schema/dot-registry-v1.json",
+  "title": "Dot Module Registry v1",
+  "description": "Integrity-pinned index consumed by dot registry.",
+  "type": "object",
+  "required": ["version", "modules"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "updated": { "type": "string", "format": "date-time" },
+    "registry": { "type": "string", "minLength": 1 },
+    "modules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "version", "description", "archive_url", "sha256"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" },
+          "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([+-][0-9A-Za-z.-]+)?$" },
+          "description": { "type": "string", "maxLength": 200 },
+          "archive_url": { "type": "string", "pattern": "^https://" },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "repo": { "type": "string", "pattern": "^https://" },
+          "tags": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+          "maintainer": { "type": "string", "minLength": 1 },
+          "license": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/docs/security/SCORECARD.md

@@ -35,7 +35,7 @@ Aggregate score **7.6 / 10** at 2026-05-17T08:11:51Z.
 | 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).*
+*Refresh: `scripts/qa/scorecard-snapshot.sh` · Monitoring: `.github/workflows/scorecard.yml`.*
 <!-- END scorecard-snapshot -->
 
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/sebastienrousseau/dotfiles/badge)](https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles)

package/install.sh

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Universal Dotfiles Installer (Zero-Dependency)
-# Usage: bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+# Usage: gh repo clone sebastienrousseau/dotfiles && cd dotfiles && ./install.sh
 # (or ./install.sh locally)
 
 # This installer uses bash features (set -o pipefail, arrays, [[ ]]). If it is
@@ -12,7 +12,7 @@
 # it parses in any shell before bash takes over.
 if [ -z "${BASH_VERSION:-}" ]; then
   echo "install.sh requires bash. Run:  bash install.sh" >&2
-  echo "  or:  bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)\"" >&2
+  echo "  clone: gh repo clone sebastienrousseau/dotfiles && cd dotfiles && ./install.sh" >&2
   exit 1
 fi
 
@@ -71,7 +71,7 @@ show_help() {
 Usage: install.sh [version] [options]
 
 Arguments:
-  version       The version (tag or branch) to install (default: v0.2.511)
+  version       The version (tag or branch) to install (default: v0.2.513)
 
 Options:
   --help        Show this help message
@@ -87,7 +87,7 @@ EOF
 }
 
 main() {
-  local version="v0.2.511"
+  local version="v0.2.513"
   local version_set=0
   local minimal=0
   local provision="${DOTFILES_PROVISION:-0}"
@@ -117,7 +117,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.511)."
+          error "Unrecognized positional argument '$arg' — expected a semver version (e.g. v0.2.513)."
         fi
         version="$arg"
         version_set=1
@@ -158,8 +158,15 @@ main() {
       brew install gum >/dev/null 2>&1
     elif [[ "$target_os" == "debian" || "$target_os" == "wsl2" ]]; then
       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
+      charm_key_tmp="$(mktemp -t charm-key.XXXXXX)"
+      if ! curl --proto '=https' --tlsv1.2 -fsSL \
+        -o "$charm_key_tmp" https://repo.charm.sh/apt/gpg.key; then
+        rm -f "$charm_key_tmp"
+        return 1
+      fi
+      sudo gpg --batch --yes --dearmor \
+        -o /etc/apt/keyrings/charm.gpg "$charm_key_tmp"
+      rm -f "$charm_key_tmp"
       # 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.
@@ -362,7 +369,7 @@ main() {
   # 6. Initialize & Apply
   step "Applying Configuration..."
 
-  # ── Auto-migration for v0.2.511 reorg ─────────────────────────────────
+  # ── Auto-migration for v0.2.513 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.
@@ -371,7 +378,7 @@ main() {
   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.511 migration (idempotent; safe on fresh installs)..."
+      echo "   Running v0.2.513 migration (idempotent; safe on fresh installs)..."
       "$migrate_script" || echo "   migration exited non-zero — continuing apply"
       break
     fi
@@ -443,14 +450,16 @@ main() {
     if [[ -d "$prov_dir" ]]; then
       local script
       # run_once_install_* (shells) first, then numbered run_onchange_* in order.
+      # The fixed globs contain no user-controlled filenames.
+      # shellcheck disable=SC2012
       while IFS= read -r script; do
         [[ -f "$script" ]] || continue
         echo "   → $(basename "$script")"
         if [[ "$script" == *.tmpl ]]; then
-          chezmoi execute-template <"$script" | bash ||
+          chezmoi execute-template <"$script" | DOTFILES_SOURCE_DIR="$SOURCE_DIR" bash ||
             echo "     (step exited non-zero — continuing)"
         else
-          bash "$script" || echo "     (step exited non-zero — continuing)"
+          DOTFILES_SOURCE_DIR="$SOURCE_DIR" 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebastienrousseau/dotfiles",
-  "version": "0.2.511",
+  "version": "0.2.513",
   "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/diagnostics/aliases-manifest.sh

@@ -6,6 +6,15 @@
 
 set -euo pipefail
 
+usage() {
+  cat <<'EOF'
+Usage: aliases-manifest.sh [chezmoi-source-dir]
+
+Emit alias definitions as tab-separated rows:
+  name<TAB>value<TAB>file<TAB>line
+EOF
+}
+
 resolve_source_dir() {
   if [[ -n "${CHEZMOI_SOURCE_DIR:-}" && -d "${CHEZMOI_SOURCE_DIR}" ]]; then
     printf "%s\n" "${CHEZMOI_SOURCE_DIR}"
@@ -39,12 +48,30 @@ resolve_chezmoi_source_dir() {
   printf "%s\n" "$root"
 }
 
+case "${1:-}" in
+  -h | --help)
+    usage
+    exit 0
+    ;;
+  -*)
+    printf 'Unknown option: %s\n' "$1" >&2
+    usage >&2
+    exit 2
+    ;;
+esac
+
 src_root="${1:-$(resolve_source_dir)}"
 src_dir="$(resolve_chezmoi_source_dir "$src_root")"
 
-rg -n \
-  -e '^[[:space:]]*alias[[:space:]]+[A-Za-z0-9_.:-]+=' \
-  -e '^[[:space:]]*[^#"'\'']*&&[[:space:]]*alias[[:space:]]+[A-Za-z0-9_.:-]+=' \
-  "$src_dir/.chezmoitemplates/aliases" \
-  "$src_dir/.chezmoitemplates/functions" |
-  sed -E 's#^([^:]+):([0-9]+):.*alias[[:space:]]+([A-Za-z0-9_.:-]+)=(.*)$#\3\t\4\t\1\t\2#'
+alias_pattern='^[[:space:]]*alias[[:space:]]+[A-Za-z0-9_.:-]+='
+conditional_alias_pattern='^[[:space:]]*[^#"'\'']*&&[[:space:]]*alias[[:space:]]+[A-Za-z0-9_.:-]+='
+search_paths=(
+  "$src_dir/.chezmoitemplates/aliases"
+  "$src_dir/.chezmoitemplates/functions"
+)
+
+if command -v rg >/dev/null 2>&1; then
+  rg -n -e "$alias_pattern" -e "$conditional_alias_pattern" "${search_paths[@]}"
+else
+  grep -rEn -e "$alias_pattern" -e "$conditional_alias_pattern" "${search_paths[@]}"
+fi | sed -E 's#^([^:]+):([0-9]+):.*alias[[:space:]]+([A-Za-z0-9_.:-]+)=(.*)$#\3\t\4\t\1\t\2#'

package/scripts/diagnostics/benchmark.sh

@@ -56,6 +56,19 @@ export DOT_COMMAND="benchmark"
 BENCHMARK_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/dotfiles/benchmarks"
 mkdir -p "$BENCHMARK_DIR"
 
+usage() {
+  cat <<'EOF'
+Usage: dot benchmark [--detailed] [--profile] [--compare] [--waterfall]
+
+Options:
+  -d, --detailed    Show per-component timing before the benchmark
+  -p, --profile     Run zsh zprof analysis
+  -c, --compare     Compare recent benchmark history
+  -w, --waterfall   Show an ASCII component waterfall
+  -h, --help        Show this help
+EOF
+}
+
 # Parse arguments
 DETAILED=false
 PROFILE=false
@@ -79,11 +92,24 @@ while [[ $# -gt 0 ]]; do
       WATERFALL=true
       shift
       ;;
-    *) shift ;;
+    --help | -h)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown option: %s\n' "$1" >&2
+      usage >&2
+      exit 2
+      ;;
   esac
 done
 
 ui_init
+GREEN="${GREEN:-}"
+YELLOW="${YELLOW:-}"
+RED="${RED:-}"
+CYAN="${CYAN:-}"
+NC="${NC:-}"
 
 print_header() {
   echo ""

package/scripts/diagnostics/doctor.sh

@@ -169,7 +169,7 @@ fi
 
 # --- AI CLIs ---
 _section "AI CLIs"
-for cmd in claude copilot agy sgpt ollama opencode aider kiro-cli; do
+for cmd in claude copilot kimi agy sgpt ollama opencode aider kiro-cli; do
   if check_cmd "$cmd"; then
     _ok "$cmd" "$(pretty_path "$(get_cmd_path "$cmd")")"
   else
@@ -226,6 +226,9 @@ fi
 
 # --- OS-specific detection ---
 _os="" _host="" _cpu="" _cpu_cores="" _gpu="" _mem="" _resolution="" _packages="" _de=""
+os_release_file="${DOT_DOCTOR_OS_RELEASE:-/etc/os-release}"
+proc_root="${DOT_DOCTOR_PROC_ROOT:-/proc}"
+sys_root="${DOT_DOCTOR_SYS_ROOT:-/sys}"
 
 if [[ "$_os_name" == "Darwin" ]]; then
   # macOS
@@ -243,33 +246,37 @@ if [[ "$_os_name" == "Darwin" ]]; then
   _packages="$(brew list --formula 2>/dev/null | wc -l | tr -d ' ') (brew)"
   _de="Aqua"
 
-elif [[ -r /etc/os-release ]]; then
+elif [[ -r "$os_release_file" ]]; then
   # Linux (Debian, Ubuntu, Arch, Fedora, RHEL, etc.)
   # shellcheck disable=SC1091
-  . /etc/os-release
+  . "$os_release_file"
   _os="${PRETTY_NAME:-$ID}"
 
-  _host="$(cat /sys/devices/virtual/dmi/id/product_name 2>/dev/null || cat /sys/firmware/devicetree/base/model 2>/dev/null || echo "Linux")"
+  _host="$(cat "$sys_root/devices/virtual/dmi/id/product_name" 2>/dev/null || cat "$sys_root/firmware/devicetree/base/model" 2>/dev/null || echo "Linux")"
 
   if command -v lscpu >/dev/null 2>&1; then
     _cpu="$(lscpu | awk -F': +' '/Model name/{print $2}')"
     _cpu_cores="$(lscpu | awk -F': +' '/^CPU\(s\):/{print $2}')"
   else
-    _cpu="$(grep -m1 'model name' /proc/cpuinfo 2>/dev/null | cut -d: -f2 | sed 's/^ //' || uname -p)"
-    _cpu_cores="$(grep -c '^processor' /proc/cpuinfo 2>/dev/null || echo "?")"
+    _cpu="$(grep -m1 'model name' "$proc_root/cpuinfo" 2>/dev/null | cut -d: -f2 | sed 's/^ //' || uname -p)"
+    _cpu_cores="$(grep -c '^processor' "$proc_root/cpuinfo" 2>/dev/null || echo "?")"
   fi
 
   if command -v lspci >/dev/null 2>&1; then
-    _gpu="$(lspci 2>/dev/null | grep -iE 'vga|3d|display' | head -1 | sed 's/.*: //')"
+    # Headless hosts (VMs, containers, CI runners) expose no display
+    # controller, so `grep` exits 1 and — under `set -euo pipefail` —
+    # would abort the whole report mid-section. Absorb the miss.
+    _gpu="$(lspci 2>/dev/null | grep -iE 'vga|3d|display' | head -1 | sed 's/.*: //' || true)"
+    _gpu="${_gpu:-n/a}"
   else
     _gpu="n/a"
   fi
 
   if command -v free >/dev/null 2>&1; then
     _mem="$(free -b | awk '/Mem:/{printf "%.2f GiB / %.2f GiB", $3/1073741824, $2/1073741824}')"
-  elif [[ -r /proc/meminfo ]]; then
-    _mem_total_kb="$(awk '/MemTotal/{print $2}' /proc/meminfo)"
-    _mem_avail_kb="$(awk '/MemAvailable/{print $2}' /proc/meminfo)"
+  elif [[ -r "$proc_root/meminfo" ]]; then
+    _mem_total_kb="$(awk '/MemTotal/{print $2}' "$proc_root/meminfo")"
+    _mem_avail_kb="$(awk '/MemAvailable/{print $2}' "$proc_root/meminfo")"
     _mem_used_kb=$((_mem_total_kb - _mem_avail_kb))
     _mem="$(awk "BEGIN{printf \"%.2f GiB / %.2f GiB\", ${_mem_used_kb}/1048576, ${_mem_total_kb}/1048576}")"
   else
@@ -319,7 +326,7 @@ fi
 
 # WSL detection and overrides
 _wsl=""
-if [[ -f /proc/version ]] && grep -qi microsoft /proc/version 2>/dev/null; then
+if [[ -f "$proc_root/version" ]] && grep -qi microsoft "$proc_root/version" 2>/dev/null; then
   _wsl="yes"
   _os="${_os} (WSL)"
   _de="Windows Desktop (WSL)"