@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/reference/FONTS.md

@@ -0,0 +1,112 @@
+---
+render_with_liquid: false
+---
+
+# Font configuration
+
+How fonts are set up, rendered, and installed in these dotfiles.
+
+## Recommended fonts
+
+### Primary: JetBrains Mono Nerd Font
+
+The default font is JetBrains Mono with Nerd Font patches. It's designed for code readability, supports ligatures, includes Powerline/Nerd Font glyphs, and clearly distinguishes similar characters (`0`/`O`, `1`/`l`/`I`).
+
+### Alternatives
+
+| Font | Style | Best for |
+|------|-------|----------|
+| Fira Code | Modern | Ligature fans |
+| Cascadia Code | Microsoft | VS Code users |
+| Hack | Classic | Traditional monospace look |
+| Source Code Pro | Adobe | Clean aesthetic |
+| Iosevka | Narrow | Small screens |
+
+## Installation
+
+### macOS (Homebrew)
+
+```bash
+brew tap homebrew/cask-fonts
+brew install --cask font-jetbrains-mono-nerd-font
+
+# Or use the dot CLI
+dot fonts install
+```
+
+### Linux (manual)
+
+```bash
+wget https://github.com/ryanoasis/nerd-fonts/releases/download/v3.4.0/JetBrainsMono.zip
+unzip JetBrainsMono.zip -d ~/.local/share/fonts/
+fc-cache -fv
+```
+
+### Patching your own fonts
+
+To patch a custom font with Nerd Font glyphs:
+
+```bash
+~/.dotfiles/scripts/fonts/patch-fonts.sh /path/to/font.ttf
+```
+
+## Terminal configuration
+
+### Ghostty
+
+```text
+font-family = JetBrains Mono Nerd Font
+font-size = 14
+```
+
+### WezTerm
+
+```lua
+config.font = wezterm.font("JetBrains Mono Nerd Font")
+config.font_size = 14.0
+```
+
+### Alacritty
+
+```yaml
+font:
+  normal:
+    family: JetBrains Mono Nerd Font
+  size: 14.0
+```
+
+### Kitty
+
+```text
+font_family JetBrains Mono Nerd Font
+font_size 14.0
+```
+
+## Font size recommendations
+
+| Display | Size |
+|---------|------|
+| 13" laptop | 12-13pt |
+| 15" laptop | 13-14pt |
+| 24" monitor | 14-15pt |
+| 27" 4K monitor | 15-16pt |
+
+## Troubleshooting
+
+### Fonts not displaying correctly
+
+1. Verify the font is installed: `fc-list | grep JetBrains`
+2. Restart your terminal
+3. Double-check the terminal's font settings
+
+### Nerd Font icons missing
+
+1. Make sure you're using a Nerd Font variant (not the plain version)
+2. Confirm the terminal supports the required Unicode range
+3. Try a different Nerd Font if the issue persists
+
+### Ligatures not working
+
+1. Enable ligatures in your terminal's settings
+2. Some terminals don't support ligatures (e.g., `Terminal.app`)
+3. Ghostty, WezTerm, and Kitty all handle ligatures well

package/docs/reference/PROFILES.md

@@ -0,0 +1,69 @@
+---
+render_with_liquid: false
+---
+
+# Profiles and Machine Setup
+
+## Profile System
+
+You can set up each machine differently using profiles and hardware presets.
+
+### Setting Your Profile
+
+Edit `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[data]
+profile = "laptop"        # laptop | minimal | server
+machine = "macbook-m3"    # optional: machine identifier
+```
+
+### Available Profiles
+
+| Profile | Description | What's Included |
+|---------|-------------|-----------------|
+| `laptop` | Full desktop setup (default) | All tools, AI CLIs, themes, completions |
+| `minimal` | Fast, lightweight | Core shell, git, basic aliases only |
+| `server` | Headless server | Shell, git, monitoring tools, no desktop |
+
+### Per-Machine Overrides
+
+Create a `~/.config/chezmoi/chezmoi.toml` file on each machine to override defaults:
+
+```toml
+[data]
+profile = "laptop"
+machine = "work-macbook"
+default_shell = "zsh"
+
+[data.features]
+linux_desktop = false
+zellij = true
+```
+
+### Hardware Presets
+
+The `templates/chezmoi-data/` folder has ready-made configs for common hardware:
+
+- `mac-m1.toml.example` — Apple Silicon MacBook
+- `geekom-a9.toml.example` — AMD mini PC (Linux)
+- `surface-pro-7p.toml.example` — Microsoft Surface (Linux)
+- `mac-t2-linux.toml.example` — Intel Mac running Linux
+
+Copy the one that matches your hardware:
+
+```bash
+cp templates/chezmoi-data/mac-m1.toml.example ~/.config/chezmoi/chezmoi.toml
+chezmoi apply
+```
+
+### Environment Variables
+
+You can change behavior for a single session without editing any files:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `DOTFILES_FAST=1` | 0 | Skip heavy layers (zinit, completions) |
+| `DOTFILES_ULTRA_FAST=1` | 0 | Bare minimum shell (aliases + prompt) |
+| `DOTFILES_AI=1` | 0 | Enable AI helper scripts |
+| `DOTFILES_PROFILE=custom` | laptop | Override profile for session |

package/docs/reference/SCREENSHOTS.md

@@ -0,0 +1,121 @@
+---
+render_with_liquid: false
+---
+
+# Screenshots Gallery
+
+Here's how the dotfiles look across different themes and configurations.
+
+## Theme Gallery
+
+### Catppuccin Mocha (default)
+
+The default theme. Catppuccin Mocha gives you a dark palette with warm, muted colors.
+
+```text
+Terminal: Ghostty / WezTerm / Alacritty
+Font:     JetBrains Mono Nerd Font
+Theme:    Catppuccin Mocha
+```
+
+Key colors:
+
+- Background: `#1e1e2e`
+- Foreground: `#cdd6f4`
+- Accent Blue: `#89b4fa`
+- Accent Red: `#f38ba8`
+
+### Catppuccin Latte (light)
+
+A light theme option for daytime use.
+
+```text
+Terminal: Ghostty / WezTerm / Alacritty
+Font:     JetBrains Mono Nerd Font
+Theme:    Catppuccin Latte
+```
+
+Key colors:
+
+- Background: `#eff1f5`
+- Foreground: `#4c4f69`
+- Accent Blue: `#1e66f5`
+- Accent Red: `#d20f39`
+
+## Terminal Configurations
+
+### Ghostty
+
+Modern, native terminal with GPU acceleration.
+
+- Native macOS integration
+- Fast rendering
+- Ligature support
+- Custom key bindings
+
+### WezTerm
+
+Cross-platform terminal with Lua configuration.
+
+- GPU acceleration
+- Multiple windows/tabs
+- Hyperlinks
+- Image protocol support
+
+### Alacritty
+
+Minimal, fast terminal.
+
+- Fast rendering
+- Simple YAML config
+- Vi mode
+- Cross-platform
+
+### Kitty
+
+Feature-rich terminal.
+
+- GPU rendering
+- Ligatures
+- Image support
+- Keyboard protocol
+
+## Prompt (Starship)
+
+The Starship prompt displays:
+
+- Current directory
+- Git branch and status
+- Language versions (when relevant)
+- Command duration
+- Exit status
+
+## Neovim
+
+The Neovim configuration includes:
+
+- Catppuccin theme
+- Treesitter syntax highlighting
+- LSP integration
+- Telescope fuzzy finder
+- File tree (`nvim-tree`)
+
+## tmux
+
+The tmux status bar displays:
+
+- Session name
+- Current window
+- Host name
+- Date and time
+
+## Adding Screenshots
+
+To contribute screenshots:
+
+1. Take a screenshot of your terminal.
+2. Save it as a PNG in `docs/themes/`.
+3. Add a reference in this file.
+4. Submit a PR.
+
+Recommended screenshot size: 1920x1080 or 2560x1440.

package/docs/reference/SCRIPTS.md

@@ -0,0 +1,71 @@
+---
+render_with_liquid: false
+---
+
+# Script Catalog
+
+Exhaustive catalog of user-facing executables installed from `dot_local/bin/`.
+
+## Core and dotfiles workflows
+
+| Command | Description |
+|---------|-------------|
+| `dot` | Primary dotfiles command-line interface |
+| `dot-ai` | Legacy AI query wrapper for local dotfiles context |
+| `dot-bootstrap` | Deterministic bootstrap entrypoint for fresh machines |
+| `dot-launch-or-focus` | Launch or focus desktop applications and sessions |
+| `dot-load-benchmark` | Measure heavy shell layer readiness in a fresh shell |
+| `dot-load-benchmark-pty` | PTY-based readiness benchmark for shell prewarm flows |
+| `dot-theme-sync` | Synchronize managed theme state across tools |
+| `update` | Update the managed dotfiles environment |
+| `tour` | Interactive guided tour of the dotfiles environment |
+
+## AI and git helpers
+
+| Command | Description |
+|---------|-------------|
+| `ai-update` | Update AI-related CLIs, runtimes, and supporting tools |
+| `ai_core` | Local AI runtime wrapper and provider fallback core |
+| `git-ai-commit` | Generate commit messages from staged changes with AI |
+| `git-ai-diff` | Review diffs and change sets with AI assistance |
+| `antigravity` | Safe wrapper for Antigravity updater execution |
+
+## Clipboard, encoding, and data inspection
+
+| Command | Description |
+|---------|-------------|
+| `b64` | Base64 encode and decode utility |
+| `bm` | Directory bookmark manager |
+| `cb` | Cross-platform clipboard helper |
+| `dtags` | Inspect Docker image tags |
+| `epoch` | Convert between human time and Unix epoch values |
+| `extract` | Archive extraction helper |
+| `hash` | Compute hashes for strings or files |
+| `hashsum` | Cross-platform cryptographic hash calculator |
+| `hex` | Hex dump and transformation helper |
+| `jsonv` | JSON validator and formatter |
+| `jwt` | JWT decoder and payload inspector |
+| `regex` | Regular expression testing helper |
+| `uuid` | UUID generation utility |
+| `yamlv` | YAML validator |
+
+## System, network, and session tools
+
+| Command | Description |
+|---------|-------------|
+| `gd` | Git diff workflow helper |
+| `gbd` | Git branch deletion workflow helper |
+| `gl` | Git log workflow helper |
+| `kill-port` | Terminate processes bound to a TCP or UDP port |
+| `lorem` | Lorem ipsum text generator |
+| `monitor` | System monitor and environment inspection helper |
+| `myip` | Show public and local IP addresses |
+| `notify` | Cross-platform desktop notification helper |
+| `open` | Cross-platform opener for files, URLs, and paths |
+| `pw` | Password and secret helper utility |
+| `rec-start` | Start shell session recording |
+| `rec-stop` | Stop shell session recording |
+| `start-niri` | Launch a Niri compositor session |
+| `tmux-sessionizer` | Fuzzy tmux session and project switcher |
+| `up` | Jump up directory levels quickly |
+| `win` | WSL bridge for launching Windows programs |

package/docs/reference/SUPPORT_MATRIX.md

@@ -0,0 +1,80 @@
+---
+render_with_liquid: false
+---
+
+# Support Matrix
+
+Tested platform and tool combinations for the dotfiles distribution.
+
+## Operating Systems
+
+| OS | Version | Architecture | Status | Notes |
+|----|---------|-------------|--------|-------|
+| macOS | 14+ (Sonoma) | aarch64 (Apple Silicon) | Supported | Primary dev platform |
+| macOS | 14+ (Sonoma) | x86_64 | Supported | CI tested |
+| Ubuntu | 22.04+ | x86_64 | Supported | CI tested |
+| Ubuntu | 22.04+ | aarch64 | Supported | Tested manually |
+| Debian | 12+ | x86_64 | Supported | Compatible with Ubuntu |
+| Fedora | 39+ | x86_64 | Community | Not CI tested |
+| Arch Linux | Rolling | x86_64 | Community | Not CI tested |
+| WSL2 | Ubuntu 22.04+ | x86_64 | Supported | Clipboard bridge included |
+| NixOS | 23.11+ | x86_64/aarch64 | Supported | Via Nix Flake |
+
+## Shells
+
+| Shell | Min Version | Status | Parity Tier | Notes |
+|-------|-------------|--------|-------------|-------|
+| Zsh | 5.8+ | Supported | Tier 1 (Full) | Default shell, all features |
+| Bash | 5.0+ | Supported | Tier 1 (Full) | Shared logic core |
+| Fish | 4.0+ | Supported | Tier 1 (Core CLI) | Native `dot`, `dm`, `da`, `dmc`, `datt`, and cached alias bridge |
+| Nushell | 0.98+ | Supported | Tier 1 (Core CLI) | Native `d`, `dm`, `da`, `dmc`, `datt` aliases for core workflows |
+| PowerShell | 7.5+ | Supported | Tier 1 (Core CLI) | Managed profile, `dot` wrapper, modern listing helpers, and attestation aliases |
+
+## Terminal Emulators
+
+| Terminal | Status | Notes |
+|----------|--------|-------|
+| Ghostty | Supported | Primary, custom config in `dot_config/ghostty/` |
+| iTerm2 | Supported | macOS only; auto-installed Dynamic Profile via `run_onchange_22-iterm2-profile.sh.tmpl` (pick "dotfiles" profile in iTerm2) |
+| Alacritty | Supported | Theme-driven, config in `dot_config/alacritty/` |
+| Kitty | Supported | Theme-driven, config in `dot_config/kitty/` |
+| WezTerm | Supported | Theme-driven, config in `dot_config/wezterm/` |
+| Foot | Supported | Linux/Wayland, gated by `features.foot`, config in `dot_config/foot/` |
+| Warp | Supported | Theme-driven, deploys to `~/.warp/themes/dotfiles.yaml`; pick "dotfiles" in Warp Settings → Appearance → Themes |
+| Windows Terminal | Supported | WSL2 profile |
+| tmux | Supported | Config in `dot_config/tmux/` |
+
+## Key Tools
+
+| Tool | Min Version | Required | Notes |
+|------|-------------|----------|-------|
+| chezmoi | 2.40+ | Yes | Core dotfiles manager |
+| git | 2.35+ | Yes | Version control |
+| curl | 7.0+ | Yes | Bootstrap installer |
+| Neovim | 0.11.2+ | No | IDE config, lazy.nvim plugins |
+| Starship | 1.17+ | No | Cross-shell prompt |
+| mise | 2024.1+ | No | Tool version manager |
+| Nix | 2.18+ | No | Reproducible environments |
+| fzf | 0.48+ | No | Fuzzy finder |
+| zoxide | 0.9+ | No | Smart directory jumper |
+| atuin | 18.0+ | No | Shell history sync |
+| pueue | 3.0+ | No | Background task manager |
+
+## CI Environments
+
+| Environment | Workflow | Platform | Status |
+|------------|----------|----------|--------|
+| GitHub Actions (Linux) | `ci.yml` | ubuntu-latest | Tested on every PR |
+| GitHub Actions (macOS) | `ci.yml` | macos-latest | Tested on every PR |
+| GitHub Actions (Enforced) | `ci-enforced.yml` | ubuntu-latest | Stricter checks |
+| Devcontainer | `devcontainer-prebuild.yml` | ubuntu-latest | Pre-built images |
+
+## Known Limitations
+
+| Platform | Limitation | Workaround |
+|----------|-----------|------------|
+| WSL2 | No native clipboard | `clip.exe`/`powershell.exe` bridge aliases |
+| NixOS | System packages conflict | Use Nix Flake exclusively |
+| Fish < 4.0 | No keyboard protocol | Upgrade to Fish 4.x |
+| Nushell | Complex aliases skipped | Core `dot` workflow remains first-class |
+| macOS Intel | Homebrew path differs | Template handles `/usr/local` vs `/opt/homebrew` |

package/docs/reference/THEMES.md

@@ -0,0 +1,117 @@
+---
+render_with_liquid: false
+---
+
+# Themes
+
+Themes are auto-generated from wallpapers. K-Means clustering in CIELAB color space extracts dominant colors. Every theme is WCAG AAA compliant.
+
+There is no fixed theme catalog. The available themes depend on which wallpapers are present on your system. Run `dot theme list` to see what's discovered.
+
+## Source of truth
+
+Wallpapers — not `themes.toml` — are the source of truth. The system discovers wallpapers from two locations:
+
+1. **System wallpapers** — platform-native (macOS `/System/Library/Desktop Pictures/`, Linux `/usr/share/backgrounds/`)
+2. **Custom wallpapers** — `~/Pictures/Wallpapers/` (custom overrides system on name collision)
+
+`extract-theme.py` runs K-Means++ in CIELAB on each wallpaper, generates a 16-color terminal palette plus UI/app mappings, and enforces WCAG AAA contrast. `rebuild-themes.sh` orchestrates discovery → parallel extraction → assembly into `.chezmoidata/themes.toml` (cached in `~/.cache/dotfiles/themes/`, regenerated only when wallpapers change).
+
+`.chezmoidata/themes.toml` is a **generated artifact**. Do not edit it directly.
+
+## Quick Start
+
+```bash
+dot theme              # Interactive picker (paired wallpaper themes only)
+dot theme tahoe-dark   # Switch directly
+dot theme toggle       # Swap dark↔light within current family
+dot theme rebuild      # Regenerate from current wallpapers
+dot theme list         # Show paired themes with System/Custom source
+```
+
+## Runtime Apply Behavior
+
+`dot theme` writes the selected theme to `.chezmoidata.toml`, regenerates target configs through chezmoi, then attempts live reloads for running applications.
+
+- **macOS**:
+  - Applies system Light/Dark appearance via `osascript` (`System Events`)
+  - Applies the wallpaper's derived accent color via `defaults write -g AppleAccentColor` and `AppleHighlightColor`
+  - Forces UI refresh via `killall cfprefsd SystemUIServer Dock "System Settings"`
+  - Sets desktop wallpaper across all displays via `osascript`
+- **Linux**:
+  - Applies desktop color scheme through `gsettings`
+  - Sets `picture-uri` and `picture-uri-dark` separately
+  - Auto-converts HEIC → PNG via `magick`/`heif-convert`/`convert`
+  - DMS (Dank Material Shell) integration when present
+
+## Theme Naming
+
+Themes follow the pattern `<wallpaper-name>-<dark|light>`. The wallpaper filename (lowercased, hyphenated) becomes the theme family.
+
+Examples (depend on what's present on your system):
+
+| Wallpaper file | Generated themes |
+|:---|:---|
+| `~/Pictures/Wallpapers/tahoe.heic` (dynamic HEIC, 2 frames) | `tahoe-dark`, `tahoe-light` |
+| `/System/Library/Desktop Pictures/Sonoma.heic` | `sonoma-dark`, `sonoma-light` |
+| `/System/Library/Desktop Pictures/.thumbnails/Dome Dark.heic` + `Dome Light.heic` | `dome-dark`, `dome-light` |
+
+Only paired themes (with both dark and light variants) appear in `dot theme` and `dot theme list`.
+
+## Custom Wallpapers — Dynamic HEIC
+
+Custom wallpapers in `~/Pictures/Wallpapers/` ship as Apple-compatible dynamic HEIC files: a single `.heic` containing both light and dark images, tagged with `apple_desktop:apr` XMP metadata. macOS auto-switches the displayed image based on appearance mode.
+
+To merge separate dark + light pairs into a single dynamic HEIC:
+
+```bash
+bash scripts/theme/merge-wallpaper.sh           # merge all pairs in ~/Pictures/Wallpapers/
+bash scripts/theme/merge-wallpaper.sh tahoe     # merge a specific family
+bash scripts/theme/merge-wallpaper.sh --dry-run # preview only
+```
+
+## Generated Theme Schema
+
+Each theme block in the generated `themes.toml` follows this schema:
+
+```toml
+[themes.example-dark]
+mode = "dark"               # "dark" or "light"
+family = "example"          # groups dark/light variants
+macos_accent = 4            # derived from accent hue (0-6, -1=Graphite)
+wallpaper = "/path/to/wallpaper.heic"
+source = "custom"           # "custom" or "system"
+
+[themes.example-dark.term]
+bg, fg, cursor, cursor_text, sel_bg, sel_fg
+c0  .. c15                  # 16 ANSI colors
+
+[themes.example-dark.ui]
+accent, accent_text         # white text always 7:1 against accent
+error, warning, success, info
+panel, border               # contrast-bound (1.03-2.0 for panel, 1.08-3.5 for border)
+
+[themes.example-dark.app]
+nvim, nvim_style, lualine
+gtk_theme, gtk_icon, gnome_shell, gnome_gtk
+vscode, vscode_dark, vscode_light
+cat_wallpaper
+starship_palette
+```
+
+## Adding a Theme
+
+To add a new theme, add a wallpaper — there are no manual TOML edits.
+
+1. Drop a wallpaper into `~/Pictures/Wallpapers/`
+2. (Optional) Use `merge-wallpaper.sh` to combine separate dark/light files into a single dynamic HEIC
+3. Run `dot theme rebuild` to regenerate `themes.toml` (parallel K-Means extraction, ~1-4s per wallpaper)
+4. Run `dot theme <name>` to test
+5. Verify with `chezmoi diff` before applying
+
+For best results, wallpapers should be 6016×6016 dynamic HEIC with ~1.6× brightness ratio between dark and light variants (golden ratio). Lower-resolution images are auto-resized; non-paired wallpapers are skipped from the picker.
+
+## See Also
+
+- [Theming Guide](../guides/THEMING.md) — full pipeline documentation
+- [Utilities](UTILS.md) — `dot theme` command reference

package/docs/reference/TOOLS.md

@@ -0,0 +1,109 @@
+---
+render_with_liquid: false
+---
+
+# Tools
+
+Integrated tools organized by role in the workflow.
+
+---
+
+## Core Shells
+
+| Tool | Purpose | Key Feature |
+| :--- | :--- | :--- |
+| **Zsh** | Primary shell | Modular `rc.d` architecture with lazy-loading |
+| **Fish** | Interactive shell | Fast startup via dynamic alias-to-function autoloading |
+| **Nushell** | Data shell | Structured data pipelines |
+| **Starship** | Cross-shell prompt | Async segment rendering |
+
+---
+
+## Infrastructure and Portability
+
+| Tool | Category | Description |
+| :--- | :--- | :--- |
+| **Nix Flakes** | Deterministic environments | Reproducible setups via `flake.nix` |
+| **Chezmoi** | Dotfiles manager | Template-based configuration across machines |
+| **Direnv** | Environment management | Automatic environment injection on `cd` |
+| **Mise** | Runtime manager | Polyglot version manager (Node, Python, Rust, Go) |
+
+---
+
+## Automation and Advanced Tools
+
+| Tool | Purpose | Description |
+| :--- | :--- | :--- |
+| **Pueue** | Task queue | Offload long-running tasks to a background daemon |
+| **Wasmtime** | Wasm runtime | Run pre-compiled Rust/Zig tools as WebAssembly modules |
+| **SOPS** | Secrets operations | Encrypted secrets with automatic en/decryption |
+
+---
+
+## Navigation and Discovery
+
+| Tool | Description |
+| :--- | :--- |
+| **Yazi** | Terminal file manager — use `yy` to `cd` on exit |
+| **Ripgrep (rg)** | Fast recursive text search |
+| **fd** | Simpler, faster alternative to `find` |
+| **Zoxide** | Fuzzy directory jumper (replaces `cd`) |
+| **fzf** | Interactive fuzzy finder for files, history, and git |
+
+---
+
+## Modern CLI Replacements
+
+| Classic | Replacement | Improvement |
+| :--- | :--- | :--- |
+| `ls` | **eza** | Icons, git status, better colors |
+| `cat` | **bat** | Syntax highlighting and git integration |
+| `top` | **btop** | Visual system resource dashboard |
+| `df` | **duf** | Readable disk usage overview |
+| `du` | **dust** | Visual breakdown of folder sizes |
+| `ps` | **procs** | Improved process tracking |
+
+---
+
+## Terminal Ecosystem
+
+| Tool | Style | Platform |
+| :--- | :--- | :--- |
+| **Ghostty** | Native / GPU | macOS, Linux |
+| **Zellij** | Layout-aware multiplexer | Cross-platform |
+| **Tmux** | Classic multiplexer | Cross-platform |
+| **Fastfetch** | System info | Cross-platform |
+
+---
+
+## Developer Tools
+
+| Tool | Description |
+| :--- | :--- |
+| **Neovim** | Lua-based configuration with lazy.nvim |
+| **Lazygit** | TUI for Git workflows |
+| **Delta** | Syntax-highlighted side-by-side diffs |
+| **Just** | Task runner (replaces Makefiles) |
+| **Age** | Modern file encryption |
+| **GnuPG** | PGP standard for signing and encryption |
+
+---
+
+## AI Pair Programming
+
+Detailed guide: [AI.md](../AI.md).
+
+| Tool | Description |
+| :--- | :--- |
+| **Aider** | Git-native AI pair programming |
+| **Claude CLI** | Anthropic's terminal assistant |
+| **Copilot CLI** | GitHub Copilot in the terminal |
+| **Kiro CLI** | Agentic AI terminal assistant |
+| **Gemini CLI** | Google's multi-modal CLI tool |
+| **Mods/Fabric** | Pipeline-friendly AI processing |
+| **sgpt** | Shell-GPT for terminal AI queries |
+| **Ollama** | Run large language models locally |
+| **Autohand Code** | Autohand coding agent CLI |
+| **Mistral Vibe** | Mistral AI coding agent |
+| **Qwen Code** | Qwen AI coding assistant |
+| **ZAI** | Zhipu AI GLM coding agent |