@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/CHANGELOG.md

@@ -2,9 +2,73 @@
 
 This file documents all notable changes to this project.
 
+## v0.2.501
+
+### Added
+
+- **Warp + iTerm2 theme support** — the two terminals the theme system did not yet cover are now first-class. `dot_warp/themes/dotfiles.yaml.tmpl` deploys a Warp theme; `run_onchange_22-iterm2-profile.sh.tmpl` writes an iTerm2 Dynamic Profile to `~/Library/Application Support/iTerm2/DynamicProfiles/dotfiles.json`. Both pick up the active theme's `.term` palette, so one `chezmoi apply` switches all six supported terminals (kitty, alacritty, wezterm, foot, warp, iterm2). The README's "Why this repo is different" surface lists this under wallpaper-driven themes.
+- **Starship Transient Prompt (fish)** — `dot_config/fish/conf.d/init.fish.tmpl` calls `enable_transience` after the cached `starship init`, collapsing past prompts to the `[character]` glyph in scrollback. The zsh implementation is a forward-compatibility hook only — Starship 1.24.2 does not yet ship `enable_transience` for zsh (upstream tracker [starship/starship#3522](https://github.com/starship/starship/issues/3522)). Rationale and rejected alternatives recorded in [ADR-010](docs/adr/ADR-010-starship-transient-prompt.md).
+- **`_cached_eval` enhancements (#847)** — `EVALCACHE_DISABLE=true` bypass for debugging, realpath sidecar pin to catch PATH-shadow swaps, file-path argument mtime check, init-failure handling (warns and returns rc instead of caching an empty output), and a new `_cached_eval_clear` helper. Applied to all three implementations (zsh, bash, fish). Adds shdoc docstrings.
+- **JSON Schema for `.chezmoidata.toml`** — `config/chezmoidata.schema.json` (draft-07) plus `.taplo.toml` and a new `lint-chezmoidata` CI job. Catches typos in feature flags, profile names, `default_shell`, and `node_manager` at PR time.
+- **OIDC trusted publishing for npm (#836)** — `publish-npm` workflow authenticates via OIDC instead of a long-lived `NPM_TOKEN`. Provenance is attached to every published tarball. The migration is breaking on the CI side: `NPM_TOKEN` is no longer used. **Manual followup needed before the first OIDC release**: configure Trusted Publishing on npmjs.com for `@sebastienrousseau/dotfiles` pointing at `sebastienrousseau/dotfiles` + `.github/workflows/npm-publish.yml`.
+- **`lint-copyright` in `ci.yml` (#834)** — the fast CI pipeline now runs the reusable copyright-header lint. Previously only `ci-enforced.yml` ran it.
+- **Test coverage roadmap, Slices 1–5d (#883)** — replaced the broken kcov pipeline with a pure bash xtrace runner that works on Linux and macOS. Eight iterations land the floor at **33% measured, 36.73% real (5,783 / 15,744 lines)**:
+    - Slice 1: 2.72% baseline + xtrace runner (`PS4 + BASH_ENV`).
+    - Slice 2: 12.01% — 59 shallow → deep conversions via new `tests/framework/coverage_helpers.sh` (sandbox + safe-mode entry-point exercise).
+    - Slice 3: 18.90% — 47 auto-generated exercise tests + 119 deep conversions.
+    - Slice 4: 19.16% — smart-output shims (`chezmoi`, `git`, `curl`) and subcommand probes.
+    - Slice 5: 34.10% — `cov_exercise_functions_file` helper (source + call each function), sandbox `$HOME/.dotfiles` symlink unblocks scripts that guard on a managed checkout, `test_auto_dot_driver.sh` drives the top-level `dot` dispatcher through 70 read-only subcommands, aggregator filters lines after `set +o xtrace` (intentionally unmeasurable in `security-score.sh` / `scorecard.sh`) and structural-only keywords (`fi`, `done`, etc.).
+    - Slice 5b: 33.73% honest — PS4 `set -u` guard (`${BASH_SOURCE:-}`) and SF: path canonicalization (collapses duplicate keys like `commands/../lib/log.sh`).
+    - Slice 5c: 36.10% — `cov_exercise_functions_file` added to every existing auto-test.
+    - Slice 5d: 36.73% — seven more auto-tests for scripts the existing-test scan had skipped.
+
+    `MIN_COVERAGE_PCT` floor: 0 → 10 → 17 → 18 → 30 → **33** (3-point cushion absorbs cross-platform jitter).
+- **GitHub Pages deploy of `docs/` to doc.dotfiles.io** — new `.github/workflows/pages.yml` builds the Jekyll site (cayman theme, kramdown, Liquid disabled for chezmoi-template snippets) and publishes on every push to master that touches `docs/**`. Replaces the old approach where `manual-publish.yml` deployed the multi-format manual to Pages.
+- **PR consolidation — 8 Dependabot bumps (#839–#846)** — major bumps: `actions/deploy-pages` 4→5, `softprops/action-gh-release` 2→3, `actions/download-artifact` 4→8.0.1, `docker/setup-buildx-action` 3→4, `actions/upload-pages-artifact` 3→5, `actions/github-script` 8→9. Minor and SHA-only refreshes for `actions/cache`, `actions/setup-node`, `bridgecrewio/checkov-action`, `devcontainers/ci`, `docker/login-action`, the `github/codeql-action` family, and `trufflesecurity/trufflehog`. All actions remain pinned by full commit SHA.
+- **Re-source guards** on the five shared library files where re-sourcing would corrupt state: `tests/framework/{assertions,mocks}.sh` and `scripts/dot/lib/{utils,ui,log}.sh`.
+- **`tests/unit/ci/test_validate_chezmoidata.sh`** — 13 assertions covering the new schema-validator script. Restores the 100% module-coverage floor that the schema commit had broken.
+- **`tests/unit/ci/test_check_*.sh`** — four new module-coverage tests for `check-insecure-tls`, `check-dangerous-chmod`, `check-regression-traceability`, and `run-coverage`. Keeps module coverage at 221/221.
+- **`docs/operations/COVERAGE.md`** — documents the why-not-kcov decision (Ubuntu 24.04 bash 5.2 incompatibility) and the xtrace approach (`PS4 + BASH_ENV`).
+- **`.chezmoiignore`** — new file at the repo root. Excludes 880 → 408 paths from chezmoi's managed surface: build artifacts (`coverage/`, `nightly-reports/`, `_build/`), repo metadata (`README.md`, `CHANGELOG.md`, `LICENSE`, `.github/`, `.git/`), documentation tree (`docs/`, intended for doc.dotfiles.io, not `$HOME`), and CI scaffolding (`scripts/`, `tests/`, `examples/`, `install/`, `nix/`, `config/`, `.well-known/`). Also gates `dot_warp/` to macOS via a template conditional. Before this file, any developer machine that had run the test suite locally would have ~600 MB of coverage trace data deployed under `~/coverage/` on the next `chezmoi apply`.
+- **Goose and Codex CLI in `dot ai`** — both AI agents now appear in the status surface under "Agents (autonomous)". `goose` and `codex` are wired in `_ai_mise_pkg` (so `dot ai-setup` knows their install targets), in the bridge `case` (so `dot goose --pattern X "prompt"` and `dot codex --pattern X "prompt"` route correctly), and in the route table in `dot_local/bin/executable_dot`.
+- **Spinner feedback on slow operations** — `dot ai` now shows `Probing N AI tools (cached for 300s)…` during the cold-cache refresh. Previously the command sat silent for 15–30s on the first run after the 5-min TTL expired.
+
+### Changed
+
+- **README rewrite for accuracy and readability** — three concrete inaccuracies fixed: PowerShell was incorrectly listed as Tier-3 (ADR-007 does not place it in the tier system), `dot bundle --manual` was a flag that does not exist (correct command is `dot manual --offline`), and the supported-terminal list missed Warp and iTerm2. Six coverage gaps filled (Starship Transient, JSON Schema, OIDC, `_cached_eval` enhancements, Bash as explicit Tier-1, and several previously-unmentioned `dot` subcommands). Command count corrected from "30+" to "over 80". Flesch baseline 28.3 → 42.9 raw / 47.7 prose-only.
+- **Header badges unified to `for-the-badge` style** — OpenSSF Scorecard and Codespaces badges now use shields.io renderings at the same height as Build / Version / Downloads.
+- **`manual-publish.yml`** — Pages-deploy steps removed. The workflow now only builds the multi-format manual and attaches it to releases.
+- **Coverage runner is now Linux + macOS** — the kcov-only runner had a hard Darwin skip. The xtrace runner works on both, so the pre-commit hook can invoke it on developer machines regardless of platform.
+- **`MIN_COVERAGE_PCT` in `.github/workflows/coverage.yml`** — raised from aspirational `50` (which never measured anything) to a real `10` floor based on the Slice 2 baseline. Ratchets up with each subsequent slice.
+- **`dot ai` runs probes in parallel** — the 14-tool cold-cache refresh now runs via `xargs -P` (defaults to `$(nproc)` workers, override via `DOTFILES_AI_PROBE_JOBS`). Cold-cache wall-time on a fast laptop: 6.2s → 1.9s. Warm-cache (within the 5-min TTL): ~0.07s, unchanged.
+
+### Fixed
+
+- **`core.hooksPath` config gap** — the global `commit-msg` hook is now tracked under chezmoi and pointed at by the user's git config, so the AI-attribution trailer fires on every commit.
+- **Liquid templating false-mangle of chezmoi snippets in docs** — 14 files containing `{{ … }}` Go-template syntax inside code blocks were being silently evaluated as Liquid by Jekyll. Bulk-wrapped with `{% raw %}` / `{% endraw %}`.
+- **Multiple `A && B || C` antipatterns** — restructured to proper `if/then/else` blocks across `tests/fuzz/fuzz_install.sh`, `tests/snapshots/test_snapshots.sh`, three diagnostics tests, two security tests, and `tests/unit/security/test_pre_push_bypass.sh`.
+- **macOS reliability gate** — the `cov_exercise_script` helper now probes for `timeout` then `gtimeout` (coreutils on macOS) before falling back to no-timeout. The previous version returned `rc=127` for every script on macOS-latest.
+- **Windows chezmoi installer fallback** — `setup-chezmoi` composite action now uses the upstream installer's `-t v$version` flag on Windows (Git Bash). The previous positional-arg form made chezmoi try to run itself as a subcommand and exit non-zero.
+- **Typos hook allowlist** — added 9 entries for alias names (`yout`, `hom`, `cod`, `dsk`, `dwn`, `mus`, `pic`, `wth`) and SLSA terminology (`intoto`, `writeable`) that the hook incorrectly flagged.
+- **`scripts/ci/check-insecure-tls.sh` and `compliance-guard.yml`** — both now exclude themselves and the `tests/` tree from the curl/wget/chmod pattern scans. The scanners were flagging their own legitimate pattern fixtures.
+- **`dot health --fix` chezmoi-sync detection** — `chezmoi status` output has two columns: column 1 (last-applied vs. actual) and column 2 (actual vs. target). The health dashboard previously counted both columns, so a single uncommitted edit to a source file (column-1-only drift, normal during development) was reported as "1 file out of sync" even though `chezmoi apply` had nothing to fix. The dashboard now counts only column-2 drift (the apply-actionable kind) and surfaces source-only drift as an informational footnote.
+- **`dot health --fix` post-apply verification** — `heal_chezmoi_drift` previously ran `chezmoi apply --force` via `_pkg_install`, which silenced stdout/stderr. When apply partially failed (e.g., on conflicting files), the next health-check pass showed the same drift count and the user had no signal that anything was wrong. The heal now captures the apply log, re-runs `chezmoi status` to verify the drift cleared, and reports either "✓ X file(s) synced" or "⚠ X applied, Y still drifted — run `chezmoi diff` to inspect". On hard failure, the last 5 lines of the apply log are surfaced inline.
+- **`ui_spinner_stop` rc=1 on a TTY** — the function's last line was `[[ ! -t 1 ]] && printf "\n"`, which evaluates to rc=1 when stdout is a TTY. Under `set -euo pipefail`, that rc killed every caller, including `_ai_refresh_status_cache` — silently leaving the user with an empty cache file. Added explicit `return 0`.
+- **macOS `xargs -I{} -n1` payload splitting** — `_ai_refresh_status_cache` originally passed `-n1` on top of `-I{}`, which on BSD-xargs triggers a quirk where the input line is word-split on whitespace. Entries like `"0|Agents (autonomous)|…"` arrived as `["0|Agents", "(autonomous)|…", …]`, garbling every probe. Removed the `-n1` (it's redundant with `-I{}`).
+- **macOS `xargs` apostrophe-quote bug** — BSD-xargs reads `Block's coding agent` as an unterminated single quote, aborts parsing, and drops every record after the offending one. Switched the probe pipeline to null-delimited input (`printf '%s\0' …` + `xargs -0`). This was masking Goose's presence: it had been silently absent from `dot ai` even when installed.
+- **AI dispatcher route gaps** — four bridge tools (`autohand`, `vibe`, `qwen`, `zai`) were accepted by the bridge `case` in `ai.sh` but missing from the route table in `dot_local/bin/executable_dot`. `dot autohand …` was hitting "Unknown ai command". Routes filled in.
+- **`run_ai_with_context` missing handlers for Goose and Codex** — `dot codex "prompt"` and `dot goose "prompt"` would route correctly through the dispatcher and bridge case but then fall through to "Unsupported tool" because the per-tool execution case was missing. Added `codex)` and `goose)` arms.
+
+### Security
+
+- **OIDC trusted publishing for npm** — see Added above. Drops the long-lived `NPM_TOKEN` from CI.
+- **SHA-pinned GitHub Actions everywhere** — confirmed across all workflows after the Dependabot consolidation.
+- **`bash-dbgsym` not required** — the kcov-based coverage runner needed Ubuntu's debug symbols for bash, which created a supply-chain question (additional apt source). The xtrace replacement removes that requirement.
+
 ## v0.2.500
 
 ### Added
+
 - **Wallpaper-driven theme engine** — themes are no longer hand-crafted. `extract-theme.py` uses K-Means clustering in CIELAB color space to extract dominant colors from any wallpaper image and generate a full terminal palette (16 ANSI colors, accent, bg/fg, panel, border) with WCAG AAA contrast enforcement.
 - **Automatic wallpaper discovery** — `rebuild-themes.sh` scans system wallpapers (macOS `/System/Library/Desktop Pictures/`, Linux `/usr/share/backgrounds/`) and custom wallpapers (`~/Pictures/Wallpapers/`). Custom overrides system. Themes are cached and only regenerated when wallpapers change.
 - **`dot theme rebuild`** — new command to regenerate themes from discovered wallpapers. Supports `--force` (ignore cache) and `--list` (show wallpapers without rebuilding). Parallel processing (4 jobs).
@@ -14,22 +78,26 @@ This file documents all notable changes to this project.
 - **Build artifact redirection** — Cargo, Go, pip, uv, Zig caches → `/tmp/builds/`.
 
 ### Changed
+
 - **themes.toml is now auto-generated** — run `dot theme rebuild` after adding wallpapers. Do not edit manually.
 - **Theme family derived from themes.toml** — `get_theme_family()` in `switch.sh` reads the `family` field dynamically instead of hardcoded case patterns.
 - **macOS appearance refresh** — kills cfprefsd/SystemUIServer/Dock/System Settings after accent changes.
 - **Graceful wallpaper fallback** — theme switching works without custom wallpapers. Core changes (colors, accent, dark/light) always apply; wallpaper is optional.
 
 ### Removed
+
 - **Static theme definitions** — all hand-crafted theme entries replaced by wallpaper-driven generation.
 
 ## v0.2.497
 
 ### Added
+
 - **Verified chezmoi installer** — `install.sh` prefers `scripts/ci/install-chezmoi-verified.sh` with SHA256 checksum validation before falling back to `get.chezmoi.io`.
 - **detect-secrets baseline** — `.secrets.baseline` for pre-commit secret scanning alongside gitleaks.
 - **Lua plugin module headers** — `@module` docstrings for ui.lua, coding.lua, lsp.lua, editor.lua, dap.lua explaining plugin selection rationale.
 
 ### Changed
+
 - **CI hardening** — Pinned `nix-installer` to SHA, removed `continue-on-error` from Home Manager build, replaced `mapfile` with portable `while read` loops.
 - **Plugin version pins** — toggleterm pinned to `^2`, venv-selector uses `version = false` instead of `branch = "main"`.
 - **DAP port configurable** — `DAP_DEV_SERVER_PORT` environment variable overrides default port 3000.
@@ -38,6 +106,7 @@ This file documents all notable changes to this project.
 - **Documentation** — Fixed default shell reference (Zsh → Fish) in INSTALL.md, added CI badge and test runner to README, added function docstrings to `utils.sh`.
 
 ### Fixed
+
 - **Shell compatibility** — Replaced zsh-only `unfunction` with POSIX `unset -f` in shell templates.
 - **Quote nesting** — Fixed broken double-quote nesting in `run_onchange_after_fonts.sh.tmpl`.
 - **Quoted expansion** — Added missing quotes around `$ZINIT_HOME` in zinit bootstrap.
@@ -47,6 +116,7 @@ This file documents all notable changes to this project.
 ## v0.2.496
 
 ### Added
+
 - **Startup budget tracking** — CI now captures per-component timing from `DOTFILES_DEBUG=1` and fails on regression.
 - **Behavioral unit tests** — 10 critical functions now have runtime behavior tests (extract, genpass, encode64, path_prepend, platform detection, lazy loaders).
 - **Property-based tests** — `property_testing.sh` framework wired up with roundtrip, idempotence, and length-invariant tests.
@@ -54,6 +124,7 @@ This file documents all notable changes to this project.
 - **Nix CI gate** — Home Manager activation package built and validated in CI.
 
 ### Changed
+
 - **Performance** — Lazy-loaded `thefuck` (~200ms saving) and cached `carapace` output via `_cached_eval` (~50ms saving).
 - **Starship timeout** — Reduced `command_timeout` from 2000ms to 500ms for snappier prompts in large repos.
 - **PATH consolidation** — All PATH mutations now originate from `00-core-paths.sh.tmpl`; removed scattered prepends from zshenv/zprofile stubs.
@@ -61,6 +132,7 @@ This file documents all notable changes to this project.
 - **dot CLI modular split** — Subcommands dispatched to individual scripts in `scripts/dot/commands/` for maintainability.
 
 ### Fixed
+
 - **Security** — Replaced `curl|sh` pipes in `heal.sh` (starship, atuin) with download-to-temp + shebang validation. Pinned all heal.sh GitHub release versions with SHA256 checksums.
 - **Security** — `install.sh` now uses the secure `install/lib/chezmoi.sh` library instead of inline `curl|sh`.
 - **Security** — `dot-bootstrap` Nix installer now downloads to temp file with validation before execution.
@@ -74,12 +146,14 @@ This file documents all notable changes to this project.
 ## v0.2.495
 
 ### Fixed
+
 - **Installation failure (Issue #807)**: Resolved "unbound variable" errors in `install.sh` by correctly initializing color and path variables.
 - **Shell Compatibility**: Fixed syntax errors when running `install.sh` with `sh` by ensuring the script runs with `bash` and updating documentation accordingly.
 - **Broken Links**: Updated installation instructions in `README.md` and `docs/guides/INSTALL.md` to use the GitHub raw URL, bypassing issues with the `dotfiles.io` redirect.
 - **Documentation Sync**: Synchronized versioning and installation commands across all documentation and source files.
 
 ### Changed
+
 - **Repository Restructuring**: Reorganized non-deployed files for improved discoverability.
   - Docs categorized into `architecture/`, `guides/`, `reference/`, `security/`, `operations/` subdirectories.
   - Tests promoted to top-level `tests/` with domain-based unit test subdirectories.
@@ -92,17 +166,20 @@ This file documents all notable changes to this project.
 ## v0.2.493
 
 ### Added
+
 - Implementation of `_cached_eval` for Zsh, Bash, and Fish for ultra-fast startup.
 - Full integration of `zoxide` and `atuin` in Nushell with caching.
 - Explicit management of `sgpt`, `poetry`, `fisher`, `micro`, and `pueue` configs.
 - Robust `target_os` detection for Arch/CachyOS in `install.sh`.
 
 ### Changed
+
 - Refactored `install.sh` to use a modular `main()` function.
 - Moved XDG exports in `dot_bashrc` above interactive checks.
 - Optimized Zellij configuration with 2026-ready UX (rounded corners, compact layout).
 
 ### Fixed
+
 - Resolved 100% of security alerts regarding `apt-get` recommendations.
 - Achieved 100.00% module test coverage with new maintenance tests.
 - Fixed Nix profile sourcing drift in `dot_zshenv`.

package/README.md

@@ -5,20 +5,35 @@
 <h1 align="center">.dotfiles</h1>
 
 <p align="center">
-  <strong>Declarative dotfiles for macOS, Linux, and WSL. Multi-shell by default, with sub-second startup, wallpaper-driven themes, and signed releases.</strong>
+  <strong>Declarative dotfiles for macOS, Linux, and WSL. Multi-shell by default. Sub-second startup. Wallpaper-driven themes. Signed releases.</strong>
 </p>
 
 <p align="center">
   <a href="https://github.com/sebastienrousseau/dotfiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=github" alt="Build" /></a>
-  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.500-blue?style=for-the-badge" alt="Version" /></a>
+  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge" alt="Version" /></a>
   <a href="https://github.com/sebastienrousseau/dotfiles/releases"><img src="https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge" alt="Downloads" /></a>
-  <a href="https://codespaces.new/sebastienrousseau/dotfiles"><img src="https://github.com/codespaces/badge.svg" alt="Open in GitHub Codespaces" /></a>
+  <a href="https://codespaces.new/sebastienrousseau/dotfiles"><img src="https://img.shields.io/badge/Open%20in-Codespaces-blue?style=for-the-badge&logo=github" alt="Open in GitHub Codespaces" /></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/dotfiles?style=for-the-badge&label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard" /></a>
 </p>
 
 ---
 
+> **Why this is different.** You won't find these three things in `mathiasbynens/`, `holman/`, or `paulirish/`. First, wallpaper-driven terminal themes. We use K-Means clustering in CIELAB and enforce WCAG AAA contrast. Second, first-class agent governance. That covers MCP policy, A2A discovery, signed attestation logs, and bounded profiles (`ask` / `plan` / `apply` / `audit`). Third, verified multi-shell parity across zsh, fish, bash, nushell, and PowerShell. The suite is tested on macOS, Linux, WSL2, and Apple Silicon CI runners. Signed commits are enforced. The installer is idempotent. The CLI heals itself.
+
 ## Install
 
+**Verified install (recommended).** Pin to a release tag. Download the installer. Check its SHA256 against the value published with the release. Then run it. See [docs/security/INSTALL_VERIFICATION.md](docs/security/INSTALL_VERIFICATION.md) for the per-release hash and how it's generated.
+
+```bash
+curl -fsSL -o /tmp/dotfiles-install.sh \
+  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.501/install.sh
+echo "4c0303a2d88d5aed98428ab0da37618c9795af4dae0e6549646c2fce5235c280  /tmp/dotfiles-install.sh" \
+  | shasum -a 256 -c
+bash /tmp/dotfiles-install.sh
+```
+
+**Trust-source one-liner** (skips the SHA check — fine for sandboxes and ephemeral CI, not recommended for primary workstations):
+
 ```bash
 bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
 ```
@@ -30,7 +45,7 @@ dot doctor        # verify installation
 dot learn         # interactive tour
 ```
 
-Requires `git` and `curl`. Works on macOS, Ubuntu/Debian, Arch, WSL2, and GitHub Codespaces.
+The install needs `git` and `curl`. The verified path also needs `shasum` or `sha256sum`. The script runs on macOS, Ubuntu, Debian, Arch, WSL2, and GitHub Codespaces.
 
 <details>
 <summary>CI/CD and Docker options</summary>
@@ -59,26 +74,27 @@ docker run --rm -e DOTFILES_NONINTERACTIVE=1 ubuntu:24.04 bash -c \
 
 ## Why this repo is different
 
-Most dotfiles repos are personal collections. This one ships as workstation infrastructure: signed, attested, multi-platform, AI-aware, and self-healing.
+Most dotfiles repos are personal collections. This one ships as workstation infrastructure. It's signed, attested, multi-platform, AI-aware, and self-healing.
 
 | Capability | What you get | Where |
 |:---|:---|:---|
-| **Wallpaper-Driven Themes** | K-Means clustering in CIELAB extracts terminal palettes from any wallpaper. WCAG AAA enforced. Dynamic HEIC dark/light. | `dot theme rebuild` |
-| **AI & MCP Native** | Agent profiles, MCP policy enforcement, attestation logs, AI commit messages | `dot ai`, `dot mcp`, `dot agent`, `dot mode` |
-| **Cryptographic Attestation** | Signed commits, machine-readable evidence, policy bundle releases | `dot attest`, `dot verify` |
-| **Fleet Management** | Multi-node drift dashboard, per-host profiles | `dot fleet` |
-| **Self-Healing** | Auto-repair tools, chezmoi drift, broken symlinks, missing files | `dot heal`, `dot chaos`, `dot rollback`, `dot bundle` |
-| **Sub-second Startup** | Lazy loading, `_cached_eval` pattern, mtime-based cache invalidation | `dot benchmark`, `dot perf` |
-| **Multi-shell Parity** | Fish, Zsh, Nushell, PowerShell share one templated baseline | `dot env`, `dot profile` |
-| **Build Artifacts → /tmp** | Cargo, Go, pip, uv, Zig caches redirected; project dirs stay clean | `~/.config/mise/config.toml`, `~/.cargo/config.toml` |
-| **Encrypted Secrets** | Age + SOPS for per-machine secrets out of plaintext history | `dot secrets` |
-| **Portable Runtimes** | Mise for managed toolchains, Nix Flakes for strict reproducibility | `dot env`, `dot upgrade` |
+| **Wallpaper-driven themes** | K-Means clustering in CIELAB extracts terminal palettes from any wallpaper. WCAG AAA enforced. Dynamic HEIC dark/light. | `dot theme rebuild` |
+| **AI and MCP native** | Agent profiles, MCP policy enforcement, attestation logs, AI commit messages. | `dot ai`, `dot mcp`, `dot agent`, `dot mode` |
+| **Cryptographic attestation** | Signed commits, machine-readable evidence, policy bundle releases. | `dot attest`, `dot verify` |
+| **Fleet management** | Multi-node drift dashboard, per-host profiles. | `dot fleet` |
+| **Self-healing** | Auto-repair tools, chezmoi drift, broken symlinks, missing files. | `dot heal`, `dot chaos`, `dot rollback`, `dot bundle` |
+| **Sub-second startup** | Lazy loading, `_cached_eval` pattern, mtime-based cache invalidation, realpath sidecar pins. | `dot benchmark`, `dot perf` |
+| **Multi-shell parity** | Tier-1 (full): zsh, bash. Tier-2 (bridged): fish. Tier-3 (compatible): nushell. PowerShell is supported as a contract-tested parity target. See [ADR-007](docs/adr/ADR-007-multi-shell-parity.md) and [ADR-011](docs/adr/ADR-011-nushell-tier3-keep.md). | `dot env`, `dot profile` |
+| **Build artifacts → /tmp** | Cargo, Go, pip, uv, and Zig caches redirect to `/tmp/builds/`. Project dirs stay clean. | `~/.config/mise/config.toml`, `~/.cargo/config.toml` |
+| **Encrypted secrets** | Age and SOPS keep per-machine secrets out of plaintext history. | `dot secrets` |
+| **Portable runtimes** | Mise for managed toolchains. Nix Flakes for strict reproducibility. | `dot env`, `dot upgrade` |
+| **Schema-validated config** | `.chezmoidata.toml` is checked against a JSON Schema in CI via taplo. Typos in feature flags or profile names fail at PR time. | `config/chezmoidata.schema.json` |
 
 ---
 
 ## Architecture
 
-Idempotent. Run it once or a hundred times. Same machine state.
+The CLI is idempotent. Run it once or a hundred times. Same machine state.
 
 ```mermaid
 graph TD
@@ -95,7 +111,7 @@ graph TD
     J --> K[themes.toml<br/>WCAG AAA enforced]
     K --> H
 
-    H --> L[Zsh / Fish / Bash / Nushell]
+    H --> L[Zsh / Fish / Bash / Nushell / PowerShell]
     H --> M[Mise / Nix Toolchains]
     H --> N[MCP Policy / Agent Profiles]
     L --> O[~/.cache/shell Fast Init]
@@ -109,7 +125,7 @@ graph TD
 
 Drop a wallpaper. Get a theme.
 
-`dot theme rebuild` discovers system wallpapers (macOS `/System/Library/Desktop Pictures/`, Linux `/usr/share/backgrounds/`) plus your custom wallpapers (`~/Pictures/Wallpapers/`). K-Means clustering in CIELAB color space extracts dominant colors, generates a 16-color terminal palette, enforces WCAG AAA contrast, and assembles `themes.toml` automatically.
+`dot theme rebuild` discovers system wallpapers and your custom ones. On macOS it looks in `/System/Library/Desktop Pictures/`. On Linux it looks in `/usr/share/backgrounds/`. Custom wallpapers live in `~/Pictures/Wallpapers/`. K-Means clustering in CIELAB color space extracts dominant colors. The engine then generates a 16-color terminal palette, enforces WCAG AAA contrast, and assembles `themes.toml` on its own.
 
 | Tier | Source | Format |
 |:---|:---|:---|
@@ -123,7 +139,7 @@ dot theme toggle       # swap dark↔light within current family
 dot theme rebuild      # regenerate from current wallpapers
 ```
 
-On theme switch, every managed surface updates: terminal colors (Ghostty, Alacritty, Kitty, WezTerm, tmux), editor (Neovim, VS Code), GTK/icons, macOS accent + dark mode (forced UI refresh), browser color mode, wallpaper. Linux auto-converts HEIC → PNG via `magick`/`heif-convert`.
+On theme switch, every managed surface updates. Terminals: Ghostty, Alacritty, Kitty, WezTerm, Warp, iTerm2, tmux. Editors: Neovim and VS Code. The theme also sets GTK and icon themes, the macOS accent and dark-mode toggle (with a forced UI refresh), the browser color mode, and the wallpaper. On Linux, the engine auto-converts HEIC to PNG via `magick` or `heif-convert`.
 
 Full guide: [docs/guides/THEMING.md](docs/guides/THEMING.md)
 
@@ -131,9 +147,10 @@ Full guide: [docs/guides/THEMING.md](docs/guides/THEMING.md)
 
 ## The `dot` CLI
 
-30+ commands grouped by intent. Run `dot help` for the full reference.
+Over 80 commands grouped by intent. Run `dot help` for the full reference.
 
 ### Start Here
+
 | | |
 |:---|:---|
 | `dot sync` | Apply dotfiles to this machine |
@@ -141,42 +158,52 @@ Full guide: [docs/guides/THEMING.md](docs/guides/THEMING.md)
 | `dot learn` | Open the guided tour |
 
 ### Daily Use
+
 | | |
 |:---|:---|
-| `dot status` / `dot diff` | Show local drift / preview pending changes |
+| `dot status` / `dot diff` | Show local drift; preview pending changes |
 | `dot edit` | Open the source directory |
 | `dot upgrade` | Update tools and dotfiles |
+| `dot commit` | Generate an AI commit message from the staged diff |
 
 ### Inspect & Repair
+
 | | |
 |:---|:---|
-| `dot heal` | Auto-fix tools, chezmoi drift, broken symlinks |
+| `dot heal` | Auto-fix tools, chezmoi drift, and broken symlinks |
 | `dot rollback` | Return to a previous known-good state |
 | `dot attest` | Export workstation evidence |
 | `dot chaos` | Simulate corruption to test self-healing |
+| `dot bundle` | Create an offline tarball of the dotfiles environment |
 
 ### AI & Agents
+
 | | |
 |:---|:---|
 | `dot ai` | Show installed AI tools |
 | `dot mcp` | Inspect MCP policy and registry |
-| `dot mode` | Show or set the agent profile |
+| `dot mode` | Show or set the agent profile (ask / plan / apply / audit) |
 | `dot agent` | Agent metadata, logs, checkpoints, conformance |
+| `dot patterns` | List bundled AI patterns (architect, hardener, refactor) |
 
 ### Configuration
+
 | | |
 |:---|:---|
-| `dot theme` / `dot theme rebuild` | Switch theme / regenerate from wallpapers |
+| `dot theme` / `dot theme rebuild` | Switch theme or regenerate from wallpapers |
 | `dot env` | Show managed tool versions |
 | `dot profile` | Show or switch active profile |
 | `dot secrets` | Edit encrypted secrets |
+| `dot fonts` | Install or refresh Nerd Fonts |
 
 ### Fleet & Performance
+
 | | |
 |:---|:---|
-| `dot fleet` | Multi-node status, drift, namespace |
+| `dot fleet` | Multi-node status, drift, and namespace |
 | `dot benchmark` / `dot perf` | Measure shell startup |
-| `dot score` | Health and security scorecard |
+| `dot score` / `dot security-score` | Health and security scorecards |
+| `dot prewarm` | Warm caches for the first interactive shell |
 
 Full reference: [docs/reference/UTILS.md](docs/reference/UTILS.md) · Complete manual: [docs/manual/](docs/manual/) or `dot manual`
 
@@ -184,12 +211,12 @@ Full reference: [docs/reference/UTILS.md](docs/reference/UTILS.md) · Complete m
 
 ## Documentation
 
-The `.dotfiles` Manual is published in 9 formats: HTML (single + multi-page), PDF, EPUB, ASCII text, compressed variants, Markdown source. Auto-built on every change.
+The `.dotfiles` Manual is published in nine formats: HTML (single and multi-page), PDF, EPUB, ASCII text, compressed variants, and Markdown source. It auto-builds on every change.
 
 - **Online** — <https://sebastienrousseau.github.io/dotfiles/manual/>
 - **Terminal** — `dot manual text | less`
 - **PDF** — `dot manual pdf`
-- **Offline bundle** — `dot bundle --manual`
+- **Offline copy** — `dot manual --offline` (uses the bundled snapshot, no network)
 - **Sources** — [`docs/manual/`](docs/manual/)
 
 ---
@@ -197,10 +224,10 @@ The `.dotfiles` Manual is published in 9 formats: HTML (single + multi-page), PD
 ## First 5 Minutes
 
 1. **Check** — `dot doctor` validates tools, paths, and security
-2. **Explore** — `dot learn` walks through shells, secrets, themes, performance
+2. **Explore** — `dot learn` walks through shells, secrets, themes, and performance
 3. **Customize** — edit `~/.config/chezmoi/chezmoi.toml` for per-machine settings ([Profiles](docs/reference/PROFILES.md))
 4. **Toggle features** — flip features in `.chezmoidata.toml` ([Feature Flags](docs/reference/FEATURES.md))
-5. **Apply** — `dot sync` applies the config; `dot prewarm` caches shell startup
+5. **Apply** — `dot sync` applies the config and `dot prewarm` caches shell startup
 
 See the [Migration Guide](docs/operations/MIGRATION.md) for version upgrades.
 
@@ -213,9 +240,12 @@ See the [Migration Guide](docs/operations/MIGRATION.md) for version upgrades.
 
 - **Zsh** loads in stages through small modules, not one big startup script
 - **Fish** uses `_cached_eval` and deferred loading for fast interactive use
-- **Nushell** handles structured terminal workflows
-- **PowerShell** keeps cross-platform and WSL sessions on the same baseline
+- **Bash** ships full parity with zsh for tooling and aliases
+- **Nushell** handles structured terminal workflows (Tier-3 compatible)
+- **PowerShell** keeps cross-platform and WSL sessions on the same baseline. A `pwsh` parity contract runs in CI on every PR
 - **Starship**, **Zoxide**, **Atuin**, and **fzf** for navigation and command recall
+- **Starship Transient Prompt** collapses past prompts to a single glyph in scrollback on fish. The zsh hook is in place for when upstream Starship lands the matching function ([ADR-010](docs/adr/ADR-010-starship-transient-prompt.md))
+
 </details>
 
 <details>
@@ -226,31 +256,38 @@ See the [Migration Guide](docs/operations/MIGRATION.md) for version upgrades.
 - **Pueue** queues long-running tasks instead of spawning extra terminal tabs
 - **Neovim** ships as a full Lua-based editor, not a starter template
 - **Lazygit** for terminal git workflow without a GUI
-- **Build caches** (Cargo, Go, pip, uv, Zig) redirected to `/tmp/builds/` — cleared on reboot
+- **Build caches** (Cargo, Go, pip, uv, Zig) redirect to `/tmp/builds/` and clear on reboot
+- **`_cached_eval`** caches expensive `tool init` output with mtime and realpath invalidation. Set `EVALCACHE_DISABLE=true` to bypass for debugging
+
 </details>
 
 <details>
 <summary><b>AI, Agents, and MCP</b></summary>
 
-- **Agent profiles** (`dot mode`) — switch between architect, hardener, refactor patterns
-- **MCP policy enforcement** (`dot mcp`) — validate Model Context Protocol registry against policy
-- **AI commit messages** (`dot commit`) — conventional commits generated from staged diff
-- **AI tools** (`dot ai`) — Claude Code, Codex, GitHub Copilot, Gemini CLI managed via Mise
-- **Attestation logs** — every agent session logged with policy hash + outcome
+- **Agent profiles** (`dot mode`) — switch between ask, plan, apply, and audit
+- **Pattern library** (`dot patterns`) — architect, hardener, and refactor patterns bundled in `dot_config/ai/patterns/`
+- **MCP policy enforcement** (`dot mcp`) — validate the Model Context Protocol registry against policy
+- **AI commit messages** (`dot commit`) — conventional commits generated from the staged diff
+- **AI tools** (`dot ai`) — Claude Code, Codex, GitHub Copilot, Gemini CLI, and friends managed via Mise
+- **Attestation logs** — every agent session is logged with a policy hash and an outcome
+
 </details>
 
 <details>
 <summary><b>Security, Trust, and Governance</b></summary>
 
-- **Age + SOPS** keep secrets encrypted at rest and out of plaintext history
-- **SSH ED25519 signing** + trust metadata back signed commits and verifiable changes
-- **Gitleaks**, policy checks, compliance workflows
-- **Workstation attestation** (`dot attest`) records machine state, policy, prompt, model metadata in tracked JSON
+- **Age and SOPS** keep secrets encrypted at rest and out of plaintext history
+- **SSH ED25519 signing** plus trust metadata back signed commits and verifiable changes
+- **Gitleaks**, policy checks, and compliance workflows
+- **Workstation attestation** (`dot attest`) records machine state, policy, prompt, and model metadata in tracked JSON
 - **Telemetry controls** and local-first defaults — you own your data
-- **SBOM (CycloneDX)** + Grype CVE scanning in CI
+- **SBOM (CycloneDX)** and Grype CVE scanning in CI
+- **JSON Schema for `.chezmoidata.toml`** — taplo runs the schema in CI on every PR, so typos in feature flags or profile names fail before merge
+- **OIDC Trusted Publishing** — npm releases authenticate via OIDC, not a long-lived `NPM_TOKEN`. Provenance is attached to every published tarball
+
 </details>
 
-For security hardening options, see [Security docs](docs/security/SECURITY.md).
+For security hardening options, see the [Security docs](docs/security/SECURITY.md).
 
 ---
 
@@ -267,6 +304,7 @@ For security hardening options, see [Security docs](docs/security/SECURITY.md).
 | Fleet management | ✓ | — | — | — |
 | Encrypted secrets (Age/SOPS) | ✓ | ✓ | — | — |
 | Build artifact redirection | ✓ | — | — | — |
+| Schema-validated config | ✓ | — | — | — |
 
 `chezmoi` is the underlying templating engine. This repo is the opinionated reference implementation.
 

package/docs/.vitepress/reports/localization-readability-audit.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Localization Readability Audit
 
 Note: Flesch metrics are English-centric. For localized pages, they are used as a plain-language proxy when Latin word boundaries are available.

package/docs/AI.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # AI Integrations (Opt-in)
 
 AI helpers are **off by default**. You choose if and when to turn them on.
@@ -25,7 +29,7 @@ Use the `dot` CLI to run AI tools with added context:
 
 ```bash
 # General usage
-dot cl|copilot|gemini|kiro|sgpt|ollama|opencode|aider|autohand|vibe|qwen|zai --pattern <name> "prompt"
+dot cl|codex|copilot|gemini|goose|kiro|sgpt|ollama|opencode|aider|autohand|vibe|qwen|zai --pattern <name> "prompt"
 
 # Quick aliases
 dcla "Optimize my zshrc"      # Claude + Architect
@@ -40,8 +44,10 @@ Supported bridge commands:
 | Command | Provider |
 |---------|----------|
 | `dot cl` | Claude Code |
+| `dot codex` | OpenAI Codex CLI |
 | `dot copilot` | GitHub Copilot CLI |
 | `dot gemini` | Gemini CLI |
+| `dot goose` | Goose (Block) |
 | `dot kiro` | Kiro CLI |
 | `dot sgpt` | Shell-GPT |
 | `dot ollama` | Ollama |
@@ -78,7 +84,7 @@ Related AI commands:
 
 These tools are not installed for you. Pick and install only the ones you want:
 
-- **Agents**: `claude`, `copilot`
+- **Agents**: `claude`, `codex`, `copilot`, `goose`
 - **Coding assistants**: `aider`, `opencode`
 - **General AI**: `gemini`, `sgpt`
 - **Local-first**: `ollama`

package/docs/CNAME

@@ -0,0 +1 @@
+doc.dotfiles.io

package/docs/COPYRIGHT

@@ -1,5 +1,5 @@
 /*
-* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.500) - <https://github.com/sebastienrousseau/dotfiles>
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.501) - <https://github.com/sebastienrousseau/dotfiles>
 * Made With ❤️ in London, United Kingdom
 * Designed by
 * Copyright (c) 2015-2026. All rights reserved.

package/docs/NAMING_CONVENTIONS.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Naming Conventions & Standardization Guide
 
 This document defines the naming conventions for all files in the dotfiles repository.
@@ -93,3 +98,5 @@ docs/             # Documentation and GitHub Pages source
   security/       # Security documentation
   operations/     # Ops and maintenance docs
 ```
+
+{% endraw %}

package/docs/README.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Documentation
 
 Start here. Then go deeper.

package/docs/_config.yml

@@ -0,0 +1,59 @@
+title: ".dotfiles"
+description: "Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL — published at doc.dotfiles.io."
+url: "https://doc.dotfiles.io"
+baseurl: ""
+
+# Jekyll renders this site from docs/ — see .github/workflows/pages.yml.
+# Theme is the GitHub-hosted Cayman skin (zero-Gemfile setup); switch to
+# `remote_theme: just-the-docs/just-the-docs` later if a richer
+# navigation/search UX is wanted (requires plugin allowlist update on
+# GH Pages side).
+theme: jekyll-theme-cayman
+
+plugins:
+  - jekyll-relative-links
+  - jekyll-seo-tag
+  - jekyll-sitemap
+  - jekyll-redirect-from
+  # Renders `README.md` as the directory index where present (matches
+  # the GitHub-browse experience for users coming from the repo links
+  # in docs/index.md).
+  - jekyll-readme-index
+
+relative_links:
+  enabled: true
+  collections: true
+
+# Treat *.md as pages so cross-page links work without trailing-slash
+# kludges; include CNAME so the published artifact preserves it across
+# workflow deploys.
+include:
+  - CNAME
+  - .well-known
+
+exclude:
+  - "*.tmpl"
+  - "manual/_toc.yml"
+  - "scripts/"
+  - "Gemfile"
+  - "Gemfile.lock"
+  - "vendor/"
+
+markdown: kramdown
+kramdown:
+  input: GFM
+  syntax_highlighter: rouge
+  hard_wrap: false
+
+# Many of our docs include chezmoi/Go-template snippets like
+# `{{ .variable }}` inside fenced code blocks. Liquid runs BEFORE
+# kramdown sees those fences and would try to resolve the placeholders
+# as Liquid expressions (silently dropping them from the output). Each
+# .md file therefore carries explicit `render_with_liquid: false` in
+# its frontmatter — a site-wide default in this block was not honored
+# reliably, so we keep the kill-switch per-page instead.
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default