@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/stylesheets/extra.css

@@ -1,444 +0,0 @@
-/* ──────────────────────────────────────────────────────────────────────────
- *  doc.dotfiles.io — custom theme
- *  Dark + terminal-green palette on MkDocs Material.
- *  Inspired by the polish of docs.n8n.io / GitHub docs dark, adapted to
- *  Material's structure.
- *  ────────────────────────────────────────────────────────────────────── */
-
-/* -- font stack ------------------------------------------------------------ */
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap");
-
-:root {
-  --dot-font-body: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI",
-    "Helvetica Neue", Arial, sans-serif;
-  --dot-font-code: "JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono",
-    Menlo, Consolas, monospace;
-
-  --dot-green: #7ee787;         /* terminal green */
-  --dot-green-bright: #b0f5b7;  /* hover / focused */
-  --dot-green-dim: #4a9153;     /* muted / secondary */
-  --dot-green-rgb: 126, 231, 135;
-
-  --dot-bg: #0b0e14;            /* base */
-  --dot-bg-elev: #111621;       /* elevated card */
-  --dot-bg-elev-2: #161b26;     /* higher elevation */
-  --dot-border: #1f2937;
-  --dot-border-strong: #2b3646;
-
-  --dot-fg: #e4e7ec;
-  --dot-fg-muted: #94a3b8;
-  --dot-fg-subtle: #64748b;
-}
-
-/* -- global typography ----------------------------------------------------- */
-body,
-.md-typeset {
-  font-family: var(--dot-font-body);
-  font-feature-settings: "ss01", "cv11";
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
-.md-typeset code,
-.md-typeset kbd,
-.md-typeset pre,
-code {
-  font-family: var(--dot-font-code);
-  font-feature-settings: "calt", "ss20";
-}
-
-/* -- dark palette override (slate) ---------------------------------------- */
-[data-md-color-scheme="slate"] {
-  --md-hue: 210;
-  --md-default-bg-color: var(--dot-bg);
-  --md-default-fg-color: var(--dot-fg);
-  --md-default-fg-color--light: var(--dot-fg-muted);
-  --md-default-fg-color--lighter: var(--dot-fg-subtle);
-  --md-default-fg-color--lightest: hsla(210, 20%, 40%, 0.3);
-
-  --md-primary-fg-color: var(--dot-green);
-  --md-primary-fg-color--light: var(--dot-green-bright);
-  --md-primary-fg-color--dark: var(--dot-green-dim);
-  --md-primary-bg-color: var(--dot-bg);
-  --md-primary-bg-color--light: var(--dot-bg-elev);
-
-  --md-accent-fg-color: var(--dot-green-bright);
-  --md-accent-fg-color--transparent: rgba(126, 231, 135, 0.1);
-  --md-accent-bg-color: var(--dot-bg);
-  --md-accent-bg-color--light: var(--dot-bg-elev);
-
-  --md-typeset-a-color: var(--dot-green);
-
-  --md-code-bg-color: var(--dot-bg-elev-2);
-  --md-code-fg-color: var(--dot-fg);
-  --md-code-hl-color: rgba(126, 231, 135, 0.12);
-  --md-code-hl-color--light: rgba(126, 231, 135, 0.08);
-
-  /* Admonitions */
-  --md-admonition-bg-color: var(--dot-bg-elev);
-  --md-admonition-fg-color: var(--dot-fg);
-
-  /* Footer */
-  --md-footer-bg-color: #050710;
-  --md-footer-bg-color--dark: #030509;
-}
-
-/* -- header --------------------------------------------------------------- */
-.md-header {
-  background-color: rgba(11, 14, 20, 0.92);
-  backdrop-filter: saturate(180%) blur(12px);
-  -webkit-backdrop-filter: saturate(180%) blur(12px);
-  border-bottom: 1px solid var(--dot-border);
-  box-shadow: none;
-}
-
-.md-header[data-md-state="shadow"] {
-  box-shadow: 0 1px 0 var(--dot-border);
-}
-
-.md-header__title {
-  font-weight: 600;
-  letter-spacing: -0.01em;
-}
-
-.md-header__button.md-logo :is(img, svg) {
-  color: var(--dot-green);
-  fill: var(--dot-green);
-  height: 1.6rem;
-  width: 1.6rem;
-}
-
-/* -- tabs --------------------------------------------------------------- */
-.md-tabs {
-  background-color: rgba(11, 14, 20, 0.85);
-  border-bottom: 1px solid var(--dot-border);
-}
-
-.md-tabs__link {
-  color: var(--dot-fg-muted);
-  opacity: 1;
-  font-size: 0.75rem;
-  font-weight: 500;
-  transition: color 120ms ease;
-}
-
-.md-tabs__link:hover,
-.md-tabs__link--active {
-  color: var(--dot-green-bright);
-}
-
-.md-tabs__link--active {
-  position: relative;
-}
-.md-tabs__link--active::after {
-  content: "";
-  position: absolute;
-  left: 0;
-  right: 0;
-  bottom: -2px;
-  height: 2px;
-  background: linear-gradient(90deg, transparent, var(--dot-green), transparent);
-}
-
-/* -- sidebar (left nav) --------------------------------------------------- */
-.md-nav__title {
-  font-size: 0.68rem;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  color: var(--dot-fg-subtle);
-  padding-top: 1.2rem;
-}
-
-.md-nav__link {
-  color: var(--dot-fg-muted);
-  transition: color 120ms ease, background-color 120ms ease;
-  border-radius: 6px;
-  padding: 4px 8px;
-  margin: 1px 0;
-}
-.md-nav__link:hover {
-  color: var(--dot-fg);
-  background: rgba(126, 231, 135, 0.06);
-}
-.md-nav__link--active,
-.md-nav__link.md-nav__link--active {
-  color: var(--dot-green-bright);
-  background: rgba(126, 231, 135, 0.1);
-  font-weight: 500;
-}
-
-/* -- right TOC ------------------------------------------------------------ */
-.md-nav--secondary .md-nav__title {
-  border-left: 2px solid var(--dot-border);
-  background: transparent;
-}
-.md-nav--secondary .md-nav__link--active {
-  border-left: 2px solid var(--dot-green);
-  color: var(--dot-green-bright);
-  background: transparent;
-}
-
-/* -- content -------------------------------------------------------------- */
-.md-typeset h1,
-.md-typeset h2,
-.md-typeset h3,
-.md-typeset h4 {
-  font-family: var(--dot-font-body);
-  letter-spacing: -0.02em;
-  color: var(--dot-fg);
-}
-
-.md-typeset h1 {
-  font-weight: 700;
-  font-size: 2.2rem;
-  line-height: 1.15;
-  margin-bottom: 0.6em;
-  background: linear-gradient(180deg, #ffffff 0%, #cbd5e1 100%);
-  -webkit-background-clip: text;
-  background-clip: text;
-  color: transparent;
-}
-
-.md-typeset h2 {
-  font-weight: 600;
-  font-size: 1.6rem;
-  margin-top: 2.4em;
-  padding-top: 0.4em;
-  border-top: 1px solid var(--dot-border);
-}
-
-.md-typeset h3 {
-  font-weight: 600;
-  font-size: 1.2rem;
-  color: var(--dot-green-bright);
-}
-
-.md-typeset a {
-  text-decoration: none;
-  border-bottom: 1px solid transparent;
-  transition: border-color 120ms ease, color 120ms ease;
-}
-.md-typeset a:hover {
-  border-bottom-color: var(--dot-green-bright);
-  color: var(--dot-green-bright);
-}
-
-/* -- code blocks ---------------------------------------------------------- */
-.md-typeset pre > code,
-.md-typeset .highlight pre {
-  background-color: var(--dot-bg-elev-2);
-  border: 1px solid var(--dot-border);
-  border-radius: 8px;
-}
-.md-typeset code {
-  background-color: rgba(126, 231, 135, 0.08);
-  border: 1px solid rgba(126, 231, 135, 0.15);
-  color: var(--dot-green-bright);
-  border-radius: 4px;
-  padding: 0.1em 0.35em;
-  font-size: 0.88em;
-}
-.md-typeset pre > code {
-  background: transparent;
-  border: none;
-  color: var(--dot-fg);
-  padding: 0;
-}
-
-/* -- tables --------------------------------------------------------------- */
-.md-typeset table:not([class]) {
-  border: 1px solid var(--dot-border);
-  border-radius: 8px;
-  overflow: hidden;
-  font-size: 0.8rem;
-}
-.md-typeset table:not([class]) th {
-  background: var(--dot-bg-elev);
-  color: var(--dot-fg);
-  font-weight: 600;
-  border-bottom: 1px solid var(--dot-border-strong);
-}
-.md-typeset table:not([class]) tr:hover {
-  background: rgba(126, 231, 135, 0.03);
-}
-
-/* -- admonitions ---------------------------------------------------------- */
-.md-typeset .admonition,
-.md-typeset details {
-  background: var(--dot-bg-elev);
-  border: 1px solid var(--dot-border);
-  border-left: 3px solid var(--dot-green);
-  border-radius: 8px;
-  box-shadow: none;
-}
-.md-typeset .admonition-title,
-.md-typeset summary {
-  background: transparent;
-  border-bottom: 1px solid var(--dot-border);
-  font-weight: 600;
-}
-
-/* -- grid cards ----------------------------------------------------------- */
-.md-typeset .grid.cards > :is(ul, ol) > li,
-.md-typeset .grid.cards > .card {
-  background: var(--dot-bg-elev);
-  border: 1px solid var(--dot-border);
-  border-radius: 12px;
-  padding: 1.2rem;
-  transition: transform 180ms ease, border-color 180ms ease,
-    box-shadow 180ms ease, background 180ms ease;
-  position: relative;
-  overflow: hidden;
-}
-.md-typeset .grid.cards > :is(ul, ol) > li::before {
-  content: "";
-  position: absolute;
-  inset: 0;
-  background: radial-gradient(
-    circle at top left,
-    rgba(126, 231, 135, 0.06),
-    transparent 60%
-  );
-  opacity: 0;
-  transition: opacity 220ms ease;
-  pointer-events: none;
-}
-.md-typeset .grid.cards > :is(ul, ol) > li:hover {
-  transform: translateY(-2px);
-  border-color: rgba(126, 231, 135, 0.35);
-  background: var(--dot-bg-elev-2);
-  box-shadow: 0 8px 24px -8px rgba(0, 0, 0, 0.5),
-    0 0 0 1px rgba(126, 231, 135, 0.08) inset;
-}
-.md-typeset .grid.cards > :is(ul, ol) > li:hover::before {
-  opacity: 1;
-}
-.md-typeset .grid.cards > :is(ul, ol) > li > :first-child {
-  margin-top: 0;
-}
-.md-typeset .grid.cards > :is(ul, ol) > li strong {
-  color: var(--dot-green-bright);
-  font-weight: 600;
-  font-size: 1rem;
-  display: block;
-  margin-bottom: 0.4rem;
-}
-.md-typeset .grid.cards > :is(ul, ol) > li .twemoji,
-.md-typeset .grid.cards > :is(ul, ol) > li svg {
-  color: var(--dot-green);
-  fill: var(--dot-green);
-  height: 1.4rem;
-  width: 1.4rem;
-  margin-bottom: 0.6rem;
-}
-
-/* -- hero banner (used by landing page) ----------------------------------- */
-.dot-hero {
-  padding: 3rem 0 2.4rem;
-  margin: -1.6rem -0.8rem 2.4rem;
-  text-align: center;
-  border-bottom: 1px solid var(--dot-border);
-  position: relative;
-  background: radial-gradient(
-    ellipse 60% 100% at 50% 0%,
-    rgba(126, 231, 135, 0.08),
-    transparent 70%
-  );
-}
-.dot-hero h1 {
-  font-size: 3rem;
-  line-height: 1.05;
-  margin-bottom: 0.4em;
-  padding: 0;
-  border: none;
-}
-.dot-hero .tagline {
-  font-size: 1.1rem;
-  color: var(--dot-fg-muted);
-  max-width: 40rem;
-  margin: 0 auto 1.4rem;
-}
-.dot-hero .buttons {
-  display: flex;
-  gap: 0.6rem;
-  justify-content: center;
-  flex-wrap: wrap;
-}
-.dot-hero .buttons a {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.4rem;
-  padding: 0.6rem 1.1rem;
-  border-radius: 8px;
-  font-weight: 500;
-  font-size: 0.9rem;
-  text-decoration: none;
-  border: 1px solid var(--dot-border-strong);
-  color: var(--dot-fg);
-  transition: all 160ms ease;
-}
-.dot-hero .buttons a.primary {
-  background: var(--dot-green);
-  color: var(--dot-bg);
-  border-color: var(--dot-green);
-  font-weight: 600;
-}
-.dot-hero .buttons a.primary:hover {
-  background: var(--dot-green-bright);
-  border-color: var(--dot-green-bright);
-  transform: translateY(-1px);
-}
-.dot-hero .buttons a:not(.primary):hover {
-  border-color: var(--dot-green);
-  color: var(--dot-green-bright);
-}
-
-/* -- search --------------------------------------------------------------- */
-.md-search__form {
-  background: var(--dot-bg-elev);
-  border: 1px solid var(--dot-border);
-  border-radius: 8px;
-}
-.md-search__form:hover,
-.md-search__input:focus + .md-search__icon,
-.md-search__form:focus-within {
-  border-color: var(--dot-green);
-  background: var(--dot-bg-elev-2);
-}
-.md-search__input {
-  color: var(--dot-fg);
-}
-.md-search__input::placeholder {
-  color: var(--dot-fg-subtle);
-}
-
-/* -- footer --------------------------------------------------------------- */
-.md-footer {
-  border-top: 1px solid var(--dot-border);
-}
-.md-footer-meta {
-  background: var(--dot-bg);
-  border-top: 1px solid var(--dot-border);
-}
-.md-copyright {
-  color: var(--dot-fg-subtle);
-  font-size: 0.72rem;
-}
-
-/* -- scrollbar (webkit) --------------------------------------------------- */
-::-webkit-scrollbar {
-  width: 10px;
-  height: 10px;
-}
-::-webkit-scrollbar-track {
-  background: transparent;
-}
-::-webkit-scrollbar-thumb {
-  background: var(--dot-border-strong);
-  border-radius: 8px;
-  border: 2px solid var(--dot-bg);
-}
-::-webkit-scrollbar-thumb:hover {
-  background: var(--dot-green-dim);
-}

package/docs/themes/README.md

@@ -1,10 +0,0 @@
----
-render_with_liquid: false
----
-
-# Theme Gallery
-
-Themes are auto-generated from your wallpapers — the available set depends on what's present on your system. Run `dot theme list` to see what's discovered.
-
-See [Theme Reference](../reference/THEMES.md) for the wallpaper-driven engine.
-See [Theming Guide](../guides/THEMING.md) for setup, switching, and the K-Means CIELAB pipeline.

package/docs/themes/VISUAL_INTEGRITY_REPORT.md

@@ -1,30 +0,0 @@
----
-render_with_liquid: false
----
-
-# Visual Integrity Report
-
-Generated: 2026-04-08
-Scope: terminal theme SSOT, shell first-paint path, font rendering, and cross-platform template intent.
-
-| Metric | Current | Target | Status |
-| :--- | :--- | :--- | :--- |
-| Contrast (APCA) | `macos-monterey-dark` body text `Lc 90+`, critical UI `Lc 95+` | `Lc 75+` body, `Lc 90+` critical | Pass |
-| Startup Time | `bash 25ms`, `zsh 35ms`, `fish 25ms` | `< 100ms` | Pass |
-| Color DeltaE | SSOT palette unified across Ghostty/Kitty/Alacritty/WezTerm; no runtime probe yet | `< 2.0` | Needs instrumentation |
-
-## Findings
-
-- Theme colors are already centralized in `.chezmoidata/themes.toml`, but accessibility intent was implicit. The active theme now carries explicit OKLCH/APCA metadata.
-- First-prompt Fish initialization still performed live CLI work when cache artifacts were present. The prompt path now sources prewarmed cache files first and only regenerates on cache miss.
-- Terminal templates were palette-consistent, but rendering policy was inconsistent. macOS now prefers Display P3 and CoreText-friendly metrics; Linux/Wayland templates prefer more conservative opacity and FreeType-safe fallbacks.
-
-## Edge Cases
-
-- Wayland fontconfig now sets `rgba` declaratively from feature flags to avoid color fringing on mixed-density Linux panels.
-- Ghostty, Kitty, Alacritty, and WezTerm now share the same terminal ramp while allowing platform-specific font fallback and window-compositor behavior.
-- WSL parity is still template-capable, but DeltaE validation is not yet automated against Windows Terminal serialization.
-
-## Next Step
-
-Implement a small palette audit utility that computes APCA and DeltaE from `.chezmoidata/themes.toml` so the report can become test-backed rather than declarative.

package/docs/themes/hero-shot.svg

@@ -1,78 +0,0 @@
-<svg width="800" height="450" viewBox="0 0 800 450" xmlns="http://www.w3.org/2000/svg">
-  <!-- Background Shadow -->
-  <rect x="10" y="10" width="780" height="430" rx="12" fill="rgba(0,0,0,0.3)" filter="blur(10px)" />
-
-  <!-- Terminal Window -->
-  <rect x="20" y="20" width="760" height="410" rx="10" fill="#1e1e2e" stroke="#313244" stroke-width="1" />
-
-  <!-- Window Title Bar -->
-  <path d="M20 30 a10 10 0 0 1 10 -10 h740 a10 10 0 0 1 10 10 v20 h-760 z" fill="#181825" />
-
-  <!-- macOS Buttons -->
-  <circle cx="40" cy="35" r="6" fill="#f38ba8" />
-  <circle cx="60" cy="35" r="6" fill="#fab387" />
-  <circle cx="80" cy="35" r="6" fill="#a6e3a1" />
-
-  <!-- Title -->
-  <text x="400" y="38" font-family="JetBrains Mono, monospace" font-size="12" fill="#bac2de" text-anchor="middle">~/.dotfiles — zsh</text>
-
-  <!-- Mock Terminal Content -->
-  <g font-family="JetBrains Mono, monospace" font-size="13">
-    <!-- Prompt + command -->
-    <text x="40" y="75" fill="#a6e3a1">&#10148;</text>
-    <text x="60" y="75" fill="#cdd6f4">dot doctor</text>
-
-    <!-- Section: Dotfiles Core -->
-    <text x="40" y="105" fill="#89b4fa" font-weight="bold">Dotfiles Core</text>
-    <text x="40" y="125" fill="#a6e3a1">  &#10003; chezmoi</text>
-    <text x="220" y="125" fill="#585b70">2.47.1 (mise)</text>
-    <text x="40" y="145" fill="#a6e3a1">  &#10003; git</text>
-    <text x="220" y="145" fill="#585b70">2.49.0 (system)</text>
-    <text x="40" y="165" fill="#a6e3a1">  &#10003; age encryption</text>
-    <text x="220" y="165" fill="#585b70">key present</text>
-
-    <!-- Section: Shell Environment -->
-    <text x="40" y="195" fill="#89b4fa" font-weight="bold">Shell Environment</text>
-    <text x="40" y="215" fill="#a6e3a1">  &#10003; zsh</text>
-    <text x="220" y="215" fill="#585b70">5.9.0 (system)</text>
-    <text x="40" y="235" fill="#a6e3a1">  &#10003; starship</text>
-    <text x="220" y="235" fill="#585b70">1.22.1 (mise)</text>
-    <text x="40" y="255" fill="#a6e3a1">  &#10003; zoxide</text>
-    <text x="220" y="255" fill="#585b70">0.9.7 (mise)</text>
-
-    <!-- Section: CLI Tools -->
-    <text x="420" y="105" fill="#89b4fa" font-weight="bold">CLI Tools</text>
-    <text x="420" y="125" fill="#a6e3a1">  &#10003; rg (ripgrep)</text>
-    <text x="600" y="125" fill="#585b70">14.1.1</text>
-    <text x="420" y="145" fill="#a6e3a1">  &#10003; bat</text>
-    <text x="600" y="145" fill="#585b70">0.25.0</text>
-    <text x="420" y="165" fill="#a6e3a1">  &#10003; fzf</text>
-    <text x="600" y="165" fill="#585b70">0.60.3</text>
-
-    <!-- Section: Security -->
-    <text x="420" y="195" fill="#89b4fa" font-weight="bold">Security</text>
-    <text x="420" y="215" fill="#a6e3a1">  &#10003; SSH keys</text>
-    <text x="600" y="215" fill="#585b70">ed25519</text>
-    <text x="420" y="235" fill="#a6e3a1">  &#10003; GPG signing</text>
-    <text x="600" y="235" fill="#585b70">configured</text>
-    <text x="420" y="255" fill="#a6e3a1">  &#10003; secrets (age)</text>
-    <text x="600" y="255" fill="#585b70">encrypted</text>
-
-    <!-- Performance line -->
-    <text x="40" y="290" fill="#89b4fa" font-weight="bold">Performance</text>
-    <text x="40" y="310" fill="#a6e3a1">  &#10003; zsh startup</text>
-    <text x="220" y="310" fill="#585b70">12ms</text>
-
-    <!-- Score -->
-    <text x="40" y="350" fill="#a6e3a1" font-weight="bold">Score: 95/100 — Excellent</text>
-    <text x="40" y="370" fill="#585b70">18 passed, 0 errors, 1 warning</text>
-
-    <!-- New prompt -->
-    <text x="40" y="405" fill="#a6e3a1">&#10148;</text>
-    <text x="60" y="405" fill="#cdd6f4">~/.dotfiles</text>
-    <text x="170" y="405" fill="#f5c2e7">on main</text>
-    <rect x="275" y="393" width="8" height="16" fill="#cdd6f4">
-      <animate attributeName="opacity" values="1;0;1" dur="1s" repeatCount="indefinite" />
-    </rect>
-  </g>
-</svg>

package/scripts/README.md

@@ -1,123 +0,0 @@
-# `scripts/` — Framework Code
-
-Everything in this directory is **framework code**. Nothing here
-deploys to `~/`; chezmoi ignores the whole tree (see
-`.chezmoiignore`). Scripts are invoked by the `dot` CLI, by CI
-workflows, by `chezmoi apply` hooks, or by hand.
-
-## Subtree map
-
-Per the repository reorg (RFC `docs/operations/RFC_v0_2_503_reorganization.md`),
-**repo-only ops** (CI, release, maintenance, docs-generation) have
-moved to the top-level `tools/` tree. `scripts/` retains the
-**runtime-invoked** scripts that the `dot` CLI dispatches to plus a
-few specialised subtrees.
-
-### `scripts/` (CLI dispatch + specialised subtrees)
-
-| Path | Purpose | Touched by |
-|---|---|---|
-| `scripts/dot/commands/` | Per-subcommand handlers for the `dot` CLI. Sources `lib/dot/*.sh` (moved out of this tree in the Phase 1 reorg). | Dispatched by `bin/dot` |
-| `scripts/dot/powershell/` | Native PowerShell module (`Dot.psm1`) exporting `Get-DotVersion` / `Invoke-DotHelp` / `Test-DotAgentsSync`. | `bin/dot.ps1` |
-| `scripts/dot/data/` | Per-command static data (registry seeds, palette tables). | `scripts/dot/commands/*` |
-| `scripts/lib/` | Cross-cutting library helpers reused across multiple scripts. Example: `secrets_provider.sh` (keychain / pass / age dispatch). | `scripts/dot/commands/*`, ops scripts |
-| `scripts/diagnostics/` | `doctor.sh` and its helpers — long-form environment health check. | `dot doctor` |
-| `scripts/security/` | Security-domain ops: `check-disclosure-key-expiry.sh`, `lock-configs.sh`, etc. | `dot security`, CI |
-| `scripts/secrets/` | Secret-bucket utilities (rotation, audit). | `dot secrets` subcommands |
-| `scripts/theme/` | Wallpaper-to-palette extraction logic. | `dot theme rebuild` |
-| `scripts/tools/` | Tool-helpers shipped via `dot tools` (e.g. `cmatrix.sh`, `emoji-picker.sh`, `figlet-banner.sh`, `log-rotate.sh`). Runtime-invoked. | `dot tools`, `dot env` |
-| `scripts/tuning/` | Opt-in OS tuning scripts (`macos.sh`, `linux.sh`). | `dot tune`, manual invocation |
-| `scripts/ops/` | Repo-wide ops: `rollback.sh`, etc. | `dot rollback`, maintenance |
-| `scripts/fonts/` | Nerd Font install helpers. | `dot fonts` |
-| `scripts/git-hooks/` | Git hooks not managed by chezmoi (kept here for portable install). | `install/provision/*` |
-| `scripts/qa/` | Quality-assurance helpers (PowerShell contract tests, version-consistency checks, scorecard snapshot, etc). | `.github/workflows/pr-signature.yml`, `powershell-contract.yml`, doc-drift |
-| `scripts/demo/` | Demonstration helpers (recordings, screenshots). | Manual |
-| `scripts/version-sync.sh` | Bulk version-string propagator (`scripts/qa/check-version-consistency.sh` is the verifier). | Release flow |
-| `scripts/uninstall.sh` | Reverse-of-`install.sh` — user-invoked. | Manual |
-
-### `tools/` (repo-only ops, not distributable)
-
-| Path | Purpose | Touched by |
-|---|---|---|
-| `tools/ci/` | CI-only helpers: `dot-cli-startup-bench.sh`, `install-chezmoi-verified.sh`, `windows-smoke-test.ps1`, `run-coverage.sh`, etc. | `.github/workflows/*` |
-| `tools/release/` | Release-time tasks. | Release workflow |
-| `tools/maintenance/` | Recurring upkeep: `check-updates.sh`, etc. | Cron, manual |
-| `tools/docs/` | Documentation-generation helpers (manual builds, screenshot CI, `generate-command-index.sh`). | `manual-publish.yml`, `dot manual`, doc-drift |
-
-## `scripts/dot/` breakdown
-
-The `dot` CLI is implemented as `bin/dot`
-(dispatcher) + `scripts/dot/commands/<cmd>.sh` (per-command
-handlers) + `lib/dot/*.sh` (shared helpers — moved out of
-`scripts/dot/lib/` in the Phase 1 reorg per the
-[reorganisation RFC](../docs/operations/RFC_v0_2_503_reorganization.md)).
-
-| Path | Purpose |
-|---|---|
-| `scripts/dot/commands/` | One file per `dot <cmd>` subcommand. Each defines a `cmd_<name>()` function the dispatcher calls. Sources the library via `$SCRIPT_DIR/../../../lib/dot/<X>.sh`. |
-| `scripts/dot/powershell/` | Native PowerShell module — see top-level table. |
-| **`lib/dot/utils.sh`** | Common helpers (resolve_source_dir, validate_name, die, run_script, etc.). |
-| **`lib/dot/ui.sh`** | Single source of truth for CLI output (ui_ok/warn/err/info, ui_header, ui_table_*, ui_spinner_*, ui_confirm, ...). |
-| **`lib/dot/platform.sh`** | OS / shell / WSL detection, path translation. |
-| **`lib/dot/log.sh`** | Structured logging (JSONL audit log when `DOTFILES_AUDIT_LOG=1`). |
-| **`lib/dot/bento.sh`** | The "bento box" layout primitive used by `dot health` and friends. |
-
-## Adding a new subcommand
-
-1. Create `scripts/dot/commands/<name>.sh`:
-
-   ```bash
-   #!/usr/bin/env bash
-   # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
-   set -euo pipefail
-   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-   # shellcheck source=../lib/utils.sh
-   source "$SCRIPT_DIR/../lib/utils.sh"
-
-   dot_ui_command_banner "<Title>" "${1:-}"
-
-   cmd_<name>() {
-     # ...
-   }
-
-   cmd_<name>_help() {
-     cat <<-EOF
-     Usage: dot <name> [args]
-     # ...
-   EOF
-   }
-   ```
-
-2. Add a dispatch arm in `bin/dot`:
-
-   ```bash
-   <name>) load_commands "<name>"; cmd_<name> "$@" ;;
-   ```
-
-3. Document it in `docs/manual/03-reference/01-dot-cli.md` and add
-   to `docs/manual/command-index.md`.
-
-4. Add a help-table entry in `bin/dot`'s
-   help renderer.
-
-5. Add a unit test under `tests/unit/<domain>/test_<name>.sh`
-   (run with `./tests/framework/test_runner.sh`).
-
-## Conventions
-
-- **Shell style**: 2-space indent, `set -euo pipefail`, shellcheck-clean
-  with the project's flags (`--severity=error -e SC1091 -e SC2030 -e SC2031`).
-- **Formatting**: `shfmt -i 2 -ci`.
-- **Output**: NEVER `printf` raw ANSI. Source `scripts/dot/lib/ui.sh`
-  and use `ui_ok`, `ui_table_*`, etc.
-- **Exit codes**: 1 = bad usage, 2 = no provider / dependency missing,
-  3 = empty result / not found, ≥4 = provider-specific. Document
-  per-command in the help text.
-- **Validation**: Always `validate_name "$arg" "tool name"` before
-  passing user input to `mise`, `gh`, `ssh`, etc.
-
-## See also
-
-- `../docs/STRUCTURE.md` — full repository map.
-- `docs/manual/03-reference/01-dot-cli.md` — every `dot <cmd>` documented.
-- `scripts/dot/lib/ui.sh` — the UI primitive library (always source this for output).