@sebastienrousseau/dotfiles 0.2.520 → 0.2.522

package/docs/MAINTAINERS.md

@@ -1,41 +0,0 @@
-# Maintainers
-
-This project is maintained by a single primary maintainer with an
-explicit, documented governance model (see [`GOVERNANCE.md`](GOVERNANCE.md)).
-
-## Primary maintainer
-
-- **Sebastien Rousseau** — <sebastian.rousseau@gmail.com>
-  - GitHub: [@sebastienrousseau](https://github.com/sebastienrousseau)
-  - Role: project owner, release manager, security disclosure contact
-  - Commit signing: SSH ED25519 (`SHA256:kIOPAavp1TCEauTr1tTIN3cv+tSs6F9m/4lZjuM9tqk`)
-  - GPG disclosure key fingerprint: `55AFAD364FD9DB3819E61F0C8D688FAFA9144693` (ed25519 + cv25519, expires 2029-05-15, published via WKD at `security@sebastienrousseau.com`)
-
-## Active contributors
-
-This is a solo-maintained project. Contributions are welcomed via
-pull request (see `CONTRIBUTING.md`); the maintainer reviews and
-merges. When the project gains additional regular committers their
-names will land here with role and contact.
-
-## Security contact
-
-For coordinated vulnerability disclosure, follow `SECURITY.md`.
-TL;DR: encrypt your report to the WKD-published GPG key above and
-email `security@sebastienrousseau.com`. Acknowledgement SLA: 72 hours.
-
-## Backup / continuity
-
-In the event the primary maintainer becomes unable to maintain the
-project, the repository is published under the MIT license and may
-be forked. The `chezmoi`-based architecture means existing user
-installs continue to work indefinitely without upstream activity.
-
-## Releases
-
-| Release author | Cadence | Signing |
-|---|---|---|
-| Primary maintainer | ~weekly | Signed annotated git tag + Cosign-signed SBOM + SLSA L3 provenance |
-
-See `docs/operations/HARD_AUDIT_2026.md` Part 7 for the
-disclosure-key generation + WKD publication record.

package/docs/MINIMUM-TOOLCHAIN.md

@@ -1,100 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
-
-# Minimum toolchain policy
-
-This project has no compiler and therefore no MSRV. The equivalent
-contract is the set of **interpreter and tool versions the framework
-runs on**, and — more importantly — the policy for when those floors
-may move.
-
-The policy matters more than the numbers. A floor stated without a
-policy is a number that drifts silently; a floor stated without CI
-behind it is a claim, not a guarantee. Everything marked "enforced"
-below is a job in `.github/workflows/`; everything else is labelled
-as expectation.
-
-## The floors
-
-| Component | Floor | Why this floor | Enforced by |
-|---|---|---|---|
-| **bash** (running `dot`, `install.sh`, every script) | **3.2** | macOS still ships bash 3.2 as `/bin/bash` and always will (GPLv3). The CLI must work there or `dot` breaks on a stock Mac. No associative arrays, no `mapfile`/`readarray`, no `${var,,}`. | `cross-platform-test.yml` and `reliability-gate.yml` on `macos-latest` + `macos-14`, whose stock `/bin/bash` is 3.2.57 |
-| **bash** (as an *interactive* shell with the full config) | **5.0** | The shell configuration (completions, prompt hooks) uses bash 5 features. This is a different, higher floor than the CLI's. | `reusable-test-suite.yml` on ubuntu-latest |
-| **zsh** | **5.8** | The default interactive shell; `rc.d` ordering and the completion system assume 5.8. | `cross-platform-test.yml` (macOS stock zsh 5.9, Ubuntu 5.9) |
-| **fish** | **4.0** | `dot`, the alias bridge, and the generated completions target the fish 4 syntax. | `ci.yml` job `Lint / Fish` |
-| **nushell** | **0.98** | Tier-3 reference shell; see [ADR-011](adr/ADR-011-nushell-tier3-keep.md). | `ci.yml` job `Lint / Nushell` |
-| **PowerShell** | **7.5** | The Windows parity surface. Note `windows-latest` currently ships 7.4 LTS, so CI proves 7.4 and the 7.5 claim covers features gated behind it. | `reliability-gate.yml` job `PowerShell Contract` on `windows-latest` |
-| **git** | **2.34** | The oldest release with SSH commit/tag signing (`gpg.format = ssh`), which the signing and verification flow requires. | Not version-gated in CI; the signing workflows exercise it on runner git (≥ 2.40) |
-| **chezmoi** | **2.47.1** | The pinned, checksum-verified version `install.sh` and CI install. Newer works; older is untested. | `install.sh` and `CHEZMOI_VERSION` in `ci.yml`, `ci-enforced.yml`, `perf-baseline.yml` |
-| **Go** (fuzz harnesses and the two TUIs only — not needed to *use* the framework) | **1.23** | `fuzz/go.mod`. | `fuzz.yml`, `cockpit-test.yml`, `dot-ui-test.yml` |
-| **Python** (pre-commit and the docs build only) | **3.12** | `pre-commit.yml`, `requirements-docs.txt`. | `pre-commit.yml`, `pages.yml` |
-
-`make install` additionally needs GNU make or BSD make and a POSIX
-`install(1)`; nothing else.
-
-## Distro mapping — what is actually verified
-
-The rule the repository standard sets is: **never claim distro-LTS
-compatibility without a table mapping current distro toolchains to the
-floor.** Here is that table, with an honest column for whether CI
-proves it.
-
-| Platform | Ships bash | Ships zsh | Ships git | Meets the CLI floor? | In CI? |
-|---|---|---|---|---|---|
-| Ubuntu 24.04 LTS (`ubuntu-latest`) | 5.2 | 5.9 | 2.43 | Yes | **Yes** — the primary Linux runner across ~20 workflows |
-| Ubuntu 22.04 LTS | 5.1 | 5.8 | 2.34 | Yes | No — expected to work; not exercised since runners moved to 24.04 |
-| Debian 12 (bookworm) | 5.2 | 5.9 | 2.39 | Yes | No — same package versions as Ubuntu 22.04/24.04; expected, unverified |
-| Debian 13 (trixie) | 5.2 | 5.9 | 2.47 | Yes | No |
-| RHEL 9 / Rocky 9 / Alma 9 | 5.1 | 5.8 | 2.43 | Yes | No — no RHEL-family runner or container in CI |
-| RHEL 10 / Rocky 10 | 5.2 | 5.9 | 2.47 | Yes | No |
-| Fedora 41+ | 5.2 | 5.9 | 2.47 | Yes | No |
-| Arch Linux (rolling) | current | current | current | Yes | No — AUR package published, not CI-tested |
-| Alpine (musl, busybox ash) | — | — | 2.45 | **No** — bash is not installed by default and `install.sh` requires it | No |
-| macOS 14+, stock `/bin/bash` | **3.2.57** | 5.9 | 2.39+ (Xcode) | Yes — this is why the CLI floor is 3.2 | **Yes** — `macos-latest`, `macos-14` |
-| macOS + Homebrew bash | 5.3 | 5.9 | 2.5x | Yes | Yes (same runners, Homebrew bash present) |
-| Windows 11 + PowerShell 7.4 | n/a | n/a | 2.4x | Core CLI surface only | **Yes** — `windows-latest` PowerShell contract |
-| WSL2 (Ubuntu) | 5.2 | 5.9 | 2.43 | Yes | Partially — `reliability-gate.yml` runs a WSL *contract* check on Linux, not a real WSL VM |
-
-Read the last column as the honest one. "Expected, unverified" means
-the package versions clear the floor by inspection but no job proves
-it; a bug report from such a platform is legitimate and welcome.
-
-## When a floor may rise
-
-A floor is not a promise never to move — it is a promise about *how*
-it moves.
-
-1. **A raise is a breaking change** for the affected surface and gets
-   a minor-version bump (a major once this project reaches 1.0), never
-   a patch.
-2. **A raise needs a reason recorded in the changelog entry**: the
-   specific feature or fix that requires it. "Newer is better" is not
-   a reason.
-3. **The bash 3.2 floor for the CLI does not move while macOS ships
-   3.2 as `/bin/bash`.** This one is effectively permanent. Code that
-   needs bash 4+ goes in a script that is not on the `dot` startup
-   path, and says so in a comment.
-4. **A raise must be enforced by CI in the same pull request** that
-   raises it. Bumping a documented number without moving the matrix
-   produces exactly the aspirational claim this policy exists to
-   prevent.
-5. **Deprecation window**: one minor release announcing the intent in
-   the changelog before the floor actually rises, so a pinned consumer
-   sees it coming.
-
-## Where the numbers live
-
-| Number | Source of truth |
-|---|---|
-| chezmoi version | `CHEZMOI_VERSION` in `.github/workflows/ci.yml`, mirrored into `install.sh` |
-| Go version | `fuzz/go.mod` |
-| Every other pinned tool | `mise.toml` + `mise.lock` |
-| Python docs deps | `requirements-docs.txt` (hash-pinned) |
-| Platform/shell support tiers | [`reference/SUPPORT_MATRIX.md`](reference/SUPPORT_MATRIX.md) |
-
-If this document and one of those files disagree, the file wins and
-this document is the bug.

package/docs/NAMING_CONVENTIONS.md

@@ -1,102 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Naming Conventions & Standardization Guide
-
-This document defines the naming conventions for all files in the dotfiles repository.
-
----
-
-## File Naming
-
-| Context | Convention | Example |
-|---|---|---|
-| Run scripts | `run_{type}_{NN}-{verb}-{noun}.sh.tmpl` | `run_onchange_10-install-packages.sh.tmpl` |
-| Shell fragments | `{NN}-{domain}-{detail}.sh.tmpl` | `90-ux-aliases.sh.tmpl` |
-| Alias files | `{tool}.aliases.sh` | `git.aliases.sh` |
-| Function files | `{name}.sh` (lowercase) | `apihealth.sh` |
-| Test files | `test_{domain}_{feature}.sh` | `test_aliases_git.sh` |
-| Scripts | `{verb}-{noun}.sh` (hyphenated) | `install-nerd-fonts.sh` |
-
-## Run Script Numbering Tiers
-
-| Range | Category | Examples |
-|---|---|---|
-| 00-09 | Audit & pre-flight | `run_before_00-audit.sh` |
-| 10-19 | Package installation | `run_onchange_10-linux-packages.sh.tmpl` |
-| 20-29 | Config & languages | `run_onchange_20-ghostty-config.sh.tmpl` |
-| 25-29 | Language toolchains | `run_onchange_25-python-tools.sh.tmpl` |
-| 30-39 | Applications | `run_onchange_30-vscode-extensions.sh.tmpl` |
-| 40-49 | System defaults | `run_onchange_40-darwin-default-apps.sh.tmpl` |
-| 50-59 | Assets (fonts, themes) | `run_onchange_50-install-fonts.sh.tmpl` |
-
----
-
-## Adding New Modules
-
-### New app config
-
-1. Create `dot_config/<app>/` with chezmoi-compatible filenames
-2. Add entry to `dot_config/.module-manifest.json`
-3. Optionally gate with feature flag in `.chezmoidata.toml` + `.chezmoiignore.tmpl`
-
-### New alias category
-
-1. Create `.chezmoitemplates/aliases/<category>/<name>.aliases.sh`
-2. The `**/*.aliases.sh` glob auto-discovers it
-3. Add to `$coreCategories` list in `90-ux-aliases.sh.tmpl` for eager loading; otherwise it loads lazily
-
-### New function
-
-1. Create file in `.chezmoitemplates/functions/<group>/`
-2. Add to `groups.json` with the `<group>/<filename>` path
-3. It auto-registers for lazy loading via `51-logic-functions-extra.sh.tmpl`
-
-### New provisioning script
-
-1. Create `install/provision/run_onchange_{NN}-{name}.sh.tmpl`
-2. Use the numbering tiers above
-3. Source `install/lib/os_detection.sh` for platform detection
-4. Guard OS-specific code with `{{ if eq .chezmoi.os "darwin" }}`
-
----
-
-## Directory Structure Overview
-
-```text
-.chezmoitemplates/
-  aliases/        # 48 categories, auto-discovered
-  functions/      # Grouped by domain (api/, curl/, text/, system/, etc.)
-  paths/          # PATH construction templates
-  desktop/        # Desktop environment templates (dconf)
-
-dot_config/       # Flat — chezmoi constraint, no intermediate grouping
-
-install/
-  lib/            # Shared helpers (os_detection, logging, installers)
-  provision/      # run_onchange_* provisioning scripts
-
-scripts/          # Repo-only scripts (not deployed)
-  dot/            # dot CLI subcommands
-  ops/            # Operations scripts
-  diagnostics/    # Health checks
-  security/       # Security tools
-  ...
-
-tests/            # Test suite (not deployed)
-  framework/      # Test runner, assertions, mocks
-  unit/           # Domain-organized unit tests
-  integration/    # End-to-end tests
-  performance/    # Benchmarks
-
-docs/             # Documentation and GitHub Pages source
-  architecture/   # System design docs
-  guides/         # How-to guides
-  reference/      # Reference material
-  security/       # Security documentation
-  operations/     # Ops and maintenance docs
-```
-
-{% endraw %}

package/docs/OPENCODE.md

@@ -1,127 +0,0 @@
-<!--
-  Role:     Repo-scoped instructions for the OpenCode CLI when operating
-            inside this repository. Mirrors CLAUDE.md but targets OpenCode's
-            conventions/discovery.
-  Audience: OpenCode, this repo only.
-
-  Distinct from:
-    - CLAUDE.md           — same intent, but for Claude Code.
-    - dot_claude/CLAUDE.md — PERSONAL cross-project Claude Code preferences,
-                             deployed to ~/.claude/CLAUDE.md by chezmoi.
-
-  Keep CLAUDE.md and OPENCODE.md in sync on repo-level conventions (layout,
-  naming, CI, testing). If they drift, CLAUDE.md is the source of truth.
--->
-
-# OPENCODE.md — AI Assistant Guidelines for Dotfiles Repository
-
-## Chezmoi Source Directory Conventions
-
-This is a **chezmoi-managed** dotfiles repository. Files here are *source templates*,
-not the deployed config files. Understanding the naming conventions is critical.
-
-### File Naming Rules
-
-| Prefix/Suffix    | Meaning                                              |
-|------------------|------------------------------------------------------|
-| `dot_`           | Deployed with a leading `.` (e.g., `dot_zshrc` -> `.zshrc`) |
-| `executable_`    | Deployed with `+x` permission                        |
-| `private_`       | Deployed with `0600` permissions                      |
-| `.tmpl`          | **Go template** — processed by chezmoi before deployment |
-| `run_onchange_`  | Script that runs when the target file changes         |
-| `encrypted_`     | Age-encrypted file, decrypted at deploy time          |
-
-### Critical: Template vs Non-Template Files
-
-Many shell config files exist **only** as `.tmpl` variants. When reading files:
-
-- `dot_config/shell/00-core-paths.sh` does **NOT** exist
-- `dot_config/shell/00-core-paths.sh.tmpl` **DOES** exist (this is the source)
-
-**Rule**: If a `.sh` or `.zsh` file is not found, always try appending `.tmpl`.
-
-Files that are templates (use Go template syntax like `{{ .variable }}`):
-
-- `dot_config/shell/*.sh.tmpl` — all shell layer files
-- `dot_config/zsh/dot_zshrc.tmpl` — main zsh config
-- `dot_config/zsh/rc.d/*.tmpl` — zsh startup modules
-- `dot_gitconfig.tmpl` — git configuration
-- `private_dot_ssh/config.tmpl` — SSH configuration
-- `dot_npmrc.tmpl` — npm configuration
-- `private_dot_netrc.tmpl` — netrc credentials
-
-Files that are **NOT** templates (plain files, no `.tmpl` suffix):
-
-- `dot_config/shell/00-container-detect.sh` — plain shell script
-- `dot_config/shell/90-theme-switch.sh` — plain shell script
-- `dot_config/zsh/rc.d/00-alias-shims.zsh` — plain zsh
-- `dot_config/zsh/rc.d/05-ssh-agent.zsh` — plain zsh
-- Most files under `dot_config/nvim/`, `dot_config/starship.toml.tmpl`, etc.
-
-### Reading Template Files
-
-Template files contain Go template directives like:
-
-```
-{{ if eq .chezmoi.os "darwin" }}
-  # macOS-specific config
-{{ end }}
-```
-
-Data variables come from `.chezmoidata.toml` (profiles, features, theme, tools).
-User-specific values (git identity, age keys) come from `~/.config/chezmoi/chezmoi.toml`.
-
-### Repository Layout
-
-```
-.chezmoidata.toml           # Feature flags, profiles, version
-.chezmoitemplates/          # Reusable template partials (aliases, functions, paths)
-dot_config/                 # XDG configs (~/.config/*) — largest directory
-  zsh/                      # Zsh configuration
-    dot_zshrc.tmpl          # Main zsh orchestrator
-    rc.d/                   # Startup modules (sourced in order)
-  shell/                    # POSIX shell layers (paths, safety, aliases, functions)
-  nvim/                     # Neovim configuration (Lua)
-  mise/                     # mise version manager config
-  starship.toml.tmpl        # Starship prompt config
-  atuin/                    # Atuin shell history
-  bat/                      # bat (cat replacement) config
-  ghostty/                  # Ghostty terminal config
-  kitty/                    # Kitty terminal config
-  alacritty/                # Alacritty terminal config
-dot_local/bin/              # User scripts (~/.local/bin)
-scripts/                    # Repo-only scripts (tests, ops, security, diagnostics)
-docs/                       # Documentation (30+ files)
-install.sh                  # Bootstrap installer
-```
-
-### Shell Startup Chain
-
-```
-~/.zshenv (dot_zshenv)           → XDG vars, PATH, ZDOTDIR
-~/.config/zsh/.zshrc (dot_zshrc.tmpl) → Main orchestrator
-  → rc.d/00-alias-shims.zsh     → Single-letter fallback commands
-  → rc.d/05-ssh-agent.zsh       → SSH agent + YubiKey
-  → rc.d/10-env.zsh.tmpl        → Environment variables
-  → rc.d/20-zinit.zsh.tmpl      → Plugin manager (deferred)
-  → rc.d/30-options.zsh.tmpl    → History, keybindings, completions
-  → rc.d/40-bell.zsh.tmpl       → Bell settings
-  → rc.d/50-login-fortune.zsh.tmpl → Login greeting
-  → shell/00-core-paths.sh.tmpl → Full PATH construction
-  → shell/05-core-safety.sh.tmpl → Safety defaults
-  → shell/90-ux-aliases.sh.tmpl → Core aliases (eager)
-  → [deferred] mise, atuin, starship, zoxide, fzf
-  → [lazy] shell/91-ux-aliases-lazy.sh.tmpl → Tool aliases
-```
-
-### Key Data Files
-
-- `.chezmoidata.toml` — All configuration: profiles, feature flags, tool settings
-- `dot_config/mise/conf.d/00-dotfiles.toml` — mise tool versions (node, python, go, rust, etc.); the writable `~/.config/mise/config.toml` is mise-owned and not chezmoi-managed
-- `dot_config/starship.toml.tmpl` — Prompt configuration
-
-### Testing
-
-- Test framework: `tests/framework/`
-- Unit tests: `tests/unit/`
-- Tests execute bash source files directly — they do NOT use Go template syntax

package/docs/README.md

@@ -1,84 +0,0 @@
----
-render_with_liquid: false
----
-
-# Documentation
-
-Start here. Then go deeper.
-
-## The Manual
-
-The complete reference is the `.dotfiles` Manual — a multi-format book covering every concept, tutorial, reference, and recipe.
-
-- Online: <https://sebastienrousseau.github.io/dotfiles/manual/> (HTML, PDF, EPUB, ASCII)
-- Locally: `dot manual` opens the HTML in your browser
-- Sources: [`docs/manual/`](manual/)
-
-Quick jumps into the Manual:
-
-- [Introduction](manual/00-introduction.md) — who, what, how
-- [Concepts](manual/01-concepts/) — architecture, trust model, theme engine, fleet, self-healing
-- [Tutorials](manual/02-tutorials/) — first install, wallpaper→theme, profiles, secrets, fleet
-- [Reference](manual/03-reference/) — CLI, config files, environment, templates, feature flags
-- [Cookbook](manual/04-cookbook/) — 40+ recipes, troubleshooting, FAQ
-
-## Start
-
-- [Install](guides/INSTALL.md)
-- [Troubleshooting](guides/TROUBLESHOOTING.md)
-- [Support matrix](reference/SUPPORT_MATRIX.md)
-
-## Daily use
-
-- [Utilities and `dot` CLI](reference/UTILS.md)
-- [Operations](operations/OPERATIONS.md)
-- [Trusted agent workstation](operations/TRUSTED_AGENT_WORKSTATION.md)
-- [Workstation attestation](operations/ATTESTATION.md)
-- [Interoperability](architecture/INTEROP.md)
-- [Agent interoperability](interop/A2A.md)
-- [AI integrations](AI.md)
-
-## Security and trust
-
-- [Security overview](security/SECURITY.md)
-- [Security checklist](security/SECURITY_CHECKLIST.md)
-- [Policy bundle releases](security/POLICY_RELEASES.md)
-- [Secrets](security/SECRETS.md)
-- [Compliance](security/COMPLIANCE.md)
-- [Threat model](security/THREAT_MODEL.md)
-
-## Build and maintain
-
-- [Testing](operations/TESTING.md)
-- [Reliability](operations/RELIABILITY.md)
-- [Naming conventions](NAMING_CONVENTIONS.md)
-- [Architecture](ARCHITECTURE.md)
-- [Repository layout](architecture/REPO_LAYOUT.md)
-- [AI cost optimization](architecture/AI_COST_OPTIMIZATION.md)
-- [Release pipeline](operations/RELEASE_PIPELINE.md)
-- [Architecture decisions](adr/README.md)
-
-## Repository map
-
-| Path | Purpose |
-| :--- | :--- |
-| `docs/` | Guides, reference, security, and architecture |
-| `scripts/` | Repo-only scripts and `dot` command internals |
-| `install/` | Installer and provisioning helpers |
-| `dot_config/` | Managed user configuration files |
-| `dot_local/` | Managed local executables |
-| `examples/` | Executable examples |
-| `tests/` | Unit, integration, and framework coverage |
-
-## Platform guides
-
-- [WSL2 and Nix](guides/WSL2_NIX_TROUBLESHOOTING.md)
-- [Neovim IDE](guides/NEOVIM_IDE_GUIDE.md)
-
-## Reference
-
-- [Features](reference/FEATURES.md)
-- [Tools](reference/TOOLS.md)
-- [Aliases](reference/ALIASES.md)
-- [Roadmap](operations/ROADMAP.md)
-- [Version sync](operations/VERSION_SYNC.md)

package/docs/STRUCTURE.md

@@ -1,102 +0,0 @@
-# Repository Structure
-
-This document maps every top-level path in the repository to its
-purpose. Skim it once and you should be able to answer:
-
-- **Where is the `dot` CLI?** → `bin/dot` (the source-of-truth file). At runtime it lives at `~/.local/bin/dot`.
-- **Why are there 20+ `dot_*` files at root?** → chezmoi convention: a `dot_X` source file deploys to `~/.X` on apply. Same for `executable_*` (gains `+x`), `private_*` (`0600`), `run_onchange_*` (re-runs when source changes).
-- **What's the framework vs. the maintainer's personal config?** → Everything under `scripts/`, `install/`, `tools/`, `lib/`, and `defaults/.chezmoitemplates/` is framework code. Everything under `defaults/dot_config/`, `defaults/dot_warp/`, `defaults/private_dot_ssh/` is user-facing default configuration (chezmoi auto-rebases via `.chezmoiroot`).
-
-The Debian/aws-cli-style root layout shipped in **v0.2.503**:
-`bin/` (dispatcher), `lib/` (shared bash libs), `defaults/`
-(all chezmoi-tracked source files, rebased via
-`.chezmoiroot`). Repo root now hosts only project/CI/docs paths.
-See `docs/operations/ROADMAP_V0_2_503.md` for the full history.
-
----
-
-## Top-level paths
-
-| Path | Kind | Purpose |
-|------|------|---------|
-| **CLI + framework** | | |
-| `dot_local/bin/` | framework | `executable_dot` (CLI entrypoint) and helper scripts. Deploys to `~/.local/bin/`. |
-| `dot_local/share/` | framework | Man pages, zsh completions. Deploys to `~/.local/share/`. |
-| `scripts/` | framework | Runtime-invoked scripts (`dot` CLI dispatch + specialised subtrees). See `scripts/README.md`. |
-| `tools/` | repo-ops | Repo-only ops: CI helpers, release, maintenance, docs-generation. Not distributable. See `tools/README.md`. |
-| `lib/dot/` | framework | Shared bash library sourced by every `dot` subcommand and the dispatcher. Reorganised here from `scripts/dot/lib/` per RFC Phase 1. See `lib/dot/README.md`. |
-| `lib/` | framework | Library tree (`lib/dot/` + the `dot-sys` Rust crate in `lib/wasm-tools/`, built for `wasm32-wasip1` and run under `wasmtime` by `dot attest --verify`). |
-| `install/` | framework | Bootstrap logic + distribution-channel manifests (`homebrew/`, `scoop/`, `aur/`). See `install/README.md`. `install/provision/` runs on `chezmoi apply` via `run_onchange_*` triggers. |
-| `install.sh` | framework | Top-level installer. SHA256-verified chezmoi fetch + initial apply. |
-| `.chezmoitemplates/` | framework | Reusable Go-template partials (aliases, functions, paths). Sourced by `dot_*.tmpl` files. |
-| **User-facing defaults** | | |
-| `dot_bashrc`, `dot_zshrc`, `dot_zshenv`, `dot_zprofile`, `dot_profile`, `dot_vimrc`, etc. | defaults | Shell + editor rc files. Deploy to `~/.X`. |
-| `dot_config/` | defaults | XDG config (`~/.config/*`). Largest tree — 80+ tool configs. |
-| `dot_local/` (non-bin/share) | defaults | Per-user state files for tools (`dot_local/state/`, etc.). |
-| `dot_cargo/`, `dot_etc/`, `dot_warp/` | defaults | Tool-specific roots (cargo, system etc, Warp terminal). |
-| `private_dot_ssh/` | defaults | SSH config — chezmoi `private_` prefix forces 0600. Does NOT contain private keys. |
-| `dot_claude/` | defaults | Claude Code per-user skills and config. |
-| **Templates + data** | | |
-| `templates/` | framework | Non-chezmoi templates (e.g. for `dot agents render`). |
-| `.chezmoidata/` | data | Hardware presets (`macbook-t2`, `surface-pro`) read by templates. |
-| `.chezmoidata.toml` | data | Feature flags + version. Single source-of-truth for `dotfiles_version`. |
-| `.chezmoi.toml.tmpl` | framework | Per-host chezmoi config generated on first apply. |
-| `.chezmoiignore` / `.chezmoiignore.tmpl` | framework | Tells chezmoi which paths NOT to deploy. |
-| **Docs + tests** | | |
-| `docs/` | docs | All documentation: `manual/` (user guide), `operations/` (audits, roadmaps), `reference/` (lookup tables), `security/`. |
-| `tests/` | tests | Test suite: `framework/` (runner + assertions + mocks), `unit/`, `integration/`, `regression/`, `fuzz/`, `snapshots/`. |
-| `examples/` | docs | Standalone examples (mise plugin, AI patterns, ops scripts). |
-| **CI + release** | | |
-| `.github/` | ci | GitHub Actions workflows + issue/PR templates + repo-level SECURITY/CODEOWNERS. |
-| `.devcontainer/` | ci | Dev Container spec for reproducible contributor onboarding. |
-| `Dockerfile.test` | ci | Container baseline for the CI test job. |
-| `.pre-commit-config.yaml` → `config/pre-commit-config.yaml` | ci | Pre-commit hooks (shellcheck, shfmt, luacheck, gitleaks, typos, conventional-commits). |
-| `flake.nix` / `flake.lock` | ci | Nix flake for reproducible dev shell. |
-| `mise.toml` / `mise-versions.lock.json` | ci | Pinned tool versions (mise as the package manager). |
-| **Misc + agents** | | |
-| `AGENTS.md` | docs | Cross-harness AI agent context (the standard read by Codex/Cursor/etc.). |
-| `.cursor/`, `.codex/`, `.windsurf/`, `.zed/`, `.roo/`, `.clinerules`, `.aider.conf.yml`, `.continuerc.json`, `.jules/`, `.agy/` | agents | Per-harness AGENTS.md renderings. Generated by `dot agents render`. Each one points back at `CLAUDE.md` as canonical. |
-| `CLAUDE.md` | docs | Project guidelines (the canonical source — `dot agents render` propagates it). |
-| `CONTRIBUTING.md` | docs | Contributor guide (must stay at root for GitHub auto-discovery). |
-| `docs/CONFIG_STRATEGY.md`, `docs/OPENCODE.md` | docs | Strategy + OpenCode-CLI guidance. Moved out of root for cleanliness in v0.2.503. |
-| `README.md` / `CHANGELOG.md` / `LICENSE` | docs | Standard project files. |
-| `Justfile.tmpl` / `Makefile` | dev | Task runners. |
-| `dist/` | build | Build artefacts directory. |
-| `coverage/`, `nightly-reports/` | build | CI output directories (gitignored). |
-| `nix/` | build | Nix flake source. |
-| `.well-known/` | misc | RFC-compliant `.well-known/` content (currently used for WKD GPG key publication). |
-| `.version-sync-backup/` | misc | Backup directory used by `scripts/version-sync.sh` during release prep. |
-
-## Chezmoi naming contract
-
-| Prefix / suffix | Effect on deployment |
-|---|---|
-| `dot_foo` | Deploys as `.foo` (the `dot_` is consumed). |
-| `executable_foo` | Adds `+x` permission. |
-| `private_foo` | Sets `0600` permission. |
-| `run_onchange_foo.sh` | Script re-executes when its hash changes. |
-| `*.tmpl` | Processed as a Go template with chezmoi data before deployment. |
-
-**Critical gotcha:** `executable_dot_foo` deploys as `.foo` (not
-`dot_foo`). The `dot_` prefix is consumed by chezmoi after the
-`executable_` prefix. Renaming a deployed file silently can leave
-stale state in `~/.config/chezmoi/`.
-
-## Where to make changes
-
-| Goal | File(s) to edit |
-|------|----------------|
-| Add a new `dot <subcommand>` | `scripts/dot/commands/<subcommand>.sh` + dispatch in `bin/dot` + entry in `docs/manual/03-reference/01-dot-cli.md` + entry in `docs/manual/command-index.md`. |
-| Change an alias | `.chezmoitemplates/aliases/<file>.aliases.sh` (sourced by `dot_zshrc.tmpl`, etc.). |
-| Add a feature flag | `[features]` block in `.chezmoidata.toml` + doc entry in `docs/manual/03-reference/05-feature-flags.md`. |
-| Add a new file deployed to `~/.X` | Create `dot_X` at root (or under a chezmoi-managed subtree). |
-| Add a new chezmoi template | `dot_X.tmpl` at root, then use `{{ }}` for chezmoi data. |
-| Add a CI workflow | `.github/workflows/<name>.yml`. |
-| Add a test | `tests/unit/<domain>/test_<name>.sh` or `tests/integration/test_<name>.sh`. |
-
-## See also
-
-- `scripts/README.md` — map of the `scripts/` subtree.
-- `CONTRIBUTING.md` — code-style + commit-message + signing requirements.
-- `CLAUDE.md` — AI-assistant guidelines (the canonical source for `dot agents render`).
-- `docs/operations/ROADMAP_V0_2_503.md` — current release scope, including the v0.2.503 reorganisation plan.

package/docs/adr/ADR-001-ci-cd-pipeline.md

@@ -1,118 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# ADR-001: Multi-stage CI/CD Pipeline Design
-
-**Status**: Accepted
-**Date**: 2026-02-09
-**Authors**: @sebastienrousseau
-
-## Context
-
-The dotfiles repository requires a CI/CD pipeline that:
-
-- Validates changes across multiple platforms (Linux, macOS)
-- Runs security scans to detect secrets and vulnerabilities
-- Tests shell scripts, Lua configurations, and Nix expressions
-- Maintains fast feedback loops for developers
-- Minimizes GitHub Actions costs (runner minutes)
-
-Traditional approaches run all checks on every commit, leading to:
-
-- Wasted compute on unrelated changes (e.g., running Lua linting when only docs change)
-- High costs from macOS runners ($0.08/min vs $0.008/min for Linux)
-- Long feedback times from sequential job execution
-
-## Decision
-
-Implement a **5-stage progressive CI pipeline** with path-based filtering:
-
-### Stage 1: Change Detection
-
-Use `dorny/paths-filter` to detect which file categories changed:
-
-- `shell`: *.sh, scripts/**, install/**
-- `lua`: dot_config/nvim/**, *.lua
-- `nix`: nix/**, *.nix
-- `config`: dot_*/**, .chezmoitemplates/**
-
-### Stage 2: Lint (Parallel, Conditional)
-
-- **lint-shell**: Only runs if shell files changed
-- **lint-lua**: Only runs if Lua files changed
-- Run in parallel to minimize wall-clock time
-
-### Stage 3: Security (Always on PRs)
-
-- **secrets-scan**: Gitleaks on every PR (critical)
-- **link-check**: Only on schedule (expensive)
-
-### Stage 4: Test (Conditional Matrix)
-
-- Linux-only for PRs (cheapest)
-- Full matrix (Linux + macOS) on schedule/manual trigger
-- Docker container tests for installation validation
-
-### Stage 5: Quality (Schedule/Manual Only)
-
-- Idempotency verification
-- Performance benchmarks
-- Nix flake checks
-
-### Cost Optimization Strategies
-
-1. **Path filters**: Skip jobs when files don't match
-2. **Concurrency groups**: Cancel in-progress runs on new pushes
-3. **Conditional matrices**: Expensive OS testing only on schedule
-4. **Aggressive caching**: Tools, dependencies, databases
-
-## Consequences
-
-### Positive
-
-- ~50% reduction in GitHub Actions minutes
-- Fast feedback for most changes (1-3 minutes)
-- Comprehensive testing still available via schedule/manual
-- Clear separation of concerns between stages
-
-### Negative
-
-- Complexity in workflow configuration
-- Some bugs might only surface in scheduled runs
-- Path filter maintenance required as repo structure evolves
-
-### Neutral
-
-- Developers can trigger full CI manually with `workflow_dispatch`
-- Breaking changes to CI require testing across all stages
-
-## Implementation
-
-```yaml
-# Key patterns used
-on:
-  push:
-    paths:
-      - '**.sh'  # Only trigger on shell changes
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  changes:
-    outputs:
-      shell: ${{ steps.filter.outputs.shell }}
-
-  lint-shell:
-    needs: changes
-    if: needs.changes.outputs.shell == 'true'
-```
-
-## References
-
-- [GitHub Actions Path Filtering](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
-- [dorny/paths-filter](https://github.com/dorny/paths-filter)
-{% endraw %}