@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

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,7 +1,7 @@
 /*
-* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.480) - <https://dotfiles.io>
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.500) - <https://github.com/sebastienrousseau/dotfiles>
 * Made With ❤️ in London, United Kingdom
-* Designed by Sebastien Rousseau
+* 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

@@ -1,269 +1,78 @@
-# Dotfiles Documentation
+# Documentation
 
-<div align="center">
+Start here. Then go deeper.
 
-**A modern, cross-platform shell environment built for developers.**
+## The Manual
 
-[Quick Start](#quick-start) · [Features](#features) · [Architecture](#architecture) · [Security](#security) · [Contributing](#contributing)
+The complete reference is the `.dotfiles` Manual — a multi-format book covering every concept, tutorial, reference, and recipe.
 
-</div>
+- 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:
 
-## Overview
+- [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
 
-Welcome to the dotfiles documentation. This guide will help you install, configure, and customize your development environment across macOS, Linux, and WSL.
+## Start
 
-### What You'll Get
+- [Install](guides/INSTALL.md)
+- [Troubleshooting](guides/TROUBLESHOOTING.md)
+- [Support matrix](reference/SUPPORT_MATRIX.md)
 
-| Feature | Description |
-|---------|-------------|
-| 🚀 **Fast Shell** | Zsh with lazy loading, <500ms startup |
-| 🔧 **Modern Tools** | Neovim, tmux, starship, fzf, ripgrep |
-| 🔐 **Security First** | Encrypted secrets, credential management |
-| 🎨 **Beautiful UI** | Nerd Fonts, themes, consistent styling |
-| 📦 **Cross-Platform** | macOS, Linux, WSL2 support |
+## 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)
 
-## Table of Contents
+## Security and trust
 
-### Getting Started
-- [Installation Guide](INSTALL.md) — Set up your environment in minutes
-- [Walkthrough](WALKTHROUGH.md) — Interactive tour of key features
-- [Features Overview](FEATURES.md) — Complete feature list
+- [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)
 
-### Core Documentation
-- [Architecture](ARCHITECTURE.md) — System design and structure
-- [Operations Guide](OPERATIONS.md) — Daily usage and maintenance
-- [Troubleshooting](TROUBLESHOOTING.md) — Common issues and solutions
+## Build and maintain
 
-### Configuration
-- [Aliases Reference](ALIASES.md) — Shell aliases and shortcuts
-- [Keybindings](KEYS.md) — Keyboard shortcuts catalog
-- [Tools Reference](TOOLS.md) — Installed tools and utilities
-- [Utilities](UTILS.md) — Helper scripts and functions
+- [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)
 
-### Customization
-- [Fonts Guide](FONTS.md) — Nerd Fonts installation
-- [Screenshots](SCREENSHOTS.md) — Visual gallery
-- [Neovim IDE Guide](NEOVIM_IDE_GUIDE.md) — Editor configuration
+## Repository map
 
-### Security
-- [Security Overview](SECURITY.md) — Security model and practices
-- [Security Checklist](SECURITY_CHECKLIST.md) — Hardening guide
-- [Secrets Management](SECRETS.md) — Encrypted credentials
+| 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 |
 
-### Development
-- [Testing Guide](TESTING.md) — Test framework and coverage
-- [Compliance](COMPLIANCE.md) — Standards and policies
-- [Architecture Decisions](adr/) — ADRs for key decisions
+## Platform guides
 
-### Platform-Specific
-- [WSL2 + Nix Guide](WSL2_NIX_TROUBLESHOOTING.md) — Windows Subsystem for Linux
+- [WSL2 and Nix](guides/WSL2_NIX_TROUBLESHOOTING.md)
+- [Neovim IDE](guides/NEOVIM_IDE_GUIDE.md)
 
-### Reference
-- [Roadmap](ROADMAP.md) — Future plans and priorities
-- [Legacy Roadmap](LEGACY_ROADMAP.md) — Historical context
+## Reference
 
----
-
-## Quick Start
-
-### Prerequisites
-
-- macOS 12+, Ubuntu 22.04+, or Windows 11 with WSL2
-- Git 2.30+
-- curl or wget
-
-### Installation
-
-```bash
-# One-line install
-curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh | bash
-```
-
-Or clone and install manually:
-
-```bash
-git clone https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles
-cd ~/.dotfiles && ./install.sh
-```
-
-### First Steps
-
-After installation, run these commands to explore:
-
-```bash
-dot help          # Show all available commands
-dot doctor        # Check system health
-dot learn         # Interactive tour
-dot keys          # View keybindings
-```
-
----
-
-## Features
-
-### Shell Environment
-
-The shell configuration provides a fast, feature-rich experience:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Startup Time: <500ms  │  Plugin Manager: Zinit            │
-│  Prompt: Starship      │  Completions: Lazy-loaded         │
-│  History: Shared       │  Syntax: fast-syntax-highlighting │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Key Features:**
-- Intelligent command suggestions with autosuggestions
-- Fuzzy finding with fzf for files, history, and git
-- Git integration with delta for beautiful diffs
-- Directory jumping with zoxide
-
-### Development Tools
-
-Pre-configured toolchains for modern development:
-
-| Language | Tools |
-|----------|-------|
-| **Rust** | rustup, cargo, clippy, rustfmt |
-| **Go** | go, golangci-lint |
-| **Node.js** | nvm, npm, pnpm |
-| **Python** | pyenv, pipx, uv |
-
-### AI Integration
-
-Built-in support for AI coding assistants:
-
-- **aider** — AI pair programming
-- **Claude** — Anthropic's assistant
-- **GitHub Copilot** — Code suggestions
-- **git-ai-commit** — AI-powered commit messages
-
----
-
-## Architecture
-
-The dotfiles follow a modular architecture:
-
-```
-~/.dotfiles/
-├── dot_config/           # XDG config files
-│   ├── nvim/             # Neovim configuration
-│   ├── zsh/              # Zsh configuration layers
-│   └── git/              # Git configuration
-├── dot_local/bin/        # User scripts and tools
-├── install/              # Installation scripts
-│   └── provision/        # Tool provisioning
-├── scripts/              # Operational scripts
-│   ├── dot/commands/     # CLI command modules
-│   ├── diagnostics/      # Health checks
-│   ├── security/         # Security tools
-│   └── tuning/           # Performance tuning
-└── docs/                 # Documentation (you are here)
-```
-
-### Shell Layer System
-
-Zsh configuration uses numbered layers for predictable loading:
-
-| Range | Purpose | Examples |
-|-------|---------|----------|
-| 00-19 | Core | Environment, history, options |
-| 20-49 | Middleware | Zinit, completions, plugins |
-| 50-89 | Toolchain | Languages, package managers |
-| 90-99 | UX | Prompt, aliases, keybindings |
-
-### CLI Architecture
-
-The `dot` CLI uses modular command dispatch:
-
-```bash
-dot <command> [args]
-     │
-     ├── core.sh        # apply, sync, update, diff
-     ├── diagnostics.sh # doctor, heal, benchmark
-     ├── tools.sh       # tools, new, packages
-     ├── appearance.sh  # theme, fonts, wallpaper
-     ├── secrets.sh     # secrets-init, secrets
-     ├── security.sh    # firewall, backup, encrypt
-     └── meta.sh        # upgrade, docs, learn
-```
-
----
-
-## Security
-
-Security is a core principle, not an afterthought.
-
-### Secrets Management
-
-```bash
-dot secrets-init    # Initialize age encryption
-dot secrets         # Edit encrypted secrets
-dot ssh-key         # Encrypt SSH keys
-```
-
-Secrets are encrypted with [age](https://age-encryption.org/) and never stored in plaintext.
-
-### Credential Management
-
-Supported credential stores:
-- **macOS** — Keychain integration
-- **Linux** — libsecret / GNOME Keyring
-- **Git** — git-credential-manager
-
-### Security Hardening (Opt-in)
-
-```bash
-dot firewall      # Configure firewall rules
-dot telemetry     # Disable OS telemetry
-dot dns-doh       # Enable DNS-over-HTTPS
-dot encrypt-check # Verify disk encryption
-```
-
-All security modifications require explicit consent.
-
----
-
-## Contributing
-
-We welcome contributions! Please see our guidelines:
-
-1. **Fork** the repository
-2. **Create** a feature branch
-3. **Test** your changes with `dot doctor`
-4. **Submit** a pull request
-
-### Code Style
-
-- Shell scripts: Follow ShellCheck recommendations
-- Templates: Use `.chezmoitemplates/` for reusable logic
-- Documentation: Use UPPERCASE.md naming convention
-
-### Testing
-
-```bash
-./scripts/tests/framework/test_runner.sh        # Unit tests
-RUN_INTEGRATION=1 ./scripts/tests/framework/test_runner.sh  # Integration
-```
-
----
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/sebastienrousseau/dotfiles/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/sebastienrousseau/dotfiles/discussions)
-
----
-
-<div align="center">
-
-**[Back to Top](#dotfiles-documentation)**
-
-Made with ❤️ by [Sebastien Rousseau](https://github.com/sebastienrousseau)
-
-</div>
+- [Features](reference/FEATURES.md)
+- [Tools](reference/TOOLS.md)
+- [Aliases](reference/ALIASES.md)
+- [Roadmap](operations/ROADMAP.md)
+- [Version sync](operations/VERSION_SYNC.md)

package/docs/adr/ADR-004-cli-architecture.md

@@ -25,7 +25,7 @@ Use **Chezmoi as the core engine** with a **custom `dot` CLI wrapper** that:
 
 ### Architecture
 
-```
+```text
 ┌─────────────────────────────────────────────┐
 │                 dot CLI                      │
 │  (User-friendly interface, custom commands)  │
@@ -57,7 +57,7 @@ Use **Chezmoi as the core engine** with a **custom `dot` CLI wrapper** that:
 - Consistent help and error messages
 
 **3. Modular command structure:**
-```
+```text
 scripts/dot/
 ├── lib/
 │   └── utils.sh          # Shared functions

package/docs/adr/ADR-006-shell-selection.md

@@ -30,7 +30,7 @@ Use **Zsh** as the default interactive shell with **Zinit** as the plugin manage
 
 1. **Default on macOS**: Pre-installed since Catalina
 2. **Plugin Ecosystem**: Massive library of plugins and themes
-3. **Compatibility**: POSIX-compatible, easy migration from bash
+3. **Compatibility**: POSIX-compatible, smooth migration from bash
 4. **Completion System**: Superior tab completion
 5. **Customization**: Highly configurable prompt and behavior
 6. **Community**: Large community, well-documented
@@ -54,7 +54,7 @@ Zinit provides:
 
 ### Shell Layer System
 
-```
+```text
 dot_config/zsh/rc.d/
 ├── 00-10: Core (env, history, options)
 ├── 20-49: Middleware (zinit, completions)

package/docs/adr/ADR-007-multi-shell-parity.md

@@ -0,0 +1,53 @@
+# ADR-007: Multi-Shell Parity Strategy
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-08
+
+## Context
+
+The dotfiles distribution supports three shells: Zsh (default since macOS Catalina), Fish (modern interactive shell), and Nushell (structured data shell). The codebase has 98 alias files and 52+ functions written in POSIX/Bash. Without a parity strategy, each shell gets a fragmented subset of functionality.
+
+**Problem:** Fish had zero access to the alias/function library until v0.2.500 added bridge templates. Nushell had only 6 hardcoded aliases and no function access.
+
+**Constraints:**
+- Nushell's `source` is parse-time evaluated (no dynamic sourcing)
+- Fish syntax differs significantly from POSIX (no `$()`, different `if`, no `[[`)
+- Maintaining N copies of every alias/function is unsustainable
+
+## Decision
+
+Adopt a **hub-and-spoke bridge architecture**:
+
+1. **Hub:** Canonical definitions live in `.chezmoitemplates/aliases/` (Bash/POSIX) and `.chezmoitemplates/functions/` (Bash)
+2. **Bash/Zsh spoke:** Direct inclusion via `90-ux-aliases.sh.tmpl` and `50-logic-functions.sh.tmpl`
+3. **Fish spoke:** Runtime bash bridge with caching (`aliases.fish.tmpl`, `functions.fish.tmpl`)
+4. **Nushell spoke:** Hybrid approach:
+   - Aliases: Runtime bash extraction cached to `~/.cache/nushell/bash-aliases.nu` (in `env.nu.tmpl`), sourced by `aliases.nu.tmpl`
+   - Functions: Chezmoi template-generated `def` wrappers delegating to bash (in `functions.nu.tmpl`)
+
+**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, `_cached_eval` caching
+- **Tier 3 (Compatible):** Nushell — simple aliases (no complex bash syntax), all functions via bash delegation
+
+## Consequences
+
+### Positive
+- 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 `_cached_eval`
+
+### Negative
+- 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
+
+### Risks
+- Nushell's rapid development may break bridge syntax in future versions
+- Very large alias sets may slow Nushell startup during cache generation