@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/architecture/REPO_LAYOUT.md

@@ -0,0 +1,241 @@
+---
+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` — 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.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                                           |
+| `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,86 @@
+---
+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

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

package/docs/archive/EUXIS_2026_REVIEW.md

@@ -0,0 +1,127 @@
+---
+render_with_liquid: false
+---
+
+# 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.
+
+1. `dot_config/zsh/dot_zshrc.tmpl`
+
+- Add startup budget guard (record startup time; warn >400ms).
+- Move optional integrations behind capability checks generated once/session.
+
+1. `scripts/ops/health-check.sh`
+
+- Import `platform.sh`, unify WSL/macOS/Linux branch logic.
+- Emit machine-readable JSON summary for UI frontends.
+
+1. `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.