helixevo 0.2.11 → 0.2.13

package/dashboard/app/api/run/route.ts

@@ -0,0 +1,55 @@
+import { NextResponse } from 'next/server'
+import { execSync } from 'child_process'
+
+export const dynamic = 'force-dynamic'
+
+// Allowed commands — whitelist to prevent arbitrary execution
+const ALLOWED_COMMANDS: Record<string, { cmd: string; timeout: number }> = {
+  'status':         { cmd: 'helixevo status',                    timeout: 15000 },
+  'health':         { cmd: 'helixevo health --verbose',          timeout: 120000 },
+  'metrics':        { cmd: 'helixevo metrics --verbose',         timeout: 15000 },
+  'evolve':         { cmd: 'helixevo evolve --verbose',          timeout: 300000 },
+  'evolve-dry':     { cmd: 'helixevo evolve --dry-run --verbose', timeout: 300000 },
+  'generalize':     { cmd: 'helixevo generalize --verbose',      timeout: 300000 },
+  'generalize-dry': { cmd: 'helixevo generalize --dry-run --verbose', timeout: 300000 },
+  'graph-rebuild':  { cmd: 'helixevo graph --rebuild --verbose', timeout: 300000 },
+  'graph-optimize': { cmd: 'helixevo graph --optimize --verbose', timeout: 300000 },
+  'research':       { cmd: 'helixevo research --verbose',        timeout: 300000 },
+  'research-dry':   { cmd: 'helixevo research --dry-run --verbose', timeout: 300000 },
+  'report':         { cmd: 'helixevo report --days 7',           timeout: 30000 },
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json()
+    const { command } = body as { command: string }
+
+    const entry = ALLOWED_COMMANDS[command]
+    if (!entry) {
+      return NextResponse.json({
+        success: false,
+        error: `Unknown command: ${command}`,
+      }, { status: 400 })
+    }
+
+    const output = execSync(`${entry.cmd} 2>&1`, {
+      encoding: 'utf-8',
+      timeout: entry.timeout,
+      env: { ...process.env },
+    })
+
+    return NextResponse.json({
+      success: true,
+      command: entry.cmd,
+      output,
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err)
+    // execSync errors include stdout in the message
+    const stdout = (err as { stdout?: string })?.stdout ?? ''
+    return NextResponse.json({
+      success: false,
+      output: stdout || message.slice(-2000),
+    }, { status: 500 })
+  }
+}

package/dashboard/app/api/upgrade/route.ts

@@ -0,0 +1,37 @@
+import { NextResponse } from 'next/server'
+import { execSync } from 'child_process'
+
+export const dynamic = 'force-dynamic'
+
+export async function POST() {
+  try {
+    // Run the upgrade command
+    const output = execSync('npm install -g helixevo@latest 2>&1', {
+      encoding: 'utf-8',
+      timeout: 120000, // 2 minute timeout
+      env: { ...process.env },
+    })
+
+    // Get the new version
+    let newVersion = ''
+    try {
+      newVersion = execSync('helixevo --version 2>/dev/null', { encoding: 'utf-8' }).trim()
+    } catch {
+      // Try parsing from output
+      const match = output.match(/helixevo@(\d+\.\d+\.\d+)/)
+      newVersion = match?.[1] ?? 'unknown'
+    }
+
+    return NextResponse.json({
+      success: true,
+      version: newVersion,
+      output: output.slice(-500), // last 500 chars
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err)
+    return NextResponse.json({
+      success: false,
+      error: message.slice(-500),
+    }, { status: 500 })
+  }
+}

package/dashboard/app/commands/page.tsx

@@ -0,0 +1,432 @@
+'use client'
+
+import { useState } from 'react'
+import { QuickActions } from '@/components/quick-actions'
+
+interface CommandInfo {
+  name: string
+  description: string
+  usage: string
+  examples: { cmd: string; desc: string }[]
+  options?: { flag: string; desc: string }[]
+  category: 'core' | 'evolution' | 'network' | 'analysis' | 'system'
+  runnable?: { command: string; label: string; icon: string; color: string }
+  needsLLM: boolean
+  note?: string
+}
+
+const COMMANDS: CommandInfo[] = [
+  {
+    name: 'watch',
+    description: 'Always-on learning mode. Watches for corrections in real-time, captures failures automatically, and triggers evolution when enough failures accumulate. This is the primary way to use HelixEvo day-to-day.',
+    usage: 'helixevo watch [options]',
+    examples: [
+      { cmd: 'helixevo watch', desc: 'Start watching with default settings' },
+      { cmd: 'helixevo watch --project myapp', desc: 'Watch with project context for specialized learning' },
+      { cmd: 'helixevo watch --no-evolve', desc: 'Capture corrections only, skip auto-evolution' },
+      { cmd: 'helixevo watch --verbose', desc: 'Show detailed capture and metrics output' },
+    ],
+    options: [
+      { flag: '--project <name>', desc: 'Associate captured failures with a specific project' },
+      { flag: '--events <path>', desc: 'Path to events.jsonl (default: ./events.jsonl)' },
+      { flag: '--verbose', desc: 'Show detailed capture and metrics' },
+      { flag: '--no-evolve', desc: 'Disable auto-evolution (capture only)' },
+    ],
+    category: 'core',
+    needsLLM: true,
+    note: 'This is a long-running process. It monitors your events.jsonl for new corrections.',
+  },
+  {
+    name: 'init',
+    description: 'Import existing skills from ~/.agents/skills and Craft Agent workspaces. Generates skill tests and builds an initial skill graph for the dashboard.',
+    usage: 'helixevo init [options]',
+    examples: [
+      { cmd: 'helixevo init', desc: 'Import from default paths and generate skill tests' },
+      { cmd: 'helixevo init --skip-tests', desc: 'Import skills without generating tests (faster)' },
+      { cmd: 'helixevo init --skills-paths ~/my-skills', desc: 'Import from a custom directory' },
+    ],
+    options: [
+      { flag: '--skills-paths <paths...>', desc: 'Custom paths to scan for existing skills' },
+      { flag: '--skip-tests', desc: 'Skip skill test generation (faster but no regression testing)' },
+    ],
+    category: 'core',
+    needsLLM: true,
+    note: 'Run this once after installing HelixEvo. Re-running is safe — existing skills are skipped.',
+  },
+  {
+    name: 'evolve',
+    description: 'The core evolution loop. Analyzes captured failures, proposes skill improvements, evaluates them with multi-judge consensus, runs regression tests, and applies winning changes to the Pareto frontier.',
+    usage: 'helixevo evolve [options]',
+    examples: [
+      { cmd: 'helixevo evolve', desc: 'Run evolution with default settings' },
+      { cmd: 'helixevo evolve --dry-run', desc: 'Preview proposals without applying changes' },
+      { cmd: 'helixevo evolve --verbose', desc: 'Show detailed LLM interactions and judge reasoning' },
+      { cmd: 'helixevo evolve --max-proposals 3', desc: 'Limit to 3 proposals per run' },
+    ],
+    options: [
+      { flag: '--dry-run', desc: 'Show proposals without applying them' },
+      { flag: '--verbose', desc: 'Show detailed LLM interactions' },
+      { flag: '--max-proposals <n>', desc: 'Maximum proposals per run (default: 5)' },
+    ],
+    category: 'evolution',
+    needsLLM: true,
+    runnable: { command: 'evolve', label: 'Run Evolve', icon: 'M13 7h8m0 0v8m0-8l-8 8-4-4-6 6', color: 'var(--green)' },
+    note: 'Requires at least 5 captured failures. Use "watch" or "capture" to collect them first.',
+  },
+  {
+    name: 'generalize',
+    description: 'Promotes cross-skill patterns to a higher abstraction layer. Detects when multiple skills share common patterns and creates parent skills that capture the shared knowledge. This is how skills "level up".',
+    usage: 'helixevo generalize [options]',
+    examples: [
+      { cmd: 'helixevo generalize', desc: 'Detect and promote cross-skill patterns' },
+      { cmd: 'helixevo generalize --dry-run', desc: 'Preview candidates without applying' },
+      { cmd: 'helixevo generalize --verbose', desc: 'Show detailed pattern analysis' },
+    ],
+    options: [
+      { flag: '--dry-run', desc: 'Show candidates without applying' },
+      { flag: '--verbose', desc: 'Show detailed analysis' },
+    ],
+    category: 'evolution',
+    needsLLM: true,
+    runnable: { command: 'generalize', label: 'Run Generalize', icon: 'M5 10l7-7m0 0l7 7m-7-7v18', color: 'var(--blue)' },
+  },
+  {
+    name: 'specialize',
+    description: 'Creates project-specific skills from general ones. Takes a project context and creates specialized variants of general skills tailored to that project\'s patterns and conventions.',
+    usage: 'helixevo specialize --project <name> [options]',
+    examples: [
+      { cmd: 'helixevo specialize --project myapp', desc: 'Create project-specific skills for myapp' },
+      { cmd: 'helixevo specialize --project myapp --dry-run', desc: 'Preview without creating skills' },
+    ],
+    options: [
+      { flag: '--project <name>', desc: 'Required. Project name for specialization' },
+      { flag: '--dry-run', desc: 'Show candidates without applying' },
+      { flag: '--verbose', desc: 'Show detailed analysis' },
+    ],
+    category: 'evolution',
+    needsLLM: true,
+  },
+  {
+    name: 'graph',
+    description: 'Visualize and manage the skill network graph. Shows relationships between skills (depends, enhances, conflicts, co-evolves). Can render as TUI, Mermaid diagram, or sync to Obsidian.',
+    usage: 'helixevo graph [options]',
+    examples: [
+      { cmd: 'helixevo graph', desc: 'Show skill network in terminal (instant)' },
+      { cmd: 'helixevo graph --rebuild', desc: 'Re-infer all relationships via LLM' },
+      { cmd: 'helixevo graph --optimize', desc: 'Detect merge/split/conflict opportunities' },
+      { cmd: 'helixevo graph --mermaid', desc: 'Open interactive Mermaid diagram in browser' },
+      { cmd: 'helixevo graph --obsidian ~/vault', desc: 'Sync skill graph to an Obsidian vault' },
+    ],
+    options: [
+      { flag: '--rebuild', desc: 'Force rebuild — re-infer relationships via LLM call' },
+      { flag: '--optimize', desc: 'Run network optimization (merge/split/conflict detection)' },
+      { flag: '--mermaid', desc: 'Render as Mermaid diagram in browser' },
+      { flag: '--obsidian <path>', desc: 'Sync to Obsidian vault at the given path' },
+      { flag: '--verbose', desc: 'Show detailed analysis' },
+    ],
+    category: 'network',
+    needsLLM: true,
+    runnable: { command: 'graph-rebuild', label: 'Rebuild Graph', icon: 'M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1', color: 'var(--purple)' },
+  },
+  {
+    name: 'research',
+    description: 'Proactive skill discovery via web research. Identifies gaps in your skill network, generates hypotheses, searches the web for solutions, and creates draft skills from discoveries.',
+    usage: 'helixevo research [options]',
+    examples: [
+      { cmd: 'helixevo research', desc: 'Run proactive research' },
+      { cmd: 'helixevo research --project ~/myapp', desc: 'Research with project context for targeted discovery' },
+      { cmd: 'helixevo research --dry-run', desc: 'Show discoveries without creating skills' },
+    ],
+    options: [
+      { flag: '--project <path>', desc: 'Project path for goal extraction' },
+      { flag: '--dry-run', desc: 'Show discoveries without creating skills' },
+      { flag: '--verbose', desc: 'Show detailed research steps' },
+      { flag: '--max-hypotheses <n>', desc: 'Max hypotheses to test (default: 3)' },
+    ],
+    category: 'network',
+    needsLLM: true,
+    runnable: { command: 'research', label: 'Run Research', icon: 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z', color: 'var(--purple)' },
+  },
+  {
+    name: 'health',
+    description: 'Comprehensive assessment of your skill network. Evaluates cohesion (how well skills connect), coverage (gaps in knowledge), balance (over/under-developed areas), and cross-project transfer potential.',
+    usage: 'helixevo health [options]',
+    examples: [
+      { cmd: 'helixevo health', desc: 'Run health assessment' },
+      { cmd: 'helixevo health --verbose', desc: 'Show detailed per-metric analysis' },
+    ],
+    options: [
+      { flag: '--verbose', desc: 'Show detailed analysis' },
+    ],
+    category: 'analysis',
+    needsLLM: true,
+    runnable: { command: 'health', label: 'Run Health Check', icon: 'M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z', color: 'var(--yellow)' },
+  },
+  {
+    name: 'metrics',
+    description: 'Show correction rates, skill improvement trends, and evolution impact over time. Helps you understand how your skills are improving and where attention is needed.',
+    usage: 'helixevo metrics [options]',
+    examples: [
+      { cmd: 'helixevo metrics', desc: 'Show summary metrics' },
+      { cmd: 'helixevo metrics --verbose', desc: 'Show detailed per-skill breakdown' },
+    ],
+    options: [
+      { flag: '--verbose', desc: 'Show detailed per-skill breakdown' },
+    ],
+    category: 'analysis',
+    needsLLM: false,
+    runnable: { command: 'metrics', label: 'Show Metrics', icon: 'M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z', color: 'var(--text-secondary)' },
+  },
+  {
+    name: 'status',
+    description: 'Quick overview of system state: total skills, frontier size, failure count, skill tests, and network health. Like a health check but without LLM analysis.',
+    usage: 'helixevo status',
+    examples: [
+      { cmd: 'helixevo status', desc: 'Show system status' },
+    ],
+    category: 'analysis',
+    needsLLM: false,
+    runnable: { command: 'status', label: 'Show Status', icon: 'M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z', color: 'var(--text-secondary)' },
+  },
+  {
+    name: 'report',
+    description: 'Generate an evolution report summarizing changes over a time period. Shows proposals, accepted/rejected changes, skill improvements, and failure resolution.',
+    usage: 'helixevo report [options]',
+    examples: [
+      { cmd: 'helixevo report', desc: 'Generate report for the last day' },
+      { cmd: 'helixevo report --days 7', desc: 'Weekly evolution report' },
+      { cmd: 'helixevo report --output report.md', desc: 'Save report to a file' },
+    ],
+    options: [
+      { flag: '--days <n>', desc: 'Report period in days (default: 1)' },
+      { flag: '--output <path>', desc: 'Output path for report' },
+    ],
+    category: 'analysis',
+    needsLLM: false,
+    runnable: { command: 'report', label: 'Generate Report', icon: 'M9 17v-2m3 2v-4m3 4v-6m2 10H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z', color: 'var(--blue)' },
+  },
+  {
+    name: 'capture',
+    description: 'Extract failures from a Craft Agent session file. Parses conversation history to identify user corrections and converts them into structured failure records for evolution.',
+    usage: 'helixevo capture <sessionPath> [options]',
+    examples: [
+      { cmd: 'helixevo capture session.json', desc: 'Extract failures from a session file' },
+      { cmd: 'helixevo capture session.json --project myapp', desc: 'Capture with project context' },
+    ],
+    options: [
+      { flag: '--project <name>', desc: 'Project name override' },
+    ],
+    category: 'system',
+    needsLLM: true,
+    note: 'Typically not needed if using "watch" mode, which captures automatically.',
+  },
+  {
+    name: 'dashboard',
+    description: 'Launch the web dashboard at http://localhost:3847. Provides a visual interface for monitoring skills, evolution, frontier, and network health.',
+    usage: 'helixevo dashboard',
+    examples: [
+      { cmd: 'helixevo dashboard', desc: 'Open the dashboard in your browser' },
+    ],
+    category: 'system',
+    needsLLM: false,
+    note: 'You are currently using the dashboard!',
+  },
+]
+
+const CATEGORIES: { id: string; label: string; color: string }[] = [
+  { id: 'core', label: 'Core Workflow', color: 'var(--purple)' },
+  { id: 'evolution', label: 'Evolution', color: 'var(--green)' },
+  { id: 'network', label: 'Network & Research', color: 'var(--blue)' },
+  { id: 'analysis', label: 'Analysis & Reports', color: 'var(--yellow)' },
+  { id: 'system', label: 'System', color: 'var(--text-secondary)' },
+]
+
+export default function CommandsPage() {
+  const [expandedCmd, setExpandedCmd] = useState<string | null>(null)
+
+  return (
+    <div>
+      <div className="page-header">
+        <h1 className="page-title">Commands</h1>
+        <p className="page-desc">
+          All CLI commands available in HelixEvo — click any command for details and examples, or run directly from here
+        </p>
+      </div>
+
+      {/* Typical workflow */}
+      <div className="card" style={{ marginBottom: 24, padding: '16px 20px' }}>
+        <div style={{ fontSize: 13, fontWeight: 700, color: 'var(--text)', marginBottom: 8 }}>Typical Workflow</div>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 6, flexWrap: 'wrap', fontSize: 12 }}>
+          {[
+            { label: 'init', desc: 'Import skills' },
+            { label: 'watch', desc: 'Capture corrections' },
+            { label: 'evolve', desc: 'Improve skills' },
+            { label: 'generalize', desc: 'Abstract patterns' },
+            { label: 'graph --rebuild', desc: 'Map relationships' },
+            { label: 'health', desc: 'Assess quality' },
+          ].map((step, i) => (
+            <span key={step.label} style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+              <span style={{
+                background: 'var(--purple-light)', color: 'var(--purple)',
+                padding: '4px 10px', borderRadius: 'var(--radius)',
+                fontFamily: 'var(--font-mono)', fontWeight: 600,
+              }}>
+                {step.label}
+              </span>
+              <span style={{ color: 'var(--text-dim)' }}>{step.desc}</span>
+              {i < 5 && <span style={{ color: 'var(--text-muted)', margin: '0 4px' }}>&rarr;</span>}
+            </span>
+          ))}
+        </div>
+      </div>
+
+      {/* Commands by category */}
+      {CATEGORIES.map(cat => {
+        const cmds = COMMANDS.filter(c => c.category === cat.id)
+        if (cmds.length === 0) return null
+
+        return (
+          <div key={cat.id} style={{ marginBottom: 24 }}>
+            <div style={{
+              fontSize: 11, fontWeight: 700, color: cat.color,
+              textTransform: 'uppercase', letterSpacing: 1.2, marginBottom: 10,
+            }}>
+              {cat.label}
+            </div>
+
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+              {cmds.map(cmd => {
+                const isExpanded = expandedCmd === cmd.name
+                return (
+                  <div key={cmd.name} className="card" style={{
+                    overflow: 'hidden',
+                    border: isExpanded ? `1px solid ${cat.color}40` : undefined,
+                  }}>
+                    {/* Command header — clickable */}
+                    <div
+                      onClick={() => setExpandedCmd(isExpanded ? null : cmd.name)}
+                      style={{
+                        padding: '12px 16px',
+                        cursor: 'pointer',
+                        display: 'flex', justifyContent: 'space-between', alignItems: 'center',
+                      }}
+                    >
+                      <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+                        <code style={{
+                          fontFamily: 'var(--font-mono)', fontSize: 13, fontWeight: 700,
+                          color: cat.color,
+                        }}>
+                          {cmd.name}
+                        </code>
+                        <span style={{ fontSize: 12, color: 'var(--text-secondary)' }}>
+                          {cmd.description.split('.')[0]}
+                        </span>
+                        {cmd.needsLLM && (
+                          <span style={{
+                            fontSize: 9, fontWeight: 600, padding: '2px 6px',
+                            background: 'var(--purple-light)', color: 'var(--purple)',
+                            borderRadius: 4,
+                          }}>LLM</span>
+                        )}
+                      </div>
+                      <span style={{
+                        color: 'var(--text-muted)', fontSize: 12,
+                        transform: isExpanded ? 'rotate(180deg)' : 'none',
+                        transition: 'transform 0.2s',
+                      }}>▼</span>
+                    </div>
+
+                    {/* Expanded details */}
+                    {isExpanded && (
+                      <div style={{
+                        padding: '0 16px 16px',
+                        borderTop: '1px solid var(--border-subtle)',
+                      }}>
+                        {/* Description */}
+                        <p style={{ fontSize: 12, color: 'var(--text-secondary)', lineHeight: 1.6, marginTop: 12, marginBottom: 14 }}>
+                          {cmd.description}
+                        </p>
+
+                        {/* Usage */}
+                        <div style={{ marginBottom: 14 }}>
+                          <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 1, marginBottom: 6 }}>Usage</div>
+                          <code style={{
+                            display: 'block', padding: '8px 12px',
+                            background: 'var(--bg-section)', borderRadius: 'var(--radius)',
+                            fontFamily: 'var(--font-mono)', fontSize: 12, color: 'var(--text)',
+                          }}>
+                            $ {cmd.usage}
+                          </code>
+                        </div>
+
+                        {/* Options */}
+                        {cmd.options && cmd.options.length > 0 && (
+                          <div style={{ marginBottom: 14 }}>
+                            <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 1, marginBottom: 6 }}>Options</div>
+                            <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+                              {cmd.options.map(opt => (
+                                <div key={opt.flag} style={{ display: 'flex', gap: 12, fontSize: 12, padding: '4px 0' }}>
+                                  <code style={{
+                                    fontFamily: 'var(--font-mono)', color: 'var(--purple)',
+                                    fontWeight: 600, minWidth: 180, flexShrink: 0,
+                                  }}>{opt.flag}</code>
+                                  <span style={{ color: 'var(--text-dim)' }}>{opt.desc}</span>
+                                </div>
+                              ))}
+                            </div>
+                          </div>
+                        )}
+
+                        {/* Examples */}
+                        <div style={{ marginBottom: cmd.runnable ? 14 : 0 }}>
+                          <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 1, marginBottom: 6 }}>Examples</div>
+                          <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                            {cmd.examples.map((ex, i) => (
+                              <div key={i} style={{
+                                padding: '8px 12px',
+                                background: 'var(--bg-section)', borderRadius: 'var(--radius)',
+                              }}>
+                                <code style={{ fontFamily: 'var(--font-mono)', fontSize: 11, color: 'var(--text)', fontWeight: 600 }}>
+                                  $ {ex.cmd}
+                                </code>
+                                <div style={{ fontSize: 11, color: 'var(--text-dim)', marginTop: 2 }}>{ex.desc}</div>
+                              </div>
+                            ))}
+                          </div>
+                        </div>
+
+                        {/* Note */}
+                        {cmd.note && (
+                          <div style={{
+                            padding: '8px 12px', marginBottom: cmd.runnable ? 14 : 0,
+                            background: 'var(--yellow-light)', borderRadius: 'var(--radius)',
+                            fontSize: 11, color: 'var(--yellow)', fontWeight: 500,
+                            borderLeft: '3px solid var(--yellow)',
+                          }}>
+                            {cmd.note}
+                          </div>
+                        )}
+
+                        {/* Run button */}
+                        {cmd.runnable && (
+                          <QuickActions actions={[{
+                            id: cmd.runnable.command,
+                            label: cmd.runnable.label,
+                            command: cmd.runnable.command,
+                            icon: cmd.runnable.icon,
+                            color: cmd.runnable.color,
+                            description: `Run: helixevo ${cmd.name}`,
+                          }]} />
+                        )}
+                      </div>
+                    )}
+                  </div>
+                )
+              })}
+            </div>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/dashboard/app/layout.tsx

@@ -15,6 +15,7 @@ const NAV = [
   { href: '/evolution', label: 'Evolution', icon: 'M13 7h8m0 0v8m0-8l-8 8-4-4-6 6' },
   { href: '/research', label: 'Research', icon: 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z' },
   { href: '/frontier', label: 'Frontier', icon: 'M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z' },
+  { href: '/commands', label: 'Commands', icon: 'M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z' },
   { href: '/guide', label: 'Guide', icon: 'M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253' },
 ]
 

package/dashboard/app/page.tsx

@@ -1,4 +1,5 @@
-import { getDashboardSummary, loadFrontier, loadHistory, loadGraph } from '@/lib/data'
+import { getDashboardSummary, loadFrontier, loadHistory, loadGraph, loadFailures } from '@/lib/data'
+import { OverviewActions } from '@/components/overview-actions'
 
 export const dynamic = 'force-dynamic'
 
@@ -28,6 +29,7 @@ export default function Overview() {
   const frontier = loadFrontier()
   const history = loadHistory()
   const graph = loadGraph()
+  const failures = loadFailures()
   const recent = history.iterations.slice(-5).reverse()
 
   return (
@@ -39,6 +41,18 @@ export default function Overview() {
         </p>
       </div>
 
+      {/* Quick Actions */}
+      <div className="card" style={{ marginBottom: 20, padding: '14px 18px' }}>
+        <div style={{ fontSize: 9, fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 1.5, marginBottom: 10 }}>
+          Quick Actions
+        </div>
+        <OverviewActions
+          hasSkills={graph.nodes.length > 0}
+          hasFailures={failures.length > 0}
+          hasEdges={graph.edges.length > 0}
+        />
+      </div>
+
       {/* Stats */}
       <div className="grid-5" style={{ marginBottom: 28 }}>
         <StatCard value={s.skills.total} label="Total Skills" color="var(--purple)" sub={`${s.skills.evolved} evolved`} accent="◆" />

package/dashboard/components/overview-actions.tsx

@@ -0,0 +1,74 @@
+'use client'
+
+import { QuickActions } from './quick-actions'
+
+interface OverviewActionsProps {
+  hasFailures: boolean
+  hasSkills: boolean
+  hasEdges: boolean
+}
+
+export function OverviewActions({ hasFailures, hasSkills, hasEdges }: OverviewActionsProps) {
+  const actions = [
+    {
+      id: 'graph-rebuild',
+      label: 'Organize Skills',
+      command: 'graph-rebuild',
+      icon: 'M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1',
+      color: 'var(--purple)',
+      description: 'Use LLM to infer relationships between skills (depends, enhances, conflicts)',
+      disabled: !hasSkills,
+      disabledReason: 'No skills imported yet — run helixevo init first',
+    },
+    {
+      id: 'generalize',
+      label: 'Generalize',
+      command: 'generalize',
+      icon: 'M5 10l7-7m0 0l7 7m-7-7v18',
+      color: 'var(--blue)',
+      description: 'Detect patterns across skills and promote to abstract parent skills',
+      disabled: !hasSkills,
+      disabledReason: 'No skills imported yet',
+    },
+    {
+      id: 'evolve',
+      label: 'Evolve',
+      command: 'evolve',
+      icon: 'M13 7h8m0 0v8m0-8l-8 8-4-4-6 6',
+      color: 'var(--green)',
+      description: 'Evolve skills based on captured failures',
+      disabled: !hasFailures,
+      disabledReason: 'No failures captured yet — use Craft Agent and corrections will be captured automatically',
+    },
+    {
+      id: 'health',
+      label: 'Health Check',
+      command: 'health',
+      icon: 'M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z',
+      color: 'var(--yellow)',
+      description: 'Assess network cohesion, coverage, balance, and cross-project transfer',
+      disabled: !hasSkills,
+      disabledReason: 'No skills imported yet',
+    },
+    {
+      id: 'graph-optimize',
+      label: 'Optimize',
+      command: 'graph-optimize',
+      icon: 'M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15',
+      color: 'var(--text-secondary)',
+      description: 'Detect merge/split/conflict opportunities in the skill network',
+      disabled: !hasEdges,
+      disabledReason: 'Run "Organize Skills" first to build relationships',
+    },
+    {
+      id: 'research',
+      label: 'Research',
+      command: 'research',
+      icon: 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z',
+      color: 'var(--purple)',
+      description: 'Proactive web research to discover new skill opportunities',
+    },
+  ]
+
+  return <QuickActions actions={actions} />
+}

package/dashboard/components/quick-actions.tsx

@@ -0,0 +1,177 @@
+'use client'
+
+import { useState } from 'react'
+
+interface Action {
+  id: string
+  label: string
+  command: string
+  icon: string
+  color: string
+  description: string
+  disabled?: boolean
+  disabledReason?: string
+}
+
+interface QuickActionsProps {
+  actions: Action[]
+}
+
+type RunState = 'idle' | 'running' | 'success' | 'error'
+
+export function QuickActions({ actions }: QuickActionsProps) {
+  const [running, setRunning] = useState<string | null>(null)
+  const [state, setState] = useState<RunState>('idle')
+  const [output, setOutput] = useState<string | null>(null)
+
+  const handleRun = async (action: Action) => {
+    if (action.disabled) return
+    setRunning(action.id)
+    setState('running')
+    setOutput(null)
+
+    try {
+      const res = await fetch('/api/run', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ command: action.command }),
+      })
+      const data = await res.json()
+      setOutput(data.output ?? data.error ?? 'No output')
+      setState(data.success ? 'success' : 'error')
+    } catch {
+      setOutput('Network error')
+      setState('error')
+    }
+  }
+
+  const handleClose = () => {
+    setRunning(null)
+    setState('idle')
+    setOutput(null)
+  }
+
+  return (
+    <>
+      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+        {actions.map(action => (
+          <button
+            key={action.id}
+            onClick={() => handleRun(action)}
+            disabled={action.disabled || (running !== null && running !== action.id)}
+            title={action.disabled ? action.disabledReason : action.description}
+            style={{
+              display: 'flex', alignItems: 'center', gap: 6,
+              padding: '8px 14px',
+              background: action.disabled ? 'var(--bg-section)' : 'var(--bg-card)',
+              border: `1px solid ${running === action.id && state === 'running' ? action.color : 'var(--border)'}`,
+              borderRadius: 'var(--radius)',
+              fontSize: 12,
+              fontWeight: 600,
+              color: action.disabled ? 'var(--text-muted)' : 'var(--text-secondary)',
+              cursor: action.disabled ? 'not-allowed' : 'pointer',
+              opacity: (running !== null && running !== action.id) ? 0.5 : 1,
+              transition: 'all 0.15s',
+            }}
+          >
+            {running === action.id && state === 'running' ? (
+              <span style={{
+                width: 14, height: 14, border: '2px solid var(--border)',
+                borderTopColor: action.color, borderRadius: '50%',
+                animation: 'actionSpin 0.8s linear infinite',
+                flexShrink: 0,
+              }} />
+            ) : (
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+                stroke={action.disabled ? 'var(--text-muted)' : action.color}
+                strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <path d={action.icon} />
+              </svg>
+            )}
+            {action.label}
+          </button>
+        ))}
+      </div>
+
+      {/* Output modal */}
+      {running && state !== 'idle' && (
+        <div style={{
+          marginTop: 12,
+          background: 'var(--bg-card)',
+          border: `1px solid ${state === 'success' ? 'var(--green-border)' : state === 'error' ? 'var(--red-border)' : 'var(--border)'}`,
+          borderRadius: 'var(--radius-lg)',
+          overflow: 'hidden',
+        }}>
+          {/* Header */}
+          <div style={{
+            display: 'flex', justifyContent: 'space-between', alignItems: 'center',
+            padding: '10px 14px',
+            background: state === 'running' ? 'var(--bg-section)'
+              : state === 'success' ? 'var(--green-light)'
+              : 'var(--red-light)',
+            borderBottom: '1px solid var(--border)',
+          }}>
+            <div style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 12, fontWeight: 600 }}>
+              {state === 'running' && (
+                <span style={{
+                  width: 12, height: 12, border: '2px solid var(--border)',
+                  borderTopColor: 'var(--purple)', borderRadius: '50%',
+                  animation: 'actionSpin 0.8s linear infinite',
+                }} />
+              )}
+              {state === 'success' && <span style={{ color: 'var(--green)' }}>&#10003;</span>}
+              {state === 'error' && <span style={{ color: 'var(--red)' }}>&#10007;</span>}
+              <span style={{
+                color: state === 'success' ? 'var(--green)' : state === 'error' ? 'var(--red)' : 'var(--text-secondary)',
+              }}>
+                {state === 'running' ? `Running ${actions.find(a => a.id === running)?.label}...`
+                  : state === 'success' ? 'Completed'
+                  : 'Failed'}
+              </span>
+            </div>
+            {state !== 'running' && (
+              <div style={{ display: 'flex', gap: 6 }}>
+                <button onClick={() => { window.location.reload() }} style={{
+                  background: 'none', border: '1px solid var(--border)', borderRadius: 'var(--radius)',
+                  padding: '3px 10px', fontSize: 11, fontWeight: 600, cursor: 'pointer',
+                  color: 'var(--text-secondary)',
+                }}>
+                  Refresh
+                </button>
+                <button onClick={handleClose} style={{
+                  background: 'none', border: '1px solid var(--border)', borderRadius: 'var(--radius)',
+                  padding: '3px 10px', fontSize: 11, fontWeight: 600, cursor: 'pointer',
+                  color: 'var(--text-secondary)',
+                }}>
+                  Close
+                </button>
+              </div>
+            )}
+          </div>
+
+          {/* Output */}
+          <pre style={{
+            padding: '12px 14px',
+            margin: 0,
+            fontSize: 11,
+            lineHeight: 1.5,
+            fontFamily: 'var(--font-mono)',
+            color: 'var(--text-secondary)',
+            maxHeight: 400,
+            overflow: 'auto',
+            whiteSpace: 'pre-wrap',
+            wordBreak: 'break-word',
+          }}>
+            {output ?? 'Waiting for output...'}
+          </pre>
+        </div>
+      )}
+
+      <style>{`
+        @keyframes actionSpin {
+          to { transform: rotate(360deg); }
+        }
+      `}</style>
+    </>
+  )
+}

package/dashboard/components/update-banner.tsx

@@ -15,10 +15,14 @@ function compareVersions(current: string, latest: string): boolean {
   return false
 }
 
+type UpdateState = 'idle' | 'updating' | 'success' | 'error'
+
 export function UpdateBanner({ currentVersion }: { currentVersion: string }) {
   const [latestVersion, setLatestVersion] = useState<string | null>(null)
   const [dismissed, setDismissed] = useState(false)
-  const [copied, setCopied] = useState(false)
+  const [state, setState] = useState<UpdateState>('idle')
+  const [newVersion, setNewVersion] = useState<string | null>(null)
+  const [errorMsg, setErrorMsg] = useState<string | null>(null)
 
   useEffect(() => {
     let mounted = true
@@ -41,14 +45,29 @@ export function UpdateBanner({ currentVersion }: { currentVersion: string }) {
 
   if (!latestVersion || dismissed) return null
 
-  const command = 'npm install -g helixevo@latest'
+  const handleUpdate = async () => {
+    setState('updating')
+    setErrorMsg(null)
 
-  const handleCopy = async () => {
     try {
-      await navigator.clipboard.writeText(command)
-      setCopied(true)
-      setTimeout(() => setCopied(false), 2000)
-    } catch {}
+      const res = await fetch('/api/upgrade', { method: 'POST' })
+      const data = await res.json()
+
+      if (data.success) {
+        setState('success')
+        setNewVersion(data.version)
+        // Reload after a brief delay to show success state
+        setTimeout(() => {
+          window.location.reload()
+        }, 2000)
+      } else {
+        setState('error')
+        setErrorMsg(data.error ?? 'Update failed')
+      }
+    } catch (err) {
+      setState('error')
+      setErrorMsg('Network error — try running: npm install -g helixevo@latest')
+    }
   }
 
   return (
@@ -58,7 +77,7 @@ export function UpdateBanner({ currentVersion }: { currentVersion: string }) {
       right: 20,
       width: 320,
       background: 'var(--bg-card)',
-      border: '1px solid var(--purple-border)',
+      border: `1px solid ${state === 'success' ? 'var(--green-border)' : state === 'error' ? 'var(--red-border)' : 'var(--purple-border)'}`,
       borderRadius: 'var(--radius-lg)',
       boxShadow: 'var(--shadow-xl)',
       padding: '16px 18px',
@@ -66,83 +85,168 @@ export function UpdateBanner({ currentVersion }: { currentVersion: string }) {
       animation: 'updateSlideIn 0.4s ease-out',
     }}>
       {/* Close button */}
-      <button
-        onClick={() => setDismissed(true)}
-        style={{
-          position: 'absolute', top: 8, right: 10,
-          background: 'none', border: 'none', cursor: 'pointer',
-          color: 'var(--text-dim)', fontSize: 18, lineHeight: 1,
-          padding: '2px 4px',
-        }}
-        aria-label="Dismiss"
-      >
-        &times;
-      </button>
+      {state !== 'updating' && (
+        <button
+          onClick={() => setDismissed(true)}
+          style={{
+            position: 'absolute', top: 8, right: 10,
+            background: 'none', border: 'none', cursor: 'pointer',
+            color: 'var(--text-dim)', fontSize: 18, lineHeight: 1,
+            padding: '2px 4px',
+          }}
+          aria-label="Dismiss"
+        >
+          &times;
+        </button>
+      )}
 
       {/* Header */}
-      <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 10 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12 }}>
         <div style={{
           width: 28, height: 28, borderRadius: '50%',
-          background: 'var(--purple-light)', display: 'flex',
+          background: state === 'success' ? 'var(--green-light)'
+            : state === 'error' ? 'var(--red-light)'
+            : 'var(--purple-light)',
+          display: 'flex',
           alignItems: 'center', justifyContent: 'center',
         }}>
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="var(--purple)" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
-            <path d="M12 19V5m-7 7l7-7 7 7" />
-          </svg>
+          {state === 'updating' ? (
+            <div style={{
+              width: 14, height: 14, border: '2px solid var(--purple-border)',
+              borderTopColor: 'var(--purple)', borderRadius: '50%',
+              animation: 'updateSpin 0.8s linear infinite',
+            }} />
+          ) : state === 'success' ? (
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="var(--green)" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M20 6L9 17l-5-5" />
+            </svg>
+          ) : state === 'error' ? (
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="var(--red)" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M18 6L6 18M6 6l12 12" />
+            </svg>
+          ) : (
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="var(--purple)" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M12 19V5m-7 7l7-7 7 7" />
+            </svg>
+          )}
         </div>
         <div>
           <div style={{ fontSize: 13, fontWeight: 700, color: 'var(--text)', letterSpacing: -0.2 }}>
-            Update Available
+            {state === 'updating' ? 'Updating...'
+              : state === 'success' ? 'Updated!'
+              : state === 'error' ? 'Update Failed'
+              : 'Update Available'}
           </div>
           <div style={{ fontSize: 11, color: 'var(--text-dim)' }}>
-            v{currentVersion} &rarr; <span style={{ color: 'var(--green)', fontWeight: 600 }}>v{latestVersion}</span>
+            {state === 'success'
+              ? <>Now on <span style={{ color: 'var(--green)', fontWeight: 600 }}>v{newVersion}</span> — restarting...</>
+              : <>v{currentVersion} &rarr; <span style={{ color: 'var(--green)', fontWeight: 600 }}>v{latestVersion}</span></>
+            }
           </div>
         </div>
       </div>
 
-      {/* Command */}
-      <div
-        onClick={handleCopy}
-        style={{
+      {/* Action area */}
+      {state === 'idle' && (
+        <button
+          onClick={handleUpdate}
+          style={{
+            width: '100%',
+            padding: '9px 16px',
+            background: 'var(--purple)',
+            color: '#fff',
+            border: 'none',
+            borderRadius: 'var(--radius)',
+            fontSize: 13,
+            fontWeight: 600,
+            cursor: 'pointer',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 6,
+            transition: 'opacity 0.15s',
+          }}
+          onMouseOver={e => (e.currentTarget.style.opacity = '0.9')}
+          onMouseOut={e => (e.currentTarget.style.opacity = '1')}
+        >
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M21 12a9 9 0 01-9 9m9-9a9 9 0 00-9-9m9 9H3m9 9a9 9 0 01-9-9m9 9c1.657 0 3-4.03 3-9s-1.343-9-3-9m0 18c-1.657 0-3-4.03-3-9s1.343-9 3-9" />
+          </svg>
+          Update Now
+        </button>
+      )}
+
+      {state === 'updating' && (
+        <div style={{
+          width: '100%',
+          padding: '9px 16px',
           background: 'var(--bg-section)',
-          border: '1px solid var(--border)',
           borderRadius: 'var(--radius)',
-          padding: '8px 12px',
-          fontFamily: 'var(--font-mono)',
-          fontSize: 11,
+          fontSize: 12,
           color: 'var(--text-secondary)',
-          cursor: 'pointer',
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'space-between',
-          gap: 8,
-          transition: 'border-color 0.15s',
-        }}
-        title="Click to copy"
-      >
-        <span style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
-          $ {command}
-        </span>
-        <span style={{
-          fontSize: 10, fontFamily: 'var(--font)', fontWeight: 600,
-          color: copied ? 'var(--green)' : 'var(--purple)',
-          whiteSpace: 'nowrap',
-          flexShrink: 0,
+          textAlign: 'center',
         }}>
-          {copied ? 'Copied!' : 'Copy'}
-        </span>
-      </div>
+          Installing helixevo@latest...
+        </div>
+      )}
 
-      {/* Subtle hint */}
-      <div style={{ fontSize: 10, color: 'var(--text-muted)', marginTop: 8, textAlign: 'center' }}>
-        Run in terminal, then refresh dashboard
-      </div>
+      {state === 'success' && (
+        <div style={{
+          width: '100%',
+          padding: '9px 16px',
+          background: 'var(--green-light)',
+          borderRadius: 'var(--radius)',
+          fontSize: 12,
+          color: 'var(--green)',
+          textAlign: 'center',
+          fontWeight: 600,
+        }}>
+          Restarting dashboard...
+        </div>
+      )}
+
+      {state === 'error' && (
+        <>
+          <div style={{
+            width: '100%',
+            padding: '8px 12px',
+            background: 'var(--red-light)',
+            borderRadius: 'var(--radius)',
+            fontSize: 11,
+            color: 'var(--red)',
+            marginBottom: 8,
+            maxHeight: 60,
+            overflow: 'auto',
+          }}>
+            {errorMsg}
+          </div>
+          <button
+            onClick={handleUpdate}
+            style={{
+              width: '100%',
+              padding: '7px 12px',
+              background: 'var(--bg-section)',
+              color: 'var(--text-secondary)',
+              border: '1px solid var(--border)',
+              borderRadius: 'var(--radius)',
+              fontSize: 12,
+              fontWeight: 600,
+              cursor: 'pointer',
+            }}
+          >
+            Retry
+          </button>
+        </>
+      )}
 
       <style>{`
         @keyframes updateSlideIn {
           from { opacity: 0; transform: translateY(16px) scale(0.97); }
           to { opacity: 1; transform: translateY(0) scale(1); }
         }
+        @keyframes updateSpin {
+          to { transform: rotate(360deg); }
+        }
       `}</style>
     </div>
   )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helixevo",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Self-evolving skill ecosystem for AI agents. Skills and projects co-evolve through multi-judge evaluation and a Pareto frontier.",
   "type": "module",
   "bin": {