From 9ab5eb820f5f4f99a009576122674f719827e05c Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 02:30:41 +0100
Subject: [PATCH 1/8] chore(install): run brew bundle verbosely

Show per-package progress so a failing Brewfile entry is visible in the
installer output.
---
 install.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/install.sh b/install.sh
index b09eccb..6435202 100755
--- a/install.sh
+++ b/install.sh
@@ -433,14 +433,14 @@ install_brew_packages() {
             print_error "Could not read casks from Brewfile: $BREWFILE"
             return 1
         fi
-        if ! HOMEBREW_DOWNLOAD_CONCURRENCY=1 HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_BUNDLE_CASK_SKIP="${casks//$'\n'/ }" brew bundle --jobs=1 --file="$BREWFILE"; then
+        if ! HOMEBREW_DOWNLOAD_CONCURRENCY=1 HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_BUNDLE_CASK_SKIP="${casks//$'\n'/ }" brew bundle --jobs=1 --verbose --file="$BREWFILE"; then
             print_error "Homebrew failed to install CLI packages from: $BREWFILE"
             return 1
         fi
         print_success "CLI packages installed"
     else
         print_header "Installing all packages from Brewfile..."
-        if ! HOMEBREW_DOWNLOAD_CONCURRENCY=1 HOMEBREW_NO_INSTALL_CLEANUP=1 brew bundle --jobs=1 --file="$BREWFILE"; then
+        if ! HOMEBREW_DOWNLOAD_CONCURRENCY=1 HOMEBREW_NO_INSTALL_CLEANUP=1 brew bundle --jobs=1 --verbose --file="$BREWFILE"; then
             print_error "Homebrew failed to install packages from: $BREWFILE"
             return 1
         fi

From 55fb34ee50ef04f9f3a03a698ce5efd6851dd729 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 02:30:41 +0100
Subject: [PATCH 2/8] refactor(install): drop Stow-era migration steps

Every machine has been migrated to dotstate, so link_dotfiles no longer
needs to move pre-dotstate state or unfold Stow directory links.
---
 install.sh | 66 +-----------------------------------------------------
 test.sh    | 15 ++++---------
 2 files changed, 5 insertions(+), 76 deletions(-)

diff --git a/install.sh b/install.sh
index 6435202..e9595e7 100755
--- a/install.sh
+++ b/install.sh
@@ -642,69 +642,8 @@ install_dotstate() {
     print_success "dotstate installed to ~/.local/bin"
 }
 
-# Move untracked state left at pre-dotstate paths (e.g. .config/zsh/secrets.zsh,
-# herdr sessions, tmux plugins) into the common/ or macos/ directory that is now
-# linked in its place. Apps the manifest does not link (no such directory under
-# common/ or a profile) stay put.
-migrate_legacy_state() {
-    [ -d "$DOTFILES/.config" ] || return 0
-
-    local app dir
-    for app in "$DOTFILES"/.config/*/; do
-        app="$(basename "$app")"
-        for dir in common macos linux; do
-            if [ -d "$DOTFILES/$dir/.config/$app" ]; then
-                merge_legacy_dir "$DOTFILES/.config/$app" "$DOTFILES/$dir/.config/$app" ".config/$app"
-                break
-            fi
-        done
-    done
-
-    find "$DOTFILES/.config" -depth -type d -empty -delete
-}
-
-# Move every entry of $1 into $2 without replacing anything already there.
-# Usage: merge_legacy_dir <src> <dst> <label>
-merge_legacy_dir() {
-    local src="$1" dst="$2" label="$3" entry name
-    for entry in "$src"/* "$src"/.[!.]* "$src"/..?*; do
-        [ -e "$entry" ] || [ -L "$entry" ] || continue
-        name="$(basename "$entry")"
-        if [ -d "$entry" ] && [ ! -L "$entry" ] && [ -d "$dst/$name" ] && [ ! -L "$dst/$name" ]; then
-            merge_legacy_dir "$entry" "$dst/$name" "$label/$name"
-        elif [ -e "$dst/$name" ] || [ -L "$dst/$name" ]; then
-            print_warning "Not moving $label/$name: it already exists in ${dst#"$DOTFILES"/}"
-        else
-            mv "$entry" "$dst/$name"
-            echo "  Moved $label/$name to ${dst#"$DOTFILES"/}/"
-        fi
-    done
-}
-
-# Stow folded whole directories into links to the repository. dotstate creates
-# parent directories itself, so drop such links once they dangle and refuse to
-# write through ones that still resolve into the repository.
-remove_legacy_parent_links() {
-    local dir target
-    for dir in .config .pi .pi/agent .agents .agents/skills; do
-        [ -L "$HOME/$dir" ] || continue
-        target="$(readlink "$HOME/$dir")"
-        case "$target" in
-            *"$(basename "$DOTFILES")"/*) ;;
-            *) continue ;;
-        esac
-        if [ ! -e "$HOME/$dir" ]; then
-            rm "$HOME/$dir"
-            print_info "Removed stale Stow link ~/$dir"
-        else
-            print_error "$HOME/$dir links into the repository ($target); replace it with a real directory first"
-            return 1
-        fi
-    done
-}
-
 # Link dotfiles into $HOME with dotstate. Conflicting files and stale links
-# (e.g. from the old Stow setup) are backed up to ~/.dotstate-backups/.
+# are backed up to ~/.dotstate-backups/.
 link_dotfiles() {
     if ! command_exists dotstate; then
         print_error "dotstate is not installed. Please install it first."
@@ -713,9 +652,6 @@ link_dotfiles() {
 
     print_header "Linking dotfiles with dotstate..."
 
-    migrate_legacy_state
-    remove_legacy_parent_links
-
     local config="$HOME/.config/dotstate/config.toml"
 
     # First-time setup is TUI-only in dotstate, so write a Local-mode config
diff --git a/test.sh b/test.sh
index c5e876d..94dceab 100755
--- a/test.sh
+++ b/test.sh
@@ -1002,26 +1002,19 @@ if command_exists dotstate; then
         LINK_ERRORS=$((LINK_ERRORS + 1))
     fi
 
-    # Existing machine pulling a new layout: a clone of this checkout, with
-    # untracked state left at a pre-dotstate path and a manifest entry added
-    # after the first link
+    # Existing machine pulling a new layout: a clone of this checkout with a
+    # manifest entry added after the first link
     LINK_CLONE="$LINK_TEST_ROOT/repo"
     LINK_PULL_HOME="$LINK_TEST_ROOT/pull"
     mkdir -p "$LINK_PULL_HOME"
     git clone -q "$LINK_REPO" "$LINK_CLONE"
     git -C "$LINK_CLONE" checkout -q "$(git rev-parse HEAD)"
     cp install.sh "$LINK_CLONE/install.sh"
-    mkdir -p "$LINK_CLONE/.config/zsh"
-    printf '%s\n' 'export LEGACY=1' > "$LINK_CLONE/.config/zsh/secrets.zsh"
 
     LINK_RESULT=0
     LINK_REPO="$LINK_CLONE" link_run "$LINK_PULL_HOME" linux run1 || LINK_RESULT=$?
-    if [ "$LINK_RESULT" -eq 0 ] &&
-       [ ! -e "$LINK_CLONE/.config" ] &&
-       grep -qx 'export LEGACY=1' "$LINK_PULL_HOME/.config/zsh/secrets.zsh"; then
-        echo -e "${GREEN}✓ untracked state at pre-dotstate paths moves into the linked directory${NC}"
-    else
-        echo -e "${RED}✗ link_dotfiles must move .config/zsh/secrets.zsh into common/ (exit $LINK_RESULT)${NC}"
+    if [ "$LINK_RESULT" -ne 0 ]; then
+        echo -e "${RED}✗ link_dotfiles must link a clone of this checkout (exit $LINK_RESULT)${NC}"
         cat "$LINK_PULL_HOME.run1.log"
         LINK_ERRORS=$((LINK_ERRORS + 1))
     fi

From 0276eff2587ec843738828074c8b999ea5ce30c9 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 03:00:38 +0100
Subject: [PATCH 3/8] refactor(install): run install steps as ordered
 components

Group the installer steps into named components (brew, gh, shell, tmux,
tools, link, herdr, skills) run from one ordered list, so parts of the
setup can be installed on their own. A full install runs the same steps
in the same order. Shared checks used by the installers move into small
helpers, and the ordering tests read the step order from the components.
---
 install.sh | 219 ++++++++++++++++++++++++++++++++++++++++-------------
 test.sh    |  42 ++++++----
 2 files changed, 194 insertions(+), 67 deletions(-)

diff --git a/install.sh b/install.sh
index e9595e7..474bb6a 100755
--- a/install.sh
+++ b/install.sh
@@ -128,6 +128,7 @@ setup_codespaces_environment() {
     if [ -d "$PERSISTED_DOTFILES" ]; then
         DOTFILES="$PERSISTED_DOTFILES"
         BREWFILE="$DOTFILES/common/.config/brew/Brewfile"
+        GH_EXTENSIONS_FILE="$DOTFILES/common/.config/gh/extensions"
         print_success "Using dotfiles at: $DOTFILES"
     else
         print_warning "Persisted dotfiles not found at $PERSISTED_DOTFILES"
@@ -180,18 +181,23 @@ install_linux_homebrew_dependencies() {
     print_success "Homebrew dependencies installed"
 }
 
+# Put an installed brew on PATH; it may be missing in a fresh shell on Apple
+# Silicon or Linux
+load_brew_env() {
+    command_exists brew && return
+
+    local brew_bin
+    for brew_bin in /opt/homebrew/bin/brew /usr/local/bin/brew /home/linuxbrew/.linuxbrew/bin/brew; do
+        if [ -x "$brew_bin" ]; then
+            eval "$("$brew_bin" shellenv)"
+            return
+        fi
+    done
+}
+
 # Install Homebrew
 install_homebrew() {
-    # brew may be installed but not on PATH yet (fresh shell on Apple Silicon or Linux)
-    if ! command_exists brew; then
-        local brew_bin
-        for brew_bin in /opt/homebrew/bin/brew /usr/local/bin/brew /home/linuxbrew/.linuxbrew/bin/brew; do
-            if [ -x "$brew_bin" ]; then
-                eval "$("$brew_bin" shellenv)"
-                break
-            fi
-        done
-    fi
+    load_brew_env
 
     if command_exists brew; then
         print_success "Homebrew already installed"
@@ -351,13 +357,18 @@ ZSH_GITHUB_PLUGINS=(
     jeffreytse/zsh-vi-mode
 )
 
+zsh_plugins_dir() {
+    echo "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins"
+}
+
 install_zsh_plugins() {
     if [ ! -d "$HOME/.oh-my-zsh" ]; then
         print_warning "oh-my-zsh not installed, skipping zsh plugins"
         return
     fi
 
-    local plugins_dir="${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins"
+    local plugins_dir
+    plugins_dir="$(zsh_plugins_dir)"
     local plugin name
     mkdir -p "$plugins_dir"
 
@@ -411,6 +422,14 @@ set_zsh_default() {
     fi
 }
 
+# Print the Brewfile's casks in the form HOMEBREW_BUNDLE_CASK_SKIP takes:
+# space-separated names, not a boolean
+brewfile_casks() {
+    local casks
+    casks="$(brew bundle list --cask --file="$BREWFILE")" || return 1
+    echo "${casks//$'\n'/ }"
+}
+
 # Install packages from Brewfile
 install_brew_packages() {
     if [ ! -f "$BREWFILE" ]; then
@@ -428,12 +447,11 @@ install_brew_packages() {
     elif [ "$NO_GUI" = true ]; then
         print_header "Installing CLI packages only (skipping GUI applications)..."
         local casks
-        # HOMEBREW_BUNDLE_CASK_SKIP takes space-separated cask names, not a boolean
-        if ! casks="$(brew bundle list --cask --file="$BREWFILE")"; then
+        if ! casks="$(brewfile_casks)"; then
             print_error "Could not read casks from Brewfile: $BREWFILE"
             return 1
         fi
-        if ! HOMEBREW_DOWNLOAD_CONCURRENCY=1 HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_BUNDLE_CASK_SKIP="${casks//$'\n'/ }" brew bundle --jobs=1 --verbose --file="$BREWFILE"; then
+        if ! HOMEBREW_DOWNLOAD_CONCURRENCY=1 HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_BUNDLE_CASK_SKIP="$casks" brew bundle --jobs=1 --verbose --file="$BREWFILE"; then
             print_error "Homebrew failed to install CLI packages from: $BREWFILE"
             return 1
         fi
@@ -526,6 +544,23 @@ install_ccstatusline() {
     fi
 }
 
+GH_EXTENSIONS_FILE="$DOTFILES/common/.config/gh/extensions"
+
+# Print the extensions listed in GH_EXTENSIONS_FILE, trimmed, without blank
+# lines and comments
+gh_extensions_wanted() {
+    [ -f "$GH_EXTENSIONS_FILE" ] || return 0
+    local extension
+    while IFS= read -r extension || [ -n "$extension" ]; do
+        [[ -z "$extension" || "$extension" =~ ^# ]] && continue
+        echo "$extension" | xargs
+    done < "$GH_EXTENSIONS_FILE"
+}
+
+gh_extension_installed() {
+    gh extension list 2>/dev/null | grep -F -- "$1" >/dev/null
+}
+
 # Install GitHub CLI extensions
 install_gh_extensions() {
     if ! command_exists gh; then
@@ -545,10 +580,8 @@ install_gh_extensions() {
         return
     fi
 
-    local extensions_file="$DOTFILES/common/.config/gh/extensions"
-
-    if [ ! -f "$extensions_file" ]; then
-        print_info "No gh extensions file found at $extensions_file"
+    if [ ! -f "$GH_EXTENSIONS_FILE" ]; then
+        print_info "No gh extensions file found at $GH_EXTENSIONS_FILE"
         return
     fi
 
@@ -557,16 +590,8 @@ install_gh_extensions() {
     local installed=0
     local skipped=0
 
-    # Read extensions file line by line
-    while IFS= read -r extension || [ -n "$extension" ]; do
-        # Skip empty lines and comments
-        [[ -z "$extension" || "$extension" =~ ^# ]] && continue
-
-        # Trim whitespace
-        extension=$(echo "$extension" | xargs)
-
-        # Check if already installed
-        if gh extension list 2>/dev/null | grep -F -- "$extension" >/dev/null; then
+    while IFS= read -r extension; do
+        if gh_extension_installed "$extension"; then
             print_success "$extension already installed"
             skipped=$((skipped + 1))
         else
@@ -578,7 +603,7 @@ install_gh_extensions() {
                 print_warning "Failed to install $extension"
             fi
         fi
-    done < "$extensions_file"
+    done < <(gh_extensions_wanted)
 
     if [ $installed -eq 0 ] && [ $skipped -eq 0 ]; then
         print_info "No extensions to install"
@@ -688,6 +713,19 @@ EOF
 }
 
 # Install trusted Herd (herdr) plugins
+# herdr plugins as plugin_id:source
+HERDR_PLUGINS=(
+    "persiyanov.reviewr:persiyanov/herdr-reviewr"
+    "worktrunk:devashish2203/herdr-worktrunk"
+    "dutifuldev.ghzinga:dutifuldev/ghzinga/plugins/herdr"
+)
+
+# Usage: herdr_plugin_installed <herdr plugin list --json output> <plugin_id>
+herdr_plugin_installed() {
+    printf '%s' "$1" | jq -e --arg id "$2" \
+        'any(.result.plugins[]; .plugin_id == $id)' >/dev/null 2>&1
+}
+
 install_herdr_plugins() {
     if [ -n "${CI:-}" ]; then
         print_info "CI environment detected, skipping herdr plugin installation"
@@ -706,12 +744,6 @@ install_herdr_plugins() {
 
     print_header "Installing herdr plugins..."
 
-    local herdr_plugins=(
-        "persiyanov.reviewr:persiyanov/herdr-reviewr"
-        "worktrunk:devashish2203/herdr-worktrunk"
-        "dutifuldev.ghzinga:dutifuldev/ghzinga/plugins/herdr"
-    )
-
     local installed_json
     if ! installed_json="$(herdr plugin list --json </dev/null)"; then
         print_error "Failed to list installed herdr plugins"
@@ -732,12 +764,11 @@ install_herdr_plugins() {
     local plugin_id
     local plugin_source
 
-    for entry in "${herdr_plugins[@]}"; do
+    for entry in "${HERDR_PLUGINS[@]}"; do
         plugin_id="${entry%%:*}"
         plugin_source="${entry#*:}"
 
-        if printf '%s' "$installed_json" | jq -e --arg id "$plugin_id" \
-            'any(.result.plugins[]; .plugin_id == $id)' >/dev/null 2>&1; then
+        if herdr_plugin_installed "$installed_json" "$plugin_id"; then
             print_success "herdr plugin already installed: $plugin_id"
             continue
         fi
@@ -881,38 +912,120 @@ print_summary() {
     fi
 }
 
-# Main installation flow
-main() {
-    parse_args "$@"
-
-    setup_codespaces_environment
-
-    echo -e "${MAGENTA}"
-    echo "╔════════════════════════════════════════╗"
-    echo "║     Dotfiles Setup & Installation     ║"
-    echo "║                                        ║"
-    echo "║  This will install development tools   ║"
-    echo "║  and configure your environment        ║"
-    echo "╚════════════════════════════════════════╝"
-    echo -e "${NC}"
+# Install components in run order. main installs all of them; dots installs
+# a selection.
+COMPONENTS=(brew gh shell tmux tools link herdr skills)
+
+component_description() {
+    case "$1" in
+        brew) echo "Homebrew and the Brewfile packages" ;;
+        gh) echo "GitHub CLI extensions" ;;
+        shell) echo "zsh as default shell, oh-my-zsh and its custom plugins" ;;
+        tmux) echo "tmux plugin manager" ;;
+        tools) echo "uv, OpenCode and ccstatusline" ;;
+        link) echo "dotstate and the dotfile links" ;;
+        herdr) echo "herdr plugins" ;;
+        skills) echo "agent skills missing from the skills lockfile" ;;
+    esac
+}
 
-    detect_os
+component_brew() {
     install_linux_homebrew_dependencies
     install_homebrew
     bootstrap_codespaces_homebrew
     install_brew_packages
+}
+
+component_gh() {
     install_gh_extensions
+}
+
+component_shell() {
     set_zsh_default
     install_oh_my_zsh
     install_zsh_plugins
+}
+
+component_tmux() {
     install_tpm
+}
+
+component_tools() {
     install_uv
     install_opencode
     install_ccstatusline
+}
+
+component_link() {
     install_dotstate
     link_dotfiles
+}
+
+component_herdr() {
     install_herdr_plugins
+}
+
+component_skills() {
     install_agent_skills
+}
+
+# Set SELECTED_COMPONENTS to the given component names in run order, each
+# once; fail on an unknown name
+select_components() {
+    local name selected
+    for selected in "$@"; do
+        case " ${COMPONENTS[*]} " in
+            *" $selected "*) ;;
+            *)
+                print_error "Unknown component: $selected (known: ${COMPONENTS[*]})"
+                return 1
+                ;;
+        esac
+    done
+
+    SELECTED_COMPONENTS=()
+    for name in "${COMPONENTS[@]}"; do
+        for selected in "$@"; do
+            if [ "$selected" = "$name" ]; then
+                SELECTED_COMPONENTS+=("$name")
+                break
+            fi
+        done
+    done
+}
+
+# Runs before each component; dots overrides it to check prerequisites
+before_component() {
+    :
+}
+
+# Install the given components in run order
+run_components() {
+    local name
+    select_components "$@" || return 1
+    for name in "${SELECTED_COMPONENTS[@]}"; do
+        before_component "$name" || return 1
+        "component_$name"
+    done
+}
+
+# Main installation flow
+main() {
+    parse_args "$@"
+
+    setup_codespaces_environment
+
+    echo -e "${MAGENTA}"
+    echo "╔════════════════════════════════════════╗"
+    echo "║     Dotfiles Setup & Installation     ║"
+    echo "║                                        ║"
+    echo "║  This will install development tools   ║"
+    echo "║  and configure your environment        ║"
+    echo "╚════════════════════════════════════════╝"
+    echo -e "${NC}"
+
+    detect_os
+    run_components "${COMPONENTS[@]}"
     print_summary
 }
 
diff --git a/test.sh b/test.sh
index 94dceab..c5a0159 100755
--- a/test.sh
+++ b/test.sh
@@ -22,6 +22,27 @@ command_exists() {
     command -v "$1" >/dev/null 2>&1
 }
 
+# Print the steps of a full install in run order: main runs every component
+# in COMPONENTS order, and each component_* function runs its steps in order
+install_step_order() {
+    # shellcheck disable=SC2016
+    grep -qxF '    run_components "${COMPONENTS[@]}"' install.sh || return 1
+    bash -c 'source ./install.sh
+        for component in "${COMPONENTS[@]}"; do
+            declare -f "component_$component" | sed -n "s/^    \([a-z_]*\);*$/\1/p"
+        done'
+}
+
+INSTALL_STEP_ORDER="$(install_step_order || true)"
+
+# Succeed when install step $1 runs before step $2 in a full install
+step_runs_before() {
+    local first second
+    first="$(grep -nx "$1" <<< "$INSTALL_STEP_ORDER" | cut -d: -f1)"
+    second="$(grep -nx "$2" <<< "$INSTALL_STEP_ORDER" | cut -d: -f1)"
+    [ -n "$first" ] && [ -n "$second" ] && [ "$first" -lt "$second" ]
+}
+
 # Test 1: Shell script syntax with shellcheck
 echo -e "${BLUE}→ Checking shell scripts...${NC}"
 if command_exists shellcheck; then
@@ -412,14 +433,11 @@ echo -e "${BLUE}→ Checking herdr plugin installation...${NC}"
 HERDR_ERRORS=0
 
 # Structural ordering assertion: herdr plugins must install after dotfiles are
-# linked. This checks the literal call order in main(), not internal
-# implementation details, so it stays robust across refactors.
-LINK_LINE=$(grep -n '^    link_dotfiles$' install.sh | cut -d: -f1)
-HERDR_INSTALL_LINE=$(grep -n '^    install_herdr_plugins$' install.sh | cut -d: -f1)
-if [ -n "$LINK_LINE" ] && [ -n "$HERDR_INSTALL_LINE" ] && [ "$LINK_LINE" -lt "$HERDR_INSTALL_LINE" ]; then
+# linked
+if step_runs_before link_dotfiles install_herdr_plugins; then
     echo -e "${GREEN}✓ herdr plugins install after dotfiles are linked${NC}"
 else
-    echo -e "${RED}✗ install_herdr_plugins must run after link_dotfiles in main${NC}"
+    echo -e "${RED}✗ install_herdr_plugins must run after link_dotfiles in a full install${NC}"
     HERDR_ERRORS=$((HERDR_ERRORS + 1))
 fi
 
@@ -1055,12 +1073,10 @@ echo
 echo -e "${BLUE}→ Checking agent skill installation...${NC}"
 SKILLS_ERRORS=0
 
-LINK_LINE=$(grep -n '^    link_dotfiles$' install.sh | cut -d: -f1)
-SKILLS_INSTALL_LINE=$(grep -n '^    install_agent_skills$' install.sh | cut -d: -f1)
-if [ -n "$LINK_LINE" ] && [ -n "$SKILLS_INSTALL_LINE" ] && [ "$LINK_LINE" -lt "$SKILLS_INSTALL_LINE" ]; then
+if step_runs_before link_dotfiles install_agent_skills; then
     echo -e "${GREEN}✓ agent skills install after dotfiles are linked${NC}"
 else
-    echo -e "${RED}✗ install_agent_skills must run after link_dotfiles in main${NC}"
+    echo -e "${RED}✗ install_agent_skills must run after link_dotfiles in a full install${NC}"
     SKILLS_ERRORS=$((SKILLS_ERRORS + 1))
 fi
 
@@ -1217,12 +1233,10 @@ else
     CCSTATUS_ERRORS=$((CCSTATUS_ERRORS + 1))
 fi
 
-INSTALL_LINE=$(grep -n '^    install_brew_packages$' install.sh | cut -d: -f1)
-CCSTATUS_LINE=$(grep -n '^    install_ccstatusline$' install.sh | cut -d: -f1)
-if [ -n "$INSTALL_LINE" ] && [ -n "$CCSTATUS_LINE" ] && [ "$INSTALL_LINE" -lt "$CCSTATUS_LINE" ]; then
+if step_runs_before install_brew_packages install_ccstatusline; then
     echo -e "${GREEN}✓ ccstatusline installs after the Brewfile provides node${NC}"
 else
-    echo -e "${RED}✗ install_ccstatusline must run after install_brew_packages in main${NC}"
+    echo -e "${RED}✗ install_ccstatusline must run after install_brew_packages in a full install${NC}"
     CCSTATUS_ERRORS=$((CCSTATUS_ERRORS + 1))
 fi
 

From 0699b699d9b01203ae4f269afc0ae23efb234f9d Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 03:00:44 +0100
Subject: [PATCH 4/8] feat(dots): add CLI to install, check and update
 components

install.sh could only reinstall everything. dots installs selected
components (failing with a hint when a prerequisite is missing), reports
their status, updates them, and passes doctor/sync/add/remove through to
dotstate. It sources install.sh and is linked to ~/.local/bin/dots by
dotstate.
---
 .dotstate-profiles.toml |   1 +
 .gitignore              |   1 +
 README.md               |  22 +++
 common/.local/bin/dots  |   1 +
 dots                    | 307 ++++++++++++++++++++++++++++++++++++++++
 install.sh              |   2 +
 test.sh                 | 123 ++++++++++++++++
 7 files changed, 457 insertions(+)
 create mode 120000 common/.local/bin/dots
 create mode 100755 dots

diff --git a/.dotstate-profiles.toml b/.dotstate-profiles.toml
index 6776633..7998702 100644
--- a/.dotstate-profiles.toml
+++ b/.dotstate-profiles.toml
@@ -24,6 +24,7 @@ synced_files = [
     ".editorconfig",
     ".gitconfig",
     ".gitconfig-work",
+    ".local/bin/dots",
     ".pi/agent/settings.json",
     ".zprofile",
     ".zshenv",
diff --git a/.gitignore b/.gitignore
index 8e1ae01..7c4e5c7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
 !/linux/
 !/install.sh
 !/test.sh
+!/dots
 !/AGENTS.md
 !/README.md
 
diff --git a/README.md b/README.md
index c01b9c7..aaa8a68 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,28 @@ in the way are moved to `~/.dotstate-backups/<timestamp>/` with their paths
 kept. Re-running is safe and links paths added to the manifest since. Run
 `./test.sh` to validate configs and installer behavior.
 
+### Installing parts with `dots`
+
+`dots` installs, checks and updates one part of the setup at a time. Run it as
+`./dots` from a fresh clone; once linked it is on `PATH` as
+`~/.local/bin/dots`.
+
+```sh
+dots list                    # components, in install order
+dots install skills          # install only the missing agent skills
+dots install brew shell      # several components, run in install order
+dots install --all --no-gui  # everything, same as ./install.sh --no-gui
+dots status                  # which components look installed
+dots update brew herdr       # update components (default: all)
+dots link                    # link dotfiles with dotstate
+dots doctor                  # also: sync, add, remove (passed to dotstate)
+```
+
+Components are `brew`, `gh`, `shell`, `tmux`, `tools` (uv, OpenCode,
+ccstatusline), `link` (dotstate and the links), `herdr` and `skills`. `dots
+install` checks what a component needs from earlier ones and stops with a hint
+such as `npx not found; run: dots install brew` instead of installing it.
+
 To stop managing a path, run `dotstate remove <path> --yes` before deleting it
 from the repository, or `dotstate doctor` keeps reporting its dangling link.
 
diff --git a/common/.local/bin/dots b/common/.local/bin/dots
new file mode 120000
index 0000000..d3746ce
--- /dev/null
+++ b/common/.local/bin/dots
@@ -0,0 +1 @@
+../../../dots
\ No newline at end of file
diff --git a/dots b/dots
new file mode 100755
index 0000000..ed00873
--- /dev/null
+++ b/dots
@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+
+self="${BASH_SOURCE[0]}"
+while [ -L "$self" ]; do
+  self_dir="$(cd "$(dirname "$self")" && pwd)"
+  self="$(readlink "$self")"
+  case "$self" in
+  /*) ;;
+  *) self="$self_dir/$self" ;;
+  esac
+done
+# shellcheck source=install.sh
+source "$(cd "$(dirname "$self")" && pwd)/install.sh"
+
+show_dots_help() {
+  echo "Usage: dots <command> [args]"
+  echo ""
+  echo "Commands:"
+  echo "  install [--no-gui] <component>...  Install the given components"
+  echo "  install --all [--no-gui]           Install everything (same as ./install.sh)"
+  echo "  list                               List components in install order"
+  echo "  status [--no-gui] [component]...   Show which components are installed"
+  echo "  update [component]...              Update components (default: all)"
+  echo "  link                               Link dotfiles with dotstate"
+  echo "  doctor|sync|add|remove [args]      Run the dotstate command"
+  echo "  help                               Show this help message"
+  echo ""
+  echo "Components: ${COMPONENTS[*]}"
+}
+
+# Split args into DOTS_ARGS (component names) and DOTS_ALL; parse_args reads
+# --no-gui
+split_dots_args() {
+  local arg
+  DOTS_ARGS=()
+  DOTS_ALL=false
+  for arg in "$@"; do
+    case "$arg" in
+    --all) DOTS_ALL=true ;;
+    --no-gui) ;;
+    -*)
+      print_error "Unknown option: $arg"
+      return 1
+      ;;
+    *) DOTS_ARGS+=("$arg") ;;
+    esac
+  done
+}
+
+dots_init() {
+  parse_args "$@"
+  setup_codespaces_environment
+  detect_os
+  load_brew_env
+}
+
+# Fail unless $1 is installed, naming the component that provides it
+require_cmd() {
+  if ! command_exists "$1"; then
+    print_error "$1 not found; run: dots install $2"
+    return 1
+  fi
+}
+
+# Check what a component needs from components before it
+component_requires() {
+  case "$1" in
+  gh) require_cmd gh brew ;;
+  shell) require_cmd zsh brew && require_cmd git brew ;;
+  tmux) require_cmd git brew ;;
+  tools) require_cmd curl brew && require_cmd npm brew ;;
+  link) [ "$OS" != macos ] || require_cmd dotstate brew ;;
+  herdr) require_cmd herdr brew && require_cmd jq brew ;;
+  skills)
+    require_cmd npx brew && require_cmd jq brew || return 1
+    if [ ! -f "$HOME/.agents/.skill-lock.json" ]; then
+      print_error "No skills lockfile at ~/.agents/.skill-lock.json; run: dots install link"
+      return 1
+    fi
+    ;;
+  esac
+}
+
+# Check each component just before it runs, so earlier ones in the same call
+# can provide what it needs
+before_component() {
+  load_brew_env
+  component_requires "$1"
+}
+
+fail() {
+  echo "$*"
+  return 1
+}
+
+# Fail listing the names in "$@", if any
+fail_missing() {
+  [ $# -eq 0 ] || fail "missing: $*"
+}
+
+# Per-component checks: print what is missing and fail, or succeed silently
+status_brew() {
+  command_exists brew || fail "brew not installed" || return
+  local casks=""
+  if [ "$OS" = linux ] || [ "$NO_GUI" = true ]; then
+    casks="$(brewfile_casks 2>/dev/null)" || fail "could not read casks from the Brewfile" || return
+  fi
+  HOMEBREW_BUNDLE_CASK_SKIP="$casks" brew bundle check --file="$BREWFILE" >/dev/null 2>&1 ||
+    fail "Brewfile packages missing"
+}
+
+status_gh() {
+  command_exists gh || fail "gh not installed" || return
+  local extension missing=()
+  while IFS= read -r extension; do
+    gh_extension_installed "$extension" || missing+=("$extension")
+  done < <(gh_extensions_wanted)
+  fail_missing "${missing[@]}"
+}
+
+status_shell() {
+  [ "$(basename "$SHELL")" = zsh ] || fail "default shell is $SHELL" || return
+  [ -d "$HOME/.oh-my-zsh" ] || fail "oh-my-zsh not installed" || return
+  local plugins_dir plugin missing=()
+  plugins_dir="$(zsh_plugins_dir)"
+  for plugin in "${ZSH_GITHUB_PLUGINS[@]}"; do
+    [ -d "$plugins_dir/${plugin#*/}" ] || missing+=("${plugin#*/}")
+  done
+  fail_missing "${missing[@]}"
+}
+
+status_tmux() {
+  [ -d "$HOME/.tmux/plugins/tpm" ] || fail "tpm not installed"
+}
+
+status_tools() {
+  local tool missing=()
+  for tool in uv opencode ccstatusline; do
+    command_exists "$tool" || missing+=("$tool")
+  done
+  fail_missing "${missing[@]}"
+}
+
+status_link() {
+  command_exists dotstate || fail "dotstate not installed" || return
+  dotstate doctor --no-colors >/dev/null 2>&1 || fail "dotstate doctor reports issues; run: dots doctor"
+}
+
+status_herdr() {
+  command_exists herdr || fail "herdr not installed" || return
+  command_exists jq || fail "jq not installed" || return
+  local installed_json entry missing=()
+  installed_json="$(herdr plugin list --json </dev/null 2>/dev/null)" || fail "could not list plugins" || return
+  for entry in "${HERDR_PLUGINS[@]}"; do
+    herdr_plugin_installed "$installed_json" "${entry%%:*}" || missing+=("${entry%%:*}")
+  done
+  fail_missing "${missing[@]}"
+}
+
+status_skills() {
+  local lock="$HOME/.agents/.skill-lock.json" names name missing=()
+  [ -f "$lock" ] || fail "no skills lockfile" || return
+  command_exists jq || fail "jq not installed" || return
+  names="$(jq -r '.skills | keys[]' "$lock" 2>/dev/null)" || fail "unreadable lockfile" || return
+  while IFS= read -r name; do
+    [ -z "$name" ] || [ -d "$HOME/.agents/skills/$name" ] || missing+=("$name")
+  done <<<"$names"
+  fail_missing "${missing[@]}"
+}
+
+# Per-component updates; components without one are skipped
+update_brew() {
+  require_cmd brew brew || return 1
+  # Upgrade only what is installed, so a --no-gui machine gets no casks
+  brew update
+  brew upgrade
+}
+
+update_gh() {
+  require_cmd gh brew || return 1
+  gh extension upgrade --all
+}
+
+update_shell() {
+  [ -d "$HOME/.oh-my-zsh" ] || {
+    print_error "oh-my-zsh not installed; run: dots install shell"
+    return 1
+  }
+  ZSH="$HOME/.oh-my-zsh" zsh -f "$HOME/.oh-my-zsh/tools/upgrade.sh"
+  local plugins_dir plugin
+  plugins_dir="$(zsh_plugins_dir)"
+  for plugin in "${ZSH_GITHUB_PLUGINS[@]}"; do
+    if [ -d "$plugins_dir/${plugin#*/}" ]; then
+      print_info "Updating zsh plugin ${plugin#*/}"
+      git -C "$plugins_dir/${plugin#*/}" pull --ff-only --recurse-submodules
+    fi
+  done
+}
+
+update_tmux() {
+  [ -x "$HOME/.tmux/plugins/tpm/bin/update_plugins" ] || {
+    print_error "tpm not installed; run: dots install tmux"
+    return 1
+  }
+  "$HOME/.tmux/plugins/tpm/bin/update_plugins" all
+}
+
+update_herdr() {
+  require_cmd herdr brew || return 1
+  herdr plugin update --yes </dev/null
+}
+
+update_skills() {
+  require_cmd npx brew || return 1
+  npx -y skills update --global --yes </dev/null
+}
+
+cmd_install() {
+  split_dots_args "$@" || return 1
+  if [ "$DOTS_ALL" = true ]; then
+    [ ${#DOTS_ARGS[@]} -eq 0 ] || {
+      print_error "--all takes no components"
+      return 1
+    }
+    main "$@"
+    return
+  fi
+  if [ ${#DOTS_ARGS[@]} -eq 0 ]; then
+    print_error "Name the components to install, or pass --all (components: ${COMPONENTS[*]})"
+    return 1
+  fi
+
+  select_components "${DOTS_ARGS[@]}" || return 1
+  dots_init "$@"
+  run_components "${DOTS_ARGS[@]}"
+}
+
+cmd_list() {
+  local name
+  for name in "${COMPONENTS[@]}"; do
+    printf '  %-8s %s\n' "$name" "$(component_description "$name")"
+  done
+}
+
+cmd_status() {
+  local name detail failed=0
+  split_dots_args "$@" || return 1
+  [ ${#DOTS_ARGS[@]} -gt 0 ] || DOTS_ARGS=("${COMPONENTS[@]}")
+  select_components "${DOTS_ARGS[@]}" || return 1
+  dots_init "$@" >/dev/null
+  for name in "${SELECTED_COMPONENTS[@]}"; do
+    if detail="$("status_$name")"; then
+      print_success "$name"
+    else
+      print_error "$name: $detail"
+      failed=$((failed + 1))
+    fi
+  done
+  [ $failed -eq 0 ]
+}
+
+cmd_update() {
+  local name
+  split_dots_args "$@" || return 1
+  [ ${#DOTS_ARGS[@]} -gt 0 ] || DOTS_ARGS=("${COMPONENTS[@]}")
+  select_components "${DOTS_ARGS[@]}" || return 1
+  dots_init "$@"
+  for name in "${SELECTED_COMPONENTS[@]}"; do
+    if declare -F "update_$name" >/dev/null; then
+      print_header "Updating $name..."
+      "update_$name"
+    else
+      print_info "Nothing to update for $name"
+    fi
+  done
+}
+
+dots_main() {
+  local cmd="${1:-help}"
+  [ $# -eq 0 ] || shift
+  case "$cmd" in
+  install) cmd_install "$@" ;;
+  list) cmd_list ;;
+  status) cmd_status "$@" ;;
+  update) cmd_update "$@" ;;
+  link)
+    dots_init
+    link_dotfiles
+    ;;
+  doctor | sync | add | remove)
+    load_brew_env
+    require_cmd dotstate link || return 1
+    dotstate "$cmd" "$@"
+    ;;
+  help | --help | -h) show_dots_help ;;
+  *)
+    print_error "Unknown command: $cmd"
+    show_dots_help
+    return 1
+    ;;
+  esac
+}
+
+# Run dots_main (skip when this script is sourced, e.g. by test.sh)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  dots_main "$@"
+fi
diff --git a/install.sh b/install.sh
index 474bb6a..9bfa525 100755
--- a/install.sh
+++ b/install.sh
@@ -61,6 +61,8 @@ show_help() {
     echo "Example:"
     echo "  $0              # Install everything"
     echo "  $0 --no-gui     # Install only CLI tools"
+    echo ""
+    echo "Install single components with: $DOTFILES/dots install <component>"
 }
 
 # Helper functions
diff --git a/test.sh b/test.sh
index c5a0159..ca43117 100755
--- a/test.sh
+++ b/test.sh
@@ -58,6 +58,16 @@ if command_exists shellcheck; then
         fi
     fi
 
+    # Check the dots CLI
+    if [ -f "dots" ]; then
+        if shellcheck -x dots; then
+            echo -e "${GREEN}✓ dots passed shellcheck${NC}"
+        else
+            echo -e "${RED}✗ dots has shellcheck issues${NC}"
+            SHELL_ERRORS=$((SHELL_ERRORS + 1))
+        fi
+    fi
+
     # Check test.sh itself
     if [ -f "test.sh" ]; then
         if shellcheck test.sh; then
@@ -858,6 +868,13 @@ else
     MANIFEST_ERRORS=$((MANIFEST_ERRORS + 1))
 fi
 
+if git check-ignore -q --no-index dots common/.local/bin/dots; then
+    echo -e "${RED}✗ dots and common/.local/bin/dots must remain trackable${NC}"
+    MANIFEST_ERRORS=$((MANIFEST_ERRORS + 1))
+else
+    echo -e "${GREEN}✓ the dots CLI and its link are trackable${NC}"
+fi
+
 if git check-ignore -q --no-index common/.agents/skills/paranoid-review/SKILL.md; then
     echo -e "${RED}✗ common/.agents/skills/paranoid-review/SKILL.md must remain trackable${NC}"
     MANIFEST_ERRORS=$((MANIFEST_ERRORS + 1))
@@ -1247,6 +1264,112 @@ if [ $CCSTATUS_ERRORS -gt 0 ]; then
 fi
 echo
 
+# Test 16: the dots CLI installs components selectively
+echo -e "${BLUE}→ Checking the dots CLI...${NC}"
+DOTS_ERRORS=0
+
+# The full install runs exactly these steps in this order
+DOTS_EXPECTED_STEPS="install_linux_homebrew_dependencies
+install_homebrew
+bootstrap_codespaces_homebrew
+install_brew_packages
+install_gh_extensions
+set_zsh_default
+install_oh_my_zsh
+install_zsh_plugins
+install_tpm
+install_uv
+install_opencode
+install_ccstatusline
+install_dotstate
+link_dotfiles
+install_herdr_plugins
+install_agent_skills"
+if [ "$INSTALL_STEP_ORDER" = "$DOTS_EXPECTED_STEPS" ]; then
+    echo -e "${GREEN}✓ a full install runs every step in the expected order${NC}"
+else
+    echo -e "${RED}✗ main must run every install step once, in the expected order:${NC}"
+    echo "$INSTALL_STEP_ORDER"
+    DOTS_ERRORS=$((DOTS_ERRORS + 1))
+fi
+DOTS_TEST_DIR="$(mktemp -d "${TMPDIR:-/tmp}/dots-test.XXXXXX")"
+mkdir -p "$DOTS_TEST_DIR/bin" "$DOTS_TEST_DIR/home/.local/bin"
+cat > "$DOTS_TEST_DIR/bin/dotstate" <<'STUB'
+#!/usr/bin/env bash
+echo "dotstate $*" >> "$DOTS_STUB_LOG"
+STUB
+chmod +x "$DOTS_TEST_DIR/bin/dotstate"
+
+# Runs dots_main with stubbed components that log instead of installing, no
+# Homebrew and only the stubs on PATH. Args are passed to dots_main; set
+# DOTS_SKIP_REQUIRES=1 to stub the prerequisite checks too.
+run_dots() {
+    : > "$DOTS_TEST_DIR/log"
+    # shellcheck disable=SC2016
+    env HOME="$DOTS_TEST_DIR/home" PATH="$DOTS_TEST_DIR/bin:/usr/bin:/bin" \
+        DOTS_STUB_LOG="$DOTS_TEST_DIR/log" DOTS_SKIP_REQUIRES="${DOTS_SKIP_REQUIRES:-}" bash -c '
+        source ./dots
+        load_brew_env() { :; }
+        [ -z "$DOTS_SKIP_REQUIRES" ] || component_requires() { :; }
+        for component in "${COMPONENTS[@]}"; do
+            eval "component_$component() { echo $component >> \"\$DOTS_STUB_LOG\"; }"
+        done
+        dots_main "$@"' _ "$@" >"$DOTS_TEST_DIR/out" 2>&1
+}
+
+DOTS_COMPONENTS="$(bash -c 'source ./install.sh; printf "%s\n" "${COMPONENTS[@]}"')"
+ln -s "$(pwd)/common/.local/bin/dots" "$DOTS_TEST_DIR/home/.local/bin/dots"
+if [ "$("$DOTS_TEST_DIR/home/.local/bin/dots" list | awk '{ print $1 }')" = "$DOTS_COMPONENTS" ]; then
+    echo -e "${GREEN}✓ dots list shows every component through the linked command${NC}"
+else
+    echo -e "${RED}✗ dots list, run through ~/.local/bin/dots, must print every component in order${NC}"
+    DOTS_ERRORS=$((DOTS_ERRORS + 1))
+fi
+
+# Neither Homebrew nor npx is on the stub PATH
+if ! run_dots install skills && [ ! -s "$DOTS_TEST_DIR/log" ] &&
+   grep -q 'npx not found; run: dots install brew' "$DOTS_TEST_DIR/out"; then
+    echo -e "${GREEN}✓ dots install fails with a hint when a component's prerequisites are missing${NC}"
+else
+    echo -e "${RED}✗ dots install skills without npx must stop with a 'run: dots install brew' hint before running anything${NC}"
+    cat "$DOTS_TEST_DIR/out"
+    DOTS_ERRORS=$((DOTS_ERRORS + 1))
+fi
+
+if DOTS_SKIP_REQUIRES=1 run_dots install skills tools shell skills &&
+   [ "$(cat "$DOTS_TEST_DIR/log")" = "$(printf '%s\n' shell tools skills)" ]; then
+    echo -e "${GREEN}✓ dots install runs the selected components once each in install order${NC}"
+else
+    echo -e "${RED}✗ dots install skills tools shell skills must run shell, tools, skills once each${NC}"
+    cat "$DOTS_TEST_DIR/out"
+    DOTS_ERRORS=$((DOTS_ERRORS + 1))
+fi
+
+if ! run_dots install brew nope && [ ! -s "$DOTS_TEST_DIR/log" ] &&
+   grep -q 'Unknown component: nope' "$DOTS_TEST_DIR/out" &&
+   ! run_dots install; then
+    echo -e "${GREEN}✓ dots install rejects unknown or missing components without installing anything${NC}"
+else
+    echo -e "${RED}✗ dots install must reject unknown components and an empty selection${NC}"
+    DOTS_ERRORS=$((DOTS_ERRORS + 1))
+fi
+
+if run_dots doctor --fix && [ "$(cat "$DOTS_TEST_DIR/log")" = "dotstate doctor --fix" ] &&
+   run_dots sync -m "Update foo" && [ "$(cat "$DOTS_TEST_DIR/log")" = "dotstate sync -m Update foo" ]; then
+    echo -e "${GREEN}✓ dots passes dotstate commands through with their arguments${NC}"
+else
+    echo -e "${RED}✗ dots doctor/sync must run dotstate with the same arguments${NC}"
+    cat "$DOTS_TEST_DIR/out"
+    DOTS_ERRORS=$((DOTS_ERRORS + 1))
+fi
+
+rm -rf "$DOTS_TEST_DIR"
+unset -f run_dots
+if [ $DOTS_ERRORS -gt 0 ]; then
+    ERRORS=$((ERRORS + DOTS_ERRORS))
+fi
+echo
+
 # Summary
 echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then

From 59402ece0fc4ba6197bf0aabb0b8c300bca2c23c Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 03:11:12 +0100
Subject: [PATCH 5/8] fix(install): reject multiword component names

The substring check accepted an argument like 'brew gh', which then
matched no component, so dots install, status and update silently did
nothing. Compare each argument against the component names exactly.
---
 install.sh | 17 +++++++++--------
 test.sh    |  1 +
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/install.sh b/install.sh
index 9bfa525..5b781ca 100755
--- a/install.sh
+++ b/install.sh
@@ -974,15 +974,16 @@ component_skills() {
 # Set SELECTED_COMPONENTS to the given component names in run order, each
 # once; fail on an unknown name
 select_components() {
-    local name selected
+    local name selected known
     for selected in "$@"; do
-        case " ${COMPONENTS[*]} " in
-            *" $selected "*) ;;
-            *)
-                print_error "Unknown component: $selected (known: ${COMPONENTS[*]})"
-                return 1
-                ;;
-        esac
+        known=false
+        for name in "${COMPONENTS[@]}"; do
+            [ "$selected" != "$name" ] || known=true
+        done
+        if [ "$known" = false ]; then
+            print_error "Unknown component: $selected (known: ${COMPONENTS[*]})"
+            return 1
+        fi
     done
 
     SELECTED_COMPONENTS=()
diff --git a/test.sh b/test.sh
index ca43117..ad43944 100755
--- a/test.sh
+++ b/test.sh
@@ -1351,6 +1351,7 @@ if ! run_dots install brew nope && [ ! -s "$DOTS_TEST_DIR/log" ] &&
     echo -e "${GREEN}✓ dots install rejects unknown or missing components without installing anything${NC}"
 else
     echo -e "${RED}✗ dots install must reject unknown components and an empty selection${NC}"
+   ! run_dots install 'brew gh' && [ ! -s "$DOTS_TEST_DIR/log" ] &&
     DOTS_ERRORS=$((DOTS_ERRORS + 1))
 fi
 

From 5b648a2c4016b36770899a215fc0089e526a750a Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 03:11:13 +0100
Subject: [PATCH 6/8] test(dots): hide npx explicitly in the
 missing-prerequisite check

The check relied on npx being absent from /usr/bin:/bin, which fails on
hosts with distro-installed Node. Stub command_exists to hide it instead.
---
 test.sh | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/test.sh b/test.sh
index ad43944..1d0d105 100755
--- a/test.sh
+++ b/test.sh
@@ -1302,15 +1302,20 @@ chmod +x "$DOTS_TEST_DIR/bin/dotstate"
 
 # Runs dots_main with stubbed components that log instead of installing, no
 # Homebrew and only the stubs on PATH. Args are passed to dots_main; set
-# DOTS_SKIP_REQUIRES=1 to stub the prerequisite checks too.
+# DOTS_SKIP_REQUIRES=1 to stub the prerequisite checks too, and DOTS_HIDE_CMD
+# to a command that must look missing even if the host has it.
 run_dots() {
     : > "$DOTS_TEST_DIR/log"
     # shellcheck disable=SC2016
     env HOME="$DOTS_TEST_DIR/home" PATH="$DOTS_TEST_DIR/bin:/usr/bin:/bin" \
-        DOTS_STUB_LOG="$DOTS_TEST_DIR/log" DOTS_SKIP_REQUIRES="${DOTS_SKIP_REQUIRES:-}" bash -c '
+        DOTS_STUB_LOG="$DOTS_TEST_DIR/log" DOTS_SKIP_REQUIRES="${DOTS_SKIP_REQUIRES:-}" \
+        DOTS_HIDE_CMD="${DOTS_HIDE_CMD:-}" bash -c '
         source ./dots
         load_brew_env() { :; }
         [ -z "$DOTS_SKIP_REQUIRES" ] || component_requires() { :; }
+        if [ -n "$DOTS_HIDE_CMD" ]; then
+            command_exists() { [ "$1" != "$DOTS_HIDE_CMD" ] && command -v "$1" >/dev/null 2>&1; }
+        fi
         for component in "${COMPONENTS[@]}"; do
             eval "component_$component() { echo $component >> \"\$DOTS_STUB_LOG\"; }"
         done
@@ -1326,8 +1331,7 @@ else
     DOTS_ERRORS=$((DOTS_ERRORS + 1))
 fi
 
-# Neither Homebrew nor npx is on the stub PATH
-if ! run_dots install skills && [ ! -s "$DOTS_TEST_DIR/log" ] &&
+if ! DOTS_HIDE_CMD=npx run_dots install skills && [ ! -s "$DOTS_TEST_DIR/log" ] &&
    grep -q 'npx not found; run: dots install brew' "$DOTS_TEST_DIR/out"; then
     echo -e "${GREEN}✓ dots install fails with a hint when a component's prerequisites are missing${NC}"
 else

From c4eace8c628b19040543fd5cf44ce69e43198fdf Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 03:11:13 +0100
Subject: [PATCH 7/8] feat(dots): update standalone tools

dots update skipped the tools component. Update uv with uv self update,
OpenCode with opencode upgrade and ccstatusline with npm, matching how
each is installed.
---
 dots | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/dots b/dots
index ed00873..6ebeaff 100755
--- a/dots
+++ b/dots
@@ -206,6 +206,19 @@ update_tmux() {
 }
 
 update_herdr() {
+# uv and OpenCode come from their own installers, ccstatusline from npm
+update_tools() {
+  if command_exists uv; then
+    uv self update || print_warning "uv self update failed; if a package manager installed uv, update it there"
+  fi
+  if command_exists opencode; then
+    opencode upgrade </dev/null
+  fi
+  if command_exists ccstatusline && command_exists npm; then
+    npm install --global ccstatusline@latest </dev/null
+  fi
+}
+
   require_cmd herdr brew || return 1
   herdr plugin update --yes </dev/null
 }

From 4823ba3b118c9db9952b174199762918754922d5 Mon Sep 17 00:00:00 2001
From: mainframev <vgenaev@gmail.com>
Date: Sun, 25 Oct 2026 03:11:13 +0100
Subject: [PATCH 8/8] fix(dots): guard skills update and check the linked
 repository

skills update reinstalls through the same Claude Code paths that
install_agent_skills refuses to replace, so update only installed skills
whose ~/.claude/skills entry is not a real directory. dots status link
trusted dotstate doctor even when dotstate links another checkout; check
repo_path first, sharing the checks with install.sh.
---
 dots       | 29 ++++++++++++++++++++++++++---
 install.sh | 19 +++++++++++++++----
 test.sh    | 38 +++++++++++++++++++++++++++++++++++++-
 3 files changed, 78 insertions(+), 8 deletions(-)

diff --git a/dots b/dots
index 6ebeaff..f00c7c8 100755
--- a/dots
+++ b/dots
@@ -143,6 +143,7 @@ status_tools() {
 
 status_link() {
   command_exists dotstate || fail "dotstate not installed" || return
+  dotstate_uses_this_repo || fail "dotstate links another repository, not $DOTFILES" || return
   dotstate doctor --no-colors >/dev/null 2>&1 || fail "dotstate doctor reports issues; run: dots doctor"
 }
 
@@ -205,7 +206,6 @@ update_tmux() {
   "$HOME/.tmux/plugins/tpm/bin/update_plugins" all
 }
 
-update_herdr() {
 # uv and OpenCode come from their own installers, ccstatusline from npm
 update_tools() {
   if command_exists uv; then
@@ -219,13 +219,36 @@ update_tools() {
   fi
 }
 
+update_herdr() {
   require_cmd herdr brew || return 1
   herdr plugin update --yes </dev/null
 }
 
+# Update installed lockfile skills, skipping any whose Claude Code path is a
+# real directory: skills update would replace it like skills add does
 update_skills() {
-  require_cmd npx brew || return 1
-  npx -y skills update --global --yes </dev/null
+  require_cmd npx brew && require_cmd jq brew || return 1
+  local lock="$HOME/.agents/.skill-lock.json" name names=()
+  [ -f "$lock" ] || {
+    print_error "No skills lockfile at ~/.agents/.skill-lock.json; run: dots install link"
+    return 1
+  }
+  while IFS= read -r name; do
+    case "$name" in
+    "" | .* | */*) continue ;;
+    esac
+    [ -d "$HOME/.agents/skills/$name" ] || continue
+    if claude_skill_unmanaged "$name"; then
+      print_warning "Not updating agent skill $name: its Claude Code skill directory is not a link"
+    else
+      names+=("$name")
+    fi
+  done < <(jq -r '.skills | keys[]' "$lock")
+  if [ ${#names[@]} -eq 0 ]; then
+    print_info "No agent skills to update"
+    return
+  fi
+  npx -y skills update --global --yes "${names[@]}" </dev/null
 }
 
 cmd_install() {
diff --git a/install.sh b/install.sh
index 5b781ca..b380e90 100755
--- a/install.sh
+++ b/install.sh
@@ -669,6 +669,11 @@ install_dotstate() {
     print_success "dotstate installed to ~/.local/bin"
 }
 
+# Succeed when dotstate's config links this checkout
+dotstate_uses_this_repo() {
+    grep -Fqx "repo_path = \"$DOTFILES\"" "$HOME/.config/dotstate/config.toml" 2>/dev/null
+}
+
 # Link dotfiles into $HOME with dotstate. Conflicting files and stale links
 # are backed up to ~/.dotstate-backups/.
 link_dotfiles() {
@@ -692,7 +697,7 @@ active_profile = "$OS"
 backup_enabled = true
 EOF
         print_info "Created $config (profile: $OS)"
-    elif ! grep -Fqx "repo_path = \"$DOTFILES\"" "$config"; then
+    elif ! dotstate_uses_this_repo; then
         print_warning "$config uses another repository; not linking $DOTFILES"
         return
     fi
@@ -789,6 +794,14 @@ install_herdr_plugins() {
     fi
 }
 
+# The skills CLI replaces whatever is at the Claude Code link path, so never
+# let it delete a real directory there: succeed when ~/.claude/skills/$1 is
+# one
+claude_skill_unmanaged() {
+    local path="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/$1"
+    [ -e "$path" ] && [ ! -L "$path" ]
+}
+
 # Reinstall agent skills recorded in the skills CLI lockfile (linked from
 # common/.agents/.skill-lock.json) that are missing from ~/.agents/skills,
 # with one `skills add` per source repository, linked for Claude Code
@@ -830,8 +843,6 @@ install_agent_skills() {
         return 1
     fi
 
-    # The skills CLI replaces whatever is at the Claude Code link path, so
-    # never let it delete a real directory there
     local claude_skills="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills"
     local errors=0
     local source
@@ -851,7 +862,7 @@ install_agent_skills() {
                 *)
                     if [ -d "$HOME/.agents/skills/$name" ]; then
                         print_success "Agent skill already installed: $name"
-                    elif [ -e "$claude_skills/$name" ] && [ ! -L "$claude_skills/$name" ]; then
+                    elif claude_skill_unmanaged "$name"; then
                         print_warning "Not installing agent skill $name: $claude_skills/$name exists and is not a link; move it away to install"
                     else
                         missing+=("$name")
diff --git a/test.sh b/test.sh
index 1d0d105..7791faa 100755
--- a/test.sh
+++ b/test.sh
@@ -1351,11 +1351,11 @@ fi
 
 if ! run_dots install brew nope && [ ! -s "$DOTS_TEST_DIR/log" ] &&
    grep -q 'Unknown component: nope' "$DOTS_TEST_DIR/out" &&
+   ! run_dots install 'brew gh' && [ ! -s "$DOTS_TEST_DIR/log" ] &&
    ! run_dots install; then
     echo -e "${GREEN}✓ dots install rejects unknown or missing components without installing anything${NC}"
 else
     echo -e "${RED}✗ dots install must reject unknown components and an empty selection${NC}"
-   ! run_dots install 'brew gh' && [ ! -s "$DOTS_TEST_DIR/log" ] &&
     DOTS_ERRORS=$((DOTS_ERRORS + 1))
 fi
 
@@ -1368,6 +1368,42 @@ else
     DOTS_ERRORS=$((DOTS_ERRORS + 1))
 fi
 
+mkdir -p "$DOTS_TEST_DIR/home/.config/dotstate"
+echo 'repo_path = "/elsewhere"' > "$DOTS_TEST_DIR/home/.config/dotstate/config.toml"
+if ! run_dots status link && grep -q 'links another repository' "$DOTS_TEST_DIR/out" &&
+   [ ! -s "$DOTS_TEST_DIR/log" ]; then
+    echo -e "${GREEN}✓ dots status link fails when dotstate links another repository${NC}"
+else
+    echo -e "${RED}✗ dots status link must not trust dotstate doctor for another repository${NC}"
+    cat "$DOTS_TEST_DIR/out"
+    DOTS_ERRORS=$((DOTS_ERRORS + 1))
+fi
+
+if command_exists jq; then
+    cat > "$DOTS_TEST_DIR/bin/npx" <<'STUB'
+#!/usr/bin/env bash
+echo "npx $*" >> "$DOTS_STUB_LOG"
+STUB
+    chmod +x "$DOTS_TEST_DIR/bin/npx"
+    ln -sf "$(command -v jq)" "$DOTS_TEST_DIR/bin/jq"
+    mkdir -p "$DOTS_TEST_DIR/home/.agents/skills/linked-skill" \
+        "$DOTS_TEST_DIR/home/.agents/skills/own-skill" \
+        "$DOTS_TEST_DIR/home/.claude/skills/own-skill"
+    echo '{"version":3,"skills":{"linked-skill":{},"own-skill":{},"missing-skill":{}}}' \
+        > "$DOTS_TEST_DIR/home/.agents/.skill-lock.json"
+    if run_dots update skills &&
+       [ "$(cat "$DOTS_TEST_DIR/log")" = "npx -y skills update --global --yes linked-skill" ]; then
+        echo -e "${GREEN}✓ dots update skills skips skills whose ~/.claude/skills entry is a real directory${NC}"
+    else
+        echo -e "${RED}✗ dots update skills must update only installed skills not shadowed by a real ~/.claude/skills directory${NC}"
+        cat "$DOTS_TEST_DIR/out" "$DOTS_TEST_DIR/log"
+        DOTS_ERRORS=$((DOTS_ERRORS + 1))
+    fi
+else
+    echo -e "${YELLOW}⚠ jq not installed, skipping dots update skills check${NC}"
+    WARNINGS=$((WARNINGS + 1))
+fi
+
 rm -rf "$DOTS_TEST_DIR"
 unset -f run_dots
 if [ $DOTS_ERRORS -gt 0 ]; then