dotfiles/.config/dot/todo.md

# Migration findings: ~/wrk/dotfiles (old) → ~/.dotfiles (new)

Exploratory session comparing the archived i3/X11/bash dotfiles repo
(`~/wrk/dotfiles`, GitHub, 2023-2025) against the current bare-repo setup
(`~/.dotfiles`, Gitea, started 2026-07-03) on a fresh CachyOS + KDE Plasma
(Wayland) machine. Goal: not a literal port — for each old feature, decide
whether CachyOS/KDE already covers it for free (skip) or whether it needs an
equivalent tracked in the new repo (port). Nothing below has been
implemented yet; this is a planning doc only.

## Resolved — no action needed (already covered by KDE/CachyOS defaults)

- **Package management split** (old: `pacman.gui/nogui` + `aur.gui/nogui` +
  Makefile/aurman installer). New `dot install` + flat `packages/pacman`
  stays as-is — no plan to port the old list wholesale, just add packages as
  needed.
- **Touchpad `xorg.conf`** — `kcminputrc`/System Settings has caused no
  issues; not tracking it.
- **i3 tiling paradigm** (focus-by-direction, split/layout toggle, floating
  toggle, resize, move-by-pixel, gaps, borders) — dropped entirely. No KWin
  tiling script (Polonium/Bismuth/Krohnkite) installed or wanted; primary
  tiling-like workflow now happens in tmux. KDE's native floating +
  quick-tile (`Meta+Arrow`) is accepted as-is.
- **i3 workspace switch/move** (`Super+1-9,0` / `Super+Shift+1-9,0`) —
  already matched by existing KDE defaults: `Meta+1-9` (Switch to Desktop
  N), `Meta+Shift+1-9` i.e. `Meta+!/@/#/...` (Window to Desktop N).
- **Desktop count** — KDE has 9 virtual desktops configured; confirmed
  sufficient, no change to 10.
- **Workspace/window assignment rules** (`assign firefox → ws1`, `plexamp →
  ws10`) — skipped. `kwinrulesrc` stays empty for now.
- **Kill/reload/restart WM keys** — functionally covered by KDE defaults
  (`Alt+F4` close, `Meta+Ctrl+Esc` kill window).
- **Terminal launch** (`Super+Return` → alacritty) — already identically
  bound: `Meta+Return` → Alacritty, confirmed in `kglobalshortcutsrc`.
- **App launcher** (rofi) — superseded by KRunner (default `Alt+Space`/`Alt+F2`).
- **Media keys** (volume, mic mute, play/pause/next/prev) — already covered
  natively via hardware key bindings, exceeding the old `wpctl`+`playerctl`
  setup.
- **Brightness/backlight keys** — already covered via hardware
  `Monitor Brightness Up/Down` bindings (powerdevil).
- **picom, Xresources, dracula color theme** — dropped. Not using dracula
  going forward; kwin compositor replaces picom with no config needed.
- **rofi power menu** (lock/shutdown/restart/switch-user) — covered by
  existing KDE defaults: `Meta+L` (Lock Session), `Ctrl+Alt+Del` (Show
  Logout Screen = full power menu). *Note: `Meta+L` will be reassigned, see
  below — Lock Session needs to move to `Meta+X`.*
- **polybar → Plasma panel** — nearly the entire module set already exists
  as stock, **unmodified** Plasma panel defaults on this machine: workspace
  indicator → Pager applet, battery → Battery applet (machine has `BAT0`),
  backlight → Brightness applet, date/time → Digital Clock applet, volume →
  system tray audio, now-playing → Media Controller applet (present, just
  nothing to show — no MPRIS player installed currently). Only non-exact
  match is polybar's centered window-title label (closest KDE equivalent is
  the icon-only taskbar) — decided not worth adding a dedicated Window Title
  applet. Whole row needs no tracking; see also the panel-layout finding
  below (it's CachyOS's own shipped default, reproduces automatically).

## Resolved — needs porting (design agreed, not yet built)

- **Extra groups** (old: `.extra_groups` → `video`, `docker` via
  `setup_users` in `bin/dot init`). Missing in new repo; not urgently needed
  yet but a real gap.
  - **Architecture decision**: new `dot` subcommand, e.g. `dot setup` (name
    tentative), separate from `dot init`. `dot init` stays scoped to the
    one-shot bootstrap (clone + checkout) and explicitly refuses to re-run;
    `dot setup` is idempotent/re-runnable and is the new home for
    machine-setup tasks (extra groups, folder layout, future ones), mirroring
    the old `bin/dot init`'s `setup_users`/`setup_folders` sub-task split.
- **Folder naming / XDG dirs** (old: `setup_folders` renamed
  `Desktop→.desktop`, `Documents→doc`, `Downloads→dwn`, `Music→mus`,
  `Pictures→pic`, `Videos→vid`, `Templates/Public→.ignoreme`).
  - **Decision**: restore the short-name convention (better for fish
    autocompletion — shorter shared prefixes, e.g. `doc`/`dwn` only share one
    character vs `Documents`/`Downloads`).
  - Replace old `Projects`-style folder with **`wrk`** (matches the existing
    `~/wrk` directory already in active use, e.g. `~/wrk/dotfiles`).
  - `user-dirs.dirs` currently untracked and diverged (has full names +
    an ad hoc `XDG_PROJECTS_DIR=$HOME/Projects` not in the old file at all).
    Needs to be regenerated to the short-name convention (with `wrk`) and
    then tracked, as part of the `dot setup` folders task.
- **Caps-lock/Escape swap** — user confirmed this needed manual
  configuration (`kxkbrc`: `Options=caps:escape_shifted_capslock`), it is
  **not** a KDE default. Needs tracking. No kcfg schema backs this setting —
  it's a freeform string; "default" = the `Options=` line being absent
  entirely. Simple to declare directly, no diffing tooling needed for this
  one.
- **Screenshots** (old: `Print`/`Ctrl+Print`/`Shift+Print` via `maim`+`xclip`
  → `~/pic/screenshots/`, save + clipboard copy).
  - **New keybinds**: `Meta+L` = full-screen capture, `Ctrl+Meta+L` = select
    region, `Shift+Meta+L` = window capture — all via **Spectacle** (built-in
    capture + clipboard; `maim`/`xclip` not needed, `xclip` isn't even
    installed).
  - **Consequence**: `Meta+L` is currently KDE's default Lock Session
    shortcut — must be freed and Lock Session rebound to **`Meta+X`**.
  - **Folder**: rename Spectacle's default save-folder name from
    `Screenshots` (capital) to lowercase `screenshots`, matching the rest of
    the short-folder convention.
  - **Open detail**: exact Spectacle shortcut action IDs (likely
    `FullScreenScreenShot`, `RectangularRegionScreenShot`,
    `ActiveWindowScreenShot`) need to be verified via System Settings →
    Shortcuts at implementation time — only `CurrentMonitorScreenShot` and
    `OpenWithoutScreenshot` show up in the current `kglobalshortcutsrc` dump
    (both unset), the others aren't customized yet so don't appear there.

## KDE config-tracking architecture (cross-cutting decision)

**Problem**: KDE rc files (`kxkbrc`, `kglobalshortcutsrc`, `kwinrc`,
`plasma-org.kde.plasma.desktop-appletsrc`, `kdeglobals`, etc.) mix real user
intent with large amounts of machine-specific/volatile noise (timestamps,
UUIDs, window state, plugin caches). Whole-file tracking (what naive
dotfiles repos do, e.g. `dnephin/dotfiles`) produces noisy diffs and risks
clobbering machine-specific state.

**Considered and rejected (for now)**: `chezmoi_modify_manager`-style
filtered source-of-truth + merge script. Powerful (tracks a minimal "intent"
INI fragment + per-file ignore/set rules, merges onto the live file), but
it's real tooling to build from scratch outside of chezmoi, and not
justified yet for the ~2 settings currently in scope.

**Decision**: track KDE settings as a declarative list of key/value pairs
applied imperatively via `kwriteconfig6`, run through `dot setup` (or
wherever machine-setup tasks land, see above) — not one-off hand-written
`kwriteconfig6` calls accumulating over time.

**Auto-detection tooling to build** (exploratory design only — not
implemented):

- **Command**: `dot config kde` — deliberately dispatchable, implies a
  `dot config <target>` family with room for non-KDE targets later.
- **Language**: Python 3 (already installed) for XML/kcfg parsing — nested
  `<group>`/`<entry>`/`<default>` structures are painful to parse in
  fish/`xmllint` one-liners. Invoked from a fish wrapper
  (`~/.config/dot/commands/config.fish` → `_dot_config` → sub-dispatch to
  KDE logic), following the existing help-then-argparse /
  `_dot_<name>_usage` convention.
- **Coverage**: as broad as possible across known KDE rc files, not just
  `kwinrc` — files/settings with nothing customized are expected to return
  empty, that's fine.
- **Per-file-type handling** (three different mechanisms, no single
  approach covers everything):
  1. **`kglobalshortcutsrc`** — self-describing, no schema needed. Each line
     is `Action=Current,Default,FriendlyName`; diff field 1 vs field 2,
     report only mismatches. Fully automatic.
  2. **KConfigXT schema-backed settings** — real schemas exist at
     `/usr/share/config.kcfg/*.kcfg` (41 files on this machine) with
     `<default>` tags per `<entry>` inside `<group>` blocks. **Caveat**: not
     every kcfg statically declares its target rc file — some use
     `<kcfgfile arg="true" />` (e.g. `kwin.kcfg`), meaning the target file is
     supplied at runtime by the owning app, not in the XML. Full automatic
     discovery isn't possible in all cases; a curated `(rcfile → [kcfg
     files])` mapping table needs to be hardcoded from domain knowledge —
     confirmed acceptable. Known `kwinrc` mapping so far:
     `virtualdesktopssettings.kcfg`, `kwindecorationsettings.kcfg`,
     `workspaceoptions_kwinsettings.kcfg`, several accessibility kcfg files,
     plus `kwin.kcfg` itself (needs manual mapping, `arg="true"`). For each
     entry: read the live value via
     `kreadconfig6 --file <rcfile> --group <group> --key <key>` and compare
     against the schema's `<default>`.
  3. **Freeform/schema-less string settings** (e.g. `kxkbrc`'s `Options=`
     line) — no kcfg exists; "default" simply means the key/line is absent.
     Trivial, no diffing tooling needed, just declare directly.
  4. **Plasma panel layout** (`plasma-org.kde.plasma.desktop-appletsrc`) —
     not schema-based at all; generated once from a shipped `layout.js`.
     Confirmed CachyOS ships its **own** look-and-feel/layout
     (`/usr/share/plasma/look-and-feel/CachyOS-Nord/`), not vanilla KDE
     Breeze — so the current panel *is* "default" by construction and
     reproduces automatically on any fresh CachyOS install. No tracking
     needed, no diffing possible/necessary.
  5. **Empirical fallback** (not needed yet, noted for completeness): for
     anything not covered by the above, spin up a scratch
     `HOME`/`XDG_CONFIG_HOME`, let the app initialize its config fresh, diff
     against the real file.

**Status**: design only, per explicit instruction — do not implement until
asked.

## Also noted, not yet actioned

- Once any of the above keybind changes are actually made (screenshot
  rebinds, `Meta+L`→`Meta+X` lock move, etc.), remember the project's own
  convention: add/update rows in `~/.github/keybindings.md` for each changed
  keybind, per `~/.config/dot/CLAUDE.md`.

## dot voice — hands-free dictation (shelved, 2026-07-04)

Built and then fully reverted a `dot voice` subcommand for hands-free
dictation into Claude Code: local Silero VAD (torch-free, onnxruntime
only) segmenting mic audio into utterances, each POSTed to a
`whisper-server` instance running remotely on a Proxmox host with an
NVIDIA GPU (Vulkan backend), transcribed text buffered at the cursor via
`ydotool`, submitted on a spoken "send it" and cancelled on "scratch
that".
Iterated through several accuracy levers in one session: dropped then
restored a literal-vocabulary `initial_prompt` (helped once on the
stronger model), a deterministic post-transcription `replacements.txt`
for persistent single-word misses, per-request `temperature`/
`temperature_inc`, beam search (`-bs`/`-bo`, ruled out as a factor),
and a quantization bump from `q5_0` to full fp16 `medium.en` (helped
substantially).
Also fixed a real bug along the way: whisper-server can return multi-
segment text joined by newlines, and `ydotool type` sends an embedded
`\n` as a literal Enter keypress — this was silently submitting partial
dictation mid-sentence. Fixed by collapsing all whitespace before typing.
Despite all of that, real-world accuracy over the laptop's built-in mic
was still not good enough for daily use — small word-substitution and
dropped-word errors persisted even with the best config found (fp16,
no beam search, prompt restored).
**Shelved reason**: audio input quality was the one variable never
tested — everything tuned this session was server/decoding-side. The
user's only better-microphone option is their desktop, which doesn't
have this dotfiles setup yet.
**If resumed**: test with a real microphone (headset/USB) before any
further server-side tuning — it's suspected to matter more than any of
the software changes made so far. Also worth trying `large-v3-turbo`
given the Proxmox GPU had comfortable headroom even at fp16 `medium.en`
(~0.1–0.5s per utterance).
**State**: fully reverted, nothing left in the tree or installed
packages list. The full implementation existed as local commit
`745e417f19a02bc589c5b32853e629993adaa01f` ("dotcli: Voice dictation
software using whisper"), never pushed, then hard-reset away — not
recoverable via normal git history, only via reflog for a limited time
if urgently needed. The KDE global shortcut (`Meta+Ctrl+Space` → `dot
voice arm`) was configured in System Settings and was **not** undone by
this revert — check System Settings → Shortcuts → Custom Shortcuts if
this work is ever picked back up or fully abandoned.