@sebastienrousseau/dotfiles 0.2.502 → 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.502-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.502)
+[![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.502`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.502)
+- 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.502 — 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/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.502"
+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.502",
+  "version": "0.2.503",
   "capabilities": ["chezmoi.apply", "theme.switch", "secrets.decrypt"],
   "policy_hash": "0x7f2a..."
 }

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.502"
+version: "0.2.503"
 
 sections:
   - file: 00-introduction.md

package/docs/manual/command-index.md

@@ -4,63 +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 agents check`
-- `dot agents list`
-- `dot agents render`
-- `dot agents`
-- `dot ai`
-- `dot apply --dry-run`
-- `dot apply`
-- `dot attest`
-- `dot bundle`
-- `dot cache-refresh`
-- `dot cd`
-- `dot chaos`
-- `dot commit`
-- `dot diff`
-- `dot doctor --json`
-- `dot doctor`
-- `dot edit`
-- `dot env`
-- `dot fleet apply --dry-run`
-- `dot fleet apply`
-- `dot fleet attest`
-- `dot fleet diff`
-- `dot fleet sync`
-- `dot fleet`
-- `dot heal`
-- `dot help`
-- `dot init --dry-run`
-- `dot init`
-- `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 profile`
-- `dot registry info`
-- `dot registry list`
-- `dot registry search`
-- `dot registry`
-- `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 upgrade`
-- `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] |

package/docs/operations/CI_COMPOSITES.md

@@ -17,7 +17,7 @@ to bump pins. Managed under
 Path: `.github/actions/setup-chezmoi/action.yml`
 
 Installs the pinned `chezmoi` binary (using the SHA256-verified
-installer at `scripts/ci/install-chezmoi-verified.sh` when the repo is
+installer at `tools/ci/install-chezmoi-verified.sh` when the repo is
 checked out, falling back to `get.chezmoi.io` otherwise), caches the
 result, and appends the bin-dir to `$GITHUB_PATH`.
 
@@ -151,6 +151,6 @@ bump on a weekly schedule.
 
 - `.github/actions/setup-chezmoi/action.yml`
 - `.github/actions/setup-mise/action.yml`
-- `scripts/ci/install-chezmoi-verified.sh` — the SHA-pinned installer
+- `tools/ci/install-chezmoi-verified.sh` — the SHA-pinned installer
   the chezmoi composite prefers when available.
 - Issue [#879](https://github.com/sebastienrousseau/dotfiles/issues/879).

package/docs/operations/COMPLETIONS.md

@@ -116,8 +116,8 @@ their lifecycle.
 
 ## References
 
-- [`dot_config/zsh/rc.d/30-options.zsh.tmpl`](../../dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
-- [`run_onchange_after_zcompile-completions.sh.tmpl`](../../run_onchange_after_zcompile-completions.sh.tmpl) — the apply-time precompile hook.
+- [`dot_config/zsh/rc.d/30-options.zsh.tmpl`](../../defaults/dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
+- [`run_onchange_after_zcompile-completions.sh.tmpl`](../../defaults/run_onchange_after_zcompile-completions.sh.tmpl) — the apply-time precompile hook.
 - [`zsh` completion docs](https://zsh.sourceforge.io/Doc/Release/Completion-System.html).
 - ADR-002 (Shell Performance Optimization).
 - Issue [#864](https://github.com/sebastienrousseau/dotfiles/issues/864).

package/docs/operations/COVERAGE.md

@@ -44,7 +44,7 @@ matches and emits standard `lcov.info` that Codecov ingests natively.
 | Surface | What runs |
 |---|---|
 | **PR + push to master** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `0`, ratcheted up each slice). |
-| **Local dev** | `bash scripts/ci/run-coverage.sh` — works on Linux + macOS (xtrace is a bash primitive, no platform tools needed). |
+| **Local dev** | `bash tools/ci/run-coverage.sh` — works on Linux + macOS (xtrace is a bash primitive, no platform tools needed). |
 | **macOS dev** | Supported. xtrace-based instrumentation runs on macOS bash 3.2+ and Homebrew bash 5.x. |
 
 ## The current floor
@@ -87,7 +87,7 @@ not aspirational:
   aggregator level.
 - **Animated demo helpers** — same as interactive UIs.
 
-`scripts/ci/run-coverage.sh` has a `SKIP_PATHS` set that removes
+`tools/ci/run-coverage.sh` has a `SKIP_PATHS` set that removes
 genuinely-untestable scripts from the lcov denominator. Within the
 files that remain, individual mutation-only function bodies are
 fenced with `# LCOV_EXCL_START` / `# LCOV_EXCL_STOP` and a one-line
@@ -101,7 +101,7 @@ The honest floor is the achievable one.
 ## Running locally
 
 ```bash
-bash scripts/ci/run-coverage.sh   # Linux or macOS
+bash tools/ci/run-coverage.sh   # Linux or macOS
 
 # Output:
 #   coverage/traces/<file>.trace  — per-test xtrace logs
@@ -159,7 +159,7 @@ threshold to get two independent signals.
 
 ## Excluded paths
 
-`scripts/ci/run-coverage.sh` excludes:
+`tools/ci/run-coverage.sh` excludes:
 
 - `tests/**` itself (don't measure coverage of the tests).
 - `.git/`, `node_modules/`.
@@ -176,7 +176,7 @@ Adjust via the env vars at the top of `run-coverage.sh`.
 ## References
 
 - [Bash xtrace + PS4 + BASH_ENV docs](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html).
-- [`scripts/ci/run-coverage.sh`](../../scripts/ci/run-coverage.sh).
+- [`tools/ci/run-coverage.sh`](../../tools/ci/run-coverage.sh).
 - [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml).
 - Issue [#856](https://github.com/sebastienrousseau/dotfiles/issues/856) (closed) /
   [#883](https://github.com/sebastienrousseau/dotfiles/issues/883) (coverage roadmap).

package/docs/operations/HARD_AUDIT_2026.md

@@ -24,12 +24,12 @@ The goal stated by the maintainer: become the de facto workstation provisioning
 
 | # | File:line | Finding | Recommended fix |
 |---|---|---|---|
-| H1 | `dot_local/bin/executable_dot:589` | `source "$_user_cmd" "$@"` — a user-provided custom command calling `exit` kills the whole CLI. | Replace with `bash "$_user_cmd" "$@"` or `( source "$_user_cmd" "$@" )` subshell. |
+| H1 | `bin/dot:589` | `source "$_user_cmd" "$@"` — a user-provided custom command calling `exit` kills the whole CLI. | Replace with `bash "$_user_cmd" "$@"` or `( source "$_user_cmd" "$@" )` subshell. |
 | H2 | `scripts/dot/commands/agent.sh:28,51,83-92` | `_agent_default_profile()` calls `jq` before `_agent_assert_dependencies()` runs in `cmd_mode()`. On a host without jq, error message is cryptic. | Move dependency assertion to top of every entry-point. |
 | H3 | `scripts/dot/commands/fleet.sh:294-297` | GNU vs BSD `sed -i` branch isn't atomic; concurrent `dot fleet namespace set` calls can corrupt `.chezmoidata.toml`. | Use `mktemp` + `mv` (atomic) and wrap with `flock`. |
 | H4 | `dot_config/zsh/dot_zshrc.tmpl:220-221` | `_cached_eval` writes cache with `mv "$cache.tmp.$$" "$cache"` — PID collision possible between two shells. Cold-start affected. | Use `mktemp` instead of `$$`. |
 | H5 | `scripts/dot/commands/meta.sh:64-67` | `rm -rf "$cache_dir/zsh"/*-init.zsh` — if the glob doesn't match, expands to the literal pattern and the `-rf` removes the wrong path. | Guard with `[[ -d ... ]]` or use `find ... -type f -delete`. |
-| H6 | `install.sh:177-198` | Chezmoi installer downloaded over `https://get.chezmoi.io` with size/shebang validation but no cryptographic signature check. | **Fixed in `eaca…` (TBD commit) by removing the unverified fallback.** The verified installer at `scripts/ci/install-chezmoi-verified.sh` (SHA256-checked against GitHub Releases) is now the only path; if it fails we refuse to bootstrap rather than silently degrading. |
+| H6 | `install.sh:177-198` | Chezmoi installer downloaded over `https://get.chezmoi.io` with size/shebang validation but no cryptographic signature check. | **Fixed in `eaca…` (TBD commit) by removing the unverified fallback.** The verified installer at `tools/ci/install-chezmoi-verified.sh` (SHA256-checked against GitHub Releases) is now the only path; if it fails we refuse to bootstrap rather than silently degrading. |
 | H7 | `install/lib/package_managers.sh:71-92` | Homebrew installer runs from `brew.sh` with a warning but no SHA256 verification. | **False positive on review** — `install_homebrew()` already requires `HOMEBREW_INSTALLER_SHA256` and aborts on checksum mismatch (`install/lib/package_managers.sh:84-92`). Audit cited the security-note string at line 56, not the verification block. |
 | H8 | `install/lib/installers.sh:40-54` | Binary downloads SHA256-verify, but the checksum URL is not pinned. DNS attacker can redirect both binary and checksum together. | **Overstated on review** — `github_asset_url` already obtains both binary and checksum URLs from `api.github.com` via a single authenticated call; both transit HTTPS with cert validation. A DNS attacker would need a valid cert for `api.github.com`. Real defence in depth would add `cosign verify` for releases that publish a Sigstore bundle; tracking as a future enhancement. |
 | H9 | `scripts/dot/lib/platform.sh:42-65` | `dot_path_to_unix/native()` silently returns the Windows path if `wslpath` is missing — caller cannot tell success from failure. | Return non-zero when `wslpath` is required but absent; document the contract. |
@@ -39,12 +39,12 @@ The goal stated by the maintainer: become the de facto workstation provisioning
 | # | File:line | Finding | Recommended fix |
 |---|---|---|---|
 | M1 | `scripts/dot/commands/core.sh:81` | `chezmoi status \|\| true` loses error context — can't distinguish "tree is clean" from "chezmoi crashed". | Capture into a variable and inspect the exit code. |
-| M2 | `dot_local/bin/executable_dot:542` | `route="$(_dot_command_route "$COMMAND" \|\| true)"` is defensible (falls through to the user-command path that emits a proper error), but reads as a bug. | Add comment explaining intent or refactor to explicit `if`. |
+| M2 | `bin/dot:542` | `route="$(_dot_command_route "$COMMAND" \|\| true)"` is defensible (falls through to the user-command path that emits a proper error), but reads as a bug. | Add comment explaining intent or refactor to explicit `if`. |
 | M3 | `scripts/dot/lib/ui.sh:335,340` | `mktemp` output race in `ui_run_cmd()` between subshell write and parent read; under load the `cat` can hit an empty file. | Switch to `read rc < "$rc_file"` or `[[ -s "$rc_file" ]]` guard. |
 | M4 | `scripts/dot/commands/agent.sh:221-224,338-341,385-388` | `set +e / "$@" / set -e` blocks log failure but propagate the original exit code; callers can't tell intentional vs accidental. | Document the contract or restructure to `if !`. |
 | M5 | `scripts/security/lock-configs.sh:27-33` | `sudo chattr +i` silently fails when sudo is unavailable in automation. | Fail explicitly when sudo is required. |
 | M6 | `dot_config/zsh/dot_zshrc.tmpl:147-159` | `_cached_eval` mtime check doesn't follow symlinks — a `mise` upgrade that only flips a symlink target won't bust the cache. | Resolve via `readlink -f` and track the chain. |
-| M7 | `scripts/ci/install-chezmoi-verified.sh:25-32` | Only x86_64 + arm64 are supported. ppc64le, s390x, riscv64 fail silently. | Document supported architectures and emit a clear error otherwise. |
+| M7 | `tools/ci/install-chezmoi-verified.sh:25-32` | Only x86_64 + arm64 are supported. ppc64le, s390x, riscv64 fail silently. | Document supported architectures and emit a clear error otherwise. |
 
 ### 1.4 Low (track in backlog)
 
@@ -107,7 +107,7 @@ Distribution targets (pick 3, not 5): Homebrew tap first, AUR second, Scoop thir
 
 Community moves:
 
-- **Show HN:** lead with the wallpaper-driven themes (v0.2.502). Screenshot-driven hook nobody else has.
+- **Show HN:** lead with the wallpaper-driven themes (v0.2.503). Screenshot-driven hook nobody else has.
 - **Blog post series (3 posts):** "Why I stopped using chezmoi directly", "Bootstrapping 15 machines from one git repo in <90 seconds", "Secrets in dotfiles: a 2026 threat model".
 - **CFPs:** FOSDEM 2027 (dev tools devroom), All Things Open 2026, SCaLE LA. Skip KubeCon.
 - **Sponsor 2–3 newsletters at $500–1500/issue:** Console.dev, TLDR DevOps, Changelog News.
@@ -188,7 +188,7 @@ Plus reliability fixes:
 **This quarter (positioning):** ✅ shipped
 
 1. ✅ AGENTS.md generator — `dot agents render/check/list` syncs `CLAUDE.md` → `AGENTS.md` + Cursor + Codex stubs (commit TBD). Closes #1 competitive gap.
-2. ✅ Sub-100ms `dot` CLI cold-start gate — `scripts/ci/dot-cli-startup-bench.sh` + `.github/workflows/dot-cli-bench.yml`. Median **47ms** locally, budget 250ms. Closes #3 competitive gap.
+2. ✅ Sub-100ms `dot` CLI cold-start gate — `tools/ci/dot-cli-startup-bench.sh` + `.github/workflows/dot-cli-bench.yml`. Median **47ms** locally, budget 250ms. Closes #3 competitive gap.
 3. ⏳ Add `windows-latest` runner to the test matrix (deferred; needs PS7 mock harness).
 4. ⏳ Pursue mise + 1Password + Codespaces integrations (months 6-12 of the roadmap).
 
@@ -230,8 +230,8 @@ The round-2 audit found regressions in the freshly-shipped strategic features. A
 | R6 | **Medium** | `scripts/dot/commands/agents.sh:render` | New files written with default umask permissions — could leak through a permissive global umask. | ✅ Explicit `chmod 0644` after each write. |
 | R7 | **Medium** | `scripts/dot/commands/registry.sh:128-135` | `set-url` accepted any scheme (http, ftp, file) without validation; the unsigned registry JSON is fetched from whatever URL was set. | ✅ Refuses non-HTTPS (with `file://` exemption documented for testing); atomic `mktemp + mv` write to config so concurrent `set-url` invocations cannot corrupt. |
 | R8 | **Medium** | `scripts/dot/commands/fleet.sh:467` | `mktemp -d` without a `-t` template could collide between concurrent `dot fleet apply` invocations from the same user. | ✅ Now uses `mktemp -d -t dotfiles-fleet.XXXXXX`. |
-| R9 | **Medium** | `scripts/ci/dot-cli-startup-bench.sh:87-89` | `env -i HOME=... PATH=...` preserved a PATH that could include user-installed `dot` shims; not a true cold-start measurement. Low-impact (the explicit `$DOT_BIN` argument is absolute), but the comment overclaimed. | Annotated only — the explicit `$DOT_BIN` already pins the binary; the PATH note in the comment is now precise. |
-| R10 | **Low** | `scripts/ci/dot-cli-startup-bench.sh:58-71` | `_now_ms` falls through to `python3 -c '…'` on macOS bash 3.2; Python startup can inflate measurements 80-150ms. | Documented; consider switching to `gdate +%s%N` when GNU coreutils is installed. |
+| R9 | **Medium** | `tools/ci/dot-cli-startup-bench.sh:87-89` | `env -i HOME=... PATH=...` preserved a PATH that could include user-installed `dot` shims; not a true cold-start measurement. Low-impact (the explicit `$DOT_BIN` argument is absolute), but the comment overclaimed. | Annotated only — the explicit `$DOT_BIN` already pins the binary; the PATH note in the comment is now precise. |
+| R10 | **Low** | `tools/ci/dot-cli-startup-bench.sh:58-71` | `_now_ms` falls through to `python3 -c '…'` on macOS bash 3.2; Python startup can inflate measurements 80-150ms. | Documented; consider switching to `gdate +%s%N` when GNU coreutils is installed. |
 | R11 | **Low** | `scripts/dot/commands/agents.sh` (list path) | `mkdir -p` for `.cursor/rules` and `.codex` ran even for read-only subcommands (`list`, `check`). Harmless, but pointless. | Deferred. |
 
 ### 6.3 New documentation gaps (all fixed in this commit)
@@ -346,7 +346,7 @@ Round-3 docs agent found 5 drifts, 2 of which were false positives on re-verific
 
 | ID | File | Drift | Status |
 |---|---|---|---|
-| D1+D2 | `dot_local/bin/executable_dot` | 5 orphan dispatch routes + 1 orphan help-table entry for commands removed in C3 of Round 1 (`verify`, `benchmark`, `prewarm`, `remove`, `clean-cache`) | ✅ Fixed |
+| D1+D2 | `bin/dot` | 5 orphan dispatch routes + 1 orphan help-table entry for commands removed in C3 of Round 1 (`verify`, `benchmark`, `prewarm`, `remove`, `clean-cache`) | ✅ Fixed |
 | D3 | `docs/reference/POWERSHELL_PARITY.md` | `dot agents` + `dot fleet apply` labelled "Full" on Windows without backing CI | ✅ Relabelled to "Stub (bash-bridged)" |
 | D4 | `docs/operations/ROADMAP_2026.md` + `HARD_AUDIT_2026.md` §6.9 | Microsoft Build 2026 date was wrong: "2026-05-19 in Seattle" vs actual **2026-06-02 to 2026-06-03 in San Francisco (Fort Mason)** | ✅ Corrected; Show-HN timing shifts ~2 weeks right |
 
@@ -501,10 +501,10 @@ R4 cross-platform agent produced a 10-table audit. Real findings, ranked by what
 
 | # | Severity | Gap | Concrete close |
 |---|---|---|---|
-| **P1** | High | No `Makefile install` target with `PREFIX`/`DESTDIR` support. Distro packagers have no canonical artefact to package. | Add `Makefile` with `install:` rule copying `dot_local/bin/executable_dot` to `$(PREFIX)/bin/dot`, man page to `$(PREFIX)/share/man/man1/`, completions to `$(PREFIX)/share/zsh/site-functions/_dot`. |
+| **P1** | High | No `Makefile install` target with `PREFIX`/`DESTDIR` support. Distro packagers have no canonical artefact to package. | Add `Makefile` with `install:` rule copying `bin/dot` to `$(PREFIX)/bin/dot`, man page to `$(PREFIX)/share/man/man1/`, completions to `$(PREFIX)/share/zsh/site-functions/_dot`. |
 | **P2** | High | No Homebrew tap, no AUR `PKGBUILD`, no Scoop manifest. | Publish `sebastienrousseau/homebrew-tap`, `aur/dotfiles-git/PKGBUILD`, `scoop-bucket/dot.json` from CI on tag — single tarball with SHA256 + Cosign-signed bundle. |
 | **P3** | High | `.devcontainer/Dockerfile:31` still installs unverified `get.chezmoi.io` (the same anti-pattern that gave us H6 in R1). | Replace with the pinned-SHA256 path used in `install-chezmoi-verified.sh`. |
-| **P4** | High | Repo intermingles framework (`scripts/`, `dot_local/bin/executable_dot`, `install/`) with maintainer's personal `dot_config/` (~80 tools). Packagers must ship both. | Document the framework/user split in a new `FRAMEWORK_STRUCTURE.md`; long-term, move framework code under `framework/` so `Makefile install` skips `dot_config/`. |
+| **P4** | High | Repo intermingles framework (`scripts/`, `bin/dot`, `install/`) with maintainer's personal `dot_config/` (~80 tools). Packagers must ship both. | Document the framework/user split in a new `FRAMEWORK_STRUCTURE.md`; long-term, move framework code under `framework/` so `Makefile install` skips `dot_config/`. |
 | **P5** | Medium | PowerShell-native parity is bash-bridged for `dot agents`, `dot fleet apply`, `dot theme`. Windows-native users can't run them without WSL. | Native PowerShell ports per `docs/reference/POWERSHELL_PARITY.md` Stub rows; estimated 1-week effort for full top-3. |
 
 P1+P2 together unlock the entire distribution surface and are ~5 person-days combined. They are the *cheapest path to "you can install us with `brew install`/`paru -S`/`scoop install`"* — which is the literal threshold for de-facto status on each platform.

package/docs/operations/MAINTENANCE.md

@@ -46,7 +46,7 @@ For every release update:
 6. Local apply has completed:
 
 ```bash
-CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./dot_local/bin/executable_dot apply
+CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./bin/dot apply
 ```
 
 ## Security Scan Guardrails
@@ -54,10 +54,10 @@ CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./dot_local/bin/executable_dot apply
 We prevent gitleaks historical-scan regressions with:
 
 - Shallow checkout (`fetch-depth: 1`, `fetch-tags: false`) in gitleaks jobs.
-- A workflow-dispatch guard script: `scripts/ci/guard-gitleaks-checkout.sh`.
+- A workflow-dispatch guard script: `tools/ci/guard-gitleaks-checkout.sh`.
 
 **Manual verification:**
 
 ```bash
-bash scripts/ci/guard-gitleaks-checkout.sh
+bash tools/ci/guard-gitleaks-checkout.sh
 ```