helixevo 0.2.39 → 0.2.41

package/dashboard/app/commands/page.tsx

@@ -1,7 +1,10 @@
 'use client'
 
-import { useState } from 'react'
+import { useMemo, useState } from 'react'
+import { MetricCard } from '@/components/metric-card'
+import { PageHero } from '@/components/page-hero'
 import { QuickActions } from '@/components/quick-actions'
+import { SectionFrame } from '@/components/section-frame'
 
 interface CommandInfo {
   name: string
@@ -222,209 +225,290 @@ const COMMANDS: CommandInfo[] = [
   },
   {
     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',
+    description: 'Launch the web dashboard at http://localhost:3847. When a newer npm version is available, HelixEvo now auto-updates itself before opening the dashboard unless you opt out.',
+    usage: 'helixevo dashboard [options]',
     examples: [
-      { cmd: 'helixevo dashboard', desc: 'Open the dashboard in your browser' },
+      { cmd: 'helixevo dashboard', desc: 'Auto-update to the latest version if needed, then open the dashboard' },
+      { cmd: 'helixevo dashboard --background', desc: 'Run the dashboard in the background after the same update check' },
+      { cmd: 'helixevo dashboard --no-auto-update', desc: 'Open the dashboard immediately without checking npm for updates' },
+    ],
+    options: [
+      { flag: '--background', desc: 'Run the dashboard detached from the terminal' },
+      { flag: '--stop', desc: 'Stop a background dashboard process' },
+      { flag: '--no-auto-update', desc: 'Skip the automatic update check before launch' },
     ],
     category: 'system',
     needsLLM: false,
-    note: 'You are currently using the dashboard!',
+    note: 'You are currently using the dashboard. By default it now upgrades itself first when a newer release is available.',
   },
 ]
 
-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)' },
+const WORKFLOW = [
+  { label: 'init', desc: 'Import skills', tone: 'purple' as const },
+  { label: 'watch', desc: 'Capture corrections', tone: 'blue' as const },
+  { label: 'evolve', desc: 'Improve skills', tone: 'green' as const },
+  { label: 'generalize', desc: 'Abstract patterns', tone: 'purple' as const },
+  { label: 'graph --rebuild', desc: 'Map relationships', tone: 'yellow' as const },
+  { label: 'health', desc: 'Assess quality', tone: 'blue' as const },
+]
+
+const CATEGORIES: Array<{
+  id: CommandInfo['category']
+  label: string
+  tone: 'neutral' | 'purple' | 'green' | 'blue' | 'yellow'
+  description: string
+}> = [
+  { id: 'core', label: 'Core workflow', tone: 'purple', description: 'The commands that initialize HelixEvo and keep it learning continuously.' },
+  { id: 'evolution', label: 'Evolution', tone: 'green', description: 'Mutation, promotion, and specialization controls for active skill improvement.' },
+  { id: 'network', label: 'Network & research', tone: 'blue', description: 'Graph maintenance, discovery, and relationship mapping across the skill ecosystem.' },
+  { id: 'analysis', label: 'Analysis & reports', tone: 'yellow', description: 'Operational reads on system quality, trends, reports, and health.' },
+  { id: 'system', label: 'System', tone: 'neutral', description: 'Supporting commands for capture, dashboard access, and environment-level actions.' },
 ]
 
+function toneColor(tone: 'neutral' | 'purple' | 'green' | 'blue' | 'yellow') {
+  if (tone === 'purple') return 'var(--purple)'
+  if (tone === 'green') return 'var(--green)'
+  if (tone === 'blue') return 'var(--blue)'
+  if (tone === 'yellow') return 'var(--yellow)'
+  return 'var(--text-secondary)'
+}
+
 export default function CommandsPage() {
-  const [expandedCmd, setExpandedCmd] = useState<string | null>(null)
+  const [expandedCmd, setExpandedCmd] = useState<string | null>('watch')
+
+  const stats = useMemo(() => {
+    const llmCommands = COMMANDS.filter(command => command.needsLLM).length
+    const runnableCommands = COMMANDS.filter(command => command.runnable).length
+    const optionFlags = COMMANDS.reduce((sum, command) => sum + (command.options?.length ?? 0), 0)
+    return { llmCommands, runnableCommands, optionFlags }
+  }, [])
 
   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>
+      <PageHero
+        eyebrow="Command center"
+        title="Commands"
+        description="The complete HelixEvo CLI surface — organized by workflow, annotated by purpose, and ready to run from the dashboard when supported."
+        chips={[
+          { label: `${COMMANDS.length} commands`, tone: 'blue' },
+          { label: `${stats.llmCommands} need LLM access`, tone: 'purple' },
+          { label: `${stats.runnableCommands} runnable here`, tone: 'green' },
+          { label: `${stats.optionFlags} documented flags`, tone: 'yellow' },
+        ]}
+        actions={
+          <div className="hero-note-card">
+            <div className="hero-note-label">Recommended operating loop</div>
+            <div className="hero-note-title">Init → Watch → Evolve → Generalize → Graph → Health</div>
+            <div className="hero-note-copy">Use the Commands page as the practical bridge between HelixEvo’s CLI and the premium dashboard cockpit.</div>
+          </div>
+        }
+      />
+
+      <div className="grid-4" style={{ marginBottom: 24 }}>
+        <MetricCard label="CLI surface" value={COMMANDS.length} sublabel="Documented HelixEvo commands across core, evolution, network, analysis, and system layers." tone="blue" />
+        <MetricCard label="Live actions" value={stats.runnableCommands} sublabel="Commands with dashboard launch actions wired through the quick action system." tone="green" />
+        <MetricCard label="LLM-dependent" value={stats.llmCommands} sublabel="Commands that rely on model-backed evaluation, generation, or analysis." tone="purple" />
+        <MetricCard label="Flags documented" value={stats.optionFlags} sublabel="Total option flags surfaced across the current command reference." tone="yellow" />
       </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,
+      <SectionFrame
+        eyebrow="Workflow framing"
+        title="Typical operating sequence"
+        description="A high-signal path through the CLI when standing HelixEvo up and then keeping it improving over time."
+        tone="purple"
+      >
+        <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
+          {WORKFLOW.map((step, index) => (
+            <div key={step.label} style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+              <div style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                gap: 8,
+                padding: '10px 14px',
+                borderRadius: 999,
+                border: '1px solid var(--border)',
+                background: 'rgba(255,255,255,0.72)',
+                boxShadow: 'var(--shadow-xs)',
               }}>
-                {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>
+                <span className={`hero-chip hero-chip-${step.tone}`}>{step.label}</span>
+                <span style={{ fontSize: 12, color: 'var(--text-dim)' }}>{step.desc}</span>
+              </div>
+              {index < WORKFLOW.length - 1 ? <span style={{ color: 'var(--text-muted)', fontSize: 15 }}>→</span> : null}
+            </div>
           ))}
         </div>
-      </div>
+      </SectionFrame>
 
-      {/* Commands by category */}
-      {CATEGORIES.map(cat => {
-        const cmds = COMMANDS.filter(c => c.category === cat.id)
-        if (cmds.length === 0) return null
+      {CATEGORIES.map(category => {
+        const commands = COMMANDS.filter(command => command.category === category.id)
+        if (commands.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>
+          <SectionFrame
+            key={category.id}
+            eyebrow={`${commands.length} command${commands.length === 1 ? '' : 's'}`}
+            title={category.label}
+            description={category.description}
+            tone={category.tone}
+            className="section-frame-tight"
+          >
+            <div style={{ display: 'grid', gap: 12 }}>
+              {commands.map(command => {
+                const isExpanded = expandedCmd === command.name
+                const categoryColor = toneColor(category.tone)
 
-            <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
-              {cmds.map(cmd => {
-                const isExpanded = expandedCmd === cmd.name
                 return (
-                  <div key={cmd.name} className="card" style={{
+                  <article key={command.name} className="card" style={{
                     overflow: 'hidden',
-                    border: isExpanded ? `1px solid ${cat.color}40` : undefined,
+                    borderColor: isExpanded ? `${categoryColor}30` : undefined,
+                    boxShadow: isExpanded ? 'var(--shadow-md)' : undefined,
                   }}>
-                    {/* Command header — clickable */}
-                    <div
-                      onClick={() => setExpandedCmd(isExpanded ? null : cmd.name)}
+                    <button
+                      onClick={() => setExpandedCmd(isExpanded ? null : command.name)}
                       style={{
-                        padding: '12px 16px',
+                        width: '100%',
+                        padding: '16px 18px',
+                        border: 'none',
+                        background: isExpanded ? 'linear-gradient(180deg, rgba(255,255,255,0.92), rgba(245,241,236,0.82))' : 'transparent',
+                        display: 'flex',
+                        justifyContent: 'space-between',
+                        alignItems: 'flex-start',
+                        gap: 16,
                         cursor: 'pointer',
-                        display: 'flex', justifyContent: 'space-between', alignItems: 'center',
+                        textAlign: 'left',
                       }}
                     >
-                      <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 style={{ flex: 1, minWidth: 0 }}>
+                        <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap', marginBottom: 8 }}>
+                          <code style={{ fontFamily: 'var(--font-mono)', fontSize: 14, fontWeight: 700, color: categoryColor }}>
+                            {command.name}
+                          </code>
+                          <span className={`hero-chip hero-chip-${category.tone}`}>{category.label}</span>
+                          {command.needsLLM ? <span className="hero-chip hero-chip-purple">LLM</span> : <span className="hero-chip hero-chip-neutral">local</span>}
+                          {command.runnable ? <span className="hero-chip hero-chip-green">runnable</span> : null}
+                        </div>
+                        <div style={{ fontSize: 12.5, color: 'var(--text-secondary)', lineHeight: 1.65, maxWidth: 860 }}>
+                          {command.description}
+                        </div>
                       </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)',
+                        flexShrink: 0,
+                        width: 30,
+                        height: 30,
+                        borderRadius: 999,
+                        background: 'rgba(97,93,86,0.08)',
+                        border: '1px solid var(--border)',
+                        color: 'var(--text-muted)',
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        transform: isExpanded ? 'rotate(180deg)' : 'none',
+                        transition: 'transform 0.2s ease',
+                        marginTop: 2,
                       }}>
-                        {/* Description */}
-                        <p style={{ fontSize: 12, color: 'var(--text-secondary)', lineHeight: 1.6, marginTop: 12, marginBottom: 14 }}>
-                          {cmd.description}
-                        </p>
+                        ▼
+                      </div>
+                    </button>
 
-                        {/* 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>
+                    {isExpanded ? (
+                      <div style={{ padding: '0 18px 18px', borderTop: '1px solid var(--border-subtle)' }}>
+                        <div className="grid-2" style={{ alignItems: 'start', gap: 16, marginTop: 16 }}>
+                          <div style={{ display: 'grid', gap: 14 }}>
+                            <div>
+                              <div style={{ fontSize: 10.5, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.9, marginBottom: 6 }}>Usage</div>
+                              <code style={{
+                                display: 'block',
+                                padding: '12px 14px',
+                                background: 'rgba(97,93,86,0.07)',
+                                borderRadius: 16,
+                                border: '1px solid var(--border)',
+                                fontFamily: 'var(--font-mono)',
+                                fontSize: 12,
+                                color: 'var(--text)',
+                              }}>
+                                $ {command.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>
+                            {command.options && command.options.length > 0 ? (
+                              <div>
+                                <div style={{ fontSize: 10.5, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.9, marginBottom: 6 }}>Options</div>
+                                <div style={{ display: 'grid', gap: 8 }}>
+                                  {command.options.map(option => (
+                                    <div key={option.flag} style={{
+                                      padding: '10px 12px',
+                                      borderRadius: 14,
+                                      background: 'rgba(255,255,255,0.72)',
+                                      border: '1px solid var(--border)',
+                                    }}>
+                                      <code style={{ display: 'block', fontFamily: 'var(--font-mono)', color: 'var(--purple)', fontSize: 11.5, fontWeight: 700, marginBottom: 4 }}>
+                                        {option.flag}
+                                      </code>
+                                      <div style={{ fontSize: 12, color: 'var(--text-dim)', lineHeight: 1.55 }}>{option.desc}</div>
+                                    </div>
+                                  ))}
                                 </div>
-                              ))}
-                            </div>
-                          </div>
-                        )}
+                              </div>
+                            ) : null}
 
-                        {/* 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)',
+                            {command.note ? (
+                              <div style={{
+                                padding: '12px 14px',
+                                background: 'var(--yellow-light)',
+                                border: '1px solid var(--yellow-border)',
+                                borderRadius: 16,
+                                color: 'var(--yellow)',
+                                fontSize: 12,
+                                lineHeight: 1.6,
                               }}>
-                                <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>
+                                <strong style={{ display: 'block', marginBottom: 4 }}>Operational note</strong>
+                                {command.note}
                               </div>
-                            ))}
+                            ) : null}
                           </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>
-                        )}
+                          <div style={{ display: 'grid', gap: 14 }}>
+                            <div>
+                              <div style={{ fontSize: 10.5, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.9, marginBottom: 6 }}>Examples</div>
+                              <div style={{ display: 'grid', gap: 8 }}>
+                                {command.examples.map((example, index) => (
+                                  <div key={`${command.name}-example-${index}`} style={{
+                                    padding: '12px 14px',
+                                    borderRadius: 16,
+                                    background: 'rgba(255,255,255,0.72)',
+                                    border: '1px solid var(--border)',
+                                  }}>
+                                    <code style={{ display: 'block', fontFamily: 'var(--font-mono)', fontSize: 11.5, color: 'var(--text)', fontWeight: 700, marginBottom: 4 }}>
+                                      $ {example.cmd}
+                                    </code>
+                                    <div style={{ fontSize: 12, color: 'var(--text-dim)', lineHeight: 1.55 }}>{example.desc}</div>
+                                  </div>
+                                ))}
+                              </div>
+                            </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}`,
-                          }]} />
-                        )}
+                            {command.runnable ? (
+                              <div>
+                                <div style={{ fontSize: 10.5, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.9, marginBottom: 8 }}>Launch from dashboard</div>
+                                <QuickActions actions={[{
+                                  id: command.runnable.command,
+                                  label: command.runnable.label,
+                                  command: command.runnable.command,
+                                  icon: command.runnable.icon,
+                                  color: command.runnable.color,
+                                  description: `Run: helixevo ${command.name}`,
+                                }]} />
+                              </div>
+                            ) : null}
+                          </div>
+                        </div>
                       </div>
-                    )}
-                  </div>
+                    ) : null}
+                  </article>
                 )
               })}
             </div>
-          </div>
+          </SectionFrame>
         )
       })}
     </div>