From 935f074d9a0031c5a337421f81b2080ca34ba419 Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Wed, 15 Apr 2026 16:57:59 -0400
Subject: [PATCH 1/8] feat: add lib/common.sh with shared constants and helpers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract repeated patterns from task scripts:
- Path constants (WALLPAPERS_OUTPUT_DIR, CONFIG_FILE, STATE_DIR)
- detect_screen_resolution() — replaces 5 copies of system_profiler pipeline
- resolution_width/height() — replaces cut -d'x' pattern
- require_command() — replaces ad-hoc command -v checks
- require_config() — replaces ad-hoc config file checks
---
 lib/common.sh | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 lib/common.sh

diff --git a/lib/common.sh b/lib/common.sh
new file mode 100644
index 0000000..00ecc03
--- /dev/null
+++ b/lib/common.sh
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Shared constants and helpers for wallpapers tasks.
+
+# Paths
+WALLPAPERS_OUTPUT_DIR="$HOME/.local/share/wallpapers"
+WALLPAPERS_CONFIG_DIR="$HOME/.config/wallpapers"
+WALLPAPERS_CONFIG_FILE="$WALLPAPERS_CONFIG_DIR/config.json"
+WALLPAPERS_STATE_DIR="$HOME/.local/state/wallpapers"
+
+# Detect the primary screen resolution.
+# Outputs WxH (e.g. "3024x1964"). Returns 1 if detection fails.
+detect_screen_resolution() {
+  local res
+  res=$(system_profiler SPDisplaysDataType 2>/dev/null \
+    | grep -i "Resolution:" \
+    | head -1 \
+    | sed 's/.*: //' \
+    | sed 's/ Retina//' \
+    | sed 's/ //g')
+  if [[ -z "$res" ]]; then
+    echo "error: could not detect screen resolution" >&2
+    return 1
+  fi
+  echo "$res"
+}
+
+# Extract width from a WxH resolution string.
+resolution_width() {
+  echo "${1%%x*}"
+}
+
+# Extract height from a WxH resolution string.
+resolution_height() {
+  echo "${1#*x}"
+}
+
+# Check that a command exists, exit with a styled error if not.
+# Usage: require_command <cmd> [install hint]
+require_command() {
+  local cmd="$1"
+  local hint="${2:-}"
+  if ! command -v "$cmd" &>/dev/null; then
+    if command -v gum &>/dev/null; then
+      gum style --foreground 196 "❌ $cmd not found.${hint:+ $hint}"
+    else
+      echo "error: $cmd not found.${hint:+ $hint}" >&2
+    fi
+    exit 1
+  fi
+}
+
+# Check that the config file exists, exit with error if not.
+require_config() {
+  if [[ ! -f "$WALLPAPERS_CONFIG_FILE" ]]; then
+    if command -v gum &>/dev/null; then
+      gum style --foreground 196 "❌ Config not found. Run: wallpapers config init"
+    else
+      echo "error: config not found at $WALLPAPERS_CONFIG_FILE" >&2
+    fi
+    exit 1
+  fi
+}

From 1efddf0c46a879677894f34aac008475ff41a9d8 Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Wed, 15 Apr 2026 16:58:06 -0400
Subject: [PATCH 2/8] refactor: use lib/common.sh across all task scripts

- Source common.sh for shared paths and helpers
- Replace inline system_profiler with detect_screen_resolution()
- Replace ad-hoc command/config checks with require_command/require_config
- Replace BASH_SOURCE gymnastics with $MISE_CONFIG_ROOT
- Add #USAGE headers to cli task
- Update ai task reference from CLAUDE.md to README.md
---
 .mise/tasks/ai                 |  2 +-
 .mise/tasks/apply/_default     | 28 +++++++++-------------------
 .mise/tasks/apply/undo         |  8 +++-----
 .mise/tasks/clean              |  7 +++----
 .mise/tasks/cli                |  8 ++++++++
 .mise/tasks/config/edit        | 12 +++---------
 .mise/tasks/config/init        | 16 +++++++---------
 .mise/tasks/generate           | 11 +++++------
 .mise/tasks/goto               | 23 +++++++----------------
 .mise/tasks/hammerspoon/config |  2 +-
 .mise/tasks/info/list          |  9 ++++-----
 .mise/tasks/info/resolution    |  6 ++++--
 .mise/tasks/open               |  7 +++----
 .mise/tasks/quick              | 13 ++++++-------
 .mise/tasks/shell              |  3 +--
 .mise/tasks/tutorial/apply     |  5 +++--
 .mise/tasks/tutorial/generate  |  5 +++--
 .mise/tasks/tutorial/navigate  |  5 +++--
 18 files changed, 74 insertions(+), 96 deletions(-)

diff --git a/.mise/tasks/ai b/.mise/tasks/ai
index 02016f9..b26f70d 100755
--- a/.mise/tasks/ai
+++ b/.mise/tasks/ai
@@ -5,7 +5,7 @@ cat << 'EOF'
 # Wallpapers
 
 > llms.txt for AI agents helping users USE this tool.
-> For agents working ON the codebase, see CLAUDE.md.
+> For agents working ON the codebase, see the Development section in README.md.
 
 ## Overview
 
diff --git a/.mise/tasks/apply/_default b/.mise/tasks/apply/_default
index c2ddbe5..62ed58a 100755
--- a/.mise/tasks/apply/_default
+++ b/.mise/tasks/apply/_default
@@ -7,20 +7,10 @@
 #USAGE flag "--apps" help="Only launch and position apps"
 #USAGE flag "--clean" help="Close previous app windows before applying"
 set -e
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
-OUTPUT_DIR="$HOME/.local/share/wallpapers"
-CONFIG_FILE="$HOME/.config/wallpapers/config.json"
-
-if [ ! -f "$CONFIG_FILE" ]; then
-    gum style --foreground 196 "❌ Config not found. Run: mise run config:init"
-    exit 1
-fi
-
-# Require butthair (manages Hammerspoon backend)
-if ! command -v butthair &>/dev/null; then
-    gum style --foreground 196 "❌ butthair not found. Install with: shiv install butthair"
-    exit 1
-fi
+require_config
+require_command butthair "Install with: shiv install butthair"
 
 # Require Hammerspoon via butthair
 APP_PATH="/Applications/Hammerspoon.app"
@@ -51,13 +41,13 @@ cache_bust() {
 }
 
 # Auto-detect screen resolution
-SCREEN_RES=$(system_profiler SPDisplaysDataType | grep -i "Resolution:" | head -1 | sed 's/.*: //' | sed 's/ Retina//' | sed 's/ //g')
-SCREEN_W=$(echo "$SCREEN_RES" | cut -d'x' -f1)
-SCREEN_H=$(echo "$SCREEN_RES" | cut -d'x' -f2)
+SCREEN_RES=$(detect_screen_resolution)
+SCREEN_W=$(resolution_width "$SCREEN_RES")
+SCREEN_H=$(resolution_height "$SCREEN_RES")
 
 # Apply to all spaces
 {
-    CONFIG_COUNT=$(jq 'if .spaces then .spaces | length elif .workspaces then .workspaces | length else 0 end' "$CONFIG_FILE")
+    CONFIG_COUNT=$(jq 'if .spaces then .spaces | length elif .workspaces then .workspaces | length else 0 end' "$WALLPAPERS_CONFIG_FILE")
 
     SPACE_COUNT=$(butthair spaces:list -- -j 2>/dev/null | jq 'length')
     if [ -z "$SPACE_COUNT" ] || [ "$SPACE_COUNT" = "0" ]; then
@@ -131,7 +121,7 @@ SCREEN_H=$(echo "$SCREEN_RES" | cut -d'x' -f2)
         USABLE_H=$(echo "$SCREEN_JSON" | jq '.usable.h')
         USABLE_Y=$(echo "$SCREEN_JSON" | jq '.usable.y')
 
-        GAP=$(jq '.defaults.gap // 8' "$CONFIG_FILE")
+        GAP=$(jq '.defaults.gap // 8' "$WALLPAPERS_CONFIG_FILE")
 
         STATE_FILE="$HOME/.local/share/wallpapers/.apply-state"
         mkdir -p "$(dirname "$STATE_FILE")"
@@ -165,7 +155,7 @@ SCREEN_H=$(echo "$SCREEN_RES" | cut -d'x' -f2)
 
         for s in $(seq 0 $((CONFIG_COUNT - 1))); do
             SPACE_NUM=$((s + 1))
-            ZONES_JSON=$(jq -c ".spaces[$s].zones" "$CONFIG_FILE")
+            ZONES_JSON=$(jq -c ".spaces[$s].zones" "$WALLPAPERS_CONFIG_FILE")
             ZONE_COUNT=$(echo "$ZONES_JSON" | jq 'length')
 
             # Skip spaces with no apps
diff --git a/.mise/tasks/apply/undo b/.mise/tasks/apply/undo
index 40d6fe6..85e596e 100755
--- a/.mise/tasks/apply/undo
+++ b/.mise/tasks/apply/undo
@@ -1,12 +1,10 @@
 #!/usr/bin/env bash
 #MISE description="Close windows created by the last 'apply --apps'"
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
-STATE_FILE="$HOME/.local/share/wallpapers/.apply-state"
+STATE_FILE="$WALLPAPERS_OUTPUT_DIR/.apply-state"
 
-if ! command -v butthair &>/dev/null; then
-    gum style --foreground 196 "❌ butthair not found. Install with: shiv install butthair"
-    exit 1
-fi
+require_command butthair "Install with: shiv install butthair"
 
 if [ ! -f "$STATE_FILE" ] || [ ! -s "$STATE_FILE" ]; then
     echo "Nothing to undo."
diff --git a/.mise/tasks/clean b/.mise/tasks/clean
index 6ff79f3..bd09888 100755
--- a/.mise/tasks/clean
+++ b/.mise/tasks/clean
@@ -1,10 +1,9 @@
 #!/usr/bin/env bash
 #MISE description="Remove all generated wallpapers"
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
-OUTPUT_DIR="$HOME/.local/share/wallpapers"
-
-if gum confirm "Delete all generated wallpapers from $OUTPUT_DIR?"; then
-    rm -rf "$OUTPUT_DIR"/*.png
+if gum confirm "Delete all generated wallpapers from $WALLPAPERS_OUTPUT_DIR?"; then
+    rm -rf "$WALLPAPERS_OUTPUT_DIR"/*.png
     gum style --foreground 46 "✅ Cleaned wallpapers directory"
 else
     gum style --foreground 244 "Cancelled"
diff --git a/.mise/tasks/cli b/.mise/tasks/cli
index 46c3337..21432b2 100755
--- a/.mise/tasks/cli
+++ b/.mise/tasks/cli
@@ -1,3 +1,11 @@
 #!/usr/bin/env bash
 #MISE description="Run generator directly with arguments"
+#USAGE arg "<name>" help="Workspace name"
+#USAGE flag "-d --description <desc>" help="Subtitle text"
+#USAGE flag "-r --resolution <res>" help="Preset: 1080p, 1440p, 4k, macbook-14, macbook-16, imac-24, studio-display"
+#USAGE flag "--width <w>" help="Custom width"
+#USAGE flag "--height <h>" help="Custom height"
+#USAGE flag "--bg-color <color>" help="Background hex color"
+#USAGE flag "--text-color <color>" help="Text hex color"
+#USAGE flag "--style <style>" help="Visual style: classic, diagonal, tiled, flowfield, typography, perspective"
 swift run generate -- "$@"
diff --git a/.mise/tasks/config/edit b/.mise/tasks/config/edit
index e0bd33f..31fd326 100755
--- a/.mise/tasks/config/edit
+++ b/.mise/tasks/config/edit
@@ -1,13 +1,7 @@
 #!/usr/bin/env bash
 #MISE description="Edit config file in your editor"
 set -e
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
-CONFIG_FILE="$HOME/.config/wallpapers/config.json"
-
-if [ ! -f "$CONFIG_FILE" ]; then
-    gum style --foreground 196 "❌ Config not found at $CONFIG_FILE"
-    gum style --foreground 245 "Run: mise run config:init"
-    exit 1
-fi
-
-${EDITOR:-nano} "$CONFIG_FILE"
+require_config
+${EDITOR:-nano} "$WALLPAPERS_CONFIG_FILE"
diff --git a/.mise/tasks/config/init b/.mise/tasks/config/init
index e5787d5..7c0eebf 100755
--- a/.mise/tasks/config/init
+++ b/.mise/tasks/config/init
@@ -1,23 +1,21 @@
 #!/usr/bin/env bash
 #MISE description="Initialize config file with example workspaces"
 set -e
-
-CONFIG_DIR="$HOME/.config/wallpapers"
-CONFIG_FILE="$CONFIG_DIR/config.json"
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
 # Check if config already exists
-if [ -f "$CONFIG_FILE" ]; then
-    if ! gum confirm "Config already exists at $CONFIG_FILE. Overwrite?"; then
+if [ -f "$WALLPAPERS_CONFIG_FILE" ]; then
+    if ! gum confirm "Config already exists at $WALLPAPERS_CONFIG_FILE. Overwrite?"; then
         gum style --foreground 226 "⚠️  Cancelled"
         exit 0
     fi
 fi
 
 # Create config directory
-mkdir -p "$CONFIG_DIR"
+mkdir -p "$WALLPAPERS_CONFIG_DIR"
 
 # Write template config
-cat > "$CONFIG_FILE" << 'EOF'
+cat > "$WALLPAPERS_CONFIG_FILE" << 'EOF'
 {
   "workspaces": [
     {
@@ -44,5 +42,5 @@ cat > "$CONFIG_FILE" << 'EOF'
 }
 EOF
 
-gum style --foreground 46 "✅ Config created at $CONFIG_FILE"
-gum style --foreground 245 "Edit with: mise run config:edit"
+gum style --foreground 46 "✅ Config created at $WALLPAPERS_CONFIG_FILE"
+gum style --foreground 245 "Edit with: wallpapers config edit"
diff --git a/.mise/tasks/generate b/.mise/tasks/generate
index 862aec4..3786a29 100755
--- a/.mise/tasks/generate
+++ b/.mise/tasks/generate
@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
 #MISE description="Generate a wallpaper interactively"
 set -e
-
-OUTPUT_DIR="$HOME/.local/share/wallpapers"
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
 # Styled header
 gum style \
@@ -28,9 +27,9 @@ if gum confirm "Add a description?"; then
 fi
 
 # Detect current screen resolution
-SCREEN_RES=$(system_profiler SPDisplaysDataType | grep -i "Resolution:" | head -1 | sed 's/.*: //' | sed 's/ Retina//' | sed 's/ //g')
-SCREEN_W=$(echo "$SCREEN_RES" | cut -d'x' -f1)
-SCREEN_H=$(echo "$SCREEN_RES" | cut -d'x' -f2)
+SCREEN_RES=$(detect_screen_resolution)
+SCREEN_W=$(resolution_width "$SCREEN_RES")
+SCREEN_H=$(resolution_height "$SCREEN_RES")
 
 # Select resolution
 RESOLUTION=$(gum choose --header "📐 Select resolution:" \
@@ -101,7 +100,7 @@ gum spin --spinner dot --title "Generating wallpaper..." -- \
         --style "$STYLE" \
         $DESC_ARG ${DESCRIPTION:+"$DESCRIPTION"}
 
-gum style --foreground 46 "✅ Wallpaper generated! Saved to $OUTPUT_DIR"
+gum style --foreground 46 "✅ Wallpaper generated! Saved to $WALLPAPERS_OUTPUT_DIR"
 
 # Show the generated files
 ls -la "$OUTPUT_DIR"
diff --git a/.mise/tasks/goto b/.mise/tasks/goto
index 7aa7ee0..92dea19 100755
--- a/.mise/tasks/goto
+++ b/.mise/tasks/goto
@@ -3,21 +3,12 @@
 #USAGE arg "[name]" help="Workspace name/id, or '-' to go back (shows picker if omitted)"
 #USAGE complete "name" run="jq -r '.workspaces[] | (.id // .name) + \":\" + (.description // .name)' ~/.config/wallpapers/config.json 2>/dev/null" descriptions=#true
 set -e
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
-CONFIG_FILE="$HOME/.config/wallpapers/config.json"
-STATE_DIR="$HOME/.local/state/wallpapers"
-PREVIOUS_FILE="$STATE_DIR/previous-space"
+PREVIOUS_FILE="$WALLPAPERS_STATE_DIR/previous-space"
 
-if [ ! -f "$CONFIG_FILE" ]; then
-    gum style --foreground 196 "❌ Config not found. Run: mise run config:init"
-    exit 1
-fi
-
-# Require butthair
-if ! command -v butthair &>/dev/null; then
-    gum style --foreground 196 "❌ butthair not found. Install with: shiv install butthair"
-    exit 1
-fi
+require_config
+require_command butthair "Install with: shiv install butthair"
 
 # Get current space
 CURRENT=$(butthair spaces:current -- -i 2>/dev/null)
@@ -42,7 +33,7 @@ if [ "$TARGET" = "-" ]; then
     fi
 # Handle no argument (show picker)
 elif [ -z "$TARGET" ]; then
-    WORKSPACES=$(jq -r '.workspaces | to_entries[] | "\(.key + 1). \(.value.name)"' "$CONFIG_FILE")
+    WORKSPACES=$(jq -r '.workspaces | to_entries[] | "\(.key + 1). \(.value.name)"' "$WALLPAPERS_CONFIG_FILE")
 
     SELECTION=$(echo "$WORKSPACES" | gum choose --header "Go to workspace:")
 
@@ -64,7 +55,7 @@ else
             or (.value.name | ascii_downcase) == $search
         ) |
         .key + 1
-    ' "$CONFIG_FILE")
+    ' "$WALLPAPERS_CONFIG_FILE")
 
     if [ -z "$TARGET_INDEX" ]; then
         gum style --foreground 196 "❌ Workspace not found: $TARGET"
@@ -78,7 +69,7 @@ else
 fi
 
 # Save current space before navigating
-mkdir -p "$STATE_DIR"
+mkdir -p "$WALLPAPERS_STATE_DIR"
 echo "$CURRENT" > "$PREVIOUS_FILE"
 
 # Navigate
diff --git a/.mise/tasks/hammerspoon/config b/.mise/tasks/hammerspoon/config
index 3be5506..a308e1c 100755
--- a/.mise/tasks/hammerspoon/config
+++ b/.mise/tasks/hammerspoon/config
@@ -7,7 +7,7 @@ CONFIG_FILE="$CONFIG_DIR/init.lua"
 WP_MODULE="$CONFIG_DIR/wp.lua"
 APP_PATH="/Applications/Hammerspoon.app"
 HS_CLI="$APP_PATH/Contents/Frameworks/hs/hs"
-REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+REPO_DIR="$MISE_CONFIG_ROOT"
 
 # Require butthair to have set up Hammerspoon first
 if [ ! -f "$CONFIG_FILE" ]; then
diff --git a/.mise/tasks/info/list b/.mise/tasks/info/list
index a6091ae..20b2aa5 100755
--- a/.mise/tasks/info/list
+++ b/.mise/tasks/info/list
@@ -1,11 +1,10 @@
 #!/usr/bin/env bash
 #MISE description="List generated wallpapers"
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
-OUTPUT_DIR="$HOME/.local/share/wallpapers"
-
-if [ -d "$OUTPUT_DIR" ] && [ "$(ls -A "$OUTPUT_DIR" 2>/dev/null)" ]; then
+if [ -d "$WALLPAPERS_OUTPUT_DIR" ] && [ "$(ls -A "$WALLPAPERS_OUTPUT_DIR" 2>/dev/null)" ]; then
     gum style --foreground 212 --bold "📁 Generated Wallpapers:"
-    ls -lh "$OUTPUT_DIR"/*.png 2>/dev/null | awk '{print "  " $9 " (" $5 ")"}'
+    ls -lh "$WALLPAPERS_OUTPUT_DIR"/*.png 2>/dev/null | awk '{print "  " $9 " (" $5 ")"}'
 else
-    gum style --foreground 244 "No wallpapers generated yet. Run 'mise run generate' to create one."
+    gum style --foreground 244 "No wallpapers generated yet. Run 'wallpapers generate' to create one."
 fi
diff --git a/.mise/tasks/info/resolution b/.mise/tasks/info/resolution
index eb3e00b..626b030 100755
--- a/.mise/tasks/info/resolution
+++ b/.mise/tasks/info/resolution
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 #MISE description="Show your screen resolution"
-SCREEN_RES=$(system_profiler SPDisplaysDataType | grep -i "Resolution:" | head -1 | sed 's/.*: //' | sed 's/ Retina//' | sed 's/ //g')
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
+
+SCREEN_RES=$(detect_screen_resolution)
 gum style --foreground 212 "🖥️ Your screen resolution: $SCREEN_RES"
-gum style --foreground 244 "Use 'mise run quick' to auto-generate at this size"
+gum style --foreground 244 "Use 'wallpapers quick' to auto-generate at this size"
diff --git a/.mise/tasks/open b/.mise/tasks/open
index e010268..3196f00 100755
--- a/.mise/tasks/open
+++ b/.mise/tasks/open
@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
 #MISE description="Open the wallpapers directory in Finder"
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
-OUTPUT_DIR="$HOME/.local/share/wallpapers"
-
-mkdir -p "$OUTPUT_DIR"
-open "$OUTPUT_DIR"
+mkdir -p "$WALLPAPERS_OUTPUT_DIR"
+open "$WALLPAPERS_OUTPUT_DIR"
diff --git a/.mise/tasks/quick b/.mise/tasks/quick
index 5acc18b..f1c7726 100755
--- a/.mise/tasks/quick
+++ b/.mise/tasks/quick
@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
 #MISE description="Quick generate with just a name (auto-detects screen resolution)"
 set -e
-
-OUTPUT_DIR="$HOME/.local/share/wallpapers"
+source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
 NAME=$(gum input --placeholder "Workspace name" --prompt "📝 Quick generate: ")
 
@@ -12,17 +11,17 @@ if [ -z "$NAME" ]; then
 fi
 
 # Auto-detect screen resolution
-SCREEN_RES=$(system_profiler SPDisplaysDataType | grep -i "Resolution:" | head -1 | sed 's/.*: //' | sed 's/ Retina//' | sed 's/ //g')
-SCREEN_W=$(echo "$SCREEN_RES" | cut -d'x' -f1)
-SCREEN_H=$(echo "$SCREEN_RES" | cut -d'x' -f2)
+SCREEN_RES=$(detect_screen_resolution)
+SCREEN_W=$(resolution_width "$SCREEN_RES")
+SCREEN_H=$(resolution_height "$SCREEN_RES")
 
 gum spin --spinner dot --title "Generating at ${SCREEN_W}x${SCREEN_H}..." -- \
     swift run generate -- "$NAME" --width "$SCREEN_W" --height "$SCREEN_H"
 
-gum style --foreground 46 "✅ Generated! Saved to $OUTPUT_DIR"
+gum style --foreground 46 "✅ Generated! Saved to $WALLPAPERS_OUTPUT_DIR"
 
 # Get the most recently created wallpaper (the one we just generated)
-WALLPAPER_PATH="$(ls -t "$OUTPUT_DIR"/*.png | head -1)"
+WALLPAPER_PATH="$(ls -t "$WALLPAPERS_OUTPUT_DIR"/*.png | head -1)"
 
 # Set wallpaper for current desktop
 gum spin --spinner dot --title "Setting wallpaper..." -- \
diff --git a/.mise/tasks/shell b/.mise/tasks/shell
index a837e66..2303b45 100755
--- a/.mise/tasks/shell
+++ b/.mise/tasks/shell
@@ -1,4 +1,3 @@
 #!/usr/bin/env bash
 #MISE description="Output shell configuration (use with eval)"
-REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-echo "alias wp='mise -C \"$REPO_DIR\" run'"
+echo "alias wp='mise -C \"${MISE_CONFIG_ROOT}\" run'"
diff --git a/.mise/tasks/tutorial/apply b/.mise/tasks/tutorial/apply
index edd90e2..0824988 100755
--- a/.mise/tasks/tutorial/apply
+++ b/.mise/tasks/tutorial/apply
@@ -12,7 +12,8 @@ done
 
 # Constants
 OUTPUT_DIR="$HOME/.local/share/wallpapers"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+# shellcheck disable=SC2154
+SCRIPT_DIR="$MISE_CONFIG_ROOT"
 
 # Header
 echo ""
@@ -23,7 +24,7 @@ gum style \
 echo ""
 
 # Show current space info
-SPACE_INFO=$(swift "$SCRIPT_DIR/src/current-space.swift" 2>/dev/null || echo "1/1")
+SPACE_INFO=$(swift "$MISE_CONFIG_ROOT/src/current-space.swift" 2>/dev/null || echo "1/1")
 CURRENT_SPACE=$(echo "$SPACE_INFO" | cut -d'/' -f1)
 TOTAL_SPACES=$(echo "$SPACE_INFO" | cut -d'/' -f2)
 
diff --git a/.mise/tasks/tutorial/generate b/.mise/tasks/tutorial/generate
index 2cb0525..c9010d6 100755
--- a/.mise/tasks/tutorial/generate
+++ b/.mise/tasks/tutorial/generate
@@ -12,7 +12,8 @@ done
 
 # Constants
 OUTPUT_DIR="$HOME/.local/share/wallpapers"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+# shellcheck disable=SC2154
+SCRIPT_DIR="$MISE_CONFIG_ROOT"
 
 # Header
 echo ""
@@ -53,7 +54,7 @@ if gum confirm "Generate a demo wallpaper now?"; then
     mkdir -p "$OUTPUT_DIR"
 
     gum spin --spinner dot --title "Generating wallpaper..." -- \
-        swift "$SCRIPT_DIR/src/generate.swift" "$DEMO_NAME" \
+        swift "$MISE_CONFIG_ROOT/src/generate.swift" "$DEMO_NAME" \
         --width "$SCREEN_W" --height "$SCREEN_H" \
         --bg-color "#1a1a2e"
 
diff --git a/.mise/tasks/tutorial/navigate b/.mise/tasks/tutorial/navigate
index 19488e3..1418ad8 100755
--- a/.mise/tasks/tutorial/navigate
+++ b/.mise/tasks/tutorial/navigate
@@ -11,7 +11,8 @@ for cmd in gum swift jq; do
 done
 
 # Constants
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+# shellcheck disable=SC2154
+SCRIPT_DIR="$MISE_CONFIG_ROOT"
 USER_CONFIG="$HOME/.config/wallpapers/config.json"
 STATE_DIR="$HOME/.local/state/wallpapers"
 ACTIVE_CONFIG_FILE="$STATE_DIR/tutorial-active-config"
@@ -58,7 +59,7 @@ else
 fi
 
 # Get current space info
-SPACE_INFO=$(swift "$SCRIPT_DIR/src/current-space.swift" 2>/dev/null || echo "1/1")
+SPACE_INFO=$(swift "$MISE_CONFIG_ROOT/src/current-space.swift" 2>/dev/null || echo "1/1")
 CURRENT_SPACE=$(echo "$SPACE_INFO" | cut -d'/' -f1)
 TOTAL_SPACES=$(echo "$SPACE_INFO" | cut -d'/' -f2)
 

From 516f7fddbc778046f1412ee8e91b61e658d791d3 Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Wed, 15 Apr 2026 16:58:09 -0400
Subject: [PATCH 3/8] test: add BATS test suite for lib/common.sh

14 tests covering path constants, resolution helpers,
require_command, require_config, and test fixtures.
---
 .mise/tasks/test      |  6 +++
 test/common.bats      | 94 +++++++++++++++++++++++++++++++++++++++++++
 test/test_helper.bash | 36 +++++++++++++++++
 3 files changed, 136 insertions(+)
 create mode 100755 .mise/tasks/test
 create mode 100644 test/common.bats
 create mode 100644 test/test_helper.bash

diff --git a/.mise/tasks/test b/.mise/tasks/test
new file mode 100755
index 0000000..96d7456
--- /dev/null
+++ b/.mise/tasks/test
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#MISE description="Run tests"
+set -euo pipefail
+
+cd "$MISE_CONFIG_ROOT"
+bats test/*.bats "$@"
diff --git a/test/common.bats b/test/common.bats
new file mode 100644
index 0000000..a56267e
--- /dev/null
+++ b/test/common.bats
@@ -0,0 +1,94 @@
+#!/usr/bin/env bats
+
+setup() {
+  load test_helper
+}
+
+# --- Path constants ---
+
+@test "WALLPAPERS_OUTPUT_DIR points to ~/.local/share/wallpapers" {
+  [[ "$WALLPAPERS_OUTPUT_DIR" == "$HOME/.local/share/wallpapers" ]]
+}
+
+@test "WALLPAPERS_CONFIG_FILE points to ~/.config/wallpapers/config.json" {
+  [[ "$WALLPAPERS_CONFIG_FILE" == "$HOME/.config/wallpapers/config.json" ]]
+}
+
+@test "WALLPAPERS_STATE_DIR points to ~/.local/state/wallpapers" {
+  [[ "$WALLPAPERS_STATE_DIR" == "$HOME/.local/state/wallpapers" ]]
+}
+
+# --- resolution helpers ---
+
+@test "resolution_width extracts width from WxH" {
+  run resolution_width "3024x1964"
+  [[ "$output" == "3024" ]]
+}
+
+@test "resolution_height extracts height from WxH" {
+  run resolution_height "3024x1964"
+  [[ "$output" == "1964" ]]
+}
+
+@test "resolution_width handles 1080p" {
+  run resolution_width "1920x1080"
+  [[ "$output" == "1920" ]]
+}
+
+@test "resolution_height handles 1080p" {
+  run resolution_height "1920x1080"
+  [[ "$output" == "1080" ]]
+}
+
+# --- detect_screen_resolution ---
+
+@test "detect_screen_resolution returns a WxH string on macOS" {
+  # Skip if not on macOS (no system_profiler)
+  command -v system_profiler &>/dev/null || skip "not macOS"
+  run detect_screen_resolution
+  [[ "$status" -eq 0 ]]
+  [[ "$output" =~ ^[0-9]+x[0-9]+$ ]]
+}
+
+# --- require_command ---
+
+@test "require_command succeeds for an installed command" {
+  run require_command bash
+  [[ "$status" -eq 0 ]]
+}
+
+@test "require_command fails for a missing command" {
+  run require_command nonexistent_cmd_xyz
+  [[ "$status" -ne 0 ]]
+  [[ "$output" == *"not found"* ]]
+}
+
+@test "require_command includes install hint in error" {
+  run require_command nonexistent_cmd_xyz "Install with: brew install xyz"
+  [[ "$status" -ne 0 ]]
+  [[ "$output" == *"Install with: brew install xyz"* ]]
+}
+
+# --- require_config ---
+
+@test "require_config fails when config does not exist" {
+  WALLPAPERS_CONFIG_FILE="$BATS_TEST_TMPDIR/nonexistent.json"
+  run require_config
+  [[ "$status" -ne 0 ]]
+  [[ "$output" == *"Config not found"* ]]
+}
+
+@test "require_config succeeds when config exists" {
+  create_test_config
+  run require_config
+  [[ "$status" -eq 0 ]]
+}
+
+# --- test config fixture ---
+
+@test "create_test_config creates valid JSON with 3 workspaces" {
+  create_test_config
+  [[ -f "$WALLPAPERS_CONFIG_FILE" ]]
+  run jq '.workspaces | length' "$WALLPAPERS_CONFIG_FILE"
+  [[ "$output" == "3" ]]
+}
diff --git a/test/test_helper.bash b/test/test_helper.bash
new file mode 100644
index 0000000..cb09d82
--- /dev/null
+++ b/test/test_helper.bash
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Common test fixtures for wallpapers BATS tests.
+
+# Repo root — use MISE_CONFIG_ROOT if available (task context), fall back to git
+REPO_ROOT="${MISE_CONFIG_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+
+# Source shared library
+source "$REPO_ROOT/lib/common.sh"
+
+# Create a minimal config file in a temp directory.
+# Sets WALLPAPERS_CONFIG_FILE and WALLPAPERS_CONFIG_DIR for the test.
+create_test_config() {
+  local config_dir="$BATS_TEST_TMPDIR/config/wallpapers"
+  mkdir -p "$config_dir"
+  WALLPAPERS_CONFIG_DIR="$config_dir"
+  WALLPAPERS_CONFIG_FILE="$config_dir/config.json"
+  cat > "$WALLPAPERS_CONFIG_FILE" <<'JSON'
+{
+  "workspaces": [
+    { "name": "Personal", "bgColor": "#2d3436" },
+    { "name": "Code", "bgColor": "#1a1a2e" },
+    { "name": "Design", "id": "design", "bgColor": "#0f3460" }
+  ],
+  "defaults": {
+    "bgColor": "#000000",
+    "textColor": "#ffffff"
+  }
+}
+JSON
+}
+
+# Create a temp output directory for generated wallpapers.
+create_test_output_dir() {
+  WALLPAPERS_OUTPUT_DIR="$BATS_TEST_TMPDIR/wallpapers"
+  mkdir -p "$WALLPAPERS_OUTPUT_DIR"
+}

From 1e5a688870025a6b1730ada4dd6c327b6a840fcd Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Wed, 15 Apr 2026 16:58:18 -0400
Subject: [PATCH 4/8] chore: add bats, task_output setting to mise.toml

---
 mise.toml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/mise.toml b/mise.toml
index 4dfff32..88c8731 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,9 +1,13 @@
 # Mise configuration for wallpaper generator
 # Tasks are auto-discovered from .mise/tasks/
 
+[settings]
+task_output = "interleave"
+
 [tools]
 gum = "latest"
 jq = "latest"
-usage = "latest"  # enables shell completions for task args
+usage = "latest"
+bats = "1.13.0"
 
 # Note: Swift is built-in on macOS, no need to manage it

From 07dea646bc4666c75ce94a08314d828d0151d852 Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Wed, 15 Apr 2026 16:58:22 -0400
Subject: [PATCH 5/8] docs: remove CLAUDE.md, add README.tsx, expand README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Delete CLAUDE.md — tool codebases should be agent-agnostic
- Add Development section to README with architecture, resolution
  presets, and test instructions
- Add README.tsx JSX template for dynamic README generation
---
 CLAUDE.md  | 102 ---------------------------
 README.md  |  34 +++++++++
 README.tsx | 204 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 238 insertions(+), 102 deletions(-)
 delete mode 100644 CLAUDE.md
 create mode 100644 README.tsx

diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 2f46640..0000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Wallpapers is a native macOS wallpaper generator that creates labeled wallpapers for workspace/desktop identification. Since macOS doesn't allow naming Spaces/Desktops, this tool generates custom wallpapers with labels to visually identify workspaces.
-
-**Tech stack:** Pure Swift 5.9+ with Core Graphics, bash task scripts, gum for CLI interactions, mise for task orchestration. Zero external dependencies for core functionality. macOS 13+ required.
-
-## Common Commands
-
-All commands can be run via `mise run <task>` or globally via `wp <task>` (after setting up the shell alias).
-
-| Command | Purpose |
-|---------|---------|
-| `mise run apply` | Default task - show picker to apply wallpaper to current or all spaces |
-| `mise run apply <name>` | Generate and apply wallpaper for a specific workspace |
-| `mise run apply --all` | Generate and apply wallpapers to all spaces |
-| `mise run goto` | Show picker to switch workspaces |
-| `mise run goto <name>` | Switch to a workspace by name |
-| `mise run goto -` | Go back to previous workspace (like `cd -`) |
-| `mise run quick` | Quick generate with auto-detected resolution, auto-sets wallpaper |
-| `mise run generate` | Full interactive generator (colors, resolution, description) |
-| `mise run cli "Name" [options]` | Direct CLI without interactive prompts |
-| `mise run config:init` | Create starter config at ~/.config/wallpapers/config.json |
-| `mise run config:edit` | Open config in $EDITOR |
-| `mise run info:list` | List generated wallpapers |
-| `mise run info:space` | Show current desktop number (e.g., "3/5") |
-| `mise run info:resolution` | Show screen resolution |
-| `mise run clean` | Delete all generated wallpapers |
-| `mise run tutorial` | Interactive tutorial to learn the tool |
-| `mise run shell` | Output shell config for `wp` alias (use with eval) |
-
-Direct Swift invocation: `swift src/generate.swift "Name" [options]`
-
-## Architecture
-
-### Core Components
-
-**`src/generate.swift`** - Main wallpaper generator using Core Graphics
-- Creates PNG images with text labels
-- Supports resolution presets (1080p, 1440p, 4k, macbook-14, macbook-16, imac-24, studio-display) and custom dimensions
-- Background/text color customization via hex colors
-- RTL/LTR text positioning (Hebrew, Arabic auto-detected)
-- Outputs to `~/.local/share/wallpapers/{id}.{index}.png`
-
-**`src/current-space.swift`** - Detects current macOS desktop/space number
-- Uses private CGS (Core Graphics Server) APIs: `CGSCopyManagedDisplaySpaces()`, `CGSGetActiveSpace()`, `CGSMainConnectionID()`
-- Returns "current/total" format (e.g., "3/5")
-- Note: Private APIs may break in future macOS versions
-
-**`src/setup.swift`** - Batch wallpaper generator from config
-- Reads `~/.config/wallpapers/config.json`
-- Generates wallpapers for each workspace by calling generate.swift
-- Outputs file paths for the bash wrapper to apply
-
-**`.mise/tasks/`** - File-based bash task definitions
-- Each task is a bash script with `#MISE` metadata headers
-- Uses gum for interactive prompts (input, choose, confirm, style, spin)
-- Auto-discovered by mise
-
-### Data Flow
-
-1. User runs task (e.g., `mise run quick`)
-2. Bash task collects input via gum prompts or CLI args
-3. Task invokes `swift src/generate.swift` with options
-4. Swift generates PNG to `~/.local/share/wallpapers/`
-5. Task optionally sets wallpaper via osascript
-
-### Config File
-
-Location: `~/.config/wallpapers/config.json`
-
-```json
-{
-  "workspaces": [
-    { "name": "Personal", "bgColor": "#2d3436" },
-    { "name": "Skydiving 🪂", "id": "skydiving", "bgColor": "#0f3460" }
-  ],
-  "defaults": { "bgColor": "#000000", "textColor": "#ffffff" }
-}
-```
-
-**Workspace ID:** Each workspace gets a filename-safe ID. By default, this is derived from the name (slugified: lowercase, spaces→hyphens, alphanumeric only). Use the optional `id` field to override, especially for names with emojis or special characters.
-
-**Filename format:** `{id}.{index}.png` (e.g., `personal.1.png`, `skydiving.2.png`)
-
-## Resolution Presets
-
-```
-1080p: 1920x1080    macbook-14: 3024x1964
-1440p: 2560x1440    macbook-16: 3456x2234
-4k: 3840x2160       imac-24: 4480x2520
-                    studio-display: 5120x2880
-```
-
-## Notes
-
-- No automated test suite - testing is manual through CLI
-- macOS-only (AppKit, Core Graphics, osascript)
-- Global `wp` command via shell alias: `alias wp='mise -C /path/to/wallpapers run'`
diff --git a/README.md b/README.md
index f09b916..f3b0424 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,40 @@ swift src/generate.swift "Name" [options]
   --text-color         Text hex color
 ```
 
+## Development
+
+### Architecture
+
+**Swift layer** — Core Graphics rendering, no external dependencies:
+- `Sources/WallpaperKit/` — generator library (colors, styles, noise, decorations)
+- `Sources/generate/` — CLI entry point for wallpaper generation
+- `Sources/setup/` — batch generator that reads config and outputs file paths
+- `src/current-space.swift` — detects current macOS space via private CGS APIs
+
+**Task layer** — bash scripts in `.mise/tasks/`, orchestrated by mise:
+- Interactive prompts via `gum`
+- Shared helpers in `lib/common.sh` (paths, screen detection, dependency checks)
+- Space management delegates to `butthair` (Hammerspoon wrapper)
+
+**Data flow:** User runs task → bash collects input → invokes Swift generator → PNG written to `~/.local/share/wallpapers/` → optionally set as wallpaper via `osascript`.
+
+### Resolution presets
+
+```
+1080p: 1920x1080    macbook-14: 3024x1964
+1440p: 2560x1440    macbook-16: 3456x2234
+4k: 3840x2160       imac-24: 4480x2520
+                    studio-display: 5120x2880
+```
+
+### Running tests
+
+```bash
+mise run test
+```
+
+Tests use [BATS](https://github.com/bats-core/bats-core) for the bash task layer. Swift tests are in `Tests/`.
+
 ## License
 
 MIT
diff --git a/README.tsx b/README.tsx
new file mode 100644
index 0000000..e20939f
--- /dev/null
+++ b/README.tsx
@@ -0,0 +1,204 @@
+/** @jsxImportSource jsx-md */
+
+import { readdirSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+
+import {
+  Heading, Paragraph, CodeBlock,
+  Bold, Code, Link,
+  Badge, Badges, Center, Section,
+  Table, TableHead, TableRow, Cell,
+} from "readme/src/components";
+
+// ── Dynamic data ─────────────────────────────────────────────
+
+const REPO_DIR = resolve(import.meta.dirname);
+
+// Count tasks (excluding _ helpers and test)
+function countTasks(dir: string, prefix = ""): string[] {
+  const tasks: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith("_")) continue;
+    if (entry.name === "test") continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      tasks.push(...countTasks(full, `${prefix}${entry.name}:`));
+    } else {
+      tasks.push(`${prefix}${entry.name}`);
+    }
+  }
+  return tasks;
+}
+
+const taskDir = join(REPO_DIR, ".mise/tasks");
+const tasks = countTasks(taskDir);
+
+// Parse task descriptions
+const taskInfo = tasks.map((name) => {
+  const filePath = join(taskDir, name.replace(/:/g, "/"));
+  const content = readFileSync(filePath, "utf-8");
+  const match = content.match(/#MISE description="(.+?)"/);
+  return { name, desc: match?.[1] ?? "" };
+});
+
+// Count tests from .bats files
+const testDir = join(REPO_DIR, "test");
+const testCount = readdirSync(testDir)
+  .filter((f) => f.endsWith(".bats"))
+  .reduce((sum, f) => {
+    const content = readFileSync(join(testDir, f), "utf-8");
+    return sum + (content.match(/@test /g) || []).length;
+  }, 0);
+
+// Resolution presets for the table
+const resolutions = [
+  { name: "1080p", dims: "1920×1080" },
+  { name: "1440p", dims: "2560×1440" },
+  { name: "4k", dims: "3840×2160" },
+  { name: "macbook-14", dims: "3024×1964" },
+  { name: "macbook-16", dims: "3456×2234" },
+  { name: "imac-24", dims: "4480×2520" },
+  { name: "studio-display", dims: "5120×2880" },
+];
+
+// ── README ───────────────────────────────────────────────────
+
+const readme = (
+  <>
+    <Center>
+      <Heading level={1}>Wallpapers</Heading>
+
+      <CodeBlock lang="">{`         ▲ ▲
+        ╱   ╲
+       ╱ ° ° ╲      ╭───╮
+      ▕  ───  ▏ ◁━━━│ @ │━╮
+       ╲ ╰─╯ ╱      ╰───╯ │
+      ╱╱    ╲╲        ◀═══╯
+     ╱╱  ╱╲  ╲╲
+    ▔▔  ▔▔▔▔  ▔▔
+   ZERGLING    TURTLE
+               (in peril)`}</CodeBlock>
+
+      <Paragraph>
+        <Bold>Generate labeled wallpapers for macOS workspaces.</Bold>
+      </Paragraph>
+
+      <Paragraph>
+        macOS lets you create multiple desktops ("Spaces") but doesn't let you name them.{"\n"}
+        This tool generates wallpapers with labels so you can tell them apart.
+      </Paragraph>
+
+      <Badges>
+        <Badge label="lang" value="Swift + Bash" color="F05138" logo="swift" logoColor="white" />
+        <Badge label="runtime" value="mise" color="7c3aed" href="https://mise.jdx.dev" />
+        <Badge label="tasks" value={`${tasks.length}`} color="blue" />
+        <Badge label="tests" value={`${testCount}`} color="green" />
+        <Badge label="License" value="MIT" color="blue" href="LICENSE" />
+      </Badges>
+    </Center>
+
+    <Section title="Quick Start">
+      <CodeBlock lang="bash">{`# Install
+shiv install wallpapers
+
+# Add the wp alias to your shell
+eval "$(wallpapers shell)"
+
+# Run the tutorial
+wp tutorial`}</CodeBlock>
+    </Section>
+
+    <Section title="Usage">
+      <CodeBlock lang="bash">{`wp                # Apply wallpaper (picker or --all)
+wp --all          # Apply wallpapers to all spaces from config
+wp quick          # Quick one-off wallpaper for current space
+wp goto           # Switch workspace (picker)
+wp goto code      # Switch to workspace by name
+wp goto -         # Go back to previous workspace`}</CodeBlock>
+    </Section>
+
+    <Section title="Config">
+      <Paragraph>
+        Create your config with <Code>wp config init</Code>, then edit
+        with <Code>wp config edit</Code>:
+      </Paragraph>
+
+      <CodeBlock lang="json">{`{
+  "workspaces": [
+    { "name": "Personal", "bgColor": "#2d3436" },
+    { "name": "Code", "bgColor": "#1a1a2e", "description": "Dev environment" },
+    { "name": "Design", "bgColor": "#0f3460" }
+  ],
+  "defaults": {
+    "bgColor": "#000000",
+    "textColor": "#ffffff"
+  }
+}`}</CodeBlock>
+
+      <Paragraph>
+        The order of workspaces matches your Spaces order (left to right).
+      </Paragraph>
+    </Section>
+
+    <Section title="Resolution presets">
+      <Paragraph>
+        Auto-detect is the default. You can also specify a preset with <Code>--resolution</Code>:
+      </Paragraph>
+
+      <Table>
+        <TableHead>
+          <Cell>Preset</Cell>
+          <Cell>Dimensions</Cell>
+        </TableHead>
+        {resolutions.map((r) => (
+          <TableRow>
+            <Cell><Code>{r.name}</Code></Cell>
+            <Cell>{r.dims}</Cell>
+          </TableRow>
+        ))}
+      </Table>
+    </Section>
+
+    <Section title="All tasks">
+      <Table>
+        <TableHead>
+          <Cell>Task</Cell>
+          <Cell>Description</Cell>
+        </TableHead>
+        {taskInfo.map((t) => (
+          <TableRow>
+            <Cell><Code>{t.name}</Code></Cell>
+            <Cell>{t.desc}</Cell>
+          </TableRow>
+        ))}
+      </Table>
+    </Section>
+
+    <Section title="Development">
+      <CodeBlock lang="bash">{`gh repo clone KnickKnackLabs/wallpapers
+cd wallpapers && mise trust && mise install
+mise run test   # ${testCount} tests`}</CodeBlock>
+
+      <Paragraph>
+        <Bold>Architecture:</Bold> Swift layer (<Code>Sources/WallpaperKit/</Code>) handles
+        Core Graphics rendering. Bash tasks in <Code>.mise/tasks/</Code> handle user
+        interaction via <Code>gum</Code>. Shared helpers live in <Code>lib/common.sh</Code>.
+        Space management delegates to{" "}
+        <Link href="https://github.com/KnickKnackLabs/butthair">butthair</Link>.
+      </Paragraph>
+    </Section>
+
+    <Center>
+      <Section title="License">
+        <Paragraph>MIT</Paragraph>
+      </Section>
+
+      <Paragraph>
+        {"This README was created using "}
+        <Link href="https://github.com/KnickKnackLabs/readme">readme</Link>.
+      </Paragraph>
+    </Center>
+  </>
+);
+
+console.log(readme);

From db6d0850d20edf820be3352a5a735d8f6857e1bf Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Wed, 15 Apr 2026 16:59:46 -0400
Subject: [PATCH 6/8] refactor: replace 'mise run' with 'wp' in all user-facing
 strings

Tutorial scripts, error messages, and hints now reference the wp
alias consistently. Internal task dispatch and Hammerspoon config
(non-shiv context) retain mise run.
---
 .mise/tasks/apply/_default    |  2 +-
 .mise/tasks/tutorial/apply    | 10 +++++-----
 .mise/tasks/tutorial/config   |  6 +++---
 .mise/tasks/tutorial/generate |  8 ++++----
 .mise/tasks/tutorial/intro    |  4 ++--
 .mise/tasks/tutorial/navigate | 12 ++++++------
 .mise/tasks/tutorial/summary  |  8 ++++----
 7 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/.mise/tasks/apply/_default b/.mise/tasks/apply/_default
index 62ed58a..37f20b1 100755
--- a/.mise/tasks/apply/_default
+++ b/.mise/tasks/apply/_default
@@ -67,7 +67,7 @@ SCREEN_H=$(resolution_height "$SCREEN_RES")
         else
             DIFF=$((SPACE_COUNT - CONFIG_COUNT))
             gum style --foreground 245 "You have $DIFF extra space(s). Either:"
-            echo "  • Add more workspaces to your config: mise run config:edit"
+            echo "  • Add more workspaces to your config: wp config edit"
             echo "  • Or remove spaces: Mission Control → hover space → click X"
         fi
         echo ""
diff --git a/.mise/tasks/tutorial/apply b/.mise/tasks/tutorial/apply
index 0824988..297beaa 100755
--- a/.mise/tasks/tutorial/apply
+++ b/.mise/tasks/tutorial/apply
@@ -34,9 +34,9 @@ echo ""
 # Explain apply options
 gum style --foreground 141 --bold "Apply Commands"
 echo ""
-echo "  mise run apply              Picker to choose workspace"
-echo "  mise run apply <name>       Apply specific workspace to current"
-echo "  mise run apply --all        Apply to all spaces (by config order)"
+echo "  wp apply              Picker to choose workspace"
+echo "  wp apply <name>       Apply specific workspace to current"
+echo "  wp apply --all        Apply to all spaces (by config order)"
 echo ""
 
 gum style --foreground 245 "The '--all' option is powerful: it generates wallpapers for"
@@ -70,13 +70,13 @@ if [ -n "$WALLPAPERS" ]; then
     fi
 else
     gum style --foreground 226 "No wallpapers found in $OUTPUT_DIR"
-    gum style --foreground 244 "Generate some wallpapers first with 'mise run quick'"
+    gum style --foreground 244 "Generate some wallpapers first with 'wp quick'"
 fi
 
 echo ""
 
 # Continue prompt
 if ! gum confirm "Continue to workspace navigation?"; then
-    gum style --foreground 244 "Run 'mise run tutorial' to continue later."
+    gum style --foreground 244 "Run 'wp tutorial' to continue later."
     exit 1
 fi
diff --git a/.mise/tasks/tutorial/config b/.mise/tasks/tutorial/config
index 647ebe9..384c9de 100755
--- a/.mise/tasks/tutorial/config
+++ b/.mise/tasks/tutorial/config
@@ -118,12 +118,12 @@ echo ""
 # Helpful commands
 gum style --foreground 141 --bold "Helpful Commands"
 echo ""
-echo "  mise run config:init   Create a starter config"
-echo "  mise run config:edit   Open config in your editor"
+echo "  wp config init   Create a starter config"
+echo "  wp config edit   Open config in your editor"
 echo ""
 
 # Continue prompt
 if ! gum confirm "Continue to wallpaper generation?"; then
-    gum style --foreground 244 "Run 'mise run tutorial' to continue later."
+    gum style --foreground 244 "Run 'wp tutorial' to continue later."
     exit 1
 fi
diff --git a/.mise/tasks/tutorial/generate b/.mise/tasks/tutorial/generate
index c9010d6..4f263a0 100755
--- a/.mise/tasks/tutorial/generate
+++ b/.mise/tasks/tutorial/generate
@@ -34,9 +34,9 @@ echo ""
 # Explain generation options
 gum style --foreground 141 --bold "Generation Commands"
 echo ""
-echo "  mise run quick         Quick generate with auto resolution"
-echo "  mise run generate      Full interactive (colors, description)"
-echo "  mise run cli \"Name\"    Direct CLI generation"
+echo "  wp quick         Quick generate with auto resolution"
+echo "  wp generate      Full interactive (colors, description)"
+echo "  wp cli \"Name\"    Direct CLI generation"
 echo ""
 
 gum style --foreground 245 "The 'quick' command is the fastest way to create a wallpaper."
@@ -81,6 +81,6 @@ echo ""
 
 # Continue prompt
 if ! gum confirm "Continue to applying wallpapers?"; then
-    gum style --foreground 244 "Run 'mise run tutorial' to continue later."
+    gum style --foreground 244 "Run 'wp tutorial' to continue later."
     exit 1
 fi
diff --git a/.mise/tasks/tutorial/intro b/.mise/tasks/tutorial/intro
index 6104437..b819c30 100755
--- a/.mise/tasks/tutorial/intro
+++ b/.mise/tasks/tutorial/intro
@@ -48,11 +48,11 @@ echo "  4. Navigating between workspaces by name"
 echo "  5. Quick command reference"
 echo ""
 
-gum style --foreground 244 "Tip: Add 'eval \"\$(mise run -q shell)\"' to your shell config for 'wp'."
+gum style --foreground 244 "Tip: Add 'eval \"\$(wallpapers shell)\"' to your shell config for the 'wp' alias."
 echo ""
 
 # Continue prompt
 if ! gum confirm "Ready to begin?"; then
-    gum style --foreground 244 "No problem! Run 'mise run tutorial' when you're ready."
+    gum style --foreground 244 "No problem! Run 'wp tutorial' when you're ready."
     exit 1
 fi
diff --git a/.mise/tasks/tutorial/navigate b/.mise/tasks/tutorial/navigate
index 1418ad8..57f7481 100755
--- a/.mise/tasks/tutorial/navigate
+++ b/.mise/tasks/tutorial/navigate
@@ -42,9 +42,9 @@ echo ""
 # Explain navigation options
 gum style --foreground 141 --bold "Navigation Commands"
 echo ""
-echo "  mise run goto              Picker to choose workspace"
-echo "  mise run goto <name>       Jump to workspace by name or ID"
-echo "  mise run goto -            Go back to previous space (like cd -)"
+echo "  wp goto              Picker to choose workspace"
+echo "  wp goto <name>       Jump to workspace by name or ID"
+echo "  wp goto -            Go back to previous space (like cd -)"
 echo ""
 
 # Show workspaces from config
@@ -54,7 +54,7 @@ if [ -n "$ACTIVE_CONFIG" ] && [ -f "$ACTIVE_CONFIG" ]; then
     jq -r '.workspaces | to_entries[] | "  \(.key + 1). \(.value.name)"' "$ACTIVE_CONFIG"
     echo ""
 else
-    gum style --foreground 244 "No config found. Create one with 'mise run config:init'"
+    gum style --foreground 244 "No config found. Create one with 'wp config init'"
     echo ""
 fi
 
@@ -83,7 +83,7 @@ if [ "$TOTAL_SPACES" -gt 1 ]; then
 
         gum style --foreground 46 "Back on Desktop $CURRENT_SPACE. That's how 'goto' navigates!"
         echo ""
-        gum style --foreground 245 "Tip: 'mise run goto -' remembers your previous space."
+        gum style --foreground 245 "Tip: 'wp goto -' remembers your previous space."
     else
         gum style --foreground 244 "Skipping navigation demo."
     fi
@@ -96,6 +96,6 @@ echo ""
 
 # Continue prompt
 if ! gum confirm "Continue to command summary?"; then
-    gum style --foreground 244 "Run 'mise run tutorial' to continue later."
+    gum style --foreground 244 "Run 'wp tutorial' to continue later."
     exit 1
 fi
diff --git a/.mise/tasks/tutorial/summary b/.mise/tasks/tutorial/summary
index 7c9db73..d706e58 100755
--- a/.mise/tasks/tutorial/summary
+++ b/.mise/tasks/tutorial/summary
@@ -63,7 +63,7 @@ echo "  clean                Delete all wallpapers"
 echo "  shell                Output shell config for 'wp' alias"
 echo ""
 
-gum style --foreground 244 "All commands above can be run with 'mise run <command>'"
+gum style --foreground 244 "All commands above can be run with 'wp <command>'"
 gum style --foreground 244 "or 'wp <command>' if you've set up the alias."
 echo ""
 
@@ -89,13 +89,13 @@ if [ "$USED_DEMO" = true ] && [ -f "$TUTORIAL_CONFIG" ]; then
         if gum confirm "Save demo config to ~/.config/wallpapers/config.json?"; then
             mkdir -p "$(dirname "$USER_CONFIG")"
             cp "$TUTORIAL_CONFIG" "$USER_CONFIG"
-            gum style --foreground 46 "Config saved! Edit with 'mise run config:edit'"
+            gum style --foreground 46 "Config saved! Edit with 'wp config edit'"
         else
             gum style --foreground 244 "Demo config discarded."
         fi
     else
         gum style --foreground 244 "You already have a config file."
-        gum style --foreground 244 "Run 'mise run config:edit' to modify it."
+        gum style --foreground 244 "Run 'wp config edit' to modify it."
     fi
 fi
 
@@ -105,5 +105,5 @@ rm -rf "$TUTORIAL_CONFIG_DIR" 2>/dev/null || true
 
 echo ""
 gum style --foreground 46 "Happy wallpapering!"
-gum style --foreground 245 "Run 'mise run tutorial' anytime to revisit this guide."
+gum style --foreground 245 "Run 'wp tutorial' anytime to revisit this guide."
 echo ""

From eb3cb2a900bd79e6db288f57f6fd124f3fb9ed8d Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Thu, 16 Apr 2026 12:58:47 -0400
Subject: [PATCH 7/8] fix: use WALLPAPERS_OUTPUT_DIR in generate task

Replace stale $OUTPUT_DIR reference with $WALLPAPERS_OUTPUT_DIR from
lib/common.sh. Add TODO comments to tutorial tasks for future migration
to shared lib.

Addresses review feedback from baby-joel on #49.
---
 .mise/tasks/generate          | 2 +-
 .mise/tasks/tutorial/apply    | 1 +
 .mise/tasks/tutorial/generate | 1 +
 .mise/tasks/tutorial/navigate | 1 +
 4 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/.mise/tasks/generate b/.mise/tasks/generate
index 3786a29..2cc9aff 100755
--- a/.mise/tasks/generate
+++ b/.mise/tasks/generate
@@ -103,4 +103,4 @@ gum spin --spinner dot --title "Generating wallpaper..." -- \
 gum style --foreground 46 "✅ Wallpaper generated! Saved to $WALLPAPERS_OUTPUT_DIR"
 
 # Show the generated files
-ls -la "$OUTPUT_DIR"
+ls -la "$WALLPAPERS_OUTPUT_DIR"
diff --git a/.mise/tasks/tutorial/apply b/.mise/tasks/tutorial/apply
index 297beaa..b94db88 100755
--- a/.mise/tasks/tutorial/apply
+++ b/.mise/tasks/tutorial/apply
@@ -11,6 +11,7 @@ for cmd in gum swift; do
 done
 
 # Constants
+# TODO: source lib/common.sh instead of hardcoding paths
 OUTPUT_DIR="$HOME/.local/share/wallpapers"
 # shellcheck disable=SC2154
 SCRIPT_DIR="$MISE_CONFIG_ROOT"
diff --git a/.mise/tasks/tutorial/generate b/.mise/tasks/tutorial/generate
index 4f263a0..d9f4225 100755
--- a/.mise/tasks/tutorial/generate
+++ b/.mise/tasks/tutorial/generate
@@ -11,6 +11,7 @@ for cmd in gum swift; do
 done
 
 # Constants
+# TODO: source lib/common.sh instead of hardcoding paths
 OUTPUT_DIR="$HOME/.local/share/wallpapers"
 # shellcheck disable=SC2154
 SCRIPT_DIR="$MISE_CONFIG_ROOT"
diff --git a/.mise/tasks/tutorial/navigate b/.mise/tasks/tutorial/navigate
index 57f7481..f7fac9c 100755
--- a/.mise/tasks/tutorial/navigate
+++ b/.mise/tasks/tutorial/navigate
@@ -11,6 +11,7 @@ for cmd in gum swift jq; do
 done
 
 # Constants
+# TODO: source lib/common.sh instead of hardcoding paths
 # shellcheck disable=SC2154
 SCRIPT_DIR="$MISE_CONFIG_ROOT"
 USER_CONFIG="$HOME/.config/wallpapers/config.json"

From 3a849ba9a6e187ff917d322a4bb9f1635b550b11 Mon Sep 17 00:00:00 2001
From: quick <quick@ricon.family>
Date: Fri, 8 May 2026 20:15:39 -0400
Subject: [PATCH 8/8] chore: finish convention revival

---
 .github/workflows/ci.yml       |  30 +++++
 .mise/tasks/ai                 |   1 +
 .mise/tasks/apply/_default     |   8 +-
 .mise/tasks/apply/undo         |  12 +-
 .mise/tasks/generate           |  12 +-
 .mise/tasks/hammerspoon/config |   4 +-
 .mise/tasks/info/list          |   1 +
 .mise/tasks/quick              |   1 +
 .mise/tasks/readme             |   6 +
 .mise/tasks/test               |  29 ++++-
 .mise/tasks/tutorial/apply     |   1 +
 .mise/tasks/tutorial/generate  |   1 +
 .mise/tasks/tutorial/intro     |  10 +-
 .mise/tasks/tutorial/summary   |  14 +--
 README.md                      | 154 ++++++++++++-------------
 README.tsx                     |   2 +-
 mise.lock                      | 205 +++++++++++++++++++++++++++++++++
 mise.toml                      |  19 ++-
 test/common.bats               |   4 +-
 test/test_helper.bash          |   5 +-
 20 files changed, 403 insertions(+), 116 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100755 .mise/tasks/readme
 create mode 100644 mise.lock

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..f0ca349
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v6
+      - uses: jdx/mise-action@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Verify shell tasks
+        run: |
+          mise run test
+          codebase lint:mise-settings "$PWD"
+          codebase lint:bats-test-task "$PWD"
+          codebase lint:bats-test-helper "$PWD"
+          codebase lint:mcr-scope "$PWD"
+          codebase lint:or-true "$PWD"
+          codebase lint:shellcheck "$PWD"
+      - name: Verify Swift package
+        run: swift test
+      - name: Verify generated README
+        run: |
+          mise run readme
+          git diff --exit-code README.md
diff --git a/.mise/tasks/ai b/.mise/tasks/ai
index b26f70d..af8b6a5 100755
--- a/.mise/tasks/ai
+++ b/.mise/tasks/ai
@@ -411,6 +411,7 @@ if [ -d "$OUTPUT_DIR" ] && [ "$(ls -A "$OUTPUT_DIR"/*.png 2>/dev/null)" ]; then
     echo ""
     echo "| File | Size | Modified |"
     echo "|------|------|----------|"
+    # shellcheck disable=SC2012 # Human-readable listing of tool-generated wallpaper files.
     ls -lh "$OUTPUT_DIR"/*.png 2>/dev/null | awk '{print "| " $NF " | " $5 " | " $6 " " $7 " |"}' | sed "s|$OUTPUT_DIR/||"
     echo ""
 else
diff --git a/.mise/tasks/apply/_default b/.mise/tasks/apply/_default
index 37f20b1..e49f45b 100755
--- a/.mise/tasks/apply/_default
+++ b/.mise/tasks/apply/_default
@@ -142,11 +142,15 @@ SCREEN_H=$(resolution_height "$SCREEN_RES")
             PREV_LAST_SPACE=""
             for i in "${!PREV_WINS[@]}"; do
                 if [ "${PREV_SPACES[$i]}" != "$PREV_LAST_SPACE" ]; then
-                    butthair spaces:goto -- "${PREV_SPACES[$i]}" < /dev/null 2>/dev/null || true
+                    if ! butthair spaces:goto -- "${PREV_SPACES[$i]}" < /dev/null 2>/dev/null; then
+                        : # Window cleanup is best-effort; continue closing what we can.
+                    fi
                     sleep 0.3
                     PREV_LAST_SPACE="${PREV_SPACES[$i]}"
                 fi
-                butthair windows:close -- "${PREV_WINS[$i]}" < /dev/null 2>/dev/null || true
+                if ! butthair windows:close -- "${PREV_WINS[$i]}" < /dev/null 2>/dev/null; then
+                    : # Window may already be gone.
+                fi
             done
         fi
         : > "$STATE_FILE"
diff --git a/.mise/tasks/apply/undo b/.mise/tasks/apply/undo
index 85e596e..3024c94 100755
--- a/.mise/tasks/apply/undo
+++ b/.mise/tasks/apply/undo
@@ -30,16 +30,22 @@ for i in "${!WINS[@]}"; do
     WIN_ID="${WINS[$i]}"
 
     if [ "$SPACE_NUM" != "$LAST_SPACE" ]; then
-        butthair spaces:goto -- "$SPACE_NUM" < /dev/null 2>/dev/null || true
+        if ! butthair spaces:goto -- "$SPACE_NUM" < /dev/null 2>/dev/null; then
+            : # Window may already be gone; continue best-effort cleanup.
+        fi
         sleep 0.3
         LAST_SPACE="$SPACE_NUM"
     fi
 
-    RESULT=$(butthair windows:close -- "$WIN_ID" < /dev/null 2>&1) || true
+    if ! RESULT=$(butthair windows:close -- "$WIN_ID" < /dev/null 2>&1); then
+        : # Window may already be closed; print butthair's response below.
+    fi
     echo "  $RESULT"
 done
 
-butthair spaces:goto -- "$CURRENT_SPACE" < /dev/null 2>/dev/null || true
+if ! butthair spaces:goto -- "$CURRENT_SPACE" < /dev/null 2>/dev/null; then
+    : # Restore is best-effort; cleanup state below regardless.
+fi
 
 rm -f "$STATE_FILE"
 echo "Done."
diff --git a/.mise/tasks/generate b/.mise/tasks/generate
index 2cc9aff..96f89a4 100755
--- a/.mise/tasks/generate
+++ b/.mise/tasks/generate
@@ -18,11 +18,11 @@ if [ -z "$NAME" ]; then
 fi
 
 # Ask for optional description
-DESC_ARG=""
+DESC_ARGS=()
 if gum confirm "Add a description?"; then
     DESCRIPTION=$(gum input --placeholder "Brief description" --prompt "📋 Description: ")
     if [ -n "$DESCRIPTION" ]; then
-        DESC_ARG="--description"
+        DESC_ARGS=("--description" "$DESCRIPTION")
     fi
 fi
 
@@ -44,10 +44,10 @@ RESOLUTION=$(gum choose --header "📐 Select resolution:" \
 
 # Extract resolution - handle auto-detect
 if [[ "$RESOLUTION" == auto* ]]; then
-    RES_ARGS="--width $SCREEN_W --height $SCREEN_H"
+    RES_ARGS=("--width" "$SCREEN_W" "--height" "$SCREEN_H")
 else
     RES_KEY=$(echo "$RESOLUTION" | cut -d' ' -f1)
-    RES_ARGS="-r $RES_KEY"
+    RES_ARGS=("-r" "$RES_KEY")
 fi
 
 # Select colors
@@ -94,11 +94,11 @@ STYLE=$(gum choose --header "Visual style:" \
 # Build and run Swift generator
 gum spin --spinner dot --title "Generating wallpaper..." -- \
     swift run generate -- "$NAME" \
-        $RES_ARGS \
+        "${RES_ARGS[@]}" \
         --bg-color "$BG_COLOR" \
         --text-color "$TEXT_COLOR" \
         --style "$STYLE" \
-        $DESC_ARG ${DESCRIPTION:+"$DESCRIPTION"}
+        "${DESC_ARGS[@]}"
 
 gum style --foreground 46 "✅ Wallpaper generated! Saved to $WALLPAPERS_OUTPUT_DIR"
 
diff --git a/.mise/tasks/hammerspoon/config b/.mise/tasks/hammerspoon/config
index a308e1c..541b51e 100755
--- a/.mise/tasks/hammerspoon/config
+++ b/.mise/tasks/hammerspoon/config
@@ -334,5 +334,7 @@ fi
 
 # Reload config if Hammerspoon is running
 if pgrep -x "Hammerspoon" > /dev/null && [ -x "$HS_CLI" ]; then
-    "$HS_CLI" -c "hs.reload()" 2>/dev/null && echo "Config reloaded" || true
+    if "$HS_CLI" -c "hs.reload()" 2>/dev/null; then
+        echo "Config reloaded"
+    fi
 fi
diff --git a/.mise/tasks/info/list b/.mise/tasks/info/list
index 20b2aa5..ec53521 100755
--- a/.mise/tasks/info/list
+++ b/.mise/tasks/info/list
@@ -4,6 +4,7 @@ source "${MISE_CONFIG_ROOT}/lib/common.sh"
 
 if [ -d "$WALLPAPERS_OUTPUT_DIR" ] && [ "$(ls -A "$WALLPAPERS_OUTPUT_DIR" 2>/dev/null)" ]; then
     gum style --foreground 212 --bold "📁 Generated Wallpapers:"
+    # shellcheck disable=SC2012 # Human-readable listing of tool-generated wallpaper files.
     ls -lh "$WALLPAPERS_OUTPUT_DIR"/*.png 2>/dev/null | awk '{print "  " $9 " (" $5 ")"}'
 else
     gum style --foreground 244 "No wallpapers generated yet. Run 'wallpapers generate' to create one."
diff --git a/.mise/tasks/quick b/.mise/tasks/quick
index f1c7726..ba6d539 100755
--- a/.mise/tasks/quick
+++ b/.mise/tasks/quick
@@ -21,6 +21,7 @@ gum spin --spinner dot --title "Generating at ${SCREEN_W}x${SCREEN_H}..." -- \
 gum style --foreground 46 "✅ Generated! Saved to $WALLPAPERS_OUTPUT_DIR"
 
 # Get the most recently created wallpaper (the one we just generated)
+# shellcheck disable=SC2012 # Need newest generated file; wallpaper names are tool-generated.
 WALLPAPER_PATH="$(ls -t "$WALLPAPERS_OUTPUT_DIR"/*.png | head -1)"
 
 # Set wallpaper for current desktop
diff --git a/.mise/tasks/readme b/.mise/tasks/readme
new file mode 100755
index 0000000..8c5b64a
--- /dev/null
+++ b/.mise/tasks/readme
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#MISE description="Regenerate README.md from README.tsx"
+set -euo pipefail
+
+cd "$MISE_CONFIG_ROOT"
+readme build
diff --git a/.mise/tasks/test b/.mise/tasks/test
index 96d7456..54a38c1 100755
--- a/.mise/tasks/test
+++ b/.mise/tasks/test
@@ -1,6 +1,29 @@
 #!/usr/bin/env bash
-#MISE description="Run tests"
+#MISE description="Run BATS test suite"
+#USAGE arg "[args]..." var=#true help="Test suites, files, or bats flags"
+#USAGE example "mise run test" header="Run all tests"
+#USAGE example "mise run test common" header="Run a specific suite by name"
+#USAGE example "mise run test test/common.bats" header="Run a specific file"
+#USAGE example "mise run test -- --filter resolution" header="Filter tests by name"
 set -euo pipefail
 
-cd "$MISE_CONFIG_ROOT"
-bats test/*.bats "$@"
+TEST_DIR="$MISE_CONFIG_ROOT/test"
+
+args=()
+has_target=false
+
+for arg in "$@"; do
+  if [[ "$arg" != -* && "$arg" != *.bats && -f "$TEST_DIR/$arg.bats" ]]; then
+    args+=("$TEST_DIR/$arg.bats")
+    has_target=true
+  else
+    [[ "$arg" == *.bats || -d "$arg" ]] && has_target=true
+    args+=("$arg")
+  fi
+done
+
+if ! $has_target; then
+  args+=("$TEST_DIR/")
+fi
+
+bats "${args[@]}"
diff --git a/.mise/tasks/tutorial/apply b/.mise/tasks/tutorial/apply
index b94db88..5468809 100755
--- a/.mise/tasks/tutorial/apply
+++ b/.mise/tasks/tutorial/apply
@@ -45,6 +45,7 @@ gum style --foreground 245 "each workspace in your config and applies them in or
 echo ""
 
 # Check if wallpapers exist
+# shellcheck disable=SC2012 # Need newest generated files; wallpaper names are tool-generated.
 WALLPAPERS=$(ls -t "$OUTPUT_DIR"/*.png 2>/dev/null | head -5)
 
 if [ -n "$WALLPAPERS" ]; then
diff --git a/.mise/tasks/tutorial/generate b/.mise/tasks/tutorial/generate
index d9f4225..b977119 100755
--- a/.mise/tasks/tutorial/generate
+++ b/.mise/tasks/tutorial/generate
@@ -63,6 +63,7 @@ if gum confirm "Generate a demo wallpaper now?"; then
     echo ""
 
     # Show the generated file
+    # shellcheck disable=SC2012 # Need newest generated file; wallpaper names are tool-generated.
     LATEST=$(ls -t "$OUTPUT_DIR"/*.png 2>/dev/null | head -1)
     if [ -n "$LATEST" ]; then
         gum style --foreground 245 "Saved to:"
diff --git a/.mise/tasks/tutorial/intro b/.mise/tasks/tutorial/intro
index b819c30..52b5c34 100755
--- a/.mise/tasks/tutorial/intro
+++ b/.mise/tasks/tutorial/intro
@@ -3,12 +3,10 @@
 set -e
 
 # Check dependencies
-for cmd in gum; do
-    if ! command -v "$cmd" &>/dev/null; then
-        echo "Error: $cmd is required but not installed."
-        exit 1
-    fi
-done
+if ! command -v gum &>/dev/null; then
+    echo "Error: gum is required but not installed."
+    exit 1
+fi
 
 clear
 
diff --git a/.mise/tasks/tutorial/summary b/.mise/tasks/tutorial/summary
index d706e58..292b66d 100755
--- a/.mise/tasks/tutorial/summary
+++ b/.mise/tasks/tutorial/summary
@@ -3,12 +3,10 @@
 set -e
 
 # Check dependencies
-for cmd in gum; do
-    if ! command -v "$cmd" &>/dev/null; then
-        echo "Error: $cmd is required but not installed."
-        exit 1
-    fi
-done
+if ! command -v gum &>/dev/null; then
+    echo "Error: gum is required but not installed."
+    exit 1
+fi
 
 # Constants
 USER_CONFIG="$HOME/.config/wallpapers/config.json"
@@ -101,7 +99,9 @@ fi
 
 # Cleanup
 rm -f "$ACTIVE_CONFIG_FILE"
-rm -rf "$TUTORIAL_CONFIG_DIR" 2>/dev/null || true
+if ! rm -rf "$TUTORIAL_CONFIG_DIR" 2>/dev/null; then
+    : # Demo cleanup is best-effort.
+fi
 
 echo ""
 gum style --foreground 46 "Happy wallpapering!"
diff --git a/README.md b/README.md
index f3b0424..8a290db 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
+<!-- Generated from README.tsx — edit that file, then run: mise run readme -->
+
+<div align="center">
+
 # Wallpapers
 
 ```
@@ -13,25 +17,29 @@
                (in peril)
 ```
 
-Generate labeled wallpapers for macOS workspaces.
+**Generate labeled wallpapers for macOS workspaces.**
+
+macOS lets you create multiple desktops ("Spaces") but doesn't let you name them.
+This tool generates wallpapers with labels so you can tell them apart.
+
+![lang: Swift + Bash](https://img.shields.io/badge/lang-Swift%20%2B%20Bash-F05138?style=flat&logo=swift&logoColor=white)
+[![runtime: mise](https://img.shields.io/badge/runtime-mise-7c3aed?style=flat)](https://mise.jdx.dev)
+![tasks: 24](https://img.shields.io/badge/tasks-24-blue?style=flat)
+![tests: 14](https://img.shields.io/badge/tests-14-green?style=flat)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat)](LICENSE)
 
-**What's a workspace?** macOS lets you create multiple desktops called "Spaces" (swipe left/right with three fingers, or ctrl+←/→). But Apple doesn't let you name them - so this tool generates wallpapers with labels to identify each one.
+</div>
 
 ## Quick Start
 
 ```bash
-# Install mise (if you don't have it)
-curl https://mise.run | sh
+# Install
+shiv install wallpapers
 
-# Install wallpapers
-git clone https://github.com/KnickKnackLabs/wallpapers.git ~/.local/share/wallpapers
-cd ~/.local/share/wallpapers && mise trust && mise install
+# Add the wp alias to your shell
+eval "$(wallpapers shell)"
 
-# Add to your shell config (~/.zshrc or ~/.bashrc)
-eval "$(mise -C ~/.local/share/wallpapers run -q shell)"
-
-# Reload shell and run the tutorial
-source ~/.zshrc
+# Run the tutorial
 wp tutorial
 ```
 
@@ -48,7 +56,7 @@ wp goto -         # Go back to previous workspace
 
 ## Config
 
-Create your config with `wp config:init`, then edit with `wp config:edit`:
+Create your config with `wp config init`, then edit with `wp config edit`:
 
 ```json
 {
@@ -66,81 +74,65 @@ Create your config with `wp config:init`, then edit with `wp config:edit`:
 
 The order of workspaces matches your Spaces order (left to right).
 
-## Features
-
-- **Native Swift** - Core Graphics rendering, no external dependencies
-- **Auto-detect resolution** - Fits your screen perfectly
-- **LTR/RTL support** - Works with English, Hebrew, Arabic, etc.
-- **Space navigation** - Switch workspaces by name
-
-## Requirements
-
-- macOS 13+
-- [mise](https://mise.jdx.dev/) (installs other dependencies automatically)
-
-## All Commands
-
-| Command | Description |
-|---------|-------------|
-| `wp` | Apply wallpaper (shows picker, or use `--all`) |
-| `wp quick` | Quick generate - just enter a name |
-| `wp goto [name]` | Switch workspace (picker if no name) |
-| `wp goto -` | Go back to previous workspace |
-| `wp generate` | Full interactive generator with all options |
-| `wp config:init` | Create starter config |
-| `wp config:edit` | Open config in editor |
-| `wp info:space` | Show current desktop number |
-| `wp info:list` | List generated wallpapers |
-| `wp clean` | Delete all generated wallpapers |
-| `wp tutorial` | Interactive tutorial |
-
-## Advanced
-
-For scripting or direct access:
-
-```bash
-swift src/generate.swift "Name" [options]
-  -d, --description    Subtitle text
-  -r, --resolution     Preset: 1080p, 1440p, 4k, macbook-14, macbook-16, imac-24, studio-display
-  --width, --height    Custom dimensions
-  --bg-color           Background hex color
-  --text-color         Text hex color
-```
+## Resolution presets
+
+Auto-detect is the default. You can also specify a preset with `--resolution`:
+
+| Preset | Dimensions |
+| --- | --- |
+| `1080p` | 1920×1080 |
+| `1440p` | 2560×1440 |
+| `4k` | 3840×2160 |
+| `macbook-14` | 3024×1964 |
+| `macbook-16` | 3456×2234 |
+| `imac-24` | 4480×2520 |
+| `studio-display` | 5120×2880 |
+
+## All tasks
+
+| Task | Description |
+| --- | --- |
+| `apply:undo` | Close windows created by the last 'apply --apps' |
+| `tutorial:apply` | Tutorial: Apply wallpaper to spaces demo |
+| `tutorial:navigate` | Tutorial: Workspace navigation demo |
+| `tutorial:intro` | Tutorial: Introduction and overview |
+| `tutorial:config` | Tutorial: Configuration setup walkthrough |
+| `tutorial:generate` | Tutorial: Wallpaper generation demo |
+| `tutorial:summary` | Tutorial: Command reference and completion |
+| `goto` | Switch to a workspace by name |
+| `config:init` | Initialize config file with example workspaces |
+| `config:edit` | Edit config file in your editor |
+| `shell` | Output shell configuration (use with eval) |
+| `quick` | Quick generate with just a name (auto-detects screen resolution) |
+| `cli` | Run generator directly with arguments |
+| `readme` | Regenerate README.md from README.tsx |
+| `info:resolution` | Show your screen resolution |
+| `info:list` | List generated wallpapers |
+| `info:wallpaper` | Show current wallpaper file path |
+| `info:space` | Show current desktop space |
+| `clean` | Remove all generated wallpapers |
+| `ai` | Agent instructions for helping users |
+| `generate` | Generate a wallpaper interactively |
+| `hammerspoon:config` | Install wp workspace integration into Hammerspoon config |
+| `open` | Open the wallpapers directory in Finder |
+| `help` | Show generator CLI help |
 
 ## Development
 
-### Architecture
-
-**Swift layer** — Core Graphics rendering, no external dependencies:
-- `Sources/WallpaperKit/` — generator library (colors, styles, noise, decorations)
-- `Sources/generate/` — CLI entry point for wallpaper generation
-- `Sources/setup/` — batch generator that reads config and outputs file paths
-- `src/current-space.swift` — detects current macOS space via private CGS APIs
-
-**Task layer** — bash scripts in `.mise/tasks/`, orchestrated by mise:
-- Interactive prompts via `gum`
-- Shared helpers in `lib/common.sh` (paths, screen detection, dependency checks)
-- Space management delegates to `butthair` (Hammerspoon wrapper)
-
-**Data flow:** User runs task → bash collects input → invokes Swift generator → PNG written to `~/.local/share/wallpapers/` → optionally set as wallpaper via `osascript`.
-
-### Resolution presets
-
-```
-1080p: 1920x1080    macbook-14: 3024x1964
-1440p: 2560x1440    macbook-16: 3456x2234
-4k: 3840x2160       imac-24: 4480x2520
-                    studio-display: 5120x2880
-```
-
-### Running tests
-
 ```bash
-mise run test
+gh repo clone KnickKnackLabs/wallpapers
+cd wallpapers && mise trust && mise install
+mise run test   # 14 tests
 ```
 
-Tests use [BATS](https://github.com/bats-core/bats-core) for the bash task layer. Swift tests are in `Tests/`.
+**Architecture:** Swift layer (`Sources/WallpaperKit/`) handles Core Graphics rendering. Bash tasks in `.mise/tasks/` handle user interaction via `gum`. Shared helpers live in `lib/common.sh`. Space management delegates to [butthair](https://github.com/KnickKnackLabs/butthair).
+
+<div align="center">
 
 ## License
 
 MIT
+
+This README was created using [readme](https://github.com/KnickKnackLabs/readme).
+
+</div>
diff --git a/README.tsx b/README.tsx
index e20939f..22a51d0 100644
--- a/README.tsx
+++ b/README.tsx
@@ -201,4 +201,4 @@ mise run test   # ${testCount} tests`}</CodeBlock>
   </>
 );
 
-console.log(readme);
+console.log(`<!-- Generated from README.tsx — edit that file, then run: mise run readme -->\n\n${readme}`);
diff --git a/mise.lock b/mise.lock
new file mode 100644
index 0000000..ae7710f
--- /dev/null
+++ b/mise.lock
@@ -0,0 +1,205 @@
+# @generated - this file is auto-generated by `mise lock` https://mise.en.dev/dev-tools/mise-lock.html
+
+[[tools.actionlint]]
+version = "1.7.12"
+backend = "aqua:rhysd/actionlint"
+
+[tools.actionlint."platforms.linux-arm64"]
+checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-arm64-musl"]
+checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-x64"]
+checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-x64-musl"]
+checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-arm64"]
+checksum = "sha256:aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_arm64.tar.gz"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-x64"]
+checksum = "sha256:5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_amd64.tar.gz"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.windows-x64"]
+checksum = "sha256:6e7241b51e6817ea6a047693d8e6fed13b31819c9a0dd6c5a726e1592d22f6e9"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_windows_amd64.zip"
+provenance = "github-attestations"
+
+[[tools.bats]]
+version = "1.13.0"
+backend = "aqua:bats-core/bats-core"
+
+[tools.bats."platforms.linux-arm64"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+
+[tools.bats."platforms.linux-arm64-musl"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+
+[tools.bats."platforms.linux-x64"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+
+[tools.bats."platforms.linux-x64-musl"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+
+[tools.bats."platforms.macos-arm64"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+
+[tools.bats."platforms.macos-x64"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+
+[[tools.gum]]
+version = "0.17.0"
+backend = "aqua:charmbracelet/gum"
+
+[tools.gum."platforms.linux-arm64"]
+checksum = "sha256:b0b9ed95cbf7c8b7073f17b9591811f5c001e33c7cfd066ca83ce8a07c576f9c"
+url = "https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Linux_arm64.tar.gz"
+
+[tools.gum."platforms.linux-arm64-musl"]
+checksum = "sha256:b0b9ed95cbf7c8b7073f17b9591811f5c001e33c7cfd066ca83ce8a07c576f9c"
+url = "https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Linux_arm64.tar.gz"
+
+[tools.gum."platforms.linux-x64"]
+checksum = "sha256:69ee169bd6387331928864e94d47ed01ef649fbfe875baed1bbf27b5377a6fdb"
+url = "https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Linux_x86_64.tar.gz"
+
+[tools.gum."platforms.linux-x64-musl"]
+checksum = "sha256:69ee169bd6387331928864e94d47ed01ef649fbfe875baed1bbf27b5377a6fdb"
+url = "https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Linux_x86_64.tar.gz"
+
+[tools.gum."platforms.macos-arm64"]
+checksum = "sha256:e2a4b8596efa05821d8c58d0c1afbcd7ad1699ba69c689cc3ff23a4a99c8b237"
+url = "https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Darwin_arm64.tar.gz"
+
+[tools.gum."platforms.macos-x64"]
+checksum = "sha256:cd66576aeebe6cd19c771863c7e8d696e0e1d5387d1e7075666baa67c2052e53"
+url = "https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Darwin_x86_64.tar.gz"
+
+[tools.gum."platforms.windows-x64"]
+checksum = "sha256:b2be80531c6babc8d4e0e6ca95773d58118a2e1582ae006aace08dbc55503072"
+url = "https://github.com/charmbracelet/gum/releases/download/v0.17.0/gum_0.17.0_Windows_x86_64.zip"
+
+[[tools.jq]]
+version = "1.8.1"
+backend = "aqua:jqlang/jq"
+
+[tools.jq."platforms.linux-arm64"]
+checksum = "sha256:6bc62f25981328edd3cfcfe6fe51b073f2d7e7710d7ef7fcdac28d4e384fc3d4"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-linux-arm64"
+provenance = "github-attestations"
+
+[tools.jq."platforms.linux-arm64-musl"]
+checksum = "sha256:6bc62f25981328edd3cfcfe6fe51b073f2d7e7710d7ef7fcdac28d4e384fc3d4"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-linux-arm64"
+provenance = "github-attestations"
+
+[tools.jq."platforms.linux-x64"]
+checksum = "sha256:020468de7539ce70ef1bceaf7cde2e8c4f2ca6c3afb84642aabc5c97d9fc2a0d"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-linux-amd64"
+provenance = "github-attestations"
+
+[tools.jq."platforms.linux-x64-musl"]
+checksum = "sha256:020468de7539ce70ef1bceaf7cde2e8c4f2ca6c3afb84642aabc5c97d9fc2a0d"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-linux-amd64"
+provenance = "github-attestations"
+
+[tools.jq."platforms.macos-arm64"]
+checksum = "sha256:a9fe3ea2f86dfc72f6728417521ec9067b343277152b114f4e98d8cb0e263603"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-macos-arm64"
+provenance = "github-attestations"
+
+[tools.jq."platforms.macos-x64"]
+checksum = "sha256:e80dbe0d2a2597e3c11c404f03337b981d74b4a8504b70586c354b7697a7c27f"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-macos-amd64"
+provenance = "github-attestations"
+
+[tools.jq."platforms.windows-x64"]
+checksum = "sha256:23cb60a1354eed6bcc8d9b9735e8c7b388cd1fdcb75726b93bc299ef22dd9334"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-windows-amd64.exe"
+provenance = "github-attestations"
+
+[[tools.shellcheck]]
+version = "0.11.0"
+backend = "aqua:koalaman/shellcheck"
+
+[tools.shellcheck."platforms.linux-arm64"]
+checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz"
+
+[tools.shellcheck."platforms.linux-arm64-musl"]
+checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz"
+
+[tools.shellcheck."platforms.linux-x64"]
+checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz"
+
+[tools.shellcheck."platforms.linux-x64-musl"]
+checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz"
+
+[tools.shellcheck."platforms.macos-arm64"]
+checksum = "sha256:56affdd8de5527894dca6dc3d7e0a99a873b0f004d7aabc30ae407d3f48b0a79"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.aarch64.tar.xz"
+
+[tools.shellcheck."platforms.macos-x64"]
+checksum = "sha256:3c89db4edcab7cf1c27bff178882e0f6f27f7afdf54e859fa041fca10febe4c6"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.x86_64.tar.xz"
+
+[tools.shellcheck."platforms.windows-x64"]
+checksum = "sha256:8a4e35ab0b331c85d73567b12f2a444df187f483e5079ceffa6bda1faa2e740e"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.zip"
+
+[[tools."shiv:codebase"]]
+version = "0.2.0"
+backend = "shiv:codebase"
+
+[[tools."shiv:readme"]]
+version = "0.1.0"
+backend = "shiv:readme"
+
+[[tools.usage]]
+version = "3.2.1"
+backend = "aqua:jdx/usage"
+
+[tools.usage."platforms.linux-arm64"]
+checksum = "sha256:c5a237c272e3b08d05a698aa37e6775ab36152e12e74084363c7a230d9fc7070"
+url = "https://github.com/jdx/usage/releases/download/v3.2.1/usage-aarch64-unknown-linux-musl.tar.gz"
+
+[tools.usage."platforms.linux-arm64-musl"]
+checksum = "sha256:c5a237c272e3b08d05a698aa37e6775ab36152e12e74084363c7a230d9fc7070"
+url = "https://github.com/jdx/usage/releases/download/v3.2.1/usage-aarch64-unknown-linux-musl.tar.gz"
+
+[tools.usage."platforms.linux-x64"]
+checksum = "sha256:aea16298c6fa7d13e10a04ce7a9e7c743a1d49151a7065aa3f80697c56a89452"
+url = "https://github.com/jdx/usage/releases/download/v3.2.1/usage-x86_64-unknown-linux-musl.tar.gz"
+
+[tools.usage."platforms.linux-x64-musl"]
+checksum = "sha256:aea16298c6fa7d13e10a04ce7a9e7c743a1d49151a7065aa3f80697c56a89452"
+url = "https://github.com/jdx/usage/releases/download/v3.2.1/usage-x86_64-unknown-linux-musl.tar.gz"
+
+[tools.usage."platforms.macos-arm64"]
+checksum = "sha256:94c0b8a913618e24c0bc8002a688112210ec3f5e8bbb5431a2687eed9fad2dff"
+url = "https://github.com/jdx/usage/releases/download/v3.2.1/usage-universal-apple-darwin.tar.gz"
+
+[tools.usage."platforms.macos-x64"]
+checksum = "sha256:94c0b8a913618e24c0bc8002a688112210ec3f5e8bbb5431a2687eed9fad2dff"
+url = "https://github.com/jdx/usage/releases/download/v3.2.1/usage-universal-apple-darwin.tar.gz"
+
+[tools.usage."platforms.windows-x64"]
+checksum = "sha256:9ac550ddcb67c1bb30e76fbf04126d50704004fc7850e7fa1aaa6994ce4601f5"
+url = "https://github.com/jdx/usage/releases/download/v3.2.1/usage-x86_64-pc-windows-msvc.zip"
diff --git a/mise.toml b/mise.toml
index 88c8731..1c213fd 100644
--- a/mise.toml
+++ b/mise.toml
@@ -2,12 +2,25 @@
 # Tasks are auto-discovered from .mise/tasks/
 
 [settings]
+experimental = true
+quiet = true
 task_output = "interleave"
+lockfile = true
+
+[plugins]
+shiv = "https://github.com/KnickKnackLabs/vfox-shiv"
 
 [tools]
-gum = "latest"
-jq = "latest"
-usage = "latest"
+gum = "0.17.0"
+jq = "1.8.1"
+usage = "3.2.1"
 bats = "1.13.0"
+actionlint = "1.7.12"
+shellcheck = "0.11.0"
+"shiv:codebase" = "latest"
+"shiv:readme" = "latest"
+
+[_.codebase]
+lint = ["mise-settings", "bats-test-task", "bats-test-helper", "mcr-scope", "or-true", "shellcheck"]
 
 # Note: Swift is built-in on macOS, no need to manage it
diff --git a/test/common.bats b/test/common.bats
index a56267e..0c74285 100644
--- a/test/common.bats
+++ b/test/common.bats
@@ -46,7 +46,9 @@ setup() {
   # Skip if not on macOS (no system_profiler)
   command -v system_profiler &>/dev/null || skip "not macOS"
   run detect_screen_resolution
-  [[ "$status" -eq 0 ]]
+  if [[ "$status" -ne 0 ]]; then
+    skip "no display resolution available"
+  fi
   [[ "$output" =~ ^[0-9]+x[0-9]+$ ]]
 }
 
diff --git a/test/test_helper.bash b/test/test_helper.bash
index cb09d82..452e5eb 100644
--- a/test/test_helper.bash
+++ b/test/test_helper.bash
@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Common test fixtures for wallpapers BATS tests.
 
-# Repo root — use MISE_CONFIG_ROOT if available (task context), fall back to git
-REPO_ROOT="${MISE_CONFIG_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+# Repo root — derive from the test file's own path.
+# Do not read MISE_CONFIG_ROOT here; agent shells inherit it from the launcher.
+REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/.." && pwd)"
 
 # Source shared library
 source "$REPO_ROOT/lib/common.sh"