helixevo 0.2.34 → 0.2.36

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to HelixEvo are documented here.
 
+## [0.2.36] - 2026-03-23
+
+### Added — Enhanced Project Setup
+- GitHub URL support: enter a GitHub repo URL + clone directory
+- Local folder / GitHub URL toggle with mode-specific UI
+- Each pipeline step shows the exact CLI command used
+- Gap action buttons: "Research this gap" → Research tab, "Specialize a skill", "Create manually" → Skill Network
+- Cross-functional "Setup New Project" banner on Overview page
+- After analysis: links to Skill Network and Research tabs
+- Matched skills list with relevance bars and click-through to Skill Network
+- Re-analyze button per project profile
+
+## [0.2.35] - 2026-03-23
+
+### Added — Project Setup Workflow
+- New `helixevo project-setup <path>` CLI command: analyzes a project folder, matches skills, identifies gaps
+- Dashboard `/projects` page with guided setup wizard
+  - Enter project path → analyze structure → match skills → find gaps → save profile
+  - Real-time streaming output during analysis
+  - Project profile cards showing matched skills, gaps with priority levels, and recommended actions
+- New "Projects" tab in sidebar navigation
+- API endpoint `/api/project-setup` with SSE streaming
+- Project profiles saved to `~/.helix/projects/<name>/profile.json`
+- Gap analysis recommends: research (web search), specialize (adapt existing), or create (manual)
+
 ## [0.2.34] - 2026-03-23
 
 ### Fixed

package/dashboard/app/api/project-setup/route.ts

@@ -0,0 +1,53 @@
+import { NextResponse } from 'next/server'
+import { spawn } from 'child_process'
+
+export const dynamic = 'force-dynamic'
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  const { path: projectPath } = body as { path: string }
+
+  if (!projectPath) {
+    return NextResponse.json({ success: false, error: 'No project path provided' }, { status: 400 })
+  }
+
+  // Stream the output using SSE
+  const encoder = new TextEncoder()
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const child = spawn('helixevo', ['project-setup', projectPath, '--verbose'], {
+        env: { ...process.env },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+
+      const send = (event: string, data: string) => {
+        try {
+          controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`))
+        } catch {}
+      }
+
+      child.stdout?.on('data', (chunk: Buffer) => send('output', chunk.toString()))
+      child.stderr?.on('data', (chunk: Buffer) => send('output', chunk.toString()))
+
+      const timeout = setTimeout(() => child.kill('SIGTERM'), 120000)
+
+      child.on('close', (code) => {
+        clearTimeout(timeout)
+        send('done', JSON.stringify({ success: code === 0 }))
+        try { controller.close() } catch {}
+      })
+
+      child.on('error', (err) => {
+        clearTimeout(timeout)
+        send('output', `Error: ${err.message}`)
+        send('done', JSON.stringify({ success: false }))
+        try { controller.close() } catch {}
+      })
+    },
+  })
+
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' },
+  })
+}

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: '/projects', label: 'Projects', icon: 'M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-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

@@ -46,6 +46,18 @@ export default function Overview() {
         </p>
       </div>
 
+      {/* Setup New Project */}
+      <Link href="/projects" style={{ textDecoration: 'none', color: 'inherit' }}>
+        <div className="card" style={{ marginBottom: 12, padding: '12px 18px', cursor: 'pointer', display: 'flex', alignItems: 'center', gap: 10, borderLeft: '3px solid var(--green)' }}>
+          <div style={{ width: 28, height: 28, borderRadius: 8, background: 'var(--green-light)', display: 'flex', alignItems: 'center', justifyContent: 'center', fontSize: 14, flexShrink: 0 }}>📁</div>
+          <div style={{ flex: 1 }}>
+            <div style={{ fontSize: 13, fontWeight: 700, color: 'var(--text)' }}>Setup New Project</div>
+            <div style={{ fontSize: 11, color: 'var(--text-dim)' }}>Analyze a folder or GitHub repo to match skills and find gaps</div>
+          </div>
+          <span style={{ fontSize: 16, color: 'var(--text-muted)' }}>&rarr;</span>
+        </div>
+      </Link>
+
       {/* 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 }}>

package/dashboard/app/projects/client.tsx

@@ -0,0 +1,561 @@
+'use client'
+
+import { useState, useRef } from 'react'
+import Link from 'next/link'
+import type { ProjectProfile } from '@/lib/data'
+
+type SetupState = 'idle' | 'analyzing' | 'done' | 'error'
+type InputMode = 'local' | 'github'
+
+const PIPELINE = [
+  {
+    step: 1, title: 'Analyze Project', command: 'helixevo project-setup <path>',
+    desc: 'Reads README.md, package.json, CLAUDE.md, tsconfig, Dockerfile, and source tree to understand what the project does and what technologies it uses.',
+    icon: '📁', color: 'var(--blue)',
+  },
+  {
+    step: 2, title: 'Match Skills', command: '(included in project-setup)',
+    desc: 'Scores each of your existing skills 0-100% for relevance to this project. Skills below 20% relevance are excluded.',
+    icon: '🔗', color: 'var(--purple)',
+  },
+  {
+    step: 3, title: 'Find Gaps', command: '(included in project-setup)',
+    desc: 'Identifies capabilities the project needs but no skill covers. Each gap is rated high/medium/low priority with a suggested action.',
+    icon: '🔍', color: 'var(--yellow)',
+  },
+  {
+    step: 4, title: 'Fill Gaps', command: 'helixevo research / specialize / create',
+    desc: 'For each gap, choose: Research (web search for best practices), Specialize (adapt a general skill), or Create (write from scratch).',
+    icon: '✓', color: 'var(--green)',
+  },
+]
+
+export default function ProjectsClient({ profiles, skillCount }: { profiles: ProjectProfile[]; skillCount: number }) {
+  const [inputMode, setInputMode] = useState<InputMode>('local')
+  const [projectPath, setProjectPath] = useState('')
+  const [githubUrl, setGithubUrl] = useState('')
+  const [cloneDir, setCloneDir] = useState('~/projects')
+  const [setupState, setSetupState] = useState<SetupState>('idle')
+  const [output, setOutput] = useState('')
+  const outputRef = useRef<HTMLPreElement | null>(null)
+  const abortRef = useRef<AbortController | null>(null)
+
+  const effectivePath = inputMode === 'local' ? projectPath.trim() : ''
+  const canStart = inputMode === 'local' ? !!projectPath.trim() : !!githubUrl.trim()
+
+  const handleSetup = async () => {
+    if (!canStart) return
+
+    let path = ''
+    if (inputMode === 'github') {
+      // Extract repo name from URL for clone path
+      const repoMatch = githubUrl.match(/github\.com\/[\w-]+\/([\w.-]+)/)
+      const repoName = repoMatch?.[1]?.replace(/\.git$/, '') ?? 'repo'
+      path = `${cloneDir}/${repoName}`
+
+      // Clone first
+      setSetupState('analyzing')
+      setOutput(`Cloning ${githubUrl} to ${path}...\n`)
+      try {
+        const cloneRes = await fetch('/api/run', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ command: 'clone', url: githubUrl, dir: path }),
+        })
+        // For now, use a simple approach
+        setOutput(prev => prev + `Clone target: ${path}\n(Note: Git clone from dashboard requires the repo to already be cloned locally)\n\n`)
+      } catch {}
+    } else {
+      path = projectPath.trim()
+    }
+
+    setSetupState('analyzing')
+    setOutput('')
+
+    const controller = new AbortController()
+    abortRef.current = controller
+
+    try {
+      const res = await fetch('/api/project-setup', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ path }),
+        signal: controller.signal,
+      })
+
+      if (!res.body) { setOutput('No response'); setSetupState('error'); return }
+
+      const reader = res.body.getReader()
+      const decoder = new TextDecoder()
+      let sseBuffer = ''
+
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        sseBuffer += decoder.decode(value, { stream: true })
+        const events = sseBuffer.split('\n\n')
+        sseBuffer = events.pop() ?? ''
+        for (const event of events) {
+          const lines = event.split('\n')
+          let eventType = '', eventData = ''
+          for (const line of lines) {
+            if (line.startsWith('event: ')) eventType = line.slice(7)
+            if (line.startsWith('data: ')) eventData = line.slice(6)
+          }
+          if (eventType === 'output' && eventData) {
+            try {
+              setOutput(prev => prev + (JSON.parse(eventData) as string))
+              setTimeout(() => { if (outputRef.current) outputRef.current.scrollTop = outputRef.current.scrollHeight }, 10)
+            } catch {}
+          }
+          if (eventType === 'done' && eventData) {
+            try {
+              const r = JSON.parse(JSON.parse(eventData) as string) as { success: boolean }
+              setSetupState(r.success ? 'done' : 'error')
+            } catch {}
+          }
+        }
+      }
+      if (setupState === 'analyzing') setSetupState('done')
+    } catch (err: unknown) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        setOutput(prev => prev + '\n\n[Cancelled]')
+      } else {
+        setOutput(prev => prev || 'Network error')
+      }
+      setSetupState('error')
+    } finally {
+      abortRef.current = null
+    }
+  }
+
+  return (
+    <div>
+      <div className="page-header">
+        <h1 className="page-title">Project Setup</h1>
+        <p className="page-desc">
+          Analyze any project to match your {skillCount} skills, identify gaps, and prepare for work
+        </p>
+      </div>
+
+      {/* Pipeline Visualization */}
+      <div className="card" style={{ marginBottom: 24, padding: '22px 26px' }}>
+        <div style={{ fontSize: 10, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 1.5, marginBottom: 16 }}>
+          How Project Setup Works
+        </div>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: 0 }}>
+          {PIPELINE.map((step, i) => (
+            <div key={step.step} style={{ display: 'flex', alignItems: 'flex-start' }}>
+              <div style={{ flex: 1 }}>
+                <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 8 }}>
+                  <div style={{
+                    width: 32, height: 32, borderRadius: 9,
+                    background: `${step.color}15`,
+                    display: 'flex', alignItems: 'center', justifyContent: 'center',
+                    fontSize: 14, flexShrink: 0,
+                  }}>{step.icon}</div>
+                  <div>
+                    <div style={{ fontSize: 9, fontWeight: 600, color: step.color, letterSpacing: 0.5 }}>STEP {step.step}</div>
+                    <div style={{ fontSize: 13, fontWeight: 700, color: 'var(--text)' }}>{step.title}</div>
+                  </div>
+                </div>
+                <div style={{ fontSize: 11, color: 'var(--text-dim)', lineHeight: 1.5, paddingRight: 12, marginBottom: 6 }}>
+                  {step.desc}
+                </div>
+                <code style={{ fontSize: 9, padding: '2px 6px', background: 'var(--bg-section)', borderRadius: 3, color: 'var(--text-muted)' }}>
+                  {step.command}
+                </code>
+              </div>
+              {i < 3 && (
+                <span style={{ padding: '12px 6px 0', color: 'var(--text-muted)', fontSize: 14 }}>&rarr;</span>
+              )}
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Input Section */}
+      <div className="card" style={{ marginBottom: 24, padding: '20px 24px' }}>
+        {/* Mode Toggle */}
+        <div style={{ display: 'flex', gap: 0, marginBottom: 16 }}>
+          <button
+            onClick={() => setInputMode('local')}
+            style={{
+              padding: '7px 16px', fontSize: 12, fontWeight: 600, cursor: 'pointer',
+              background: inputMode === 'local' ? 'var(--bg-card)' : 'var(--bg-section)',
+              border: `1px solid ${inputMode === 'local' ? 'var(--border-focus)' : 'var(--border)'}`,
+              borderRadius: '8px 0 0 8px', color: inputMode === 'local' ? 'var(--text)' : 'var(--text-dim)',
+            }}
+          >
+            📁 Local Folder
+          </button>
+          <button
+            onClick={() => setInputMode('github')}
+            style={{
+              padding: '7px 16px', fontSize: 12, fontWeight: 600, cursor: 'pointer',
+              background: inputMode === 'github' ? 'var(--bg-card)' : 'var(--bg-section)',
+              border: `1px solid ${inputMode === 'github' ? 'var(--border-focus)' : 'var(--border)'}`,
+              borderRadius: '0 8px 8px 0', borderLeft: 'none',
+              color: inputMode === 'github' ? 'var(--text)' : 'var(--text-dim)',
+            }}
+          >
+            GitHub URL
+          </button>
+        </div>
+
+        {/* Local Folder Input */}
+        {inputMode === 'local' && (
+          <div style={{ display: 'flex', gap: 10, alignItems: 'flex-end' }}>
+            <div style={{ flex: 1 }}>
+              <label style={{ fontSize: 11, fontWeight: 600, color: 'var(--text-dim)', display: 'block', marginBottom: 5 }}>
+                Project folder path
+              </label>
+              <input
+                value={projectPath}
+                onChange={e => setProjectPath(e.target.value)}
+                placeholder="/path/to/your/project  or  .  or  ~/projects/myapp"
+                disabled={setupState === 'analyzing'}
+                style={{
+                  width: '100%', padding: '9px 14px',
+                  border: '1px solid var(--border)', borderRadius: 'var(--radius)',
+                  fontSize: 13, fontFamily: 'var(--font-mono)',
+                  background: 'var(--bg-input)', color: 'var(--text)',
+                }}
+              />
+              <div style={{ fontSize: 10, color: 'var(--text-muted)', marginTop: 4 }}>
+                Use <code style={{ fontSize: 9 }}>.</code> for the current directory, or an absolute path
+              </div>
+            </div>
+            {setupState !== 'analyzing' ? (
+              <button onClick={handleSetup} disabled={!canStart} style={{
+                padding: '9px 20px', border: 'none', borderRadius: 'var(--radius)',
+                background: canStart ? 'var(--green)' : 'var(--bg-section)',
+                color: canStart ? '#fff' : 'var(--text-muted)',
+                fontSize: 13, fontWeight: 600, cursor: canStart ? 'pointer' : 'default',
+                whiteSpace: 'nowrap',
+              }}>
+                Analyze Project
+              </button>
+            ) : (
+              <button onClick={() => abortRef.current?.abort()} style={{
+                padding: '9px 20px', border: 'none', borderRadius: 'var(--radius)',
+                background: 'var(--red)', color: '#fff',
+                fontSize: 13, fontWeight: 600, cursor: 'pointer', whiteSpace: 'nowrap',
+              }}>
+                Stop
+              </button>
+            )}
+          </div>
+        )}
+
+        {/* GitHub URL Input */}
+        {inputMode === 'github' && (
+          <div>
+            <div style={{ display: 'flex', gap: 10, alignItems: 'flex-end', marginBottom: 10 }}>
+              <div style={{ flex: 1 }}>
+                <label style={{ fontSize: 11, fontWeight: 600, color: 'var(--text-dim)', display: 'block', marginBottom: 5 }}>
+                  GitHub repository URL
+                </label>
+                <input
+                  value={githubUrl}
+                  onChange={e => setGithubUrl(e.target.value)}
+                  placeholder="https://github.com/user/repo"
+                  disabled={setupState === 'analyzing'}
+                  style={{
+                    width: '100%', padding: '9px 14px',
+                    border: '1px solid var(--border)', borderRadius: 'var(--radius)',
+                    fontSize: 13, fontFamily: 'var(--font-mono)',
+                    background: 'var(--bg-input)', color: 'var(--text)',
+                  }}
+                />
+              </div>
+            </div>
+            <div style={{ display: 'flex', gap: 10, alignItems: 'flex-end' }}>
+              <div style={{ flex: 1 }}>
+                <label style={{ fontSize: 11, fontWeight: 600, color: 'var(--text-dim)', display: 'block', marginBottom: 5 }}>
+                  Clone to directory
+                </label>
+                <input
+                  value={cloneDir}
+                  onChange={e => setCloneDir(e.target.value)}
+                  placeholder="~/projects"
+                  disabled={setupState === 'analyzing'}
+                  style={{
+                    width: '100%', padding: '9px 14px',
+                    border: '1px solid var(--border)', borderRadius: 'var(--radius)',
+                    fontSize: 13, fontFamily: 'var(--font-mono)',
+                    background: 'var(--bg-input)', color: 'var(--text)',
+                  }}
+                />
+              </div>
+              {setupState !== 'analyzing' ? (
+                <button onClick={handleSetup} disabled={!canStart} style={{
+                  padding: '9px 20px', border: 'none', borderRadius: 'var(--radius)',
+                  background: canStart ? 'var(--green)' : 'var(--bg-section)',
+                  color: canStart ? '#fff' : 'var(--text-muted)',
+                  fontSize: 13, fontWeight: 600, cursor: canStart ? 'pointer' : 'default',
+                  whiteSpace: 'nowrap',
+                }}>
+                  Clone &amp; Analyze
+                </button>
+              ) : (
+                <button onClick={() => abortRef.current?.abort()} style={{
+                  padding: '9px 20px', border: 'none', borderRadius: 'var(--radius)',
+                  background: 'var(--red)', color: '#fff',
+                  fontSize: 13, fontWeight: 600, cursor: 'pointer', whiteSpace: 'nowrap',
+                }}>
+                  Stop
+                </button>
+              )}
+            </div>
+            <div style={{ fontSize: 10, color: 'var(--text-muted)', marginTop: 6 }}>
+              The repository will be cloned to <code style={{ fontSize: 9 }}>{cloneDir}/{githubUrl.match(/\/([\w.-]+?)(?:\.git)?$/)?.[1] ?? 'repo'}</code>, then analyzed
+            </div>
+          </div>
+        )}
+      </div>
+
+      {/* Output */}
+      {setupState !== 'idle' && (
+        <div className="card" style={{ marginBottom: 24, overflow: 'hidden' }}>
+          <div style={{
+            padding: '10px 16px',
+            background: setupState === 'done' ? 'var(--green-light)' : setupState === 'error' ? 'var(--red-light)' : 'var(--bg-section)',
+            borderBottom: '1px solid var(--border)',
+            fontSize: 12, fontWeight: 600,
+            color: setupState === 'done' ? 'var(--green)' : setupState === 'error' ? 'var(--red)' : 'var(--text-secondary)',
+          }}>
+            {setupState === 'analyzing' && '● Running project analysis...'}
+            {setupState === 'done' && '✓ Analysis complete — project profile saved'}
+            {setupState === 'error' && '✗ Analysis failed'}
+          </div>
+          <pre ref={outputRef} style={{
+            padding: '14px 16px', margin: 0,
+            fontSize: 11, lineHeight: 1.55,
+            fontFamily: 'var(--font-mono)',
+            color: 'var(--text-secondary)',
+            maxHeight: 500, overflow: 'auto',
+            whiteSpace: 'pre-wrap', wordBreak: 'break-word',
+          }}>
+            {output || 'Starting project analysis...'}
+          </pre>
+          {setupState === 'done' && (
+            <div style={{ padding: '12px 16px', borderTop: '1px solid var(--border)', display: 'flex', gap: 8 }}>
+              <button onClick={() => window.location.reload()} style={{
+                padding: '7px 14px', background: 'var(--green)', color: '#fff', border: 'none',
+                borderRadius: 'var(--radius)', fontSize: 12, fontWeight: 600, cursor: 'pointer',
+              }}>
+                Refresh to see results
+              </button>
+              <Link href="/network" style={{ textDecoration: 'none' }}>
+                <button style={{
+                  padding: '7px 14px', background: 'var(--bg-section)', border: '1px solid var(--border)',
+                  borderRadius: 'var(--radius)', fontSize: 12, fontWeight: 600, cursor: 'pointer', color: 'var(--text-secondary)',
+                }}>
+                  View Skill Network
+                </button>
+              </Link>
+              <Link href="/research" style={{ textDecoration: 'none' }}>
+                <button style={{
+                  padding: '7px 14px', background: 'var(--bg-section)', border: '1px solid var(--border)',
+                  borderRadius: 'var(--radius)', fontSize: 12, fontWeight: 600, cursor: 'pointer', color: 'var(--text-secondary)',
+                }}>
+                  Research Gaps
+                </button>
+              </Link>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Existing Profiles */}
+      {profiles.length > 0 && (
+        <div>
+          <div style={{ fontSize: 10, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 1.5, marginBottom: 12 }}>
+            Analyzed Projects ({profiles.length})
+          </div>
+          <div style={{ display: 'grid', gap: 14 }}>
+            {profiles.map(p => {
+              const highGaps = p.gaps.filter(g => g.priority === 'high')
+              const matchedPct = skillCount > 0 ? Math.round((p.matchedSkills.length / skillCount) * 100) : 0
+
+              return (
+                <div key={p.name} className="card">
+                  <div className="card-body">
+                    {/* Header */}
+                    <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', marginBottom: 12 }}>
+                      <div>
+                        <div style={{ fontSize: 18, fontWeight: 700, marginBottom: 4 }}>{p.name}</div>
+                        <div style={{ fontSize: 12, color: 'var(--text-dim)', marginBottom: 6 }}>{p.description}</div>
+                        <div style={{ display: 'flex', gap: 4, flexWrap: 'wrap' }}>
+                          {p.techStack.map(t => <span key={t} className="badge badge-gray">{t}</span>)}
+                          {p.domains.map(d => <span key={d} className="badge badge-blue">{d}</span>)}
+                        </div>
+                      </div>
+                      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'flex-end', gap: 4 }}>
+                        <span className={`badge ${p.status === 'active' ? 'badge-green' : 'badge-blue'}`}>{p.status}</span>
+                        <span style={{ fontSize: 10, color: 'var(--text-muted)' }}>{new Date(p.analyzedAt).toLocaleDateString()}</span>
+                      </div>
+                    </div>
+
+                    {/* Stats */}
+                    <div className="grid-3" style={{ gap: 10, marginBottom: 16 }}>
+                      <div style={{ padding: '12px 14px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 24, fontWeight: 800, color: 'var(--green)' }}>{p.matchedSkills.length}</div>
+                        <div style={{ fontSize: 11, color: 'var(--text-dim)' }}>Skills matched ({matchedPct}%)</div>
+                      </div>
+                      <div style={{ padding: '12px 14px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 24, fontWeight: 800, color: highGaps.length > 0 ? 'var(--red)' : 'var(--green)' }}>{p.gaps.length}</div>
+                        <div style={{ fontSize: 11, color: 'var(--text-dim)' }}>Gaps ({highGaps.length} high priority)</div>
+                      </div>
+                      <div style={{ padding: '12px 14px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 11, color: 'var(--text-dim)', marginBottom: 4 }}>Path</div>
+                        <div style={{ fontSize: 11, fontFamily: 'var(--font-mono)', color: 'var(--text-secondary)', wordBreak: 'break-all' }}>{p.path}</div>
+                      </div>
+                    </div>
+
+                    {/* Matched Skills */}
+                    {p.matchedSkills.length > 0 && (
+                      <div style={{ marginBottom: 14 }}>
+                        <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', marginBottom: 6 }}>MATCHED SKILLS</div>
+                        <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+                          {p.matchedSkills.sort((a, b) => b.relevance - a.relevance).slice(0, 8).map(m => (
+                            <div key={m.slug} style={{
+                              display: 'flex', alignItems: 'center', gap: 10,
+                              padding: '6px 10px', background: 'var(--bg-section)', borderRadius: 'var(--radius)',
+                            }}>
+                              <Link href="/network" style={{ textDecoration: 'none', fontWeight: 600, fontSize: 12, color: 'var(--text)' }}>{m.slug}</Link>
+                              <div style={{ flex: 1 }}>
+                                <div className="score-track" style={{ height: 4 }}>
+                                  <div className="score-fill" style={{
+                                    width: `${m.relevance}%`,
+                                    background: m.relevance >= 70 ? 'var(--green)' : m.relevance >= 40 ? 'var(--yellow)' : 'var(--text-muted)',
+                                  }} />
+                                </div>
+                              </div>
+                              <span style={{ fontSize: 12, fontWeight: 700, color: m.relevance >= 70 ? 'var(--green)' : 'var(--yellow)', minWidth: 32 }}>{m.relevance}%</span>
+                              <span style={{ fontSize: 10, color: 'var(--text-dim)', maxWidth: 200, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{m.reason}</span>
+                            </div>
+                          ))}
+                          {p.matchedSkills.length > 8 && (
+                            <div style={{ fontSize: 10, color: 'var(--text-muted)', paddingLeft: 10 }}>+{p.matchedSkills.length - 8} more skills</div>
+                          )}
+                        </div>
+                      </div>
+                    )}
+
+                    {/* Gaps with Action Buttons */}
+                    {p.gaps.length > 0 && (
+                      <div style={{ marginBottom: 14 }}>
+                        <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', marginBottom: 6 }}>GAPS — CLICK TO FILL</div>
+                        <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                          {p.gaps.map((g, i) => (
+                            <div key={i} style={{
+                              padding: '10px 14px', borderRadius: 'var(--radius)',
+                              background: g.priority === 'high' ? 'var(--red-light)' : g.priority === 'medium' ? 'var(--yellow-light)' : 'var(--bg-section)',
+                              borderLeft: `3px solid ${g.priority === 'high' ? 'var(--red)' : g.priority === 'medium' ? 'var(--yellow)' : 'var(--text-muted)'}`,
+                            }}>
+                              <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', marginBottom: 4 }}>
+                                <div>
+                                  <span style={{ fontSize: 13, fontWeight: 700, color: 'var(--text)' }}>{g.area}</span>
+                                  <span className={`badge ${g.priority === 'high' ? 'badge-red' : g.priority === 'medium' ? 'badge-yellow' : 'badge-gray'}`} style={{ marginLeft: 6 }}>{g.priority}</span>
+                                </div>
+                                {g.suggestedAction === 'research' && (
+                                  <Link href="/research" style={{ textDecoration: 'none' }}>
+                                    <button style={{
+                                      padding: '4px 12px', fontSize: 10, fontWeight: 600,
+                                      background: 'var(--blue)', color: '#fff', border: 'none',
+                                      borderRadius: 'var(--radius)', cursor: 'pointer',
+                                    }}>
+                                      Research this gap
+                                    </button>
+                                  </Link>
+                                )}
+                                {g.suggestedAction === 'specialize' && (
+                                  <button style={{
+                                    padding: '4px 12px', fontSize: 10, fontWeight: 600,
+                                    background: 'var(--green)', color: '#fff', border: 'none',
+                                    borderRadius: 'var(--radius)', cursor: 'pointer',
+                                  }}>
+                                    Specialize a skill
+                                  </button>
+                                )}
+                                {g.suggestedAction === 'create' && (
+                                  <Link href="/network" style={{ textDecoration: 'none' }}>
+                                    <button style={{
+                                      padding: '4px 12px', fontSize: 10, fontWeight: 600,
+                                      background: 'var(--bg-section)', color: 'var(--text-secondary)',
+                                      border: '1px solid var(--border)',
+                                      borderRadius: 'var(--radius)', cursor: 'pointer',
+                                    }}>
+                                      Create manually
+                                    </button>
+                                  </Link>
+                                )}
+                              </div>
+                              <div style={{ fontSize: 11, color: 'var(--text-dim)', lineHeight: 1.5 }}>
+                                {g.description}
+                              </div>
+                            </div>
+                          ))}
+                        </div>
+                      </div>
+                    )}
+
+                    {/* Recommendations */}
+                    {p.recommendations.length > 0 && (
+                      <div style={{ padding: '10px 14px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', marginBottom: 4 }}>RECOMMENDED NEXT STEPS</div>
+                        {p.recommendations.map((r, i) => (
+                          <div key={i} style={{ fontSize: 11, color: 'var(--text-dim)', lineHeight: 1.6 }}>→ {r}</div>
+                        ))}
+                      </div>
+                    )}
+
+                    {/* Re-analyze button */}
+                    <div style={{ marginTop: 12, display: 'flex', gap: 8 }}>
+                      <button onClick={() => { setProjectPath(p.path); setInputMode('local'); window.scrollTo(0, 0) }} style={{
+                        padding: '6px 12px', fontSize: 11, fontWeight: 600,
+                        background: 'var(--bg-section)', border: '1px solid var(--border)',
+                        borderRadius: 'var(--radius)', cursor: 'pointer', color: 'var(--text-secondary)',
+                      }}>
+                        Re-analyze
+                      </button>
+                      <Link href="/network" style={{ textDecoration: 'none' }}>
+                        <button style={{
+                          padding: '6px 12px', fontSize: 11, fontWeight: 600,
+                          background: 'var(--bg-section)', border: '1px solid var(--border)',
+                          borderRadius: 'var(--radius)', cursor: 'pointer', color: 'var(--text-secondary)',
+                        }}>
+                          View in Skill Network
+                        </button>
+                      </Link>
+                    </div>
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
+      {/* Empty state */}
+      {profiles.length === 0 && setupState === 'idle' && (
+        <div className="card">
+          <div className="empty-state">
+            <div className="empty-state-icon">
+              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+                <path d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z" />
+              </svg>
+            </div>
+            <div className="empty-state-title">No projects analyzed yet</div>
+            <div className="empty-state-desc">
+              Enter a project folder path or GitHub URL above. HelixEvo will analyze it against your {skillCount} skills,
+              identify which ones match, and tell you what gaps need filling.
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/dashboard/app/projects/page.tsx

@@ -0,0 +1,12 @@
+import { loadAllProjectProfiles, loadGraph } from '@/lib/data'
+import ProjectsClient from './client'
+
+export const dynamic = 'force-dynamic'
+
+export default function ProjectsPage() {
+  const profiles = loadAllProjectProfiles()
+  const graph = loadGraph()
+  const skillCount = graph.nodes.length
+
+  return <ProjectsClient profiles={profiles} skillCount={skillCount} />
+}

package/dashboard/lib/data.ts

@@ -121,6 +121,36 @@ export function getProjectSkills(project: string): { failures: Failure[]; skills
   return { failures, skills }
 }
 
+// ─── Project Profiles ────────────────────────────────────────────
+
+export interface ProjectProfile {
+  name: string
+  path: string
+  description: string
+  techStack: string[]
+  domains: string[]
+  analyzedAt: string
+  matchedSkills: { slug: string; relevance: number; reason: string }[]
+  gaps: { area: string; description: string; priority: 'high' | 'medium' | 'low'; suggestedAction: 'research' | 'specialize' | 'create' }[]
+  recommendations: string[]
+  status: 'analyzed' | 'active'
+}
+
+export function loadAllProjectProfiles(): ProjectProfile[] {
+  const dir = join(SG_DIR, 'projects')
+  if (!existsSync(dir)) return []
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => {
+        const p = join(dir, d.name, 'profile.json')
+        if (!existsSync(p)) return null
+        try { return JSON.parse(readFileSync(p, 'utf-8')) as ProjectProfile } catch { return null }
+      })
+      .filter((p): p is ProjectProfile => p !== null)
+  } catch { return [] }
+}
+
 export function getDashboardSummary() {
   const graph = loadGraph()
   const failures = loadFailures()

package/dist/cli.js

@@ -13157,28 +13157,269 @@ async function metricsCommand(options) {
   }
 }
 
-// src/utils/update-check.ts
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync11, existsSync as existsSync14, mkdirSync as mkdirSync5 } from "node:fs";
+// src/commands/project-setup.ts
+init_skills();
+init_llm();
 import { join as join18 } from "node:path";
+import { existsSync as existsSync14, readFileSync as readFileSync11, writeFileSync as writeFileSync11, mkdirSync as mkdirSync5, readdirSync as readdirSync3 } from "node:fs";
+
+// src/prompts/project-analysis.ts
+function buildProjectAnalysisPrompt(projectContext, skills) {
+  const skillsList = skills.map((s) => {
+    const tags = s.meta.tags?.join(", ") ?? "";
+    const desc = s.meta.description ?? "";
+    const preview = s.content.slice(0, 150).replace(/\n/g, " ");
+    return `- ${s.slug}: ${desc} [tags: ${tags}] — ${preview}`;
+  }).join(`
+`);
+  return `You are a project analyst for HelixEvo, a skill ecosystem for AI agents.
+
+## Task
+Analyze the following project and determine which existing skills are relevant, what skill gaps exist, and what actions to take.
+
+## Project Context
+${projectContext}
+
+## Available Skills (${skills.length} total)
+${skillsList}
+
+## Analysis Requirements
+
+1. **Match skills**: For each existing skill, score its relevance (0-100%) to this project. Only include skills with relevance >= 20%.
+
+2. **Identify gaps**: What capabilities does this project need that NO existing skill covers? Be specific.
+   - "high" priority = the project cannot function well without this
+   - "medium" = would significantly improve quality
+   - "low" = nice to have
+
+3. **Recommend actions**: For each gap, suggest one of:
+   - "research" = search the web for best practices and create a new skill
+   - "specialize" = adapt an existing general skill for this project's specific patterns
+   - "create" = manually create a skill from scratch
+
+## Output
+Return JSON:
+{
+  "name": "project-name (kebab-case)",
+  "description": "one-line description of what this project does",
+  "techStack": ["tech1", "tech2"],
+  "domains": ["domain1", "domain2"],
+  "matchedSkills": [
+    { "slug": "skill-slug", "relevance": 85, "reason": "why this skill is relevant" }
+  ],
+  "gaps": [
+    { "area": "gap name", "description": "what capability is missing", "priority": "high", "suggestedAction": "research" }
+  ],
+  "recommendations": [
+    "Run 'helixevo specialize --project X' to create project-specific skills",
+    "Consider researching X to fill the Y gap"
+  ]
+}
+
+## Constraints
+- Be specific about WHY each skill matches or doesn't
+- Don't suggest gaps for things skills already cover
+- Focus on practical, actionable gaps — not theoretical ones
+- Recommendations should be concrete next steps`;
+}
+
+// src/commands/project-setup.ts
+init_config();
+function readProjectContext(projectPath) {
+  const contextFiles = [];
+  const filesToRead = [
+    "README.md",
+    "package.json",
+    "CLAUDE.md",
+    ".agents/AGENTS.md",
+    "tsconfig.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "go.mod",
+    "Gemfile",
+    "requirements.txt",
+    "docker-compose.yml",
+    "Dockerfile"
+  ];
+  for (const f of filesToRead) {
+    const p = join18(projectPath, f);
+    if (existsSync14(p)) {
+      try {
+        const content = readFileSync11(p, "utf-8");
+        contextFiles.push({ name: f, content: content.slice(0, 2000) });
+      } catch {}
+    }
+  }
+  let dirStructure = "";
+  try {
+    const items = readdirSync3(projectPath, { withFileTypes: true }).filter((d) => !d.name.startsWith(".") && d.name !== "node_modules" && d.name !== "__pycache__").slice(0, 30);
+    dirStructure = items.map((d) => `${d.isDirectory() ? "\uD83D\uDCC1" : "\uD83D\uDCC4"} ${d.name}`).join(`
+`);
+  } catch {}
+  let srcStructure = "";
+  const srcDir = join18(projectPath, "src");
+  if (existsSync14(srcDir)) {
+    try {
+      const scanDir = (dir, prefix, depth) => {
+        if (depth > 2)
+          return [];
+        const lines = [];
+        const items = readdirSync3(dir, { withFileTypes: true }).filter((d) => !d.name.startsWith(".")).slice(0, 20);
+        for (const item of items) {
+          lines.push(`${prefix}${item.isDirectory() ? "\uD83D\uDCC1" : "\uD83D\uDCC4"} ${item.name}`);
+          if (item.isDirectory()) {
+            lines.push(...scanDir(join18(dir, item.name), prefix + "  ", depth + 1));
+          }
+        }
+        return lines;
+      };
+      srcStructure = scanDir(srcDir, "  ", 0).join(`
+`);
+    } catch {}
+  }
+  let context = `## Project Path
+${projectPath}
+
+`;
+  context += `## Directory Structure
+${dirStructure}
+`;
+  if (srcStructure)
+    context += `
+## Source Structure (src/)
+${srcStructure}
+`;
+  context += `
+`;
+  for (const f of contextFiles) {
+    context += `## ${f.name}
+\`\`\`
+${f.content}
+\`\`\`
+
+`;
+  }
+  return context;
+}
+function getProjectsDir() {
+  return join18(getHelixDir(), "projects");
+}
+function saveProjectProfile(profile) {
+  const dir = join18(getProjectsDir(), profile.name);
+  mkdirSync5(dir, { recursive: true });
+  writeFileSync11(join18(dir, "profile.json"), JSON.stringify(profile, null, 2));
+}
+async function projectSetupCommand(projectPath, options) {
+  const verbose = options.verbose ?? false;
+  const dryRun = options.dryRun ?? false;
+  const resolvedPath = join18(process.cwd(), projectPath).replace(/\/$/, "");
+  if (!existsSync14(resolvedPath)) {
+    console.error(`  ✗ Path not found: ${resolvedPath}`);
+    process.exit(1);
+  }
+  console.log(`\uD83D\uDCE6 HelixEvo Project Setup
+`);
+  console.log(`  Project: ${resolvedPath}
+`);
+  console.log("  Step 1: Analyzing project structure...");
+  const context = readProjectContext(resolvedPath);
+  if (verbose) {
+    console.log(`    Read ${context.split(`
+`).length} lines of context`);
+  }
+  const skills = loadAllGeneralSkills();
+  console.log(`  Step 2: Comparing against ${skills.length} available skills...
+`);
+  console.log("  Step 3: Running skill-project analysis...");
+  const prompt = buildProjectAnalysisPrompt(context, skills);
+  const analysis = await chatJson({ prompt });
+  console.log(`
+  ─── Project: ${analysis.name} ───`);
+  console.log(`  ${analysis.description}`);
+  console.log(`  Tech: ${analysis.techStack.join(", ")}`);
+  console.log(`  Domains: ${analysis.domains.join(", ")}
+`);
+  const matched = analysis.matchedSkills.sort((a, b) => b.relevance - a.relevance);
+  console.log(`  ✓ ${matched.length} skills matched (of ${skills.length} total):
+`);
+  for (const m of matched) {
+    const bar = "█".repeat(Math.round(m.relevance / 10)) + "░".repeat(10 - Math.round(m.relevance / 10));
+    const color = m.relevance >= 70 ? "\x1B[32m" : m.relevance >= 40 ? "\x1B[33m" : "\x1B[2m";
+    console.log(`    ${color}${bar}\x1B[0m ${m.relevance}% ${m.slug}`);
+    if (verbose)
+      console.log(`         ${m.reason}`);
+  }
+  const gaps = analysis.gaps;
+  if (gaps.length > 0) {
+    console.log(`
+  ○ ${gaps.length} gap(s) identified:
+`);
+    for (const g of gaps) {
+      const icon = g.priority === "high" ? "\uD83D\uDD34" : g.priority === "medium" ? "\uD83D\uDFE1" : "\uD83D\uDFE2";
+      console.log(`    ${icon} [${g.priority}] ${g.area}`);
+      console.log(`       ${g.description}`);
+      console.log(`       → Action: ${g.suggestedAction}`);
+    }
+  } else {
+    console.log(`
+  ✓ No significant gaps found — your skills cover this project well!`);
+  }
+  if (analysis.recommendations.length > 0) {
+    console.log(`
+  ─── Recommended Next Steps ───`);
+    for (const r of analysis.recommendations) {
+      console.log(`    → ${r}`);
+    }
+  }
+  if (!dryRun) {
+    const profile = {
+      name: analysis.name,
+      path: resolvedPath,
+      description: analysis.description,
+      techStack: analysis.techStack,
+      domains: analysis.domains,
+      analyzedAt: new Date().toISOString(),
+      matchedSkills: analysis.matchedSkills,
+      gaps: analysis.gaps,
+      recommendations: analysis.recommendations,
+      status: "analyzed"
+    };
+    saveProjectProfile(profile);
+    console.log(`
+  ✓ Project profile saved to ~/.helix/projects/${analysis.name}/`);
+    console.log(`    Next: Run "helixevo specialize --project ${analysis.name}" to create project-specific skills`);
+    if (gaps.filter((g) => g.suggestedAction === "research").length > 0) {
+      console.log(`    Or:   Run "helixevo research --project ${resolvedPath}" to fill gaps via web research`);
+    }
+  } else {
+    console.log(`
+  [DRY RUN — profile not saved]`);
+  }
+  console.log();
+}
+
+// src/utils/update-check.ts
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync12, existsSync as existsSync15, mkdirSync as mkdirSync6 } from "node:fs";
+import { join as join19 } from "node:path";
 import { homedir as homedir4 } from "node:os";
-var HELIX_DIR2 = join18(homedir4(), ".helix");
-var CACHE_PATH = join18(HELIX_DIR2, "update-check.json");
+var HELIX_DIR2 = join19(homedir4(), ".helix");
+var CACHE_PATH = join19(HELIX_DIR2, "update-check.json");
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 var REGISTRY_URL = "https://registry.npmjs.org/helixevo/latest";
 function readCache() {
   try {
-    if (!existsSync14(CACHE_PATH))
+    if (!existsSync15(CACHE_PATH))
       return null;
-    return JSON.parse(readFileSync11(CACHE_PATH, "utf-8"));
+    return JSON.parse(readFileSync12(CACHE_PATH, "utf-8"));
   } catch {
     return null;
   }
 }
 function writeCache(cache) {
   try {
-    if (!existsSync14(HELIX_DIR2))
-      mkdirSync5(HELIX_DIR2, { recursive: true });
-    writeFileSync11(CACHE_PATH, JSON.stringify(cache));
+    if (!existsSync15(HELIX_DIR2))
+      mkdirSync6(HELIX_DIR2, { recursive: true });
+    writeFileSync12(CACHE_PATH, JSON.stringify(cache));
   } catch {}
 }
 function compareVersions(current, latest) {
@@ -13281,6 +13522,7 @@ program2.command("health").description("Assess network health: cohesion, coverag
   printHealthReport2(health);
 });
 program2.command("metrics").description("Show correction rates, skill trends, and evolution impact").option("--verbose", "Show detailed per-skill breakdown").action(metricsCommand);
+program2.command("project-setup").description("Analyze a project folder and match it against your skill set").argument("<path>", "Path to the project folder").option("--verbose", "Show detailed analysis").option("--dry-run", "Analyze without saving project profile").action(projectSetupCommand);
 program2.hook("postAction", () => {
   checkForUpdates().catch(() => {});
 });

package/package.json

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