Add the installer, uninstaller, and generated docs

2026-09-20 00:19:38 -04:00
parent 0c422e7345
commit 3e65d176e3
100 changed files with 2585 additions and 0 deletions
@@ -0,0 +1,92 @@
 <div align="center">
  <h1>Blob</h1>
  <p>A self-contained Wayland desktop for Arch Linux.</p>
  <img src="https://img.shields.io/badge/Arch_Linux-1793D1?style=for-the-badge&logo=arch-linux&logoColor=white" alt="Arch Linux" />
  <img src="https://img.shields.io/badge/Hyprland-00A86B?style=for-the-badge&logo=hyprland&logoColor=white" alt="Hyprland" />
  <img src="https://img.shields.io/badge/Quickshell-2A2A2A?style=for-the-badge&logo=qt&logoColor=white" alt="Quickshell" />
 </div>
 ---
 This started as a layer of overrides on top of Omarchy and is now its own
 desktop. It keeps the look, layout, and base functionality that were worth
 keeping, and owns every line that runs. There is no upstream package to track
 and nothing to re-apply after somebody else's release.
 ## What it is
 - **[Hyprland](https://hyprland.org/)** as the compositor, configured in Lua.
 - **[Quickshell](https://quickshell.org/)** as the desktop: `blob-shell` is one
  process hosting the bar, both menus, the panels, notifications, the lock
  screen, and the OSD as plugins.
 - **A `blob-*` CLI** of 251 commands, dispatched by `blob`.
 - **24 themes** with a palette pipeline that retints the terminal, editor,
  browser, shell, and lock screen from one `colors.toml`.
 ## Layout
 | Path | Contents |
 | --- | --- |
 | `bin/` | the `blob-<area>-<verb>` commands |
 | `shell/` | the Quickshell desktop |
 | `hypr/` | personal Hyprland config, deployed to `~/.config/hypr` |
 | `default/` | the shipped defaults the commands and shell resolve: `hypr/` Lua layer, `themed/` templates, `blob/` menu tree |
 | `themes/` | colour themes |
 | `config/` | shipped app configs |
 | `shell.json` | bar layout and idle timings |
 | `hooks/` | event hooks, such as retinting on theme change |
 | `branding/` | icon, ASCII art, boot splash |
 | `wallpapers/` | 103 wallpapers, previewed in [the gallery](wallpaper-gallery/index.md) |
 | `session/` | wayland session entry and uwsm environment |
 | `docs/` | everything below |
 ## Docs
 | Doc | Covers |
 | --- | --- |
 | [commands.md](docs/commands.md) | every command, generated from its own metadata |
 | [keybinds.md](docs/keybinds.md) | every binding, generated from the Lua |
 | [shell.md](docs/shell.md) | shell layout, bar config, plugin model |
 | [themes.md](docs/themes.md) | the palette pipeline and how to add a theme |
 | [widgets.md](docs/widgets.md) | the ported GTK widgets and where they went |
 | [menu.md](docs/menu.md) | the menu tree and what was trimmed |
 | [upstream.md](docs/upstream.md) | the fork base, for diffing later |
 ## Install
 `BLOB_PATH` is a symlink to this checkout, so `bin/`, `shell/`, `themes/` and
 `default/` are always the working tree and edits are live. Only the handful of
 files that must sit under `~/.config` get copied.
 ```bash
 ./install.sh            # link and deploy
 ./install.sh --check    # report what would change, write nothing
 ./install.sh --force    # overwrite files with local changes
 ```
 Then log out and pick the Blob session.
 To back out, `./uninstall.sh` removes the session entry, the config, and the
 symlink, restoring any `.bak` the installer made. The checkout, the wallpapers,
 and the themes stay where they are.
 ## Regenerating docs
 ```bash
 blob-docs-commands
 blob-docs-keybinds
 ```
 ## Keys worth knowing
 | Keys | Action |
 | --- | --- |
 | `Super + Space` | Apps menu |
 | `Super + Alt + Space` | Root menu |
 | `Super + Ctrl + Q` | Quick settings |
 | `Super + Ctrl + M` | System monitor |
 | `Super + Alt + W` | Wallpaper picker |
 | `Super + Ctrl + L` | Lock |
 The rest are in [keybinds.md](docs/keybinds.md), or run `blob menu keybindings`.
@@ -0,0 +1,62 @@
 #!/bin/bash
 # blob:summary=Regenerate docs/commands.md from each command's own metadata
 # blob:hidden=true
 set -e
 bin_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 repo_dir="$(dirname "$bin_dir")"
 output="$repo_dir/docs/commands.md"
 metadata() {
  sed -n "s/^# blob:$2=//p" "$1" | head -1
 }
 area_of() {
  local name="${1#blob-}"
  printf '%s\n' "${name%%-*}"
 }
 {
  echo "# Commands"
  echo
  echo "Generated by \`blob-docs-commands\` from the \`# blob:summary=\` line in each"
  echo "file. Do not edit by hand."
  echo
  echo "Commands marked hidden are plumbing other commands call, and are left out"
  echo "of the \`blob\` listing."
  echo
  current_area=""
  for file in "$bin_dir"/blob-*; do
    [[ -f $file ]] || continue
    name="$(basename "$file")"
    area="$(area_of "$name")"
    if [[ $area != "$current_area" ]]; then
      echo
      echo "## $area"
      echo
      echo "| Command | Does | Arguments |"
      echo "| --- | --- | --- |"
      current_area="$area"
    fi
    summary="$(metadata "$file" summary)"
    args="$(metadata "$file" args)"
    [[ -n $summary ]] || summary="-"
    [[ -n $args ]] || args="-"
    if grep -q '^# blob:hidden=true' "$file"; then
      summary="$summary (hidden)"
    fi
    printf '| `%s` | %s | %s |\n' "$name" "$summary" "${args//|/\\|}"
  done
  echo
  echo "## Totals"
  echo
  printf '%s commands.\n' "$(ls "$bin_dir"/blob-* | wc -l)"
 } > "$output"
 echo "Wrote $output"
@@ -0,0 +1,60 @@
 #!/bin/bash
 # blob:summary=Regenerate docs/keybinds.md from the Hyprland Lua bindings
 # blob:hidden=true
 set -e
 bin_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 repo_dir="$(dirname "$bin_dir")"
 output="$repo_dir/docs/keybinds.md"
 # o.bind("KEYS", "Description", ...) and o.bind_toggle("KEYS", "Description", ...)
 # are the only two forms the Lua layer uses to declare a binding.
 collect() {
  local file="$1"
  grep -ohE 'o\.bind(_toggle)?\(\s*"[^"]+",\s*"[^"]+"' "$file" 2>/dev/null |
    sed -E 's/o\.bind(_toggle)?\(\s*"([^"]+)",\s*"([^"]+)"/\2\t\3/'
 }
 section() {
  local title="$1"
  shift
  local rows
  rows="$(for file in "$@"; do collect "$file"; done | sort -u -t$'\t' -k1,1)"
  [[ -n $rows ]] || return 0
  echo
  echo "## $title"
  echo
  echo "| Keys | Action |"
  echo "| --- | --- |"
  printf '%s\n' "$rows" | while IFS=$'\t' read -r keys action; do
    printf '| `%s` | %s |\n' "$keys" "$action"
  done
 }
 {
  echo "# Keybindings"
  echo
  echo "Generated by \`blob-docs-keybinds\` from the \`o.bind\` calls in the Hyprland"
  echo "Lua files. Do not edit by hand."
  echo
  echo "Personal overrides in \`hypr/bindings.lua\` win over the defaults, and"
  echo "\`hl.unbind\` in that file removes a default outright."
  section "Personal" "$repo_dir/hypr/bindings.lua"
  section "Applications" "$repo_dir/default/hypr/bindings/applications.lua"
  section "Tiling" "$repo_dir/default/hypr/bindings/tiling.lua"
  section "Media" "$repo_dir/default/hypr/bindings/media.lua"
  section "Clipboard" "$repo_dir/default/hypr/bindings/clipboard.lua"
  section "Utilities" "$repo_dir/default/hypr/bindings/utilities.lua"
  echo
  echo "## Unbound defaults"
  echo
  grep -ohE 'hl\.unbind\("[^"]+"\)' "$repo_dir/hypr/bindings.lua" 2>/dev/null |
    sed -E 's/hl\.unbind\("([^"]+)"\)/- `\1`/' || echo "None."
 } > "$output"
 echo "Wrote $output"
@@ -0,0 +1,61 @@
 #!/bin/bash
 # blob:summary=Monitor sleep preparation and lock before suspend
 # blob:group=system
 # blob:hidden=true
 consume_sleep_events() {
  local line sleep_lock
  sleep_lock="$BLOB_PATH/bin/blob-system-sleep"
  while IFS= read -r line; do
    if [[ $line == *"boolean true"* ]]; then
      "$sleep_lock"
      return 0
    fi
  done
 }
 monitor_sleep_events() {
  local monitor_fd monitor_pid status
  coproc SLEEP_EVENTS {
    exec dbus-monitor --system \
      "type='signal',sender='org.freedesktop.login1',interface='org.freedesktop.login1.Manager',member='PrepareForSleep'"
  }
  monitor_fd=${SLEEP_EVENTS[0]}
  monitor_pid=$SLEEP_EVENTS_PID
  cleanup_monitor() {
    kill "$monitor_pid" 2>/dev/null || true
    wait "$monitor_pid" 2>/dev/null || true
  }
  trap cleanup_monitor EXIT
  consume_sleep_events <&"$monitor_fd"
  status=$?
  cleanup_monitor
  trap - EXIT
  return "$status"
 }
 case ${1:-} in
  --consume)
    consume_sleep_events
    exit 0
    ;;
  --inhibited)
    monitor_sleep_events
    exit 0
    ;;
 esac
 sleep_monitor="$BLOB_PATH/bin/blob-system-sleep-monitor"
 exec systemd-inhibit \
  --what=sleep \
  --mode=delay \
  --who=Blob \
  --why="Lock screen before suspend" \
  "$sleep_monitor" --inhibited
@@ -0,0 +1,272 @@
 #? Config file for btop v.1.4.6
 #* Name of a btop++/bpytop/bashtop formatted ".theme" file, "Default" and "TTY" for builtin themes.
 #* Themes should be placed in "../share/btop/themes" relative to binary or "$HOME/.config/btop/themes"
 color_theme = "current"
 #* If the theme set background should be shown, set to False if you want terminal background transparency.
 theme_background = true
 #* Sets if 24-bit truecolor should be used, will convert 24-bit colors to 256 color (6x6x6 color cube) if false.
 truecolor = true
 #* Set to true to force tty mode regardless if a real tty has been detected or not.
 #* Will force 16-color mode and TTY theme, set all graph symbols to "tty" and swap out other non tty friendly symbols.
 force_tty = false
 #* Define presets for the layout of the boxes. Preset 0 is always all boxes shown with default settings. Max 9 presets.
 #* Format: "box_name:P:G,box_name:P:G" P=(0 or 1) for alternate positions, G=graph symbol to use for box.
 #* Use whitespace " " as separator between different presets.
 #* Example: "cpu:0:default,mem:0:tty,proc:1:default cpu:0:braille,proc:0:tty"
 presets = "cpu:1:default,proc:0:default cpu:0:default,mem:0:default,net:0:default cpu:0:block,net:0:tty"
 #* Set to True to enable "h,j,k,l,g,G" keys for directional control in lists.
 #* Conflicting keys for h:"help" and k:"kill" is accessible while holding shift.
 vim_keys = true
 #* Rounded corners on boxes, is ignored if TTY mode is ON.
 rounded_corners = true
 #* Use terminal synchronized output sequences to reduce flickering on supported terminals.
 terminal_sync = true
 #* Default symbols to use for graph creation, "braille", "block" or "tty".
 #* "braille" offers the highest resolution but might not be included in all fonts.
 #* "block" has half the resolution of braille but uses more common characters.
 #* "tty" uses only 3 different symbols but will work with most fonts and should work in a real TTY.
 #* Note that "tty" only has half the horizontal resolution of the other two, so will show a shorter historical view.
 graph_symbol = "braille"
 # Graph symbol to use for graphs in cpu box, "default", "braille", "block" or "tty".
 graph_symbol_cpu = "default"
 # Graph symbol to use for graphs in gpu box, "default", "braille", "block" or "tty".
 graph_symbol_gpu = "default"
 # Graph symbol to use for graphs in cpu box, "default", "braille", "block" or "tty".
 graph_symbol_mem = "default"
 # Graph symbol to use for graphs in cpu box, "default", "braille", "block" or "tty".
 graph_symbol_net = "default"
 # Graph symbol to use for graphs in cpu box, "default", "braille", "block" or "tty".
 graph_symbol_proc = "default"
 #* Manually set which boxes to show. Available values are "cpu mem net proc" and "gpu0" through "gpu5", separate values with whitespace.
 shown_boxes = "cpu mem net proc"
 #* Update time in milliseconds, recommended 2000 ms or above for better sample times for graphs.
 update_ms = 2000
 #* Processes sorting, "pid" "program" "arguments" "threads" "user" "memory" "cpu lazy" "cpu direct",
 #* "cpu lazy" sorts top process over time (easier to follow), "cpu direct" updates top process directly.
 proc_sorting = "cpu lazy"
 #* Reverse sorting order, True or False.
 proc_reversed = false
 #* Show processes as a tree.
 proc_tree = false
 #* Use the cpu graph colors in the process list.
 proc_colors = true
 #* Use a darkening gradient in the process list.
 proc_gradient = true
 #* If process cpu usage should be of the core it's running on or usage of the total available cpu power.
 proc_per_core = false
 #* Show process memory as bytes instead of percent.
 proc_mem_bytes = true
 #* Show cpu graph for each process.
 proc_cpu_graphs = true
 #* Use /proc/[pid]/smaps for memory information in the process info box (very slow but more accurate)
 proc_info_smaps = false
 #* Show proc box on left side of screen instead of right.
 proc_left = false
 #* (Linux) Filter processes tied to the Linux kernel(similar behavior to htop).
 proc_filter_kernel = false
 #* In tree-view, always accumulate child process resources in the parent process.
 proc_aggregate = false
 #* Should cpu and memory usage display be preserved for dead processes when paused.
 keep_dead_proc_usage = false
 #* Sets the CPU stat shown in upper half of the CPU graph, "total" is always available.
 #* Select from a list of detected attributes from the options menu.
 cpu_graph_upper = "Auto"
 #* Sets the CPU stat shown in lower half of the CPU graph, "total" is always available.
 #* Select from a list of detected attributes from the options menu.
 cpu_graph_lower = "Auto"
 #* If gpu info should be shown in the cpu box. Available values = "Auto", "On" and "Off".
 show_gpu_info = "Auto"
 #* Toggles if the lower CPU graph should be inverted.
 cpu_invert_lower = true
 #* Set to True to completely disable the lower CPU graph.
 cpu_single_graph = false
 #* Show cpu box at bottom of screen instead of top.
 cpu_bottom = false
 #* Shows the system uptime in the CPU box.
 show_uptime = true
 #* Shows the CPU package current power consumption in watts. Requires running `make setcap` or `make setuid` or running with sudo.
 show_cpu_watts = true
 #* Show cpu temperature.
 check_temp = true
 #* Which sensor to use for cpu temperature, use options menu to select from list of available sensors.
 cpu_sensor = "Auto"
 #* Show temperatures for cpu cores also if check_temp is True and sensors has been found.
 show_coretemp = true
 #* Set a custom mapping between core and coretemp, can be needed on certain cpus to get correct temperature for correct core.
 #* Use lm-sensors or similar to see which cores are reporting temperatures on your machine.
 #* Format "x:y" x=core with wrong temp, y=core with correct temp, use space as separator between multiple entries.
 #* Example: "4:0 5:1 6:3"
 cpu_core_map = ""
 #* Which temperature scale to use, available values: "celsius", "fahrenheit", "kelvin" and "rankine".
 temp_scale = "celsius"
 #* Use base 10 for bits/bytes sizes, KB = 1000 instead of KiB = 1024.
 base_10_sizes = false
 #* Show CPU frequency.
 show_cpu_freq = true
 #* How to calculate CPU frequency, available values: "first", "range", "lowest", "highest" and "average".
 freq_mode = "first"
 #* Draw a clock at top of screen, formatting according to strftime, empty string to disable.
 #* Special formatting: /host = hostname | /user = username | /uptime = system uptime
 clock_format = "%X"
 #* Update main ui in background when menus are showing, set this to false if the menus is flickering too much for comfort.
 background_update = true
 #* Custom cpu model name, empty string to disable.
 custom_cpu_name = ""
 #* Optional filter for shown disks, should be full path of a mountpoint, separate multiple values with whitespace " ".
 #* Only disks matching the filter will be shown. Prepend exclude= to only show disks not matching the filter. Examples: disk_filter="/boot /home/user", disks_filter="exclude=/boot /home/user"
 disks_filter = ""
 #* Show graphs instead of meters for memory values.
 mem_graphs = true
 #* Show mem box below net box instead of above.
 mem_below_net = false
 #* Count ZFS ARC in cached and available memory.
 zfs_arc_cached = true
 #* If swap memory should be shown in memory box.
 show_swap = true
 #* Show swap as a disk, ignores show_swap value above, inserts itself after first disk.
 swap_disk = true
 #* If mem box should be split to also show disks info.
 show_disks = true
 #* Filter out non physical disks. Set this to False to include network disks, RAM disks and similar.
 only_physical = true
 #* Read disks list from /etc/fstab. This also disables only_physical.
 use_fstab = true
 #* Setting this to True will hide all datasets, and only show ZFS pools. (IO stats will be calculated per-pool)
 zfs_hide_datasets = false
 #* Set to true to show available disk space for privileged users.
 disk_free_priv = false
 #* Toggles if io activity % (disk busy time) should be shown in regular disk usage view.
 show_io_stat = true
 #* Toggles io mode for disks, showing big graphs for disk read/write speeds.
 io_mode = false
 #* Set to True to show combined read/write io graphs in io mode.
 io_graph_combined = false
 #* Set the top speed for the io graphs in MiB/s (100 by default), use format "mountpoint:speed" separate disks with whitespace " ".
 #* Example: "/mnt/media:100 /:20 /boot:1".
 io_graph_speeds = ""
 #* Set fixed values for network graphs in Mebibits. Is only used if net_auto is also set to False.
 net_download = 100
 net_upload = 100
 #* Use network graphs auto rescaling mode, ignores any values set above and rescales down to 10 Kibibytes at the lowest.
 net_auto = true
 #* Sync the auto scaling for download and upload to whichever currently has the highest scale.
 net_sync = true
 #* Starts with the Network Interface specified here.
 net_iface = ""
 #* "True" shows bitrates in base 10 (Kbps, Mbps). "False" shows bitrates in binary sizes (Kibps, Mibps, etc.). "Auto" uses base_10_sizes.
 base_10_bitrate = "Auto"
 #* Show battery stats in top right if battery is present.
 show_battery = true
 #* Which battery to use if multiple are present. "Auto" for auto detection.
 selected_battery = "Auto"
 #* Show power stats of battery next to charge indicator.
 show_battery_watts = true
 #* Set loglevel for "~/.local/state/btop.log" levels are: "ERROR" "WARNING" "INFO" "DEBUG".
 #* The level set includes all lower levels, i.e. "DEBUG" will show all logging info.
 log_level = "WARNING"
 #* Automatically save current settings to config file on exit.
 save_config_on_exit = true
 #* Measure PCIe throughput on NVIDIA cards, may impact performance on certain cards.
 nvml_measure_pcie_speeds = true
 #* Measure PCIe throughput on AMD cards, may impact performance on certain cards.
 rsmi_measure_pcie_speeds = true
 #* Horizontally mirror the GPU graph.
 gpu_mirror_graph = true
 #* Set which GPU vendors to show. Available values are "nvidia amd intel"
 shown_gpus = "nvidia amd intel"
 #* Custom gpu0 model name, empty string to disable.
 custom_gpu_name0 = ""
 #* Custom gpu1 model name, empty string to disable.
 custom_gpu_name1 = ""
 #* Custom gpu2 model name, empty string to disable.
 custom_gpu_name2 = ""
 #* Custom gpu3 model name, empty string to disable.
 custom_gpu_name3 = ""
 #* Custom gpu4 model name, empty string to disable.
 custom_gpu_name4 = ""
 #* Custom gpu5 model name, empty string to disable.
 custom_gpu_name5 = ""
@@ -0,0 +1,26 @@
 [main]
 include=~/.local/state/blob/current/theme/foot.ini
 term=xterm-256color
 font=JetBrainsMono Nerd Font:size=9
 pad=14x14
 initial-window-mode=windowed
 workers=0
 [scrollback]
 lines=10000
 multiplier=7.0
 [cursor]
 style=block
 blink=no
 [key-bindings]
 clipboard-copy=Control+Insert Control+Shift+c XF86Copy
 primary-paste=none
 clipboard-paste=Shift+Insert Control+Shift+v XF86Paste
 [text-bindings]
 # Send Shift+Return as CSI-u so TUIs can distinguish it from Return.
 \x1b[13;2u=Shift+Return
 # Send Alt+Shift+Return as CSI-u so tmux can match M-S-Enter.
 \x1b[13;4u=Mod1+Shift+Return
@@ -0,0 +1,28 @@
 # See https://git-scm.com/docs/git-config
 [alias]
 	co = checkout
 	br = branch
 	ci = commit
 	st = status
 [init]
 	defaultBranch = master
 [pull]
 	rebase = true 			 # Rebase (instead of merge) on pull
 [push]
 	autoSetupRemote = true   # Automatically set upstream branch on push
 [diff]
 	algorithm = histogram    # Clearer diffs on moved/edited lines
 	colorMoved = plain       # Highlight moved blocks in diffs
 	mnemonicPrefix = true    # More intuitive refs in diff output
 [commit]
 	verbose = true           # Include diff comment in commit message template
 [column]
 	ui = auto 			     # Output in columns when possible
 [branch]
 	sort = -committerdate    # Sort branches by most recent commit first
 [tag]
 	sort = -version:refname  # Sort version numbers as you would expect
 [rerere]
 	enabled = true           # Record and reuse conflict resolutions
 	autoupdate = true        # Apply stored conflict resolutions automatically
@@ -0,0 +1,2 @@
 -- Extra autostart processes.
 -- o.launch_on_start("my-service")
@@ -0,0 +1,29 @@
 -- Keep only your personal keybinding overrides here. Add new bindings or
 -- unbind defaults before replacing them.
 -- See current bindings and descriptions:
 --   blob menu keybindings --print
 -- To disable every Blob default binding, set this in
 -- ~/.config/hypr/hyprland.lua before require("default.hypr.blob"), then add
 -- only the bindings you want below:
 --   blob_default_bindings = false
 -- To disable all preinstalled app/webapp bindings, set:
 --   blob_preinstalled_bindings = false
 -- Add a new binding.
 -- o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
 -- Change an existing binding by unbinding it first, then binding the key again.
 -- This example changes SUPER+SPACE from the launcher to the Blob root menu.
 -- hl.unbind("SUPER + SPACE")
 -- o.bind("SUPER + SPACE", "Blob menu", "blob-menu toggle root")
 -- Disable a default binding without replacing it.
 -- hl.unbind("SUPER + SHIFT + B")
 -- Logitech MX Keys examples:
 -- o.bind("SUPER + SHIFT + S", nil, "blob-capture-screenshot")
 -- o.bind("SUPER + H", nil, "voxtype record toggle")
 -- o.bind("SUPER + PERIOD", nil, "blob-shell shell toggle blob.emojis")
@@ -0,0 +1,29 @@
 -- Learn how to configure Hyprland: https://wiki.hypr.land/Configuring/Start/
 -- Blob's bootstrap keeps path setup out of this user config.
 dofile((os.getenv("BLOB_PATH") or "$HOME/.local/share/blob") .. "/default/hypr/bootstrap.lua")
 -- Disable all Blob default bindings. Add your own in hypr/bindings.lua.
 -- blob_default_bindings = false
 --
 -- Or disable only bindings for Blob's preinstalled apps/web apps while
 -- keeping core window-manager bindings:
 -- blob_preinstalled_bindings = false
 -- Load Blob defaults.
 require("default.hypr.blob")
 -- Put your personal overrides in these files. They're loaded after Blob's
 -- defaults so package updates can improve the defaults without rewriting your
 -- ~/.config/hypr files.
 require("hypr.monitors")
 require("hypr.input")
 require("hypr.bindings")
 require("hypr.looknfeel")
 require("hypr.autostart")
 -- Toggle config flags dynamically.
 require("default.hypr.toggles")
 -- Add any other personal Hyprland configuration below.
 -- o.window("qemu", { workspace = "5" })
@@ -0,0 +1,14 @@
 # Makes hyprsunset do nothing to the screen by default
 # Without this, the default applies some tint to the monitor
 profile {
    time = 07:00
    identity = true
 }
 # To enable auto switch to nightlight, add to your .config/hypr/autostart.lua:
 # o.launch_on_start("hyprsunset")
 # and use the following:
 # profile {
 #     time = 20:00
 #     temperature = 4000
 # }
@@ -0,0 +1,57 @@
 -- Keep only your personal input overrides here. Uncommented settings below
 -- replace Blob's defaults.
 -- Keyboard layout and options.
 -- See https://wiki.hypr.land/Configuring/Basics/Variables/#input
 -- hl.config({
 --   input = {
 --     -- Use multiple keyboard layouts and switch between them with Left Alt + Right Alt.
 --     kb_layout = "us,dk,eu",
 --     kb_options = "compose:caps,shift:both_capslock_cancel,grp:alts_toggle",
 --
 --     -- Use a specific keyboard variant if needed (e.g. intl for international keyboards).
 --     kb_variant = "intl",
 --
 --     -- Change speed of keyboard repeat.
 --     repeat_rate = 40,
 --     repeat_delay = 250,
 --
 --     -- Start with numlock on by default.
 --     numlock_by_default = true,
 --
 --     -- Increase sensitivity for mouse/trackpad (default: 0).
 --     sensitivity = 0.35,
 --
 --     -- Turn off mouse acceleration (default: adaptive).
 --     accel_profile = "flat",
 --
 --     touchpad = {
 --       -- Use natural (inverse) scrolling.
 --       natural_scroll = true,
 --
 --       -- Use two-finger clicks for right-click instead of lower-right corner.
 --       clickfinger_behavior = true,
 --
 --       -- Control the speed of your scrolling.
 --       scroll_factor = 0.4,
 --
 --       -- Enable the touchpad while typing.
 --       disable_while_typing = false,
 --
 --       -- Left-click-and-drag with three fingers.
 --       drag_3fg = 1,
 --     },
 --   },
 -- })
 -- App-specific touchpad scroll speeds.
 -- o.window("(Alacritty|kitty|foot)", { scroll_touchpad = 1.5 })
 -- o.window("com.mitchellh.ghostty", { scroll_touchpad = 0.2 })
 -- Enable touchpad gestures for changing workspaces.
 -- See https://wiki.hypr.land/Configuring/Advanced-and-Cool/Gestures/
 -- hl.gesture({ fingers = 3, direction = "horizontal", action = "workspace" })
 -- Enable touchpad gestures for moving focus (helpful on scrolling layout).
 -- hl.gesture({ fingers = 3, direction = "left", action = function() hl.dispatch(hl.dsp.focus({ direction = "l" })) end })
 -- hl.gesture({ fingers = 3, direction = "right", action = function() hl.dispatch(hl.dsp.focus({ direction = "r" })) end })
@@ -0,0 +1,50 @@
 -- Change the default Blob look'n'feel.
 -- https://wiki.hypr.land/Configuring/Basics/Variables/#general
 -- hl.config({
 --   general = {
 --     -- No gaps between windows or borders.
 --     gaps_in = 0,
 --     gaps_out = 0,
 --     border_size = 0,
 --
 --     -- Change to niri-like side-scrolling layout.
 --     layout = "scrolling",
 --   },
 -- })
 -- https://wiki.hypr.land/Configuring/Basics/Variables/#decoration
 -- hl.config({
 --   decoration = {
 --     -- Use round window corners.
 --     rounding = 8,
 --
 --     -- Dim unfocused windows (0.0 = no dim, 1.0 = fully dimmed).
 --     dim_inactive = true,
 --     dim_strength = 0.15,
 --   },
 -- })
 -- https://wiki.hypr.land/Configuring/Basics/Variables/#animations
 -- hl.config({
 --   animations = {
 --     -- Disable all animations.
 --     enabled = false,
 --   },
 -- })
 -- https://wiki.hypr.land/Configuring/Basics/Variables/#layout
 -- hl.config({
 --   layout = {
 --     -- Avoid overly wide single-window layouts on wide screens.
 --     single_window_aspect_ratio = { 1, 1 },
 --   },
 -- })
 -- https://wiki.hypr.land/Configuring/Layouts/Scrolling-Layout/
 -- hl.config({
 --   scrolling = {
 --     -- See only one column per screen instead of two.
 --     column_width = 0.97,
 --   },
 -- })
@@ -0,0 +1,14 @@
 -- See https://wiki.hypr.land/Configuring/Basics/Monitors/
 -- List current monitors and supported resolutions with: hyprctl monitors all
 local blob_gdk_scale = 2
 local blob_monitor_scale = "auto"
 hl.env("GDK_SCALE", tostring(blob_gdk_scale))
 hl.monitor({ output = "", mode = "preferred", position = "auto", scale = blob_monitor_scale })
 -- Configure a specific monitor.
 -- hl.monitor({ output = "DP-2", mode = "2560x1440@144", position = "0x0", scale = 1 })
 -- Portrait/rotated secondary monitor (transform: 1 = 90°, 3 = 270°).
 -- hl.monitor({ output = "DP-2", mode = "preferred", position = "auto", scale = 1, transform = 1 })
@@ -0,0 +1,4 @@
 screencopy {
    allow_token_by_default = true
    custom_picker_binary = hyprland-preview-share-picker
 }
@@ -0,0 +1,16 @@
 [binds]
 # Print the current image file
 <Ctrl+p> = exec lp "$imv_current_file"
 # Trash the current image and quit the viewer (recoverable from Trash)
 <Ctrl+x> = exec gio trash -- "$imv_current_file"; quit
 # Trash the current image and move to the next one
 <Ctrl+Shift+X> = exec gio trash -- "$imv_current_file"; close
 # Rotate the currently open image by 90 degrees
 <Ctrl+r> = exec mogrify -rotate 90 "$imv_current_file"
 # Edit the current image in Tensaku and quit the viewer
 <Ctrl+e> = exec tensaku-edit "$imv_current_file" & ; quit
@@ -0,0 +1,32 @@
 add_newline = true
 command_timeout = 200
 format = "[$directory$git_branch$git_status]($style)$character"
 [character]
 error_symbol = "[✗](bold cyan)"
 success_symbol = "[❯](bold cyan)"
 [directory]
 truncation_length = 2
 truncation_symbol = "…/"
 repo_root_style = "bold cyan"
 repo_root_format = "[$repo_root]($repo_root_style)[$path]($style)[$read_only]($read_only_style) "
 [git_branch]
 format = "[$branch]($style) "
 style = "italic cyan"
 [git_status]
 format     = '[$all_status]($style)'
 style      = "cyan"
 ahead      = "⇡${count} "
 diverged   = "⇕⇡${ahead_count}⇣${behind_count} "
 behind     = "⇣${count} "
 conflicted = " "
 up_to_date = " "
 untracked  = "? "
 modified   = " "
 stashed    = ""
 staged     = ""
 renamed    = ""
 deleted    = ""
@@ -0,0 +1,40 @@
 # Host config for the Blob speaker tuning.
 #
 # This exists so the tuning gets its own PipeWire client rather than sharing
 # PipeWire's stock filter-chain.conf. That config merges every fragment in
 # ~/.config/pipewire/filter-chain.conf.d/, so hosting the tuning there would load
 # any unrelated filter a user keeps in that directory -- duplicating filters
 # already hosted elsewhere, and stopping them all when the tuning is switched off.
 #
 # Installed as ~/.config/pipewire/blob-speaker-tuning.conf with the tuning
 # graph merged from blob-speaker-tuning.conf.d/, and run with
 #   pipewire -c blob-speaker-tuning.conf
 #
 # The contents are the minimum a filter-hosting client needs, taken from
 # /usr/share/pipewire/filter-chain.conf.
 context.properties = {
    log.level = 0
 }
 context.spa-libs = {
    audio.convert.* = audioconvert/libspa-audioconvert
    support.*       = support/libspa-support
 }
 context.modules = [
    # Boost the audio thread priority.
    { name = libpipewire-module-rt
        args = { }
        flags = [ ifexists nofail ]
    }
    # The native communication protocol.
    { name = libpipewire-module-protocol-native }
    # Lets this process provide nodes to PipeWire.
    { name = libpipewire-module-client-node }
    # Wraps nodes in an adapter with a converter and resampler.
    { name = libpipewire-module-adapter }
 ]
@@ -0,0 +1,140 @@
 # Dell XPS 14 / XPS 16 (2026) speaker tuning.
 #
 # Biquad chain fitted to the measured response of the xps-audio-linux EasyEffects
 # profile under a dense pink-weighted multitone of 104 bin-aligned tones,
 # followed by a lookahead limiter. Measures 1.24 dB RMS against that reference
 # (0.97 dB weighted over the fit's own error metric).
 #
 # Fitted and measured on the XPS 14 (SKU 0DB9); the XPS 16 (0DBA) is covered on
 # report that the same profile suits it. See tuning.conf.
 #
 # Q below 200 Hz is capped at 1.8 on purpose. A closer magnitude fit is possible
 # with high-Q sections, but the reference produces its narrow bass features by
 # convolution, and reproducing them with high-Q biquads swung group delay 31 ms
 # across 63-80 Hz, which smears bass transients. The cap costs 0.33 dB and
 # halves the swing.
 #
 # This is a plain filter-chain sink rather than a WirePlumber smart filter. A
 # smart filter is the better shape -- it would leave the real device as the
 # default output instead of adding a second one -- but on PipeWire 1.6.8 /
 # WirePlumber 0.5.15 this graph loads and links correctly as a smart filter and
 # then passes audio through unprocessed: its controls are present and
 # mpv -> filter -> sink links are made, yet the filter's input monitor and the
 # speaker sink's monitor measure identically. Revisit when that is understood.
 #
 # Channels are wired explicitly because the limiter is a stereo plugin; a mono
 # graph is duplicated per channel and would limit each side independently,
 # shifting the stereo image on bass transients.
 context.modules = [
  { name = libpipewire-module-filter-chain
    args = {
      node.description = "Laptop Speakers"
      media.name       = "Laptop Speakers"
      filter.graph = {
        nodes = [
          { type = builtin name = s0_l      label = bq_highpass  control = { "Freq" = 60.9 "Q" = 1.0 } }
          { type = builtin name = s1_l      label = bq_highpass  control = { "Freq" = 60.9 "Q" = 1.0 } }
          { type = builtin name = s2_l      label = bq_peaking   control = { "Freq" = 83.4 "Q" = 1.8 "Gain" = -8.0 } }
          { type = builtin name = s3_l      label = bq_peaking   control = { "Freq" = 100.4 "Q" = 1.59 "Gain" = 7.47 } }
          { type = builtin name = s4_l      label = bq_peaking   control = { "Freq" = 250.5 "Q" = 2.966 "Gain" = -4.7 } }
          { type = builtin name = s5_l      label = bq_peaking   control = { "Freq" = 419.8 "Q" = 3.0 "Gain" = -5.83 } }
          { type = builtin name = s6_l      label = bq_peaking   control = { "Freq" = 631.3 "Q" = 2.515 "Gain" = -10.33 } }
          { type = builtin name = s7_l      label = bq_peaking   control = { "Freq" = 894.4 "Q" = 4.0 "Gain" = -2.42 } }
          { type = builtin name = s8_l      label = bq_peaking   control = { "Freq" = 1355.7 "Q" = 2.884 "Gain" = 6.92 } }
          { type = builtin name = s9_l      label = bq_peaking   control = { "Freq" = 1707.2 "Q" = 1.311 "Gain" = -6.54 } }
          { type = builtin name = s10_l     label = bq_peaking   control = { "Freq" = 3100.0 "Q" = 0.5 "Gain" = -10.09 } }
          { type = builtin name = s11_l     label = bq_peaking   control = { "Freq" = 3200.0 "Q" = 1.048 "Gain" = 3.09 } }
          { type = builtin name = s12_l     label = bq_highshelf control = { "Freq" = 6015.2 "Q" = 1.5 "Gain" = -1.34 } }
          { type = builtin name = s0_r      label = bq_highpass  control = { "Freq" = 60.9 "Q" = 1.0 } }
          { type = builtin name = s1_r      label = bq_highpass  control = { "Freq" = 60.9 "Q" = 1.0 } }
          { type = builtin name = s2_r      label = bq_peaking   control = { "Freq" = 83.4 "Q" = 1.8 "Gain" = -8.0 } }
          { type = builtin name = s3_r      label = bq_peaking   control = { "Freq" = 100.4 "Q" = 1.59 "Gain" = 7.47 } }
          { type = builtin name = s4_r      label = bq_peaking   control = { "Freq" = 250.5 "Q" = 2.966 "Gain" = -4.7 } }
          { type = builtin name = s5_r      label = bq_peaking   control = { "Freq" = 419.8 "Q" = 3.0 "Gain" = -5.83 } }
          { type = builtin name = s6_r      label = bq_peaking   control = { "Freq" = 631.3 "Q" = 2.515 "Gain" = -10.33 } }
          { type = builtin name = s7_r      label = bq_peaking   control = { "Freq" = 894.4 "Q" = 4.0 "Gain" = -2.42 } }
          { type = builtin name = s8_r      label = bq_peaking   control = { "Freq" = 1355.7 "Q" = 2.884 "Gain" = 6.92 } }
          { type = builtin name = s9_r      label = bq_peaking   control = { "Freq" = 1707.2 "Q" = 1.311 "Gain" = -6.54 } }
          { type = builtin name = s10_r     label = bq_peaking   control = { "Freq" = 3100.0 "Q" = 0.5 "Gain" = -10.09 } }
          { type = builtin name = s11_r     label = bq_peaking   control = { "Freq" = 3200.0 "Q" = 1.048 "Gain" = 3.09 } }
          { type = builtin name = s12_r     label = bq_highshelf control = { "Freq" = 6015.2 "Q" = 1.5 "Gain" = -1.34 } }
          { type   = lv2
            name   = limiter
            plugin = "http://lsp-plug.in/plugins/lv2/limiter_stereo"
            control = {
              # Both default to enabled: "alr" regulates level toward the
              # threshold and "boost" normalises the threshold up to full
              # scale. A fixed tuning must switch them off or its tone drifts
              # with programme level.
              "alr"   = 0
              "boost" = 0
              "g_in"  = 0.5456
              "th"    = 0.891
            }
          }
        ]
        links = [
          { output = "s0_l:Out" input = "s1_l:In" }
          { output = "s1_l:Out" input = "s2_l:In" }
          { output = "s2_l:Out" input = "s3_l:In" }
          { output = "s3_l:Out" input = "s4_l:In" }
          { output = "s4_l:Out" input = "s5_l:In" }
          { output = "s5_l:Out" input = "s6_l:In" }
          { output = "s6_l:Out" input = "s7_l:In" }
          { output = "s7_l:Out" input = "s8_l:In" }
          { output = "s8_l:Out" input = "s9_l:In" }
          { output = "s9_l:Out" input = "s10_l:In" }
          { output = "s10_l:Out" input = "s11_l:In" }
          { output = "s11_l:Out" input = "s12_l:In" }
          { output = "s12_l:Out" input = "limiter:in_l" }
          { output = "s0_r:Out" input = "s1_r:In" }
          { output = "s1_r:Out" input = "s2_r:In" }
          { output = "s2_r:Out" input = "s3_r:In" }
          { output = "s3_r:Out" input = "s4_r:In" }
          { output = "s4_r:Out" input = "s5_r:In" }
          { output = "s5_r:Out" input = "s6_r:In" }
          { output = "s6_r:Out" input = "s7_r:In" }
          { output = "s7_r:Out" input = "s8_r:In" }
          { output = "s8_r:Out" input = "s9_r:In" }
          { output = "s9_r:Out" input = "s10_r:In" }
          { output = "s10_r:Out" input = "s11_r:In" }
          { output = "s11_r:Out" input = "s12_r:In" }
          { output = "s12_r:Out" input = "limiter:in_r" }
        ]
        inputs  = [ "s0_l:In" "s0_r:In" ]
        outputs = [ "limiter:out_l" "limiter:out_r" ]
      }
      audio.channels = 2
      audio.position = [ FL FR ]
      capture.props = {
        node.name   = "blob_speaker_tuning"
        media.class = Audio/Sink
      }
      playback.props = {
        node.name     = "blob_speaker_tuning_output"
        node.passive  = true
        target.object = "@SPEAKER_SINK@"
        # This stream is the filter's output and is a movable sink input like any
        # other, so anything that reroutes "all streams" to a newly selected
        # output would drag the processing along with it -- onto headphones, or
        # into the tuning's own sink, which is a cycle. Pin it.
        node.dont-move = true
        # If the speaker sink is not present yet -- the tuning host can start
        # before the device is discovered -- WirePlumber would otherwise link this
        # output to whatever default exists, quietly tuning the wrong device while
        # the tuning sink still looks healthy. Wait for the named target instead.
        # Both are needed: without linger, WirePlumber destroys the node rather
        # than waiting (see its scripts/linking/find-defined-target.lua).
        node.dont-fallback = true
        node.linger = true
      }
    }
  }
 ]
@@ -0,0 +1,39 @@
 ## Dell XPS 14 / XPS 16 (2026) internal speakers.
 ##
 ## Thirteen biquads and a lookahead limiter, applied as a PipeWire filter-chain
 ## in front of the internal speaker sink. The stock Linux path already loads
 ## Dell's Cirrus smart-amplifier firmware; this adds the perceptual voicing the
 ## Windows Waves layer provides and Linux does not.
 description="Dell XPS 14/16 (2026) speakers"
 ## Matched on the DMI product SKU, which is what Dell keys the Cirrus speaker
 ## firmware on -- 10280db9 for the XPS 14 and 10280dba for the XPS 16 -- so it
 ## identifies the speaker hardware itself rather than a marketing name. Compared as
 ## whole values, so this cannot widen to the rest of the XPS line.
 ##
 ##   0DB9  XPS 14 -- measured here, see below
 ##   0DBA  XPS 16 -- included on report that this profile suits it, not measured
 match_sku=("0DB9" "0DBA")
 ## Unescaped dots: this is passed to awk as a string, where a backslash escape
 ## would be consumed before the regex sees it.
 sink_pattern='^alsa_output.*sof_sdw.*HiFi__Speaker__sink$'
 ## Provenance. Derived by measuring the response of the xps-clone EasyEffects
 ## profile from https://github.com/spencerbull/xps-audio-linux (MIT) and fitting
 ## a biquad chain to it. No upstream asset is redistributed: the convolution
 ## impulse response is not carried, so this tuning has no binary blob and is
 ## sample-rate agnostic.
 derived_from="xps-audio-linux xps-clone (MIT, spencerbull)"
 validated_by="dhh"
 validated_on="2026-07-24"
 ## The measurements below were taken on the XPS 14 (0DB9). The XPS 16 (0DBA) is
 ## covered on report rather than measurement; re-measure there before treating
 ## these figures as describing it.
 validated_hardware="XPS 14 DA14260 (0DB9)"
 ## Measured against that reference under a dense pink-weighted multitone of 104
 ## bin-aligned tones. See docs/AUDIO-TUNING.md for how to reproduce these.
 magnitude_rms_db="1.24"
 bass_group_delay_swing_ms="13.2"
 limiter_headroom_db="1.6"   ## worst-case peak on a hot master vs -1 dBFS
 dynamic_range_delta_lu="0.1"
@@ -0,0 +1,7 @@
 [main]
 font=JetBrainsMono Nerd Font:size=18
 pad=0x0
 [colors-dark]
 background=000000
 foreground=ffffff
@@ -0,0 +1,2 @@
 [Manager]
 DefaultTimeoutStopSec=5s
@@ -0,0 +1,65 @@
 #!/bin/bash
 set -e
 # Use the Vfio to Integrated trick to turn off NVIDIA dgpu when in integrated mode
 # without needing to restart the computer. This is needed because computers like the Asus G14
 # will wake after suspend in Hybrid mode, even if the system was in Integrated mode before
 # suspending.
 restore_marker=/run/blob-force-igpu-integrated
 sleep_action=${SYSTEMD_SLEEP_ACTION:-$2}
 [[ -x /usr/bin/supergfxctl ]] || exit 0
 switch_mode() {
  local expected="$1" current
  if ! /usr/bin/timeout --kill-after=1s 3s /usr/bin/supergfxctl -m "$expected"; then
    echo "Could not request the GPU transition to $expected mode" >&2
    return 1
  fi
  for _ in {1..10}; do
    if current=$(/usr/bin/timeout --kill-after=1s 2s /usr/bin/supergfxctl -g 2>/dev/null) &&
      [[ $current == "$expected" ]]; then
      return 0
    fi
    sleep 1
  done
  echo "Could not confirm the GPU transition to $expected mode" >&2
  return 1
 }
 case "$1" in
  pre)
    # Remember the mode this sleep cycle started in. supergfxctl persists the
    # temporary hibernate switch to Vfio, so post must not consult that mutable
    # value when deciding whether to restore Integrated mode.
    if [[ -L $restore_marker ]]; then
      exit 1
    elif [[ ! -f $restore_marker ]]; then
      /usr/bin/grep -Eq '"mode"[[:space:]]*:[[:space:]]*"Integrated"' /etc/supergfxd.conf 2>/dev/null || exit 0
      /usr/bin/install -m 0600 -o root -g root -T /dev/null "$restore_marker"
    fi
    # Before hibernating, switch to Vfio so the nvidia driver is detached from the dGPU.
    # Without this, hibernate resume fails because the nvidia driver can't freeze a
    # powered-off dGPU (returns -EIO), which aborts the entire resume.
    if [[ $sleep_action == "hibernate" ]]; then
      switch_mode Vfio
    fi
    ;;
  post)
    [[ -f $restore_marker && ! -L $restore_marker ]] || exit 0
    # small delay so the device is fully re-enumerated
    sleep 4
    # force-bind dGPU to vfio (fully detached from nvidia)
    switch_mode Vfio
    # then go back to Integrated, which powers it off again
    switch_mode Integrated
    /usr/bin/rm -f -- "$restore_marker"
    ;;
 esac
@@ -0,0 +1,20 @@
 #!/bin/bash
 # Turn off keyboard backlight before hibernate to prevent hang on power-off.
 # The ASUS keyboard controller can block S4 shutdown if LEDs are active.
 sleep_action=${SYSTEMD_SLEEP_ACTION:-$2}
 if [[ $1 == "pre" && $sleep_action == "hibernate" ]]; then
  device=""
  for candidate in /sys/class/leds/*kbd_backlight*; do
    if [[ -e "$candidate" ]]; then
      device="$(basename "$candidate")"
      break
    fi
  done
  if [[ -n "$device" ]]; then
    brightnessctl -d "$device" set 0 >/dev/null 2>&1
  fi
 fi
@@ -0,0 +1,32 @@
 #!/bin/bash
 # Lazy-unmount gvfsd-fuse filesystems before suspend/hibernate to prevent the
 # kernel's process freeze from timing out. FUSE daemons (like gvfsd-fuse from
 # Nautilus) can block in uninterruptible sleep during freeze, causing suspend
 # to silently fail. After wake, restart gvfs so the FUSE mount is restored.
 if [[ $1 == "pre" ]]; then
  while IFS=' ' read -r _ mountpoint fstype _; do
    if [[ $fstype == fuse.gvfsd-fuse ]]; then
      mountpoint=$(printf '%b' "$mountpoint")
      fusermount3 -uz "$mountpoint" 2>/dev/null || fusermount -uz "$mountpoint" 2>/dev/null || true
    fi
  done < /proc/mounts
 fi
 if [[ $1 == "post" ]]; then
  # Run in background — user.slice is still frozen at this point, so a
  # synchronous restart would block the thaw for up to 90 seconds.
  (
    sleep 5
    for uid_dir in /run/user/*; do
      uid=$(basename "$uid_dir")
      if [[ -S $uid_dir/bus ]]; then
        sudo -u "#$uid" env \
          DBUS_SESSION_BUS_ADDRESS="unix:path=$uid_dir/bus" \
          XDG_RUNTIME_DIR="$uid_dir" \
          systemctl --user restart gvfs-daemon.service 2>/dev/null || true
      fi
    done
  ) &
 fi
@@ -0,0 +1,3 @@
 [Service]
 ExecStart=
 ExecStart=/usr/bin/updatedb --prune-bind-mounts=no --add-prunepaths=/.snapshots
@@ -0,0 +1,6 @@
 [Service]
 # Delay startup to avoid race condition with display manager initialization
 # when booting in Integrated mode. Without this delay, the system can freeze
 # on boot because supergfxd tries to disable the dGPU while the display
 # subsystem is still initializing.
 ExecStartPre=/bin/sleep 5
@@ -0,0 +1,16 @@
 # Make user apps the only thing systemd-oomd is allowed to kill.
 #
 # Hyprland runs in session.slice, as wayland-wm@hyprland.desktop.service, while
 # everything launched through uwsm-app lands in app.slice/app-*.scope. Marking
 # only app.slice as a kill candidate means the compositor is structurally
 # ineligible: oomd takes the browser or terminal that caused the pressure, and
 # the session survives to show the notification about it. Setting this on
 # user@.service instead would put the compositor back in the candidate pool.
 #
 # Swap kill is a backstop for the slower shape of the same problem, where swap
 # fills before pressure spikes. It uses the global SwapUsedLimit (90%) from
 # /etc/systemd/oomd.conf.d/10-blob.conf, which also carries the pressure
 # thresholds.
 [Slice]
 ManagedOOMMemoryPressure=kill
 ManagedOOMSwap=kill
@@ -0,0 +1,19 @@
 [Unit]
 Description=Announce process crashes and offer an AI diagnosis
 # Needs the session bus to notify, and uwsm-app to open the diagnosis terminal.
 # Both are up only after graphical-session.target.
 After=graphical-session.target
 PartOf=graphical-session.target
 ConditionEnvironment=WAYLAND_DISPLAY
 # Set by blob-toggle-crash-capture. Checked here so a disabled watcher stays
 # disabled across logins without the unit having to be disabled.
 ConditionPathExists=!%h/.local/state/blob/toggles/crash-capture-off
 [Service]
 Type=simple
 ExecStart=/usr/bin/blob-crash-watch
 Restart=always
 RestartSec=5
 [Install]
 WantedBy=graphical-session.target
@@ -0,0 +1,31 @@
 [Unit]
 Description=Fcitx5 input method (XCompose sequences)
 # fcitx5 turns the CapsLock compose sequences in ~/.XCompose into text for
 # Wayland clients.
 #
 # Wait for the compositor: fcitx5 needs WAYLAND_DISPLAY and DISPLAY, which uwsm
 # imports into the user manager before it reaches graphical-session.target.
 After=graphical-session.target
 # The wayland connection dies with the compositor, so follow the session rather
 # than linger against a socket that is gone.
 PartOf=graphical-session.target
 # After= is ordering only -- it does not stop anything from starting this unit
 # while the target is inactive. An `blob update` over SSH has a live user
 # manager (pam_systemd) and no graphical session, and a fcitx5 started there
 # comes up with no WAYLAND_DISPLAY and no way to reach any client. Worse, it
 # stays active, so the later graphical-session.target activation won't pull in a
 # working one -- Wants= does not restart what is already running. Skip the start
 # instead; the unit stays enabled and starts for real at graphical login.
 ConditionEnvironment=WAYLAND_DISPLAY
 [Service]
 Type=simple
 # notificationitem duplicates the tray entry blob already renders itself.
 ExecStart=/usr/bin/fcitx5 --disable notificationitem
 # always, not on-failure: fcitx5 exits 0 when it detects another instance owning
 # its bus name, and a clean exit still leaves the user with no input method.
 Restart=always
 RestartSec=2
 [Install]
 WantedBy=graphical-session.target
@@ -0,0 +1,19 @@
 [Unit]
 Description=Lock Blob before suspend
 # The monitor calls into the running Blob shell. Wait until UWSM has imported
 # BLOB_PATH and WAYLAND_DISPLAY, but keep the default target ordering so the
 # monitor starts before graphical-session.target is reached.
 After=dbus.socket wayland-session-waitenv.service
 Requires=dbus.socket
 PartOf=graphical-session.target
 ConditionEnvironment=BLOB_PATH
 ConditionEnvironment=WAYLAND_DISPLAY
 [Service]
 Type=simple
 ExecStart=/usr/bin/blob-system-sleep-monitor
 Restart=always
 RestartSec=2
 [Install]
 WantedBy=graphical-session.target
@@ -0,0 +1,32 @@
 [Unit]
 Description=Blob speaker tuning filter-chain
 Documentation=https://github.com/basecamp/omarchy/blob/master/docs/AUDIO-TUNING.md
 # WirePlumber does the linking, so starting before it is up risks the output being
 # linked before the speaker device has been discovered.
 After=pipewire.service wireplumber.service
 Requires=pipewire.service
 Wants=wireplumber.service
 # Restart with the audio daemon, since the filter-chain loses its connection when
 # PipeWire goes away.
 PartOf=pipewire.service
 [Service]
 Type=simple
 # Hosts the tuning as a PipeWire *client* rather than loading it into the daemon
 # from pipewire.conf.d, which is only read at daemon startup. That is what lets
 # the tuning be switched on and off without restarting pipewire-pulse -- a
 # restart drops every PulseAudio client's connection, and applications that do
 # not reconnect (Spotify) have to be restarted by hand.
 #
 # It also contains failure: a malformed tuning breaks only this service, where a
 # bad drop-in in the daemon's own config stops PipeWire from starting at all.
 #
 # The config name is deliberately not PipeWire's stock filter-chain.conf, which
 # merges every fragment in ~/.config/pipewire/filter-chain.conf.d/ and would make
 # this service host unrelated user filters too.
 ExecStart=/usr/bin/pipewire -c blob-speaker-tuning.conf
 Restart=on-failure
 RestartSec=2
 [Install]
 WantedBy=graphical-session.target
@@ -0,0 +1,23 @@
 [Unit]
 Description=Bluetooth pairing agent (auto-accept)
 Documentation=man:bt-agent(1)
 ConditionPathIsDirectory=/sys/class/bluetooth
 # bluez must be reachable on the system bus before we can register.
 After=dbus.socket
 Requires=dbus.socket
 [Service]
 Type=simple
 # If bluetoothd is unavailable (for example in VMs or machines without a
 # usable adapter), skip cleanly instead of entering a restart loop.
 ExecCondition=/usr/bin/systemctl is-active --quiet bluetooth.service
 # NoInputNoOutput auto-accepts pair requests. Safe because the adapter
 # is only `pairable: true` when the user explicitly opens the blob
 # bluetoothPanel and starts scanning; outside that window bluez refuses
 # inbound pair attempts at a lower layer.
 ExecStart=/usr/bin/bt-agent -c NoInputNoOutput
 Restart=on-failure
 RestartSec=2
 [Install]
 WantedBy=graphical-session.target
@@ -0,0 +1,2 @@
 [Service]
 TimeoutStopSec=5s
@@ -0,0 +1,559 @@
 # Commands
 Generated by `blob-docs-commands` from the `# blob:summary=` line in each
 file. Do not edit by hand.
 Commands marked hidden are plumbing other commands call, and are left out
 of the `blob` listing.
 ## audio
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-audio-availability` | Print PulseAudio sink availability for the shell | - |
 | `blob-audio-input-mute` | Toggle microphone mute. Drives the hardware mic-mute LED on laptops that expose one. | - |
 | `blob-audio-input-set` | Set the default audio input and move active streams | <node-id> <source-name> |
 | `blob-audio-restart` | Restart audio services and recover stuck USB audio devices. | - |
 | `blob-audio-sink` | Print the sink whose volume and mute a given output really uses | [sink-name] |
 | `blob-audio-sink-set` | Set the default audio output and move active streams | <node-id> <sink-name> |
 | `blob-audio-sink-switch` | Switch between audio outputs while preserving the mute status | - |
 | `blob-audio-source-switch` | Cycle to the next media source and transfer playback when the current source is playing | [next\|previous] |
 | `blob-audio-tuning` | Manage the speaker tuning for this laptop | <on\|off\|status\|match\|fronted-sink> [--force] |
 | `blob-audio-volume` | Adjust output volume and show the Blob OSD | <raise\|lower\|mute-toggle\|+N\|-N> |
 ## bar
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-bar` | Configure the bar and its widget layout | use <id> \| reset \| defaults \| position <top\|bottom\|left\|right> \| transparent <true\|false\|toggle> \| put <id> [placement] \| move <id> [placement] \| set <id> <key> <value> [--json] [placement] |
 | `blob-bar-color` | Choose a legible transparent bar text color (hidden) | - |
 ## battery
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-battery-low` | Send the low battery warning notification and run battery-low hooks. (hidden) | <percentage> |
 | `blob-battery-status` | Returns a formatted battery status string with percentage and power draw/charge. | [--shell] |
 ## bg
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-bg-cache` | Cache background switcher thumbnails for the current theme | - |
 | `blob-bg-current` | Show current background | - |
 | `blob-bg-install` | Open the current theme's user background folder | - |
 | `blob-bg-next` | Cycle to the next background for the current theme | - |
 | `blob-bg-set` | Set the current background image | <path-to-image> |
 | `blob-bg-switcher` | Open the Blob background switcher | - |
 ## bluetooth
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-bluetooth-device` | Control a Bluetooth device | [pair\|connect\|disconnect\|forget] <address> |
 | `blob-bluetooth-power` | Turn Bluetooth on or off, remembered across reboots | <on\|off\|toggle\|is-on> |
 | `blob-bluetooth-restart` | Unblock and restart the bluetooth service. | - |
 ## boot
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-boot` | - | - |
 ## branding
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-branding-about` | Edit, set, or reset About branding | <image\|text\|reset> |
 | `blob-branding-screensaver` | Edit, set, or reset screensaver branding | <image\|text\|reset> |
 ## brightness
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-brightness-ddc` | Show or adjust DDC/CI display brightness for a Hyprland monitor. | <monitor> [+N%\|N%-\|N%] |
 | `blob-brightness-display` | Show or adjust brightness on the focused display. | [--no-osd] [--monitor name] [+N%\|N%-\|N%\|off\|on] |
 | `blob-brightness-display-apple` | Show or adjust Apple Studio Display and Apple XDR Display brightness using asdcontrol. | [--no-osd] [+N%\|N%-\|N%] |
 | `blob-brightness-keyboard` | Adjust keyboard backlight brightness using available steps. | [--no-osd] <up\|down\|cycle\|off\|restore> |
 | `blob-brightness-keyboard-mute` | Set the mic-mute indicator LED on laptops that expose a platform::micmute LED node. | <on\|off> |
 ## capture
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-capture-qr` | Decode a QR code from a screenshot region | - |
 | `blob-capture-record` | Start or stop screen recording | [--fullscreen] [--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--webcam-size=<small\|medium\|large>] [--resolution=<size>] [--stop-recording] |
 | `blob-capture-record-webcam` | Pick a webcam and start a screen recording with it | - |
 | `blob-capture-region` | Pick a screen region over frozen screen content (hidden) | [region\|windows\|smart\|fullscreen] [--keep-freeze] [--match-monitor] \| --take-fullscreen \| --take-window \| --select-window <next\|prev\|left\|right\|up\|down> |
 | `blob-capture-screenshot` | Take a screenshot | [smart\|region\|windows\|fullscreen] [slurp\|copy\|save] [--editor=<name>] |
 | `blob-capture-text` | Extract text from a screenshot region with OCR | - |
 | `blob-capture-webcam-list` | List webcam devices that support video capture (hidden) | - |
 | `blob-capture-webcam-resize` | Resize the active webcam recording overlay | <smaller\|larger\|reset\|small\|medium\|large> |
 ## clipboard
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-clipboard-file` | Copy a file to the clipboard and paste it (hidden) | [--copy-only] <mime-type> <path> |
 | `blob-clipboard-open` | Open a clipboard history entry (hidden) | --history-index <index> |
 | `blob-clipboard-text` | Copy text to the clipboard and type or paste it (hidden) | [--shift-insert] [--copy-only] [--history-index <index>\|<text>] |
 ## cmd
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-cmd-cwd` | Print the current working directory of the active terminal window (hidden) | - |
 | `blob-cmd-missing` | Check whether any required commands are missing | - |
 | `blob-cmd-present` | Check whether all required commands are available | - |
 ## crash
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-crash-watch` | Watch for process crashes and offer an AI diagnosis (hidden) | - |
 ## default
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-default-browser` | Set the default browser for Blob and XDG handlers | [chromium\|chrome\|brave\|brave-origin\|edge\|firefox\|zen] |
 | `blob-default-editor` | Set the default editor used by blob-launch-editor | [code\|cursor\|zed\|sublime_text\|helix\|vim\|emacs\|nvim] |
 | `blob-default-terminal` | Set the default terminal used by xdg-terminal-exec | [alacritty\|foot\|ghostty\|kitty] |
 ## disk
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-disk-speedtest` | Measure live disk read and write speed | [target-dir] |
 ## display
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-display-size` | Scale text everywhere — blob shell, GTK apps, and terminals | [size\|reset] |
 | `blob-display-state` | Print monitor panel state for the shell | - |
 ## docs
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-docs-commands` | Regenerate docs/commands.md from each command's own metadata (hidden) | - |
 | `blob-docs-keybinds` | Regenerate docs/keybinds.md from the Hyprland Lua bindings (hidden) | - |
 ## drive
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-drive-info` | Print drive information such as size, model, and mount details | <drive> |
 | `blob-drive-password` | Set a new encryption password for a drive selected. | - |
 | `blob-drive-select` | Select a drive from a list with info that includes space and brand. Used by blob-drive-password. | - |
 ## file
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-file-select` | Pick files with the desktop file chooser | [--title <title>] [--multiple] [--directory] [--extensions "<ext ext...>"] |
 ## font
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-font-current` | Show current monospace font | - |
 | `blob-font-list` | List available monospace fonts | - |
 | `blob-font-set` | Set the system monospace font | <font-name> |
 ## git
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-git-url-check` | Check that a git URL names a repository, not a transport helper (hidden) | <git-url> |
 ## hibernation
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-hibernation-available` | Check if hibernation is supported | - |
 ## hook
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-hook` | Run a named hook from ~/.config/blob/hooks/<name> and ~/.config/blob/hooks/<name>.d/. | [name] [args...] |
 ## hw
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-hw-clamshell` | Returns true when clamshell mode is active (hidden) | - |
 | `blob-hw-dell-xps-haptic-touchpad` | Match Dell XPS systems with the Synaptics haptic touchpad. | - |
 | `blob-hw-display` | Print the most likely display backlight device. | - |
 | `blob-hw-external` | Returns true when an external monitor is physically connected. | - |
 | `blob-hw-fingerprint` | Returns true when a fingerprint reader is present (hidden) | - |
 | `blob-hw-hybrid-gpu` | Detect whether the system has an active hybrid GPU configuration | - |
 | `blob-hw-laptop` | Returns true when running on a laptop (has a lid or laptop chassis). | - |
 | `blob-hw-laptop-closed` | Returns true when the laptop lid is closed (hidden) | - |
 | `blob-hw-match` | Match against the computer's DMI product name or product family (case-insensitive). | <pattern> |
 | `blob-hw-nvidia` | Detect whether the computer has an NVIDIA GPU. | - |
 | `blob-hw-nvidia-gsp` | Detect whether the computer has an NVIDIA GPU with GSP firmware (Turing or newer). | - |
 | `blob-hw-nvidia-without-gsp` | Detect whether the computer has an NVIDIA GPU without GSP firmware (Maxwell/Pascal/Volta). | - |
 | `blob-hw-touchpad` | Print the detected Hyprland touchpad or trackpad device name | - |
 | `blob-hw-touchscreen` | Print the detected Hyprland touchscreen or tablet device name | - |
 | `blob-hw-webcam` | Check whether a webcam is available | - |
 ## hypr
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-hypr-focus` | Focus a Hyprland window by application identity | <app-name> |
 | `blob-hypr-monitor-clamshell` | Apply clamshell display state to Hyprland monitors (hidden) | - |
 | `blob-hypr-monitor-external` | Returns true when Hyprland has an active external monitor (hidden) | - |
 | `blob-hypr-monitor-focused` | Print the name of the currently focused Hyprland monitor. | - |
 | `blob-hypr-monitor-focused-apple` | Return success if the focused or named Hyprland monitor is an Apple display. | [monitor] |
 | `blob-hypr-monitor-internal` | Enable, disable, toggle, or recover the internal laptop display | <on\|off\|toggle\|recover> |
 | `blob-hypr-monitor-laptop` | Print the name of the built-in laptop display, including disabled outputs. | - |
 | `blob-hypr-monitor-mirror` | Enable, disable, toggle, or recover mirroring the internal display to an external monitor | <on\|off\|toggle\|recover> |
 | `blob-hypr-monitor-modeless` | Returns true when Hyprland has an enabled monitor with no mode (hidden) | - |
 | `blob-hypr-monitor-scaling` | Show, set, or adjust focused Hyprland monitor scaling | [up\|down\|SCALE] |
 | `blob-hypr-monitor-watch` | Watch Hyprland monitor events and recover monitor toggles when a monitor is removed | - |
 | `blob-hypr-reload-guard` | Pause or resume Hyprland config auto-reload around package transactions. (hidden) | - |
 | `blob-hypr-restart` | Reload hyprland configuration (used by the Blob theme switching). | - |
 | `blob-hypr-session-locked` | Returns true when the compositor holds a session lock (hidden) | - |
 | `blob-hypr-toggle` | Toggle permanent Hyprland flags by copying them into a directory that's sourced entirely. | <flag-name> [on\|off\|toggle] |
 | `blob-hypr-toggle-disabled` | Check if a Hyprland toggle is currently disabled (missing). | <flag-name> |
 | `blob-hypr-toggle-enabled` | Check if a Hyprland toggle is currently enabled. | <flag-name> |
 | `blob-hypr-window-close-all` | Close all open windows | - |
 | `blob-hypr-window-gaps-toggle` | Toggles the window gaps globally between no gaps and the default. | - |
 | `blob-hypr-window-pop` | Toggle to pop-out a tile to stay fixed on a display basis. | [width height x y] |
 | `blob-hypr-window-single-square-aspect-toggle` | Toggle single-window square aspect ratio. | - |
 | `blob-hypr-window-tiled-fullscreen-toggle` | Toggle tiled fullscreen for the focused Hyprland window | - |
 | `blob-hypr-window-transparency-toggle` | Toggles transparency for the currently focused window. | - |
 | `blob-hypr-window-width` | Save or restore the focused Hyprland window width | <save\|restore> |
 | `blob-hypr-workspace-layout-toggle` | Toggle the layout on the current active workspace between dwindle and scrolling | - |
 ## install
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-install-font` | Install a Nerd Font package and switch the system to it | <display-name> <package> <family> |
 | `blob-install-launch` | Install a packaged app and launch it once it finishes | <display-name> <packages> <desktop-id> |
 ## launch
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-launch-about` | Launch the fastfetch TUI that gives information about the current system. | - |
 | `blob-launch-browser` | Launch the default browser as determined by xdg-settings. | [url] |
 | `blob-launch-config-editor` | Open a config file in the user's editor and surface a toast | <path> |
 | `blob-launch-docker-tui` | Open the Docker TUI (lazydocker) with access to the Docker daemon (hidden) | - |
 | `blob-launch-editor` | Launch the default editor selected via Blob defaults. | [--inline] <path> |
 ## launcher
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-launcher-remove` | Remove or uninstall the selected launcher entry (hidden) | <desktop-id> <name> |
 ## launch
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-launch-floating` | Launch a floating terminal with the Blob presentation wrapper | <command> |
 | `blob-launch-or-focus` | Launch an app or focus an existing window matching a pattern | <window-pattern> <launch-command> |
 | `blob-launch-or-focus-tui` | Launch a TUI or focus an existing terminal window for it | [--app-id=<app-id>] <command> [args...] |
 | `blob-launch-screensaver` | Launch the Blob screensaver in the default terminal on the system with the correct font configuration. | - |
 | `blob-launch-shell` | Launch the Blob shell with its log kept in the journal (hidden) | - |
 | `blob-launch-tui` | Launch a TUI command in the default terminal with Blob styling | [--app-id=<app-id>] <command> [args...] |
 ## menu
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-menu` | Control the Blob menu (toggle / summon / close / refresh) | [toggle\|summon\|close\|refresh\|ping] [route] |
 | `blob-menu-emoji` | Launch emojis | - |
 | `blob-menu-emoji-insert` | Insert an emoji into the focused application (hidden) | <emoji> |
 | `blob-menu-file` | Pick a file from a menu | label paths formats [menu args...] |
 | `blob-menu-images` | Open a generic image selector menu | [--selected <image>] [--print-name] [--show-labels] [--filterable] [--lazy-thumbnails] [--preload] [--cache-only] <image-dir>... |
 | `blob-menu-keybindings` | Display Hyprland keybindings defined in your configuration using an interactive search menu. | - |
 | `blob-menu-plugin` | Pick a shell plugin to enable, disable, clone, or remove | <enable\|disable\|clone\|remove> |
 | `blob-menu-select` | Pick one option from a menu | prompt [option...] [-- menu args...] |
 | `blob-menu-share` | Share clipboard, files, or folders with LocalSend | <clipboard\|file\|folder> [path...] |
 | `blob-menu-timezone` | Select and set the system timezone | - |
 ## network
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-network-band` | Show or pin the Wi-Fi band for the active connection | [auto\|2.4\|5\|6] |
 | `blob-network-dns` | Show or configure the system DNS provider | [Cloudflare\|Google\|DHCP\|Custom] |
 | `blob-network-iwd` | - | - |
 | `blob-network-password` | Print the active Wi-Fi connection's password | <interface> |
 | `blob-network-qr` | Generate a Wi-Fi QR matrix for the shell | [--meta] [interface] |
 | `blob-network-restart` | Unblock and restart the Wi-Fi service. | - |
 | `blob-network-speedtest` | Measure live internet speed for one direction | [down\|up] |
 | `blob-network-status` | Print active network status for the shell | [--verbose] |
 ## notification
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-notification-battery` | Show the current battery status notification | - |
 | `blob-notification-time` | Show the current time and date notification | - |
 | `blob-notification-wait` | Wait for the desktop notification server to accept notifications (hidden) | [timeout-seconds] |
 | `blob-notification-weather` | Toggle the current weather panel | - |
 ## notify
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-notify-dismiss` | Dismiss a notification by summary substring. Used by the first-run notifications to dismiss them after clicking for action. | <summary> |
 | `blob-notify-send` | Send an Blob desktop notification | [--app-name <app-name>] [-g <glyph>] [-u <low\|normal\|critical>] [-i <icon>] [-t <ms>] [-r <id>] [-p] [--image <path-or-uri>] <headline> [description] [--exec <program> [args...]] |
 ## osd
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-osd` | Show the Blob Quickshell on-screen display | [-i\|--icon <icon>] [-m\|--message <text>] [-p\|--progress <0-100>] [-d\|--duration <ms>] |
 ## pkg
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-pkg-add` | Install Arch packages if they are missing | <packages...> |
 | `blob-pkg-aur` | Returns true if the AUR is up and available. | - |
 | `blob-pkg-aur-install` | Show a fuzzy-finder TUI for picking new AUR packages to install. | - |
 | `blob-pkg-drop` | Remove all the named packages from the system if they're installed (otherwise ignore). | <packages...> |
 | `blob-pkg-install` | Show a fuzzy-finder TUI for picking new Arch and OPR packages to install. | - |
 | `blob-pkg-missing` | Returns true if any of the named packages are missing from the system (or false if they're all there). | <packages...> |
 | `blob-pkg-present` | Returns true if all of the named packages are installed on the system (or false if any of them are missing). | <packages...> |
 | `blob-pkg-remove` | Show a fuzzy-finder TUI for picking packages installed on the system to be removed. | - |
 ## plugin
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-plugin-add` | Add a shell plugin from git | [git-url] [--enable] [--yes] |
 | `blob-plugin-catalog` | Emit every first-party and user plugin manifest as JSON (hidden) | - |
 | `blob-plugin-clone` | Clone a built-in Blob shell plugin into your own config | <source-id> [--edit] |
 | `blob-plugin-enable` | Enable a shell plugin | <id> [placement] |
 | `blob-plugin-list` | List discovered shell plugins | [--json] |
 | `blob-plugin-remove` | Remove an installed shell plugin | [id] [--yes] |
 | `blob-plugin-validate` | Validate a plugin folder against the Blob plugin manifest schema | <plugin-folder> |
 ## plymouth
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-plymouth-set` | Set the Plymouth boot theme colors and logo | <background-hex> <text-hex> <path-to-logo.png> |
 ## power
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-power-list` | Returns a list of all the available power profiles on the system. | [--active-state] |
 ## powerprofiles
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-powerprofiles-init` | Set the correct power profile on boot based on current AC/battery state. | - |
 ## power
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-power-set` | Set and remember the power profile for AC or battery use | [autodetect\|ac\|battery] [power-saver\|balanced\|performance] |
 ## refresh
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-refresh-config` | Copy a shipped user config from $BLOB_PATH/config into ~/.config (backs up your version). | <config-path> |
 | `blob-refresh-hyprland` | Overwrite all the user Hyprland Lua configs in ~/.config/hypr with the Blob defaults. | - |
 | `blob-refresh-hyprsunset` | Overwrite the user config for hyprsunset with the Blob default and restart the service. | - |
 | `blob-refresh-plymouth` | Overwrite the user config for the Plymouth drive decryption and boot sequence with the Blob default and rebuild it. | - |
 | `blob-refresh-shell` | Reset shell.json to Blob defaults | - |
 ## reminder
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-reminder` | Set and show lightweight desktop notification reminders | [-i\|--interactive] \| <minutes> [message] \| show [-j\|--json] \| clear |
 ## remove
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-remove-security-fido2` | Remove FIDO2 authentication from sudo and polkit | - |
 | `blob-remove-security-sudoless-docker` | Disable sudoless Docker by removing your user from the docker group | - |
 ## restart
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-restart-app` | Restart an application by killing it and relaunching via uwsm. | <application-name> [application-args...] |
 | `blob-restart-btop` | Reload btop configuration (used by the Blob theme switching). | - |
 | `blob-restart-gum` | Export the current theme's gum styling into the environment (hidden) | - |
 | `blob-restart-hyprsunset` | Restart the hyprsunset service (used for blue light filtering/night light). | - |
 | `blob-restart-terminal` | Reload supported terminal emulators after config changes | - |
 | `blob-restart-trackpad` | Reset the trackpad by unbinding and rebinding its driver. | - |
 | `blob-restart-xcompose` | Restart the XCompose input method service (fcitx5) to apply new compose key settings. | - |
 ## screensaver
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-screensaver` | Run the Blob screensaver using random effects from TTE. | - |
 ## secret
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-secret` | - | - |
 ## setup
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-setup-direct-boot` | Add or remove an EFI boot entry for the Blob UKI, allowing the system to boot directly | - |
 | `blob-setup-security-fido2` | Set up FIDO2 authentication for sudo and polkit | - |
 | `blob-setup-security-fingerprint` | Set up fingerprint authentication for sudo, polkit, and lock screen | - |
 | `blob-setup-security-sshd` | Set up the OpenSSH server, open the firewall, and authorize an SSH key | [--key=<public-key>] |
 | `blob-setup-security-sudoless-docker` | Enable sudoless Docker by adding your user to the docker group (root-equivalent!) | - |
 ## shell
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-shell` | Send an IPC call to the running Blob shell | [-q] <target> <method> [args...] |
 | `blob-shell-config` | Shared helpers for editing ~/.config/blob/shell.json (source this, don't run it). (hidden) | - |
 | `blob-shell-restart` | Restart the Blob shell | - |
 ## show
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-show-done` | Display a "Done!" message and wait for user to press any key. | - |
 | `blob-show-logo` | Display the Blob logo in the terminal using green color. | - |
 ## state
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-state` | Manage persistent state files for Blob toggles and settings. (hidden) | <set\|clear> <state-name-or-pattern> |
 ## sudo
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-sudo-docker` | Succeed when Docker needs sudo, fail when it can be used directly (hidden) | [--configured] |
 | `blob-sudo-keepalive` | Prompt for sudo once and keep the credential alive in the background. | - |
 | `blob-sudo-passwordless` | Toggle passwordless sudo for the current user. | [MINUTES] |
 ## system
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-system-lid` | Lock and reconcile displays when the laptop lid closes (hidden) | - |
 | `blob-system-lock` | Lock the computer and turn off the display | - |
 | `blob-system-logout` | Log out after closing application windows | - |
 | `blob-system-reboot` | Reboot after closing application windows | - |
 | `blob-system-shutdown` | Shut down after closing application windows | - |
 | `blob-system-sleep` | Lock before suspend and wait for the session lock to become secure (hidden) | - |
 | `blob-system-sleep-monitor` | Monitor sleep preparation and lock before suspend (hidden) | - |
 | `blob-system-stats` | Print CPU and memory stats for the shell | [--bar-widget] |
 | `blob-system-wake` | Wake displays and restore brightness after idle | - |
 ## tablet
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-tablet-follow` | - | - |
 ## theme
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-theme-browser` | Apply the current theme color to Chromium, Chrome, Edge, and Brave (hidden) | - |
 | `blob-theme-browser-policy` | Write the current theme color into the browser policy directories (hidden) | <rrggbb> |
 | `blob-theme-color` | Resolve semantic colors from an Blob theme colors.toml (hidden) | [--file <colors.toml>] (--all \| --raw \| <key> [fallback]) |
 | `blob-theme-contrast` | - | - |
 | `blob-theme-current` | Show current theme | - |
 | `blob-theme-dir` | Print the directory holding a theme, preferring a user-installed copy | <theme-name> |
 | `blob-theme-dynamic` | Apply the pywal-generated theme built from the current wallpaper | - |
 | `blob-theme-extras` | List the user-installed themes that came from a git clone | - |
 | `blob-theme-foot` | Apply current Blob theme colors to running Foot terminals (hidden) | - |
 | `blob-theme-import` | Generate a theme's colors.toml from its alacritty.toml palette (hidden) | <theme-dir> |
 | `blob-theme-install` | Install a theme from a git repository | [git-repo-url] |
 | `blob-theme-list` | List available themes | - |
 | `blob-theme-menu` | Pick a color theme from the local and bundled sets | [--mode\|--print] |
 | `blob-theme-osc` | Print OSC sequences for an Blob color theme (hidden) | - |
 | `blob-theme-refresh` | Refresh the current theme from its templates. | - |
 | `blob-theme-remove` | Remove a user-installed theme | [theme-name] |
 | `blob-theme-set` | Apply an Blob theme | <theme-name> |
 | `blob-theme-share` | Fetch a shared theme by link or id and apply it as blob-dynamic | <share-link-or-id> |
 | `blob-theme-switcher` | Open the Blob theme switcher | - |
 | `blob-theme-templates` | Generate themed config files from Blob templates (hidden) | - |
 | `blob-theme-update` | Update user-installed git themes | - |
 ## toggle
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-toggle` | Toggle Blob features between enabled and disabled | <flag-name> [toggle\|on\|off] |
 | `blob-toggle-bar` | Toggle bar visibility without killing the Blob shell | [toggle\|on\|off] |
 | `blob-toggle-crash-capture` | Toggle crash capture notifications | - |
 | `blob-toggle-enabled` | Check if a toggle is enabled (flag file exists) | <flag-name> |
 | `blob-toggle-glass` | - | - |
 | `blob-toggle-hybrid-gpu` | Toggle dedicated vs integrated GPU mode via supergfxd (for hybrid gpu laptops, like Asus G14). | - |
 | `blob-toggle-idle` | Toggle idle behavior so the system either idles normally or stays awake | [toggle\|stay-awake\|allow-idle\|status] |
 | `blob-toggle-input` | Enable, disable, or toggle a Hyprland input device (hidden) | <touchpad\|touchscreen> [on\|off\|toggle] |
 | `blob-toggle-nightlight` | Toggle nightlight screen temperature | [--status] |
 | `blob-toggle-screensaver` | Toggle screensaver availability | - |
 | `blob-toggle-silencing` | Toggle notification do-not-disturb mode | - |
 | `blob-toggle-tablet` | - | - |
 | `blob-toggle-touchpad` | Enable, disable, or toggle the touchpad | [on\|off\|toggle] |
 | `blob-toggle-touchscreen` | Enable, disable, or toggle the touch functionality of the screen | [on\|off\|toggle] |
 ## transcode
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-transcode` | Transcode pictures and videos for sharing | [--path path] [input] [format] [resolution] |
 | `blob-transcode-ascii` | Transcode an image into ASCII/Unicode art text | <input-image.svg\|png> <output-path> [--width <columns>] [--height <rows>] [--mode <braille\|block>] [--threshold <percent>] [--invert] |
 ## tui
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-tui-install` | Create a desktop launcher for a terminal UI app | [name command window-style icon-url-or-name] |
 | `blob-tui-remove` | Remove a terminal UI desktop launcher | [name] |
 | `blob-tui-remove-all` | Remove all TUIs installed via blob-tui-install. | - |
 ## update
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-update` | Update system and AUR packages | [--no-confirm] |
 | `blob-update-available` | Print the number of pending package updates (hidden) | - |
 | `blob-update-firmware` | Update system firmware using fwupd. Ensures the fwupd EFI binary is installed | - |
 | `blob-update-time` | Restart system time synchronization | - |
 ## wallpaper
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-wallpaper-set` | Set a wallpaper from ~/wallpapers and recolor the desktop from it | [--menu\|<file>] |
 ## weather
 | Command | Does | Arguments |
 | --- | --- | --- |
 | `blob-weather-card` | Print a one-line weather summary for the quick settings card (hidden) | - |
 | `blob-weather-icon` | Returns a weather condition icon, adjusted for live sunrise and sunset. | - |
 | `blob-weather-location` | Show or set the location used for weather reports | - |
 | `blob-weather-status` | Returns a formatted weather status string with temperature and wind speed. | - |
 ## Totals
 252 commands.
@@ -0,0 +1,202 @@
 # Keybindings
 Generated by `blob-docs-keybinds` from the `o.bind` calls in the Hyprland
 Lua files. Do not edit by hand.
 Personal overrides in `hypr/bindings.lua` win over the defaults, and
 `hl.unbind` in that file removes a default outright.
 ## Personal
 | Keys | Action |
 | --- | --- |
 | `SUPER + ALT + SPACE` | Blob menu |
 | `SUPER + ALT + W` | Wallpaper picker |
 | `SUPER + CTRL + M` | System monitor |
 | `SUPER + CTRL + Q` | Quick settings |
 | `SUPER + SPACE` | Apps menu |
 ## Applications
 | Keys | Action |
 | --- | --- |
 | `SUPER + ALT + SHIFT + F` | File manager (cwd) |
 | `SUPER + RETURN` | Terminal |
 | `SUPER + SHIFT + ALT + B` | Browser (private) |
 | `SUPER + SHIFT + B` | Browser |
 | `SUPER + SHIFT + D` | Docker |
 | `SUPER + SHIFT + F` | File manager |
 | `SUPER + SHIFT + G` | Signal |
 | `SUPER + SHIFT + M` | Music |
 | `SUPER + SHIFT + N` | Editor |
 | `SUPER + SHIFT + O` | Obsidian |
 | `SUPER + SHIFT + RETURN` | Browser |
 ## Tiling
 | Keys | Action |
 | --- | --- |
 | `ALT + SHIFT + TAB` | Focus on previous window |
 | `ALT + TAB` | Focus on next window |
 | `CTRL + ALT + DELETE` | Close all windows |
 | `CTRL + ALT + SHIFT + TAB` | Focus on previous monitor |
 | `CTRL + ALT + TAB` | Focus on next monitor |
 | `SUPER + ALT + code:20` | Expand window left a little |
 | `SUPER + ALT + code:21` | Shrink window left a little |
 | `SUPER + ALT + DOWN` | Move window to group on bottom |
 | `SUPER + ALT + F` | Full width |
 | `SUPER + ALT + G` | Move active window out of group |
 | `SUPER + ALT + Home` | Save window width |
 | `SUPER + ALT + LEFT` | Move window to group on left |
 | `SUPER + ALT + mouse_down` | Next window in group |
 | `SUPER + ALT + mouse_up` | Previous window in group |
 | `SUPER + ALT + RIGHT` | Move window to group on right |
 | `SUPER + ALT + S` | Move window to scratchpad |
 | `SUPER + ALT + SHIFT + TAB` | Previous window in group |
 | `SUPER + ALT + SLASH` | Monitor scaling down |
 | `SUPER + ALT + TAB` | Next window in group |
 | `SUPER + ALT + UP` | Move window to group on top |
 | `SUPER + code:20` | Expand window left |
 | `SUPER + code:21` | Shrink window left |
 | `SUPER + CTRL + code:20` | Expand window left a lot |
 | `SUPER + CTRL + code:21` | Shrink window left a lot |
 | `SUPER + CTRL + F` | Tiled full screen |
 | `SUPER + CTRL + LEFT` | Move grouped window focus left |
 | `SUPER + CTRL + RIGHT` | Move grouped window focus right |
 | `SUPER + CTRL + SHIFT + code:20` | Shrink window up a lot |
 | `SUPER + CTRL + SHIFT + code:21` | Expand window down a lot |
 | `SUPER + CTRL + TAB` | Former workspace |
 | `SUPER + DOWN` | Focus on below window |
 | `SUPER + F` | Full screen |
 | `SUPER + G` | Toggle window grouping |
 | `SUPER + Home` | Restore window width |
 | `SUPER + J` | Toggle window split |
 | `SUPER + L` | Toggle workspace layout |
 | `SUPER + LEFT` | Focus on left window |
 | `SUPER + mouse:272` | Move window |
 | `SUPER + mouse:273` | Resize window |
 | `SUPER + mouse_down` | Scroll active workspace forward |
 | `SUPER + mouse_up` | Scroll active workspace backward |
 | `SUPER + O` | Pop window out (float & pin) |
 | `SUPER + P` | Pseudo window |
 | `SUPER + RIGHT` | Focus on right window |
 | `SUPER + S` | Toggle scratchpad |
 | `SUPER + SHIFT + ALT + code:20` | Shrink window up a little |
 | `SUPER + SHIFT + ALT + code:21` | Expand window down a little |
 | `SUPER + SHIFT + ALT + DOWN` | Move workspace to down monitor |
 | `SUPER + SHIFT + ALT + LEFT` | Move workspace to left monitor |
 | `SUPER + SHIFT + ALT + RIGHT` | Move workspace to right monitor |
 | `SUPER + SHIFT + ALT + UP` | Move workspace to up monitor |
 | `SUPER + SHIFT + code:20` | Shrink window up |
 | `SUPER + SHIFT + code:21` | Expand window down |
 | `SUPER + SHIFT + DOWN` | Swap window down |
 | `SUPER + SHIFT + LEFT` | Swap window to the left |
 | `SUPER + SHIFT + RIGHT` | Swap window to the right |
 | `SUPER + SHIFT + TAB` | Previous workspace |
 | `SUPER + SHIFT + UP` | Swap window up |
 | `SUPER + SLASH` | Monitor scaling up |
 | `SUPER + T` | Toggle window floating/tiling |
 | `SUPER + TAB` | Next workspace |
 | `SUPER + UP` | Focus on above window |
 | `SUPER + W` | Close window |
 ## Media
 | Keys | Action |
 | --- | --- |
 | `ALT + SHIFT + XF86AudioPlay` | Previous track |
 | `ALT + XF86AudioLowerVolume` | Volume down precise |
 | `ALT + XF86AudioPlay` | Next track |
 | `ALT + XF86AudioRaiseVolume` | Volume up precise |
 | `ALT + XF86MonBrightnessDown` | Brightness down precise |
 | `ALT + XF86MonBrightnessUp` | Brightness up precise |
 | `SHIFT + XF86AudioMute` | Switch audio output |
 | `SHIFT + XF86AudioPause` | Switch media source |
 | `SHIFT + XF86AudioPlay` | Switch media source |
 | `SHIFT + XF86MonBrightnessDown` | Brightness minimum |
 | `SHIFT + XF86MonBrightnessUp` | Brightness maximum |
 | `XF86AudioLowerVolume` | Volume down |
 | `XF86AudioMicMute` | Mute microphone |
 | `XF86AudioMute` | Mute |
 | `XF86AudioNext` | Next track |
 | `XF86AudioPause` | Pause |
 | `XF86AudioPlay` | Play |
 | `XF86AudioPrev` | Previous track |
 | `XF86AudioRaiseVolume` | Volume up |
 | `XF86Eject` | Eject media |
 | `XF86KbdBrightnessDown` | Keyboard brightness down |
 | `XF86KbdBrightnessUp` | Keyboard brightness up |
 | `XF86KbdLightOnOff` | Keyboard backlight cycle |
 | `XF86MonBrightnessDown` | Brightness down |
 | `XF86MonBrightnessUp` | Brightness up |
 | `XF86TouchpadOff` | Disable touchpad |
 | `XF86TouchpadOn` | Enable touchpad |
 | `XF86TouchpadToggle` | Toggle touchpad |
 ## Clipboard
 | Keys | Action |
 | --- | --- |
 | `SUPER + C` | Universal copy |
 | `SUPER + CTRL + V` | Clipboard manager |
 | `SUPER + V` | Universal paste |
 | `SUPER + X` | Universal cut |
 ## Utilities
 | Keys | Action |
 | --- | --- |
 | `ALT + PRINT` | Screenrecording |
 | `PRINT` | Screenshot |
 | `SUPER + ALT + code:34` | Make webcam overlay smaller |
 | `SUPER + ALT + code:35` | Make webcam overlay larger |
 | `SUPER + ALT + comma` | Invoke last notification |
 | `SUPER + ALT + SPACE` | Apps menu |
 | `SUPER + BACKSPACE` | Toggle window transparency |
 | `SUPER + comma` | Dismiss last notification |
 | `SUPER + CTRL + A` | Audio |
 | `SUPER + CTRL + ALT + B` | Show battery remaining |
 | `SUPER + CTRL + ALT + D` | Calendar |
 | `SUPER + CTRL + ALT + Delete` | Toggle laptop display mirroring |
 | `SUPER + CTRL + ALT + R` | Show reminders |
 | `SUPER + CTRL + ALT + T` | Show time |
 | `SUPER + CTRL + ALT + W` | Toggle weather |
 | `SUPER + CTRL + ALT + Z` | Reset zoom |
 | `SUPER + CTRL + B` | Bluetooth |
 | `SUPER + CTRL + BACKSPACE` | Toggle single-window square aspect |
 | `SUPER + CTRL + C` | Capture menu |
 | `SUPER + CTRL + comma` | Toggle silencing notifications |
 | `SUPER + CTRL + D` | Display |
 | `SUPER + CTRL + Delete` | Toggle laptop display |
 | `SUPER + CTRL + E` | Emojis |
 | `SUPER + CTRL + H` | Hardware menu |
 | `SUPER + CTRL + I` | Toggle locking on idle |
 | `SUPER + CTRL + L` | Lock system |
 | `SUPER + CTRL + N` | Toggle nightlight |
 | `SUPER + CTRL + O` | Toggle menu |
 | `SUPER + CTRL + P` | Power |
 | `SUPER + CTRL + PERIOD` | Transcode |
 | `SUPER + CTRL + PRINT` | Extract text (OCR) from screenshot |
 | `SUPER + CTRL + R` | Set reminder |
 | `SUPER + CTRL + S` | Share |
 | `SUPER + CTRL + SPACE` | Background switcher |
 | `SUPER + CTRL + T` | Activity |
 | `SUPER + CTRL + W` | Network |
 | `SUPER + CTRL + Z` | Zoom in |
 | `SUPER + ESCAPE` | System menu |
 | `SUPER + K` | Keybindings |
 | `SUPER + PRINT` | Color picker |
 | `SUPER + SHIFT + ALT + comma` | Open notification history |
 | `SUPER + SHIFT + BACKSPACE` | Toggle window gaps |
 | `SUPER + SHIFT + code:201` | Blob menu |
 | `SUPER + SHIFT + comma` | Dismiss all notifications |
 | `SUPER + SHIFT + CTRL + R` | Clear reminders |
 | `SUPER + SHIFT + CTRL + SPACE` | Theme menu |
 | `SUPER + SHIFT + SPACE` | Toggle top bar |
 | `SUPER + SPACE` | Blob menu |
 | `XF86PowerOff` | Power menu |
 ## Unbound defaults
 - `SUPER + SPACE`
 - `SUPER + ALT + SPACE`
@@ -0,0 +1,91 @@
 # The shell
 `blob-shell` is one long-running Quickshell process hosting the bar, panels,
 notifications, lock screen, OSD, and both menus. Everything runs inside it as a
 plugin, so summoning a panel is an IPC call into a process that is already up.
 ## Layout
 ```
 shell/
  shell.qml            entry point
  Commons/             Style, Color, Border, Util
  Ui/                  shared components
  services/            plugin registry, bar widget registry, app library
  plugins/
    bar/               the bar and its widgets
    menu/              both menus
    notifications/     daemon, popups, DND, history
    notification-center/
    lock/  polkit/  osd/  background/  clipboard/  emojis/
    image-picker/  reminders/
    panels/            audio bluetooth clock disk-speedtest monitor network
                       power quick-settings speedtest sysmon weather wifiqr
    services/          battery idle media nightlight
 ```
 First-party plugins are discovered under `shell/plugins` at a depth of two or
 three and are enabled without being listed anywhere. Third-party plugins live in
 `~/.config/blob/plugins/<id>/` and are enabled through `shell.json`.
 ## Config
 `shell.json` is the whole bar config. It hot-reloads on save, and dragging a bar
 widget rewrites `~/.config/blob/shell.json` directly, so after rearranging by
 hand copy it back:
 ```
 cp ~/.config/blob/shell.json shell.json
 ```
 `./install.sh --check` reports the drift.
 Defaults live at `config/blob/shell.json`. A valid user file replaces them
 entirely rather than merging.
 ## Bar layout
 | Section | Widgets |
 | --- | --- |
 | left | `blob.menu`, `blob.workspaces` |
 | center | `blob.clock` (anchored), `blob.system-update` |
 | right | `blob.tray`, `blob.bluetooth`, `blob.network`, `blob.audio`, `blob.monitor`, `blob.power`, `blob.notifications` |
 `blob.clock` and `blob.notifications` are `type: "command"` modules, which is how
 they carry their own click actions: the clock opens quick settings on left click,
 the shell's calendar on middle, and the timezone picker on right; the bell opens
 the notification centre on left and toggles silencing on right.
 The centre module named by `centerAnchor` cannot be dragged out of the centre.
 Every other widget still reorders.
 ## Differences from upstream
 This shell was forked from Omarchy 4.0.4 and is not tracked against it. The
 changes beyond renaming:
 - `agents`, `tailscale`, `dropbox`, and `dev-gallery` plugins removed, about
  7,000 lines.
 - The `Dictation` bar indicator removed with voice typing.
 - Persistent workspaces 1-9 instead of 1-5.
 - Menu cards 440 wide instead of 300, with the Blob icon on the bar button.
 - The lock screen carries `branding/screensaver.txt` and an AGS-style password
  field: square corners, a 2px border on the blue slot at half alpha going to
  solid accent once typing starts, and urgent on a failed attempt.
 - `quick-settings`, `sysmon`, and `notification-center` are new, ported from the
  GTK widgets. See [widgets.md](widgets.md).
 None of these are clones or overrides. They are edits to first-party source, so
 there is no clone machinery and nothing to re-apply after an upstream release.
 The fork base is recorded in [upstream.md](upstream.md).
 ## Debugging
 ```
 journalctl --user -t blob-shell -f
 blob-shell-restart
 ```
 A QML error in a `service` plugin means that service never loads. For the lock
 that leaves the machine unlockable rather than locked open, so test it with
 `blob-shell lock lock` before trusting a change to it.
@@ -0,0 +1,68 @@
 # Themes
 A theme is a directory under `themes/` holding at minimum a `colors.toml`.
 `blob-theme-set <name>` stages it, renders every template against it, and
 retints the running desktop.
 ## What a theme can ship
 | File | Used by |
 | --- | --- |
 | `colors.toml` | required; the palette everything else derives from |
 | `backgrounds/` | the background switcher |
 | `shell.lock.toml` | lock screen surface tokens |
 | `neovim.lua` | the editor colorscheme |
 | `icons.theme` | GTK icon theme name |
 | `preview.png`, `unlock.png`, `preview-unlock.png` | theme and lock previews |
 ## colors.toml
 Named keys are preferred: `background`, `foreground`, `accent`, `muted`,
 `selection`, the eight base colors, and their `bright_` variants. The pywal
 `color0`..`color15` form also works and is resolved through the same cascade:
 `color0` is the background, `color4` is blue, `color5` is magenta.
 That cascade lives in `blob-theme-color`, and `Commons/Color.qml` mirrors it so
 the shell and the CLI never disagree about what a slot means.
 ## Templates
 `default/themed/*.tpl` are rendered per theme into
 `~/.local/state/blob/current/theme/`. Nine ship: foot, kitty, btop, chromium,
 hyprland, the screenshare picker, neovim, `shell.toml`, and zen.
 An app picks its colors up in one of two ways. Most include the generated file
 directly, so nothing has to run:
 ```
 include ~/.local/state/blob/current/theme/kitty.conf
 ```
 Zen does the same through a CSS import in `userChrome.css`. The rest are pushed
 by a short applier listed in `post_theme_commands` inside `blob-theme-set`:
 `blob-theme-foot`, `blob-theme-browser`, `blob-restart-terminal`,
 `blob-restart-btop`, `blob-hypr-restart`.
 Adding a template for another app means dropping a `.tpl` in `default/themed/`
 and, if it cannot include a file, adding an applier to that list.
 ## The three ways to set a theme
 | Command | Does |
 | --- | --- |
 | `blob theme menu` | pick from the bundled and local sets |
 | `blob theme set <name>` | apply one by name |
 | `blob wallpaper set <image>` | extract a palette from a wallpaper with pywal, fix flat palettes with `blob-theme-contrast`, and apply it as `blob-dynamic` |
 | `blob theme share <link>` | fetch a shared palette and apply it as `blob-dynamic` |
 Aether is also installed and does the same job with a GUI. To have its palettes
 land where these do, add Blob as a custom app in Aether with a template writing
 `colors.toml` into `~/.local/state/blob/current/theme/` and a post-apply hook
 calling `blob-theme-refresh`.
 ## Bundled themes
 Twenty-two came across from upstream, plus `flats` and `pitch-dark`. Their
 `backgrounds/` directories are empty on purpose: the upstream images were
 Omarchy branding, and `~/wallpapers` holds 103 of your own. A theme with no
 background of its own leaves the current wallpaper alone.
@@ -0,0 +1,10 @@
 #!/bin/bash
 # This hook is called with the current battery percentage when the low battery
 # notification is sent. To put it into use, remove .sample from the name.
 SOUND_FILE="/usr/share/sounds/freedesktop/stereo/dialog-warning.oga"
 if blob-cmd-present mpv && [[ -f $SOUND_FILE ]]; then
  mpv --no-video "$SOUND_FILE" >/dev/null 2>&1
 fi
@@ -0,0 +1,7 @@
 #!/bin/bash
 # This hook is called with the snake-cased name of the font that has just been set.
 # To put it into use, remove .sample from the name.
 # Example: Show the name of the theme that was just set.
 # notify-send -u low "New font" "Your new font is $1"
@@ -0,0 +1,7 @@
 #!/bin/bash
 # This hook is called after an Blob system update has been performed.
 # To put it into use, remove .sample from the name.
 # Example: Show notification after the system has been updated.
 # notify-send -u low "Update Performed" "Your system is now up to date"
@@ -0,0 +1,7 @@
 #!/bin/bash
 # This hook is called with the snake-cased name of the theme that has just been set.
 # To put it into use, remove .sample from the name.
 # Example: Show the name of the theme that was just set.
 # notify-send -u low "New theme" "Your new theme is $1"
@@ -0,0 +1,196 @@
 #!/bin/bash
 set -e
 repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 blob_path="$HOME/.local/share/blob"
 config_dir="$HOME/.config"
 state_dir="$HOME/.local/state/blob"
 session_dir="/usr/share/wayland-sessions"
 font_dir="$HOME/.local/share/fonts"
 force=false
 check=false
 changes=0
 usage() {
  cat <<USAGE
 Usage: ./install.sh [OPTIONS]
  --check    Report what would change, write nothing
  --force    Overwrite files that have local changes
  --help     Show this message
 USAGE
  exit 0
 }
 while (( $# > 0 )); do
  case "$1" in
    --force) force=true; shift ;;
    --check) check=true; shift ;;
    --help) usage ;;
    *) echo "Unknown option: $1" >&2; usage ;;
  esac
 done
 say() {
  printf '%s\n' "$1"
 }
 note_change() {
  changes=$((changes + 1))
 }
 # BLOB_PATH is a symlink to this checkout rather than a copy, so bin/, shell/,
 # themes/ and default/ are always the working tree. Every path the shell
 # resolves as $BLOB_PATH/... therefore needs no install step at all.
 link_blob_path() {
  local current=""
  [[ -L $blob_path ]] && current="$(readlink -f "$blob_path")"
  if [[ $current == "$repo_dir" ]]; then
    say "ok    BLOB_PATH -> $repo_dir"
    return
  fi
  if [[ -e $blob_path && ! -L $blob_path ]]; then
    say "WARN  $blob_path exists and is not a symlink; move it aside first"
    note_change
    return
  fi
  note_change
  if [[ $check == true ]]; then
    say "would link BLOB_PATH -> $repo_dir"
    return
  fi
  ln -sfn "$repo_dir" "$blob_path"
  say "link  BLOB_PATH -> $repo_dir"
 }
 # Copy a file only when the destination is missing or matches what we last
 # wrote. A destination that differs is a local edit, reported and kept unless
 # --force says otherwise.
 install_file() {
  local source="$1" dest="$2" label="$3"
  if [[ ! -e $source ]]; then
    say "SKIP  $label (missing in repo)"
    return
  fi
  if [[ -e $dest ]] && cmp -s "$source" "$dest"; then
    say "ok    $label"
    return
  fi
  note_change
  if [[ -e $dest ]] && [[ $force == false ]]; then
    say "DIFF  $label (local changes kept; --force to overwrite)"
    return
  fi
  if [[ $check == true ]]; then
    say "would write $label"
    return
  fi
  mkdir -p "$(dirname "$dest")"
  [[ -e $dest ]] && cp "$dest" "$dest.bak"
  cp "$source" "$dest"
  say "write $label"
 }
 install_tree() {
  local source="$1" dest="$2" label="$3"
  if [[ ! -d $source ]]; then
    say "SKIP  $label (missing in repo)"
    return
  fi
  local relative
  while IFS= read -r relative; do
    install_file "$source/$relative" "$dest/$relative" "$label/$relative"
  done < <(cd "$source" && find . -type f -printf '%P\n' | sort)
 }
 install_session_entry() {
  local source="$repo_dir/session/blob.desktop"
  local dest="$session_dir/blob.desktop"
  if [[ -e $dest ]] && cmp -s "$source" "$dest"; then
    say "ok    wayland session entry"
    return
  fi
  note_change
  if [[ $check == true ]]; then
    say "would install wayland session entry (needs sudo)"
    return
  fi
  sudo install -Dm644 "$source" "$dest"
  say "write wayland session entry"
 }
 say "Blob installer"
 say "repo: $repo_dir"
 if [[ $check == true ]]; then
  say "mode: check (nothing will be written)"
 fi
 say ""
 link_blob_path
 if [[ $check == false ]]; then
  mkdir -p "$state_dir"/{toggles/hypr,indicators,notifications}
  mkdir -p "$config_dir/blob"/{hooks,extensions,plugins,themed,themes}
  mkdir -p "$HOME/wallpapers"
 fi
 install_tree "$repo_dir/hypr" "$config_dir/hypr" "hypr"
 # config/ is the shipped-defaults directory. Everything in it is reachable as
 # $BLOB_PATH/config/... so `blob-refresh-config` can reset a file, and most of it
 # is also the right thing to deploy on a fresh install. Two subdirectories are
 # reference-only and must not be copied into ~/.config:
 #
 #   blob/  the shell defaults; copying them over ~/.config/blob/shell.json would
 #          replace the user's bar layout with the stock one
 #   hypr/  the stock Hyprland config; the personal hypr/ below is authoritative
 #          and is installed to the same place
 for entry in "$repo_dir"/config/*; do
  entry_name="$(basename "$entry")"
  [[ $entry_name == blob || $entry_name == hypr ]] && continue
  if [[ -d $entry ]]; then
    install_tree "$entry" "$config_dir/$entry_name" "config/$entry_name"
  else
    install_file "$entry" "$config_dir/$entry_name" "config/$entry_name"
  fi
 done
 install_tree "$repo_dir/hooks" "$config_dir/blob/hooks" "hooks"
 install_tree "$repo_dir/branding" "$config_dir/blob/branding" "branding"
 install_file "$repo_dir/shell.json" "$config_dir/blob/shell.json" "shell.json"
 install_file "$repo_dir/session/uwsm/default" "$config_dir/uwsm/default" "uwsm/default"
 install_file "$repo_dir/session/uwsm/env.d/10-blob" "$config_dir/uwsm/env.d/10-blob" "uwsm/env.d/10-blob"
 install_file "$repo_dir/fonts/omarchy.ttf" "$font_dir/omarchy.ttf" "fonts/omarchy.ttf"
 install_session_entry
 zen_profile="$(find "$config_dir/zen" -maxdepth 1 -type d -name '*.Default (release)*' 2>/dev/null | head -1)"
 if [[ -n $zen_profile ]]; then
  install_file "$repo_dir/zen/userChrome.css" "$zen_profile/chrome/userChrome.css" "zen/userChrome.css"
 else
  say "SKIP  zen/userChrome.css (no Zen profile found)"
 fi
 say ""
 if [[ $check == true ]]; then
  say "$changes item(s) would change."
  (( changes == 0 )) || exit 1
 else
  say "$changes item(s) changed."
  say ""
  say "Next: log out and pick the Blob session, then run 'blob theme set <name>'."
 fi
@@ -0,0 +1,94 @@
 #!/bin/bash
 set -e
 blob_path="$HOME/.local/share/blob"
 config_dir="$HOME/.config"
 session_entry="/usr/share/wayland-sessions/blob.desktop"
 keep_state=false
 assume_yes=false
 usage() {
  cat <<USAGE
 Usage: ./uninstall.sh [OPTIONS]
 Removes what install.sh wrote. The checkout itself is never touched.
  --keep-state   Leave ~/.local/state/blob in place
  --yes          Do not prompt
  --help         Show this message
 USAGE
  exit 0
 }
 while (( $# > 0 )); do
  case "$1" in
    --keep-state) keep_state=true; shift ;;
    --yes) assume_yes=true; shift ;;
    --help) usage ;;
    *) echo "Unknown option: $1" >&2; usage ;;
  esac
 done
 say() {
  printf '%s\n' "$1"
 }
 restore_or_remove() {
  local path="$1" label="$2"
  if [[ -e $path.bak ]]; then
    mv "$path.bak" "$path"
    say "restore $label (from .bak)"
    return
  fi
  if [[ -e $path ]]; then
    rm -f "$path"
    say "remove  $label"
  fi
 }
 say "This removes the Blob session, its config, and the BLOB_PATH symlink."
 say "Your checkout, wallpapers, and themes stay where they are."
 if [[ $keep_state == false ]]; then
  say "It also removes ~/.local/state/blob (active theme, toggles, notifications)."
 fi
 say ""
 if [[ $assume_yes == false ]]; then
  read -rp "Continue? [y/N] " answer
  [[ $answer == [yY] ]] || exit 0
 fi
 if [[ -L $blob_path ]]; then
  rm -f "$blob_path"
  say "remove  BLOB_PATH symlink"
 fi
 for relative in blob/shell.json uwsm/default uwsm/env.d/10-blob; do
  restore_or_remove "$config_dir/$relative" "$relative"
 done
 if [[ -d $config_dir/blob ]]; then
  rm -rf "$config_dir/blob"
  say "remove  ~/.config/blob"
 fi
 for lua in hyprland.lua monitors.lua input.lua looknfeel.lua bindings.lua autostart.lua hyprsunset.conf xdph.conf; do
  restore_or_remove "$config_dir/hypr/$lua" "hypr/$lua"
 done
 if [[ $keep_state == false && -d $HOME/.local/state/blob ]]; then
  rm -rf "$HOME/.local/state/blob"
  say "remove  ~/.local/state/blob"
 fi
 if [[ -e $session_entry ]]; then
  sudo rm -f "$session_entry"
  say "remove  wayland session entry"
 fi
 say ""
 say "Done. Pick another session at the login screen before rebooting."
		`@@ -0,0 +1,2 @@`
							`-- Extra autostart processes.`
							`-- o.launch_on_start("my-service")`