@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/README.md

@@ -0,0 +1,322 @@
+<p align="center">
+  <img src="https://cloudcdn.pro/dotfiles/v2/images/logos/dotfiles.svg" alt="Dotfiles logo" width="128" />
+</p>
+
+<h1 align="center">.dotfiles</h1>
+
+<p align="center">
+  <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.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://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)"
+```
+
+Then verify and explore:
+
+```bash
+dot doctor        # verify installation
+dot learn         # interactive tour
+```
+
+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>
+
+Silent install (no prompts):
+
+```bash
+DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
+  bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+```
+
+Docker sandbox:
+
+```bash
+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>
+
+---
+
+## Why this repo is different
+
+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 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
+
+The CLI is idempotent. Run it once or a hundred times. Same machine state.
+
+```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 / PowerShell]
+    H --> M[Mise / Nix Toolchains]
+    H --> N[MCP Policy / Agent Profiles]
+    L --> O[~/.cache/shell Fast Init]
+
+    G --> P[Signed Attestation Logs]
+```
+
+---
+
+## Wallpaper-Driven Themes
+
+Drop a wallpaper. Get a theme.
+
+`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 |
+|:---|:---|:---|
+| **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
+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
+```
+
+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)
+
+---
+
+## The `dot` CLI
+
+Over 80 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 |
+| `dot commit` | Generate an AI commit message from the staged diff |
+
+### Inspect & Repair
+
+| | |
+|:---|:---|
+| `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 (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 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, and namespace |
+| `dot benchmark` / `dot perf` | Measure shell startup |
+| `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`
+
+---
+
+## Documentation
+
+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 copy** — `dot manual --offline` (uses the bundled snapshot, no network)
+- **Sources** — [`docs/manual/`](docs/manual/)
+
+---
+
+## First 5 Minutes
+
+1. **Check** — `dot doctor` validates tools, paths, and security
+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 and `dot prewarm` caches shell startup
+
+See the [Migration Guide](docs/operations/MIGRATION.md) for version upgrades.
+
+---
+
+## What's Included
+
+<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
+- **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>
+<summary><b>Development and Runtimes</b></summary>
+
+- **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) 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 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 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)** 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 the [Security docs](docs/security/SECURITY.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 | ✓ | — | — | — |
+| Schema-validated config | ✓ | — | — | — |
+
+`chezmoi` is the underlying templating engine. This repo is the opinionated reference implementation.
+
+---
+
+**THE ARCHITECT** ᛫ [Sebastien Rousseau](https://sebastienrousseau.com)
+**THE ENGINE** ᛞ [EUXIS](https://euxis.co) ᛫ Enterprise Unified Execution Intelligence System
+
+---
+
+## License
+
+Licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
+
+<p align="right"><a href="#dotfiles">Back to Top</a></p>

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

@@ -0,0 +1,73 @@
+---
+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.
+
+## 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

package/docs/AI.md

@@ -0,0 +1,108 @@
+---
+render_with_liquid: false
+---
+
+# AI Integrations (Opt-in)
+
+AI helpers are **off by default**. You choose if and when to turn them on.
+
+## Enable AI helpers
+
+```bash
+export DOTFILES_AI=1
+exec zsh
+```
+
+This turns on the local helper scripts for context suggestions and error analysis. It does not install any AI tools.
+
+## Steering Patterns
+
+Patterns in `~/.dotfiles/dot_config/ai/patterns/` add focused context to AI requests.
+
+- **Architect** — shell setup and stack tuning
+- **Hardener** — security, encryption, and compliance
+- **Refactor** — POSIX compatibility, performance, and linting
+
+### Contextual Bridge
+
+Use the `dot` CLI to run AI tools with added context:
+
+```bash
+# General usage
+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
+dgmnh "Audit my ssh config"   # Gemini + Hardener
+dkir "Refactor this script"   # Kiro + Refactorer
+```
+
+The bridge adds system details (OS, architecture, date) to the prompt. This gives the AI the context it needs for accurate answers.
+
+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 |
+| `dot opencode` | OpenCode |
+| `dot aider` | Aider |
+| `dot autohand` | Autohand Code |
+| `dot vibe` | Mistral Vibe |
+| `dot qwen` | Qwen Code |
+| `dot zai` | ZAI (Zhipu AI) |
+
+### `dot ai` status and launcher
+
+`dot ai` shows which AI CLIs are installed, grouped by category. If `gum` is available, it also opens a quick launcher.
+
+Current categories:
+
+- Agents (autonomous)
+- Coding (interactive)
+- General (prompt-based)
+- Runtime (local)
+- Cloud (platform)
+
+The launcher is simple and fast. It shows short role labels like `agent`, `coding`, `general`, `local`, and `cloud` so you can pick quickly.
+
+To stay fast, `dot ai` caches provider info in `~/.cache/dotfiles/ai/status.tsv` for 5 minutes. You can change this with `DOTFILES_AI_STATUS_TTL`.
+
+Related AI commands:
+
+- `dot ai` — check status and launch tools
+- `dot ai-setup` — set up AI CLIs step by step
+- `dot ai-query` — run context-aware queries on the dotfiles repo
+
+## Optional AI CLI tools
+
+These tools are not installed for you. Pick and install only the ones you want:
+
+- **Agents**: `claude`, `codex`, `copilot`, `goose`
+- **Coding assistants**: `aider`, `opencode`
+- **General AI**: `gemini`, `sgpt`
+- **Local-first**: `ollama`
+- **Coding agents**: `autohand`, `vibe`, `qwen`, `zai`
+- **Cloud / platform**: `kiro-cli`
+
+Once installed, the dotfiles add helper functions and shortcuts. These only load when `DOTFILES_AI=1` is set.
+
+## Agentic terminal workflows
+
+If your terminal has built-in AI agents, keep your shell lean and fast:
+
+- Use `DOTFILES_FAST=1` or `DOTFILES_ULTRA_FAST=1`.
+- Let the terminal handle agents and its own UI.
+- Keep dotfiles focused on consistency, safety, and clean repeats.
+
+## Privacy and safety
+
+- No AI tools are installed for you.
+- No background services run by default.
+- You control AI helpers with `DOTFILES_AI=1`.

package/docs/CNAME

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

package/docs/COPYRIGHT

@@ -1,6 +1,7 @@
 /*
-* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.471) - <https://dotfiles.io>
-* Made with ♥ in London, UK by Sebastien Rousseau
-* Copyright (c) 2015-2024. All rights reserved
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.501) - <https://github.com/sebastienrousseau/dotfiles>
+* Made With ❤️ in London, United Kingdom
+* Designed by
+* Copyright (c) 2015-2026. All rights reserved.
 * License: MIT
 */

package/docs/NAMING_CONVENTIONS.md

@@ -0,0 +1,102 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
+# Naming Conventions & Standardization Guide
+
+This document defines the naming conventions for all files in the dotfiles repository.
+
+---
+
+## File Naming
+
+| Context | Convention | Example |
+|---|---|---|
+| Run scripts | `run_{type}_{NN}-{verb}-{noun}.sh.tmpl` | `run_onchange_10-install-packages.sh.tmpl` |
+| Shell fragments | `{NN}-{domain}-{detail}.sh.tmpl` | `90-ux-aliases.sh.tmpl` |
+| Alias files | `{tool}.aliases.sh` | `git.aliases.sh` |
+| Function files | `{name}.sh` (lowercase) | `apihealth.sh` |
+| Test files | `test_{domain}_{feature}.sh` | `test_aliases_git.sh` |
+| Scripts | `{verb}-{noun}.sh` (hyphenated) | `install-nerd-fonts.sh` |
+
+## Run Script Numbering Tiers
+
+| Range | Category | Examples |
+|---|---|---|
+| 00-09 | Audit & pre-flight | `run_before_00-audit.sh` |
+| 10-19 | Package installation | `run_onchange_10-linux-packages.sh.tmpl` |
+| 20-29 | Config & languages | `run_onchange_20-ghostty-config.sh.tmpl` |
+| 25-29 | Language toolchains | `run_onchange_25-python-tools.sh.tmpl` |
+| 30-39 | Applications | `run_onchange_30-vscode-extensions.sh.tmpl` |
+| 40-49 | System defaults | `run_onchange_40-darwin-default-apps.sh.tmpl` |
+| 50-59 | Assets (fonts, themes) | `run_onchange_50-install-fonts.sh.tmpl` |
+
+---
+
+## Adding New Modules
+
+### New app config
+
+1. Create `dot_config/<app>/` with chezmoi-compatible filenames
+2. Add entry to `dot_config/.module-manifest.json`
+3. Optionally gate with feature flag in `.chezmoidata.toml` + `.chezmoiignore.tmpl`
+
+### New alias category
+
+1. Create `.chezmoitemplates/aliases/<category>/<name>.aliases.sh`
+2. The `**/*.aliases.sh` glob auto-discovers it
+3. Add to `$coreCategories` list in `90-ux-aliases.sh.tmpl` for eager loading; otherwise it loads lazily
+
+### New function
+
+1. Create file in `.chezmoitemplates/functions/<group>/`
+2. Add to `groups.json` with the `<group>/<filename>` path
+3. It auto-registers for lazy loading via `51-logic-functions-extra.sh.tmpl`
+
+### New provisioning script
+
+1. Create `install/provision/run_onchange_{NN}-{name}.sh.tmpl`
+2. Use the numbering tiers above
+3. Source `install/lib/os_detection.sh` for platform detection
+4. Guard OS-specific code with `{{ if eq .chezmoi.os "darwin" }}`
+
+---
+
+## Directory Structure Overview
+
+```text
+.chezmoitemplates/
+  aliases/        # 48 categories, auto-discovered
+  functions/      # Grouped by domain (api/, curl/, text/, system/, etc.)
+  paths/          # PATH construction templates
+  desktop/        # Desktop environment templates (dconf)
+
+dot_config/       # Flat — chezmoi constraint, no intermediate grouping
+
+install/
+  lib/            # Shared helpers (os_detection, logging, installers)
+  provision/      # run_onchange_* provisioning scripts
+
+scripts/          # Repo-only scripts (not deployed)
+  dot/            # dot CLI subcommands
+  ops/            # Operations scripts
+  diagnostics/    # Health checks
+  security/       # Security tools
+  ...
+
+tests/            # Test suite (not deployed)
+  framework/      # Test runner, assertions, mocks
+  unit/           # Domain-organized unit tests
+  integration/    # End-to-end tests
+  performance/    # Benchmarks
+
+docs/             # Documentation and GitHub Pages source
+  architecture/   # System design docs
+  guides/         # How-to guides
+  reference/      # Reference material
+  security/       # Security documentation
+  operations/     # Ops and maintenance docs
+```
+
+{% endraw %}