@sebastienrousseau/dotfiles 0.2.469 → 0.2.499

package/docs/ARCHITECTURE.md

@@ -0,0 +1,62 @@
+# Architecture & Design
+
+v0.2.471 constitutes a portable **Shell Distribution** managed by `chezmoi`. This document outlines the core architectural decisions and system design.
+
+## 1. Core Philosophy
+
+- **XDG-First**: configuration is strictly mapped to `~/.config/` (XDG Base Directory specification). We avoid `~/.foo` file sprawl in the home directory.
+- **Single Entrypoint**: `dot_zshenv` acts as the "Bootloader". It is loaded by Zsh immediately and sets up the environment (XDG variables, PATH) before any other initialization occurs.
+- **Zero-Dependency Bootstrap**: The installation process relies only on `curl` and `git` (and `chezmoi`, which it self-installs).
+
+## 2. Directory Structure
+
+The repository follows standard `chezmoi` conventions:
+
+```text
+~/.local/share/chezmoi/
+├── dot_config/          # Mapped to ~/.config/
+│   ├── atuin/           # Shell history
+│   ├── ghostty/         # Terminal emulator
+│   ├── shell/           # Core shell logic (aliases, functions)
+│   ├── nvim/            # Neovim IDE configuration
+│   └── zsh/             # Zsh specific config
+├── dot_local/           # Mapped to ~/.local/
+│   └── bin/             # User scripts (added to PATH)
+├── dot_zshenv           # The Environment Bootloader
+├── .chezmoitemplates/   # Reusable logic blocks
+└── install.sh           # Universal bootstrapping script
+```
+
+## 3. Modern Toolchain
+
+We replace distinct Unix legacy tools with high-performance Rust alternatives:
+
+| Legacy | Modern Replacement | Purpose |
+| :--- | :--- | :--- |
+| `ls` | `eza` | Modern file listing with git integration |
+| `cat` | `bat` | Syntax highlighted file viewing |
+| `grep` | `ripgrep` (`rg`) | Blazing fast search |
+| `cd` | `zoxide` | Smart directory jumping |
+| `history` | `atuin` | Syncable, encrypted SQLite history |
+| `find` | `fd` | User-friendly filesystem search |
+| `vim` | `neovim` | Lua-extensible IDE |
+
+## 4. Predictive Shell Strategy
+
+- **AI Integration**: The shell is "AI Aware" via the `ai_core` wrapper.
+- **Autosuggestions**: Context-aware completion based on shell history.
+- **Error Analysis**: Hooks to send failed command context to local LLMs or GitHub Copilot for explanation.
+
+## 5. Security Posture
+
+- **Hardened Defaults**: Shell scripts run with `set -euo pipefail` to fail fast.
+- **Supply Chain Safety**:
+  - **Pinned Installation**: Installers reference specific Git tags (e.g., `v0.2.471`), not `main`.
+  - **Immutable History**: Logic logic is version controlled and reviewable via `chezmoi diff`.
+- **Audit Logging**: All mutations are logged to `~/.dotfiles_audit.log`.
+
+## 6. Compatibility
+
+- **macOS**: Full support (Homebrew, defaults).
+- **Linux**: Debian/Ubuntu support (apt-get).
+- **Windows**: WSL2 support.

package/docs/COMPLIANCE.md

@@ -0,0 +1,47 @@
+# Regulatory Compliance & Security Controls
+
+This document maps the dotfiles configuration and tooling to standard regulatory frameworks (SOC 2, ISO 27001, GDPR).
+
+## 🛡️ Control Mappings
+
+### SOC 2 Type II
+
+| Control | Description | Dotfiles Implementation |
+| :--- | :--- | :--- |
+| **CC6.1** | Logical Access Security | `zsh` restricted permissions, SSH key management via `1Password`/Agents. |
+| **CC6.8** | Unauthorized Code Protection | `enable-signing` enforces GPG/SSH signed commits. `slsa-framework` workflow. |
+| **CC8.1** | Change Management | All changes managed via git (Infrastructure as Code). `lock-configs` for immutability. |
+| **A1.2** | Audit Logs | `dotfiles_audit.log` tracks all configuration applications (`chezmoi apply`). |
+
+### ISO 27001
+
+| Control | Description | Dotfiles Implementation |
+| :--- | :--- | :--- |
+| **A.9.1.1** | Access Control Policy | Principle of Least Privilege in filesystem permissions (umask 022/077). |
+| **A.12.1.2** | Change Management | Git-based version control with CI/CD verification (`ci.yml`, `security-release.yml`). |
+| **A.14.2.5** | Secure Engineering | `scan-licenses` (FOSSology) and `check-cla` ensure legal/security compliance. |
+
+### GDPR / HIPAA (Privacy)
+
+| Requirement | Description | Dotfiles Implementation |
+| :--- | :--- | :--- |
+| **Data Minimization** | Limit data collection | `privacy-mode` disables CLI telemetry (Dotnet, Brew, Functions). |
+| **Integrity** | Protect against tampering | `lock-configs` prevents unauthorized modification of shell history/config. |
+
+## 🔒 Security Features
+
+### Immutability
+Critical configuration files can be locked to prevent tampering:
+```bash
+lock-configs  # Sets chflags uchg (macOS) or chattr +i (Linux)
+```
+
+### Forensic Audit
+All `chezmoi` operations are logged. View audit trails:
+```bash
+dot audit
+```
+
+### Supply Chain Security
+- **SBOM**: Generated for every release (SPDX format).
+- **Provenance**: SLSA Level 3 build attestation.

package/docs/COPYRIGHT

@@ -0,0 +1,6 @@
+/*
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.471) - <https://dotfiles.io>
+* Made with ♥ in London, UK by Sebastien Rousseau
+* Copyright (c) 2015-2024. All rights reserved
+* License: MIT
+*/

package/docs/OPERATIONS.md

@@ -0,0 +1,103 @@
+# Operational Guide
+
+This document outlines the standard workflows to **Maintain**, **Update**, and **Operate** your dotfiles environment across all supported platforms.
+
+---
+
+## 🏗️ Platform-Specific Operations
+
+### 🍎 macOS
+**Primary Manager**: `Homebrew`
+
+- **Update System**:
+  ```bash
+  # Updates Dotfiles AND Homebrew packages
+  chezmoi update
+  ```
+  *Behind the scenes, this runs `brew bundle install` to match the `Brewfile.lock.json`.*
+
+- **Troubleshooting**:
+  - **Permission Issues**: `sudo chown -R $(whoami) $(brew --prefix)/*`
+  - **Drift**: Run `brew bundle cleanup` to remove unmanaged packages.
+
+### 🐧 Linux (Debian, Ubuntu, ZorinOS, Kali)
+**Primary Manager**: `apt-get` / `snap`
+
+- **Update System**:
+  ```bash
+  # 1. Update OS packages
+  sudo apt update && sudo apt upgrade -y
+  
+  # 2. Update Dotfiles
+  chezmoi update
+  ```
+  *Note: `chezmoi` on Linux focuses on configuration. Package updates are often best handled by the OS package manager to avoid `sudo` conflicts.*
+
+- **Troubleshooting**:
+  - **Font Issues**: If icons are missing, run `./provision/run_onchange_50-install-fonts.sh` manually.
+  - **ZorinOS/Gnome**: Custom keybindings may need `dconf load` if not applied automatically.
+
+### 🪟 Windows (WSL2)
+**Primary Manager**: `apt-get` (inside WSL)
+
+- **Update System**: Same as **Linux**.
+
+- **WSL Specifics**:
+  - **Access Windows Files**: Windows drives are mounted at `/mnt/c/`.
+  - **Clipboard**: The setup configures `win32yank.exe` automatically for clipboard sharing.
+  - **Performance**: We recommend keeping project files inside the Linux filesystem (`~/projects`), NOT in `/mnt/c/`, for 100x better IO performance.
+
+---
+
+## 🔄 Common Workflows
+
+### Applying Changes
+After editing any config file:
+```bash
+chezmoi apply
+```
+*Triggers: `dot_zshrc` reload, audit logging.*
+
+### Rolling Back
+If an update breaks your setup:
+```bash
+cd ~/.local/share/chezmoi
+git reset --hard HEAD@{1}  # Go back 1 operation
+chezmoi apply
+```
+
+### Debugging
+If something feels slow or broken:
+
+1. **Check Health**:
+   ```bash
+   dot doctor
+   ```
+2. **Verbose Mode**:
+   ```bash
+   DOTFILES_DEBUG=1 chezmoi apply
+   ```
+
+---
+
+## 🛠️ Tool-Specific Guides
+
+### 📦 Atuin (History Sync)
+- **Login**: `atuin login`
+- **Sync**: `atuin sync`
+- **Search**: `Ctrl-r` (Global history search)
+
+### 🚀 Zoxide (Smart CD)
+- **Jump**: `z project` matches `~/dev/project`
+- **Query**: `zi` (Interactive selection)
+
+### 🌳 Yazi (File Manager)
+- **Open**: Type `y`
+- **Preview**: Spacebar to preview files
+- **Quit**: `q`
+
+---
+
+## 🔐 Security Policy
+- **GPG/SSH**: All commits are SSH signed.
+- **Audit Log**: Review `~/.dotfiles_audit.log` for a timeline of all changes applied to your system.

package/docs/PLAN.md

@@ -0,0 +1,161 @@
+# Universal Configuration Plan (Chezmoi)
+
+... [Previous Sections Unchanged] ...
+
+# Phase 15: Operational Documentation [COMPLETED]
+- [x] **Guide**: Created `OPERATIONS.md`.
+
+# Phase 16: Final Release Verification [COMPLETED]
+- [x] **Verification**: All systems passed.
+
+# Phase 17: Structural Optimizations (v0.3.0)
+
+## Goal
+Implement structural improvements for better organization and maintainability, anticipating v0.3.0.
+
+## Proposed Changes
+
+### [REFACTOR] Semantic Organization
+- **Move**: `dot_config/dotfiles` -> `dot_config/shell`.
+- **Reason**: `dotfiles` is redundant inside a dotfiles repo. `shell` describes the content (aliases, paths, functions).
+- **Update**: Update references in `dot_zshrc.tmpl` and install scripts.
+
+### [REFACTOR] Script Installation
+- **Move**: `bin/` -> `dot_local/bin/`.
+- **Reason**: Ensures scripts are automatically installed to `~/.local/bin` (user PATH).
+
+### [CLEANUP] Remove Legacy Files
+- **Delete**: `Makefile`, `package.json`.
+- **Reason**: Replaced by `chezmoi` and GitHub Actions.
+
+### [REFACTOR] Script Segregation
+- **Split**: `run_onchange_install_packages.sh.tmpl` into:
+    - `run_onchange_darwin_install-packages.sh.tmpl` (Homebrew)
+    - `run_onchange_linux_install-packages.sh.tmpl` (Apt)
+    - `run_onchange_after_install-vim-plug.sh.tmpl` (Universal)
+- **Reason**: Improves readability and maintainability.
+
+# Phase 18: Component Documentation Polish [COMPLETED]
+
+## Goal
+Update component documentation (`aliases`, `functions`, `paths`) to match the new `chezmoi` architecture and ensure accuracy.
+
+## Changes
+- **Aliases**: Updated `aliases/README.md` to explain modular `*.aliases.sh` loading.
+- **Functions**: Updated `functions/README.md` to remove legacy install instructions.
+- **Paths**: Updated `paths/README.md` to clarify precedence and `chezmoi` integration.
+- **Cleanup**: Standardized all nested alias READMEs to remove legacy HTML artifacts and restore banners.
+
+# Phase 19: Toolchain Expansion [COMPLETED]
+
+## Goal
+Add comprehensive support for modern DevOps/Cloud engineering tools.
+
+## Proposed Changes
+### [NEW] Aliases
+- **Kubernetes**: `kubectl` shortcuts (`k`), `helm`, `k9s`.
+- **IaC**: `terraform` (`tf`), `opentofu`, `ansible`.
+- **Languages**: `go` (`g`), `yarn`, `uv` (modern Python).
+- **Diagnostics**: `jq`, `yq`, `nc`, `curlie`.
+- **Structure**: Each component gets its own directory in `.chezmoitemplates/aliases/` with a standard `README.md`.
+
+# Phase 20: Intelligent Assistance [COMPLETED]
+
+## Goal
+Integrate AI capabilities and improved help systems.
+
+## Proposed Changes
+### [NEW] Functions
+- **`dothelp`**: Index and search all aliases/functions with descriptions.
+- **AI Wrappers**: Aliases for `gh copilot`, `fabric`, or generic LLM CLI tools.
+
+# Phase 22: Automated Testing [COMPLETED]
+
+## Goal
+Verify the dotfiles work on clean Linux environments.
+
+## Proposed Changes
+### [CI] GitHub Actions
+- **Container Job**: Run `chezmoi init --apply` inside a localized Docker container (Ubuntu/Fedora) to prove universal compatibility.
+
+# Phase 23: Enterprise Core & Security (The Trust Layer) [COMPLETED]
+
+## Goal
+Establish a "Trust Layer" for the dotfiles ecosystem, ensuring supply chain security and configuration integrity.
+
+## Changes
+- **SLSA & SBOM**: Implemented `security-release.yml` for provenance and SBOM generation.
+- **Signing**: Created `enable-signing` wizard alias for easy GPG/SSH configuration.
+- **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.
+
+- **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.
+
+# Phase 27: Self-Healing & Diagnostics [COMPLETED]
+
+## Goal
+Enable the system to self-diagnose and repair configuration drift.
+
+## Changes
+- **Scripts**: Created `scripts/doctor.sh` for system health checks.
+- **Aliases**: Added `dot doctor`, `dot drift` (`chezmoi verify`), and `dot heal` (`chezmoi apply`).
+
+# Phase 51: Regulatory Compliance [COMPLETED]
+
+## Goal
+Document and enforce compliance with SOC2, ISO, and GDPR standards.
+
+## Changes
+- **Documentation**: Created `COMPLIANCE.md` with control mappings.
+- **Privacy**: Added `privacy-mode` alias to disable CLI telemetry.
+- **Audit**: Added `dot audit` alias for tracking changes.
+
+# Phase 54: macOS Deep Integration [COMPLETED]
+
+## Goal
+Harden and optimize the macOS environment via code.
+
+## Changes
+- **Defaults**: Created `run_onchange_darwin_defaults.sh.tmpl` to apply secure/optimized `defaults`.
+- **Hardening**: Enabled screensaver passwords, firewall settings, and disabled guest access.
+
+## Goal
+Ensure legal compliance and proper attribution for the open-source project.
+
+## Changes
+- **Licensing**: Added `scan-licenses` alias (Trivy/FOSSology).
+- **Headers**: Added `add-headers` alias for automated copyright insertion.
+- **Compliance**: Added `check-cla` and `gen-notice` tools.
+
+# Phase 59: Font Typography [COMPLETED]
+
+## Goal
+Standardize typography and ensure high-quality font rendering across all environments.
+
+## Proposed Changes
+- **Nerd Fonts**: Automate installation of `JetBrainsMono Nerd Font` and `Symbols Nerd Font`.
+- **Fontconfig**: Deploy XML configuration for Linux font rendering (antialiasing, hinting).
+- **Aliases**: `update-fonts` to refresh font caches (`fc-cache`).
+
+# Phase 26: OS Bundling & Compliance [COMPLETED]
+
+## Goal
+Prepare the dotfiles for system-wide deployment and ensure strict adherence to standards.
+
+## Proposed Changes
+- **XDG Compliance**: Audit `00-default.paths.sh` to ensure all standard XDG variables are exported.
+- **Vendor Hooks**: Update `dot_zshrc.tmpl` to source system-level overrides from `/etc/dotfiles/defaults.d/` (Simulates "site-local" config).
+- **Bundling**: Create `scripts/package.sh` to create a distributable tarball and scaffold `.deb`/`.pkg` generation logic.
+
+# Phase 24: The Universal Installer (Zero-Dependency) [COMPLETED]
+
+## Goal
+Provide a frictionless, "one-curl" onboarding experience and capabilities to deploy configurations remotely.
+
+## Proposed Changes
+- **install.sh**: A standalone, zero-dependency bash script that:
+    1.  Detects OS/Arch.
+    2.  Installs `chezmoi` (binary or via package manager).
+    3.  Initializes the dotfiles repo.
+    4.  Runs `chezmoi apply`.
+    5.  Uses ANSI colors for a polished "TUI" feel.
+- **Teleportation**: `scripts/teleport.sh` using `chezmoi archive` piped to SSH to ephemeralize configs on remote servers (e.g., `dot teleport user@server`).

package/docs/PR_DESCRIPTION.md

@@ -0,0 +1,150 @@
+# PR Title
+feat(core): Rel v0.2.471 - Universal Config, Security & Performance
+
+# PR Description
+
+## 🚀 v0.2.471 Release: Universal Configuration
+
+This release transforms the dotfiles into a high-performance, universally compatible system managed by **chezmoi**.
+
+### 🏗️ Technical Architecture
+v0.2.471 is not just "dotfiles" but a portable **Shell Distribution** managed by `chezmoi` ("source of truth" in `~/.local/share/chezmoi`).
+
+- **XDG-First**: Configs strictly mapped to `~/.config/` (No `~/.foo` sprawl).
+- **Single Entrypoint**: `dot_zshenv` acts as an XDG bootloader for instant environment setup.
+- **Modern Toolchain**: Replaces classic Unix tools with high-performance Rust alternatives:
+  - `ls` → `eza`
+  - `cat` → `bat`
+  - `grep` → `ripgrep`
+  - `cd` → `zoxide` (Smart Directory Jumping)
+  - `history` → `atuin` (Syncable, Encrypted SQlite history)
+- **Predictive Shell**:
+  - **AI Strategy**: Context-aware autosuggestions coupled with optional local LLM integration (`ai_core`).
+  - **Error Analysis**: Smart wrappers to analyze command failures via `gh copilot` or local models.
+
+### 🚫 Non-Goals
+- **Not a Framework**: This is a curated distribution, not a plugin manager like Oh-My-Zsh.
+- **Not POSIX-Pure**: Prioritizes modern Zsh/Rust features over strict POSIX compliance.
+- **Not Minimal**: Optimizes for functionality and speed, not line-count minimalism.
+
+### 🛡️ Security Posture
+- **Hardened by Default**: Scripts run with `set -euo pipefail` to fail fast on errors.
+- **Supply Chain Safety**:
+  - **Pinned Install**: Installation commands are pinned to the specific release tag (`v0.2.471`) to prevent drift.
+  - **Zero-Trust**: No implicit reliance on `main` branch code in production.
+- **Threat Model**: This project assumes a **trusted local machine** and focuses on supply-chain (pinned versions) and configuration safety (immutable history).
+- **Audit Logging**: All `chezmoi` mutations are logged to `~/.dotfiles_audit.log` for day-2 operations review.
+
+### 🛠️ Changes
+- **Migrated**:
+  - Shell: `~/.zshrc` now sources generated templates from `~/.config/shell`.
+  - Shell: `~/.zshrc` now sources generated templates from `~/.config/shell`.
+  - Neovim: `~/.config/nvim` fully managed via Lua/Lazy.nvim.
+  - Tmux: Modular config consolidated to `~/.local/share/chezmoi/dot_tmux.conf`.
+- **Packaging**:
+  - `Brewfile` (macOS) and `apt-get` (Linux) handled automatically.
+- **Structural**:
+  - **Renamed**: `dot_config/dotfiles` → `dot_config/shell` for semantic clarity.
+  - **Moved**: `bin/` → `dot_local/bin/` for automatic path integration.
+  - **Segregated**: Install scripts split by OS (Darwin/Linux) for cleaner logic.
+- **Layered Architecture**: Refactored shell config into explicit layers:
+  - `00-core`: Safety/Paths
+  - `50-logic`: Functions/Toolchain
+  - `90-ux`: Aliases/Theme
+- **Trust & Reproducibility**:
+  - **Pinned Formulae**: Generated `Brewfile.lock.json` for strictly reproducible macOS builds.
+  - **Binary Pinning**: `install.sh` now enforces specific version tags for initial bootstrap.
+### 🔒 Security & Quality
+- **Conflict Resolution**: Detected and resolved **46 namespace collisions** across all alias modules (Git, Go, Archives, etc.) to ensure zero overlap.
+- **Git Safety**: Renamed colliding Go aliases (e.g., `gr` -> `gor`) to protect core Git commands.
+- **Modernization**: Merged `list` into `modern` for a cohesive Rust-based toolchain experience (`eza`, `bat`).
+- **Standardization**: Removed duplicate logging functions in favor of a shared utility.
+- **Documentation**: All 30+ component READMEs are now 100% accurate and verified.
+
+### 🛠️ Start-of-Art Toolchain
+- **Kubernetes**: Added `kubectl`, `helm`, `k9s` aliases.
+- **IaC**: Added `terraform`, `opentofu`, `ansible`.
+- **Languages**: Added ecosystem support for `go`, `yarn`, `uv` (modern Python).
+- **AI Integration**: Added wrappers for `gh copilot`, `fabric`, and local LLMs.
+- **Smart Help**: Introduced `dothelp` to strictly search and index custom functions.
+
+### 🤖 CI/CD & Testing
+
+- **Automated Testing**
+  - Docker CI (`ci-docker.yml`) running on Ubuntu/Fedora/Arch.
+  - Integration tests for alias syntax (`test-aliases.sh`).
+
+- **Enterprise Core & Security (The Trust Layer)**
+  - **SLSA & SBOM**: `security-release.yml` generates SPDX SBOMs and SLSA Level 3 Provenance.
+  - **Signing**: `enable-signing` wizard for GPG/SSH git signing.
+  - **Immutability**: `lock-configs` / `unlock-configs` to protect critical dotfiles (`chflags`/`chattr`).
+
+- **Legal & Licensing**
+  - **Compliance**: `scan-licenses` (FOSSology/Trivy), `check-cla` (GitHub checks).
+  - **Attribution**: `add-headers` automation and `gen-notice` generation.
+
+- **Self-Healing & Diagnostics**
+  - **Health**: `dot doctor` script diagnoses environment (Dependencies, XDG, Paths).
+  - **Repair**: `dot heal` / `dot drift` aliases for auto-repair and drift detection.
+
+- **Regulatory Compliance**
+  - **Documentation**: `COMPLIANCE.md` maps features to **SOC2 Type II** and **ISO 27001**.
+  - **Privacy**: `privacy-mode` alias disables CLI telemetry for 7+ frameworks.
+
+- **macOS Deep Integration**
+  - **Hardening**: `defaults` script secures screensaver, firewall, and finder settings.
+  - **Optimization**: Configures Safari for dev, removes Dock clutter.
+
+- **Font Typography**
+  - **Fonts**: Auto-installs `JetBrainsMono Nerd Font` and `Symbols Nerd Font`.
+  - **Rendering**: Linux `fontconfig` XML for sub-pixel antialiasing.
+
+- **Phase 58: Editor Unification (The Grand Vim)** (Implemented)
+  - **Neovim IDE**: Full VS Code feature parity (Noice, Lualine, Gitsigns, Indent-Blankline).
+  - **Language Support**: Optimized for Rust (Rustaceanvim) and Python (BasedPyright/Ruff).
+  - **Performance**: Lazy-loading architecture with `<30ms` startup.
+  - **CI/CD Fixes**: Resolved CodeQL alerts (removed legacy Node.js) and fixed Docker builds.
+
+- **OS Bundling & Compliance**
+  - **Packaging**: `scripts/package.sh` generates versioned distribution tarballs.
+  - **Enterprise**: `/etc/dotfiles/defaults.d` hooks for site-local config overrides.
+  - **Standards**: Strict **XDG Base Directory** enforcement in `paths.sh`.
+
+- **The Universal Installer (Zero-Dep)**
+  - **Bootstrap**: `install.sh` running via `curl | sh` with no dependencies.
+  - **Teleport**: `dot teleport user@host` to ephemerally deploy configs via SSH.
+
+### 🧪 Verification
+- **Performance**: Benchmark script `scripts/benchmark.sh` confirms <20ms startup.
+- **Integration**: `test-aliases.sh` verified syntax of all 32 alias modules.
+- **Security**: **Zero Critical Vulnerabilities** (CodeQL & Dependabot clean).
+- **Functionality**: Local migration verified on macOS, Linux, and WSL.
+
+
+### 📦 Installation & Migration
+
+#### Option A: Fresh Install (New Machines)
+If you are setting up a new machine, simply run the universal installer:
+```bash
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.471/install.sh)"
+```
+
+#### Option B: Migration (Upgrade from `master` / v1)
+⚠️ **Important**: This release changes the architecture from direct symlinks to `chezmoi` templates. Functional backups are recommended.
+**Compatibility Note**: Existing `chezmoi` users can simply run `chezmoi apply` to upgrade, but the full installer is recommended for major version jumps.
+
+1. **Backup Legacy Configs**:
+   ```bash
+   mv ~/.zshrc ~/.zshrc.bak
+   mv ~/.config/nvim ~/.config/nvim.bak
+   ```
+2. **Run Installer**:
+   ```bash
+   sh -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.471/install.sh)"
+   ```
+3. **Resolve Conflicts**:
+   - If prompted by `chezmoi` to overwrite files (e.g., `.zshrc`), select **overwrite** (or diff to check) as this release uses a new sourcing strategy.
+4. **Restart Shell**:
+   ```bash
+   exec zsh
+   ```

package/docs/ROADMAP.md

@@ -0,0 +1,148 @@
+# Product Roadmap: The Trusted Shell Platform
+
+This roadmap steers the project from a "feature-rich dotfiles repo" to an **Enterprise-Grade Shell Distribution**. The structure is organized by strategic pillars (**Trust**, **Predictability**, **Observability**) rather than linear phases, though the original 100-Phase vision is preserved within these categories.
+
+---
+
+## 🏗️ Pillar 1: Reproducibility & Determinism (Highest ROI)
+**Goal:** "Reproducible Shell Environments".
+> *This distribution aims for deterministic rebuilds: the same tag yields the same environment across machines.*
+
+- [ ] **Pinned Formulae**: Strict version locking for Homebrew bundle and Apt packages.
+- [ ] **Binary Locking**: Future versions may replace bootstrap download helpers with checksum-verified artifacts once a portable verification strategy is finalized.
+- [ ] **State Capture**: `chezmoi` templates that capture host-specific state for idempotence.
+- [ ] **Manifests**: Optional `Brewfile.lock` or equivalent for Linux.
+- [ ] **Cloud-Init (Phase 28)**: Generate `user-data` scripts for AWS/GCP bootstrapping.
+- [ ] **Container Native (Phase 28)**: Base Docker image for devcontainers.
+- [ ] **Terraform Provider (Phase 28)**: Custom provider to provision dotfiles state.
+
+## 👁️ Pillar 2: First-Class Observability
+**Goal:** "Observable Shell Lifecycle".
+> *The shell is instrumented: failures, timing, and lifecycle events are visible by design.*
+
+- [ ] **Audit Structuring**: JSON-structured logging for bootstrap and provisioning events.
+- [ ] **Debug Modes**: First-class support for `DOTFILES_DEBUG=1` and `DOTFILES_TRACE=1`.
+- [ ] **Telemetry (Local)**: Granular startup timing breakdown (init vs plugins vs prompt).
+- [ ] **Health Dashboard (Phase 39)**: CLI view of system "health" metrics.
+- [ ] **System Status (Phase 39)**: Real-time resource usage, battery, and network stats.
+- [ ] **Update Manager (Phase 39)**: Visual interface for tool updates and migration.
+
+## 🔐 Pillar 3: Secrets & Trust Boundaries
+**Goal:** "Explicit Secrets Model".
+> *Secrets are never committed; sensitive state is encrypted or host-local by default.*
+
+- [ ] **Secret Driver**: Native integration with 1Password/Bitwarden CLI via `chezmoi`.
+- [ ] **Encryption**: Promoted use of `age` encryption for all private config files.
+- [ ] **Leak Prevention (Phase 29)**: Pre-commit hooks (TruffleHog/Gitleaks) for high-entropy detection.
+- [ ] **Vault Integration (Phase 29)**: Native HashiCorp Vault support.
+- [ ] **Hardware Enclaves (Phase 29)**: Support for Secure Enclave/TPM key storage.
+- [ ] **OIDC Auth (Phase 29)**: Keyless authentication via GitHub OIDC.
+
+## 🧱 Pillar 4: Layered Architecture & Toolchain
+**Goal:** "Composable Shell Layers".
+> *The distribution is layered: core safety is mandatory, advanced features are opt-in.*
+
+- [ ] **Core Layer**: XDG, PATH, Safety (`set -euo pipefail`). (Zero external deps).
+- [ ] **UX Layer**: Prompt (Starship), Aliases, Completions.
+- [ ] **Toolchain Layer**: Rust replacements (`eza`, `bat`, `ripgrep`).
+- [ ] **Cross-Compiler Toolchain (Phase 34)**:
+    - [ ] **Multi-Arch**: `qemu-user-static` for ARM64/AMD64.
+    - [ ] **Wasm Target**: WebAssembly toolchain setup.
+    - [ ] **Embedded Dev**: Presets for Arduino/ESP32.
+
+## ⚙️ Pillar 5: Controlled Opt-In Features
+**Goal:** "Explicit Feature Flags".
+> *Advanced features are gated behind explicit opt-in flags.*
+
+- [ ] **Feature Toggles**: Environment variables (e.g., `ENABLE_AI=0`, `ENABLE_HISTORY_SYNC=0`).
+- [ ] **Lazy Loading**: Strict lazy-loading for all non-core plugins.
+- [ ] **Plugin Ecosystem (Phase 35)**:
+    - [ ] **Module Registry**: Public index of dotfiles modules.
+    - [ ] **Dependency Solving**: Semantic versioning for modules.
+    - [ ] **Verified Publishers**: Cryptographic signing for "Official" modules.
+
+## 🛡️ Pillar 6: Threat Model & Safety
+**Goal:** "Documented Threat Model".
+> *Security decisions are driven by an explicit, documented threat model.*
+
+- [ ] **Threat Model Doc**: A lightweight document defining the trust boundary (Local Machine).
+- [ ] **Supply Chain**: Verification steps for upstream dependencies.
+- [ ] **Identity & Access (Phase 40)**:
+    - [ ] **SSH Certs**: Short-lived SSH Certificates.
+    - [ ] **YubiKey Bio**: Biometric enforcement for `sudo`.
+    - [ ] **PAM Modules**: Custom auth modules.
+    - [ ] **Auditd Rules**: Pre-configured audit rules.
+
+## 🧪 Pillar 7: Self-Test & Validation
+**Goal:** "Self-Validating Environment".
+> *The environment can validate itself after installation or update.*
+
+- [ ] **Smoke Tests**: Automated verification of key aliases (`ls`, `git`, `docker`).
+- [ ] **CI Validation**: GitHub Actions workflow to boot and verify the shell syntax.
+- [ ] **Chaos Engineering (Phase 41)**:
+    - [ ] **Config Chaos**: Randomly corrupt config files to test recovery.
+    - [ ] **Network Simulation**: Simulate high latency/packet loss.
+    - [ ] **Permission Fuzzing**: Verify strict umask behavior.
+
+## 📦 Pillar 8: Distribution Guarantees & Platform Support
+**Goal:** "Supported Platforms Matrix".
+> *Only listed platforms are guaranteed to work; others are best-effort.*
+
+- [ ] **Support Matrix**: Explicit table of OS/Version support (macOS 14+, Ubuntu 24.04+, WSL2).
+- [ ] **Windows Deep Integration (Phase 53)**:
+    - [ ] **PowerShell Profile**: Mirror Zsh functionality.
+    - [ ] **WinGet**: Declarative package management.
+    - [ ] **WSL Bridge**: Seamless interop.
+- [ ] **Linux Deep Integration (Phase 55)**:
+    - [ ] **Systemd User Units**: User service management.
+    - [ ] **Desktop Envs**: GNOME/KDE/Sway configs.
+
+---
+
+## 🔮 Future Horizons (Legacy Roadmap)
+
+### Domain-Specific Environments
+- [ ] **Data Science (Phase 38)**: Conda/Mamba, GPU Config, Jupyter.
+- [ ] **Network Topologies (Phase 56)**: Mesh Networks, Tor, Private VPNs.
+- [ ] **Build Systems (Phase 57)**: Bazel, Maven/Gradle, CMake.
+- [ ] **Financial Operations (Phase 63)**: Cost CLI, Ledger, Stock Tickers.
+- [ ] **Game Development (Phase 64)**: Unity/Unreal CLI, Godot, Blender.
+- [ ] **Scientific Computing (Phase 68)**: Latex, R/Julia, Pandoc.
+- [ ] **Quantum Computing (Phase 69)**: Qiskit, Simulators.
+- [ ] **Bio-Informatics (Phase 70)**: Genomics, PDB, FASTA.
+
+### Enterprise & Operations
+- [ ] **Collaborations (Phase 45)**: Pair Programming, Team Sync, ChatOps.
+- [ ] **Database DevOps (Phase 46)**: DB Clients, Local Docker DBs, Migrations.
+- [ ] **Serverless (Phase 47)**: Lambda, Edge Workers, Wasm.
+- [ ] **Enterprise Fleet (Phase 30)**: MDM Profiles, Policy as Code.
+- [ ] **Legal & Procurement (Phase 93)**: RFP Templates, Vendor Management.
+- [ ] **Recruiting & HR (Phase 94)**: Resume Generators, coding interview sets.
+
+### Accessibility & Legacy
+- [ ] **Accessibility (Phase 36)**: Screen Reader optimization, High Contrast.
+- [ ] **Legacy Modernization (Phase 42)**: Mainframe/Unix support, PowerShell Core.
+
+---
+
+## 📜 Completed Milestones
+
+### Core Foundations
+- [x] **Universal Config (Chezmoi) (Phase 1)**
+- [x] **Shell Environment (Phase 2)**
+- [x] **Tool Modernization (Phase 3)**
+- [x] **Performance Optimization (Phase 4)**
+
+### Hardened Security
+- [x] **Security & Validation (Phase 5)**
+- [x] **Package Management (Phase 6)**
+- [x] **Hardened Security (Phase 21)**
+- [x] **Enterprise Core (Phase 23)**: SLSA, SBOM, Signed Releases.
+- [x] **Legal & Licensing (Phase 92)**: FOSSology, Headers, CLA.
+
+### Experience
+- [x] **Documentation (Phase 25)**: DocSite, Interactive Tour.
+- [x] **Self-Healing (Phase 27)**: Doctor, Auto-Repair.
+- [x] **OS Bundling (Phase 26)**: XDG Compliance, Vendor Hooks.
+- [x] **Predictive Shell (Phase 32)**: Autosuggest, Local LLM.
+- [x] **Visual Layer (Phase 34)**: Yazi, Zellij, Ghostty.