gsd-opencode 1.22.1 → 1.30.0

package/get-shit-done/workflows/ui-phase.md

@@ -0,0 +1,302 @@
+<objective>
+Generate a UI design contract (UI-SPEC.md) for frontend phases. Orchestrates gsd-ui-researcher and gsd-ui-checker with a revision loop. Inserts between discuss-phase and plan-phase in the lifecycle.
+
+UI-SPEC.md locks spacing, typography, color, copywriting, and design system decisions before the planner creates tasks. This prevents design debt caused by ad-hoc styling decisions during execution.
+</objective>
+
+<required_reading>
+@$HOME/.config/opencode/get-shit-done/references/ui-brand.md
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general'):
+- gsd-ui-researcher — Researches UI/UX approaches
+- gsd-ui-checker — Reviews UI implementation quality
+</available_agent_types>
+
+<process>
+
+## 1. Initialize
+
+```bash
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_UI=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-ui-researcher 2>/dev/null)
+AGENT_SKILLS_UI_CHECKER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-ui-checker 2>/dev/null)
+```
+
+Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`.
+
+**File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`.
+
+Resolve UI agent models:
+
+```bash
+UI_RESEARCHER_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-researcher --raw)
+UI_CHECKER_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-checker --raw)
+```
+
+Check config:
+
+```bash
+UI_ENABLED=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
+```
+
+**If `UI_ENABLED` is `false`:**
+```
+UI phase is disabled in config. Enable via /gsd-settings.
+```
+Exit workflow.
+
+**If `planning_exists` is false:** Error — run `/gsd-new-project` first.
+
+## 2. Parse and Validate Phase
+
+Extract phase number from $ARGUMENTS. If not provided, detect next unplanned phase.
+
+```bash
+PHASE_INFO=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}")
+```
+
+**If `found` is false:** Error with available phases.
+
+## 3. Check Prerequisites
+
+**If `has_context` is false:**
+```
+No CONTEXT.md found for Phase {N}.
+Recommended: run /gsd-discuss-phase {N} first to capture design preferences.
+Continuing without user decisions — UI researcher will ask all questions.
+```
+Continue (non-blocking).
+
+**If `has_research` is false:**
+```
+No RESEARCH.md found for Phase {N}.
+Note: stack decisions (component library, styling approach) will be asked during UI research.
+```
+Continue (non-blocking).
+
+## 4. Check Existing UI-SPEC
+
+```bash
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+```
+
+**If exists:** Use question:
+- header: "Existing UI-SPEC"
+- question: "UI-SPEC.md already exists for Phase {N}. What would you like to do?"
+- options:
+  - "Update — re-run researcher with existing as baseline"
+  - "View — display current UI-SPEC and exit"
+  - "Skip — keep current UI-SPEC, proceed to verification"
+
+If "View": display file contents, exit.
+If "Skip": proceed to step 7 (checker).
+If "Update": continue to step 5.
+
+## 5. Spawn gsd-ui-researcher
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► UI DESIGN CONTRACT — PHASE {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning UI researcher...
+```
+
+Build prompt:
+
+```markdown
+read $HOME/.config/opencode/agents/gsd-ui-researcher.md for instructions.
+
+<objective>
+Create UI design contract for Phase {phase_number}: {phase_name}
+Answer: "What visual and interaction contracts does this phase need?"
+</objective>
+
+<files_to_read>
+- {state_path} (Project State)
+- {roadmap_path} (Roadmap)
+- {requirements_path} (Requirements)
+- {context_path} (USER DECISIONS from /gsd-discuss-phase)
+- {research_path} (Technical Research — stack decisions)
+</files_to_read>
+
+${AGENT_SKILLS_UI}
+
+<output>
+write to: {phase_dir}/{padded_phase}-UI-SPEC.md
+Template: $HOME/.config/opencode/get-shit-done/templates/UI-SPEC.md
+</output>
+
+<config>
+commit_docs: {commit_docs}
+phase_dir: {phase_dir}
+padded_phase: {padded_phase}
+</config>
+```
+
+Omit null file paths from `<files_to_read>`.
+
+```
+task(
+  prompt=ui_research_prompt,
+  subagent_type="gsd-ui-researcher",
+  model="{UI_RESEARCHER_MODEL}",
+  description="UI Design Contract Phase {N}"
+)
+```
+
+## 6. Handle Researcher Return
+
+**If `## UI-SPEC COMPLETE`:**
+Display confirmation. Continue to step 7.
+
+**If `## UI-SPEC BLOCKED`:**
+Display blocker details and options. Exit workflow.
+
+## 7. Spawn gsd-ui-checker
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► VERIFYING UI-SPEC
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning UI checker...
+```
+
+Build prompt:
+
+```markdown
+read $HOME/.config/opencode/agents/gsd-ui-checker.md for instructions.
+
+<objective>
+Validate UI design contract for Phase {phase_number}: {phase_name}
+Check all 6 dimensions. Return APPROVED or BLOCKED.
+</objective>
+
+<files_to_read>
+- {phase_dir}/{padded_phase}-UI-SPEC.md (UI Design Contract — PRIMARY INPUT)
+- {context_path} (USER DECISIONS — check compliance)
+- {research_path} (Technical Research — check stack alignment)
+</files_to_read>
+
+${AGENT_SKILLS_UI_CHECKER}
+
+<config>
+ui_safety_gate: {ui_safety_gate config value}
+</config>
+```
+
+```
+task(
+  prompt=ui_checker_prompt,
+  subagent_type="gsd-ui-checker",
+  model="{UI_CHECKER_MODEL}",
+  description="Verify UI-SPEC Phase {N}"
+)
+```
+
+## 8. Handle Checker Return
+
+**If `## UI-SPEC VERIFIED`:**
+Display dimension results. Proceed to step 10.
+
+**If `## ISSUES FOUND`:**
+Display blocking issues. Proceed to step 9.
+
+## 9. Revision Loop (Max 2 Iterations)
+
+Track `revision_count` (starts at 0).
+
+**If `revision_count` < 2:**
+- Increment `revision_count`
+- Re-spawn gsd-ui-researcher with revision context:
+
+```markdown
+<revision>
+The UI checker found issues with the current UI-SPEC.md.
+
+### Issues to Fix
+{paste blocking issues from checker return}
+
+read the existing UI-SPEC.md, fix ONLY the listed issues, re-write the file.
+Do NOT re-ask the user questions that are already answered.
+</revision>
+```
+
+- After researcher returns → re-spawn checker (step 7)
+
+**If `revision_count` >= 2:**
+```
+Max revision iterations reached. Remaining issues:
+
+{list remaining issues}
+
+Options:
+1. Force approve — proceed with current UI-SPEC (FLAGs become accepted)
+2. edit manually — open UI-SPEC.md in editor, re-run /gsd-ui-phase
+3. Abandon — exit without approving
+```
+
+Use question for the choice.
+
+## 10. Present Final Status
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► UI-SPEC READY ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {N}: {Name}** — UI design contract approved
+
+Dimensions: 6/6 passed
+{If any FLAGs: "Recommendations: {N} (non-blocking)"}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan Phase {N}** — planner will use UI-SPEC.md as design context
+
+`/gsd-plan-phase {N}`
+
+*/new first → fresh context window*
+
+───────────────────────────────────────────────────────────────
+```
+
+## 11. Commit (if configured)
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): UI design contract" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
+```
+
+## 12. Update State
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state record-session \
+  --stopped-at "Phase ${PHASE} UI-SPEC approved" \
+  --resume-file "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
+```
+
+</process>
+
+<success_criteria>
+- [ ] Config checked (exit if ui_phase disabled)
+- [ ] Phase validated against roadmap
+- [ ] Prerequisites checked (CONTEXT.md, RESEARCH.md — non-blocking warnings)
+- [ ] Existing UI-SPEC handled (update/view/skip)
+- [ ] gsd-ui-researcher spawned with correct context and file paths
+- [ ] UI-SPEC.md created in correct location
+- [ ] gsd-ui-checker spawned with UI-SPEC.md
+- [ ] All 6 dimensions evaluated
+- [ ] Revision loop if BLOCKED (max 2 iterations)
+- [ ] Final status displayed with next steps
+- [ ] UI-SPEC.md committed (if commit_docs enabled)
+- [ ] State updated
+</success_criteria>

package/get-shit-done/workflows/ui-review.md

@@ -0,0 +1,165 @@
+<objective>
+Retroactive 6-pillar visual audit of implemented frontend code. Standalone command that works on any project — GSD-managed or not. Produces scored UI-REVIEW.md with actionable findings.
+</objective>
+
+<required_reading>
+@$HOME/.config/opencode/get-shit-done/references/ui-brand.md
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general'):
+- gsd-ui-auditor — Audits UI against design requirements
+</available_agent_types>
+
+<process>
+
+## 0. Initialize
+
+```bash
+INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_UI_REVIEWER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-ui-reviewer 2>/dev/null)
+```
+
+Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
+
+```bash
+UI_AUDITOR_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-auditor --raw)
+```
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► UI AUDIT — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 1. Detect Input State
+
+```bash
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+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 /gsd-execute-phase {N} first."
+
+**If `UI_REVIEW_FILE` non-empty:** Use question:
+- header: "Existing UI Review"
+- question: "UI-REVIEW.md already exists for Phase {N}."
+- options:
+  - "Re-audit — run fresh audit"
+  - "View — display current review and exit"
+
+If "View": display file, exit.
+If "Re-audit": continue.
+
+## 2. Gather Context Paths
+
+Build file list for auditor:
+- All SUMMARY.md files in phase dir
+- All PLAN.md files in phase dir
+- UI-SPEC.md (if exists — audit baseline)
+- CONTEXT.md (if exists — locked decisions)
+
+## 3. Spawn gsd-ui-auditor
+
+```
+◆ Spawning UI auditor...
+```
+
+Build prompt:
+
+```markdown
+read $HOME/.config/opencode/agents/gsd-ui-auditor.md for instructions.
+
+<objective>
+Conduct 6-pillar visual audit of Phase {phase_number}: {phase_name}
+{If UI-SPEC exists: "Audit against UI-SPEC.md design contract."}
+{If no UI-SPEC: "Audit against abstract 6-pillar standards."}
+</objective>
+
+<files_to_read>
+- {summary_paths} (Execution summaries)
+- {plan_paths} (Execution plans — what was intended)
+- {ui_spec_path} (UI Design Contract — audit baseline, if exists)
+- {context_path} (User decisions, if exists)
+</files_to_read>
+
+${AGENT_SKILLS_UI_REVIEWER}
+
+<config>
+phase_dir: {phase_dir}
+padded_phase: {padded_phase}
+</config>
+```
+
+Omit null file paths.
+
+```
+task(
+  prompt=ui_audit_prompt,
+  subagent_type="gsd-ui-auditor",
+  model="{UI_AUDITOR_MODEL}",
+  description="UI Audit Phase {N}"
+)
+```
+
+## 4. Handle Return
+
+**If `## UI REVIEW COMPLETE`:**
+
+Display score summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► UI AUDIT COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {N}: {Name}** — Overall: {score}/24
+
+| Pillar | Score |
+|--------|-------|
+| Copywriting | {N}/4 |
+| Visuals | {N}/4 |
+| Color | {N}/4 |
+| Typography | {N}/4 |
+| Spacing | {N}/4 |
+| Experience Design | {N}/4 |
+
+Top fixes:
+1. {fix}
+2. {fix}
+3. {fix}
+
+Full review: {path to UI-REVIEW.md}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next
+
+- `/gsd-verify-work {N}` — UAT testing
+- `/gsd-plan-phase {N+1}` — plan next phase
+
+*/new first → fresh context window*
+
+───────────────────────────────────────────────────────────────
+```
+
+## 5. Commit (if configured)
+
+```bash
+node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated
+- [ ] SUMMARY.md files found (execution completed)
+- [ ] Existing review handled (re-audit/view)
+- [ ] gsd-ui-auditor spawned with correct context
+- [ ] UI-REVIEW.md created in phase directory
+- [ ] Score summary displayed to user
+- [ ] Next steps presented
+</success_criteria>

package/get-shit-done/workflows/update.md

@@ -1,6 +1,6 @@
-<purpose>
+<objective>
 Check for GSD updates via npm, display changelog for versions between installed and latest, obtain user confirmation, and execute clean installation with cache clearing.
-</purpose>
+</objective>
 
 <required_reading>
 read all files referenced by the invoking prompt's execution_context before starting.
@@ -9,23 +9,74 @@ read all files referenced by the invoking prompt's execution_context before star
 <process>
 
 <step name="get_installed_version">
-Detect whether GSD is installed locally or globally by checking both locations and validating install integrity:
+Detect whether GSD 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:
+- Path contains `/.codex/` -> `codex`
+- Path contains `/.gemini/` -> `gemini`
+- Path contains `/.config/opencode/` or `/.opencode/` -> `opencode`
+- Otherwise -> `OpenCode`
+
+Use `PREFERRED_RUNTIME` as the first runtime checked so `/gsd-update` targets the runtime that invoked it.
 
 ```bash
-# Check local first (takes priority only if valid)
-# Detect runtime config directory (supports OpenCode, OpenCode, Gemini)
-LOCAL_VERSION_FILE="" LOCAL_MARKER_FILE="" LOCAL_DIR=""
-for dir in .OpenCode .config/opencode .opencode .gemini; do
-  if [ -f "./$dir/get-shit-done/VERSION" ]; then
+# 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=( "OpenCode:.OpenCode" "opencode:.config/opencode" "opencode:.opencode" "gemini:.gemini" "codex:.codex" )
+
+# PREFERRED_RUNTIME should be set from execution_context before running this block.
+# If not set, infer from runtime env vars; fallback to OpenCode.
+if [ -z "$PREFERRED_RUNTIME" ]; then
+  if [ -n "$CODEX_HOME" ]; then
+    PREFERRED_RUNTIME="codex"
+  elif [ -n "$GEMINI_CONFIG_DIR" ]; then
+    PREFERRED_RUNTIME="gemini"
+  elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
+    PREFERRED_RUNTIME="opencode"
+  elif [ -n "$CLAUDE_CONFIG_DIR" ]; then
+    PREFERRED_RUNTIME="OpenCode"
+  else
+    PREFERRED_RUNTIME="OpenCode"
+  fi
+fi
+
+# Reorder entries so preferred runtime is checked first.
+ORDERED_RUNTIME_DIRS=()
+for entry in "${RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  if [ "$runtime" = "$PREFERRED_RUNTIME" ]; then
+    ORDERED_RUNTIME_DIRS+=( "$entry" )
+  fi
+done
+for entry in "${RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  if [ "$runtime" != "$PREFERRED_RUNTIME" ]; then
+    ORDERED_RUNTIME_DIRS+=( "$entry" )
+  fi
+done
+
+# Check local first (takes priority only if valid and distinct from global)
+LOCAL_VERSION_FILE="" LOCAL_MARKER_FILE="" LOCAL_DIR="" LOCAL_RUNTIME=""
+for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  dir="${entry#*:}"
+  if [ -f "./$dir/get-shit-done/VERSION" ] || [ -f "./$dir/get-shit-done/workflows/update.md" ]; then
+    LOCAL_RUNTIME="$runtime"
     LOCAL_VERSION_FILE="./$dir/get-shit-done/VERSION"
     LOCAL_MARKER_FILE="./$dir/get-shit-done/workflows/update.md"
     LOCAL_DIR="$(cd "./$dir" 2>/dev/null && pwd)"
     break
   fi
 done
-GLOBAL_VERSION_FILE="" GLOBAL_MARKER_FILE="" GLOBAL_DIR=""
-for dir in .OpenCode .config/opencode .opencode .gemini; do
-  if [ -f "$HOME/$dir/get-shit-done/VERSION" ]; then
+
+GLOBAL_VERSION_FILE="" GLOBAL_MARKER_FILE="" GLOBAL_DIR="" GLOBAL_RUNTIME=""
+for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do
+  runtime="${entry%%:*}"
+  dir="${entry#*:}"
+  if [ -f "$HOME/$dir/get-shit-done/VERSION" ] || [ -f "$HOME/$dir/get-shit-done/workflows/update.md" ]; then
+    GLOBAL_RUNTIME="$runtime"
     GLOBAL_VERSION_FILE="$HOME/$dir/get-shit-done/VERSION"
     GLOBAL_MARKER_FILE="$HOME/$dir/get-shit-done/workflows/update.md"
     GLOBAL_DIR="$(cd "$HOME/$dir" 2>/dev/null && pwd)"
@@ -42,20 +93,40 @@ if [ -n "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_
 fi
 
 if [ "$IS_LOCAL" = true ]; then
-  cat "$LOCAL_VERSION_FILE"
-  echo "LOCAL"
+  INSTALLED_VERSION="$(cat "$LOCAL_VERSION_FILE")"
+  INSTALL_SCOPE="LOCAL"
+  TARGET_RUNTIME="$LOCAL_RUNTIME"
 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
-  cat "$GLOBAL_VERSION_FILE"
-  echo "GLOBAL"
+  INSTALLED_VERSION="$(cat "$GLOBAL_VERSION_FILE")"
+  INSTALL_SCOPE="GLOBAL"
+  TARGET_RUNTIME="$GLOBAL_RUNTIME"
+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"
+elif [ -n "$GLOBAL_RUNTIME" ] && [ -f "$GLOBAL_MARKER_FILE" ]; then
+  INSTALLED_VERSION="0.0.0"
+  INSTALL_SCOPE="GLOBAL"
+  TARGET_RUNTIME="$GLOBAL_RUNTIME"
 else
-  echo "UNKNOWN"
+  INSTALLED_VERSION="0.0.0"
+  INSTALL_SCOPE="UNKNOWN"
+  TARGET_RUNTIME="OpenCode"
 fi
+
+echo "$INSTALLED_VERSION"
+echo "$INSTALL_SCOPE"
+echo "$TARGET_RUNTIME"
 ```
 
 Parse output:
-- If last line is "LOCAL": local install is valid; installed version is first line; use `--local`
-- If last line is "GLOBAL": local missing/invalid, global install is valid; installed version is first line; use `--global`
-- If "UNKNOWN": proceed to install step (treat as version 0.0.0)
+- Line 1 = installed version (`0.0.0` means unknown version)
+- Line 2 = install scope (`LOCAL`, `GLOBAL`, or `UNKNOWN`)
+- Line 3 = target runtime (`OpenCode`, `opencode`, `gemini`, or `codex`)
+- If scope is `UNKNOWN`, proceed to install step using `--OpenCode --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.
 
 **If VERSION file missing:**
 ```
@@ -149,7 +220,9 @@ Exit.
 - `get-shit-done/` will be wiped and replaced
 - `agents/gsd-*` files will be replaced
 
-(Paths are relative to your install location: `$HOME/.config/opencode/` for global, `./.OpenCode/` for local)
+(Paths are relative to detected runtime install location:
+global: `$HOME/.config/opencode/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, or `~/.codex/`
+local: `./.OpenCode/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, or `./.codex/`)
 
 Your custom files in other locations are preserved:
 - Custom commands not in `commands/gsd/` ✓
@@ -172,14 +245,24 @@ Use question:
 <step name="run_update">
 Run the update using the install type detected in step 1:
 
+Build runtime flag from step 1:
+```bash
+RUNTIME_FLAG="--$TARGET_RUNTIME"
+```
+
 **If LOCAL install:**
 ```bash
-npx -y gsd-opencode@latest --local
+npx -y gsd-opencode@latest "$RUNTIME_FLAG" --local
+```
+
+**If GLOBAL install:**
+```bash
+npx -y gsd-opencode@latest "$RUNTIME_FLAG" --global
 ```
 
-**If GLOBAL install (or unknown):**
+**If UNKNOWN install:**
 ```bash
-npx -y gsd-opencode@latest --global
+npx -y gsd-opencode@latest --OpenCode --global
 ```
 
 Capture output. If install fails, show error and exit.
@@ -188,7 +271,7 @@ Clear the update cache so statusline indicator disappears:
 
 ```bash
 # Clear update cache across all runtime directories
-for dir in .OpenCode .config/opencode .opencode .gemini; do
+for dir in .OpenCode .config/opencode .opencode .gemini .codex; do
   rm -f "./$dir/cache/gsd-update-check.json"
   rm -f "$HOME/$dir/cache/gsd-update-check.json"
 done
@@ -205,7 +288,7 @@ Format completion message (changelog was already shown in confirmation step):
 ║  GSD Updated: v1.5.10 → v1.5.15                           ║
 ╚═══════════════════════════════════════════════════════════╝
 
-⚠️  Restart OpenCode to pick up the new commands.
+⚠️  Restart your runtime to pick up the new commands.
 
 [View full changelog](https://github.com/rokicool/gsd-opencode/blob/main/CHANGELOG.md)
 ```