dotcontext

#!/bin/bash
set -e

VERSION="0.19.0"
REPO="goca-se/dotcontext"
BRANCH="main"
BASE_URL="https://raw.githubusercontent.com/${REPO}/${BRANCH}"
# ── Colors ────────────────────────────────────────────────────────────────────

if [[ -t 1 ]]; then
  RED='\033[0;31m'
  GREEN='\033[0;32m'
  YELLOW='\033[0;33m'
  BLUE='\033[0;34m'
  PURPLE='\033[0;35m'
  CYAN='\033[0;36m'
  GRAY='\033[0;90m'
  BOLD='\033[1m'
  DIM='\033[2m'
  NC='\033[0m'
else
  RED='' GREEN='' YELLOW='' BLUE='' PURPLE='' CYAN='' GRAY='' BOLD='' DIM='' NC=''
fi

# Helper print functions
print_green() { printf "${GREEN}%s${NC}\n" "$1"; }
print_red() { printf "${RED}%s${NC}\n" "$1"; }
print_yellow() { printf "${YELLOW}%s${NC}\n" "$1"; }
print_blue() { printf "${BLUE}%s${NC}\n" "$1"; }
print_gray() { printf "${GRAY}%s${NC}\n" "$1"; }
print_cyan() { printf "${CYAN}%s${NC}\n" "$1"; }
# ── Icons ─────────────────────────────────────────────────────────────────────

ICON_SUCCESS="✓"
ICON_ERROR="✗"
ICON_WARNING="⚠"
ICON_ARROW="➤"
ICON_INFO="ℹ"
ICON_SECTION="◆"
ICON_DOWNLOAD="↓"
ICON_SKIP="○"
ICON_UPDATE="↻"
ICON_CHECK="◎"
ICON_ADMIN="⚙"
ICON_NAV="↳"
ICON_ADD="+"
ICON_MODIFY="~"
ICON_UNCHANGED="="
ICON_MANAGED="•"
# ── UI Utilities ──────────────────────────────────────────────────────────────

get_term_width() {
  local width
  width=$(tput cols 2>/dev/null || echo "")
  if [ -z "$width" ] || [ "$width" -lt 40 ] 2>/dev/null; then
    width=80
  fi
  echo "$width"
}

# Print a section header with divider line
# Usage: print_block_header "Title"
print_block_header() {
  local title="$1"
  local width
  width=$(get_term_width)
  local title_len=${#title}
  local pad=$((width - title_len - 6))
  [ "$pad" -lt 4 ] && pad=4
  local line=""
  local i
  for ((i = 0; i < pad; i++)); do
    line="${line}─"
  done
  printf "\n  ${BOLD}── %s ${NC}${GRAY}%s${NC}\n" "$title" "$line"
}

# Print a block footer divider
print_block_footer() {
  local width
  width=$(get_term_width)
  local pad=$((width - 4))
  [ "$pad" -lt 10 ] && pad=10
  local line=""
  local i
  for ((i = 0; i < pad; i++)); do
    line="${line}─"
  done
  printf "  ${GRAY}%s${NC}\n" "$line"
}

# Print aligned label-value pair
# Usage: print_aligned "label" "value" [indent]
print_aligned() {
  local label="$1"
  local value="$2"
  local indent="${3:-4}"
  local pad_fmt="%-${indent}s"
  printf "  ${pad_fmt}${GRAY}%s${NC}\n" "$label" "$value"
}
# ── Spinner ───────────────────────────────────────────────────────────────────

SPINNER_PID=""
start_spinner() {
  local msg="$1"
  local frames=(⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏)
  local i=0
  while true; do
    printf "\r  ${BLUE}${frames[$i]}${NC} ${msg}"
    i=$(( (i + 1) % 10 ))
    sleep 0.1
  done &
  SPINNER_PID=$!
}

stop_spinner() {
  local msg="$1"
  if [ -n "$SPINNER_PID" ]; then
    kill "$SPINNER_PID" 2>/dev/null
    wait "$SPINNER_PID" 2>/dev/null || true
    SPINNER_PID=""
  fi
  printf "\r\033[K"
  if [ -n "$msg" ]; then
    echo "$msg"
  fi
}
# ── Utilities ─────────────────────────────────────────────────────────────────

prompt() {
  local message="$1"
  local default="$2"
  local result
  if [ -n "$default" ]; then
    printf "%s [%s]: " "$message" "$default" >&2
    read -r result
    echo "${result:-$default}"
  else
    printf "%s: " "$message" >&2
    read -r result
    echo "$result"
  fi
}

confirm() {
  local message="$1"
  local answer
  printf "%s [y/N]: " "$message"
  read -r answer
  [[ "$answer" =~ ^[Yy] ]]
}

confirm_yes() {
  local message="$1"
  local answer
  printf "%s [Y/n]: " "$message"
  read -r answer
  [[ ! "$answer" =~ ^[Nn] ]]
}

download() {
  local url="$1"
  local target="$2"
  if command -v curl &> /dev/null; then
    curl -fsSL "$url" -o "$target"
  elif command -v wget &> /dev/null; then
    wget -q "$url" -O "$target"
  else
    print_red "Error: curl or wget required"
    exit 1
  fi
}

# Declarative cleanup: remove files in a managed directory that aren't in the expected list.
# Usage: cleanup_managed_dir <dir> <expected_file1> [expected_file2] ...
cleanup_managed_dir() {
  local dir="$1"; shift
  local expected=("$@")

  [ -d "$dir" ] || return 0
  [ ${#expected[@]} -eq 0 ] && return 0

  for file in "$dir"/*; do
    [ -L "$file" ] && continue
    [ -f "$file" ] || continue
    local name=$(basename "$file")
    local keep=false
    for expected_name in "${expected[@]}"; do
      if [ "$name" = "$expected_name" ]; then
        keep=true
        break
      fi
    done
    if [ "$keep" = false ]; then
      rm -f "$file"
    fi
  done
}

# Compare two semver strings (X.Y.Z). Returns 0 if $1 > $2, else 1.
version_gt() {
  [ "$1" = "$2" ] && return 1
  local IFS=.
  local a=($1) b=($2)
  local i ai bi
  for i in 0 1 2; do
    ai=${a[i]:-0}; bi=${b[i]:-0}
    # strip any pre-release suffix so "1.2.3-dev" compares as 3
    ai=${ai%%[^0-9]*}; bi=${bi%%[^0-9]*}
    if [ "${ai:-0}" -gt "${bi:-0}" ] 2>/dev/null; then return 0; fi
    if [ "${ai:-0}" -lt "${bi:-0}" ] 2>/dev/null; then return 1; fi
  done
  return 1
}

# Fetch the latest released version from GitHub, cached for 1 day.
# Echoes the bare version (no leading "v"); returns 1 on failure/offline.
fetch_latest_version() {
  local cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/dotcontext"
  local cache_file="$cache_dir/latest_version"

  # Serve from cache if fresh (modified within the last day)
  if [ -f "$cache_file" ] && [ -n "$(find "$cache_file" -mtime -1 2>/dev/null)" ]; then
    cat "$cache_file"
    return 0
  fi

  local resp tag ver
  if command -v curl &> /dev/null; then
    resp=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null)
  elif command -v wget &> /dev/null; then
    resp=$(wget -qO- "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null)
  else
    return 1
  fi

  tag=$(echo "$resp" | grep '"tag_name"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
  ver=$(echo "$tag" | sed 's/^v//')
  [ -z "$ver" ] && return 1

  mkdir -p "$cache_dir" 2>/dev/null
  echo "$ver" > "$cache_file" 2>/dev/null
  echo "$ver"
}
# ── Hook Setup ────────────────────────────────────────────────────────────────

# Setup Claude Code hooks (project-local)
# - Notification + Stop: native OS notifications
# - PostToolUseFailure: tool failure guard (asks user after 4+ consecutive failures)
setup_notifications() {
  local scripts_dir=".claude/scripts"
  local settings_file=".claude/settings.json"

  # Create scripts directory
  mkdir -p "$scripts_dir"

  # Download and install scripts into project
  download "${BASE_URL}/scripts/notify.sh" "$scripts_dir/notify.sh"
  chmod +x "$scripts_dir/notify.sh"
  download "${BASE_URL}/scripts/tool-failure-guard.sh" "$scripts_dir/tool-failure-guard.sh"
  chmod +x "$scripts_dir/tool-failure-guard.sh"

  # Warn if global hooks exist from a previous dotcontext version
  if [ -f "$HOME/.claude/settings.json" ] && grep -q "notify.sh" "$HOME/.claude/settings.json" 2>/dev/null; then
    print_yellow "Global notification hooks detected in ~/.claude/settings.json"
    print_yellow "dotcontext now configures hooks per-project. You can remove the global hooks manually."
  fi

  # Create or update project-local settings.json with hooks
  local notification_hook='{
    "matcher": "",
    "hooks": [{"type": "command", "command": ".claude/scripts/notify.sh '\''Claude Code'\'' '\''Needs your attention'\'' question"}]
  }'
  local stop_hook='{
    "matcher": "",
    "hooks": [{"type": "command", "command": ".claude/scripts/notify.sh '\''Claude Code'\'' '\''Task completed'\'' success"}]
  }'
  local failure_guard_hook='{
    "matcher": "",
    "hooks": [{"type": "command", "command": ".claude/scripts/tool-failure-guard.sh"}]
  }'

  if [ ! -f "$settings_file" ]; then
    cat > "$settings_file" << 'SETTINGS_EOF'
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": ".claude/scripts/notify.sh 'Claude Code' 'Needs your attention' question"}]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": ".claude/scripts/notify.sh 'Claude Code' 'Task completed' success"}]
      }
    ],
    "PostToolUseFailure": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": ".claude/scripts/tool-failure-guard.sh"}]
      }
    ]
  }
}
SETTINGS_EOF
    print_gray "Hooks configured in .claude/settings.json"
  else
    # Check if hooks already configured
    if ! grep -q "notify.sh" "$settings_file" 2>/dev/null; then
      if command -v jq &>/dev/null; then
        local temp_file=$(mktemp)
        jq --argjson notif "$notification_hook" --argjson stop "$stop_hook" '
          .hooks.Notification = ((.hooks.Notification // []) + [$notif]) |
          .hooks.Stop = ((.hooks.Stop // []) + [$stop])
        ' "$settings_file" > "$temp_file" 2>/dev/null
        if [ $? -eq 0 ] && [ -s "$temp_file" ]; then
          mv "$temp_file" "$settings_file"
          print_gray "Notification hooks added to .claude/settings.json"
        else
          rm -f "$temp_file"
        fi
      else
        print_yellow "Install jq to auto-configure hooks, or add manually"
      fi
    fi

    # Add failure guard if not already present
    if ! grep -q "tool-failure-guard" "$settings_file" 2>/dev/null; then
      if command -v jq &>/dev/null; then
        local temp_file=$(mktemp)
        jq --argjson guard "$failure_guard_hook" '
          .hooks.PostToolUseFailure = ((.hooks.PostToolUseFailure // []) + [$guard])
        ' "$settings_file" > "$temp_file" 2>/dev/null
        if [ $? -eq 0 ] && [ -s "$temp_file" ]; then
          mv "$temp_file" "$settings_file"
          print_gray "Tool failure guard hook added to .claude/settings.json"
        else
          rm -f "$temp_file"
        fi
      fi
    fi
  fi
}
# ── MCP Server Setup ──────────────────────────────────────────────────────────

# Setup MCP servers in .mcp.json
setup_mcp() {
  local add_context7="$1"
  local add_atlassian="$2"
  local mcp_file=".mcp.json"

  if [ -f "$mcp_file" ]; then
    return 0
  fi

  local servers=""
  local comma=""

  if [ "$add_context7" = true ]; then
    servers="${servers}${comma}
    \"context7\": {
      \"command\": \"npx\",
      \"args\": [\"-y\", \"@upstash/context7-mcp\"]
    }"
    comma=","
  fi

  if [ "$add_atlassian" = true ]; then
    servers="${servers}${comma}
    \"atlassian\": {
      \"type\": \"http\",
      \"url\": \"https://mcp.atlassian.com/v1/sse\"
    }"
  fi

  if [ -n "$servers" ]; then
    cat > "$mcp_file" << EOF
{
  "mcpServers": {${servers}
  }
}
EOF
    print_gray "MCP servers configured in .mcp.json"
  fi
}
# ── Agent Adapter Registry ──────────────────────────────────────────────────
# Each supported coding agent is one entry. Adding an agent means adding it to
# AGENT_IDS and the case arms below — nothing else in the toolkit hard-codes an
# agent. (ADR-016)
#
# Emit modes for the project-instructions file:
#   import — a thin stub that @-imports AGENTS.md (Claude Code, Gemini CLI)
#   native — reads AGENTS.md directly; needs no file of its own (Codex,
#            opencode, Copilot, Cursor incl. the cursor-agent CLI)
#
# AGENTS.md itself is the canonical single source and is always emitted.

AGENT_IDS="claude codex opencode gemini copilot cursor"

agent_name() {
  case "$1" in
    claude)   echo "Claude Code" ;;
    codex)    echo "OpenAI Codex" ;;
    opencode) echo "opencode" ;;
    gemini)   echo "Gemini CLI" ;;
    copilot)  echo "GitHub Copilot" ;;
    cursor)   echo "Cursor (cursor-agent)" ;;
    *)        echo "$1" ;;
  esac
}

# Detection: is the agent's CLI installed?
agent_detect() {
  case "$1" in
    claude)   command -v claude >/dev/null 2>&1 ;;
    codex)    command -v codex >/dev/null 2>&1 ;;
    opencode) command -v opencode >/dev/null 2>&1 ;;
    gemini)   command -v gemini >/dev/null 2>&1 ;;
    copilot)  command -v copilot >/dev/null 2>&1 || \
              { command -v gh >/dev/null 2>&1 && gh extension list 2>/dev/null | grep -qi copilot; } ;;
    cursor)   command -v cursor-agent >/dev/null 2>&1 ;;
    *)        return 1 ;;
  esac
}

# The instruction file this agent reads.
agent_instructions_file() {
  case "$1" in
    claude)   echo "CLAUDE.md" ;;
    gemini)   echo "GEMINI.md" ;;
    *)        echo "AGENTS.md" ;;
  esac
}

# How this agent gets its instructions: import | native
agent_emit_mode() {
  case "$1" in
    claude|gemini) echo "import" ;;
    *)             echo "native" ;;
  esac
}

# Echo the ids of detected (installed) agents, space-separated.
detect_agents() {
  local id out=""
  for id in $AGENT_IDS; do
    if agent_detect "$id"; then out="$out $id"; fi
  done
  echo "${out# }"
}

# Echo "url|target" instruction-file seed mappings for the selected agent ids.
# AGENTS.md (canonical) is always first; import-mode agents add their stub.
# Native agents need no extra file (they read AGENTS.md directly).
# The "|" separator can't appear in a URL or a filename, so consumers parse it
# unambiguously: url="${mapping%|*}", target="${mapping##*|}".
agent_instruction_seeds() {
  local selected="$1" id target seen=" "
  echo "${BASE_URL}/templates/AGENTS.md|AGENTS.md"
  for id in $selected; do
    [ "$(agent_emit_mode "$id")" = "import" ] || continue
    target="$(agent_instructions_file "$id")"
    case "$seen" in *" $target "*) continue ;; esac
    seen="$seen$target "
    echo "${BASE_URL}/templates/${target}|${target}"
  done
}

# True if the id list contains a given agent.
agents_include() {
  case " $1 " in *" $2 "*) return 0 ;; *) return 1 ;; esac
}

# Resolve which harnesses to instantiate. Sets the global SELECTED_AGENTS.
# Priority: explicit --agents list > non-interactive (detected, fallback claude)
# > interactive (confirm each detected agent; offer Claude if none).
# Must NOT run inside $(...) — it prompts on stdout. (ADR-016)
SELECTED_AGENTS=""
resolve_selected_agents() {
  local agents_flag="$1" skip_prompts="$2"
  SELECTED_AGENTS=""

  if [ -n "$agents_flag" ]; then
    local IFS=',' id
    for id in $agents_flag; do
      id="$(echo "$id" | tr -d '[:space:]')"
      [ -z "$id" ] && continue
      if agents_include "$AGENT_IDS" "$id"; then
        SELECTED_AGENTS="$SELECTED_AGENTS $id"
      else
        print_yellow "  unknown agent '$id' (skipped) — known: $AGENT_IDS"
      fi
    done
    SELECTED_AGENTS="${SELECTED_AGENTS# }"
    return 0
  fi

  local detected; detected="$(detect_agents)"

  if [ "$skip_prompts" = "true" ]; then
    SELECTED_AGENTS="$detected"
    [ -z "$SELECTED_AGENTS" ] && SELECTED_AGENTS="claude"
    return 0
  fi

  local id
  if [ -n "$detected" ]; then
    print_blue "Detected agents — choose which to set up:"
    for id in $detected; do
      if confirm_yes "  Set up for $(agent_name "$id")?"; then
        SELECTED_AGENTS="$SELECTED_AGENTS $id"
      fi
    done
  fi
  SELECTED_AGENTS="${SELECTED_AGENTS# }"

  if [ -z "$SELECTED_AGENTS" ]; then
    if confirm_yes "  No agent selected — set up for Claude Code?"; then
      SELECTED_AGENTS="claude"
    fi
  fi
}

# Create $2 as a symlink to $1 (relative), or copy if symlinks aren't available.
# No-op if $2 already exists. Used to mirror the skills dir across ecosystems.
link_or_copy_dir() {
  local src="$1" dst="$2"
  [ -d "$src" ] || return 0
  if [ -e "$dst" ] || [ -L "$dst" ]; then return 0; fi
  mkdir -p "$(dirname "$dst")"
  ln -s "../$src" "$dst" 2>/dev/null || cp -r "$src" "$dst"
}

# ── Per-agent hooks ───────────────────────────────────────────────────────────
# Wire a "task finished / needs attention" notification per selected agent.
# Claude keeps its richer hooks (notify + tool-failure-guard) via
# setup_notifications. Non-Claude agents get a notification hook in their native
# config format, pointing at a shared, arg-driven notify.sh (it ignores stdin,
# so the same script works regardless of each agent's hook JSON contract).
# Best-effort + create-only: never clobbers an existing agent config.
NOTIFY_SHARED=".context/scripts/notify.sh"

ensure_shared_notify() {
  [ -f "$NOTIFY_SHARED" ] && return 0
  mkdir -p ".context/scripts"
  download "${BASE_URL}/scripts/notify.sh" "$NOTIFY_SHARED" && chmod +x "$NOTIFY_SHARED"
}

setup_agent_hooks() {
  local selected="$1" id done_any=false
  for id in $selected; do
    case "$id" in
      claude)
        setup_notifications 2>/dev/null || true
        done_any=true
        ;;
      codex)
        ensure_shared_notify
        if [ ! -f ".codex/hooks.json" ]; then
          mkdir -p ".codex"
          cat > ".codex/hooks.json" <<JSON
{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "$NOTIFY_SHARED 'Codex' 'Task completed' success" } ] }
    ]
  }
}
JSON
          print_gray "  hooks: .codex/hooks.json"
          done_any=true
        fi
        ;;
      gemini)
        ensure_shared_notify
        if [ ! -f ".gemini/settings.json" ]; then
          mkdir -p ".gemini"
          cat > ".gemini/settings.json" <<JSON
{
  "hooks": {
    "Notification": [
      { "hooks": [ { "type": "command", "command": "$NOTIFY_SHARED 'Gemini' 'Needs your attention' question" } ] }
    ],
    "AfterAgent": [
      { "hooks": [ { "type": "command", "command": "$NOTIFY_SHARED 'Gemini' 'Task completed' success" } ] }
    ]
  }
}
JSON
          print_gray "  hooks: .gemini/settings.json"
          done_any=true
        fi
        ;;
      copilot)
        ensure_shared_notify
        if [ ! -f ".github/hooks/dotcontext-notify.json" ]; then
          mkdir -p ".github/hooks"
          cat > ".github/hooks/dotcontext-notify.json" <<JSON
{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "$NOTIFY_SHARED 'Copilot' 'Task completed' success" } ] }
    ]
  }
}
JSON
          print_gray "  hooks: .github/hooks/dotcontext-notify.json"
          done_any=true
        fi
        ;;
      cursor)
        ensure_shared_notify
        if [ ! -f ".cursor/hooks.json" ]; then
          mkdir -p ".cursor"
          cat > ".cursor/hooks.json" <<JSON
{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": "$NOTIFY_SHARED 'Cursor' 'Task completed' success" }
    ]
  }
}
JSON
          print_gray "  hooks: .cursor/hooks.json"
          done_any=true
        fi
        ;;
      opencode)
        ensure_shared_notify
        if [ ! -f ".opencode/plugins/dotcontext-notify.js" ]; then
          mkdir -p ".opencode/plugins"
          cat > ".opencode/plugins/dotcontext-notify.js" <<'JS'
// dotcontext: fire an OS notification when the session goes idle.
export const DotcontextNotify = async ({ $ }) => ({
  event: async ({ event }) => {
    if (event?.type === "session.idle") {
      await $`.context/scripts/notify.sh 'opencode' 'Task completed' success`.catch(() => {})
    }
  },
})
JS
          print_gray "  hooks: .opencode/plugins/dotcontext-notify.js"
          done_any=true
        fi
        ;;
    esac
  done
  [ "$done_any" = true ] || true
}

# ── Per-agent commands (hybrid, ADR-018) ──────────────────────────────────────
# The canonical workflow prompts ship in templates/.claude/commands/. Claude gets
# them in .claude/commands/ (handled in init). opencode and Copilot get native
# command/prompt files here; Gemini/Cursor/Codex rely on the "## Workflows"
# section emitted into AGENTS.md. Create-only — never clobbers existing files.
DOTCONTEXT_COMMANDS="setup-context spec-dc plan-dc execute-dc code-review commit create-pr pr-comment deep-context fix-bug add-decision add-skill add-command"

emit_agent_commands() {
  local selected="$1" id name
  for id in $selected; do
    case "$id" in
      opencode)
        mkdir -p ".opencode/command"
        for name in $DOTCONTEXT_COMMANDS; do
          [ -f ".opencode/command/${name}.md" ] || \
            download "${BASE_URL}/templates/.claude/commands/${name}.md" ".opencode/command/${name}.md"
        done
        print_gray "  commands: .opencode/command/ (opencode)"
        ;;
      copilot)
        mkdir -p ".github/prompts"
        for name in $DOTCONTEXT_COMMANDS; do
          [ -f ".github/prompts/${name}.prompt.md" ] || \
            download "${BASE_URL}/templates/.claude/commands/${name}.md" ".github/prompts/${name}.prompt.md"
        done
        print_gray "  commands: .github/prompts/ (copilot)"
        ;;
    esac
  done
}
# ── Command: init ─────────────────────────────────────────────────────────────

cmd_init() {
  local project_name=""
  local skip_prompts=false
  local skip_setup=false
  local agents_flag=""

  while [[ $# -gt 0 ]]; do
    case "$1" in
      -n|--name) project_name="$2"; shift 2 ;;
      -y|--yes) skip_prompts=true; shift ;;
      --no-setup) skip_setup=true; shift ;;
      --agents) agents_flag="$2"; shift 2 ;;
      *) shift ;;
    esac
  done

  print_blue ""
  printf "${BLUE}📁 dotcontext - AI Context Toolkit${NC}\n\n"

  local cwd="$(pwd)"

  local is_reinit=false
  if [ -d ".context" ]; then
    is_reinit=true
    print_yellow "Existing .context/ detected — will add missing files without overwriting your content."
  fi

  if [ -z "$project_name" ]; then
    if [ "$skip_prompts" = false ]; then
      project_name=$(prompt "Project name" "$(basename "$cwd")")
    else
      project_name="$(basename "$cwd")"
    fi
  fi

  # Resolve which harnesses to instantiate (sets SELECTED_AGENTS). Only the
  # chosen harnesses get files — no .claude/ for a Codex-only user, etc. (ADR-016)
  resolve_selected_agents "$agents_flag" "$skip_prompts"
  local selected="$SELECTED_AGENTS"
  if [ -z "$selected" ]; then
    print_red "No harness selected — nothing to set up. Re-run and pick at least one agent."
    return 1
  fi
  local wants_claude=false; agents_include "$selected" claude && wants_claude=true
  local wants_agents_skills=false
  local _id
  for _id in $selected; do [ "$_id" != "claude" ] && wants_agents_skills=true; done

  print_gray "Setting up for: $selected"

  # Harness-agnostic context skeleton (always)
  # specs/ + plans/ back the spec → plan → execute workflow (ADR-020).
  mkdir -p ".context/decisions" ".context/specs" ".context/plans" \
           ".context/discoveries" ".context/bugs"

  start_spinner "Downloading templates..."

  # Helper: download only if file doesn't exist (seed/user-customizable files)
  local skipped_files=""
  download_if_missing() {
    local url="$1"
    local target="$2"
    if [ -f "$target" ]; then
      [ "$is_reinit" = true ] && skipped_files="${skipped_files}${target}\n"
      return 0
    fi
    download "$url" "$target"
  }

  # ── Shared context (every harness) ──
  download_if_missing "${BASE_URL}/templates/.context/CONTEXT.md" ".context/CONTEXT.md"
  download_if_missing "${BASE_URL}/templates/.context/decisions/README.md" ".context/decisions/README.md"
  download_if_missing "${BASE_URL}/templates/.context/specs/README.md" ".context/specs/README.md"
  download_if_missing "${BASE_URL}/templates/.context/plans/README.md" ".context/plans/README.md"

  # ── Project instructions: canonical AGENTS.md + import stubs for selected agents ──
  for mapping in $(agent_instruction_seeds "$selected"); do
    # mappings are "url|target" ("|" can't appear in a URL or filename)
    download_if_missing "${mapping%|*}" "${mapping##*|}"
  done

  # ── Skills (shared SKILL.md content; physical home depends on selection) ──
  local skills_dir
  if [ "$wants_claude" = true ]; then skills_dir=".claude/skills"; else skills_dir=".agents/skills"; fi
  mkdir -p "$skills_dir/bug-reproduction" "$skills_dir/batch-operations" \
           "$skills_dir/git-platform" "$skills_dir/update-api-documentation"
  download_if_missing "${BASE_URL}/templates/.claude/skills/bug-reproduction/SKILL.md" "$skills_dir/bug-reproduction/SKILL.md"
  download_if_missing "${BASE_URL}/templates/.claude/skills/batch-operations/SKILL.md" "$skills_dir/batch-operations/SKILL.md"
  download_if_missing "${BASE_URL}/templates/.claude/skills/git-platform/SKILL.md" "$skills_dir/git-platform/SKILL.md"
  download_if_missing "${BASE_URL}/templates/.claude/skills/update-api-documentation/SKILL.md" "$skills_dir/update-api-documentation/SKILL.md"
  # If both Claude and an AGENTS.md-reading agent are selected, mirror so both see the skills
  if [ "$wants_claude" = true ] && [ "$wants_agents_skills" = true ]; then
    link_or_copy_dir ".claude/skills" ".agents/skills"
  fi

  # ── Claude-only toolkit (commands, agents, statusline, ignore) ──
  if [ "$wants_claude" = true ]; then
    mkdir -p ".claude/commands" ".claude/scripts" \
             ".claude/agents/code-review" ".claude/agents/deep-context" ".claude/agents/fix-bug" \
             ".claude/agents/spec-dc" ".claude/agents/plan-dc" ".claude/agents/execute-dc"
    download_if_missing "${BASE_URL}/templates/.claudeignore" ".claudeignore"

    local c
    for c in setup-context code-review spec-dc plan-dc execute-dc add-decision add-skill \
             add-command create-pr pr-comment deep-context fix-bug commit; do
      download "${BASE_URL}/templates/.claude/commands/${c}.md" ".claude/commands/${c}.md"
    done

    download "${BASE_URL}/templates/.claude/scripts/statusline.sh" ".claude/scripts/statusline.sh"
    chmod +x ".claude/scripts/statusline.sh"

    local a
    for a in code-review/compliance-checker code-review/bug-detector code-review/security-analyst \
             deep-context/step1-overview deep-context/step2-subsystems deep-context/step3-drill \
             deep-context/step4-dataflow fix-bug/investigator fix-bug/fix-conservative \
             fix-bug/fix-minimal fix-bug/fix-refactor fix-bug/reviewer \
             spec-dc/reviewer-pro spec-dc/reviewer-fast \
             plan-dc/reviewer-pro plan-dc/reviewer-fast \
             execute-dc/reviewer-pro execute-dc/reviewer-fast; do
      download "${BASE_URL}/templates/.claude/agents/${a}.md" ".claude/agents/${a}.md"
    done

    cleanup_managed_dir ".claude/agents/code-review" \
      compliance-checker.md bug-detector.md security-analyst.md
    cleanup_managed_dir ".claude/agents/deep-context" \
      step1-overview.md step2-subsystems.md step3-drill.md step4-dataflow.md
    cleanup_managed_dir ".claude/agents/fix-bug" \
      investigator.md fix-conservative.md fix-minimal.md fix-refactor.md reviewer.md
    cleanup_managed_dir ".claude/agents/spec-dc" \
      reviewer-pro.md reviewer-fast.md
    cleanup_managed_dir ".claude/agents/plan-dc" \
      reviewer-pro.md reviewer-fast.md
    cleanup_managed_dir ".claude/agents/execute-dc" \
      reviewer-pro.md reviewer-fast.md
    cleanup_managed_dir ".claude/scripts" \
      statusline.sh notify.sh tool-failure-guard.sh
  fi

  stop_spinner

  if [ -n "$skipped_files" ]; then
    printf "$skipped_files" | while read -r f; do
      [ -n "$f" ] && print_gray "  skipped (exists): $f"
    done
  fi

  touch ".context/discoveries/.keep" ".context/bugs/.keep"

  # ── Commands per selected harness (opencode/Copilot native; others via AGENTS.md Workflows) ──
  emit_agent_commands "$selected" 2>/dev/null || true

  # ── Hooks per selected harness (notifications; Claude also gets the failure guard) ──
  setup_agent_hooks "$selected" 2>/dev/null || true

  # ── MCP servers (cross-agent; Context7/Atlassian work across harnesses) ──
  if [ ! -f ".mcp.json" ]; then
    local add_context7=false
    local add_atlassian=false
    if [ "$skip_prompts" = false ]; then
      echo ""
      print_blue "MCP Servers"
      print_gray "Configure Model Context Protocol servers for your agents"
      echo ""
      confirm_yes "  Add Context7? (up-to-date library docs for LLMs)" && add_context7=true
      confirm_yes "  Add Atlassian? (Jira + Confluence via OAuth)" && add_atlassian=true
    else
      add_context7=true
      add_atlassian=true
    fi
    setup_mcp "$add_context7" "$add_atlassian"
  else
    print_gray "  skipped (exists): .mcp.json"
  fi

  # Offer to install shell tab-completion (interactive runs only)
  if [ "$skip_prompts" = false ] && [ -t 0 ]; then
    offer_completion_install
  fi

  # Substitute project name in any instruction file that still has the placeholder
  local inst_file
  for inst_file in AGENTS.md CLAUDE.md GEMINI.md; do
    if grep -q "{{projectName}}" "$inst_file" 2>/dev/null; then
      if [[ "$OSTYPE" == "darwin"* ]]; then
        sed -i '' "s/{{projectName}}/$project_name/g" "$inst_file"
      else
        sed -i "s/{{projectName}}/$project_name/g" "$inst_file"
      fi
    fi
  done

  echo ""
  if [ "$is_reinit" = true ]; then
    printf "  ${GREEN}${ICON_SUCCESS}${NC} Context structure updated\n"
  else
    printf "  ${GREEN}${ICON_SUCCESS}${NC} Context structure created\n"
  fi
  local _names="" _i
  for _i in $selected; do _names="$_names$(agent_name "$_i"), "; done
  printf "  ${GRAY}Harnesses: %s${NC}\n" "${_names%, }"
  echo ""

  # /setup-context is a Claude command — only when Claude is part of the setup
  if [ "$wants_claude" = true ]; then
    if [ "$skip_setup" = true ]; then
      printf "  ${CYAN}Next:${NC}  run ${CYAN}/setup-context${NC} in Claude Code\n"
    elif command -v claude &> /dev/null; then
      printf "  ${CYAN}Running /setup-context...${NC}\n\n"
      claude "/setup-context"
    else
      printf "  ${YELLOW}Claude CLI not found.${NC} Run ${CYAN}/setup-context${NC} manually in Claude Code.\n"
    fi
  else
    printf "  ${CYAN}Next:${NC}  edit ${CYAN}AGENTS.md${NC} and ${CYAN}.context/CONTEXT.md${NC} to describe your project\n"
  fi
  echo ""
}
# ── Command: update ───────────────────────────────────────────────────────────

cmd_update() {
  local templates_only=false
  local cli_only=false
  local auto_yes=false
  local dry_run=false

  while [[ $# -gt 0 ]]; do
    case "$1" in
      --templates) templates_only=true; shift ;;
      --cli) cli_only=true; shift ;;
      --yes|-y) auto_yes=true; shift ;;
      --dry-run) dry_run=true; shift ;;
      *) shift ;;
    esac
  done

  if [ "$templates_only" = true ]; then
    cmd_update_templates "$auto_yes" "$dry_run"
  elif [ "$cli_only" = true ]; then
    cmd_update_cli
  else
    # Default: update CLI, then templates if in a project
    cmd_update_cli
    if [ -d ".context" ]; then
      echo ""
      # Re-exec with new binary so template list is up to date
      local new_bin
      new_bin=$(command -v dotcontext 2>/dev/null || echo "")
      if [ -n "$new_bin" ] && [ -x "$new_bin" ]; then
        local new_ver
        new_ver=$("$new_bin" --version 2>/dev/null | sed 's/dotcontext //')
        if [ "$new_ver" != "$VERSION" ]; then
          local args="update --templates"
          [ "$auto_yes" = "true" ] && args="$args --yes"
          [ "$dry_run" = "true" ] && args="$args --dry-run"
          exec "$new_bin" $args
        fi
      fi
      cmd_update_templates "$auto_yes" "$dry_run"
    fi
  fi
}

cmd_update_cli() {
  start_spinner "Checking for CLI updates..."

  # Get latest version tag from GitHub (try releases first, then tags)
  local latest_version
  local latest_tag
  local api_response

  if command -v curl &> /dev/null; then
    api_response=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null)
    latest_tag=$(echo "$api_response" | grep '"tag_name"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
    latest_version=$(echo "$latest_tag" | sed 's/^v//')

    if [ -z "$latest_version" ]; then
      api_response=$(curl -fsSL "https://api.github.com/repos/${REPO}/tags" 2>/dev/null)
      latest_tag=$(echo "$api_response" | grep '"name"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
      latest_version=$(echo "$latest_tag" | sed 's/^v//')
    fi
  else
    api_response=$(wget -qO- "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null)
    latest_tag=$(echo "$api_response" | grep '"tag_name"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
    latest_version=$(echo "$latest_tag" | sed 's/^v//')

    if [ -z "$latest_version" ]; then
      api_response=$(wget -qO- "https://api.github.com/repos/${REPO}/tags" 2>/dev/null)
      latest_tag=$(echo "$api_response" | grep '"name"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
      latest_version=$(echo "$latest_tag" | sed 's/^v//')
    fi
  fi

  if [ -z "$latest_version" ]; then
    stop_spinner
    print_red "Could not check latest version."
    return 1
  fi

  if [ "$VERSION" = "$latest_version" ]; then
    stop_spinner "$(printf "${GREEN}${ICON_SUCCESS} CLI already at latest version ($VERSION)${NC}")"
    return 0
  fi

  stop_spinner "$(printf "${GRAY}Current: $VERSION → Latest: $latest_version${NC}")"

  # Find installation path
  local install_path=$(command -v dotcontext)
  if [ -z "$install_path" ]; then
    install_path="/usr/local/bin/dotcontext"
  fi

  # Download from release tag (not main branch) to avoid unreleased code
  local release_url="https://raw.githubusercontent.com/${REPO}/${latest_tag}/dotcontext"
  start_spinner "Downloading from release ${latest_tag}..."

  local tmp_file=$(mktemp)
  download "$release_url" "$tmp_file"
  stop_spinner

  # Verify download
  if [ ! -s "$tmp_file" ] || ! head -1 "$tmp_file" | grep -q "^#!/bin/bash"; then
    print_red "Error: Download failed"
    rm -f "$tmp_file"
    return 1
  fi

  chmod +x "$tmp_file"

  # Install
  if [ -w "$(dirname "$install_path")" ]; then
    mv "$tmp_file" "$install_path"
  else
    print_yellow "Need sudo to update $install_path"
    sudo mv "$tmp_file" "$install_path"
    sudo chmod +x "$install_path"
  fi

  print_green "${ICON_SUCCESS} CLI updated to $latest_version"
}

cmd_update_templates() {
  local auto_yes="$1"
  local dry_run="$2"

  if [ ! -d ".context" ]; then
    print_red "No .context directory. Run \`dotcontext init\` first."
    return 1
  fi

  # Migration: move skills from .context/skills/ to .claude/skills/
  if [ -d ".context/skills" ] && [ ! -d ".claude/skills" ]; then
    mkdir -p ".claude/skills"
    cp -r .context/skills/* .claude/skills/ 2>/dev/null || true
    rm -rf .context/skills
    print_green "  Migrated .context/skills/ → .claude/skills/"
  elif [ -d ".context/skills" ] && [ -d ".claude/skills" ]; then
    # Both exist — merge old into new (don't overwrite existing)
    for dir in .context/skills/*/; do
      local skill_name=$(basename "$dir")
      if [ ! -d ".claude/skills/$skill_name" ]; then
        cp -r "$dir" ".claude/skills/$skill_name"
      fi
    done
    rm -rf .context/skills
    print_green "  Migrated remaining skills from .context/skills/ → .claude/skills/"
  fi

  # Migration: adopt AGENTS.md as the canonical instruction source (ADR-016).
  # Legacy projects have a content-bearing CLAUDE.md and no AGENTS.md. Moving
  # the content to AGENTS.md (and leaving CLAUDE.md as an @import stub) is
  # content- and behavior-preserving for Claude, and lets the other agents read
  # the same instructions natively.
  local _stub_comment='<!-- Project instructions live in AGENTS.md (shared canonical source). Edit that file. -->'
  if [ -f "CLAUDE.md" ] && [ ! -f "AGENTS.md" ] && ! grep -q '@AGENTS.md' "CLAUDE.md" 2>/dev/null; then
    if [ "$dry_run" = "true" ]; then
      print_gray "  [dry-run] would migrate CLAUDE.md → AGENTS.md (+ CLAUDE.md import stub)"
    else
      local do_migrate=false
      if [ "$auto_yes" = "true" ]; then
        do_migrate=true
      elif confirm_yes "  Adopt AGENTS.md as the shared instructions file? (Claude keeps working via import)"; then
        do_migrate=true
      fi
      if [ "$do_migrate" = true ]; then
        mv "CLAUDE.md" "AGENTS.md"
        printf '%s\n\n%s\n' "$_stub_comment" '@AGENTS.md' > "CLAUDE.md"
        print_green "  Migrated CLAUDE.md → AGENTS.md (Claude reads it via @import)"
      fi
    fi
  fi

  # Add a Gemini import stub when the Gemini CLI is present and AGENTS.md exists.
  if agent_detect gemini && [ -f "AGENTS.md" ] && [ ! -f "GEMINI.md" ]; then
    if [ "$dry_run" = "true" ]; then
      print_gray "  [dry-run] would add GEMINI.md (imports AGENTS.md)"
    else
      printf '%s\n\n%s\n' "$_stub_comment" '@AGENTS.md' > "GEMINI.md"
      print_green "  Added GEMINI.md (imports AGENTS.md)"
    fi
  fi

  # Mirror skills to .agents/skills/ when a non-Claude agent is present (ADR-017).
  if [ -d ".claude/skills" ] && [ ! -e ".agents/skills" ]; then
    local _na=false _aid
    for _aid in $(detect_agents); do [ "$_aid" != "claude" ] && _na=true; done
    if [ "$_na" = true ]; then
      if [ "$dry_run" = "true" ]; then
        print_gray "  [dry-run] would mirror .claude/skills → .agents/skills (non-Claude agent detected)"
      else
        link_or_copy_dir ".claude/skills" ".agents/skills"
        print_green "  Mirrored skills to .agents/skills/"
      fi
    fi
  fi

  start_spinner "Checking templates..."

  # MANAGED templates: dotcontext-owned code (commands, templates that drive commands).
  # Always offered for update — diff is shown, user can accept or skip.
  declare -a managed_templates=(
    "templates/.claude/commands/setup-context.md:.claude/commands/setup-context.md"
    "templates/.claude/commands/code-review.md:.claude/commands/code-review.md"
    "templates/.claude/commands/spec-dc.md:.claude/commands/spec-dc.md"
    "templates/.claude/commands/plan-dc.md:.claude/commands/plan-dc.md"
    "templates/.claude/commands/execute-dc.md:.claude/commands/execute-dc.md"
    "templates/.claude/commands/add-decision.md:.claude/commands/add-decision.md"
    "templates/.claude/commands/add-skill.md:.claude/commands/add-skill.md"
    "templates/.claude/commands/add-command.md:.claude/commands/add-command.md"
    "templates/.claude/commands/create-pr.md:.claude/commands/create-pr.md"
    "templates/.claude/commands/pr-comment.md:.claude/commands/pr-comment.md"
    "templates/.claude/commands/deep-context.md:.claude/commands/deep-context.md"
    "templates/.claude/commands/fix-bug.md:.claude/commands/fix-bug.md"
    "templates/.claude/commands/commit.md:.claude/commands/commit.md"
    "templates/.claude/scripts/statusline.sh:.claude/scripts/statusline.sh"
    "templates/.claude/agents/code-review/compliance-checker.md:.claude/agents/code-review/compliance-checker.md"
    "templates/.claude/agents/code-review/bug-detector.md:.claude/agents/code-review/bug-detector.md"
    "templates/.claude/agents/code-review/security-analyst.md:.claude/agents/code-review/security-analyst.md"
    "templates/.claude/agents/deep-context/step1-overview.md:.claude/agents/deep-context/step1-overview.md"
    "templates/.claude/agents/deep-context/step2-subsystems.md:.claude/agents/deep-context/step2-subsystems.md"
    "templates/.claude/agents/deep-context/step3-drill.md:.claude/agents/deep-context/step3-drill.md"
    "templates/.claude/agents/deep-context/step4-dataflow.md:.claude/agents/deep-context/step4-dataflow.md"
    "templates/.claude/agents/fix-bug/investigator.md:.claude/agents/fix-bug/investigator.md"
    "templates/.claude/agents/fix-bug/fix-conservative.md:.claude/agents/fix-bug/fix-conservative.md"
    "templates/.claude/agents/fix-bug/fix-minimal.md:.claude/agents/fix-bug/fix-minimal.md"
    "templates/.claude/agents/fix-bug/fix-refactor.md:.claude/agents/fix-bug/fix-refactor.md"
    "templates/.claude/agents/fix-bug/reviewer.md:.claude/agents/fix-bug/reviewer.md"
    "templates/.claude/agents/spec-dc/reviewer-pro.md:.claude/agents/spec-dc/reviewer-pro.md"
    "templates/.claude/agents/spec-dc/reviewer-fast.md:.claude/agents/spec-dc/reviewer-fast.md"
    "templates/.claude/agents/plan-dc/reviewer-pro.md:.claude/agents/plan-dc/reviewer-pro.md"
    "templates/.claude/agents/plan-dc/reviewer-fast.md:.claude/agents/plan-dc/reviewer-fast.md"
    "templates/.claude/agents/execute-dc/reviewer-pro.md:.claude/agents/execute-dc/reviewer-pro.md"
    "templates/.claude/agents/execute-dc/reviewer-fast.md:.claude/agents/execute-dc/reviewer-fast.md"
  )

  # SEED templates: created once during init, customized by user or /setup-context.
  # Only added if missing — never offered for overwrite to protect user content.
  declare -a seed_templates=(
    "templates/AGENTS.md:AGENTS.md"
    "templates/.context/decisions/README.md:.context/decisions/README.md"
    "templates/.context/specs/README.md:.context/specs/README.md"
    "templates/.context/plans/README.md:.context/plans/README.md"
    "templates/.claude/skills/bug-reproduction/SKILL.md:.claude/skills/bug-reproduction/SKILL.md"
    "templates/.claude/skills/batch-operations/SKILL.md:.claude/skills/batch-operations/SKILL.md"
    "templates/.claude/skills/git-platform/SKILL.md:.claude/skills/git-platform/SKILL.md"
    "templates/.claude/skills/update-api-documentation/SKILL.md:.claude/skills/update-api-documentation/SKILL.md"
  )

  # Create temp directory for downloads
  local tmp_dir=$(mktemp -d)
  trap "rm -rf $tmp_dir" EXIT

  # Arrays to categorize files
  declare -a new_files=()
  declare -a modified_files=()
  declare -a unchanged_files=()
  declare -a seed_new_files=()
  declare -a seed_skipped_files=()

  # Process managed templates (can be updated)
  for mapping in "${managed_templates[@]}"; do
    local remote_path="${mapping%%:*}"
    local local_path="${mapping##*:}"
    local tmp_file="$tmp_dir/$(echo "$local_path" | sed 's|/|__|g')"

    if ! download "${BASE_URL}/${remote_path}" "$tmp_file" 2>/dev/null; then
      print_red "  failed to download: $remote_path"
      continue
    fi

    if [ ! -f "$local_path" ]; then
      new_files+=("$mapping")
    elif ! diff -q "$local_path" "$tmp_file" >/dev/null 2>&1; then
      modified_files+=("$mapping")
    else
      unchanged_files+=("$mapping")
    fi
  done

  # Process seed templates (create-only, never overwrite)
  for mapping in "${seed_templates[@]}"; do
    local remote_path="${mapping%%:*}"
    local local_path="${mapping##*:}"
    local tmp_file="$tmp_dir/$(echo "$local_path" | sed 's|/|__|g')"

    if ! download "${BASE_URL}/${remote_path}" "$tmp_file" 2>/dev/null; then
      print_red "  failed to download: $remote_path"
      continue
    fi

    if [ ! -f "$local_path" ]; then
      # Seed file missing — will be added
      seed_new_files+=("$mapping")
    else
      # Seed file exists — never touch it, even if different
      seed_skipped_files+=("$mapping")
    fi
  done

  stop_spinner

  # Display summary
  echo ""
  local has_changes=false

  if [ ${#new_files[@]} -gt 0 ] || [ ${#seed_new_files[@]} -gt 0 ]; then
    has_changes=true
    for mapping in "${new_files[@]}"; do
      local local_path="${mapping##*:}"
      printf "  ${GREEN}${ICON_ADD}${NC} %s ${GRAY}(new)${NC}\n" "$local_path"
    done
    for mapping in "${seed_new_files[@]}"; do
      local local_path="${mapping##*:}"
      printf "  ${GREEN}${ICON_ADD}${NC} %s ${GRAY}(new — seed template)${NC}\n" "$local_path"
    done
  fi

  if [ ${#modified_files[@]} -gt 0 ]; then
    has_changes=true
    for mapping in "${modified_files[@]}"; do
      local local_path="${mapping##*:}"
      printf "  ${YELLOW}${ICON_MODIFY}${NC} %s ${GRAY}(modified)${NC}\n" "$local_path"
    done
  fi

  if [ ${#unchanged_files[@]} -gt 0 ]; then
    for mapping in "${unchanged_files[@]}"; do
      local local_path="${mapping##*:}"
      printf "  ${GRAY}${ICON_UNCHANGED}${NC} %s ${GRAY}(unchanged)${NC}\n" "$local_path"
    done
  fi

  if [ ${#seed_skipped_files[@]} -gt 0 ]; then
    for mapping in "${seed_skipped_files[@]}"; do
      local local_path="${mapping##*:}"
      printf "  ${CYAN}${ICON_MANAGED}${NC} %s ${GRAY}(user-managed — skipped)${NC}\n" "$local_path"
    done
  fi

  local total_new=$((${#new_files[@]} + ${#seed_new_files[@]}))
  echo ""
  printf "Summary: ${GREEN}%d to add${NC}, ${YELLOW}%d to update${NC}, ${GRAY}%d unchanged${NC}, ${CYAN}%d user-managed${NC}\n" \
    "$total_new" "${#modified_files[@]}" "${#unchanged_files[@]}" "${#seed_skipped_files[@]}"

  # If no changes, exit early
  if [ "$has_changes" = false ]; then
    echo ""
    print_green "${ICON_SUCCESS} All templates up to date"
    return 0
  fi

  # Dry run - just show what would happen
  if [ "$dry_run" = "true" ]; then
    echo ""
    print_gray "Dry run - no changes made"
    return 0
  fi

  # Ask user what to do
  local action="n"
  if [ "$auto_yes" = "true" ]; then
    action="y"
  elif [ ${#modified_files[@]} -gt 0 ]; then
    echo ""
    printf "Update %d existing file(s)? [y/N/d] " "${#modified_files[@]}"
    printf "${GRAY}(y=yes, N=no, d=show diffs)${NC} "
    read -r action
    action="${action:-n}"

    # Handle diff option
    if [[ "$action" =~ ^[Dd] ]]; then
      echo ""
      for mapping in "${modified_files[@]}"; do
        local remote_path="${mapping%%:*}"
        local local_path="${mapping##*:}"
        local tmp_file="$tmp_dir/$(echo "$local_path" | sed 's|/|__|g')"

        print_cyan "=== $local_path ==="
        # diff exits 1 when files differ (normal), 2 when error (e.g. --color not supported)
        diff --color=auto -u "$local_path" "$tmp_file" 2>/dev/null
        if [ $? -eq 2 ]; then
          diff -u "$local_path" "$tmp_file"
        fi
        echo ""
      done

      printf "Update %d existing file(s)? [y/N] " "${#modified_files[@]}"
      read -r action
      action="${action:-n}"
    fi
  else
    action="y"  # Only new files, no need to ask
  fi

  # Apply changes
  local added=0
  local updated=0

  # Always add new managed files
  for mapping in "${new_files[@]}"; do
    local local_path="${mapping##*:}"
    local dir_path=$(dirname "$local_path")
    local tmp_file="$tmp_dir/$(echo "$local_path" | sed 's|/|__|g')"

    mkdir -p "$dir_path"
    cp "$tmp_file" "$local_path"
    ((added++))
  done

  # Always add new seed files (they don't exist yet)
  for mapping in "${seed_new_files[@]}"; do
    local local_path="${mapping##*:}"
    local dir_path=$(dirname "$local_path")
    local tmp_file="$tmp_dir/$(echo "$local_path" | sed 's|/|__|g')"

    mkdir -p "$dir_path"
    cp "$tmp_file" "$local_path"
    ((added++))
  done

  # Update modified managed files only if user said yes
  if [[ "$action" =~ ^[Yy] ]]; then
    for mapping in "${modified_files[@]}"; do
      local local_path="${mapping##*:}"
      local tmp_file="$tmp_dir/$(echo "$local_path" | sed 's|/|__|g')"

      cp "$tmp_file" "$local_path"
      ((updated++))
    done
  fi

  # Declarative cleanup: remove stale files from managed-only directories
  # NOTE: .claude/commands/ is excluded — users create custom commands there via /add-command
  cleanup_managed_dir ".claude/agents/code-review" \
    compliance-checker.md bug-detector.md security-analyst.md
  cleanup_managed_dir ".claude/agents/deep-context" \
    step1-overview.md step2-subsystems.md step3-drill.md step4-dataflow.md
  cleanup_managed_dir ".claude/agents/fix-bug" \
    investigator.md fix-conservative.md fix-minimal.md fix-refactor.md reviewer.md
  cleanup_managed_dir ".claude/agents/spec-dc" \
    reviewer-pro.md reviewer-fast.md
  cleanup_managed_dir ".claude/agents/plan-dc" \
    reviewer-pro.md reviewer-fast.md
  cleanup_managed_dir ".claude/agents/execute-dc" \
    reviewer-pro.md reviewer-fast.md
  cleanup_managed_dir ".claude/scripts" \
    statusline.sh

  # ── Deliver renamed workflows to existing per-harness installs (ADR-020) ──
  # Claude picks up spec/plan/execute-dc via managed_templates above. opencode and
  # Copilot keep their commands in .opencode/command / .github/prompts, emitted only
  # by emit_agent_commands (create-only). Re-run it here — inferring the harnesses in
  # use from the dirs that exist — so those installs also get the new commands.
  if [ "$dry_run" != "true" ]; then
    local _reemit=""
    [ -d ".opencode/command" ] && _reemit="$_reemit opencode"
    [ -d ".github/prompts" ]   && _reemit="$_reemit copilot"
    _reemit="${_reemit# }"
    [ -n "$_reemit" ] && emit_agent_commands "$_reemit" 2>/dev/null || true
  fi

  # ── Migration notice: the PRP flow is now spec → plan → execute (ADR-020) ──
  # Non-destructive — the old command files are kept and still work; tell the user so
  # they can clean up, and remind AGENTS.md-only harnesses (their table isn't rewritten).
  if [ -f ".claude/commands/generate-prp.md" ] || [ -f ".opencode/command/generate-prp.md" ] || \
     [ -f ".github/prompts/generate-prp.prompt.md" ] || grep -q "generate-prp" "AGENTS.md" 2>/dev/null; then
    echo ""
    print_yellow "Heads up: the PRP flow is now spec -> plan -> execute (ADR-020)."
    print_gray "  /generate-prp  ->  /spec-dc + /plan-dc      /execute-prp  ->  /execute-dc"
    print_gray "  Your old generate-prp/execute-prp were kept and still work -- remove them when ready."
    print_gray "  Gemini/Cursor/Codex: refresh the '## Workflows' table in AGENTS.md (it is not auto-updated)."
  fi

  echo ""
  if [ $added -gt 0 ] || [ $updated -gt 0 ]; then
    if [ $added -gt 0 ]; then
      print_green "${ICON_SUCCESS} Added $added new file(s)"
    fi
    if [ $updated -gt 0 ]; then
      print_green "${ICON_SUCCESS} Updated $updated file(s)"
    fi
  else
    print_gray "No changes made"
  fi

  # Offer MCP configuration if .mcp.json doesn't exist
  if [ ! -f ".mcp.json" ]; then
    local add_context7=false
    local add_atlassian=false

    if [ "$auto_yes" = "true" ]; then
      add_context7=true
      add_atlassian=true
    else
      echo ""
      print_blue "MCP Servers"
      print_gray "Configure Model Context Protocol servers for your agents"
      echo ""

      if confirm_yes "  Add Context7? (up-to-date library docs for LLMs)"; then
        add_context7=true
      fi

      if confirm_yes "  Add Atlassian? (Jira + Confluence via OAuth)"; then
        add_atlassian=true
      fi
    fi

    setup_mcp "$add_context7" "$add_atlassian"
  fi
}
# ── Command: doctor ───────────────────────────────────────────────────────────

cmd_doctor() {
  print_block_header "dotcontext doctor"
  echo ""

  local pass=0
  local fail=0
  local warn=0

  check_pass() {
    printf "  ${GREEN}${ICON_SUCCESS}${NC} %s\n" "$1"
    pass=$((pass + 1))
  }

  check_fail() {
    printf "  ${RED}${ICON_ERROR}${NC} %s\n" "$1"
    fail=$((fail + 1))
  }

  check_warn() {
    printf "  ${YELLOW}${ICON_WARNING}${NC} %s\n" "$1"
    warn=$((warn + 1))
  }

  # Check: Git repository
  if git rev-parse --is-inside-work-tree &>/dev/null; then
    check_pass "Git repository"
  else
    check_fail "Git repository — not a git repo"
  fi

  # Check: Claude CLI installed (informational — dotcontext is multi-agent, so a
  # missing Claude CLI is not a failure for Codex/opencode/Gemini/etc. projects)
  if command -v claude &>/dev/null; then
    local claude_ver
    claude_ver=$(claude --version 2>/dev/null || echo "unknown")
    check_pass "Claude CLI installed ($claude_ver)"
  else
    check_warn "Claude CLI — not installed (fine if you use another agent)"
  fi

  # Check: .context/ directory
  if [ -d ".context" ]; then
    check_pass ".context/ directory exists"
  else
    check_fail ".context/ directory — missing (run dotcontext init)"
  fi

  # Check: project instructions (AGENTS.md is canonical; CLAUDE.md/GEMINI.md may import it)
  local inst=""
  [ -s "AGENTS.md" ] && inst="AGENTS.md"
  [ -z "$inst" ] && [ -s "CLAUDE.md" ] && inst="CLAUDE.md"
  if [ -n "$inst" ]; then
    if grep -q "{{projectName}}" "$inst" 2>/dev/null; then
      check_warn "$inst — exists but has unfilled placeholders"
    elif [ "$inst" = "CLAUDE.md" ] && [ ! -f "AGENTS.md" ]; then
      check_warn "CLAUDE.md present but no AGENTS.md — run 'dotcontext update' to adopt the shared instructions file"
    else
      check_pass "Project instructions populated ($inst)"
    fi
  else
    check_fail "Project instructions — missing (run dotcontext init)"
  fi

  # Check: CONTEXT.md exists and non-empty
  if [ -s ".context/CONTEXT.md" ]; then
    check_pass ".context/CONTEXT.md populated"
  elif [ -f ".context/CONTEXT.md" ]; then
    check_warn ".context/CONTEXT.md — exists but empty"
  else
    check_fail ".context/CONTEXT.md — missing"
  fi

  # Check: decisions directory has ADRs
  local adr_count=0
  if [ -d ".context/decisions" ]; then
    adr_count=$(find .context/decisions -name "*.md" ! -name "README.md" 2>/dev/null | wc -l | tr -d ' ')
  fi
  if [ "$adr_count" -gt 0 ]; then
    check_pass ".context/decisions/ — $adr_count ADR(s)"
  else
    check_warn ".context/decisions/ — no ADRs found"
  fi

  # Check: workflow commands present (per-harness — a non-Claude project has no
  # .claude/, getting its workflows from .opencode/command, .github/prompts, or
  # the AGENTS.md "Workflows" section instead)
  local cmd_count=0
  if [ -d ".claude/commands" ]; then
    cmd_count=$(find .claude/commands -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
  fi
  if [ "$cmd_count" -gt 0 ]; then
    check_pass ".claude/commands/ — $cmd_count command(s)"
  elif [ -d ".opencode/command" ] || [ -d ".github/prompts" ]; then
    check_pass "Commands present (non-Claude harness)"
  elif grep -q "## Workflows" "AGENTS.md" 2>/dev/null; then
    check_pass "Workflows documented in AGENTS.md"
  else
    check_fail "No commands found (run dotcontext init)"
  fi

  # Check: .claude/agents/ present
  local agent_count=0
  if [ -d ".claude/agents" ]; then
    agent_count=$(find .claude/agents -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
  fi
  if [ "$agent_count" -gt 0 ]; then
    check_pass ".claude/agents/ — $agent_count agent(s)"
  else
    check_warn ".claude/agents/ — no agents found (run dotcontext update)"
  fi

  # Check: .claude/skills/ present
  if [ -d ".claude/skills" ]; then
    local skill_count
    skill_count=$(find .claude/skills -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
    if [ "$skill_count" -gt 0 ]; then
      check_pass ".claude/skills/ — $skill_count skill(s)"
    else
      check_warn ".claude/skills/ — directory exists but no skills"
    fi
  else
    check_warn ".claude/skills/ — missing"
  fi

  # Check: .mcp.json
  if [ -f ".mcp.json" ]; then
    if command -v jq &>/dev/null; then
      local server_count
      server_count=$(jq '.mcpServers | length' .mcp.json 2>/dev/null || echo "0")
      check_pass ".mcp.json — $server_count MCP server(s)"
    else
      check_pass ".mcp.json exists"
    fi
  else
    check_warn ".mcp.json — missing (no MCP servers configured)"
  fi

  # Check: hooks (project-local)
  if [ -f ".claude/settings.json" ]; then
    if grep -q "notify.sh" ".claude/settings.json" 2>/dev/null; then
      check_pass "Notification hooks configured (project-local)"
    else
      check_warn "Notification hooks — not configured in .claude/settings.json"
    fi
    if grep -q "tool-failure-guard" ".claude/settings.json" 2>/dev/null; then
      check_pass "Tool failure guard hook configured"
    else
      check_warn "Tool failure guard — not configured (run dotcontext init to add)"
    fi
  else
    check_warn ".claude/settings.json — missing (no hooks configured)"
  fi

  # Warn about legacy global hooks
  if [ -f "$HOME/.claude/settings.json" ] && grep -q "notify.sh" "$HOME/.claude/settings.json" 2>/dev/null; then
    check_warn "Legacy global hooks detected in ~/.claude/settings.json — remove manually to avoid duplicates"
  fi

  # Check: detected agents (informational — which agent CLIs are on PATH)
  local detected_agents
  detected_agents="$(detect_agents)"
  if [ -n "$detected_agents" ]; then
    local _names="" _aid
    for _aid in $detected_agents; do _names="$_names$(agent_name "$_aid"), "; done
    check_pass "Agents detected: ${_names%, }"
  else
    check_warn "No supported agent CLI detected on PATH"
  fi

  # Check: CLI update available (cached, best-effort — silent when offline)
  local latest_version
  latest_version=$(fetch_latest_version 2>/dev/null || echo "")
  if [ -n "$latest_version" ]; then
    if version_gt "$latest_version" "$VERSION"; then
      check_warn "dotcontext update available: $VERSION → $latest_version (run: dotcontext update --cli)"
    else
      check_pass "dotcontext up to date ($VERSION)"
    fi
  fi

  # Summary
  print_block_footer
  printf "  ${GREEN}%d passed${NC}  ${RED}%d failed${NC}  ${YELLOW}%d warnings${NC}\n" "$pass" "$fail" "$warn"

  if [ "$fail" -gt 0 ]; then
    echo ""
    print_gray "  Fix failures with: dotcontext init"
    return 1
  fi
}
# ── Command: help ─────────────────────────────────────────────────────────────

cmd_help() {
  local width
  width=$(get_term_width)

  # Determine column widths based on terminal
  local cmd_col=20
  local opt_col=22
  if [ "$width" -ge 100 ]; then
    cmd_col=24
    opt_col=26
  fi

  echo ""
  printf "  ${BOLD}dotcontext${NC} ${GRAY}— AI context toolkit for coding agents${NC}\n"
  echo ""

  # Usage
  printf "  ${BLUE}${BOLD}Usage${NC}\n"
  printf "    dotcontext <command> [options]\n"
  echo ""

  # Commands
  printf "  ${BLUE}${BOLD}Commands${NC}\n"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "init"       "Initialize context for your agent(s)"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "update"     "Update CLI and/or templates"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "doctor"     "Check project setup health"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "completion" "Generate shell tab completions"
  echo ""

  # Init Options
  printf "  ${BLUE}${BOLD}Init Options${NC}\n"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--name, -n <name>" "Project name"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--agents <list>"   "Harnesses to set up (e.g. claude,codex). Default: detected"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--yes, -y"         "Skip prompts, use defaults"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--no-setup"        "Skip automatic /setup-context"
  echo ""

  # Update Options
  printf "  ${BLUE}${BOLD}Update Options${NC}\n"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--cli"       "Only update CLI"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--templates" "Only update templates"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--yes, -y"   "Update without asking"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--dry-run"   "Show what would change"
  echo ""

  # Global Options
  printf "  ${BLUE}${BOLD}Global Options${NC}\n"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--help, -h"        "Show this help"
  printf "    ${YELLOW}%-${opt_col}s${NC}%s\n" "--version, -v"     "Show version (add --features or --json)"
  echo ""

  # Claude Code Commands
  printf "  ${BLUE}${BOLD}Workflows${NC} ${GRAY}(after init — slash commands on Claude/opencode/Copilot; AGENTS.md elsewhere)${NC}\n"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/setup-context"  "Analyze codebase and populate context"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/spec-dc"        "Write a behavior spec (the WHAT)"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/plan-dc"        "Turn a spec into a plan (the HOW)"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/execute-dc"     "Implement a plan in waves (the DO)"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/code-review"    "Multi-agent code review"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/commit"         "Smart commit messages"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/create-pr"      "Create PR with description"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/deep-context"   "Structured codebase exploration"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/fix-bug"        "Test-driven bug fixing"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/add-decision"   "Add architectural decision"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/add-skill"      "Add skill guide"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/add-command"    "Create custom command"
  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/release"        "Version bump and release"
  echo ""

  # Examples
  printf "  ${BLUE}${BOLD}Examples${NC}\n"
  printf "    ${GRAY}\$${NC} dotcontext init\n"
  printf "    ${GRAY}\$${NC} dotcontext init --name \"My Project\"\n"
  printf "    ${GRAY}\$${NC} dotcontext update --dry-run\n"
  printf "    ${GRAY}\$${NC} dotcontext doctor\n"
  printf "    ${GRAY}\$${NC} eval \"\$(dotcontext completion bash)\"\n"
  echo ""
}

# ── Command: version ──────────────────────────────────────────────────────────
# Plain `--version` prints the version. `--features` adds a human-readable
# capability list; `--json` emits a machine-readable capability handshake so an
# agent/harness can discover what this dotcontext supports before invoking it.

cmd_version() {
  local features=false
  local json=false
  for arg in "$@"; do
    case "$arg" in
      --features) features=true ;;
      --json) json=true ;;
      *)
        printf "${RED}Unknown option for --version: %s${NC}\n" "$arg" >&2
        printf "Usage: dotcontext --version [--features] [--json]\n" >&2
        return 1
        ;;
    esac
  done

  # Build the supported-agents array from the adapter registry (ADR-016)
  local id agents_json="" agents_list=""
  for id in $AGENT_IDS; do
    agents_json="${agents_json}\"$id\", "
    agents_list="${agents_list}$id "
  done
  agents_json="[${agents_json%, }]"
  agents_list="${agents_list% }"

  if [ "$json" = true ]; then
    cat <<JSON
{
  "name": "dotcontext",
  "version": "$VERSION",
  "repo": "$REPO",
  "commands": ["init", "update", "doctor", "completion"],
  "capabilities": {
    "update_check": true,
    "askuserquestion": true,
    "statusline": true,
    "hooks": true,
    "skills": true,
    "commands": true,
    "multiagent": true,
    "agents": $agents_json
  }
}
JSON
    return 0
  fi

  echo "dotcontext $VERSION"
  if [ "$features" = true ]; then
    echo ""
    echo "Capabilities:"
    printf "  %-16s %s\n" "update_check"    "yes"
    printf "  %-16s %s\n" "askuserquestion" "yes"
    printf "  %-16s %s\n" "statusline"      "yes"
    printf "  %-16s %s\n" "hooks"           "yes"
    printf "  %-16s %s\n" "skills"          "yes"
    printf "  %-16s %s\n" "commands"        "yes"
    printf "  %-16s %s\n" "multiagent"      "yes"
    printf "  %-16s %s\n" "agents"          "$agents_list"
  fi
}
# ── Command: completion ───────────────────────────────────────────────────────

cmd_completion() {
  local shell="${1:-}"
  if [ -z "$shell" ]; then
    if [ -n "$ZSH_VERSION" ]; then
      shell="zsh"
    else
      shell="bash"
    fi
  fi

  case "$shell" in
    bash)
      cat << 'BASH_COMP'
_dotcontext() {
  local cur prev commands
  COMPREPLY=()
  cur="${COMP_WORDS[COMP_CWORD]}"
  prev="${COMP_WORDS[COMP_CWORD-1]}"
  commands="init update doctor completion"

  case "$prev" in
    dotcontext)
      COMPREPLY=( $(compgen -W "$commands --help --version" -- "$cur") )
      return 0
      ;;
    init)
      COMPREPLY=( $(compgen -W "--name -n --agents --yes -y --no-setup" -- "$cur") )
      return 0
      ;;
    update)
      COMPREPLY=( $(compgen -W "--cli --templates --yes -y --dry-run" -- "$cur") )
      return 0
      ;;
    completion)
      COMPREPLY=( $(compgen -W "bash zsh" -- "$cur") )
      return 0
      ;;
  esac

  COMPREPLY=( $(compgen -W "$commands --help --version" -- "$cur") )
}
complete -F _dotcontext dotcontext
BASH_COMP
      ;;
    zsh)
      cat << 'ZSH_COMP'
#compdef dotcontext

_dotcontext() {
  local -a commands
  commands=(
    'init:Initialize .context structure + open Claude Code'
    'update:Update CLI and/or templates'
    'doctor:Check project setup health'
    'completion:Generate shell tab completions'
  )

  _arguments -C \
    '1:command:->command' \
    '*::arg:->args'

  case "$state" in
    command)
      _describe 'command' commands
      _arguments \
        '--help[Show help]' \
        '-h[Show help]' \
        '--version[Show version]' \
        '-v[Show version]'
      ;;
    args)
      case "${words[1]}" in
        init)
          _arguments \
            '--name[Project name]:name:' \
            '-n[Project name]:name:' \
            '--agents[Harnesses to set up, comma-separated]:agents:' \
            '--yes[Skip prompts]' \
            '-y[Skip prompts]' \
            '--no-setup[Skip automatic /setup-context]'
          ;;
        update)
          _arguments \
            '--cli[Only update CLI]' \
            '--templates[Only update templates]' \
            '--yes[Update without asking]' \
            '-y[Update without asking]' \
            '--dry-run[Show what would change]'
          ;;
        completion)
          _arguments '1:shell:(bash zsh)'
          ;;
      esac
      ;;
  esac
}

compdef _dotcontext dotcontext
ZSH_COMP
      ;;
    *)
      print_red "Unknown shell: $shell (supported: bash, zsh)"
      return 1
      ;;
  esac
}

# Offer to wire shell completion into the user's profile (called from init).
# No-ops for unknown shells, when dotcontext isn't on PATH, when already
# installed, or when declined.
offer_completion_install() {
  local shell profile line

  case "$(basename "${SHELL:-bash}")" in
    zsh)
      shell="zsh"
      profile="${ZDOTDIR:-$HOME}/.zshrc"
      ;;
    bash)
      shell="bash"
      # macOS interactive bash reads ~/.bash_profile; Linux reads ~/.bashrc.
      if [ -f "$HOME/.bashrc" ]; then
        profile="$HOME/.bashrc"
      elif [ "$(uname)" = "Darwin" ]; then
        profile="$HOME/.bash_profile"
      else
        profile="$HOME/.bashrc"
      fi
      ;;
    *) return 0 ;;
  esac

  # Only offer when dotcontext is actually on PATH — otherwise the line would
  # just print "command not found" in every new shell.
  command -v dotcontext >/dev/null 2>&1 || return 0

  # Self-guard the persisted line so it stays harmless if dotcontext later
  # leaves PATH (uninstalled, moved, etc.).
  line="command -v dotcontext >/dev/null 2>&1 && eval \"\$(dotcontext completion $shell)\""

  if [ -f "$profile" ] && grep -qF "dotcontext completion" "$profile" 2>/dev/null; then
    return 0
  fi

  echo ""
  if confirm "  Install $shell tab-completion to ${profile/#$HOME/~}?"; then
    printf '\n# dotcontext completion\n%s\n' "$line" >> "$profile"
    print_gray "  added — restart your shell or run: source ${profile/#$HOME/~}"
  fi
}
# ── Main Routing ──────────────────────────────────────────────────────────────

case "${1:-}" in
  init) shift; cmd_init "$@" ;;
  update) shift; cmd_update "$@" ;;
  doctor) cmd_doctor ;;
  completion) shift; cmd_completion "$@" ;;
  --version|-v) shift; cmd_version "$@" ;;
  --help|-h|"") cmd_help ;;
  *) print_red "Unknown command: $1. Run 'dotcontext --help' for usage."; exit 1 ;;
esac