helixevo 0.6.0 → 0.7.0

package/dashboard/app/research/client.tsx

@@ -5,6 +5,9 @@ import { ConsolePanel } from '@/components/console-panel'
 import { MetricCard } from '@/components/metric-card'
 import { PageHero } from '@/components/page-hero'
 import { SectionFrame } from '@/components/section-frame'
+import { OperatorLoopTrail } from '@/components/operator-loop-trail'
+import { SurfaceJumpLinks } from '@/components/surface-jump-links'
+import { NextStepEmptyState } from '@/components/next-step-empty-state'
 
 interface Discovery {
   id: string
@@ -190,8 +193,20 @@ export default function ResearchClient({ buffer, projects, coevolution }: Props)
           { label: `${buffer.drafts.length} drafts`, tone: 'yellow' },
           { label: `${nearPass.length} near-pass drafts`, tone: 'green' },
         ]}
+        actions={
+          <div style={{ display: 'grid', gap: 12 }}>
+            <div className="hero-note-card">
+              <div className="hero-note-label">Discovery handoff</div>
+              <div className="hero-note-title">Observe gaps → research patterns → draft reusable skills</div>
+              <div className="hero-note-copy">Use Research when recurring project demand needs external evidence before it can become a stronger response or semantic pattern.</div>
+            </div>
+            <SurfaceJumpLinks surface="research" variant="compact" title="Discovery handoffs" />
+          </div>
+        }
       />
 
+      <OperatorLoopTrail surface="research" />
+
       <SectionFrame
         eyebrow="Why research now"
         title="Current pressure handoff"
@@ -371,10 +386,13 @@ export default function ResearchClient({ buffer, projects, coevolution }: Props)
           tone="blue"
         >
           {buffer.discoveries.length === 0 ? (
-            <div className="empty-state" style={{ padding: 24 }}>
-              <div className="empty-state-title">No discoveries yet</div>
-              <div className="empty-state-desc">Run research to search the web for techniques your skill network does not cover yet.</div>
-            </div>
+            <NextStepEmptyState
+              title="No discoveries yet"
+              description="Run research to search the web for techniques your skill network does not cover yet, then compare those discoveries against the current routed pressure picture."
+              command="helixevo research"
+              pageLink={{ label: 'Open Co-Evolution', href: '/coevolution', tone: 'green' }}
+              guideLink={{ label: 'Guide · Adaptation Loop', anchor: 'loop', tone: 'purple' }}
+            />
           ) : (
             <div className="summary-list">
               {buffer.discoveries.sort((a, b) => b.score - a.score).map((discovery) => (
@@ -400,10 +418,13 @@ export default function ResearchClient({ buffer, projects, coevolution }: Props)
           tone="yellow"
         >
           {buffer.drafts.length === 0 ? (
-            <div className="empty-state" style={{ padding: 24 }}>
-              <div className="empty-state-title">No drafts yet</div>
-              <div className="empty-state-desc">Run research to generate the first draft skills and evaluate them against the current thresholds.</div>
-            </div>
+            <NextStepEmptyState
+              title="No drafts yet"
+              description="Once research has enough evidence, it will generate the first draft skills and evaluate them against the current thresholds before they enter the wider loop."
+              command="helixevo research --verbose"
+              pageLink={{ label: 'Open Projects', href: '/projects', tone: 'blue' }}
+              guideLink={{ label: 'Guide · Quick Start', anchor: 'quickstart', tone: 'purple' }}
+            />
           ) : (
             <div className="summary-list">
               {buffer.drafts.sort((a, b) => b.avgScore - a.avgScore).map((draft) => (

package/dashboard/app/topology/client.tsx

@@ -6,7 +6,11 @@ import { ConsolePanel } from '@/components/console-panel'
 import { MetricCard } from '@/components/metric-card'
 import { PageHero } from '@/components/page-hero'
 import { SectionFrame } from '@/components/section-frame'
+import { OperatorLoopTrail } from '@/components/operator-loop-trail'
+import { SurfaceJumpLinks } from '@/components/surface-jump-links'
+import { NextStepEmptyState } from '@/components/next-step-empty-state'
 import type { GovernanceModeName, GovernanceState, TopologyDashboardSummary, TopologyReviewDecisionStatus, TopologyReviewStatus } from '@/lib/data'
+import type { ProofDashboardSummary } from '@/lib/proof'
 
 type RunState = 'idle' | 'running' | 'success' | 'error' | 'stopped'
 
@@ -62,9 +66,11 @@ function consoleTone(state: RunState): 'neutral' | 'green' | 'red' | 'yellow' {
 export default function TopologyClient({
   initialDashboard,
   initialGovernanceState,
+  proof,
 }: {
   initialDashboard: TopologyDashboardSummary
   initialGovernanceState: GovernanceState
+  proof: ProofDashboardSummary
 }) {
   const [dashboard, setDashboard] = useState(initialDashboard)
   const [governanceState, setGovernanceState] = useState(initialGovernanceState)
@@ -241,6 +247,7 @@ export default function TopologyClient({
           { label: `${dashboard.summary.open} open reviews`, tone: dashboard.summary.open > 0 ? 'yellow' : 'green' },
           { label: `${dashboard.execution.prepared} prepared`, tone: dashboard.execution.prepared > 0 ? 'blue' : 'neutral' },
           { label: `${dashboard.execution.applied} applied`, tone: dashboard.execution.applied > 0 ? 'green' : 'neutral' },
+          { label: `${proof.summary.reviewOpen} proof review`, tone: proof.summary.reviewOpen > 0 ? 'yellow' : proof.summary.effective > 0 ? 'green' : 'neutral' },
           { label: formatMode(dashboard.governance.activeMode), tone: toneForMode(dashboard.governance.activeMode) },
           { label: dashboard.governance.source === 'operator-selected' ? 'operator-steered' : 'derived mode', tone: dashboard.governance.source === 'operator-selected' ? 'purple' : 'neutral' },
         ]}
@@ -250,22 +257,29 @@ export default function TopologyClient({
               <div className="hero-note-label">Active governance profile</div>
               <div className="hero-note-title">{formatMode(dashboard.governance.activeMode)}</div>
               <div className="hero-note-copy">{dashboard.governance.profile.explanation}</div>
+              <div style={{ marginTop: 8, display: 'flex', gap: 6, flexWrap: 'wrap' }}>
+                <span className="badge badge-gray">{proof.summary.effective} effective records</span>
+                <Link href="/proof" className="badge badge-gray" style={{ textDecoration: 'none' }}>open proof</Link>
+              </div>
             </div>
-            <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', justifyContent: 'flex-end' }}>
-              <button onClick={handleOptimize} disabled={runState === 'running'} className="badge badge-blue" style={{ border: 'none', cursor: 'pointer' }}>Run graph optimize</button>
-              <Link href="/ontology" className="badge badge-gray">Open ontology</Link>
-              <Link href="/coevolution" className="badge badge-gray">Open co-evolution</Link>
-              <Link href="/network" className="badge badge-gray">Open network</Link>
+            <div style={{ display: 'grid', gap: 10 }}>
+              <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', justifyContent: 'flex-end' }}>
+                <button onClick={handleOptimize} disabled={runState === 'running'} className="badge badge-blue" style={{ border: 'none', cursor: 'pointer' }}>Run graph optimize</button>
+              </div>
+              <SurfaceJumpLinks surface="topology" variant="compact" title="Structural handoffs" />
             </div>
           </div>
         }
       />
 
+      <OperatorLoopTrail surface="topology" />
+
       <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: 16 }}>
         <MetricCard label="Open review items" value={dashboard.summary.open} sublabel={`${dashboard.summary.deferred} deferred • ${dashboard.summary.accepted} accepted`} tone={dashboard.summary.open > 0 ? 'yellow' : 'green'} icon="⇄" />
         <MetricCard label="Accepted ready" value={dashboard.acceptedReady.length} sublabel="accepted candidates not yet prepared for execution" tone={dashboard.acceptedReady.length > 0 ? 'blue' : 'neutral'} icon="✓" />
         <MetricCard label="Prepared plans" value={dashboard.execution.prepared} sublabel={`${dashboard.execution.safeToApply} safe-to-apply • ${dashboard.execution.prepareOnly} prepare-only`} tone={dashboard.execution.prepared > 0 ? 'blue' : 'neutral'} icon="◇" />
         <MetricCard label="Applied plans" value={dashboard.execution.applied} sublabel={`${dashboard.execution.rolledBack} rolled back • ${dashboard.execution.artifacts} artifacts`} tone={dashboard.execution.applied > 0 ? 'green' : 'neutral'} icon="↑" />
+        <MetricCard label="Structural proof" value={proof.summary.reviewOpen} sublabel={`${proof.summary.effective} effective • ${proof.summary.regressed} regressed`} tone={proof.summary.reviewOpen > 0 ? 'yellow' : proof.summary.effective > 0 ? 'green' : 'neutral'} icon="◇" />
         <MetricCard label="Manual-route backlog" value={dashboard.summary.generatedFromManualReview} sublabel="pressure routed into actual operator review" tone="purple" icon="!" />
         <MetricCard label="Snapshots" value={dashboard.execution.snapshots} sublabel="before/after state preserved for reviewed execution" tone="purple" icon="◎" />
       </div>
@@ -300,10 +314,13 @@ export default function TopologyClient({
                 </div>
               </div>
             )) : (
-              <div className="empty-state" style={{ padding: 24 }}>
-                <div className="empty-state-title">No accepted candidates waiting for preparation</div>
-                <div className="empty-state-desc">Accept a topology review item first, then it will enter the reviewed execution pipeline here.</div>
-              </div>
+              <NextStepEmptyState
+                title="No accepted candidates waiting for preparation"
+                description="Accept a topology review item first, then it can enter the reviewed execution pipeline and become a prepared apply plan."
+                command="helixevo graph --optimize"
+                pageLink={{ label: 'Open Co-Evolution', href: '/coevolution', tone: 'purple' }}
+                guideLink={{ label: 'Guide · Maturity & Safety', anchor: 'maturity', tone: 'yellow' }}
+              />
             )}
           </div>
 
@@ -342,10 +359,13 @@ export default function TopologyClient({
                 </div>
               </div>
             )) : (
-              <div className="empty-state" style={{ padding: 24 }}>
-                <div className="empty-state-title">No prepared plans yet</div>
-                <div className="empty-state-desc">Prepared plans will appear here after you convert an accepted review candidate into an explicit apply plan.</div>
-              </div>
+              <NextStepEmptyState
+                title="No prepared plans yet"
+                description="Prepared plans will appear here after an accepted review candidate is converted into an explicit apply plan with snapshot-backed safety."
+                command="helixevo topology --prepare <candidateId>"
+                pageLink={{ label: 'Open Ontology', href: '/ontology', tone: 'green' }}
+                guideLink={{ label: 'Guide · Maturity & Safety', anchor: 'maturity', tone: 'yellow' }}
+              />
             )}
           </div>
         </div>
@@ -426,10 +446,13 @@ export default function TopologyClient({
                 </div>
               </div>
             )) : (
-              <div className="empty-state" style={{ padding: 24 }}>
-                <div className="empty-state-title">No topology decisions yet</div>
-                <div className="empty-state-desc">Run graph optimize to populate the queue, then accept, defer, or reject structural candidates from here.</div>
-              </div>
+              <NextStepEmptyState
+                title="No topology decisions yet"
+                description="Run graph optimize to populate the queue, then accept, defer, or reject structural candidates from this page so the review memory becomes explicit."
+                command="helixevo graph --optimize"
+                pageLink={{ label: 'Open Co-Evolution', href: '/coevolution', tone: 'purple' }}
+                guideLink={{ label: 'Guide · Surface Map', anchor: 'surfaces', tone: 'blue' }}
+              />
             )}
           </div>
         </SectionFrame>
@@ -491,10 +514,13 @@ export default function TopologyClient({
               </div>
             </div>
           )) : (
-            <div className="empty-state" style={{ padding: 28 }}>
-              <div className="empty-state-title">No topology backlog yet</div>
-              <div className="empty-state-desc">Run <code>graph --optimize</code> from this page to refresh structural review candidates and turn manual-review into a populated operator lane.</div>
-            </div>
+            <NextStepEmptyState
+              title="No topology backlog yet"
+              description="Refresh structural review candidates from this page to turn manual-review into a populated operator lane instead of a placeholder route label."
+              command="helixevo graph --optimize"
+              pageLink={{ label: 'Open Ontology', href: '/ontology', tone: 'green' }}
+              guideLink={{ label: 'Guide · Surface Map', anchor: 'surfaces', tone: 'blue' }}
+            />
           )}
         </div>
       </SectionFrame>
@@ -539,10 +565,12 @@ export default function TopologyClient({
               </div>
             </div>
           )) : (
-            <div className="empty-state" style={{ padding: 24 }}>
-              <div className="empty-state-title">No applied topology history yet</div>
-              <div className="empty-state-desc">Once a prepared safe plan is applied, it will appear here with rollback continuity.</div>
-            </div>
+            <NextStepEmptyState
+              title="No applied topology history yet"
+              description="Applied topology history will appear here once a prepared safe plan is executed and snapshot-backed rollback continuity becomes relevant."
+              command="helixevo topology --apply <planId>"
+              guideLink={{ label: 'Guide · Maturity & Safety', anchor: 'maturity', tone: 'yellow' }}
+            />
           )}
         </div>
       </SectionFrame>
@@ -567,10 +595,13 @@ export default function TopologyClient({
               </div>
             </div>
           )) : (
-            <div className="empty-state" style={{ padding: 24 }}>
-              <div className="empty-state-title">No structural candidates stored yet</div>
-              <div className="empty-state-desc">The ledger will populate after the first topology refresh.</div>
-            </div>
+            <NextStepEmptyState
+              title="No structural candidates stored yet"
+              description="The structural review ledger will populate after the first topology refresh and then persist reviewed intent across decisions and execution."
+              command="helixevo graph --optimize"
+              pageLink={{ label: 'Open Co-Evolution', href: '/coevolution', tone: 'purple' }}
+              guideLink={{ label: 'Guide · Surface Map', anchor: 'surfaces', tone: 'blue' }}
+            />
           )}
         </div>
       </SectionFrame>

package/dashboard/app/topology/page.tsx

@@ -1,4 +1,5 @@
 import { loadGovernanceState, loadTopologyDashboardSummary } from '@/lib/data'
+import { loadProofDashboardSummary } from '@/lib/proof'
 import TopologyClient from './client'
 
 export const dynamic = 'force-dynamic'
@@ -6,5 +7,6 @@ export const dynamic = 'force-dynamic'
 export default function TopologyPage() {
   const dashboard = loadTopologyDashboardSummary()
   const governanceState = loadGovernanceState()
-  return <TopologyClient initialDashboard={dashboard} initialGovernanceState={governanceState} />
+  const proof = loadProofDashboardSummary()
+  return <TopologyClient initialDashboard={dashboard} initialGovernanceState={governanceState} proof={proof} />
 }

package/dashboard/components/guide-deep-link.tsx

@@ -0,0 +1,22 @@
+import Link from 'next/link'
+import { guideHref, type GuideAnchorId, type SurfaceTone } from '@/lib/loop-map'
+
+function toneClass(tone: SurfaceTone) {
+  return `hero-chip hero-chip-${tone}`
+}
+
+export function GuideDeepLink({
+  anchor,
+  label,
+  tone = 'neutral',
+}: {
+  anchor: GuideAnchorId
+  label: string
+  tone?: SurfaceTone
+}) {
+  return (
+    <Link href={guideHref(anchor)} className={toneClass(tone)} style={{ textDecoration: 'none' }}>
+      {label}
+    </Link>
+  )
+}

package/dashboard/components/next-step-empty-state.tsx

@@ -0,0 +1,53 @@
+import Link from 'next/link'
+import { GuideDeepLink } from '@/components/guide-deep-link'
+import type { GuideAnchorId, SurfaceTone } from '@/lib/loop-map'
+
+export function NextStepEmptyState({
+  title,
+  description,
+  command,
+  pageLink,
+  guideLink,
+}: {
+  title: string
+  description: string
+  command?: string
+  pageLink?: { label: string; href: string; tone?: SurfaceTone }
+  guideLink?: { label: string; anchor: GuideAnchorId; tone?: SurfaceTone }
+}) {
+  return (
+    <div className="empty-state" style={{ padding: 24 }}>
+      <div className="empty-state-title">{title}</div>
+      <div className="empty-state-desc" style={{ maxWidth: 680 }}>{description}</div>
+      {command ? (
+        <div
+          style={{
+            marginTop: 14,
+            padding: '12px 14px',
+            borderRadius: 16,
+            border: '1px solid var(--border)',
+            background: 'rgba(255,255,255,0.76)',
+            display: 'inline-grid',
+            gap: 6,
+            textAlign: 'left',
+          }}
+        >
+          <div style={{ fontSize: 10.5, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.9 }}>Try next</div>
+          <code style={{ fontFamily: 'var(--font-mono)', fontSize: 11.5, color: 'var(--text)' }}>$ {command}</code>
+        </div>
+      ) : null}
+      {(pageLink || guideLink) ? (
+        <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', justifyContent: 'center', marginTop: 14 }}>
+          {pageLink ? (
+            <Link href={pageLink.href} className={`hero-chip hero-chip-${pageLink.tone ?? 'blue'}`} style={{ textDecoration: 'none' }}>
+              {pageLink.label}
+            </Link>
+          ) : null}
+          {guideLink ? (
+            <GuideDeepLink anchor={guideLink.anchor} label={guideLink.label} tone={guideLink.tone ?? 'purple'} />
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  )
+}

package/dashboard/components/operator-loop-trail.tsx

@@ -0,0 +1,46 @@
+import Link from 'next/link'
+import { LOOP_STAGES, getSurfaceLoopConfig, type SurfaceKey } from '@/lib/loop-map'
+
+export function OperatorLoopTrail({ surface }: { surface: SurfaceKey }) {
+  const config = getSurfaceLoopConfig(surface)
+
+  return (
+    <div
+      style={{
+        padding: '14px 16px',
+        borderRadius: 20,
+        border: '1px solid var(--border)',
+        background: 'linear-gradient(180deg, rgba(255,255,255,0.82), rgba(245,241,236,0.72))',
+        boxShadow: 'var(--shadow-xs)',
+        display: 'grid',
+        gap: 10,
+      }}
+    >
+      <div style={{ display: 'flex', justifyContent: 'space-between', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
+        <div>
+          <div className="section-label">Operator loop</div>
+          <div style={{ fontSize: 12.5, color: 'var(--text-dim)', marginTop: 4, lineHeight: 1.55 }}>{config.context}</div>
+        </div>
+        <span className="badge badge-gray">
+          {config.stage ? `Current stage · ${LOOP_STAGES.find((stage) => stage.id === config.stage)?.label}` : 'Cockpit view'}
+        </span>
+      </div>
+
+      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+        {LOOP_STAGES.map((stage) => {
+          const active = config.stage === stage.id
+          return (
+            <Link
+              key={stage.id}
+              href={stage.href}
+              className={`hero-chip hero-chip-${active ? stage.tone : 'neutral'}`}
+              style={{ textDecoration: 'none' }}
+            >
+              {stage.label}
+            </Link>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/dashboard/components/sidebar-nav.tsx

@@ -14,6 +14,7 @@ const OPERATE_NAV: NavItem[] = [
   { 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: '/research', label: 'Research', icon: 'M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z' },
   { href: '/coevolution', label: 'Co-Evolution', icon: 'M4 12h4m8 0h4M12 4v4m0 8v4M7.05 7.05l2.83 2.83m4.24 4.24l2.83 2.83m0-9.9l-2.83 2.83m-4.24 4.24l-2.83 2.83' },
+  { href: '/proof', label: 'Proof', icon: 'M9 17v-2m3 2v-4m3 4v-6m2 10H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z' },
 ]
 
 const STRUCTURE_NAV: NavItem[] = [

package/dashboard/components/surface-jump-links.tsx

@@ -0,0 +1,69 @@
+import Link from 'next/link'
+import { getSurfaceLoopConfig, guideHref, type SurfaceKey } from '@/lib/loop-map'
+
+export function SurfaceJumpLinks({
+  surface,
+  title = 'Next hops',
+  variant = 'compact',
+}: {
+  surface: SurfaceKey
+  title?: string
+  variant?: 'compact' | 'panel'
+}) {
+  const config = getSurfaceLoopConfig(surface)
+
+  if (variant === 'compact') {
+    return (
+      <div style={{ display: 'grid', gap: 8 }}>
+        <div style={{ fontSize: 10.5, fontWeight: 700, color: 'var(--text-muted)', letterSpacing: 0.9, textTransform: 'uppercase' }}>{title}</div>
+        <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', justifyContent: 'flex-end' }}>
+          {config.adjacentLinks.map((link) => (
+            <Link key={link.href} href={link.href} className={`badge badge-${link.tone === 'neutral' ? 'gray' : link.tone}`} style={{ textDecoration: 'none' }}>
+              {link.label}
+            </Link>
+          ))}
+          {config.guideLinks.map((link) => (
+            <Link key={link.anchor} href={guideHref(link.anchor)} className={`hero-chip hero-chip-${link.tone}`} style={{ textDecoration: 'none' }}>
+              {link.label}
+            </Link>
+          ))}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div style={{ display: 'grid', gap: 12 }}>
+      <div>
+        <div className="section-label">{title}</div>
+        <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 6, lineHeight: 1.6 }}>
+          Move deliberately into the next most relevant surface instead of backing out to Overview every time.
+        </div>
+      </div>
+
+      <div className="grid-2" style={{ gap: 12 }}>
+        {config.adjacentLinks.map((link) => (
+          <Link
+            key={link.href}
+            href={link.href}
+            className="card"
+            style={{ padding: '14px 16px', textDecoration: 'none', display: 'grid', gap: 6 }}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
+              <span className={`hero-chip hero-chip-${link.tone}`}>{link.label}</span>
+            </div>
+            <div style={{ fontSize: 12, color: 'var(--text-dim)', lineHeight: 1.6 }}>{link.description}</div>
+          </Link>
+        ))}
+      </div>
+
+      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+        {config.guideLinks.map((link) => (
+          <Link key={link.anchor} href={guideHref(link.anchor)} className={`hero-chip hero-chip-${link.tone}`} style={{ textDecoration: 'none' }}>
+            {link.label}
+          </Link>
+        ))}
+      </div>
+    </div>
+  )
+}