@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/security/SECURITY_CHECKLIST.md

@@ -0,0 +1,55 @@
+---
+render_with_liquid: false
+---
+
+# Security Release Checklist
+
+Use this checklist before cutting any new release (e.g., `v0.x.x`) to ensure supply-chain integrity.
+
+## 1. Supply Chain & Installer
+
+- [ ] **Pinned Version**: Update `install.sh` `VERSION` variable to match the release tag.
+- [ ] **Docs Sync**: Ensure `README.md` and `.github/PULL_REQUEST_TEMPLATE.md` installer URLs point to the new tag (not `main`).
+- [ ] **Clean Build**: Verify `install.sh` does not curl random scripts from third parties without pinning.
+- [ ] **SOUP Register**: Review [SOUP_REGISTER.md](/home/seb/.dotfiles/docs/security/SOUP_REGISTER.md) and confirm all active external components have an owner and validation path.
+
+## 2. Secrets & Leak Prevention
+
+- [ ] **SSH Keys**: Scan `dot_ssh/` to ensure no private keys (`id_rsa`, `id_ed25519`) are committed.
+- [ ] **Env Vars**: Check for hardcoded API tokens in `dot_config/` (use `age` encryption or environment variables instead).
+- [ ] **Git History**: Run `git secrets` or similar to scan for accidental commits of credentials.
+
+## 3. Platform Safety
+
+- [ ] **WSL Check**: Verify `install.sh` detects WSL and does not try to install systemd services or macOS defaults.
+- [ ] **Root usage**: Ensure no script requires `sudo` unnecessarily (Principle of Least Privilege).
+
+## 4. Toolchain
+
+- [ ] **Binary Integrity**: Check that `dot_local/bin/` scripts are pure shell/executable and match expected checksums (no binary blobs).
+- [ ] **Dependency Scan**: Run `npm audit` / `cargo audit` if applicable (currently Node.js legacy is removed).
+
+## 5. MCP (Model Context Protocol) Hardening
+
+- [ ] **Launcher Policy**: Verify `dot mcp` shows only allowlisted launchers (`npx`, `node`, `uvx`).
+- [ ] **Filesystem Scope**: Ensure no MCP server has broad access (`/`, `/home`, `/Users`).
+- [ ] **Default Profile**: Confirm only the `strict-local` server set is enabled by default.
+- [ ] **Token Validation**: Confirm required API tokens are set (`GITHUB_TOKEN`, `BRAVE_API_KEY`).
+- [ ] **Arg Policy**: No wildcard (`*`) or `--unsafe` arguments in MCP server configs.
+- [ ] **Env Placeholders**: All `${VAR}` references in MCP config have corresponding environment variables.
+
+Run `dot mcp --strict --json` to validate all MCP server configurations and capture an audit artifact.
+
+## 6. Release Attestation
+
+- [ ] **SBOM Generation**: Verify `dotfiles-sbom.spdx.json` is generated in release workflow.
+- [ ] **Attestation Signing**: Confirm `actions/attest-build-provenance` signs the release artifacts.
+- [ ] **Attestation Verification**: Verify with `gh attestation verify <artifact> --repo sebastienrousseau/dotfiles`.
+- [ ] **Branch Protection**: Ensure `security-attestation` is a required status check on master.
+- [ ] **Automation Keying**: Confirm `ACTIONS_BOT_SIGNING_KEY` exists and matches the signer in `dot_config/git/allowed_signers`.
+
+## 7. Final Verification
+
+- [ ] **Docker Test**: Run `docker build -f Dockerfile.test .` to verify clean install.
+- [ ] **Doctor**: Run `dot doctor` locally.
+- [ ] **MCP Check**: Run `dot mcp` to verify MCP configuration.

package/docs/security/SHELL_EXEMPTIONS.md

@@ -0,0 +1,145 @@
+---
+render_with_liquid: false
+---
+
+# Shell Preamble Exemptions
+
+Every bash script in this repo must include `set -euo pipefail` (or
+`set -eu` for POSIX `sh`) within its first 50 lines. The rule is
+enforced by
+[`scripts/ci/check-shell-preamble.sh`](../../scripts/ci/check-shell-preamble.sh),
+wired into `pre-commit` and the `reusable-shell-lint.yml` CI job.
+Tests pin the contract under
+[`tests/unit/security/test_shell_preamble_lint.sh`](../../tests/unit/security/test_shell_preamble_lint.sh).
+
+## Why the preamble is mandatory
+
+`set -e` fails the script on the first error. `set -u` rejects
+reads of unset variables. `set -o pipefail` propagates the exit
+code of the last failing command in a pipeline rather than only the
+final command's. Together they convert silent failures into loud
+ones — which is the only way to catch them.
+
+Real example from this repo's history: `executable_dot-load-benchmark`
+shipped with only `set -e`. A failing pipeline (e.g. `cmd | grep`)
+where `grep` succeeded would still report success even when `cmd`
+crashed. The full triple catches this. The benchmark was upgraded
+in commit 970b631d under #854.
+
+## Exemption categories
+
+Two kinds of files legitimately can't enforce the preamble locally:
+
+### 1. Sourced libraries
+
+Files loaded via `source` / `.` into a caller's shell context. The
+caller already has `set -euo pipefail`; the library inherits it.
+Adding `set -e` locally would persist after the library returns and
+break the caller's own error-handling logic.
+
+These files must carry a comment header in their first 15 lines:
+
+```bash
+# Sourced by <parent>.sh; inherits set -euo pipefail.
+```
+
+The lint accepts files with this marker regardless of preamble
+state. Current adopters:
+
+| Path | Sourced by |
+|---|---|
+| `dot_config/shell/00-core-paths.sh.tmpl` | shell init (zsh/bash/fish) |
+| `dot_config/shell/05-core-safety.sh` | shell init |
+| `dot_config/shell/10-secrets.sh` | shell init |
+| `dot_config/shell/40-fzf-defaults.sh.tmpl` | shell init |
+| `dot_config/shell/40-ls-colors.sh` | shell init |
+| `dot_config/shell/50-logic-functions-core.sh.tmpl` | shell init + fish bridge |
+| `dot_config/shell/50-logic-functions.sh.tmpl` | shell init + fish bridge |
+| `dot_config/shell/51-logic-functions-extra.sh.tmpl` | shell init (lazy) |
+| `dot_config/shell/90-ux-aliases.sh.tmpl` | shell init + fish bridge |
+| `dot_config/shell/91-ux-aliases-lazy.sh.tmpl` | shell init (lazy) |
+| `scripts/dot/lib/bento.sh` | dot CLI commands |
+| `scripts/dot/lib/log.sh` | dot CLI + diagnostics |
+| `scripts/dot/lib/platform.sh` | dot CLI commands |
+| `scripts/dot/lib/ui.sh` | dot CLI + diagnostics + ops |
+| `scripts/dot/lib/utils.sh` | dot CLI |
+| `scripts/ops/heal-chezmoi.sh` | `scripts/ops/heal.sh` |
+| `scripts/ops/heal-system.sh` | `scripts/ops/heal.sh` |
+| `scripts/ops/heal-tools.sh` | `scripts/ops/heal.sh` |
+
+### 2. Bulk-sourced fragments (path-skipped)
+
+Three directories contain hundreds of alias / function / PATH
+snippets that are sourced into the shell. Annotating each one
+individually would be 300+ marker comments with no extra signal.
+The lint skips them by path:
+
+| Path | Contents |
+|---|---|
+| `.chezmoitemplates/aliases/**/*.aliases.sh` | alias definitions sourced into the user's shell. |
+| `.chezmoitemplates/functions/**` | shell-function definitions sourced into the user's shell. |
+| `.chezmoitemplates/paths/**` | `PATH=…:$PATH` snippets concatenated by the shell init. |
+
+### 3. Test scripts (path-skipped)
+
+`tests/**` — every file under the test tree is invoked through
+`tests/framework/test_runner.sh` which manages shell options for its
+children. The runner itself has the full preamble; children that
+source the framework inherit it.
+
+### 4. Explicit opt-outs
+
+Init fragments and completion scripts that must NOT carry their own
+preamble (e.g., `dot_local/bin/executable_dot_completion`, a zsh
+completion sourced into the interactive shell) can carry an
+explicit marker:
+
+```bash
+# preamble:skip — opt-out for completion / init fragments.
+```
+
+The lint accepts these. Use sparingly.
+
+## Adding a new exemption
+
+When you need to mark a new file:
+
+1. **Decide whether it's actually sourced or executed.** If a user
+   ever invokes it directly (chmod +x + `./file.sh`), add the
+   preamble. If it's only ever `source`d, mark it.
+
+2. **Pick the right marker.**
+   - Sourced library: `# Sourced by <caller>; inherits set -euo pipefail.`
+   - Completion / init fragment: `# preamble:skip — <why>.`
+
+3. **Run the checker:**
+
+   ```bash
+   ./scripts/ci/check-shell-preamble.sh path/to/file.sh
+   ```
+
+   Exit 0 = lint passes.
+
+4. **If you're adding a new entire directory of fragments**
+   (rare — alias buckets, plugin trees), edit the path-skip rule
+   in `scripts/ci/check-shell-preamble.sh` and document it in this
+   page's "Bulk-sourced fragments" table above.
+
+## CI integration
+
+- **Pre-commit hook** (`config/pre-commit-config.yaml` →
+  `shell-preamble-check`): blocks `git commit` if a staged shell
+  file fails the lint.
+- **CI** (`.github/workflows/reusable-shell-lint.yml`): runs the
+  full-repo scan on every PR.
+
+A change to either the checker or the marker convention must update
+this page in the same PR.
+
+## References
+
+- `scripts/ci/check-shell-preamble.sh` — the lint.
+- `tests/unit/security/test_shell_preamble_lint.sh` — contract test.
+- `config/pre-commit-config.yaml` (`shell-preamble-check` hook).
+- `.github/workflows/reusable-shell-lint.yml` — CI invocation.
+- Issue [#854](https://github.com/sebastienrousseau/dotfiles/issues/854).

package/docs/security/SOUP_REGISTER.md

@@ -0,0 +1,36 @@
+---
+render_with_liquid: false
+---
+
+# SOUP Register
+
+## Purpose
+
+Controlled inventory for software of unknown pedigree used by the dotfiles platform.
+
+## Active components
+
+| Component | Source | Version control | Verification path | Owner | Status |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| Homebrew installer | `raw.githubusercontent.com/Homebrew/install` | Moving upstream script, gated by `HOMEBREW_INSTALLER_SHA256` | SHA-256 in [package_managers.sh](/home/seb/.dotfiles/install/lib/package_managers.sh) | Repo maintainer | Conditional |
+| Chezmoi installer | `get.chezmoi.io` | Pinned by `CHEZMOI_INSTALLER_SHA256` when used | SHA-256 in `install/lib/chezmoi.sh` | Repo maintainer | Controlled |
+| GitHub Actions marketplace actions | GitHub Marketplace | Full commit SHA pinning | Workflow `uses:` pins | Repo maintainer | Controlled |
+| Grype container | `anchore/grype` | Pinned tag in workflow | Container tag in [security-enhanced.yml](/home/seb/.dotfiles/.github/workflows/security-enhanced.yml) | Repo maintainer | Controlled |
+| Trivy container | `aquasec/trivy` | Pinned tag in workflow | Container tag in [security-enhanced.yml](/home/seb/.dotfiles/.github/workflows/security-enhanced.yml) | Repo maintainer | Controlled |
+| Checkov action | GitHub Marketplace | Full commit SHA pinning | Workflow `uses:` pin | Repo maintainer | Controlled |
+| Nix inputs | GitHub flakes | Locked in [flake.lock](/home/seb/.dotfiles/flake.lock) | `narHash` and revision lock | Repo maintainer | Controlled |
+| GitHub release metadata queries | GitHub API | Discovery only, not release validation | `update-deps.yml` query path | Repo maintainer | Monitored |
+
+## Validation record
+
+1. Record version or commit SHA.
+2. Record checksum, signature, or attestation method.
+3. Record workflow or script that consumes the component.
+4. Record owner and review date.
+5. Reject moving inputs in production or release paths unless checksum-gated.
+
+## Exit criteria
+
+- No unsigned automation commits.
+- No unverified executable download in installer or release path.
+- Every SOUP item has owner, version control method, and validation record.

package/docs/security/THREAT_MODEL.md

@@ -0,0 +1,130 @@
+---
+render_with_liquid: false
+---
+
+# Threat Model
+
+Security analysis of the dotfiles distribution. Covers trust boundaries, threat actors, attack surfaces, and mitigations.
+
+## Trust Boundary
+
+The primary trust boundary is the **local machine**. Dotfiles are deployed to and executed on the user's own system. All configuration files, scripts, and templates run with the user's privileges.
+
+```text
+┌─────────────────────────────────────────────────┐
+│ Local Machine (trusted zone)                    │
+│  ┌─────────────────┐  ┌──────────────────────┐  │
+│  │ ~/.dotfiles/     │  │ ~/.config/ (deployed)│  │
+│  │ (source repo)    │──│ Shell configs, nvim  │  │
+│  └─────────────────┘  └──────────────────────┘  │
+│                                                  │
+│  ┌─────────────────┐  ┌──────────────────────┐  │
+│  │ ~/.local/bin/    │  │ ~/.cache/shell/      │  │
+│  │ (user scripts)   │  │ (cached eval output) │  │
+│  └─────────────────┘  └──────────────────────┘  │
+└─────────────────────────────────────────────────┘
+         │
+    ─────┼──────── Trust boundary ────────
+         │
+┌─────────────────────────────────────────────────┐
+│ External (untrusted zone)                        │
+│  GitHub (repo hosting), Homebrew, Nix,           │
+│  Zinit plugins, Neovim plugins, npm, pip         │
+└─────────────────────────────────────────────────┘
+```
+
+## Threat Actors
+
+| Actor | Motivation | Capability |
+|-------|-----------|------------|
+| Supply chain attacker | Inject malicious code via dependency | Compromise upstream packages (Homebrew, npm, Zinit plugins) |
+| Secrets harvester | Steal API keys, SSH keys, tokens | Scrape git history, shell history, env vars |
+| Privilege escalation | Gain root access | Exploit `sudo` aliases, writable scripts in PATH |
+| Network attacker | Intercept credentials | MITM on install scripts, curl-pipe-bash |
+
+## Attack Surfaces
+
+### 1. Shell Startup Scripts
+
+**Risk:** Malicious code in sourced files executes with user privileges on every shell start.
+
+**Mitigations:**
+
+- All shell scripts pass `shellcheck --severity=error`
+- `set -euo pipefail` enforced in all operational scripts
+- `eval` usage hardened with process substitution (`. /dev/stdin`)
+- Input validation on dynamic function generation
+- `DOTFILES_ULTRA_FAST=1` bypasses all non-core sourcing
+
+### 2. Secrets Exposure
+
+**Risk:** API keys, tokens, and SSH keys leaked via git history, shell history, or environment.
+
+**Mitigations:**
+
+- [Gitleaks](https://github.com/gitleaks/gitleaks) pre-commit hook blocks secrets in commits
+- Atuin `history_filter` excludes sensitive patterns
+- Age encryption for local secret storage
+- `dot secrets set` uses secure prompts (no shell history)
+- `.gitignore` excludes `key.txt`, `.env`, credential files
+
+### 3. Supply Chain Dependencies
+
+**Risk:** Compromised upstream packages injected into the toolchain.
+
+**Mitigations:**
+
+- Nix Flakes provide reproducible, pinned dependencies
+- Zinit plugin versions pinned (`ver"0.8.0"`)
+- Neovim plugin versions locked via `lazy-lock.json`
+- `install.sh` uses HTTPS for all downloads
+- Homebrew formula integrity via bottle checksums
+
+### 4. Path Manipulation
+
+**Risk:** Attacker places malicious binary in a PATH directory that shadows legitimate tools.
+
+**Mitigations:**
+
+- PATH construction is deterministic (template-generated)
+- `~/.local/bin` is user-controlled and checked for writability
+- No world-writable directories in PATH
+- `prependpath` function validates directory existence
+
+### 5. Template Injection
+
+**Risk:** Chezmoi template variables could inject shell code if not properly quoted.
+
+**Mitigations:**
+
+- Template variables come from `.chezmoidata.toml` (user-controlled)
+- No external/network data used in templates
+- Template validation via `chezmoi apply --dry-run` in CI
+
+### 6. Cached Eval Files
+
+**Risk:** Stale or tampered cache files in `~/.cache/shell/` sourced at startup.
+
+**Mitigations:**
+
+- `_cached_eval` validates cache against binary mtime
+- Cache files are user-owned (0644)
+- Cache directory is under `$XDG_CACHE_HOME` (user-controlled)
+- Cache can be cleared with `rm -rf ~/.cache/shell/`
+
+## Residual Risks
+
+| Risk | Likelihood | Impact | Status |
+|------|-----------|--------|--------|
+| Zinit plugin compromise | Low | High | Mitigated by version pinning |
+| Shell history leak | Medium | Medium | Mitigated by Atuin filter |
+| Stale Nix closure | Low | Low | Accepted (manual `nix flake update`) |
+| macOS Keychain access | Low | Medium | Accepted (OS-level protection) |
+
+## Recommendations
+
+1. Run `gitleaks detect` before every push (pre-commit hook enforced)
+2. Rotate secrets on a 90-day schedule
+3. Audit `lazy-lock.json` diffs when updating Neovim plugins
+4. Pin Homebrew versions for security-critical tools
+5. Use `DOTFILES_ULTRA_FAST=1` in CI to minimize attack surface

package/docs/security/VERIFICATION_VALIDATION.md

@@ -0,0 +1,228 @@
+---
+render_with_liquid: false
+---
+
+# Verification and Validation Report
+
+## Document Control
+
+| Field | Value |
+|-------|-------|
+| Document ID | VV-DOT-001 |
+| Version | 0.2.501 |
+| Date | 2026-03-20 |
+| Author | Repository Maintainer |
+| Status | Active |
+| Classification | Internal |
+| Standard | ISO 13485:2016 Sections 7.3.6 / 7.3.7 (adapted) |
+
+---
+
+## Purpose
+
+This document constitutes the formal Verification and Validation (V&V) report for the chezmoi-managed dotfiles repository, adapted from ISO 13485:2016 Sections 7.3.6 (Design and Development Verification) and 7.3.7 (Design and Development Validation) for infrastructure-as-code.
+
+**Verification** confirms that each design output meets its corresponding design input requirement through inspection, analysis, and testing. **Validation** confirms that the deployed system satisfies its intended use under representative operating conditions (Linux, macOS, WSL).
+
+All verification activities are executed through automated CI pipelines, pre-commit hooks, and the repository test framework. Evidence is retained in CI logs, test output, and this document.
+
+---
+
+## Verification Matrix
+
+| Req ID | Requirement | Verification Method | Test File(s) | Result |
+|--------|-------------|---------------------|--------------|--------|
+| VR-01 | Shell scripts pass ShellCheck (severity=error) | Static analysis via `shellcheck --severity=error -e SC1091 -e SC2030 -e SC2031` | `ci.yml`, `ci-enforced.yml`, pre-commit hook | Pass |
+| VR-02 | All scripts have `set -euo pipefail` | Pattern scan across all `.sh` files; CI enforcement | `ci-enforced.yml`, `compliance-guard.yml` | Pass |
+| VR-03 | No secrets in source control (gitleaks clean) | Gitleaks scan with `config/gitleaks.toml` ruleset | Pre-commit hook, `security-enhanced.yml` | Pass |
+| VR-04 | Cross-platform compatibility (BSD + GNU) | Dual-platform CI matrix (ubuntu-latest, macos-latest) | `cross-platform-test.yml` | Pass |
+| VR-05 | TLS enforcement (no insecure curl/wget) | Pattern blocking for `curl -k`, `--insecure`, `wget --no-check-certificate` | Pre-commit hook, `compliance-guard.yml` | Pass |
+| VR-06 | Permission controls (no chmod 777/666) | CI pattern scan blocks world-writable permissions | Pre-commit hook, `compliance-guard.yml` | Pass |
+| VR-07 | Signed commits enforced | Pre-push hook verifies `git verify-commit` for all commits in range | `scripts/git-hooks/pre-push`, `compliance-guard.yml` | Pass |
+| VR-08 | Conventional commit format | Pre-commit hook validates `feat:`, `fix:`, `docs:` prefixes | Pre-commit hook (conventional-commits) | Pass |
+| VR-09 | Template rendering correctness | `chezmoi apply --dry-run` on Linux and macOS CI runners | `ci.yml` (Linux + macOS matrix), `tests/unit/test_*.sh` | Pass |
+| VR-10 | Alias system functional | Unit tests source alias files and verify command availability | `tests/unit/aliases/test_*.sh` (104 files) | Pass |
+| VR-11 | Neovim config loads without errors | Headless Neovim launch with error detection | `tests/unit/neovim/test_*.sh` (15 files) | Pass |
+| VR-12 | Fish/Zsh/Nushell configs valid | Syntax validation and functional tests per shell | `tests/unit/fish/` (33), `tests/unit/shell/` (12), `tests/unit/nushell/` (5) | Pass |
+| VR-13 | CI pipelines execute successfully | GitHub Actions workflow status across all triggers | `ci.yml`, `ci-enforced.yml`, `compliance-guard.yml`, `cross-platform-test.yml`, `security-enhanced.yml`, `codeql.yml` | Pass |
+| VR-14 | Pre-commit hooks functional | Hook execution via `pre-commit run --all-files` | `config/pre-commit-config.yaml` | Pass |
+| VR-15 | Age encryption operational | Chezmoi age-encrypted file decryption during apply | `chezmoi apply --dry-run` (encrypted targets), integration tests | Pass |
+
+---
+
+## Validation Summary
+
+### Coverage Metrics
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| Total test files | 430 | N/A | Measured |
+| Total assertions | 2,217 | N/A | Measured |
+| Pass rate | 100% | 100% | Pass |
+| Module coverage | 100% | >= 95% | Pass |
+
+### Category Breakdown
+
+| Category | Test Files | Status |
+|----------|-----------|--------|
+| Alias files | 104 | Tested |
+| Function files | 76 | Tested |
+| Fish functions + conf.d | 33 | Tested |
+| Misc / compliance | 34 | Tested |
+| Dot CLI | 30 | Tested |
+| Diagnostics | 28 | Tested |
+| Shell configs | 20 | Tested |
+| Ops | 18 | Tested |
+| Install | 17 | Tested |
+| Security | 16 | Tested |
+| Neovim Lua configs | 15 | Tested |
+| Theme | 11 | Tested |
+| Tools | 7 | Tested |
+| Nushell configs | 6 | Tested |
+| Secrets | 5 | Tested |
+| Integration tests | 10 | Tested |
+| **Total** | **430** | **All pass** |
+
+### Validation Environments
+
+| Environment | OS | Shell | Bash Version | Status |
+|-------------|-----|-------|--------------|--------|
+| CI (Linux) | Ubuntu latest | Bash | 5.x | Validated |
+| CI (macOS) | macOS latest | Zsh | 3.2 (system) | Validated |
+| Local (Linux) | CachyOS / Arch | Fish, Zsh, Bash | 5.x | Validated |
+| Local (WSL) | Ubuntu | Bash | 5.x | Validated |
+
+---
+
+## Test Framework Architecture
+
+### Directory Structure
+
+```
+tests/
+├── framework/
+│   ├── test_runner.sh     # Test executor — discovers and runs all test_*.sh files
+│   ├── assertions.sh      # 16 assertion functions (assert_equals, assert_contains, etc.)
+│   └── mocks.sh           # Mock utilities for isolating external dependencies
+├── unit/
+│   ├── aliases/           # Alias and command-surface tests
+│   ├── functions/         # Function behavior tests
+│   ├── dot-cli/           # `dot` command workflow tests
+│   ├── shell/             # Shell integration and completion tests
+│   ├── fish/              # Fish function and completion tests
+│   ├── nushell/           # Nushell configuration tests
+│   ├── nvim/              # Neovim configuration tests
+│   └── test_*.sh          # 425 unit test files total
+├── integration/
+│   └── test_*.sh          # 11 integration test files
+└── performance/
+    └── benchmark_runner.sh # Performance regression benchmarks
+```
+
+### Execution Model
+
+1. `test_runner.sh` recursively discovers all `test_*.sh` files under `tests/`.
+2. Each test file is executed in a subshell with `assertions.sh` sourced.
+3. Tests source bash files directly from the repository (not Go templates).
+4. `mocks.sh` provides stubs for external tools (`chezmoi`, `git`, `brew`, etc.).
+5. Exit codes and assertion counts are aggregated into a final report.
+
+### Assertion Library
+
+| Function | Purpose |
+|----------|---------|
+| `assert_equals` | Exact string equality |
+| `assert_not_equals` | String inequality |
+| `assert_contains` | Substring match |
+| `assert_not_contains` | Substring absence |
+| `assert_starts_with` | Prefix match |
+| `assert_ends_with` | Suffix match |
+| `assert_matches` | Regex match |
+| `assert_file_exists` | File presence |
+| `assert_file_not_exists` | File absence |
+| `assert_directory_exists` | Directory presence |
+| `assert_command_exists` | Command availability |
+| `assert_exit_code` | Process exit code |
+| `assert_empty` | Empty string |
+| `assert_not_empty` | Non-empty string |
+| `assert_true` | Boolean truth |
+| `assert_false` | Boolean false |
+
+---
+
+## Traceability Matrix
+
+This matrix maps compliance controls from COMPLIANCE.md to verification requirements defined in this document.
+
+### SOC 2 Type II Traceability
+
+| SOC 2 Control | Description | Verification Requirement(s) |
+|---------------|-------------|----------------------------|
+| CC6.1 | Logical Access Security | VR-06 (Permission controls), VR-15 (Age encryption) |
+| CC6.8 | Unauthorized Code Protection | VR-07 (Signed commits), VR-03 (No secrets) |
+| CC7.1 | System Operations | VR-05 (TLS enforcement), VR-13 (CI pipelines) |
+| CC7.2 | Change Detection | VR-14 (Pre-commit hooks), VR-08 (Conventional commits) |
+| CC8.1 | Change Management | VR-07 (Signed commits), VR-08 (Conventional commits), VR-13 (CI pipelines) |
+| A1.2 | Audit Logs | VR-13 (CI pipelines — logs retained in GitHub Actions) |
+
+### ISO 27001 Traceability
+
+| ISO Control | Description | Verification Requirement(s) |
+|-------------|-------------|----------------------------|
+| A.9.1.1 | Access Control Policy | VR-06 (Permission controls), VR-15 (Age encryption) |
+| A.9.4.1 | Information Access Restriction | VR-06 (No chmod 777/666) |
+| A.12.1.2 | Change Management | VR-07 (Signed commits), VR-08 (Conventional commits) |
+| A.12.6.1 | Technical Vulnerability Management | VR-03 (Gitleaks), VR-05 (TLS enforcement) |
+| A.13.1.1 | Network Controls | VR-05 (TLS enforcement) |
+| A.14.2.5 | Secure Engineering | VR-01 (ShellCheck), VR-02 (set -euo pipefail), VR-04 (Cross-platform) |
+| A.14.2.8 | System Security Testing | VR-09 (Template rendering), VR-10 (Aliases), VR-11 (Neovim), VR-12 (Shell configs) |
+
+### GDPR / Privacy Traceability
+
+| Requirement | Description | Verification Requirement(s) |
+|-------------|-------------|----------------------------|
+| Data Minimization | Limit data collection | VR-03 (No secrets in source) |
+| Integrity | Protect against tampering | VR-07 (Signed commits), VR-14 (Pre-commit hooks) |
+| Encryption | Protect data at rest | VR-15 (Age encryption operational) |
+
+---
+
+## Acceptance Criteria
+
+All of the following criteria must be satisfied for this V&V report to remain valid.
+
+| Criterion | Verification Method | Required Outcome |
+|-----------|---------------------|------------------|
+| All unit and integration tests pass | `./tests/framework/test_runner.sh` | Exit code 0, 0 failures |
+| ShellCheck clean | `shellcheck --severity=error` on all `.sh` files | Zero findings |
+| Gitleaks clean | `gitleaks detect --config config/gitleaks.toml` | Zero findings |
+| Chezmoi dry-run clean | `chezmoi apply --dry-run` on Linux and macOS | Exit code 0, no errors |
+| Pre-commit hooks pass | `pre-commit run --all-files` | Exit code 0 |
+| Cross-platform CI green | `cross-platform-test.yml` on ubuntu-latest and macos-latest | All jobs pass |
+| Module coverage at threshold | Test runner coverage report | >= 95% (currently 100%) |
+| No world-writable permissions | `compliance-guard.yml` pattern scan | Zero `chmod 777` or `chmod 666` matches |
+| No insecure TLS patterns | `compliance-guard.yml` pattern scan | Zero `curl -k` or `wget --no-check-certificate` matches |
+| All commits signed | `git verify-commit` on HEAD~50..HEAD range | All commits verified |
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Signature |
+|------|------|------|-----------|
+| Repository Owner | | | |
+| Security Reviewer | | | |
+| Quality Assurance | | | |
+| Release Manager | | | |
+
+---
+
+## References
+
+- [ISO 13485:2016](https://www.iso.org/standard/59752.html) — Medical devices, Quality management systems
+- [ISO 27001:2022](https://www.iso.org/standard/27001) — Information security management
+- [SOC 2 Type II](https://www.aicpa.org/soc2) — Trust Services Criteria
+- [SLSA Framework](https://slsa.dev/) — Supply chain Levels for Software Artifacts
+- [ShellCheck](https://www.shellcheck.net/) — Static analysis for shell scripts
+- [Gitleaks](https://gitleaks.io/) — Secrets detection
+- [Chezmoi](https://www.chezmoi.io/) — Dotfiles manager

package/docs/themes/README.md

@@ -0,0 +1,10 @@
+---
+render_with_liquid: false
+---
+
+# Theme Gallery
+
+Themes are auto-generated from your wallpapers — the available set depends on what's present on your system. Run `dot theme list` to see what's discovered.
+
+See [Theme Reference](../reference/THEMES.md) for the wallpaper-driven engine.
+See [Theming Guide](../guides/THEMING.md) for setup, switching, and the K-Means CIELAB pipeline.

package/docs/themes/VISUAL_INTEGRITY_REPORT.md

@@ -0,0 +1,30 @@
+---
+render_with_liquid: false
+---
+
+# Visual Integrity Report
+
+Generated: 2026-04-08
+Scope: terminal theme SSOT, shell first-paint path, font rendering, and cross-platform template intent.
+
+| Metric | Current | Target | Status |
+| :--- | :--- | :--- | :--- |
+| Contrast (APCA) | `macos-monterey-dark` body text `Lc 90+`, critical UI `Lc 95+` | `Lc 75+` body, `Lc 90+` critical | Pass |
+| Startup Time | `bash 25ms`, `zsh 35ms`, `fish 25ms` | `< 100ms` | Pass |
+| Color DeltaE | SSOT palette unified across Ghostty/Kitty/Alacritty/WezTerm; no runtime probe yet | `< 2.0` | Needs instrumentation |
+
+## Findings
+
+- Theme colors are already centralized in `.chezmoidata/themes.toml`, but accessibility intent was implicit. The active theme now carries explicit OKLCH/APCA metadata.
+- First-prompt Fish initialization still performed live CLI work when cache artifacts were present. The prompt path now sources prewarmed cache files first and only regenerates on cache miss.
+- Terminal templates were palette-consistent, but rendering policy was inconsistent. macOS now prefers Display P3 and CoreText-friendly metrics; Linux/Wayland templates prefer more conservative opacity and FreeType-safe fallbacks.
+
+## Edge Cases
+
+- Wayland fontconfig now sets `rgba` declaratively from feature flags to avoid color fringing on mixed-density Linux panels.
+- Ghostty, Kitty, Alacritty, and WezTerm now share the same terminal ramp while allowing platform-specific font fallback and window-compositor behavior.
+- WSL parity is still template-capable, but DeltaE validation is not yet automated against Windows Terminal serialization.
+
+## Next Step
+
+Implement a small palette audit utility that computes APCA and DeltaE from `.chezmoidata/themes.toml` so the report can become test-backed rather than declarative.