@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

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 |

package/docs/archive/EUXIS_2026_REVIEW.md

@@ -0,0 +1,119 @@
+# Euxis 2026 Architecture & Product Review
+
+This review translates the current dotfiles CLI stack into an Apple-tier product strategy:
+high power, near-zero cognitive load, and cross-platform parity (macOS, Linux, WSL).
+
+## Current state (what is already strong)
+
+- Unified entrypoint (`dot`) with modular command routing.
+- Good safety baseline (strict mode, governance, preflight checks).
+- Broad CI coverage with strong shell quality gates.
+- WSL support already exists but is distributed across scripts.
+
+## Gaps to close for Apple-tier quality
+
+### Performance and responsiveness
+
+- `dot doctor` scans broad filesystem paths and can feel slow on large homes.
+- Platform detection logic is duplicated across scripts.
+- Source directory resolution repeats file system probes in hot paths.
+
+### UX and cognitive load
+
+- Cross-platform behavior is implicit, not surfaced as a simple product contract.
+- Users still need to understand host/guest boundaries (especially WSL).
+- Onboarding signal is fragmented across docs and command help.
+
+### Product parity
+
+- No single abstraction layer for path conversion and host-native opening.
+- No first-class “platform parity” diagnostics in one section.
+
+## Implemented in this branch
+
+### 1) Platform abstraction layer
+
+Added `scripts/dot/lib/platform.sh` with:
+
+- `dot_platform_id`
+- `dot_host_os`
+- `dot_is_wsl`
+- `dot_path_to_unix`
+- `dot_path_to_native`
+- `dot_open_path`
+
+This centralizes platform semantics and removes per-script drift.
+
+### 2) Hot-path optimization in shared utils
+
+Updated `scripts/dot/lib/utils.sh`:
+
+- sources `platform.sh`
+- adds process-local source dir cache (`_DOT_SOURCE_DIR_CACHE`)
+- avoids repeated filesystem checks in repeated command flows
+
+### 3) Faster, clearer diagnostics
+
+Updated `scripts/diagnostics/doctor.sh`:
+
+- new **Platform** section (runtime + host + WSL bridge/fallback checks)
+- warns when running in `/mnt/*` under WSL (high IO latency path)
+- scoped symlink scan to standard roots only (`~/.config`, `~/.local`, `~/.ssh`)
+- adds explicit `dot` command resolution check
+
+### 4) Onboarding clarity
+
+Updated `README.md`:
+
+- added “60-second onboarding” with a clear success state
+
+### 5) Test coverage for new abstraction
+
+Added `scripts/tests/unit/test_dot_lib_platform.sh`:
+
+- existence + syntax + function presence + return contract checks
+
+## File-by-file next refactors (high ROI)
+
+1. `scripts/dot/commands/tools.sh`
+- Split `cmd_aliases` into submodule file.
+- Replace repeated `command -v` checks with cached capability map.
+
+2. `dot_config/zsh/dot_zshrc.tmpl`
+- Add startup budget guard (record startup time; warn >400ms).
+- Move optional integrations behind capability checks generated once/session.
+
+3. `scripts/ops/health-check.sh`
+- Import `platform.sh`, unify WSL/macOS/Linux branch logic.
+- Emit machine-readable JSON summary for UI frontends.
+
+4. `scripts/diagnostics/perf.sh`
+- Add percentile reporting (P50/P95 over 10 runs).
+- Add regression threshold with actionable remediation hints.
+
+## Product roadmap (prioritized)
+
+### P0 (1-2 weeks)
+
+- Platform abstraction adoption across all dot commands.
+- Bounded diagnostic scans everywhere (`find` scope + timeout).
+- “Single-screen health” command output format harmonization.
+
+### P1 (2-4 weeks)
+
+- Local state model for predictive UX (`~/.local/state/dotfiles/session.json`).
+- Adaptive hints (“next best action”) based on detected failures.
+- Non-blocking diagnostics execution with staged rendering.
+
+### P2 (4-8 weeks)
+
+- Optional Rust helper binary for path/process abstraction and fast JSON output.
+- WASM-compatible policy engine for deterministic config validation.
+- Cross-device state sync model (privacy-first, local-first defaults).
+
+## Apple-tier UX bar (acceptance criteria)
+
+- First successful install + health check in under 90 seconds.
+- `dot doctor` completes in under 700ms on warmed cache.
+- No user-facing distinction between macOS/Linux/WSL for core commands.
+- All failures return one-line remediation with direct command to fix.

package/docs/archive/LEGACY_ROADMAP.md

@@ -0,0 +1,142 @@
+# The Ultimate Developer Environment Roadmap
+
+This roadmap outlines the path to a high-performance, super-efficient development machine designed for Rust, Python, and AI on Linux (Zorin OS / T2 Mac hardware).
+
+## Phase 1: Foundation (Completed)
+- **Core Shell**: Zsh + Oh My Zsh.
+- **Modern Prompt**: Starship (hooked & active).
+- **Language Managers**: `rustup` (Rust) and `fnm` (Node.js).
+- **Ultra-Fast Python**: `uv` installed.
+- **Basic Modern Tools**: `eza` (ls), `bat` (cat), `fd` (find), `ripgrep` (grep).
+- **Git Enhancements**: `lazygit` (TUI) and `delta` (Diffs).
+- **Multiplexer**: `zellij` installed.
+- **AI**: `ollama` installed locally.
+- **Security**: Firewall (`ufw`) enabled.
+
+---
+
+## Phase 2: Speed & Navigation (Completed)
+Focus: Reduce friction in filesystem navigation and build times.
+
+### 1. Navigation
+- [x] **Zoxide**: Smarter `cd` command that learns your habits (`z directory`).
+- [x] **FZF**: Command-line fuzzy finder. Essential for search history, files, and replacing standard completion.
+- [x] **Yazi**: Blazing fast terminal file manager (Rust-based).
+
+### 2. Rust Optimization
+- [x] **Mold**: Use the `mold` linker to speed up Rust compile times by 3x-10x.
+- [x] **Sccache**: Shared compilation cache to speed up recompilations across projects.
+- [x] **Bacon**: Background rust compiler that gives instant feedback on errors.
+
+### 3. Python Optimization
+- [x] **Ruff**: Extremely fast Python linter and formatter (replace flake8/black).
+- [x] **Global Config**: Set `uv` to use system Python or managed Python preferences.
+
+### 4. Code Search
+- [x] **Ripgrep-all (rga)**: Search inside PDFs, E-Books, zip files, etc.
+
+---
+
+## Phase 3: AI Power User (Completed)
+Focus: Integrate AI deeply into the workflow.
+
+- [x] **Fabric**: Open-source framework for augmenting humans using AI (installed via `cmd` path).
+- [x] **Open WebUI**: A beautiful web interface for `ollama` (requires Docker).
+- [x] **GitHub Copilot CLI**: Integrate AI assistance directly into the terminal commands.
+- [x] **Local RAG**: Setup tools to chat with your own documents locally (Open WebUI).
+
+---
+
+## Phase 4: System Tuning & Hardening (Completed)
+Focus: Squeeze every ounce of performance and security from the hardware.
+
+- [x] **Kernel Tuning**: Increase file descriptor limits and optimize TCP stack for lower latency.
+- [x] **Swap Optimization**: Configure `zram` for memory compression (improves performance on 16GB RAM).
+- [x] **Flatpak Overrides**: Secure Flatpak permissions using `Flatseal`.
+- [x] **Automated Updates**: Configure `unattended-upgrades` for security patches.
+
+---
+
+## Phase 5: Final Polish (Completed)
+- [x] **Global UV Config**: Created `~/.config/uv/uv.toml` for managed python perference.
+- [x] **Roadmap Completion**: Verified all items are 100% complete.
+
+---
+
+## Maintenance & Updates
+- **Update System**: `sudo apt update && sudo apt upgrade`
+- **Update Rust**: `rustup update`
+- **Update Node**: `fnm install --lts`
+- **Update UV**: `uv self update`
+- **Update Firmware**: `fwupdmgr get-updates`
+
+---
+
+## Phase 6: Desktop Environment (Completed)
+Focus: Clean, bloat-free, and supercharged GNOME/Zorin experience.
+
+- [x] **Bloatware Removal**: Removed games (`aisleriot`, `mines`, etc.) and media apps (`rhythmbox`, `totem`).
+- [x] **Menu Cleanup**: Created `hide_menu_entries.sh` to deduplicate and hide unwanted entries.
+- [x] **GNOME Extensions**: Installed productivity boosters via `gnome-extensions-cli`:
+    - [x] `Clipboard Indicator`: History management.
+    - [x] `Caffeine`: Prevent auto-suspend.
+    - [x] `Impatience`: Speed up animations.
+    - [x] `Vitals`: System monitoring in top bar.
+- [x] **Memory Tuning**: Optimize GNOME Shell performance.
+
+---
+
+## Phase 7: Browser Optimization (Completed)
+Focus: Chrome tuned for development and memory efficiency.
+
+- [x] **Settings**: Enable "Memory Saver" and "Energy Saver" via Managed Policies.
+- [x] **Extensions**: Automated installation of developer stack (uBlock, JSON Viewer, React DevTools, Vimium, Refined GitHub).
+- [x] **Profile Separation**: Separate Personal and Work profiles (Manual setup recommendation).
+
+---
+
+## Phase 8: Neovim IDE (Completed)
+Focus: Building a terminal-based IDE that rivals VS Code for Rust, Python, and AI.
+
+- [x] **Latest Version**: Installed Neovim v0.12.0-dev (Nightly) to resolve plugin stability issues.
+- [x] **Plugin Manager**: Setup `lazy.nvim` with modular config (Restored from **PR #62**).
+- [x] **Core Plugins**:
+    - [x] `Telescope`: Fuzzy finding.
+    - [x] `Treesitter`: Syntax highlighting.
+    - [x] `Harpoon`: Fast file switching.
+    - [x] `Neo-tree`: File explorer.
+- [x] **UI/UX Menus**: Added `dressing.nvim` and `telescope-ui-select.nvim` for modern, searchable selection lists and floating inputs.
+- [x] **LSP & Autocomplete**:
+    - [x] `Mason`: Managing LSPs (rust-analyzer, pyright, ruff).
+    - [x] `Cmp`: Autocompletion engine.
+- [x] **Language Specifics**:
+    - [x] **Rust**: `rustaceanvim` configured.
+    - [x] **Python**: `pyright` + `ruff`.
+- [x] **AI Integration**:
+    - [x] `Copilot.lua`: Enabled (needs `:Copilot auth`).
+    - [x] `CopilotChat.nvim`: Sidebar chat (VS Code style).
+    - [ ] `Avante.nvim`: Skipped (Removed due to complexity/instability).
+- [x] **VS Code Parity Pack**:
+    - [x] `Trouble`: Problems panel.
+    - [x] `Spectre`: Search/Replace.
+    - [x] `Autopairs`: Auto-close brackets.
+    - [x] `Todo-Comments`: TODO/FIXME highlighting.
+    - [x] `Persistence`: Session management.
+
+---
+
+## Phase 9: Repository Polish & PR #62 (In Progress)
+Focus: Finalize the `dotfiles` repository for public consumption and sync the local "Gold Standard" environment.
+
+- [x] **Repository Sync**:
+    - [x] Clone official repo to `~/dotfiles`.
+    - [ ] Sync validated configuration (Neovim, scripts, tuning) into repository.
+- [ ] **Documentation Update**:
+    - [ ] Refactor `README.md` for the modern architecture.
+    - [ ] Add "Easy Setup" and "Troubleshooting" guides.
+- [ ] **Final PR Submission**:
+    - [ ] Verify clean diff against original PR #62.
+    - [ ] Push updates to PR #62 branch.
+
+
+