@arthai/agents 1.0.0

package/install.sh

@@ -0,0 +1,3185 @@
+#!/bin/bash
+# Claude Agents — Symlink Install System
+#
+# Installs portable agents, skills, and hooks into any project's .claude/
+# directory using symlinks. Changes to the repo propagate automatically.
+#
+# Usage:
+#   install.sh [path]                Sync symlinks into project (auto-detects setup needs)
+#   install.sh --setup [path]        Interactive setup (pick categories, configure hooks)
+#   install.sh --uninstall [path]    Clean uninstall (restore everything)
+#   install.sh --sync-from-config [path]  Sync only configured categories (used by hook)
+#   install.sh --init [path]         Scaffold + sync (greenfield)
+#   install.sh --convert [path]      One-time migration: replace matching copies with symlinks
+#   install.sh --assess [path]       Brownfield assessment (read-only, no license needed)
+#   install.sh --upgrade [path]      Brownfield upgrade (converts stale/identical to symlinks)
+#   install.sh --generate-config [path]  Generate config from existing .claude/ contents
+#   install.sh --status [path]       Show symlink status report
+#   install.sh --key KEY             Store license key
+#   install.sh --railway             Include Railway sub-skills
+#   install.sh --categories cat1,cat2  Install specific categories (non-interactive)
+#   install.sh --json-output         Emit JSON summary on completion
+#   install.sh --check-license-only  Validate license and exit (used by sync hook)
+#   install.sh --help                Show help
+
+set -euo pipefail
+
+# CLAUDE_AGENTS_TOOLKIT_DIR can override SCRIPT_DIR (used by test harness in CI
+# where ~/.claude-agents is a symlink and BASH_SOURCE resolves to physical path)
+SCRIPT_DIR="${CLAUDE_AGENTS_TOOLKIT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
+MANIFEST="$SCRIPT_DIR/portable.manifest"
+LICENSE_FILE="$SCRIPT_DIR/.license"
+AUTHORIZED_KEYS="$SCRIPT_DIR/authorized-keys.txt"
+
+# Config & backup constants
+CONFIG_NAME=".claude-agents.conf"
+BACKUP_DIR_NAME=".claude-agents-backup"
+GITIGNORE_MARKER_START="# >>> claude-agents managed (DO NOT EDIT THIS BLOCK) >>>"
+GITIGNORE_MARKER_END="# <<< claude-agents managed <<<"
+CLAUDEMD_MARKER_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+CLAUDEMD_MARKER_END="<!-- <<< claude-agents toolkit <<< -->"
+CLAUDEMD_MANAGED_TEMPLATE="$SCRIPT_DIR/templates/CLAUDE.md.managed-block"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m' # No Color
+
+# Counters
+CREATED=0
+UPDATED=0
+SKIPPED=0
+CONVERTED=0
+UPGRADED=0
+ERRORS=0
+REMOVED=0
+KEPT=0
+STALE_DEFERRED=()
+SKIP_ITEMS=""
+FORCE_YES=false
+
+# ============================================================================
+# License Validation
+# ============================================================================
+
+check_license() {
+    if [ ! -f "$LICENSE_FILE" ]; then
+        echo -e "${RED}No license key found.${NC}"
+        echo "Run: $0 --key YOUR_KEY"
+        echo ""
+        echo "Get a license key at https://github.com/ArthTech-AI/claude-agents or contact support."
+        exit 1
+    fi
+
+    local key
+    key=$(cat "$LICENSE_FILE")
+
+    # Validate key format: ARTH-XXXX-XXXX-XXXX-XXXX
+    if ! echo "$key" | grep -qE '^ARTH-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$'; then
+        echo -e "${RED}Invalid license key format.${NC} Expected: ARTH-XXXX-XXXX-XXXX-XXXX"
+        exit 1
+    fi
+
+    # Phase 1: Check against local hashed allowlist
+    if [ ! -f "$AUTHORIZED_KEYS" ]; then
+        echo -e "${RED}Authorization file missing.${NC} Re-clone the repo."
+        exit 1
+    fi
+
+    local key_hash
+    key_hash=$(echo -n "$key" | shasum -a 256 | awk '{print $1}')
+
+    if ! grep -v '^#' "$AUTHORIZED_KEYS" | grep -q "$key_hash"; then
+        echo -e "${RED}Invalid license key.${NC} Contact support."
+        exit 1
+    fi
+}
+
+# ============================================================================
+# Category Definitions
+# ============================================================================
+# Maps categories to their manifest entry paths.
+# Categories: core, agents, skills, hooks, railway
+
+get_category_items() {
+    case "$1" in
+        core)
+            echo "agents/explore-light.md skills/sync skills/scan skills/calibrate hooks/sync-agents.sh"
+            ;;
+        strategy)
+            echo "agents/architect.md agents/code-reviewer.md agents/design-studio-create.md agents/design-studio-critique.md agents/design-studio-think.md agents/gtm-expert.md agents/product-manager.md agents/stakeholder-reporter.md agents/meeting-prep.md agents/content-strategist.md agents/user-researcher.md agents/competitive-analyst.md"
+            ;;
+        development)
+            echo "agents/frontend.md agents/python-backend.md agents/ops.md skills/planning skills/implement skills/fix skills/pr skills/precheck skills/review-pr skills/issue"
+            ;;
+        quality)
+            echo "agents/qa.md agents/qa-e2e.md agents/qa-challenger.md agents/qa-test-promoter.md agents/qa-baseline-updater.md agents/qa-domain.md skills/qa skills/ci-fix skills/qa-incident skills/qa-learn"
+            ;;
+        operations)
+            echo "agents/sre.md agents/setup.md skills/sre skills/incident skills/setup skills/restart skills/discord-ops skills/arth skills/custom-domain"
+            ;;
+        hooks)
+            echo "hooks/triage-router.sh hooks/session-end.sh"
+            ;;
+        guardrails)
+            echo "hooks/session-bootstrap.sh hooks/pre-bash-guard.sh hooks/pre-task-context.sh hooks/pre-edit-guard.sh hooks/post-test-summary.sh hooks/post-edit-lint.sh hooks/post-deploy-health.sh hooks/post-diff-test-compare.sh hooks/post-git-state.sh hooks/post-merge-cleanup.sh skills/onboard skills/welcome skills/share skills/templates skills/wizard skills/autopilot skills/continue"
+            ;;
+        railway)
+            echo "skills/railway/central-station skills/railway/database skills/railway/deploy skills/railway/deployment skills/railway/domain skills/railway/environment skills/railway/metrics skills/railway/new skills/railway/projects skills/railway/railway-docs skills/railway/service skills/railway/status skills/railway/templates"
+            ;;
+        superpowers)
+            echo "skills/superpowers skills/explore.md"
+            ;;
+        consulting)
+            echo "agents/ai-consultant.md skills/consulting skills/client-discovery skills/opportunity-map skills/pitch-generator skills/roi-calculator skills/market-research skills/solution-architect skills/deliverable-builder skills/engagement-tracker hooks/ensure-client-dir.sh hooks/check-deliverable.sh hooks/session-summary.sh"
+            ;;
+    esac
+}
+
+get_category_label() {
+    case "$1" in
+        core)        echo "Core (required)" ;;
+        strategy)    echo "Strategy & Design (12 agents)" ;;
+        development) echo "Development (3 agents, 6 skills)" ;;
+        quality)     echo "Quality Assurance (6 agents, 4 skills)" ;;
+        operations)  echo "Operations (2 agents, 5 skills)" ;;
+        hooks)       echo "Hooks (3)" ;;
+        guardrails)  echo "Guardrails (8 hooks, 7 skills)" ;;
+        railway)     echo "Railway (13 skills, 1 hook)" ;;
+        superpowers) echo "Superpowers (2 skills)" ;;
+        consulting)  echo "Consulting (1 agent, 9 skills, 3 hooks)" ;;
+    esac
+}
+
+get_category_desc() {
+    case "$1" in
+        core)        echo "Sync, codebase scanner, exploration, auto-update hook" ;;
+        strategy)    echo "Architect, code-review, design-studio, PM, GTM, competitive-analyst, stakeholder-reporter, meeting-prep, content-strategist, user-researcher agents" ;;
+        development) echo "Frontend, backend, ops agents + planning, implement, fix, PR, review-pr, issue skills" ;;
+        quality)     echo "QA orchestrator, E2E, challenger, promoter, baseline, domain + QA skills" ;;
+        operations)  echo "SRE + setup agents, SRE, setup, restart, discord-ops, arth, custom-domain skills" ;;
+        hooks)       echo "Triage router (cost delegation) + git worktree sync + session-end memory" ;;
+        guardrails)  echo "Safety guards, auto-lint, test summaries, deploy checks, onboard, welcome, share, templates, wizard, autopilot, continue" ;;
+        railway)     echo "Railway deployment skills (deploy, database, domain, etc.)" ;;
+        superpowers) echo "Superpowers + deep explore skills" ;;
+        consulting)  echo "AI consulting agent, client discovery, opportunity mapping, pitch generation, ROI calculator" ;;
+    esac
+}
+
+get_category_default() {
+    case "$1" in
+        guardrails)  echo "1" ;;
+        railway)     echo "0" ;;
+        superpowers) echo "0" ;;
+        consulting)  echo "0" ;;
+        *)           echo "1" ;;
+    esac
+}
+
+# Returns the settings.json hook names that correspond to a category
+get_category_hooks() {
+    case "$1" in
+        core)       echo "sync-agents" ;;
+        hooks)      echo "triage-router session-end" ;;
+        guardrails) echo "session-bootstrap pre-bash-guard pre-task-context pre-edit-guard pre-write-guard post-test-summary post-edit-lint post-deploy-health post-diff-test-compare post-merge-cleanup" ;;
+        *)          echo "" ;;
+    esac
+}
+
+# Build combined item list for a space-separated list of categories
+items_for_categories() {
+    local categories="$1"
+    local all_items=""
+    for cat in $categories; do
+        local items
+        items=$(get_category_items "$cat")
+        all_items="$all_items $items"
+    done
+    echo "$all_items" | sed 's/^ *//' | sed 's/ *$//'
+}
+
+# Build combined settings hook list for categories
+hooks_for_categories() {
+    local categories="$1"
+    local all_hooks=""
+    for cat in $categories; do
+        local h
+        h=$(get_category_hooks "$cat")
+        if [ -n "$h" ]; then
+            all_hooks="$all_hooks $h"
+        fi
+    done
+    echo "$all_hooks" | sed 's/^ *//' | sed 's/ *$//'
+}
+
+# ============================================================================
+# Config System
+# ============================================================================
+
+config_path() {
+    echo "$1/.claude/$CONFIG_NAME"
+}
+
+config_exists() {
+    [ -f "$(config_path "$1")" ]
+}
+
+# Sources config into CONF_* variables
+load_config() {
+    local conf_file
+    conf_file=$(config_path "$1")
+    if [ ! -f "$conf_file" ]; then
+        return 1
+    fi
+    # Source the file — sets INSTALLED_CATEGORIES, INSTALLED_AGENTS, etc.
+    # shellcheck disable=SC1090
+    . "$conf_file"
+    # Export as CONF_ prefixed for clarity
+    CONF_INSTALLED_CATEGORIES="${INSTALLED_CATEGORIES:-}"
+    CONF_INSTALLED_AGENTS="${INSTALLED_AGENTS:-}"
+    CONF_INSTALLED_SKILLS="${INSTALLED_SKILLS:-}"
+    CONF_INSTALLED_HOOKS="${INSTALLED_HOOKS:-}"
+    CONF_INSTALLED_RAILWAY="${INSTALLED_RAILWAY:-}"
+    CONF_SETTINGS_HOOKS_ADDED="${SETTINGS_HOOKS_ADDED:-}"
+    CONF_BACKUP_EXISTS="${BACKUP_EXISTS:-false}"
+}
+
+write_config() {
+    local target_dir="$1"
+    local categories="$2"  # space-separated
+    local conf_file
+    conf_file=$(config_path "$target_dir")
+
+    # Derive individual lists from categories
+    local agents="" skills="" hooks_list="" railway=""
+    for cat in $categories; do
+        local items
+        items=$(get_category_items "$cat")
+        for item in $items; do
+            local bname
+            bname=$(basename "$item")
+            bname="${bname%.md}"
+            bname="${bname%.sh}"
+            case "$item" in
+                agents/*)
+                    agents="$agents $bname"
+                    ;;
+                skills/railway/*)
+                    railway="$railway $bname"
+                    ;;
+                skills/*)
+                    skills="$skills $bname"
+                    ;;
+                hooks/*)
+                    hooks_list="$hooks_list $bname"
+                    ;;
+            esac
+        done
+    done
+
+    # Trim leading spaces
+    agents="${agents# }"
+    skills="${skills# }"
+    hooks_list="${hooks_list# }"
+    railway="${railway# }"
+
+    # Settings hooks we manage
+    local settings_hooks
+    settings_hooks=$(hooks_for_categories "$categories")
+
+    # Backup status
+    local backup_exists="false"
+    if [ -d "$target_dir/.claude/$BACKUP_DIR_NAME" ]; then
+        backup_exists="true"
+    fi
+
+    cat > "$conf_file" << CONFEOF
+# claude-agents project config — generated by install.sh
+# Re-run: install.sh --setup $(basename "$target_dir")
+INSTALLED_CATEGORIES="$categories"
+INSTALLED_AGENTS="$agents"
+INSTALLED_SKILLS="$skills"
+INSTALLED_HOOKS="$hooks_list"
+INSTALLED_RAILWAY="$railway"
+INSTALLED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+SETTINGS_HOOKS_ADDED="$settings_hooks"
+BACKUP_EXISTS=$backup_exists
+CONFEOF
+}
+
+# ============================================================================
+# JSON Output
+# ============================================================================
+
+emit_json_summary() {
+    local mode="${1:-sync}"
+    local target="${2:-}"
+    local conf_file
+    conf_file=$(config_path "$target")
+    local categories=""
+    if config_exists "$target"; then
+        load_config "$target"
+        categories="${CONF_INSTALLED_CATEGORIES:-}"
+    fi
+    printf '{"status":"success","mode":"%s","target":"%s","stats":{"created":%d,"updated":%d,"skipped":%d,"errors":%d},"categories":"%s","configPath":"%s"}\n' \
+        "$mode" "$target" "$CREATED" "$UPDATED" "$SKIPPED" "$ERRORS" "$categories" "$conf_file"
+}
+
+# ============================================================================
+# Backup System
+# ============================================================================
+
+backup_dir() {
+    echo "$1/.claude/$BACKUP_DIR_NAME"
+}
+
+# Create backup snapshot — only on FIRST install (or if backup dir is missing)
+snapshot_pre_install() {
+    local target_dir="$1"
+    local bdir
+    bdir=$(backup_dir "$target_dir")
+
+    if [ -d "$bdir" ]; then
+        return 0  # Backup already exists, don't overwrite
+    fi
+
+    mkdir -p "$bdir"
+
+    # Back up settings.json if it exists
+    if [ -f "$target_dir/.claude/settings.json" ]; then
+        cp "$target_dir/.claude/settings.json" "$bdir/settings.json.bak"
+    fi
+
+    # Back up .gitignore if it exists
+    if [ -f "$target_dir/.claude/.gitignore" ]; then
+        cp "$target_dir/.claude/.gitignore" "$bdir/gitignore.bak"
+    fi
+
+    echo -e "  ${DIM}Backup created at .claude/$BACKUP_DIR_NAME/${NC}" >&2
+}
+
+# Record all symlinks we created (written AFTER install completes)
+post_install_record() {
+    local target_dir="$1"
+    local bdir
+    bdir=$(backup_dir "$target_dir")
+    mkdir -p "$bdir"
+
+    local manifest_file="$bdir/manifest.txt"
+    : > "$manifest_file"  # Truncate
+
+    # Walk .claude/ for symlinks pointing to our repo
+    for subdir in agents skills hooks; do
+        local search_dir="$target_dir/.claude/$subdir"
+        [ ! -d "$search_dir" ] && continue
+
+        # Find symlinks (non-recursive for agents/hooks, handle skill subdirs)
+        for item in "$search_dir"/*; do
+            [ ! -e "$item" ] && [ ! -L "$item" ] && continue
+            if [ -L "$item" ]; then
+                local link_target
+                link_target=$(readlink "$item" 2>/dev/null || true)
+                if echo "$link_target" | grep -q "/.claude-agents/"; then
+                    echo "$item" >> "$manifest_file"
+                fi
+            fi
+        done
+    done
+}
+
+# ============================================================================
+# Settings.json Merge (Phase 3)
+# ============================================================================
+# Uses embedded Python3 for safe JSON manipulation.
+# Adds/removes hook entries without touching other settings.
+
+merge_settings_hooks() {
+    local settings_file="$1"
+    local action="$2"       # "add" or "remove"
+    local hooks_str="$3"    # space-separated hook names: "sync-agents triage-router"
+
+    if [ -z "$hooks_str" ]; then
+        return 0
+    fi
+
+    if ! command -v python3 &>/dev/null; then
+        echo -e "${YELLOW}Warning: python3 not found. Cannot auto-merge hooks into settings.json.${NC}" >&2
+        echo -e "Please manually add/remove hooks in $settings_file" >&2
+        return 1
+    fi
+
+    python3 - "$settings_file" "$action" "$hooks_str" "$SCRIPT_DIR" <<'PYEOF'
+import json, sys, os
+
+settings_file = sys.argv[1]
+action = sys.argv[2]
+hooks_to_process = sys.argv[3].split()
+script_dir = sys.argv[4] if len(sys.argv) > 4 else os.path.dirname(os.path.abspath(__file__))
+
+# Load hook definitions from hook-defs.json (single source of truth)
+# Translates entries-array format into the flat per-matcher HOOK_DEFS dict
+# that install.sh's settings merge logic expects.
+hook_defs_path = os.path.join(script_dir, "hook-defs.json")
+_raw_defs = {}
+if os.path.exists(hook_defs_path):
+    with open(hook_defs_path) as _f:
+        _raw_defs = json.load(_f)
+
+HOOK_DEFS = {}
+for _name, _defn in _raw_defs.items():
+    _script = _defn["script"]
+    _entries = _defn["entries"]
+    if _name == "sync-agents":
+        # sync-agents uses a special command_override (not $CLAUDE_PROJECT_DIR path)
+        _entry0 = _entries[0]
+        _cmd = _entry0.get("command_override",
+               "bash -c 'export HOME=$(eval echo ~$(id -un)); [ -x \"$HOME/.claude-agents/hooks/sync-agents.sh\" ] && \"$HOME/.claude-agents/hooks/sync-agents.sh\" || true'")
+        HOOK_DEFS["sync-agents"] = {
+            "event": _entry0["event"],
+            "entry": {"matcher": _entry0["matcher"], "hooks": [{"type": "command", "command": _cmd, "timeout": _entry0["timeout"]}]},
+            "fingerprint": _script,
+        }
+    elif len(_entries) == 1:
+        _e = _entries[0]
+        HOOK_DEFS[_name] = {
+            "event": _e["event"],
+            "entry": {"matcher": _e["matcher"], "hooks": [{"type": "command", "command": f"$CLAUDE_PROJECT_DIR/.claude/hooks/{_script}", "timeout": _e["timeout"]}]},
+            "fingerprint": _script,
+        }
+    else:
+        # Multi-entry hook (e.g. pre-edit-guard fires on both Edit and Write).
+        # Expand into separate HOOK_DEFS keys so each matcher gets its own entry.
+        for _i, _e in enumerate(_entries):
+            _key = _name if _i == 0 else f"{_name.rsplit('-', 1)[0]}-write-guard" if _e["matcher"] == "Write" else f"{_name}-{_i}"
+            HOOK_DEFS[_key] = {
+                "event": _e["event"],
+                "entry": {"matcher": _e["matcher"], "hooks": [{"type": "command", "command": f"$CLAUDE_PROJECT_DIR/.claude/hooks/{_script}", "timeout": _e["timeout"]}]},
+                "fingerprint": _script,
+            }
+
+# Fallback: if hook-defs.json missing, keep hardcoded sync-agents for safety
+if not HOOK_DEFS:
+    HOOK_DEFS = {
+        "sync-agents": {
+            "event": "SessionStart",
+            "entry": {"matcher": "", "hooks": [{"type": "command", "command": "bash -c 'export HOME=$(eval echo ~$(id -un)); [ -x \"$HOME/.claude-agents/hooks/sync-agents.sh\" ] && \"$HOME/.claude-agents/hooks/sync-agents.sh\" || true'", "timeout": 30}]},
+            "fingerprint": "sync-agents.sh",
+        }
+    }
+
+# Read or create settings
+if os.path.exists(settings_file):
+    with open(settings_file) as f:
+        try:
+            settings = json.load(f)
+        except json.JSONDecodeError:
+            settings = {}
+else:
+    settings = {}
+
+if "hooks" not in settings:
+    settings["hooks"] = {}
+
+for hook_name in hooks_to_process:
+    if hook_name not in HOOK_DEFS:
+        continue
+    defn = HOOK_DEFS[hook_name]
+    event = defn["event"]
+    fingerprint = defn["fingerprint"]
+
+    if action == "add":
+        if event not in settings["hooks"]:
+            settings["hooks"][event] = []
+        # Check if already present (by fingerprint AND matcher to avoid false dedup)
+        entry_matcher = defn["entry"].get("matcher", "")
+        already_present = False
+        for entry in settings["hooks"][event]:
+            if entry.get("matcher", "") != entry_matcher:
+                continue
+            for h in entry.get("hooks", []):
+                if fingerprint in h.get("command", ""):
+                    already_present = True
+                    break
+            if already_present:
+                break
+        if not already_present:
+            settings["hooks"][event].append(defn["entry"])
+
+    elif action == "remove":
+        if event in settings["hooks"]:
+            entry_matcher = defn["entry"].get("matcher", "")
+            settings["hooks"][event] = [
+                entry for entry in settings["hooks"][event]
+                if not (
+                    entry.get("matcher", "") == entry_matcher and
+                    any(fingerprint in h.get("command", "") for h in entry.get("hooks", []))
+                )
+            ]
+            if not settings["hooks"][event]:
+                del settings["hooks"][event]
+
+# Clean up empty hooks dict
+if not settings.get("hooks"):
+    if "hooks" in settings:
+        del settings["hooks"]
+
+with open(settings_file, "w") as f:
+    json.dump(settings, f, indent=2)
+    f.write("\n")
+PYEOF
+}
+
+# ============================================================================
+# Gitignore Management
+# ============================================================================
+# Maintains a marker block in .claude/.gitignore for our symlinks.
+# User entries outside the block are never touched.
+
+update_gitignore_block() {
+    local target_dir="$1"
+    local items="$2"      # space-separated list of manifest entry paths
+    local gitignore="$target_dir/.claude/.gitignore"
+
+    # Build the block content
+    local block=""
+    block="$GITIGNORE_MARKER_START"$'\n'
+
+    for item in $items; do
+        local bname
+        bname=$(basename "$item")
+        case "$item" in
+            agents/*)          block="${block}agents/$bname"$'\n' ;;
+            skills/railway/*)  block="${block}skills/$bname"$'\n' ;;
+            skills/*)          block="${block}skills/$bname"$'\n' ;;
+            hooks/*)           block="${block}hooks/$bname"$'\n' ;;
+        esac
+    done
+
+    # Always gitignore our config and backup
+    block="${block}$CONFIG_NAME"$'\n'
+    block="${block}$BACKUP_DIR_NAME/"$'\n'
+    block="$block$GITIGNORE_MARKER_END"
+
+    if [ -f "$gitignore" ]; then
+        # Remove existing block if present, then append new one
+        local tmp
+        tmp=$(mktemp)
+        local in_block=false
+        while IFS= read -r line; do
+            if [ "$line" = "$GITIGNORE_MARKER_START" ]; then
+                in_block=true
+                continue
+            fi
+            if [ "$line" = "$GITIGNORE_MARKER_END" ]; then
+                in_block=false
+                continue
+            fi
+            if ! $in_block; then
+                echo "$line" >> "$tmp"
+            fi
+        done < "$gitignore"
+        # Append our block
+        echo "" >> "$tmp"
+        echo "$block" >> "$tmp"
+        mv "$tmp" "$gitignore"
+    else
+        # Create new file with just our block
+        echo "$block" > "$gitignore"
+    fi
+}
+
+remove_gitignore_block() {
+    local target_dir="$1"
+    local gitignore="$target_dir/.claude/.gitignore"
+
+    if [ ! -f "$gitignore" ]; then
+        return 0
+    fi
+
+    local tmp
+    tmp=$(mktemp)
+    local in_block=false
+    while IFS= read -r line; do
+        if [ "$line" = "$GITIGNORE_MARKER_START" ]; then
+            in_block=true
+            continue
+        fi
+        if [ "$line" = "$GITIGNORE_MARKER_END" ]; then
+            in_block=false
+            continue
+        fi
+        if ! $in_block; then
+            echo "$line" >> "$tmp"
+        fi
+    done < "$gitignore"
+
+    # Remove trailing blank lines
+    sed -e :a -e '/^[[:space:]]*$/{ $d; N; ba; }' "$tmp" > "$gitignore" 2>/dev/null || mv "$tmp" "$gitignore"
+    rm -f "$tmp"
+
+    # If gitignore is now empty, remove it
+    if [ ! -s "$gitignore" ]; then
+        rm -f "$gitignore"
+    fi
+}
+
+# ============================================================================
+# CLAUDE.md Managed Block (toolkit instructions that auto-update)
+# ============================================================================
+
+update_claudemd_block() {
+    local target_dir="$1"
+    local mode="${2:-silent}"   # "silent" = update existing block only, "ask" = offer to inject
+    local claudemd="$target_dir/CLAUDE.md"
+
+    # No template? Nothing to do.
+    if [ ! -f "$CLAUDEMD_MANAGED_TEMPLATE" ]; then
+        return 0
+    fi
+
+    # No CLAUDE.md? Nothing to do. (--init creates it separately)
+    if [ ! -f "$claudemd" ]; then
+        return 0
+    fi
+
+    # Build the block content (markers + template)
+    local block_content
+    block_content="$CLAUDEMD_MARKER_START"$'\n'
+    block_content+=$(cat "$CLAUDEMD_MANAGED_TEMPLATE")
+    block_content+=$'\n'"$CLAUDEMD_MARKER_END"
+
+    # Check if markers already exist
+    if grep -qF "$CLAUDEMD_MARKER_START" "$claudemd" 2>/dev/null; then
+        # Markers exist — replace the block in-place
+        local tmp
+        tmp=$(mktemp)
+        local in_block=false
+        local replaced=false
+        while IFS= read -r line; do
+            if [ "$line" = "$CLAUDEMD_MARKER_START" ]; then
+                in_block=true
+                if ! $replaced; then
+                    echo "$block_content" >> "$tmp"
+                    replaced=true
+                fi
+                continue
+            fi
+            if $in_block && [ "$line" = "$CLAUDEMD_MARKER_END" ]; then
+                in_block=false
+                continue
+            fi
+            if ! $in_block; then
+                echo "$line" >> "$tmp"
+            fi
+        done < "$claudemd"
+        mv "$tmp" "$claudemd"
+        return 0
+    fi
+
+    # No markers yet — behavior depends on mode
+    if [ "$mode" = "silent" ]; then
+        # Silent mode (sync): don't inject into unmarked files
+        return 0
+    fi
+
+    # Ask mode (upgrade/setup): offer to inject
+    echo ""
+    echo -e "  ${BOLD}CLAUDE.md toolkit instructions:${NC}"
+    echo -e "  Your CLAUDE.md doesn't have toolkit instructions yet."
+    echo -e "  These tell Claude how to use the toolkit (routing, session start, delegation)."
+    echo -e "  They go in a managed block — your content won't be touched."
+    echo ""
+
+    if [ "$FORCE_YES" = "true" ]; then
+        echo -e "  Adding toolkit instructions to CLAUDE.md (--yes)"
+    else
+        echo -n "  Add toolkit instructions to CLAUDE.md? [y/N] "
+        local answer
+        read -r answer < /dev/tty 2>/dev/null || read -r answer
+        case "$answer" in
+            y|Y) ;;
+            *)
+                echo -e "  ${DIM}Skipped — run --upgrade again to add later${NC}"
+                return 0
+                ;;
+        esac
+    fi
+
+    # Inject after the first line (the # heading)
+    local tmp
+    tmp=$(mktemp)
+    local first_line=true
+    while IFS= read -r line; do
+        echo "$line" >> "$tmp"
+        if $first_line; then
+            first_line=false
+            echo "" >> "$tmp"
+            echo "$block_content" >> "$tmp"
+        fi
+    done < "$claudemd"
+    mv "$tmp" "$claudemd"
+    echo -e "  ${GREEN}✓${NC} Added toolkit instructions to CLAUDE.md"
+}
+
+remove_claudemd_block() {
+    local target_dir="$1"
+    local claudemd="$target_dir/CLAUDE.md"
+
+    if [ ! -f "$claudemd" ]; then
+        return 0
+    fi
+
+    # No markers? Nothing to remove.
+    if ! grep -qF "$CLAUDEMD_MARKER_START" "$claudemd" 2>/dev/null; then
+        return 0
+    fi
+
+    local tmp
+    tmp=$(mktemp)
+    local in_block=false
+    local prev_blank=false
+    while IFS= read -r line; do
+        if [ "$line" = "$CLAUDEMD_MARKER_START" ]; then
+            in_block=true
+            continue
+        fi
+        if [ "$line" = "$CLAUDEMD_MARKER_END" ]; then
+            in_block=false
+            # Skip the blank line after the block too
+            prev_blank=true
+            continue
+        fi
+        if ! $in_block; then
+            # Skip one blank line right after block removal
+            if $prev_blank && [ -z "$line" ]; then
+                prev_blank=false
+                continue
+            fi
+            prev_blank=false
+            echo "$line" >> "$tmp"
+        fi
+    done < "$claudemd"
+    mv "$tmp" "$claudemd"
+    echo -e "  CLAUDE.md: ${GREEN}removed toolkit instructions block${NC}"
+}
+
+# ============================================================================
+# Project State Detection
+# ============================================================================
+# Detects the state of the target project to tailor the setup experience.
+# Returns: "greenfield" | "minimal" | "established"
+#
+# greenfield   — no .claude/ dir, or .claude/ exists but is mostly empty
+# minimal      — .claude/ exists with settings.json/CLAUDE.md but few agents/skills
+# established  — .claude/ exists with significant existing agents/skills/hooks
+
+detect_project_state() {
+    local target_dir="$1"
+
+    # No .claude dir at all → greenfield
+    if [ ! -d "$target_dir/.claude" ]; then
+        echo "greenfield"
+        return
+    fi
+
+    # Count existing non-symlink agents, skills, hooks
+    local agent_count=0
+    local skill_count=0
+    local hook_count=0
+
+    if [ -d "$target_dir/.claude/agents" ]; then
+        for f in "$target_dir/.claude/agents"/*.md; do
+            [ ! -f "$f" ] && continue
+            [ -L "$f" ] && continue
+            agent_count=$((agent_count + 1))
+        done
+    fi
+
+    if [ -d "$target_dir/.claude/skills" ]; then
+        for d in "$target_dir/.claude/skills"/*/; do
+            [ ! -d "$d" ] && continue
+            [ -L "${d%/}" ] && continue
+            skill_count=$((skill_count + 1))
+        done
+        # Also count single-file skills
+        for f in "$target_dir/.claude/skills"/*.md; do
+            [ ! -f "$f" ] && continue
+            [ -L "$f" ] && continue
+            skill_count=$((skill_count + 1))
+        done
+    fi
+
+    if [ -d "$target_dir/.claude/hooks" ]; then
+        for f in "$target_dir/.claude/hooks"/*.sh; do
+            [ ! -f "$f" ] && continue
+            [ -L "$f" ] && continue
+            hook_count=$((hook_count + 1))
+        done
+    fi
+
+    local total=$((agent_count + skill_count + hook_count))
+
+    # Has settings.json but very few custom tools → minimal
+    if [ "$total" -le 2 ]; then
+        if [ -f "$target_dir/.claude/settings.json" ] || [ -f "$target_dir/CLAUDE.md" ]; then
+            echo "minimal"
+        else
+            echo "greenfield"
+        fi
+        return
+    fi
+
+    # Significant existing setup
+    echo "established"
+}
+
+# ============================================================================
+# Interactive Menu
+# ============================================================================
+# Pure bash interactive category selector.
+# All UI output goes to stderr; result (selected categories) goes to stdout.
+
+show_interactive_menu() {
+    local target_dir="$1"
+    local preselected="$2"  # space-separated category names, or "" for defaults
+    local project_state="$3"  # greenfield | minimal | established
+
+    local num_categories=9
+    local current=0
+
+    # Category names (indexed array — bash 3+ compatible)
+    # Note: 'consulting' is a hidden category — not shown in menu.
+    # Install via: INSTALLED_CATEGORIES="... consulting" in .claude-agents.conf
+    local cat_names_0="core"
+    local cat_names_1="strategy"
+    local cat_names_2="development"
+    local cat_names_3="quality"
+    local cat_names_4="operations"
+    local cat_names_5="hooks"
+    local cat_names_6="guardrails"
+    local cat_names_7="railway"
+    local cat_names_8="superpowers"
+
+    # Initialize selections from defaults
+    local sel_0=1 sel_1=1 sel_2=1 sel_3=1 sel_4=1 sel_5=1 sel_6=1 sel_7=0 sel_8=0
+
+    # Pre-populate from existing config if provided
+    if [ -n "$preselected" ]; then
+        sel_0=0; sel_1=0; sel_2=0; sel_3=0; sel_4=0; sel_5=0; sel_6=0; sel_7=0; sel_8=0
+        # Hidden categories (consulting) are preserved if already in config
+        local _hidden_cats=""
+        for cat in $preselected; do
+            case "$cat" in
+                core)        sel_0=1 ;;
+                strategy)    sel_1=1 ;;
+                development) sel_2=1 ;;
+                quality)     sel_3=1 ;;
+                operations)  sel_4=1 ;;
+                hooks)       sel_5=1 ;;
+                guardrails)  sel_6=1 ;;
+                railway)     sel_7=1 ;;
+                superpowers) sel_8=1 ;;
+                consulting)  _hidden_cats="$_hidden_cats consulting" ;;
+            esac
+        done
+    fi
+
+    # Hide cursor
+    printf '\033[?25l' >&2
+
+    # Ensure cursor is restored on exit/interrupt
+    trap 'printf "\033[?25h" >&2' EXIT INT TERM
+
+    # Header
+    echo "" >&2
+    echo -e "${BOLD}Claude Agents — Setup${NC}" >&2
+    echo -e "Target: ${CYAN}$target_dir${NC}" >&2
+    echo "" >&2
+
+    # Show project state context
+    case "$project_state" in
+        greenfield)
+            echo -e "${GREEN}Fresh project detected.${NC} We'll set up the full toolkit — agents, skills," >&2
+            echo -e "hooks, and workflows — so Claude Code works optimally from day one." >&2
+            echo "" >&2
+            ;;
+        minimal)
+            echo -e "${CYAN}Existing project with basic Claude Code setup.${NC} We'll add our agents" >&2
+            echo -e "and skills alongside your existing configuration. Your CLAUDE.md and" >&2
+            echo -e "settings stay untouched — we only add, never replace." >&2
+            echo "" >&2
+            # Count and show what they have
+            local their_agents=0 their_skills=0 their_hooks=0
+            if [ -d "$target_dir/.claude/agents" ]; then
+                for f in "$target_dir/.claude/agents"/*.md; do
+                    [ -f "$f" ] && [ ! -L "$f" ] && their_agents=$((their_agents + 1))
+                done
+            fi
+            if [ -d "$target_dir/.claude/skills" ]; then
+                for d in "$target_dir/.claude/skills"/*/; do
+                    [ -d "$d" ] && [ ! -L "${d%/}" ] && their_skills=$((their_skills + 1))
+                done
+            fi
+            if [ -d "$target_dir/.claude/hooks" ]; then
+                for f in "$target_dir/.claude/hooks"/*.sh; do
+                    [ -f "$f" ] && [ ! -L "$f" ] && their_hooks=$((their_hooks + 1))
+                done
+            fi
+            if [ $((their_agents + their_skills + their_hooks)) -gt 0 ]; then
+                echo -e "  ${DIM}Your existing tools: ${their_agents} agents, ${their_skills} skills, ${their_hooks} hooks${NC}" >&2
+                echo -e "  ${DIM}These will be auto-discovered by the triage router and work${NC}" >&2
+                echo -e "  ${DIM}alongside our portable tools — better together.${NC}" >&2
+                echo "" >&2
+            fi
+            ;;
+        established)
+            echo -e "${YELLOW}Established Claude Code project detected.${NC} Your existing agents," >&2
+            echo -e "skills, and hooks are preserved. We symlink our tools alongside yours —" >&2
+            echo -e "the triage router auto-discovers everything and routes optimally." >&2
+            echo "" >&2
+            ;;
+    esac
+
+    echo "Select categories to install (arrows to move, space to toggle, enter to confirm):" >&2
+    echo "" >&2
+
+    while true; do
+        # Render each category line
+        local i=0
+        while [ "$i" -lt "$num_categories" ]; do
+            local prefix="  "
+            if [ "$i" -eq "$current" ]; then
+                prefix="> "
+            fi
+
+            # Get selection state
+            local sel_val=0
+            case "$i" in
+                0) sel_val=$sel_0 ;; 1) sel_val=$sel_1 ;; 2) sel_val=$sel_2 ;;
+                3) sel_val=$sel_3 ;; 4) sel_val=$sel_4 ;; 5) sel_val=$sel_5 ;;
+                6) sel_val=$sel_6 ;; 7) sel_val=$sel_7 ;; 8) sel_val=$sel_8 ;;
+            esac
+
+            local checkbox="[ ]"
+            if [ "$sel_val" -eq 1 ]; then
+                checkbox="[x]"
+            fi
+            # Core is required — show locked indicator
+            if [ "$i" -eq 0 ]; then
+                checkbox="[x]"  # Always checked, cannot toggle
+            fi
+
+            # Get label and description
+            local cat_name=""
+            case "$i" in
+                0) cat_name="core" ;; 1) cat_name="strategy" ;; 2) cat_name="development" ;;
+                3) cat_name="quality" ;; 4) cat_name="operations" ;; 5) cat_name="hooks" ;;
+                6) cat_name="guardrails" ;; 7) cat_name="railway" ;; 8) cat_name="superpowers" ;;
+            esac
+
+            local label desc
+            label=$(get_category_label "$cat_name")
+            desc=$(get_category_desc "$cat_name")
+
+            # Highlight current row
+            if [ "$i" -eq "$current" ]; then
+                printf '\033[K' >&2
+                printf "${BOLD}%s %s %-22s${NC} %s\n" "$prefix" "$checkbox" "$label" "$desc" >&2
+            else
+                printf '\033[K' >&2
+                printf "%s %s %-22s ${DIM}%s${NC}\n" "$prefix" "$checkbox" "$label" "$desc" >&2
+            fi
+
+            i=$((i + 1))
+        done
+
+        # Read key
+        IFS= read -rsn1 key < /dev/tty 2>/dev/null || IFS= read -rsn1 key
+
+        if [ "$key" = $'\x1b' ]; then
+            IFS= read -rsn2 key < /dev/tty 2>/dev/null || IFS= read -rsn2 key
+            case "$key" in
+                '[A')  # Up
+                    current=$(( (current - 1 + num_categories) % num_categories ))
+                    ;;
+                '[B')  # Down
+                    current=$(( (current + 1) % num_categories ))
+                    ;;
+            esac
+        elif [ "$key" = " " ]; then
+            # Toggle selection (core is always-on — cannot be deselected)
+            case "$current" in
+                0) ;; # core is required — no toggle
+                1) sel_1=$(( 1 - sel_1 )) ;; 2) sel_2=$(( 1 - sel_2 )) ;;
+                3) sel_3=$(( 1 - sel_3 )) ;; 4) sel_4=$(( 1 - sel_4 )) ;;
+                5) sel_5=$(( 1 - sel_5 )) ;; 6) sel_6=$(( 1 - sel_6 )) ;;
+                7) sel_7=$(( 1 - sel_7 )) ;; 8) sel_8=$(( 1 - sel_8 )) ;;
+            esac
+        elif [ "$key" = "" ]; then
+            # Enter — confirm
+            break
+        fi
+
+        # Move cursor back up to reprint menu
+        printf '\033[%dA' "$num_categories" >&2
+    done
+
+    # Restore cursor
+    printf '\033[?25h' >&2
+    trap - EXIT INT TERM
+
+    echo "" >&2
+
+    # Build result string (to stdout)
+    local result=""
+    [ "$sel_0" -eq 1 ] && result="$result core"
+    [ "$sel_1" -eq 1 ] && result="$result strategy"
+    [ "$sel_2" -eq 1 ] && result="$result development"
+    [ "$sel_3" -eq 1 ] && result="$result quality"
+    [ "$sel_4" -eq 1 ] && result="$result operations"
+    [ "$sel_5" -eq 1 ] && result="$result hooks"
+    [ "$sel_6" -eq 1 ] && result="$result guardrails"
+    [ "$sel_7" -eq 1 ] && result="$result railway"
+    [ "$sel_8" -eq 1 ] && result="$result superpowers"
+
+    # Re-append hidden categories that were already in config
+    result="$result$_hidden_cats"
+
+    # Trim leading space and output
+    echo "${result# }"
+}
+
+# ============================================================================
+# Symlink Helpers
+# ============================================================================
+
+# safe_symlink: Default mode for daily sync
+# - Symlink exists → update (it's ours)
+# - Regular file exists → SKIP (project override)
+# - Doesn't exist → create symlink
+safe_symlink() {
+    local source="$1"  # Absolute path in repo
+    local target="$2"  # Absolute path in project .claude/
+
+    if [ -L "$target" ]; then
+        # It's a symlink — update it (managed by us)
+        rm "$target"
+        ln -s "$source" "$target"
+        UPDATED=$((UPDATED + 1))
+    elif [ -e "$target" ]; then
+        # Regular file/dir exists — project override, skip
+        SKIPPED=$((SKIPPED + 1))
+    else
+        # Doesn't exist — create symlink
+        local target_dir
+        target_dir=$(dirname "$target")
+        mkdir -p "$target_dir"
+        ln -s "$source" "$target"
+        CREATED=$((CREATED + 1))
+    fi
+}
+
+# convert_to_symlink: One-time migration mode (--convert)
+# - Symlink exists → update
+# - Regular file, matches repo → replace with symlink
+# - Regular file, differs → SKIP + warn (project override)
+# - Doesn't exist → create symlink
+convert_to_symlink() {
+    local source="$1"
+    local target="$2"
+
+    if [ -L "$target" ]; then
+        # Already a symlink — update
+        rm "$target"
+        ln -s "$source" "$target"
+        UPDATED=$((UPDATED + 1))
+    elif [ -d "$target" ] && [ -d "$source" ]; then
+        # Both are directories — compare contents
+        if diff -rq "$source" "$target" >/dev/null 2>&1; then
+            # Contents match — replace with symlink
+            rm -rf "$target"
+            ln -s "$source" "$target"
+            CONVERTED=$((CONVERTED + 1))
+        else
+            # Differs — project override
+            echo -e "  ${YELLOW}OVERRIDE${NC} $(basename "$target") (differs from repo)"
+            SKIPPED=$((SKIPPED + 1))
+        fi
+    elif [ -f "$target" ] && [ -f "$source" ]; then
+        # Both are files — compare
+        if diff -q "$source" "$target" >/dev/null 2>&1; then
+            # Matches — replace with symlink
+            rm "$target"
+            ln -s "$source" "$target"
+            CONVERTED=$((CONVERTED + 1))
+        else
+            # Differs — project override
+            echo -e "  ${YELLOW}OVERRIDE${NC} $(basename "$target") (differs from repo)"
+            SKIPPED=$((SKIPPED + 1))
+        fi
+    elif [ ! -e "$target" ]; then
+        # Doesn't exist — create
+        local target_dir
+        target_dir=$(dirname "$target")
+        mkdir -p "$target_dir"
+        ln -s "$source" "$target"
+        CREATED=$((CREATED + 1))
+    else
+        echo -e "  ${RED}ERROR${NC} $(basename "$target") — unexpected state"
+        ERRORS=$((ERRORS + 1))
+    fi
+}
+
+# ============================================================================
+# Brownfield Assessment Helpers
+# ============================================================================
+
+# get_size: Returns total bytes for a file or directory
+get_size() {
+    local path="$1"
+    if [ -f "$path" ]; then
+        wc -c < "$path" | tr -d ' '
+    elif [ -d "$path" ]; then
+        find "$path" -type f -exec cat {} + 2>/dev/null | wc -c | tr -d ' '
+    else
+        echo "0"
+    fi
+}
+
+# classify_file: Compare a regular file/dir at target to its toolkit source
+# Returns: SYMLINK | MISSING | IDENTICAL | STALE | CUSTOMIZED | MODIFIED
+classify_file() {
+    local source="$1"
+    local target="$2"
+
+    if [ -L "$target" ]; then
+        echo "SYMLINK"
+        return
+    fi
+
+    if [ ! -e "$target" ]; then
+        echo "MISSING"
+        return
+    fi
+
+    # Compare content
+    if [ -d "$source" ] && [ -d "$target" ]; then
+        if diff -rq "$source" "$target" >/dev/null 2>&1; then
+            echo "IDENTICAL"
+            return
+        fi
+    elif [ -f "$source" ] && [ -f "$target" ]; then
+        if diff -q "$source" "$target" >/dev/null 2>&1; then
+            echo "IDENTICAL"
+            return
+        fi
+    fi
+
+    # Size-based classification
+    local source_size target_size
+    source_size=$(get_size "$source")
+    target_size=$(get_size "$target")
+
+    if [ "$source_size" -eq 0 ]; then
+        echo "MODIFIED"
+        return
+    fi
+
+    local ratio=$((target_size * 100 / source_size))
+
+    if [ "$ratio" -lt 70 ]; then
+        echo "STALE"
+    elif [ "$ratio" -gt 150 ]; then
+        echo "CUSTOMIZED"
+    else
+        echo "MODIFIED"
+    fi
+}
+
+# generate_config_from_existing: Scan what exists in .claude/ and derive a config
+# Args: $1=target_dir $2=dry_run (optional, "true" to skip writing)
+# Echoes: space-separated category list
+generate_config_from_existing() {
+    local target_dir="$1"
+    local dry_run="${2:-false}"
+
+    local categories="core"
+
+    local cat_list="strategy development quality operations hooks guardrails railway superpowers"
+    for cat in $cat_list; do
+        local items
+        items=$(get_category_items "$cat")
+        local found=false
+        for item in $items; do
+            local bname target_path
+            bname=$(basename "$item")
+            case "$item" in
+                agents/*)          target_path="$target_dir/.claude/agents/$bname" ;;
+                skills/railway/*)  target_path="$target_dir/.claude/skills/$bname" ;;
+                skills/*)          target_path="$target_dir/.claude/skills/$bname" ;;
+                hooks/*)           target_path="$target_dir/.claude/hooks/$bname" ;;
+                *)                 continue ;;
+            esac
+            if [ -e "$target_path" ] || [ -L "$target_path" ]; then
+                found=true
+                break
+            fi
+        done
+        if $found; then
+            categories="$categories $cat"
+        fi
+    done
+
+    if [ "$dry_run" != "true" ]; then
+        write_config "$target_dir" "$categories"
+    fi
+
+    echo "$categories"
+}
+
+# smart_sync: Enhanced symlink for brownfield upgrades
+# - Symlink → update (same as safe_symlink)
+# - Missing → create symlink (same as safe_symlink)
+# - IDENTICAL regular file → backup + convert to symlink
+# - STALE regular file → backup + convert to symlink + warning
+# - CUSTOMIZED/MODIFIED → skip
+smart_sync() {
+    local source="$1"
+    local target="$2"
+
+    if [ -L "$target" ]; then
+        rm "$target"
+        ln -s "$source" "$target"
+        UPDATED=$((UPDATED + 1))
+        return
+    fi
+
+    if [ ! -e "$target" ]; then
+        local target_parent
+        target_parent=$(dirname "$target")
+        mkdir -p "$target_parent"
+        ln -s "$source" "$target"
+        CREATED=$((CREATED + 1))
+        return
+    fi
+
+    # Regular file/dir exists
+    local bname
+    bname=$(basename "$target")
+
+    # Check --skip list (only for regular files — symlinks still updated, missing still created)
+    if [ -n "$SKIP_ITEMS" ] && echo ",$SKIP_ITEMS," | grep -q ",$bname,"; then
+        SKIPPED=$((SKIPPED + 1))
+        return
+    fi
+
+    # Classify it
+    local classification
+    classification=$(classify_file "$source" "$target")
+
+    # Derive project root from target path (strip /.claude/...)
+    local project_root
+    project_root=$(echo "$target" | sed 's|/.claude/.*||')
+    local bdir
+    bdir=$(backup_dir "$project_root")
+    mkdir -p "$bdir"
+
+    case "$classification" in
+        IDENTICAL)
+            # Backup + convert to symlink
+            cp -a "$target" "$bdir/$bname.pre-upgrade" 2>/dev/null || true
+            if [ -d "$target" ]; then
+                rm -rf "$target"
+            else
+                rm "$target"
+            fi
+            ln -s "$source" "$target"
+            CONVERTED=$((CONVERTED + 1))
+            ;;
+        STALE)
+            # Defer for interactive confirmation (or auto-convert with --yes)
+            STALE_DEFERRED+=("$source|$target|$bname")
+            ;;
+        CUSTOMIZED|MODIFIED)
+            SKIPPED=$((SKIPPED + 1))
+            ;;
+    esac
+}
+
+# do_stale_upgrade: Performs the actual backup + symlink conversion for a stale item
+do_stale_upgrade() {
+    local source="$1" target="$2" name="$3"
+    local project_root
+    project_root=$(echo "$target" | sed 's|/.claude/.*||')
+    local bdir
+    bdir=$(backup_dir "$project_root")
+    mkdir -p "$bdir"
+
+    cp -a "$target" "$bdir/$name.pre-upgrade" 2>/dev/null || true
+    if [ -d "$target" ]; then
+        rm -rf "$target"
+    else
+        rm "$target"
+    fi
+    ln -s "$source" "$target"
+    UPGRADED=$((UPGRADED + 1))
+}
+
+# prompt_stale_conversion: Interactive per-file confirmation for stale items
+prompt_stale_conversion() {
+    local source="$1" target="$2" name="$3"
+    local source_size target_size
+    source_size=$(get_size "$source")
+    target_size=$(get_size "$target")
+    local ratio=0
+    if [ "$source_size" -gt 0 ]; then
+        ratio=$((target_size * 100 / source_size))
+    fi
+
+    echo -e "    ⚠ ${BOLD}$name${NC} (${target_size}B → ${source_size}B toolkit — ${ratio}%)"
+
+    # Show preview of each version
+    local your_line="" toolkit_line=""
+    if [ -f "$target" ]; then
+        your_line=$(head -5 "$target" 2>/dev/null | grep -v '^$' | grep -v '^---$' | head -1 | cut -c1-80)
+    elif [ -d "$target" ]; then
+        your_line="[directory: $(ls "$target" 2>/dev/null | wc -l | tr -d ' ') files]"
+    fi
+    if [ -f "$source" ]; then
+        toolkit_line=$(head -5 "$source" 2>/dev/null | grep -v '^$' | grep -v '^---$' | head -1 | cut -c1-80)
+    elif [ -d "$source" ]; then
+        toolkit_line="[directory: $(ls "$source" 2>/dev/null | wc -l | tr -d ' ') files]"
+    fi
+    echo -e "      ${DIM}Your version:${NC}    $your_line"
+    echo -e "      ${DIM}Toolkit version:${NC} $toolkit_line"
+
+    while true; do
+        if [ "$FORCE_YES" = "true" ]; then
+            echo -e "      Replace with toolkit version? [y/N/d(diff)] ${GREEN}y${NC} (--yes)"
+            do_stale_upgrade "$source" "$target" "$name"
+            echo -e "      ${GREEN}✓ Upgraded${NC} $name"
+            return
+        fi
+        printf "      Replace with toolkit version? [y/N/d(diff)] " >&2
+        read -r answer < /dev/tty 2>/dev/null || read -r answer
+        case "$answer" in
+            y|Y)
+                do_stale_upgrade "$source" "$target" "$name"
+                echo -e "      ${GREEN}✓ Upgraded${NC} $name"
+                return
+                ;;
+            d|D)
+                echo ""
+                if [ -d "$target" ]; then
+                    diff -r "$target" "$source" 2>/dev/null | head -40 || true
+                else
+                    diff "$target" "$source" 2>/dev/null | head -40 || true
+                fi
+                echo -e "      ${DIM}(showing first 40 lines of diff)${NC}"
+                echo ""
+                ;;
+            *)
+                echo -e "      ${CYAN}Kept${NC} your version of $name"
+                KEPT=$((KEPT + 1))
+                return
+                ;;
+        esac
+    done
+}
+
+# ============================================================================
+# Manifest Parsing
+# ============================================================================
+
+# Process entries from the manifest
+# Args: $1=target_dir $2=mode(safe|convert) $3=include_railway(true|false) $4=filter_items(optional)
+# If filter_items is provided (space-separated paths), only those entries are processed.
+# If empty, all entries are processed (with railway controlled by $3).
+process_manifest() {
+    local target_dir="$1"
+    local mode="$2"
+    local include_railway="$3"
+    local filter_items="${4:-}"
+
+    local linker="safe_symlink"
+    if [ "$mode" = "convert" ]; then
+        linker="convert_to_symlink"
+    elif [ "$mode" = "smart" ]; then
+        linker="smart_sync"
+    fi
+
+    while IFS= read -r line; do
+        # Skip comments and empty lines
+        [[ "$line" =~ ^#.*$ ]] && continue
+        [[ -z "$line" ]] && continue
+
+        local entry_type entry_path
+        entry_type=$(echo "$line" | awk '{print $1}')
+        entry_path=$(echo "$line" | awk '{print $2}')
+
+        # Apply filter if provided
+        if [ -n "$filter_items" ]; then
+            local in_filter=false
+            for allowed in $filter_items; do
+                if [ "$entry_path" = "$allowed" ]; then
+                    in_filter=true
+                    break
+                fi
+            done
+            if ! $in_filter; then
+                continue
+            fi
+        else
+            # No filter — use railway flag for backwards compat
+            if [ "$entry_type" = "railway-skill-dir" ] && [ "$include_railway" != "true" ]; then
+                continue
+            fi
+        fi
+
+        local source_abs="$SCRIPT_DIR/$entry_path"
+        local target_abs=""
+
+        case "$entry_type" in
+            agent)
+                local filename
+                filename=$(basename "$entry_path")
+                target_abs="$target_dir/.claude/agents/$filename"
+                ;;
+            skill)
+                local filename
+                filename=$(basename "$entry_path")
+                target_abs="$target_dir/.claude/skills/$filename"
+                ;;
+            skill-dir)
+                local dirname
+                dirname=$(basename "$entry_path")
+                target_abs="$target_dir/.claude/skills/$dirname"
+                ;;
+            hook)
+                local filename
+                filename=$(basename "$entry_path")
+                target_abs="$target_dir/.claude/hooks/$filename"
+                ;;
+            railway-skill-dir)
+                local dirname
+                dirname=$(basename "$entry_path")
+                target_abs="$target_dir/.claude/skills/$dirname"
+                ;;
+            *)
+                echo -e "  ${YELLOW}WARN${NC} Unknown entry type: $entry_type"
+                continue
+                ;;
+        esac
+
+        # Verify source exists
+        if [ ! -e "$source_abs" ]; then
+            echo -e "  ${RED}MISSING${NC} $entry_path (not found in repo)"
+            ERRORS=$((ERRORS + 1))
+            continue
+        fi
+
+        $linker "$source_abs" "$target_abs"
+    done < "$MANIFEST"
+}
+
+# ============================================================================
+# Deselection Handler (Phase 7)
+# ============================================================================
+# Removes items for categories that were previously installed but are now deselected.
+
+remove_category_items() {
+    local target_dir="$1"
+    local category="$2"
+    local items
+    items=$(get_category_items "$category")
+
+    for item in $items; do
+        local target_abs=""
+        local bname
+        bname=$(basename "$item")
+
+        case "$item" in
+            agents/*)          target_abs="$target_dir/.claude/agents/$bname" ;;
+            skills/railway/*)  target_abs="$target_dir/.claude/skills/$bname" ;;
+            skills/*)          target_abs="$target_dir/.claude/skills/$bname" ;;
+            hooks/*)           target_abs="$target_dir/.claude/hooks/$bname" ;;
+        esac
+
+        # Only remove if it's a symlink pointing to our repo
+        if [ -L "$target_abs" ]; then
+            local link_target
+            link_target=$(readlink "$target_abs" 2>/dev/null || true)
+            if echo "$link_target" | grep -q "/.claude-agents/"; then
+                rm "$target_abs"
+                REMOVED=$((REMOVED + 1))
+            fi
+        fi
+    done
+
+    # Remove corresponding hooks from settings.json
+    local hooks_to_remove
+    hooks_to_remove=$(get_category_hooks "$category")
+    if [ -n "$hooks_to_remove" ]; then
+        merge_settings_hooks "$target_dir/.claude/settings.json" "remove" "$hooks_to_remove"
+    fi
+}
+
+handle_deselection() {
+    local target_dir="$1"
+    local old_cats="$2"
+    local new_cats="$3"
+
+    for old_cat in $old_cats; do
+        local still_selected=false
+        for new_cat in $new_cats; do
+            if [ "$old_cat" = "$new_cat" ]; then
+                still_selected=true
+                break
+            fi
+        done
+
+        if ! $still_selected; then
+            echo -e "  Removing ${YELLOW}$old_cat${NC} (deselected)..."
+            remove_category_items "$target_dir" "$old_cat"
+        fi
+    done
+}
+
+# ============================================================================
+# Uninstall Handler (Phase 4)
+# ============================================================================
+
+handle_uninstall() {
+    local target_dir="$1"
+
+    echo -e "${BOLD}Claude Agents — Uninstall${NC}"
+    echo -e "Target: ${CYAN}$target_dir${NC}"
+    echo ""
+
+    local bdir
+    bdir=$(backup_dir "$target_dir")
+    local manifest_file="$bdir/manifest.txt"
+
+    # Count what will be removed
+    local symlink_count=0
+    local preserved_count=0
+
+    if [ -f "$manifest_file" ]; then
+        while IFS= read -r item_path; do
+            [ -z "$item_path" ] && continue
+            if [ -L "$item_path" ]; then
+                local link_target
+                link_target=$(readlink "$item_path" 2>/dev/null || true)
+                if echo "$link_target" | grep -q "/.claude-agents/"; then
+                    symlink_count=$((symlink_count + 1))
+                fi
+            elif [ -e "$item_path" ]; then
+                preserved_count=$((preserved_count + 1))
+            fi
+        done < "$manifest_file"
+    else
+        # No manifest — scan for symlinks
+        for subdir in agents skills hooks; do
+            local search_dir="$target_dir/.claude/$subdir"
+            [ ! -d "$search_dir" ] && continue
+            for item in "$search_dir"/*; do
+                [ ! -e "$item" ] && [ ! -L "$item" ] && continue
+                if [ -L "$item" ]; then
+                    local link_target
+                    link_target=$(readlink "$item" 2>/dev/null || true)
+                    if echo "$link_target" | grep -q "/.claude-agents/"; then
+                        symlink_count=$((symlink_count + 1))
+                    fi
+                fi
+            done
+        done
+    fi
+
+    echo "This will:"
+    echo "  - Remove $symlink_count symlinks managed by claude-agents"
+    if [ "$preserved_count" -gt 0 ]; then
+        echo -e "  - ${GREEN}Preserve $preserved_count project-specific files${NC} (not ours)"
+    fi
+    if [ -f "$bdir/settings.json.bak" ]; then
+        echo "  - Restore settings.json from backup"
+    else
+        echo "  - Remove our hook entries from settings.json"
+    fi
+    if [ -f "$bdir/gitignore.bak" ]; then
+        echo "  - Restore .gitignore from backup"
+    fi
+    echo "  - Remove config and backup files"
+    echo ""
+
+    # Confirm
+    printf "Proceed? [y/N] "
+    local confirm
+    read -r confirm < /dev/tty 2>/dev/null || read -r confirm
+    if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then
+        echo "Aborted."
+        exit 0
+    fi
+
+    echo ""
+
+    # Step 1: Remove symlinks
+    local removed=0
+    local kept=0
+
+    remove_our_symlinks() {
+        local search_path="$1"
+        if [ -L "$search_path" ]; then
+            local lt
+            lt=$(readlink "$search_path" 2>/dev/null || true)
+            if echo "$lt" | grep -q "/.claude-agents/"; then
+                rm "$search_path"
+                removed=$((removed + 1))
+                return
+            fi
+        fi
+        if [ -e "$search_path" ] && [ ! -L "$search_path" ]; then
+            kept=$((kept + 1))
+        fi
+    }
+
+    if [ -f "$manifest_file" ]; then
+        while IFS= read -r item_path; do
+            [ -z "$item_path" ] && continue
+            remove_our_symlinks "$item_path"
+        done < "$manifest_file"
+    else
+        for subdir in agents skills hooks; do
+            local search_dir="$target_dir/.claude/$subdir"
+            [ ! -d "$search_dir" ] && continue
+            for item in "$search_dir"/*; do
+                [ ! -e "$item" ] && [ ! -L "$item" ] && continue
+                remove_our_symlinks "$item"
+            done
+        done
+    fi
+
+    echo -e "  Symlinks removed: ${GREEN}$removed${NC}"
+    if [ "$kept" -gt 0 ]; then
+        echo -e "  Project files preserved: ${GREEN}$kept${NC}"
+    fi
+
+    # Step 2: Restore settings.json
+    if [ -f "$bdir/settings.json.bak" ]; then
+        cp "$bdir/settings.json.bak" "$target_dir/.claude/settings.json"
+        echo -e "  Settings.json: ${GREEN}restored from backup${NC}"
+    elif [ -f "$target_dir/.claude/settings.json" ]; then
+        # No backup — remove our hooks by fingerprint
+        local hooks_to_remove
+        hooks_to_remove=""
+        if config_exists "$target_dir"; then
+            load_config "$target_dir"
+            hooks_to_remove="$CONF_SETTINGS_HOOKS_ADDED"
+        else
+            hooks_to_remove="sync-agents triage-router session-end session-bootstrap pre-bash-guard pre-task-context pre-edit-guard pre-write-guard post-test-summary post-edit-lint post-deploy-health"
+        fi
+        if [ -n "$hooks_to_remove" ]; then
+            merge_settings_hooks "$target_dir/.claude/settings.json" "remove" "$hooks_to_remove"
+            echo -e "  Settings.json: ${GREEN}removed our hook entries${NC}"
+        fi
+    fi
+
+    # Step 3: Restore .gitignore
+    if [ -f "$bdir/gitignore.bak" ]; then
+        cp "$bdir/gitignore.bak" "$target_dir/.claude/.gitignore"
+        echo -e "  .gitignore: ${GREEN}restored from backup${NC}"
+    else
+        remove_gitignore_block "$target_dir"
+        echo -e "  .gitignore: ${GREEN}removed our marker block${NC}"
+    fi
+
+    # Step 3b: Remove CLAUDE.md managed block
+    remove_claudemd_block "$target_dir"
+
+    # Step 4: Remove empty directories
+    for subdir in agents skills hooks; do
+        local dir="$target_dir/.claude/$subdir"
+        if [ -d "$dir" ]; then
+            # Remove if empty (rmdir fails on non-empty, which is what we want)
+            rmdir "$dir" 2>/dev/null && echo -e "  ${DIM}Removed empty .claude/$subdir/${NC}" || true
+        fi
+    done
+
+    # Step 5: Remove our config and backup
+    rm -f "$(config_path "$target_dir")"
+    rm -rf "$bdir"
+
+    echo ""
+    echo -e "${BOLD}Uninstall complete.${NC} Your project is restored to its pre-install state."
+}
+
+# ============================================================================
+# Setup Handler (Phase 2 + 7)
+# ============================================================================
+# Full interactive setup flow: detect state, show menu, install, configure.
+
+handle_setup() {
+    local target_dir="$1"
+
+    # Detect project state
+    local project_state
+    project_state=$(detect_project_state "$target_dir")
+
+    # Load existing config if present (for re-setup)
+    local old_categories=""
+    if config_exists "$target_dir"; then
+        load_config "$target_dir"
+        old_categories="$CONF_INSTALLED_CATEGORIES"
+    fi
+
+    # Show interactive menu
+    local new_categories
+    new_categories=$(show_interactive_menu "$target_dir" "$old_categories" "$project_state")
+
+    if [ -z "$new_categories" ]; then
+        echo -e "${YELLOW}No categories selected. Nothing to install.${NC}"
+        exit 0
+    fi
+
+    echo -e "${BOLD}Claude Agents${NC} — Installing into: ${CYAN}$target_dir${NC}"
+    echo ""
+
+    # Snapshot backup (first time only)
+    snapshot_pre_install "$target_dir"
+
+    # Handle deselections (re-setup only)
+    if [ -n "$old_categories" ]; then
+        handle_deselection "$target_dir" "$old_categories" "$new_categories"
+    fi
+
+    # Build filter list from selected categories
+    local filter_items
+    filter_items=$(items_for_categories "$new_categories")
+
+    # Ensure directories
+    mkdir -p "$target_dir/.claude/agents"
+    mkdir -p "$target_dir/.claude/skills"
+    mkdir -p "$target_dir/.claude/hooks"
+
+    # Process manifest (filtered)
+    echo -e "Mode: ${GREEN}setup${NC} (interactive install)"
+    process_manifest "$target_dir" "safe" "false" "$filter_items"
+
+    # Merge settings.json hooks
+    local hooks_to_add
+    hooks_to_add=$(hooks_for_categories "$new_categories")
+    if [ -n "$hooks_to_add" ]; then
+        merge_settings_hooks "$target_dir/.claude/settings.json" "add" "$hooks_to_add"
+    fi
+
+    # If hooks were deselected, make sure they're removed
+    if [ -n "$old_categories" ]; then
+        local old_hooks new_hooks
+        old_hooks=$(hooks_for_categories "$old_categories")
+        new_hooks=$(hooks_for_categories "$new_categories")
+        for oh in $old_hooks; do
+            local still_needed=false
+            for nh in $new_hooks; do
+                if [ "$oh" = "$nh" ]; then
+                    still_needed=true
+                    break
+                fi
+            done
+            if ! $still_needed; then
+                merge_settings_hooks "$target_dir/.claude/settings.json" "remove" "$oh"
+            fi
+        done
+    fi
+
+    # Update .gitignore marker block
+    update_gitignore_block "$target_dir" "$filter_items"
+
+    # Create CLAUDE.md from template if it doesn't exist (greenfield setup)
+    if [ ! -f "$target_dir/CLAUDE.md" ]; then
+        local project_name
+        project_name=$(basename "$target_dir")
+        sed "s/{{PROJECT_NAME}}/$project_name/g" "$SCRIPT_DIR/templates/CLAUDE.md.template" > "$target_dir/CLAUDE.md"
+        # Inject toolkit managed block into freshly created CLAUDE.md
+        if [ -f "$CLAUDEMD_MANAGED_TEMPLATE" ]; then
+            local tmp block_content
+            tmp=$(mktemp)
+            block_content="$CLAUDEMD_MARKER_START"$'\n'
+            block_content+=$(cat "$CLAUDEMD_MANAGED_TEMPLATE")
+            block_content+=$'\n'"$CLAUDEMD_MARKER_END"
+            local first_line=true
+            while IFS= read -r line; do
+                echo "$line" >> "$tmp"
+                if $first_line; then
+                    first_line=false
+                    echo "" >> "$tmp"
+                    echo "$block_content" >> "$tmp"
+                fi
+            done < "$target_dir/CLAUDE.md"
+            mv "$tmp" "$target_dir/CLAUDE.md"
+        fi
+        echo -e "  ${GREEN}Created${NC} CLAUDE.md (edit the TODOs)"
+    fi
+
+    # Update CLAUDE.md managed block (ask on setup, silent on sync)
+    if [ "$MODE" = "setup" ]; then
+        update_claudemd_block "$target_dir" "ask"
+    else
+        update_claudemd_block "$target_dir" "silent"
+    fi
+
+    # Make hooks executable
+    for hook in "$target_dir/.claude/hooks/"*.sh; do
+        if [ -f "$hook" ] || [ -L "$hook" ]; then
+            chmod +x "$hook" 2>/dev/null || true
+        fi
+    done
+
+    # Write config
+    write_config "$target_dir" "$new_categories"
+
+    # Post-install record (manifest.txt of symlinks)
+    post_install_record "$target_dir"
+
+    # Summary
+    echo ""
+    echo -e "${BOLD}Done!${NC}"
+    echo -e "  Created:   ${GREEN}$CREATED${NC}"
+    echo -e "  Updated:   ${GREEN}$UPDATED${NC}"
+    echo -e "  Skipped:   ${YELLOW}$SKIPPED${NC} (project overrides)"
+    if [ "$REMOVED" -gt 0 ]; then
+        echo -e "  Removed:   ${YELLOW}$REMOVED${NC} (deselected)"
+    fi
+    if [ "$ERRORS" -gt 0 ]; then
+        echo -e "  Errors:    ${RED}$ERRORS${NC}"
+    fi
+
+    # Post-setup guidance based on project state
+    echo ""
+    case "$project_state" in
+        greenfield)
+            echo -e "${BOLD}Your project is ready!${NC} Here's what was set up:"
+            echo ""
+            echo "  Agents:  AI-powered specialists (architect, code-reviewer, design, PM, QA)"
+            echo "  Skills:  Workflow automations (/planning, /implement, /pr, /issue)"
+            echo "  Hooks:   Auto-sync on session start + cost-saving triage router"
+            echo ""
+            echo "Start with:"
+            echo "  - Run ${CYAN}claude${NC} to begin — the triage router auto-delegates to cheap agents"
+            echo "  - Use ${CYAN}/planning <feature>${NC} to plan a feature with a team of agents"
+            echo "  - Use ${CYAN}/pr${NC} to create a PR with automated QA"
+            echo "  - Use ${CYAN}/sync status${NC} to see what's installed"
+            ;;
+        minimal)
+            echo -e "${BOLD}Tools installed alongside your existing setup.${NC}"
+            echo ""
+            echo "  Your existing agents/skills/hooks are auto-discovered by the triage"
+            echo "  router and will be included in routing decisions alongside ours."
+            echo ""
+            echo "  Use ${CYAN}/sync status${NC} to see everything that's linked."
+            echo "  Use ${CYAN}/sync setup${NC} to change your selections later."
+            ;;
+        established)
+            echo -e "${BOLD}Portable tools symlinked — your project files are untouched.${NC}"
+            echo ""
+            echo "  The triage router sees both your tools and ours. Routing is automatic."
+            echo "  Use ${CYAN}/sync status${NC} to review. Use ${CYAN}/sync setup${NC} to adjust."
+            ;;
+    esac
+
+    # Cross-sell clade/arth if available
+    if command -v clade &>/dev/null || command -v arth &>/dev/null; then
+        echo ""
+        echo -e "${BOLD}Also available:${NC}"
+        if command -v clade &>/dev/null; then
+            echo -e "  ${CYAN}clade sync${NC}                Translate toolkit to Cursor/Codex/Kiro/Gemini"
+        fi
+        if command -v arth &>/dev/null; then
+            echo -e "  ${CYAN}arth setup .${NC}             Full setup: toolkit + multi-engine + dashboard"
+        fi
+    fi
+}
+
+# ============================================================================
+# Sync From Config (Phase 6)
+# ============================================================================
+# Silent sync respecting previously configured categories.
+
+handle_sync_from_config() {
+    local target_dir="$1"
+
+    if ! config_exists "$target_dir"; then
+        # No config — fall through to full sync (backwards compat)
+        return 1
+    fi
+
+    load_config "$target_dir"
+
+    local filter_items
+    filter_items=$(items_for_categories "$CONF_INSTALLED_CATEGORIES")
+
+    # Ensure directories
+    mkdir -p "$target_dir/.claude/agents"
+    mkdir -p "$target_dir/.claude/skills"
+    mkdir -p "$target_dir/.claude/hooks"
+
+    echo -e "${BOLD}Claude Agents${NC} — Installing into: ${CYAN}$target_dir${NC}"
+    echo ""
+    echo -e "Mode: ${GREEN}sync${NC} (safe symlinks — won't touch regular files)"
+
+    process_manifest "$target_dir" "safe" "false" "$filter_items"
+
+    # Merge settings.json hooks (ensure all configured hooks are registered)
+    local hooks_to_add
+    hooks_to_add=$(hooks_for_categories "$CONF_INSTALLED_CATEGORIES")
+    if [ -n "$hooks_to_add" ]; then
+        merge_settings_hooks "$target_dir/.claude/settings.json" "add" "$hooks_to_add"
+    fi
+
+    # Update CLAUDE.md managed block (silent — only updates existing markers)
+    update_claudemd_block "$target_dir" "silent"
+
+    # Make hooks executable
+    for hook in "$target_dir/.claude/hooks/"*.sh; do
+        if [ -f "$hook" ] || [ -L "$hook" ]; then
+            chmod +x "$hook" 2>/dev/null || true
+        fi
+    done
+
+    # Update manifest.txt
+    post_install_record "$target_dir"
+
+    # Summary
+    echo ""
+    echo -e "${BOLD}Done!${NC}"
+    echo -e "  Created:   ${GREEN}$CREATED${NC}"
+    echo -e "  Updated:   ${GREEN}$UPDATED${NC}"
+    echo -e "  Skipped:   ${YELLOW}$SKIPPED${NC} (project overrides)"
+    if [ "$ERRORS" -gt 0 ]; then
+        echo -e "  Errors:    ${RED}$ERRORS${NC}"
+    fi
+
+    return 0
+}
+
+# ============================================================================
+# Status Report
+# ============================================================================
+
+show_status() {
+    local target_dir="$1"
+    local include_railway="$2"
+
+    echo -e "${BOLD}Claude Agents — Status Report${NC}"
+    echo -e "Project: ${CYAN}$target_dir${NC}"
+    echo -e "Repo:    ${CYAN}$SCRIPT_DIR${NC}"
+    echo ""
+
+    # Show config info if present
+    if config_exists "$target_dir"; then
+        load_config "$target_dir"
+        echo -e "Config:  ${GREEN}found${NC} (categories: $CONF_INSTALLED_CATEGORIES)"
+        echo ""
+    else
+        echo -e "Config:  ${YELLOW}none${NC} (using full manifest)"
+        echo ""
+    fi
+
+    local linked=0
+    local overridden=0
+    local missing=0
+
+    printf "%-14s %-30s %s\n" "TYPE" "NAME" "STATUS"
+    printf "%-14s %-30s %s\n" "----" "----" "------"
+
+    while IFS= read -r line; do
+        [[ "$line" =~ ^#.*$ ]] && continue
+        [[ -z "$line" ]] && continue
+
+        local entry_type entry_path
+        entry_type=$(echo "$line" | awk '{print $1}')
+        entry_path=$(echo "$line" | awk '{print $2}')
+
+        if [ "$entry_type" = "railway-skill-dir" ] && [ "$include_railway" != "true" ]; then
+            continue
+        fi
+
+        local target_abs=""
+        local display_name
+        display_name=$(basename "$entry_path")
+
+        case "$entry_type" in
+            agent)          target_abs="$target_dir/.claude/agents/$display_name" ;;
+            skill)          target_abs="$target_dir/.claude/skills/$display_name" ;;
+            skill-dir)      target_abs="$target_dir/.claude/skills/$display_name" ;;
+            hook)           target_abs="$target_dir/.claude/hooks/$display_name" ;;
+            railway-skill-dir)
+                entry_type="railway"
+                target_abs="$target_dir/.claude/skills/$display_name"
+                ;;
+        esac
+
+        local status=""
+        if [ -L "$target_abs" ]; then
+            status="${GREEN}symlinked${NC}"
+            linked=$((linked + 1))
+        elif [ -e "$target_abs" ]; then
+            status="${YELLOW}override${NC}"
+            overridden=$((overridden + 1))
+        else
+            status="${RED}missing${NC}"
+            missing=$((missing + 1))
+        fi
+
+        printf "%-14s %-30s " "$entry_type" "$display_name"
+        echo -e "$status"
+    done < "$MANIFEST"
+
+    echo ""
+    echo -e "Symlinked: ${GREEN}$linked${NC}  Overridden: ${YELLOW}$overridden${NC}  Missing: ${RED}$missing${NC}"
+
+    # Show project-specific items (auto-discovered)
+    local project_agents=0
+    local project_skills=0
+    if [ -d "$target_dir/.claude/agents" ]; then
+        for f in "$target_dir/.claude/agents"/*.md; do
+            [ -f "$f" ] && [ ! -L "$f" ] && project_agents=$((project_agents + 1))
+        done
+    fi
+    if [ -d "$target_dir/.claude/skills" ]; then
+        for d in "$target_dir/.claude/skills"/*/; do
+            [ -d "$d" ] && [ ! -L "${d%/}" ] && project_skills=$((project_skills + 1))
+        done
+    fi
+    if [ $((project_agents + project_skills)) -gt 0 ]; then
+        echo ""
+        echo -e "${DIM}Project-specific (auto-discovered by triage router):${NC}"
+        if [ -d "$target_dir/.claude/agents" ]; then
+            for f in "$target_dir/.claude/agents"/*.md; do
+                [ -f "$f" ] && [ ! -L "$f" ] && printf "  %-14s %s\n" "agent" "$(basename "$f")"
+            done
+        fi
+        if [ -d "$target_dir/.claude/skills" ]; then
+            for d in "$target_dir/.claude/skills"/*/; do
+                [ -d "$d" ] && [ ! -L "${d%/}" ] && printf "  %-14s %s\n" "skill" "$(basename "$d")"
+            done
+        fi
+    fi
+
+    # License status
+    echo ""
+    if [ -f "$LICENSE_FILE" ]; then
+        local key
+        key=$(cat "$LICENSE_FILE")
+        local masked="${key:0:9}****-****"
+        echo -e "License: ${GREEN}$masked${NC}"
+    else
+        echo -e "License: ${RED}not configured${NC}"
+    fi
+}
+
+# ============================================================================
+# Scaffold (Greenfield)
+# ============================================================================
+
+scaffold_project() {
+    local target_dir="$1"
+
+    echo -e "${BOLD}Scaffolding new project...${NC}"
+
+    # Create directory structure
+    mkdir -p "$target_dir/.claude/agents"
+    mkdir -p "$target_dir/.claude/skills"
+    mkdir -p "$target_dir/.claude/hooks"
+    mkdir -p "$target_dir/.claude/plans"
+    mkdir -p "$target_dir/.claude/qa-knowledge"
+
+    # Copy settings template if doesn't exist
+    if [ ! -f "$target_dir/.claude/settings.json" ]; then
+        cp "$SCRIPT_DIR/templates/settings.json" "$target_dir/.claude/settings.json"
+        echo -e "  ${GREEN}Created${NC} .claude/settings.json"
+    else
+        echo -e "  ${YELLOW}Exists${NC}  .claude/settings.json"
+    fi
+
+    # Copy CLAUDE.md template if doesn't exist
+    if [ ! -f "$target_dir/CLAUDE.md" ]; then
+        local project_name
+        project_name=$(basename "$target_dir")
+        sed "s/{{PROJECT_NAME}}/$project_name/g" "$SCRIPT_DIR/templates/CLAUDE.md.template" > "$target_dir/CLAUDE.md"
+        # Inject toolkit managed block into freshly created CLAUDE.md
+        if [ -f "$CLAUDEMD_MANAGED_TEMPLATE" ]; then
+            local tmp block_content
+            tmp=$(mktemp)
+            block_content="$CLAUDEMD_MARKER_START"$'\n'
+            block_content+=$(cat "$CLAUDEMD_MANAGED_TEMPLATE")
+            block_content+=$'\n'"$CLAUDEMD_MARKER_END"
+            local first_line=true
+            while IFS= read -r line; do
+                echo "$line" >> "$tmp"
+                if $first_line; then
+                    first_line=false
+                    echo "" >> "$tmp"
+                    echo "$block_content" >> "$tmp"
+                fi
+            done < "$target_dir/CLAUDE.md"
+            mv "$tmp" "$target_dir/CLAUDE.md"
+        fi
+        echo -e "  ${GREEN}Created${NC} CLAUDE.md (edit the TODOs)"
+    else
+        echo -e "  ${YELLOW}Exists${NC}  CLAUDE.md"
+    fi
+
+    # Copy example agents for reference
+    if [ -d "$SCRIPT_DIR/examples/agents" ]; then
+        echo ""
+        echo "Example project-specific agents available at:"
+        echo "  $SCRIPT_DIR/examples/agents/"
+        echo "  Copy any you need to: $target_dir/.claude/agents/"
+    fi
+
+    echo ""
+}
+
+# ============================================================================
+# Brownfield Assessment (--assess)
+# ============================================================================
+
+handle_assess() {
+    local target_dir="$1"
+
+    echo -e "${BOLD}Claude Agents — Brownfield Assessment${NC}"
+    echo -e "Project: ${CYAN}$target_dir${NC}"
+    echo ""
+
+    # Legend
+    echo -e "${BOLD}Legend:${NC}"
+    echo -e "  ✓ ${GREEN}SYMLINK${NC}      Already managed by toolkit. Auto-updated on sync."
+    echo -e "  = ${CYAN}IDENTICAL${NC}    Same content as toolkit. Safe to convert to symlink."
+    echo -e "  ⚠ ${YELLOW}STALE${NC}        Much smaller than toolkit version (<70% size)."
+    echo -e "                  Could be: outdated copy OR completely different file sharing a name."
+    echo -e "  ★ ${BOLD}CUSTOMIZED${NC}   Much larger than toolkit (>150% size). Your project-specific content."
+    echo -e "  ~ ${DIM}MODIFIED${NC}     Similar size but different content. Your edits preserved."
+    echo -e "  ◆ PROJECT-ONLY No toolkit equivalent. Unique to your project."
+    echo ""
+
+    local section_symlinks="" section_identical="" section_stale=""
+    local section_customized="" section_modified="" section_missing=""
+    local count_symlinks=0 count_identical=0 count_stale=0
+    local count_customized=0 count_modified=0 count_missing=0
+    local stale_data=()
+
+    while IFS= read -r line; do
+        [[ "$line" =~ ^#.*$ ]] && continue
+        [[ -z "$line" ]] && continue
+
+        local entry_type entry_path
+        entry_type=$(echo "$line" | awk '{print $1}')
+        entry_path=$(echo "$line" | awk '{print $2}')
+
+        local source_abs="$SCRIPT_DIR/$entry_path"
+        local target_abs=""
+        local display_name
+        display_name=$(basename "$entry_path")
+
+        case "$entry_type" in
+            agent)              target_abs="$target_dir/.claude/agents/$display_name" ;;
+            skill|skill-dir)    target_abs="$target_dir/.claude/skills/$display_name" ;;
+            hook)               target_abs="$target_dir/.claude/hooks/$display_name" ;;
+            railway-skill-dir)  target_abs="$target_dir/.claude/skills/$display_name" ;;
+            *)                  continue ;;
+        esac
+
+        if [ ! -e "$source_abs" ]; then
+            continue
+        fi
+
+        local classification
+        classification=$(classify_file "$source_abs" "$target_abs")
+
+        local source_size target_size
+        source_size=$(get_size "$source_abs")
+        target_size=$(get_size "$target_abs")
+
+        case "$classification" in
+            SYMLINK)
+                local link_target
+                link_target=$(readlink "$target_abs" 2>/dev/null || true)
+                section_symlinks="${section_symlinks}    ✓ $display_name → $link_target\n"
+                count_symlinks=$((count_symlinks + 1))
+                ;;
+            IDENTICAL)
+                section_identical="${section_identical}    = $display_name (${target_size}B = ${source_size}B)\n"
+                count_identical=$((count_identical + 1))
+                ;;
+            STALE)
+                local ratio=$((target_size * 100 / source_size))
+                stale_data+=("$source_abs|$target_abs|$display_name|$source_size|$target_size|$ratio")
+                section_stale="${section_stale}    ⚠ $display_name (${target_size}B vs ${source_size}B toolkit — ${ratio}%)\n"
+                count_stale=$((count_stale + 1))
+                ;;
+            CUSTOMIZED)
+                local ratio=$((target_size * 100 / source_size))
+                section_customized="${section_customized}    ★ $display_name (${target_size}B vs ${source_size}B — ${ratio}%)\n"
+                count_customized=$((count_customized + 1))
+                ;;
+            MODIFIED)
+                local ratio=$((target_size * 100 / source_size))
+                section_modified="${section_modified}    ~ $display_name (${target_size}B vs ${source_size}B — ${ratio}%)\n"
+                count_modified=$((count_modified + 1))
+                ;;
+            MISSING)
+                section_missing="${section_missing}    - $display_name\n"
+                count_missing=$((count_missing + 1))
+                ;;
+        esac
+    done < "$MANIFEST"
+
+    # Display sections
+    if [ $count_symlinks -gt 0 ]; then
+        echo -e "  ${GREEN}SYMLINKS${NC} (managed by toolkit — auto-updated):"
+        echo -e "$section_symlinks"
+    fi
+
+    if [ $count_identical -gt 0 ]; then
+        echo -e "  ${CYAN}IDENTICAL${NC} (can safely convert to symlink):"
+        echo -e "$section_identical"
+    fi
+
+    if [ ${#stale_data[@]} -gt 0 ]; then
+        echo -e "  ${YELLOW}STALE${NC} (recommend upgrade — review diffs below):"
+        for _stale_entry in "${stale_data[@]}"; do
+            IFS='|' read -r _src _tgt _dname _ssize _tsize _ratio <<< "$_stale_entry"
+            echo -e "    ⚠ $_dname (${_tsize}B vs ${_ssize}B toolkit — ${_ratio}%)"
+            # Show preview of first line from each version
+            local _your_preview="" _toolkit_preview=""
+            if [ -f "$_tgt" ]; then
+                _your_preview=$(head -5 "$_tgt" 2>/dev/null | grep -v '^$' | grep -v '^---$' | head -1 | cut -c1-80)
+            elif [ -d "$_tgt" ]; then
+                _your_preview="[directory: $(ls "$_tgt" 2>/dev/null | wc -l | tr -d ' ') files]"
+            fi
+            if [ -f "$_src" ]; then
+                _toolkit_preview=$(head -5 "$_src" 2>/dev/null | grep -v '^$' | grep -v '^---$' | head -1 | cut -c1-80)
+            elif [ -d "$_src" ]; then
+                _toolkit_preview="[directory: $(ls "$_src" 2>/dev/null | wc -l | tr -d ' ') files]"
+            fi
+            echo -e "      ${DIM}--- your version ---${NC}"
+            echo -e "      $_your_preview"
+            echo -e "      ${DIM}--- toolkit version ---${NC}"
+            echo -e "      $_toolkit_preview"
+            echo -e "      ${DIM}→ --upgrade will ASK before converting this file.${NC}"
+            echo ""
+        done
+    fi
+
+    if [ $count_customized -gt 0 ]; then
+        echo -e "  ${BOLD}CUSTOMIZED${NC} (project-specific — will not touch):"
+        echo -e "$section_customized"
+    fi
+
+    if [ $count_modified -gt 0 ]; then
+        echo -e "  ${DIM}MODIFIED${NC} (similar size but different — will not touch):"
+        echo -e "$section_modified"
+    fi
+
+    if [ $count_missing -gt 0 ]; then
+        echo -e "  ${RED}MISSING${NC} (not installed):"
+        echo -e "$section_missing"
+    fi
+
+    # Scan for project-only items (exist in .claude/ but NOT in manifest)
+    local section_project_only=""
+    local count_project_only=0
+    if [ -d "$target_dir/.claude/agents" ]; then
+        for f in "$target_dir/.claude/agents"/*.md; do
+            [ ! -f "$f" ] && continue
+            [ -L "$f" ] && continue
+            local bname
+            bname=$(basename "$f")
+            if ! grep -q "agents/$bname" "$MANIFEST" 2>/dev/null; then
+                section_project_only="${section_project_only}    ◆ agents/$bname\n"
+                count_project_only=$((count_project_only + 1))
+            fi
+        done
+    fi
+    if [ -d "$target_dir/.claude/skills" ]; then
+        for d in "$target_dir/.claude/skills"/*/; do
+            [ ! -d "$d" ] && continue
+            [ -L "${d%/}" ] && continue
+            local bname
+            bname=$(basename "$d")
+            if ! grep -q "skills/$bname" "$MANIFEST" 2>/dev/null; then
+                section_project_only="${section_project_only}    ◆ skills/$bname\n"
+                count_project_only=$((count_project_only + 1))
+            fi
+        done
+    fi
+    if [ -d "$target_dir/.claude/hooks" ]; then
+        for f in "$target_dir/.claude/hooks"/*.sh; do
+            [ ! -f "$f" ] && continue
+            [ -L "$f" ] && continue
+            local bname
+            bname=$(basename "$f")
+            if ! grep -q "hooks/$bname" "$MANIFEST" 2>/dev/null; then
+                section_project_only="${section_project_only}    ◆ hooks/$bname\n"
+                count_project_only=$((count_project_only + 1))
+            fi
+        done
+    fi
+
+    if [ $count_project_only -gt 0 ]; then
+        echo -e "  ${DIM}PROJECT-ONLY${NC} (no toolkit equivalent):"
+        echo -e "$section_project_only"
+    fi
+
+    # Summary box
+    local _skip_count=$((count_customized + count_modified + count_project_only))
+    echo ""
+    echo "─── What --upgrade would do ────────────────────────────────"
+    printf "  Auto-convert:   %3d  (identical files → symlink, backed up)\n" "$count_identical"
+    printf "  Ask you first:  %3d  (stale files — you decide per file)\n" "$count_stale"
+    printf "  Create new:     %3d  (missing toolkit items)\n" "$count_missing"
+    printf "  Skip:           %3d  (modified + customized + project-only)\n" "$_skip_count"
+    echo ""
+    echo -e "  Backups saved to: ${CYAN}.claude/$BACKUP_DIR_NAME/${NC}"
+    echo "  Each converted file gets a .pre-upgrade copy."
+    echo "────────────────────────────────────────────────────────────"
+
+    # Config status
+    if config_exists "$target_dir"; then
+        load_config "$target_dir"
+        echo -e "  CONFIG: ${GREEN}found${NC} (categories: $CONF_INSTALLED_CATEGORIES)"
+    else
+        echo -e "  CONFIG: ${YELLOW}⚠ No .claude-agents.conf found${NC}"
+        local derived
+        derived=$(generate_config_from_existing "$target_dir" "true")
+        if [ -n "$derived" ]; then
+            echo "    → Will generate from existing files"
+            echo "    → Derived categories: $derived"
+        fi
+    fi
+
+    echo ""
+    echo -e "${DIM}Run install.sh --upgrade to apply changes.${NC}"
+    echo -e "${DIM}  Add --yes to auto-approve all stale conversions (CI/non-interactive mode).${NC}"
+    echo -e "${DIM}  Add --skip file1,file2 to exclude specific items.${NC}"
+}
+
+# ============================================================================
+# Brownfield Upgrade (--upgrade)
+# ============================================================================
+
+handle_upgrade() {
+    local target_dir="$1"
+
+    echo -e "${BOLD}Claude Agents — Brownfield Upgrade${NC}"
+    echo -e "Target: ${CYAN}$target_dir${NC}"
+    echo ""
+
+    # Step 1: Assess current state
+    echo -e "${BOLD}Step 1/4:${NC} Assessing current state..."
+
+    # Step 2: Generate config if missing
+    echo -e "${BOLD}Step 2/4:${NC} Generating config..."
+    if ! config_exists "$target_dir"; then
+        local derived_categories
+        derived_categories=$(generate_config_from_existing "$target_dir")
+        echo -e "  Derived categories: ${GREEN}$derived_categories${NC}"
+    else
+        load_config "$target_dir"
+        echo -e "  Using existing config: ${GREEN}$CONF_INSTALLED_CATEGORIES${NC}"
+    fi
+    echo ""
+
+    # Load config (either existing or newly generated)
+    load_config "$target_dir"
+
+    local filter_items
+    filter_items=$(items_for_categories "$CONF_INSTALLED_CATEGORIES")
+
+    # Ensure directories
+    mkdir -p "$target_dir/.claude/agents"
+    mkdir -p "$target_dir/.claude/skills"
+    mkdir -p "$target_dir/.claude/hooks"
+
+    # Snapshot backup
+    snapshot_pre_install "$target_dir"
+
+    # Step 3: Converting files
+    echo -e "${BOLD}Step 3/4:${NC} Converting files..."
+    echo ""
+
+    # Reset deferred stale array
+    STALE_DEFERRED=()
+
+    # Process manifest with smart_sync (identical auto-converts, stale deferred)
+    process_manifest "$target_dir" "smart" "false" "$filter_items"
+
+    # Report auto-converted identical files
+    if [ $CONVERTED -gt 0 ]; then
+        echo -e "  ${CYAN}IDENTICAL files${NC} (auto-converted — content is the same):"
+        echo -e "    ✓ Converted $CONVERTED identical files to symlinks"
+        echo ""
+    fi
+
+    # Handle stale items interactively (or auto with --yes)
+    if [ ${#STALE_DEFERRED[@]} -gt 0 ]; then
+        echo -e "  ${YELLOW}STALE files${NC} (asking per file):"
+        echo ""
+        for entry in "${STALE_DEFERRED[@]}"; do
+            IFS='|' read -r src tgt name <<< "$entry"
+            # Check --skip list
+            if [ -n "$SKIP_ITEMS" ] && echo ",$SKIP_ITEMS," | grep -q ",$name,"; then
+                echo -e "    ${DIM}Skipped${NC} $name (--skip)"
+                SKIPPED=$((SKIPPED + 1))
+                continue
+            fi
+            prompt_stale_conversion "$src" "$tgt" "$name"
+        done
+        echo ""
+    fi
+
+    # Report created items
+    if [ $CREATED -gt 0 ]; then
+        echo -e "  Creating missing toolkit items..."
+        echo -e "    ✓ Created $CREATED new symlinks"
+        echo ""
+    fi
+
+    # Merge settings.json hooks
+    local hooks_to_add
+    hooks_to_add=$(hooks_for_categories "$CONF_INSTALLED_CATEGORIES")
+    if [ -n "$hooks_to_add" ]; then
+        merge_settings_hooks "$target_dir/.claude/settings.json" "add" "$hooks_to_add"
+    fi
+
+    # Update .gitignore
+    update_gitignore_block "$target_dir" "$filter_items"
+
+    # Update CLAUDE.md managed block (ask — offer to inject if not present)
+    update_claudemd_block "$target_dir" "ask"
+
+    # Make hooks executable
+    for hook in "$target_dir/.claude/hooks/"*.sh; do
+        if [ -f "$hook" ] || [ -L "$hook" ]; then
+            chmod +x "$hook" 2>/dev/null || true
+        fi
+    done
+
+    # Post-install record
+    post_install_record "$target_dir"
+
+    # Step 4: Summary
+    echo ""
+    echo -e "${BOLD}Step 4/4: Done!${NC}"
+    echo -e "  Converted: ${GREEN}$CONVERTED${NC} (identical → symlink)"
+    echo -e "  Upgraded:  ${GREEN}$UPGRADED${NC} (stale → symlink, user approved)"
+    echo -e "  Kept:      ${CYAN}$KEPT${NC} (stale → user chose to keep)"
+    echo -e "  Created:   ${GREEN}$CREATED${NC} (new)"
+    echo -e "  Skipped:   ${YELLOW}$SKIPPED${NC} (modified/customized)"
+    echo -e "  Updated:   ${GREEN}$UPDATED${NC}"
+    if [ "$ERRORS" -gt 0 ]; then
+        echo -e "  Errors:    ${RED}$ERRORS${NC}"
+    fi
+    echo ""
+    echo -e "  Backups at: ${CYAN}.claude/$BACKUP_DIR_NAME/${NC}"
+}
+
+# ============================================================================
+# Generate Config (--generate-config)
+# ============================================================================
+
+handle_generate_config() {
+    local target_dir="$1"
+
+    if config_exists "$target_dir"; then
+        echo -e "${YELLOW}Config already exists at$(config_path "$target_dir")${NC}"
+        echo "Use --setup to change selections."
+        return 0
+    fi
+
+    local derived
+    derived=$(generate_config_from_existing "$target_dir")
+    echo -e "${GREEN}Generated config${NC} with categories: $derived"
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+
+TARGET_DIR=""
+MODE="sync"           # sync | setup | uninstall | sync-from-config | init | convert | status | assess | upgrade | generate-config | store-key | check-license
+INSTALL_RAILWAY=false
+LICENSE_KEY=""
+CATEGORIES_ARG=""
+JSON_OUTPUT=false
+
+# Parse arguments
+while [ $# -gt 0 ]; do
+    case $1 in
+        --setup)
+            MODE="setup"
+            shift
+            ;;
+        --uninstall)
+            MODE="uninstall"
+            shift
+            ;;
+        --sync-from-config)
+            MODE="sync-from-config"
+            shift
+            ;;
+        --init)
+            MODE="init"
+            shift
+            ;;
+        --convert)
+            MODE="convert"
+            shift
+            ;;
+        --assess)
+            MODE="assess"
+            shift
+            ;;
+        --upgrade)
+            MODE="upgrade"
+            shift
+            ;;
+        --skip)
+            SKIP_ITEMS="${2:-}"
+            shift
+            [ $# -gt 0 ] && shift
+            ;;
+        --yes|-y)
+            FORCE_YES=true
+            shift
+            ;;
+        --generate-config)
+            MODE="generate-config"
+            shift
+            ;;
+        --status)
+            MODE="status"
+            shift
+            ;;
+        --key)
+            MODE="store-key"
+            LICENSE_KEY="${2:-}"
+            shift
+            [ $# -gt 0 ] && shift
+            ;;
+        --railway)
+            INSTALL_RAILWAY=true
+            shift
+            ;;
+        --check-license-only)
+            MODE="check-license"
+            shift
+            ;;
+        --force-remove-hooks)
+            MODE="force-remove-hooks"
+            FORCE_HOOKS_TARGET="${2:-}"
+            FORCE_HOOKS_LIST="${3:-}"
+            shift
+            [ $# -gt 0 ] && shift
+            [ $# -gt 0 ] && shift
+            ;;
+        --revoke)
+            MODE="revoke"
+            REVOKE_LABEL="${2:-}"
+            shift
+            [ $# -gt 0 ] && shift
+            ;;
+        --add-user)
+            MODE="add-user"
+            ADD_USER_LABEL="${2:-}"
+            shift
+            [ $# -gt 0 ] && shift
+            ;;
+        --list-users)
+            MODE="list-users"
+            shift
+            ;;
+        --categories)
+            CATEGORIES_ARG="${2:-}"
+            shift
+            [ $# -gt 0 ] && shift
+            ;;
+        --bundle)
+            # Install a named bundle (e.g., forge, spark, prime)
+            # Delegates to bin/cli.js install for compiled plugin mode.
+            BUNDLE_NAME="${2:-}"
+            if [ -z "$BUNDLE_NAME" ]; then
+                echo "Error: --bundle requires a bundle name" >&2
+                echo "Available bundles: forge spark scalpel sentinel prism canvas compass counsel shield cruise prime" >&2
+                exit 1
+            fi
+            shift
+            [ $# -gt 0 ] && shift
+            # Determine target path (next arg if present and not a flag)
+            BUNDLE_TARGET="${1:-}"
+            if [[ -n "$BUNDLE_TARGET" && ! "$BUNDLE_TARGET" =~ ^-- ]]; then
+                shift
+            else
+                BUNDLE_TARGET="."
+            fi
+            BUNDLE_TARGET="$(cd "$BUNDLE_TARGET" && pwd)"
+            CLI_JS="$SCRIPT_DIR/bin/cli.js"
+            if command -v node &>/dev/null && [ -f "$CLI_JS" ]; then
+                exec node "$CLI_JS" install "$BUNDLE_NAME" "$BUNDLE_TARGET"
+            else
+                echo "Error: node not found or bin/cli.js missing. Cannot install bundle." >&2
+                echo "Ensure Node.js is installed and the toolkit is fully set up." >&2
+                exit 1
+            fi
+            ;;
+        --json-output)
+            JSON_OUTPUT=true
+            shift
+            ;;
+        --help|-h)
+            echo -e "${BOLD}Claude Agents — Symlink Install System${NC}"
+            echo ""
+            echo "Usage:"
+            echo "  install.sh [path]                Sync (auto-detects if setup needed)"
+            echo "  install.sh --setup [path]        Interactive setup (pick categories)"
+            echo "  install.sh --uninstall [path]    Clean uninstall (restore everything)"
+            echo "  install.sh --sync-from-config [path]  Sync configured categories only"
+            echo "  install.sh --init [path]         Scaffold new project + sync"
+            echo "  install.sh --convert [path]      Replace matching copies with symlinks"
+            echo "  install.sh --assess [path]       Brownfield assessment (read-only)"
+            echo "  install.sh --upgrade [path]      Brownfield upgrade (converts stale/identical)"
+            echo "    --yes                          Auto-approve all stale conversions (CI mode)"
+            echo "    --skip file1,file2             Exclude specific items from conversion"
+            echo "  install.sh --generate-config [path]  Generate config from existing files"
+            echo "  install.sh --status [path]       Show what's linked/overridden/missing"
+            echo "  install.sh --key KEY             Store your license key"
+            echo "  install.sh --railway             Include Railway deployment skills"
+            echo "  install.sh --categories cat1,cat2  Install specific categories (non-interactive)"
+            echo "  install.sh --bundle NAME [path]  Install a compiled plugin bundle (requires node)"
+            echo "  install.sh --json-output         Output JSON summary on completion"
+            echo ""
+            echo "Admin commands (Arth employees only — requires repo write access):"
+            echo "  install.sh --add-user NAME       Generate a license key for a new user"
+            echo "  install.sh --revoke NAME         Revoke a user's license (removes on next session)"
+            echo "  install.sh --list-users          List all licensed users"
+            echo ""
+            echo "  install.sh --help                Show this help"
+            echo ""
+            echo "Categories:"
+            echo "  core        Sync skill, explore-light agent, auto-update hook (always included)"
+            echo "  strategy    Strategy & Design agents (architect, PM, GTM, design-studio)"
+            echo "  development Development agents + planning, implement, PR, issue skills"
+            echo "  quality     QA agents + QA skills"
+            echo "  operations  SRE agent + operations skills"
+            echo "  hooks       Triage router + git worktree sync"
+            echo "  guardrails  Safety hooks + onboard, autopilot skills"
+            echo "  railway     Railway deployment skills"
+            echo "  superpowers Superpowers + deep explore skills"
+            echo ""
+            echo "First install auto-launches interactive setup."
+            echo "Subsequent runs do silent sync respecting your selections."
+            echo ""
+            echo "Symlink behavior (sync):"
+            echo "  Symlink exists     → Update (managed by us)"
+            echo "  Regular file exists → Skip (your project override)"
+            echo "  Doesn't exist      → Create symlink"
+            exit 0
+            ;;
+        *)
+            TARGET_DIR="$1"
+            shift
+            ;;
+    esac
+done
+
+# Handle --key mode (no license check needed)
+if [ "$MODE" = "store-key" ]; then
+    if [ -z "$LICENSE_KEY" ]; then
+        echo -e "${RED}Usage: $0 --key ARTH-XXXX-XXXX-XXXX-XXXX${NC}"
+        exit 1
+    fi
+    echo "$LICENSE_KEY" > "$LICENSE_FILE"
+    echo -e "${GREEN}License key stored.${NC}"
+
+    # Validate immediately
+    if check_license 2>/dev/null; then
+        echo -e "${GREEN}Key validated successfully.${NC}"
+    fi
+    exit 0
+fi
+
+# Handle --check-license-only mode
+if [ "$MODE" = "check-license" ]; then
+    check_license
+    exit 0
+fi
+
+# Handle --force-remove-hooks (used by sync-agents.sh during revocation)
+if [ "$MODE" = "force-remove-hooks" ]; then
+    if [ -n "$FORCE_HOOKS_TARGET" ] && [ -f "$FORCE_HOOKS_TARGET/.claude/settings.json" ] && [ -n "$FORCE_HOOKS_LIST" ]; then
+        merge_settings_hooks "$FORCE_HOOKS_TARGET/.claude/settings.json" "remove" "$FORCE_HOOKS_LIST"
+    fi
+    exit 0
+fi
+
+# ============================================================================
+# Admin Commands (Arth employees only — requires repo write access)
+# ============================================================================
+
+# Handle --list-users
+if [ "$MODE" = "list-users" ]; then
+    if [ ! -f "$AUTHORIZED_KEYS" ]; then
+        echo -e "${RED}authorized-keys.txt not found.${NC}"
+        exit 1
+    fi
+    echo -e "${BOLD}Licensed Users${NC}"
+    echo "---"
+    current_label=""
+    while IFS= read -r line; do
+        # Skip empty lines
+        [ -z "$line" ] && continue
+        # Comment line = label
+        if echo "$line" | grep -q '^#'; then
+            current_label=$(echo "$line" | sed 's/^#[[:space:]]*//')
+            continue
+        fi
+        # Hash line
+        hash="$line"
+        short_hash="${hash:0:12}..."
+        if [ -n "$current_label" ]; then
+            echo -e "  ${CYAN}$current_label${NC}  ($short_hash)"
+            current_label=""
+        else
+            echo -e "  ${DIM}(unlabeled)${NC}  ($short_hash)"
+        fi
+    done < "$AUTHORIZED_KEYS"
+    echo ""
+    echo "Total: $(grep -v '^#' "$AUTHORIZED_KEYS" | grep -v '^$' | wc -l | tr -d ' ') key(s)"
+    exit 0
+fi
+
+# Handle --add-user LABEL
+if [ "$MODE" = "add-user" ]; then
+    if [ -z "$ADD_USER_LABEL" ]; then
+        echo -e "${RED}Usage: $0 --add-user USERNAME${NC}"
+        echo "  Example: $0 --add-user john"
+        exit 1
+    fi
+    if [ ! -f "$AUTHORIZED_KEYS" ]; then
+        echo -e "${RED}authorized-keys.txt not found.${NC}"
+        exit 1
+    fi
+
+    # Check for duplicate label
+    if grep -q "^# $ADD_USER_LABEL$" "$AUTHORIZED_KEYS" 2>/dev/null; then
+        echo -e "${RED}User '$ADD_USER_LABEL' already exists in authorized-keys.txt${NC}"
+        exit 1
+    fi
+
+    # Generate key: ARTH-XXXX-XXXX-XXXX-XXXX (uppercase alphanumeric)
+    GEN_KEY="ARTH"
+    for i in 1 2 3 4; do
+        SEGMENT=$(openssl rand -hex 2 | tr '[:lower:]' '[:upper:]')
+        GEN_KEY="${GEN_KEY}-${SEGMENT}"
+    done
+
+    # Hash the key
+    GEN_HASH=$(echo -n "$GEN_KEY" | shasum -a 256 | awk '{print $1}')
+
+    # Append to authorized-keys.txt
+    echo "" >> "$AUTHORIZED_KEYS"
+    echo "# $ADD_USER_LABEL" >> "$AUTHORIZED_KEYS"
+    echo "$GEN_HASH" >> "$AUTHORIZED_KEYS"
+
+    echo -e "${BOLD}User added: ${CYAN}$ADD_USER_LABEL${NC}"
+    echo ""
+    echo -e "${BOLD}License key (give to user — store securely, shown only once):${NC}"
+    echo ""
+    echo -e "  ${GREEN}$GEN_KEY${NC}"
+    echo ""
+    echo -e "Hash: ${DIM}$GEN_HASH${NC}"
+    echo ""
+    echo -e "${YELLOW}Next steps:${NC}"
+    echo "  1. Give the key above to $ADD_USER_LABEL (securely — not in plain text chat)"
+    echo "  2. Commit: git add authorized-keys.txt && git commit -m 'add license: $ADD_USER_LABEL'"
+    echo "  3. Push:   git push"
+    echo ""
+    echo "  User installs with: install.sh --key $GEN_KEY"
+    exit 0
+fi
+
+# Handle --revoke LABEL
+if [ "$MODE" = "revoke" ]; then
+    if [ -z "$REVOKE_LABEL" ]; then
+        echo -e "${RED}Usage: $0 --revoke USERNAME${NC}"
+        echo "  Example: $0 --revoke john"
+        echo ""
+        echo "  List users: $0 --list-users"
+        exit 1
+    fi
+    if [ ! -f "$AUTHORIZED_KEYS" ]; then
+        echo -e "${RED}authorized-keys.txt not found.${NC}"
+        exit 1
+    fi
+
+    # Find the label
+    if ! grep -q "^# $REVOKE_LABEL$" "$AUTHORIZED_KEYS" 2>/dev/null; then
+        echo -e "${RED}User '$REVOKE_LABEL' not found in authorized-keys.txt${NC}"
+        echo ""
+        echo "Available users:"
+        # Show only single-word labels (user names) — lines like "# username" with no spaces in the name
+        grep -E '^# [a-zA-Z0-9_-]+$' "$AUTHORIZED_KEYS" | sed 's/^# /  /'
+        exit 1
+    fi
+
+    # Remove the label line and the hash line immediately after it
+    tmp=$(mktemp)
+    skip_next=false
+    while IFS= read -r line; do
+        if $skip_next; then
+            # This is the hash line — skip it
+            skip_next=false
+            continue
+        fi
+        if [ "$line" = "# $REVOKE_LABEL" ]; then
+            skip_next=true
+            continue
+        fi
+        echo "$line" >> "$tmp"
+    done < "$AUTHORIZED_KEYS"
+    mv "$tmp" "$AUTHORIZED_KEYS"
+
+    echo -e "${BOLD}License revoked: ${RED}$REVOKE_LABEL${NC}"
+    echo ""
+    echo -e "${YELLOW}What happens next:${NC}"
+    echo "  1. Commit & push this change to propagate revocation"
+    echo "  2. On their next Claude Code session, sync-agents.sh will:"
+    echo "     a. Pull the updated authorized-keys.txt"
+    echo "     b. Detect the license is no longer valid"
+    echo "     c. Remove all toolkit symlinks from their project"
+    echo "     d. Remove hook entries from settings.json"
+    echo "     e. Remove the managed CLAUDE.md block"
+    echo "     f. Display: 'License revoked. Toolkit has been disabled.'"
+    echo ""
+    echo -e "${YELLOW}To complete revocation:${NC}"
+    echo "  git add authorized-keys.txt && git commit -m 'revoke license: $REVOKE_LABEL' && git push"
+    exit 0
+fi
+
+# --status and --assess work WITHOUT a license (users can inspect before buying)
+if [ "$MODE" = "status" ] || [ "$MODE" = "assess" ]; then
+    if [ -z "$TARGET_DIR" ]; then
+        TARGET_DIR="$(pwd)"
+    fi
+    TARGET_DIR="$(cd "$TARGET_DIR" 2>/dev/null && pwd)" || {
+        echo -e "${RED}Error: $TARGET_DIR is not a valid directory${NC}"
+        exit 1
+    }
+    if [ "$MODE" = "status" ]; then
+        show_status "$TARGET_DIR" "$INSTALL_RAILWAY"
+    else
+        handle_assess "$TARGET_DIR"
+    fi
+    exit 0
+fi
+
+# All other modes require a valid license
+check_license
+
+# Default target to current directory
+if [ -z "$TARGET_DIR" ]; then
+    TARGET_DIR="$(pwd)"
+fi
+
+# Resolve to absolute path
+TARGET_DIR="$(cd "$TARGET_DIR" 2>/dev/null && pwd)" || {
+    echo -e "${RED}Error: $TARGET_DIR is not a valid directory${NC}"
+    exit 1
+}
+
+# Verify manifest exists
+if [ ! -f "$MANIFEST" ]; then
+    echo -e "${RED}Error: portable.manifest not found. Re-clone the repo.${NC}"
+    exit 1
+fi
+
+# ---- Mode dispatch ----
+
+# Handle --uninstall
+if [ "$MODE" = "uninstall" ]; then
+    handle_uninstall "$TARGET_DIR"
+    exit 0
+fi
+
+# Handle --setup (explicit interactive setup)
+if [ "$MODE" = "setup" ]; then
+    handle_setup "$TARGET_DIR"
+    exit 0
+fi
+
+# Handle --upgrade (brownfield upgrade)
+if [ "$MODE" = "upgrade" ]; then
+    handle_upgrade "$TARGET_DIR"
+    exit 0
+fi
+
+# Handle --generate-config (generate config from existing files)
+if [ "$MODE" = "generate-config" ]; then
+    handle_generate_config "$TARGET_DIR"
+    exit 0
+fi
+
+# Handle --sync-from-config (used by sync hook)
+if [ "$MODE" = "sync-from-config" ]; then
+    if handle_sync_from_config "$TARGET_DIR"; then
+        exit 0
+    fi
+    # Falls through to full sync if no config found
+    MODE="sync"
+fi
+
+# Handle --init
+if [ "$MODE" = "init" ]; then
+    echo -e "${BOLD}Claude Agents${NC} — Installing into: ${CYAN}$TARGET_DIR${NC}"
+    echo ""
+    scaffold_project "$TARGET_DIR"
+
+    # After scaffolding, run setup if interactive
+    if [ -t 0 ]; then
+        handle_setup "$TARGET_DIR"
+    else
+        # Non-interactive init — install everything
+        mkdir -p "$TARGET_DIR/.claude/agents"
+        mkdir -p "$TARGET_DIR/.claude/skills"
+        mkdir -p "$TARGET_DIR/.claude/hooks"
+        process_manifest "$TARGET_DIR" "safe" "$INSTALL_RAILWAY"
+
+        for hook in "$TARGET_DIR/.claude/hooks/"*.sh; do
+            if [ -f "$hook" ] || [ -L "$hook" ]; then
+                chmod +x "$hook" 2>/dev/null || true
+            fi
+        done
+
+        echo ""
+        echo -e "${BOLD}Done!${NC}"
+        echo -e "  Created:   ${GREEN}$CREATED${NC}"
+        echo -e "  Updated:   ${GREEN}$UPDATED${NC}"
+        echo -e "  Skipped:   ${YELLOW}$SKIPPED${NC} (project overrides)"
+
+        if [ "$JSON_OUTPUT" = "true" ]; then
+            emit_json_summary "init" "$TARGET_DIR"
+        elif [ -t 1 ]; then
+            echo ""
+            echo -e "${BOLD}Next steps:${NC}"
+            echo -e "  ${CYAN}cd $(basename "$TARGET_DIR") && claude${NC}    Start Claude Code in this project"
+            echo -e "  ${CYAN}/calibrate${NC}                   Deep-learn your project (first session — run this once)"
+            echo ""
+            echo -e "  ${DIM}/calibrate reads your source code to learn architecture patterns, coding"
+            echo -e "  conventions, and domain language. It then recommends and installs MCP servers,"
+            echo -e "  agents, skills, and workflows tailored to your project.${NC}"
+            echo ""
+            if command -v clade &>/dev/null; then
+                echo -e "  ${CYAN}clade sync${NC}                Translate toolkit to Cursor/Codex/Kiro/Gemini"
+            fi
+            if command -v arth &>/dev/null; then
+                echo -e "  ${CYAN}arth setup .${NC}             Full setup: toolkit + multi-engine + dashboard"
+            fi
+            echo -e "  ${CYAN}install.sh --status .${NC}    See what's linked/overridden"
+            echo -e "  ${CYAN}install.sh --setup .${NC}     Change category selections"
+        fi
+    fi
+    exit 0
+fi
+
+# ---- Default sync mode ----
+# Smart first-run detection:
+#   config exists            → sync from config (silent)
+#   --categories provided    → use those directly (non-interactive)
+#   no .claude/ AND no config → greenfield, run init flow (interactive)
+#   .claude/ exists, no config → suggest --assess (interactive)
+#   interactive + no config  → launch setup
+
+if config_exists "$TARGET_DIR"; then
+    # Config exists — sync from config silently
+    if handle_sync_from_config "$TARGET_DIR"; then
+        if [ "$JSON_OUTPUT" = "true" ]; then
+            emit_json_summary "sync-from-config" "$TARGET_DIR"
+        fi
+        exit 0
+    fi
+fi
+
+# --categories provided → use those directly (non-interactive)
+if [ -n "$CATEGORIES_ARG" ]; then
+    cats="${CATEGORIES_ARG//,/ }"
+    # Validate categories
+    for cat in $cats; do
+        label=$(get_category_label "$cat")
+        if [ -z "$label" ]; then
+            echo -e "${RED}Unknown category: $cat${NC}" >&2
+            echo "Valid categories: core, strategy, development, quality, operations, hooks, guardrails, railway, superpowers" >&2
+            echo "" >&2
+            echo "Example: install.sh --categories strategy,development,railway ." >&2
+            exit 1
+        fi
+    done
+    # Ensure core is always included
+    if ! echo " $cats " | grep -q " core "; then
+        cats="core $cats"
+    fi
+    echo -e "${BOLD}Claude Agents${NC} — Installing into: ${CYAN}$TARGET_DIR${NC}"
+    echo -e "Categories: ${GREEN}$cats${NC}"
+    echo ""
+    mkdir -p "$TARGET_DIR/.claude/agents"
+    mkdir -p "$TARGET_DIR/.claude/skills"
+    mkdir -p "$TARGET_DIR/.claude/hooks"
+    snapshot_pre_install "$TARGET_DIR"
+    write_config "$TARGET_DIR" "$cats"
+    handle_sync_from_config "$TARGET_DIR"
+    if [ "$JSON_OUTPUT" = "true" ]; then
+        emit_json_summary "categories" "$TARGET_DIR"
+    elif [ -t 1 ]; then
+        echo ""
+        echo -e "${DIM}Change selections: ${CYAN}install.sh --setup .${NC}${DIM}  |  See status: ${CYAN}install.sh --status .${NC}"
+    fi
+    exit 0
+fi
+
+if [ ! -d "$TARGET_DIR/.claude" ] && [ ! -f "$(config_path "$TARGET_DIR")" ]; then
+    # No .claude/ AND no config → greenfield, run init flow
+    if [ -t 0 ]; then
+        echo -e "${BOLD}Claude Agents${NC} — New project detected: ${CYAN}$TARGET_DIR${NC}"
+        echo ""
+        scaffold_project "$TARGET_DIR"
+        handle_setup "$TARGET_DIR"
+        exit 0
+    fi
+fi
+
+if [ -d "$TARGET_DIR/.claude" ] && [ ! -f "$(config_path "$TARGET_DIR")" ]; then
+    # .claude/ exists but no config → suggest --assess
+    if [ -t 0 ]; then
+        echo -e "${YELLOW}Existing .claude/ directory found but no claude-agents config.${NC}"
+        echo ""
+        echo "This project may have manually-created .claude/ files."
+        echo "Options:"
+        echo "  install.sh --setup .           Interactive setup — pick categories to install"
+        echo "  install.sh --categories cat1,cat2 .  Non-interactive install of specific categories"
+        echo "  install.sh --assess .          See what you have vs the toolkit"
+        echo "  install.sh --generate-config . Generate config from existing files"
+        echo ""
+        echo "Available categories: core (always), strategy, development, quality,"
+        echo "  operations, hooks, guardrails, railway, superpowers"
+        exit 0
+    fi
+fi
+
+if [ -t 0 ] && [ ! -f "$(config_path "$TARGET_DIR")" ]; then
+    # Interactive + no config → launch setup
+    handle_setup "$TARGET_DIR"
+    exit 0
+fi
+
+# Fallback: no config, non-interactive — install defaults with category awareness
+# Use default categories (all on except railway, superpowers)
+FALLBACK_CATEGORIES="core strategy development quality operations hooks guardrails"
+if [ "$INSTALL_RAILWAY" = "true" ]; then
+    FALLBACK_CATEGORIES="$FALLBACK_CATEGORIES railway"
+fi
+
+echo -e "${BOLD}Claude Agents${NC} — Installing into: ${CYAN}$TARGET_DIR${NC}"
+echo ""
+echo -e "${DIM}Installing default categories: $FALLBACK_CATEGORIES${NC}"
+echo -e "${DIM}Tip: Use ${CYAN}--setup${DIM} for interactive selection or ${CYAN}--categories${DIM} for specific categories${NC}"
+echo ""
+
+# Build filter list from fallback categories
+FALLBACK_ITEMS=$(items_for_categories "$FALLBACK_CATEGORIES")
+
+# Ensure base directories exist
+mkdir -p "$TARGET_DIR/.claude/agents"
+mkdir -p "$TARGET_DIR/.claude/skills"
+mkdir -p "$TARGET_DIR/.claude/hooks"
+
+if [ "$MODE" = "convert" ]; then
+    echo -e "Mode: ${YELLOW}convert${NC} (replacing matching copies with symlinks)"
+    process_manifest "$TARGET_DIR" "convert" "false" "$FALLBACK_ITEMS"
+else
+    echo -e "Mode: ${GREEN}sync${NC} (safe symlinks — won't touch regular files)"
+    process_manifest "$TARGET_DIR" "safe" "false" "$FALLBACK_ITEMS"
+fi
+
+# Write config so subsequent runs use sync-from-config
+write_config "$TARGET_DIR" "$FALLBACK_CATEGORIES"
+
+# Make hooks executable
+for hook in "$TARGET_DIR/.claude/hooks/"*.sh; do
+    if [ -f "$hook" ] || [ -L "$hook" ]; then
+        chmod +x "$hook" 2>/dev/null || true
+    fi
+done
+
+# Summary
+echo ""
+echo -e "${BOLD}Done!${NC}"
+echo -e "  Created:   ${GREEN}$CREATED${NC}"
+echo -e "  Updated:   ${GREEN}$UPDATED${NC}"
+if [ "$MODE" = "convert" ]; then
+    echo -e "  Converted: ${GREEN}$CONVERTED${NC}"
+fi
+echo -e "  Skipped:   ${YELLOW}$SKIPPED${NC} (project overrides)"
+if [ "$ERRORS" -gt 0 ]; then
+    echo -e "  Errors:    ${RED}$ERRORS${NC}"
+fi
+
+# Next steps (only in interactive mode, not with --json-output)
+if [ "$JSON_OUTPUT" != "true" ] && [ -t 1 ]; then
+    echo ""
+    # Check if project has been calibrated
+    local has_profile=false
+    [ -f "$TARGET_DIR/.claude/project-profile.md" ] && has_profile=true
+
+    if ! $has_profile; then
+        echo -e "${BOLD}First time? Calibrate the toolkit to your project:${NC}"
+        echo -e "  ${CYAN}claude${NC}                     Start Claude Code"
+        echo -e "  ${CYAN}/calibrate${NC}                 Deep-learn your project (run once in Claude Code)"
+        echo ""
+        echo -e "  ${DIM}/calibrate reads source code to learn your architecture, conventions, and domain."
+        echo -e "  It recommends and installs MCP servers, agents, skills, and workflows.${NC}"
+        echo ""
+    fi
+
+    echo -e "${BOLD}Customize your install:${NC}"
+    echo -e "  ${CYAN}install.sh --setup .${NC}     Interactive category picker"
+    echo -e "  ${CYAN}install.sh --categories railway,superpowers .${NC}"
+    echo -e "                             Add optional categories (non-interactive)"
+    echo ""
+    echo -e "${BOLD}Available categories:${NC}"
+    echo -e "  ${GREEN}Installed:${NC}  core, strategy, development, quality, operations, hooks, guardrails"
+    echo -e "  ${YELLOW}Optional:${NC}   railway (Railway deployment skills), superpowers (advanced skills)"
+    echo ""
+    echo -e "${BOLD}Other commands:${NC}"
+    echo -e "  ${CYAN}claude${NC}                     Start Claude Code in this project"
+
+    if command -v clade &>/dev/null; then
+        echo -e "  ${CYAN}clade sync${NC}                Translate toolkit to Cursor/Codex/Kiro/Gemini"
+    fi
+
+    if command -v arth &>/dev/null; then
+        echo -e "  ${CYAN}arth setup .${NC}             Full setup: toolkit + multi-engine + dashboard"
+    fi
+
+    echo -e "  ${CYAN}install.sh --status .${NC}    See what's linked/overridden"
+
+    if $has_profile; then
+        echo -e "  ${CYAN}/calibrate rescan${NC}         Re-scan project after major changes"
+    fi
+fi
+
+# JSON summary (last line, parseable by callers)
+if [ "$JSON_OUTPUT" = "true" ]; then
+    emit_json_summary "sync" "$TARGET_DIR"
+fi