diff --git a/crates/fastskill-cli/src/commands/skillopt/export.rs b/crates/fastskill-cli/src/commands/skillopt/export.rs
index 852653d..1496e10 100644
--- a/crates/fastskill-cli/src/commands/skillopt/export.rs
+++ b/crates/fastskill-cli/src/commands/skillopt/export.rs
@@ -1,4 +1,4 @@
-//! `fastskill skillopt export` subcommand
+//! `fastskill optimize export` subcommand
 
 use crate::error::{CliError, CliResult};
 use cli_framework::command::{FromArgValueMap, IntoCommandSpec};
@@ -8,7 +8,7 @@ use cli_framework::spec::value::ArgValue;
 use std::collections::HashMap;
 use std::path::PathBuf;
 
-/// Arguments for `fastskill skillopt export`
+/// Arguments for `fastskill optimize export`
 #[derive(Debug)]
 pub struct ExportArgs {
     /// Path to the run directory
@@ -22,7 +22,7 @@ impl IntoCommandSpec for ExportArgs {
     fn command_spec() -> CommandSpec {
         CommandSpec {
             summary: "Export the best skill document from a completed run",
-            syntax: Some("skillopt export <run-dir> --out <path>"),
+            syntax: Some("optimize export <run-dir> --out <path>"),
             args: vec![
                 ArgSpec {
                     name: "run-dir",
@@ -66,7 +66,7 @@ impl FromArgValueMap for ExportArgs {
 pub async fn execute_export(args: ExportArgs) -> CliResult<()> {
     if !args.run_dir.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_MISSING: run directory not found: {}",
+            "OPTIMIZE_RUN_DIR_MISSING: run directory not found: {}",
             args.run_dir.display()
         )));
     }
@@ -74,7 +74,7 @@ pub async fn execute_export(args: ExportArgs) -> CliResult<()> {
     let best_skill_path = args.run_dir.join("best_skill.md");
     if !best_skill_path.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_EXPORT_BEST_MISSING: best_skill.md not found in run directory: {}",
+            "OPTIMIZE_EXPORT_BEST_MISSING: best_skill.md not found in run directory: {}",
             args.run_dir.display()
         )));
     }
diff --git a/crates/fastskill-cli/src/commands/skillopt/inspect.rs b/crates/fastskill-cli/src/commands/skillopt/inspect.rs
index b886a2f..399d9ea 100644
--- a/crates/fastskill-cli/src/commands/skillopt/inspect.rs
+++ b/crates/fastskill-cli/src/commands/skillopt/inspect.rs
@@ -1,4 +1,4 @@
-//! `fastskill skillopt inspect` subcommand
+//! `fastskill optimize inspect` subcommand
 
 use crate::error::{CliError, CliResult};
 use cli_framework::command::{FromArgValueMap, IntoCommandSpec};
@@ -8,7 +8,7 @@ use cli_framework::spec::value::ArgValue;
 use std::collections::HashMap;
 use std::path::PathBuf;
 
-/// Arguments for `fastskill skillopt inspect`
+/// Arguments for `fastskill optimize inspect`
 #[derive(Debug)]
 pub struct InspectArgs {
     /// Path to the run directory
@@ -34,7 +34,7 @@ impl IntoCommandSpec for InspectArgs {
     fn command_spec() -> CommandSpec {
         CommandSpec {
             summary: "Inspect per-step artifacts from a training run",
-            syntax: Some("skillopt inspect <run-dir> --step <n> [--show <mode>]"),
+            syntax: Some("optimize inspect <run-dir> --step <n> [--show <mode>]"),
             args: vec![
                 ArgSpec {
                     name: "run-dir",
@@ -100,7 +100,7 @@ impl FromArgValueMap for InspectArgs {
 pub async fn execute_inspect(args: InspectArgs) -> CliResult<()> {
     if !args.run_dir.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_MISSING: run directory not found: {}",
+            "OPTIMIZE_RUN_DIR_MISSING: run directory not found: {}",
             args.run_dir.display()
         )));
     }
@@ -108,7 +108,7 @@ pub async fn execute_inspect(args: InspectArgs) -> CliResult<()> {
     let step_dir = args.run_dir.join(format!("step-{}", args.step));
     if !step_dir.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_STEP_NOT_FOUND: no artifacts for step {} in: {}",
+            "OPTIMIZE_STEP_NOT_FOUND: no artifacts for step {} in: {}",
             args.step,
             args.run_dir.display()
         )));
diff --git a/crates/fastskill-cli/src/commands/skillopt/mod.rs b/crates/fastskill-cli/src/commands/skillopt/mod.rs
index 7eaa35b..0108cad 100644
--- a/crates/fastskill-cli/src/commands/skillopt/mod.rs
+++ b/crates/fastskill-cli/src/commands/skillopt/mod.rs
@@ -1,4 +1,4 @@
-//! SkillOpt command group — iterative skill-document optimization via text-gradient.
+//! Optimize command group — iterative skill-document optimization via text-gradient.
 //!
 //! All subcommands are registered individually via `AppBuilder::register::<T>()` in main.rs.
 //! The per-subcommand Args structs implement `IntoCommandSpec + FromArgValueMap` directly.
diff --git a/crates/fastskill-cli/src/commands/skillopt/resume.rs b/crates/fastskill-cli/src/commands/skillopt/resume.rs
index e060e6c..d5be9ca 100644
--- a/crates/fastskill-cli/src/commands/skillopt/resume.rs
+++ b/crates/fastskill-cli/src/commands/skillopt/resume.rs
@@ -1,4 +1,4 @@
-//! `fastskill skillopt resume` subcommand
+//! `fastskill optimize resume` subcommand
 
 use super::config::{build_run_config, load_suite_with_splits, validate_config, SkillOptToml};
 use crate::error::{CliError, CliResult};
@@ -9,7 +9,7 @@ use cli_framework::spec::value::ArgValue;
 use std::collections::HashMap;
 use std::path::PathBuf;
 
-/// Arguments for `fastskill skillopt resume`
+/// Arguments for `fastskill optimize resume`
 #[derive(Debug)]
 pub struct ResumeArgs {
     /// Path to the run directory to resume
@@ -20,7 +20,7 @@ impl IntoCommandSpec for ResumeArgs {
     fn command_spec() -> CommandSpec {
         CommandSpec {
             summary: "Resume an interrupted optimization run",
-            syntax: Some("skillopt resume <run-dir>"),
+            syntax: Some("optimize resume <run-dir>"),
             args: vec![ArgSpec {
                 name: "run-dir",
                 kind: ArgKind::Positional,
@@ -50,29 +50,34 @@ pub async fn execute_resume(args: ResumeArgs) -> CliResult<()> {
     // 1. Verify run dir exists
     if !args.run_dir.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_MISSING: run directory not found: {}",
+            "OPTIMIZE_RUN_DIR_MISSING: run directory not found: {}",
             args.run_dir.display()
         )));
     }
 
-    // 2. Read stored skillopt.toml from the run directory
-    let stored_config_path = args.run_dir.join("skillopt.toml");
+    // 2. Read stored config from the run directory; try optimize.toml first, then skillopt.toml
+    let stored_config_path = {
+        let new_path = args.run_dir.join("optimize.toml");
+        if new_path.exists() {
+            new_path
+        } else {
+            args.run_dir.join("skillopt.toml") // backward compat for pre-rename run dirs
+        }
+    };
     if !stored_config_path.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_CORRUPT: missing skillopt.toml in run directory: {}",
+            "OPTIMIZE_RUN_DIR_CORRUPT: missing optimize.toml in run directory: {}",
             args.run_dir.display()
         )));
     }
 
     let config_str = std::fs::read_to_string(&stored_config_path).map_err(|e| {
-        CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_CORRUPT: cannot read skillopt.toml: {e}"
-        ))
+        CliError::Config(format!("OPTIMIZE_RUN_DIR_CORRUPT: cannot read config: {e}"))
     })?;
 
     let cfg: SkillOptToml = toml::from_str(&config_str).map_err(|e| {
         CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_CORRUPT: invalid skillopt.toml: {e}"
+            "OPTIMIZE_RUN_DIR_CORRUPT: invalid config toml: {e}"
         ))
     })?;
 
@@ -87,7 +92,7 @@ pub async fn execute_resume(args: ResumeArgs) -> CliResult<()> {
     let checks = if let Some(ref checks_path) = cfg.checks {
         let checks_path = base_dir.join(checks_path);
         fastskill_evals::load_checks(&checks_path)
-            .map_err(|e| CliError::Config(format!("SKILLOPT_CHECKS_PARSE_ERROR: {e}")))?
+            .map_err(|e| CliError::Config(format!("OPTIMIZE_CHECKS_PARSE_ERROR: {e}")))?
     } else {
         vec![]
     };
@@ -97,7 +102,7 @@ pub async fn execute_resume(args: ResumeArgs) -> CliResult<()> {
         Some(a) => a,
         None => {
             eprintln!(
-                "SKILLOPT_OPTIMIZER_DEFAULT_WARN: optimizer_agent not set, defaulting to target_agent '{}'",
+                "OPTIMIZE_OPTIMIZER_DEFAULT_WARN: optimizer_agent not set, defaulting to target_agent '{}'",
                 cfg.target_agent
             );
             cfg.target_agent.clone()
@@ -107,11 +112,11 @@ pub async fn execute_resume(args: ResumeArgs) -> CliResult<()> {
     // 6. Read skill document
     let skill_path = base_dir.join(&cfg.skill);
     let initial_skill_md = std::fs::read_to_string(&skill_path)
-        .map_err(|e| CliError::Config(format!("SKILLOPT_SKILL_NOT_FOUND: {e}")))?;
+        .map_err(|e| CliError::Config(format!("OPTIMIZE_SKILL_NOT_FOUND: {e}")))?;
 
     // 7. Build RunConfig
     let run_config = build_run_config(&cfg, &optimizer_agent)
-        .map_err(|e| CliError::Config(format!("SKILLOPT_TRAINING_FAILED: invalid config: {e}")))?;
+        .map_err(|e| CliError::Config(format!("OPTIMIZE_TRAINING_FAILED: invalid config: {e}")))?;
 
     // 8. Resume training
     let outcome = aikit_skillopt::resume_skill(
@@ -123,7 +128,7 @@ pub async fn execute_resume(args: ResumeArgs) -> CliResult<()> {
         run_config,
     )
     .await
-    .map_err(|e| CliError::Config(format!("SKILLOPT_TRAINING_FAILED: {e}")))?;
+    .map_err(|e| CliError::Config(format!("OPTIMIZE_TRAINING_FAILED: {e}")))?;
 
     println!("{}", outcome.best_artifact_path.display());
     Ok(())
diff --git a/crates/fastskill-cli/src/commands/skillopt/run.rs b/crates/fastskill-cli/src/commands/skillopt/run.rs
index 9b8146a..618a99b 100644
--- a/crates/fastskill-cli/src/commands/skillopt/run.rs
+++ b/crates/fastskill-cli/src/commands/skillopt/run.rs
@@ -1,4 +1,4 @@
-//! `fastskill skillopt run` subcommand
+//! `fastskill optimize run` subcommand
 
 use super::config::{build_run_config, load_suite_with_splits, validate_config, SkillOptToml};
 use crate::error::{CliError, CliResult};
@@ -9,10 +9,10 @@ use cli_framework::spec::value::ArgValue;
 use std::collections::HashMap;
 use std::path::PathBuf;
 
-/// Arguments for `fastskill skillopt run`
+/// Arguments for `fastskill optimize run`
 #[derive(Debug)]
 pub struct RunArgs {
-    /// Path to skillopt.toml config file
+    /// Path to optimize config file
     pub config: PathBuf,
 
     /// Override the out_dir from the config file
@@ -26,7 +26,7 @@ impl IntoCommandSpec for RunArgs {
     fn command_spec() -> CommandSpec {
         CommandSpec {
             summary: "Run skill optimization from a config file",
-            syntax: Some("skillopt run --config <path> [--out-dir <dir>] [--resume <run-dir>]"),
+            syntax: Some("optimize run --config <path> [--out-dir <dir>] [--resume <run-dir>]"),
             args: vec![
                 ArgSpec {
                     name: "config",
@@ -34,7 +34,7 @@ impl IntoCommandSpec for RunArgs {
                     long: Some("config"),
                     value_type: ArgValueType::String,
                     cardinality: Cardinality::Required,
-                    help: "Path to skillopt.toml config file",
+                    help: "Path to optimize config file",
                     ..Default::default()
                 },
                 ArgSpec {
@@ -95,17 +95,17 @@ pub async fn execute_run(args: RunArgs) -> CliResult<()> {
     // 1. Read config file
     if !args.config.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_CONFIG_MISSING: config file not found: {}",
+            "OPTIMIZE_CONFIG_MISSING: config file not found: {}",
             args.config.display()
         )));
     }
 
     let config_str = std::fs::read_to_string(&args.config).map_err(|e| {
-        CliError::Config(format!("SKILLOPT_CONFIG_MISSING: cannot read config: {e}"))
+        CliError::Config(format!("OPTIMIZE_CONFIG_MISSING: cannot read config: {e}"))
     })?;
 
     let mut cfg: SkillOptToml = toml::from_str(&config_str)
-        .map_err(|e| CliError::Config(format!("SKILLOPT_INVALID_TOML: {e}")))?;
+        .map_err(|e| CliError::Config(format!("OPTIMIZE_INVALID_TOML: {e}")))?;
 
     if let Some(out_dir) = args.out_dir {
         cfg.out_dir = out_dir.to_string_lossy().to_string();
@@ -126,7 +126,7 @@ pub async fn execute_run(args: RunArgs) -> CliResult<()> {
 
     if selection_count == 0 {
         return Err(CliError::Config(
-            "SKILLOPT_NO_SELECTION_CASES: suite has zero cases tagged 'selection'".to_string(),
+            "OPTIMIZE_NO_SELECTION_CASES: suite has zero cases tagged 'selection'".to_string(),
         ));
     }
 
@@ -134,7 +134,7 @@ pub async fn execute_run(args: RunArgs) -> CliResult<()> {
     let checks = if let Some(ref checks_path) = cfg.checks {
         let checks_path = config_dir.join(checks_path);
         fastskill_evals::load_checks(&checks_path)
-            .map_err(|e| CliError::Config(format!("SKILLOPT_CHECKS_PARSE_ERROR: {e}")))?
+            .map_err(|e| CliError::Config(format!("OPTIMIZE_CHECKS_PARSE_ERROR: {e}")))?
     } else {
         vec![]
     };
@@ -144,7 +144,7 @@ pub async fn execute_run(args: RunArgs) -> CliResult<()> {
         Some(a) => a,
         None => {
             eprintln!(
-                "SKILLOPT_OPTIMIZER_DEFAULT_WARN: optimizer_agent not set, defaulting to target_agent '{}'",
+                "OPTIMIZE_OPTIMIZER_DEFAULT_WARN: optimizer_agent not set, defaulting to target_agent '{}'",
                 cfg.target_agent
             );
             cfg.target_agent.clone()
@@ -154,14 +154,14 @@ pub async fn execute_run(args: RunArgs) -> CliResult<()> {
     // 6. Read skill document
     let skill_path = config_dir.join(&cfg.skill);
     let initial_skill_md = std::fs::read_to_string(&skill_path).map_err(|e| {
-        CliError::Config(format!("SKILLOPT_SKILL_NOT_FOUND: cannot read skill: {e}"))
+        CliError::Config(format!("OPTIMIZE_SKILL_NOT_FOUND: cannot read skill: {e}"))
     })?;
 
     // 7. Allocate timestamped run directory
     let out_base = config_dir.join(&cfg.out_dir);
     std::fs::create_dir_all(&out_base).map_err(|e| {
         CliError::Config(format!(
-            "SKILLOPT_OUT_DIR_UNWRITABLE: cannot create out_dir: {e}"
+            "OPTIMIZE_OUT_DIR_UNWRITABLE: cannot create out_dir: {e}"
         ))
     })?;
 
@@ -169,16 +169,16 @@ pub async fn execute_run(args: RunArgs) -> CliResult<()> {
     let run_dir = out_base.join(&timestamp);
     std::fs::create_dir_all(&run_dir).map_err(|e| {
         CliError::Config(format!(
-            "SKILLOPT_OUT_DIR_UNWRITABLE: cannot create run dir: {e}"
+            "OPTIMIZE_OUT_DIR_UNWRITABLE: cannot create run dir: {e}"
         ))
     })?;
 
     // 8. Copy config for provenance (before calling train_skill)
-    std::fs::write(run_dir.join("skillopt.toml"), &config_str).map_err(CliError::Io)?;
+    std::fs::write(run_dir.join("optimize.toml"), &config_str).map_err(CliError::Io)?;
 
     // 9. Build RunConfig via serde_json (avoids direct GateMetric/SlowUpdateMode imports)
     let run_config = build_run_config(&cfg, &optimizer_agent)
-        .map_err(|e| CliError::Config(format!("SKILLOPT_TRAINING_FAILED: invalid config: {e}")))?;
+        .map_err(|e| CliError::Config(format!("OPTIMIZE_TRAINING_FAILED: invalid config: {e}")))?;
 
     // 10. Build inputs and invoke training loop
     let inputs = aikit_skillopt::SkillOptInputs {
@@ -192,7 +192,7 @@ pub async fn execute_run(args: RunArgs) -> CliResult<()> {
 
     let outcome = aikit_skillopt::train_skill(inputs)
         .await
-        .map_err(|e| CliError::Config(format!("SKILLOPT_TRAINING_FAILED: {e}")))?;
+        .map_err(|e| CliError::Config(format!("OPTIMIZE_TRAINING_FAILED: {e}")))?;
 
     println!("{}", outcome.best_artifact_path.display());
     Ok(())
diff --git a/crates/fastskill-cli/src/commands/skillopt/status.rs b/crates/fastskill-cli/src/commands/skillopt/status.rs
index df7c66a..86da838 100644
--- a/crates/fastskill-cli/src/commands/skillopt/status.rs
+++ b/crates/fastskill-cli/src/commands/skillopt/status.rs
@@ -1,4 +1,4 @@
-//! `fastskill skillopt status` subcommand
+//! `fastskill optimize status` subcommand
 
 use crate::error::{CliError, CliResult};
 use cli_framework::command::{FromArgValueMap, IntoCommandSpec};
@@ -9,7 +9,7 @@ use serde::Deserialize;
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 
-/// Arguments for `fastskill skillopt status`
+/// Arguments for `fastskill optimize status`
 #[derive(Debug)]
 pub struct StatusArgs {
     /// Path to the run directory
@@ -23,7 +23,7 @@ impl IntoCommandSpec for StatusArgs {
     fn command_spec() -> CommandSpec {
         CommandSpec {
             summary: "Show the status of a training run",
-            syntax: Some("skillopt status <run-dir> [--watch]"),
+            syntax: Some("optimize status <run-dir> [--watch]"),
             args: vec![
                 ArgSpec {
                     name: "run-dir",
@@ -81,7 +81,7 @@ struct StepRecordView {
 pub async fn execute_status(args: StatusArgs) -> CliResult<()> {
     if !args.run_dir.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_MISSING: run directory not found: {}",
+            "OPTIMIZE_RUN_DIR_MISSING: run directory not found: {}",
             args.run_dir.display()
         )));
     }
@@ -103,7 +103,7 @@ fn render_status(run_dir: &Path) -> CliResult<()> {
 
     if !state_path.exists() || !history_path.exists() {
         return Err(CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_CORRUPT: missing runtime_state.json or history.json in: {}",
+            "OPTIMIZE_RUN_DIR_CORRUPT: missing runtime_state.json or history.json in: {}",
             run_dir.display()
         )));
     }
@@ -111,7 +111,7 @@ fn render_status(run_dir: &Path) -> CliResult<()> {
     let state_bytes = std::fs::read(&state_path).map_err(CliError::Io)?;
     let state: RuntimeStateView = serde_json::from_slice(&state_bytes).map_err(|e| {
         CliError::Config(format!(
-            "SKILLOPT_RUN_DIR_CORRUPT: malformed runtime_state.json: {e}"
+            "OPTIMIZE_RUN_DIR_CORRUPT: malformed runtime_state.json: {e}"
         ))
     })?;
 
diff --git a/crates/fastskill-cli/src/main.rs b/crates/fastskill-cli/src/main.rs
index 517dccf..a77d61f 100644
--- a/crates/fastskill-cli/src/main.rs
+++ b/crates/fastskill-cli/src/main.rs
@@ -409,19 +409,19 @@ fn build_app(builder: AppBuilder, state: Arc<FsState>) -> anyhow::Result<AppBuil
             )?
     };
 
-    // ── skillopt: fully migrated to typed API (spec #89 reference migration) ──
+    // ── optimize: fully migrated to typed API ────────────────────────────────────
     let builder = {
         use cli_framework::spec::command_tree::GroupMetadata;
         builder
             .register_group(
-                &path!["skillopt"],
+                &path!["optimize"],
                 GroupMetadata {
                     summary: "Iterative skill-document optimization via text-gradient",
                     hidden: false,
                 },
             )?
             .register(
-                path!["skillopt", "run"],
+                path!["optimize", "run"],
                 |_ctx, args: skillopt::run::RunArgs| async move {
                     skillopt::run::execute_run(args)
                         .await
@@ -429,7 +429,7 @@ fn build_app(builder: AppBuilder, state: Arc<FsState>) -> anyhow::Result<AppBuil
                 },
             )?
             .register(
-                path!["skillopt", "resume"],
+                path!["optimize", "resume"],
                 |_ctx, args: skillopt::resume::ResumeArgs| async move {
                     skillopt::resume::execute_resume(args)
                         .await
@@ -437,7 +437,7 @@ fn build_app(builder: AppBuilder, state: Arc<FsState>) -> anyhow::Result<AppBuil
                 },
             )?
             .register(
-                path!["skillopt", "status"],
+                path!["optimize", "status"],
                 |_ctx, args: skillopt::status::StatusArgs| async move {
                     skillopt::status::execute_status(args)
                         .await
@@ -445,7 +445,7 @@ fn build_app(builder: AppBuilder, state: Arc<FsState>) -> anyhow::Result<AppBuil
                 },
             )?
             .register(
-                path!["skillopt", "inspect"],
+                path!["optimize", "inspect"],
                 |_ctx, args: skillopt::inspect::InspectArgs| async move {
                     skillopt::inspect::execute_inspect(args)
                         .await
@@ -453,7 +453,7 @@ fn build_app(builder: AppBuilder, state: Arc<FsState>) -> anyhow::Result<AppBuil
                 },
             )?
             .register(
-                path!["skillopt", "export"],
+                path!["optimize", "export"],
                 |_ctx, args: skillopt::export::ExportArgs| async move {
                     skillopt::export::execute_export(args)
                         .await
diff --git a/tests/cli/skillopt_tests.rs b/tests/cli/skillopt_tests.rs
index fef6bc0..0a4b43a 100644
--- a/tests/cli/skillopt_tests.rs
+++ b/tests/cli/skillopt_tests.rs
@@ -1,4 +1,4 @@
-//! CLI integration tests for skillopt commands
+//! CLI integration tests for optimize commands
 
 #![allow(clippy::all, clippy::unwrap_used, clippy::expect_used)]
 
@@ -12,17 +12,17 @@ use tempfile::TempDir;
 
 #[test]
 fn test_skillopt_help() {
-    let result = run_fastskill_command(&["skillopt", "--help"], None);
+    let result = run_fastskill_command(&["optimize", "--help"], None);
     assert!(result.success);
-    assert_snapshot_with_settings("skillopt_help", &result.stdout, &cli_snapshot_settings());
+    assert_snapshot_with_settings("optimize_help", &result.stdout, &cli_snapshot_settings());
 }
 
 #[test]
 fn test_skillopt_run_help() {
-    let result = run_fastskill_command(&["skillopt", "run", "--help"], None);
+    let result = run_fastskill_command(&["optimize", "run", "--help"], None);
     assert!(result.success);
     assert_snapshot_with_settings(
-        "skillopt_run_help",
+        "optimize_run_help",
         &result.stdout,
         &cli_snapshot_settings(),
     );
@@ -30,10 +30,10 @@ fn test_skillopt_run_help() {
 
 #[test]
 fn test_skillopt_resume_help() {
-    let result = run_fastskill_command(&["skillopt", "resume", "--help"], None);
+    let result = run_fastskill_command(&["optimize", "resume", "--help"], None);
     assert!(result.success);
     assert_snapshot_with_settings(
-        "skillopt_resume_help",
+        "optimize_resume_help",
         &result.stdout,
         &cli_snapshot_settings(),
     );
@@ -41,10 +41,10 @@ fn test_skillopt_resume_help() {
 
 #[test]
 fn test_skillopt_status_help() {
-    let result = run_fastskill_command(&["skillopt", "status", "--help"], None);
+    let result = run_fastskill_command(&["optimize", "status", "--help"], None);
     assert!(result.success);
     assert_snapshot_with_settings(
-        "skillopt_status_help",
+        "optimize_status_help",
         &result.stdout,
         &cli_snapshot_settings(),
     );
@@ -52,10 +52,10 @@ fn test_skillopt_status_help() {
 
 #[test]
 fn test_skillopt_inspect_help() {
-    let result = run_fastskill_command(&["skillopt", "inspect", "--help"], None);
+    let result = run_fastskill_command(&["optimize", "inspect", "--help"], None);
     assert!(result.success);
     assert_snapshot_with_settings(
-        "skillopt_inspect_help",
+        "optimize_inspect_help",
         &result.stdout,
         &cli_snapshot_settings(),
     );
@@ -63,10 +63,10 @@ fn test_skillopt_inspect_help() {
 
 #[test]
 fn test_skillopt_export_help() {
-    let result = run_fastskill_command(&["skillopt", "export", "--help"], None);
+    let result = run_fastskill_command(&["optimize", "export", "--help"], None);
     assert!(result.success);
     assert_snapshot_with_settings(
-        "skillopt_export_help",
+        "optimize_export_help",
         &result.stdout,
         &cli_snapshot_settings(),
     );
@@ -77,7 +77,7 @@ fn test_skillopt_export_help() {
 #[test]
 fn test_skillopt_run_config_missing() {
     let result = run_fastskill_command(
-        &["skillopt", "run", "--config", "/tmp/nonexistent-skillopt-config-xyz.toml"],
+        &["optimize", "run", "--config", "/tmp/nonexistent-skillopt-config-xyz.toml"],
         None,
     );
     assert!(!result.success);
@@ -95,7 +95,7 @@ fn test_skillopt_run_no_selection_cases() {
     let suite_csv = "id,prompt,should_trigger,tags\ntrain-1,hello,true,train\n";
     fs::write(base.join("suite.csv"), suite_csv).unwrap();
 
-    // Write a valid skillopt.toml
+    // Write a valid config
     let toml = r#"
 skill = "SKILL.md"
 skill_name = "test-skill"
@@ -121,7 +121,7 @@ timeout_seconds = 30
 
     let result = run_fastskill_command(
         &[
-            "skillopt",
+            "optimize",
             "run",
             "--config",
             config_path.to_str().unwrap(),
@@ -131,8 +131,8 @@ timeout_seconds = 30
     assert!(!result.success);
     let combined = format!("{}{}", result.stdout, result.stderr);
     assert!(
-        combined.contains("SKILLOPT_NO_SELECTION_CASES"),
-        "Expected SKILLOPT_NO_SELECTION_CASES in: {}",
+        combined.contains("OPTIMIZE_NO_SELECTION_CASES"),
+        "Expected OPTIMIZE_NO_SELECTION_CASES in: {}",
         combined
     );
 }
@@ -167,7 +167,7 @@ timeout_seconds = 30
 
     let result = run_fastskill_command(
         &[
-            "skillopt",
+            "optimize",
             "run",
             "--config",
             config_path.to_str().unwrap(),
@@ -212,7 +212,7 @@ timeout_seconds = 30
 
     let result = run_fastskill_command(
         &[
-            "skillopt",
+            "optimize",
             "run",
             "--config",
             config_path.to_str().unwrap(),
@@ -233,14 +233,14 @@ timeout_seconds = 30
 #[test]
 fn test_skillopt_resume_missing_run_dir() {
     let result = run_fastskill_command(
-        &["skillopt", "resume", "/tmp/nonexistent-skillopt-run-dir-xyz"],
+        &["optimize", "resume", "/tmp/nonexistent-skillopt-run-dir-xyz"],
         None,
     );
     assert!(!result.success);
     let combined = format!("{}{}", result.stdout, result.stderr);
     assert!(
-        combined.contains("SKILLOPT_RUN_DIR_MISSING"),
-        "Expected SKILLOPT_RUN_DIR_MISSING in: {}",
+        combined.contains("OPTIMIZE_RUN_DIR_MISSING"),
+        "Expected OPTIMIZE_RUN_DIR_MISSING in: {}",
         combined
     );
 }
@@ -251,7 +251,7 @@ fn test_skillopt_export_missing_best_skill() {
     // Run dir exists but has no best_skill.md
     let result = run_fastskill_command(
         &[
-            "skillopt",
+            "optimize",
             "export",
             dir.path().to_str().unwrap(),
             "--out",
@@ -262,8 +262,8 @@ fn test_skillopt_export_missing_best_skill() {
     assert!(!result.success);
     let combined = format!("{}{}", result.stdout, result.stderr);
     assert!(
-        combined.contains("SKILLOPT_EXPORT_BEST_MISSING"),
-        "Expected SKILLOPT_EXPORT_BEST_MISSING in: {}",
+        combined.contains("OPTIMIZE_EXPORT_BEST_MISSING"),
+        "Expected OPTIMIZE_EXPORT_BEST_MISSING in: {}",
         combined
     );
 }
@@ -281,7 +281,7 @@ fn test_skillopt_export_byte_identical() {
     let out_path = dir.path().join("exported_skill.md");
     let result = run_fastskill_command(
         &[
-            "skillopt",
+            "optimize",
             "export",
             dir.path().to_str().unwrap(),
             "--out",
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_export_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_export_help.snap
new file mode 100644
index 0000000..6fb889e
--- /dev/null
+++ b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_export_help.snap
@@ -0,0 +1,20 @@
+---
+source: tests/cli/snapshot_helpers.rs
+expression: normalized
+---
+Export the best skill document from a completed run
+
+Usage: fastskill optimize export [OPTIONS] --out <out> <run-dir>
+
+Arguments:
+  <run-dir>  Path to the run directory
+
+Options:
+      --out <out>                Destination path for the exported skill document
+      --skills-dir <skills-dir>  Override the skills directory path
+      --global                   Use global skills directory (~/.config/fastskill/skills)
+  -v, --verbose                  Enable verbose output
+  -h, --help                     Print help
+  -V, --version                  Print version
+
+Syntax: optimize export <run-dir> --out <path>
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_help.snap
new file mode 100644
index 0000000..bdc7605
--- /dev/null
+++ b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_help.snap
@@ -0,0 +1,22 @@
+---
+source: tests/cli/snapshot_helpers.rs
+expression: normalized
+---
+Iterative skill-document optimization via text-gradient
+
+Usage: fastskill optimize [OPTIONS] <COMMAND>
+
+Commands:
+  export   Export the best skill document from a completed run
+  inspect  Inspect per-step artifacts from a training run
+  resume   Resume an interrupted optimization run
+  run      Run skill optimization from a config file
+  status   Show the status of a training run
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+      --skills-dir <skills-dir>  Override the skills directory path
+      --global                   Use global skills directory (~/.config/fastskill/skills)
+  -v, --verbose                  Enable verbose output
+  -h, --help                     Print help
+  -V, --version                  Print version
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_inspect_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_inspect_help.snap
new file mode 100644
index 0000000..2977c86
--- /dev/null
+++ b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_inspect_help.snap
@@ -0,0 +1,21 @@
+---
+source: tests/cli/snapshot_helpers.rs
+expression: normalized
+---
+Inspect per-step artifacts from a training run
+
+Usage: fastskill optimize inspect [OPTIONS] --step <step> <run-dir>
+
+Arguments:
+  <run-dir>  Path to the run directory
+
+Options:
+      --skills-dir <skills-dir>  Override the skills directory path
+      --step <step>              Step number to inspect
+      --global                   Use global skills directory (~/.config/fastskill/skills)
+      --show <show>              What to show: patches, diffs, gate, skips, or all [possible: patches|diffs|gate|skips|all] [default: all]
+  -v, --verbose                  Enable verbose output
+  -h, --help                     Print help
+  -V, --version                  Print version
+
+Syntax: optimize inspect <run-dir> --step <n> [--show <mode>]
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_resume_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_resume_help.snap
new file mode 100644
index 0000000..ba48266
--- /dev/null
+++ b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_resume_help.snap
@@ -0,0 +1,19 @@
+---
+source: tests/cli/snapshot_helpers.rs
+expression: normalized
+---
+Resume an interrupted optimization run
+
+Usage: fastskill optimize resume [OPTIONS] <run-dir>
+
+Arguments:
+  <run-dir>  Path to the run directory to resume
+
+Options:
+      --skills-dir <skills-dir>  Override the skills directory path
+      --global                   Use global skills directory (~/.config/fastskill/skills)
+  -v, --verbose                  Enable verbose output
+  -h, --help                     Print help
+  -V, --version                  Print version
+
+Syntax: optimize resume <run-dir>
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_run_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_run_help.snap
new file mode 100644
index 0000000..97d6eea
--- /dev/null
+++ b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_run_help.snap
@@ -0,0 +1,19 @@
+---
+source: tests/cli/snapshot_helpers.rs
+expression: normalized
+---
+Run skill optimization from a config file
+
+Usage: fastskill optimize run [OPTIONS] --config <config>
+
+Options:
+      --config <config>          Path to optimize config file
+      --skills-dir <skills-dir>  Override the skills directory path
+      --global                   Use global skills directory (~/.config/fastskill/skills)
+      --out-dir <out-dir>        Override the out_dir from the config file
+      --resume <resume>          Resume from this run directory instead of starting fresh
+  -v, --verbose                  Enable verbose output
+  -h, --help                     Print help
+  -V, --version                  Print version
+
+Syntax: optimize run --config <path> [--out-dir <dir>] [--resume <run-dir>]
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_status_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_status_help.snap
new file mode 100644
index 0000000..cd899ca
--- /dev/null
+++ b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__optimize_status_help.snap
@@ -0,0 +1,20 @@
+---
+source: tests/cli/snapshot_helpers.rs
+expression: normalized
+---
+Show the status of a training run
+
+Usage: fastskill optimize status [OPTIONS] <run-dir>
+
+Arguments:
+  <run-dir>  Path to the run directory
+
+Options:
+      --skills-dir <skills-dir>  Override the skills directory path
+      --watch                    Poll and re-render every ~2 seconds
+      --global                   Use global skills directory (~/.config/fastskill/skills)
+  -v, --verbose                  Enable verbose output
+  -h, --help                     Print help
+  -V, --version                  Print version
+
+Syntax: optimize status <run-dir> [--watch]
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_export_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_export_help.snap
deleted file mode 100644
index 36eaa08..0000000
--- a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_export_help.snap
+++ /dev/null
@@ -1,13 +0,0 @@
----
-source: tests/cli/snapshot_helpers.rs
-expression: normalized
----
-Command help (legacy)
-
-Usage: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill skillopt [-- <args>]
-
-Summary: Iterative skill-document optimization via text-gradient
-
-Syntax: skillopt <run|resume|status|inspect|export>
-
-For the full command list, run: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill --help
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_help.snap
deleted file mode 100644
index a48c311..0000000
--- a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_help.snap
+++ /dev/null
@@ -1,16 +0,0 @@
----
-source: tests/cli/snapshot_helpers.rs
-expression: normalized
----
-Iterative skill-document optimization via text-gradient
-
-Usage: fastskill skillopt [trailing]...
-
-Arguments:
-  [trailing]...
-
-Options:
-  -h, --help     Print help
-  -V, --version  Print version
-
-Syntax: skillopt <run|resume|status|inspect|export>
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_inspect_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_inspect_help.snap
deleted file mode 100644
index 36eaa08..0000000
--- a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_inspect_help.snap
+++ /dev/null
@@ -1,13 +0,0 @@
----
-source: tests/cli/snapshot_helpers.rs
-expression: normalized
----
-Command help (legacy)
-
-Usage: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill skillopt [-- <args>]
-
-Summary: Iterative skill-document optimization via text-gradient
-
-Syntax: skillopt <run|resume|status|inspect|export>
-
-For the full command list, run: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill --help
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_resume_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_resume_help.snap
deleted file mode 100644
index 36eaa08..0000000
--- a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_resume_help.snap
+++ /dev/null
@@ -1,13 +0,0 @@
----
-source: tests/cli/snapshot_helpers.rs
-expression: normalized
----
-Command help (legacy)
-
-Usage: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill skillopt [-- <args>]
-
-Summary: Iterative skill-document optimization via text-gradient
-
-Syntax: skillopt <run|resume|status|inspect|export>
-
-For the full command list, run: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill --help
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_run_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_run_help.snap
deleted file mode 100644
index 36eaa08..0000000
--- a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_run_help.snap
+++ /dev/null
@@ -1,13 +0,0 @@
----
-source: tests/cli/snapshot_helpers.rs
-expression: normalized
----
-Command help (legacy)
-
-Usage: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill skillopt [-- <args>]
-
-Summary: Iterative skill-document optimization via text-gradient
-
-Syntax: skillopt <run|resume|status|inspect|export>
-
-For the full command list, run: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill --help
diff --git a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_status_help.snap b/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_status_help.snap
deleted file mode 100644
index 36eaa08..0000000
--- a/tests/cli/snapshots/cli_tests__cli__snapshot_helpers__skillopt_status_help.snap
+++ /dev/null
@@ -1,13 +0,0 @@
----
-source: tests/cli/snapshot_helpers.rs
-expression: normalized
----
-Command help (legacy)
-
-Usage: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill skillopt [-- <args>]
-
-Summary: Iterative skill-document optimization via text-gradient
-
-Syntax: skillopt <run|resume|status|inspect|export>
-
-For the full command list, run: [HOME_DIR]/ws001/gofastskill/fastskill/target/debug/fastskill --help