@sebastienrousseau/dotfiles 0.2.520 → 0.2.522

package/docs/index.md

@@ -1,132 +0,0 @@
----
-title: .dotfiles — dark, signed, cross-platform
-description: Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL.
-hide:
-  - navigation
-  - toc
-render_with_liquid: false
----
-
-<section class="dot-hero" markdown>
-
-# .dotfiles
-
-<p class="tagline">Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL — multi-shell parity (bash/zsh/fish/nushell), a fast <code>dot</code> CLI, wallpaper-driven themes, SLSA-signed releases, and AI/MCP-aware tooling.</p>
-
-<div class="buttons">
-  <a class="primary" href="guides/INSTALL/">Install →</a>
-  <a href="https://github.com/sebastienrousseau/dotfiles">GitHub</a>
-  <a href="reference/UTILS/">Utilities</a>
-  <a href="ARCHITECTURE/">Architecture</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. Cross-shell env parity from `.chezmoidata.toml`.
-
-    [→ Shell hub](reference/UTILS.md)
-
-- :material-lock-check:{ .lg .middle } **Signed & attested**
-
-    ---
-
-    Every commit SSH-signed, DCO enforced, SLSA-signed releases, SBOM + CVE gate, secret encryption via age.
-
-    [→ Security](operations/ATTESTATION.md)
-
-- :material-palette:{ .lg .middle } **190 wallpaper-driven themes**
-
-    ---
-
-    K-Means CIELAB color extraction. Terminal, editor, DE — all follow the wallpaper. `dot theme rebuild --force` regenerates from `~/Pictures/Wallpapers/`.
-
-    [→ Theme system](reference/UTILS.md)
-
-- :material-rocket-launch:{ .lg .middle } **Fast `dot` CLI**
-
-    ---
-
-    142+ subcommands: apply, health, doctor, heal, ai, agent, fleet, secrets, teleport, uninstall — with fzf pickers and a Bubble Tea cockpit.
-
-    [→ CLI reference](reference/UTILS.md)
-
-- :material-check-decagram:{ .lg .middle } **CI you can trust**
-
-    ---
-
-    35+ checks — shellcheck, shfmt, luacheck, stylua, CodeQL, Snyk, grype/SBOM, deps.dev, doc-drift gate, examples contract at 100%.
-
-    [→ Operations](operations/OPERATIONS.md)
-
-- :material-earth:{ .lg .middle } **Cross-platform**
-
-    ---
-
-    macOS (Intel & Apple Silicon), Linux (Ubuntu, Fedora, Arch, Alpine, openSUSE), WSL, PowerShell 7.5+, real BSDs.
-
-    [→ Support matrix](reference/SUPPORT_MATRIX.md)
-
-- :material-brain:{ .lg .middle } **AI & MCP aware**
-
-    ---
-
-    18-agent fleet cockpit (`dot ai`), local Claude gateway, MCP registry, context patterns, provider secrets — first-class support, not bolted on.
-
-    [→ AI operations](AI.md)
-
-- :material-account-cog:{ .lg .middle } **Chezmoi under the hood**
-
-    ---
-
-    Deterministic templates, feature flags, profiles, `run_onchange_` hooks. Everything lives in `defaults/` and applies to `$HOME` on-demand.
-
-    [→ Architecture](ARCHITECTURE.md)
-
-</div>
-
-## Quick start
-
-Install onto a fresh machine:
-
-=== "macOS / Linux / WSL"
-
-    ```bash
-    bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"
-    ```
-
-=== "Windows (PowerShell 7+)"
-
-    ```powershell
-    iwr -useb https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.ps1 | iex
-    ```
-
-Once installed:
-
-    dot doctor      # verify state
-    dot health      # dashboard with actionable warnings
-    dot ai          # launch the AI cockpit (Bubble Tea TUI)
-    dot theme       # pick a wallpaper-driven theme
-    dot help all    # full CLI reference
-
-## Where to next
-
-- [**Install guide**](guides/INSTALL.md) — full bootstrap walkthrough, per-platform.
-- [**Utilities & `dot` CLI**](reference/UTILS.md) — every subcommand with examples.
-- [**Architecture**](ARCHITECTURE.md) — how the layers fit together.
-- [**Trusted agent workstation**](operations/TRUSTED_AGENT_WORKSTATION.md) — hardening + attestation runbook.
-- [**Troubleshooting**](guides/TROUBLESHOOTING.md) — the common gotchas.
-- [**Support matrix**](reference/SUPPORT_MATRIX.md) — OS × shell × package-manager grid.
-- [**Security overview**](security/SECURITY.md) — signing, attestation, secret handling, threat model.
-
-## Current release
-
-- Release feed: [GitHub releases](https://github.com/sebastienrousseau/dotfiles/releases/latest)
-- Source: [sebastienrousseau/dotfiles](https://github.com/sebastienrousseau/dotfiles)

package/docs/interop/A2A.md

@@ -1,39 +0,0 @@
----
-render_with_liquid: false
----
-
-# Agent Interop
-
-The repository now ships an agent card and an A2A-ready discovery document.
-
-Artifacts:
-
-- [agent-card.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/agent-card.json)
-- [agent.json](https://github.com/sebastienrousseau/dotfiles/blob/main/.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/interop/POWERSHELL.md

@@ -1,102 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# PowerShell Parity
-
-This page documents how PowerShell 7.5+ support is exercised in CI
-and what specifically is verified. Closes the docs slice of
-[#860](https://github.com/sebastienrousseau/dotfiles/issues/860).
-
-## What ships
-
-| File | Role |
-|---|---|
-| [`dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl) | The dotfiles PowerShell profile. Deployed to `$PROFILE` (resolves to `~/.config/powershell/Microsoft.PowerShell_profile.ps1` on Linux/macOS; `Documents\PowerShell\Microsoft.PowerShell_profile.ps1` on Windows). |
-| [`scripts/qa/powershell-contract.ps1`](https://github.com/sebastienrousseau/dotfiles/blob/main/scripts/qa/powershell-contract.ps1) | The runtime contract. Renders the template, dot-sources it, asserts required function shims exist, runs PSScriptAnalyzer. |
-| [`tests/unit/install/test_powershell_profile_syntax.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tests/unit/install/test_powershell_profile_syntax.sh) | Static-syntax test runnable on Linux/macOS via `pwsh` when present; falls back to brace-balance + textual invariants when not. |
-
-## What's verified
-
-### On every Linux/macOS PR (`tests/unit/install/...`)
-
-- Profile file exists at the expected path.
-- Defines the `dot` function shim so PowerShell users invoke the
-  same CLI as Unix shells.
-- Sets `XDG_CONFIG_HOME` (matches Unix XDG conventions for
-  `~/.config/powershell` discoverability).
-- Brace count balances (`{` vs `}`).
-- If `pwsh` is installed locally, parses the rendered template via
-  `System.Management.Automation.Language.Parser` and fails on any
-  parse error.
-
-### On `windows-latest` runner via reliability-gate.yml
-
-The `powershell-contract` job runs `scripts/qa/powershell-contract.ps1`
-which does:
-
-1. **Renders the template** via `chezmoi execute-template` so any
-   chezmoi data references (e.g. `{{ .dotfiles_version }}`) resolve
-   to real values before parsing.
-2. **Dot-sources** the rendered profile and asserts no exception is
-   thrown during load.
-3. **Asserts the required function shims** are defined after load:
-   `dot`, `d`, `ll`, `la`, `cat`.
-4. **Runs PSScriptAnalyzer** at `Error` severity. Warnings surface
-   but don't fail the gate (tightenable later).
-
-Exit non-zero on any failure. The job is in the `reliability-summary`
-required-checks list so a broken PowerShell profile blocks merge.
-
-## Running locally
-
-### On Linux/macOS
-
-```bash
-# Static test — runs in any context.
-bash tests/unit/install/test_powershell_profile_syntax.sh
-
-# Full contract — needs pwsh + chezmoi installed.
-brew install --cask powershell   # or apt / package manager equivalent
-pwsh ./scripts/qa/powershell-contract.ps1
-```
-
-### On Windows
-
-```powershell
-.\scripts\qa\powershell-contract.ps1
-```
-
-## Known limitations
-
-- The contract doesn't currently exercise PowerShell-specific runtime
-  semantics (e.g. PSDrive providers, custom completion). Those are a
-  follow-up.
-- Function shims are smoke-tested by name only — we check that
-  `Get-Command dot` resolves to a function, not that it actually
-  invokes the right binary. A richer integration test that creates a
-  fake `dot` binary and confirms the shim invokes it correctly is a
-  future hardening step.
-- macOS is not in the matrix because `pwsh` isn't pre-installed on
-  GitHub macOS runners. The Linux/macOS static test runs on every PR
-  via the existing test suite; full pwsh validation is Windows-only
-  to keep the matrix small.
-
-## When to update this page
-
-- The PowerShell profile gains a new function → add it to the
-  `RequiredFunctions` array in `powershell-contract.ps1` AND to the
-  list above.
-- A static-test invariant is added → document it in the "What's
-  verified on every PR" list.
-- The PSScriptAnalyzer severity is tightened from `Error` to
-  `Warning` → update the relevant bullet here.
-
-## References
-
-- [PowerShell 7 docs](https://learn.microsoft.com/en-us/powershell/scripting/overview)
-- [PSScriptAnalyzer rule reference](https://github.com/PowerShell/PSScriptAnalyzer/blob/main/docs/Rules/README.md)
-- `.github/workflows/reliability-gate.yml` — Windows job definition.
-- Issue [#860](https://github.com/sebastienrousseau/dotfiles/issues/860).
-{% endraw %}

package/docs/manual/00-introduction.md

@@ -1,89 +0,0 @@
----
-render_with_liquid: false
----
-
-# Introduction
-
-This manual describes `.dotfiles` v0.2.520 — a trusted agent workstation baseline for macOS, Linux, and WSL.
-
-The repository is more than a personal dotfiles collection. It ships as workstation infrastructure: signed, attested, multi-platform, AI-aware, and self-healing. Chezmoi handles templating and platform differences. The `dot` CLI sits on top and coordinates lifecycle operations.
-
-## 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/main/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 `main` branch

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

@@ -1,138 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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

@@ -1,183 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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 `main` 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 `tools/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 `main` |
-| `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, Antigravity CLI, 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.501",
-  "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": "main",
-    "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% executable module mapping | `ci-enforced.yml` | Yes |
-| Measured Bash line coverage | `coverage.yml` | Ratcheted floor; see `docs/operations/COVERAGE.md` |
-| 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)