@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/reference/UTILS.md

@@ -0,0 +1,155 @@
+---
+render_with_liquid: false
+---
+
+# Utilities
+
+Aliases, functions, and the `dot` CLI provide day-to-day tooling across macOS, Linux, and WSL.
+
+## Dot CLI
+
+The `dot` command is the main interface for managing dotfiles. Run `dot version` or `dot --version` to check the installed version.
+
+### Core commands
+
+| Command | Description |
+|---------|-------------|
+| `dot commit` | Create an AI-assisted conventional commit |
+| `dot apply` | Apply dotfiles (`chezmoi apply`) |
+| `dot sync` | Alias of apply |
+| `dot update` | Pull latest changes and apply |
+| `dot add <file>` | Add a file to chezmoi source |
+| `dot diff` | Show local changes (excludes scripts) |
+| `dot status` | Show configuration drift |
+| `dot remove <path>` | Safely remove a managed file |
+| `dot cd` | Print source directory path |
+| `dot edit` | Open source in your editor |
+| `dot clean-cache` | Clear generated shell initialization caches |
+| `dot prewarm` | Regenerate shell caches for fast startup |
+| `dot bundle` | Create an offline portable archive |
+| `dot upgrade` | Update toolchains, plugins, and dotfiles |
+| `dot packages` | Show installed packages and package managers |
+| `dot cache-refresh` | Rebuild generated shell state |
+| `dot search <term>` | Find commands by keyword |
+| `dot help` | Show command help and the public reference |
+| `dot version` | Show the installed dotfiles version |
+
+### Diagnostics
+
+| Command | Description |
+|---------|-------------|
+| `dot doctor` | Run system health checks (`--score/-s`,`--heal/-H`) |
+| `dot health` | Run the health dashboard (`--verbose/-v`,`--json/-j`,`--fix/-f`,`--force/-F`) |
+| `dot heal` | Auto-repair missing tools, chezmoi drift, broken symlinks, and critical files (`--dry-run/-n`,`--force/-f`) |
+| `dot smoke-test` | Verify toolchains (Rust, Go, AI CLIs) |
+| `dot verify` | Run security and integrity verification (`--security/-s`) |
+| `dot chaos` | Simulate config corruption to test self-healing |
+| `dot rollback` | Roll back dotfiles to the previous known-good state |
+| `dot drift` | Detailed configuration drift dashboard |
+| `dot benchmark` | Measure shell startup time (`--detailed/-d`,`--profile/-p`,`--compare/-c`,`--waterfall/-w`) |
+| `dot perf` | Show performance mode + quick timing (`--json/-j`,`--profile/-p`,`--runs/-r`,`--target/-t`) |
+| `dot score` | Show the high-level system health and security scorecard |
+| `dot metrics` | Show recent observability metrics |
+| `dot load-bench` | Measure heavy-layer readiness |
+| `dot mcp` | Validate MCP policy and registry (`--strict/-s`,`--json/-j`) |
+| `dot attest` | Export workstation evidence (`--json/-j`,`--write/-w`,`--fleet-store/-F`) |
+| `dot history` | Analyse shell history |
+| `dot security-score` | Score workstation security (`--verbose/-v`,`--quiet/-q`,`--json/-j`) |
+| `dot snapshot` | Capture workstation state (`--baseline/-b`,`--force/-f`) |
+| `dot ai` | Show categorized AI CLI status and launch an installed provider |
+| `dot ai-setup` | Bootstrap supported AI CLIs interactively |
+| `dot ai-query` | Run context-aware AI queries over the repo |
+| `dot mode` | Show or switch the active agent profile |
+| `dot agent` | Inspect agent metadata, logs, checkpoints, and conformance |
+| `dot agent checkpoint` | Save, list, show, and replay bounded agent checkpoints |
+| `dot agent conformance` | Validate A2A discovery and agent card conformance (`--strict/-s`,`--json/-j`) |
+
+### Tools
+
+| Command | Description |
+|---------|-------------|
+| `dot env` | Show managed runtime and tool versions |
+| `dot profile` | Show or switch the active configuration profile |
+| `dot keys` | Show the keybindings and signing reference |
+| `dot tools` | Show tools documentation |
+| `dot tools install` | Enter Nix development shell |
+| `dot new <lang> <name>` | Scaffold a project (`python`/`go`/`node`) |
+| `dot sandbox` | Launch Docker sandbox preview |
+| `dot learn` | Start the guided onboarding tour |
+| `dot docs` | Show the main repository documentation |
+| `dot log-rotate` | Rotate `~/.local/share/dotfiles.log` |
+| `dot lint` | Lint shell scripts (`--check/-c`,`--fix/-f`) |
+
+## Universal Scripts
+
+POSIX scripts in `~/.local/bin/` that work across macOS, Linux, and WSL.
+
+| Command | Description |
+|---------|-------------|
+| `als` | Interactive alias and script viewer (categorized) |
+| `cb` | Universal clipboard utility (detects `pbcopy`/`pbpaste`, `xclip`/`wl-copy`, or `clip.exe`) |
+| `open` | Universal file/URL opener (maps to `open`, `xdg-open`, or `explorer.exe`) |
+| `notify` | Universal desktop notifications (`osascript`, `notify-send`, or `powershell`) |
+| `extract` | Universal archive extractor with robust format support and `gum` UI feedback |
+| `up <n>` | Navigate up `n` directory levels |
+| `bm` | Directory bookmarking tool (`add`, `goto`, `list`, `remove`, `update`) |
+| `win` | WSL-specific shim for running Windows binaries with translated paths |
+
+## Appearance
+
+| Command | Description |
+|---------|-------------|
+| `dot theme` | Interactive picker (paired wallpaper themes only) |
+| `dot theme <name>` | Switch directly (e.g. `dot theme tahoe-dark`) |
+| `dot theme toggle` | Swap dark↔light within current family |
+| `dot theme rebuild` | Regenerate themes from system + custom wallpapers via K-Means in CIELAB (`--force`, `--list`) |
+| `dot theme list` | Show paired wallpaper themes with System/Custom source |
+| `dot wallpaper` | Apply a wallpaper independently of theme |
+| `dot fonts` | Install Nerd Fonts |
+| `dot tune` | Apply supported host tuning changes |
+
+Themes are auto-generated from wallpapers — `themes.toml` is not hand-edited. See [Theming Guide](../guides/THEMING.md) for the K-Means CIELAB extraction model and Apple-compatible dynamic HEIC support.
+
+## AI Bridges
+
+| Command | Description |
+|---------|-------------|
+| `dot cl` | Invoke Claude Code with dotfiles context injection |
+| `dot copilot` | Invoke GitHub Copilot CLI with dotfiles context injection |
+| `dot gemini` | Invoke Gemini CLI with dotfiles context injection |
+| `dot kiro` | Invoke Kiro CLI with dotfiles context injection |
+| `dot sgpt` | Invoke Shell-GPT with dotfiles context injection |
+| `dot ollama` | Invoke Ollama with dotfiles context injection |
+| `dot opencode` | Invoke OpenCode with dotfiles context injection |
+| `dot aider` | Invoke Aider with dotfiles context injection |
+
+## Secrets
+
+| Command | Description |
+|---------|-------------|
+| `dot secrets-init` | Initialize the local age identity for secrets |
+| `dot secrets` | Manage encrypted secrets and environment buckets |
+| `dot secrets-create` | Create a new encrypted secrets file |
+| `dot ssh-key` | Encrypt a local SSH key with age |
+| `dot ssh-cert` | Manage short-lived SSH certificates (`issue`/`status`/`revoke`) |
+
+## Security (opt-in)
+
+| Command | Description |
+|---------|-------------|
+| `dot backup` | Create a compressed backup |
+| `dot encrypt-check` | Check disk encryption status |
+| `dot firewall` | Apply firewall hardening |
+| `dot telemetry` | Disable telemetry |
+| `dot dns-doh` | Enable DNS-over-HTTPS |
+| `dot lock-screen` | Enforce lock screen idle settings |
+| `dot usb-safety` | Disable automount for removable media |
+
+## Fleet
+
+| Command | Description |
+|---------|-------------|
+| `dot fleet` | Show fleet node status, namespace, and drift |
+| `dot fleet drift` | Check configuration drift across managed files |
+| `dot fleet namespace` | Show or set the active fleet namespace |
+| `dot fleet events` | Show recent local fleet events |

package/docs/security/AI_ACT_COMPLIANCE.md

@@ -0,0 +1,94 @@
+---
+render_with_liquid: false
+---
+
+# EU AI Act Compliance Assessment
+
+This document maps the dotfiles project against the EU Artificial Intelligence Act (Regulation (EU) 2024/1689) to confirm compliance posture and applicable obligations.
+
+---
+
+## Risk Classification (Annex III Assessment)
+
+| Criterion | Assessment | Result |
+|-----------|-----------|--------|
+| Biometric identification | Not applicable | N/A |
+| Critical infrastructure | Not applicable | N/A |
+| Education / employment | Not applicable | N/A |
+| Essential services | Not applicable | N/A |
+| Law enforcement | Not applicable | N/A |
+| Migration / border control | Not applicable | N/A |
+
+**Classification: Minimal Risk**
+
+This project is a workstation configuration management tool. It does not deploy, train, or host AI models. It integrates with external AI CLI tools (Claude, Gemini, Ollama) as a consumer, not a provider.
+
+---
+
+## Open-Source Exemption (Article 2(12))
+
+| Requirement | Status |
+|-------------|--------|
+| License type | MIT (permissive, open-source) |
+| Model weights distributed | No — no model training or distribution |
+| Free and open-source | Yes — publicly available source code |
+| No prohibited practices (Article 5) | Confirmed — no subliminal, exploitative, or social scoring use |
+
+**Result:** This project qualifies for the open-source exemption under Article 2(12). Open-source AI components released under free licenses are exempt from most AI Act obligations, provided they do not fall under prohibited practices or high-risk classifications.
+
+---
+
+## Transparency Obligations
+
+Even for minimal-risk and exempt systems, the AI Act encourages transparency. This project voluntarily implements the following:
+
+| Obligation | Implementation | Evidence |
+|-----------|----------------|----------|
+| AI interaction disclosure | Agent session logging | `agent-sessions.jsonl` via `dot_agent_session_log()` |
+| Model identification | Model registry | `dot_config/dotfiles/model-registry.json` |
+| Configuration transparency | Agent profiles | `dot_config/dotfiles/agent-profiles.json` |
+| Audit trail | Structured logging | `~/.local/share/dotfiles.log`, `~/.local/state/dotfiles/` |
+| Workstation attestation | Attestation export | `dot attest --json` |
+
+---
+
+## GPAI Provisions (Chapter V)
+
+| Criterion | Assessment |
+|-----------|-----------|
+| General-purpose AI model provider | **No** — this project does not train, fine-tune, or distribute AI models |
+| Systemic risk model | **No** — no model hosting or inference serving |
+| Downstream provider obligations | **No** — consumer of external AI APIs only |
+
+**Result:** GPAI provisions are not applicable. This project consumes AI services but does not provide them.
+
+---
+
+## Enforcement Timeline
+
+| Milestone | Date | Relevance |
+|-----------|------|-----------|
+| AI Act entered into force | August 1, 2024 | Awareness |
+| Prohibited practices apply | February 2, 2025 | Confirmed no prohibited use |
+| GPAI rules apply | August 2, 2025 | Not applicable |
+| High-risk obligations apply | **August 2, 2026** | Not applicable (minimal risk) |
+| Full enforcement | August 2, 2027 | Maintain compliance posture |
+
+**Next review:** Before August 2026 enforcement date — reassess if project scope changes to include model hosting or high-risk use cases.
+
+---
+
+## Cross-References
+
+| Document | Relevance |
+|----------|-----------|
+| [COMPLIANCE.md](COMPLIANCE.md) | SOC 2, ISO 27001, GDPR framework mapping |
+| [THREAT_MODEL.md](THREAT_MODEL.md) | Trust boundaries and attack surface |
+| [MCP_POLICY.md](MCP_POLICY.md) | MCP governance and supply-chain controls |
+| [SECURITY.md](SECURITY.md) | Core security model |
+
+---
+
+## Summary
+
+This project is classified as **minimal risk** under the EU AI Act and qualifies for the **open-source exemption** under Article 2(12). No mandatory obligations apply. Transparency measures are voluntarily implemented through agent session logging, model registry, and workstation attestation.

package/docs/security/AUDIT_BYPASS.md

@@ -0,0 +1,103 @@
+---
+render_with_liquid: false
+---
+
+# Pre-Push Audit Bypass
+
+This page documents when the pre-push reliability audit can be bypassed,
+how to do it, and why the answer is "almost never on `master`."
+
+## Background
+
+`scripts/git-hooks/pre-push` runs two checks on every push:
+
+1. **Signed-commit verification** — every commit being pushed must have
+   a valid GPG/SSH signature. No bypass is available; an unsigned
+   commit is refused unconditionally.
+
+2. **Reliability audit** — `scripts/qa/reliability-audit.sh --quick`
+   runs a fast subset of the test suite + lint checks. This is the
+   step that can be bypassed.
+
+Before issue #871 the audit was opt-out: `DOTFILES_SKIP_PRE_PUSH_AUDIT=1`
+in your shell rc would silently skip every push's audit. Bypass was
+invisible, persistent, and one keystroke away. That's the wrong default.
+
+## The new policy
+
+Effective with #871 and the corresponding commit on this branch:
+
+- The audit **always runs by default**. Missing env var → audit runs.
+- Bypass requires `DOTFILES_ALLOW_UNSKIPPED_PUSH=1` set inline for the
+  one push you want to bypass (not exported in your shell rc).
+- The legacy `DOTFILES_SKIP_PRE_PUSH_AUDIT=1` is **rejected** with a
+  migration message; the hook exits non-zero if it sees the old var.
+- Every bypass is appended to
+  `${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log` with
+  timestamp, branch, remote, and reason.
+- `dot doctor` reports the count of bypasses in the last 7 days.
+
+The new variable name is deliberately awkward
+(`DOTFILES_ALLOW_UNSKIPPED_PUSH`) — it should not feel like a routine
+flag. Setting it should require a moment's thought.
+
+## How to bypass for a single push
+
+```bash
+DOTFILES_ALLOW_UNSKIPPED_PUSH=1 \
+DOTFILES_BYPASS_REASON='hotfix: CI is wedged on flake' \
+  git push origin hotfix/my-branch
+```
+
+The reason string is optional but encouraged. It lands in the audit log
+so `dot doctor` and any future review can answer "why was this
+bypassed?" without git archaeology.
+
+## When bypass is legitimate
+
+Short list — anything outside this is suspicious:
+
+- **Hotfix push to a non-master branch** when CI infrastructure itself
+  is the audit blocker (e.g., the audit pre-flight depends on a remote
+  service that's down). The fix should land *before* the
+  infrastructure recovers; bypass is the bridge.
+- **Force-push of a tag rewind** that doesn't introduce new commits
+  (rare).
+
+When bypass is **not** legitimate:
+
+- Routine `master` pushes. The whole point of the audit is to guard
+  the protected branch.
+- Pushes whose audit failure is "annoying" — the right move is to fix
+  the failure, not skip the check.
+- CI environments. CI should run the audit explicitly, never bypass
+  it; if a CI job pushes, the env var must remain unset there.
+
+## Verifying current state
+
+```bash
+dot doctor   # surfaces recent bypasses
+cat ${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log
+```
+
+Each line of the log is tab-separated:
+`ISO8601-timestamp \t branch=... \t remote=... \t reason=...`.
+
+## Disabling bypass entirely
+
+If your machine should *never* bypass (e.g., a release runner), unset
+the env var in your shell rc and add a guard to your `.zshenv` or
+equivalent:
+
+```bash
+unset DOTFILES_ALLOW_UNSKIPPED_PUSH
+```
+
+There's no way to permanently grant bypass — that's intentional.
+
+## References
+
+- `scripts/git-hooks/pre-push` — the hook itself
+- `scripts/diagnostics/doctor.sh` — the "Pre-Push Audit Bypass" section
+- `tests/unit/security/test_pre_push_bypass.sh` — regression test
+- Issue #871

package/docs/security/AUTOMATION_SECRETS.md

@@ -0,0 +1,26 @@
+---
+render_with_liquid: false
+---
+
+# Automation Secrets
+
+## Required secrets
+
+| Secret | Scope | Purpose |
+| :--- | :--- | :--- |
+| `ACTIONS_BOT_SIGNING_KEY` | GitHub Actions | SSH private key used for signed automation commits |
+| `GITHUB_TOKEN` | GitHub Actions | GitHub API access for PRs, attestations, and scans |
+
+## Required local variables
+
+| Variable | Scope | Purpose |
+| :--- | :--- | :--- |
+| `HOMEBREW_INSTALLER_SHA256` | macOS bootstrap | Verifies the Homebrew installer before execution |
+| `CHEZMOI_INSTALLER_SHA256` | Installer | Verifies the Chezmoi installer before execution |
+
+## Provisioning notes
+
+1. Store the SSH signing private key in GitHub Actions as `ACTIONS_BOT_SIGNING_KEY`.
+2. Store the matching public key in [allowed_signers](/home/seb/.dotfiles/dot_config/git/allowed_signers).
+3. Rotate the key on personnel or workstation change.
+4. Fail closed when secrets are absent.

package/docs/security/CI_EGRESS_ALLOWLIST.md

@@ -0,0 +1,127 @@
+---
+render_with_liquid: false
+---
+
+# CI Egress Allowlist
+
+This page documents the network endpoints CI jobs are allowed to
+reach when `step-security/harden-runner` is operating in `block`
+mode. Managed under
+[#878](https://github.com/sebastienrousseau/dotfiles/issues/878).
+
+## Status
+
+All 76 jobs across the 28 workflow files in `.github/workflows/` are
+currently in **`audit` mode** — harden-runner is the first step in
+every job and records outbound network calls to the
+[step-security telemetry dashboard](https://app.stepsecurity.io) but
+does not block them.
+
+The next iteration (tracked as a follow-up under #878) flips each
+group to `block` once the audit-mode runs confirm the allowlist is
+complete. Switching one job at a time keeps blast radius small:
+a missing endpoint on a `block`-mode job fails the run loud and the
+list below gets updated.
+
+## Allowlist (by domain)
+
+This is the union of endpoints the entire workflow surface needs.
+When flipping a specific job to `block` mode, narrow this list to
+the endpoints that particular job actually touches.
+
+### GitHub itself (universally required)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `github.com:443` | every job | git clone, gh CLI |
+| `api.github.com:443` | every job | gh CLI, issue/PR API |
+| `objects.githubusercontent.com:443` | every job | release-asset downloads, LFS objects |
+| `*.actions.githubusercontent.com:443` | every job | runner ↔ orchestrator |
+| `pkg.actions.githubusercontent.com:443` | every job | action-cache CDN |
+| `results-receiver.actions.githubusercontent.com:443` | every job | workflow telemetry |
+| `codeload.github.com:443` | jobs that `git clone` tagged refs | tarball downloads for some actions |
+| `uploads.github.com:443` | jobs that upload artifacts | `actions/upload-artifact` |
+| `raw.githubusercontent.com:443` | the install-script jobs | curl-pull of unversioned content |
+
+### Package managers (apt, brew, cargo, npm, luarocks)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `azure.archive.ubuntu.com:443` | ubuntu jobs running `apt-get` | apt mirror |
+| `archive.ubuntu.com:80` | ubuntu jobs running `apt-get` | apt mirror |
+| `security.ubuntu.com:80` | ubuntu jobs running `apt-get` | security updates |
+| `keyserver.ubuntu.com:443` | jobs that add repo signing keys | GPG keyserver |
+| `formulae.brew.sh:443` | macOS jobs running `brew` | Homebrew formula index |
+| `ghcr.io:443` + `*.docker.io:443` | docker / container jobs | image pulls |
+| `registry.npmjs.org:443` | npm-publish.yml + the pre-commit npm hook | npm metadata + publish |
+| `registry-1.docker.io:443` | docker jobs | image manifests |
+| `crates.io:443` + `static.crates.io:443` | cargo-install jobs | crate downloads |
+| `index.crates.io:443` | cargo-install jobs | crate index |
+| `luarocks.org:443` + `*.luarocks.org:443` | reusable-lua-lint.yml | luacheck install |
+
+### Project-specific installers (chezmoi / mise / starship / stylua / typos / etc.)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `get.chezmoi.io:443` | `setup-chezmoi` composite (fallback path) | chezmoi installer |
+| `mise.run:443` | `setup-mise` composite | mise installer |
+| `releases.starship.rs:443` | mise-managed install of starship | starship binary |
+
+### Security / SBOM / scanning
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `api.osv.dev:443` | grype / scorecard | OSV vuln database |
+| `vulners.com:443` | grype | vulnerability metadata |
+| `toolbox-data.anchore.io:443` | anchore/sbom-action | SBOM tooling |
+| `api.deps.dev:443` | future deps.dev integration (#877) | package metadata |
+| `api.securityscorecards.dev:443` | scorecard.yml | publish_results upload |
+| `*.codeql.github.com:443` | codeql.yml | CodeQL bundle download |
+
+## Job-level egress notes (legitimate broad-egress jobs)
+
+A few jobs need wider network access than the standard allowlist
+covers. Each carries an inline comment near the harden-runner step
+explaining the deviation so reviewers can audit at a glance.
+
+### `update-deps.yml` — broad GitHub API egress
+
+Polls multiple `github.com/<repo>/releases/latest` endpoints to find
+new tool versions. Allowlist needs to include `api.github.com:443`
+and the raw-content domain for sed-replacing version strings.
+
+### `devcontainer-prebuild.yml` — registry push
+
+Pushes to `ghcr.io:443` with the `packages: write` token. The egress
+allowlist for that job is the standard set plus `ghcr.io` writes.
+
+### `nightly.yml` — `Beta/Nightly Tools Test` job
+
+This job deliberately runs `curl ... | tar -xJf -` against the
+shellcheck release. Justified because the job is `continue-on-error: true`
+and is opt-in (manual or scheduled). Future hardening: download the
+release asset, verify a known hash, then exec — same shape as
+`scripts/ci/install-chezmoi-verified.sh`.
+
+## Updating this page
+
+Whenever a job is flipped to `block` mode:
+
+1. Run the audit-mode workflow at least once after every recent
+   workflow change to make sure the harden-runner telemetry reflects
+   reality.
+2. Visit the [step-security dashboard](https://app.stepsecurity.io/)
+   filtered to the repo + job + last 7 days.
+3. Add any endpoints the dashboard reports that aren't already in
+   this page's tables.
+4. Edit the job to set `egress-policy: block` and add the per-job
+   `allowed-endpoints:` block listing only what that specific job
+   needs (not the whole union).
+5. Land the change, watch the first run; if anything fails the run
+   loud, add the missing endpoint and retry.
+
+## References
+
+- `step-security/harden-runner` — [https://github.com/step-security/harden-runner](https://github.com/step-security/harden-runner)
+- `docs/security/SCORECARD.md` — Token-Permissions check ties to harden-runner adoption.
+- Issue [#878](https://github.com/sebastienrousseau/dotfiles/issues/878).