@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/reference/PROFILES.md

@@ -0,0 +1,65 @@
+# 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,117 @@
+# 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,67 @@
+# 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,74 @@
+# 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, profile config included |
+| Alacritty | Supported | Config in `dot_config/alacritty/` |
+| Kitty | Supported | Config in `dot_config/kitty/` |
+| WezTerm | Supported | Config in `dot_config/wezterm/` |
+| 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,113 @@
+# 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,105 @@
+# 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 |

package/docs/reference/UTILS.md

@@ -0,0 +1,151 @@
+# Utilities
+
+Aliases, functions, and the `dot` CLI provide day-to-day tooling across macOS, Linux, and WSL.
+
+## Dot CLI
+
+The `dot` command is the main interface for managing dotfiles. Run `dot version` or `dot --version` to check the installed version.
+
+### Core commands
+
+| Command | Description |
+|---------|-------------|
+| `dot commit` | Create an AI-assisted conventional commit |
+| `dot apply` | Apply dotfiles (`chezmoi apply`) |
+| `dot sync` | Alias of apply |
+| `dot update` | Pull latest changes and apply |
+| `dot add <file>` | Add a file to chezmoi source |
+| `dot diff` | Show local changes (excludes scripts) |
+| `dot status` | Show configuration drift |
+| `dot remove <path>` | Safely remove a managed file |
+| `dot cd` | Print source directory path |
+| `dot edit` | Open source in your editor |
+| `dot clean-cache` | Clear generated shell initialization caches |
+| `dot prewarm` | Regenerate shell caches for fast startup |
+| `dot bundle` | Create an offline portable archive |
+| `dot upgrade` | Update toolchains, plugins, and dotfiles |
+| `dot packages` | Show installed packages and package managers |
+| `dot cache-refresh` | Rebuild generated shell state |
+| `dot search <term>` | Find commands by keyword |
+| `dot help` | Show command help and the public reference |
+| `dot version` | Show the installed dotfiles version |
+
+### Diagnostics
+
+| Command | Description |
+|---------|-------------|
+| `dot doctor` | Run system health checks (`--score|-s`, `--heal|-H`) |
+| `dot health` | Run the health dashboard (`--verbose|-v`, `--json|-j`, `--fix|-f`, `--force|-F`) |
+| `dot heal` | Auto-repair missing tools, chezmoi drift, broken symlinks, and critical files (`--dry-run|-n`, `--force|-f`) |
+| `dot smoke-test` | Verify toolchains (Rust, Go, AI CLIs) |
+| `dot verify` | Run security and integrity verification (`--security|-s`) |
+| `dot chaos` | Simulate config corruption to test self-healing |
+| `dot rollback` | Roll back dotfiles to the previous known-good state |
+| `dot drift` | Detailed configuration drift dashboard |
+| `dot benchmark` | Measure shell startup time (`--detailed|-d`, `--profile|-p`, `--compare|-c`, `--waterfall|-w`) |
+| `dot perf` | Show performance mode + quick timing (`--json|-j`, `--profile|-p`, `--runs|-r`, `--target|-t`) |
+| `dot score` | Show the high-level system health and security scorecard |
+| `dot metrics` | Show recent observability metrics |
+| `dot load-bench` | Measure heavy-layer readiness |
+| `dot mcp` | Validate MCP policy and registry (`--strict|-s`, `--json|-j`) |
+| `dot attest` | Export workstation evidence (`--json|-j`, `--write|-w`, `--fleet-store|-F`) |
+| `dot history` | Analyse shell history |
+| `dot security-score` | Score workstation security (`--verbose|-v`, `--quiet|-q`, `--json|-j`) |
+| `dot snapshot` | Capture workstation state (`--baseline|-b`, `--force|-f`) |
+| `dot ai` | Show categorized AI CLI status and launch an installed provider |
+| `dot ai-setup` | Bootstrap supported AI CLIs interactively |
+| `dot ai-query` | Run context-aware AI queries over the repo |
+| `dot mode` | Show or switch the active agent profile |
+| `dot agent` | Inspect agent metadata, logs, checkpoints, and conformance |
+| `dot agent checkpoint` | Save, list, show, and replay bounded agent checkpoints |
+| `dot agent conformance` | Validate A2A discovery and agent card conformance (`--strict|-s`, `--json|-j`) |
+
+### Tools
+
+| Command | Description |
+|---------|-------------|
+| `dot env` | Show managed runtime and tool versions |
+| `dot profile` | Show or switch the active configuration profile |
+| `dot keys` | Show the keybindings and signing reference |
+| `dot tools` | Show tools documentation |
+| `dot tools install` | Enter Nix development shell |
+| `dot new <lang> <name>` | Scaffold a project (`python`/`go`/`node`) |
+| `dot sandbox` | Launch Docker sandbox preview |
+| `dot learn` | Start the guided onboarding tour |
+| `dot docs` | Show the main repository documentation |
+| `dot log-rotate` | Rotate `~/.local/share/dotfiles.log` |
+| `dot lint` | Lint shell scripts (`--check|-c`, `--fix|-f`) |
+
+## Universal Scripts
+
+POSIX scripts in `~/.local/bin/` that work across macOS, Linux, and WSL.
+
+| Command | Description |
+|---------|-------------|
+| `als` | Interactive alias and script viewer (categorized) |
+| `cb` | Universal clipboard utility (detects `pbcopy`/`pbpaste`, `xclip`/`wl-copy`, or `clip.exe`) |
+| `open` | Universal file/URL opener (maps to `open`, `xdg-open`, or `explorer.exe`) |
+| `notify` | Universal desktop notifications (`osascript`, `notify-send`, or `powershell`) |
+| `extract` | Universal archive extractor with robust format support and `gum` UI feedback |
+| `up <n>` | Navigate up `n` directory levels |
+| `bm` | Directory bookmarking tool (`add`, `goto`, `list`, `remove`, `update`) |
+| `win` | WSL-specific shim for running Windows binaries with translated paths |
+
+## Appearance
+
+| Command | Description |
+|---------|-------------|
+| `dot theme` | Interactive picker (paired wallpaper themes only) |
+| `dot theme <name>` | Switch directly (e.g. `dot theme tahoe-dark`) |
+| `dot theme toggle` | Swap dark↔light within current family |
+| `dot theme rebuild` | Regenerate themes from system + custom wallpapers via K-Means in CIELAB (`--force`, `--list`) |
+| `dot theme list` | Show paired wallpaper themes with System/Custom source |
+| `dot wallpaper` | Apply a wallpaper independently of theme |
+| `dot fonts` | Install Nerd Fonts |
+| `dot tune` | Apply supported host tuning changes |
+
+Themes are auto-generated from wallpapers — `themes.toml` is not hand-edited. See [Theming Guide](../guides/THEMING.md) for the K-Means CIELAB extraction model and Apple-compatible dynamic HEIC support.
+
+## AI Bridges
+
+| Command | Description |
+|---------|-------------|
+| `dot cl` | Invoke Claude Code with dotfiles context injection |
+| `dot copilot` | Invoke GitHub Copilot CLI with dotfiles context injection |
+| `dot gemini` | Invoke Gemini CLI with dotfiles context injection |
+| `dot kiro` | Invoke Kiro CLI with dotfiles context injection |
+| `dot sgpt` | Invoke Shell-GPT with dotfiles context injection |
+| `dot ollama` | Invoke Ollama with dotfiles context injection |
+| `dot opencode` | Invoke OpenCode with dotfiles context injection |
+| `dot aider` | Invoke Aider with dotfiles context injection |
+
+## Secrets
+
+| Command | Description |
+|---------|-------------|
+| `dot secrets-init` | Initialize the local age identity for secrets |
+| `dot secrets` | Manage encrypted secrets and environment buckets |
+| `dot secrets-create` | Create a new encrypted secrets file |
+| `dot ssh-key` | Encrypt a local SSH key with age |
+| `dot ssh-cert` | Manage short-lived SSH certificates (`issue`/`status`/`revoke`) |
+
+## Security (opt-in)
+
+| Command | Description |
+|---------|-------------|
+| `dot backup` | Create a compressed backup |
+| `dot encrypt-check` | Check disk encryption status |
+| `dot firewall` | Apply firewall hardening |
+| `dot telemetry` | Disable telemetry |
+| `dot dns-doh` | Enable DNS-over-HTTPS |
+| `dot lock-screen` | Enforce lock screen idle settings |
+| `dot usb-safety` | Disable automount for removable media |
+
+## Fleet
+
+| Command | Description |
+|---------|-------------|
+| `dot fleet` | Show fleet node status, namespace, and drift |
+| `dot fleet drift` | Check configuration drift across managed files |
+| `dot fleet namespace` | Show or set the active fleet namespace |
+| `dot fleet events` | Show recent local fleet events |