@plexor-dev/claude-code-plugin-staging 0.1.0-beta.19 → 0.1.0-beta.20

package/commands/plexor-login.js

@@ -247,10 +247,9 @@ async function main() {
     console.log(`│  Already Logged In                          │`);
     console.log(`├─────────────────────────────────────────────┤`);
     console.log(`│  API Key: ${(existingKey.substring(0, 8) + '...').padEnd(33)}│`);
-    console.log(`│  To re-login, provide a new key:            │`);
-    console.log(`│    echo $PLEXOR_API_KEY | /plexor-login     │`);
-    console.log(`│  To logout:                                 │`);
-    console.log(`│    /plexor-logout                           │`);
+    console.log(`│  Human setup path: /plexor-setup            │`);
+    console.log(`│  Automation path: /plexor-login <key>       │`);
+    console.log(`│  To logout: /plexor-logout                  │`);
     console.log(`└─────────────────────────────────────────────┘`);
     return;
   }
@@ -258,7 +257,9 @@ async function main() {
   // If no key provided, show secure usage options
   if (!apiKey) {
     console.log(`┌─────────────────────────────────────────────┐`);
-    console.log(`│  Plexor Login                               │`);
+    console.log(`│  Plexor Login (Advanced)                    │`);
+    console.log(`├─────────────────────────────────────────────┤`);
+    console.log(`│  Human first-run: /plexor-setup             │`);
     console.log(`├─────────────────────────────────────────────┤`);
     console.log(`│  Get your API key at:                       │`);
     console.log(`│  https://plexor.dev/dashboard/api-keys      │`);
@@ -304,30 +305,42 @@ async function main() {
       process.exit(1);
     }
 
-    // AUTO-CONFIGURE CLAUDE CODE ROUTING
-    // This is the key feature: automatically set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
-    // in ~/.claude/settings.json so ALL Claude Code sessions route through Plexor
+    // Automation path: save credentials and activate routing.
+    // Guided human setup should go through /plexor-setup, which also verifies the route.
     const useStaging = apiUrl.includes('staging');
     const routingEnabled = settingsManager.enablePlexorRouting(apiKey, { useStaging });
 
+    config.health = {
+      installed: true,
+      connected: true,
+      routing_active: routingEnabled,
+      verified: false,
+      verified_at: null,
+      verify_error: 'Verification not run. Use /plexor-setup for guided verification.',
+      gateway: useStaging ? 'staging' : 'production',
+      previous_auth_preserved: false
+    };
+    saveConfig(config);
+
     const email = user.email || 'Unknown';
     const tier = user.tier?.name || 'Free';
 
     console.log(`┌─────────────────────────────────────────────┐`);
-    console.log(`│  ✓ Login Successful                         │`);
+    console.log(`│  ✓ Plexor Credentials Saved                 │`);
     console.log(`├─────────────────────────────────────────────┤`);
     console.log(`│  Email: ${email.substring(0, 35).padEnd(35)}│`);
     console.log(`│  Tier: ${tier.padEnd(36)}│`);
     console.log(`├─────────────────────────────────────────────┤`);
     if (routingEnabled) {
-    console.log(`│  ✓ Claude Code routing: CONFIGURED          │`);
-    console.log(`│    All sessions now route through Plexor    │`);
+    console.log(`│  ✓ Claude routing: ACTIVE                   │`);
+    console.log(`│  ○ Claude verify: NOT RUN                   │`);
     } else {
-    console.log(`│  ⚠ Claude Code routing: MANUAL SETUP NEEDED │`);
-    console.log(`│    Set ANTHROPIC_BASE_URL in environment    │`);
+    console.log(`│  ⚠ Claude routing: MANUAL SETUP NEEDED      │`);
+    console.log(`│  Run /plexor-setup after fixing permissions │`);
     }
     console.log(`├─────────────────────────────────────────────┤`);
-    console.log(`│  Run /plexor-status to see your stats.      │`);
+    console.log(`│  Human first-run: /plexor-setup             │`);
+    console.log(`│  Automation complete. Status: /plexor-status│`);
     console.log(`└─────────────────────────────────────────────┘`);
   } catch (err) {
     console.error(`┌─────────────────────────────────────────────┐`);

package/commands/plexor-login.md

@@ -1,5 +1,4 @@
----
-description: Authenticate with Plexor to enable optimization (user)
+description: Advanced/manual Plexor authentication for automation and repair (user)
 ---
 
 **RULE: Execute the bash command below EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT re-execute the command. DO NOT call any other tools.**

package/commands/plexor-logout.js

@@ -90,20 +90,26 @@ function main() {
 
   if (!config || !config.auth?.api_key) {
     console.log(`┌─────────────────────────────────────────────┐`);
-    console.log(`│  Not Logged In                              │`);
+    console.log(`│  Plexor Is Not Active                       │`);
     console.log(`├─────────────────────────────────────────────┤`);
     console.log(`│  No active Plexor session found.            │`);
-    console.log(`│  Run /plexor-login to authenticate.         │`);
+    console.log(`│  Run /plexor-setup to connect Plexor.       │`);
     console.log(`└─────────────────────────────────────────────┘`);
     return;
   }
 
   const clearCache = args.includes('--clear-cache') || args.includes('-c');
+  const currentSettings = settingsManager.load();
+  const hadPriorAuth = Boolean(
+    currentSettings.env?.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY ||
+    currentSettings.env?.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN
+  );
 
   // Clear credentials
   delete config.auth.api_key;
   config.settings = config.settings || {};
   config.settings.enabled = false;
+  delete config.health;
   if (!saveConfig(config)) {
     process.exit(1);
   }
@@ -127,13 +133,14 @@ function main() {
   console.log(`├─────────────────────────────────────────────┤`);
   console.log(`│  ✓ API key removed                          │`);
   console.log(`│  ${routingDisabled ? '✓' : '○'} Claude Code routing disabled             │`);
+  console.log(`│  ${hadPriorAuth ? '✓' : '○'} Prior Claude auth restored                │`);
   console.log(`│  ✓ Session cleared                          │`);
   if (clearCache) {
     console.log(`│  ${cacheCleared ? '✓' : '○'} Cache cleared                            │`);
   }
   console.log(`├─────────────────────────────────────────────┤`);
   console.log(`│  Claude Code now connects directly.         │`);
-  console.log(`│  Run /plexor-login to re-authenticate.      │`);
+  console.log(`│  Run /plexor-setup to reconnect Plexor.     │`);
   if (!clearCache) {
     console.log(`│  Use --clear-cache to also clear cache.     │`);
   }

package/commands/plexor-setup.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { PLEXOR_DIR, CONFIG_PATH, DEFAULT_API_URL } = require('../lib/constants');
+const PlexorClient = require('../lib/plexor-client');
+const { settingsManager } = require('../lib/settings-manager');
+const {
+  EXPECTED_VERIFY_RESPONSE,
+  VERIFY_PROMPT,
+  runClaudeRouteVerification
+} = require('../lib/verify-route');
+
+function isPlexorApiKey(value) {
+  return typeof value === 'string' && value.startsWith('plx_') && value.length >= 20;
+}
+
+function loadConfig() {
+  try {
+    if (!fs.existsSync(CONFIG_PATH)) {
+      return { version: 1, auth: {}, settings: {} };
+    }
+    const data = fs.readFileSync(CONFIG_PATH, 'utf8');
+    if (!data || data.trim() === '') {
+      return { version: 1, auth: {}, settings: {} };
+    }
+    const parsed = JSON.parse(data);
+    if (typeof parsed !== 'object' || parsed === null) {
+      return { version: 1, auth: {}, settings: {} };
+    }
+    return parsed;
+  } catch {
+    return { version: 1, auth: {}, settings: {} };
+  }
+}
+
+function saveConfig(config) {
+  try {
+    if (!fs.existsSync(PLEXOR_DIR)) {
+      fs.mkdirSync(PLEXOR_DIR, { recursive: true, mode: 0o700 });
+    }
+    const tempPath = path.join(PLEXOR_DIR, `.config.${Date.now()}.tmp`);
+    fs.writeFileSync(tempPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    fs.renameSync(tempPath, CONFIG_PATH);
+    return true;
+  } catch (err) {
+    console.error(`Failed to save config: ${err.message}`);
+    return false;
+  }
+}
+
+function readFromStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    const timeout = setTimeout(() => {
+      reject(new Error('Timeout reading from stdin'));
+    }, 5000);
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timeout);
+      resolve(data.trim());
+    });
+    process.stdin.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+    process.stdin.resume();
+  });
+}
+
+function getKeySource(args, existingKey) {
+  if (process.env.PLEXOR_API_KEY) {
+    return { apiKey: process.env.PLEXOR_API_KEY, source: 'environment' };
+  }
+  if (!process.stdin.isTTY && args.length === 0) {
+    return { apiKey: null, source: 'stdin' };
+  }
+  if (args[0] && !args[0].startsWith('--')) {
+    return { apiKey: args[0], source: 'argument' };
+  }
+  if (existingKey) {
+    return { apiKey: existingKey, source: 'saved-config' };
+  }
+  return { apiKey: null, source: null };
+}
+
+function getGatewayLabel(apiUrl) {
+  return apiUrl.includes('staging') ? 'staging' : 'production';
+}
+
+function updateHealth(config, state) {
+  config.health = {
+    installed: true,
+    connected: true,
+    routing_active: state.routingEnabled,
+    verified: state.verifyResult.ok,
+    verified_at: state.verifyResult.ok ? new Date().toISOString() : null,
+    verify_prompt: VERIFY_PROMPT,
+    verify_expected: EXPECTED_VERIFY_RESPONSE,
+    verify_error: state.verifyResult.ok ? null : state.verifyResult.reason,
+    gateway: state.gateway,
+    previous_auth_preserved: state.previousAuthPreserved
+  };
+}
+
+function printUsage() {
+  console.log('Plexor setup is the guided first-run path.');
+  console.log('');
+  console.log('Provide a Plexor API key one of these ways:');
+  console.log('  /plexor-setup plx_...');
+  console.log('  echo "plx_..." | /plexor-setup');
+  console.log('  PLEXOR_API_KEY=plx_... /plexor-setup');
+}
+
+function printReceipt({ user, gateway, previousAuthPreserved, verifyResult }) {
+  const line = (content) => `│  ${String(content).slice(0, 43).padEnd(43)}│`;
+
+  console.log('┌─────────────────────────────────────────────┐');
+  console.log(line('Plexor setup complete'));
+  console.log('├─────────────────────────────────────────────┤');
+  console.log(line(`Connected: OK (${user.email || 'Unknown'})`));
+  console.log(line(`Routing Active: OK (${gateway})`));
+  console.log(line(`Verified: ${verifyResult.ok ? 'OK' : 'FAILED'}`));
+  console.log(line(`Previous Claude auth: ${previousAuthPreserved ? 'Saved' : 'None found'}`));
+  console.log('├─────────────────────────────────────────────┤');
+  if (verifyResult.ok) {
+    console.log(line('Claude is now routed through Plexor'));
+    console.log(line('Logout/uninstall restores prior auth'));
+    console.log(line('Next: Run /plexor-status for health + stats'));
+  } else {
+    console.log(line('Claude routing was configured'));
+    console.log(line('Verification did not pass'));
+    console.log(line('Next: Run /plexor-setup again to repair'));
+  }
+  console.log('└─────────────────────────────────────────────┘');
+
+  if (!verifyResult.ok) {
+    console.log('');
+    console.log(`Verification failed: ${verifyResult.reason}`);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const skipVerify = args.includes('--skip-verify');
+  const config = loadConfig();
+  const existingKey = config.auth?.api_key || '';
+  const keyInput = getKeySource(args.filter(arg => arg !== '--skip-verify'), existingKey);
+  let apiKey = keyInput.apiKey;
+
+  if (!apiKey && keyInput.source === 'stdin') {
+    try {
+      apiKey = await readFromStdin();
+    } catch {
+      apiKey = null;
+    }
+  }
+
+  if (!apiKey) {
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!isPlexorApiKey(apiKey)) {
+    console.error('Error: Plexor API keys must start with "plx_" and be at least 20 characters.');
+    process.exit(1);
+  }
+
+  const apiUrl = config.settings?.apiUrl || DEFAULT_API_URL;
+  const client = new PlexorClient({ apiKey, baseUrl: apiUrl });
+
+  let user;
+  try {
+    user = await client.getUser();
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const updatedConfig = {
+    ...config,
+    version: 1,
+    auth: {
+      ...(config.auth || {}),
+      api_key: apiKey,
+      mode: 'api_key',
+      authenticated_at: new Date().toISOString()
+    },
+    settings: {
+      ...(config.settings || {}),
+      enabled: true,
+      apiUrl,
+      preferred_provider: config.settings?.preferred_provider || 'auto',
+      mode: config.settings?.mode || 'balanced',
+      localCacheEnabled: config.settings?.localCacheEnabled ?? true
+    }
+  };
+
+  if (!saveConfig(updatedConfig)) {
+    process.exit(1);
+  }
+
+  const routingEnabled = settingsManager.enablePlexorRouting(apiKey, {
+    useStaging: apiUrl.includes('staging')
+  });
+
+  if (!routingEnabled) {
+    console.error('Error: Plexor saved your key but could not activate Claude routing.');
+    console.error('Run /plexor-setup again after fixing ~/.claude/settings.json permissions.');
+    process.exit(1);
+  }
+
+  const currentSettings = settingsManager.load();
+  const previousAuthPreserved = Boolean(
+    currentSettings.env?.PLEXOR_PREVIOUS_ANTHROPIC_API_KEY ||
+    currentSettings.env?.PLEXOR_PREVIOUS_ANTHROPIC_AUTH_TOKEN
+  );
+
+  const verifyResult = skipVerify
+    ? { ok: true, reason: '', stdout: EXPECTED_VERIFY_RESPONSE, stderr: '', code: 0 }
+    : runClaudeRouteVerification();
+
+  updateHealth(updatedConfig, {
+    gateway: getGatewayLabel(apiUrl),
+    previousAuthPreserved,
+    routingEnabled,
+    verifyResult
+  });
+
+  if (!saveConfig(updatedConfig)) {
+    process.exit(1);
+  }
+
+  printReceipt({
+    user,
+    gateway: getGatewayLabel(apiUrl),
+    previousAuthPreserved,
+    verifyResult
+  });
+
+  if (!verifyResult.ok) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/commands/plexor-setup.md

@@ -1,177 +1,28 @@
+description: Guided first-run setup for Plexor with Claude Code (user)
 ---
-description: First-time setup wizard for Plexor with Claude Code (user)
----
-
-**RULE: Execute this workflow EXACTLY ONCE. After completing all steps, STOP. DO NOT restart the workflow. DO NOT re-execute any commands. DO NOT call any other tools.**
-
-# Plexor Setup Wizard
-
-Guide users through first-time Plexor setup. **No manual environment variable configuration required!**
-
-The plugin automatically configures `~/.claude/settings.json` to route all Claude Code sessions through Plexor.
 
-## Steps
+**RULE: Execute this workflow EXACTLY ONCE. After the Bash tool returns output, your ONLY action is to present that output to the user. DO NOT restart the workflow.**
 
-**Step 1: Check if already configured**
+Plexor setup is the primary human setup flow.
 
-Use the Read tool to check if `~/.plexor/config.json` exists and has valid configuration.
-Also check `~/.claude/settings.json` for routing status.
+If `$ARGUMENTS` already contains a Plexor API key (`plx_...`), run:
 
-If configured, show:
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-setup.js $ARGUMENTS
 ```
-Plexor Setup
-============
-Already configured!
-
-API URL: [apiUrl from config]
-Mode: [mode from config]
-Status: [Enabled/Disabled]
-Claude Routing: [Active/Inactive]
-
-Run /plexor-status to see your usage.
-Run /plexor-settings to modify configuration.
-Run /plexor-enabled off to disable routing.
-```
-
-**Step 2: Ask about Claude subscription**
 
-Use the AskUserQuestion tool:
+If the user did not provide a key yet, ask them:
 
-Question: "How do you pay for Claude usage?"
-Header: "Billing"
-Options:
-1. **Claude MAX subscription (Pro/Team/Enterprise)** - I have a subscription and want Plexor for optimization & tracking (you'll still need a Plexor API key)
-2. **Pay-per-use via Plexor** - I want Plexor to handle billing and route to the cheapest provider
+`Please paste your Plexor API key (starts with plx_). You can get one at https://plexor.dev/dashboard.`
 
-**Step 3A: Claude MAX User Setup**
+After the user replies with the key, run:
 
-If user selected the "Claude MAX subscription (Pro/Team/Enterprise)" option:
-
-1. Ask for their Plexor API key:
-   "Please provide your Plexor API key (starts with 'plx_')."
-   "Get one at: https://plexor.dev/dashboard"
-   "Your MAX subscription will be used for Claude - the Plexor key is for tracking/optimization."
-
-2. Use the Write tool to create `~/.plexor/config.json`:
-```json
-{
-  "version": 1,
-  "auth": {
-    "api_key": "[user's Plexor key]",
-    "mode": "oauth_passthrough",
-    "authenticated_at": "[current ISO timestamp]"
-  },
-  "settings": {
-    "enabled": true,
-    "apiUrl": "https://staging.api.plexor.dev",
-    "mode": "balanced",
-    "localCacheEnabled": true
-  }
-}
+```bash
+node ~/.claude/plugins/plexor/commands/plexor-setup.js <user_key>
 ```
 
-3. Use the Write tool to update `~/.claude/settings.json` env block:
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://staging.api.plexor.dev/gateway/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]",
-    "ANTHROPIC_API_KEY": "[user's Plexor key]"
-  }
-}
-```
-Note: Preserve unrelated settings, but replace `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, and `ANTHROPIC_API_KEY` in the env block. This is required when the user previously configured Claude with direct API auth.
-
-4. Show the user:
-```
-Plexor Setup - Claude MAX User
-==============================
-Setup Complete! No manual configuration needed.
-
-What was configured:
-- ~/.plexor/config.json (Plexor plugin settings)
-- ~/.claude/settings.json (automatic Claude Code routing)
-
-How it works:
-- All Claude Code sessions now route through Plexor
-- Your MAX subscription OAuth token is passed through
-- You keep your MAX benefits ($0 cost, 20x rate limits)
-- Plexor optimizes prompts and tracks usage
-
-Commands:
-- /plexor-status    - See your usage stats
-- /plexor-enabled off - Temporarily disable Plexor
-- /plexor-enabled on  - Re-enable Plexor
-
-Changes take effect immediately in all Claude Code sessions!
-```
-
-**Step 3B: API Key User Setup**
-
-If user selected the "Pay-per-use via Plexor" option:
-
-1. Ask for their Plexor API key:
-   "Please provide your Plexor API key (starts with 'plx_')."
-   "Get one at: https://plexor.dev/dashboard"
-
-2. Once they provide the key, use the Write tool to create `~/.plexor/config.json`:
-```json
-{
-  "version": 1,
-  "auth": {
-    "api_key": "[user's API key]",
-    "mode": "api_key",
-    "authenticated_at": "[current ISO timestamp]"
-  },
-  "settings": {
-    "enabled": true,
-    "apiUrl": "https://staging.api.plexor.dev",
-    "preferred_provider": "auto",
-    "mode": "balanced",
-    "localCacheEnabled": true
-  }
-}
-```
-
-3. Use the Write tool to update `~/.claude/settings.json` env block:
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://staging.api.plexor.dev/gateway/anthropic",
-    "ANTHROPIC_AUTH_TOKEN": "[user's Plexor key]",
-    "ANTHROPIC_API_KEY": "[user's Plexor key]"
-  }
-}
-```
-Note: Preserve unrelated settings, but replace `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, and `ANTHROPIC_API_KEY` in the env block. This is required when the user previously configured Claude with direct API auth.
-
-4. Show the user:
-```
-Plexor Setup - API Key User
-===========================
-Setup Complete! No manual configuration needed.
-
-What was configured:
-- ~/.plexor/config.json (Plexor plugin settings)
-- ~/.claude/settings.json (automatic Claude Code routing)
-
-How it works:
-- All Claude Code sessions now route through Plexor
-- Plexor picks the best provider (can save up to 90%)
-- Your usage is tracked and optimized
-
-Commands:
-- /plexor-status    - See your usage and savings
-- /plexor-mode eco  - Maximize savings
-- /plexor-mode quality - Maximize quality
-- /plexor-enabled off - Temporarily disable Plexor
-
-Changes take effect immediately in all Claude Code sessions!
-```
-
-**NOTES**:
-- The `~/.claude/settings.json` env block is the KEY mechanism that routes Claude Code through Plexor
-- Set both `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` to the Plexor key so Claude cannot bypass the Plexor gateway with a previously saved direct API key
-- Changes take effect immediately - no shell restart needed
-
-After completing all steps, STOP. DO NOT restart the workflow. DO NOT re-execute any commands.
+This command:
+- saves the Plexor key
+- routes Claude through the Plexor staging gateway
+- preserves prior direct Claude auth for restore on logout/uninstall
+- runs a deterministic Claude verification step

package/commands/plexor-status.js

@@ -170,11 +170,30 @@ function checkStateMismatch(configEnabled, routingActive) {
   return null;
 }
 
+function printHealthSummary(summary) {
+  const line = (content) => `  │  ${String(content).slice(0, 43).padEnd(43)}│`;
+  console.log(`  ┌─────────────────────────────────────────────┐`);
+  console.log(line('Plexor health'));
+  console.log(`  ├─────────────────────────────────────────────┤`);
+  console.log(line(`Installed: ${summary.installed}`));
+  console.log(line(`Connected: ${summary.connected}`));
+  console.log(line(`Routing Active: ${summary.routing}`));
+  console.log(line(`Verified: ${summary.verified}`));
+  console.log(line(`Next action: ${summary.nextAction}`));
+  console.log(`  └─────────────────────────────────────────────┘`);
+}
+
 async function main() {
   // Read config with integrity checking
   const config = loadConfig();
   if (!config) {
-    console.log('Not configured. Run /plexor-setup.');
+    printHealthSummary({
+      installed: 'Missing',
+      connected: 'Not connected',
+      routing: 'Inactive',
+      verified: 'Not run',
+      nextAction: 'Run /plexor-setup'
+    });
     process.exit(1);
   }
 
@@ -184,28 +203,42 @@ async function main() {
   const provider = config.settings?.preferred_provider || 'auto';
   const localCache = config.settings?.localCacheEnabled ?? false;
   const apiUrl = config.settings?.apiUrl || 'https://api.plexor.dev';
+  const verification = config.health || {};
 
   if (!apiKey) {
-    console.log('Not authenticated. Run /plexor-setup.');
+    printHealthSummary({
+      installed: 'OK',
+      connected: 'Missing key',
+      routing: 'Inactive',
+      verified: 'Not run',
+      nextAction: 'Run /plexor-setup'
+    });
     process.exit(1);
   }
 
   // Validate API key format
   if (!isValidApiKeyFormat(apiKey)) {
-    console.log('Invalid API key format. Keys must start with "plx_" and be at least 20 characters.');
-    console.log('Run /plexor-setup with a valid Plexor API key.');
+    printHealthSummary({
+      installed: 'OK',
+      connected: 'Invalid key',
+      routing: 'Needs repair',
+      verified: 'Failed',
+      nextAction: 'Run /plexor-setup'
+    });
     process.exit(1);
   }
 
   // Fetch user info and stats
   let user = { email: 'Unknown', tier: { name: 'Free', limits: {} } };
   let stats = { period: {}, summary: {} };
+  let userFetchWorked = false;
 
   try {
     [user, stats] = await Promise.all([
       fetchJson(apiUrl, '/v1/user', apiKey),
       fetchJson(apiUrl, '/v1/stats', apiKey)
     ]);
+    userFetchWorked = true;
   } catch (err) {
     // Continue with defaults if API fails
   }
@@ -289,20 +322,34 @@ ${line(`└── Cost saved: $${sessionCostSaved}`)}
   const routing = getRoutingStatus();
   const routingIndicator = routing.active ? '🟢 PLEXOR MODE: ON' : '🔴 PLEXOR MODE: OFF';
   const envLabel = routing.isStaging ? '(staging)' : '(production)';
+  const partialState = detectPartialState();
+  const stateMismatch = checkStateMismatch(enabled, routing.active);
+  const connectedState = userFetchWorked ? 'OK' : 'Unknown';
+  const verifiedState = verification.verified
+    ? 'OK'
+    : (verification.verify_error ? 'Failed' : 'Not yet');
+  const nextAction = !routing.active || partialState.partial || stateMismatch || !verification.verified
+    ? '/plexor-setup'
+    : '/plexor-status';
 
   // Note: Environment mismatch warning removed - it caused false positives during
   // concurrent operations and transient states. The partial state and config/routing
   // mismatch warnings below provide more actionable feedback.
 
-  // Check for partial routing state (Plexor URL without valid auth)
-  const partialState = detectPartialState();
+  printHealthSummary({
+    installed: 'OK',
+    connected: connectedState,
+    routing: routing.active ? `OK ${envLabel}` : 'Needs repair',
+    verified: verifiedState,
+    nextAction
+  });
+  console.log('');
   if (partialState.partial) {
     console.log(`  ⚠ PARTIAL STATE DETECTED: ${partialState.issue}`);
     console.log(`    Run /plexor-setup to repair, or /plexor-logout to disable routing\n`);
   }
 
   // Check for state mismatch between config enabled flag and routing status
-  const stateMismatch = checkStateMismatch(enabled, routing.active);
   if (stateMismatch) {
     console.log(`  ⚠ State mismatch: ${stateMismatch.message}`);
     console.log(`  └─ ${stateMismatch.suggestion}\n`);

package/lib/settings-manager.js

@@ -416,7 +416,7 @@ class ClaudeSettingsManager {
       const settings = this.load();
 
       if (!settings.env?.ANTHROPIC_BASE_URL) {
-        console.log('Plexor routing is not enabled. Run /plexor-login first.');
+        console.log('Plexor routing is not enabled. Run /plexor-setup first.');
         return false;
       }
 

package/lib/verify-route.js

@@ -0,0 +1,77 @@
+const { spawnSync } = require('child_process');
+const { HOME_DIR } = require('./constants');
+
+const VERIFY_PROMPT = 'Reply with exactly PONG. Do not use tools.';
+const EXPECTED_VERIFY_RESPONSE = 'PONG';
+
+function normalizeVerifyOutput(output = '') {
+  return String(output).trim();
+}
+
+function interpretVerifyResult(result = {}) {
+  const stdout = normalizeVerifyOutput(result.stdout);
+  const stderr = normalizeVerifyOutput(result.stderr);
+
+  if (result.error) {
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      code: null,
+      reason: result.error.message || 'Claude verification failed to start'
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      code: result.status,
+      reason: stderr || stdout || `Claude exited with status ${result.status}`
+    };
+  }
+
+  if (stdout !== EXPECTED_VERIFY_RESPONSE) {
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      code: result.status,
+      reason: `Expected "${EXPECTED_VERIFY_RESPONSE}" but received "${stdout || '(empty)'}"`
+    };
+  }
+
+  return {
+    ok: true,
+    stdout,
+    stderr,
+    code: result.status,
+    reason: ''
+  };
+}
+
+function runClaudeRouteVerification(options = {}, runCommand = spawnSync) {
+  const result = runCommand(options.claudeCommand || 'claude', [
+    '-p',
+    '--tools', '',
+    '--output-format', 'text',
+    VERIFY_PROMPT
+  ], {
+    cwd: options.cwd || HOME_DIR,
+    env: options.env || process.env,
+    encoding: 'utf8',
+    timeout: options.timeoutMs || 30000,
+    maxBuffer: 1024 * 1024
+  });
+
+  return interpretVerifyResult(result);
+}
+
+module.exports = {
+  EXPECTED_VERIFY_RESPONSE,
+  VERIFY_PROMPT,
+  interpretVerifyResult,
+  normalizeVerifyOutput,
+  runClaudeRouteVerification
+};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@plexor-dev/claude-code-plugin-staging",
-  "version": "0.1.0-beta.19",
+  "version": "0.1.0-beta.20",
   "description": "STAGING - LLM cost optimization plugin for Claude Code (internal testing)",
   "main": "lib/constants.js",
   "bin": {
     "plexor-status": "./commands/plexor-status.js",
+    "plexor-setup": "./commands/plexor-setup.js",
     "plexor-enabled": "./commands/plexor-enabled.js",
     "plexor-login": "./commands/plexor-login.js",
     "plexor-logout": "./commands/plexor-logout.js",

package/scripts/postinstall.js

@@ -437,7 +437,8 @@ function main() {
     console.log('    1. Ask for your Plexor API key');
     console.log('    2. Write ~/.plexor/config.json');
     console.log('    3. Point Claude at the Plexor staging gateway');
-    console.log('    4. Replace any existing Claude API env auth while Plexor is active');
+    console.log('    4. Preserve prior Claude auth for restore on logout');
+    console.log('    5. Verify Claude routing with a deterministic check');
     console.log('');
     console.log('  ┌─────────────────────────────────────────────────────────────────┐');
     console.log('  │  No shell edits or Claude restart required after setup        │');
@@ -445,7 +446,7 @@ function main() {
     console.log('');
     console.log('  Available commands:');
     console.log('    /plexor-setup    - First-time setup wizard');
-    console.log('    /plexor-login    - Authenticate with API key');
+    console.log('    /plexor-login    - Advanced/manual auth path');
     console.log('    /plexor-status   - Check connection and see savings');
     console.log('    /plexor-enabled  - Enable/disable Plexor routing');
     console.log('');