@esoteric-logic/praxis-harness 1.1.0

package/scripts/health-check.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+set -euo pipefail
+
+# ════════════════════════════════════════════════════════════════
+#  Praxis — Health Check
+#  Verifies install integrity: symlinks, config, tools, base layer
+# ════════════════════════════════════════════════════════════════
+
+CLAUDE_DIR="$HOME/.claude"
+CONFIG_FILE="$CLAUDE_DIR/praxis.config.json"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PRAXIS_DIR="$(dirname "$SCRIPT_DIR")"
+
+PASS=0
+FAIL=0
+TOTAL=0
+
+check() {
+  TOTAL=$((TOTAL + 1))
+  if eval "$1" 2>/dev/null; then
+    echo "  ✓ $2"
+    PASS=$((PASS + 1))
+  else
+    echo "  ✗ $2"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "Praxis Health Check"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# ─── CLAUDE.md symlink ───
+echo ""
+echo "Core:"
+check "[[ -e '$CLAUDE_DIR/CLAUDE.md' ]]" "CLAUDE.md installed"
+
+# ─── Rules symlinks ───
+echo ""
+echo "Rules:"
+if [[ -d "$PRAXIS_DIR/base/rules" ]]; then
+  for rule in "$PRAXIS_DIR"/base/rules/*.md; do
+    [[ -f "$rule" ]] || continue
+    fname=$(basename "$rule")
+    check "[[ -e '$CLAUDE_DIR/rules/$fname' ]]" "rules/$fname installed"
+  done
+fi
+
+# ─── Commands symlinks ───
+echo ""
+echo "Commands:"
+if [[ -d "$PRAXIS_DIR/base/commands" ]]; then
+  for cmd in "$PRAXIS_DIR"/base/commands/*.md; do
+    [[ -f "$cmd" ]] || continue
+    fname=$(basename "$cmd")
+    check "[[ -e '$CLAUDE_DIR/commands/$fname' ]]" "commands/$fname installed"
+  done
+fi
+
+# ─── Skills symlinks ───
+echo ""
+echo "Skills:"
+if [[ -d "$PRAXIS_DIR/base/skills" ]]; then
+  for skill_dir in "$PRAXIS_DIR"/base/skills/*/; do
+    [[ -d "$skill_dir" ]] || continue
+    skill_name=$(basename "$skill_dir")
+    check "[[ -e '$CLAUDE_DIR/skills/$skill_name' ]]" "skills/$skill_name installed"
+  done
+fi
+
+# ─── Kits symlink ───
+echo ""
+echo "Kits:"
+check "[[ -e '$CLAUDE_DIR/kits' ]]" "kits directory installed"
+
+# ─── Config ───
+echo ""
+echo "Config:"
+check "[[ -f '$CONFIG_FILE' ]]" "praxis.config.json exists"
+
+if [[ -f "$CONFIG_FILE" ]]; then
+  VAULT_PATH=$(jq -r '.vault_path // empty' "$CONFIG_FILE" 2>/dev/null)
+  if [[ -n "$VAULT_PATH" ]]; then
+    check "[[ -d '$VAULT_PATH' ]]" "vault_path ($VAULT_PATH) is a real directory"
+  else
+    TOTAL=$((TOTAL + 1))
+    echo "  ✗ vault_path not set in config"
+    FAIL=$((FAIL + 1))
+  fi
+fi
+
+# ─── Required tools (conditional on backend) ───
+echo ""
+echo "Tools:"
+VAULT_BACKEND=""
+if [[ -f "$CONFIG_FILE" ]]; then
+  VAULT_BACKEND=$(jq -r '.vault_backend // "obsidian"' "$CONFIG_FILE" 2>/dev/null)
+fi
+if [[ "$VAULT_BACKEND" == "obsidian" ]]; then
+  check "command -v obsidian" "Obsidian CLI available"
+else
+  check "command -v rg" "ripgrep available"
+fi
+check "command -v node" "node available"
+check "command -v claude" "claude available"
+check "command -v jq" "jq available"
+
+# ─── MCP Servers (warn only) ───
+echo ""
+echo "MCP Servers:"
+if command -v claude &>/dev/null; then
+  MCP_LIST=$(claude mcp list 2>/dev/null || true)
+  for server in context7 perplexity github; do
+    TOTAL=$((TOTAL + 1))
+    if echo "$MCP_LIST" | grep -q "$server"; then
+      echo "  ✓ $server registered"
+      PASS=$((PASS + 1))
+    else
+      echo "  ⚠ $server not registered (optional)"
+      PASS=$((PASS + 1))  # optional = pass either way
+    fi
+  done
+else
+  echo "  ⚠ claude CLI not available — cannot check MCP servers"
+fi
+
+# ─── Broken symlinks (relevant for git-clone/symlink installs) ───
+echo ""
+echo "Symlink integrity:"
+BROKEN=0
+for dir in "$CLAUDE_DIR/rules" "$CLAUDE_DIR/commands" "$CLAUDE_DIR/skills"; do
+  if [[ -d "$dir" ]]; then
+    while IFS= read -r link; do
+      if [[ -L "$link" && ! -e "$link" ]]; then
+        echo "  ✗ Broken symlink: $link"
+        BROKEN=$((BROKEN + 1))
+      fi
+    done < <(find "$dir" -maxdepth 1 -type l 2>/dev/null)
+  fi
+done
+
+TOTAL=$((TOTAL + 1))
+if [[ $BROKEN -eq 0 ]]; then
+  echo "  ✓ No broken symlinks"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ $BROKEN broken symlink(s) found"
+  FAIL=$((FAIL + 1))
+fi
+
+# ─── Summary ───
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Results: $PASS/$TOTAL passed"
+if [[ $FAIL -gt 0 ]]; then
+  echo "  $FAIL check(s) failed"
+  exit 1
+else
+  echo "  All checks passed"
+  exit 0
+fi

package/scripts/lint-harness.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+set -euo pipefail
+
+# ════════════════════════════════════════════════════════════════
+#  Praxis — Harness Content Lint
+#  Validates frontmatter, placeholders, registry consistency, syntax
+# ════════════════════════════════════════════════════════════════
+
+REPO_PATH="${1:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+ERRORS=0
+WARNINGS=0
+
+error() {
+  echo "  ✗ ERROR: $1"
+  ERRORS=$((ERRORS + 1))
+}
+
+warn() {
+  echo "  ⚠ WARN:  $1"
+  WARNINGS=$((WARNINGS + 1))
+}
+
+ok() {
+  echo "  ✓ $1"
+}
+
+echo "Praxis Harness Lint"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Repo: $REPO_PATH"
+
+# ─── 1. Command frontmatter ───
+echo ""
+echo "Commands (description: field):"
+if [[ -d "$REPO_PATH/base/commands" ]]; then
+  for cmd in "$REPO_PATH"/base/commands/*.md; do
+    [[ -f "$cmd" ]] || continue
+    fname=$(basename "$cmd")
+    if head -5 "$cmd" | grep -q "^description:"; then
+      ok "$fname"
+    else
+      error "$fname missing description: in frontmatter"
+    fi
+  done
+fi
+
+# ─── 2. Skill frontmatter ───
+echo ""
+echo "Skills (name:, disable-model-invocation:, description:):"
+if [[ -d "$REPO_PATH/base/skills" ]]; then
+  for skill_dir in "$REPO_PATH"/base/skills/*/; do
+    [[ -d "$skill_dir" ]] || continue
+    skill_name=$(basename "$skill_dir")
+    skill_file="$skill_dir/SKILL.md"
+    if [[ ! -f "$skill_file" ]]; then
+      error "skills/$skill_name/ missing SKILL.md"
+      continue
+    fi
+    # Check required frontmatter fields (within first 10 lines)
+    header=$(head -10 "$skill_file")
+    missing=""
+    echo "$header" | grep -q "^name:" || missing="$missing name:"
+    echo "$header" | grep -q "^disable-model-invocation:" || missing="$missing disable-model-invocation:"
+    echo "$header" | grep -q "^description:" || missing="$missing description:"
+    if [[ -z "$missing" ]]; then
+      ok "skills/$skill_name"
+    else
+      error "skills/$skill_name SKILL.md missing:$missing"
+    fi
+  done
+fi
+
+# ─── 3. Kit frontmatter ───
+echo ""
+echo "Kits (name:, version:, description:, activation:, skills_chain:):"
+if [[ -d "$REPO_PATH/kits" ]]; then
+  for kit_dir in "$REPO_PATH"/kits/*/; do
+    [[ -d "$kit_dir" ]] || continue
+    kit_name=$(basename "$kit_dir")
+    kit_file="$kit_dir/KIT.md"
+    if [[ ! -f "$kit_file" ]]; then
+      error "kits/$kit_name/ missing KIT.md"
+      continue
+    fi
+    header=$(head -15 "$kit_file")
+    missing=""
+    echo "$header" | grep -q "^name:" || missing="$missing name:"
+    echo "$header" | grep -q "^version:" || missing="$missing version:"
+    echo "$header" | grep -q "^description:" || missing="$missing description:"
+    echo "$header" | grep -q "^activation:" || missing="$missing activation:"
+    echo "$header" | grep -q "^skills_chain:" || missing="$missing skills_chain:"
+    if [[ -z "$missing" ]]; then
+      ok "kits/$kit_name"
+    else
+      error "kits/$kit_name KIT.md missing:$missing"
+    fi
+  done
+fi
+
+# ─── 4. Placeholder scan ───
+echo ""
+echo "Placeholder scan ({placeholder} patterns):"
+PLACEHOLDER_FOUND=0
+# Scan base/, kits/, docs/, scripts/ — exclude templates/ and */references/
+# Also exclude HTML comments and fenced code blocks
+while IFS= read -r file; do
+  [[ -f "$file" ]] || continue
+  # Skip templates directory and references directories
+  [[ "$file" == *"/templates/"* ]] && continue
+  [[ "$file" == *"/references/"* ]] && continue
+
+  # Strip fenced code blocks (including indented), HTML comments,
+  # lines with inline backticks, and shell comments/echo lines
+  matches=$(sed -E \
+    -e '/^[[:space:]]*```/,/^[[:space:]]*```/d' \
+    -e '/<!--/,/-->/d' \
+    "$file" \
+    | grep -nE '\{[a-zA-Z_][a-zA-Z0-9_-]*\}' \
+    | grep -vE '`[^`]*\{[^}]+\}[^`]*`' \
+    | grep -vE '^[0-9]+:\s*#' \
+    | grep -vE '^[0-9]+:\s*echo ' \
+    | grep -vE '\{vault_path\}|\{today_date\}|\{project-slug\}|\{YYYY-MM-DD\}|\{kebab-title\}|\{date\}|\{[nN]\}|\{1-line\}|\{ISO timestamp\}|\{repo_root\}|\{identity_email\}|\{stack\}|\{placeholder\}|\{placeholders\}|\{http_code\}' \
+    || true)
+  if [[ -n "$matches" ]]; then
+    rel_path="${file#"$REPO_PATH"/}"
+    while IFS= read -r match; do
+      error "$rel_path:$match"
+      PLACEHOLDER_FOUND=$((PLACEHOLDER_FOUND + 1))
+    done <<< "$matches"
+  fi
+done < <(find "$REPO_PATH/base" "$REPO_PATH/docs" "$REPO_PATH/scripts" -name "*.md" -o -name "*.sh" 2>/dev/null; find "$REPO_PATH/kits" -name "*.md" -o -name "*.sh" 2>/dev/null)
+
+if [[ $PLACEHOLDER_FOUND -eq 0 ]]; then
+  ok "No unreplaced placeholders found"
+fi
+
+# ─── 5. Rules registry consistency ───
+echo ""
+echo "Rules registry (CLAUDE.md references vs disk):"
+if [[ -f "$REPO_PATH/base/CLAUDE.md" ]]; then
+  # Extract rule filenames from CLAUDE.md registry tables
+  rule_refs=$(grep -oE '~/.claude/rules/[a-zA-Z0-9_-]+\.md' "$REPO_PATH/base/CLAUDE.md" \
+    | sed 's|~/.claude/rules/||' | sort -u)
+  for rule_file in $rule_refs; do
+    if [[ -f "$REPO_PATH/base/rules/$rule_file" ]]; then
+      ok "rules/$rule_file exists"
+    else
+      error "CLAUDE.md references rules/$rule_file but file not found"
+    fi
+  done
+fi
+
+# ─── 6. Shell script syntax ───
+echo ""
+echo "Shell syntax (bash -n):"
+while IFS= read -r script; do
+  [[ -f "$script" ]] || continue
+  fname="${script#"$REPO_PATH"/}"
+  if bash -n "$script" 2>/dev/null; then
+    ok "$fname"
+  else
+    error "$fname has syntax errors"
+  fi
+done < <(find "$REPO_PATH" -maxdepth 1 -name "*.sh" 2>/dev/null; find "$REPO_PATH/scripts" -name "*.sh" 2>/dev/null; find "$REPO_PATH/kits" -name "*.sh" 2>/dev/null)
+
+# ─── 7. Template content warnings ───
+echo ""
+echo "Template content warnings:"
+for check_file in "$REPO_PATH/base/rules/git-workflow.md" "$REPO_PATH/base/rules/profile.md"; do
+  if [[ -f "$check_file" ]]; then
+    fname="${check_file#"$REPO_PATH"/}"
+    if grep -qiE "you@company\.com|Your Name" "$check_file"; then
+      warn "$fname contains uncustomized template values (you@company.com or Your Name)"
+    else
+      ok "$fname — no template placeholders"
+    fi
+  fi
+done
+
+# ─── Summary ───
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Errors:   $ERRORS"
+echo "  Warnings: $WARNINGS"
+if [[ $ERRORS -gt 0 ]]; then
+  echo "  FAILED — fix errors above"
+  exit 1
+else
+  if [[ $WARNINGS -gt 0 ]]; then
+    echo "  PASSED with warnings"
+  else
+    echo "  PASSED — all clean"
+  fi
+  exit 0
+fi

package/scripts/onboard-mcp.sh

@@ -0,0 +1,326 @@
+#!/bin/bash
+set -euo pipefail
+
+# ════════════════════════════════════════════════════════════════
+#  Praxis — MCP Server Onboarding
+#  Configures cross-cutting MCP servers for Claude Code.
+#  Can be sourced (install.sh) or run standalone.
+#
+#  Servers:
+#    context7    — live library docs (free, no key)
+#    perplexity  — AI web search (requires API key)
+#    github      — repo operations (requires PAT)
+#
+#  Usage:
+#    bash scripts/onboard-mcp.sh [context7|perplexity|github|all]
+#    source scripts/onboard-mcp.sh  # then call functions directly
+# ════════════════════════════════════════════════════════════════
+
+# ─── Constants (match install.sh when sourced) ───
+CLAUDE_DIR="${CLAUDE_DIR:-$HOME/.claude}"
+CONFIG_FILE="${CONFIG_FILE:-$CLAUDE_DIR/praxis.config.json}"
+
+# ─── Colors (safe defaults if not already set) ───
+RED="${RED:-\033[0;31m}"
+GREEN="${GREEN:-\033[0;32m}"
+YELLOW="${YELLOW:-\033[0;33m}"
+CYAN="${CYAN:-\033[0;36m}"
+BOLD="${BOLD:-\033[1m}"
+NC="${NC:-\033[0m}"
+
+# ─── Output helpers (no-op if already defined by install.sh) ───
+if ! declare -f ok &>/dev/null; then
+  ok()   { echo -e "  $GREEN✓$NC $1"; }
+fi
+if ! declare -f warn &>/dev/null; then
+  warn() { echo -e "  $YELLOW⚠$NC $1"; }
+fi
+if ! declare -f fail &>/dev/null; then
+  fail() { echo -e "  $RED✗$NC $1"; }
+fi
+
+# ═══════════════════════════════════════════
+# Utilities
+# ═══════════════════════════════════════════
+
+mcp_server_exists() {
+  local name="$1"
+  claude mcp list 2>/dev/null | grep -q "$name"
+}
+
+open_url() {
+  local url="$1"
+  if [[ "$(uname -s)" == "Darwin" ]]; then
+    open "$url" 2>/dev/null || echo "  Open: $url"
+  elif command -v xdg-open &>/dev/null; then
+    xdg-open "$url" 2>/dev/null || echo "  Open: $url"
+  else
+    echo "  Open: $url"
+  fi
+}
+
+update_mcp_status() {
+  local key="$1"
+  local val="$2"
+  if [[ -f "$CONFIG_FILE" ]] && command -v jq &>/dev/null; then
+    local tmp="$CONFIG_FILE.tmp"
+    jq --arg k "$key" --arg v "$val" '.[$k] = $v' "$CONFIG_FILE" > "$tmp" && mv "$tmp" "$CONFIG_FILE"
+  fi
+}
+
+# ═══════════════════════════════════════════
+# Server: Context7 — live library docs
+# ═══════════════════════════════════════════
+
+onboard_context7() {
+  echo -e "  ${BOLD}Context7${NC} — live library/API documentation"
+
+  # Check if running as Claude Code plugin (settings.json)
+  local settings_file="$CLAUDE_DIR/settings.json"
+  if [[ -f "$settings_file" ]] && command -v jq &>/dev/null; then
+    if jq -e '.enabledPlugins // [] | map(select(contains("context7"))) | length > 0' "$settings_file" &>/dev/null; then
+      ok "Context7 already active as Claude Code plugin (skipping MCP)"
+      update_mcp_status "context7_status" "plugin"
+      return 0
+    fi
+  fi
+
+  # Check if already registered as MCP server
+  if mcp_server_exists "context7"; then
+    ok "Context7 MCP already registered"
+    update_mcp_status "context7_status" "configured"
+    return 0
+  fi
+
+  # Configure
+  echo "  Registering Context7 MCP server..."
+  if claude mcp add context7 -s user -- npx -y @upstash/context7-mcp 2>/dev/null; then
+    # Verify
+    if mcp_server_exists "context7"; then
+      ok "Context7 MCP registered"
+      update_mcp_status "context7_status" "configured"
+    else
+      warn "Context7 registered but not showing in mcp list"
+      update_mcp_status "context7_status" "unverified"
+    fi
+  else
+    fail "Context7 registration failed"
+    echo "    Run manually: claude mcp add context7 -s user -- npx -y @upstash/context7-mcp"
+    update_mcp_status "context7_status" "failed"
+    return 1
+  fi
+}
+
+# ═══════════════════════════════════════════
+# Server: Perplexity — AI web search
+# ═══════════════════════════════════════════
+
+onboard_perplexity() {
+  echo -e "  ${BOLD}Perplexity${NC} — AI-powered web search"
+
+  # Check if already registered
+  if mcp_server_exists "perplexity"; then
+    echo -e "  Perplexity MCP is already registered."
+    read -p "  Reconfigure? [y/N] " RECONFIG
+    if [[ ! "${RECONFIG:-N}" =~ ^[Yy]$ ]]; then
+      ok "Perplexity MCP — keeping existing config"
+      return 0
+    fi
+    echo "  Removing existing config..."
+    claude mcp remove perplexity 2>/dev/null || true
+  fi
+
+  # Acquire API key
+  echo ""
+  echo "  You need a Perplexity API key (starts with pplx-)."
+  echo "  Opening API settings page..."
+  open_url "https://www.perplexity.ai/settings/api"
+  echo ""
+  read -s -p "  Paste your Perplexity API key: " PPLX_KEY
+  echo ""
+
+  if [[ -z "$PPLX_KEY" ]]; then
+    warn "No key entered — skipping Perplexity"
+    update_mcp_status "perplexity_status" "skipped"
+    return 0
+  fi
+
+  # Validate prefix
+  if [[ ! "$PPLX_KEY" =~ ^pplx- ]]; then
+    warn "Key doesn't start with 'pplx-' — this may not be a valid Perplexity key"
+    read -p "  Continue anyway? [y/N] " CONTINUE
+    if [[ ! "${CONTINUE:-N}" =~ ^[Yy]$ ]]; then
+      unset PPLX_KEY
+      update_mcp_status "perplexity_status" "skipped"
+      return 0
+    fi
+  fi
+
+  # Verify key with API
+  echo "  Verifying API key..."
+  local http_code
+  local curl_fmt='%{http_code}'
+  http_code=$(curl -s -o /dev/null -w "$curl_fmt" \
+    -X POST "https://api.perplexity.ai/chat/completions" \
+    -H "Authorization: Bearer $PPLX_KEY" \
+    -H "Content-Type: application/json" \
+    -d '{"model":"sonar","messages":[{"role":"user","content":"ping"}],"max_tokens":1}' \
+    2>/dev/null || echo "000")
+
+  if [[ "$http_code" == "200" ]]; then
+    ok "API key verified"
+  elif [[ "$http_code" == "000" ]]; then
+    warn "Could not reach Perplexity API (network issue?) — proceeding anyway"
+  else
+    warn "API returned HTTP $http_code — key may be invalid"
+    read -p "  Continue with this key? [y/N] " CONTINUE
+    if [[ ! "${CONTINUE:-N}" =~ ^[Yy]$ ]]; then
+      unset PPLX_KEY
+      update_mcp_status "perplexity_status" "skipped"
+      return 0
+    fi
+  fi
+
+  # Configure
+  echo "  Registering Perplexity MCP server..."
+  if claude mcp add perplexity -s user -e PERPLEXITY_API_KEY="$PPLX_KEY" -- npx -y @pplx/mcp-server 2>/dev/null; then
+    if mcp_server_exists "perplexity"; then
+      ok "Perplexity MCP registered"
+      update_mcp_status "perplexity_status" "configured"
+    else
+      warn "Perplexity registered but not showing in mcp list"
+      update_mcp_status "perplexity_status" "unverified"
+    fi
+  else
+    fail "Perplexity registration failed"
+    echo "    Run manually: claude mcp add perplexity -s user -e PERPLEXITY_API_KEY=\"\$KEY\" -- npx -y @pplx/mcp-server"
+    update_mcp_status "perplexity_status" "failed"
+  fi
+
+  # Clear key from memory
+  unset PPLX_KEY
+}
+
+# ═══════════════════════════════════════════
+# Server: GitHub — repo operations
+# ═══════════════════════════════════════════
+
+onboard_github() {
+  echo -e "  ${BOLD}GitHub${NC} — repo operations, PRs, issues, code search"
+
+  # Check if already registered
+  if mcp_server_exists "github"; then
+    echo -e "  GitHub MCP is already registered."
+    read -p "  Reconfigure? [y/N] " RECONFIG
+    if [[ ! "${RECONFIG:-N}" =~ ^[Yy]$ ]]; then
+      ok "GitHub MCP — keeping existing config"
+      return 0
+    fi
+    echo "  Removing existing config..."
+    claude mcp remove github 2>/dev/null || true
+  fi
+
+  # Acquire PAT
+  echo ""
+  echo "  You need a GitHub Personal Access Token (starts with ghp_ or github_pat_)."
+  echo "  Opening GitHub token settings..."
+  open_url "https://github.com/settings/tokens"
+  echo ""
+  read -s -p "  Paste your GitHub PAT: " GH_TOKEN
+  echo ""
+
+  if [[ -z "$GH_TOKEN" ]]; then
+    warn "No token entered — skipping GitHub"
+    update_mcp_status "github_mcp_status" "skipped"
+    return 0
+  fi
+
+  # Validate prefix
+  if [[ ! "$GH_TOKEN" =~ ^(ghp_|github_pat_) ]]; then
+    warn "Token doesn't start with 'ghp_' or 'github_pat_' — this may not be a valid PAT"
+    read -p "  Continue anyway? [y/N] " CONTINUE
+    if [[ ! "${CONTINUE:-N}" =~ ^[Yy]$ ]]; then
+      unset GH_TOKEN
+      update_mcp_status "github_mcp_status" "skipped"
+      return 0
+    fi
+  fi
+
+  # Verify token
+  echo "  Verifying GitHub token..."
+  local gh_user
+  gh_user=$(curl -s -H "Authorization: Bearer $GH_TOKEN" \
+    "https://api.github.com/user" 2>/dev/null | jq -r '.login // empty' 2>/dev/null || echo "")
+
+  if [[ -n "$gh_user" ]]; then
+    ok "Authenticated as: $gh_user"
+  else
+    warn "Could not verify token — proceeding anyway"
+  fi
+
+  # Configure
+  echo "  Registering GitHub MCP server..."
+  if claude mcp add github -s user -e GITHUB_PERSONAL_ACCESS_TOKEN="$GH_TOKEN" -- npx -y @modelcontextprotocol/server-github 2>/dev/null; then
+    if mcp_server_exists "github"; then
+      ok "GitHub MCP registered"
+      update_mcp_status "github_mcp_status" "configured"
+    else
+      warn "GitHub registered but not showing in mcp list"
+      update_mcp_status "github_mcp_status" "unverified"
+    fi
+  else
+    fail "GitHub registration failed"
+    echo "    Run manually: claude mcp add github -s user -e GITHUB_PERSONAL_ACCESS_TOKEN=\"\$TOKEN\" -- npx -y @modelcontextprotocol/server-github"
+    update_mcp_status "github_mcp_status" "failed"
+  fi
+
+  # Clear token from memory
+  unset GH_TOKEN
+}
+
+# ═══════════════════════════════════════════
+# Entrypoint (standalone mode only)
+# ═══════════════════════════════════════════
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  TARGET="${1:-all}"
+
+  echo ""
+  echo -e "${BOLD}Praxis — MCP Server Onboarding${NC}"
+  echo ""
+
+  if ! command -v claude &>/dev/null; then
+    fail "Claude Code CLI not found. Install it first: npm install -g @anthropic-ai/claude-code"
+    exit 1
+  fi
+
+  case "$TARGET" in
+    context7)
+      onboard_context7
+      ;;
+    perplexity)
+      onboard_perplexity
+      ;;
+    github)
+      onboard_github
+      ;;
+    all)
+      onboard_context7
+      echo ""
+      read -p "  Set up Perplexity? [y/N] " DO_PPLX
+      [[ "${DO_PPLX:-N}" =~ ^[Yy]$ ]] && onboard_perplexity
+      echo ""
+      read -p "  Set up GitHub MCP? [y/N] " DO_GH
+      [[ "${DO_GH:-N}" =~ ^[Yy]$ ]] && onboard_github
+      ;;
+    *)
+      echo "Usage: bash scripts/onboard-mcp.sh [context7|perplexity|github|all]"
+      exit 1
+      ;;
+  esac
+
+  echo ""
+  echo -e "${BOLD}Current MCP servers:${NC}"
+  claude mcp list 2>/dev/null || echo "  (none)"
+  echo ""
+fi