diff --git a/codex-rs/cli/src/main.rs b/codex-rs/cli/src/main.rs
index 337be81e5d..d7c7cd288b 100644
--- a/codex-rs/cli/src/main.rs
+++ b/codex-rs/cli/src/main.rs
@@ -459,8 +459,8 @@ enum FeaturesSubcommand {
 fn stage_str(stage: codex_core::features::Stage) -> &'static str {
     use codex_core::features::Stage;
     match stage {
-        Stage::Experimental => "experimental",
-        Stage::Beta { .. } => "beta",
+        Stage::Beta => "experimental",
+        Stage::Experimental { .. } => "beta",
         Stage::Stable => "stable",
         Stage::Deprecated => "deprecated",
         Stage::Removed => "removed",
diff --git a/codex-rs/core/src/features.rs b/codex-rs/core/src/features.rs
index 66f6a08602..3e95c566bd 100644
--- a/codex-rs/core/src/features.rs
+++ b/codex-rs/core/src/features.rs
@@ -21,28 +21,33 @@ pub(crate) use legacy::legacy_feature_keys;
 /// High-level lifecycle stage for a feature.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Stage {
-    Experimental,
-    Beta {
+    /// Closed beta features to be used while developing or within the company.
+    Beta,
+    /// Experimental features made available to users through the `/experimental` menu
+    Experimental {
         name: &'static str,
         menu_description: &'static str,
         announcement: &'static str,
     },
+    /// Stable features. The feature flag is kept for ad-hoc enabling/disabling
     Stable,
+    /// Deprecated feature that should not be used anymore.
     Deprecated,
+    /// The feature flag is useless but kept for backward compatibility reason.
     Removed,
 }
 
 impl Stage {
     pub fn beta_menu_name(self) -> Option<&'static str> {
         match self {
-            Stage::Beta { name, .. } => Some(name),
+            Stage::Experimental { name, .. } => Some(name),
             _ => None,
         }
     }
 
     pub fn beta_menu_description(self) -> Option<&'static str> {
         match self {
-            Stage::Beta {
+            Stage::Experimental {
                 menu_description, ..
             } => Some(menu_description),
             _ => None,
@@ -51,7 +56,7 @@ impl Stage {
 
     pub fn beta_announcement(self) -> Option<&'static str> {
         match self {
-            Stage::Beta { announcement, .. } => Some(announcement),
+            Stage::Experimental { announcement, .. } => Some(announcement),
             _ => None,
         }
     }
@@ -336,14 +341,14 @@ pub const FEATURES: &[FeatureSpec] = &[
     FeatureSpec {
         id: Feature::WebSearchCached,
         key: "web_search_cached",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     // Beta program. Rendered in the `/experimental` menu for users.
     FeatureSpec {
         id: Feature::UnifiedExec,
         key: "unified_exec",
-        stage: Stage::Beta {
+        stage: Stage::Experimental {
             name: "Background terminal",
             menu_description: "Run long-running terminal commands in the background.",
             announcement: "NEW! Try Background terminals for long-running commands. Enable in /experimental!",
@@ -353,7 +358,7 @@ pub const FEATURES: &[FeatureSpec] = &[
     FeatureSpec {
         id: Feature::ShellSnapshot,
         key: "shell_snapshot",
-        stage: Stage::Beta {
+        stage: Stage::Experimental {
             name: "Shell snapshot",
             menu_description: "Snapshot your shell environment to avoid re-running login scripts for every command.",
             announcement: "NEW! Try shell snapshotting to make your Codex faster. Enable in /experimental!",
@@ -363,50 +368,50 @@ pub const FEATURES: &[FeatureSpec] = &[
     FeatureSpec {
         id: Feature::ChildAgentsMd,
         key: "child_agents_md",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::ApplyPatchFreeform,
         key: "apply_patch_freeform",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::ExecPolicy,
         key: "exec_policy",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: true,
     },
     FeatureSpec {
         id: Feature::WindowsSandbox,
         key: "experimental_windows_sandbox",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::WindowsSandboxElevated,
         key: "elevated_windows_sandbox",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::RemoteCompaction,
         key: "remote_compaction",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: true,
     },
     FeatureSpec {
         id: Feature::RemoteModels,
         key: "remote_models",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::PowershellUtf8,
         key: "powershell_utf8",
         #[cfg(windows)]
-        stage: Stage::Beta {
+        stage: Stage::Experimental {
             name: "Powershell UTF-8 support",
             menu_description: "Enable UTF-8 output in Powershell.",
             announcement: "Codex now supports UTF-8 output in Powershell. If you are seeing problems, disable in /experimental.",
@@ -414,32 +419,32 @@ pub const FEATURES: &[FeatureSpec] = &[
         #[cfg(windows)]
         default_enabled: true,
         #[cfg(not(windows))]
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         #[cfg(not(windows))]
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::EnableRequestCompression,
         key: "enable_request_compression",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::Collab,
         key: "collab",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::Tui2,
         key: "tui2",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
     FeatureSpec {
         id: Feature::Steer,
         key: "steer",
-        stage: Stage::Beta {
+        stage: Stage::Experimental {
             name: "Steer conversation",
             menu_description: "Enter submits immediately; Tab queues messages when a task is running.",
             announcement: "NEW! Try Steer mode: Enter submits immediately, Tab queues. Enable in /experimental!",
@@ -449,7 +454,7 @@ pub const FEATURES: &[FeatureSpec] = &[
     FeatureSpec {
         id: Feature::CollaborationModes,
         key: "collaboration_modes",
-        stage: Stage::Experimental,
+        stage: Stage::Beta,
         default_enabled: false,
     },
 ];