@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/docs/archive/EUXIS_2026_REVIEW.md

@@ -1,127 +0,0 @@
----
-render_with_liquid: false
----
-
-# Euxis 2026 Architecture & Product Review
-
-This review translates the current dotfiles CLI stack into an Apple-tier product strategy:
-high power, near-zero cognitive load, and cross-platform parity (macOS, Linux, WSL).
-
-## Current state (what is already strong)
-
-- Unified entrypoint (`dot`) with modular command routing.
-- Good safety baseline (strict mode, governance, preflight checks).
-- Broad CI coverage with strong shell quality gates.
-- WSL support already exists but is distributed across scripts.
-
-## Gaps to close for Apple-tier quality
-
-### Performance and responsiveness
-
-- `dot doctor` scans broad filesystem paths and can feel slow on large homes.
-- Platform detection logic is duplicated across scripts.
-- Source directory resolution repeats file system probes in hot paths.
-
-### UX and cognitive load
-
-- Cross-platform behavior is implicit, not surfaced as a simple product contract.
-- Users still need to understand host/guest boundaries (especially WSL).
-- Onboarding signal is fragmented across docs and command help.
-
-### Product parity
-
-- No single abstraction layer for path conversion and host-native opening.
-- No first-class “platform parity” diagnostics in one section.
-
-## Implemented in this branch
-
-### 1) Platform abstraction layer
-
-Added `scripts/dot/lib/platform.sh` with:
-
-- `dot_platform_id`
-- `dot_host_os`
-- `dot_is_wsl`
-- `dot_path_to_unix`
-- `dot_path_to_native`
-- `dot_open_path`
-
-This centralizes platform semantics and removes per-script drift.
-
-### 2) Hot-path optimization in shared utils
-
-Updated `scripts/dot/lib/utils.sh`:
-
-- sources `platform.sh`
-- adds process-local source dir cache (`_DOT_SOURCE_DIR_CACHE`)
-- avoids repeated filesystem checks in repeated command flows
-
-### 3) Faster, clearer diagnostics
-
-Updated `scripts/diagnostics/doctor.sh`:
-
-- new **Platform** section (runtime + host + WSL bridge/fallback checks)
-- warns when running in `/mnt/*` under WSL (high IO latency path)
-- scoped symlink scan to standard roots only (`~/.config`, `~/.local`, `~/.ssh`)
-- adds explicit `dot` command resolution check
-
-### 4) Onboarding clarity
-
-Updated `README.md`:
-
-- added “60-second onboarding” with a clear success state
-
-### 5) Test coverage for new abstraction
-
-Added `scripts/tests/unit/test_dot_lib_platform.sh`:
-
-- existence + syntax + function presence + return contract checks
-
-## File-by-file next refactors (high ROI)
-
-1. `scripts/dot/commands/tools.sh`
-
-- Split `cmd_aliases` into submodule file.
-- Replace repeated `command -v` checks with cached capability map.
-
-1. `dot_config/zsh/dot_zshrc.tmpl`
-
-- Add startup budget guard (record startup time; warn >400ms).
-- Move optional integrations behind capability checks generated once/session.
-
-1. `scripts/ops/health-check.sh`
-
-- Import `platform.sh`, unify WSL/macOS/Linux branch logic.
-- Emit machine-readable JSON summary for UI frontends.
-
-1. `scripts/diagnostics/perf.sh`
-
-- Add percentile reporting (P50/P95 over 10 runs).
-- Add regression threshold with actionable remediation hints.
-
-## Product roadmap (prioritized)
-
-### P0 (1-2 weeks)
-
-- Platform abstraction adoption across all dot commands.
-- Bounded diagnostic scans everywhere (`find` scope + timeout).
-- “Single-screen health” command output format harmonization.
-
-### P1 (2-4 weeks)
-
-- Local state model for predictive UX (`~/.local/state/dotfiles/session.json`).
-- Adaptive hints (“next best action”) based on detected failures.
-- Non-blocking diagnostics execution with staged rendering.
-
-### P2 (4-8 weeks)
-
-- Optional Rust helper binary for path/process abstraction and fast JSON output.
-- WASM-compatible policy engine for deterministic config validation.
-- Cross-device state sync model (privacy-first, local-first defaults).
-
-## Apple-tier UX bar (acceptance criteria)
-
-- First successful install + health check in under 90 seconds.
-- `dot doctor` completes in under 700ms on warmed cache.
-- No user-facing distinction between macOS/Linux/WSL for core commands.
-- All failures return one-line remediation with direct command to fix.

package/docs/archive/LEGACY_ROADMAP.md

@@ -1,6 +0,0 @@
-# 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/archive/MILESTONE_v0.2.493.md

@@ -1,47 +0,0 @@
----
-render_with_liquid: false
----
-
-# Milestone v0.2.493 Scope
-
-This milestone keeps scope intentionally small and operationally focused.
-
-## Goals
-
-- Make post-merge verification a first-class workflow (`dot verify`).
-- Keep protected-branch CI deterministic (no unsigned bot commits on `master`).
-- Improve day-2 operator confidence with explicit verification guidance.
-
-## In Scope
-
-- [x] Add `dot verify` command routing in diagnostics module.
-  - `scripts/dot/commands/diagnostics.sh`
-  - `bin/dot`
-- [x] Add verification runner script.
-  - `scripts/diagnostics/verify.sh`
-  - Runs:
-    - `dot doctor`
-    - `dot status`
-    - `chezmoi diff`
-- [x] Update completion surfaces for new command.
-  - `dot_local/share/bash-completion/completions/dot`
-  - `dot_local/bin/executable_dot_completion`
-- [x] Harden sync-versions behavior for protected `master`.
-  - `.github/workflows/sync-versions.yml`
-  - `master` now verifies only; auto-sync commit job runs on non-master branches.
-- [x] Update docs and command references.
-  - `README.md`
-  - `docs/README.md`
-  - `docs/OPERATIONS.md`
-
-## Out of Scope
-
-- New security controls beyond existing baseline.
-- Major CLI redesign or command namespace reshuffle.
-- Release process automation changes outside sync-versions policy hardening.
-
-## Exit Criteria
-
-- `dot verify` returns non-zero on drift/issues and zero when healthy.
-- `sync-versions` workflow no longer attempts commits to protected `master`.
-- Relevant unit tests and targeted command tests pass.

package/docs/archive/PLAN.md

@@ -1,199 +0,0 @@
----
-render_with_liquid: false
----
-
-# Universal Configuration Plan (Chezmoi)
-
-... [Previous Sections Unchanged] ...
-
-# Phase 15: Operational Documentation [COMPLETED]
-
-- [x] **Guide**: Created `OPERATIONS.md`.
-
-# Phase 16: Final Release Verification [COMPLETED]
-
-- [x] **Verification**: All systems passed.
-
-# Phase 17: Structural Optimizations (v0.3.0)
-
-## Goal
-
-Implement structural improvements for better organization and maintainability, anticipating v0.3.0.
-
-## Proposed Changes
-
-### [REFACTOR] Semantic Organization
-
-- **Move**: `dot_config/dotfiles` -> `dot_config/shell`.
-- **Reason**: `dotfiles` is redundant inside a dotfiles repo. `shell` describes the content (aliases, paths, functions).
-- **Update**: Update references in `dot_zshrc.tmpl` and install scripts.
-
-### [REFACTOR] Script Installation
-
-- **Move**: `bin/` -> `dot_local/bin/`.
-- **Reason**: Ensures scripts are automatically installed to `~/.local/bin` (user PATH).
-
-### [CLEANUP] Remove Legacy Files
-
-- **Delete**: `Makefile`, `package.json`.
-- **Reason**: Replaced by `chezmoi` and GitHub Actions.
-
-### [REFACTOR] Script Segregation
-
-- **Split**: `run_onchange_install_packages.sh.tmpl` into:
-  - `run_onchange_darwin_install-packages.sh.tmpl` (Homebrew)
-  - `run_onchange_linux_install-packages.sh.tmpl` (Apt)
-  - `run_onchange_after_install-vim-plug.sh.tmpl` (Universal)
-- **Reason**: Improves readability and maintainability.
-
-# Phase 18: Component Documentation Polish [COMPLETED]
-
-## Goal
-
-Update component documentation (`aliases`, `functions`, `paths`) to match the new `chezmoi` architecture and ensure accuracy.
-
-## Changes
-
-- **Aliases**: Updated `aliases/README.md` to explain modular `*.aliases.sh` loading.
-- **Functions**: Updated `functions/README.md` to remove legacy install instructions.
-- **Paths**: Updated `paths/README.md` to clarify precedence and `chezmoi` integration.
-- **Cleanup**: Standardized all nested alias READMEs to remove legacy HTML artifacts and restore banners.
-
-# Phase 19: Toolchain Expansion [COMPLETED]
-
-## Goal
-
-Add comprehensive support for modern DevOps/Cloud engineering tools.
-
-## Proposed Changes
-
-### [NEW] Aliases
-
-- **Kubernetes**: `kubectl` shortcuts (`k`), `helm`, `k9s`.
-- **IaC**: `terraform` (`tf`), `opentofu`, `ansible`.
-- **Languages**: `go` (`g`), `yarn`, `uv` (modern Python).
-- **Diagnostics**: `jq`, `yq`, `nc`, `curlie`.
-- **Structure**: Each component gets its own directory in `.chezmoitemplates/aliases/` with a standard `README.md`.
-
-# Phase 20: Intelligent Assistance [COMPLETED]
-
-## Goal
-
-Integrate AI capabilities and improved help systems.
-
-## Proposed Changes
-
-### [NEW] Functions
-
-- **`dothelp`**: Index and search all aliases/functions with descriptions.
-- **AI Wrappers**: Aliases for `gh copilot`, `fabric`, or generic LLM CLI tools.
-
-# Phase 22: Automated Testing [COMPLETED]
-
-## Goal
-
-Verify the dotfiles work on clean Linux environments.
-
-## Proposed Changes
-
-### [CI] GitHub Actions
-
-- **Container Job**: Run `chezmoi init --apply` inside a localized Docker container (Ubuntu/Fedora) to prove universal compatibility.
-
-# Phase 23: Enterprise Core & Security (The Trust Layer) [COMPLETED]
-
-## Goal
-
-Establish a "Trust Layer" for the dotfiles ecosystem, ensuring supply chain security and configuration integrity.
-
-## Changes
-
-- **SLSA & SBOM**: Implemented `security-release.yml` for provenance and SBOM generation.
-- **Signing**: Created `enable-signing` wizard alias for streamlined GPG/SSH configuration.
-- **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.
-
-- **Immutability**: Created `lock-configs.sh` script and `lock-configs`/`unlock-configs` aliases.
-
-# Phase 27: Self-Healing & Diagnostics [COMPLETED]
-
-## Goal
-
-Enable the system to self-diagnose and repair configuration drift.
-
-## Changes
-
-- **Scripts**: Created `scripts/diagnostics/doctor.sh` for system health checks.
-- **Aliases**: Added `dot doctor`, `dot drift` (`chezmoi verify`), and `dot heal` (`chezmoi apply`).
-
-# Phase 51: Regulatory Compliance [COMPLETED]
-
-## Goal
-
-Document and enforce compliance with SOC2, ISO, and GDPR standards.
-
-## Changes
-
-- **Documentation**: Created `COMPLIANCE.md` with control mappings.
-- **Privacy**: Added `privacy-mode` alias to disable CLI telemetry.
-- **Audit**: Added `dot audit` alias for tracking changes.
-
-# Phase 54: macOS Deep Integration [COMPLETED]
-
-## Goal
-
-Harden and optimize the macOS environment via code.
-
-## Changes
-
-- **Defaults**: Created `run_onchange_darwin_defaults.sh.tmpl` to apply secure/optimized `defaults`.
-- **Hardening**: Enabled screensaver passwords, firewall settings, and disabled guest access.
-
-## Goal
-
-Ensure legal compliance and proper attribution for the open-source project.
-
-## Changes
-
-- **Licensing**: Added `scan-licenses` alias (Trivy/FOSSology).
-- **Headers**: Added `add-headers` alias for automated copyright insertion.
-- **Compliance**: Added `check-cla` and `gen-notice` tools.
-
-# Phase 59: Font Typography [COMPLETED]
-
-## Goal
-
-Standardize typography and ensure high-quality font rendering across all environments.
-
-## Proposed Changes
-
-- **Nerd Fonts**: Automate installation of `JetBrainsMono Nerd Font` and `Symbols Nerd Font`.
-- **Fontconfig**: Deploy XML configuration for Linux font rendering (antialiasing, hinting).
-- **Aliases**: `update-fonts` to refresh font caches (`fc-cache`).
-
-# Phase 26: OS Bundling & Compliance [COMPLETED]
-
-## Goal
-
-Prepare the dotfiles for system-wide deployment and ensure strict adherence to standards.
-
-## Proposed Changes
-
-- **XDG Compliance**: Audit `00-default.paths.sh` to ensure all standard XDG variables are exported.
-- **Vendor Hooks**: Update `dot_zshrc.tmpl` to source system-level overrides from `/etc/dotfiles/defaults.d/` (Simulates "site-local" config).
-- **Bundling**: Create `scripts/core/package.sh` to create a distributable tarball and scaffold `.deb`/`.pkg` generation logic.
-
-# Phase 24: The Universal Installer (Zero-Dependency) [COMPLETED]
-
-## Goal
-
-Provide a frictionless, "one-curl" onboarding experience and capabilities to deploy configurations remotely.
-
-## Proposed Changes
-
-- **install.sh**: A standalone, zero-dependency bash script that:
-    1. Detects OS/Arch.
-    2. Installs `chezmoi` (binary or via package manager).
-    3. Initializes the dotfiles repo.
-    4. Runs `chezmoi apply`.
-    5. Uses ANSI colors for a polished "TUI" feel.
-- **Teleportation**: `scripts/ops/teleport.sh` using `chezmoi archive` piped to SSH to ephemeralize configs on remote servers (e.g., `dot teleport user@server`).

package/docs/archive/REPO_AUDIT.md

@@ -1,31 +0,0 @@
----
-render_with_liquid: false
----
-
-# Repo Audit
-
-## Source of truth
-
-- `~/.dotfiles` (chezmoi source directory)
-
-## Key directories
-
-- `.chezmoitemplates/` - templated aliases, functions, paths
-- `dot_config/` - configs mapped into `~/.config`
-- `dot_local/` - binaries and local data (e.g., `dot` CLI)
-- `scripts/` - diagnostics, tests, tooling
-- `tests/` - sandbox Dockerfile
-- `nix/` - optional Nix toolchain
-
-## Notable dependencies
-
-- `chezmoi`
-- `zsh`, `starship`
-- `neovim`
-- `ripgrep`, `fd`, `bat`, `fzf`, `zoxide`
-- `lazygit`
-
-## Notes
-
-- Repo-only files excluded via `.chezmoiignore`.
-- Secrets are handled via `age` + `dot secrets` (see `docs/SECRETS.md`).

package/docs/articles/.pages

@@ -1,6 +0,0 @@
-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

@@ -1,216 +0,0 @@
----
-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).