/install

name: install
description: "Verify VexJoy Agent installation, diagnose issues, and guide first-time setup."
user-invocable: true
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
  - Write
  - Edit
  - Agent
routing:
  force_route: true
  not_for: "installing npm packages, pip packages, OS packages, hardware, third-party tools — only for VexJoy Agent toolkit setup verification"
  triggers:
    - "install toolkit"
    - "verify installation"
    - "health check toolkit"
    - "setup toolkit"
    - "diagnose setup"
    - "toolkit health"
  category: meta-tooling

/install — Setup & Health Check

Verify your VexJoy Agent installation, diagnose issues, and get oriented. Use after cloning the repo and running `install.sh`, when something seems broken (hooks not firing, missing commands), for first-time orientation, or after a `git pull` to verify nothing broke.

Instructions

Phase 1: DIAGNOSE

**Goal**: Run deterministic health checks and report results.

**Step 1: Run install-doctor.py**

python3 ~/.claude/scripts/install-doctor.py check

If the script is not found at `scripts/install-doctor.py`, try `~/.claude/scripts/install-doctor.py`.

**Step 1b: Run runtime health check**

python3 ~/.claude/scripts/toolkit-health.py --json

If the script is not found at `scripts/toolkit-health.py`, try `~/.claude/scripts/toolkit-health.py`. This surfaces runtime health (hook error rate, stale memory files) that `install-doctor.py` does not cover. It exits 1 when `has_warnings` is true — treat that as "warnings to surface," not a setup failure. Capture the `flags` array for Step 3.

**Step 2: Interpret results**

| Result | Action | |--------|--------| | All checks pass | Skip to Phase 3 (Inventory) | | `~/.claude` missing | Guide user to run `install.sh` — go to Phase 2 | | Components missing | Guide user to run `install.sh` — go to Phase 2 | | Codex skill content drift | Run `./install.sh --sync` from the toolkit repo, then re-check | | Hooks not configured | Guide user to run `install.sh` — go to Phase 2 | | Broken symlinks | Symlink targets moved. Re-run `install.sh --symlink --force` | | Python deps missing | Run `pip install -r requirements.txt` from the repo directory | | Permissions wrong | Run `chmod 755` on affected files |

**Step 3: Display results clearly**

Show the check output to the user with a clear pass/fail summary. Display the raw script output without paraphrasing or reformatting, because the script already formats diagnostics for readability and rewriting them risks losing detail or misrepresenting status.

Append the runtime-health result from Step 1b: if `has_warnings` is true, list each entry from the `flags` array as a WARN line in the summary (e.g. stale memory files, elevated hook error rate). When `has_warnings` is false, report runtime health as OK. WARN flags are advisory — they inform the user without blocking the pass/fail verdict for setup.

**Gate**: Health check complete. If issues found, proceed to Phase 2. If clean, skip to Phase 3.

Phase 2: FIX (only if issues found)

**Goal**: Guide the user through fixing detected issues.

**Step 1: Determine if install.sh needs to run**

If `~/.claude` is missing or components are not installed, the user needs to run install.sh. Tell them:

The toolkit hasn't been installed yet. Run this from the repo directory:

  ./install.sh --symlink     # recommended: updates with git pull
  ./install.sh --dry-run     # preview first

Wait for the user to confirm they've run it, then re-run the health check. This phase is interactive because installation changes system state -- always show the user what needs fixing and let them choose before acting.

**Step 2: Fix individual issues**

For fixable issues (permissions, missing deps), offer to fix them:

# Fix permissions
find ~/.claude/hooks -name "*.py" -exec chmod 755 {} \;
find ~/.claude/scripts -name "*.py" -exec chmod 755 {} \;

# Install Python deps (from repo directory)
pip install -r requirements.txt

Only run fixes the user approves, because automated fixes to `~/.claude` can break an existing setup if assumptions about the environment are wrong.

**Step 3: Re-check**

After fixes, re-run:

python3 ~/.claude/scripts/install-doctor.py check

`--sync` refreshes canonical Codex skill content, including changed files and new references inside an existing skill. It preserves Codex-only skill entries.

**Gate**: All checks pass. Proceed to Phase 3.

Phase 3: INVENTORY

**Goal**: Show the user what they have installed.

**Step 1: Run inventory**

python3 ~/.claude/scripts/install-doctor.py inventory

**Step 2: Display summary**

Show the actual counts returned by `install-doctor.py inventory` -- never display hardcoded numbers, because component counts change with every install and stale numbers erode trust. Present them as:

Your toolkit is ready. Here's what's installed:

  Agents:   [N] specialized domain experts
  Skills:   [N] workflow methodologies ([N] user-invocable)
  Hooks:    [N] automation hooks
  Commands: [N] slash commands
  Scripts:  [N] utility scripts

**Gate**: User sees their inventory. Proceed to Phase 3.5.

Phase 3.5: MCP INVENTORY

**Goal**: Show which MCP servers are available and their status.

**Step 1: Run MCP registry check**

python3 ~/.claude/scripts/mcp-registry.py list

If the script is not found at `scripts/mcp-registry.py`, try `~/.claude/scripts/mcp-registry.py`.

**Step 2: Display MCP status**

Show the MCP inventory as:

MCP Servers:

  [✓] Chrome DevTools MCP  — Live browser debugging
      Paired skills: wordpress-live-validation
  [✓] Playwright MCP       — Automated browser testing
      Paired skills: wordpress-live-validation
  [✓] gopls MCP            — Go workspace intelligence
      Paired skills: go-patterns
  [✗] Context7 MCP         — Library documentation lookups
      Install: claude mcp add context7 -- npx @anthropic-