@sebastienrousseau/dotfiles 0.2.501 → 0.2.502

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 This file documents all notable changes to this project.
 
+## v0.2.502 — 2026-05-17
+
+### Added
+
+- **`dot agents`** — multi-harness AI agent context generator. `CLAUDE.md` is canonical; `dot agents render` mirrors it into `AGENTS.md` (the cross-harness standard read by Codex/Copilot/Cursor/Windsurf/Amp/Devin), `.cursor/rules/dotfiles.mdc`, and `.codex/config.toml`. `dot agents check` returns rc 0 when in sync (suitable for a pre-commit hook). Round-1 audit gap #1 closed.
+- **`dot init <github-user|owner/repo|url>`** — analogue to `chezmoi init`. Bootstrap a foreign dotfiles repo through this framework's harness with `--dry-run`, `--no-apply`, `--force` flags; an interactive trust prompt warns before SSH/HTTPS clones; refuses plain HTTP. Owner/repo and bare-user shorthands validated against `[A-Za-z0-9._-]+` to block shell-metacharacter injection.
+- **`dot fleet apply`** — SSH-based fleet reconciliation across hosts in `~/.config/dotfiles/fleet.toml`. Parallel fan-out (default 4-way) via background-job semaphore (no `xargs -d` so it works on macOS BSD xargs too). Hostnames validated against `[A-Za-z0-9._@:+/-]+` before fan-out. Flags: `--host`, `--cmd "<shell>"` (trust boundary — warning shown), `--dry-run`, `--jobs <n>`. Per-host stderr captured; collision-safe `mktemp -d -t dotfiles-fleet.XXXXXX` temp dir.
+- **`dot registry`** — JSON-indexed module marketplace scaffold. Subcommands `list / search / info / install / url / set-url`. Default registry at `https://sebastienrousseau.github.io/dotfiles/registry.json` (published from `docs/registry.json` via GitHub Pages). 6h cache TTL; `set-url` validates HTTPS-only (or `file://` for testing) and writes atomically via `mktemp + mv`. Full module contract + contribution flow in [`docs/operations/REGISTRY.md`](docs/operations/REGISTRY.md).
+- **Sub-100ms CLI cold-start gate** — `scripts/ci/dot-cli-startup-bench.sh` measures median dispatcher startup under a clean `env -i`. New workflow `.github/workflows/dot-cli-bench.yml` runs on every PR touching `dot_local/bin/executable_dot` or `scripts/dot/**`. Current observation: median 47ms locally; CI budget 250ms.
+- **`docs/operations/HARD_AUDIT_2026.md`** — consolidated audit (round 1 + round 2 addendum) of operational reliability, performance, documentation accuracy, cross-platform parity, security posture, competitor positioning, 2026 industry trends, and adoption playbook. Produced from twelve parallel research-agent runs.
+
+### Fixed
+
+- **`install.sh`** — removed the unverified `get.chezmoi.io` curl|sh fallback. The SHA256-verified installer is now the only path; if it fails, we refuse to bootstrap rather than silently degrading (H6).
+- **`scripts/dot/lib/platform.sh`** — `dot_path_to_unix` / `dot_path_to_native` return rc 2 with a stderr error when called in WSL without `wslpath`, instead of silently echoing a Windows-format path (H9).
+- **`dot_local/bin/executable_dot`** — user-provided custom commands now run in a subshell so a `exit` in the user script can't kill the whole CLI (H1).
+- **`scripts/dot/commands/fleet.sh`** — `dot fleet namespace set` writes via `mktemp + mv` instead of the brittle GNU/BSD `sed -i` dance (H3).
+- **`dot_config/zsh/dot_zshrc.tmpl`** — `_cached_eval` uses `mktemp` instead of `${cache}.tmp.$$`, eliminating the PID-collision race under shell recycling (H4).
+- **`scripts/dot/commands/meta.sh`** — cache-clear uses `find ... -type f -delete` with a directory guard instead of `rm -rf "$cache_dir/zsh"/*-init.zsh`, which expanded the literal pattern when no files matched (H5).
+- **`scripts/dot/commands/agent.sh`** — replaced three `set +e / "$@" / set -e` blocks with idiomatic `if !` so bash errexit suspension is implicit (M4).
+- **`scripts/dot/commands/core.sh`** — `cmd_status` captures chezmoi stderr and inspects the exit code, so a chezmoi crash is now distinguishable from a clean tree (M1).
+- **`scripts/dot/lib/ui.sh`** — `ui_run_cmd` guards the rc-file read with `[[ -s ]]` to avoid races between the subshell write and the parent read (M3).
+- **`scripts/security/lock-configs.sh`** — pre-checks `sudo` availability and TTY attachment before attempting `chattr +i`, instead of failing per-file in automation (M5).
+- **`scripts/ci/install-chezmoi-verified.sh`** — unsupported-architecture error now names the supported set (x86_64/amd64, arm64/aarch64) and points at the upstream release page (M7).
+- **`docs/manual/03-reference/01-dot-cli.md`** + **`docs/manual/command-index.md`** — removed six commands that were documented but never shipped (`dot verify`, `dot benchmark`, `dot prewarm`, `dot clean-cache`, `dot remove`, `dot update`). Added the new `agents`, `init`, `registry`, and `fleet apply` sections (C3).
+- **Version drift** — bumped `v0.2.501` → `v0.2.502` in five doc surfaces (`docs/manual/00-introduction.md`, `docs/manual/_toc.yml`, `docs/index.md`, `docs/manual/03-reference/02-config-files.md` × 2) (C2).
+- **`docs/manual/index.md`** — new landing page for `https://doc.dotfiles.io/manual/` (the Jekyll site was 404ing because `jekyll-readme-index` had no `README.md`/`index.md` to render in `docs/manual/`).
+
+### Security
+
+- **`scripts/dot/commands/agents.sh`** — render only writes when the resolved root contains `.chezmoidata.toml`, so a user running `dot agents render` from inside an unrelated git repo can't accidentally write agent configs there. Output files get explicit `chmod 0644`.
+- **`scripts/dot/commands/init.sh`** — owner/repo and bare-user shorthands are now validated against `[A-Za-z0-9._-]+` before URL construction.
+- **`scripts/dot/commands/fleet.sh`** — hostnames validated against `[A-Za-z0-9._@:+/-]+` before SSH fan-out; an attacker controlling `fleet.toml` can no longer inject shell metacharacters.
+- **`scripts/dot/commands/registry.sh`** — `set-url` refuses non-HTTPS schemes (with a `file://` exemption for local testing) and writes config atomically.
+
+### Documentation
+
+- **`docs/operations/REGISTRY.md`** — module contract, JSON schema, and contribution flow for the new registry.
+- **`docs/operations/COVERAGE.md`** — documents the achieved unit-test floor (~47%) plus the structural ceiling for xtrace-only instrumentation; closes #883.
+
+### Round 3 (HARD_AUDIT_2026.md Part 7)
+
+- **C1 closed — GPG disclosure key published.** Generated `security@sebastienrousseau.com` ed25519 + cv25519 keypair, fingerprint `55AFAD364FD9DB3819E61F0C8D688FAFA9144693`, expires 2029-05-15. Published to WKD at `sebastienrousseau.github.io/.well-known/openpgpkey/`. Repo carries the armored public key at `docs/security/security-pubkey.asc`.
+- **`.github/workflows/verify-gpg-wkd.yml`** (N1) — imports both the in-repo `.asc` and the live WKD-fetched key, compares fingerprints, fails loud on mismatch. Runs on push/PR + weekly schedule (Mondays 09:00 UTC). Wires the expiry monitor as the final step.
+- **`scripts/security/check-disclosure-key-expiry.sh`** (N2) — monitors the 2029-05-15 expiry; warns at 90 days remaining, fails CI at 30 days.
+- **`dot fleet apply --verify-hosts`** (N4) — closes the TOFU window per-invocation. Aborts the apply unless every host in `fleet.toml` is already present in `~/.ssh/known_hosts`.
+- **`install.sh` Charm GPG pin** (N5) — pins `CHARM_GPG_EXPECTED_FPR=C026D31B92F9BBE91D5DB75AB07AE17C9E0A6585`; aborts (removing the keyring file) on mismatch.
+- **`scripts/lib/secrets_provider.sh` exit codes** (N6) — `dot_secrets_get` now returns `2` (no provider), `3` (provider returned empty / key not found), or the provider's own rc; stderr names provider + key for diagnosis.
+- **R3 docs drifts** — purged 5 orphan dispatch routes + 1 orphan help-table entry in `dot_local/bin/executable_dot`; relabelled `dot agents` + `dot fleet apply` from "Full" to "Stub (bash-bridged)" on Windows-native in `docs/reference/POWERSHELL_PARITY.md`; corrected Microsoft Build 2026 date from "2026-05-19 in Seattle" to actual `2026-06-02 to 2026-06-03 in San Francisco (Fort Mason)` in `ROADMAP_2026.md`.
+- **R3 mocked-SSH test catches 2 real bugs.** `tests/unit/fleet/test_fleet_apply_mocked_ssh.sh` (5 tests with PATH-shim overriding `ssh`) caught: (a) subshell counter loss via pipe — fixed with `done < <(printf '%s\n' "$entries")`; (b) RETURN trap referencing `local tmpdir` failed under `set -u` — fixed with `printf -v _cleanup 'rm -rf %q' "$tmpdir"`.
+- **R3 strategic reversal.** Ship `dot env emit` BEFORE `--attest` (driven by AGNTCon Amsterdam 2026-09-17 deadline + EU CRA SBOM binding 2026-09-11). Full rationale in `HARD_AUDIT_2026.md` §7.4.
+
+### Round 4 (HARD_AUDIT_2026.md Part 8)
+
+- **Zero reliability findings** — second consecutive 0-finding round. 4 of 5 candidate perf claims were false positives (SSH-agent guard, completion-chain forks, FNM completion, carapace defer) caught by live verification.
+- **Documentation completeness fixes:**
+  - `README.md` — removed 4 stale references to ghost commands `dot verify` / `dot benchmark` / `dot prewarm` (none ship). Routed to `dot secrets verify`, `dot perf`, `dot health`.
+  - `docs/manual/03-reference/05-feature-flags.md` — documented the 9 previously-undocumented flags (`alias_wrapper`, `zellij`, `fuzzel`, `mako`, `foot`, `kanshi`, `touch`, `t2`, `surface`) with purpose + platform applicability + requirements.
+  - `dot_local/share/man/man1/dot.1` — header bumped `v0.2.500 → v0.2.502`, `April → May 2026`.
+  - `dot_config/zsh/rc.d/30-options.zsh.tmpl` — completion-block comment no longer references the non-existent `dot prewarm`.
+- **Strategic outputs** (deferred to follow-up PRs / R5):
+  - OSPS Baseline v2026.02.19 Level-2 adoption path documented as the cross-walk for EU CRA Article 24, NIS2 Article 21, SSDF v1.2.
+  - **R5 headline** identified: Shai-Hulud-class personal-device defence (credential-locality policy + honeytoken + shell-init integrity manifest + post-incident playbook in `SECURITY.md`).
+  - **Strategic leapfrog** identified: `dot attest --format=trustmee-wasm` — Wasm-verifiable workstation attestation (composes SLSA-Graduated + arXiv:2602.13148 TrustMee + MCP-exposed workstation state). No competitor reaches this.
+  - **Top-5 de-facto adoption gaps**: Homebrew tap, AUR `PKGBUILD`, Scoop manifest, Hyprland config, awesome-dotfiles listing.
+
+### Performance + polish (post-R4)
+
+- **`dot_config/zsh/dot_zshrc.tmpl`** — `_cached_eval_impl` writes use `>|` (force-clobber) instead of `>`, so the just-`mktemp`'d temp file is not rejected when the user has `setopt noclobber` set globally via `dot_config/shell/05-core-safety.sh:15`. Fixes the `_cached_eval_impl:64: file exists` warning surfaced on every interactive shell with a cache miss.
+- **`dot_config/shell/00-core-paths.sh.tmpl`** — system paths added via `path_prepend` (which removes duplicates first) instead of `PATH="...:${PATH}"`, eliminating the duplicate-system-path bloat that accumulates when the parent shell already had those entries (macOS launchd default).
+- **`dot_config/zsh/dot_zshrc.tmpl`** — re-apply `typeset -U path` after `_dotfiles_async_init` runs cached `export PATH=...` from mise/atuin/etc, since those bypass zsh's `-U` flag on the `path` array.
+- **`scripts/diagnostics/doctor.sh`** — only flag tools that actually emit shell-init eval and are not already lazy-loaded; raise PATH-length thresholds (60 ok / 120 warn) to match a populated mise-managed dev machine; skip `nu` when `cached_eval.nu` is present.
+- **`dot_config/git/hooks/executable_commit-msg`** — replaced hardcoded `/Users/seb` path with `${HOME}` so the hook is portable across hosts.
+- **`dot_config/fish/conf.d/{direnv,mise-activate}.fish`** — empty shadow files that override Homebrew `vendor_conf.d` to prevent eager init. fish dedupes `conf.d/` by basename, user wins. Saves ~140ms on every fish shell start; both tools are loaded lazily via `_cached_eval` in `init.fish`.
+- **`.devcontainer/Dockerfile`** — chezmoi install now goes through `scripts/ci/install-chezmoi-verified.sh` (SHA256-verified) instead of the unverified `curl -fsSL https://get.chezmoi.io` fallback. Closes R4 §8.3 P3 / mirrors R1 H6 fix in `install.sh`.
+- **`typos.toml`** — extended file exclusions (`**/*.asc`, `**/*.pgp`, `**/*.gpg`, `**/*.sig`) to skip armored cryptographic blobs; added `fpr` / `FPR` to the allow-list (GPG `--with-colons` fingerprint column label).
+
 ## v0.2.501
 
 ### Added

package/README.md

@@ -5,12 +5,12 @@
 <h1 align="center">.dotfiles</h1>
 
 <p align="center">
-  <strong>Declarative dotfiles for macOS, Linux, and WSL. Multi-shell by default. Sub-second startup. Wallpaper-driven themes. Signed releases.</strong>
+  <strong>Declarative dotfiles for macOS, Linux, WSL, and Windows-native PowerShell 7.4 LTS / 7.5+. Multi-shell by default. Sub-100ms CLI cold-start. Wallpaper-driven themes. Signed + attested releases. Fleet apply over SSH.</strong>
 </p>
 
 <p align="center">
   <a href="https://github.com/sebastienrousseau/dotfiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=github" alt="Build" /></a>
-  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge" alt="Version" /></a>
+  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.502-blue?style=for-the-badge" alt="Version" /></a>
   <a href="https://github.com/sebastienrousseau/dotfiles/releases"><img src="https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge" alt="Downloads" /></a>
   <a href="https://codespaces.new/sebastienrousseau/dotfiles"><img src="https://img.shields.io/badge/Open%20in-Codespaces-blue?style=for-the-badge&logo=github" alt="Open in GitHub Codespaces" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/dotfiles?style=for-the-badge&label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard" /></a>
@@ -20,13 +20,37 @@
 
 > **Why this is different.** You won't find these three things in `mathiasbynens/`, `holman/`, or `paulirish/`. First, wallpaper-driven terminal themes. We use K-Means clustering in CIELAB and enforce WCAG AAA contrast. Second, first-class agent governance. That covers MCP policy, A2A discovery, signed attestation logs, and bounded profiles (`ask` / `plan` / `apply` / `audit`). Third, verified multi-shell parity across zsh, fish, bash, nushell, and PowerShell. The suite is tested on macOS, Linux, WSL2, and Apple Silicon CI runners. Signed commits are enforced. The installer is idempotent. The CLI heals itself.
 
+<!-- ASCIINEMA DEMO — closes #874 once recorded.
+     30-second clip covering: install.sh → dot doctor → dot theme rebuild.
+     Recording recipe (maintainer):
+
+       asciinema rec ~/dotfiles-demo.cast \
+         --idle-time-limit 1 --rows 30 --cols 100 \
+         --title "Dotfiles: install → doctor → theme"
+       # in the recording shell:
+       #   curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh | bash
+       #   dot doctor
+       #   dot theme rebuild --force
+       # then Ctrl-D to stop
+
+     Upload with `asciinema upload ~/dotfiles-demo.cast`, grab the
+     resulting `https://asciinema.org/a/<id>` URL, and replace this
+     comment with:
+
+       <p align="center">
+         <a href="https://asciinema.org/a/<id>">
+           <img src="https://asciinema.org/a/<id>.svg" alt="install → doctor → theme demo" />
+         </a>
+       </p>
+-->
+
 ## Install
 
 **Verified install (recommended).** Pin to a release tag. Download the installer. Check its SHA256 against the value published with the release. Then run it. See [docs/security/INSTALL_VERIFICATION.md](docs/security/INSTALL_VERIFICATION.md) for the per-release hash and how it's generated.
 
 ```bash
 curl -fsSL -o /tmp/dotfiles-install.sh \
-  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.501/install.sh
+  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.502/install.sh
 echo "4c0303a2d88d5aed98428ab0da37618c9795af4dae0e6549646c2fce5235c280  /tmp/dotfiles-install.sh" \
   | shasum -a 256 -c
 bash /tmp/dotfiles-install.sh
@@ -80,10 +104,10 @@ Most dotfiles repos are personal collections. This one ships as workstation infr
 |:---|:---|:---|
 | **Wallpaper-driven themes** | K-Means clustering in CIELAB extracts terminal palettes from any wallpaper. WCAG AAA enforced. Dynamic HEIC dark/light. | `dot theme rebuild` |
 | **AI and MCP native** | Agent profiles, MCP policy enforcement, attestation logs, AI commit messages. | `dot ai`, `dot mcp`, `dot agent`, `dot mode` |
-| **Cryptographic attestation** | Signed commits, machine-readable evidence, policy bundle releases. | `dot attest`, `dot verify` |
+| **Cryptographic attestation** | Signed commits, machine-readable evidence, policy bundle releases. | `dot attest`, `dot secrets verify` |
 | **Fleet management** | Multi-node drift dashboard, per-host profiles. | `dot fleet` |
 | **Self-healing** | Auto-repair tools, chezmoi drift, broken symlinks, missing files. | `dot heal`, `dot chaos`, `dot rollback`, `dot bundle` |
-| **Sub-second startup** | Lazy loading, `_cached_eval` pattern, mtime-based cache invalidation, realpath sidecar pins. | `dot benchmark`, `dot perf` |
+| **Sub-second startup** | Lazy loading, `_cached_eval` pattern, mtime-based cache invalidation, realpath sidecar pins. | `dot perf`, `dot health` |
 | **Multi-shell parity** | Tier-1 (full): zsh, bash. Tier-2 (bridged): fish. Tier-3 (compatible): nushell. PowerShell is supported as a contract-tested parity target. See [ADR-007](docs/adr/ADR-007-multi-shell-parity.md) and [ADR-011](docs/adr/ADR-011-nushell-tier3-keep.md). | `dot env`, `dot profile` |
 | **Build artifacts → /tmp** | Cargo, Go, pip, uv, and Zig caches redirect to `/tmp/builds/`. Project dirs stay clean. | `~/.config/mise/config.toml`, `~/.cargo/config.toml` |
 | **Encrypted secrets** | Age and SOPS keep per-machine secrets out of plaintext history. | `dot secrets` |
@@ -153,9 +177,15 @@ Over 80 commands grouped by intent. Run `dot help` for the full reference.
 
 | | |
 |:---|:---|
+| `dot init <user>` | Bootstrap any GitHub user's dotfiles repo through this harness |
 | `dot sync` | Apply dotfiles to this machine |
 | `dot doctor` | Check the environment and surface issues |
 | `dot learn` | Open the guided tour |
+| `dot agents render` | Sync `CLAUDE.md` → `AGENTS.md` + Cursor + Codex stubs |
+| `dot fleet apply` | SSH out to every host in `~/.config/dotfiles/fleet.toml` |
+| `dot registry list` | Browse reusable dotfile modules from the registry |
+
+A [Claude Code skill](dot_claude/skills/dotfiles-bootstrap/SKILL.md) is also shipped — `/skills` discovers `dotfiles-bootstrap` and runs `dot init` with profile-aware safety defaults.
 
 ### Daily Use
 
@@ -201,9 +231,9 @@ Over 80 commands grouped by intent. Run `dot help` for the full reference.
 | | |
 |:---|:---|
 | `dot fleet` | Multi-node status, drift, and namespace |
-| `dot benchmark` / `dot perf` | Measure shell startup |
+| `dot perf` | Measure shell startup |
 | `dot score` / `dot security-score` | Health and security scorecards |
-| `dot prewarm` | Warm caches for the first interactive shell |
+| `dot health` | Live dashboard for caches and tool state |
 
 Full reference: [docs/reference/UTILS.md](docs/reference/UTILS.md) · Complete manual: [docs/manual/](docs/manual/) or `dot manual`
 
@@ -227,7 +257,7 @@ The `.dotfiles` Manual is published in nine formats: HTML (single and multi-page
 2. **Explore** — `dot learn` walks through shells, secrets, themes, and performance
 3. **Customize** — edit `~/.config/chezmoi/chezmoi.toml` for per-machine settings ([Profiles](docs/reference/PROFILES.md))
 4. **Toggle features** — flip features in `.chezmoidata.toml` ([Feature Flags](docs/reference/FEATURES.md))
-5. **Apply** — `dot sync` applies the config and `dot prewarm` caches shell startup
+5. **Apply** — `dot sync` applies the config and the next interactive shell hydrates caches via `_cached_eval`
 
 See the [Migration Guide](docs/operations/MIGRATION.md) for version upgrades.
 

package/docs/COPYRIGHT

@@ -1,5 +1,5 @@
 /*
-* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.501) - <https://github.com/sebastienrousseau/dotfiles>
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.502) - <https://github.com/sebastienrousseau/dotfiles>
 * Made With ❤️ in London, United Kingdom
 * Designed by
 * Copyright (c) 2015-2026. All rights reserved.

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.502-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.502)
 [![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.502`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.502)
 - Latest release feed: [GitHub releases](https://github.com/sebastienrousseau/dotfiles/releases/latest)
 - Source repository: [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles)

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.502 — 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/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.502"
 
 # 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.502",
   "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.502"
 
 sections:
   - file: 00-introduction.md

package/docs/manual/command-index.md

@@ -7,30 +7,34 @@ render_with_liquid: false
 Alphabetical list of `dot` subcommands referenced in the manual.
 
 - `dot agent`
+- `dot agents check`
+- `dot agents list`
+- `dot agents render`
+- `dot agents`
 - `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 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`
@@ -42,8 +46,11 @@ Alphabetical list of `dot` subcommands referenced in the manual.
 - `dot mode`
 - `dot packages`
 - `dot perf`
-- `dot prewarm`
 - `dot profile`
+- `dot registry info`
+- `dot registry list`
+- `dot registry search`
+- `dot registry`
 - `dot rollback`
 - `dot score`
 - `dot secrets rotate`
@@ -55,8 +62,5 @@ Alphabetical list of `dot` subcommands referenced in the manual.
 - `dot theme toggle`
 - `dot theme`
 - `dot tune`
-- `dot update`
 - `dot upgrade`
-- `dot verify --security`
-- `dot verify`
 - `dot version`

package/docs/manual/index.md

@@ -0,0 +1,66 @@
+---
+title: "The .dotfiles Manual"
+description: "A trusted agent workstation baseline for macOS, Linux, and WSL."
+render_with_liquid: false
+---
+
+# The .dotfiles Manual
+
+A trusted agent workstation baseline for macOS, Linux, and WSL. Chezmoi handles templating and platform differences; the `dot` CLI coordinates lifecycle operations on top.
+
+This manual is generated from the Markdown sources in [`docs/manual/`](https://github.com/sebastienrousseau/dotfiles/tree/master/docs/manual) and published in nine formats per release. The HTML edition you are reading is the canonical online version.
+
+## Read it your way
+
+- **Web (multi-page)** — browse the chapters below
+- **Single-page HTML, PDF, EPUB, ASCII text** — attached to every [GitHub Release](https://github.com/sebastienrousseau/dotfiles/releases/latest)
+- **CLI** — `dot manual` opens the manual locally; `dot manual pdf` downloads the PDF; `dot manual text` pipes the ASCII edition to your pager
+
+## Contents
+
+### [Introduction](00-introduction.md)
+
+The audience, scope, conventions, and where the manual is published.
+
+### Concepts
+
+- [Architecture](01-concepts/01-architecture.md) — repository layout, chezmoi templating, the `dot` dispatcher
+- [Trust model](01-concepts/02-trust-model.md) — signing, attestation, SBOM, policy gates
+- [Theme engine](01-concepts/03-theme-engine.md) — wallpaper-driven theming across apps
+- [Fleet](01-concepts/04-fleet.md) — multi-workstation coordination and drift detection
+- [Self-healing](01-concepts/05-self-healing.md) — automatic remediation and rollback
+
+### Tutorials
+
+- [First install](02-tutorials/01-first-install.md)
+- [Add a wallpaper-driven theme](02-tutorials/02-add-wallpaper.md)
+- [Create an agent profile](02-tutorials/03-create-profile.md)
+- [Encrypt a secret](02-tutorials/04-encrypt-secret.md)
+- [Deploy to a fleet](02-tutorials/05-deploy-fleet.md)
+
+### Reference
+
+- [`dot` CLI](03-reference/01-dot-cli.md) — every subcommand
+- [Config files](03-reference/02-config-files.md) — every `~/.config/dotfiles/*` path
+- [Environment](03-reference/03-environment.md) — every variable read by the framework
+- [Templates](03-reference/04-templates.md) — every `{{ .var }}` reference
+- [Feature flags](03-reference/05-feature-flags.md)
+
+### Cookbook
+
+- [Recipes](04-cookbook/01-recipes.md)
+- [Troubleshooting](04-cookbook/02-troubleshooting.md)
+- [FAQ](04-cookbook/03-faq.md)
+
+### Appendices
+
+- [A — Platform matrix](05-appendices/A-platform-matrix.md)
+- [B — Security checklist](05-appendices/B-security-checklist.md)
+- [C — Glossary](05-appendices/C-glossary.md)
+- [D — Bibliography](05-appendices/D-bibliography.md)
+- [E — License](05-appendices/E-license.md)
+
+### Indexes
+
+- [Concept index](concept-index.md)
+- [Command index](command-index.md)