@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/README.md

@@ -0,0 +1,284 @@
+<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, with sub-second startup, wallpaper-driven themes, and signed releases.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/sebastienrousseau/dotfiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=github" alt="Build" /></a>
+  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.500-blue?style=for-the-badge" alt="Version" /></a>
+  <a href="https://github.com/sebastienrousseau/dotfiles/releases"><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>
+
+---
+
+## Install
+
+```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
+```
+
+Requires `git` and `curl`. Works 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: signed, attested, multi-platform, AI-aware, and self-healing.
+
+| Capability | What you get | Where |
+|:---|:---|:---|
+| **Wallpaper-Driven Themes** | K-Means clustering in CIELAB extracts terminal palettes from any wallpaper. WCAG AAA enforced. Dynamic HEIC dark/light. | `dot theme rebuild` |
+| **AI & MCP Native** | Agent profiles, MCP policy enforcement, attestation logs, AI commit messages | `dot ai`, `dot mcp`, `dot agent`, `dot mode` |
+| **Cryptographic Attestation** | Signed commits, machine-readable evidence, policy bundle releases | `dot attest`, `dot verify` |
+| **Fleet Management** | Multi-node drift dashboard, per-host profiles | `dot fleet` |
+| **Self-Healing** | Auto-repair tools, chezmoi drift, broken symlinks, missing files | `dot heal`, `dot chaos`, `dot rollback`, `dot bundle` |
+| **Sub-second Startup** | Lazy loading, `_cached_eval` pattern, mtime-based cache invalidation | `dot benchmark`, `dot perf` |
+| **Multi-shell Parity** | Fish, Zsh, Nushell, PowerShell share one templated baseline | `dot env`, `dot profile` |
+| **Build Artifacts → /tmp** | Cargo, Go, pip, uv, Zig caches redirected; project dirs stay clean | `~/.config/mise/config.toml`, `~/.cargo/config.toml` |
+| **Encrypted Secrets** | Age + SOPS for per-machine secrets out of plaintext history | `dot secrets` |
+| **Portable Runtimes** | Mise for managed toolchains, Nix Flakes for strict reproducibility | `dot env`, `dot upgrade` |
+
+---
+
+## Architecture
+
+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]
+    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 (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.
+
+| 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: 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`.
+
+Full guide: [docs/guides/THEMING.md](docs/guides/THEMING.md)
+
+---
+
+## The `dot` CLI
+
+30+ commands grouped by intent. Run `dot help` for the full reference.
+
+### 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`
+
+---
+
+## Documentation
+
+The `.dotfiles` Manual is published in 9 formats: HTML (single + multi-page), PDF, EPUB, ASCII text, compressed variants, Markdown source. Auto-built on every change.
+
+- **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/)
+
+---
+
+## First 5 Minutes
+
+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
+
+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
+- **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>
+
+<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) redirected to `/tmp/builds/` — cleared on reboot
+</details>
+
+<details>
+<summary><b>AI, Agents, and MCP</b></summary>
+
+- **Agent profiles** (`dot mode`) — switch between architect, hardener, refactor patterns
+- **MCP policy enforcement** (`dot mcp`) — validate Model Context Protocol registry against policy
+- **AI commit messages** (`dot commit`) — conventional commits generated from staged diff
+- **AI tools** (`dot ai`) — Claude Code, Codex, GitHub Copilot, Gemini CLI managed via Mise
+- **Attestation logs** — every agent session logged with policy hash + outcome
+</details>
+
+<details>
+<summary><b>Security, Trust, and Governance</b></summary>
+
+- **Age + SOPS** keep secrets encrypted at rest and out of plaintext history
+- **SSH ED25519 signing** + trust metadata back signed commits and verifiable changes
+- **Gitleaks**, policy checks, compliance workflows
+- **Workstation attestation** (`dot attest`) records machine state, policy, prompt, model metadata in tracked JSON
+- **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).
+
+---
+
+## 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 | ✓ | — | — | — |
+
+`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,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

package/docs/AI.md

@@ -0,0 +1,102 @@
+# 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|copilot|gemini|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 copilot` | GitHub Copilot CLI |
+| `dot gemini` | Gemini CLI |
+| `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`, `copilot`
+- **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/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.500) - <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,95 @@
+# 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
+```

package/docs/README.md

@@ -0,0 +1,78 @@
+# Documentation
+
+Start here. Then go deeper.
+
+## The Manual
+
+The complete reference is the `.dotfiles` Manual — a multi-format book covering every concept, tutorial, reference, and recipe.
+
+- Online: <https://sebastienrousseau.github.io/dotfiles/manual/> (HTML, PDF, EPUB, ASCII)
+- Locally: `dot manual` opens the HTML in your browser
+- Sources: [`docs/manual/`](manual/)
+
+Quick jumps into the Manual:
+
+- [Introduction](manual/00-introduction.md) — who, what, how
+- [Concepts](manual/01-concepts/) — architecture, trust model, theme engine, fleet, self-healing
+- [Tutorials](manual/02-tutorials/) — first install, wallpaper→theme, profiles, secrets, fleet
+- [Reference](manual/03-reference/) — CLI, config files, environment, templates, feature flags
+- [Cookbook](manual/04-cookbook/) — 40+ recipes, troubleshooting, FAQ
+
+## Start
+
+- [Install](guides/INSTALL.md)
+- [Troubleshooting](guides/TROUBLESHOOTING.md)
+- [Support matrix](reference/SUPPORT_MATRIX.md)
+
+## Daily use
+
+- [Utilities and `dot` CLI](reference/UTILS.md)
+- [Operations](operations/OPERATIONS.md)
+- [Trusted agent workstation](operations/TRUSTED_AGENT_WORKSTATION.md)
+- [Workstation attestation](operations/ATTESTATION.md)
+- [Interoperability](architecture/INTEROP.md)
+- [Agent interoperability](interop/A2A.md)
+- [AI integrations](AI.md)
+
+## Security and trust
+
+- [Security overview](security/SECURITY.md)
+- [Security checklist](security/SECURITY_CHECKLIST.md)
+- [Policy bundle releases](security/POLICY_RELEASES.md)
+- [Secrets](security/SECRETS.md)
+- [Compliance](security/COMPLIANCE.md)
+- [Threat model](security/THREAT_MODEL.md)
+
+## Build and maintain
+
+- [Testing](operations/TESTING.md)
+- [Reliability](operations/RELIABILITY.md)
+- [Naming conventions](NAMING_CONVENTIONS.md)
+- [Architecture](architecture/ARCHITECTURE.md)
+- [Repository layout](architecture/REPO_LAYOUT.md)
+- [Architecture decisions](adr/README.md)
+
+## Repository map
+
+| Path | Purpose |
+| :--- | :--- |
+| `docs/` | Guides, reference, security, and architecture |
+| `scripts/` | Repo-only scripts and `dot` command internals |
+| `install/` | Installer and provisioning helpers |
+| `dot_config/` | Managed user configuration files |
+| `dot_local/` | Managed local executables |
+| `examples/` | Executable examples |
+| `tests/` | Unit, integration, and framework coverage |
+
+## Platform guides
+
+- [WSL2 and Nix](guides/WSL2_NIX_TROUBLESHOOTING.md)
+- [Neovim IDE](guides/NEOVIM_IDE_GUIDE.md)
+
+## Reference
+
+- [Features](reference/FEATURES.md)
+- [Tools](reference/TOOLS.md)
+- [Aliases](reference/ALIASES.md)
+- [Roadmap](operations/ROADMAP.md)
+- [Version sync](operations/VERSION_SYNC.md)