@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/index.md

@@ -0,0 +1,39 @@
+# .dotfiles
+
+Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL.
+
+[![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.500-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.500)
+[![Downloads](https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases)
+
+This site is published from the `docs/` directory on `master` and tracks the current workstation baseline, operational guidance, and security material for the repository.
+
+## Start Here
+
+- [Repository README](https://github.com/sebastienrousseau/dotfiles#readme)
+- [Install guide](guides/INSTALL.md)
+- [Troubleshooting](guides/TROUBLESHOOTING.md)
+- [Support matrix](reference/SUPPORT_MATRIX.md)
+
+## Workstation Operations
+
+- [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)
+
+## Security and Governance
+
+- [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)
+
+## Current Release
+
+- Current tagged release: [`v0.2.500`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.500)
+- Latest release feed: [GitHub releases](https://github.com/sebastienrousseau/dotfiles/releases/latest)
+- Source repository: [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles)

package/docs/interop/A2A.md

@@ -0,0 +1,32 @@
+# Agent Interop
+
+The repository now ships an agent card and an A2A-ready discovery document.
+
+Artifacts:
+- [agent-card.json](/home/seb/.dotfiles/dot_config/dotfiles/agent-card.json)
+- [agent.json](/home/seb/.dotfiles/.well-known/agent.json)
+
+Core properties:
+- bounded profiles: `ask`, `plan`, `apply`, `audit`
+- MCP-governed execution
+- workstation attestation export
+- persistent agent session logs
+- replayable checkpoints
+- fleet attestation export
+
+Tracked governance artifacts:
+- policy bundles
+- prompt registry
+- model registry
+
+Session logs are stored in `~/.local/state/dotfiles/agent-sessions.jsonl`.
+Checkpoints are stored in `~/.local/state/dotfiles/checkpoints/`.
+
+Validate conformance with:
+
+```bash
+dot agent conformance
+dot agent conformance --strict --json
+```
+
+The current posture is A2A-ready with tracked conformance checks. It exposes identity, governance, checkpoints, and local evidence.

package/docs/manual/00-introduction.md

@@ -0,0 +1,85 @@
+# Introduction
+
+This manual describes `.dotfiles` v0.2.500 — 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.
+
+## Who This Manual Is For
+
+- **Developers** who want a reproducible, signed development environment across machines
+- **Security engineers** who require cryptographic attestation, SBOM, and policy gates
+- **AI agent operators** running Claude Code, Codex, GitHub Copilot, or MCP-aware tooling
+- **Team leads** deploying standardized workstations across a fleet
+
+The content assumes basic familiarity with Git, shell environments, and chezmoi. No prior knowledge of the specific tools used (Mise, Nix, Age, SOPS, MCP) is required.
+
+## What the Manual Covers
+
+- **Concepts** — the mental model behind the theme engine, trust model, fleet architecture, and self-healing
+- **Tutorials** — step-by-step walkthroughs for common tasks
+- **Reference** — every `dot` command, every config file, every template variable, every feature flag
+- **Cookbook** — 30+ specific recipes for day-to-day tasks and troubleshooting
+- **Appendices** — platform support matrix, security checklist, glossary, bibliography
+
+## Getting the Manual
+
+The manual is published in nine formats — all generated from the same Markdown source on every release:
+
+| Format | Size | Use case |
+|:---|---:|:---|
+| HTML (single page) | ~200K | Offline browsing |
+| HTML (multi-page) | — | Web reading |
+| HTML gzipped (single) | ~50K | Fast download |
+| EPUB | ~150K | E-readers |
+| PDF | ~400K | Printing |
+| ASCII text | ~120K | Terminal pagers |
+| Markdown source | ~80K | Re-processing |
+
+Published at: `https://sebastienrousseau.github.io/dotfiles/manual/`
+
+Fetch from the CLI:
+
+```sh
+dot manual           # open in browser
+dot manual pdf       # download and open PDF
+dot manual text      # pipe plain text to pager
+```
+
+## Quick Install
+
+```sh
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh)"
+dot doctor
+```
+
+Requires `git` and `curl`. Supported on macOS 14+, Ubuntu/Debian, Arch, Fedora, openSUSE, and WSL2.
+
+## Conventions Used in This Manual
+
+| Convention | Meaning |
+|:---|:---|
+| `fixed-width` | Commands, file paths, environment variables |
+| **Bold** | Important terms introduced for the first time |
+| > Note: | Supplementary information |
+| > Warning: | Actions with potentially destructive effects |
+
+Command placeholders use `<angle-brackets>`. Optional arguments use `[brackets]`. Repeated arguments end with `...`.
+
+## How to Read This Manual
+
+- **First-time users** — read [Introduction](#introduction), [First Install](02-tutorials/01-first-install.md), then browse the [Cookbook](04-cookbook/01-recipes.md).
+- **Upgrading** — read the [Migration section](../operations/MIGRATION.md) for your version delta.
+- **Deep diving** — the [Concepts](01-concepts/) chapters explain the architecture and rationale.
+- **Looking something up** — use the [Command Index](command-index.md) or [Concept Index](concept-index.md).
+
+## Licensing
+
+The `.dotfiles` repository is licensed under the MIT License. See [Appendix E](05-appendices/E-license.md) for the full text.
+
+Individual tools packaged, referenced, or templated by this repository retain their original licenses.
+
+## Reporting Issues
+
+- **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

package/docs/manual/01-concepts/01-architecture.md

@@ -0,0 +1,134 @@
+# Architecture
+
+`.dotfiles` is composed of four loosely coupled subsystems, coordinated by a single command-line interface.
+
+## The Four Subsystems
+
+### 1. Templating Engine — Chezmoi
+
+[Chezmoi](https://chezmoi.io) reads the source directory (`~/.dotfiles/` or `~/.local/share/chezmoi/`), renders templates using data from `.chezmoidata.toml`, and writes the results to the target paths in `$HOME`.
+
+Every file in the source directory follows chezmoi naming conventions:
+
+| Prefix / Suffix | Effect |
+|:---|:---|
+| `dot_` | Deployed with leading `.` (`dot_zshrc` → `~/.zshrc`) |
+| `executable_` | Sets `+x` permission on the destination |
+| `private_` | Sets `0600` permission on the destination |
+| `.tmpl` | Processed as a Go template with chezmoi data |
+| `run_onchange_` | Script runs when the target changes |
+| `run_before_` | Script runs before apply |
+| `run_after_` | Script runs after apply |
+
+### 2. Runtime Management — Mise and Nix
+
+**Mise** ([mise.jdx.dev](https://mise.jdx.dev)) manages per-user language runtimes and CLI tools. All entries in `~/.config/mise/config.toml` are installed to `~/.local/share/mise/installs/`, activated by PATH shimming. No system-level packages are touched.
+
+**Nix Flakes** (`nix/flake.nix`) provide strictly reproducible builds when Mise's approximate semver-pinning is insufficient — for example, for declaring an entire system via Home Manager.
+
+### 3. The `dot` CLI
+
+`dot` is the entry point for all lifecycle operations. It is a pure Bash script (no runtime dependencies) that dispatches to command handlers in `scripts/dot/commands/`.
+
+Each command is self-contained — any command can be invoked directly as a script if needed:
+
+```sh
+bash ~/.dotfiles/scripts/dot/commands/diagnostics.sh doctor
+# equivalent to:
+dot doctor
+```
+
+The CLI follows a grouping convention (see [dot CLI Reference](../03-reference/01-dot-cli.md)):
+
+- **Lifecycle** — `sync`, `apply`, `rollback`, `heal`, `bundle`
+- **Diagnostics** — `doctor`, `drift`, `benchmark`, `score`, `metrics`
+- **AI & Agents** — `ai`, `mcp`, `agent`, `mode`
+- **Configuration** — `theme`, `env`, `profile`, `secrets`
+- **Fleet** — `fleet`, `attest`
+- **Reference** — `help`, `search`, `version`, `manual`
+
+### 4. Secrets and Attestation
+
+Secrets are encrypted at rest using **Age** (modern file encryption) with **SOPS** (YAML-aware envelope) or `chezmoi encrypt`. The private key never leaves `~/.config/age/keys.txt` (or the user's password manager).
+
+Attestation produces signed, machine-readable JSON recording:
+
+- Host identity (kernel, arch, hostname hash)
+- Policy hash (MCP policy, agent profiles)
+- Tool versions (mise, nix, key binaries)
+- Git HEAD and signature status
+- Timestamp and verification hash
+
+See [Trust Model](02-trust-model.md) for the full threat model.
+
+## Data Flow
+
+```mermaid
+graph TD
+    User[User Shell] --> CLI{dot CLI}
+
+    CLI --> L[Lifecycle Commands]
+    CLI --> D[Diagnostics Commands]
+    CLI --> A[AI Commands]
+    CLI --> C[Config Commands]
+    CLI --> F[Fleet Commands]
+
+    L --> Chezmoi[Chezmoi Engine]
+    C --> Chezmoi
+
+    Chezmoi --> Source[~/.dotfiles source]
+    Source --> Data[.chezmoidata.toml + themes.toml]
+    Source --> Tmpl[.tmpl files]
+
+    Data --> Render[Template render]
+    Tmpl --> Render
+    Render --> Target[~ target paths]
+
+    Target --> Shells[Zsh / Fish / Bash / Nushell]
+    Target --> Apps[Ghostty / Neovim / VS Code / etc.]
+
+    Wallpapers[~/Pictures/Wallpapers/ + System] --> KMeans[K-Means CIELAB engine]
+    KMeans --> ThemesT[themes.toml generated]
+    ThemesT --> Data
+
+    A --> MCP[MCP Policy + Registry]
+    F --> Attest[Signed Attestation Logs]
+```
+
+## Startup Performance Model
+
+Shell startup is optimized via a three-tier caching strategy:
+
+1. **Bake-at-apply-time** — values computed once during `chezmoi apply` (HOSTNAME, platform, OS version) are written directly into config files, avoiding subshells at startup.
+2. **`_cached_eval` pattern** — slow initializers (mise, zoxide, atuin, starship) write their output to `~/.cache/shell/<tool>-init.sh`. Subsequent shells `source` the cache. Cache is invalidated when the binary's mtime changes.
+3. **Lazy loading** — heavy layers (nvm, rbenv, direnv) are loaded on first invocation via shell function stubs.
+
+Target: ≤500ms cold shell startup, ≤100ms per component. Enforced by CI benchmark (see [Performance Reference](../03-reference/01-dot-cli.md#benchmark)).
+
+## Per-Machine Profiles
+
+The `machine` key in `.chezmoidata.toml` (or the per-host override in `~/.config/chezmoi/chezmoi.toml`) selects a hardware preset from `.chezmoidata/hardware.toml`. Presets define:
+
+- Display scale (1.0, 1.5, 2.0)
+- Keyboard modifier hierarchy
+- Performance profile (desktop, laptop, low-power)
+- Feature flags (e.g. `features.dms = true` for Niri on Wayland)
+
+A single source tree deploys correctly to a MacBook, a Surface, a Linux desktop, and a WSL2 session — each rendering a platform-appropriate config.
+
+## Trust Boundaries
+
+| Boundary | Trusted | Untrusted |
+|:---|:---|:---|
+| Source tree | Your Git history, signed commits | Unverified pull requests |
+| Secret store | `~/.config/age/keys.txt` | Environment variables, cloud storage |
+| Attestation logs | Signed by SSH ED25519 key | Unsigned JSON reports |
+| Template data | `.chezmoidata.toml` | User-provided template input |
+
+Every boundary is enforced: unsigned commits fail CI gates, secrets never appear in plaintext git history, attestation logs are hash-chained.
+
+## Next
+
+- [Trust Model](02-trust-model.md) — detailed threat model and verification procedures
+- [Theme Engine](03-theme-engine.md) — K-Means CIELAB pipeline
+- [Fleet Architecture](04-fleet.md) — multi-host deployment model

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

@@ -0,0 +1,178 @@
+# Trust Model
+
+The trust model combines cryptographic signing, local-first secrets, policy-gated agent operations, and machine-verifiable attestation.
+
+## Threat Model Summary
+
+| Threat | Mitigation |
+|:---|:---|
+| Unauthorized code execution on the workstation | Signed commits, shellcheck gates, no `curl | sh` in install path |
+| Secret leakage into Git history | Age/SOPS encryption, gitleaks in CI, `detect-secrets` baseline |
+| Tampered upstream tool | SHA256-pinned chezmoi installer, SBOM + Grype CVE scan |
+| Malicious agent behavior | MCP policy enforcement, agent profile allowlists, attestation logs |
+| Compromised fleet host | Per-host signing keys, attestation comparison, `dot chaos` self-tests |
+| Downgrade attacks | Version-sync enforcement, signed release tags |
+
+## Identity and Signing
+
+### SSH ED25519 for Git
+
+Every commit on `master` is signed with SSH ED25519:
+
+```sh
+git verify-commit HEAD
+# Good "git" signature for you@example.com with ED25519 key SHA256:...
+```
+
+The trust anchor is the signer's public key published in `~/.ssh/allowed_signers`. CI enforces signature verification on every PR.
+
+### Verified Chezmoi Installer
+
+The `install.sh` script prefers `scripts/ci/install-chezmoi-verified.sh`, which:
+
+1. Downloads chezmoi from the upstream release URL
+2. Verifies the SHA256 checksum against a hardcoded, version-pinned value
+3. Falls back to `get.chezmoi.io` only if the verified path is unavailable
+
+No unverified binary is ever executed.
+
+## Secrets
+
+### Three Layers
+
+1. **Repository-managed config** (`dot_config/**/*.tmpl`) — checked into Git, no secrets
+2. **Local-only config** (`~/.config/*.local`) — gitignored, user-edited
+3. **Encrypted secrets** (Age-encrypted `private_*` files, SOPS YAML) — checked in, decrypted on apply
+
+Example encrypted file:
+
+```
+dot_config/api-keys.yaml.sops.yaml  # SOPS-encrypted, safe to commit
+```
+
+Decryption uses the user's Age private key at `~/.config/age/keys.txt`. Chezmoi invokes `age` or `sops` automatically during apply.
+
+### Secret Scanning
+
+CI runs three independent scanners:
+
+| Scanner | Purpose | Threshold |
+|:---|:---|:---|
+| `gitleaks` | Pattern-based secret detection | Zero leaks on `master` |
+| `detect-secrets` | Baseline-comparing scanner | Zero new secrets vs `.secrets.baseline` |
+| `trufflehog` | Verified-secret scanner (API-tested) | Zero verified secrets |
+
+All three must pass for a commit to be merged.
+
+## Agent Policy Enforcement
+
+AI agent operations (Claude Code, Codex, Copilot, Gemini, etc.) are governed by the **Model Context Protocol (MCP)** policy in `dot_config/dotfiles/mcp.json` and validated by `dot mcp`.
+
+### Policy Structure
+
+```json
+{
+  "policy_version": "2026-01",
+  "allowed_servers": ["fs", "shell", "github"],
+  "denied_tools": ["network.raw", "fs.write:/etc"],
+  "attestation_required": true,
+  "signature": "<ed25519-signature>"
+}
+```
+
+### Enforcement Points
+
+1. **On agent start** — `dot mcp --strict` validates the registry matches the policy hash
+2. **Per-tool call** — MCP-aware agents check the policy before invoking a tool
+3. **On commit** — `dot attest` records the active policy hash in the attestation log
+
+Violations are logged to `~/.local/state/dotfiles/mcp-violations.log` and reported by `dot doctor`.
+
+## Attestation
+
+`dot attest` generates a signed JSON document containing:
+
+```json
+{
+  "version": "0.2.500",
+  "timestamp": "2026-04-16T09:00:00Z",
+  "host": {
+    "hostname_sha256": "...",
+    "kernel": "Darwin 25.4.0",
+    "arch": "arm64"
+  },
+  "identity": {
+    "ssh_key_sha256": "...",
+    "git_signer": "you@example.com"
+  },
+  "policy": {
+    "mcp_policy_sha256": "...",
+    "agent_profile": "architect"
+  },
+  "tools": {
+    "chezmoi": "2.47.1",
+    "mise": "2026.4.0"
+  },
+  "git": {
+    "head": "abc123...",
+    "branch": "master",
+    "signed": true,
+    "verified": true
+  }
+}
+```
+
+The document is:
+
+- Signed with the user's SSH ED25519 key
+- Stored at `~/.local/state/dotfiles/attestation/YYYY-MM-DD-HHMMSS.json`
+- Optionally published to `~/.dotfiles/docs/attestations/` for team review
+
+### Verifying Someone Else's Attestation
+
+```sh
+dot verify --attestation <path>
+# ✓ Signature valid (ED25519)
+# ✓ Policy hash matches repository
+# ✓ Tool versions within supported range
+```
+
+## Fleet Trust Propagation
+
+Across multiple hosts, trust is established by:
+
+1. Each host generates its own SSH key pair
+2. Each host's public key is added to `~/.ssh/allowed_signers` on every other host
+3. Attestations from any host can be verified by any other host
+4. `dot fleet` compares attestations across the fleet and flags drift
+
+See [Fleet Architecture](04-fleet.md) for the full model.
+
+## CI-Level Gates
+
+| Gate | Workflow | Blocks Merge |
+|:---|:---|:---|
+| Signed commits | `ci-enforced.yml` | Yes |
+| Shellcheck zero-warnings | `ci.yml` | Yes |
+| Gitleaks scan | `ci.yml` | Yes |
+| Copyright headers | `ci-enforced.yml` | Yes |
+| 100% unit test coverage | `ci-enforced.yml` | Yes |
+| Reliability (macOS + Linux) | `ci-enforced.yml` | Yes |
+| Checkov infrastructure scan | `ci-enforced.yml` | On severity MEDIUM+ |
+| SBOM (CycloneDX) | `ci.yml` | No (informational) |
+| Grype CVE scan | `ci.yml` | On severity CRITICAL |
+| Lychee link check | `ci.yml` (nightly) | No |
+
+## Principles
+
+- **Local-first** — nothing leaves the workstation unless the user opts in
+- **Zero trust in transit** — every network-fetched artifact is checksum-verified
+- **Machine-readable evidence** — human-readable summaries are backed by signed JSON
+- **Reversible** — `dot rollback` undoes any change with a single command
+
+## See Also
+
+- [Security Policy](../../security/SECURITY.md)
+- [Threat Model](../../security/THREAT_MODEL.md)
+- [MCP Policy Reference](../../security/MCP_POLICY.md)
+- [Attestation Operations](../../operations/ATTESTATION.md)

package/docs/manual/01-concepts/03-theme-engine.md

@@ -0,0 +1,182 @@
+# The Theme Engine
+
+`.dotfiles` generates terminal color palettes directly from wallpaper images. There are no hand-crafted themes — dominant colors are extracted via K-Means clustering in CIELAB color space, mapped to ANSI slots, and enforced to WCAG AAA contrast.
+
+This chapter explains the pipeline end to end.
+
+## The Why
+
+Hand-crafted themes are expensive to maintain and constrain the user to a fixed palette. Wallpaper-driven themes:
+
+- **Adapt to any wallpaper** — drop a new image, run `dot theme rebuild`, get a new theme
+- **Guarantee contrast** — WCAG AAA is enforced algorithmically, not by taste
+- **Avoid IP issues** — the engine never redistributes Apple/Microsoft wallpapers; it works with whatever is already on the user's system
+- **Produce matched pairs** — every wallpaper yields a dark and light variant with a golden-ratio brightness relationship
+
+## The Pipeline
+
+```mermaid
+graph LR
+    A[Wallpaper image<br/>any format] --> B[ImageMagick<br/>downsample + RGB extract]
+    B --> C[Random subsample<br/>2000 pixels]
+    C --> D[sRGB → CIE XYZ → CIELAB]
+    D --> E[K-Means++ clustering<br/>k=8, 3 runs, best inertia]
+    E --> F[Map clusters to<br/>ANSI hue slots]
+    F --> G[Enforce WCAG AAA<br/>contrast adjustments]
+    G --> H[Generate theme TOML<br/>16 ANSI + UI + app mappings]
+```
+
+### Stage 1 — Pixel Extraction
+
+`ImageMagick` resizes the wallpaper to 80×80 maximum dimension (preserving aspect ratio) and emits pixel-by-pixel text output:
+
+```sh
+magick input.heic -resize 80x80\> -depth 8 txt:-
+```
+
+At 80×80 the image has ~6,400 pixels. For dynamic HEIC files (`image.heic[0]`, `image.heic[1]`), each frame is processed independently.
+
+### Stage 2 — Subsampling
+
+2,000 pixels are sampled uniformly from the downsampled image using a seeded PRNG (`random.Random(42)`). This gives a reproducible run and keeps K-Means iteration fast.
+
+### Stage 3 — Color Space Conversion
+
+Each RGB triplet is converted:
+
+1. **sRGB → linear RGB** — gamma correction using the sRGB companding curve
+2. **Linear RGB → CIE XYZ** — D65 illuminant, matrix multiplication
+3. **CIE XYZ → CIELAB** — nonlinear transform; distances in Lab approximate human perception
+
+Why CIELAB? In RGB, a "distance" of 30 between two colors might look identical to one eye and drastically different to another. In CIELAB, Δ*E* distances are perceptually uniform — a Δ*E* of 2 is the threshold for "just noticeable different" regardless of which axis moves.
+
+### Stage 4 — K-Means Clustering
+
+**K-Means++** initialization places initial centroids spread across the color space (reducing "bad seed" failures). The algorithm:
+
+1. Pick one random pixel as centroid 1
+2. For centroids 2..k, pick a pixel with probability proportional to D(x)² (squared distance to nearest existing centroid)
+3. Iterate: assign each pixel to its nearest centroid, recompute centroid as mean of assigned pixels
+4. Stop when assignments stabilize or max iterations reached
+
+We run the algorithm 3 times with different seeds and keep the clustering with lowest inertia (sum of squared distances from each pixel to its centroid). This avoids local minima without the cost of more runs.
+
+### Stage 5 — ANSI Hue Mapping
+
+The 6 chromatic ANSI slots (red, green, yellow, blue, magenta, cyan) are assigned target hue angles:
+
+| ANSI Slot | Target Hue (degrees) |
+|:---|---:|
+| red | 30 |
+| yellow | 95 |
+| green | 145 |
+| cyan | 210 |
+| blue | 275 |
+| magenta | 330 |
+
+For each slot, the engine picks the most chromatic cluster whose hue is nearest to the target. If no cluster is close enough, the color is synthesized by projecting the accent chroma onto the target hue angle.
+
+Structural slots (`c0`/black, `c7`/white, `c8`, `c15`) are computed from the background Lab with fixed lightness offsets — they exist to provide the required contrast ratios, not to carry hue information.
+
+### Stage 6 — WCAG AAA Contrast Enforcement
+
+Every color pair is checked and adjusted:
+
+| Pair | Minimum Ratio |
+|:---|---:|
+| `fg` / `bg` | 7:1 |
+| `accent_text` / `accent` | 7:1 |
+| `c15` / `bg` | 7:1 |
+| `fg` / `sel_bg` | 4.5:1 |
+| `c8` / `bg` | 2.5:1 |
+| `c0` / `bg` | 1.5:1 |
+| `panel` / `bg` | 1.03-2.0 (bounded) |
+| `border` / `bg` | 1.08-3.5 (bounded) |
+
+For the accent, the engine darkens in Lab space until white text has 7:1 contrast. For fg and bright ANSI colors, lightness is adjusted until the target ratio is met. The output is guaranteed AAA on launch — the `test_themes_toml.sh` unit test verifies this for every generated theme.
+
+## Wallpaper Discovery
+
+`rebuild-themes.sh` scans two tiers of wallpapers:
+
+### System Wallpapers
+
+- **macOS** — `/System/Library/Desktop Pictures/*.heic` and `/System/Library/Desktop Pictures/.thumbnails/*.heic`
+- **Linux** — `/usr/share/backgrounds/` and `/usr/share/wallpapers/` (recursive)
+
+### Custom Wallpapers
+
+- `~/Pictures/Wallpapers/*.{heic,jpg,png}` (or `$DOTFILES_WALLPAPER_DIR`)
+
+### Deduplication
+
+Custom wallpapers override system wallpapers on name collision. For Apple's dynamic HEIC files that contain multiple appearances in one file, the engine extracts each frame (`file.heic[0]`, `file.heic[1]`) and generates one theme per appearance.
+
+If a base wallpaper has explicit `-dark` and `-light` variants (e.g. `Big Sur Graphic.heic` + `Big Sur Graphic Dark.heic` + `Big Sur Graphic Light.heic`), the base is skipped to avoid duplicate theme names.
+
+## Dynamic HEIC (Apple Appearance Metadata)
+
+macOS dynamic wallpapers embed the `apple_desktop:apr` XMP metadata — a base64-encoded plist mapping image indices to appearance modes:
+
+```xml
+<rdf:Description rdf:about=""
+  xmlns:apple_desktop="http://ns.apple.com/namespace/1.0/"
+  apple_desktop:apr="YnBsaXN0MDDSAQIDBFFsUWQQABABCA0PERMAAAAAAAABAQAAAAAAAAAFAAAAAAAAAAAAAAAAAAAAFQ=="/>
+```
+
+Decoded:
+
+```xml
+<dict>
+    <key>l</key><integer>0</integer>  <!-- light = image 0 -->
+    <key>d</key><integer>1</integer>  <!-- dark = image 1 -->
+</dict>
+```
+
+`scripts/theme/merge-wallpaper.sh` combines separate dark+light files into a single dynamic HEIC with this metadata:
+
+```sh
+bash scripts/theme/merge-wallpaper.sh           # merge all pairs
+bash scripts/theme/merge-wallpaper.sh tahoe     # merge a specific family
+bash scripts/theme/merge-wallpaper.sh --dry-run # preview
+```
+
+macOS then auto-switches the displayed image based on the current Light/Dark mode — no application-level logic required.
+
+## Caching
+
+Per-wallpaper themes are cached in `~/.cache/dotfiles/themes/<name>.toml`. The cache is invalidated when the wallpaper's mtime is newer than the cached TOML. `dot theme rebuild --force` skips the cache.
+
+Full parallel rebuild of ~150 wallpapers takes ~3-5 minutes on modern hardware (4 parallel jobs, ~4 seconds per wallpaper). Incremental rebuilds (after adding 1-2 new wallpapers) take ~10 seconds.
+
+## Theme Application
+
+`dot-theme-sync` orchestrates the switch across every managed surface:
+
+| Surface | Mechanism |
+|:---|:---|
+| Ghostty | `chezmoi apply config.tmpl` + DBus reload or SIGUSR2 |
+| Alacritty | `chezmoi apply alacritty.toml.tmpl` |
+| Kitty | `chezmoi apply kitty.conf.tmpl` + SIGUSR1 |
+| WezTerm | `chezmoi apply wezterm.lua.tmpl` |
+| Tmux | `chezmoi apply tmux.conf.tmpl` + `source-file` |
+| Neovim | `chezmoi apply` + `--remote-expr` colorscheme switch over socket |
+| VS Code | `chezmoi apply settings.json.tmpl` |
+| GTK | `chezmoi apply gtk.css.tmpl` + `gsettings set gtk-theme` |
+| macOS accent | `defaults write -g AppleAccentColor` + `killall cfprefsd SystemUIServer Dock` |
+| Desktop wallpaper | `osascript` (macOS) or `gsettings picture-uri` (Linux) |
+
+See [Theming Reference](../03-reference/01-dot-cli.md#theme) for the exact command surface.
+
+## Bibliography
+
+- MacQueen, J. (1967). *Some methods for classification and analysis of multivariate observations.* Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability.
+- Arthur, D. & Vassilvitskii, S. (2007). *K-Means++: The advantages of careful seeding.* ACM-SIAM Symposium on Discrete Algorithms.
+- CIE (1976). *Recommendations on uniform color spaces, color-difference equations, psychometric color terms.* Supplement No. 2 to CIE Publication No. 15.
+- W3C (2023). *Web Content Accessibility Guidelines (WCAG) 2.2.* <https://www.w3.org/TR/WCAG22/>
+
+## See Also
+
+- [Theming Guide](../../guides/THEMING.md) — quick-start and troubleshooting
+- [Theme Reference](../../reference/THEMES.md) — data schema and runtime behaviour
+- [Tutorial: Add a Wallpaper](../02-tutorials/02-add-wallpaper.md)