helixevo 0.2.41 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to HelixEvo are documented here.
 
+## [0.3.1] - 2026-03-23
+
+### Fixed
+- `helixevo dashboard` now recovers cleanly when the preferred port is occupied: it reuses a known managed dashboard if one is already running there, otherwise it falls forward to the next open port instead of failing with `EADDRINUSE`
+- Added `helixevo dashboard --port <port>` so operators can choose a preferred starting port while preserving automatic fallback behavior
+- Background dashboard stop/reuse logic now tracks the actual assigned port, so `helixevo dashboard --stop` works correctly even after fallback to a non-default port
+
+## [0.3.0] - 2026-03-23
+
+### Added
+- Ontology foundation for skills, projects, tasks, capabilities, relations, operations, invariants, and ontology-aware graph summaries
+- Native and derived evolution evidence artifacts with provenance-aware persistence in `~/.helix/evolution-artifacts.jsonl`
+- Native and derived activation traces with provenance-aware persistence in `~/.helix/activation-traces.jsonl`
+- Native and derived pressure signals with provenance-aware persistence in `~/.helix/pressure-signals.jsonl`
+- Co-evolution dashboard summaries that surface project hotspots, role pressure, recurring gap motifs, and routed recommendation counts
+- Premium dashboard brain views across Overview, Evolution, Skill Network, Projects, and Research
+
+### Changed
+- HelixEvo is now documented and surfaced more explicitly as a co-evolving skill and project brain rather than only a skill manager
+- README and dashboard Guide now document the ontology / activation / artifact / pressure model and updated dashboard surfaces
+- Projects page now shows project pressure hotspots and per-project capability pressure context
+- Research page now includes a "Current pressure handoff" view so discovery work is grounded in current adaptation demand
+- Skill Network page now includes a compact co-evolution pressure summary panel
+
+### Fixed
+- Claude invocation now retries without an inherited `CLAUDE_CODE_OAUTH_TOKEN` when that override is stale but local Claude auth is valid
+- Local runtime `events.jsonl` is now ignored to keep mutable telemetry out of normal product commits
+
 ## [0.2.41] - 2026-03-23
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # HelixEvo
 
-Self-evolving skill ecosystem for AI agents. Captures failures, evolves skills through multi-judge evaluation, and maintains a Pareto frontier of optimal skill configurations.
+Co-evolving skill and project brain for AI agents. HelixEvo captures failures, traces activations, models pressure, evolves skills through multi-judge evaluation, and maintains a Pareto frontier of optimal skill configurations.
 
 ## How it works
 
@@ -22,6 +22,8 @@ Every proposed change goes through:
 - **[Claude CLI](https://docs.anthropic.com/en/docs/claude-code)** — installed and authenticated
   - Requires a **Claude Max plan** subscription
   - HelixEvo uses `claude --print` for all LLM operations (no API key needed)
+  - Prefer `claude auth login` managed credentials over exporting a hardcoded `CLAUDE_CODE_OAUTH_TOKEN`
+  - HelixEvo now retries once without an inherited `CLAUDE_CODE_OAUTH_TOKEN` if that override is stale but local Claude auth is valid
 
 Verify prerequisites:
 ```bash
@@ -82,12 +84,13 @@ helixevo dashboard
 | `helixevo health` | Network health: cohesion, coverage, balance, transfer |
 | `helixevo init` | Import existing skills + generate skill tests |
 | `helixevo capture <session>` | Extract failures from a session file |
+| `helixevo project-setup <path>` | Analyze a project, match skills, and surface capability gaps |
 | `helixevo evolve` | Evolve skills from captured failures |
 | `helixevo generalize` | Promote cross-project patterns ↑ |
 | `helixevo specialize --project <name>` | Create project-specific skills ↓ |
 | `helixevo graph` | View skill network in terminal |
 | `helixevo research` | Proactive web research for skill improvement |
-| `helixevo dashboard` | Open web dashboard at localhost:3847 |
+| `helixevo dashboard [--port <n>]` | Open web dashboard, preferring localhost:3847 and falling forward if occupied |
 | `helixevo status` | Show system health |
 | `helixevo report` | Generate evolution report |
 
@@ -124,10 +127,13 @@ All data is stored in `~/.helix/`:
 ~/.helix/
 ├── config.json              # Configuration
 ├── failures.jsonl           # Captured failures
+├── activation-traces.jsonl  # Native + derived activation traces
+├── pressure-signals.jsonl   # Native + derived adaptation pressure
+├── evolution-artifacts.jsonl # Evolution evidence artifacts per proposal/iteration
 ├── frontier.json            # Pareto frontier (top-k configurations)
 ├── evolution-history.json   # All evolution runs + proposals
 ├── skill-tests.jsonl       # Regression test cases
-├── skill-graph.json         # Cached network (nodes + edges)
+├── skill-graph.json         # Cached network (nodes + edges + ontology version)
 ├── canary-registry.json     # Active canary deployments
 ├── knowledge-buffer.json    # Research discoveries + drafts
 ├── general/                 # Skills (SKILL.md files)
@@ -143,14 +149,18 @@ The dashboard provides an interactive view of your skill ecosystem:
 
 ```bash
 helixevo dashboard
-# Opens http://localhost:3847
+# Prefers http://localhost:3847 and falls forward if that port is occupied
+
+helixevo dashboard --port 3900
+# Prefer port 3900 first
 ```
 
 **Tabs:**
-- **Overview** — Stats, frontier programs, recent evolution
-- **Skill Network** — Interactive graph + skill cards + project view + co-evolution analysis
-- **Evolution** — Timeline of all evolution runs with judge scores
-- **Research** — Knowledge buffer: discoveries and drafts
+- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, and pressure counts
+- **Skill Network** — Interactive graph, premium inspector, and co-evolution pressure routing signals
+- **Projects** — Project intake studio, live project analysis, gap routing, and per-project pressure hotspots
+- **Evolution** — Timeline of evolution runs with judge scores, artifact provenance, and activation-aware context
+- **Research** — Knowledge buffer plus a live “why research now” handoff from current pressure and recurring gaps
 - **Frontier** — Pareto frontier with 4-dimension scores + canary status
 
 The dashboard requires Next.js dependencies. On first run:
@@ -183,6 +193,12 @@ Failures → Cluster → Propose → Replay → Multi-Judge → Regression → C
          (discoveries + drafts from rejected proposals)
 ```
 
+**Brain foundation:**
+- **Ontology** defines the stable semantic kernel for skills, projects, tasks, capabilities, artifacts, and mutations.
+- **Activation traces** record which skills and gaps were active during capture and project analysis.
+- **Pressure signals** turn failures and project gaps into explicit adaptation demand.
+- **Evolution artifacts** preserve proposal-level evidence so the dashboard can show what changed, why, and with what provenance.
+
 **Three-layer hierarchy:**
 - **System** — Global agent behaviors
 - **Domain** — Cross-project patterns (generalized skills)

package/dashboard/app/commands/page.tsx

@@ -223,23 +223,42 @@ const COMMANDS: CommandInfo[] = [
     needsLLM: true,
     note: 'Typically not needed if using "watch" mode, which captures automatically.',
   },
+  {
+    name: 'project-setup',
+    description: 'Analyze a local project, match it against your current skills, identify capability gaps, persist a project profile, and emit activation traces plus pressure signals for the dashboard brain surfaces.',
+    usage: 'helixevo project-setup <path> [options]',
+    examples: [
+      { cmd: 'helixevo project-setup .', desc: 'Analyze the current repository and persist a project profile' },
+      { cmd: 'helixevo project-setup ~/myapp', desc: 'Analyze a local project folder by path' },
+      { cmd: 'helixevo project-setup ~/myapp --dry-run', desc: 'Preview the analysis without saving profile data' },
+    ],
+    options: [
+      { flag: '--dry-run', desc: 'Run analysis without saving the project profile or pressure data' },
+      { flag: '--verbose', desc: 'Show additional context and matched-skill reasoning' },
+    ],
+    category: 'system',
+    needsLLM: true,
+    note: 'This powers the Projects intake workflow and now feeds activation traces plus project-analysis pressure into the dashboard.',
+  },
   {
     name: '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.',
+    description: 'Launch the web dashboard at http://localhost:3847 by default. When that port is occupied, HelixEvo now reuses a known managed dashboard or falls forward to the next open port instead of failing. When a newer npm version is available, HelixEvo also auto-updates itself before opening the dashboard unless you opt out.',
     usage: 'helixevo dashboard [options]',
     examples: [
-      { cmd: 'helixevo dashboard', desc: 'Auto-update to the latest version if needed, then open the dashboard' },
+      { cmd: 'helixevo dashboard', desc: 'Auto-update to the latest version if needed, then open the dashboard on 3847 or the next open port' },
       { cmd: 'helixevo dashboard --background', desc: 'Run the dashboard in the background after the same update check' },
+      { cmd: 'helixevo dashboard --port 3900', desc: 'Prefer port 3900 first, then fall forward if that port is occupied' },
       { 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: '--stop', desc: 'Stop a managed background dashboard process' },
+      { flag: '--port <port>', desc: 'Preferred port to try first (default: 3847)' },
       { flag: '--no-auto-update', desc: 'Skip the automatic update check before launch' },
     ],
     category: 'system',
     needsLLM: false,
-    note: 'You are currently using the dashboard. By default it now upgrades itself first when a newer release is available.',
+    note: 'You are currently using the dashboard. It now prefers 3847, reuses a known managed dashboard when one is already running there, and otherwise falls forward to the next open port.',
   },
 ]
 

package/dashboard/app/evolution/page.tsx

@@ -1,4 +1,4 @@
-import { loadHistory } from '@/lib/data'
+import { loadEvolutionArtifacts, loadHistory } from '@/lib/data'
 import { MetricCard } from '@/components/metric-card'
 import { PageHero } from '@/components/page-hero'
 import { SectionFrame } from '@/components/section-frame'
@@ -7,11 +7,15 @@ export const dynamic = 'force-dynamic'
 
 export default function EvolutionPage() {
   const history = loadHistory()
+  const artifacts = loadEvolutionArtifacts()
   const iterations = [...history.iterations].reverse()
   const totalProposals = iterations.flatMap((iteration) => iteration.proposals)
   const accepted = totalProposals.filter((proposal) => proposal.outcome === 'accepted').length
   const rejected = totalProposals.filter((proposal) => proposal.outcome === 'rejected').length
   const avgAcceptance = totalProposals.length > 0 ? Math.round((accepted / totalProposals.length) * 100) : 0
+  const nativeArtifacts = artifacts.filter((artifact) => artifact.provenance === 'native-evolution').length
+  const derivedArtifacts = artifacts.filter((artifact) => artifact.provenance === 'derived-history').length
+  const artifactByProposal = new Map(artifacts.map((artifact) => [artifact.proposalId, artifact]))
 
   return (
     <div style={{ display: 'grid', gap: 22 }}>
@@ -23,15 +27,15 @@ export default function EvolutionPage() {
           { label: `${iterations.length} runs`, tone: 'purple' },
           { label: `${accepted} accepted`, tone: 'green' },
           { label: `${rejected} rejected`, tone: 'red' },
-          { label: `${avgAcceptance}% acceptance rate`, tone: 'blue' },
+          { label: `${artifacts.length} evidence artifacts`, tone: 'blue' },
         ]}
       />
 
       <div className="grid-4">
         <MetricCard label="Runs" value={iterations.length} sublabel="Completed evolution loops" tone="purple" icon="◎" />
+        <MetricCard label="Native artifacts" value={nativeArtifacts} sublabel={`${derivedArtifacts} compatibility-derived`} tone="blue" icon="◇" />
         <MetricCard label="Accepted" value={accepted} sublabel="Promotions that survived judging" tone="green" icon="✓" />
-        <MetricCard label="Rejected" value={rejected} sublabel="Proposals blocked by quality gates" tone="red" icon="✕" />
-        <MetricCard label="Acceptance rate" value={`${avgAcceptance}%`} sublabel="Across all recorded proposals" tone="blue" icon="↗" />
+        <MetricCard label="Acceptance rate" value={`${avgAcceptance}%`} sublabel="Across all recorded proposals" tone="yellow" icon="↗" />
       </div>
 
       <SectionFrame
@@ -78,47 +82,64 @@ export default function EvolutionPage() {
                       </div>
                     ) : null}
 
-                    {iteration.proposals.map((proposal) => (
-                      <div key={proposal.id} className="proposal-card" style={{ borderLeft: `3px solid ${proposal.outcome === 'accepted' ? 'var(--green)' : 'var(--red)'}` }}>
-                        <div style={{ padding: '14px 16px' }}>
-                          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', gap: 12, marginBottom: 10 }}>
-                            <div>
-                              <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
-                                <span className={`badge ${proposal.outcome === 'accepted' ? 'badge-green' : 'badge-red'}`}>{proposal.outcome}</span>
-                                <span style={{ fontSize: 15, fontWeight: 800, letterSpacing: '-0.02em' }}>{proposal.targetSkill}</span>
-                                <span className="badge badge-gray">{proposal.action}</span>
+                    {iteration.proposals.map((proposal) => {
+                      const artifact = artifactByProposal.get(proposal.id)
+
+                      return (
+                        <div key={proposal.id} className="proposal-card" style={{ borderLeft: `3px solid ${proposal.outcome === 'accepted' ? 'var(--green)' : 'var(--red)'}` }}>
+                          <div style={{ padding: '14px 16px' }}>
+                            <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', gap: 12, marginBottom: 10 }}>
+                              <div>
+                                <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
+                                  <span className={`badge ${proposal.outcome === 'accepted' ? 'badge-green' : 'badge-red'}`}>{proposal.outcome}</span>
+                                  <span style={{ fontSize: 15, fontWeight: 800, letterSpacing: '-0.02em' }}>{proposal.targetSkill}</span>
+                                  <span className="badge badge-gray">{proposal.action}</span>
+                                  {artifact ? (
+                                    <span className={`badge ${artifact.provenance === 'native-evolution' ? 'badge-blue' : 'badge-gray'}`}>
+                                      {artifact.provenance === 'native-evolution' ? 'native artifact' : 'derived artifact'}
+                                    </span>
+                                  ) : null}
+                                </div>
+                                <div style={{ marginTop: 8, color: 'var(--text-secondary)', fontSize: 12.5, lineHeight: 1.65 }}>
+                                  {proposal.description.slice(0, 260)}
+                                  {proposal.description.length > 260 ? '…' : ''}
+                                </div>
                               </div>
-                              <div style={{ marginTop: 8, color: 'var(--text-secondary)', fontSize: 12.5, lineHeight: 1.65 }}>
-                                {proposal.description.slice(0, 260)}
-                                {proposal.description.length > 260 ? '…' : ''}
+                              <div style={{ minWidth: 92, textAlign: 'right' }}>
+                                <div style={{ fontSize: 11, color: 'var(--text-muted)', fontWeight: 700, textTransform: 'uppercase', letterSpacing: '0.08em' }}>Regression</div>
+                                <div style={{ marginTop: 6, fontSize: 22, fontWeight: 850, lineHeight: 1, color: proposal.regressionResult.total > 0 && proposal.regressionResult.passed === proposal.regressionResult.total ? 'var(--green)' : 'var(--text)' }}>
+                                  {proposal.regressionResult.total > 0 ? `${proposal.regressionResult.passed}/${proposal.regressionResult.total}` : '—'}
+                                </div>
                               </div>
                             </div>
-                            <div style={{ minWidth: 92, textAlign: 'right' }}>
-                              <div style={{ fontSize: 11, color: 'var(--text-muted)', fontWeight: 700, textTransform: 'uppercase', letterSpacing: '0.08em' }}>Regression</div>
-                              <div style={{ marginTop: 6, fontSize: 22, fontWeight: 850, lineHeight: 1, color: proposal.regressionResult.total > 0 && proposal.regressionResult.passed === proposal.regressionResult.total ? 'var(--green)' : 'var(--text)' }}>
-                                {proposal.regressionResult.total > 0 ? `${proposal.regressionResult.passed}/${proposal.regressionResult.total}` : '—'}
-                              </div>
+
+                            <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', marginBottom: 10 }}>
+                              {[
+                                { label: 'Task', score: proposal.judges.taskCompletion.score, color: 'var(--green)' },
+                                { label: 'Align', score: proposal.judges.correctionAlignment.score, color: 'var(--blue)' },
+                                { label: 'Side-effects', score: proposal.judges.sideEffectCheck.score, color: 'var(--purple)' },
+                              ].map((judge) => (
+                                <span key={judge.label} className="score-pill" style={{ color: judge.score >= 7 ? judge.color : 'var(--red)' }}>
+                                  {judge.label} {judge.score}/10
+                                </span>
+                              ))}
                             </div>
-                          </div>
 
-                          <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', marginBottom: 10 }}>
-                            {[
-                              { label: 'Task', score: proposal.judges.taskCompletion.score, color: 'var(--green)' },
-                              { label: 'Align', score: proposal.judges.correctionAlignment.score, color: 'var(--blue)' },
-                              { label: 'Side-effects', score: proposal.judges.sideEffectCheck.score, color: 'var(--purple)' },
-                            ].map((judge) => (
-                              <span key={judge.label} className="score-pill" style={{ color: judge.score >= 7 ? judge.color : 'var(--red)' }}>
-                                {judge.label} {judge.score}/10
-                              </span>
-                            ))}
-                          </div>
+                            {artifact ? (
+                              <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', marginBottom: 10 }}>
+                                {artifact.clusterType ? <span className="badge badge-gray">cluster {artifact.clusterType}</span> : null}
+                                {artifact.trigger ? <span className="badge badge-gray">trigger {artifact.trigger}</span> : null}
+                                {artifact.iterationId ? <span className="badge badge-gray">{artifact.iterationId}</span> : null}
+                              </div>
+                            ) : null}
 
-                          <div style={{ color: 'var(--text-dim)', fontSize: 11.5, lineHeight: 1.55 }}>
-                            {proposal.outcomeReason}
+                            <div style={{ color: 'var(--text-dim)', fontSize: 11.5, lineHeight: 1.55 }}>
+                              {proposal.outcomeReason}
+                            </div>
                           </div>
                         </div>
-                      </div>
-                    ))}
+                      )
+                    })}
                   </div>
                 </article>
               </div>

package/dashboard/app/guide/page.tsx

@@ -340,6 +340,11 @@ export default function GuidePage() {
               </div>
             </div>
           </div>
+          <Callout type="tip">
+            HelixEvo now exposes a visible <strong>brain foundation</strong> in the dashboard: ontology-backed summaries,
+            activation traces, evolution artifacts, and pressure signals all feed the Overview, Skill Network, Projects,
+            Research, and Evolution surfaces.
+          </Callout>
         </Section>
 
         {/* ─── Quick Start ─── */}
@@ -347,6 +352,7 @@ export default function GuidePage() {
           <Callout type="info">
             <strong>Prerequisites:</strong> Node.js 18+, <a href="https://bun.sh">Bun</a> (for building),
             and <a href="https://docs.anthropic.com/en/docs/claude-code">Claude CLI</a> with a Claude Max plan.
+            Prefer <code>claude auth login</code> managed credentials over exporting a hardcoded <code>CLAUDE_CODE_OAUTH_TOKEN</code>.
           </Callout>
 
           <Step n={1} title="Install HelixEvo">
@@ -389,8 +395,14 @@ helixevo graph
 # Open this dashboard
 helixevo dashboard
 
+# Prefer a different port if you want
+helixevo dashboard --port 3900
+
 # Check system health
 helixevo status`}</Code>
+            <p className="guide-text-sm">
+              The dashboard prefers port <code>3847</code>. If that port is already occupied, HelixEvo now reuses a known managed dashboard or falls forward to the next open port instead of failing immediately.
+            </p>
           </Step>
         </Section>
 
@@ -450,8 +462,8 @@ helixevo status`}</Code>
               },
               {
                 cmd: 'helixevo dashboard',
-                desc: 'Open the interactive web dashboard at localhost:3847. Before launch, HelixEvo checks npm for a newer version and auto-updates itself unless you opt out.',
-                flags: ['--background', '--stop', '--no-auto-update'],
+                desc: 'Open the interactive web dashboard. HelixEvo prefers localhost:3847, reuses a known managed dashboard if one is already there, and otherwise falls forward to the next open port. Before launch, it also checks npm for a newer version and auto-updates itself unless you opt out.',
+                flags: ['--background', '--stop', '--port <port>', '--no-auto-update'],
               },
               {
                 cmd: 'helixevo status',
@@ -491,6 +503,26 @@ helixevo status`}</Code>
           </p>
           <ArchitectureDiagram />
 
+          <h3 className="guide-h3">Brain Foundation</h3>
+          <div className="grid-2" style={{ gap: 12, marginBottom: 20 }}>
+            <div className="guide-dimension-card" style={{ borderLeftColor: 'var(--blue)' }}>
+              <div style={{ fontSize: 11, fontWeight: 700, color: 'var(--blue)', textTransform: 'uppercase', letterSpacing: 1 }}>Ontology</div>
+              <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 4 }}>Defines the stable semantic kernel for skills, projects, tasks, capabilities, artifacts, and mutations.</div>
+            </div>
+            <div className="guide-dimension-card" style={{ borderLeftColor: 'var(--green)' }}>
+              <div style={{ fontSize: 11, fontWeight: 700, color: 'var(--green)', textTransform: 'uppercase', letterSpacing: 1 }}>Activation traces</div>
+              <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 4 }}>Capture which skills and gaps were active during failure analysis and project analysis.</div>
+            </div>
+            <div className="guide-dimension-card" style={{ borderLeftColor: 'var(--purple)' }}>
+              <div style={{ fontSize: 11, fontWeight: 700, color: 'var(--purple)', textTransform: 'uppercase', letterSpacing: 1 }}>Evolution artifacts</div>
+              <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 4 }}>Preserve proposal-level evidence so the dashboard can show what changed, why, and with which provenance.</div>
+            </div>
+            <div className="guide-dimension-card" style={{ borderLeftColor: 'var(--yellow)' }}>
+              <div style={{ fontSize: 11, fontWeight: 700, color: 'var(--yellow)', textTransform: 'uppercase', letterSpacing: 1 }}>Pressure signals</div>
+              <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 4 }}>Turn failures and project gaps into explicit adaptation demand, routing attention into Network, Projects, and Research.</div>
+            </div>
+          </div>
+
           <h3 className="guide-h3">Three-Layer Hierarchy</h3>
           <p className="guide-text">
             Skills are organized into three layers. The <code>generalize</code> command promotes patterns upward,
@@ -874,10 +906,13 @@ generation: 3
           <Code title="~/.helix/ directory structure">{`~/.helix/
 ├── config.json              # Configuration
 ├── failures.jsonl           # Captured failure records (append-only)
+├── activation-traces.jsonl  # Native + derived activation traces
+├── pressure-signals.jsonl   # Native + derived adaptation pressure
+├── evolution-artifacts.jsonl # Proposal/iteration evidence artifacts
 ├── frontier.json            # Pareto frontier (top-K programs)
 ├── evolution-history.json   # All evolution iterations + proposals
 ├── skill-tests.jsonl       # Regression test cases (append-only)
-├── skill-graph.json         # Cached network (nodes + edges)
+├── skill-graph.json         # Cached network (nodes + edges + ontology version)
 ├── canary-registry.json     # Active canary deployments
 ├── knowledge-buffer.json    # Research discoveries + drafts
 ├── general/                 # Skills (SKILL.md files)
@@ -984,6 +1019,11 @@ generation: 3
             HelixEvo uses <code>claude --print</code> with configurable models (default: <code>sonnet</code>).
             No API key is needed — it requires a Claude Max plan subscription. Judges and proposals can use different models.
           </FAQItem>
+          <FAQItem q="What if Claude says my OAuth token expired?">
+            First run <code>claude auth login</code> to refresh local Claude credentials. Avoid exporting a hardcoded
+            <code> CLAUDE_CODE_OAUTH_TOKEN</code> in your shell profile. HelixEvo also retries once without an inherited
+            token override when local Claude auth is healthy.
+          </FAQItem>
           <FAQItem q="Can I use HelixEvo with other AI agents?">
             Yes. HelixEvo manages standard SKILL.md files with YAML frontmatter. Any agent that reads SKILL.md
             files can benefit from HelixEvo&apos;s evolution pipeline.

package/dashboard/app/network/client.tsx

@@ -12,6 +12,7 @@ import {
 } from '@xyflow/react'
 import '@xyflow/react/dist/style.css'
 import SkillFlowNode from '@/components/SkillFlowNode'
+import { SectionFrame } from '@/components/section-frame'
 
 // ─── Types ──────────────────────────────────────────────────────
 
@@ -33,6 +34,23 @@ interface ProjectData {
   name: string; failures: any[]; skills: string[]
 }
 
+interface ProjectPressureSummary {
+  projectId: string
+  totalSignals: number
+  nativeSignals: number
+  derivedSignals: number
+  highPrioritySignals: number
+  topCapabilities: string[]
+}
+
+interface CoEvolutionSummary {
+  pressureSignals: { total: number; native: number; derived: number }
+  topProjects: ProjectPressureSummary[]
+  rolePressure: { generalist: number; specialist: number; hybrid: number }
+  crossProjectGapAreas: { area: string; projects: string[]; count: number }[]
+  activeRecommendations: { action: 'research' | 'specialize' | 'create'; count: number }[]
+}
+
 interface Props {
   allNodes: SkillNode[]
   generalized: SkillNode[]
@@ -42,6 +60,7 @@ interface Props {
   evolutionBySkill: Record<string, EvolutionEntry[]>
   skillContents: Record<string, string>
   projects: ProjectData[]
+  coevolution: CoEvolutionSummary
   stats: { nodes: number; edges: number; clusters: number; generalized: number; evolved: number; original: number }
 }
 
@@ -84,7 +103,7 @@ function actionBtnStyle(color?: string): React.CSSProperties {
 // ─── Main Component ─────────────────────────────────────────────
 
 export default function NetworkClient({
-  allNodes, generalized, evolved, original, edges: graphEdges, evolutionBySkill, skillContents, projects, stats
+  allNodes, generalized, evolved, original, edges: graphEdges, evolutionBySkill, skillContents, projects, coevolution, stats
 }: Props) {
   const [view, setView] = useState<SubView>('graph')
   const [selectedSkill, setSelectedSkill] = useState<string | null>(null)
@@ -264,6 +283,111 @@ export default function NetworkClient({
         </div>
       </div>
 
+      <SectionFrame
+        eyebrow="Co-evolution signals"
+        title="Pressure and transfer foundation"
+        description="A compact view of where current project demand is pushing on the network, which cognitive roles are implicated, and which gap motifs are repeating across projects."
+        tone="blue"
+      >
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: 16, marginBottom: 16 }}>
+          <div className="metric-card metric-card-blue">
+            <div className="metric-card-header">
+              <div>
+                <div className="metric-card-label">Pressure signals</div>
+                <div className="metric-card-value">{coevolution.pressureSignals.total}</div>
+              </div>
+              <div className="metric-card-icon">◎</div>
+            </div>
+            <div className="metric-card-sublabel">{coevolution.pressureSignals.native} native • {coevolution.pressureSignals.derived} derived</div>
+          </div>
+          <div className="metric-card metric-card-purple">
+            <div className="metric-card-header">
+              <div>
+                <div className="metric-card-label">Generalist pressure</div>
+                <div className="metric-card-value">{coevolution.rolePressure.generalist}</div>
+              </div>
+              <div className="metric-card-icon">◎</div>
+            </div>
+            <div className="metric-card-sublabel">Pressure touching reusable abstractions</div>
+          </div>
+          <div className="metric-card metric-card-green">
+            <div className="metric-card-header">
+              <div>
+                <div className="metric-card-label">Specialist pressure</div>
+                <div className="metric-card-value">{coevolution.rolePressure.specialist}</div>
+              </div>
+              <div className="metric-card-icon">◉</div>
+            </div>
+            <div className="metric-card-sublabel">Project-local demand pushing on specialist skills</div>
+          </div>
+          <div className="metric-card metric-card-yellow">
+            <div className="metric-card-header">
+              <div>
+                <div className="metric-card-label">Cross-project gap motifs</div>
+                <div className="metric-card-value">{coevolution.crossProjectGapAreas.length}</div>
+              </div>
+              <div className="metric-card-icon">⇄</div>
+            </div>
+            <div className="metric-card-sublabel">Recurring gap areas spanning multiple projects</div>
+          </div>
+        </div>
+
+        <div style={{ display: 'grid', gridTemplateColumns: 'minmax(0, 1.4fr) minmax(0, 1fr)', gap: 16 }}>
+          <div style={{ padding: '16px 18px', borderRadius: 20, border: '1px solid var(--border)', background: 'rgba(255,255,255,0.72)' }}>
+            <div className="section-label" style={{ marginBottom: 10 }}>Top project hotspots</div>
+            {coevolution.topProjects.length === 0 ? (
+              <div className="signal-text">No project pressure signals yet — pressure will appear here once failures and project analysis records accumulate.</div>
+            ) : (
+              <div style={{ display: 'grid', gap: 10 }}>
+                {coevolution.topProjects.map((project) => (
+                  <div key={project.projectId} style={{ display: 'flex', justifyContent: 'space-between', gap: 12, alignItems: 'flex-start', padding: '12px 14px', borderRadius: 16, background: 'rgba(97,93,86,0.06)', border: '1px solid var(--border)' }}>
+                    <div>
+                      <div style={{ fontSize: 13, fontWeight: 700, color: 'var(--text)' }}>{project.projectId}</div>
+                      <div style={{ fontSize: 11.5, color: 'var(--text-dim)', marginTop: 4 }}>
+                        {project.highPrioritySignals} high-priority • {project.nativeSignals} native • {project.derivedSignals} derived
+                      </div>
+                      {project.topCapabilities.length > 0 ? (
+                        <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginTop: 8 }}>
+                          {project.topCapabilities.map((capability) => (
+                            <span key={capability} className="badge badge-gray">{capability}</span>
+                          ))}
+                        </div>
+                      ) : null}
+                    </div>
+                    <div style={{ fontSize: 24, fontWeight: 850, color: project.highPrioritySignals > 0 ? 'var(--red)' : 'var(--blue)' }}>{project.totalSignals}</div>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+
+          <div style={{ padding: '16px 18px', borderRadius: 20, border: '1px solid var(--border)', background: 'rgba(255,255,255,0.72)' }}>
+            <div className="section-label" style={{ marginBottom: 10 }}>Emergent routing signals</div>
+            <div style={{ display: 'grid', gap: 10 }}>
+              <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+                {coevolution.activeRecommendations.length > 0 ? coevolution.activeRecommendations.map((entry) => (
+                  <span key={entry.action} className={`hero-chip hero-chip-${entry.action === 'research' ? 'blue' : entry.action === 'specialize' ? 'green' : 'purple'}`}>
+                    {entry.action} × {entry.count}
+                  </span>
+                )) : <span className="badge badge-gray">No routed actions yet</span>}
+              </div>
+              {coevolution.crossProjectGapAreas.length > 0 ? (
+                <div style={{ display: 'grid', gap: 8 }}>
+                  {coevolution.crossProjectGapAreas.slice(0, 4).map((entry) => (
+                    <div key={entry.area} style={{ padding: '12px 14px', borderRadius: 16, background: 'rgba(97,93,86,0.06)', border: '1px solid var(--border)' }}>
+                      <div style={{ fontSize: 12.5, fontWeight: 700, color: 'var(--text)' }}>{entry.area}</div>
+                      <div style={{ fontSize: 11.5, color: 'var(--text-dim)', marginTop: 4 }}>{entry.count} projects • {entry.projects.join(', ')}</div>
+                    </div>
+                  ))}
+                </div>
+              ) : (
+                <div className="signal-text">Cross-project gap motifs will appear here when the same capability pressure is seen across multiple projects.</div>
+              )}
+            </div>
+          </div>
+        </div>
+      </SectionFrame>
+
       {/* Create Skill Panel */}
       {creating && (
         <div className="card" style={{ marginBottom: 20 }}>

package/dashboard/app/network/page.tsx

@@ -1,4 +1,4 @@
-import { loadGraph, loadSkillContent, loadHistory, listProjects, getProjectSkills } from '@/lib/data'
+import { loadCoEvolutionSummary, loadGraph, loadSkillContent, loadHistory, listProjects, getProjectSkills } from '@/lib/data'
 import NetworkClient from './client'
 
 export const dynamic = 'force-dynamic'
@@ -6,6 +6,7 @@ export const dynamic = 'force-dynamic'
 export default function SkillNetworkPage() {
   const graph = loadGraph()
   const history = loadHistory()
+  const coevolution = loadCoEvolutionSummary()
   const projects = listProjects()
 
   const generalized = graph.nodes.filter(n =>
@@ -62,6 +63,7 @@ export default function SkillNetworkPage() {
       evolutionBySkill={evolutionBySkill}
       skillContents={skillContents}
       projects={projectData}
+      coevolution={coevolution}
       stats={{
         nodes: graph.nodes.length,
         edges: graph.edges.length,