@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/docs/adr/README.md

@@ -1,40 +0,0 @@
----
-render_with_liquid: false
----
-
-# Architecture Decision Records
-
-This directory contains Architecture Decision Records (ADRs) that document
-significant architectural decisions made in this project.
-
-## Index
-
-| ADR | Title | Status |
-|-----|-------|--------|
-| [ADR-001](ADR-001-ci-cd-pipeline.md) | Multi-stage CI/CD Pipeline Design | Accepted |
-| [ADR-002](ADR-002-shell-performance.md) | Shell Performance Optimization Strategy | Accepted |
-| [ADR-003](ADR-003-security-first.md) | Security-First Approach | Accepted |
-| [ADR-004](ADR-004-cli-architecture.md) | Chezmoi + Custom CLI Wrapper Architecture | Accepted |
-| [ADR-005](ADR-005-chezmoi-choice.md) | Chezmoi as Dotfiles Manager | Accepted |
-| [ADR-006](ADR-006-shell-selection.md) | Zsh as Default Shell | Accepted |
-| [ADR-007](ADR-007-multi-shell-parity.md) | Multi-Shell Parity Strategy | Accepted |
-| [ADR-008](ADR-008-alias-system-architecture.md) | Alias System Architecture | Accepted |
-| [ADR-009](ADR-009-wallpaper-driven-theming.md) | Wallpaper-Driven Theming Engine | Accepted |
-| [ADR-010](ADR-010-starship-transient-prompt.md) | Enable Starship Transient Prompt in Zsh and Fish | Accepted |
-| [ADR-011](ADR-011-nushell-tier3-keep.md) | Keep Nushell as Tier-3 Reference with Minimum-Viable Caching | Accepted |
-| [ADR-012](ADR-012-ai-fleet-local-proxy.md) | AI Fleet — Native Local Claude Proxy and Cockpit | Accepted |
-
-## ADR Format
-
-Each ADR follows this structure:
-
-- **Status**: Proposed, Accepted, Deprecated, Superseded
-- **Context**: The situation and forces at play
-- **Decision**: The change being made
-- **Consequences**: The resulting context after applying the decision
-
-## References
-
-- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
-- [ADR Tools](https://github.com/npryce/adr-tools)
-

package/docs/architecture/AI_COST_OPTIMIZATION.md

@@ -1,144 +0,0 @@
----
-title: "AI Cost Optimization"
-date: 2026-05-24
----
-
-# AI Cost Optimization
-
-This dotfiles framework ships an opinionated AI-cost layer designed to
-keep token spend predictable and low while still using the smartest
-model for orchestration. Two ideas drive it:
-
-1. **Delegate the grunt work.** Have the expensive smart model
-   orchestrate, and a cheap fast model do the file reads, edits, and
-   verification. The smart model sees one tool call and the final
-   `git diff` instead of every intermediate read.
-2. **Account every call.** Every invocation through `dot ai <provider>`
-   appends a JSONL entry so you can see spend across all providers in
-   one report, not just per-tool dashboards.
-
-## Quick reference
-
-```sh
-dot ai delegate "rename every UserService method that starts with get to fetch"
-dot ai cost                # all-time overview
-dot ai cost --since 7      # last 7 days
-dot ai cost --fails        # only failures + breakdown by failure type
-```
-
-Inside Claude Code: `/vibe`, `/vibe-report`, `/vibeon`, `/vibeoff`,
-`/vibestatus`, `/vibe-model-pick`, `/vibe-model-clear`.
-
-## The delegator pattern
-
-The pattern comes from [pcx-wave/vibe-skill][vibe-skill]. Mistral Vibe
-is the default delegate but the same wrapper accepts any model Vibe
-knows about (DeepSeek V4 Flash, Gemini Flash, etc.).
-
-[vibe-skill]: https://github.com/pcx-wave/vibe-skill
-
-Cost comparison (May 2026 list prices, blended 85 in / 15 out typical
-of coding tasks):
-
-| Task | Claude Sonnet 4.6 ($3 / $15) | Mistral Medium 3.5 ($1.50 / $7.50) | DeepSeek V4 Flash ($0.14 / $0.28) |
-|---|---|---|---|
-| 1-file tweak (800 tok) | ~$0.004 | ~$0.002 | ~$0.0001 |
-| 6-read task (4,800 tok) | ~$0.023 | ~$0.012 | ~$0.0008 |
-| Multi-file refactor (12,000 tok) | ~$0.058 | ~$0.029 | ~$0.002 |
-
-Real-world stats from 254 vibe-skill runs over 10 days (May 2026):
-
-| | Amount |
-|---|---|
-| Actually paid (Mistral Pro prorated + DeepSeek pay-as-you-go) | **$10.35** |
-| Same workload pay-as-you-go via Mistral API | $46.61 |
-| Same workload on Claude Sonnet 4.6 | $179.91 |
-| Saved vs Claude | **$169.56 (17.4× cheaper)** |
-
-Claude itself contributes ~500-1500 tokens per delegation as
-orchestration overhead. Even with that overhead the savings dominate
-for anything beyond a one-line edit.
-
-## Pieces deployed by this repo
-
-| Component | Source path | Deployed to | Role |
-|---|---|---|---|
-| `vibe` skill | `defaults/dot_claude/skills/vibe/` | `~/.claude/skills/vibe/` | Claude Code slash commands (`/vibe`, `/vibe-report`, etc.) |
-| Delegator binary | `defaults/dot_claude/skills/vibe/tools/executable_vibe-delegate` | `~/.claude/skills/vibe/tools/vibe-delegate` | Runs the cheap-model task in a pseudo-TTY, parses streaming JSON, syntax-checks changes, logs the run |
-| Reporter | `defaults/dot_claude/skills/vibe/tools/executable_delegate-report` | `~/.claude/skills/vibe/tools/delegate-report` | Reads the JSONL log, prints overview / by-model / by-project / failure tables |
-| CLI shim | `scripts/dot/commands/ai.sh` | `bin/dot ai delegate` / `bin/dot ai cost` | Same delegator + reporter, callable from the terminal without Claude Code |
-| Unified log hook | `_ai_log_run` in `ai.sh` | runs inside `run_ai_with_context` | Appends one JSONL line per `dot ai <provider>` invocation |
-| Log file | runtime-managed | `~/.local/share/delegate-runs.jsonl` | One line per run; `dot ai cost` reads it |
-
-## State files
-
-| File | Owner | Purpose |
-|---|---|---|
-| `~/.local/share/delegate-runs.jsonl` | runtime | One JSONL entry per AI invocation (vibe + every other provider) |
-| `~/.local/share/vibe-auto.flag` | `/vibeon` / `/vibeoff` | When present, Claude auto-delegates coding tasks to Vibe |
-| `~/.local/share/vibe-model.flag` | `/vibe-model-pick` | Override the Vibe model for the next runs; cleared by `/vibe-model-clear` |
-| `~/.vibe/config.toml` | user | Vibe's own provider / model configuration |
-
-## Reading the report
-
-```
-DELEGATE REPORT  2026-05-17 → 2026-05-24
-  Runs          : 27  (ok: 25, failed: 2, timeout: 0)
-  Success rate  :  92%
-  Avg duration  : 18.4s
-  Tokens total  : 4,231,082
-  Delegate cost : $1.4711
-  Claude equiv  : $14.8294
-  Saved         : $13.3583  (90% cheaper than Claude)
-```
-
-`Claude equiv` is what the same workload would have cost on Claude
-Sonnet 4.6 ($3 / $15 per M tokens, blended at the same in/out ratio).
-The savings line is the difference. Failure types are broken out per
-model so you can see which delegate is most reliable for your repo.
-
-## Provider coverage
-
-Every provider exposed via `dot ai <provider>` is logged best-effort.
-For providers that don't surface token counts in their CLI output, the
-report still tracks: timestamp, project, exit code, duration, prompt
-word count. Token / cost fields stay zero for those providers — the
-report tolerates the gap and aggregates by `model` regardless.
-
-Providers tracked today:
-
-| Provider | Binary | Logged | Tokens surfaced? |
-|---|---|---|---|
-| Claude Code | `claude` | yes | no (CLI doesn't expose) |
-| Codex | `codex` | yes | no |
-| Copilot CLI | `copilot` | yes | no |
-| Gemini CLI | `gemini` | yes | no |
-| Goose | `goose` | yes | no |
-| Kimi CLI | `kimi` | yes | no |
-| Aider | `aider` | yes | no |
-| OpenCode | `opencode` | yes | no |
-| Autohand | `autohand` | yes | no |
-| Mistral Vibe | `vibe` | yes | **yes** (via delegator) |
-| Qwen | `qwen` | yes | no |
-| ZAI | `zai` | yes | no |
-| Shell-GPT | `sgpt` | yes | no |
-| Ollama (local) | `ollama` | yes | n/a (no cost) |
-| Kiro CLI | `kiro-cli` | yes | no |
-
-## Future work
-
-Not implemented yet, ordered roughly by likely impact:
-
-1. **Provider-level budget guard.** `dot ai budget --set 50/month`
-   would warn at 80% and refuse new requests at 100% (overridable).
-   Needs per-provider cost estimation hooks beyond what each CLI
-   surfaces today.
-2. **Prompt response cache.** Many coding-helper queries are
-   deterministic ("syntax for X in Y"). A local cache keyed on prompt
-   hash + provider could short-circuit repeat queries.
-3. **Per-task-class model routing.** `dot ai delegate --class refactor`
-   would pick the cheapest model that meets the quality bar for the
-   task class. Today the user picks the model.
-4. **Rate-limit awareness.** Track API rate limits from response
-   headers, queue requests, surface a `dot ai cost --limits` view that
-   shows time-to-reset for every provider with an active limit.

package/docs/architecture/ARCHITECTURE.md

@@ -1,20 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
-
-# Architecture
-
-This document moved to [`../ARCHITECTURE.md`](../ARCHITECTURE.md), the
-canonical location required by the repository standard (`docs/ARCHITECTURE.md`,
-alongside `DEVELOPMENT.md` as the two entry points a contributor needs).
-
-This file is a pointer so existing links keep resolving. Do not add
-content here.
-
-Neighbouring architecture documents are unaffected:
-
-- [`REPO_LAYOUT.md`](REPO_LAYOUT.md) — every top-level path and why it exists
-- [`INTEROP.md`](INTEROP.md) — agent and MCP interoperability surfaces

package/docs/architecture/INTEROP.md

@@ -1,44 +0,0 @@
----
-render_with_liquid: false
----
-
-# Cross-Platform Interoperability
-
-How dotfiles commands and shims map across macOS, Linux, and WSL2.
-
-## Command Mapping
-
-| Alias / Command | macOS | Linux (Debian/Arch) | WSL2 (Windows Host) |
-| :--- | :--- | :--- | :--- |
-| `cb` (Clipboard) | `pbcopy` / `pbpaste` | `xclip` / `wl-copy` | `clip.exe` / `powershell.exe` |
-| `open` | `open` | `xdg-open` | `wslview` / `explorer.exe` |
-| `notify` | `osascript` (AppleScript) | `notify-send` / `gum log` | `powershell.exe` (Toast) / `gum` |
-| `win` (Paths) | N/A | N/A | `wslpath` |
-| `browser` | `open` | `xdg-open` | `powershell.exe Start-Process` |
-
-## Infrastructure Parity
-
-| Feature | macOS | Linux | WSL2 |
-| :--- | :--- | :--- | :--- |
-| **Package Manager** | Homebrew (`brew`) | `apt` / `pacman` / `nix` | `apt` + Windows binaries |
-| **Shell Startup** | Async lazy-hydration | Async lazy-hydration | Async (optimized for IO) |
-| **Environment** | native plist / launchctl | systemd / dbus | systemd (if enabled) / init |
-| **Hardware** | Secure Enclave | TPM 2.0 / LUKS | Windows Hello bridge |
-
-## Troubleshooting
-
-### WSL2 IO Latency
-
-Keep projects in the Linux filesystem (`~/...`), not under `/mnt/c/`.
-
-### WSL2 Windows Binary Path
-
-If you've disabled WSL path sharing, make sure Windows-side binaries like `clip.exe` and `explorer.exe` are still reachable in `$PATH`.
-
-### macOS Permissions
-
-Grant your terminal "Full Disk Access" in System Settings so dotfiles can manage all configurations.
-
-### Linux GUI Fallbacks
-
-In headless environments, GUI commands like `cb` and `open` fall back to `gum log` or terminal bell instead of hanging.

package/docs/architecture/REPO_LAYOUT.md

@@ -1,241 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- Copyright (c) 2015-2026 Dotfiles. All rights reserved. -->
-
-# Repository Layout
-
-A map of every top-level folder and file in this repo, grouped by purpose.
-Use this when you're not sure where something belongs or why a particular
-directory exists.
-
-For naming conventions (file prefixes, run-script numbering tiers), see
-[`../NAMING_CONVENTIONS.md`](../NAMING_CONVENTIONS.md). For the broader
-architectural rationale (philosophy, startup model, flake strategy), see
-[`ARCHITECTURE.md`](ARCHITECTURE.md). For the configuration-management
-strategy at a higher level, see [`../CONFIG_STRATEGY.md`](../CONFIG_STRATEGY.md).
-
----
-
-## 1. Chezmoi source tree — the actual dotfiles
-
-Chezmoi reads this directory and deploys to `$HOME`. Filename **prefixes**
-carry semantics:
-
-| Prefix           | Effect                                      | Example                                            |
-|------------------|---------------------------------------------|----------------------------------------------------|
-| `dot_`           | Deployed with a leading `.`                 | `dot_gitconfig.tmpl` → `~/.gitconfig`              |
-| `private_`       | Sets `0600` perms on deploy                 | `private_dot_ssh/` → `~/.ssh/`                     |
-| `executable_`    | Sets `+x` on deploy                         | `executable_dot` → `~/.local/bin/dot`              |
-| `run_onchange_`  | Runs once when its content hash changes     | `run_onchange_20-ghostty-config.sh.tmpl`           |
-| `.tmpl`          | Rendered as a Go template at apply time     | `dot_npmrc.tmpl`                                    |
-
-> **Gotcha:** `executable_dot_foo` deploys as `.foo` (not `dot_foo`). Chezmoi
-> consumes the `dot_` prefix even when stacked with `executable_`.
-
-### Chezmoi data and templates
-
-| Path                        | Role                                                                                         |
-|-----------------------------|----------------------------------------------------------------------------------------------|
-| `.chezmoi.toml.tmpl`        | Init-time prompts (name, email, signing key).                                                |
-| `.chezmoidata.toml`         | **Source of truth** for version, profile, default theme, shell, feature flags.              |
-| `.chezmoidata/`             | Split data files: `themes.toml`, `keybinds.toml`, `hardware.toml`.                           |
-| `.chezmoiignore.tmpl`       | Feature-flag-gated "don't deploy these to `$HOME`" list.                                     |
-| `.chezmoitemplates/`        | Reusable template partials (`aliases/`, `functions/`, `paths/`, `desktop/`). Not deployed.   |
-
-### Shell rc files (root level)
-
-| Path | Target | Purpose |
-|---|---|---|
-| `dot_bashrc`, `dot_profile` | `~/.bashrc`, `~/.profile` | Bash startup |
-| `dot_zshenv`, `dot_zprofile`, `dot_zshrc` | `~/.zshenv` etc. | Zsh startup chain (see [`ARCHITECTURE.md`](ARCHITECTURE.md) for order) |
-| `dot_vimrc`, `dot_inputrc`, `dot_psqlrc`, `dot_sqliterc`, `dot_Xresources` | `~/.*` | Classic per-tool dotfiles |
-| `dot_gitconfig.tmpl`, `dot_npmrc.tmpl` | `~/.gitconfig`, `~/.npmrc` | Templated — identity/tokens injected at apply |
-| `dot_cargo/config.toml.tmpl` | `~/.cargo/config.toml` | Rust build dirs redirected to `/tmp` |
-| `dot_fdignore`, `dot_noderc`, `dot_rustfmt.toml` | `~/.*` | Per-tool config |
-| `private_dot_netrc.tmpl`, `private_dot_ssh/` | `~/.netrc`, `~/.ssh/` | 0600 files |
-
-### Large chezmoi directories
-
-| Path          | Target            | Notes                                                                                        |
-|---------------|-------------------|----------------------------------------------------------------------------------------------|
-| `dot_config/` | `~/.config/`      | **Largest** — fish, zsh, nvim, ghostty, tmux, niri, mise, and ~90 other app configs.         |
-| `dot_local/bin/` | `~/.local/bin/` | Every `dot-*` subcommand and helper script (the `dot` CLI lives here).                        |
-| `dot_local/share/` | `~/.local/share/` | Fonts and shared data.                                                                     |
-| `dot_etc/opt/chrome/policies/` | `~/etc/opt/chrome/policies/` | Managed Chrome enterprise policies.                                              |
-
-### `run_onchange_*` hooks at the root
-
-Scripts triggered when their content changes. Numbering follows the
-convention in [`../NAMING_CONVENTIONS.md`](../NAMING_CONVENTIONS.md):
-
-- `run_onchange_20-ghostty-config.sh.tmpl` — re-renders Ghostty config
-- `run_onchange_21-topgrade-config.sh.tmpl` — refreshes topgrade config
-- `run_onchange_after_fonts.sh.tmpl` — post-deploy font cache refresh
-
----
-
-## 2. AI-assistant files — **three** files, three distinct roles
-
-This is the most common source of confusion in the repo. All three files
-exist on purpose and don't overlap:
-
-| File                          | Deployed to           | Audience                                                         | Scope                         |
-|-------------------------------|-----------------------|------------------------------------------------------------------|-------------------------------|
-| `dot_claude/CLAUDE.md`        | `~/.claude/CLAUDE.md` | Claude Code, in **any** cwd on this machine                      | Personal, cross-project       |
-| `CLAUDE.md` (repo root)       | Not deployed          | Claude Code, when cwd is **this** repo                           | Repo-scoped guidance          |
-| `docs/OPENCODE.md`            | Not deployed          | OpenCode CLI, when cwd is **this** repo                          | Repo-scoped guidance (mirror) |
-| `.claude/settings.local.json` | Not deployed, **not tracked** | Claude Code                                                     | Per-machine permission allowlist |
-
-Each of the three tracked files carries a header comment explaining its
-role to prevent drift. Keep that header in place when editing.
-
----
-
-## 3. Agent-protocol surface
-
-Standards-compliant discovery endpoints that let external agents and tools
-find this workstation's agent capabilities:
-
-| Path                                | Purpose                                                                     |
-|-------------------------------------|-----------------------------------------------------------------------------|
-| `.well-known/agent-card.json`       | A2A v0.3 agent card — skills, capabilities, URL                             |
-| `.well-known/agent.json`            | Legacy pointer card, kept for back-compat                                   |
-| `.well-known/mcp/server-card.json`  | MCP server discovery manifest                                               |
-
----
-
-## 4. CI/CD and repo metadata
-
-| Path                                                             | Purpose                                                        |
-|------------------------------------------------------------------|----------------------------------------------------------------|
-| `.github/workflows/`                                             | 20+ workflows: `ci.yml`, `ci-enforced.yml`, reusable lints, release pipelines |
-| `.github/workflows/reusable-*.yml`                               | Shared workflow fragments (`shell-lint`, `lua-lint`, `nix-lint`, `copyright-lint`, `test-suite`, `secrets-scan`, `security-baseline`) |
-| `.github/ISSUE_TEMPLATE/`, `PULL_REQUEST_TEMPLATE.md`, `CODEOWNERS`, `SECURITY.md`, `CONTRIBUTING.md`, `CODE-OF-CONDUCT.md`, `FUNDING.yml` | Standard GitHub metadata                                       |
-| `.github/security-policies/`                                     | Org-level security policy files                                |
-| `.github/branch-protection-config.json`, `BRANCH_PROTECTION.md`  | Codified branch-protection settings                            |
-| `.github/dependabot.yml`                                         | Dependency bump schedule                                       |
-| `.devcontainer/`                                                 | GitHub Codespaces + VS Code dev container                      |
-| `Dockerfile.test`, `tests/Dockerfile.sandbox`                    | Ubuntu sandboxes for integration / e2e tests                   |
-
----
-
-## 5. Build, bootstrap, and dev tooling
-
-| Path                                    | Purpose                                                                        |
-|-----------------------------------------|--------------------------------------------------------------------------------|
-| `install.sh`                            | Top-level one-liner installer                                                  |
-| `install/provision/`, `install/lib/`    | Platform-specific install helpers invoked by `install.sh`                      |
-| `Makefile`, `Justfile.tmpl`, `treefmt.toml` | Convenience runners                                                            |
-| `mise.toml`, `mise-versions.lock.json`  | Mise toolchain versions (locked)                                               |
-| `flake.nix`, `flake.lock` (root)        | Root Nix flake for `direnv` + repo dev shell                                   |
-| `nix/flake.nix`, `nix/home.nix`         | Separate flake for Home Manager activation (used by `dot upgrade` and `ci-enforced.yml → lint-nix`) |
-| `lib/wasm-tools/`                       | `dot-sys` Rust crate (lib + bin), built for `wasm32-wasip1`: the health-probe record and the sandboxed verifier behind `dot attest --verify`; gated by `rust.yml` |
-| `.envrc`                                | `direnv` hook into the root flake                                              |
-
----
-
-## 6. Scripts (`scripts/`) — repo-local, never deployed
-
-Nothing under `scripts/` ends up in `$HOME`. It's all tooling for running
-the repo itself.
-
-| Subdir                                    | Purpose                                                         |
-|-------------------------------------------|-----------------------------------------------------------------|
-| `tools/ci/`                             | CI helpers (`check-copyright-headers.sh`, `install-chezmoi-verified.sh`, `validate-ci-config.sh`) |
-| `scripts/dot/commands/`                   | Subcommand implementations for the `dot` CLI                    |
-| `tools/docs/`                           | Manual build pipeline (`build-manual.sh`, `check-manual.sh`)    |
-| `scripts/theme/`                          | K-Means CIELAB theme engine + HEIC merge/convert                |
-| `scripts/ops/`, `tools/maintenance/`, `tools/release/` | Operator tooling                                        |
-| `scripts/diagnostics/`, `scripts/qa/`, `scripts/security/`, `scripts/secrets/` | Domain-scoped scripts                          |
-| `scripts/fonts/`, `scripts/demo/`, `scripts/git-hooks/`, `scripts/tools/`, `scripts/tuning/`, `scripts/lib/` | Supporting scripts                                          |
-| `scripts/uninstall.sh`, `scripts/version-sync.sh` | Top-level ops entrypoints                                 |
-
----
-
-## 7. Documentation (`docs/`)
-
-| Path                                  | Purpose                                                                    |
-|---------------------------------------|----------------------------------------------------------------------------|
-| `docs/manual/`                        | 26-page GNU-Stow-style reference manual (the v0.2.501 feature)             |
-| `docs/architecture/`                  | This file + core architecture docs (ARCHITECTURE, INTEROP, fleet, walkthrough) |
-| `docs/operations/`                    | Runbooks, traceability matrix, migration notes                             |
-| `docs/reference/`                     | Command/config reference material                                           |
-| `docs/guides/`                        | Long-form how-tos                                                          |
-| `docs/security/`                      | Threat model, disclosure policy, audit records                             |
-| `docs/adr/`                           | Architecture Decision Records                                              |
-| `docs/themes/`                        | Theme catalogue / screenshots                                              |
-| `docs/interop/`                       | Agent/MCP interop notes                                                    |
-| `docs/archive/`                       | Superseded docs kept for history                                           |
-| `docs/NAMING_CONVENTIONS.md`          | Naming bible (file prefixes, run-script numbering tiers)                    |
-| `docs/index.md`, `docs/README.md`, `docs/AI.md`, `docs/COPYRIGHT` | Entry points                                                |
-
----
-
-## 8. Tests (`tests/`)
-
-| Path                                      | Purpose                                                                                    |
-|-------------------------------------------|--------------------------------------------------------------------------------------------|
-| `tests/framework/`                        | `test_runner.sh`, `assertions.sh`, `mocks.sh` — the custom shell-test framework            |
-| `tests/unit/`                             | Unit tests organised by domain: `aliases/`, `ci/`, `docs/`, `dot-cli/`, `fish/`, `functions/`, `install/`, `nvim/`, `ops/`, `secrets/`, `security/`, `shell/`, `theme/`, `tools/`, `diagnostics/`, `misc/`, `nushell/` |
-| `tests/integration/`                      | End-to-end install and apply flows                                                         |
-| `tests/regression/`                       | Guardrail tests for previously-broken behaviours                                           |
-| `benches/`                      | `benchmark_runner.sh` and friends                                                          |
-| `tests/benchmark.sh`, `tests/test-aliases.sh`, `tests/test-docker.sh` | Top-level entrypoints                                              |
-| `tests/Dockerfile.sandbox`                | Fresh-Ubuntu sandbox image for integration tests                                           |
-
-Tests execute shell source files directly — **do not** use Go template
-syntax in non-`.tmpl` files, or the test framework will choke on the curly
-braces.
-
----
-
-## 9. Other top-level
-
-| Path                                      | Purpose                                                                      |
-|-------------------------------------------|------------------------------------------------------------------------------|
-| `config/`                                 | Repo-local tool configs: `cliff.toml` (changelog), `gitleaks.toml`, `pre-commit-config.yaml`, `stylua.toml`, `trivyignore` |
-| `templates/chezmoi-data/`, `templates/projects/` | Starter scaffolding for new machines / new projects                     |
-| `examples/`                               | 14 standalone demo scripts used by the manual and tutorials                  |
-| `CHANGELOG.md`, `LICENSE`, `README.md`    | Standard                                                                     |
-| `docs/CONFIG_STRATEGY.md`                 | High-level "how configuration management works here" overview                |
-| `.gitattributes`, `.gitignore`, `.gitleaksignore`, `.editorconfig`, `.secrets.baseline`, `.sops.yaml`, `.luacheckrc` | Repo-level tool configs                                                    |
-| `.pre-commit-config.yaml` → `config/pre-commit-config.yaml` | Symlink so `pre-commit` finds the canonical config                       |
-
----
-
-## 10. Local-only artefacts (gitignored — if you see them, don't commit them)
-
-The following paths can appear during local work but are excluded from
-version control. If one of them ever shows up in `git status`, check the
-`.gitignore` entry rather than adding the file:
-
-| Path                     | Source                                                                       |
-|--------------------------|------------------------------------------------------------------------------|
-| `_build/`                | Output of `tools/docs/build-manual.sh`                                     |
-| `.pnpm-store/`           | pnpm's content-addressable store (should never appear here)                  |
-| `.claude/`               | Claude Code per-machine state (`settings.local.json` permission allowlists)  |
-| `node_modules/`          | Node dependency trees from repo-local scripts                                |
-| `.version-sync-backup/`  | Timestamped backups from `version-sync.sh`                                   |
-| `lib/wasm-tools/target/` | Rust build artefacts for the `dot-sys` crate, including the `wasm32-wasip1/release/dot-sys.wasm` module `dot attest --verify` runs (and `fuzz/target/`) |
-| `dot_etc/machines/`      | Host-specific installer overrides                                            |
-
----
-
-## How to decide where a new file belongs
-
-A quick decision tree for common cases:
-
-- **New app config that lives under `~/.config/<app>/`** → `dot_config/<app>/` (see `docs/NAMING_CONVENTIONS.md` → "Adding New Modules").
-- **New user-facing CLI script** → `dot_local/bin/executable_<name>`.
-- **New `dot` subcommand** → implementation in `scripts/dot/commands/<name>.sh`, routing in `bin/dot`.
-- **New repo-only automation** (CI helper, maintenance task, release step) → `scripts/<domain>/<name>.sh`.
-- **New test** → `tests/unit/<domain>/test_<feature>.sh` (follow `test_{domain}_{feature}.sh` naming).
-- **New doc** → pick the narrowest of `docs/architecture/`, `docs/reference/`, `docs/guides/`, `docs/operations/`, `docs/security/`.
-- **New alias file** → `.chezmoitemplates/aliases/<category>/<tool>.aliases.sh` (see conventions doc).
-- **New run-once hook** → `run_onchange_<NN>-<verb>-<noun>.sh.tmpl` at the root, using the numbering tier appropriate to its category.
-
-If none of the above fits, stop and ask in an issue or PR before
-introducing a new top-level directory. The current layout is deliberate
-and one-off additions cost everyone later.

package/docs/architecture/WALKTHROUGH.md

@@ -1,86 +0,0 @@
----
-render_with_liquid: false
----
-
-# Walkthrough
-
-A hands-on tour of the dotfiles after installation. Run each step in your terminal to get comfortable with what's available.
-
-## Step 1: Verify Installation
-
-Make sure everything landed correctly:
-
-```bash
-dot --version
-dot doctor
-dot status
-```
-
-`dot doctor` catches common problems early. If something's off, it'll tell you.
-
-## Step 2: Explore the Shell
-
-The shell ships with modern replacements wired in:
-
-```bash
-z dotfiles          # Jump to ~/.dotfiles (zoxide)
-z -                 # Go back
-
-<Ctrl-R>            # Fuzzy search command history (fzf)
-<Ctrl-T>            # Fuzzy find files
-
-ls                  # Aliased to eza
-cat file.txt        # Aliased to bat
-```
-
-## Step 3: Git Workflow
-
-```bash
-gst                 # git status
-lg                  # Pretty log graph
-ga .                # git add
-gcm "message"       # git commit -m
-lgui                # Launch lazygit
-```
-
-## Step 4: Tmux
-
-Prefix is `Ctrl-a`:
-
-```bash
-<Ctrl-a> c          # New window
-<Ctrl-a> |          # Split vertically
-<Ctrl-a> -          # Split horizontally
-<Ctrl-a> h/j/k/l    # Navigate panes (vim-style)
-<Ctrl-a> f          # Fuzzy session switcher
-```
-
-## Step 5: Neovim
-
-```bash
-nvim .
-
-# Inside Neovim:
-<Space>             # Leader — shows command palette
-<Space>ff           # Find files
-<Space>fg           # Live grep
-<Space>e            # Toggle file tree
-```
-
-## Step 6: Docker
-
-```bash
-dps                 # List running containers
-dco up -d           # docker compose up
-dlogsf container    # Follow container logs
-lzd                 # Launch lazydocker
-```
-
-## Step 7: Kubernetes (if enabled)
-
-```bash
-k get pods          # kubectl
-kctx                # Switch context
-kn                  # Switch namespace
-k9                  # Launch k9s
-```

package/docs/architecture/fleet-deployment.md

@@ -1,77 +0,0 @@
----
-render_with_liquid: false
----
-
-# Fleet Deployment Architecture
-
-## Deployment Flow
-
-```mermaid
----
-title: Fleet Deployment Architecture
----
-flowchart TD
-    subgraph repo["Git Repository (SSOT)"]
-        data[".chezmoidata.toml<br/>theme, profile, machine, features"]
-        wallpapers["~/Pictures/Wallpapers/ + System<br/>wallpapers (source of truth)"]
-        engine_k["K-Means CIELAB engine<br/>extract-theme.py + rebuild-themes.sh"]
-        themes[".chezmoidata/themes.toml<br/>auto-generated, WCAG AAA"]
-        hw[".chezmoidata/hardware.toml<br/>machine presets: T2, Surface, Geekom"]
-        keys[".chezmoidata/keybinds.toml<br/>modifier hierarchy matrix"]
-        tpl[".chezmoitemplates/<br/>reusable partials"]
-        configs["dot_config/<br/>50+ app configs as .tmpl"]
-        wallpapers --> engine_k --> themes
-    end
-
-    repo --> engine["Chezmoi Template Engine<br/>chezmoi apply"]
-
-    engine --> t2["MacBook T2<br/>scale 2.0 | macOS"]
-    engine --> sp["Surface Pro<br/>scale 1.5 | Linux"]
-    engine --> gk["Geekom A9<br/>scale 1.0 | Linux"]
-
-    subgraph apps["App Configs (per machine)"]
-        niri["Niri (WM)"]
-        ghostty["Ghostty (Term)"]
-        tmux["Tmux (Mux)"]
-        nvim["Neovim (Edit)"]
-        gtk["GTK (UI)"]
-    end
-
-    t2 --> apps
-    sp --> apps
-    gk --> apps
-
-    themes -. "colors" .-> niri & ghostty & tmux & nvim & gtk
-
-    subgraph hotreload["IPC Hot-Reload Path"]
-        direction LR
-        user(["User runs dot-theme-sync"]) --> ipc["dot-theme-sync<br/>writes theme choice"]
-        ipc --> reload_niri["niri: IPC reload"]
-        ipc --> reload_ghostty["ghostty: config reload"]
-        ipc --> reload_gtk["GTK: gsettings"]
-        ipc --> reload_tmux["tmux: source-file"]
-        ipc --> reload_nvim["nvim: RPC colorscheme"]
-    end
-
-    style repo fill:#313244,stroke:#cba6f7,color:#cdd6f4
-    style engine fill:#45475a,stroke:#89b4fa,color:#cdd6f4
-    style apps fill:#313244,stroke:#a6e3a1,color:#cdd6f4
-    style hotreload fill:#313244,stroke:#f9e2af,color:#cdd6f4
-```
-
-> **Note — Keybind Modifier Hierarchy:** Each input layer owns a
-> non-overlapping modifier prefix. The compositor (Super) never collides
-> with the multiplexer (Ctrl+a prefix), which never collides with the
-> editor (Space leader). `Ctrl+h/j/k/l` is the sole shared binding,
-> resolved by `tmux-vim-navigator` interop.
-
-## Keybind Conflict Resolution Matrix
-
-| Modifier | Layer | Owner | Examples |
-|---|---|---|---|
-| `Super` (Mod) | Compositor | Niri | `Super+1`-`9` workspaces, `Super+Enter` terminal |
-| `Alt` | Window Switch | Niri | `Alt+Tab`, `Alt+grave` |
-| `Ctrl+a` prefix | Multiplexer | Tmux | `Ctrl+a h/j/k/l` panes, `Ctrl+a N` new window |
-| `Ctrl+h/j/k/l` | Smart Navigation | Tmux / Neovim | Seamless pane/split traversal |
-| `Ctrl+c/v/t/w` | Terminal | Ghostty | Copy, paste, new tab, close |
-| `Space` (leader) | Editor | Neovim | `Space+ff` find, `Space+ca` code action |