ruvnet-kb-first 6.1.0 → 6.3.0

package/SKILL.md

@@ -1,13 +1,51 @@
-Updated: 2026-01-02 10:15:00 EST | Version 6.0.0
+Updated: 2026-01-02 10:35:00 EST | Version 6.2.0
 Created: 2026-01-01 15:00:00 EST
 
-# RuvNet KB-First Application Builder v6.0
+# RuvNet KB-First Application Builder v6.2
 
-## Score-Driven Architecture: Scoring IS Enforcement
+## Score-Driven Architecture: Scoring IS Enforcement + UX Excellence
 
-**Version:** 6.0.0
+**Version:** 6.2.0
 **NPM Package:** `ruvnet-kb-first`
-**Philosophy:** Every operation requires baseline scoring. Every change shows delta. Negative delta BLOCKS progress. No shortcuts.
+**Philosophy:** Every operation requires baseline scoring. Every change shows delta. Negative delta BLOCKS progress. No shortcuts. **NEW:** Applications must be excellent, not just functional.
+
+---
+
+## What's New in v6.2.0 - UX Excellence
+
+| Feature | Description |
+|---------|-------------|
+| **UX Quality Dimension** | 7th KB dimension: Visual design, emotional appeal, user flow |
+| **Phase 12: UX Quality Review** | Playwright-based end-user perspective audit |
+| **`kb_first_ux_review` Tool** | Captures screenshots, checks versioning, critical review |
+| **Version Display Check** | Verifies version in header/footer (major.minor.patch) |
+| **Cache-Busting Check** | Ensures users see latest version, not cached content |
+| **Critical Review Questions** | How good? How could it be better? Where falling down? What would excellent look like? |
+| **Playwright Auto-Install** | Offers to install Playwright if not present |
+
+### The 6 MCP Tools (v6.2)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `kb_first_assess` | Score ALL dimensions (7 KB + 13 Phases) | **FIRST** - before any work |
+| `kb_first_plan` | Generate enhancement plan with predictions | After assess, shows gaps |
+| `kb_first_confirm` | User confirms readiness to proceed | Before execution |
+| `kb_first_execute` | Execute plan phase by phase | After confirmation |
+| `kb_first_verify` | Compare predicted vs actual, recursive until 98+ | After execution |
+| `kb_first_ux_review` | Playwright-based visual quality audit | **NEW** - for UX excellence |
+
+### UX Quality Criteria (Scored in UX Review)
+
+| Criterion | Weight | Checks |
+|-----------|--------|--------|
+| Version Display | 15% | Header/footer shows major.minor.patch |
+| Cache Management | 10% | Version change detection, user notification |
+| Visual Design Excellence | 20% | Typography, color, spacing, not generic AI look |
+| Emotional Appeal | 15% | Creates confidence, celebrates success, softens errors |
+| Loading States | 10% | Skeleton loaders, progress indicators, graceful |
+| Error Handling UX | 10% | Clear messages, actionable, no technical jargon |
+| User Flow | 10% | Intuitive navigation, clear CTAs, minimal friction |
+| Accessibility | 10% | Keyboard nav, screen reader, contrast, focus |
 
 ---
 
@@ -22,7 +60,7 @@ Created: 2026-01-01 15:00:00 EST
 | **Baseline Requirement** | Cannot start work without establishing baseline |
 | **Automatic Refresh** | Baseline resets after each gate passage |
 
-### The 4 MCP Tools
+### The Original 4 MCP Tools (v6.0)
 
 | Tool | Purpose | When to Use |
 |------|---------|-------------|

package/bin/kb-first.js

@@ -58,6 +58,9 @@ program
   .option('-f, --force', 'Overwrite existing configuration')
   .option('-t, --template <type>', 'Template type (basic, api, fullstack)', 'basic')
   .option('--no-hooks', 'Skip hook installation')
+  .option('--kb <schema>', 'Connect to existing KB schema (e.g., ask_ruvnet)')
+  .option('--kb-host <host>', 'KB database host', 'localhost')
+  .option('--kb-port <port>', 'KB database port', '5435')
   .action(initCommand);
 
 // Score command
@@ -113,11 +116,11 @@ program
     await startMCPServer(options);
   });
 
-// Parse arguments
-program.parse();
-
-// Show help if no command provided
+// Show dashboard if no command provided (before parsing)
 if (!process.argv.slice(2).length) {
-  console.log(banner);
-  program.outputHelp();
+  const { dashboardCommand } = await import('../src/commands/dashboard.js');
+  await dashboardCommand();
+} else {
+  // Parse arguments
+  program.parse();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-kb-first",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "RuvNet KB-First Application Builder - Build intelligent applications on expert knowledge",
   "type": "module",
   "main": "src/index.js",
@@ -56,19 +56,19 @@
     "glob": "^10.3.0",
     "inquirer": "^9.2.0",
     "ora": "^8.0.0",
-    "pg": "^8.11.3",
+    "pg": "^8.16.3",
     "ruv-swarm": "^1.0.20",
     "ruvector": "^0.1.82"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.11",
     "@types/node": "^20.10.0",
     "@types/pg": "^8.10.9",
-    "typescript": "^5.3.0",
-    "eslint": "^8.55.0",
     "@typescript-eslint/eslint-plugin": "^6.13.0",
     "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.55.0",
     "jest": "^29.7.0",
-    "@types/jest": "^29.5.11"
+    "typescript": "^5.3.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/commands/dashboard.js

@@ -0,0 +1,359 @@
+/**
+ * RuvNet-KB-First Dashboard
+ *
+ * Shows comprehensive status when running `ruvnet-kb-first` with no arguments.
+ * Displays KB metrics, application scores, and actionable recommendations.
+ */
+
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { globSync } from 'glob';
+
+export async function dashboardCommand() {
+  const cwd = process.cwd();
+  const projectName = cwd.split('/').pop();
+
+  // Banner
+  console.log('');
+  console.log(chalk.cyan('╔════════════════════════════════════════════════════════════════════════╗'));
+  console.log(chalk.cyan('║') + chalk.bold.white('                      RuvNet-KB-First Dashboard                        ') + chalk.cyan('║'));
+  console.log(chalk.cyan('║') + chalk.gray('                Build intelligent applications on expert knowledge        ') + chalk.cyan('║'));
+  console.log(chalk.cyan('╚════════════════════════════════════════════════════════════════════════╝'));
+  console.log('');
+
+  // Check if initialized
+  const configPath = join(cwd, '.ruvector', 'config.json');
+  if (!existsSync(configPath)) {
+    console.log(chalk.yellow('  ⚠ Not initialized in this directory'));
+    console.log('');
+    console.log(chalk.white('  Quick Start:'));
+    console.log(chalk.cyan('    ruvnet-kb-first init --kb ask_ruvnet'));
+    console.log('');
+    console.log(chalk.gray('  This will:'));
+    console.log(chalk.gray('    • Connect to the RuvNet Knowledge Base (230K+ entries)'));
+    console.log(chalk.gray('    • Set up hooks to enforce KB-first development'));
+    console.log(chalk.gray('    • Enable comprehensive scoring for your application'));
+    console.log('');
+    return;
+  }
+
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECTION 1: KNOWLEDGE BASE STATUS
+  // ═══════════════════════════════════════════════════════════════════════════
+  console.log(chalk.white.bold('  📚 KNOWLEDGE BASE'));
+  console.log(chalk.gray('  ────────────────────────────────────────────────────────────────────'));
+
+  if (config.knowledgeBase?.connected) {
+    let kbStats = {
+      entries: config.knowledgeBase.entries,
+      isLive: false,
+      categories: 0,
+      avgEmbeddingSize: 0
+    };
+
+    // Try to get live stats
+    try {
+      const pg = await import('pg');
+      const client = new pg.default.Client({
+        host: config.knowledgeBase.host,
+        port: config.knowledgeBase.port,
+        database: 'postgres',
+        user: 'postgres',
+        password: 'guruKB2025'
+      });
+      await client.connect();
+
+      // Entry count
+      const countResult = await client.query(
+        `SELECT COUNT(*) as count FROM ${config.knowledgeBase.schema}.architecture_docs`
+      );
+      kbStats.entries = parseInt(countResult.rows[0].count);
+      kbStats.isLive = true;
+
+      // Get category count (if source column exists)
+      try {
+        const catResult = await client.query(
+          `SELECT COUNT(DISTINCT source) as cats FROM ${config.knowledgeBase.schema}.architecture_docs`
+        );
+        kbStats.categories = parseInt(catResult.rows[0].cats);
+      } catch (e) {
+        // Ignore if source column doesn't exist
+      }
+
+      await client.end();
+    } catch (e) {
+      // Use cached values
+    }
+
+    const statusIcon = kbStats.isLive ? chalk.green('●') : chalk.yellow('○');
+    const statusText = kbStats.isLive ? chalk.green('CONNECTED') : chalk.yellow('CACHED');
+
+    console.log(`  ${statusIcon} Status:    ${statusText}`);
+    console.log(`    Schema:    ${chalk.cyan(config.knowledgeBase.schema)}`);
+    console.log(`    Entries:   ${chalk.cyan(kbStats.entries.toLocaleString())}`);
+    if (kbStats.categories > 0) {
+      console.log(`    Sources:   ${chalk.cyan(kbStats.categories)}`);
+    }
+    console.log(`    Host:      ${chalk.gray(config.knowledgeBase.host + ':' + config.knowledgeBase.port)}`);
+
+    // KB Score (out of 100)
+    const kbScore = calculateKBScore(kbStats);
+    console.log('');
+    console.log(`    ${chalk.white('KB Health Score:')} ${renderScoreBar(kbScore)} ${colorScore(kbScore)}/100`);
+
+  } else {
+    console.log(chalk.red('  ○ Status:    NOT CONNECTED'));
+    console.log('');
+    console.log(chalk.yellow('    Run: ruvnet-kb-first init --kb ask_ruvnet'));
+  }
+
+  console.log('');
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECTION 2: APPLICATION SCORES
+  // ═══════════════════════════════════════════════════════════════════════════
+  console.log(chalk.white.bold('  📊 APPLICATION SCORES'));
+  console.log(chalk.gray('  ────────────────────────────────────────────────────────────────────'));
+
+  const scores = await calculateAllScores(cwd, config);
+
+  // Display each score category
+  for (const [category, data] of Object.entries(scores)) {
+    const label = formatLabel(category).padEnd(18);
+    const bar = renderScoreBar(data.percentage);
+    const scoreText = colorScore(data.percentage);
+    console.log(`    ${label} ${bar} ${scoreText.padStart(4)}/100  ${chalk.gray(data.summary)}`);
+  }
+
+  // Total Score
+  const totalScore = Math.round(
+    Object.values(scores).reduce((sum, s) => sum + s.percentage, 0) / Object.keys(scores).length
+  );
+
+  console.log('');
+  console.log(chalk.gray('  ────────────────────────────────────────────────────────────────────'));
+  const totalBar = renderScoreBar(totalScore);
+  console.log(`    ${chalk.bold('OVERALL SCORE')}     ${totalBar} ${colorScore(totalScore).padStart(4)}/100  ${getGrade(totalScore)}`);
+  console.log('');
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECTION 3: PROJECT INFO
+  // ═══════════════════════════════════════════════════════════════════════════
+  console.log(chalk.white.bold('  📁 PROJECT'));
+  console.log(chalk.gray('  ────────────────────────────────────────────────────────────────────'));
+  console.log(`    Name:      ${chalk.cyan(projectName)}`);
+  console.log(`    Namespace: ${chalk.cyan(config.kbFirst?.namespace || 'not set')}`);
+  console.log(`    Phase:     ${chalk.cyan(config.phases?.current || 0)}/11`);
+  console.log(`    Hooks:     ${config.hooks?.enabled ? chalk.green('Enabled') : chalk.red('Disabled')}`);
+  console.log('');
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECTION 4: RECOMMENDATIONS
+  // ═══════════════════════════════════════════════════════════════════════════
+  const recommendations = getRecommendations(scores, config);
+
+  if (recommendations.length > 0) {
+    console.log(chalk.white.bold('  💡 RECOMMENDATIONS'));
+    console.log(chalk.gray('  ────────────────────────────────────────────────────────────────────'));
+    for (const rec of recommendations.slice(0, 5)) {
+      console.log(chalk.yellow(`    → ${rec}`));
+    }
+    console.log('');
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECTION 5: COMMANDS
+  // ═══════════════════════════════════════════════════════════════════════════
+  console.log(chalk.white.bold('  ⌨️  COMMANDS'));
+  console.log(chalk.gray('  ────────────────────────────────────────────────────────────────────'));
+  console.log(chalk.cyan('    ruvnet-kb-first score --detailed') + chalk.gray('   Full score breakdown'));
+  console.log(chalk.cyan('    ruvnet-kb-first status --detailed') + chalk.gray('  Detailed project status'));
+  console.log(chalk.cyan('    ruvnet-kb-first verify') + chalk.gray('             Run verification checks'));
+  console.log(chalk.cyan('    ruvnet-kb-first phase <n>') + chalk.gray('          Execute build phase'));
+  console.log('');
+
+  // Final prompt
+  if (config.knowledgeBase?.connected) {
+    console.log(chalk.gray('  Ask Claude: "Review this app using RuvNet-KB-First and recommend improvements"'));
+  }
+  console.log('');
+}
+
+function calculateKBScore(stats) {
+  let score = 0;
+
+  // Connection (30 points)
+  if (stats.isLive) score += 30;
+  else score += 15;
+
+  // Entry count (50 points)
+  if (stats.entries >= 100000) score += 50;
+  else if (stats.entries >= 50000) score += 40;
+  else if (stats.entries >= 10000) score += 30;
+  else if (stats.entries >= 1000) score += 20;
+  else score += 10;
+
+  // Categories (20 points)
+  if (stats.categories >= 50) score += 20;
+  else if (stats.categories >= 20) score += 15;
+  else if (stats.categories >= 10) score += 10;
+  else score += 5;
+
+  return Math.min(score, 100);
+}
+
+async function calculateAllScores(cwd, config) {
+  const scores = {};
+
+  // 1. KB Coverage
+  const srcDir = join(cwd, 'src');
+  let kbCoverage = { percentage: 100, summary: 'No code yet' };
+  if (existsSync(srcDir)) {
+    const codeFiles = globSync('**/*.{ts,tsx,js,jsx,py}', { cwd: srcDir });
+    if (codeFiles.length > 0) {
+      let withCitation = 0;
+      for (const file of codeFiles) {
+        const content = readFileSync(join(srcDir, file), 'utf-8');
+        if (content.includes('KB-Generated:') || content.includes('Sources:')) {
+          withCitation++;
+        }
+      }
+      const pct = Math.round((withCitation / codeFiles.length) * 100);
+      kbCoverage = { percentage: pct, summary: `${withCitation}/${codeFiles.length} files` };
+    }
+  }
+  scores.kbCoverage = kbCoverage;
+
+  // 2. Phase Progress
+  const completed = config.phases?.completed?.length || 0;
+  const phasePct = Math.round((completed / 12) * 100);
+  scores.phaseProgress = { percentage: phasePct, summary: `${completed}/12 complete` };
+
+  // 3. Hook Compliance
+  let hookPct = 0;
+  if (config.hooks?.enabled) {
+    const hooksDir = join(cwd, '.ruvector', 'hooks');
+    let found = 0;
+    if (existsSync(join(hooksDir, 'pre-tool-use.py'))) found++;
+    if (existsSync(join(hooksDir, 'post-tool-use.py'))) found++;
+    hookPct = found === 2 ? 100 : (found === 1 ? 50 : 0);
+  }
+  scores.hooks = { percentage: hookPct, summary: hookPct === 100 ? 'All installed' : 'Incomplete' };
+
+  // 4. KB Gaps
+  const gapPath = join(cwd, '.ruvector', 'gaps.jsonl');
+  let gapPct = 100;
+  let gapSummary = 'No gaps';
+  if (existsSync(gapPath)) {
+    const content = readFileSync(gapPath, 'utf-8').trim();
+    if (content) {
+      const gaps = content.split('\n').length;
+      gapPct = Math.max(0, 100 - (gaps * 10));
+      gapSummary = `${gaps} unresolved`;
+    }
+  }
+  scores.kbGaps = { percentage: gapPct, summary: gapSummary };
+
+  // 5. Documentation
+  let docScore = 0;
+  if (existsSync(join(cwd, 'README.md'))) docScore += 40;
+  if (existsSync(join(cwd, 'docs', 'api.md'))) docScore += 30;
+  if (existsSync(join(cwd, 'docs', 'architecture.md'))) docScore += 30;
+  scores.documentation = { percentage: docScore, summary: docScore === 100 ? 'Complete' : 'Incomplete' };
+
+  // 6. Security
+  let secScore = 100;
+  const gitignore = join(cwd, '.gitignore');
+  if (!existsSync(gitignore)) {
+    secScore -= 30;
+  } else {
+    const content = readFileSync(gitignore, 'utf-8');
+    if (!content.includes('.env')) secScore -= 20;
+  }
+  if (!existsSync(join(cwd, 'package-lock.json')) && existsSync(join(cwd, 'package.json'))) {
+    secScore -= 20;
+  }
+  scores.security = { percentage: Math.max(0, secScore), summary: secScore === 100 ? 'Passed' : 'Issues found' };
+
+  return scores;
+}
+
+function renderScoreBar(percentage) {
+  const filled = Math.round(percentage / 5);
+  const empty = 20 - filled;
+  const color = percentage >= 80 ? chalk.green :
+               percentage >= 60 ? chalk.yellow :
+               percentage >= 40 ? chalk.hex('#FFA500') :
+               chalk.red;
+  return color('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
+}
+
+function colorScore(score) {
+  const color = score >= 80 ? chalk.green :
+               score >= 60 ? chalk.yellow :
+               score >= 40 ? chalk.hex('#FFA500') :
+               chalk.red;
+  return color(score.toString());
+}
+
+function formatLabel(key) {
+  const labels = {
+    kbCoverage: 'KB Coverage',
+    phaseProgress: 'Phase Progress',
+    hooks: 'Hooks',
+    kbGaps: 'KB Gaps',
+    documentation: 'Documentation',
+    security: 'Security'
+  };
+  return labels[key] || key;
+}
+
+function getGrade(score) {
+  if (score >= 95) return chalk.green.bold('A+');
+  if (score >= 90) return chalk.green.bold('A');
+  if (score >= 85) return chalk.green('A-');
+  if (score >= 80) return chalk.yellow.bold('B+');
+  if (score >= 75) return chalk.yellow('B');
+  if (score >= 70) return chalk.yellow('B-');
+  if (score >= 65) return chalk.hex('#FFA500')('C+');
+  if (score >= 60) return chalk.hex('#FFA500')('C');
+  if (score >= 55) return chalk.hex('#FFA500')('C-');
+  return chalk.red.bold('F');
+}
+
+function getRecommendations(scores, config) {
+  const recs = [];
+
+  if (!config.knowledgeBase?.connected) {
+    recs.push('Connect to KB: ruvnet-kb-first init --kb ask_ruvnet --force');
+  }
+
+  if (scores.kbCoverage.percentage < 80) {
+    recs.push('Add KB citations to code files (use kb_code_gen before writing)');
+  }
+
+  if (scores.phaseProgress.percentage < 50) {
+    recs.push(`Complete build phases: ruvnet-kb-first phase ${config.phases?.current || 0}`);
+  }
+
+  if (scores.hooks.percentage < 100) {
+    recs.push('Install enforcement hooks: ruvnet-kb-first hooks --install');
+  }
+
+  if (scores.kbGaps.percentage < 100) {
+    recs.push('Resolve KB gaps logged in .ruvector/gaps.jsonl');
+  }
+
+  if (scores.documentation.percentage < 100) {
+    recs.push('Add documentation: README.md, docs/api.md, docs/architecture.md');
+  }
+
+  if (scores.security.percentage < 100) {
+    recs.push('Fix security issues: ruvnet-kb-first verify --phase=9');
+  }
+
+  return recs;
+}

package/src/commands/init.js

@@ -14,6 +14,22 @@ import inquirer from 'inquirer';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// Known KB schemas with descriptions
+const KNOWN_KB_SCHEMAS = {
+  'ask_ruvnet': {
+    description: 'RuvNet comprehensive knowledge base (230K+ entries)',
+    path: '/Users/stuartkerr/Code/Ask-Ruvnet'
+  },
+  'retirewell': {
+    description: 'Retirement planning knowledge base',
+    path: '/Users/stuartkerr/Code/RetireWell'
+  },
+  'presentermode': {
+    description: 'Presentation and public speaking knowledge',
+    path: null
+  }
+};
+
 // Project structure template
 const PROJECT_STRUCTURE = {
   directories: [
@@ -30,12 +46,21 @@ const PROJECT_STRUCTURE = {
   files: {
     '.ruvector/config.json': {
       kbFirst: {
-        version: '5.0.0',
+        version: '6.2.0',
         initialized: new Date().toISOString(),
         namespace: '',
         minConfidence: 0.5,
         gapLogging: true
       },
+      knowledgeBase: {
+        schema: null,
+        host: 'localhost',
+        port: 5435,
+        database: 'postgres',
+        table: 'architecture_docs',
+        entries: 0,
+        connected: false
+      },
       hooks: {
         enabled: true,
         preToolUse: true,
@@ -55,7 +80,7 @@ export async function initCommand(options) {
   const projectName = cwd.split('/').pop().toLowerCase().replace(/[^a-z0-9]/g, '_');
 
   console.log('');
-  console.log(chalk.cyan('Initializing KB-First project structure...'));
+  console.log(chalk.cyan('Initializing RuvNet-KB-First project structure...'));
   console.log('');
 
   // Check if already initialized
@@ -67,14 +92,42 @@ export async function initCommand(options) {
   }
 
   // Interactive prompts if not forcing
-  let config = { ...PROJECT_STRUCTURE.files['.ruvector/config.json'] };
+  let config = JSON.parse(JSON.stringify(PROJECT_STRUCTURE.files['.ruvector/config.json']));
+  config.kbFirst.initialized = new Date().toISOString();
+
+  // Handle --kb flag for connecting to existing KB
+  let kbSchema = options.kb;
+  const kbHost = options.kbHost || 'localhost';
+  const kbPort = options.kbPort || '5435';
+
+  if (!options.force && !kbSchema) {
+    // Show available KBs if not specified
+    const kbChoices = [
+      { name: 'None - Create new KB for this project', value: null },
+      ...Object.entries(KNOWN_KB_SCHEMAS).map(([schema, info]) => ({
+        name: `${schema} - ${info.description}`,
+        value: schema
+      })),
+      { name: 'Other - Enter custom schema name', value: '__custom__' }
+    ];
 
-  if (!options.force) {
     const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'kbSchema',
+        message: 'Connect to existing Knowledge Base?',
+        choices: kbChoices
+      },
+      {
+        type: 'input',
+        name: 'customSchema',
+        message: 'Enter KB schema name:',
+        when: (answers) => answers.kbSchema === '__custom__'
+      },
       {
         type: 'input',
         name: 'namespace',
-        message: 'KB namespace (leave empty for project name):',
+        message: 'Project namespace (for new content):',
         default: projectName
       },
       {
@@ -96,12 +149,74 @@ export async function initCommand(options) {
       }
     ]);
 
+    kbSchema = answers.kbSchema === '__custom__' ? answers.customSchema : answers.kbSchema;
     config.kbFirst.namespace = answers.namespace || projectName;
     config.hooks.enabled = answers.installHooks;
   } else {
     config.kbFirst.namespace = projectName;
   }
 
+  // Connect to KB if specified
+  if (kbSchema) {
+    const spinner = ora(`Connecting to KB schema: ${kbSchema}...`).start();
+
+    try {
+      const pg = await import('pg');
+      const client = new pg.default.Client({
+        host: kbHost,
+        port: parseInt(kbPort),
+        database: 'postgres',
+        user: 'postgres',
+        password: 'guruKB2025'
+      });
+
+      await client.connect();
+
+      // Check if schema exists and count entries
+      const schemaCheck = await client.query(
+        `SELECT COUNT(*) as count FROM information_schema.schemata WHERE schema_name = $1`,
+        [kbSchema]
+      );
+
+      if (schemaCheck.rows[0].count === '0') {
+        spinner.fail(`KB schema '${kbSchema}' not found`);
+        await client.end();
+        console.log(chalk.yellow('\nAvailable schemas:'));
+        Object.entries(KNOWN_KB_SCHEMAS).forEach(([name, info]) => {
+          console.log(chalk.gray(`  ${name} - ${info.description}`));
+        });
+        return;
+      }
+
+      // Count entries
+      const countResult = await client.query(
+        `SELECT COUNT(*) as count FROM ${kbSchema}.architecture_docs`
+      );
+      const entryCount = parseInt(countResult.rows[0].count);
+
+      await client.end();
+
+      // Update config with KB connection
+      config.knowledgeBase = {
+        schema: kbSchema,
+        host: kbHost,
+        port: parseInt(kbPort),
+        database: 'postgres',
+        table: 'architecture_docs',
+        entries: entryCount,
+        connected: true,
+        connectedAt: new Date().toISOString()
+      };
+
+      spinner.succeed(`Connected to KB: ${kbSchema} (${entryCount.toLocaleString()} entries)`);
+
+    } catch (err) {
+      spinner.fail(`Failed to connect to KB: ${err.message}`);
+      console.log(chalk.yellow('\nMake sure the ruvector-kb container is running:'));
+      console.log(chalk.gray('  docker ps | grep ruvector-kb'));
+    }
+  }
+
   // Create directories
   const spinner = ora('Creating directory structure...').start();
 
@@ -192,8 +307,18 @@ export async function initCommand(options) {
 
   // Summary
   console.log('');
-  console.log(chalk.green('KB-First project initialized successfully!'));
+  console.log(chalk.green('RuvNet-KB-First project initialized successfully!'));
   console.log('');
+
+  // Show KB connection status
+  if (config.knowledgeBase.connected) {
+    console.log(chalk.white('Knowledge Base:'));
+    console.log(chalk.green(`  ✓ Connected to: ${config.knowledgeBase.schema}`));
+    console.log(chalk.gray(`    ${config.knowledgeBase.entries.toLocaleString()} entries available`));
+    console.log(chalk.gray(`    Host: ${config.knowledgeBase.host}:${config.knowledgeBase.port}`));
+    console.log('');
+  }
+
   console.log(chalk.white('Project structure:'));
   console.log(chalk.gray('  .ruvector/         - KB configuration and hooks'));
   console.log(chalk.gray('  src/kb/            - Knowledge base modules'));
@@ -201,9 +326,13 @@ export async function initCommand(options) {
   console.log(chalk.gray('  scripts/           - Verification scripts'));
   console.log('');
   console.log(chalk.white('Next steps:'));
-  console.log(chalk.cyan('  1. Run: kb-first status'));
-  console.log(chalk.cyan('  2. Start Phase 0: kb-first phase 0'));
-  console.log(chalk.cyan('  3. Build your KB in src/kb/'));
+  console.log(chalk.cyan('  1. Run: npx ruvnet-kb-first status'));
+  console.log(chalk.cyan('  2. Start Phase 0: npx ruvnet-kb-first phase 0'));
+  if (config.knowledgeBase.connected) {
+    console.log(chalk.cyan('  3. Ask Claude: "Review this app using RuvNet-KB-First and recommend improvements"'));
+  } else {
+    console.log(chalk.cyan('  3. Build your KB in src/kb/'));
+  }
   console.log('');
 }
 

package/src/commands/status.js

@@ -31,22 +31,70 @@ export async function statusCommand(options) {
 
   console.log('');
   console.log(chalk.cyan('╔═══════════════════════════════════════════════════════════════╗'));
-  console.log(chalk.cyan('║') + chalk.bold.white('                    KB-First Project Status                   ') + chalk.cyan('║'));
+  console.log(chalk.cyan('║') + chalk.bold.white('                 RuvNet-KB-First Project Status                ') + chalk.cyan('║'));
   console.log(chalk.cyan('╚═══════════════════════════════════════════════════════════════╝'));
   console.log('');
 
   // Check if initialized
   const configPath = join(cwd, '.ruvector', 'config.json');
   if (!existsSync(configPath)) {
-    console.log(chalk.red('  Not a KB-First project.'));
+    console.log(chalk.red('  Not a RuvNet-KB-First project.'));
     console.log('');
-    console.log(chalk.gray('  Initialize with: kb-first init'));
+    console.log(chalk.gray('  Initialize with: npx ruvnet-kb-first init'));
+    console.log(chalk.gray('  With KB:         npx ruvnet-kb-first init --kb ask_ruvnet'));
     console.log('');
     return;
   }
 
   const config = JSON.parse(readFileSync(configPath, 'utf-8'));
 
+  // Knowledge Base Connection (PROMINENT - this is the "Bible")
+  if (config.knowledgeBase?.connected) {
+    console.log(chalk.white('  Knowledge Base (Authority Source)'));
+    console.log(chalk.gray('  ─────────────────────────────────────────────────────────────'));
+
+    // Try to get live count
+    let liveCount = config.knowledgeBase.entries;
+    let isLive = false;
+    try {
+      const pg = await import('pg');
+      const client = new pg.default.Client({
+        host: config.knowledgeBase.host,
+        port: config.knowledgeBase.port,
+        database: 'postgres',
+        user: 'postgres',
+        password: 'guruKB2025'
+      });
+      await client.connect();
+      const result = await client.query(
+        `SELECT COUNT(*) as count FROM ${config.knowledgeBase.schema}.architecture_docs`
+      );
+      liveCount = parseInt(result.rows[0].count);
+      await client.end();
+      isLive = true;
+    } catch (e) {
+      // Use cached count
+    }
+
+    const statusIcon = isLive ? chalk.green('●') : chalk.yellow('○');
+    console.log(`  ${statusIcon} Schema:     ${chalk.green(config.knowledgeBase.schema)}`);
+    console.log(`    Entries:    ${chalk.cyan(liveCount.toLocaleString())} ${isLive ? chalk.green('(live)') : chalk.yellow('(cached)')}`);
+    console.log(`    Host:       ${chalk.gray(config.knowledgeBase.host + ':' + config.knowledgeBase.port)}`);
+    console.log('');
+    console.log(chalk.gray('  Claude will use this KB to:'));
+    console.log(chalk.gray('    • Verify architecture patterns are correct'));
+    console.log(chalk.gray('    • Ensure optimal configurations are applied'));
+    console.log(chalk.gray('    • Identify missing best practices'));
+    console.log(chalk.gray('    • Generate code with proper KB citations'));
+    console.log('');
+  } else {
+    console.log(chalk.white('  Knowledge Base'));
+    console.log(chalk.gray('  ─────────────────────────────────────────────────────────────'));
+    console.log(chalk.yellow('  ○ Not connected'));
+    console.log(chalk.gray('    Reinitialize with: npx ruvnet-kb-first init --kb ask_ruvnet'));
+    console.log('');
+  }
+
   // Project Info
   console.log(chalk.white('  Project Information'));
   console.log(chalk.gray('  ─────────────────────────────────────────────────────────────'));
@@ -132,12 +180,18 @@ export async function statusCommand(options) {
   console.log(chalk.white('  Next Steps'));
   console.log(chalk.gray('  ─────────────────────────────────────────────────────────────'));
 
+  if (config.knowledgeBase?.connected) {
+    console.log(chalk.cyan('  → Ask Claude: "Review this app using RuvNet-KB-First"'));
+    console.log(chalk.gray('    Claude will query the KB and analyze your code'));
+    console.log('');
+  }
+
   if (currentPhase < 11) {
-    console.log(chalk.cyan(`  → Run: kb-first phase ${currentPhase}`));
+    console.log(chalk.cyan(`  → Run: npx ruvnet-kb-first phase ${currentPhase}`));
     console.log(chalk.gray(`    Complete Phase ${currentPhase}: ${PHASES.find(p => p.num === currentPhase)?.name}`));
   } else {
     console.log(chalk.green('  → All phases complete!'));
-    console.log(chalk.gray('    Run: kb-first score --detailed'));
+    console.log(chalk.gray('    Run: npx ruvnet-kb-first score --detailed'));
   }
 
   console.log('');

package/src/mcp-server.js

@@ -1,20 +1,22 @@
 /**
  * RuvNet KB-First MCP Server - Granular Score-Driven Architecture
- * Version 6.1.0
+ * Version 6.2.0
  *
  * PHILOSOPHY: Granular scoring drives discipline.
- * - Score each KB dimension 1-100 (completeness, depth, comprehensiveness, accuracy, freshness)
- * - Score each phase readiness 1-100
+ * - Score each KB dimension 1-100 (completeness, depth, comprehensiveness, accuracy, freshness, attribution, ux_quality)
+ * - Score each phase readiness 1-100 (including Phase 12: UX Quality Review)
  * - Generate enhancement plan based on gaps
  * - User confirms before execution
  * - Post-verify: did we hit predicted scores?
+ * - Playwright UX Review: Visual quality audit from end-user perspective
  *
- * 5 Tools:
- *   1. kb_first_assess   - Score ALL dimensions (KB quality + phase readiness)
- *   2. kb_first_plan     - Generate enhancement plan with predicted improvements
- *   3. kb_first_confirm  - User confirms readiness, locks in plan
- *   4. kb_first_execute  - Execute plan phase by phase
- *   5. kb_first_verify   - Post-verification: predicted vs actual, identify gaps
+ * 6 Tools:
+ *   1. kb_first_assess     - Score ALL dimensions (KB quality + phase readiness)
+ *   2. kb_first_plan       - Generate enhancement plan with predicted improvements
+ *   3. kb_first_confirm    - User confirms readiness, locks in plan
+ *   4. kb_first_execute    - Execute plan phase by phase
+ *   5. kb_first_verify     - Post-verification: predicted vs actual, identify gaps
+ *   6. kb_first_ux_review  - Playwright-based UX quality audit with screenshots
  *
  * Usage:
  *   npx ruvnet-kb-first mcp
@@ -26,7 +28,7 @@ import { globSync } from 'glob';
 
 const MCP_VERSION = '0.1.0';
 const SERVER_NAME = 'ruvnet-kb-first';
-const SERVER_VERSION = '6.1.0';
+const SERVER_VERSION = '6.2.0';
 
 /**
  * KB Quality Dimensions (each scored 1-100)
@@ -61,6 +63,11 @@ const KB_DIMENSIONS = {
     name: 'Attribution',
     description: 'Are sources and experts properly cited?',
     weight: 10
+  },
+  ux_quality: {
+    name: 'UX Quality',
+    description: 'Is the user experience excellent? Visual design, emotional appeal, user flow, versioning display, loading states, error handling, accessibility.',
+    weight: 15
   }
 };
 
@@ -119,6 +126,21 @@ const PHASES = {
   11: {
     name: 'Deployment',
     criteria: ['Infrastructure ready', 'Environments configured', 'CI/CD built', 'Migrations run', 'Monitoring active', 'Go-live complete']
+  },
+  12: {
+    name: 'UX Quality Review',
+    criteria: [
+      'Version displayed in header/footer (major.minor.patch)',
+      'Cache-busting implemented with version notifications',
+      'Visual design excellence (not just functional)',
+      'Emotional appeal and user psychology considered',
+      'Loading states are elegant',
+      'Error messages are helpful and actionable',
+      'User flow is intuitive and compelling',
+      'Playwright screenshots reviewed and critiqued',
+      'Accessibility verified (WCAG 2.1 AA)',
+      'Mobile responsiveness tested'
+    ]
   }
 };
 
@@ -221,6 +243,53 @@ This closes the loop and ensures you delivered what you promised.`,
         detailed: { type: 'boolean', description: 'Show detailed comparison', default: true }
       }
     }
+  },
+  {
+    name: 'kb_first_ux_review',
+    description: `Playwright-based UX Quality Audit - End-user perspective review.
+
+Walks through the application as an end user, capturing screenshots.
+Then critically reviews EACH screenshot:
+
+For each screen:
+- How good is this? (1-100 score)
+- How could we make it better? (specific recommendations)
+- Where is it falling down? (issues identified)
+- What would EXCELLENT look like? (vision for improvement)
+- Recommendations with priority
+
+Also checks critical UX requirements:
+- Version number displayed in header/footer (major.minor.patch)
+- Cache-busting with version change notifications
+- Loading states are elegant, not jarring
+- Error messages are helpful and guide user to resolution
+- Visual design creates emotional appeal, not just functional
+- User psychology leveraged for compelling flow
+
+This ensures the application isn't just functional—it's EXCELLENT.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        appUrl: { type: 'string', description: 'URL of the running application to review' },
+        flows: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'User flows to test (e.g., ["login", "search", "checkout"])',
+          default: ['homepage', 'main_flow']
+        },
+        screenshotDir: {
+          type: 'string',
+          description: 'Directory to save screenshots',
+          default: '.ruvector/ux-review'
+        },
+        criticalReview: {
+          type: 'boolean',
+          description: 'Perform deep critical review of each screenshot',
+          default: true
+        }
+      },
+      required: ['appUrl']
+    }
   }
 ];
 
@@ -351,6 +420,50 @@ function scoreKBDimensions(cwd) {
     improvement: attributionScore < 80 ? 'Add KB citations to code files' : 'Good attribution'
   };
 
+  // UX Quality: Based on presence of UX-related artifacts
+  let uxScore = 0;
+  const packagePath = join(cwd, 'package.json');
+  const uxReviewPath = join(cwd, '.ruvector', 'ux-review');
+
+  // Check for version in package.json
+  if (existsSync(packagePath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+      if (pkg.version) uxScore += 15; // Versioning exists
+    } catch {}
+  }
+
+  // Check for prior UX review
+  if (existsSync(uxReviewPath)) {
+    try {
+      const reviewFiles = readdirSync(uxReviewPath);
+      if (reviewFiles.length > 0) uxScore += 25; // UX review conducted
+      if (reviewFiles.some(f => f.includes('review-report'))) uxScore += 20; // Detailed review exists
+    } catch {}
+  }
+
+  // Check for accessibility considerations
+  if (existsSync(srcDir)) {
+    try {
+      const files = globSync('**/*.{tsx,jsx,html}', { cwd: srcDir });
+      let a11yScore = 0;
+      for (const f of files) {
+        try {
+          const content = readFileSync(join(srcDir, f), 'utf-8');
+          if (content.includes('aria-') || content.includes('role=')) a11yScore += 5;
+          if (content.includes('alt=') || content.includes('loading=')) a11yScore += 3;
+        } catch {}
+      }
+      uxScore += Math.min(40, a11yScore);
+    } catch {}
+  }
+
+  scores.ux_quality = {
+    score: Math.min(100, uxScore),
+    reason: uxScore >= 60 ? 'UX review conducted, accessibility present' : 'Limited UX review artifacts',
+    improvement: uxScore < 80 ? 'Run kb_first_ux_review for Playwright-based UX audit' : 'Good UX coverage'
+  };
+
   return scores;
 }
 
@@ -941,6 +1054,296 @@ async function handleVerify(cwd, args) {
   return result;
 }
 
+/**
+ * UX Review Criteria for critical evaluation
+ */
+const UX_CRITERIA = {
+  versioning: {
+    name: 'Version Display',
+    checks: ['Header shows version', 'Footer shows version', 'Format: major.minor.patch'],
+    weight: 15
+  },
+  caching: {
+    name: 'Cache Management',
+    checks: ['Version change detection', 'User notification on updates', 'Force refresh capability'],
+    weight: 10
+  },
+  visual_design: {
+    name: 'Visual Design Excellence',
+    checks: ['Professional typography', 'Cohesive color palette', 'Proper spacing/hierarchy', 'Not generic AI aesthetic'],
+    weight: 20
+  },
+  emotional_appeal: {
+    name: 'Emotional Appeal',
+    checks: ['Creates confidence', 'Guides without confusion', 'Celebrates success states', 'Softens error states'],
+    weight: 15
+  },
+  loading_states: {
+    name: 'Loading States',
+    checks: ['Skeleton loaders present', 'Progress indicators', 'No jarring transitions', 'Graceful degradation'],
+    weight: 10
+  },
+  error_handling: {
+    name: 'Error Handling UX',
+    checks: ['Clear error messages', 'Actionable next steps', 'Recovery paths provided', 'No technical jargon'],
+    weight: 10
+  },
+  user_flow: {
+    name: 'User Flow',
+    checks: ['Intuitive navigation', 'Clear call-to-actions', 'Logical progression', 'Minimal friction'],
+    weight: 10
+  },
+  accessibility: {
+    name: 'Accessibility',
+    checks: ['Keyboard navigation', 'Screen reader compatible', 'Color contrast', 'Focus indicators'],
+    weight: 10
+  }
+};
+
+/**
+ * Detect available frontend-design skills
+ */
+function detectFrontendDesignSkills() {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  const skillsDir = join(homeDir, '.claude', 'skills');
+  const skills = {
+    preferred: null,
+    available: [],
+    recommendation: null
+  };
+
+  // Check for frontend-design-Stu (preferred)
+  if (existsSync(join(skillsDir, 'frontend-design-Stu.md'))) {
+    skills.preferred = 'frontend-design-Stu';
+    skills.available.push('frontend-design-Stu');
+  }
+
+  // Check for frontend-design
+  if (existsSync(join(skillsDir, 'frontend-design.md'))) {
+    if (!skills.preferred) {
+      skills.preferred = 'frontend-design';
+    }
+    skills.available.push('frontend-design');
+  }
+
+  // Generate recommendation if no skills found
+  if (skills.available.length === 0) {
+    skills.recommendation = {
+      message: 'No frontend-design skill installed. For UX excellence, install the Anthropic frontend-design skill.',
+      installation: 'Visit: https://github.com/anthropics/claude-code-plugins and install frontend-design plugin',
+      benefit: 'Creates distinctive, production-grade interfaces that avoid generic AI aesthetics'
+    };
+  }
+
+  return skills;
+}
+
+/**
+ * Handle UX Review with Playwright
+ */
+async function handleUXReview(cwd, args) {
+  const { appUrl, flows = ['homepage', 'main_flow'], screenshotDir = '.ruvector/ux-review', criticalReview = true } = args;
+
+  // Check for frontend-design skills
+  const designSkills = detectFrontendDesignSkills();
+
+  // Check if Playwright is installed
+  let playwrightAvailable = false;
+  try {
+    await import('playwright');
+    playwrightAvailable = true;
+  } catch {
+    // Playwright not installed
+  }
+
+  if (!playwrightAvailable) {
+    return {
+      action: 'PLAYWRIGHT_REQUIRED',
+      status: 'INSTALLATION_NEEDED',
+      message: 'Playwright is required for UX review but not installed.',
+      installation: {
+        command: 'npm install playwright && npx playwright install chromium',
+        description: 'Installs Playwright and Chromium browser for screenshot capture',
+        automated: 'Run this command, then re-run kb_first_ux_review'
+      },
+      designSkills: designSkills,
+      alternative: {
+        message: 'Alternatively, you can manually capture screenshots and place them in:',
+        directory: join(cwd, screenshotDir),
+        format: 'Name format: 01-homepage.png, 02-login.png, etc.',
+        thenRun: 'Re-run kb_first_ux_review with criticalReview=true to analyze'
+      }
+    };
+  }
+
+  // Create screenshot directory
+  const screenshotPath = join(cwd, screenshotDir);
+  if (!existsSync(screenshotPath)) {
+    mkdirSync(screenshotPath, { recursive: true });
+  }
+
+  // Capture screenshots using Playwright
+  const screenshots = [];
+  try {
+    const { chromium } = await import('playwright');
+    const browser = await chromium.launch();
+    const context = await browser.newContext({
+      viewport: { width: 1920, height: 1080 }
+    });
+    const page = await context.newPage();
+
+    // Navigate to app
+    await page.goto(appUrl, { waitUntil: 'networkidle', timeout: 30000 });
+
+    // Capture initial screenshot
+    const timestamp = Date.now();
+    const homepagePath = join(screenshotPath, `01-homepage-${timestamp}.png`);
+    await page.screenshot({ path: homepagePath, fullPage: true });
+    screenshots.push({
+      id: 1,
+      name: 'Homepage',
+      path: homepagePath,
+      url: appUrl,
+      viewport: 'desktop'
+    });
+
+    // Check for version display
+    const versionCheck = await page.evaluate(() => {
+      const body = document.body.innerText;
+      const versionPattern = /v?\d+\.\d+\.\d+/;
+      const hasVersion = versionPattern.test(body);
+      const header = document.querySelector('header')?.innerText || '';
+      const footer = document.querySelector('footer')?.innerText || '';
+      return {
+        hasVersion,
+        inHeader: versionPattern.test(header),
+        inFooter: versionPattern.test(footer),
+        foundVersion: body.match(versionPattern)?.[0] || null
+      };
+    });
+
+    // Mobile viewport screenshot
+    await page.setViewportSize({ width: 375, height: 812 });
+    await page.reload({ waitUntil: 'networkidle' });
+    const mobilePath = join(screenshotPath, `02-homepage-mobile-${timestamp}.png`);
+    await page.screenshot({ path: mobilePath, fullPage: true });
+    screenshots.push({
+      id: 2,
+      name: 'Homepage Mobile',
+      path: mobilePath,
+      url: appUrl,
+      viewport: 'mobile'
+    });
+
+    await browser.close();
+
+    // Generate critical review for each screenshot
+    const reviews = [];
+    if (criticalReview) {
+      for (const screenshot of screenshots) {
+        reviews.push({
+          screenshot: screenshot.name,
+          path: screenshot.path,
+          score: 0, // To be filled by Claude's analysis
+          evaluation: {
+            howGood: 'REQUIRES_VISUAL_ANALYSIS - Open screenshot and evaluate',
+            couldBeBetter: [],
+            fallingDown: [],
+            excellentWouldLookLike: '',
+            recommendations: []
+          },
+          criteria: Object.entries(UX_CRITERIA).map(([key, crit]) => ({
+            name: crit.name,
+            checks: crit.checks,
+            score: 0,
+            notes: 'Awaiting visual review'
+          }))
+        });
+      }
+    }
+
+    // Save review report
+    const reviewReport = {
+      timestamp: new Date().toISOString(),
+      appUrl,
+      versionCheck,
+      screenshots,
+      reviews,
+      summary: {
+        screenshotsCaptured: screenshots.length,
+        versionDisplayed: versionCheck.hasVersion,
+        versionInHeader: versionCheck.inHeader,
+        versionInFooter: versionCheck.inFooter,
+        requiresManualReview: true
+      },
+      criticalQuestions: [
+        'How good is this? (Score each screen 1-100)',
+        'How could we make it better?',
+        'Where is it falling down?',
+        'What would EXCELLENT look like?',
+        'What are the specific recommendations?'
+      ]
+    };
+
+    writeFileSync(join(screenshotPath, 'review-report.json'), JSON.stringify(reviewReport, null, 2));
+
+    return {
+      action: 'UX_REVIEW_CAPTURED',
+      status: 'SCREENSHOTS_READY',
+      appUrl,
+      versionCheck: {
+        found: versionCheck.hasVersion,
+        version: versionCheck.foundVersion,
+        inHeader: versionCheck.inHeader,
+        inFooter: versionCheck.inFooter,
+        recommendation: !versionCheck.inHeader && !versionCheck.inFooter
+          ? '⚠️ Version not displayed in header/footer - ADD version display immediately'
+          : '✓ Version displayed'
+      },
+      screenshots: screenshots.map(s => ({
+        name: s.name,
+        path: s.path,
+        viewport: s.viewport
+      })),
+      nextSteps: {
+        step1: 'Open each screenshot file and visually inspect',
+        step2: 'Score each screen 1-100 for overall UX quality',
+        step3: 'Document: What works? What fails? What would excellent look like?',
+        step4: 'Generate specific recommendations with priority (HIGH/MEDIUM/LOW)',
+        step5: 'Update review-report.json with scores and findings',
+        step6: 'Re-run kb_first_assess to update UX Quality scores'
+      },
+      criticalQuestions: reviewReport.criticalQuestions,
+      criteria: Object.entries(UX_CRITERIA).map(([key, crit]) => ({
+        name: crit.name,
+        checks: crit.checks,
+        weight: `${crit.weight}%`
+      })),
+      reportPath: join(screenshotPath, 'review-report.json'),
+      designSkills: {
+        available: designSkills.available,
+        useSkill: designSkills.preferred || null,
+        recommendation: designSkills.recommendation,
+        implementationGuidance: designSkills.preferred
+          ? `Use skill "${designSkills.preferred}" when implementing UX improvements. It creates distinctive, production-grade interfaces.`
+          : 'Install frontend-design skill for UX improvements: https://github.com/anthropics/claude-code-plugins'
+      }
+    };
+  } catch (error) {
+    return {
+      action: 'UX_REVIEW_ERROR',
+      status: 'CAPTURE_FAILED',
+      error: error.message,
+      troubleshooting: {
+        step1: 'Ensure the app is running at the specified URL',
+        step2: 'Check if Playwright browsers are installed: npx playwright install chromium',
+        step3: 'Try with a simpler URL first',
+        step4: 'Manually capture screenshots and place in: ' + screenshotPath
+      }
+    };
+  }
+}
+
 /**
  * Get improvement task based on gap
  */
@@ -983,6 +1386,8 @@ async function handleToolCall(toolName, args) {
       return await handleExecute(cwd, args);
     case 'kb_first_verify':
       return await handleVerify(cwd, args);
+    case 'kb_first_ux_review':
+      return await handleUXReview(cwd, args);
     default:
       return { error: `Unknown tool: ${toolName}` };
   }
@@ -1033,8 +1438,9 @@ async function handleMCPMessage(message) {
  */
 export async function startMCPServer(options = {}) {
   console.error(`RuvNet KB-First MCP Server v${SERVER_VERSION}`);
-  console.error('Architecture: Granular Score-Driven | Tools: 5 | Dimensions: 6 KB + 12 Phases');
-  console.error('Workflow: Assess → Plan → Confirm → Execute → Verify');
+  console.error('Architecture: Granular Score-Driven | Tools: 6 | Dimensions: 7 KB + 13 Phases');
+  console.error('Workflow: Assess → Plan → Confirm → Execute → Verify → UX Review');
+  console.error('UX Review: Playwright-based visual quality audit from end-user perspective');
 
   let buffer = '';
   process.stdin.setEncoding('utf-8');