@sebastienrousseau/dotfiles 0.2.519 → 0.2.520

package/docs/guides/MACOS_ICLOUD_SYMLINKS.md

@@ -0,0 +1,121 @@
+---
+render_with_liquid: false
+---
+
+# macOS iCloud Drive Symlinks
+
+On macOS, this dotfiles setup can (safely) symlink personal directories into iCloud Drive so `~/Desktop`, `~/Documents`, `~/Downloads`, `~/Movies`, `~/Music`, `~/Pictures`, and `~/Public` all live in iCloud and back up automatically.
+
+The mechanism is `defaults/run_before_macos-icloud-symlinks.sh.tmpl`, which chezmoi runs before **every** `apply` — not once, and not only when the script changes. That is deliberate: a run-once script gets a single attempt, and on a fresh Mac that attempt lands while iCloud Drive is still syncing the folder tree down, so every candidate would skip and the one chance would be spent. Running each time lets it link whatever has become safe to link since the last apply. Repeat runs are no-ops that cost a few milliseconds.
+
+## `~/Desktop` and `~/Documents` are a special case
+
+macOS has its own **"Desktop & Documents Folders"** iCloud feature (System Settings -> Apple Account -> iCloud -> iCloud Drive -> Options). When it is on, macOS itself syncs those two folders, and it marks them in the iCloud container by putting symlinks there pointing *back* at your home directory:
+
+```text
+com~apple~CloudDocs/Desktop    -> ~/Desktop
+com~apple~CloudDocs/Documents  -> ~/Documents
+```
+
+Check whether it is on:
+
+```bash
+defaults read com.apple.finder FXICloudDriveDesktop    # 1 = Desktop sync on
+defaults read com.apple.finder FXICloudDriveDocuments  # 1 = Documents sync on
+```
+
+**If those return `1`, `~/Desktop` and `~/Documents` are already fully synced to iCloud and across your devices — by macOS, not by this script.** They will show as `SKIP ... iCloud source is itself a symlink` in the log. That is the correct outcome, not a failure.
+
+Do **not** apply the manual migration recipe below to `~/Desktop` or `~/Documents` while native sync is on: you would be moving data into a symlink that points back at its own source, fighting a feature macOS is already managing. Turn native sync off first if you genuinely want the symlink approach — but for these two folders the native feature is the better mechanism, since Finder, Migration Assistant, and iOS all understand it.
+
+The symlink approach in this guide is for the folders macOS does *not* cover natively: `~/Downloads`, `~/Movies`, `~/Music`, `~/Pictures`, `~/Public`.
+
+## Safety guarantees
+
+This script is the **replacement** for a previous `symlink_*.tmpl` set that had a data-loss bug (see #1018): chezmoi's built-in symlink handling does `rm -rf $target; ln -s $source $target`, which destroys real content if the target directory has data.
+
+The current script's contract is:
+
+| Situation | What the script does |
+|---|---|
+| `~/$name` is already the correct symlink to iCloud | no-op |
+| `~/$name` is a symlink pointing somewhere else | **skip, log** — never overwrite your own link |
+| `~/$name` is a directory with any content (including `.DS_Store`) | **skip, log** — never delete your data |
+| `~/$name` is an empty directory | `rmdir` (fails safely if non-empty due to a race) + create symlink |
+| `~/$name` is a regular file | **skip, log** — never touch |
+| `~/$name` does not exist | create symlink directly |
+| iCloud source `com~apple~CloudDocs/$name` does not exist | **skip, log** — iCloud may still be syncing |
+| iCloud Drive is not set up on the Mac | **skip everything, log** — no partial state |
+| iCloud source `com~apple~CloudDocs/$name` is itself a symlink | **skip, log** — macOS's native Desktop & Documents sync owns it (see below) |
+
+The script has **two kill-switches**:
+
+- `touch ~/.dotfiles.icloud-skip` — permanent per-machine opt-out
+- `DOTFILES_ICLOUD_SYMLINKS=0` — env var, one run only
+
+And a **dry-run mode**:
+
+- `DOTFILES_ICLOUD_DRY_RUN=1` — log every decision, take no action
+
+## Rescue: how to link a directory that has content
+
+If one of the non-native folders (`~/Downloads`, `~/Movies`, `~/Music`, `~/Pictures`, `~/Public`) already has content and you want it in iCloud — the example uses `Documents`, which applies only if you have turned native Desktop & Documents sync **off**:
+
+```bash
+# 1. Move your data into iCloud MANUALLY
+mv ~/Documents/* ~/Documents/.* "~/Library/Mobile Documents/com~apple~CloudDocs/Documents/" 2>/dev/null
+
+# 2. Verify iCloud has everything
+ls -la "~/Library/Mobile Documents/com~apple~CloudDocs/Documents/"
+
+# 3. Now the dir is empty — chezmoi's next apply will do the rmdir + symlink
+rmdir ~/Documents          # sanity check: this succeeds only if truly empty
+chezmoi apply
+```
+
+## After the links exist: what changes
+
+Linking a folder into iCloud does exactly what it says, and that has consequences worth understanding *before* you migrate rather than after.
+
+**Storage.** Everything saved to a linked folder counts against your iCloud quota, not just local disk. `~/Downloads` is the one that catches people out.
+
+**Deletion.** Deleting a file from a linked folder deletes it from iCloud, and therefore from every device signed into that account. There is no local-only copy any more. This is inherent to symlinking and is not something the hook can guard.
+
+**Eviction.** macOS may evict a synced file's contents to reclaim disk space, leaving a placeholder behind. Reading it downloads it again — so a script that walks one of these folders can block on the network where it used to return instantly.
+
+**Two things in this repository write into these folders.** Neither runs during `chezmoi apply`; both are commands you invoke deliberately:
+
+| What | Where | Why it matters after linking |
+|---|---|---|
+| `scripts/theme/merge-wallpaper.sh` | `~/Pictures/Wallpapers` (override with `DOTFILES_WALLPAPER_DIR`) | Merges a light/dark pair into one `.heic` and then **deletes both source files**. After linking, that pair is consumed from iCloud. Point `DOTFILES_WALLPAPER_DIR` at a local directory to keep the library off iCloud. |
+| `defaults/dot_config/mpv/mpv.conf` | `~/Pictures/Screenshots` | `screenshot-directory` is set here, so mpv screenshots land in iCloud. |
+
+Nothing else in this repository writes into the seven folders, and chezmoi itself never touches them: they are listed in the Darwin block of `.chezmoiignore.tmpl`, and `chezmoi managed` reports none of them among the paths it controls.
+
+## Log
+
+Every run appends to `$XDG_STATE_HOME/dotfiles/icloud-symlinks.log` (default: `~/.local/state/dotfiles/icloud-symlinks.log`). Grep for `SKIP` to see why a candidate wasn't linked, or `LINK` to see what was created.
+
+## Belt-and-braces protection
+
+The same directory names are listed in `defaults/.chezmoiignore.tmpl`'s Darwin block, so even if the script never ran, chezmoi's regular `apply` would still refuse to touch these paths on macOS. Two independent layers of protection.
+
+## Tests
+
+Three suites, 52 assertions, all of them run under `/bin/bash` 3.2 as well as bash 5:
+
+- `tests/unit/misc/test_macos_icloud_symlinks.sh` — 29 assertions covering every branch of the refusal matrix.
+- `tests/regression/test_macos_icloud_symlinks_safety.sh` — 12 assertions on the data-loss invariants, checking that named canary files survive.
+- `tests/regression/test_macos_icloud_symlinks_manifest.sh` — 11 assertions that hash the *whole* sandbox tree before and after, so a file lost in a path nobody named still shows up. Verified to drop from 11/11 to 4/11 against a deliberately reintroduced #1018.
+
+`tests/regression/test_gate_integrity.sh` adds 10 more asserting those gates fail when they should. If any of them regress, CI blocks the merge.
+
+## Manual override: disable entirely
+
+If you never want the automation:
+
+```bash
+touch ~/.dotfiles.icloud-skip
+```
+
+The script sees this file in the first 5 lines of execution and exits 0 immediately, without touching the filesystem.

package/docs/index.md

@@ -17,7 +17,7 @@ render_with_liquid: false
   <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>
+  <a href="ARCHITECTURE/">Architecture</a>
 </div>
 
 </section>
@@ -88,7 +88,7 @@ render_with_liquid: false
 
     Deterministic templates, feature flags, profiles, `run_onchange_` hooks. Everything lives in `defaults/` and applies to `$HOME` on-demand.
 
-    [→ Architecture](architecture/ARCHITECTURE.md)
+    [→ Architecture](ARCHITECTURE.md)
 
 </div>
 
@@ -120,7 +120,7 @@ Once installed:
 
 - [**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.
+- [**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.

package/docs/manual/00-introduction.md

@@ -4,7 +4,7 @@ render_with_liquid: false
 
 # Introduction
 
-This manual describes `.dotfiles` v0.2.519 — a trusted agent workstation baseline for macOS, Linux, and WSL.
+This manual describes `.dotfiles` v0.2.520 — 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

@@ -212,14 +212,39 @@ still work as deprecated aliases. See [AI.md](../../AI.md) for the full guide.
 
 ### `dot mcp`
 
-Inspect MCP policy and registry.
+Inspect MCP policy and registry, or run the MCP server.
 
 ```
-dot mcp [--strict|-s] [--json|-j]
+dot mcp [--strict|-s] [--json|-j]   # audit (default: doctor)
+dot mcp registry [--json|-j]        # show the tracked MCP server registry
+dot mcp serve                       # run the stdio MCP server
 ```
 
 With `--strict`, validates the active MCP registry matches the policy hash. Exit code 1 on mismatch.
 
+#### `dot mcp serve`
+
+Runs the Model Context Protocol server described by
+`.well-known/mcp/server-card.json`: JSON-RPC 2.0 over newline-delimited
+frames on stdin/stdout, with stderr reserved for logs. It is meant to be
+launched by an MCP client, not typed at a prompt:
+
+```json
+{ "mcpServers": { "dotfiles": { "command": "dot", "args": ["mcp", "serve"] } } }
+```
+
+It serves four read-only tools — `mcp-doctor`, `agent-mode`,
+`workstation-attestation` and `fleet-status`, each a fixed `dot` argument
+vector run without a shell — and five resources (the MCP policy, the MCP
+registry, the agent profiles and both discovery cards). Mutating paths
+(`dot mode set`, `dot attest --write`) are deliberately not exposed: a
+client cannot change this workstation through the server.
+
+The binary is `~/.local/bin/dot-mcp`, built by chezmoi from
+[`defaults/dot_local/share/dot-mcp`](../../../defaults/dot_local/share/dot-mcp/README.md);
+when it is missing and a Go toolchain is present, `dot mcp serve` builds
+it on demand into the user cache.
+
 ### `dot mode [<profile>]`
 
 Show or set the agent profile.
@@ -360,7 +385,7 @@ 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`.
+Default registry: `https://sebastienrousseau.github.io/dotfiles/registry.json`. Cache lives under `${XDG_CACHE_HOME:-~/.cache}/dotfiles/registry/`, one `index-<digest>.json` per registry URL, 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).
 

package/docs/manual/command-index.md

@@ -4,9 +4,12 @@ render_with_liquid: false
 
 # Command Index
 
-Generated from `dot help all`. To refresh after adding or renaming
-a subcommand, run `tools/docs/generate-command-index.sh`. The CI
-job `lint/command-index` fails when this file is stale.
+Generated from `dot help all` plus the `dot help <command>` detail
+registry, so a command that is routable and has help text is listed
+even when it is absent from the compact overview. To refresh after
+adding or renaming a subcommand, run
+`tools/docs/generate-command-index.sh`. The CI job
+`lint/command-index` fails when this file is stale.
 
 | Command | Summary |
 |---------|---------|
@@ -42,13 +45,18 @@ job `lint/command-index` fails when this file is stale.
 | `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 apply` | Apply the current dotfiles to this machine. |
 | `dot attest` | Export workstation attestation evidence (--json |
+| `dot autohand` | Run the Autohand CLI with dotfiles context patterns. |
 | `dot backup` | Create a compressed backup of your home |
+| `dot benchmark` | Benchmark shell startup with per-component profiling |
 | `dot bundle` | Create offline archive of dotfiles environment |
 | `dot cache-refresh` | Regenerate shell caches for ultra-fast startup |
 | `dot cd` | Print source directory path (use: cd $(dot cd)) |
 | `dot chaos` | Simulate config corruption to test self-healing |
 | `dot cl` | Claude CLI with context patterns |
+| `dot claude` | Run the Claude CLI bridge (alias for cl). |
+| `dot codex` | Run the OpenAI Codex CLI with dotfiles 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 |
@@ -73,8 +81,12 @@ job `lint/command-index` fails when this file is stale.
 | `dot fleet` | namespace Show or set the active namespace for multi-tenant isolation |
 | `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 goose` | Run the Goose CLI with dotfiles context patterns. |
+| `dot heal` | Auto-repair common dotfiles problems (missing files, broken links). |
+| `dot health` | Run the health dashboard with optional fixes. |
 | `dot help` | Show this help message |
 | `dot history` | Shell history analysis |
+| `dot init` | Bootstrap a foreign dotfiles repo through chezmoi + dot. |
 | `dot keys` | Keybindings (sign-check: verify git signing) |
 | `dot keys` | sign-check Verify git commit-signing configuration and key availability |
 | `dot kimi` | Kimi CLI with context patterns |
@@ -83,9 +95,11 @@ job `lint/command-index` fails when this file is stale.
 | `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 manual` | Open or download the dotfiles manual in HTML, PDF, EPUB, or text. |
+| `dot mcp` | Inspect MCP policy, supply chain, and registry; serve MCP over stdio |
 | `dot mcp` | doctor Run the MCP policy/supply-chain/config audit |
 | `dot mcp` | registry Show the configured MCP server registry |
+| `dot mcp` | serve Run the stdio MCP server (JSON-RPC 2.0 on stdin/stdout) |
 | `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 |
@@ -103,15 +117,18 @@ job `lint/command-index` fails when this file is stale.
 | `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 prewarm` | Alias of cache-refresh — regenerate shell init caches. |
 | `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 qwen` | Run the Qwen Coder CLI with dotfiles context patterns. |
 | `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 restore` | Restore from a backup or git ref. |
 | `dot rollback` | Rollback dotfiles to a previous state |
 | `dot sandbox` | Launch a safe sandbox preview (Docker/Podman) |
 | `dot score` | System health and security scorecard |
@@ -126,6 +143,7 @@ job `lint/command-index` fails when this file is stale.
 | `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 security-score` | Assess workstation security posture. |
 | `dot sgpt` | Shell-GPT with context patterns |
 | `dot snapshot` | Capture baseline system snapshot |
 | `dot ssh-cert` | Manage short-lived SSH certificates |
@@ -150,6 +168,8 @@ job `lint/command-index` fails when this file is stale.
 | `dot upgrade` | Update system toolchains, plugins, and dotfiles |
 | `dot usb-safety` | Disable automount for removable media [Linux] |
 | `dot version` | Show version information. |
+| `dot vibe` | Run the Vibe AI CLI with dotfiles context patterns. |
 | `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 |
+| `dot zai` | Run the ZAI CLI with dotfiles context patterns. |

package/docs/manual/concept-index.md

@@ -9,6 +9,7 @@ Alphabetical list of concepts covered in the manual.
 - Accessibility
 - Adding a New Flag
 - Agent Policy Enforcement
+- Agents
 - AI & Agents
 - Algorithms
 - Apply / Sync
@@ -97,6 +98,7 @@ Alphabetical list of concepts covered in the manual.
 - Read by Tools
 - Recovery
 - Reference
+- Registry
 - Required Binaries
 - Scenario
 - Secret-Related

package/docs/migration/README.md

@@ -0,0 +1,81 @@
+---
+render_with_liquid: false
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
+
+# Migration guides
+
+Coming from another dotfiles manager. One guide per tool, each with
+real commands, a rollback path, and an honest section on what you lose
+by switching.
+
+| You use | Guide | Rough effort |
+|---|---|---|
+| [yadm](https://yadm.io/) | [`from-yadm.md`](from-yadm.md) | 30 min — closest model, both wrap git and template |
+| [GNU Stow](https://www.gnu.org/software/stow/) | [`from-gnu-stow.md`](from-gnu-stow.md) | 1–2 h — symlink farm to managed copies is a real change |
+| A bare git repo (`--git-dir=$HOME/.dotfiles`) | [`from-bare-git-repo.md`](from-bare-git-repo.md) | 45 min |
+| Plain chezmoi, no framework | [`from-plain-chezmoi.md`](from-plain-chezmoi.md) | 10 min — same engine underneath |
+
+Upgrading between versions of *this* project is a different document:
+[`../operations/MIGRATION.md`](../operations/MIGRATION.md).
+
+## Read this first
+
+Three facts that apply to every guide.
+
+**chezmoi is the engine.** This project is a framework *over*
+[chezmoi](https://www.chezmoi.io/), not a replacement for it. Files
+live in a source tree, `chezmoi apply` renders them into `$HOME`, and
+`dot` is a control plane over that. If you already know chezmoi, you
+already know 80% of this.
+
+**Nothing is destroyed without asking.** `chezmoi apply` shows a diff
+first when you run `dot diff`, and `dot sync --check` previews without
+writing. Every guide below tells you to take a backup anyway, because
+"nothing is destroyed" is a claim about the tool, not about your typos.
+
+**You can leave.** `scripts/uninstall.sh --force` runs `chezmoi purge`
+and removes the repo, the chezmoi config and state, caches, and logs.
+Your files stay where they were applied; nothing phones home and
+nothing is left behind to reinstall itself. Each guide ends with the
+rollback for that specific migration.
+
+## The shape of every migration
+
+```sh
+# 1. Back up. Always.
+tar -czf ~/dotfiles-backup-$(date +%F).tar.gz -C "$HOME" \
+  .bashrc .zshrc .config .gitconfig 2>/dev/null || true
+
+# 2. Install the framework (does not touch your files yet).
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+
+# 3. Bring your own files under management, one at a time.
+dot add ~/.gitconfig
+dot add ~/.config/nvim
+
+# 4. Preview, then apply.
+dot diff
+dot sync
+
+# 5. Check the result.
+dot doctor
+```
+
+Step 3 is where the guides differ, because it depends on how your
+current tool stores things.
+
+## Choosing not to switch
+
+Genuinely reasonable reasons to stay where you are:
+
+- **You only symlink a handful of files and never templated anything.**
+  GNU Stow is simpler and does that job well.
+- **You need Windows-native support without WSL or PowerShell 7.**
+- **You do not want a CLI layer.** Plain chezmoi is a smaller surface.
+
+The case for switching is multi-machine fleets, per-host templating,
+multi-shell parity, and signed/attested releases. If none of those
+describe you, the migration cost may not repay itself.

package/docs/migration/from-bare-git-repo.md

@@ -0,0 +1,156 @@
+---
+render_with_liquid: false
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
+
+# Migrating from a bare git repo
+
+The `git --git-dir=$HOME/.dotfiles --work-tree=$HOME` pattern, usually
+behind a `config` alias. No dependencies, no symlinks, no templating —
+and `$HOME` is the work tree, which is the part that has to change.
+
+## Concept mapping
+
+| Bare repo | Here |
+|---|---|
+| `config add ~/.bashrc` | `dot add ~/.bashrc` |
+| `config commit` / `config push` | ordinary `git` inside `$(dot cd)` |
+| `config status` | `dot status` |
+| `config checkout` on a new machine | `dot init <user>` |
+| `.gitignore` with `*` at `$HOME` | not needed — `$HOME` is not a work tree |
+| `showUntrackedFiles = no` | not needed, same reason |
+| Per-host: branches | `.tmpl` files with `{{ if }}` |
+| Nothing | `dot doctor`, `dot heal`, `dot rollback`, secrets, provisioning |
+
+## 1. Inventory and back up
+
+```sh
+alias config='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'
+
+config ls-files > ~/bare-inventory.txt
+wc -l ~/bare-inventory.txt
+tar -czf ~/bare-backup-$(date +%F).tar.gz -C "$HOME" -T ~/bare-inventory.txt
+```
+
+Push first if the repo has a remote — the safest rollback is a clone:
+
+```sh
+config status
+config push
+```
+
+## 2. Note your branch layout
+
+Per-host branches are the one thing that needs a design decision. List
+them before you start:
+
+```sh
+config branch -a
+config log --oneline --graph --all | head -20
+```
+
+Every branch becomes conditional blocks in one file. Diff two branches
+now, while the context is fresh:
+
+```sh
+config diff main work-laptop -- .bashrc
+```
+
+## 3. Install
+
+The bare repo is at `$HOME/.dotfiles`, which is also this project's
+default clone location. The installer detects and refuses to clobber
+it, but move it first to avoid the confusion entirely:
+
+```sh
+mv "$HOME/.dotfiles" "$HOME/.dotfiles.bare.bak"
+alias config='git --git-dir=$HOME/.dotfiles.bare.bak --work-tree=$HOME'
+
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
+```
+
+Your files in `$HOME` are untouched by the move — only the git
+metadata directory changed name.
+
+## 4. Import
+
+```sh
+while read -r f; do
+  [ -e "$HOME/$f" ] && dot add "$HOME/$f"
+done < ~/bare-inventory.txt
+
+dot status
+```
+
+## 5. Collapse branches into templates
+
+Take the differences you diffed in step 2 and express them as
+conditions in a single `.tmpl`:
+
+```text
+export EDITOR=nvim
+{{ if eq .chezmoi.hostname "work-laptop" }}
+export HTTP_PROXY=http://proxy.corp:3128
+export NPM_CONFIG_REGISTRY=https://nexus.corp/repository/npm/
+{{ end }}
+{{ if eq .chezmoi.os "darwin" }}
+export HOMEBREW_NO_ANALYTICS=1
+{{ end }}
+```
+
+Rendering is testable without applying:
+
+```sh
+chezmoi execute-template < defaults/dot_bashrc.tmpl
+```
+
+## 6. Apply and verify
+
+```sh
+dot diff
+dot sync
+dot doctor
+
+while read -r f; do
+  [ -e "$HOME/$f" ] || echo "MISSING: $f"
+done < ~/bare-inventory.txt
+```
+
+## 7. Clean up
+
+```sh
+# Only if you had the $HOME/.gitignore containing '*' trick:
+grep -q '^\*$' "$HOME/.gitignore" 2>/dev/null && $EDITOR "$HOME/.gitignore"
+
+# Remove the alias from your shell rc, then, once confident:
+rm -rf "$HOME/.dotfiles.bare.bak"
+```
+
+Do not remove the backup until you have pushed the new source tree
+somewhere and used it for a while.
+
+## Rolling back
+
+```sh
+bash ~/.dotfiles/scripts/uninstall.sh --force
+mv "$HOME/.dotfiles.bare.bak" "$HOME/.dotfiles"
+git --git-dir=$HOME/.dotfiles --work-tree=$HOME checkout -- .
+```
+
+Or, if you pushed in step 1, clone the remote bare again — which is
+why step 1 says to push.
+
+## What you gain, what you lose
+
+**Gain:** templating instead of branch-per-host (the bare-repo
+pattern's real weakness: merging a change across five host branches);
+a CLI with diagnostics and repair; secrets; provisioning hooks;
+multi-shell parity; signed releases.
+
+**Lose:** zero dependencies. The bare-repo trick needs nothing but
+git, and that is a genuine virtue — especially on a locked-down host.
+You also lose `$HOME` as a work tree, so `git status` there no longer
+tells you what changed; `dot status` does. And the setup no longer
+fits in a three-line shell alias you can retype from memory.