@sebastienrousseau/dotfiles 0.2.508 → 0.2.510

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 This file documents all notable changes to this project.
 
+## v0.2.510 — 2026-07-05
+
+Post-v0.2.509 quality-of-life release: default branch renamed `master` → `main`, docs site relit with a custom dark + terminal-green MkDocs Material theme, shells warmed up (fish alias→abbr, zsh PATH prune), font bumped to 20pt across every terminal template, themes rebuilt from wallpapers.
+
+### Added
+
+- **Custom docs theme** (#960). doc.dotfiles.io now serves MkDocs Material with a bespoke palette (near-black `#0b0e14` background, terminal-green `#7ee787` accent), Inter + JetBrains Mono fonts, hero + 8-card feature grid landing page. Header, tabs, sidebar, TOC, admonitions, code blocks, tables, custom scrollbar all restyled in `docs/stylesheets/extra.css`.
+- **CLAUDE.md `## Handing over commands` rule** (#959). Cross-project preference deployed to `~/.claude/CLAUDE.md`: when Claude Code needs the user to run shell steps themselves, it must hand them over as one runnable script file, not fenced code blocks or scattered one-liners.
+- **`mirror-main-to-master` workflow** (#961). Fast-forwards `master` from `main` on every push during the rename grace period so bookmarked `raw.githubusercontent.com/…/master/…` install URLs keep resolving. Retire on 2027-07-05 per tracking issue #962.
+- **fish alias-cache pre-warm** (#964). New `run_onchange_after_30-regen-fish-alias-cache.sh.tmpl` regenerates `~/.cache/fish/bash-aliases.fish` at chezmoi-apply time when the alias sources change, so the first fish shell after apply doesn't pay ~200ms rebuilding the cache from scratch.
+
+### Changed
+
+- **Default branch: `master` → `main`** (#961). GitHub-side rename plus 96 in-repo edits (workflow triggers, docs URIs, install URLs, ruleset filename, git aliases). Every `raw.githubusercontent.com/…/master/…` and `github.com/…/blob/master/…` reference now points at `/main/`. Workflow `pull_request:` / `push:` triggers keep `master` as a grace-period fallback until the mirror is retired.
+- **Portability + missing commands** (#953). Ships as part of v0.2.509 via PR #953 (already tagged) — cross-platform fixes for macOS/BSD/Alpine/openSUSE (base64 `-D` fallback, `sort -V` stdin buffering, `date +%s%3N` guards, zypper/apk/pkg package-manager detection) plus wiring for `dot teleport`, `dot uninstall`, `dot policy`, `dot secret-audit`, `dot completion <bash|zsh|fish|nu>`, `dot fonts patch`. Cross-shell parity for `dot secrets load --shell posix|fish|nu` and auto-secret-load in bash/fish/nushell. See [v0.2.509 release notes](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.509).
+- **Terminal font 12 → 20** (#963). `defaults/.chezmoidata.toml` and every terminal template (alacritty, wezterm, ghostty, kitty, waybar) bumped so a fresh install reads at 20pt across the surface.
+- **Themes rebuilt** (#963). K-Means CIELAB color extraction re-run over all 206 detected wallpapers → 752 theme sections. Five dark themes removed where the underlying wallpaper is inherently light-toned (hello, iphone, valentine, modern, firewatch) — their `-light` counterparts kept.
+- **Zsh PATH prune** (#963). The pre-existing dedup+prune tail in `00-core-paths.sh` was gated behind `[ -z "$ZSH_VERSION" ]`, so zsh never pruned. Now runs native zsh path-array iteration for zsh (89 → 77 entries with no non-existent dirs) alongside the existing bash 4+ associative-array and bash 3.x awk paths.
+
+### Fixed
+
+- **Fish startup 217 ms → 119 ms** (#963). `defaults/dot_config/fish/conf.d/aliases.fish.tmpl` now writes the bash-bridge cache as `abbr --add NAME -- VALUE` instead of `alias NAME=VALUE`. Fish's `alias` builtin creates one function per entry (~183 µs); `abbr` is a command-line-time expansion at ~40 µs. Sourcing the same 878-entry cache went 170 ms → 34 ms. Cache self-heals on upgrade (staleness now also fires on the old `alias` format).
+- **Scorecard code-scanning alerts** (this release, #965). Nine `TokenPermissionsID` alerts closed by adding top-level `permissions: contents: read` (least-privilege default) to workflows that only declared job-level write permissions. One `PinnedDependenciesID` alert closed by hash-locking `requirements-docs.txt` via `pip-compile --generate-hashes` and switching pages.yml to `pip install --require-hashes`.
+
+### Housekeeping
+
+- Bumped `package.json`, `defaults/.chezmoidata.toml`, and every managed markdown reference from `v0.2.508` → `v0.2.510` (26 files consistent).
+- Pruned the stale `feat/v0.2.509` local branch (its remote was deleted at merge time).
+- Retired the `.git/*.sh` session helper scripts left over from the rename + docs-theme + housekeeping PRs.
+
 ## v0.2.508 — 2026-06-30
 
 Makes `dot apply` / `dot update` behave like an OS package-manager update —

package/README.md

@@ -10,7 +10,7 @@
 
 <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=githubactions&logoColor=white" alt="Build" /></a>
-  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.508-blue?style=for-the-badge&logo=semanticrelease&logoColor=white" alt="Version" /></a>
+  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.510-blue?style=for-the-badge&logo=semanticrelease&logoColor=white" 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&logo=github&logoColor=white" 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&logoColor=white" 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&logo=linuxfoundation&logoColor=white&label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard" /></a>
@@ -30,7 +30,7 @@
          --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
+       #   curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh | bash
        #   dot doctor
        #   dot theme rebuild --force
        # then Ctrl-D to stop
@@ -52,7 +52,7 @@
 
 ```bash
 curl -fsSL -o /tmp/dotfiles-install.sh \
-  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.508/install.sh
+  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.510/install.sh
 echo "d5a04c5e2813a93a63c8ecce9655cf3d107f6068862c6eba84a92cf22f801c7e  /tmp/dotfiles-install.sh" \
   | shasum -a 256 -c
 bash /tmp/dotfiles-install.sh
@@ -61,7 +61,7 @@ bash /tmp/dotfiles-install.sh
 **Trust-source one-liner** (skips the SHA check — fine for sandboxes and ephemeral CI, not recommended for primary workstations):
 
 ```bash
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 Then verify and explore:
@@ -80,7 +80,7 @@ Silent install (no prompts):
 
 ```bash
 DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
-  bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+  bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 Docker sandbox:

package/docs/COPYRIGHT

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

package/docs/GOVERNANCE.md

@@ -22,7 +22,7 @@ exist.
 ## Contribution flow
 
 1. **Issue** for non-trivial work. Confirm scope before coding.
-2. **Branch** off `master`: `feat/<scope>`, `fix/<scope>`,
+2. **Branch** off `main`: `feat/<scope>`, `fix/<scope>`,
    `docs/<scope>`, etc.
 3. **PR** with description following the template:
    - Summary (1–3 bullets)
@@ -51,7 +51,7 @@ For breaking changes or substantial new features:
    - **Backwards compatibility** (what breaks, migration path)
    - **Alternatives considered** (with reasons rejected)
    - **Unresolved questions**
-2. Open a PR labelled `rfc` against `master`.
+2. Open a PR labelled `rfc` against `main`.
 3. Comment window: 14 days minimum.
 4. Maintainer renders a decision (accept / accept-with-changes /
    reject) with public reasoning in the PR.

package/docs/adr/ADR-011-nushell-tier3-keep.md

@@ -137,8 +137,8 @@ plugin system, bash bridge for aliases) await an actual user request.
 
 ## References
 
-- [`dot_config/nushell/cached_eval.nu`](../../defaults/dot_config/nushell/cached_eval.nu) — the new module.
-- [`dot_config/nushell/env.nu.tmpl`](../../defaults/dot_config/nushell/env.nu.tmpl) — adopter.
+- [`dot_config/nushell/cached_eval.nu`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/nushell/cached_eval.nu) — the new module.
+- [`dot_config/nushell/env.nu.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/nushell/env.nu.tmpl) — adopter.
 - ADR-007 (Multi-Shell Parity Strategy) — establishes the tier definitions.
 - ADR-002 (Shell Performance Optimization Strategy) — establishes `_cached_eval` semantics this module ports.
 - Issue [#880](https://github.com/sebastienrousseau/dotfiles/issues/880).

package/docs/guides/INSTALL.md

@@ -14,7 +14,7 @@ Set up on macOS, Linux, or WSL in 3 to 5 minutes.
 
 ```bash
 bash -c "$(
-  curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh
+  curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh
 )"
 ```
 
@@ -99,7 +99,7 @@ Use this mode for CI or scripts that run without user input:
 ```bash
 DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
   bash -c "$(
-    curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh
+    curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh
   )"
 ```
 
@@ -136,7 +136,7 @@ rm -rf ~/.local/share/chezmoi ~/.local/share/dotfiles.log
 
 ### Signed contributions
 
-All commits must be signed. See [Contributing](../../CONTRIBUTING.md) for details.
+All commits must be signed. See [Contributing](https://github.com/sebastienrousseau/dotfiles/blob/main/CONTRIBUTING.md) for details.
 
 ---
 

package/docs/index.md

@@ -1,43 +1,132 @@
 ---
+title: .dotfiles — dark, signed, cross-platform
+description: Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL.
+hide:
+  - navigation
+  - toc
 render_with_liquid: false
 ---
 
+<section class="dot-hero" markdown>
+
 # .dotfiles
 
-Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL.
+<p class="tagline">Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL — multi-shell parity (bash/zsh/fish/nushell), a fast <code>dot</code> CLI, wallpaper-driven themes, SLSA-signed releases, and AI/MCP-aware tooling.</p>
+
+<div class="buttons">
+  <a class="primary" href="guides/INSTALL/">Install →</a>
+  <a href="https://github.com/sebastienrousseau/dotfiles">GitHub</a>
+  <a href="reference/UTILS/">Utilities</a>
+  <a href="architecture/ARCHITECTURE/">Architecture</a>
+</div>
+
+</section>
+
+## What's inside
+
+<div class="grid cards" markdown>
+
+- :material-console:{ .lg .middle } **Multi-shell parity**
+
+    ---
+
+    Bash, Zsh, Fish, Nushell — same aliases, functions, prompt, and completions. Cross-shell env parity from `.chezmoidata.toml`.
+
+    [→ Shell hub](reference/UTILS.md)
+
+- :material-lock-check:{ .lg .middle } **Signed & attested**
+
+    ---
+
+    Every commit SSH-signed, DCO enforced, SLSA-signed releases, SBOM + CVE gate, secret encryption via age.
+
+    [→ Security](operations/ATTESTATION.md)
+
+- :material-palette:{ .lg .middle } **190 wallpaper-driven themes**
+
+    ---
+
+    K-Means CIELAB color extraction. Terminal, editor, DE — all follow the wallpaper. `dot theme rebuild --force` regenerates from `~/Pictures/Wallpapers/`.
+
+    [→ Theme system](reference/UTILS.md)
+
+- :material-rocket-launch:{ .lg .middle } **Fast `dot` CLI**
+
+    ---
+
+    142+ subcommands: apply, health, doctor, heal, ai, agent, fleet, secrets, teleport, uninstall — with fzf pickers and a Bubble Tea cockpit.
+
+    [→ CLI reference](reference/UTILS.md)
+
+- :material-check-decagram:{ .lg .middle } **CI you can trust**
+
+    ---
+
+    35+ checks — shellcheck, shfmt, luacheck, stylua, CodeQL, Snyk, grype/SBOM, deps.dev, doc-drift gate, examples contract at 100%.
+
+    [→ Operations](operations/OPERATIONS.md)
+
+- :material-earth:{ .lg .middle } **Cross-platform**
+
+    ---
+
+    macOS (Intel & Apple Silicon), Linux (Ubuntu, Fedora, Arch, Alpine, openSUSE), WSL, PowerShell 7.5+, real BSDs.
+
+    [→ Support matrix](reference/SUPPORT_MATRIX.md)
+
+- :material-brain:{ .lg .middle } **AI & MCP aware**
+
+    ---
+
+    18-agent fleet cockpit (`dot ai`), local Claude gateway, MCP registry, context patterns, provider secrets — first-class support, not bolted on.
+
+    [→ AI operations](AI.md)
+
+- :material-account-cog:{ .lg .middle } **Chezmoi under the hood**
+
+    ---
+
+    Deterministic templates, feature flags, profiles, `run_onchange_` hooks. Everything lives in `defaults/` and applies to `$HOME` on-demand.
+
+    [→ Architecture](architecture/ARCHITECTURE.md)
+
+</div>
+
+## Quick start
+
+Install onto a fresh machine:
 
-[![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.508-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.508)
-[![Downloads](https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases)
+=== "macOS / Linux / WSL"
 
-This site is published from the `docs/` directory on `master` and tracks the current workstation baseline, operational guidance, and security material for the repository.
+    ```bash
+    bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+    ```
 
-## Start Here
+=== "Windows (PowerShell 7+)"
 
-- [Repository README](https://github.com/sebastienrousseau/dotfiles#readme)
-- [Install guide](guides/INSTALL.md)
-- [Troubleshooting](guides/TROUBLESHOOTING.md)
-- [Support matrix](reference/SUPPORT_MATRIX.md)
+    ```powershell
+    iwr -useb https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.ps1 | iex
+    ```
 
-## Workstation Operations
+Once installed:
 
-- [Utilities and `dot` CLI](reference/UTILS.md)
-- [Trusted agent workstation](operations/TRUSTED_AGENT_WORKSTATION.md)
-- [Workstation attestation](operations/ATTESTATION.md)
-- [Operations runbooks](operations/OPERATIONS.md)
-- [Architecture overview](architecture/ARCHITECTURE.md)
-- [Repository layout](architecture/REPO_LAYOUT.md)
+    dot doctor      # verify state
+    dot health      # dashboard with actionable warnings
+    dot ai          # launch the AI cockpit (Bubble Tea TUI)
+    dot theme       # pick a wallpaper-driven theme
+    dot help all    # full CLI reference
 
-## Security and Governance
+## Where to next
 
-- [Security overview](security/SECURITY.md)
-- [Security checklist](security/SECURITY_CHECKLIST.md)
-- [Compliance](security/COMPLIANCE.md)
-- [Policy bundle releases](security/POLICY_RELEASES.md)
-- [Threat model](security/THREAT_MODEL.md)
+- [**Install guide**](guides/INSTALL.md) — full bootstrap walkthrough, per-platform.
+- [**Utilities & `dot` CLI**](reference/UTILS.md) — every subcommand with examples.
+- [**Architecture**](architecture/ARCHITECTURE.md) — how the layers fit together.
+- [**Trusted agent workstation**](operations/TRUSTED_AGENT_WORKSTATION.md) — hardening + attestation runbook.
+- [**Troubleshooting**](guides/TROUBLESHOOTING.md) — the common gotchas.
+- [**Support matrix**](reference/SUPPORT_MATRIX.md) — OS × shell × package-manager grid.
+- [**Security overview**](security/SECURITY.md) — signing, attestation, secret handling, threat model.
 
-## Current Release
+## Current release
 
-- Current tagged release: [`v0.2.508`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.508)
-- Latest release feed: [GitHub releases](https://github.com/sebastienrousseau/dotfiles/releases/latest)
-- Source repository: [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles)
+- Release feed: [GitHub releases](https://github.com/sebastienrousseau/dotfiles/releases/latest)
+- Source: [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles)

package/docs/interop/A2A.md

@@ -8,8 +8,8 @@ The repository now ships an agent card and an A2A-ready discovery document.
 
 Artifacts:
 
-- [agent-card.json](../../defaults/dot_config/dotfiles/agent-card.json)
-- [agent.json](../../.well-known/agent.json)
+- [agent-card.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/agent-card.json)
+- [agent.json](https://github.com/sebastienrousseau/dotfiles/blob/main/.well-known/agent.json)
 
 Core properties:
 

package/docs/interop/POWERSHELL.md

@@ -13,9 +13,9 @@ and what specifically is verified. Closes the docs slice of
 
 | File | Role |
 |---|---|
-| [`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. |
+| [`dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/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`](https://github.com/sebastienrousseau/dotfiles/blob/main/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`](https://github.com/sebastienrousseau/dotfiles/blob/main/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. |
 
 ## What's verified
 
@@ -96,7 +96,7 @@ pwsh ./scripts/qa/powershell-contract.ps1
 ## References
 
 - [PowerShell 7 docs](https://learn.microsoft.com/en-us/powershell/scripting/overview)
-- [PSScriptAnalyzer rule reference](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/README.md)
+- [PSScriptAnalyzer rule reference](https://github.com/PowerShell/PSScriptAnalyzer/blob/main/docs/Rules/README.md)
 - `.github/workflows/reliability-gate.yml` — Windows job definition.
 - Issue [#860](https://github.com/sebastienrousseau/dotfiles/issues/860).
 {% endraw %}

package/docs/manual/00-introduction.md

@@ -4,7 +4,7 @@ render_with_liquid: false
 
 # Introduction
 
-This manual describes `.dotfiles` v0.2.508 — a trusted agent workstation baseline for macOS, Linux, and WSL.
+This manual describes `.dotfiles` v0.2.510 — 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.
 
@@ -52,7 +52,7 @@ dot manual text      # pipe plain text to pager
 ## Quick Install
 
 ```sh
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 dot doctor
 ```
 
@@ -86,4 +86,4 @@ Individual tools packaged, referenced, or templated by this repository retain th
 
 - **Bugs and feature requests** — <https://github.com/sebastienrousseau/dotfiles/issues>
 - **Security vulnerabilities** — see [Security Policy](../security/SECURITY.md); do not open public issues for unpatched vulnerabilities
-- **Documentation corrections** — open a pull request against `docs/manual/` on the `master` branch
+- **Documentation corrections** — open a pull request against `docs/manual/` on the `main` branch

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

@@ -21,7 +21,7 @@ The trust model combines cryptographic signing, local-first secrets, policy-gate
 
 ### SSH ED25519 for Git
 
-Every commit on `master` is signed with SSH ED25519:
+Every commit on `main` is signed with SSH ED25519:
 
 ```sh
 git verify-commit HEAD
@@ -62,7 +62,7 @@ CI runs three independent scanners:
 
 | Scanner | Purpose | Threshold |
 |:---|:---|:---|
-| `gitleaks` | Pattern-based secret detection | Zero leaks on `master` |
+| `gitleaks` | Pattern-based secret detection | Zero leaks on `main` |
 | `detect-secrets` | Baseline-comparing scanner | Zero new secrets vs `.secrets.baseline` |
 | `trufflehog` | Verified-secret scanner (API-tested) | Zero verified secrets |
 
@@ -119,7 +119,7 @@ Violations are logged to `~/.local/state/dotfiles/mcp-violations.log` and report
   },
   "git": {
     "head": "abc123...",
-    "branch": "master",
+    "branch": "main",
     "signed": true,
     "verified": true
   }

package/docs/manual/01-concepts/04-fleet.md

@@ -91,7 +91,7 @@ Recommended rollout procedure for fleet-wide changes:
 
 1. **Develop on one host** — make the change, test locally with `dot apply --dry-run` then `dot apply`
 2. **Open a PR** — CI validates shellcheck, tests, security scanners
-3. **Merge to master** — signed commit required
+3. **Merge to main** — signed commit required
 4. **Per-host pull** — on each fleet host: `dot update` (git pull + apply)
 5. **Verify alignment** — run `dot fleet attest` from any host
 

package/docs/manual/02-tutorials/01-first-install.md

@@ -16,7 +16,7 @@ End-to-end installation and verification, from zero to a fully-working environme
 ## Step 1: Run the Installer
 
 ```sh
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 The installer:

package/docs/manual/02-tutorials/05-deploy-fleet.md

@@ -21,7 +21,7 @@ Goal: all three running identical `.dotfiles` with per-host customization, with
 On each new host:
 
 ```sh
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 During `chezmoi init`, answer with the host's preset:
@@ -164,7 +164,7 @@ Both hosts render from the same templates, producing correct platform-appropriat
 
 ## Step 6: Fleet-Wide Updates
 
-When you push a commit to master, each host pulls independently:
+When you push a commit to main, each host pulls independently:
 
 ```sh
 # On each host

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

@@ -247,7 +247,7 @@ Agent Card (MCP A2A spec):
 
 ## Verified Files
 
-Every commit on `master` modifies tracked files only. Untracked files in the source directory (e.g. editor swap files) are ignored via `.chezmoiignore`:
+Every commit on `main` modifies tracked files only. Untracked files in the source directory (e.g. editor swap files) are ignored via `.chezmoiignore`:
 
 ```
 .DS_Store

package/docs/manual/03-reference/04-templates.md

@@ -174,7 +174,7 @@ chezmoi execute-template '{{- $t := index .themes .theme -}}{{ $t.term.bg }}'
 
 ## Validation in CI
 
-Every push to master runs:
+Every push to main runs:
 
 ```sh
 chezmoi apply --dry-run

package/docs/manual/04-cookbook/01-recipes.md

@@ -11,7 +11,7 @@ Thirty short recipes for common tasks.
 ### 1. Install on a fresh machine
 
 ```sh
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 ### 2. Update everything

package/docs/manual/04-cookbook/02-troubleshooting.md

@@ -17,7 +17,7 @@ Symptom → cause → fix.
 
 ```sh
 export PATH="$HOME/.local/bin:$PATH"
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
 ```
 
 ### Symptom: "could not create directory ~/.local/share/chezmoi"

package/docs/manual/05-appendices/B-security-checklist.md

@@ -63,7 +63,7 @@ If a host is compromised:
 
 ## Gates Enforced by CI
 
-Every PR to master must pass:
+Every PR to main must pass:
 
 - [x] SSH-signed commits
 - [x] Shellcheck zero warnings (severity=error)

package/docs/manual/command-index.md

@@ -12,11 +12,36 @@ job `lint/command-index` fails when this file is stale.
 |---------|---------|
 | `dot add` | Add a file to chezmoi source |
 | `dot agent` | Profile-aware execution, agent card, a2a-card, session log, checkpoints, and conformance |
+| `dot agent` | a2a-card Show or validate the A2A v0.3 agent card |
+| `dot agent` | card Show the local agent card metadata |
+| `dot agent` | checkpoint Manage agent run checkpoints (save/list/show/replay) |
+| `dot agent` | conformance Run the A2A conformance test suite |
+| `dot agent` | delegate Delegate execution to an allowed sub-agent |
+| `dot agent` | log Tail the agent session audit log |
+| `dot agents` | check Verify AGENTS.md tracks CLAUDE.md (exit 1 if drifted) |
+| `dot agents` | list Show recognised AI agent harnesses and their config paths |
+| `dot agents` | render Regenerate AGENTS.md and per-harness config from CLAUDE.md |
 | `dot agy` | Antigravity CLI with context patterns |
 | `dot ai` | AI fleet cockpit, gateway, and cost |
+| `dot ai` | ask Context-aware RAG query over your dotfiles |
+| `dot ai` | chat Start an interactive AI session with a chosen tool |
+| `dot ai` | cost Report AI spend across every provider from the unified run log |
+| `dot ai` | delegate Delegate a coding task to a cheaper AI model under agent policy |
+| `dot ai` | doctor Diagnose AI tooling configuration and connectivity |
+| `dot ai` | install Install AI CLI tools via mise/native installers |
+| `dot ai` | login Interactive setup/authentication for installed AI CLI tools |
+| `dot ai` | run Run a one-shot prompt with an AI tool |
+| `dot ai` | serve Run the local AI gateway/proxy that routes non-Claude providers |
+| `dot ai` | tools Show installed AI CLI tools and their versions |
 | `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 aliases` | cheatsheet Generate the alias cheatsheet markdown |
+| `dot aliases` | list List all shell aliases shipped by the dotfiles |
+| `dot aliases` | search Search aliases by term |
+| `dot aliases` | stats Show alias usage counts from shell history |
+| `dot aliases` | tiers Show which alias tiers/ecosystems are enabled |
+| `dot aliases` | why Show details and deprecation status for a single alias |
 | `dot attest` | Export workstation attestation evidence (--json |
 | `dot backup` | Create a compressed backup of your home |
 | `dot bundle` | Create offline archive of dotfiles environment |
@@ -25,6 +50,7 @@ job `lint/command-index` fails when this file is stale.
 | `dot chaos` | Simulate config corruption to test self-healing |
 | `dot cl` | Claude CLI with context patterns |
 | `dot commit` | AI-powered conventional commit |
+| `dot completion` | Generate shell completions (bash/zsh/fish/nu) from the command registry |
 | `dot copilot` | GitHub Copilot CLI with context patterns |
 | `dot diff` | Show chezmoi diff with exclusions |
 | `dot dns-doh` | Enable DNS-over-HTTPS [macOS,Linux] |
@@ -33,34 +59,70 @@ job `lint/command-index` fails when this file is stale.
 | `dot edit` | Open chezmoi source in $EDITOR |
 | `dot encrypt-check` | Check disk encryption status |
 | `dot env` | Tool versions (mise) |
+| `dot env` | emit Emit a portable workstation environment manifest (SBOM; --format json) |
+| `dot env` | install Install requested tool versions via mise |
+| `dot env` | list List managed tool versions via mise |
+| `dot env` | prune Show or remove orphan tool installs (--yes to commit) |
+| `dot env` | use Pin a tool version globally/locally via mise |
 | `dot firewall` | Apply firewall hardening [macOS,Linux] |
 | `dot fleet` | Show fleet node status, drift, and namespace (--json for machine output) |
+| `dot fleet` | apply SSH to every host in fleet.toml and run dot sync (or a custom --cmd) |
 | `dot fleet` | drift Check for configuration drift across managed files |
+| `dot fleet` | enforce Show or set RBAC enforcement mode (advisory/strict) for agent profiles |
 | `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 fleet` | status Show this node's fleet status: id, namespace, version, OS, drift, last apply |
+| `dot fonts` | Install (default) or patch Nerd Fonts (JetBrainsMono by default) |
 | `dot help` | Show this help message |
 | `dot history` | Shell history analysis |
 | `dot keys` | Keybindings (sign-check: verify git signing) |
+| `dot keys` | sign-check Verify git commit-signing configuration and key availability |
 | `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 mcp` | doctor Run the MCP policy/supply-chain/config audit |
+| `dot mcp` | registry Show the configured MCP server registry |
 | `dot metrics` | Show recent observability metrics (JSONL) |
 | `dot mode` | Set or inspect agent operating profiles (ask/plan/apply/audit) |
+| `dot mode` | current Show the active agent profile and its policy |
+| `dot mode` | doctor Validate the agent-profiles.json config and default profile |
+| `dot mode` | list List available agent operating profiles (ask/plan/apply/audit) |
+| `dot mode` | run Run a command under a given agent profile with a checkpoint |
+| `dot mode` | set Switch the active agent profile |
+| `dot mode` | show Show details of a specific agent profile |
 | `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 patterns` | edit Edit an AI steering pattern in $EDITOR |
+| `dot patterns` | list List AI steering patterns |
+| `dot patterns` | view View an AI steering pattern |
 | `dot perf` | Show performance mode and quick timing |
+| `dot policy` | Check and enforce security policies across the environment |
 | `dot profile` | Show/switch configuration profile |
+| `dot profile` | set Set the active configuration profile (run dot sync to apply) |
+| `dot profile` | show Show the active configuration profile and feature flags |
+| `dot registry` | info Print full metadata for a registry module |
+| `dot registry` | install Install a registry module (scaffold) |
+| `dot registry` | list List modules in the configured module registry |
+| `dot registry` | search Filter registry modules by keyword |
+| `dot registry` | set-url Override the registry URL (https only; persists) |
+| `dot registry` | url Show the active registry URL |
 | `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 secret-audit` | Audit secret hygiene and leakage surface |
 | `dot secrets` | Edit encrypted secrets (age) |
+| `dot secrets` | edit Edit the encrypted secrets file (age) |
+| `dot secrets` | get Retrieve a secret value (--raw for plaintext) |
+| `dot secrets` | list List indexed secret keys |
+| `dot secrets` | load Emit export lines for a secrets bucket (use with eval) |
+| `dot secrets` | provider Show the active secrets provider |
+| `dot secrets` | set Store a secret value under a key |
 | `dot secrets-create` | Create an encrypted secrets file |
 | `dot secrets-init` | Initialize age key for secrets |
 | `dot sgpt` | Shell-GPT with context patterns |
@@ -70,10 +132,23 @@ job `lint/command-index` fails when this file is stale.
 | `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 teleport` | Deploy the dotfiles environment to a remote host over SSH |
 | `dot theme` | Switch terminal theme (dark/light) |
+| `dot theme` | current Show the current theme info |
+| `dot theme` | family Cycle between theme families |
+| `dot theme` | list Show all available terminal/wallpaper themes |
+| `dot theme` | rebuild Regenerate themes from system and custom wallpapers |
+| `dot theme` | set Set a theme by name (interactive picker if omitted) |
+| `dot theme` | sync Sync the dotfiles theme with system dark/light mode |
+| `dot theme` | toggle Toggle light/dark within the current theme family |
 | `dot tools` | Show or install nix packages |
+| `dot tools` | docs Show the full tools markdown documentation |
+| `dot tools` | install Enter the Nix development shell with all managed tools |
 | `dot tune` | Apply OS tuning (opt-in) [macOS,Linux] |
+| `dot uninstall` | Remove the managed dotfiles environment (prompts unless --force) |
 | `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] |
+| `dot wallpaper` | rotate Rotate to the next wallpaper in your library |
+| `dot wallpaper` | sync Sync wallpaper from your library |