@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/{WSL2_NIX_TROUBLESHOOTING.md → guides/WSL2_NIX_TROUBLESHOOTING.md}

@@ -43,8 +43,8 @@ ls -la ~/.dotfiles/
 2. **Use WSL2 native filesystem**:
    ```bash
    # Move dotfiles to WSL2 filesystem
-   cd /home/$USER
-   git clone https://github.com/yourusername/dotfiles.git .dotfiles
+   cd ~
+   git clone https://github.com/sebastienrousseau/dotfiles.git .dotfiles
    ```
 
 3. **Configure Git for WSL2**:
@@ -60,7 +60,7 @@ time ls -la /mnt/c/Users/
 time ls -la ~/
 ```
 
-**Solution:** Always work within WSL2 filesystem (`/home/`) for performance-critical operations.
+**Solution:** Always work within WSL2 filesystem (`~/`) for performance-critical operations.
 
 #### Problem: Permission denied errors on mounted Windows drives
 ```bash
@@ -344,7 +344,7 @@ rm -rf ~/.config/chezmoi/
 
 # 4. Reinstall from scratch
 cd /tmp
-curl -fsSL https://raw.githubusercontent.com/yourusername/dotfiles/main/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh | bash
 ```
 
 #### Scenario: WSL2 completely broken
@@ -361,7 +361,7 @@ wsl --unregister Ubuntu
 wsl --import Ubuntu C:\WSL\Ubuntu Ubuntu-backup.tar
 
 # 4. Reinstall dotfiles
-wsl -d Ubuntu -u root -- curl -fsSL https://raw.githubusercontent.com/yourusername/dotfiles/main/install.sh | bash
+wsl -d Ubuntu -u root -- curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh | bash
 ```
 
 ### Partial Recovery
@@ -455,8 +455,8 @@ git config --get core.editor
 #### Optimize filesystem performance
 ```bash
 # 1. Move frequently accessed files to WSL2 filesystem
-mkdir -p /home/$USER/workspace
-ln -s /home/$USER/workspace ~/workspace
+mkdir -p ~/workspace
+ln -s ~/workspace ~/workspace
 
 # 2. Configure Git for performance
 git config --global core.preloadindex true
@@ -652,7 +652,7 @@ echo "Diagnostic report saved to ~/diagnostic-report.txt"
 ```
 
 #### Support channels
-- GitHub Issues: [Repository Issues](https://github.com/yourusername/dotfiles/issues)
+- GitHub Issues: [Repository Issues](https://github.com/sebastienrousseau/dotfiles/issues)
 - WSL2 Documentation: [Microsoft WSL Docs](https://docs.microsoft.com/en-us/windows/wsl/)
 - Nix Documentation: [Nix Manual](https://nixos.org/manual/nix/stable/)
 - Community Support: Stack Overflow, NixOS Discourse

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)