@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/index.md

@@ -0,0 +1,43 @@
+---
+render_with_liquid: false
+---
+
+# .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.501-blue?style=for-the-badge)](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.501)
+[![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.501`](https://github.com/sebastienrousseau/dotfiles/releases/tag/v0.2.501)
+- 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,39 @@
+---
+render_with_liquid: false
+---
+
+# 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/interop/POWERSHELL.md

@@ -0,0 +1,102 @@
+---
+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`](../../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`](../../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`](../../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/master/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

@@ -0,0 +1,89 @@
+---
+render_with_liquid: false
+---
+
+# Introduction
+
+This manual describes `.dotfiles` v0.2.501 — 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,138 @@
+---
+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

@@ -0,0 +1,182 @@
+---
+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 `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.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": "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)