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 02016f9..af8b6a5 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
 
@@ -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 c2ddbe5..e49f45b 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
@@ -77,7 +67,7 @@ SCREEN_H=$(echo "$SCREEN_RES" | cut -d'x' -f2)
         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 ""
@@ -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")"
@@ -152,11 +142,15 @@ SCREEN_H=$(echo "$SCREEN_RES" | cut -d'x' -f2)
             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"
@@ -165,7 +159,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..3024c94 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."
@@ -32,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/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..96f89a4 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 \
@@ -19,18 +18,18 @@ 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
 
 # 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:" \
@@ -45,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
@@ -95,13 +94,13 @@ 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 $OUTPUT_DIR"
+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/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..541b51e 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
@@ -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 a6091ae..ec53521 100755
--- a/.mise/tasks/info/list
+++ b/.mise/tasks/info/list
@@ -1,11 +1,11 @@
 #!/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 ")"}'
+    # 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 '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..ba6d539 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,18 @@ 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)"
+# 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
 gum spin --spinner dot --title "Setting wallpaper..." -- \
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/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/test b/.mise/tasks/test
new file mode 100755
index 0000000..54a38c1
--- /dev/null
+++ b/.mise/tasks/test
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+#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
+
+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 edd90e2..5468809 100755
--- a/.mise/tasks/tutorial/apply
+++ b/.mise/tasks/tutorial/apply
@@ -11,8 +11,10 @@ for cmd in gum swift; do
 done
 
 # Constants
+# TODO: source lib/common.sh instead of hardcoding paths
 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 +25,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)
 
@@ -33,9 +35,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"
@@ -43,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
@@ -69,13 +72,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 2cb0525..b977119 100755
--- a/.mise/tasks/tutorial/generate
+++ b/.mise/tasks/tutorial/generate
@@ -11,8 +11,10 @@ for cmd in gum swift; do
 done
 
 # Constants
+# TODO: source lib/common.sh instead of hardcoding paths
 OUTPUT_DIR="$HOME/.local/share/wallpapers"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+# shellcheck disable=SC2154
+SCRIPT_DIR="$MISE_CONFIG_ROOT"
 
 # Header
 echo ""
@@ -33,9 +35,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."
@@ -53,7 +55,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"
 
@@ -61,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:"
@@ -80,6 +83,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..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
 
@@ -48,11 +46,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 19488e3..f7fac9c 100755
--- a/.mise/tasks/tutorial/navigate
+++ b/.mise/tasks/tutorial/navigate
@@ -11,7 +11,9 @@ for cmd in gum swift jq; do
 done
 
 # Constants
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+# TODO: source lib/common.sh instead of hardcoding paths
+# 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"
@@ -41,9 +43,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
@@ -53,12 +55,12 @@ 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
 
 # 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)
 
@@ -82,7 +84,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
@@ -95,6 +97,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..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"
@@ -63,7 +61,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,21 +87,23 @@ 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
 
 # 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!"
-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 ""
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..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,47 +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:
+## 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
 
 ```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
+gh repo clone KnickKnackLabs/wallpapers
+cd wallpapers && mise trust && mise install
+mise run test   # 14 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
new file mode 100644
index 0000000..22a51d0
--- /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(`<!-- Generated from README.tsx — edit that file, then run: mise run readme -->\n\n${readme}`);
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
+}
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 4dfff32..1c213fd 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,9 +1,26 @@
 # Mise configuration for wallpaper generator
 # 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"  # enables shell completions for task args
+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
new file mode 100644
index 0000000..0c74285
--- /dev/null
+++ b/test/common.bats
@@ -0,0 +1,96 @@
+#!/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
+  if [[ "$status" -ne 0 ]]; then
+    skip "no display resolution available"
+  fi
+  [[ "$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..452e5eb
--- /dev/null
+++ b/test/test_helper.bash
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Common test fixtures for wallpapers BATS tests.
+
+# 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"
+
+# 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"
+}