@sebastienrousseau/dotfiles 0.2.501 → 0.2.503

package/docs/architecture/AI_COST_OPTIMIZATION.md

@@ -0,0 +1,143 @@
+---
+title: "AI Cost Optimization"
+date: 2026-05-24
+---
+
+# AI Cost Optimization
+
+This dotfiles framework ships an opinionated AI-cost layer designed to
+keep token spend predictable and low while still using the smartest
+model for orchestration. Two ideas drive it:
+
+1. **Delegate the grunt work.** Have the expensive smart model
+   orchestrate, and a cheap fast model do the file reads, edits, and
+   verification. The smart model sees one tool call and the final
+   `git diff` instead of every intermediate read.
+2. **Account every call.** Every invocation through `dot ai <provider>`
+   appends a JSONL entry so you can see spend across all providers in
+   one report, not just per-tool dashboards.
+
+## Quick reference
+
+```sh
+dot ai delegate "rename every UserService method that starts with get to fetch"
+dot ai cost                # all-time overview
+dot ai cost --since 7      # last 7 days
+dot ai cost --fails        # only failures + breakdown by failure type
+```
+
+Inside Claude Code: `/vibe`, `/vibe-report`, `/vibeon`, `/vibeoff`,
+`/vibestatus`, `/vibe-model-pick`, `/vibe-model-clear`.
+
+## The delegator pattern
+
+The pattern comes from [pcx-wave/vibe-skill][vibe-skill]. Mistral Vibe
+is the default delegate but the same wrapper accepts any model Vibe
+knows about (DeepSeek V4 Flash, Gemini Flash, etc.).
+
+[vibe-skill]: https://github.com/pcx-wave/vibe-skill
+
+Cost comparison (May 2026 list prices, blended 85 in / 15 out typical
+of coding tasks):
+
+| Task | Claude Sonnet 4.6 ($3 / $15) | Mistral Medium 3.5 ($1.50 / $7.50) | DeepSeek V4 Flash ($0.14 / $0.28) |
+|---|---|---|---|
+| 1-file tweak (800 tok) | ~$0.004 | ~$0.002 | ~$0.0001 |
+| 6-read task (4,800 tok) | ~$0.023 | ~$0.012 | ~$0.0008 |
+| Multi-file refactor (12,000 tok) | ~$0.058 | ~$0.029 | ~$0.002 |
+
+Real-world stats from 254 vibe-skill runs over 10 days (May 2026):
+
+| | Amount |
+|---|---|
+| Actually paid (Mistral Pro prorated + DeepSeek pay-as-you-go) | **$10.35** |
+| Same workload pay-as-you-go via Mistral API | $46.61 |
+| Same workload on Claude Sonnet 4.6 | $179.91 |
+| Saved vs Claude | **$169.56 (17.4× cheaper)** |
+
+Claude itself contributes ~500-1500 tokens per delegation as
+orchestration overhead. Even with that overhead the savings dominate
+for anything beyond a one-line edit.
+
+## Pieces deployed by this repo
+
+| Component | Source path | Deployed to | Role |
+|---|---|---|---|
+| `vibe` skill | `defaults/dot_claude/skills/vibe/` | `~/.claude/skills/vibe/` | Claude Code slash commands (`/vibe`, `/vibe-report`, etc.) |
+| Delegator binary | `defaults/dot_claude/skills/vibe/tools/executable_vibe-delegate` | `~/.claude/skills/vibe/tools/vibe-delegate` | Runs the cheap-model task in a pseudo-TTY, parses streaming JSON, syntax-checks changes, logs the run |
+| Reporter | `defaults/dot_claude/skills/vibe/tools/executable_delegate-report` | `~/.claude/skills/vibe/tools/delegate-report` | Reads the JSONL log, prints overview / by-model / by-project / failure tables |
+| CLI shim | `scripts/dot/commands/ai.sh` | `bin/dot ai delegate` / `bin/dot ai cost` | Same delegator + reporter, callable from the terminal without Claude Code |
+| Unified log hook | `_ai_log_run` in `ai.sh` | runs inside `run_ai_with_context` | Appends one JSONL line per `dot ai <provider>` invocation |
+| Log file | runtime-managed | `~/.local/share/delegate-runs.jsonl` | One line per run; `dot ai cost` reads it |
+
+## State files
+
+| File | Owner | Purpose |
+|---|---|---|
+| `~/.local/share/delegate-runs.jsonl` | runtime | One JSONL entry per AI invocation (vibe + every other provider) |
+| `~/.local/share/vibe-auto.flag` | `/vibeon` / `/vibeoff` | When present, Claude auto-delegates coding tasks to Vibe |
+| `~/.local/share/vibe-model.flag` | `/vibe-model-pick` | Override the Vibe model for the next runs; cleared by `/vibe-model-clear` |
+| `~/.vibe/config.toml` | user | Vibe's own provider / model configuration |
+
+## Reading the report
+
+```
+DELEGATE REPORT  2026-05-17 → 2026-05-24
+  Runs          : 27  (ok: 25, failed: 2, timeout: 0)
+  Success rate  :  92%
+  Avg duration  : 18.4s
+  Tokens total  : 4,231,082
+  Delegate cost : $1.4711
+  Claude equiv  : $14.8294
+  Saved         : $13.3583  (90% cheaper than Claude)
+```
+
+`Claude equiv` is what the same workload would have cost on Claude
+Sonnet 4.6 ($3 / $15 per M tokens, blended at the same in/out ratio).
+The savings line is the difference. Failure types are broken out per
+model so you can see which delegate is most reliable for your repo.
+
+## Provider coverage
+
+Every provider exposed via `dot ai <provider>` is logged best-effort.
+For providers that don't surface token counts in their CLI output, the
+report still tracks: timestamp, project, exit code, duration, prompt
+word count. Token / cost fields stay zero for those providers — the
+report tolerates the gap and aggregates by `model` regardless.
+
+Providers tracked today:
+
+| Provider | Binary | Logged | Tokens surfaced? |
+|---|---|---|---|
+| Claude Code | `claude` | yes | no (CLI doesn't expose) |
+| Codex | `codex` | yes | no |
+| Copilot CLI | `copilot` | yes | no |
+| Gemini CLI | `gemini` | yes | no |
+| Goose | `goose` | yes | no |
+| Aider | `aider` | yes | no |
+| OpenCode | `opencode` | yes | no |
+| Autohand | `autohand` | yes | no |
+| Mistral Vibe | `vibe` | yes | **yes** (via delegator) |
+| Qwen | `qwen` | yes | no |
+| ZAI | `zai` | yes | no |
+| Shell-GPT | `sgpt` | yes | no |
+| Ollama (local) | `ollama` | yes | n/a (no cost) |
+| Kiro CLI | `kiro-cli` | yes | no |
+
+## Future work
+
+Not implemented yet, ordered roughly by likely impact:
+
+1. **Provider-level budget guard.** `dot ai budget --set 50/month`
+   would warn at 80% and refuse new requests at 100% (overridable).
+   Needs per-provider cost estimation hooks beyond what each CLI
+   surfaces today.
+2. **Prompt response cache.** Many coding-helper queries are
+   deterministic ("syntax for X in Y"). A local cache keyed on prompt
+   hash + provider could short-circuit repeat queries.
+3. **Per-task-class model routing.** `dot ai delegate --class refactor`
+   would pick the cheapest model that meets the quality bar for the
+   task class. Today the user picks the model.
+4. **Rate-limit awareness.** Track API rate limits from response
+   headers, queue requests, surface a `dot ai cost --limits` view that
+   shows time-to-reset for every provider with an active limit.

package/docs/architecture/REPO_LAYOUT.md

@@ -14,7 +14,7 @@ For naming conventions (file prefixes, run-script numbering tiers), see
 [`../NAMING_CONVENTIONS.md`](../NAMING_CONVENTIONS.md). For the broader
 architectural rationale (philosophy, startup model, flake strategy), see
 [`ARCHITECTURE.md`](ARCHITECTURE.md). For the configuration-management
-strategy at a higher level, see [`../../CONFIG_STRATEGY.md`](../../CONFIG_STRATEGY.md).
+strategy at a higher level, see [`../CONFIG_STRATEGY.md`](../CONFIG_STRATEGY.md).
 
 ---
 
@@ -85,7 +85,7 @@ exist on purpose and don't overlap:
 |-------------------------------|-----------------------|------------------------------------------------------------------|-------------------------------|
 | `dot_claude/CLAUDE.md`        | `~/.claude/CLAUDE.md` | Claude Code, in **any** cwd on this machine                      | Personal, cross-project       |
 | `CLAUDE.md` (repo root)       | Not deployed          | Claude Code, when cwd is **this** repo                           | Repo-scoped guidance          |
-| `OPENCODE.md` (repo root)     | Not deployed          | OpenCode CLI, when cwd is **this** repo                          | Repo-scoped guidance (mirror) |
+| `docs/OPENCODE.md`            | Not deployed          | OpenCode CLI, when cwd is **this** repo                          | Repo-scoped guidance (mirror) |
 | `.claude/settings.local.json` | Not deployed, **not tracked** | Claude Code                                                     | Per-machine permission allowlist |
 
 Each of the three tracked files carries a header comment explaining its
@@ -143,11 +143,11 @@ the repo itself.
 
 | Subdir                                    | Purpose                                                         |
 |-------------------------------------------|-----------------------------------------------------------------|
-| `scripts/ci/`                             | CI helpers (`check-copyright-headers.sh`, `install-chezmoi-verified.sh`, `validate-ci-config.sh`) |
+| `tools/ci/`                             | CI helpers (`check-copyright-headers.sh`, `install-chezmoi-verified.sh`, `validate-ci-config.sh`) |
 | `scripts/dot/commands/`                   | Subcommand implementations for the `dot` CLI                    |
-| `scripts/docs/`                           | Manual build pipeline (`build-manual.sh`, `check-manual.sh`)    |
+| `tools/docs/`                           | Manual build pipeline (`build-manual.sh`, `check-manual.sh`)    |
 | `scripts/theme/`                          | K-Means CIELAB theme engine + HEIC merge/convert                |
-| `scripts/ops/`, `scripts/maintenance/`, `scripts/release/` | Operator tooling                                        |
+| `scripts/ops/`, `tools/maintenance/`, `tools/release/` | Operator tooling                                        |
 | `scripts/diagnostics/`, `scripts/qa/`, `scripts/security/`, `scripts/secrets/` | Domain-scoped scripts                          |
 | `scripts/fonts/`, `scripts/demo/`, `scripts/git-hooks/`, `scripts/tools/`, `scripts/tuning/`, `scripts/lib/` | Supporting scripts                                          |
 | `scripts/uninstall.sh`, `scripts/version-sync.sh` | Top-level ops entrypoints                                 |
@@ -199,7 +199,7 @@ braces.
 | `templates/chezmoi-data/`, `templates/projects/` | Starter scaffolding for new machines / new projects                     |
 | `examples/`                               | 14 standalone demo scripts used by the manual and tutorials                  |
 | `CHANGELOG.md`, `LICENSE`, `README.md`    | Standard                                                                     |
-| `CONFIG_STRATEGY.md`                      | High-level "how configuration management works here" overview                |
+| `docs/CONFIG_STRATEGY.md`                 | High-level "how configuration management works here" overview                |
 | `.gitattributes`, `.gitignore`, `.gitleaksignore`, `.editorconfig`, `.secrets.baseline`, `.sops.yaml`, `.luacheckrc` | Repo-level tool configs                                                    |
 | `.pre-commit-config.yaml` → `config/pre-commit-config.yaml` | Symlink so `pre-commit` finds the canonical config                       |
 
@@ -213,7 +213,7 @@ version control. If one of them ever shows up in `git status`, check the
 
 | Path                     | Source                                                                       |
 |--------------------------|------------------------------------------------------------------------------|
-| `_build/`                | Output of `scripts/docs/build-manual.sh`                                     |
+| `_build/`                | Output of `tools/docs/build-manual.sh`                                     |
 | `.pnpm-store/`           | pnpm's content-addressable store (should never appear here)                  |
 | `.claude/`               | Claude Code per-machine state (`settings.local.json` permission allowlists)  |
 | `node_modules/`          | Node dependency trees from repo-local scripts                                |
@@ -229,7 +229,7 @@ A quick decision tree for common cases:
 
 - **New app config that lives under `~/.config/<app>/`** → `dot_config/<app>/` (see `docs/NAMING_CONVENTIONS.md` → "Adding New Modules").
 - **New user-facing CLI script** → `dot_local/bin/executable_<name>`.
-- **New `dot` subcommand** → implementation in `scripts/dot/commands/<name>.sh`, routing in `dot_local/bin/executable_dot`.
+- **New `dot` subcommand** → implementation in `scripts/dot/commands/<name>.sh`, routing in `bin/dot`.
 - **New repo-only automation** (CI helper, maintenance task, release step) → `scripts/<domain>/<name>.sh`.
 - **New test** → `tests/unit/<domain>/test_<feature>.sh` (follow `test_{domain}_{feature}.sh` naming).
 - **New doc** → pick the narrowest of `docs/architecture/`, `docs/reference/`, `docs/guides/`, `docs/operations/`, `docs/security/`.

package/docs/archive/MILESTONE_v0.2.493.md

@@ -16,7 +16,7 @@ This milestone keeps scope intentionally small and operationally focused.
 
 - [x] Add `dot verify` command routing in diagnostics module.
   - `scripts/dot/commands/diagnostics.sh`
-  - `dot_local/bin/executable_dot`
+  - `bin/dot`
 - [x] Add verification runner script.
   - `scripts/diagnostics/verify.sh`
   - Runs:

package/docs/index.md

@@ -7,7 +7,7 @@ render_with_liquid: false
 Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL.
 
 [![Build](https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=github)](https://github.com/sebastienrousseau/dotfiles/actions)
-[![Version](https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.501)
+[![Version](https://img.shields.io/badge/Version-v0.2.503-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.503)
 [![Downloads](https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases)
 
 This site is published from the `docs/` directory on `master` and tracks the current workstation baseline, operational guidance, and security material for the repository.
@@ -38,6 +38,6 @@ This site is published from the `docs/` directory on `master` and tracks the cur
 
 ## Current Release
 
-- Current tagged release: [`v0.2.501`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.501)
+- Current tagged release: [`v0.2.503`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.503)
 - Latest release feed: [GitHub releases](https://github.com/sebastienrousseau/dotfiles/releases/latest)
 - Source repository: [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles)

package/docs/interop/POWERSHELL.md

@@ -13,7 +13,7 @@ and what specifically is verified. Closes the docs slice of
 
 | File | Role |
 |---|---|
-| [`dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl`](../../dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl) | The dotfiles PowerShell profile. Deployed to `$PROFILE` (resolves to `~/.config/powershell/Microsoft.PowerShell_profile.ps1` on Linux/macOS; `Documents\PowerShell\Microsoft.PowerShell_profile.ps1` on Windows). |
+| [`dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl`](../../defaults/dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl) | The dotfiles PowerShell profile. Deployed to `$PROFILE` (resolves to `~/.config/powershell/Microsoft.PowerShell_profile.ps1` on Linux/macOS; `Documents\PowerShell\Microsoft.PowerShell_profile.ps1` on Windows). |
 | [`scripts/qa/powershell-contract.ps1`](../../scripts/qa/powershell-contract.ps1) | The runtime contract. Renders the template, dot-sources it, asserts required function shims exist, runs PSScriptAnalyzer. |
 | [`tests/unit/install/test_powershell_profile_syntax.sh`](../../tests/unit/install/test_powershell_profile_syntax.sh) | Static-syntax test runnable on Linux/macOS via `pwsh` when present; falls back to brace-balance + textual invariants when not. |
 

package/docs/manual/00-introduction.md

@@ -4,7 +4,7 @@ render_with_liquid: false
 
 # Introduction
 
-This manual describes `.dotfiles` v0.2.501 — a trusted agent workstation baseline for macOS, Linux, and WSL.
+This manual describes `.dotfiles` v0.2.503 — a trusted agent workstation baseline for macOS, Linux, and WSL.
 
 The repository is more than a personal dotfiles collection. It ships as workstation infrastructure: signed, attested, multi-platform, AI-aware, and self-healing. Chezmoi handles templating and platform differences. The `dot` CLI sits on top and coordinates lifecycle operations.
 

package/docs/manual/01-concepts/02-trust-model.md

@@ -32,7 +32,7 @@ The trust anchor is the signer's public key published in `~/.ssh/allowed_signers
 
 ### Verified Chezmoi Installer
 
-The `install.sh` script prefers `scripts/ci/install-chezmoi-verified.sh`, which:
+The `install.sh` script prefers `tools/ci/install-chezmoi-verified.sh`, which:
 
 1. Downloads chezmoi from the upstream release URL
 2. Verifies the SHA256 checksum against a hardcoded, version-pinned value

package/docs/manual/03-reference/01-dot-cli.md

@@ -151,19 +151,6 @@ dot attest [--output|-o <file>] [--sign|-s]
 
 Default output: `~/.local/state/dotfiles/attestation/YYYY-MM-DD-HHMMSS.json`. With `--sign`, the JSON is signed with the user's SSH ED25519 key.
 
-### `dot verify`
-
-Verify integrity of the installation.
-
-```
-dot verify [--security|-s] [--attestation <path>]
-```
-
-| Flag | Effect |
-|:---|:---|
-| `--security`, `-s` | Run gitleaks + signature checks + policy hash |
-| `--attestation <path>` | Verify an external attestation file |
-
 ### `dot lint`
 
 Lint shell scripts (shellcheck, shfmt).
@@ -174,24 +161,6 @@ dot lint [--path <glob>] [--strict]
 
 ## Performance
 
-### `dot benchmark`
-
-Measure shell startup time.
-
-```
-dot benchmark [--detailed|-d] [--profile|-p] [--compare|-c] [--waterfall|-w] [--runs|-r <n>]
-```
-
-| Flag | Effect |
-|:---|:---|
-| `--detailed`, `-d` | Per-module timing breakdown |
-| `--profile`, `-p` | Profile with `$SHELL -ixc ""` |
-| `--compare`, `-c` | Compare against baseline |
-| `--waterfall`, `-w` | Waterfall visualization |
-| `--runs`, `-r <n>` | Number of hyperfine runs (default 10) |
-
-Exit codes: 0 (<500ms target), 1 (regression).
-
 ### `dot perf`
 
 Quick performance snapshot.
@@ -200,17 +169,9 @@ Quick performance snapshot.
 dot perf [--json|-j] [--profile|-p] [--runs|-r <n>] [--target|-t <ms>]
 ```
 
-### `dot prewarm`
-
-Regenerate shell init caches for fast startup.
-
 ### `dot cache-refresh`
 
-Rebuild generated shell state (cold-start alternative to prewarm).
-
-### `dot clean-cache`
-
-Clear generated shell initialization caches. Next shell startup will be slow; use `dot prewarm` afterward.
+Regenerate shell caches for ultra-fast startup.
 
 ### `dot score`
 
@@ -322,11 +283,72 @@ Multi-node status, drift, and namespace.
 dot fleet              # show all known hosts
 dot fleet attest       # collect signed attestations
 dot fleet diff         # compare rendered config across hosts
-dot fleet sync         # run `dot update` on every host
+dot fleet sync         # run `dot upgrade` on every host
+dot fleet apply        # SSH out to every host in fleet.toml and run 'dot sync'
 ```
 
 Fleet hosts are configured in `~/.config/dotfiles/fleet.toml`.
 
+### `dot fleet apply`
+
+Push dotfiles state to every host registered in `~/.config/dotfiles/fleet.toml`.
+
+```
+dot fleet apply [--host <name>] [--cmd <shell>] [--dry-run] [--jobs <n>]
+```
+
+| Flag | Effect |
+|:---|:---|
+| `--host <name>` | Apply to a single host only (matches the `[hosts.<name>]` stanza key). |
+| `--cmd <shell>` | Run a custom command on every host instead of the default `dot sync && dot doctor --quiet`. **Warning:** this is arbitrary shell on remote hosts; the value is your trust boundary. |
+| `--dry-run`, `-n` | Print the resolved hosts + planned command without opening SSH. |
+| `--jobs <n>` | Parallelism (default 4). |
+
+Hostnames in `fleet.toml` are validated against `[A-Za-z0-9._@:+/-]+` before fan-out; entries containing other characters abort the apply. First-time SSH connections use `StrictHostKeyChecking=accept-new` (TOFU); pre-populate `~/.ssh/known_hosts` if your threat model requires no TOFU window.
+
+Example `fleet.toml`:
+
+```toml
+[hosts.laptop]
+ssh     = "user@laptop.local"
+profile = "workstation"
+```
+
+## Agents
+
+### `dot agents`
+
+Multi-harness AI agent configuration manager. `CLAUDE.md` is canonical; `dot agents render` keeps `AGENTS.md` (the cross-harness standard read by Codex / Copilot / Cursor / Windsurf / Amp / Devin) plus `.cursor/rules/dotfiles.mdc` and `.codex/config.toml` in sync.
+
+```
+dot agents list       # show which harnesses are recognised + their target paths
+dot agents check      # exit 0 if AGENTS.md tracks CLAUDE.md; 1 if drifted
+dot agents render     # regenerate AGENTS.md + 10 harness-specific files
+```
+
+Harnesses covered: `AGENTS.md` (canonical cross-harness), Cursor (`.cursor/rules/dotfiles.mdc`), Codex (`.codex/config.toml`), Windsurf (`.windsurf/rules.md`), Zed (`.zed/agent-config.toml`), Roo (`.roo/rules.md`), Cline (`.clinerules`), Aider (`.aider.conf.yml`), Continue (`.continuerc.json`), Jules (`.jules/system.md`), Gemini (`.gemini/GEMINI.md`).
+
+Edit `CLAUDE.md` first, then run `dot agents render`; do not hand-edit `AGENTS.md` or any of the per-harness files. The check subcommand is suitable for pre-commit hooks.
+
+## Registry
+
+### `dot registry`
+
+JSON-indexed module registry. Discover and install reusable dotfile modules from a registry hosted via GitHub Pages (or any HTTPS URL via `set-url`).
+
+```
+dot registry list                 # list modules in the configured registry
+dot registry search <query>       # filter modules by keyword
+dot registry info <name>          # full metadata for one module
+dot registry install <name>       # apply a module (scaffold today)
+dot registry url                  # show the active registry URL
+dot registry set-url <url>        # override the registry URL (HTTPS-only)
+```
+
+Default registry: `https://sebastienrousseau.github.io/dotfiles/registry.json`. Cache lives at `${XDG_CACHE_HOME:-~/.cache}/dotfiles/registry/index.json` with a 6h TTL. One-off override: `DOTFILES_REGISTRY_URL=<url> dot registry list`.
+
+The JSON contract + module-contribution flow live in [`docs/operations/REGISTRY.md`](../../operations/REGISTRY.md).
+
 ## Reference
 
 ### `dot version`
@@ -361,10 +383,6 @@ dot add --encrypt ~/.somefile          # encrypted with Age
 dot add --template ~/.somefile         # templatize
 ```
 
-### `dot remove <path>`
-
-Safely remove a managed file (removes from source and unmanages).
-
 ### `dot cd`
 
 Print the source directory path. Useful for `cd $(dot cd)`.

package/docs/manual/03-reference/02-config-files.md

@@ -33,7 +33,7 @@ Every config file read or written by `.dotfiles`, with its schema and purpose.
 
 ```toml
 # Version — bumped by version-sync.sh at release time
-dotfiles_version = "0.2.501"
+dotfiles_version = "0.2.503"
 
 # Machine preset — override in ~/.config/chezmoi/chezmoi.toml per host
 machine = ""
@@ -219,7 +219,7 @@ Agent Card (MCP A2A spec):
 ```json
 {
   "name": "dotfiles-agent",
-  "version": "0.2.501",
+  "version": "0.2.503",
   "capabilities": ["chezmoi.apply", "theme.switch", "secrets.decrypt"],
   "policy_hash": "0x7f2a..."
 }

package/docs/manual/03-reference/05-feature-flags.md

@@ -11,10 +11,19 @@ Feature flags toggle optional subsystems. Set in `.chezmoidata.toml`, override p
 
 ```toml
 [features]
-dms = false                # Dank Material Shell (Niri desktop)
+alias_wrapper = false      # Wrap selected aliases with safer defaults
+dms           = true       # Dank Material Shell (Niri desktop)
+zellij        = false      # Zellij terminal multiplexer config
 linux_desktop = false      # Linux-specific desktop configs
-niri = false               # Niri window manager
-waybar = false             # Waybar status bar
+niri          = false      # Niri window manager
+waybar        = false      # Waybar status bar
+fuzzel        = false      # Fuzzel application launcher (Wayland)
+mako          = false      # Mako notification daemon (Wayland)
+foot          = false      # Foot terminal emulator (Wayland)
+kanshi        = false      # Kanshi monitor profile manager (Wayland)
+touch         = false      # Touchscreen-friendly tweaks (Surface, etc.)
+t2            = false      # Apple T2 hardware-specific tweaks
+surface       = false      # Microsoft Surface hardware-specific tweaks
 ```
 
 ## Per-Preset Overrides (`.chezmoidata/hardware.toml`)
@@ -69,6 +78,56 @@ When `true`:
 
 Requires: Waybar installed.
 
+### `alias_wrapper` — Safer Alias Defaults
+
+When `true`, opt-in wrappers replace selected aliases with confirmation-prompt
+variants (e.g., `rm -i`, `mv -i`). Default `false` for power-user ergonomics.
+
+### `zellij` — Zellij Terminal Multiplexer
+
+When `true`:
+
+- Generates `~/.config/zellij/config.kdl` from the active theme
+- Wires the `dot mux` alias to launch a profile-aware session
+
+Requires: Zellij installed.
+
+### `fuzzel` — Fuzzel Application Launcher (Wayland)
+
+When `true`, generates `~/.config/fuzzel/fuzzel.ini` using the active theme.
+Requires: Fuzzel installed (Wayland-only). No effect on macOS.
+
+### `mako` — Mako Notification Daemon (Wayland)
+
+When `true`, generates `~/.config/mako/config` with theme-derived colors.
+Requires: Mako installed (Wayland-only). No effect on macOS.
+
+### `foot` — Foot Terminal Emulator (Wayland)
+
+When `true`, generates `~/.config/foot/foot.ini` from `themes.toml`.
+Requires: Foot installed (Wayland-only). No effect on macOS.
+
+### `kanshi` — Kanshi Monitor Profile Manager (Wayland)
+
+When `true`, generates `~/.config/kanshi/config` with per-host monitor layouts.
+Requires: Kanshi installed (Wayland-only). No effect on macOS.
+
+### `touch` — Touchscreen-Friendly Tweaks
+
+When `true`, enables larger UI scaling and touch-friendly input mappings.
+Typically combined with `surface` for Microsoft Surface devices.
+
+### `t2` — Apple T2 Hardware Tweaks
+
+When `true`, enables `t2linux` kernel-module hints, audio routing fixes, and
+Touch-Bar utilities for Intel Macs with the T2 chip on Linux. Set by the
+`macbook-t2` hardware preset in `.chezmoidata/hardware.toml`.
+
+### `surface` — Microsoft Surface Hardware Tweaks
+
+When `true`, enables `linux-surface` kernel parameters, touchpad gestures, and
+pen-input mappings. Set by the `surface-pro` hardware preset.
+
 ## Using a Flag in a Template
 
 ```go

package/docs/manual/_toc.yml

@@ -2,7 +2,7 @@
 # Determines concatenation order for single-page HTML/PDF/EPUB
 title: "The .dotfiles Manual"
 subtitle: "A Trusted Agent Workstation for macOS, Linux, and WSL"
-version: "0.2.501"
+version: "0.2.503"
 
 sections:
   - file: 00-introduction.md

package/docs/manual/command-index.md

@@ -4,59 +4,76 @@ render_with_liquid: false
 
 # Command Index
 
-Alphabetical list of `dot` subcommands referenced in the manual.
+Generated from `dot help all`. To refresh after adding or renaming
+a subcommand, run `tools/docs/generate-command-index.sh`. The CI
+job `lint/command-index` fails when this file is stale.
 
-- `dot agent`
-- `dot ai`
-- `dot apply --dry-run`
-- `dot apply`
-- `dot attest`
-- `dot benchmark --detailed`
-- `dot benchmark`
-- `dot bundle`
-- `dot cache-refresh`
-- `dot cd`
-- `dot chaos`
-- `dot clean-cache`
-- `dot commit`
-- `dot diff`
-- `dot doctor --json`
-- `dot doctor`
-- `dot drift`
-- `dot edit`
-- `dot env`
-- `dot fleet attest`
-- `dot fleet diff`
-- `dot fleet sync`
-- `dot fleet`
-- `dot heal`
-- `dot help`
-- `dot learn`
-- `dot lint`
-- `dot load-bench`
-- `dot manual text`
-- `dot manual`
-- `dot mcp --strict`
-- `dot mcp`
-- `dot metrics`
-- `dot mode`
-- `dot packages`
-- `dot perf`
-- `dot prewarm`
-- `dot profile`
-- `dot rollback`
-- `dot score`
-- `dot secrets rotate`
-- `dot secrets`
-- `dot status`
-- `dot sync`
-- `dot theme list`
-- `dot theme rebuild`
-- `dot theme toggle`
-- `dot theme`
-- `dot tune`
-- `dot update`
-- `dot upgrade`
-- `dot verify --security`
-- `dot verify`
-- `dot version`
+| Command | Summary |
+|---------|---------|
+| `dot add` | Add a file to chezmoi source |
+| `dot agent` | Profile-aware execution, agent card, a2a-card, session log, checkpoints, and conformance |
+| `dot ai` | AI CLI status, delegate, and cost report |
+| `dot ai-query` | Context-aware RAG query over your dotfiles |
+| `dot ai-setup` | Interactive setup for all AI CLI tools |
+| `dot aider` | Aider with context patterns |
+| `dot attest` | Export workstation attestation evidence (--json |
+| `dot backup` | Create a compressed backup of your home |
+| `dot bundle` | Create offline archive of dotfiles environment |
+| `dot cache-refresh` | Regenerate shell caches for ultra-fast startup |
+| `dot cd` | Print source directory path (use: cd $(dot cd)) |
+| `dot chaos` | Simulate config corruption to test self-healing |
+| `dot cl` | Claude CLI with context patterns |
+| `dot commit` | AI-powered conventional commit |
+| `dot copilot` | GitHub Copilot CLI with context patterns |
+| `dot diff` | Show chezmoi diff with exclusions |
+| `dot dns-doh` | Enable DNS-over-HTTPS [macOS,Linux] |
+| `dot docs` | Show repo README |
+| `dot doctor` | Deep audit: tools, paths, portability, AI analysis (--ai |
+| `dot edit` | Open chezmoi source in $EDITOR |
+| `dot encrypt-check` | Check disk encryption status |
+| `dot env` | Tool versions (mise) |
+| `dot firewall` | Apply firewall hardening [macOS,Linux] |
+| `dot fleet` | Show fleet node status, drift, and namespace (--json for machine output) |
+| `dot fleet` | drift Check for configuration drift across managed files |
+| `dot fleet` | events Show recent fleet events from local event log |
+| `dot fleet` | namespace Show or set the active namespace for multi-tenant isolation |
+| `dot fonts` | Install Nerd Fonts (JetBrainsMono by default) |
+| `dot gemini` | Gemini CLI with context patterns |
+| `dot help` | Show this help message |
+| `dot history` | Shell history analysis |
+| `dot keys` | Keybindings (sign-check: verify git signing) |
+| `dot kiro` | Kiro CLI with context patterns |
+| `dot learn` | Start the interactive tour of your new tools |
+| `dot lint` | Lint shell scripts (--fix |
+| `dot load-bench` | Measure time to heavy-layer readiness |
+| `dot lock-screen` | Enforce lock screen idle settings [Linux] |
+| `dot mcp` | Inspect MCP policy, supply chain, and registry |
+| `dot metrics` | Show recent observability metrics (JSONL) |
+| `dot mode` | Set or inspect agent operating profiles (ask/plan/apply/audit) |
+| `dot new` | Create a new project from a template |
+| `dot ollama` | Ollama with context patterns |
+| `dot opencode` | OpenCode with context patterns |
+| `dot packages` | List installed packages and package managers |
+| `dot perf` | Show performance mode and quick timing |
+| `dot profile` | Show/switch configuration profile |
+| `dot rollback` | Rollback dotfiles to a previous state |
+| `dot sandbox` | Launch a safe sandbox preview (Docker/Podman) |
+| `dot score` | System health and security scorecard |
+| `dot search` | Find commands by keyword |
+| `dot secrets` | Edit encrypted secrets (age) |
+| `dot secrets-create` | Create an encrypted secrets file |
+| `dot secrets-init` | Initialize age key for secrets |
+| `dot sgpt` | Shell-GPT with context patterns |
+| `dot snapshot` | Capture baseline system snapshot |
+| `dot ssh-cert` | Manage short-lived SSH certificates |
+| `dot ssh-key` | Encrypt an SSH key locally with age |
+| `dot status` | Show configuration drift (chezmoi status) |
+| `dot sync` | Apply dotfiles (alias for apply; --pull to fetch, --check to preview) |
+| `dot telemetry` | Disable OS telemetry [macOS,Linux] |
+| `dot theme` | Switch terminal theme (dark/light) |
+| `dot tools` | Show or install nix packages |
+| `dot tune` | Apply OS tuning (opt-in) [macOS,Linux] |
+| `dot upgrade` | Update system toolchains, plugins, and dotfiles |
+| `dot usb-safety` | Disable automount for removable media [Linux] |
+| `dot version` | Show version information. |
+| `dot wallpaper` | Apply a wallpaper from your library [macOS,Linux] |