helixevo 0.2.34 → 0.2.35

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to HelixEvo are documented here.
 
+## [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/projects/client.tsx

@@ -0,0 +1,326 @@
+'use client'
+
+import { useState, useRef } from 'react'
+import type { ProjectProfile } from '@/lib/data'
+
+type SetupState = 'idle' | 'analyzing' | 'done' | 'error'
+
+const STEPS = [
+  { step: 1, title: 'Analyze Project', desc: 'Read project files, tech stack, and structure', icon: '📁' },
+  { step: 2, title: 'Match Skills', desc: 'Score each existing skill for relevance', icon: '🔗' },
+  { step: 3, title: 'Find Gaps', desc: 'Identify missing capabilities', icon: '🔍' },
+  { step: 4, title: 'Save Profile', desc: 'Create project profile for ongoing tracking', icon: '✓' },
+]
+
+export default function ProjectsClient({ profiles, skillCount }: { profiles: ProjectProfile[]; skillCount: number }) {
+  const [projectPath, setProjectPath] = useState('')
+  const [setupState, setSetupState] = useState<SetupState>('idle')
+  const [output, setOutput] = useState('')
+  const outputRef = useRef<HTMLPreElement | null>(null)
+  const abortRef = useRef<AbortController | null>(null)
+
+  const handleSetup = async () => {
+    if (!projectPath.trim()) return
+    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: projectPath.trim() }),
+        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
+    }
+  }
+
+  const handleStop = () => {
+    if (abortRef.current) abortRef.current.abort()
+  }
+
+  return (
+    <div>
+      <div className="page-header">
+        <h1 className="page-title">Project Setup</h1>
+        <p className="page-desc">
+          Analyze a project folder to match your skills, find gaps, and get ready to work
+        </p>
+      </div>
+
+      {/* Setup Wizard */}
+      <div className="card" style={{ marginBottom: 24, padding: '22px 26px' }}>
+        {/* Pipeline */}
+        <div style={{ display: 'flex', alignItems: 'flex-start', gap: 0, marginBottom: 24 }}>
+          {STEPS.map((step, i) => (
+            <div key={step.step} style={{ display: 'flex', alignItems: 'flex-start', flex: 1 }}>
+              <div style={{ flex: 1 }}>
+                <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}>
+                  <div style={{
+                    width: 30, height: 30, borderRadius: 8,
+                    background: 'var(--bg-section)', display: 'flex',
+                    alignItems: 'center', justifyContent: 'center', fontSize: 14,
+                  }}>{step.icon}</div>
+                  <div>
+                    <div style={{ fontSize: 9, fontWeight: 600, color: 'var(--text-muted)', letterSpacing: 0.5 }}>STEP {step.step}</div>
+                    <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--text)' }}>{step.title}</div>
+                  </div>
+                </div>
+                <div style={{ fontSize: 11, color: 'var(--text-dim)', lineHeight: 1.4 }}>{step.desc}</div>
+              </div>
+              {i < 3 && (
+                <span style={{ padding: '10px 8px 0', color: 'var(--text-muted)', fontSize: 14 }}>&rarr;</span>
+              )}
+            </div>
+          ))}
+        </div>
+
+        {/* Input */}
+        <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"
+              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 === 'idle' || setupState === 'done' || setupState === 'error' ? (
+            <button onClick={handleSetup} disabled={!projectPath.trim()} style={{
+              padding: '9px 20px', border: 'none', borderRadius: 'var(--radius)',
+              background: projectPath.trim() ? 'var(--green)' : 'var(--bg-section)',
+              color: projectPath.trim() ? '#fff' : 'var(--text-muted)',
+              fontSize: 13, fontWeight: 600, cursor: projectPath.trim() ? 'pointer' : 'default',
+              whiteSpace: 'nowrap',
+            }}>
+              {setupState === 'done' ? 'Re-analyze' : 'Analyze Project'}
+            </button>
+          ) : (
+            <button onClick={handleStop} 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>
+
+      {/* 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' && '● Analyzing project and matching skills...'}
+            {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(--bg-section)', border: '1px solid var(--border)',
+                borderRadius: 'var(--radius)', fontSize: 12, fontWeight: 600, cursor: 'pointer', color: 'var(--text-secondary)',
+              }}>
+                Refresh to see results
+              </button>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Existing Project Profiles */}
+      {profiles.length > 0 && (
+        <div style={{ marginBottom: 24 }}>
+          <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: 12 }}>
+            {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: 16, fontWeight: 700, marginBottom: 4 }}>{p.name}</div>
+                        <div style={{ fontSize: 12, color: 'var(--text-dim)' }}>{p.description}</div>
+                      </div>
+                      <span className={`badge ${p.status === 'active' ? 'badge-green' : 'badge-blue'}`}>{p.status}</span>
+                    </div>
+
+                    {/* Tech + Domains */}
+                    <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: 14 }}>
+                      {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>
+
+                    {/* Stats row */}
+                    <div className="grid-3" style={{ gap: 10, marginBottom: 14 }}>
+                      <div style={{ padding: '10px 12px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 20, fontWeight: 800, color: 'var(--green)' }}>{p.matchedSkills.length}</div>
+                        <div style={{ fontSize: 10, color: 'var(--text-dim)' }}>Skills Matched ({matchedPct}%)</div>
+                      </div>
+                      <div style={{ padding: '10px 12px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 20, fontWeight: 800, color: highGaps.length > 0 ? 'var(--red)' : 'var(--green)' }}>{p.gaps.length}</div>
+                        <div style={{ fontSize: 10, color: 'var(--text-dim)' }}>Gaps ({highGaps.length} high priority)</div>
+                      </div>
+                      <div style={{ padding: '10px 12px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 10, color: 'var(--text-dim)', marginBottom: 2 }}>Analyzed</div>
+                        <div style={{ fontSize: 12, fontWeight: 600, color: 'var(--text-secondary)' }}>{new Date(p.analyzedAt).toLocaleDateString()}</div>
+                      </div>
+                    </div>
+
+                    {/* Top matched skills */}
+                    {p.matchedSkills.length > 0 && (
+                      <div style={{ marginBottom: 14 }}>
+                        <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', marginBottom: 6 }}>TOP MATCHES</div>
+                        <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap' }}>
+                          {p.matchedSkills.slice(0, 6).map(m => (
+                            <div key={m.slug} style={{
+                              padding: '4px 10px', background: 'var(--bg-section)',
+                              borderRadius: 'var(--radius)', fontSize: 11, display: 'flex', alignItems: 'center', gap: 6,
+                            }}>
+                              <span style={{ fontWeight: 500 }}>{m.slug}</span>
+                              <span style={{ fontWeight: 700, color: m.relevance >= 70 ? 'var(--green)' : 'var(--yellow)' }}>{m.relevance}%</span>
+                            </div>
+                          ))}
+                          {p.matchedSkills.length > 6 && (
+                            <span style={{ fontSize: 10, color: 'var(--text-muted)', padding: '4px 6px' }}>+{p.matchedSkills.length - 6} more</span>
+                          )}
+                        </div>
+                      </div>
+                    )}
+
+                    {/* Gaps */}
+                    {p.gaps.length > 0 && (
+                      <div>
+                        <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', marginBottom: 6 }}>GAPS</div>
+                        <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+                          {p.gaps.map((g, i) => (
+                            <div key={i} style={{
+                              padding: '6px 10px', 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)'}`,
+                              fontSize: 11, display: 'flex', justifyContent: 'space-between', alignItems: 'center',
+                            }}>
+                              <span><strong>{g.area}</strong> — {g.description.slice(0, 60)}</span>
+                              <span className={`badge ${g.suggestedAction === 'research' ? 'badge-blue' : g.suggestedAction === 'specialize' ? 'badge-green' : 'badge-gray'}`}>
+                                {g.suggestedAction}
+                              </span>
+                            </div>
+                          ))}
+                        </div>
+                      </div>
+                    )}
+
+                    {/* Recommendations */}
+                    {p.recommendations.length > 0 && (
+                      <div style={{ marginTop: 12, padding: '10px 14px', background: 'var(--bg-section)', borderRadius: 'var(--radius)' }}>
+                        <div style={{ fontSize: 10, fontWeight: 600, color: 'var(--text-muted)', marginBottom: 4 }}>NEXT STEPS</div>
+                        {p.recommendations.map((r, i) => (
+                          <div key={i} style={{ fontSize: 11, color: 'var(--text-dim)', lineHeight: 1.5 }}>→ {r}</div>
+                        ))}
+                      </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 above to analyze it against your {skillCount} skills.
+              HelixEvo will identify which skills match and 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.35",
   "description": "Self-evolving skill ecosystem for AI agents. Skills and projects co-evolve through multi-judge evaluation and a Pareto frontier.",
   "type": "module",
   "bin": {