@sebastienrousseau/dotfiles 0.2.510 → 0.2.512

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 This file documents all notable changes to this project.
 
+## v0.2.512 — 2026-07-21
+
+### Added
+
+- **`dot-ui`** — a shared Bubble Tea (Go) renderer for the `dot` CLI: themed
+  tables across all list/table commands, a unified `dot-ui pick` that replaces
+  fzf in the theme picker, and a step-runner façade. Degrades gracefully when
+  Go is absent, so it never fails a `chezmoi apply`.
+- **AI CLIs** — Kimi Code CLI support, with a Kiri compatibility shim.
+- **Themes** — regenerated the full theme set from the updated wallpaper
+  library; system wallpapers are now opt-in (only discovered themes are
+  assembled); `bloom-light` is the new default theme.
+- **`corralctl`** — scheduled daily repo sync.
+- Symlink iCloud Drive folders into home.
+
+### Changed
+
+- **Theme engine overhaul** — terminals always use the dark palette with an
+  AAA light ramp; Apple-consistent light ANSI ramp; accurate wallpaper counts
+  and dominant-colour tracking; `dot-theme-sync` now drives through the shared
+  UI.
+- **mise** — folded `~/mise.toml` overrides into the managed base layer; bumped
+  topgrade to 17.4.0 and dropped the typos pin.
+- Bumped GitHub Actions pins (minor-patch group plus setup-go/node/python,
+  codeql-action, and action-gh-release), folding Dependabot #977 and #978.
+
+### Fixed
+
+- **Themes / terminals** — readable light-mode palettes (fixed bg/fg with
+  AA/AAA ANSI contrast); kitty now renders light themes, is opaque in light
+  mode, and gets a runtime reloader; tmux client redraw across all servers so
+  existing sessions refresh immediately; regen-proof fallback themes; correct
+  macOS accent mapping and per-mode HEIC frame resolution; no workspace freeze
+  or WallpaperAgent restart on apply.
+- **git** — render `allowed_signers` and guard it on a missing key / unset
+  email.
+- **CI / reliability** — portable `timeout` shim for macOS (real `gtimeout`);
+  reliability tests made portable and environment-tolerant; diagnostics
+  scorecard to 100; copyright and coverage gate fixes.
+- **aliases** — the CD-completion load-once guard now actually gates.
+- Push the AUR package to `master`, not `main`.
+
+## v0.2.511 — 2026-07-08
+
+Bug-fix release: restore shell aliases that were silently dropped after the CD-completion fragment.
+
+### Fixed
+
+- **`reload`, `r`, `mkcd`, `quit` — and every alias/function defined after the CD-completion block — were undefined** whenever `compdef` was not yet available when `90-ux-aliases.sh` was sourced (profiles that don't run `compinit`, and fast-startup shells). The zsh branch of `defaults/.chezmoitemplates/aliases/cd/cd-completion.aliases.sh` skipped completion registration with a **file-scope `return 0`**; because that fragment is inlined into the single concatenated `90-ux-aliases.sh`, the bare `return` aborted the whole file, dropping `set_default_aliases()` (which defines `reload` et al.) and everything after it. Replaced the early-return with a positive `if command -v compdef …; then … fi` guard, so only the completion block is skipped when `compdef` is not ready.
+
+### Changed
+
+- **`scripts/version-sync.sh`**: excluded the two dated release write-ups (`docs/articles/2026-07-05-*.md`) from version verification. They record the release they shipped in ("shipped in v0.2.510" + release-tag link) as historical fact; the `--verify` pass was false-flagging those refs as inconsistent even though the update pass correctly leaves them alone.
+
 ## 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.

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.510-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.512-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>
@@ -52,7 +52,7 @@
 
 ```bash
 curl -fsSL -o /tmp/dotfiles-install.sh \
-  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.510/install.sh
+  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.512/install.sh
 echo "d5a04c5e2813a93a63c8ecce9655cf3d107f6068862c6eba84a92cf22f801c7e  /tmp/dotfiles-install.sh" \
   | shasum -a 256 -c
 bash /tmp/dotfiles-install.sh

package/docs/AI.md

@@ -120,6 +120,7 @@ These tools are not installed for you. Install what you want with `dot ai instal
   - `amp` — Sourcegraph's agentic coder
   - `cursor-agent` — Cursor's terminal agent
   - `grok` — xAI's terminal coding agent (Grok Build; needs a SuperGrok / X Premium+ plan)
+  - `kimi` — Moonshot AI's Kimi Code CLI; installed natively to `~/.kimi-code/bin/kimi` and supports native interactive use and one-shot prompts
 
 - **Coding (interactive)** — focused pair-programming assistants:
   - `aider` — Git-aware AI pair programmer
@@ -152,7 +153,7 @@ The old command shapes still work, but print a one-line hint pointing at the new
 | Deprecated | Use instead |
 |------------|-------------|
 | `dot cl` | `dot ai claude` |
-| `dot codex` / `dot copilot` / `dot agy` / `dot goose` | `dot ai codex` / `dot ai copilot` / `dot ai agy` / `dot ai goose` |
+| `dot codex` / `dot copilot` / `dot kimi` / `dot agy` / `dot goose` | `dot ai codex` / `dot ai copilot` / `dot ai kimi` / `dot ai agy` / `dot ai goose` |
 | `dot kiro` / `dot sgpt` / `dot ollama` / `dot opencode` | `dot ai kiro` / `dot ai sgpt` / `dot ai ollama` / `dot ai opencode` |
 | `dot aider` / `dot autohand` / `dot vibe` / `dot qwen` / `dot zai` | `dot ai aider` / `dot ai autohand` / `dot ai vibe` / `dot ai qwen` / `dot ai zai` |
 | `dot ai status` | `dot ai tools` |

package/docs/COPYRIGHT

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

package/docs/architecture/AI_COST_OPTIMIZATION.md

@@ -114,6 +114,7 @@ Providers tracked today:
 | Copilot CLI | `copilot` | yes | no |
 | Gemini CLI | `gemini` | yes | no |
 | Goose | `goose` | yes | no |
+| Kimi CLI | `kimi` | yes | no |
 | Aider | `aider` | yes | no |
 | OpenCode | `opencode` | yes | no |
 | Autohand | `autohand` | yes | no |

package/docs/archive/LEGACY_ROADMAP.md

@@ -1,160 +1,6 @@
----
-render_with_liquid: false
----
-
-# The Ultimate Developer Environment Roadmap
-
-This roadmap outlines the path to a high-performance, super-efficient development machine designed for Rust, Python, and AI on Linux (Zorin OS / T2 Mac hardware).
-
-## Phase 1: Foundation (Completed)
-
-- **Core Shell**: Zsh + Oh My Zsh.
-- **Modern Prompt**: Starship (hooked & active).
-- **Language Managers**: `rustup` (Rust) and `fnm` (Node.js).
-- **Ultra-Fast Python**: `uv` installed.
-- **Basic Modern Tools**: `eza` (ls), `bat` (cat), `fd` (find), `ripgrep` (grep).
-- **Git Enhancements**: `lazygit` (TUI) and `delta` (Diffs).
-- **Multiplexer**: `zellij` installed.
-- **AI**: `ollama` installed locally.
-- **Security**: Firewall (`ufw`) enabled.
-
----
-
-## Phase 2: Speed & Navigation (Completed)
-
-Focus: Reduce friction in filesystem navigation and build times.
-
-### 1. Navigation
-
-- [x] **Zoxide**: Smarter `cd` command that learns your habits (`z directory`).
-- [x] **FZF**: Command-line fuzzy finder. Essential for search history, files, and replacing standard completion.
-- [x] **Yazi**: Blazing fast terminal file manager (Rust-based).
-
-### 2. Rust Optimization
-
-- [x] **Mold**: Use the `mold` linker to speed up Rust compile times by 3x-10x.
-- [x] **Sccache**: Shared compilation cache to speed up recompilations across projects.
-- [x] **Bacon**: Background rust compiler that gives instant feedback on errors.
-
-### 3. Python Optimization
-
-- [x] **Ruff**: Extremely fast Python linter and formatter (replace flake8/black).
-- [x] **Global Config**: Set `uv` to use system Python or managed Python preferences.
-
-### 4. Code Search
-
-- [x] **Ripgrep-all (rga)**: Search inside PDFs, E-Books, zip files, etc.
-
----
-
-## Phase 3: AI Power User (Completed)
-
-Focus: Integrate AI deeply into the workflow.
-
-- [x] **Fabric**: Open-source framework for augmenting humans using AI (installed via `cmd` path).
-- [x] **Open WebUI**: A beautiful web interface for `ollama` (requires Docker).
-- [x] **GitHub Copilot CLI**: Integrate AI assistance directly into the terminal commands.
-- [x] **Local RAG**: Setup tools to chat with your own documents locally (Open WebUI).
-
----
-
-## Phase 4: System Tuning & Hardening (Completed)
-
-Focus: Squeeze every ounce of performance and security from the hardware.
-
-- [x] **Kernel Tuning**: Increase file descriptor limits and optimize TCP stack for lower latency.
-- [x] **Swap Optimization**: Configure `zram` for memory compression (improves performance on 16GB RAM).
-- [x] **Flatpak Overrides**: Secure Flatpak permissions using `Flatseal`.
-- [x] **Automated Updates**: Configure `unattended-upgrades` for security patches.
-
----
-
-## Phase 5: Final Polish (Completed)
-
-- [x] **Global UV Config**: Created `~/.config/uv/uv.toml` for managed python preference.
-- [x] **Roadmap Completion**: Verified all items are 100% complete.
-
----
-
-## Maintenance & Updates
-
-- **Update System**: `sudo apt update && sudo apt upgrade`
-- **Update Rust**: `rustup update`
-- **Update Node**: `fnm install --lts`
-- **Update UV**: `uv self update`
-- **Update Firmware**: `fwupdmgr get-updates`
-
----
-
-## Phase 6: Desktop Environment (Completed)
-
-Focus: Clean, bloat-free, and supercharged GNOME/Zorin experience.
-
-- [x] **Bloatware Removal**: Removed games (`aisleriot`, `mines`, etc.) and media apps (`rhythmbox`, `totem`).
-- [x] **Menu Cleanup**: Created `hide_menu_entries.sh` to deduplicate and hide unwanted entries.
-- [x] **GNOME Extensions**: Installed productivity boosters via `gnome-extensions-cli`:
-  - [x] `Clipboard Indicator`: History management.
-  - [x] `Caffeine`: Prevent auto-suspend.
-  - [x] `Impatience`: Speed up animations.
-  - [x] `Vitals`: System monitoring in top bar.
-- [x] **Memory Tuning**: Optimize GNOME Shell performance.
-
----
-
-## Phase 7: Browser Optimization (Completed)
-
-Focus: Chrome tuned for development and memory efficiency.
-
-- [x] **Settings**: Enable "Memory Saver" and "Energy Saver" via Managed Policies.
-- [x] **Extensions**: Automated installation of developer stack (uBlock, JSON Viewer, React DevTools, Vimium, Refined GitHub).
-- [x] **Profile Separation**: Separate Personal and Work profiles (Manual setup recommendation).
-
----
-
-## Phase 8: Neovim IDE (Completed)
-
-Focus: Building a terminal-based IDE that rivals VS Code for Rust, Python, and AI.
-
-- [x] **Latest Version**: Installed Neovim v0.12.0-dev (Nightly) to resolve plugin stability issues.
-- [x] **Plugin Manager**: Setup `lazy.nvim` with modular config (Restored from **PR #62**).
-- [x] **Core Plugins**:
-  - [x] `Telescope`: Fuzzy finding.
-  - [x] `Treesitter`: Syntax highlighting.
-  - [x] `Harpoon`: Fast file switching.
-  - [x] `Neo-tree`: File explorer.
-- [x] **UI/UX Menus**: Added `dressing.nvim` and `telescope-ui-select.nvim` for modern, searchable selection lists and floating inputs.
-- [x] **LSP & Autocomplete**:
-  - [x] `Mason`: Managing LSPs (rust-analyzer, pyright, ruff).
-  - [x] `Cmp`: Autocompletion engine.
-- [x] **Language Specifics**:
-  - [x] **Rust**: `rustaceanvim` configured.
-  - [x] **Python**: `pyright` + `ruff`.
-- [x] **AI Integration**:
-  - [x] `Copilot.lua`: Enabled (needs `:Copilot auth`).
-  - [x] `CopilotChat.nvim`: Sidebar chat (VS Code style).
-  - [ ] `Avante.nvim`: Skipped (Removed due to complexity/instability).
-- [x] **VS Code Parity Pack**:
-  - [x] `Trouble`: Problems panel.
-  - [x] `Spectre`: Search/Replace.
-  - [x] `Autopairs`: Auto-close brackets.
-  - [x] `Todo-Comments`: TODO/FIXME highlighting.
-  - [x] `Persistence`: Session management.
-
----
-
-## Phase 9: Repository Polish & PR #62 (In Progress)
-
-Focus: Finalize the `dotfiles` repository for public consumption and sync the local "Gold Standard" environment.
-
-- [x] **Repository Sync**:
-  - [x] Clone official repo to `~/dotfiles`.
-  - [ ] Sync validated configuration (Neovim, scripts, tuning) into repository.
-- [ ] **Documentation Update**:
-  - [ ] Refactor `README.md` for the modern architecture.
-  - [ ] Add "Easy Setup" and "Troubleshooting" guides.
-- [ ] **Final PR Submission**:
-  - [ ] Verify clean diff against original PR #62.
-  - [ ] Push updates to PR #62 branch.
-
+# Legacy Roadmap
 
+Legacy roadmap material has been consolidated into the canonical
+[`../../ROADMAP.md`](../../ROADMAP.md).
 
+This archive path is retained only for compatibility with older links.

package/docs/articles/.pages

@@ -0,0 +1,6 @@
+title: Articles
+nav:
+  - index.md
+  - 2026-07-05-fish-startup-abbr.md
+  - 2026-07-05-master-to-main-rename-runbook.md
+  - 2026-07-05-custom-mkdocs-material-dark-theme.md

package/docs/articles/2026-07-05-custom-mkdocs-material-dark-theme.md

@@ -0,0 +1,216 @@
+---
+title: "Custom Documentation Sites in 2026: Building a Distinctive Dark-Themed Developer Reference on MkDocs Material Without Forking"
+description: A three-file recipe for a bespoke MkDocs Material theme — terminal-green on near-black, custom hero + card grid, hash-locked build. No custom_dir, no fork.
+date: 2026-07-05
+---
+
+# Custom Documentation Sites in 2026: Building a Distinctive Dark-Themed Developer Reference on MkDocs Material Without Forking
+
+*Documentation is the public API surface of an open-source project; the difference between the default Material theme and a bespoke palette is the difference between "reads like every other project" and "reads like this specific project".*
+
+*Sebastien Rousseau · Published 5 Jul 2026 · 11 min read*
+
+## Why Documentation Aesthetics Matter in 2026 #
+
+An open-source project's documentation site is the first surface an evaluator touches — before the README, before the release notes, before the code. In 2026, the density of developer-tool competition means that visual differentiation carries measurable weight: does the site feel like a curated product, or does it feel like a Jekyll-Cayman default from 2019? The felt distinction shapes adoption decisions before the reader has read a single sentence.
+
+The reference standard for "distinctive open-source documentation" is [docs.n8n.io](https://docs.n8n.io) — dark, polished, opinionated, immediately identifiable as n8n's. n8n runs on GitBook, a commercial SaaS. Most open-source projects, [.dotfiles](https://doc.dotfiles.io) included, cannot justify GitBook's licensing but can invest in MkDocs Material customisation to achieve equivalent visual distinction on an open-source stack.
+
+This article documents the migration of [doc.dotfiles.io](https://doc.dotfiles.io) from Jekyll's Cayman theme (the default when GitHub Pages serves markdown without a MkDocs configuration) to a fully customised MkDocs Material theme with a terminal-green-on-near-black palette, custom typography, and a hero + card-grid landing page.
+
+## The Custom Docs Theme 2026 Architecture Lens #
+
+MkDocs Material's customisation surface has four distinct layers, each with different capabilities and constraints:
+
+| Layer | Design Decision | Why It Matters | Risk if Mishandled |
+|---|---|---|---|
+| **Palette declaration** | `mkdocs.yml` `theme.palette.primary: custom` + `accent: custom` | Signals to MkDocs Material that CSS custom properties will drive the palette rather than a named preset (green, teal, indigo, etc.) | Named presets constrain the palette to Material Design's colour tokens; `custom` unlocks arbitrary hex values via CSS variables |
+| **CSS custom-property overrides** | `docs/stylesheets/extra.css` sets `--md-primary-fg-color`, `--md-accent-fg-color`, `--md-default-bg-color`, `--md-code-bg-color` under `[data-md-color-scheme="slate"]` | The single source of truth for the palette. Every Material component reads from these variables | Overriding component-level CSS rules rather than variables creates unmaintainable per-component drift as MkDocs Material upgrades |
+| **Component restyling** | Same `extra.css` overrides selectors like `.md-header`, `.md-nav__link`, `.grid.cards > ul > li` | Where the "feels bespoke" work happens — spacing, borders, hover states, gradients, backdrop blur | Under-styling produces "Material Design in a different colour"; over-styling drifts away from Material's ergonomic defaults |
+| **Landing-page markup** | `docs/index.md` with Front-Matter `hide: [navigation, toc]` + `<section class="dot-hero">` + `<div class="grid cards" markdown>` | The homepage is the highest-impact surface; it should not look like a table of contents | Default MkDocs Material index reads like documentation; a custom hero reads like a product page |
+
+## Key Documentation-UX Signals #
+
+| Signal | Operational Benchmark | Reference | Technical Platform Implementation |
+|---|---|---|---|
+| **Time-to-first-CTA** | Hero action button visible above the fold in ≤ 100 ms of first-paint | Landing-page conversion norms | Custom hero section with primary and secondary CTAs immediately below the site title |
+| **Palette Distinctiveness** | Primary accent color is unique to the project, not a Material Design preset | Brand recognition | CSS custom property overrides on `[data-md-color-scheme]` selectors |
+| **Reading Contrast** | WCAG AA compliance on all text-on-background pairs | Accessibility gate | `--md-default-fg-color` (`#e4e7ec`) on `--md-default-bg-color` (`#0b0e14`) = 15.6:1 ratio |
+| **Cognitive Load per Section** | Feature-card grid on landing page (visual chunking) rather than a bulleted link list | Landing-page ergonomics | `<div class="grid cards" markdown>` + 8 cards with material icons |
+| **Build Reproducibility** | `mkdocs.yml` + `docs/stylesheets/extra.css` under version control; hashes locked in `requirements-docs.txt` | Supply-chain hygiene | `pip-compile --generate-hashes` + `pip install --require-hashes` in the Pages workflow |
+| **Cache Cost at Edge** | CDN TTL respected; theme changes propagate to `doc.<domain>` within 10 minutes | Deployment latency | Cloudflare (or equivalent) `max-age=600` on the site |
+
+## Diagnosis: What "Default MkDocs Material" Leaves on the Table #
+
+An out-of-the-box MkDocs Material site with `primary: teal, accent: teal` and no `extra_css` is visually acceptable — but it is one of many thousand acceptable sites that look identically acceptable. The named presets are constrained to Google's Material Design palette; the sidebar, header, and content surface all read as "Material default".
+
+For a project positioning itself as "an opinionated developer platform, not a library", the visual signal that the docs are *the product's* docs — not somebody else's — is a marketing surface, not a decoration. The lift is contained to three files:
+
+- `mkdocs.yml` — palette selector configuration
+- `docs/stylesheets/extra.css` — the actual palette + typography + component overrides
+- `docs/index.md` — hero + card grid replacing the default index
+
+No template overrides (`custom_dir`), no plugin authoring, no JavaScript. All the customisation lives in files MkDocs Material is explicitly designed to consume.
+
+## Remediation: The Three-File Custom Theme #
+
+### `mkdocs.yml` Palette Configuration
+
+The magic value that unlocks CSS-driven colours is `primary: custom` (and `accent: custom`). Under `[data-md-color-scheme="slate"]`, MkDocs Material's dark variant, every component reads its colours from CSS custom properties that we get to define.
+
+```yaml
+theme:
+  name: material
+  font:
+    text: Inter
+    code: JetBrains Mono
+  palette:
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.footer
+    - content.code.copy
+
+extra_css:
+  - stylesheets/extra.css
+```
+
+The `navigation.tabs.sticky` feature keeps the top-level navigation visible on scroll, which pairs with the hero + card grid to keep the site feeling like a product page rather than a scrolling article.
+
+### `docs/stylesheets/extra.css` — Palette + Component Overrides
+
+The stylesheet is organised in five zones: CSS custom properties for the palette, typography, dark-scheme palette overrides, per-component restyling, and the custom hero + grid-card styles.
+
+```css
+:root {
+  --dot-green: #7ee787;         /* terminal green — primary */
+  --dot-green-bright: #b0f5b7;  /* hover / focused */
+  --dot-green-dim: #4a9153;     /* muted */
+  --dot-bg: #0b0e14;            /* near-black base */
+  --dot-bg-elev: #111621;       /* elevated card */
+  --dot-fg: #e4e7ec;
+  --dot-fg-muted: #94a3b8;
+  --dot-border: #1f2937;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-default-bg-color: var(--dot-bg);
+  --md-default-fg-color: var(--dot-fg);
+  --md-primary-fg-color: var(--dot-green);
+  --md-accent-fg-color: var(--dot-green-bright);
+  --md-typeset-a-color: var(--dot-green);
+  --md-code-bg-color: #161b26;
+}
+```
+
+The choice of `#7ee787` (GitHub's terminal green) as the accent is deliberate: it reads as "developer tool" to the target audience without being GitHub-branded, and the WCAG contrast on the `#0b0e14` background exceeds 12:1 for text and 4.5:1 for the accent-on-background — comfortably above AA thresholds.
+
+Component overrides are targeted at the highest-impact surfaces:
+
+```css
+/* Header: blurred backdrop-saturate for a floating feel */
+.md-header {
+  background-color: rgba(11, 14, 20, 0.92);
+  backdrop-filter: saturate(180%) blur(12px);
+  border-bottom: 1px solid var(--dot-border);
+}
+
+/* Grid cards on landing page — hover lift + accent glow */
+.md-typeset .grid.cards > :is(ul, ol) > li {
+  background: var(--dot-bg-elev);
+  border: 1px solid var(--dot-border);
+  border-radius: 12px;
+  transition: transform 180ms ease, border-color 180ms ease;
+}
+.md-typeset .grid.cards > :is(ul, ol) > li:hover {
+  transform: translateY(-2px);
+  border-color: rgba(126, 231, 135, 0.35);
+  box-shadow: 0 8px 24px -8px rgba(0, 0, 0, 0.5);
+}
+```
+
+### `docs/index.md` — Hero + Grid Cards
+
+The landing page is not documentation — it is a product surface. MkDocs Material's `md_in_html` extension allows Markdown to nest inside a custom HTML section:
+
+```markdown
+---
+hide:
+  - navigation
+  - toc
+---
+
+<section class="dot-hero" markdown>
+
+# .dotfiles
+
+<p class="tagline">Cross-platform, signed, local-first dotfiles…</p>
+
+<div class="buttons">
+  <a class="primary" href="guides/INSTALL/">Install →</a>
+  <a href="https://github.com/sebastienrousseau/dotfiles">GitHub</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.
+
+    [→ Shell hub](https://doc.dotfiles.io/reference/UTILS/)
+
+</div>
+```
+
+The `hide: [navigation, toc]` front-matter removes the sidebar and right-column table-of-contents on this page only — the landing page gets the full canvas, sub-pages retain the standard docs layout.
+
+## Verification: Build, Deploy, Contrast #
+
+The custom theme adds ~12 KB of CSS to the built site. Local `mkdocs build --clean` completes in ~2 seconds. The Pages workflow uses hash-locked dependencies (`pip install --require-hashes -r requirements-docs.txt`) to keep the build reproducible across MkDocs Material and its 30+ transitive dependencies.
+
+Accessibility contrast measured on the deployed site:
+
+- Body text (`#e4e7ec` on `#0b0e14`) — **15.6:1** (WCAG AAA)
+- Accent (`#7ee787` on `#0b0e14`) — **12.4:1** (WCAG AAA)
+- Muted text (`#94a3b8` on `#0b0e14`) — **7.2:1** (WCAG AAA)
+
+Cloudflare CDN cache invalidation after Pages deploy: ~10 minutes on `max-age=600`. Fetching the GitHub Pages origin (`sebastienrousseau.github.io/dotfiles/`) reflects the new theme immediately; the CDN-fronted custom domain propagates within one cache TTL.
+
+## Return on Resilience #
+
+| Metric | Before (Jekyll Cayman) | After (Custom MkDocs Material) |
+|---|---|---|
+| Page weight | 2.9 KB | 14.8 KB (compressed 4.2 KB) |
+| Time to visible hero | ~800 ms (no hero) | ~150 ms |
+| WCAG AA compliance | Passes body text; hero absent | Passes AAA on all text pairs |
+| Landing-page CTAs | 0 (link list only) | 4 (primary + 3 secondary) |
+| Visual differentiation from default | Zero | Distinctive palette + hero + grid |
+| Build reproducibility | Jekyll on `github-pages` gem (unpinned transitive deps) | `pip install --require-hashes` (fully locked) |
+
+## Takeaways #
+
+1. **`primary: custom` + `extra_css` beats theme forking.** No `custom_dir`, no Jinja templates, no plugin authoring. All the customisation lives in files MkDocs Material is explicitly designed to consume.
+
+2. **CSS custom properties are the maintainable seam.** Overriding `--md-primary-fg-color` scales; overriding `.md-header a.md-header__button:not(...)` selectors doesn't.
+
+3. **Treat the landing page as a product surface, not documentation.** Front-matter `hide: [navigation, toc]` unlocks the full canvas. Hero + card grid + tabbed quick-start reads as a product page.
+
+4. **Lock the docs-build supply chain.** `pip-compile --generate-hashes` + `pip install --require-hashes` closes the Scorecard `PinnedDependenciesID` alert and prevents transitive-dep drift in Pages deploys.
+
+5. **Measure contrast, not just aesthetics.** WCAG AAA on body text is achievable with the right palette; it's not a tradeoff against distinctiveness.
+
+The reference implementation landed as [PR #960](https://github.com/sebastienrousseau/dotfiles/pull/960) and is live at [doc.dotfiles.io](https://doc.dotfiles.io); the theme source lives at [`docs/stylesheets/extra.css`](https://github.com/sebastienrousseau/dotfiles/blob/main/docs/stylesheets/extra.css).