helixevo 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to HelixEvo are documented here.
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-03-24
+
+### Changed
+- Rebuilt the dashboard Guide into a clearer operator-and-theory manual with a brain-stack explanation, end-to-end adaptation loop, dashboard surface map, grouped memory model, explicit maturity/safety boundaries, glossary, and current command coverage including `project-setup` and `topology`
+
 ## [0.4.0] - 2026-03-24
 
 ### Added

package/dashboard/app/guide/page.tsx

@@ -9,6 +9,9 @@ const TOC = [
   { id: 'quickstart', label: 'Quick Start', icon: '▸' },
   { id: 'commands', label: 'Commands', icon: '⌘' },
   { id: 'architecture', label: 'Architecture', icon: '◎' },
+  { id: 'brainstack', label: 'Brain Stack', icon: '◈' },
+  { id: 'loop', label: 'Adaptation Loop', icon: '↺' },
+  { id: 'surfaces', label: 'Surface Map', icon: '▦' },
   { id: 'watch', label: 'Always-On Learning', icon: '⚡' },
   { id: 'evolution', label: 'Evolution Pipeline', icon: '⟳' },
   { id: 'judges', label: 'Multi-Judge System', icon: '⚖' },
@@ -21,8 +24,10 @@ const TOC = [
   { id: 'network', label: 'Skill Network', icon: '⬡' },
   { id: 'config', label: 'Configuration', icon: '⚙' },
   { id: 'data', label: 'Data & Storage', icon: '◫' },
+  { id: 'maturity', label: 'Maturity & Safety', icon: '⛉' },
   { id: 'manage', label: 'Skill Management', icon: '✎' },
   { id: 'craft', label: 'Craft Agent', icon: '⚡' },
+  { id: 'glossary', label: 'Glossary', icon: '✦' },
   { id: 'faq', label: 'FAQ', icon: '?' },
 ]
 
@@ -229,7 +234,7 @@ export default function GuidePage() {
           <div>
             <div className="guide-toc-title">Field Guide</div>
             <div style={{ fontSize: 11, color: 'var(--text-muted)', marginTop: 4, lineHeight: 1.45 }}>
-              CLI, evolution, research, and network operations in one manual.
+              Operator manual and brain architecture map for the current HelixEvo release.
             </div>
           </div>
           <div className="guide-toc-version">v{VERSION}</div>
@@ -240,8 +245,8 @@ export default function GuidePage() {
           </div>
           <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap' }}>
             <a href="#quickstart" className="hero-chip hero-chip-blue" style={{ textDecoration: 'none' }}>Quick Start</a>
-            <a href="#watch" className="hero-chip hero-chip-green" style={{ textDecoration: 'none' }}>Always-On</a>
-            <a href="#evolution" className="hero-chip hero-chip-purple" style={{ textDecoration: 'none' }}>Evolution</a>
+            <a href="#brainstack" className="hero-chip hero-chip-green" style={{ textDecoration: 'none' }}>Brain Stack</a>
+            <a href="#surfaces" className="hero-chip hero-chip-purple" style={{ textDecoration: 'none' }}>Surface Map</a>
           </div>
         </div>
         {TOC.map(item => (
@@ -261,227 +266,244 @@ export default function GuidePage() {
       <div className="guide-content">
         {/* Hero */}
         <div className="guide-hero">
-          <div className="guide-hero-badge">Documentation</div>
-          <h1 className="guide-hero-title">HelixEvo Guide</h1>
+          <div className="guide-hero-badge">Operator Manual</div>
+          <h1 className="guide-hero-title">HelixEvo Brain Guide</h1>
           <p className="guide-hero-desc">
-            A comprehensive guide to the self-evolving skill ecosystem for AI agents.
-            Capture failures, evolve skills through multi-judge evaluation, and maintain
-            a Pareto frontier of optimal configurations.
+            A structured guide to the current HelixEvo brain: semantic kernel, observation memory,
+            pressure, governed response, transfer, topology review, and rollbackable reviewed execution.
+            Use it as both an operator manual and a theory-to-product map.
           </p>
           <div className="hero-chip-row" style={{ marginTop: 18 }}>
             <span className="hero-chip hero-chip-blue">v{VERSION}</span>
             <span className="hero-chip hero-chip-purple">{TOC.length} sections</span>
-            <span className="hero-chip hero-chip-green">CLI + dashboard + network</span>
-            <span className="hero-chip hero-chip-yellow">operator reference</span>
+            <span className="hero-chip hero-chip-green">operator path + theory path</span>
+            <span className="hero-chip hero-chip-yellow">governed plasticity reference</span>
           </div>
 
           <div className="grid-3" style={{ marginTop: 24, marginBottom: 24 }}>
             <div className="card" style={{ padding: '18px 18px 16px' }}>
-              <div style={{ fontSize: 10, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.7, marginBottom: 8 }}>Start here</div>
-              <div style={{ fontSize: 15, fontWeight: 700, color: 'var(--text)', marginBottom: 6 }}>Quick Start → Watch → Evolve</div>
-              <div style={{ fontSize: 12.5, color: 'var(--text-dim)', lineHeight: 1.6 }}>If you are new, this path gets HelixEvo initialized, learning from corrections, and producing measurable skill improvements.</div>
+              <div style={{ fontSize: 10, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.7, marginBottom: 8 }}>Start operating</div>
+              <div style={{ fontSize: 15, fontWeight: 700, color: 'var(--text)', marginBottom: 6 }}>Project setup → Watch / Capture → Co-Evolution → Topology</div>
+              <div style={{ fontSize: 12.5, color: 'var(--text-dim)', lineHeight: 1.6 }}>This is the shortest path to seeing pressure, governed response, and structural control in the live product.</div>
             </div>
             <div className="card" style={{ padding: '18px 18px 16px' }}>
-              <div style={{ fontSize: 10, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.7, marginBottom: 8 }}>Core mental model</div>
-              <div style={{ fontSize: 15, fontWeight: 700, color: 'var(--text)', marginBottom: 6 }}>Capture failures, mutate skills, validate aggressively</div>
-              <div style={{ fontSize: 12.5, color: 'var(--text-dim)', lineHeight: 1.6 }}>The system only gets better when real corrections are fed into evaluation, regression testing, and monitored deployment.</div>
+              <div style={{ fontSize: 10, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.7, marginBottom: 8 }}>Understand the brain</div>
+              <div style={{ fontSize: 15, fontWeight: 700, color: 'var(--text)', marginBottom: 6 }}>Read the stack, then trace one signal through the loop</div>
+              <div style={{ fontSize: 12.5, color: 'var(--text-dim)', lineHeight: 1.6 }}>The current system is best understood as layered cognition: semantic kernel → observation → pressure → response → transfer → governance → topology.</div>
             </div>
             <div className="card" style={{ padding: '18px 18px 16px' }}>
               <div style={{ fontSize: 10, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.7, marginBottom: 8 }}>Fast jumps</div>
               <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
                 <a href="#quickstart" className="hero-chip hero-chip-blue" style={{ textDecoration: 'none' }}>Quick Start</a>
-                <a href="#commands" className="hero-chip hero-chip-purple" style={{ textDecoration: 'none' }}>Commands</a>
-                <a href="#architecture" className="hero-chip hero-chip-green" style={{ textDecoration: 'none' }}>Architecture</a>
-                <a href="#network" className="hero-chip hero-chip-yellow" style={{ textDecoration: 'none' }}>Skill Network</a>
+                <a href="#brainstack" className="hero-chip hero-chip-purple" style={{ textDecoration: 'none' }}>Brain Stack</a>
+                <a href="#surfaces" className="hero-chip hero-chip-green" style={{ textDecoration: 'none' }}>Surface Map</a>
+                <a href="#maturity" className="hero-chip hero-chip-yellow" style={{ textDecoration: 'none' }}>Safety</a>
               </div>
             </div>
           </div>
 
           <div className="guide-hero-features">
-            <FeatureCard icon="⚡" title="Always-On" desc="Auto-captures corrections and triggers evolution in real-time" />
-            <FeatureCard icon="♺" title="Network Evolution" desc="Skills and projects co-evolve as an interconnected organism" />
-            <FeatureCard icon="📊" title="Closed-Loop Proof" desc="Tracks whether evolution actually reduces correction rates" />
-            <FeatureCard icon="↑" title="Auto-Generalize" desc="Cross-project patterns automatically become abstract skills" />
+            <FeatureCard icon="⚡" title="Pressure-Aware" desc="Failures and project gaps become explicit adaptation demand rather than hidden friction" />
+            <FeatureCard icon="⇄" title="Governed Routing" desc="Response lanes stay visible: research, specialize, evolve, generalize, and manual review" />
+            <FeatureCard icon="◎" title="Topology Control" desc="Reviewed structural changes can now move through prepare, apply, and rollback" />
+            <FeatureCard icon="📊" title="Closed-Loop Proof" desc="Backtesting and operator visibility show whether the brain is actually improving" />
           </div>
         </div>
 
         {/* ─── Overview ─── */}
-        <Section id="overview" title="Overview" subtitle="What HelixEvo does and why it exists.">
+        <Section id="overview" title="Overview" subtitle="HelixEvo is now best understood as a governed co-evolving brain.">
           <p className="guide-text">
-            HelixEvo is a self-improving system that manages SKILL.md files for AI agents. When an agent makes a mistake
-            and gets corrected, HelixEvo captures that failure, clusters similar failures together, and proposes skill
-            improvements. Every proposed change goes through rigorous multi-judge evaluation and regression testing before
-            being deployed with a 3-day canary period.
+            HelixEvo still captures failures, proposes skill mutations, evaluates them with judges, and deploys improvements carefully.
+            What changed over the recent milestone arc is that these mutation mechanics now live inside a larger architecture that senses pressure,
+            routes intervention under governance, records transfer evidence, reviews topology, and can execute a safe reviewed subset of structural change with rollback.
           </p>
           <p className="guide-text">
-            Built on ideas from <strong>EvoSkill</strong> and <strong>AutoResearch</strong>, HelixEvo implements a
-            three-directional evolution model:
+            That means the current product should not be explained as only “capture → evolve → validate.” The more truthful frame is:
+            <strong> semantic kernel → observation → pressure → response → transfer → governance → topology review → topology execution → operator surfaces.</strong>
           </p>
           <div className="guide-directions">
             <div className="guide-direction">
-              <div className="guide-direction-arrow" style={{ color: 'var(--purple)' }}>↑</div>
+              <div className="guide-direction-arrow" style={{ color: 'var(--blue)' }}>◎</div>
               <div>
-                <strong>Generalize</strong>
-                <span>Detect cross-project patterns and promote them to abstract, reusable skills</span>
+                <strong>Sense</strong>
+                <span>Failures, project analysis, and activation traces reveal where the system is under demand</span>
               </div>
             </div>
             <div className="guide-direction">
-              <div className="guide-direction-arrow" style={{ color: 'var(--green)' }}>↓</div>
+              <div className="guide-direction-arrow" style={{ color: 'var(--purple)' }}>⇄</div>
               <div>
-                <strong>Specialize</strong>
-                <span>Create project-specific skills from domain skills combined with local failures</span>
+                <strong>Respond</strong>
+                <span>Governed routes choose whether pressure should drive research, specialize, evolve, generalize, or manual review</span>
               </div>
             </div>
             <div className="guide-direction">
-              <div className="guide-direction-arrow" style={{ color: 'var(--blue)' }}>↔</div>
+              <div className="guide-direction-arrow" style={{ color: 'var(--green)' }}>⛉</div>
               <div>
-                <strong>Lateral</strong>
-                <span>Merge, split, and resolve conflicts between skills at the same level</span>
+                <strong>Restructure</strong>
+                <span>Accepted topology review can now become prepared, applied, and rollbackable structural change</span>
               </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, pressure signals, governance steering, topology review, and reviewed topology execution all feed the Overview,
-            Skill Network, Topology, Projects, Research, and Evolution surfaces.
+            Read this guide in two modes: <strong>operator path</strong> if you want to know what to run and which tab to use,
+            or <strong>theory path</strong> if you want to understand how ontology, pressure, governance, transfer, and topology now fit together.
           </Callout>
         </Section>
 
         {/* ─── Quick Start ─── */}
-        <Section id="quickstart" title="Quick Start" subtitle="Get up and running in under 5 minutes.">
+        <Section id="quickstart" title="Quick Start" subtitle="The shortest operator path through the current HelixEvo brain loop.">
           <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">
-            <Code title="Terminal">{`# From npm (recommended)
+          <Step n={1} title="Install and initialize HelixEvo">
+            <Code title="Terminal">{`# Install from npm
 npm install -g helixevo
 
-# Or from source
-git clone https://github.com/danielchen26/helixevo.git
-cd helixevo && npm install && npm run build && npm link`}</Code>
-          </Step>
-
-          <Step n={2} title="Initialize your skill ecosystem">
-            <Code title="Terminal">{`helixevo init`}</Code>
+# Initialize your skill ecosystem
+helixevo init`}</Code>
             <p className="guide-text-sm">
-              This scans your existing SKILL.md files (from <code>~/.agents/skills/</code>), imports them into HelixEvo,
-              and generates skill tests for each skill. It also creates the data directory at <code>~/.helix/</code>.
+              Initialization imports existing skills, generates regression tests, and creates the runtime memory under <code>~/.helix/</code>.
             </p>
           </Step>
 
-          <Step n={3} title="Capture failures from a session">
-            <Code title="Terminal">{`helixevo capture path/to/session.json --project myapp`}</Code>
+          <Step n={2} title="Analyze a real project so the brain has context">
+            <Code title="Terminal">{`# Analyze the current repository
+helixevo project-setup .
+
+# Or analyze another project path
+helixevo project-setup ~/myapp --verbose`}</Code>
             <p className="guide-text-sm">
-              Extracts corrections, mode switches, retries, and manual edits from Claude session files and records them
-              as structured failure records.
+              <code>project-setup</code> is now a key operator entry point because it persists project context, activation traces, and pressure signals instead of leaving the dashboard blind to real project demand.
             </p>
           </Step>
 
-          <Step n={4} title="Evolve skills">
-            <Code title="Terminal">{`helixevo evolve --verbose`}</Code>
+          <Step n={3} title="Feed the observation layer">
+            <Code title="Terminal">{`# Continuous observation
+helixevo watch --project myapp
+
+# Or one-off capture
+helixevo capture path/to/session.json --project myapp`}</Code>
             <p className="guide-text-sm">
-              Clusters failures, generates proposals, runs 3-judge evaluation and regression tests, then deploys
-              improvements as canaries. Use <code>--dry-run</code> to preview without applying.
+              Observation is where corrections become structured memory. Without this layer, the response and topology layers have nothing truthful to operate on.
             </p>
           </Step>
 
-          <Step n={5} title="Explore the results">
-            <Code title="Terminal">{`# View the skill network
-helixevo graph
+          <Step n={4} title="Run the response loop">
+            <Code title="Terminal">{`# Proposal-level evolution
+helixevo evolve --verbose
 
-# Open this dashboard
-helixevo dashboard
-
-# Prefer a different port if you want
-helixevo dashboard --port 3900
+# Structural review + execution status
+helixevo graph --optimize
+helixevo topology --status`}</Code>
+            <p className="guide-text-sm">
+              <code>evolve</code> mutates skills directly, while <code>graph --optimize</code> and <code>topology</code> expose the higher-level structural review and execution loop.
+            </p>
+          </Step>
 
-# Check system health
-helixevo status`}</Code>
+          <Step n={5} title="Use the dashboard as the operator cockpit">
+            <Code title="Terminal">{`helixevo dashboard
+# Then visit Overview → Co-Evolution → Topology → Network`}</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.
+              The dashboard prefers port <code>3847</code>, reuses a known managed dashboard when possible, and otherwise falls forward to the next open port.
+              Use <strong>Co-Evolution</strong> for routed pressure and <strong>Topology</strong> for reviewed structural control.
             </p>
           </Step>
         </Section>
 
         {/* ─── Commands ─── */}
-        <Section id="commands" title="Commands" subtitle="Complete CLI reference for every HelixEvo command.">
+        <Section id="commands" title="Commands" subtitle="Command surfaces grouped by the job they do in the current brain loop.">
+          <p className="guide-text">
+            The CLI is now easier to reason about if you group commands by role: <strong>observe</strong>, <strong>respond</strong>,
+            <strong>restructure</strong>, and <strong>prove</strong>. The Guide now explicitly includes the current release-critical additions
+            such as <code>project-setup</code> and <code>topology</code>.
+          </p>
           <div className="guide-command-grid">
             {[
               {
-                cmd: 'helixevo watch',
-                desc: 'Always-on learning mode. Watches for corrections in real-time, auto-captures failures, and triggers evolution when thresholds are met.',
-                flags: ['--project <name>', '--events <path>', '--verbose', '--no-evolve'],
-              },
-              {
-                cmd: 'helixevo metrics',
-                desc: 'Show correction rates per skill, trends over time, and whether each evolution actually reduced corrections. The proof that HelixEvo works.',
-                flags: ['--verbose'],
+                cmd: 'helixevo init',
+                desc: 'Initialize the skill ecosystem, generate tests, and build the first local brain memory under ~/.helix/.',
+                flags: ['--skills-paths <paths...>', '--skip-tests'],
               },
               {
-                cmd: 'helixevo health',
-                desc: 'Assess network health: cohesion, coverage, balance, cross-project transfer rate. Detects gaps, orphans, and generalization candidates.',
-                flags: ['--verbose'],
+                cmd: 'helixevo project-setup <path>',
+                desc: 'Analyze a project, persist a project profile, emit activation traces, and turn missing capability into project-level pressure.',
+                flags: ['--dry-run', '--verbose'],
               },
               {
-                cmd: 'helixevo init',
-                desc: 'Import existing skills and generate skill tests. Scans ~/.agents/skills/ and creates the HelixEvo data directory.',
-                flags: ['--verbose'],
+                cmd: 'helixevo watch',
+                desc: 'Always-on observation mode. Watches for corrections in real time, captures failures automatically, and triggers evolution when thresholds are met.',
+                flags: ['--project <name>', '--events <path>', '--verbose', '--no-evolve'],
               },
               {
                 cmd: 'helixevo capture <session>',
-                desc: 'Extract failure records from a Claude session JSON file. Detects verbal corrections, manual edits, mode switches, and retries.',
+                desc: 'Extract failure records from a session file when you want one-off observation instead of continuous watch mode.',
                 flags: ['--project <name>', '--verbose'],
               },
               {
                 cmd: 'helixevo evolve',
-                desc: 'Run the full evolution cycle: cluster failures, generate proposals, evaluate with 3 judges, regression test, and deploy canaries.',
+                desc: 'Run the proposal-level mutation pipeline: cluster failures, propose changes, judge them, regression test them, and admit winners.',
                 flags: ['--dry-run', '--verbose', '--max-proposals <n>'],
               },
               {
-                cmd: 'helixevo generalize',
-                desc: 'Promote cross-project patterns upward. Detects skills that solve similar problems across projects and creates abstract parent skills.',
-                flags: ['--dry-run', '--verbose'],
+                cmd: 'helixevo research',
+                desc: 'Run the discovery lane for missing capability, frontier practices, and experimental skill opportunities.',
+                flags: ['--project <path>', '--max-hypotheses <n>', '--dry-run', '--verbose'],
               },
               {
                 cmd: 'helixevo specialize --project <name>',
-                desc: 'Create project-specific skills by combining domain skills with project-level failure patterns.',
+                desc: 'Push knowledge downward into project-specific variants when local context matters more than shared abstraction.',
                 flags: ['--dry-run', '--verbose'],
               },
               {
-                cmd: 'helixevo research',
-                desc: 'Proactive web research to discover new skill opportunities. Searches for best practices, analyzes gaps, and generates experimental skills.',
-                flags: ['--project <path>', '--max-hypotheses <n>', '--dry-run', '--verbose'],
+                cmd: 'helixevo generalize',
+                desc: 'Push recurring multi-project motifs upward into reusable shared knowledge with transfer evidence.',
+                flags: ['--dry-run', '--verbose'],
               },
               {
                 cmd: 'helixevo graph',
-                desc: 'Visualize the skill network. Shows nodes (skills), edges (relationships), and clusters.',
-                flags: ['--mermaid', '--obsidian <vault>', '--rebuild', '--optimize'],
+                desc: 'Inspect the network and, with --optimize, refresh topology review candidates for structural issues and opportunities.',
+                flags: ['--mermaid', '--obsidian <vault>', '--rebuild', '--optimize', '--verbose'],
+              },
+              {
+                cmd: 'helixevo topology',
+                desc: 'Move accepted topology review through prepare, apply, and rollback. This is the explicit control surface for reviewed structural execution.',
+                flags: ['--status', '--prepare <candidateId>', '--apply <planId>', '--rollback <planId>', '--verbose'],
+              },
+              {
+                cmd: 'helixevo health',
+                desc: 'Assess cohesion, coverage, balance, and transfer so you can tell whether the network is learning in a reusable and connected way.',
+                flags: ['--verbose'],
+              },
+              {
+                cmd: 'helixevo metrics',
+                desc: 'Measure whether evolution actually reduces corrections over time. This is the primary proof command.',
+                flags: ['--verbose'],
               },
               {
                 cmd: 'helixevo dashboard',
-                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.',
+                desc: 'Open the premium operator dashboard. It prefers localhost:3847, reuses a known managed dashboard, falls forward if needed, and can auto-update before launch.',
                 flags: ['--background', '--stop', '--port <port>', '--no-auto-update'],
               },
               {
                 cmd: 'helixevo status',
-                desc: 'Show system health: skill count, failure stats, frontier status, canary deployments, and recent evolution.',
+                desc: 'Show fast system state without deeper LLM analysis.',
                 flags: [],
               },
               {
                 cmd: 'helixevo report',
-                desc: 'Generate a detailed evolution report. Can output to file, Obsidian vault, or Craft Agent session.',
-                flags: ['--verbose'],
+                desc: 'Generate a human-readable summary of evolution activity over a time window.',
+                flags: ['--days <n>', '--output <path>'],
               },
-            ].map(c => (
+            ].map((c) => (
               <div key={c.cmd} className="guide-command-card">
                 <code className="guide-command-name">{c.cmd}</code>
                 <p className="guide-command-desc">{c.desc}</p>
                 {c.flags.length > 0 && (
                   <div className="guide-command-flags">
-                    {c.flags.map(f => <code key={f} className="guide-command-flag">{f}</code>)}
+                    {c.flags.map((f) => <code key={f} className="guide-command-flag">{f}</code>)}
                   </div>
                 )}
               </div>
@@ -489,46 +511,179 @@ helixevo status`}</Code>
           </div>
 
           <Callout type="tip">
-            Most commands support <code>--dry-run</code> to preview changes without applying them,
-            and <code>--verbose</code> to see detailed LLM interactions and scoring.
+            A good mental grouping is: <strong>observe</strong> with <code>project-setup</code>, <code>watch</code>, and <code>capture</code>;
+            <strong>respond</strong> with <code>research</code>, <code>specialize</code>, <code>evolve</code>, and <code>generalize</code>;
+            <strong>restructure</strong> with <code>graph --optimize</code> plus <code>topology</code>; and <strong>prove</strong> with <code>metrics</code>, <code>health</code>, and <code>report</code>.
           </Callout>
         </Section>
 
         {/* ─── Architecture ─── */}
-        <Section id="architecture" title="Architecture" subtitle="How the system is structured and how data flows through it.">
-          <h3 className="guide-h3">Pipeline</h3>
+        <Section id="architecture" title="Architecture" subtitle="How the classic evolution pipeline now sits inside a broader co-evolving brain.">
+          <h3 className="guide-h3">Classic mutation pipeline</h3>
           <p className="guide-text">
-            Every evolution cycle follows this pipeline. Each stage acts as a quality gate — proposals must
-            pass all stages to be deployed.
+            The original HelixEvo mutation pipeline is still real and still important. Capture, clustering, proposal generation,
+            judging, regression, and canary deployment remain the core mutation engine. What changed in the recent milestone arc is that
+            this engine now operates inside a bigger system that senses pressure, routes intervention, persists governance,
+            reviews topology, and executes a safe subset of structural changes with rollback.
           </p>
           <ArchitectureDiagram />
 
-          <h3 className="guide-h3">Brain Foundation</h3>
+          <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>
+            {[
+              ['Ontology', 'var(--blue)', 'Stable semantic kernel for skills, projects, tasks, capabilities, artifacts, and mutations.'],
+              ['Activation traces', 'var(--green)', 'Observation memory showing which skills and gaps were active when capture or project analysis occurred.'],
+              ['Pressure signals', 'var(--yellow)', 'Explicit adaptation demand derived from failures and project gaps.'],
+              ['Interventions', 'var(--purple)', 'The response ledger across research, specialize, evolve, generalize, and manual-review lanes.'],
+              ['Governance', 'var(--blue)', 'Derived or operator-selected routing bias that explains why the system is steering one way rather than another.'],
+              ['Topology memory', 'var(--green)', 'Review candidates, decisions, apply plans, snapshots, artifacts, and rollbackable structural state.'],
+            ].map(([label, color, desc]) => (
+              <div key={String(label)} className="guide-dimension-card" style={{ borderLeftColor: String(color) }}>
+                <div style={{ fontSize: 11, fontWeight: 700, color: String(color), textTransform: 'uppercase', letterSpacing: 1 }}>{label}</div>
+                <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 4 }}>{desc}</div>
+              </div>
+            ))}
           </div>
 
-          <h3 className="guide-h3">Three-Layer Hierarchy</h3>
+          <h3 className="guide-h3">Three-layer skill hierarchy</h3>
           <p className="guide-text">
-            Skills are organized into three layers. The <code>generalize</code> command promotes patterns upward,
-            while <code>specialize</code> creates project-specific variants downward.
+            The skill hierarchy still matters. <code>specialize</code> pushes knowledge downward into project context,
+            while <code>generalize</code> promotes reusable knowledge upward into shared layers. The newer pressure, transfer, and topology work does not replace this hierarchy — it makes the hierarchy more governable.
           </p>
           <HierarchyDiagram />
+
+          <Callout type="tip">
+            The next three sections are the real bridge from theory to product: the <strong>9-layer conceptual stack</strong>,
+            a concrete <strong>end-to-end adaptation loop</strong>, and a <strong>dashboard surface map</strong> showing where each part of the brain becomes visible.
+          </Callout>
+        </Section>
+
+        {/* ─── Brain Stack ─── */}
+        <Section id="brainstack" title="Brain Stack" subtitle="The clearest current mental model for HelixEvo is a layered stack, not a flat feature list.">
+          <div className="grid-2" style={{ gap: 12 }}>
+            {[
+              {
+                title: '1. Semantic layer',
+                color: 'var(--blue)',
+                desc: 'Ontology and invariants define what kinds of things HelixEvo can talk about and persist truthfully.',
+                where: 'Visible in: ontology-aware graph summaries, skill metadata, and brain foundation summaries.'
+              },
+              {
+                title: '2. Observation layer',
+                color: 'var(--green)',
+                desc: 'Failures, project analysis, and activation traces record what happened, where it happened, and which skills were active.',
+                where: 'Visible in: capture, project-setup, Projects, and Evolution.'
+              },
+              {
+                title: '3. Pressure layer',
+                color: 'var(--yellow)',
+                desc: 'Pressure signals convert raw observation into explicit adaptation demand at local, project, and network scope. Motifs aggregate recurring patterns above single signals.',
+                where: 'Visible in: Overview, Co-Evolution, Network, Projects, and Research.'
+              },
+              {
+                title: '4. Response layer',
+                color: 'var(--purple)',
+                desc: 'Interventions route pressure into research, specialize, evolve, generalize, or manual review. This is where the system decides how to act.',
+                where: 'Visible in: Co-Evolution backlog, recent interventions, and route recommendations.'
+              },
+              {
+                title: '5. Transfer layer',
+                color: 'var(--blue)',
+                desc: 'Transfer events record when reusable knowledge was actually promoted, not just suggested. This is how motif-level closure becomes truthful.',
+                where: 'Visible in: Co-Evolution promotion queue, transfer evidence, and Research / Network transfer summaries.'
+              },
+              {
+                title: '6. Governance layer',
+                color: 'var(--green)',
+                desc: 'Governance selects the current routing posture: derived automatically from conditions or pinned manually by the operator.',
+                where: 'Visible in: Co-Evolution and Topology governance chips, rationale, and profile explanation.'
+              },
+              {
+                title: '7. Topology review layer',
+                color: 'var(--yellow)',
+                desc: 'Graph optimization and network health produce structural review candidates. Operator decisions persist review memory instead of disappearing into an ephemeral suggestion list.',
+                where: 'Visible in: graph --optimize, Topology review queue, and decision ledger.'
+              },
+              {
+                title: '8. Topology execution layer',
+                color: 'var(--purple)',
+                desc: 'Accepted safe candidates can now become apply plans with snapshots, artifacts, apply state, and rollback. Riskier classes remain bounded.',
+                where: 'Visible in: Topology accepted-ready queue, prepared queue, applied history, and /api/topology-apply.'
+              },
+              {
+                title: '9. Surface layer',
+                color: 'var(--blue)',
+                desc: 'The dashboard is not decoration; each tab exposes a different slice of the brain so operators can inspect, steer, and verify it.',
+                where: 'Visible in: Overview, Co-Evolution, Network, Topology, Projects, Research, Evolution, Commands, and Guide.'
+              },
+            ].map((layer) => (
+              <div key={layer.title} className="guide-dimension-card" style={{ borderLeftColor: layer.color }}>
+                <div style={{ fontSize: 12, fontWeight: 700, color: layer.color, letterSpacing: 0.2 }}>{layer.title}</div>
+                <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 6, lineHeight: 1.6 }}>{layer.desc}</div>
+                <div style={{ fontSize: 11, color: 'var(--text-muted)', marginTop: 8, lineHeight: 1.55 }}>{layer.where}</div>
+              </div>
+            ))}
+          </div>
+        </Section>
+
+        {/* ─── Adaptation Loop ─── */}
+        <Section id="loop" title="End-to-End Adaptation Loop" subtitle="One realistic signal can now travel through observation, pressure, response, review, and safe structural execution.">
+          <p className="guide-text">
+            This example is the easiest way to connect the theory to the product. It shows how a real capability gap can move through the current HelixEvo brain.
+          </p>
+          <Code title="Worked example">{`Project setup spots repeated UI architecture gaps
+  → activation trace records the active skills + missing capability
+  → pressure signal opens for the project and contributes to a recurring motif
+  → governance biases the route toward research / specialize / generalize
+  → an intervention is recorded in the response ledger
+  → transfer events accumulate if reusable knowledge is promoted
+  → graph --optimize surfaces a topology review candidate if the structure itself needs cleanup
+  → operator accepts the candidate in /topology
+  → helixevo topology --prepare creates an apply plan + snapshot + artifact
+  → helixevo topology --apply changes the effective graph through the override layer
+  → helixevo topology --rollback restores the before-apply snapshot if needed`}</Code>
+
+          <div className="guide-pipeline" style={{ marginTop: 18 }}>
+            <PipelineStep icon="1" title="Observe" color="var(--blue)" desc="Project analysis or failure capture persists activation-aware observation." />
+            <div className="guide-pipeline-connector" />
+            <PipelineStep icon="2" title="Pressurize" color="var(--yellow)" desc="Observation becomes explicit demand through pressure signals and recurring motifs." />
+            <div className="guide-pipeline-connector" />
+            <PipelineStep icon="3" title="Route" color="var(--purple)" desc="Governance biases the next lane: research, specialize, evolve, generalize, or manual review." />
+            <div className="guide-pipeline-connector" />
+            <PipelineStep icon="4" title="Restructure" color="var(--green)" desc="Topology review and execution handle cases where the structure itself, not just a skill rule, must change." />
+            <div className="guide-pipeline-connector" />
+            <PipelineStep icon="5" title="Prove" color="var(--blue)" desc="Metrics, transfer evidence, artifacts, and rollback discipline show whether the system improved truthfully." />
+          </div>
+
+          <Callout type="info">
+            A key current semantic rule is that <strong>motif-level transfer can address recurring network pressure without falsely claiming that every local signal is closed</strong>.
+            That rule is one of the biggest maturity improvements in the recent theory and implementation arc.
+          </Callout>
+        </Section>
+
+        {/* ─── Surface Map ─── */}
+        <Section id="surfaces" title="Dashboard Surface Map" subtitle="Each tab is a different control or observability surface for the same brain.">
+          <div className="grid-2" style={{ gap: 12 }}>
+            {[
+              ['Overview', 'var(--blue)', 'Top-level cockpit for frontier state, brain foundation, pressure totals, topology review counts, and prepared/applied structural state.'],
+              ['Co-Evolution', 'var(--purple)', 'The response cockpit. Use it to inspect routed pressure, governance mode, promotion queue, interventions, and transfer evidence.'],
+              ['Skill Network', 'var(--green)', 'Graph-level understanding: relationships, co-evolution signals, inspector context, and structural handoff links.'],
+              ['Topology', 'var(--yellow)', 'Governed plasticity surface for review decisions, accepted-ready queue, prepared plans, apply, rollback, and execution history.'],
+              ['Projects', 'var(--blue)', 'Project intake and project-aware pressure surface. Best for capability gaps, activation traces, and promotion feeders.'],
+              ['Research', 'var(--purple)', 'Discovery-oriented view grounded in current pressure and routed recommendations rather than disconnected idea generation.'],
+              ['Evolution', 'var(--green)', 'Proposal-centric evidence view: judge scores, artifact provenance, and iteration history.'],
+              ['Commands + Guide', 'var(--yellow)', 'Reference surfaces: one for command execution semantics, one for operator mental model and architecture.'],
+            ].map(([title, color, desc]) => (
+              <div key={String(title)} className="guide-dimension-card" style={{ borderLeftColor: String(color) }}>
+                <div style={{ fontSize: 12, fontWeight: 700, color: String(color), letterSpacing: 0.2 }}>{title}</div>
+                <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 6, lineHeight: 1.6 }}>{desc}</div>
+              </div>
+            ))}
+          </div>
+          <Callout type="tip">
+            If you are debugging current state, the best sequence is usually: <strong>Overview → Co-Evolution → Topology → Skill Network → Projects / Research</strong>.
+            That path mirrors the stack from summary → routed demand → structural review/execution → graph context → project or discovery detail.
+          </Callout>
         </Section>
 
         {/* ─── Always-On Learning ─── */}
@@ -902,7 +1057,7 @@ generation: 3
         </Section>
 
         {/* ─── Data & Storage ─── */}
-        <Section id="data" title="Data & Storage" subtitle="Where everything lives and how it's structured.">
+        <Section id="data" title="Data & Storage" subtitle="The runtime memory is now easier to understand as grouped cognitive layers, not just a flat folder tree.">
           <Code title="~/.helix/ directory structure">{`~/.helix/
 ├── config.json              # Configuration
 ├── failures.jsonl           # Captured failure records (append-only)
@@ -921,7 +1076,7 @@ generation: 3
 ├── 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-tests.jsonl        # Regression test cases (append-only)
 ├── skill-graph.json         # Cached network (nodes + edges + ontology version)
 ├── canary-registry.json     # Active canary deployments
 ├── knowledge-buffer.json    # Research discoveries + drafts
@@ -931,35 +1086,100 @@ generation: 3
 ├── backups/                 # Pre-canary skill backups
 └── reports/                 # Generated evolution reports`}</Code>
 
-          <h3 className="guide-h3">Key Data Formats</h3>
-          <div className="grid-2" style={{ gap: 12 }}>
+          <h3 className="guide-h3">Memory groups</h3>
+          <div className="grid-2" style={{ gap: 12, marginBottom: 20 }}>
+            {[
+              ['Observation memory', 'var(--blue)', 'failures.jsonl + activation-traces.jsonl capture what happened, where it happened, and which skills were active.'],
+              ['Pressure & response memory', 'var(--yellow)', 'pressure-signals.jsonl + pressure-interventions.jsonl + transfer-events.jsonl describe demand, routing, and reusable promotion evidence.'],
+              ['Governance & review memory', 'var(--purple)', 'governance-state.json + topology-review-candidates.json + topology-review-decisions.jsonl preserve why structural decisions are being made.'],
+              ['Topology execution memory', 'var(--green)', 'topology-overrides.json + topology-snapshots.json + topology-apply-plans.json + topology-executions.jsonl + topology-artifacts.jsonl preserve reviewed structural execution and rollback.'],
+              ['Evaluation & frontier memory', 'var(--blue)', 'evolution-history.json + evolution-artifacts.jsonl + skill-tests.jsonl + canary-registry.json + frontier.json preserve proof, guardrails, and best configurations.'],
+              ['Discovery memory', 'var(--purple)', 'knowledge-buffer.json keeps research discoveries and drafts so failed experiments can be iterated instead of lost.'],
+            ].map(([title, color, desc]) => (
+              <div key={String(title)} className="guide-dimension-card" style={{ borderLeftColor: String(color) }}>
+                <div style={{ fontSize: 12, fontWeight: 700, color: String(color), letterSpacing: 0.2 }}>{title}</div>
+                <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 6, lineHeight: 1.6 }}>{desc}</div>
+              </div>
+            ))}
+          </div>
+
+          <h3 className="guide-h3">Representative data formats</h3>
+          <div className="grid-3" style={{ gap: 12 }}>
             <div className="guide-data-card">
               <div className="guide-data-title">Failure Record</div>
               <Code>{`{
   "id": "f_abc123",
   "sessionId": "session-001",
   "project": "myapp",
-  "userRequest": "Add a login page",
-  "agentAction": "Created login.tsx",
-  "correction": "Use the existing auth hook",
   "correctionType": "verbal",
   "skillsActive": ["react-patterns"],
   "resolved": false
 }`}</Code>
             </div>
             <div className="guide-data-card">
-              <div className="guide-data-title">Skill Test</div>
+              <div className="guide-data-title">Pressure Intervention</div>
               <Code>{`{
-  "id": "gc_react_42",
-  "skill": "react-patterns",
-  "input": "Create a form component",
-  "context": "React 19, TypeScript",
-  "expectedBehavior": "Uses useActionState for form submission...",
-  "lastResult": "pass",
-  "consecutivePasses": 5
+  "id": "pi_123",
+  "interventionType": "generalize",
+  "status": "completed",
+  "impact": "structural",
+  "projectId": "website-a",
+  "reasonSummary": "Recurring motif now promotes shared UI guidance"
 }`}</Code>
             </div>
+            <div className="guide-data-card">
+              <div className="guide-data-title">Topology Apply Plan</div>
+              <Code>{`{
+  "id": "topology_plan_abc",
+  "candidateId": "topology_rewire_xyz",
+  "executionMode": "apply",
+  "safeToApply": true,
+  "beforeSnapshotId": "topology_snapshot_001",
+  "plannedGraphChanges": [
+    "Suppress 1 conflict edge covered by the reviewed rewire decision"
+  ]
+}`}</Code>
+            </div>
+          </div>
+        </Section>
+
+        {/* ─── Maturity & Safety ─── */}
+        <Section id="maturity" title="Current Maturity & Safety" subtitle="What is real now, what is bounded, and what should not be overstated.">
+          <div className="grid-3" style={{ gap: 12 }}>
+            <div className="guide-dimension-card" style={{ borderLeftColor: 'var(--green)' }}>
+              <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--green)' }}>Operational now</div>
+              <ul className="guide-list" style={{ marginTop: 8 }}>
+                <li>pressure sensing and motifs</li>
+                <li>governed routing with operator-visible rationale</li>
+                <li>transfer evidence through generalized promotion</li>
+                <li>persisted governance steering</li>
+                <li>topology review queue + decisions</li>
+                <li>prepare / apply / rollback for the safe reviewed subset</li>
+              </ul>
+            </div>
+            <div className="guide-dimension-card" style={{ borderLeftColor: 'var(--yellow)' }}>
+              <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--yellow)' }}>Bounded by design</div>
+              <ul className="guide-list" style={{ marginTop: 8 }}>
+                <li>only accepted review candidates can enter apply planning</li>
+                <li>only safe plans are directly applied</li>
+                <li>snapshots and artifacts preserve execution truth</li>
+                <li>rollback restores before-apply state instead of guessing</li>
+              </ul>
+            </div>
+            <div className="guide-dimension-card" style={{ borderLeftColor: 'var(--purple)' }}>
+              <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--purple)' }}>Not yet claimed</div>
+              <ul className="guide-list" style={{ marginTop: 8 }}>
+                <li>full-spectrum autonomous destructive self-restructuring</li>
+                <li>broad automatic merge / split / prune application</li>
+                <li>fully operational dynamic ontology evolution</li>
+                <li>complete autonomous structural governance without operator oversight</li>
+              </ul>
+            </div>
           </div>
+          <Callout type="warning">
+            The most truthful way to describe the current product is: <strong>governed co-evolving brain with bounded safe structural execution</strong>.
+            That is stronger and more credible than implying unrestricted autonomous self-restructuring.
+          </Callout>
         </Section>
 
         {/* ─── Skill Management ─── */}
@@ -1019,15 +1239,58 @@ generation: 3
           </Callout>
         </Section>
 
+        {/* ─── Glossary ─── */}
+        <Section id="glossary" title="Glossary" subtitle="Short definitions for the new core terms in the current HelixEvo brain model.">
+          <div className="grid-2" style={{ gap: 12 }}>
+            {[
+              ['Ontology', 'The stable semantic kernel that defines what kinds of things HelixEvo can talk about and persist truthfully.'],
+              ['Activation trace', 'Observation memory describing which skills, gaps, and contexts were active when analysis happened.'],
+              ['Pressure signal', 'An explicit representation of adaptation demand derived from failures or project gaps.'],
+              ['Motif', 'A recurring family of pressure above the single-signal level. Motifs matter because network-level transfer should respond to patterns, not isolated anecdotes.'],
+              ['Intervention', 'A recorded response action such as research, specialize, evolve, generalize, or manual review.'],
+              ['Transfer event', 'Evidence that reusable knowledge was actually promoted or transferred across projects or layers.'],
+              ['Governance mode', 'The current routing posture — derived automatically or pinned manually by the operator.'],
+              ['Topology review', 'Persisted structural candidate memory plus explicit operator decision state.'],
+              ['Apply plan', 'A prepared reviewed topology change with a before snapshot, planned graph changes, and execution mode.'],
+              ['Snapshot', 'Saved structural state used to prove what changed and to support rollback.'],
+              ['Topology artifact', 'Evidence created around reviewed structural execution, similar to how evolution artifacts preserve proposal-level change evidence.'],
+              ['Rollback', 'Restoring the before-apply structural state for a previously applied safe topology plan.'],
+            ].map(([term, desc]) => (
+              <div key={String(term)} className="guide-dimension-card" style={{ borderLeftColor: 'var(--blue)' }}>
+                <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--blue)' }}>{term}</div>
+                <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 6, lineHeight: 1.6 }}>{desc}</div>
+              </div>
+            ))}
+          </div>
+        </Section>
+
         {/* ─── FAQ ─── */}
-        <Section id="faq" title="FAQ" subtitle="Frequently asked questions.">
-          <FAQItem q="How many failures do I need before evolution works?">
-            By default, 5 unresolved failures are required (<code>minFailuresForEvolution</code>).
-            This ensures enough signal for meaningful pattern detection.
+        <Section id="faq" title="FAQ" subtitle="Frequently asked questions for the current theory and operator model.">
+          <FAQItem q="What is governance steering?">
+            Governance steering lets the operator pin the current response posture instead of relying only on derived routing.
+            In practice, that means HelixEvo can stay <code>balanced</code>, become <code>transfer-focused</code>, shift toward <code>project-critical</code>, or stay more <code>conservative</code> depending on what the operator wants and what the system is seeing.
+          </FAQItem>
+          <FAQItem q="What is the difference between topology review and topology execution?">
+            <strong>Topology review</strong> is the memory and decision layer: candidates, reasons, risk, and accept/defer/reject state.
+            <strong>Topology execution</strong> starts only after acceptance and adds prepare/apply/rollback, snapshots, artifacts, and execution records.
           </FAQItem>
-          <FAQItem q="What LLM model does HelixEvo use?">
-            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 q="What does prepare vs apply vs rollback mean?">
+            <code>prepare</code> creates an explicit apply plan with a before snapshot and planned graph changes.
+            <code>apply</code> executes the safe reviewed subset against the effective graph state.
+            <code>rollback</code> restores the before-apply snapshot if the applied structural change should be reversed.
+          </FAQItem>
+          <FAQItem q="What is a motif and why does it matter?">
+            A motif is a recurring pattern of pressure across multiple signals or projects. It matters because network-level actions like <code>generalize</code> should respond to real recurring pressure families, not pretend that one local signal justifies system-wide promotion.
+          </FAQItem>
+          <FAQItem q="What is a transfer event?">
+            A transfer event is evidence that reusable knowledge was actually promoted or reused across layers or projects. This is how HelixEvo distinguishes a recommendation from a realized knowledge transfer.
+          </FAQItem>
+          <FAQItem q="How do I prove HelixEvo's brain is working?">
+            Use multiple proof surfaces together: <code>metrics</code> for correction reduction, Co-Evolution for routed interventions and transfer evidence, Topology for reviewed structural execution state, and the verification reports under <code>reports/verification/</code> for milestone-level backtesting.
+          </FAQItem>
+          <FAQItem q="How many failures do I need before evolution works?">
+            By default, 5 unresolved failures are required (<code>minFailuresForEvolution</code>) for the standard evolution trigger.
+            Always-on mode can also trigger earlier through burst or cross-project conditions.
           </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
@@ -1035,42 +1298,18 @@ generation: 3
             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.
-          </FAQItem>
-          <FAQItem q="What happens during canary rollback?">
-            If the failure rate for a canary skill exceeds <code>autoRollbackThreshold</code> (default: 1.5x),
-            the skill is automatically reverted from the backup. The failed evolution is recorded in history.
-          </FAQItem>
-          <FAQItem q="How does cross-skill regression work?">
-            When Skill A evolves, HelixEvo checks the skill graph for co-evolved, dependent, and enhancing
-            partners. It tests their skill tests against Skill A&apos;s changes. If partner pass rate drops below 95%,
-            the proposal is rejected.
-          </FAQItem>
-          <FAQItem q="How does the knowledge buffer work?">
-            All research discoveries are saved, even if the resulting hypothesis fails. Failed experiments above
-            a minimum score are saved as drafts. When the same hypothesis appears again, HelixEvo iterates on
-            the draft rather than starting from scratch.
-          </FAQItem>
-          <FAQItem q="How does helixevo watch detect corrections?">
-            Two-stage detection: (1) Fast regex pre-filter checks for correction signals in English and Chinese
-            (e.g., &quot;wrong&quot;, &quot;not like that&quot;, &quot;不对&quot;, &quot;改成&quot;). (2) If a signal is detected, an LLM analyzes
-            the recent conversation window to extract structured failure records with confidence scores (&gt;0.7 required).
+            Yes. HelixEvo manages standard SKILL.md files with YAML frontmatter. Any agent that reads SKILL.md files can benefit from HelixEvo&apos;s evolution, pressure, transfer, and topology workflows.
           </FAQItem>
-          <FAQItem q="How do I prove HelixEvo is working?">
-            Run <code>helixevo metrics</code>. It tracks correction rates per skill over 7-day rolling windows
-            and compares before/after rates for each evolution. The verdict shows how many evolutions actually
-            reduced corrections. This is closed-loop measurement — not LLM scores judging LLM output.
+          <FAQItem q="What happens during canary rollback versus topology rollback?">
+            Canary rollback restores a skill change that degraded live performance during monitored deployment.
+            Topology rollback restores the before-apply structural state for a reviewed topology plan. They protect different layers: one protects skill behavior, the other protects graph structure.
           </FAQItem>
           <FAQItem q="What is network health?">
-            Network health scores the entire skill network as a unit across 4 dimensions: cohesion (connectivity),
-            coverage (failure mapping), balance (hierarchy structure), and transfer rate (cross-project reuse).
-            It runs after every evolution and is shown in the summary. Run <code>helixevo health</code> to see the full report.
+            Network health scores the entire skill network as a unit across cohesion, coverage, balance, and transfer rate.
+            It remains one of the best structural diagnostics because it tells you whether the network is learning in a connected and reusable way rather than just accumulating local fixes.
           </FAQItem>
           <FAQItem q="When does auto-generalization trigger?">
-            Automatically during <code>helixevo evolve</code> when the network health assessment detects cross-project
-            patterns — the same failure type appearing in 2+ projects. It creates a domain-level abstract skill,
-            validates with regression tests, and sets up parent/child inheritance with the source project skills.
+            It triggers when recurring multi-project patterns become strong enough to justify promotion. The newer theory frame is that <code>generalize</code> responds to recurring motifs and should create transfer evidence rather than merely appearing active.
           </FAQItem>
         </Section>
 
@@ -1079,7 +1318,7 @@ generation: 3
           <div className="guide-footer-content">
             <div style={{ fontSize: 13, fontWeight: 600 }}>HelixEvo v{VERSION}</div>
             <div style={{ fontSize: 12, color: 'var(--text-dim)', marginTop: 4 }}>
-              Self-evolving skill ecosystem for AI agents · MIT License
+              Co-evolving brain for AI agents · MIT License
             </div>
           </div>
         </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helixevo",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Co-evolving skill and project brain for AI agents, with ontology-aware learning, governed response, rollbackable topology control, and a premium dashboard.",
   "type": "module",
   "bin": {