@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/adr/ADR-008-alias-system-architecture.md

@@ -0,0 +1,85 @@
+# ADR-008: Alias System Architecture
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-08
+
+## Context
+
+The dotfiles manage 98 alias files across 30+ categories (git, docker, kubernetes, python, security, etc.). These need to load fast, support per-machine toggling, and work across Zsh, Bash, Fish, and Nushell.
+
+**Design questions:**
+1. How to organize alias files for maintainability?
+2. How to control which aliases load on which machines?
+3. How to balance startup speed with alias availability?
+4. How to bridge POSIX aliases to non-POSIX shells?
+
+## Decision
+
+### Organization
+
+Aliases are organized by tool/domain in `.chezmoitemplates/aliases/<category>/<name>.aliases.sh`:
+
+```text
+aliases/
+  git/git.aliases.sh, signing.aliases.sh
+  docker/docker.aliases.sh
+  kubernetes/kubernetes.aliases.sh
+  security/crypto-utils.aliases.sh, ssh-keys.aliases.sh, ...
+  default/default.aliases.sh
+  ...
+```
+
+### Profile Tiers
+
+Three profiles control alias scope (set in `.chezmoidata.toml`):
+
+| Profile | Scope | Use Case |
+|---------|-------|----------|
+| `minimal` | Core only, excludes interactive/sudo | Servers, containers |
+| `standard` | All core + selected ecosystem | Laptops, workstations |
+| `full` | Everything including heavy/specialized | Dev machines |
+
+### Bucket Toggles
+
+Per-category flags in `.chezmoidata.toml` under `[aliases.buckets]`:
+```toml
+[aliases.buckets]
+system = true
+svn = false    # disable on machines without SVN
+```
+
+### Two-Phase Loading
+
+1. **Eager (90-ux-aliases.sh):** Core categories loaded at shell startup (~40KB). Includes: archives, cd, clear, configuration, default, diagnostics, disk-usage, editor, git, interactive, installer, mkdir, modern, ps, rsync, sudo, system.
+
+2. **Lazy (91-ux-aliases-lazy.sh):** Ecosystem aliases deferred until first prompt via `precmd` hook. Includes: docker, kubernetes, terraform, gcloud, python, npm, rust, security, etc.
+
+### Function Groups (groups.json)
+
+Functions use a parallel system with `groups.json` as a registry:
+- Groups: api, curl, text, system, files, interactive, nav, security, misc
+- Lazy-loaded per group on first invocation
+- Stub functions replaced with real implementations on first call
+
+## Consequences
+
+### Positive
+- Adding aliases is self-service: create a file in the right category
+- Per-machine customization without forking
+- Lazy loading keeps startup under 200ms even with 98 alias files
+- `groups.json` enables automated bridge generation for Fish/Nushell
+
+### Negative
+- Alias definitions wrap in functions (`set_default_aliases()`) for sourcing safety, adding complexity
+- Two-phase loading means some aliases aren't available until after first prompt
+- Profile/bucket system requires understanding .chezmoidata.toml
+
+### Trade-offs
+- Chose file-per-category over monolithic alias file for maintainability
+- Chose runtime extraction for Fish/Nushell over maintaining parallel definitions
+- Chose lazy loading over compile-time bundling for flexibility

package/docs/adr/README.md

@@ -13,6 +13,8 @@ significant architectural decisions made in this project.
 | [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 Format
 
@@ -28,6 +30,3 @@ Each ADR follows this structure:
 - [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
 - [ADR Tools](https://github.com/npryce/adr-tools)
 
----
-
-Made with ❤️ by [Sebastien Rousseau](https://github.com/sebastienrousseau)

package/docs/architecture/ARCHITECTURE.md

@@ -0,0 +1,113 @@
+# Architecture
+
+Core architectural decisions and system design of the dotfiles shell distribution.
+
+---
+
+## Philosophy
+
+- **XDG-First**: Configuration lives under `~/.config/` to keep the home directory clean.
+- **Multi-Shell**: First-class support for Zsh, Fish, and Nushell with a shared logic core.
+- **Fast Startup**: Heavy features are deferred or autoloaded to keep the first prompt under 50ms.
+- **Deterministic**: Nix Flakes provide bit-for-bit identical environments across machines.
+- **Non-Blocking**: Background daemons (Pueue) handle upgrades and builds without stalling the shell.
+
+## System Layout
+
+```text
+~/.dotfiles/
+├── dot_config/          # Managed application configurations (~/.config/)
+│   ├── zsh/             # Modular Zsh rc.d architecture
+│   ├── fish/            # Autoloading Fish configuration
+│   ├── nushell/         # Structured data shell config
+│   ├── shell/           # Shared logic (aliases, paths, functions)
+│   └── ...              # 50+ tool configurations (nvim, tmux, ghostty, etc.)
+├── dot_local/           # Local binaries and scripts (~/.local/bin/)
+├── .chezmoitemplates/   # Unified source for aliases, functions, and paths
+├── scripts/             # Internal libraries and diagnostics
+├── nix/                 # Nix Flake for deterministic toolchains
+├── lib/wasm-tools/      # Rust source for Wasm utilities
+└── install.sh           # Universal bootstrap script (zero dependencies)
+```
+
+---
+
+## Shell Startup Strategies
+
+### Shared: `_cached_eval`
+
+Across Zsh, Fish, and Bash, an idempotent caching wrapper avoids redundant tool initialization (Starship, Zoxide, Atuin).
+
+1. **Intercept** — check if a cached version of the tool's `eval` output exists in `~/.cache/shell/`.
+2. **Validate** — compare the cache timestamp against the tool binary's mtime.
+3. **Bypass** — if valid, `source` the cached text directly, saving 20-50ms per tool.
+
+### Lazy-Hydration Model
+
+To reach a fluid first-prompt target (< 50ms), the shell uses a three-phase startup:
+
+1. **Phase 1 (Visual Paint)** — render the prompt immediately using static escape codes.
+2. **Phase 2 (Async Hydration)** — dispatch tool initializations (mise, atuin, etc.) to background workers.
+3. **Phase 3 (On-Demand Activation)** — environment hydration occurs on first user interaction or after 500ms of idle time.
+
+---
+
+## Artifact Mode
+
+A minimal environment triggered by `DOTFILES_ARTIFACT_MODE=1`.
+
+- **Minimalist UI** — strips prompt complexity, leaving only a green `->`.
+- **Intelligence Surface** — an async Bento-style dashboard rendered via `bento.sh` that provides environment context (Node version, cloud status, Git health) without blocking the main thread.
+- **Redraw Signaling** — uses `SIGWINCH` to return control after background hydration completes.
+
+---
+
+## Ultra-Fast Mode
+
+Set `DOTFILES_ULTRA_FAST=1` to skip all non-essential initialization. Only core paths, aliases, and the prompt are loaded. Useful for:
+
+- CI/CD pipelines where full shell setup is unnecessary
+- Rapid scripting sessions where startup latency matters
+- Benchmarking baseline shell performance
+
+---
+
+## Debug and Trace Modes
+
+### DOTFILES_DEBUG=1
+
+Enables verbose diagnostic output during shell startup. Prints which files are sourced and their load times.
+
+### DOTFILES_TRACE=1
+
+Enables `set -x` tracing for the entire shell startup sequence. Output is written to `~/.local/state/dotfiles/debug.log` for post-mortem analysis.
+
+---
+
+## Function Groups (groups.json)
+
+Functions are organized into groups defined in `.chezmoitemplates/functions/groups.json`:
+
+| Group | Functions | Description |
+|-------|-----------|-------------|
+| `api` | apihealth, apilatency, apiload | API testing utilities |
+| `curl` | curlheader, curlstatus, curltime, httpdebug | HTTP debugging |
+| `text` | encode64, kebabcase, lowercase, titlecase, ... | Text transformation |
+| `system` | environment, freespace, hostinfo, myproc, sysinfo | System introspection |
+| `files` | backup, extract, hexdump, hiddenfiles, size, zipf | File operations |
+| `interactive` | banner, emoji, matrix, rainbow, stopwatch | Terminal fun |
+| `nav` | cdls, goto, ql | Navigation shortcuts |
+| `security` | genpass, keygen, mount_read_only | Security utilities |
+| `misc` | dothelp, view-source, prependpath, caffeine | Miscellaneous |
+
+Groups are lazy-loaded: stub functions are defined at startup, and the real implementation is loaded on first invocation. This keeps startup fast while providing 52+ functions on demand.
+
+The `groups.json` schema maps group names to arrays of relative paths (including subdirectory):
+
+```json
+{
+  "group_name": ["group_name/function1.sh", "group_name/function2.sh"]
+}
+```
+
+Each `.sh` file lives in a subdirectory matching its group and defines a single function with the same name as the file (minus `.sh` extension).

package/docs/architecture/INTEROP.md

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,237 @@
+<!-- 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` — 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          |
+| `OPENCODE.md` (repo root)     | 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/`                       | Vendored WebAssembly tooling (build output gitignored)                          |
+| `.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                                                         |
+|-------------------------------------------|-----------------------------------------------------------------|
+| `scripts/ci/`                             | CI helpers (`check-copyright-headers.sh`, `install-chezmoi-verified.sh`, `validate-ci-config.sh`) |
+| `scripts/dot/commands/`                   | Subcommand implementations for the `dot` CLI                    |
+| `scripts/docs/`                           | Manual build pipeline (`build-manual.sh`, `check-manual.sh`)    |
+| `scripts/theme/`                          | K-Means CIELAB theme engine + HEIC merge/convert                |
+| `scripts/ops/`, `scripts/maintenance/`, `scripts/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.500 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                                           |
+| `tests/performance/`                      | `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                                                                     |
+| `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 `scripts/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 vendored wasm tooling                           |
+| `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 `dot_local/bin/executable_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

@@ -0,0 +1,82 @@
+# 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

@@ -0,0 +1,73 @@
+# 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 |