@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/workflows/ui-review.md

@@ -16,15 +16,15 @@ 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_UI_REVIEWER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-ui-reviewer 2>/dev/null)
+AGENT_SKILLS_UI_REVIEWER=$(sdd-sdk query agent-skills sdd-ui-auditor)
 ```
 
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
 
 ```bash
-UI_AUDITOR_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-ui-auditor --raw)
+UI_AUDITOR_MODEL=$(sdd-sdk query resolve-model sdd-ui-auditor --raw)
 ```
 
 Display banner:
@@ -42,7 +42,7 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1)
 ```
 
-**If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /sdd-execute-phase {N} first."
+**If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /sdd:execute-phase {N} first."
 
 
 **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.
@@ -99,7 +99,7 @@ padded_phase: {padded_phase}
 Omit null file paths.
 
 ```
-Task(
+Agent(
   prompt=ui_audit_prompt,
   subagent_type="sdd-ui-auditor",
   model="{UI_AUDITOR_MODEL}",
@@ -107,6 +107,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.
+
 ## 4. Handle Return
 
 **If `## UI REVIEW COMPLETE`:**
@@ -142,11 +144,11 @@ Full review: {path to UI-REVIEW.md}
 
 `/clear` then one of:
 
-- `/sdd-verify-work {N}` — UAT testing
-- `/sdd-plan-phase {N+1}` — plan next phase
+- `/sdd:verify-work {N}` — UAT testing
+- `/sdd:plan-phase {N+1}` — plan next phase
 
-- `/sdd-verify-work {N}` — UAT testing
-- `/sdd-plan-phase {N+1}` — plan next phase
+- `/sdd:verify-work {N}` — UAT testing
+- `/sdd:plan-phase {N+1}` — plan next phase
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -174,7 +176,7 @@ tools is detected at runtime.
 ## 5. Commit (if configured)
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"
+sdd-sdk query commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"
 ```
 
 </process>

package/sdd/workflows/ultraplan-phase.md

@@ -0,0 +1,198 @@
+# Ultraplan Phase Workflow [BETA]
+
+Offload SDD's plan phase to Claude Code's ultraplan cloud infrastructure.
+
+⚠ **BETA feature.** Ultraplan is in research preview and may change. This workflow is
+intentionally isolated from /sdd:plan-phase so upstream changes to ultraplan cannot
+affect the core planning pipeline.
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► ULTRAPLAN PHASE  ⚠ BETA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Ultraplan is in research preview (Claude Code v2.1.91+).
+Use /sdd:plan-phase for stable local planning.
+```
+
+</step>
+
+---
+
+<step name="runtime_gate">
+
+Check that the session is running inside Claude Code:
+
+```bash
+if [ "$CLAUDECODE" = "1" ] || [ -n "$CLAUDE_CODE_ENTRYPOINT" ]; then
+  CC_VERSION="$(claude --version 2>/dev/null | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)"
+  if [ -n "$CC_VERSION" ] && [ "$(printf '%s\n' "2.1.91" "$CC_VERSION" | sort -V | head -n1)" = "2.1.91" ]; then
+    echo "claude-code:${CC_VERSION}"
+  else
+    echo ""
+  fi
+else
+  echo ""
+fi
+```
+
+If the output is empty or unset, display the following error and exit:
+
+```text
+╔══════════════════════════════════════════════════════════════╗
+║  RUNTIME ERROR                                               ║
+╚══════════════════════════════════════════════════════════════╝
+
+/sdd:ultraplan-phase requires Claude Code.
+ultraplan is not available in this runtime.
+
+Use /sdd:plan-phase for local planning instead.
+```
+
+</step>
+
+---
+
+<step name="initialize">
+
+Parse phase number from `$ARGUMENTS`. If no phase number is provided, detect the next
+unplanned phase from the roadmap (same logic as /sdd:plan-phase).
+
+Load SDD phase context:
+
+```bash
+INIT=$(sdd-sdk query init.plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_found`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`,
+`phase_dir`, `roadmap_path`, `requirements_path`, `research_path`, `planning_exists`.
+
+**If `planning_exists` is false:** Error and exit:
+
+```text
+No .planning directory found. Initialize the project first:
+
+/sdd:new-project
+```
+
+**If `phase_found` is false:** Error with the phase number provided and exit.
+
+Display detected phase:
+
+```text
+Phase {N}: {phase name}
+```
+
+</step>
+
+---
+
+<step name="build_prompt">
+
+Build the ultraplan prompt from SDD context.
+
+1. Read the phase scope from ROADMAP.md — extract the goal, deliverables, and scope for
+   the target phase.
+
+2. Read REQUIREMENTS.md if it exists (`requirements_path` is not null) — extract a
+   concise summary (key requirements relevant to this phase, not the full document).
+
+3. Read RESEARCH.md if it exists (`research_path` is not null) — extract a concise
+   summary of technical findings. Including this reduces redundant cloud research.
+
+Construct the prompt:
+
+```text
+Plan phase {phase_number}: {phase_name}
+
+## Phase Scope (from ROADMAP.md)
+
+{phase scope block extracted from ROADMAP.md}
+
+## Requirements Context
+
+{requirements summary, or "No REQUIREMENTS.md found — infer from phase scope."}
+
+## Existing Research
+
+{research summary, or "No RESEARCH.md found — research from scratch."}
+
+## Output Format
+
+Produce a SDD PLAN.md with the following YAML frontmatter:
+
+---
+phase: "{padded_phase}-{phase_slug}"
+plan: "{padded_phase}-01"
+type: "feature"
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths: []
+  artifacts: []
+---
+
+Then a ## Plan section with numbered tasks. Each task should have:
+- A clear imperative title
+- Files to create or modify
+- Specific implementation steps
+
+Keep the plan focused and executable.
+```
+
+</step>
+
+---
+
+<step name="return_path_card">
+
+Display the return-path instructions **before** triggering ultraplan so they are visible
+in the terminal scroll-back after ultraplan launches:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WHEN THE PLAN IS READY — WHAT TO DO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+When ◆ ultraplan ready appears in your terminal:
+
+  1. Open the session link in your browser
+  2. Review the plan — use inline comments and emoji reactions to give feedback
+  3. Ask Claude to revise until you're satisfied
+  4. Click "Approve plan and teleport back to terminal"
+  5. At the terminal dialog, choose Cancel  ← saves the plan to a file
+  6. Note the file path Claude prints
+  7. Run: /sdd:import --from <the file path>
+
+/sdd:import will run conflict detection, convert to SDD format,
+validate via plan-checker, update ROADMAP.md, and commit.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Launching ultraplan for Phase {N}: {phase_name}...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+---
+
+<step name="trigger">
+
+Trigger ultraplan with the constructed prompt:
+
+```text
+/ultraplan {constructed prompt from build_prompt step}
+```
+
+Your terminal will show a `◇ ultraplan` status indicator while the remote session works.
+Use `/tasks` to open the detail view with the session link, agent activity, and a stop action.
+
+</step>

package/sdd/workflows/undo.md

@@ -29,7 +29,7 @@ Parse $ARGUMENTS for the undo mode:
 If no valid argument is provided, display usage and exit:
 
 ```
-Usage: /sdd-undo --last N | --phase NN | --plan NN-MM
+Usage: /sdd:undo --last N | --phase NN | --plan NN-MM
 
 Modes:
   --last N      Show last N SDD commits for interactive selection
@@ -37,9 +37,9 @@ Modes:
   --plan NN-MM  Revert all commits for plan NN-MM
 
 Examples:
-  /sdd-undo --last 5
-  /sdd-undo --phase 03
-  /sdd-undo --plan 03-02
+  /sdd:undo --last 5
+  /sdd:undo --phase 03
+  /sdd:undo --plan 03-02
 ```
 </step>
 
@@ -204,7 +204,7 @@ Store the response as REVERT_REASON. Continue to execute_revert.
 
 Run `git status --porcelain`. If the output is non-empty, display the dirty files and abort:
 ```
-Working tree has uncommitted changes. Commit or stash them before running /sdd-undo.
+Working tree has uncommitted changes. Commit or stash them before running /sdd:undo.
 ```
 Exit immediately — do not proceed to any revert operations.
 
@@ -279,19 +279,19 @@ Show next steps:
 ```
 ───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Review state** — verify project is in expected state after revert
 
 /clear then:
 
-/sdd-progress
+/sdd:progress
 
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
-- `/sdd-execute-phase ${PHASE}` — re-execute if needed
-- `/sdd-undo --last 1` — undo the revert itself if something went wrong
+- `/sdd:execute-phase ${PHASE}` — re-execute if needed
+- `/sdd:undo --last 1` — undo the revert itself if something went wrong
 
 ───────────────────────────────────────────────────────────────
 ```

package/sdd/workflows/update.md

@@ -14,13 +14,14 @@ Detect whether SDD is installed locally or globally by checking both locations a
 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/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.
+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`.
 
@@ -36,7 +37,7 @@ expand_home() {
 # 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" "kilo:.config/kilo" "kilo:.kilo" "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
@@ -58,6 +59,8 @@ fi
 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
@@ -78,9 +81,27 @@ fi
 # 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"
-  for dir in .claude .config/opencode .opencode .gemini .config/kilo .kilo .codex; do
+  # 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)"
-    if [ -n "$resolved_local" ] && [ "$resolved_local" = "$PREFERRED_CONFIG_DIR" ]; then
+    normalized_local="$(normalize_path "$resolved_local")"
+    if [ -n "$normalized_local" ] && [ "$normalized_local" = "$normalized_preferred" ]; then
       INSTALL_SCOPE="LOCAL"
       break
     fi
@@ -95,6 +116,12 @@ if [ -n "$PREFERRED_CONFIG_DIR" ] && { [ -f "$PREFERRED_CONFIG_DIR/sdd/VERSION"
   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
 
@@ -102,6 +129,9 @@ fi
 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
@@ -204,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`, `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.
@@ -251,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.
@@ -289,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.
@@ -338,7 +412,7 @@ 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.
 ```
 
 
@@ -352,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:
 
@@ -362,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.
@@ -422,10 +587,15 @@ for dir in "${CACHE_DIRS[@]}"; do
   fi
 done
 
-for dir in .claude .config/opencode .opencode .gemini .config/kilo .kilo .codex; do
+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 preferred/env-derived paths and default paths must all be cleared to prevent stale update indicators.
@@ -455,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.