@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/README.md

@@ -1,315 +1,284 @@
-<p align="right">
-  <img src="https://kura.pro/dotfiles/v2/images/logos/dotfiles.svg" alt="Dotfiles logo" width="64" />
+<p align="center">
+  <img src="https://cloudcdn.pro/dotfiles/v2/images/logos/dotfiles.svg" alt="Dotfiles logo" width="128" />
 </p>
 
-# Dotfiles — A Fast, Idempotent Shell Environment
+<h1 align="center">.dotfiles</h1>
 
-[![Build](https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/actions)
-[![Version](https://img.shields.io/badge/Version-v0.2.481-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.481)
-[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
-[![Release Downloads](https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases)
-[![Last Commit](https://img.shields.io/github/last-commit/sebastienrousseau/dotfiles?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/commits)
-
----
-
-## Overview
-
-Set up your development environment in minutes and keep it consistent across every machine. Dotfiles is a cross‑platform shell distribution managed by [Chezmoi](https://github.com/twpayne/chezmoi) that works on macOS, Linux, and WSL. It is **idempotent** by design: run it once or a hundred times, and the result is always the same.
-
-Git + templates + guarded scripts = a reproducible shell.
-
----
+<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>
+</p>
 
-## Table of contents
-
-- [Why dotfiles](#why-dotfiles)
-- [Safety](#safety)
-- [Get started](#get-started)
-- [Discover](#discover)
-- [Install details](#install-details)
-- [Make it yours](#make-it-yours)
-- [Reference](#reference)
-- [How it works](#how-it-works)
-- [Roadmap](#roadmap)
-- [Contribute](#contribute)
-- [Changelog](#changelog)
-- [License](#license)
+<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"><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>
+</p>
 
 ---
 
-## Why dotfiles
-
-Dotfiles takes an infrastructure‑oriented approach to managing your shell. It is designed for developers who work across multiple machines and value **daily usability, reproducibility, and auditability.**
-
-- **The Stack.** Zsh, Neovim, tmux, and AI CLI tools configured with sane defaults so you can start working immediately.
-- **Unified Control.** The `dot` CLI wraps common workflows such as syncing, upgrading, and managing secrets.
-- **Safety First.** Every system or security change requires explicit opt‑in.
-- **Clean Slate.** Source files, generated configs, and system state stay cleanly separated.
-
+## Install
 
-## Safety
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
 
-This is **infrastructure**, not an ad‑hoc shell script.
+Then verify and explore:
 
-- No destructive actions without explicit opt‑in.
-- No background daemons install automatically.
-- No system settings change by default.
-- System‑level behavior requires explicit opt‑in through environment variables.
-- Dotfiles logs all privileged actions to `~/.local/share/dotfiles.log`.
+```bash
+dot doctor        # verify installation
+dot learn         # interactive tour
+```
 
----
+Requires `git` and `curl`. Works on macOS, Ubuntu/Debian, Arch, WSL2, and GitHub Codespaces.
 
-## Get started
+<details>
+<summary>CI/CD and Docker options</summary>
 
-> [!IMPORTANT]
-> The installer automatically backs up any existing dotfiles that chezmoi will overwrite (to `~/.dotfiles.bak.<timestamp>/`). It bootstraps `chezmoi` and applies this repo. OS packages install through Chezmoi hooks during the first apply.
+Silent install (no prompts):
 
 ```bash
-# Works on macOS, Linux, and WSL
-sh -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.481/install.sh)"
-exec zsh
+DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
+  bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
 ```
 
-For non‑interactive installs (servers and CI):
+Docker sandbox:
+
 ```bash
-DOTFILES_NONINTERACTIVE=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.481/install.sh)"
+docker run --rm -e DOTFILES_NONINTERACTIVE=1 ubuntu:24.04 bash -c \
+  'apt-get update -qq && apt-get install -y -qq git curl sudo >/dev/null 2>&1 \
+  && git clone --depth 1 https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles \
+  && bash ~/.dotfiles/install.sh \
+  && export PATH="$HOME/.local/bin:$PATH" \
+  && dot doctor'
 ```
 
+</details>
+
 ---
 
-## Discover
+## 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.
 
-- [Installation Guide](docs/INSTALL.md) — Prerequisites and supported platforms.
-- [Operations Guide](docs/OPERATIONS.md) — Common workflows and platform notes.
-- [Security Guide](docs/SECURITY.md) — Hardening matrix and logging.
-- [Secrets Guide](docs/SECRETS.md) — Age setup and encrypted files.
-- [Tools Catalog](docs/TOOLS.md) — Core tools and optional utilities.
-- [Dot Utils](docs/UTILS.md) — Aliases and dot CLI helpers.
-- [Troubleshooting](docs/TROUBLESHOOTING.md) — Fixes for common issues.
+| 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` |
 
 ---
 
-## Install details
+## Architecture
 
-**Prerequisites**
-- Required: `git`, `curl`
-- Optional: Homebrew (macOS), `apt-get` (Linux/WSL), Nix (toolchain)
+Idempotent. Run it once or a hundred times. Same machine state.
 
-**Update**
-```bash
-dot update
+```mermaid
+graph TD
+    A[User Shell] --> B{dot CLI}
+    B --> C[Lifecycle: sync / apply / rollback / heal]
+    B --> D[Diagnostics: doctor / drift / benchmark / score]
+    B --> E[AI & Agents: ai / mcp / agent / mode]
+    B --> F[Themes: theme / theme rebuild]
+    B --> G[Fleet & Attest: fleet / attest / bundle]
+
+    C --> H[Chezmoi Source]
+    F --> I[Wallpaper Discovery<br/>System + Custom]
+    I --> J[K-Means CIELAB Engine]
+    J --> K[themes.toml<br/>WCAG AAA enforced]
+    K --> H
+
+    H --> L[Zsh / Fish / Bash / Nushell]
+    H --> M[Mise / Nix Toolchains]
+    H --> N[MCP Policy / Agent Profiles]
+    L --> O[~/.cache/shell Fast Init]
+
+    G --> P[Signed Attestation Logs]
 ```
 
-**Non‑interactive apply**
-```bash
-DOTFILES_NONINTERACTIVE=1 dot apply
-```
+---
 
-## Make it yours
+## Wallpaper-Driven Themes
 
-- [Operations](docs/OPERATIONS.md)
-- [Secrets](docs/SECRETS.md)
-- [Security](docs/SECURITY.md)
-- [Troubleshooting](docs/TROUBLESHOOTING.md)
+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.
 
-## Reference
-
-Run `dot --help` or `dot <command> --help` for inline documentation.
-
-| Command | Description | Category |
-|---|---|---|
-| `dot apply` | Apply dotfiles (chezmoi apply) | Core |
-| `dot sync` | Alias of apply | Core |
-| `dot update` | Pull latest changes and apply | Core |
-| `dot add` | Add a file to chezmoi source | Core |
-| `dot diff` | Show chezmoi diff (excludes scripts) | Core |
-| `dot status` | Show configuration drift | Core |
-| `dot remove` | Safely remove a managed file | Core |
-| `dot cd` | Print source directory path | Core |
-| `dot upgrade` | Update flake, plugins, and dotfiles | Core |
-| `dot edit` | Open chezmoi source in your editor | Core |
-| `dot docs` | Show repo README | Core |
-| `dot --version` | Show version information | Core |
-| `dot help` | Show help | Core |
-| `dot drift` | Drift dashboard (chezmoi status) | Diagnostics |
-| `dot history` | Shell history analysis | Diagnostics |
-| `dot doctor` | Check system health and configuration | Diagnostics |
-| `dot health` | Comprehensive health dashboard (37 checks) | Diagnostics |
-| `dot security-score` | Security assessment with grading | Diagnostics |
-| `dot benchmark` | Shell startup benchmark (`--detailed`, `--profile`) | Diagnostics |
-| `dot restore` | Restore from backup or git ref | Diagnostics |
-| `dot theme` | Switch terminal theme (dark/light) | UX |
-| `dot wallpaper` | Apply a wallpaper from your library | UX |
-| `dot keys` | Show keybindings catalog | UX |
-| `dot learn` | Interactive tour of tools (requires `gum`) | UX |
-| `dot fonts` | Install Nerd Fonts | UX |
-| `dot sandbox` | Launch a safe sandbox preview | Tools |
-| `dot tools` | Show tools or install through Nix | Tools |
-| `dot tools install` | Enter Nix development shell | Tools |
-| `dot new` | Create a new project from a template | Tools |
-| `dot log-rotate` | Rotate `~/.local/share/dotfiles.log` | Tools |
-| `dot secrets-init` | Initialise age key for secrets | Secrets |
-| `dot secrets` | Edit encrypted secrets | Secrets |
-| `dot secrets-create` | Create an encrypted secrets file | Secrets |
-| `dot ssh-key` | Encrypt an SSH key locally with age | Secrets |
-| `dot backup` | Create a compressed backup of your home directory | Security |
-| `dot firewall` | Apply firewall hardening (opt‑in) | Security |
-| `dot telemetry` | Disable OS telemetry (opt‑in) | Security |
-| `dot dns-doh` | Enable DNS‑over‑HTTPS (opt‑in) | Security |
-| `dot encrypt-check` | Check disk encryption status | Security |
-| `dot lock-screen` | Enforce lock‑screen idle settings (opt‑in) | Security |
-| `dot usb-safety` | Disable automount for removable media | Security |
-
-### Developer CLI Tools
-
-These utilities are installed to `~/.local/bin/`:
-
-| Tool | Description |
-|------|-------------|
-| `jsonv` | JSON validator and formatter |
-| `yamlv` | YAML validator |
-| `epoch` | Unix timestamp converter |
-| `b64` | Base64 encoder/decoder |
-| `jwt` | JWT token decoder |
-| `hex` | Hex viewer/converter |
-| `regex` | Regex tester |
-| `lorem` | Lorem ipsum generator |
-| `uuid` | UUID generator |
-| `hash` | MD5/SHA hash calculator |
-| `ip` | Show public/local IP addresses |
-| `kill-port` | Kill process by port |
-| `extract` | Universal archive extraction |
-| `update` | Update all system packages |
-
-**Examples**
+| Tier | Source | Format |
+|:---|:---|:---|
+| **System** | macOS `/System/Library/Desktop Pictures/`<br/>Linux `/usr/share/backgrounds/` | `.heic`, `.jpg`, `.png` |
+| **Custom** | `~/Pictures/Wallpapers/` (overrides system on name collision) | Apple-compatible dynamic HEIC (single file, both appearances) |
 
 ```bash
-# Initialise secrets (prints a public key)
-DOTFILES_NONINTERACTIVE=1 dot secrets-init
-# Output: Age key created at ~/.config/chezmoi/key.txt
+dot theme              # interactive picker (paired themes only)
+dot theme tahoe-dark   # switch directly
+dot theme toggle       # swap dark↔light within current family
+dot theme rebuild      # regenerate from current wallpapers
 ```
 
-### Security changes
-
-These scripts are **opt‑in** and run only when you set the matching environment variable.
-All security changes are logged to `~/.local/share/dotfiles.log`.
-
-| Script | macOS | Linux |
-|---|---|---|
-| `dot firewall` | Enables macOS firewall and stealth mode via `socketfilterfw` | Configures UFW defaults and OpenSSH allow |
-| `dot telemetry` | Writes `DiagnosticMessagesHistory.plist` flags | Disables `whoopsie`, `apport`, `popularity-contest` |
-| `dot dns-doh` | No system change (browser‑level only) | Enables DoH via `resolvectl` with Cloudflare DNS |
-| `dot lock-screen` | `com.apple.screensaver` defaults and idleTime | GNOME `gsettings` lock and idle timeout |
-| `dot usb-safety` | No system change (manual UI) | GNOME `gsettings` automount off |
-| `dot encrypt-check` | Reads FileVault status via `fdesetup` | Detects LUKS via `lsblk` |
-
-### Nix
+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`.
 
-Nix is **optional**. The repo does **not** install the Nix daemon.
-
-- Use `nix develop` to enter a reproducible shell environment.
-- Use `dot tools` to see the curated utilities overview.
-- No toggle replaces Homebrew or Apt with Nix automatically.
+Full guide: [docs/guides/THEMING.md](docs/guides/THEMING.md)
 
 ---
 
-### Install guide
+## The `dot` CLI
+
+30+ commands grouped by intent. Run `dot help` for the full reference.
+
+### Start Here
+| | |
+|:---|:---|
+| `dot sync` | Apply dotfiles to this machine |
+| `dot doctor` | Check the environment and surface issues |
+| `dot learn` | Open the guided tour |
+
+### Daily Use
+| | |
+|:---|:---|
+| `dot status` / `dot diff` | Show local drift / preview pending changes |
+| `dot edit` | Open the source directory |
+| `dot upgrade` | Update tools and dotfiles |
+
+### Inspect & Repair
+| | |
+|:---|:---|
+| `dot heal` | Auto-fix tools, chezmoi drift, broken symlinks |
+| `dot rollback` | Return to a previous known-good state |
+| `dot attest` | Export workstation evidence |
+| `dot chaos` | Simulate corruption to test self-healing |
+
+### AI & Agents
+| | |
+|:---|:---|
+| `dot ai` | Show installed AI tools |
+| `dot mcp` | Inspect MCP policy and registry |
+| `dot mode` | Show or set the agent profile |
+| `dot agent` | Agent metadata, logs, checkpoints, conformance |
+
+### Configuration
+| | |
+|:---|:---|
+| `dot theme` / `dot theme rebuild` | Switch theme / regenerate from wallpapers |
+| `dot env` | Show managed tool versions |
+| `dot profile` | Show or switch active profile |
+| `dot secrets` | Edit encrypted secrets |
+
+### Fleet & Performance
+| | |
+|:---|:---|
+| `dot fleet` | Multi-node status, drift, namespace |
+| `dot benchmark` / `dot perf` | Measure shell startup |
+| `dot score` | Health and security scorecard |
+
+Full reference: [docs/reference/UTILS.md](docs/reference/UTILS.md) · Complete manual: [docs/manual/](docs/manual/) or `dot manual`
 
-See [docs/INSTALL.md](docs/INSTALL.md) for prerequisites, supported platforms, and the full install flow.
+---
 
-<p align="right"><a href="#dotfiles--your-shell-everywhere">↑ Back to Top</a></p>
+## Documentation
 
-## How it works
+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.
 
-If Mermaid does not render, the flow is: `install.sh` → `Chezmoi` → `~/.dotfiles` → `~/.config + ~/.local`.
+- **Online** — <https://sebastienrousseau.github.io/dotfiles/manual/>
+- **Terminal** — `dot manual text | less`
+- **PDF** — `dot manual pdf`
+- **Offline bundle** — `dot bundle --manual`
+- **Sources** — [`docs/manual/`](docs/manual/)
 
-```mermaid
-flowchart LR
-  A["install.sh"] --> B["Chezmoi"]
-  B --> C["~/.dotfiles (source)"]
-  B --> D["~/.config + ~/.local (targets)"]
-  E["dot CLI"] --> B
-  E --> F["scripts/*"]
-```
+---
 
-### Shell startup flow
+## First 5 Minutes
 
-```
-.zshenv ─▶ .zshrc ─▶ rc.d/{10..50} ─▶ shell/{00,05,40,50,90} ─▶ [precmd: 91-lazy] ─▶ tool init
-   │          │            │                    │                        │                   │
-   │          │            │                    │                        │                   ├─ atuin
-  XDG      zinit      options,            paths, safety,          tool-specific          ├─ starship
-  PATH     plugins    lazy fnm/nvm        functions,              aliases (deferred)     ├─ zoxide
-                                          core aliases (eager)                           └─ fzf
-```
+1. **Check** — `dot doctor` validates tools, paths, and security
+2. **Explore** — `dot learn` walks through shells, secrets, themes, 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
 
-Core aliases (~40KB) load at startup. Tool-specific aliases (~137KB) load after the first prompt via a `precmd` hook — keeping shell startup fast while still providing full alias coverage. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full startup sequence and ordering conventions.
-
-**Repository Layout**
-
-```text
-~/.dotfiles/
-├── dot_config/                 # Maps to ~/.config/ (app configs)
-│   ├── nvim/                    # Neovim config (Lua)
-│   ├── zsh/                     # Zsh config (modular)
-│   ├── tmux/                    # Tmux config
-│   ├── shell/                   # Shell logic (aliases, functions, paths)
-│   ├── wezterm/ alacritty/ kitty/ ghostty/
-│   ├── btop/ fastfetch/ atuin/ yazi/ ...
-│   └── docker/ containers/ ...
-├── dot_local/                  # Maps to ~/.local/ (CLI tools)
-│   └── bin/                     # dot CLI and helpers
-├── dot_etc/                    # System configs (sudoers, sysctl, Chrome policies; may require sudo)
-├── dot_ssh/                    # SSH config templates
-├── templates/                  # Project scaffolds used by `dot new`
-├── scripts/                    # Install, security, theme, diagnostics
-├── install/                    # Chezmoi run_onchange and run_before hooks
-├── nix/                        # Optional Nix shell environment
-├── docs/                       # Guides, keys, roadmap, architecture
-└── install.sh                  # Bootstrap installer
-```
+See the [Migration Guide](docs/operations/MIGRATION.md) for version upgrades.
 
 ---
 
-## Roadmap
+## What's Included
 
-Track progress on [GitHub Issues](https://github.com/sebastienrousseau/dotfiles/issues) and [Milestones](https://github.com/sebastienrousseau/dotfiles/milestones).
+<details>
+<summary><b>Shells and Navigation</b></summary>
 
----
+- **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
+- **Starship**, **Zoxide**, **Atuin**, and **fzf** for navigation and command recall
+</details>
 
-## Contribute
+<details>
+<summary><b>Development and Runtimes</b></summary>
 
-Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) before opening a pull request.
+- **Mise** manages language versions in user space (no system pollution)
+- **Nix Flakes** for strict reproducible builds when speed isn't the priority
+- **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
+</details>
 
-For security issues, see [SECURITY.md](.github/SECURITY.md).
+<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
+</details>
 
-## Troubleshooting
+<details>
+<summary><b>Security, Trust, and Governance</b></summary>
 
-See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
+- **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
+- **Telemetry controls** and local-first defaults — you own your data
+- **SBOM (CycloneDX)** + Grype CVE scanning in CI
+</details>
 
----
+For security hardening options, see [Security docs](docs/security/SECURITY.md).
 
-## Changelog
+---
 
-See [CHANGELOG.md](CHANGELOG.md).
+## Comparison
 
----
+| | This repo | chezmoi | holman/dotfiles | nikitabobko/dotfiles |
+|:---|:---:|:---:|:---:|:---:|
+| Cross-platform (macOS/Linux/WSL) | ✓ | ✓ | macOS-leaning | macOS only |
+| Multi-shell parity (zsh/fish/nu/pwsh) | ✓ | — | bash only | zsh only |
+| Wallpaper-driven themes (K-Means) | ✓ | — | — | — |
+| AI / MCP integration | ✓ | — | — | — |
+| Cryptographic attestation | ✓ | — | — | — |
+| Self-healing CLI | ✓ | — | — | — |
+| Fleet management | ✓ | — | — | — |
+| Encrypted secrets (Age/SOPS) | ✓ | ✓ | — | — |
+| Build artifact redirection | ✓ | — | — | — |
 
-## License
+`chezmoi` is the underlying templating engine. This repo is the opinionated reference implementation.
 
-This project is licensed under the **MIT License**. See [LICENSE](LICENSE).
+---
 
-Some bundled third‑party dependencies are licensed under GPL‑3.0; the LICENSE file lists them explicitly.
+**THE ARCHITECT** ᛫ [Sebastien Rousseau](https://sebastienrousseau.com)
+**THE ENGINE** ᛞ [EUXIS](https://euxis.co) ᛫ Enterprise Unified Execution Intelligence System
 
 ---
 
-<div align="center">
+## License
 
-🎨 Designed by **[Sebastien Rousseau](https://sebastienrousseau.com/)**
-🚀 Engineered with **[Euxis](https://euxis.co/)** — Enterprise Unified eXecution Intelligence System
+Licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
 
-</div>
+<p align="right"><a href="#dotfiles">Back to Top</a></p>

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

@@ -0,0 +1,69 @@
+# 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.
+
+## Readability Scorecard
+
+| Language | Reading Ease | Grade Level | Passive % | Avg Sentence Length |
+| :--- | ---: | ---: | ---: | ---: |
+| ar | n/a | n/a | n/a | n/a |
+| de | n/a | n/a | n/a | n/a |
+| es | n/a | n/a | n/a | n/a |
+| fr | n/a | n/a | n/a | n/a |
+| he | n/a | n/a | n/a | n/a |
+| hi | n/a | n/a | n/a | n/a |
+| id | n/a | n/a | n/a | n/a |
+| it | n/a | n/a | n/a | n/a |
+| ja | n/a | n/a | n/a | n/a |
+| ko | n/a | n/a | n/a | n/a |
+| nl | n/a | n/a | n/a | n/a |
+| pl | n/a | n/a | n/a | n/a |
+| pt | n/a | n/a | n/a | n/a |
+| ro | n/a | n/a | n/a | n/a |
+| ru | n/a | n/a | n/a | n/a |
+| th | n/a | n/a | n/a | n/a |
+| tr | n/a | n/a | n/a | n/a |
+| uk | n/a | n/a | n/a | n/a |
+| vi | n/a | n/a | n/a | n/a |
+| zh | n/a | n/a | n/a | n/a |
+| zh-tw | n/a | n/a | n/a | n/a |
+
+## Parity Gap Table
+
+| Priority | Locale | Route | Deviation |
+| :--- | :--- | :--- | :--- |
+
+## Active & Simple Diff
+
+### docs/adr/ADR-007-multi-shell-parity.md
+
+- Source: **Nushell spoke:** Hybrid approach: - Aliases: Runtime bash extraction cached to (in ), sourced by - Functions: Chezmoi template-generated wrappers delegating to bash (in ) **Parity tiers:** - **Tier 1 (Full):** Zsh, Bash — all aliases, functions, lazy loading, cached eval - **Tier 2 (Bridged):** Fish — all simple aliases, all functions via wrappers, caching - **Tier 3 (Compatible):** Nushell — simple aliases (no complex bash syntax), all functions via bash delegation - Single source of truth for aliases and functions - Adding a new alias/function automatically propagates to all shells - Nushell users get access to 40+ functions that were previously unavailable - Fish users get mtime-aware caching via - Complex bash aliases (pipes, conditionals) are skipped for Nushell - Function calls in Fish/Nushell incur bash subprocess overhead (~5ms per call) - Cache invalidation requires shell restart or manual cache clear - Nushell's rapid development may break bridge syntax in future versions - Very large alias sets may slow Nushell startup during cache generation.
+- Simplified: **Nushell spoke:** Hybrid approach: - Aliases: Runtime bash extraction cached to (in ), sourced by - Functions: Chezmoi template-generated wrappers delegating to bash (in ) **Parity tiers:** - **Tier 1 (Full):** Zsh, Bash — all aliases, functions, lazy loading, cached eval - **Tier 2 (Bridged):** Fish — all simple aliases, all functions via wrappers, caching - **Tier 3 (Compatible):** Nushell — simple aliases (no complex bash syntax), all functions via bash delegation - Single source of truth for aliases and functions -. Adding a new alias/function automatically propagates to all shells - Nushell users get access to 40+ functions that were previously unavailable - Fish users get mtime-aware caching via - Complex bash aliases (pipes, conditionals) are skipped for Nushell - Function calls in Fish/Nushell incur bash subprocess overhead (~5ms per call) - Cache invalidation requires shell restart or manual cache clear - Nushell's rapid development may break bridge syntax in future versions - Very large alias sets may slow Nushell startup during cache generation
+
+### docs/guides/TROUBLESHOOTING.md
+
+- Source: ) **Problem:** LSP not working - Install required language servers - Check for status - Review for errors **Problem:** Git aliases not working - Check if Git config is applied: - Re-apply dotfiles: **Problem:** Delta (diff pager) not showing colors - Verify is installed - Confirm your terminal supports 256 colors **Problem:** kubectl context issues - List contexts: - Switch context: - Check kubeconfig: **Problem:** Minikube won't start - Verify Docker is running - Try: - Check logs: **Problem:** High memory usage - Look for runaway processes: or - Review shell history size in atuin config - Disable unused plugins **Problem:** Nix isn't installed or commands not found - Ensure you have followed the installation guide: - On Linux, you might need to enable experimental features in : - Verify the daemon is running: **Problem:** Systemd isn't available (mostly WSL2) - Dotfiles functions that rely on systemd (like management) will fallback to direct execution.
+- Simplified: ) **Problem:** LSP not working - Install required language servers - Check for status - Review for errors **Problem:** Git aliases not working - Check if Git config is applied: - Re-apply dotfiles: **Problem:** Delta (diff pager) not showing colors - Verify is installed - Confirm your terminal supports 256 colors **Problem:** kubectl context issues - List contexts: - Switch context: - Check kubeconfig: **Problem:** Minikube won't start - Verify Docker is running - Try: - Check. logs: **Problem:** High memory usage - Look for runaway processes: or - Review shell history size in atuin config - Disable unused plugins **Problem:** Nix isn't installed or commands not found - Ensure you have followed the installation guide: - On Linux, you might need to enable experimental features in : - Verify the daemon is running: **Problem:** Systemd isn't available (mostly WSL2) - Dotfiles functions that rely on systemd (like management) will fallback to direct execution
+
+### docs/operations/VERSION_SYNC.md
+
+- Source: sh --verify || echo "Version drift detected" The GitHub Actions workflow provides metrics: - Files scanned - Files updated - Verification status - Processing time - Local backups in - GitHub Actions artifacts (30-day retention) - Git history for rollback permissions: contents: write # Required for commits pull-requests: write # Required for PR comments - Version format validation ( pattern) - File path validation (no directory traversal) - Change verification before commit - All changes logged in Git history - GitHub Actions run history - Backup preservation - Git operations use shallow fetch when possible - Pattern compilation cached - File discovery optimized with - File processing is sequential but optimized - Git operations batched - Verification runs concurrently with updates - Typical run time: 30-60 seconds - Memory usage: <100MB - Network usage: Minimal (only Git operations) 1.
+- Simplified: sh --verify || echo "Version drift detected" The GitHub Actions workflow provides metrics: - Files scanned - Files updated - Verification status - Processing time - Local backups in - GitHub Actions artifacts (30-day retention) - Git history for rollback permissions: contents: write # Required for commits pull-requests: write # Required for PR comments - Version format validation ( pattern) - File path validation (no directory traversal) - Change. verification before commit - All changes logged in Git history - GitHub Actions run history - Backup preservation - Git operations use shallow fetch when possible - Pattern compilation cached - File discovery optimized with - File processing is sequential but optimized - Git operations batched - Verification runs concurrently with updates - Typical run time: 30-60 seconds - Memory usage: <100MB - Network usage: Minimal (only Git operations) 1
+
+## Localized Terminology Glossary
+
+| Term | Rule |
+| :--- | :--- |
+| macOS | Keep official Apple spelling in all locales. |
+| Linux | Keep as Linux. |
+| WSL | Keep as WSL on first use. |
+| Chezmoi | Keep product name in English. |
+| `dot doctor` | Keep command unchanged in all locales. |
+| shell | Localize only in prose; never inside commands or paths. |
+| alias | Localize in prose when natural; keep code examples unchanged. |
+
+## Priority Action Register
+
+- [P0] Meaning Drifts: 0
+- [P1] Readability Blockers: 0
+- [P2] Stylistic Polishing: 0