Merge branch 'main' of ssh://git.commumedia.org:2222/alex/dotfiles

.config/fish/config.fish

@@ -29,3 +29,6 @@ end
 # bun
 set --export BUN_INSTALL "$HOME/.bun"
 set --export PATH $BUN_INSTALL/bin $PATH
+
+# opencode
+fish_add_path /home/alex/.opencode/bin

.config/hypr/hyprland.lua

@@ -12,14 +12,19 @@ end
 local main_mod = "SUPER"
 local terminal = "alacritty"
 
+local input = {
+  kb_layout = "us",
+  kb_variant = "intl",
+  numlock_by_default = true,
+}
+for key, value in pairs(machine.input or {}) do
+  input[key] = value
+end
+
 hl.config({
-  input = {
-    kb_layout = "us",
-    kb_variant = "intl",
-    numlock_by_default = true,
-  },
+  input = input,
   general = {
-    gaps_in = 8,
+    gaps_in = 4,
     -- Keep a thin black perimeter so the bottom border remains on-screen.
     gaps_out = 2,
     border_size = 2,
@@ -35,16 +40,27 @@ hl.config({
   animations = {
     enabled = false,
   },
+  binds = {
+    -- Selecting the current workspace again returns to the last workspace.
+    workspace_back_and_forth = true,
+  },
+})
+
+-- Dynamically hide the border when a workspace has exactly one tiled app.
+hl.workspace_rule({
+  workspace = "w[t1]",
+  no_border = true,
 })
 
 -- Application and session bindings.
 local noctalia_ipc = "noctalia msg "
+local pi_status_ui_toggle = 'ui="${PI_STATUS_UI_BINARY:-$HOME/projects/pi-status-bridge/ui/src-tauri/target/release/pi-status-ui}"; if test -x "$ui"; then setsid -f env TMPDIR=/tmp "$ui" --toggle >/tmp/pi-status-ui.log 2>&1; fi'
 -- Tap and release Super on its own to open Noctalia's control-center home.
 hl.bind(main_mod .. " + SUPER_L", hl.dsp.exec_cmd(noctalia_ipc .. "panel-toggle control-center"), { release = true })
 hl.bind(main_mod .. " + RETURN", hl.dsp.exec_cmd(terminal))
 hl.bind(main_mod .. " + CTRL + RETURN", hl.dsp.exec_cmd(terminal .. " -e zellij"))
 hl.bind(main_mod .. " + SHIFT + RETURN", hl.dsp.exec_cmd("rofi -show combi"))
-hl.bind(main_mod .. " + SPACE", hl.dsp.exec_cmd(noctalia_ipc .. "panel-toggle launcher"))
+hl.bind(main_mod .. " + SPACE", hl.dsp.exec_cmd(pi_status_ui_toggle))
 hl.bind(main_mod .. " + S", hl.dsp.exec_cmd(noctalia_ipc .. "panel-toggle control-center"))
 hl.bind(main_mod .. " + SHIFT + F", hl.dsp.exec_cmd(noctalia_ipc .. "bar-toggle main"))
 hl.bind(main_mod .. " + SHIFT + R", hl.dsp.exec_cmd("hyprctl reload"))
@@ -52,7 +68,7 @@ hl.bind(main_mod .. " + CTRL + L", hl.dsp.exec_cmd("command -v hyprlock >/dev/nu
 hl.bind(main_mod .. " + CTRL + SHIFT + ALT + S", hl.dsp.exec_cmd("systemctl suspend"))
 hl.bind(main_mod .. " + CTRL + SHIFT + ALT + H", hl.dsp.exec_cmd("systemctl hibernate"))
 hl.bind(main_mod .. " + SHIFT + C", hl.dsp.window.close())
-hl.bind(main_mod .. " + CTRL + SHIFT + F", hl.dsp.exec_cmd("env LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 flameshot gui"))
+hl.bind(main_mod .. " + CTRL + SHIFT + F", hl.dsp.exec_cmd("/home/alex/.local/bin/screenshot-select"))
 
 -- Audio, media, brightness, and calculator keys.
 hl.bind("XF86AudioLowerVolume", hl.dsp.exec_cmd("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-"), { locked = true })
@@ -64,10 +80,10 @@ hl.bind("XF86AudioNext", hl.dsp.exec_cmd("playerctl next"), { locked = true })
 hl.bind("XF86AudioPrev", hl.dsp.exec_cmd("playerctl previous"), { locked = true })
 hl.bind(main_mod .. " + XF86AudioRaiseVolume", hl.dsp.exec_cmd("playerctl next"), { locked = true })
 hl.bind(main_mod .. " + XF86AudioLowerVolume", hl.dsp.exec_cmd("playerctl previous"), { locked = true })
-hl.bind("XF86MonBrightnessUp", hl.dsp.exec_cmd('light -A 5 && notify-send "Brightness set to $(light)"'), { locked = true })
-hl.bind("XF86MonBrightnessDown", hl.dsp.exec_cmd('light -U 5 && notify-send "Brightness set to $(light)"'), { locked = true })
-hl.bind(main_mod .. " + XF86MonBrightnessDown", hl.dsp.exec_cmd('light -S 0.2 && notify-send "Brightness set to min"'), { locked = true })
-hl.bind(main_mod .. " + XF86MonBrightnessUp", hl.dsp.exec_cmd('light -S 100 && notify-send "Brightness set to max"'), { locked = true })
+hl.bind("XF86MonBrightnessUp", hl.dsp.exec_cmd('light -A 5'), { locked = true })
+hl.bind("XF86MonBrightnessDown", hl.dsp.exec_cmd('light -U 5'), { locked = true })
+hl.bind(main_mod .. " + XF86MonBrightnessDown", hl.dsp.exec_cmd('light -S 0.0'), { locked = true })
+hl.bind(main_mod .. " + XF86MonBrightnessUp", hl.dsp.exec_cmd('light -S 100'), { locked = true })
 hl.bind("XF86Calculator", hl.dsp.exec_cmd("qalculate-qt"), { locked = true })
 
 -- Retain i3's hjkl and arrow-key directional workflow.
@@ -88,7 +104,9 @@ for workspace = 1, 9 do
   hl.bind(main_mod .. " + SHIFT + " .. key, hl.dsp.window.move({ workspace = workspace }))
   hl.bind(main_mod .. " + CTRL + " .. key, hl.dsp.window.move({ workspace = workspace, follow = true }))
 end
--- Hyprland has no direct i3-style back_and_forth dispatcher; use numbered workspaces.
+-- Match i3's back-and-forth workflow: Super+Tab switches to the last workspace;
+-- selecting the current numbered workspace also returns to it.
+hl.bind(main_mod .. " + TAB", hl.dsp.focus({ workspace = "previous" }))
 hl.bind(main_mod .. " + CTRL + RIGHT", hl.dsp.focus({ workspace = "+1" }))
 hl.bind(main_mod .. " + CTRL + LEFT", hl.dsp.focus({ workspace = "-1" }))
 
@@ -113,6 +131,7 @@ local function float_rule(name, match, border_size)
 end
 
 hl.window_rule({ name = "thunderbird-workspace", match = { class = "^Thunderbird$" }, workspace = "9" })
+float_rule("pi-status-ui", { class = "^pi-status-ui$" }, 1)
 float_rule("alsamixer", { title = "^alsamixer$" }, 1)
 float_rule("qalculate", { title = "^Qalculate!$" })
 float_rule("psensor", { class = "^Psensor$" })

.config/hypr/machine.lua##class.arch_laptop

@@ -1,6 +1,11 @@
 -- Laptop profile: leave monitor selection to Hyprland's hotplug support.
 -- Noctalia replaces the i3-era Redshift, Polybar, Blueman Applet, and Picom stack.
 return {
+  input = {
+    touchpad = {
+      natural_scroll = true,
+    },
+  },
   monitors = {},
   startup = {
     "noctalia",

.config/noctalia/10-base.toml

@@ -10,3 +10,44 @@ mode = "dark"
 source = "custom"
 custom_palette = "Ember OLED"
 pure_black_dark = true
+
+# Noctalia merges files alphabetically. Keep reusable modules here; machine-specific
+# layout and hardware settings live in 90-machine.toml, while 99-extend.toml is local.
+[plugins]
+enabled = ["alex/system-status"]
+
+[widget.cpu]
+type = "alex/system-status:cpu"
+
+[widget.ram]
+type = "alex/system-status:memory"
+
+[widget.network-rate]
+type = "alex/system-status:network-rate"
+
+[widget.temp]
+type = "sysmon"
+stat = "cpu_temp"
+display = "text"
+
+[widget.disk]
+type = "sysmon"
+stat = "disk_pct"
+display = "text"
+path = "/"
+
+[desktop_widgets]
+enabled = false
+
+[wallpaper]
+enabled = true
+fill_color = "#000000"
+
+[wallpaper.default]
+path = "color:#000000"
+
+[nightlight]
+enabled = true
+force = false
+temperature_day = 6500
+temperature_night = 2500

.config/noctalia/90-machine.toml##class.arch_desktop

@@ -1,19 +1,20 @@
 # Desktop-specific shell layout and hardware telemetry.
 [bar.main]
 position = "bottom"
-layer = "overlay"
+layer = "top"
 capsule_radius = 5
 center = ["group:g3", "notifications"]
-end = ["bluetooth", "volume", "control-center", "group:g1", "session"]
+end = ["bluetooth", "input_volume", "volume", "control-center", "group:g1", "session"]
 font_weight = 400
 margin_ends = 0
 padding = 0
 panel_overlap = 3
 radius = 0
 shadow = false
-smart_auto_hide = true
-# The bar may overlay the thin perimeter while visible; hidden bars release the space.
-reserve_space = false
+# Keep the desktop status bar visible and reserve its screen edge.
+auto_hide = false
+smart_auto_hide = false
+reserve_space = true
 start = ["tray", "group:g4", "group:g2", "privacy"]
 thickness = 39
 widget_spacing = 10
@@ -47,21 +48,10 @@ radius = 5.0
 enabled = true
 fill = "surface_variant"
 id = "g4"
-members = ["cpu", "temp", "ram", "gpu", "gpu_temp", "disk", "battery"]
+members = ["cpu", "temp", "ram", "gpu", "gpu_temp", "disk"]
 opacity = 1.0
 padding = 6.0
 
-[widget.cpu]
-type = "alex/system-status:cpu"
-
-[widget.ram]
-type = "alex/system-status:memory"
-
-[widget.temp]
-type = "sysmon"
-stat = "cpu_temp"
-display = "text"
-
 [widget.gpu]
 type = "sysmon"
 stat = "gpu_usage"
@@ -72,39 +62,11 @@ type = "sysmon"
 stat = "gpu_temp"
 display = "text"
 
-[widget.disk]
-type = "sysmon"
-stat = "disk_pct"
-display = "text"
-path = "/"
-
-[battery.device."/org/freedesktop/UPower/devices/battery_hidpp_battery_0"]
-warning_threshold = 20
-
 [control_center]
 sidebar = "full"
 sidebar_section = "full"
 width = 880
 
-[desktop_widgets]
-enabled = false
-
-[wallpaper]
-enabled = true
-fill_color = "#000000"
-
-[wallpaper.default]
-path = "color:#000000"
-
 [system.monitor]
 # GPU polling is disabled by Noctalia by default; enable it for the RTX 3090 widgets.
 gpu_poll_seconds = 2.0
-
-[plugins]
-enabled = ["alex/system-status"]
-
-[nightlight]
-enabled = true
-force = false
-temperature_day = 6500
-temperature_night = 2500

.config/noctalia/90-machine.toml##class.arch_laptop

@@ -1,10 +1,11 @@
 # Laptop-specific Noctalia layout. Shared privacy/theme defaults live in 10-base.toml.
 [bar.main]
 position = "top"
-layer = "overlay"
+layer = "top"
+scale = 0.95
 capsule_radius = 5
 center = ["group:g3", "notifications"]
-end = ["bluetooth", "volume", "control-center", "group:g1", "session"]
+end = ["group:g2", "group:g6", "group:g5", "group:g1", "session"]
 font_weight = 400
 margin_ends = 0
 padding = 0
@@ -14,7 +15,8 @@ shadow = false
 auto_hide = false
 smart_auto_hide = false
 reserve_space = true
-start = ["tray", "group:g4", "group:g2", "privacy"]
+start = ["tray", "group:g4", "privacy"]
+# Accommodate the battery-rate widget's wattage + ETA lines without clipping.
 thickness = 39
 widget_spacing = 10
 
@@ -30,7 +32,7 @@ padding = 6.0
 enabled = true
 fill = "surface_variant"
 id = "g2"
-members = ["network_rx", "network_tx", "network"]
+members = ["network-rate", "network", "bluetooth"]
 opacity = 1.0
 padding = 6.0
 
@@ -47,47 +49,35 @@ radius = 5.0
 enabled = true
 fill = "surface_variant"
 id = "g4"
-members = ["cpu", "temp", "ram", "disk", "battery"]
+members = ["gpu-mode", "cpu", "temp", "ram", "disk"]
 opacity = 1.0
 padding = 6.0
 
-[widget.cpu]
-type = "alex/system-status:cpu"
+[[bar.main.capsule_group]]
+enabled = true
+fill = "surface_variant"
+id = "g5"
+members = ["battery-rate", "battery", "power_profile"]
+opacity = 1.0
+padding = 6.0
+radius = 5.0
 
-[widget.ram]
-type = "alex/system-status:memory"
+[[bar.main.capsule_group]]
+enabled = true
+fill = "surface_variant"
+id = "g6"
+members = ["input_volume", "volume"]
+opacity = 1.0
+padding = 6.0
+radius = 5.0
 
-[widget.temp]
-type = "sysmon"
-stat = "cpu_temp"
-display = "text"
+[widget.battery-rate]
+type = "alex/system-status:battery-rate"
 
-[widget.disk]
-type = "sysmon"
-stat = "disk_pct"
-display = "text"
-path = "/"
+[widget.gpu-mode]
+type = "alex/system-status:gpu-mode"
 
 [control_center]
 sidebar = "full"
 sidebar_section = "full"
 width = 720
-
-[desktop_widgets]
-enabled = false
-
-[wallpaper]
-enabled = true
-fill_color = "#000000"
-
-[wallpaper.default]
-path = "color:#000000"
-
-[plugins]
-enabled = ["alex/system-status"]
-
-[nightlight]
-enabled = true
-force = false
-temperature_day = 6500
-temperature_night = 2500

.local/share/noctalia/plugins/system-status/cpu.luau

@@ -11,6 +11,26 @@ local command = [[awk '
 local previous = {}
 local request_in_flight = false
 
+local function colorForUsage(percent)
+  if percent >= 85 then
+    return "#ff453a" -- red
+  end
+  if percent >= 70 then
+    return "#ff8800" -- orange
+  end
+  if percent >= 50 then
+    return "#ffd60a" -- yellow
+  end
+  return "#ffffff" -- white
+end
+
+local function renderStatus(text, color)
+  barWidget.render(ui.row({ gap = 4, align = "center" }, {
+    ui.glyph({ name = "cpu", size = 14, color = color }),
+    ui.label({ text = text, color = color }),
+  }))
+end
+
 function update()
   noctalia.setUpdateInterval(2000)
 
@@ -23,7 +43,8 @@ function update()
     request_in_flight = false
 
     if result.exitCode ~= 0 then
-      barWidget.setText("CPU —")
+      renderStatus("CPU —", "#fff1e6")
+      barWidget.setTooltip("Unable to read CPU utilization")
       return
     end
 
@@ -47,12 +68,19 @@ function update()
       previous[name] = { total = total, idle = idle }
     end
 
-    barWidget.setGlyph("cpu")
     if sampled > 0 then
-      barWidget.setText(string.format("%.0f%%", utilization))
-      barWidget.setTooltip("Aggregate CPU utilization (100% per logical CPU)")
+      -- Keep the aggregate display, but base its heat color on average
+      -- utilization per logical CPU so multicore systems do not stay red.
+      local per_cpu_utilization = utilization / sampled
+      renderStatus(string.format("%.0f%%", utilization), colorForUsage(per_cpu_utilization))
+      barWidget.setTooltip(
+        string.format(
+          "Aggregate CPU utilization (100%% per logical CPU) · %.0f%% average per CPU",
+          per_cpu_utilization
+        )
+      )
     else
-      barWidget.setText("—")
+      renderStatus("—", "#fff1e6")
       barWidget.setTooltip("Sampling CPU utilization…")
     end
   end)

.local/share/noctalia/plugins/system-status/memory.luau

@@ -8,16 +8,37 @@ $1 == "SwapFree:" { swap_free = $2 }
 END {
   if (!total || !available) exit 1
   used = total - available
+  memory_used = used * 100 / total
   if (swap_total > 0) {
     swap_used = (swap_total - swap_free) * 100 / swap_total
-    printf "RAM %.1f/%.1f GiB  S %.0f%%\n", used / 1048576, total / 1048576, swap_used
+    printf "%.1f/%.1f GiB  S %.0f%%\t%.0f\t%.0f\n", used / 1048576, total / 1048576, swap_used, memory_used, swap_used
   } else {
-    printf "RAM %.1f/%.1f GiB  S —\n", used / 1048576, total / 1048576
+    printf "%.1f/%.1f GiB  S —\t%.0f\t0\n", used / 1048576, total / 1048576, memory_used
   }
 }' /proc/meminfo]]
 
 local request_in_flight = false
 
+local function colorForUsage(percent)
+  if percent >= 85 then
+    return "#ff453a" -- red
+  end
+  if percent >= 70 then
+    return "#ff8800" -- orange
+  end
+  if percent >= 50 then
+    return "#ffd60a" -- yellow
+  end
+  return "#ffffff" -- white
+end
+
+local function renderStatus(text, color)
+  barWidget.render(ui.row({ gap = 4, align = "center" }, {
+    ui.glyph({ name = "memory", size = 14, color = color }),
+    ui.label({ text = text, color = color }),
+  }))
+end
+
 function update()
   noctalia.setUpdateInterval(5000)
 
@@ -30,14 +51,32 @@ function update()
     request_in_flight = false
 
     if result.exitCode ~= 0 then
-      barWidget.setText("RAM —")
+      renderStatus("RAM —", "#fff1e6")
       barWidget.setTooltip("Unable to read /proc/meminfo")
       return
     end
 
-    local text = string.gsub(result.stdout, "%s+$", "")
-    barWidget.setGlyph("memory")
-    barWidget.setText(text)
-    barWidget.setTooltip("RAM used / total · S = swap used")
+    local text, memory_percent, swap_percent = string.match(
+      result.stdout,
+      "^([^\t]+)\t([%d.]+)\t([%d.]+)"
+    )
+    memory_percent = tonumber(memory_percent)
+    swap_percent = tonumber(swap_percent)
+
+    if text == nil or memory_percent == nil or swap_percent == nil then
+      renderStatus("RAM —", "#fff1e6")
+      barWidget.setTooltip("Unable to parse memory utilization")
+      return
+    end
+
+    local highest_usage = math.max(memory_percent, swap_percent)
+    renderStatus(text, colorForUsage(highest_usage))
+    barWidget.setTooltip(
+      string.format(
+        "RAM used / total · %.0f%% RAM · %.0f%% swap",
+        memory_percent,
+        swap_percent
+      )
+    )
   end)
 end

.local/share/noctalia/plugins/system-status/plugin.toml

@@ -3,7 +3,7 @@ name = "System Status"
 version = "1.0.0"
 plugin_api = 3
 author = "alex"
-description = "Low-overhead memory and swap indicator for the bar."
+description = "Low-overhead system and network status indicators for the bar."
 
 [[widget]]
 id = "cpu"
@@ -12,3 +12,15 @@ entry = "cpu.luau"
 [[widget]]
 id = "memory"
 entry = "memory.luau"
+
+[[widget]]
+id = "battery-rate"
+entry = "battery-rate.luau"
+
+[[widget]]
+id = "network-rate"
+entry = "network-rate.luau"
+
+[[widget]]
+id = "gpu-mode"
+entry = "gpu-mode.luau"

.pi/agent/settings.json

@@ -21,8 +21,7 @@
     "npm:gentle-engram",
     "npm:pi-lens",
     "npm:@juicesharp/rpiv-todo",
-    "npm:@majorgilles/pi-grill-me",
-    "git:git.commumedia.org/alex/pi-map"
+    "npm:@majorgilles/pi-grill-me"
   ],
   "powerline": "full",
   "hideThinkingBlock": false,

.tmux.conf

@@ -32,9 +32,12 @@ bind e new-window -n tmux.conf "exec \${EDITOR:-nvim} ~/.tmux.conf"
 
 # --- Vim-style panes ----------------------------------------------------------
 # Keep the familiar split keys and always inherit the active pane's directory.
-bind - split-window -v -c "#{pane_current_path}"
-bind | split-window -h -c "#{pane_current_path}"
+bind m split-window -v -c "#{pane_current_path}"
+bind n split-window -h -c "#{pane_current_path}"
 bind c new-window -c "#{pane_current_path}"
+# Re-tile the current window using Ctrl-a, Ctrl-h / Ctrl-a, Ctrl-k.
+bind C-h select-layout even-vertical
+bind C-k select-layout even-horizontal
 
 bind -r h select-pane -L
 bind -r j select-pane -D
@@ -47,17 +50,17 @@ bind -r L resize-pane -R 5
 bind -r \{ swap-pane -U
 bind -r \} swap-pane -D
 bind z resize-pane -Z
-bind x confirm-before -p "kill pane #P? (y/n)" kill-pane
+bind w confirm-before -p "kill pane #P? (y/n)" kill-pane
 
 # --- Windows, sessions, and buffers ------------------------------------------
-bind -r n next-window
-bind -r p previous-window
+bind -r f next-window
+bind -r b previous-window
 bind Tab last-window
-bind w choose-tree -Zw
+bind d choose-tree -Zw
 bind s choose-tree -Zs
-bind f command-prompt -p "switch to session:" "switch-client -t '%%'"
+bind g command-prompt -p "switch to session:" "switch-client -t '%%'"
 bind [ choose-buffer
-bind ] paste-buffer
+bind P paste-buffer  # tmux buffer fallback; prefix + ] pastes the system clipboard
 bind C-l send-keys C-l \; clear-history
 
 # --- Copy mode ----------------------------------------------------------------
@@ -72,9 +75,12 @@ bind -T copy-mode-vi L send -X end-of-line
 bind -T copy-mode-vi C-u send -X halfpage-up
 bind -T copy-mode-vi C-d send -X halfpage-down
 
-# Prefer a native Wayland clipboard; use xclip elsewhere. set-clipboard keeps
-# OSC 52-capable terminals in sync as well.
-if-shell 'command -v wl-copy >/dev/null 2>&1' 'bind -T copy-mode-vi y send -X copy-pipe-and-cancel "wl-copy"' 'bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -in -selection clipboard"'
+# Keep tmux and the desktop clipboard in sync by default. `set-clipboard on`
+# handles OSC 52-capable terminals; these bindings cover local Wayland/X11.
+# Copy-mode y writes to the system clipboard. Prefix + ] reads it back and
+# pastes it; prefix + P remains available for the most recent tmux buffer.
+bind -T copy-mode-vi y send -X copy-pipe-and-cancel 'if command -v wl-copy >/dev/null 2>&1; then wl-copy; elif command -v xclip >/dev/null 2>&1; then xclip -in -selection clipboard; fi'
+bind ] run-shell 'if command -v wl-paste >/dev/null 2>&1; then wl-paste --no-newline | tmux load-buffer - && tmux paste-buffer; elif command -v xclip >/dev/null 2>&1; then xclip -out -selection clipboard | tmux load-buffer - && tmux paste-buffer; fi'
 
 # --- Status line --------------------------------------------------------------
 set -g status on

README.md

@@ -0,0 +1,58 @@
+# Dotfiles
+
+Personal, Arch-oriented user dotfiles and support scripts for shells, window management, applications, and package lists. This repository is a collection of machine-specific configuration, not a general-purpose installer.
+
+## Status and scope
+
+There is no authoritative root installation, linking, backup, overwrite, or rollback script. Do not infer one: review and apply only the individual files appropriate to a machine. Some filenames use `##class.arch_*` suffixes to distinguish machine classes. The repository also includes a nested README for the custom/vendored `st` terminal under `.config/st/`; it documents that component, not installation of this repository.
+
+Several scripts assume paths below `~/.setup`, Arch tooling, and root access. Some repository scripts contain machine-specific connection details; do not publish, copy, or document such values. Use local, private configuration for hosts, addresses, accounts, and credentials.
+
+## Prerequisites
+
+- An Arch-based system for the supplied `pacman`/`yay` package workflows.
+- The package manager or helper required by the script being considered (`pacman` and/or `yay`).
+- Desktop/session tools matching the chosen configuration (for example X11/XMonad-related files where applicable).
+- Root access only for the system-changing scripts described below.
+
+Package lists in `.setup/packages/` are inputs for a user-managed installation; no repository command defines how to install an entire list. Inspect package names and select lists for the intended machine before installing anything.
+
+## Safe review and user-level configuration
+
+Start by reviewing the intended files and any machine-class variants. Typical areas are:
+
+- `.zshrc`, `.bashrc`, `.terminal_aliases`, `.tmux.conf`, and `.p10k.zsh` — shell and terminal setup.
+- `.xmonad/`, `.Xresources##class.*`, `.xprofile##class.*`, and `.config/` — desktop/window-manager and application configuration.
+- `.scripts/` — optional shell, network, virtual-environment, and update helpers.
+- `.setup/packages/` — package lists grouped by purpose.
+
+Back up existing configuration before manually placing or linking a file. No test suite is provided; validate a change in the relevant shell/session or application and keep a rollback copy of the previous configuration.
+
+## Package updates
+
+`.scripts/updating.sh` defines, but does not invoke, two functions. It expects `~/.setup/packages/exclude_from_updating.list`:
+
+```sh
+source .scripts/updating.sh
+update_system
+# or
+update_pacman_packages
+```
+
+> **Warning: system-wide, potentially disruptive operation.** `update_system` runs `yay -Syu` and `update_pacman_packages` runs `sudo pacman -Syu`, both non-interactively and with the exclusion list. Review the exclusion list and pending package changes first. These functions update the running system; they are not tests.
+
+## System-changing scripts
+
+The following scripts mutate files outside this repository and must be inspected before use:
+
+- `.setup/config/setup_touchpad.sh` copies an X11 configuration into `/etc/X11/xorg.conf.d/` when absent.
+- `.setup/config/exclude_from_update.sh` edits `/etc/pacman.conf` with `sudo` based on `~/.setup/packages/exclude_from_updating.list`.
+- `.setup/config/dinit_add_logs_to_all_services.sh` edits files in `/etc/dinit.d` and writes log specifications under `/var/log/dinit`; its `-o` option removes existing logfile lines before adding them.
+
+> **Warning: destructive/system-wide operations.** These scripts can alter system package policy, service definitions, or input configuration. They have no repository-provided dry run or rollback. Run only on a machine you control after backups and after checking paths, permissions, and the script contents.
+
+`.setup/config/set_default_programs.sh` sets the default HTTP/HTTPS handler through `xdg-mime`; review the desktop entry before using it.
+
+## Custom `st` terminal
+
+The nested `.config/st/README.md` documents its own `make` and `sudo make install` workflow. Those commands build/install only that terminal component, may modify the system, and are not a bootstrap procedure for all dotfiles.