@sebastienrousseau/dotfiles 0.2.508 → 0.2.511

package/docs/articles/2026-07-05-master-to-main-rename-runbook.md

@@ -0,0 +1,128 @@
+---
+title: "Renaming master to main in 2026: A Zero-Downtime Runbook"
+description: A supply-chain-safe procedure for renaming the default branch of a mature open-source repository — 96 in-repo edits, a grace-period mirror workflow, zero broken install URLs.
+date: 2026-07-05
+---
+
+# Renaming `master` to `main` in 2026: A Zero-Downtime Runbook for a Repository at the Heart of an Open-Source Supply Chain
+
+*Renaming the default branch of a mature repository is a supply-chain event, not a cosmetic one; done wrong, it strands `curl \| bash` install commands, breaks CI, and severs external distribution channels.*
+
+*Sebastien Rousseau · Published 5 Jul 2026 · 12 min read*
+
+## Why Default-Branch Naming Matters in 2026 #
+
+Every open-source project with a public install path publishes a URL of the form `raw.githubusercontent.com/<owner>/<repo>/<branch>/install.sh`. Every downstream consumer who has copied that URL — into a README, a Slack message, a devcontainer, a company wiki, a StackOverflow answer, a Homebrew tap, an AUR PKGBUILD, an internal Ansible playbook — has taken an implicit dependency on that branch name. Renaming the branch is a **breaking change to the project's public API surface**, whether the maintainer intended one or not.
+
+The industry moved off `master` as the default branch name years ago; new repositories default to `main`. Existing repositories, however, live with a naming inconsistency that becomes actively confusing when a maintainer has multiple projects — some on `main`, some still on `master`. The migration is unavoidable, but the operational risk profile is significant enough that most maintainers put it off indefinitely.
+
+This article documents the migration of the [.dotfiles](https://github.com/sebastienrousseau/dotfiles) repository — 60+ files with hardcoded branch references, four external distribution channels, three CI providers tracking the default branch, and a public install command bookmarked by an unknown number of downstream users. The migration was **zero-downtime**: no install command broke, no CI job failed, no downstream integration degraded. The blueprint is generalisable to any medium-complexity open-source repository.
+
+## The Branch-Rename 2026 Architecture Lens #
+
+A default-branch rename is not a single operation. It's a sequence of coordinated changes across a defined dependency graph, each with its own migration mechanism:
+
+| Layer | Design Decision | Why It Matters | Risk if Mishandled |
+|---|---|---|---|
+| **GitHub metadata** | Native rename via Settings → Branches or `POST /repos/{owner}/{repo}/branches/{branch}/rename` | GitHub auto-migrates default-branch setting, open PR targets, branch-protection assignment, ruleset targeting, and Pages source | Renaming via manual `git push :old-name` + `git push new-name` skips the auto-migration and orphans PRs |
+| **In-repo workflow triggers** | `.github/workflows/*.yml` `branches:` lists updated pre-rename | Workflows that trigger on `push:` or `pull_request:` targeting the old name silently stop firing after rename | Migration PR itself under-tested — the workflows it edits no longer fire on it |
+| **Grace-period mirror** | New workflow fast-forwards `master` from `main` on every push | Preserves `raw.githubusercontent.com/…/master/…` URLs for downstream consumers who cannot be reached | External `curl \| bash` install commands return HTTP 404 the moment `master` ceases to exist |
+| **Documentation URIs** | `mkdocs.yml` `edit_uri`, README install commands, docs prose | GitHub redirects `github.com/…/blob/master/…` automatically; `raw.githubusercontent.com/…/master/…` does **not** redirect | Docs site edit buttons point at nonexistent branches; install commands 404 |
+| **Rulesets as code** | `.github/rulesets/<branch>.json` file renamed alongside the JSON `target.include` | Machine-readable ruleset files that reference `refs/heads/master` misalign with GitHub's auto-migrated state | Configuration drift between the in-repo policy source of truth and GitHub's live enforcement |
+| **Test-suite assertions** | Regression tests that asserted `/master/` URLs in README updated to assert `/main/` | Tests written before rename fail *after* rename in the exact commit that fixes them | Migration PR shows red CI, blocking merge |
+| **External distribution** | Homebrew tap, Scoop bucket, AUR PKGBUILD — pinned to release tags, not branches | Version-pinning insulates external distribution from branch renames | Branch-pinned distribution manifests break silently on rename |
+
+## Key Branch-Rename Migration Signals #
+
+| Signal | Operational Benchmark | Reference | Technical Platform Implementation |
+|---|---|---|---|
+| **URL Reachability Post-Rename** | `HTTP 200` on both `main/install.sh` and `master/install.sh` for the full grace period | External-consumer continuity | Mirror workflow: `on: push: branches: [main]` → `git push origin main:refs/heads/master` |
+| **CI Coverage on Migration PR** | Workflow-trigger `branches:` list transitionally includes both `main` and `master` | Migration PR must be tested against the current default | `pull_request: branches: [main, master]` — remove `master` once the mirror retires |
+| **In-Repo URL Consistency** | Zero remaining `/master/` URIs on the head branch, excluding intentional mirror-preservation strings | Doc/install correctness | `git grep 'raw.githubusercontent.com/.../master/'` returns empty (or only test-fixture strings) |
+| **Ruleset File Alignment** | `.github/rulesets/*.json` filename matches its `target.include` refspec | Config-as-code hygiene | File rename via `git mv` + JSON `target.include` update in the same commit |
+| **Grace-Period Retirement Marker** | Calendar-visible tracking item with an explicit sunset date | Operational-debt visibility | GitHub issue with target date in title + calendar event (`.ics` or Google Calendar quick-add URL) |
+
+## Diagnosis: Enumerating the Blast Radius #
+
+Before touching a single file, an authoritative audit surfaces the full inventory of `master` references. On the .dotfiles repository, that surfaced **~88 mechanical replacements across 60 files**, grouped as:
+
+- **24 GitHub Actions workflow files** — trigger lists, `github.ref_name == 'master'` conditionals, `--base master` PR-creating steps, inline `@SHA # master` comments describing what commit was pinned
+- **7 `raw.githubusercontent.com/.../master/…` URLs** — README install command, `install.sh` (referencing itself in its own comment header), `bin/dot-bootstrap`, `docs/index.md`, install guide, MkDocs edit_uri, chezmoi-data JSON `$id` field
+- **~25 documentation files** — `github.com/…/blob/master/…` references in operations runbooks, security docs, architecture decision records
+- **1 ruleset-as-code file** — `.github/rulesets/master.json` with a `target.include: refs/heads/master` field
+- **1 regression test** — asserting the README contains `/master/` (a red-team catch: this test PROTECTS against accidental rename, which now needs its assertion inverted)
+- **4 legitimately-kept references** — the `gbd` bulk-branch-delete script with a `main|master` whitelist regex, the `git-primary-branch` shell function's fallback path, the release-branch check in `scripts/ops/release.sh`, and Scorecard-linter fixtures demonstrating `@master` as an anti-pattern
+
+## Remediation Sequence #
+
+The rename is executed as a five-phase sequence, each with a distinct commit or GitHub operation:
+
+**Phase 1 — Pre-migration content preparation.** A single pull request rewrites all in-repo `master` references while `master` is still the default branch. This PR must merge before any GitHub-side rename. Workflow `pull_request:` triggers gain `[main, master]` (paired) so the PR itself triggers CI against the current default. The ruleset file is renamed via `git mv` and its JSON target updated. The regression test's assertion is inverted from "must contain `/master/`" to "must contain `/main/`".
+
+**Phase 2 — GitHub-side rename.** Via UI (`Settings → Branches → Rename`) or API (`POST /repos/{owner}/{repo}/branches/master/rename`). GitHub auto-migrates default-branch setting, PR targets, branch-protection assignment, ruleset targeting, Pages source. Blocked if a branch-protection *rule pattern* targeting the new name already exists — delete the empty rule first via GraphQL:
+
+```
+gh api graphql -f query='
+mutation {
+  deleteBranchProtectionRule(input: { branchProtectionRuleId: "..." }) {
+    clientMutationId
+  }
+}'
+```
+
+**Phase 3 — Mirror workflow activation.** Trigger the pre-committed mirror workflow via `workflow_dispatch` or a small push to `main`. The workflow performs a fast-forward `git push origin main:refs/heads/master`, recreating `master` as a passive mirror. From this point forward, every push to `main` mirrors automatically.
+
+**Phase 4 — Local clone update (per-workstation).** Every developer with an active clone runs:
+
+```
+git branch -m master main
+git fetch origin
+git branch -u origin/main main
+git remote set-head origin -a
+```
+
+**Phase 5 — Retirement scheduling.** A GitHub issue with a title-embedded target date (`[2027-07-05] Retire master mirror + tighten workflow triggers to main-only`) plus a calendar reminder ensures the grace-period mirror doesn't become permanent operational debt.
+
+## Verification: URLs, CI, Docs Site #
+
+Post-rename smoke tests:
+
+```
+$ curl -sI https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh   | head -1
+HTTP/2 200
+$ curl -sI https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh | head -1
+HTTP/2 200
+```
+
+Both branch names resolve during the grace period. When the mirror is retired in 12 months, `/master/` returns 404 by design — but by then no active install command should still reference it.
+
+CI status post-rename: on the .dotfiles repository, the migration PR (`#961`) ran **70 checks green, 0 failed**, driven by the `[main, master]` trigger-list transitional configuration. The follow-up test-coverage PR (`#963`) confirmed no downstream test regression.
+
+Docs site: MkDocs `edit_uri` — updated from `edit/master/docs/` to `edit/main/docs/` — resolves correctly. `github.com/…/blob/master/…` links continue to work via GitHub's built-in redirect; `raw.githubusercontent.com/…/master/…` works via the mirror.
+
+## Return on Resilience #
+
+The commercial value of a supply-chain-safe rename is defensive, not offensive: nothing new is built, but nothing existing breaks.
+
+| Metric | Result |
+|---|---|
+| Files updated in migration PR | 97 (96 edits + 1 rename + 1 new workflow) |
+| Grace-period external URL uptime | 100% (both `/main/` and `/master/` return HTTP 200) |
+| CI checks post-rename | 70 green, 0 failed |
+| Downstream distribution channels broken | 0 (Homebrew tap, Scoop bucket, AUR pinned to tags) |
+| Local-clone update commands | 4 lines, ~5 seconds per workstation |
+| Operational debt introduced | 1 mirror workflow, retired via calendar-scheduled task 2027-07-05 |
+
+## Takeaways #
+
+1. **Land the in-repo edits before the GitHub-side rename.** Merging Phase 1 while `master` is still default gives you both a working CI baseline and a rehearsal.
+
+2. **Add the mirror workflow before renaming, not after.** The interval between the GitHub rename and the mirror's first fast-forward push is the window during which `raw.githubusercontent.com/…/master/…` returns 404. Minimising that window is a matter of ordering.
+
+3. **Update `pull_request:` triggers transitionally.** `branches: [main, master]` covers the migration PR itself (which targets the pre-rename default) and every future PR (which will target `main`). The grace-period `master` entry retires with the mirror.
+
+4. **Track retirement as an issue with an explicit sunset date.** Mirror workflows are the classic case of "temporary" becoming "permanent". A calendar event and a GitHub issue with a date-anchored title enforce end-of-life.
+
+5. **Rulesets-as-code files must be renamed alongside their JSON targets.** GitHub auto-migrates the *live* ruleset assignment; the file in your repo is the source-of-truth if you ever reapply. Both must agree.
+
+The reference implementation landed as [PR #961](https://github.com/sebastienrousseau/dotfiles/pull/961) with the retirement issue tracked at [#962](https://github.com/sebastienrousseau/dotfiles/issues/962), shipped in [v0.2.510](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.510).

package/docs/articles/index.md

@@ -0,0 +1,36 @@
+---
+title: Articles
+description: Long-form writing on the design and operation of the .dotfiles framework.
+---
+
+# Articles
+
+Long-form writing on the design and operation of the [.dotfiles framework](https://github.com/sebastienrousseau/dotfiles) — deep dives into performance, supply-chain safety, developer experience, and the architectural decisions that shape a mature open-source dotfiles project.
+
+<div class="grid cards" markdown>
+
+- :material-console:{ .lg .middle } **[Fish Startup in 2026](2026-07-05-fish-startup-abbr.md)**
+
+    ---
+
+    Cutting interactive shell latency by 48% with `abbr` on multi-shell dotfiles. One printf format change + one chezmoi hook = 112 ms saved per fresh terminal.
+
+    *5 Jul 2026 · 10 min read*
+
+- :material-source-branch:{ .lg .middle } **[Renaming `master` to `main`](2026-07-05-master-to-main-rename-runbook.md)**
+
+    ---
+
+    A zero-downtime runbook for a repository at the heart of an open-source supply chain. 96 in-repo edits, a 12-month mirror workflow, zero broken install URLs.
+
+    *5 Jul 2026 · 12 min read*
+
+- :material-palette:{ .lg .middle } **[Custom Documentation Sites in 2026](2026-07-05-custom-mkdocs-material-dark-theme.md)**
+
+    ---
+
+    Building a distinctive dark-themed developer reference on MkDocs Material — three files, no theme forking, WCAG AAA contrast, hash-locked build.
+
+    *5 Jul 2026 · 11 min read*
+
+</div>

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.511 — 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)