@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/workflows/update.md

@@ -11,28 +11,62 @@ Read all files referenced by the invoking prompt's execution_context before star
 <step name="get_installed_version">
 Detect whether SDD is installed locally or globally by checking both locations and validating install integrity.
 
-First, derive `PREFERRED_RUNTIME` from the invoking prompt's `execution_context` path:
+First, derive `PREFERRED_CONFIG_DIR` and `PREFERRED_RUNTIME` from the invoking prompt's `execution_context` path:
+- If the path contains `/sdd/workflows/update.md`, strip that suffix and store the remainder as `PREFERRED_CONFIG_DIR`
 - Path contains `/.codex/` -> `codex`
+- Path contains `/.gemini/antigravity/` -> `antigravity`
 - Path contains `/.gemini/` -> `gemini`
-- Path contains `/.config/opencode/` or `/.opencode/` -> `opencode`
+- Path contains `/.config/kilo/` or `/.kilo/`, or `PREFERRED_CONFIG_DIR` contains `kilo.json` / `kilo.jsonc` -> `kilo`
+- Path contains `/.config/opencode/` or `/.opencode/`, or `PREFERRED_CONFIG_DIR` contains `opencode.json` / `opencode.jsonc` -> `opencode`
 - Otherwise -> `claude`
 
+Use `PREFERRED_CONFIG_DIR` when available so custom `--config-dir` installs are checked before default locations.
 Use `PREFERRED_RUNTIME` as the first runtime checked so `/sdd:update` targets the runtime that invoked it.
 
+Kilo config precedence must match the installer: `KILO_CONFIG_DIR` -> `dirname(KILO_CONFIG)` -> `XDG_CONFIG_HOME/kilo` -> `~/.config/kilo`.
+
 ```bash
+expand_home() {
+  case "$1" in
+    "~/"*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
 # Runtime candidates: "<runtime>:<config-dir>" stored as an array.
 # Using an array instead of a space-separated string ensures correct
 # iteration in both bash and zsh (zsh does not word-split unquoted
 # variables by default). Fixes #1173.
-RUNTIME_DIRS=( "claude:.claude" "opencode:.config/opencode" "opencode:.opencode" "gemini:.gemini" "codex:.codex" )
+RUNTIME_DIRS=( "claude:.claude" "opencode:.config/opencode" "opencode:.opencode" "antigravity:.gemini/antigravity" "gemini:.gemini" "kilo:.config/kilo" "kilo:.kilo" "codex:.codex" )
+ENV_RUNTIME_DIRS=()
+
+# PREFERRED_CONFIG_DIR / PREFERRED_RUNTIME should be set from execution_context
+# before running this block.
+if [ -n "$PREFERRED_CONFIG_DIR" ]; then
+  PREFERRED_CONFIG_DIR="$(expand_home "$PREFERRED_CONFIG_DIR")"
+  if [ -z "$PREFERRED_RUNTIME" ]; then
+    if [ -f "$PREFERRED_CONFIG_DIR/kilo.json" ] || [ -f "$PREFERRED_CONFIG_DIR/kilo.jsonc" ]; then
+      PREFERRED_RUNTIME="kilo"
+    elif [ -f "$PREFERRED_CONFIG_DIR/opencode.json" ] || [ -f "$PREFERRED_CONFIG_DIR/opencode.jsonc" ]; then
+      PREFERRED_RUNTIME="opencode"
+    elif [ -f "$PREFERRED_CONFIG_DIR/config.toml" ]; then
+      PREFERRED_RUNTIME="codex"
+    fi
+  fi
+fi
 
-# PREFERRED_RUNTIME should be set from execution_context before running this block.
-# If not set, infer from runtime env vars; fallback to claude.
+# If runtime is still unknown, infer from runtime env vars; fallback to claude.
 if [ -z "$PREFERRED_RUNTIME" ]; then
   if [ -n "$CODEX_HOME" ]; then
     PREFERRED_RUNTIME="codex"
+  elif [ -n "$ANTIGRAVITY_CONFIG_DIR" ]; then
+    PREFERRED_RUNTIME="antigravity"
   elif [ -n "$GEMINI_CONFIG_DIR" ]; then
     PREFERRED_RUNTIME="gemini"
+  elif [ -n "$KILO_CONFIG_DIR" ]; then
+    PREFERRED_RUNTIME="kilo"
+  elif [ -n "$KILO_CONFIG" ]; then
+    PREFERRED_RUNTIME="kilo"
   elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
     PREFERRED_RUNTIME="opencode"
   elif [ -n "$CLAUDE_CONFIG_DIR" ]; then
@@ -42,6 +76,83 @@ if [ -z "$PREFERRED_RUNTIME" ]; then
   fi
 fi
 
+# If execution_context already points at an installed config dir, trust it first.
+# This covers custom --config-dir installs that do not live under the default
+# runtime directories.
+if [ -n "$PREFERRED_CONFIG_DIR" ] && { [ -f "$PREFERRED_CONFIG_DIR/sdd/VERSION" ] || [ -f "$PREFERRED_CONFIG_DIR/sdd/workflows/update.md" ]; }; then
+  INSTALL_SCOPE="GLOBAL"
+  # Normalize a path for comparison: on Windows with Git Bash, pwd returns
+  # POSIX-style /c/Users/... but PREFERRED_CONFIG_DIR may carry C:/Users/...
+  # Convert Windows drive-letter paths to POSIX form so the comparison works
+  # on both Windows (Git Bash) and POSIX systems.
+  normalize_path() {
+    local p="$1"
+    case "$p" in
+      [A-Za-z]:/*)
+        local drive rest
+        drive="${p%%:*}"
+        rest="${p#?:}"
+        p="/$(printf '%s' "$drive" | tr '[:upper:]' '[:lower:]')$rest"
+        ;;
+    esac
+    printf '%s' "$p"
+  }
+  normalized_preferred="$(normalize_path "$PREFERRED_CONFIG_DIR")"
+  for dir in .claude .config/opencode .opencode .gemini/antigravity .gemini .config/kilo .kilo .codex; do
+    resolved_local="$(cd "./$dir" 2>/dev/null && pwd)"
+    normalized_local="$(normalize_path "$resolved_local")"
+    if [ -n "$normalized_local" ] && [ "$normalized_local" = "$normalized_preferred" ]; then
+      INSTALL_SCOPE="LOCAL"
+      break
+    fi
+  done
+
+  if [ -f "$PREFERRED_CONFIG_DIR/sdd/VERSION" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$PREFERRED_CONFIG_DIR/sdd/VERSION"; then
+    INSTALLED_VERSION="$(cat "$PREFERRED_CONFIG_DIR/sdd/VERSION")"
+  else
+    INSTALLED_VERSION="0.0.0"
+  fi
+
+  echo "$INSTALLED_VERSION"
+  echo "$INSTALL_SCOPE"
+  echo "${PREFERRED_RUNTIME:-claude}"
+  # 4-line output contract (#2993 CR): early-return path must also emit
+  # SDD_DIR or downstream check_latest_version misreads the install as
+  # UNKNOWN. PREFERRED_CONFIG_DIR is the resolved config dir we just
+  # validated above (line 95-96); it is the right SDD_DIR value for
+  # this fast path.
+  echo "$PREFERRED_CONFIG_DIR"
+  exit 0
+fi
+
+# Absolute global candidates from env overrides (covers custom config dirs).
+if [ -n "$CLAUDE_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "claude:$(expand_home "$CLAUDE_CONFIG_DIR")" )
+fi
+if [ -n "$ANTIGRAVITY_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "antigravity:$(expand_home "$ANTIGRAVITY_CONFIG_DIR")" )
+fi
+if [ -n "$GEMINI_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "gemini:$(expand_home "$GEMINI_CONFIG_DIR")" )
+fi
+if [ -n "$KILO_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "kilo:$(expand_home "$KILO_CONFIG_DIR")" )
+elif [ -n "$KILO_CONFIG" ]; then
+  ENV_RUNTIME_DIRS+=( "kilo:$(dirname "$(expand_home "$KILO_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  ENV_RUNTIME_DIRS+=( "kilo:$(expand_home "$XDG_CONFIG_HOME")/kilo" )
+fi
+if [ -n "$OPENCODE_CONFIG_DIR" ]; then
+  ENV_RUNTIME_DIRS+=( "opencode:$(expand_home "$OPENCODE_CONFIG_DIR")" )
+elif [ -n "$OPENCODE_CONFIG" ]; then
+  ENV_RUNTIME_DIRS+=( "opencode:$(dirname "$(expand_home "$OPENCODE_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  ENV_RUNTIME_DIRS+=( "opencode:$(expand_home "$XDG_CONFIG_HOME")/opencode" )
+fi
+if [ -n "$CODEX_HOME" ]; then
+  ENV_RUNTIME_DIRS+=( "codex:$(expand_home "$CODEX_HOME")" )
+fi
+
 # Reorder entries so preferred runtime is checked first.
 ORDERED_RUNTIME_DIRS=()
 for entry in "${RUNTIME_DIRS[@]}"; do
@@ -50,6 +161,19 @@ for entry in "${RUNTIME_DIRS[@]}"; do
     ORDERED_RUNTIME_DIRS+=( "$entry" )
   fi
 done
+ORDERED_ENV_RUNTIME_DIRS=()
+for entry in "${ENV_RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  if [ "$runtime" = "$PREFERRED_RUNTIME" ]; then
+    ORDERED_ENV_RUNTIME_DIRS+=( "$entry" )
+  fi
+done
+for entry in "${ENV_RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  if [ "$runtime" != "$PREFERRED_RUNTIME" ]; then
+    ORDERED_ENV_RUNTIME_DIRS+=( "$entry" )
+  fi
+done
 for entry in "${RUNTIME_DIRS[@]}"; do
   runtime="${entry%%:*}"
   if [ "$runtime" != "$PREFERRED_RUNTIME" ]; then
@@ -72,18 +196,32 @@ for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
 done
 
 GLOBAL_VERSION_FILE="" GLOBAL_MARKER_FILE="" GLOBAL_DIR="" GLOBAL_RUNTIME=""
-for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
+for entry in "${ORDERED_ENV_RUNTIME_DIRS[@]}"; do
   runtime="${entry%%:*}"
   dir="${entry#*:}"
-  if [ -f "$HOME/$dir/sdd/VERSION" ] || [ -f "$HOME/$dir/sdd/workflows/update.md" ]; then
+  if [ -f "$dir/sdd/VERSION" ] || [ -f "$dir/sdd/workflows/update.md" ]; then
     GLOBAL_RUNTIME="$runtime"
-    GLOBAL_VERSION_FILE="$HOME/$dir/sdd/VERSION"
-    GLOBAL_MARKER_FILE="$HOME/$dir/sdd/workflows/update.md"
-    GLOBAL_DIR="$(cd "$HOME/$dir" 2>/dev/null && pwd)"
+    GLOBAL_VERSION_FILE="$dir/sdd/VERSION"
+    GLOBAL_MARKER_FILE="$dir/sdd/workflows/update.md"
+    GLOBAL_DIR="$(cd "$dir" 2>/dev/null && pwd)"
     break
   fi
 done
 
+if [ -z "$GLOBAL_RUNTIME" ]; then
+  for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
+    runtime="${entry%%:*}"
+    dir="${entry#*:}"
+    if [ -f "$HOME/$dir/sdd/VERSION" ] || [ -f "$HOME/$dir/sdd/workflows/update.md" ]; then
+      GLOBAL_RUNTIME="$runtime"
+      GLOBAL_VERSION_FILE="$HOME/$dir/sdd/VERSION"
+      GLOBAL_MARKER_FILE="$HOME/$dir/sdd/workflows/update.md"
+      GLOBAL_DIR="$(cd "$HOME/$dir" 2>/dev/null && pwd)"
+      break
+    fi
+  done
+fi
+
 # Only treat as LOCAL if the resolved paths differ (prevents misdetection when CWD=$HOME)
 IS_LOCAL=false
 if [ -n "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$LOCAL_VERSION_FILE"; then
@@ -96,34 +234,41 @@ if [ "$IS_LOCAL" = true ]; then
   INSTALLED_VERSION="$(cat "$LOCAL_VERSION_FILE")"
   INSTALL_SCOPE="LOCAL"
   TARGET_RUNTIME="$LOCAL_RUNTIME"
+  RESOLVED_SDD_DIR="$LOCAL_DIR"
 elif [ -n "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$GLOBAL_VERSION_FILE"; then
   INSTALLED_VERSION="$(cat "$GLOBAL_VERSION_FILE")"
   INSTALL_SCOPE="GLOBAL"
   TARGET_RUNTIME="$GLOBAL_RUNTIME"
+  RESOLVED_SDD_DIR="$GLOBAL_DIR"
 elif [ -n "$LOCAL_RUNTIME" ] && [ -f "$LOCAL_MARKER_FILE" ]; then
   # Runtime detected but VERSION missing/corrupt: treat as unknown version, keep runtime target
   INSTALLED_VERSION="0.0.0"
   INSTALL_SCOPE="LOCAL"
   TARGET_RUNTIME="$LOCAL_RUNTIME"
+  RESOLVED_SDD_DIR="$LOCAL_DIR"
 elif [ -n "$GLOBAL_RUNTIME" ] && [ -f "$GLOBAL_MARKER_FILE" ]; then
   INSTALLED_VERSION="0.0.0"
   INSTALL_SCOPE="GLOBAL"
   TARGET_RUNTIME="$GLOBAL_RUNTIME"
+  RESOLVED_SDD_DIR="$GLOBAL_DIR"
 else
   INSTALLED_VERSION="0.0.0"
   INSTALL_SCOPE="UNKNOWN"
   TARGET_RUNTIME="claude"
+  RESOLVED_SDD_DIR=""
 fi
 
 echo "$INSTALLED_VERSION"
 echo "$INSTALL_SCOPE"
 echo "$TARGET_RUNTIME"
+echo "$RESOLVED_SDD_DIR"
 ```
 
 Parse output:
 - Line 1 = installed version (`0.0.0` means unknown version)
 - Line 2 = install scope (`LOCAL`, `GLOBAL`, or `UNKNOWN`)
-- Line 3 = target runtime (`claude`, `opencode`, `gemini`, or `codex`)
+- Line 3 = target runtime (`claude`, `opencode`, `gemini`, `kilo`, or `codex`)
+- Line 4 = resolved SDD config dir (e.g. `/Users/me/.claude`, `/Users/me/.gemini`); empty if scope is `UNKNOWN`. Capture this as `SDD_DIR` and pass it to subsequent steps so they don't have to re-derive the runtime path.
 - If scope is `UNKNOWN`, proceed to install step using `--claude --global` fallback.
 
 If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install.
@@ -143,17 +288,45 @@ Proceed to install step (treat as version 0.0.0 for comparison).
 </step>
 
 <step name="check_latest_version">
-Check npm for latest version:
+Check npm for latest version via the deterministic script. **Do NOT run `npm view` or `npm search` directly** — the package name must come from the script, not from a free choice at execution time. (#2992: LLM-driven prescriptions of npm package names produced wrong-package queries; moving the package name into a script constant closes that gap.)
+
+The `SDD_DIR` value emitted by `get_installed_version` (line 4) resolves to the runtime-specific config dir (`~/.claude/`, `~/.gemini/`, `~/.codex/`, etc.), so the script invocation works for every runtime — not just Claude. If `SDD_DIR` is empty (scope `UNKNOWN`), skip this step and go directly to install.
+
+`LATEST_RESULT` is a JSON document with the documented shape `{ ok: bool, version: string, reason: string, detail?: string }`. Parse via `jq` ONLY when the script actually ran. When `SDD_DIR` is empty (scope `UNKNOWN`), skip the check entirely and seed the parsed fields with their no-op values so downstream logic does not mistake an unset `LATEST_RESULT` for a failed network check (#2993 CR feedback):
 
 ```bash
-npm view @bhargavvc/sdd-cc version 2>/dev/null
+if [ -z "$SDD_DIR" ]; then
+  # No install detected — fall through to install step; version-check is skipped.
+  LATEST_RESULT=""
+  LATEST_STATUS=0
+  LATEST_OK=false
+  LATEST_VERSION=""
+  LATEST_REASON="no_install_detected"
+else
+  LATEST_RESULT="$(node "$SDD_DIR/sdd/bin/check-latest-version.cjs" --json 2>/dev/null)"
+  LATEST_STATUS=$?
+  # #2993 CR: when node is missing or the script doesn't exist, LATEST_RESULT
+  # is empty and piping it to `jq` produces a parse error on stderr while
+  # leaving LATEST_OK / LATEST_REASON as empty strings. Fail the check with a
+  # meaningful reason instead of a blank diagnostic.
+  if [ -n "$LATEST_RESULT" ]; then
+    LATEST_OK="$(printf '%s' "$LATEST_RESULT" | jq -r '.ok // false')"
+    LATEST_VERSION="$(printf '%s' "$LATEST_RESULT" | jq -r '.version // empty')"
+    LATEST_REASON="$(printf '%s' "$LATEST_RESULT" | jq -r '.reason // empty')"
+  else
+    LATEST_OK=false
+    LATEST_VERSION=""
+    LATEST_REASON="script_not_found_or_node_unavailable"
+  fi
+fi
 ```
 
-**If npm check fails:**
-```
-Couldn't check for updates (offline or npm unavailable).
+**If `LATEST_OK` is not `true`** (or `LATEST_STATUS` is non-zero):
 
-To update manually: `npx @bhargavvc/sdd-cc --global`
+```text
+Couldn't check for updates (reason: {LATEST_REASON}, exit: {LATEST_STATUS}).
+
+To update manually: `npx -y --package=@bhargavvc/sdd-cc@latest -- @bhargavvc/sdd-cc --global`
 ```
 
 Exit.
@@ -181,7 +354,16 @@ Exit.
 **Installed:** X.Y.Z
 **Latest:** A.B.C
 
-You're ahead of the latest release (development version?).
+You're ahead of the latest release — this looks like a dev install.
+
+If you see a "⚠ dev install — re-run installer to sync hooks" warning in
+your statusline, your hook files are older than your VERSION file. Fix it
+by re-running the local installer from your dev branch:
+
+    node bin/install.js --global --claude
+
+Running /sdd:update would install the npm release (A.B.C) and downgrade
+your dev version — do NOT use it to resolve this warning.
 ```
 
 Exit.
@@ -221,8 +403,8 @@ Exit.
 - `agents/sdd-*` files will be replaced
 
 (Paths are relative to detected runtime install location:
-global: `~/.claude/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, or `~/.codex/`
-local: `./.claude/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, or `./.codex/`)
+global: `~/.claude/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, `~/.config/kilo/`, or `~/.codex/`
+local: `./.claude/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, `./.kilo/`, or `./.codex/`)
 
 Your custom files in other locations are preserved:
 - Custom commands not in `commands/sdd/` ✓
@@ -230,9 +412,11 @@ Your custom files in other locations are preserved:
 - Custom hooks ✓
 - Your CLAUDE.md files ✓
 
-If you've modified any SDD files directly, they'll be automatically backed up to `sdd-local-patches/` and can be reapplied with `/sdd:reapply-patches` after the update.
+If you've modified any SDD files directly, they'll be automatically backed up to `sdd-local-patches/` and can be reapplied with `/sdd:update --reapply` after the update.
 ```
 
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 Use AskUserQuestion:
 - Question: "Proceed with update?"
 - Options:
@@ -242,6 +426,97 @@ Use AskUserQuestion:
 **If user cancels:** Exit.
 </step>
 
+<step name="backup_custom_files">
+Before running the installer, detect and back up any user-added files inside
+SDD-managed directories. These are files that exist on disk but are NOT listed
+in `sdd-file-manifest.json` — i.e., files the user added themselves that the
+installer does not know about and will delete during the wipe.
+
+**Do not use bash path-stripping (`${filepath#$RUNTIME_DIR/}`) or `node -e require()`
+inline** — those patterns fail when `$RUNTIME_DIR` is unset and the stripped
+relative path may not match manifest key format, which causes CUSTOM_COUNT=0
+even when custom files exist (bug #1997). Use `sdd-sdk query detect-custom-files`
+when `sdd-sdk` is on `PATH`, or the bundled `sdd-tools.cjs detect-custom-files`
+otherwise — both resolve paths reliably with Node.js `path.relative()`.
+
+First, resolve the config directory (`RUNTIME_DIR`) from the install scope
+detected in `get_installed_version`:
+
+```bash
+# RUNTIME_DIR is the resolved config directory (e.g. ~/.config/opencode, ~/.gemini)
+# It should already be set from get_installed_version as GLOBAL_DIR or LOCAL_DIR.
+# Use the appropriate variable based on INSTALL_SCOPE.
+if [ "$INSTALL_SCOPE" = "LOCAL" ]; then
+  RUNTIME_DIR="$LOCAL_DIR"
+elif [ "$INSTALL_SCOPE" = "GLOBAL" ]; then
+  RUNTIME_DIR="$GLOBAL_DIR"
+else
+  RUNTIME_DIR=""
+fi
+```
+
+If `RUNTIME_DIR` is empty or does not exist, skip this step (no config dir to
+inspect).
+
+Otherwise run `detect-custom-files` (prefer SDK when available):
+
+```bash
+SDD_TOOLS="$RUNTIME_DIR/sdd/bin/sdd-tools.cjs"
+CUSTOM_JSON=''
+if [ -n "$RUNTIME_DIR" ] && command -v sdd-sdk >/dev/null 2>&1; then
+  CUSTOM_JSON=$(sdd-sdk query detect-custom-files --config-dir "$RUNTIME_DIR" 2>/dev/null)
+elif [ -f "$SDD_TOOLS" ] && [ -n "$RUNTIME_DIR" ]; then
+  CUSTOM_JSON=$(node "$SDD_TOOLS" detect-custom-files --config-dir "$RUNTIME_DIR" 2>/dev/null)
+fi
+if [ -z "$CUSTOM_JSON" ]; then
+  CUSTOM_JSON='{"custom_files":[],"custom_count":0}'
+fi
+CUSTOM_COUNT=$(echo "$CUSTOM_JSON" | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).custom_count);}catch{console.log(0);}})" 2>/dev/null || echo "0")
+```
+
+**If `CUSTOM_COUNT` > 0:**
+
+Back up each custom file to `$RUNTIME_DIR/sdd-user-files-backup/` before the
+installer wipes the directories:
+
+```bash
+BACKUP_DIR="$RUNTIME_DIR/sdd-user-files-backup"
+mkdir -p "$BACKUP_DIR"
+
+# Parse custom_files array from CUSTOM_JSON and copy each file
+node - "$RUNTIME_DIR" "$BACKUP_DIR" "$CUSTOM_JSON" <<'JSEOF'
+const [,, runtimeDir, backupDir, customJson] = process.argv;
+const { custom_files } = JSON.parse(customJson);
+const fs = require('fs');
+const path = require('path');
+for (const relPath of custom_files) {
+  const src = path.join(runtimeDir, relPath);
+  const dst = path.join(backupDir, relPath);
+  if (!fs.existsSync(src)) continue;
+
+  try {
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(src, dst);
+    console.log('  Backed up: ' + relPath);
+  } catch (err) {
+    const code = err && err.code ? String(err.code) : 'ERROR';
+    console.log('  Skipped (non-fatal): ' + relPath + ' [' + code + ']');
+  }
+}
+JSEOF
+```
+
+Then inform the user:
+
+```
+⚠️  Found N custom file(s) inside SDD-managed directories.
+    These have been backed up to sdd-user-files-backup/ before the update.
+    Restore them after the update if needed.
+```
+
+**If `CUSTOM_COUNT` == 0:** No user-added files detected. Continue to install.
+</step>
+
 <step name="run_update">
 Run the update using the install type detected in step 1:
 
@@ -252,17 +527,17 @@ RUNTIME_FLAG="--$TARGET_RUNTIME"
 
 **If LOCAL install:**
 ```bash
-npx -y @bhargavvc/sdd-cc@latest "$RUNTIME_FLAG" --local
+npx -y --package=@bhargavvc/sdd-cc@latest -- @bhargavvc/sdd-cc "$RUNTIME_FLAG" --local
 ```
 
 **If GLOBAL install:**
 ```bash
-npx -y @bhargavvc/sdd-cc@latest "$RUNTIME_FLAG" --global
+npx -y --package=@bhargavvc/sdd-cc@latest -- @bhargavvc/sdd-cc "$RUNTIME_FLAG" --global
 ```
 
 **If UNKNOWN install:**
 ```bash
-npx -y @bhargavvc/sdd-cc@latest --claude --global
+npx -y --package=@bhargavvc/sdd-cc@latest -- @bhargavvc/sdd-cc --claude --global
 ```
 
 Capture output. If install fails, show error and exit.
@@ -270,14 +545,60 @@ Capture output. If install fails, show error and exit.
 Clear the update cache so statusline indicator disappears:
 
 ```bash
-# Clear update cache across all runtime directories
-for dir in .claude .config/opencode .opencode .gemini .codex; do
+expand_home() {
+  case "$1" in
+    "~/"*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
+# Clear update cache across preferred, env-derived, and default runtime directories
+CACHE_DIRS=()
+if [ -n "$PREFERRED_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$PREFERRED_CONFIG_DIR")" )
+fi
+if [ -n "$CLAUDE_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$CLAUDE_CONFIG_DIR")" )
+fi
+if [ -n "$GEMINI_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$GEMINI_CONFIG_DIR")" )
+fi
+if [ -n "$KILO_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$KILO_CONFIG_DIR")" )
+elif [ -n "$KILO_CONFIG" ]; then
+  CACHE_DIRS+=( "$(dirname "$(expand_home "$KILO_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  CACHE_DIRS+=( "$(expand_home "$XDG_CONFIG_HOME")/kilo" )
+fi
+if [ -n "$OPENCODE_CONFIG_DIR" ]; then
+  CACHE_DIRS+=( "$(expand_home "$OPENCODE_CONFIG_DIR")" )
+elif [ -n "$OPENCODE_CONFIG" ]; then
+  CACHE_DIRS+=( "$(dirname "$(expand_home "$OPENCODE_CONFIG")")" )
+elif [ -n "$XDG_CONFIG_HOME" ]; then
+  CACHE_DIRS+=( "$(expand_home "$XDG_CONFIG_HOME")/opencode" )
+fi
+if [ -n "$CODEX_HOME" ]; then
+  CACHE_DIRS+=( "$(expand_home "$CODEX_HOME")" )
+fi
+
+for dir in "${CACHE_DIRS[@]}"; do
+  if [ -n "$dir" ]; then
+    rm -f "$dir/cache/sdd-update-check.json"
+  fi
+done
+
+for dir in .claude .config/opencode .opencode .gemini/antigravity .gemini .config/kilo .kilo .codex; do
   rm -f "./$dir/cache/sdd-update-check.json"
   rm -f "$HOME/$dir/cache/sdd-update-check.json"
 done
+
+# Clear the shared tool-agnostic cache written by sdd-check-update.js hook (#2784).
+# The hook uses ~/.cache/sdd/sdd-update-check.json regardless of runtime; clear it
+# so the statusline stops showing the stale "⬆ /sdd:update" indicator after update.
+rm -f "$HOME/.cache/sdd/sdd-update-check.json"
 ```
 
-The SessionStart hook (`sdd-check-update.js`) writes to the detected runtime's cache directory, so all paths must be cleared to prevent stale update indicators.
+The SessionStart hook (`sdd-check-update.js`) writes to the detected runtime's cache directory, so preferred/env-derived paths and default paths must all be cleared to prevent stale update indicators.
 </step>
 
 <step name="display_result">
@@ -290,7 +611,7 @@ Format completion message (changelog was already shown in confirmation step):
 
 ⚠️  Restart your runtime to pick up the new commands.
 
-[View full changelog](https://github.com/gsd-build/sdd/blob/main/CHANGELOG.md)
+[View full changelog](https://github.com/bhargavvc/sdd-cc/blob/main/CHANGELOG.md)
 ```
 </step>
 
@@ -304,7 +625,7 @@ Check for sdd-local-patches/backup-meta.json in the config directory.
 
 ```
 Local patches were backed up before the update.
-Run /sdd:reapply-patches to merge your modifications into the new version.
+Run `/sdd:update --reapply` to merge your modifications into the new version.
 ```
 
 **If no patches:** Continue normally.

package/sdd/workflows/validate-phase.md

@@ -16,16 +16,16 @@ Valid SDD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "${PHASE_ARG}")
+INIT=$(sdd-sdk query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_AUDITOR=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-nyquist-auditor 2>/dev/null)
+AGENT_SKILLS_AUDITOR=$(sdd-sdk query agent-skills sdd-nyquist-auditor)
 ```
 
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 
 ```bash
-AUDITOR_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-nyquist-auditor --raw)
-NYQUIST_CFG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.nyquist_validation --raw)
+AUDITOR_MODEL=$(sdd-sdk query resolve-model sdd-nyquist-auditor --raw)
+NYQUIST_CFG=$(sdd-sdk query config-get workflow.nyquist_validation --raw)
 ```
 
 If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /sdd:settings."
@@ -83,6 +83,8 @@ No gaps → skip to Step 6, set `nyquist_compliant: true`.
 
 ## 4. Present Gap Plan
 
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 Call AskUserQuestion with gap table and options:
 1. "Fix all gaps" → Step 5
 2. "Skip — mark manual-only" → add to Manual-Only, Step 6
@@ -91,7 +93,7 @@ Call AskUserQuestion with gap table and options:
 ## 5. Spawn sdd-nyquist-auditor
 
 ```
-Task(
+Agent(
   prompt="Read ~/.claude/agents/sdd-nyquist-auditor.md for instructions.\n\n" +
     "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
     "<gaps>{gap list}</gaps>" +
@@ -104,6 +106,8 @@ Task(
 )
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
 Handle return:
 - `## GAPS FILLED` → record tests + map updates, Step 6
 - `## PARTIAL` → record resolved, move escalated to manual-only, Step 6
@@ -135,7 +139,7 @@ Handle return:
 git add {test_files}
 git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
 
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(phase-${PHASE}): add/update validation strategy"
+sdd-sdk query commit "docs(phase-${PHASE}): add/update validation strategy"
 ```
 
 ## 8. Results + Routing