helixevo 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to HelixEvo are documented here.
 
 ## [Unreleased]
 
+## [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
+- New `helixevo ontology` command for ontology frontier status, refresh, review, and deprecation control
+- New `~/.helix/ontology/` persistence model with kernel snapshot, frontier concepts, approved extensions, review decisions, and native ontology change events
+- New `/ontology` dashboard route and `/api/ontology` operator control surface for governed semantic review
+
+### Changed
+- Overview semantic-backbone summaries now expose hybrid native + derived ontology state instead of only compatibility-era framing
+- Dashboard Guide, Commands, and README now document ontology frontier control alongside co-evolution and topology control
+
 ## [0.4.1] - 2026-03-24
 
 ### Changed

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,6 +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, 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 |
@@ -109,6 +110,12 @@ 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 / 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
 helixevo topology --status        # Show reviewed topology execution state
 helixevo topology --prepare <id>  # Prepare an accepted topology candidate
 helixevo topology --apply <id>    # Apply a safe prepared topology plan
@@ -144,7 +151,13 @@ All data is stored in `~/.helix/`:
 ├── topology-apply-plans.json # Prepared reviewed topology plans
 ├── topology-executions.jsonl # Prepared/applied/rolled-back execution ledger
 ├── topology-artifacts.jsonl  # Evidence artifacts for reviewed structural execution
-├── evolution-artifacts.jsonl # Evolution evidence artifacts per proposal/iteration
+├── evolution-artifacts.jsonl # Evolution + ontology-review evidence artifacts
+├── ontology/
+│   ├── kernel.json          # Materialized ontology kernel snapshot
+│   ├── extensions.json      # Approved ontology extensions
+│   ├── frontier.json        # Provisional frontier concepts awaiting review
+│   ├── reviews.jsonl        # Ontology review decisions
+│   └── change-log.jsonl     # Native ontology change events
 ├── frontier.json            # Pareto frontier (top-k configurations)
 ├── evolution-history.json   # All evolution runs + proposals
 ├── skill-tests.jsonl       # Regression test cases
@@ -171,9 +184,10 @@ helixevo dashboard --port 3900
 ```
 
 **Tabs:**
-- **Overview** — Premium control cockpit with frontier signals, brain foundation, semantic backbone, pressure counts, 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
+- **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
@@ -212,6 +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, 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/api/ontology/route.ts

@@ -0,0 +1,89 @@
+import { NextResponse } from 'next/server'
+import { spawn } from 'child_process'
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { loadOntologyControlSummary } from '@/lib/data'
+
+export const dynamic = 'force-dynamic'
+
+function resolveOntologyRunner(): { cmd: string; argsPrefix: string[] } {
+  const candidates = [
+    join(process.cwd(), '..', 'dist', 'cli.js'),
+    join(process.cwd(), 'dist', 'cli.js'),
+  ]
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return { cmd: process.execPath, argsPrefix: [candidate] }
+  }
+
+  return { cmd: 'helixevo', argsPrefix: [] }
+}
+
+function runOntologyCommand(args: string[]): Promise<{ success: boolean; output: string }> {
+  return new Promise((resolve) => {
+    const runner = resolveOntologyRunner()
+    const child = spawn(runner.cmd, [...runner.argsPrefix, 'ontology', ...args], {
+      env: { ...process.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    let output = ''
+    child.stdout?.on('data', (chunk: Buffer) => {
+      output += chunk.toString()
+    })
+    child.stderr?.on('data', (chunk: Buffer) => {
+      output += chunk.toString()
+    })
+    child.on('close', (code) => {
+      resolve({ success: code === 0, output })
+    })
+    child.on('error', (err) => {
+      resolve({ success: false, output: `Error: ${err.message}` })
+    })
+  })
+}
+
+export async function GET() {
+  return NextResponse.json(loadOntologyControlSummary())
+}
+
+export async function POST(request: Request) {
+  const body = await request.json() as {
+    action?: 'refresh' | 'review' | 'deprecate'
+    conceptId?: string
+    decision?: 'promote' | 'reject' | 'defer'
+    rationale?: string
+  }
+
+  if (!body.action) {
+    return NextResponse.json({ success: false, error: 'action is required' }, { status: 400 })
+  }
+
+  let args: string[] = []
+  if (body.action === 'refresh') {
+    args = ['--refresh']
+  } else if (body.action === 'review') {
+    if (!body.conceptId || !body.decision) {
+      return NextResponse.json({ success: false, error: 'conceptId and decision are required for review' }, { status: 400 })
+    }
+    args = ['--review', body.conceptId, '--decision', body.decision]
+    if (body.rationale?.trim()) args.push('--rationale', body.rationale.trim())
+  } else if (body.action === 'deprecate') {
+    if (!body.conceptId) {
+      return NextResponse.json({ success: false, error: 'conceptId is required for deprecate' }, { status: 400 })
+    }
+    args = ['--deprecate', body.conceptId]
+    if (body.rationale?.trim()) args.push('--rationale', body.rationale.trim())
+  }
+
+  const result = await runOntologyCommand(args)
+  if (!result.success) {
+    return NextResponse.json({ success: false, error: result.output || 'Ontology command failed' }, { status: 500 })
+  }
+
+  return NextResponse.json({
+    success: true,
+    output: result.output,
+    dashboard: loadOntologyControlSummary(),
+  })
+}

package/dashboard/app/coevolution/client.tsx

@@ -72,7 +72,10 @@ type Summary = {
       governanceMode: Summary['governance']['activeMode']
       triggeredBy: string
       reasons: string[]
+      semanticInfluence?: 'none' | 'explanatory' | 'weighted'
+      semanticConceptIds?: string[]
     }
+    semanticConceptIds?: string[]
   }[]
   promoteQueue: {
     id: string
@@ -94,15 +97,33 @@ 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 {
   summary: Summary
+  ontology: {
+    ontologyLoop: {
+      frontier: number
+      reviewOpen: number
+      extensions: number
+      changeEvents: number
+      adoption: {
+        activeConcepts: number
+        unusedExtensions: number
+        totalBindings: number
+        routesInfluenced: number
+        conceptsAtDeprecationRisk: number
+      }
+    }
+  }
 }
 
 function consoleTone(state: RunState): 'neutral' | 'green' | 'red' | 'yellow' {
@@ -145,7 +166,7 @@ function formatMode(mode: Summary['governance']['activeMode']) {
   return mode.split('-').join(' ')
 }
 
-export default function CoEvolutionClient({ summary }: Props) {
+export default function CoEvolutionClient({ summary, ontology }: Props) {
   const [runState, setRunState] = useState<RunState>('idle')
   const [activeCommand, setActiveCommand] = useState<CommandName | null>(null)
   const [output, setOutput] = useState('')
@@ -246,6 +267,8 @@ export default function CoEvolutionClient({ summary }: Props) {
           { label: `${summary.pressureLifecycle.open} open`, tone: summary.pressureLifecycle.open > 0 ? 'yellow' : 'green' },
           { 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) },
         ]}
@@ -264,6 +287,7 @@ export default function CoEvolutionClient({ summary }: Props) {
               <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>
           </div>
@@ -275,6 +299,7 @@ export default function CoEvolutionClient({ summary }: Props) {
         <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>
@@ -366,6 +391,8 @@ export default function CoEvolutionClient({ summary }: 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 }}>
@@ -467,6 +494,7 @@ export default function CoEvolutionClient({ summary }: 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>
@@ -500,6 +528,8 @@ export default function CoEvolutionClient({ summary }: 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 ? (

package/dashboard/app/coevolution/page.tsx

@@ -1,9 +1,10 @@
-import { loadCoEvolutionSummary } from '@/lib/data'
+import { loadCoEvolutionSummary, loadOntologySummary } from '@/lib/data'
 import CoEvolutionClient from './client'
 
 export const dynamic = 'force-dynamic'
 
 export default function CoEvolutionPage() {
   const summary = loadCoEvolutionSummary()
-  return <CoEvolutionClient summary={summary} />
+  const ontology = loadOntologySummary()
+  return <CoEvolutionClient summary={summary} ontology={ontology} />
 }

package/dashboard/app/commands/page.tsx

@@ -131,6 +131,30 @@ const COMMANDS: CommandInfo[] = [
     needsLLM: true,
     runnable: { command: 'graph-rebuild', label: 'Rebuild Graph', icon: 'M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1', color: 'var(--purple)' },
   },
+  {
+    name: 'ontology',
+    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, 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 with consumer-risk visibility' },
+    ],
+    options: [
+      { 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, active semantic consumers, and ontology changes' },
+    ],
+    category: 'network',
+    needsLLM: false,
+    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',
     description: 'Move reviewed topology candidates through an explicit structural execution pipeline. Prepare accepted candidates, apply only the safe subset, inspect snapshots and artifacts, and roll back applied structural overrides when needed.',
@@ -292,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
@@ -300,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.' },
 ]
@@ -338,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>
         }
       />
@@ -379,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>
@@ -467,6 +471,11 @@ helixevo topology --status`}</Code>
                 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 ontology',
+                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'],
+              },
               {
                 cmd: 'helixevo topology',
                 desc: 'Move accepted topology review through prepare, apply, and rollback. This is the explicit control surface for reviewed structural execution.',
@@ -531,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.'],
@@ -565,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',
@@ -661,13 +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, 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.'],
@@ -681,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>
 
@@ -1080,6 +1145,12 @@ generation: 3
 ├── skill-graph.json         # Cached network (nodes + edges + ontology version)
 ├── canary-registry.json     # Active canary deployments
 ├── knowledge-buffer.json    # Research discoveries + drafts
+├── ontology/
+│   ├── kernel.json          # Materialized ontology kernel snapshot
+│   ├── extensions.json      # Approved ontology extensions
+│   ├── frontier.json        # Provisional frontier concepts awaiting review
+│   ├── reviews.jsonl        # Ontology review decisions
+│   └── change-log.jsonl     # Native ontology change events
 ├── general/                 # Skills (SKILL.md files)
 │   ├── my-skill/SKILL.md
 │   └── ...
@@ -1091,6 +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 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.'],
@@ -1171,7 +1243,8 @@ generation: 3
               <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>broad automatic semantic remapping across historical data</li>
+                <li>full kernel mutation or free-form ontology drift</li>
                 <li>complete autonomous structural governance without operator oversight</li>
               </ul>
             </div>