helixevo 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to HelixEvo are documented here.
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-03-24
+
+### Added
+- Shared dashboard operator-flow helpers for loop-stage breadcrumbs, contextual surface handoffs, curated release spotlight content, and guide deep-link integration
+
+### Changed
+- Overview, Projects, Research, Co-Evolution, Ontology, and Topology now expose clearer operator breadcrumbs, adjacent control links, and stronger next-step empty-state onboarding
+- Overview release spotlight is now curated through a dedicated helper so post-release guidance stays easy to update and does not silently drift stale
+
+## [0.6.0] - 2026-03-24
+
+### Added
+- Derived ontology adoption bindings for pressure signals, pressure motifs, route rationale, transfer events, and topology review candidates
+- Ontology adoption summaries showing active concepts, binding coverage, semantically influenced routes, and deprecation-sensitive concepts
+- Workflow-shaped dashboard navigation that now groups the product into Operate, Structure, and Reference surfaces
+- New Guide semantic-control section and operator playbooks for frontier refresh, concept promotion, semantic adoption inspection, and careful deprecation
+- New Commands operator recipes for project onboarding, pressure response, ontology adoption, and topology review/apply loops
+
+### Changed
+- `helixevo ontology --status --verbose` now surfaces semantic adoption, active concept usage, unused extensions, and deprecation-risk visibility
+- Overview, Co-Evolution, Ontology, and Topology now show where approved ontology concepts are actively shaping the live control loop
+- The Ontology dashboard surface now reads as a semantic-control cockpit instead of only frontier control
+- Strategy/master-plan docs are being refreshed so the roadmap shifts from governed ontology emergence toward governed ontology adoption and semantic control
+
 ## [0.5.0] - 2026-03-24
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # HelixEvo
 
-Co-evolving skill and project brain for AI agents. HelixEvo captures failures, traces activations, models pressure, routes governed responses, promotes cross-project transfer, reviews structural topology changes, safely executes accepted topology transitions with rollback, 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, routes governed responses, promotes cross-project transfer, reviews structural topology changes, safely executes accepted topology transitions with rollback, and now lets approved ontology concepts become active semantic consumers inside the live control loop.
 
 ## How it works
 
@@ -89,7 +89,7 @@ helixevo dashboard
 | `helixevo generalize` | Promote cross-project patterns ↑ |
 | `helixevo specialize --project <name>` | Create project-specific skills ↓ |
 | `helixevo graph` | View skill network in terminal |
-| `helixevo ontology` | Refresh, review, and govern ontology frontier concepts |
+| `helixevo ontology` | Refresh, review, adopt, and inspect ontology concepts plus semantic control coverage |
 | `helixevo topology` | Prepare, apply, roll back, and inspect reviewed topology execution |
 | `helixevo research` | Proactive web research for skill improvement |
 | `helixevo dashboard [--port <n>]` | Open web dashboard, preferring localhost:3847 and falling forward if occupied |
@@ -110,7 +110,9 @@ helixevo graph --mermaid          # Open in browser as Mermaid diagram
 helixevo graph --obsidian ~/vault # Sync to Obsidian vault
 helixevo graph --rebuild          # Re-infer relationships (LLM call)
 helixevo graph --optimize         # Detect structural candidates + refresh topology review queue
-helixevo ontology --status        # Show ontology kernel / frontier / extension state
+helixevo ontology --status        # Show ontology kernel / frontier / extension / adoption state
+helixevo ontology --status --verbose
+                                   # Show top active concepts, unused extensions, and deprecation-sensitive concepts
 helixevo ontology --refresh       # Derive frontier concepts from recurring evidence
 helixevo ontology --review <id> --decision promote
                                    # Promote a reviewed frontier concept into approved extensions
@@ -182,10 +184,10 @@ helixevo dashboard --port 3900
 ```
 
 **Tabs:**
-- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, pressure counts, ontology frontier visibility, topology review visibility, and prepared/applied structural state
+- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, ontology adoption visibility, pressure counts, topology review visibility, and prepared/applied structural state
 - **Skill Network** — Interactive graph, premium inspector, co-evolution routing signals, and topology review/execution handoff links
-- **Co-Evolution** — Operator cockpit for routed pressure response, governance mode visibility, promotion queues, transfer evidence, and topology handoff
-- **Ontology** — Semantic control surface for kernel visibility, frontier concept review, approved ontology extensions, and native ontology change events
+- **Co-Evolution** — Operator cockpit for routed pressure response, governance mode visibility, promotion queues, transfer evidence, semantic route influence, and topology handoff
+- **Ontology** — Semantic control surface for kernel visibility, frontier concept review, approved ontology extensions, adoption coverage, deprecation risk, and native ontology change events
 - **Topology** — Governance steering plus a persistent operator pipeline for review → prepare → apply → rollback across merge / split / promote / rewire / consolidate candidates
 - **Projects** — Project intake studio, live project analysis, gap routing, per-project pressure hotspots, and promotion feeders
 - **Evolution** — Timeline of evolution runs with judge scores, artifact provenance, and activation-aware context
@@ -224,7 +226,8 @@ Failures → Cluster → Propose → Replay → Multi-Judge → Regression → C
 
 **Brain foundation:**
 - **Ontology** defines the stable semantic kernel for skills, projects, tasks, capabilities, artifacts, and mutations.
-- **Ontology frontier and extensions** let new semantic concepts emerge as provisional hypotheses, pass explicit review, and become approved extensions without free-form drift.
+- **Ontology frontier and extensions** let new semantic concepts emerge as provisional hypotheses, pass explicit review, become approved extensions, and then appear as active semantic consumers in pressure, routing, transfer, and structural interpretation without free-form drift.
+- **Semantic adoption visibility** shows which approved concepts are unused, active, deprecation-sensitive, or currently influencing live route rationale.
 - **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.
 - **Pressure interventions** record how HelixEvo responded across research, specialize, evolve, generalize, and manual-review lanes.

package/dashboard/app/coevolution/client.tsx

@@ -6,6 +6,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'
 
 type RunState = 'idle' | 'running' | 'success' | 'error' | 'stopped'
 type CommandName = 'evolve' | 'research' | 'generalize'
@@ -72,7 +75,10 @@ type Summary = {
       governanceMode: Summary['governance']['activeMode']
       triggeredBy: string
       reasons: string[]
+      semanticInfluence?: 'none' | 'explanatory' | 'weighted'
+      semanticConceptIds?: string[]
     }
+    semanticConceptIds?: string[]
   }[]
   promoteQueue: {
     id: string
@@ -94,11 +100,14 @@ type Summary = {
       governanceMode: Summary['governance']['activeMode']
       triggeredBy: string
       reasons: string[]
+      semanticInfluence?: 'none' | 'explanatory' | 'weighted'
+      semanticConceptIds?: string[]
     }
+    semanticConceptIds?: string[]
   }[]
   recentAddressed: { id: string; kind: string; projectId?: string; capability?: string; description?: string; addressedAt?: string; responseSummary: string; interventionTypes: PressureInterventionType[] }[]
   recentInterventions: { id: string; interventionType: PressureInterventionType; status: 'started' | 'completed' | 'failed' | 'dry-run'; impact: 'exploratory' | 'structural' | 'resolving' | 'none'; projectId?: string; capabilities?: string[]; reasonSummary: string; completedAt?: string; createdAt: string }[]
-  recentTransfers: { id: string; timestamp: string; transferType: 'specialist-to-generalist' | 'generalist-to-project' | 'cross-project' | 'domain-transfer'; targetSkillIds?: string[]; capabilityIds?: string[]; motifIds?: string[]; status?: 'candidate' | 'realized' | 'rejected'; summary?: string }[]
+  recentTransfers: { id: string; timestamp: string; transferType: 'specialist-to-generalist' | 'generalist-to-project' | 'cross-project' | 'domain-transfer'; targetSkillIds?: string[]; capabilityIds?: string[]; motifIds?: string[]; status?: 'candidate' | 'realized' | 'rejected'; summary?: string; semanticConceptIds?: string[] }[]
 }
 
 interface Props {
@@ -109,6 +118,13 @@ interface Props {
       reviewOpen: number
       extensions: number
       changeEvents: number
+      adoption: {
+        activeConcepts: number
+        unusedExtensions: number
+        totalBindings: number
+        routesInfluenced: number
+        conceptsAtDeprecationRisk: number
+      }
     }
   }
 }
@@ -255,6 +271,7 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
           { label: `${summary.pressureMotifs.promotionReady} promotion-ready motifs`, tone: summary.pressureMotifs.promotionReady > 0 ? 'purple' : 'neutral' },
           { label: `${summary.topologyReviews.open} topology reviews`, tone: summary.topologyReviews.open > 0 ? 'yellow' : 'green' },
           { label: `${ontology.ontologyLoop.frontier} ontology frontier`, tone: ontology.ontologyLoop.reviewOpen > 0 ? 'blue' : 'neutral' },
+          { label: `${ontology.ontologyLoop.adoption.activeConcepts} active concepts`, tone: ontology.ontologyLoop.adoption.activeConcepts > 0 ? 'green' : 'neutral' },
           { label: `${summary.recentTransfers.length} recent transfers`, tone: summary.recentTransfers.length > 0 ? 'green' : 'neutral' },
           { label: formatMode(summary.governance.activeMode), tone: toneForMode(summary.governance.activeMode) },
         ]}
@@ -269,22 +286,26 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
                 <span className="badge badge-gray">review threshold {(summary.governance.profile.reviewThreshold * 100).toFixed(0)}%</span>
               </div>
             </div>
-            <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', justifyContent: 'flex-end' }}>
-              <button onClick={() => handleRun('research')} disabled={runState === 'running'} className="badge badge-blue" style={{ border: 'none', cursor: 'pointer' }}>Run research</button>
-              <button onClick={() => handleRun('evolve')} disabled={runState === 'running'} className="badge badge-green" style={{ border: 'none', cursor: 'pointer' }}>Run evolve</button>
-              <button onClick={() => handleRun('generalize')} disabled={runState === 'running'} className="badge badge-purple" style={{ border: 'none', cursor: 'pointer' }}>Run generalize</button>
-              <Link href="/ontology" className="badge badge-gray">Open ontology</Link>
-              <Link href="/topology" className="badge badge-gray">Open topology</Link>
+            <div style={{ display: 'grid', gap: 10 }}>
+              <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', justifyContent: 'flex-end' }}>
+                <button onClick={() => handleRun('research')} disabled={runState === 'running'} className="badge badge-blue" style={{ border: 'none', cursor: 'pointer' }}>Run research</button>
+                <button onClick={() => handleRun('evolve')} disabled={runState === 'running'} className="badge badge-green" style={{ border: 'none', cursor: 'pointer' }}>Run evolve</button>
+                <button onClick={() => handleRun('generalize')} disabled={runState === 'running'} className="badge badge-purple" style={{ border: 'none', cursor: 'pointer' }}>Run generalize</button>
+              </div>
+              <SurfaceJumpLinks surface="coevolution" variant="compact" title="Response handoffs" />
             </div>
           </div>
         }
       />
 
+      <OperatorLoopTrail surface="coevolution" />
+
       <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: 16 }}>
         <MetricCard label="Open pressure" value={summary.pressureLifecycle.open} sublabel={`${summary.pressureLifecycle.highPriorityOpen} high-priority waiting for response`} tone={summary.pressureLifecycle.open > 0 ? 'yellow' : 'green'} icon="!" />
         <MetricCard label="Promotion-ready motifs" value={summary.pressureMotifs.promotionReady} sublabel={`${summary.pressureMotifs.total} recurring motifs tracked`} tone="purple" icon="⇄" />
         <MetricCard label="Topology reviews" value={summary.topologyReviews.open} sublabel={`${summary.topologyReviews.accepted} accepted • ${summary.topologyReviews.deferred} deferred`} tone={summary.topologyReviews.open > 0 ? 'yellow' : 'green'} icon="◇" />
         <MetricCard label="Prepared topology" value={summary.topologyExecution.prepared} sublabel={`${summary.topologyExecution.applied} applied • ${summary.topologyExecution.rolledBack} rolled back`} tone={summary.topologyExecution.prepared > 0 ? 'blue' : summary.topologyExecution.applied > 0 ? 'green' : 'neutral'} icon="↑" />
+        <MetricCard label="Active semantics" value={ontology.ontologyLoop.adoption.activeConcepts} sublabel={`${ontology.ontologyLoop.adoption.totalBindings} bindings • ${ontology.ontologyLoop.adoption.routesInfluenced} influenced routes`} tone={ontology.ontologyLoop.adoption.activeConcepts > 0 ? 'green' : 'neutral'} icon="◎" />
         <MetricCard label="Recorded interventions" value={summary.pressureInterventions.total} sublabel={`${summary.pressureInterventions.completed} completed • ${summary.pressureInterventions.dryRun} dry-run`} tone="blue" icon="↺" />
         <MetricCard label="Realized transfers" value={summary.recentTransfers.filter((event) => event.status === 'realized').length} sublabel={`${summary.pressureMotifs.addressed} motifs now addressed`} tone="green" icon="↑" />
       </div>
@@ -376,6 +397,8 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
                     <span className={`badge badge-${toneForLifecycle(motif.lifecycle)}`}>{motif.lifecycle}</span>
                     <span className="badge badge-purple">recommend {motif.suggestedRoute.route}</span>
                     <span className="badge badge-gray">confidence {(motif.suggestedRoute.confidence * 100).toFixed(0)}%</span>
+                    {motif.suggestedRoute.semanticInfluence && motif.suggestedRoute.semanticInfluence !== 'none' ? <span className="badge badge-green">semantic {motif.suggestedRoute.semanticInfluence}</span> : null}
+                    {(motif.semanticConceptIds ?? []).slice(0, 2).map((conceptId) => <span key={`${motif.id}-${conceptId}`} className="badge badge-gray">{conceptId}</span>)}
                     {motif.projectIds.slice(0, 3).map((projectId) => <span key={`${motif.id}-${projectId}`} className="badge badge-gray">{projectId}</span>)}
                   </div>
                   <div style={{ display: 'grid', gap: 4, marginTop: 10 }}>
@@ -386,10 +409,13 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
                 </div>
               </div>
             )) : (
-              <div className="empty-state" style={{ padding: 24 }}>
-                <div className="empty-state-title">No promotion-ready motifs yet</div>
-                <div className="empty-state-desc">Recurring cross-project demand will appear here once the same pressure region repeats often enough to justify generalization.</div>
-              </div>
+              <NextStepEmptyState
+                title="No promotion-ready motifs yet"
+                description="Recurring cross-project demand will appear here once the same pressure region repeats often enough to justify generalization instead of one-off local response."
+                command="helixevo project-setup <path>"
+                pageLink={{ label: 'Open Projects', href: '/projects', tone: 'blue' }}
+                guideLink={{ label: 'Guide · Adaptation Loop', anchor: 'loop', tone: 'purple' }}
+              />
             )}
           </div>
         </SectionFrame>
@@ -413,10 +439,13 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
               <div className="metric-card-sublabel">{lane.resolving} resolving • {lane.exploratory} exploratory • {lane.none} non-resolving</div>
             </div>
           )) : (
-            <div className="empty-state" style={{ gridColumn: '1 / -1', padding: 24 }}>
-              <div className="empty-state-title">No intervention records yet</div>
-              <div className="empty-state-desc">Run research, evolve, or generalize to start populating the governed response ledger.</div>
-            </div>
+            <NextStepEmptyState
+              title="No intervention records yet"
+              description="The governed response ledger will start populating once pressure is routed into live research, evolve, or generalize work."
+              command="helixevo evolve"
+              pageLink={{ label: 'Open Research', href: '/research', tone: 'blue' }}
+              guideLink={{ label: 'Guide · Surface Map', anchor: 'surfaces', tone: 'purple' }}
+            />
           )}
         </div>
       </SectionFrame>
@@ -455,10 +484,13 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
                 </div>
               </div>
             )) : (
-              <div className="empty-state" style={{ padding: 24 }}>
-                <div className="empty-state-title">No project response hotspots yet</div>
-                <div className="empty-state-desc">Project-linked pressure will appear here once failures and project analysis produce current demand.</div>
-              </div>
+              <NextStepEmptyState
+                title="No project response hotspots yet"
+                description="Project-linked pressure will appear here once failures and project analysis produce current demand for the response loop to act on."
+                command="helixevo project-setup <path>"
+                pageLink={{ label: 'Open Projects', href: '/projects', tone: 'blue' }}
+                guideLink={{ label: 'Guide · Quick Start', anchor: 'quickstart', tone: 'purple' }}
+              />
             )}
           </div>
         </SectionFrame>
@@ -477,16 +509,20 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
                   <div className="summary-row-meta">{event.transferType} • {formatDate(event.timestamp)}</div>
                   <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginTop: 8 }}>
                     <span className={`badge badge-${event.status === 'realized' ? 'green' : event.status === 'candidate' ? 'purple' : 'gray'}`}>{event.status ?? 'candidate'}</span>
+                    {(event.semanticConceptIds ?? []).slice(0, 2).map((conceptId) => <span key={`${event.id}-${conceptId}`} className="badge badge-green">{conceptId}</span>)}
                     {(event.targetSkillIds ?? []).slice(0, 2).map((skill) => <span key={`${event.id}-${skill}`} className="badge badge-gray">{skill}</span>)}
                     {(event.capabilityIds ?? []).slice(0, 2).map((capability) => <span key={`${event.id}-${capability}`} className="badge badge-gray">{capability}</span>)}
                   </div>
                 </div>
               </div>
             )) : (
-              <div className="empty-state" style={{ padding: 24 }}>
-                <div className="empty-state-title">No transfer evidence yet</div>
-                <div className="empty-state-desc">Once recurring pressure is promoted into reusable generalized skill knowledge, realized transfer evidence will appear here.</div>
-              </div>
+              <NextStepEmptyState
+                title="No transfer evidence yet"
+                description="Transfer evidence appears after recurring pressure is promoted into reusable generalized knowledge rather than staying trapped in local fixes."
+                command="helixevo generalize"
+                pageLink={{ label: 'Open Ontology', href: '/ontology', tone: 'green' }}
+                guideLink={{ label: 'Guide · Semantic Control', anchor: 'semanticcontrol', tone: 'purple' }}
+              />
             )}
           </div>
         </SectionFrame>
@@ -510,6 +546,8 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
                     {signal.projectId ? <span className="badge badge-gray">{signal.projectId}</span> : null}
                     {signal.routeRecommendation ? <span className={`badge badge-${toneForRoute(signal.routeRecommendation.route)}`}>recommend {signal.routeRecommendation.route}</span> : null}
                     {signal.routeRecommendation ? <span className="badge badge-gray">{signal.routeRecommendation.scope}</span> : null}
+                    {signal.routeRecommendation?.semanticInfluence && signal.routeRecommendation.semanticInfluence !== 'none' ? <span className="badge badge-green">semantic {signal.routeRecommendation.semanticInfluence}</span> : null}
+                    {(signal.semanticConceptIds ?? []).slice(0, 2).map((conceptId) => <span key={`${signal.id}-${conceptId}`} className="badge badge-gray">{conceptId}</span>)}
                     {signal.interventionTypes.map((type) => <span key={`${signal.id}-${type}`} className="badge badge-gray">{type}</span>)}
                   </div>
                   {signal.routeRecommendation?.reasons?.length ? (
@@ -528,10 +566,13 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
               </div>
             </div>
           )) : (
-            <div className="empty-state" style={{ padding: 24 }}>
-              <div className="empty-state-title">No open pressure backlog</div>
-              <div className="empty-state-desc">Once pressure enters the system, open and in-progress items will be queued here with governed routing recommendations.</div>
-            </div>
+            <NextStepEmptyState
+              title="No open pressure backlog"
+              description="Open and in-progress pressure will queue here once HelixEvo is observing real demand from projects, failures, or recurring motifs."
+              command="helixevo watch --project <name>"
+              pageLink={{ label: 'Open Projects', href: '/projects', tone: 'blue' }}
+              guideLink={{ label: 'Guide · Adaptation Loop', anchor: 'loop', tone: 'purple' }}
+            />
           )}
         </div>
       </SectionFrame>
@@ -558,10 +599,13 @@ export default function CoEvolutionClient({ summary, ontology }: Props) {
               </div>
             </div>
           )) : (
-            <div className="empty-state" style={{ padding: 24 }}>
-              <div className="empty-state-title">No response records yet</div>
-              <div className="empty-state-desc">Command-level intervention records will appear here once the response loop starts operating.</div>
-            </div>
+            <NextStepEmptyState
+              title="No response records yet"
+              description="Command-level intervention records will appear here once the response loop starts operating across research, evolve, generalize, or manual review."
+              command="helixevo research"
+              pageLink={{ label: 'Open Ontology', href: '/ontology', tone: 'green' }}
+              guideLink={{ label: 'Guide · Surface Map', anchor: 'surfaces', tone: 'purple' }}
+            />
           )}
         </div>
       </SectionFrame>

package/dashboard/app/commands/page.tsx

@@ -133,26 +133,27 @@ const COMMANDS: CommandInfo[] = [
   },
   {
     name: 'ontology',
-    description: 'Govern the ontology frontier explicitly. Refresh provisional concepts from recurring evidence, review them with promote/reject/defer decisions, and deprecate approved extensions without allowing free-form semantic drift.',
+    description: 'Govern the ontology frontier explicitly and inspect semantic adoption. Refresh provisional concepts from recurring evidence, review them with promote/reject/defer decisions, and see which approved concepts are actively shaping pressure, routing, transfer, and topology interpretation.',
     usage: 'helixevo ontology [options]',
     examples: [
-      { cmd: 'helixevo ontology --status', desc: 'Show kernel, frontier, extension, and change-log counts' },
+      { cmd: 'helixevo ontology --status', desc: 'Show kernel, frontier, extension, adoption, and change-log counts' },
+      { cmd: 'helixevo ontology --status --verbose', desc: 'Show top active concepts, unused extensions, and deprecation-sensitive concepts' },
       { cmd: 'helixevo ontology --refresh', desc: 'Derive frontier concepts from recurring capability, pressure, and topology evidence' },
       { cmd: 'helixevo ontology --review ontology_capability_ui --decision promote', desc: 'Promote a frontier concept into approved ontology extensions' },
-      { cmd: 'helixevo ontology --deprecate ontology_capability_ui', desc: 'Deprecate an approved ontology extension' },
+      { cmd: 'helixevo ontology --deprecate ontology_capability_ui', desc: 'Deprecate an approved ontology extension with consumer-risk visibility' },
     ],
     options: [
-      { flag: '--status', desc: 'Show ontology kernel, frontier, extension, and review state' },
+      { flag: '--status', desc: 'Show ontology kernel, frontier, extension, adoption, and review state' },
       { flag: '--refresh', desc: 'Refresh frontier concepts from recurring evidence' },
       { flag: '--review <conceptId>', desc: 'Review a frontier concept' },
       { flag: '--decision <promote|reject|defer>', desc: 'Decision for --review' },
       { flag: '--rationale <text>', desc: 'Optional review or deprecate rationale' },
       { flag: '--deprecate <conceptId>', desc: 'Deprecate an approved ontology extension' },
-      { flag: '--verbose', desc: 'Show detailed frontier concepts, extensions, and change events' },
+      { flag: '--verbose', desc: 'Show detailed frontier concepts, active semantic consumers, and ontology changes' },
     ],
     category: 'network',
     needsLLM: false,
-    note: 'Milestone 8 keeps ontology growth governed: concepts begin in the frontier, require explicit review, and only then become approved extensions.',
+    note: 'Milestone 9 keeps ontology growth governed while also showing semantic adoption: concepts begin in the frontier, become approved extensions through review, and then become visible as live consumers inside the control loop.',
   },
   {
     name: 'topology',
@@ -315,6 +316,33 @@ const WORKFLOW = [
   { label: 'health', desc: 'Assess quality', tone: 'blue' as const },
 ]
 
+const WORKFLOW_RECIPES = [
+  {
+    title: 'New project onboarding',
+    tone: 'blue' as const,
+    summary: 'Stand up project context, detect capability gaps, and create the first routed pressure picture.',
+    steps: ['helixevo project-setup <path>', 'helixevo research --project <path>', 'helixevo specialize --project <name>'],
+  },
+  {
+    title: 'Pressure-response loop',
+    tone: 'purple' as const,
+    summary: 'Capture real demand, let governance route the response, then apply the right lane.',
+    steps: ['helixevo watch --project <name>', 'helixevo evolve', 'helixevo generalize'],
+  },
+  {
+    title: 'Ontology adoption loop',
+    tone: 'green' as const,
+    summary: 'Move from recurring evidence to approved concepts and inspect live semantic adoption.',
+    steps: ['helixevo ontology --refresh', 'helixevo ontology --review <conceptId> --decision promote', 'helixevo ontology --status --verbose'],
+  },
+  {
+    title: 'Topology review / apply loop',
+    tone: 'yellow' as const,
+    summary: 'Refresh structural review candidates, prepare accepted safe plans, apply them, and keep rollback available.',
+    steps: ['helixevo graph --optimize', 'helixevo topology --prepare <candidateId>', 'helixevo topology --apply <planId>'],
+  },
+]
+
 const CATEGORIES: Array<{
   id: CommandInfo['category']
   label: string
@@ -323,7 +351,7 @@ const CATEGORIES: Array<{
 }> = [
   { id: 'core', label: 'Core workflow', tone: 'purple', description: 'The commands that initialize HelixEvo and keep it learning continuously.' },
   { id: 'evolution', label: 'Evolution', tone: 'green', description: 'Mutation, promotion, and specialization controls for active skill improvement.' },
-  { id: 'network', label: 'Network & research', tone: 'blue', description: 'Graph maintenance, discovery, and relationship mapping across the skill ecosystem.' },
+  { id: 'network', label: 'Structure, ontology & research', tone: 'blue', description: 'Graph maintenance, semantic control, structural review, and discovery across the skill ecosystem.' },
   { id: 'analysis', label: 'Analysis & reports', tone: 'yellow', description: 'Operational reads on system quality, trends, reports, and health.' },
   { id: 'system', label: 'System', tone: 'neutral', description: 'Supporting commands for capture, dashboard access, and environment-level actions.' },
 ]
@@ -361,8 +389,8 @@ export default function CommandsPage() {
         actions={
           <div className="hero-note-card">
             <div className="hero-note-label">Recommended operating loop</div>
-            <div className="hero-note-title">Init → Watch → Evolve → Generalize → Graph → Health</div>
-            <div className="hero-note-copy">Use the Commands page as the practical bridge between HelixEvo’s CLI and the premium dashboard cockpit.</div>
+            <div className="hero-note-title">Project Setup → Watch → Co-Evolution → Ontology → Topology</div>
+            <div className="hero-note-copy">Use the Commands page as the practical bridge between HelixEvo’s CLI, semantic control loop, and the premium dashboard cockpit.</div>
           </div>
         }
       />
@@ -402,6 +430,32 @@ export default function CommandsPage() {
         </div>
       </SectionFrame>
 
+      <SectionFrame
+        eyebrow="Operator recipes"
+        title="Fast command loops for the live product"
+        description="These compact sequences make the M9 dashboard and CLI feel like one coordinated operating surface instead of separate references."
+        tone="blue"
+      >
+        <div className="grid-2" style={{ gap: 14 }}>
+          {WORKFLOW_RECIPES.map((recipe) => (
+            <div key={recipe.title} className="card" style={{ padding: '18px 18px 16px' }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap', marginBottom: 8 }}>
+                <span className={`hero-chip hero-chip-${recipe.tone}`}>{recipe.title}</span>
+              </div>
+              <div style={{ fontSize: 12.5, color: 'var(--text-dim)', lineHeight: 1.65, marginBottom: 12 }}>{recipe.summary}</div>
+              <div style={{ display: 'grid', gap: 8 }}>
+                {recipe.steps.map((step, index) => (
+                  <div key={step} style={{ padding: '10px 12px', borderRadius: 14, background: 'rgba(255,255,255,0.72)', border: '1px solid var(--border)' }}>
+                    <div style={{ fontSize: 10.5, fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: 0.9, marginBottom: 4 }}>Step {index + 1}</div>
+                    <code style={{ fontFamily: 'var(--font-mono)', fontSize: 11.5, color: 'var(--text)' }}>$ {step}</code>
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+      </SectionFrame>
+
       {CATEGORIES.map(category => {
         const commands = COMMANDS.filter(command => command.category === category.id)
         if (commands.length === 0) return null

package/dashboard/app/guide/page.tsx

@@ -11,6 +11,7 @@ const TOC = [
   { id: 'architecture', label: 'Architecture', icon: '◎' },
   { id: 'brainstack', label: 'Brain Stack', icon: '◈' },
   { id: 'loop', label: 'Adaptation Loop', icon: '↺' },
+  { id: 'semanticcontrol', label: 'Semantic Control', icon: '◉' },
   { id: 'surfaces', label: 'Surface Map', icon: '▦' },
   { id: 'watch', label: 'Always-On Learning', icon: '⚡' },
   { id: 'evolution', label: 'Evolution Pipeline', icon: '⟳' },
@@ -246,6 +247,7 @@ export default function GuidePage() {
           <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="#brainstack" className="hero-chip hero-chip-green" style={{ textDecoration: 'none' }}>Brain Stack</a>
+            <a href="#semanticcontrol" className="hero-chip hero-chip-blue" style={{ textDecoration: 'none' }}>Semantic Control</a>
             <a href="#surfaces" className="hero-chip hero-chip-purple" style={{ textDecoration: 'none' }}>Surface Map</a>
           </div>
         </div>
@@ -277,6 +279,7 @@ export default function GuidePage() {
             <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">operator path + theory path</span>
+            <span className="hero-chip hero-chip-blue">semantic control reference</span>
             <span className="hero-chip hero-chip-yellow">governed plasticity reference</span>
           </div>
 
@@ -296,6 +299,7 @@ export default function GuidePage() {
               <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="#brainstack" className="hero-chip hero-chip-purple" style={{ textDecoration: 'none' }}>Brain Stack</a>
+                <a href="#semanticcontrol" className="hero-chip hero-chip-blue" style={{ textDecoration: 'none' }}>Semantic Control</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>
@@ -469,7 +473,7 @@ helixevo topology --status`}</Code>
               },
               {
                 cmd: 'helixevo ontology',
-                desc: 'Govern the ontology frontier explicitly. Refresh concept hypotheses from recurring evidence, review them with promote/reject/defer decisions, and deprecate approved extensions without allowing free-form semantic drift.',
+                desc: 'Govern the ontology frontier explicitly and inspect semantic adoption. Refresh concept hypotheses from recurring evidence, review them with promote/reject/defer decisions, and see which approved concepts are actively shaping pressure, routing, transfer, and topology interpretation.',
                 flags: ['--status', '--refresh', '--review <conceptId>', '--decision <promote|reject|defer>', '--rationale <text>', '--deprecate <conceptId>', '--verbose'],
               },
               {
@@ -536,7 +540,7 @@ helixevo topology --status`}</Code>
           <h3 className="guide-h3">Brain foundation</h3>
           <div className="grid-2" style={{ gap: 12, marginBottom: 20 }}>
             {[
-              ['Ontology', 'var(--blue)', 'Stable semantic kernel for skills, projects, tasks, capabilities, artifacts, and mutations.'],
+              ['Ontology', 'var(--blue)', 'Stable semantic kernel plus approved extensions that can now become active semantic consumers in pressure, routing, transfer, and topology interpretation.'],
               ['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.'],
@@ -570,8 +574,8 @@ helixevo topology --status`}</Code>
               {
                 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.'
+                desc: 'Ontology and invariants define what kinds of things HelixEvo can talk about and persist truthfully, and approved extensions can now feed back into live interpretation rather than remaining passive review outcomes.',
+                where: 'Visible in: ontology-aware graph summaries, semantic adoption counts, route rationale, and brain foundation summaries.'
               },
               {
                 title: '2. Observation layer',
@@ -666,14 +670,69 @@ helixevo topology --status`}</Code>
           </Callout>
         </Section>
 
+
+        {/* ─── Semantic Control ─── */}
+        <Section id="semanticcontrol" title="Ontology Adoption + Semantic Control" subtitle="Milestone 8 made ontology reviewable; Milestone 9 made approved concepts behaviorally meaningful inside the live control loop.">
+          <p className="guide-text">
+            The key post-M9 change is that approved ontology extensions are no longer just semantic ledger entries. They can now bind into
+            recurring pressure, motifs, route rationale, transfer interpretation, and topology review context while still remaining subordinate
+            to governance and evidence.
+          </p>
+          <p className="guide-text">
+            A concise way to think about the ontology lifecycle now is: <strong>frontier hypothesis → review decision → approved extension → active semantic consumer → optional deprecation</strong>.
+            Promotion is what turns reviewed semantics into live semantic control. Deprecation is what safely withdraws that influence when the concept is no longer trustworthy or useful.
+          </p>
+          <div className="grid-2" style={{ gap: 12, marginBottom: 18 }}>
+            {[
+              ['Emergence', 'var(--blue)', 'Recurring evidence creates frontier concepts, but frontier creation alone does not yet imply live semantic adoption.'],
+              ['Adoption', 'var(--green)', 'Promoted concepts begin appearing as active semantic consumers across signals, motifs, and route rationale.'],
+              ['Bounded influence', 'var(--yellow)', 'Ontology can sharpen explanation and confidence inside the existing governance envelope; it does not bypass safety or invent arbitrary routes.'],
+              ['Withdrawal', 'var(--purple)', 'Deprecation remains explicit and operator-visible, with consumer warnings before semantic influence is retired.'],
+            ].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">Operator playbooks</h3>
+          <div className="grid-3" style={{ gap: 12, marginBottom: 18 }}>
+            <div className="card" style={{ padding: '16px 16px 14px' }}>
+              <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--blue)', marginBottom: 8 }}>Recurring pressure → adoption</div>
+              <Code title="Terminal">{`helixevo ontology --refresh
+helixevo ontology --review <conceptId> --decision promote
+helixevo ontology --status --verbose`}</Code>
+              <div style={{ fontSize: 12, color: 'var(--text-dim)', lineHeight: 1.6 }}>Use this when recurring pressure or motif evidence looks stable enough to deserve an approved semantic family.</div>
+            </div>
+            <div className="card" style={{ padding: '16px 16px 14px' }}>
+              <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--green)', marginBottom: 8 }}>Check live semantic consumers</div>
+              <div style={{ fontSize: 12, color: 'var(--text-dim)', lineHeight: 1.6, marginBottom: 10 }}>Compare these surfaces together:</div>
+              <ul className="guide-list" style={{ marginBottom: 0 }}>
+                <li><strong>/ontology</strong> for adoption counts, unused extensions, and deprecation-sensitive concepts</li>
+                <li><strong>/coevolution</strong> for semantically influenced routes and backlog rationale</li>
+                <li><strong>/topology</strong> when structural review candidates start clustering around the same semantic family</li>
+              </ul>
+            </div>
+            <div className="card" style={{ padding: '16px 16px 14px' }}>
+              <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--yellow)', marginBottom: 8 }}>Deprecate carefully</div>
+              <Code title="Terminal">{`helixevo ontology --status --verbose
+helixevo ontology --deprecate <conceptId>`}</Code>
+              <div style={{ fontSize: 12, color: 'var(--text-dim)', lineHeight: 1.6 }}>Always inspect active semantic consumers first. A deprecation warning means the concept is still shaping the live control loop and should be retired intentionally.</div>
+            </div>
+          </div>
+          <Callout type="info">
+            The safest mental model is: <strong>M8 governs semantic emergence, M9 governs semantic adoption</strong>. Together they create a semantic loop where concepts can emerge, be reviewed, influence live cognition, and then be retired without silent drift.
+          </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.'],
+              ['Co-Evolution', 'var(--purple)', 'The response cockpit. Use it to inspect routed pressure, governance mode, promotion queue, transfer evidence, and where approved ontology concepts are influencing live route rationale.'],
               ['Skill Network', 'var(--green)', 'Graph-level understanding: relationships, co-evolution signals, inspector context, and structural handoff links.'],
-              ['Ontology', 'var(--blue)', 'Semantic control surface for kernel visibility, frontier review, approved extensions, and ontology change events.'],
+              ['Ontology', 'var(--blue)', 'Semantic control surface for kernel visibility, frontier review, approved extensions, semantic adoption coverage, consumer summaries, and ontology change events.'],
               ['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.'],
@@ -687,8 +746,8 @@ helixevo topology --status`}</Code>
             ))}
           </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.
+            If you are debugging current state, the best sequence is usually: <strong>Overview → Co-Evolution → Ontology → Topology → Skill Network → Projects / Research</strong>.
+            That path mirrors the stack from summary → routed demand → semantic interpretation → structural review/execution → graph context → project or discovery detail.
           </Callout>
         </Section>
 
@@ -1103,7 +1162,7 @@ generation: 3
             {[
               ['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.'],
-              ['Ontology frontier memory', 'var(--blue)', 'ontology/kernel.json + ontology/frontier.json + ontology/extensions.json + ontology/reviews.jsonl + ontology/change-log.jsonl preserve semantic kernel state, provisional concepts, approved extensions, and review/change lineage.'],
+              ['Ontology frontier memory', 'var(--blue)', 'ontology/kernel.json + ontology/frontier.json + ontology/extensions.json + ontology/reviews.jsonl + ontology/change-log.jsonl preserve semantic kernel state, provisional concepts, approved extensions, and review/change lineage while semantic adoption is derived from active runtime/control objects rather than a parallel ontology-usage ledger.'],
               ['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.'],