feat(providers): rename v2 setting and profile listing

Author: johntmyers

architecture/gateway-settings.md

@@ -30,7 +30,7 @@ The `REGISTERED_SETTINGS` static array defines the allowed setting keys and thei
 
 ```rust
 pub const REGISTERED_SETTINGS: &[RegisteredSetting] = &[
-    RegisteredSetting { key: "use_providers_v2", kind: SettingValueKind::Bool },
+    RegisteredSetting { key: "providers_v2_enabled", kind: SettingValueKind::Bool },
     RegisteredSetting { key: "ocsf_json_enabled", kind: SettingValueKind::Bool },
 ];
 ```
@@ -375,11 +375,11 @@ Set a single setting key at sandbox or global scope.
 openshell settings set my-sandbox --key ocsf_json_enabled --value true
 
 # Global (requires confirmation)
-openshell settings set --global --key use_providers_v2 --value true
+openshell settings set --global --key providers_v2_enabled --value true
 openshell settings set --global --key ocsf_json_enabled --value true
 
 # Skip confirmation
-openshell settings set --global --key use_providers_v2 --value true --yes
+openshell settings set --global --key providers_v2_enabled --value true --yes
 ```
 
 Value parsing is type-aware: bool keys accept `true/false/yes/no/1/0/on/off` via `parse_bool_like()`. Int keys parse as base-10 `i64`. String keys accept any value.
@@ -390,7 +390,7 @@ Delete a setting key from the specified scope.
 
 ```bash
 # Global delete (unlocks sandbox control)
-openshell settings delete --global --key use_providers_v2 --yes
+openshell settings delete --global --key providers_v2_enabled --yes
 ```
 
 ### `policy set --global --policy FILE [--yes]`
@@ -500,17 +500,17 @@ Settings are refreshed on each 2-second polling tick alongside the sandbox list
 
 ## Data Flow: Setting a Global Key
 
-End-to-end trace for `openshell settings set --global --key use_providers_v2 --value true --yes`:
+End-to-end trace for `openshell settings set --global --key providers_v2_enabled --value true --yes`:
 
 1. **CLI** (`crates/openshell-cli/src/run.rs` -- `gateway_setting_set()`):
-   - `parse_cli_setting_value("use_providers_v2", "true")` -- looks up `SettingValueKind::Bool` in the registry, wraps as `SettingValue { bool_value: true }`
+   - `parse_cli_setting_value("providers_v2_enabled", "true")` -- looks up `SettingValueKind::Bool` in the registry, wraps as `SettingValue { bool_value: true }`
    - `confirm_global_setting_takeover()` -- skipped because `--yes`
-   - Sends `UpdateSettingsRequest { setting_key: "use_providers_v2", setting_value: Some(...), global: true }`
+   - Sends `UpdateSettingsRequest { setting_key: "providers_v2_enabled", setting_value: Some(...), global: true }`
 
 2. **Gateway** (`crates/openshell-server/src/grpc.rs` -- `update_settings()`):
    - Acquires `settings_mutex` for the duration of the operation
    - Detects `global=true`, `has_setting=true`
-   - `validate_registered_setting_key("use_providers_v2")` -- passes (key is in registry)
+   - `validate_registered_setting_key("providers_v2_enabled")` -- passes (key is in registry)
    - `load_global_settings()` -- reads `gateway_settings` record from store
    - `proto_setting_to_stored()` -- converts proto value to `StoredSettingValue::Bool(true)`
    - `upsert_setting_value()` -- inserts into `BTreeMap`, returns `true` (changed)
@@ -519,7 +519,7 @@ End-to-end trace for `openshell settings set --global --key use_providers_v2 --v
 
 3. **Sandbox** (next poll tick in `run_policy_poll_loop()`):
    - `poll_settings(sandbox_id)` returns new `config_revision`
-   - `log_setting_changes()` logs: `Setting changed key="use_providers_v2" old="<unset>" new="true"`
+   - `log_setting_changes()` logs: `Setting changed key="providers_v2_enabled" old="<unset>" new="true"`
    - `policy_hash` unchanged -- no OPA reload
    - Updates tracked `current_config_revision` and `current_settings`
 

architecture/sandbox-providers.md

@@ -64,10 +64,10 @@ inference-capable when their tool talks to an inference API.
 Profiles are additive to provider records. A provider record with only `type`,
 `credentials`, and `config` can be matched to built-in profile metadata by
 `provider.type`. Profile-generated policy is still opt-in: the gateway composes provider
-profile rules only when the gateway-global `use_providers_v2` setting is true.
+profile rules only when the gateway-global `providers_v2_enabled` setting is true.
 
 This keeps the compatibility boundary at the gateway. A gateway without
-`use_providers_v2=true` keeps the existing credential-only provider behavior, while a
+`providers_v2_enabled=true` keeps the existing credential-only provider behavior, while a
 gateway with the flag enabled routes all attached known provider types through the
 profile-backed policy path.
 
@@ -92,7 +92,7 @@ host/port endpoints across policy and provider rules are valid; OPA evaluates al
 rules, so allow decisions are the union of matching allows and deny rules continue to
 win globally.
 
-Gateway-global policy still overrides sandbox-authored policy. When `use_providers_v2`
+Gateway-global policy still overrides sandbox-authored policy. When `providers_v2_enabled`
 is true, provider layers compose JIT onto the effective policy source, whether that
 source is sandbox-scoped or global. The composed payload is derived data and is not
 persisted as a policy revision.
@@ -228,7 +228,7 @@ Also supported:
 
 - `openshell provider get <name>`
 - `openshell provider list`
-- `openshell provider list-types`
+- `openshell provider list-profiles`
 - `openshell provider update <name> ...`
 - `openshell provider delete <name> [<name>...]`
 

crates/openshell-cli/src/main.rs

@@ -299,10 +299,10 @@ const POLICY_EXAMPLES: &str = "\x1b[1mALIAS\x1b[0m
 const SETTINGS_EXAMPLES: &str = "\x1b[1mEXAMPLES\x1b[0m
   $ openshell settings get my-sandbox
   $ openshell settings get --global
-  $ openshell settings set --global --key use_providers_v2 --value true
+  $ openshell settings set --global --key providers_v2_enabled --value true
   $ openshell settings set my-sandbox --key ocsf_json_enabled --value true
   $ openshell settings set --global --key ocsf_json_enabled --value true
-  $ openshell settings delete --global --key use_providers_v2
+  $ openshell settings delete --global --key providers_v2_enabled
 ";
 
 const PROVIDER_EXAMPLES: &str = "\x1b[1mEXAMPLES\x1b[0m
@@ -734,9 +734,9 @@ enum ProviderCommands {
         names: bool,
     },
 
-    /// List available provider types.
+    /// List available provider profiles.
     #[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
-    ListTypes,
+    ListProfiles,
 
     /// Update an existing provider's credentials or config.
     #[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
@@ -2767,8 +2767,8 @@ async fn main() -> Result<()> {
                 } => {
                     run::provider_list(endpoint, limit, offset, names, &tls).await?;
                 }
-                ProviderCommands::ListTypes => {
-                    run::provider_list_types(endpoint, &tls).await?;
+                ProviderCommands::ListProfiles => {
+                    run::provider_list_profiles(endpoint, &tls).await?;
                 }
                 ProviderCommands::Update {
                     name,
@@ -3460,6 +3460,19 @@ mod tests {
         }
     }
 
+    #[test]
+    fn provider_list_profiles_parses() {
+        let cli = Cli::try_parse_from(["openshell", "provider", "list-profiles"])
+            .expect("provider list-profiles should parse");
+
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Provider {
+                command: Some(ProviderCommands::ListProfiles)
+            })
+        ));
+    }
+
     #[test]
     fn settings_set_global_parses_yes_flag() {
         let cli = Cli::try_parse_from([

crates/openshell-cli/src/run.rs

@@ -3980,7 +3980,7 @@ pub async fn provider_list(
     Ok(())
 }
 
-pub async fn provider_list_types(server: &str, tls: &TlsOptions) -> Result<()> {
+pub async fn provider_list_profiles(server: &str, tls: &TlsOptions) -> Result<()> {
     let mut client = grpc_client(server, tls).await?;
     let response = client
         .list_provider_profiles(ListProviderProfilesRequest {
@@ -3997,11 +3997,11 @@ pub async fn provider_list_types(server: &str, tls: &TlsOptions) -> Result<()> {
     });
 
     if profiles.is_empty() {
-        println!("No provider types found.");
+        println!("No provider profiles found.");
         return Ok(());
     }
 
-    println!("{}", "Available Provider Types:".cyan().bold());
+    println!("{}", "Available Provider Profiles:".cyan().bold());
     let mut current_category = i32::MIN;
     for profile in profiles {
         if profile.category != current_category {

crates/openshell-cli/tests/provider_commands_integration.rs

@@ -551,12 +551,12 @@ async fn provider_cli_run_functions_support_full_crud_flow() {
 }
 
 #[tokio::test]
-async fn provider_list_types_cli_uses_profile_browsing_rpc() {
+async fn provider_list_profiles_cli_uses_profile_browsing_rpc() {
     let ts = run_server().await;
 
-    run::provider_list_types(&ts.endpoint, &ts.tls)
+    run::provider_list_profiles(&ts.endpoint, &ts.tls)
         .await
-        .expect("provider list-types");
+        .expect("provider list-profiles");
 }
 
 #[tokio::test]

crates/openshell-core/src/settings.rs

@@ -48,13 +48,13 @@ pub struct RegisteredSetting {
 ///    settable via `settings set`. The server validates that only registered
 ///    keys are accepted.
 /// 5. Add a unit test in this module's `tests` section to cover the new key.
-pub const USE_PROVIDERS_V2_KEY: &str = "use_providers_v2";
+pub const PROVIDERS_V2_ENABLED_KEY: &str = "providers_v2_enabled";
 
 pub const REGISTERED_SETTINGS: &[RegisteredSetting] = &[
     // Gateway-level opt-in for provider profile policy composition. Defaults
     // to false when unset.
     RegisteredSetting {
-        key: USE_PROVIDERS_V2_KEY,
+        key: PROVIDERS_V2_ENABLED_KEY,
         kind: SettingValueKind::Bool,
     },
     // When true the sandbox writes OCSF v1.7.0 JSONL records to
@@ -107,7 +107,7 @@ pub fn parse_bool_like(raw: &str) -> Option<bool> {
 #[cfg(test)]
 mod tests {
     use super::{
-        REGISTERED_SETTINGS, RegisteredSetting, SettingValueKind, USE_PROVIDERS_V2_KEY,
+        PROVIDERS_V2_ENABLED_KEY, REGISTERED_SETTINGS, RegisteredSetting, SettingValueKind,
         parse_bool_like, registered_keys_csv, setting_for_key,
     };
 
@@ -132,9 +132,9 @@ mod tests {
     }
 
     #[test]
-    fn setting_for_key_returns_use_providers_v2() {
-        let setting =
-            setting_for_key(USE_PROVIDERS_V2_KEY).expect("use_providers_v2 should be registered");
+    fn setting_for_key_returns_providers_v2_enabled() {
+        let setting = setting_for_key(PROVIDERS_V2_ENABLED_KEY)
+            .expect("providers_v2_enabled should be registered");
         assert_eq!(setting.kind, SettingValueKind::Bool);
     }
 

crates/openshell-server/src/grpc/policy.rs

@@ -436,7 +436,8 @@ pub(super) async fn handle_get_sandbox_config(
     let global_settings = load_global_settings(state.store.as_ref()).await?;
     let sandbox_settings =
         load_sandbox_settings(state.store.as_ref(), sandbox.object_name()).await?;
-    let use_providers_v2 = bool_setting_enabled(&global_settings, settings::USE_PROVIDERS_V2_KEY)?;
+    let providers_v2_enabled =
+        bool_setting_enabled(&global_settings, settings::PROVIDERS_V2_ENABLED_KEY)?;
 
     let mut global_policy_version: u32 = 0;
 
@@ -456,7 +457,7 @@ pub(super) async fn handle_get_sandbox_config(
         }
     }
 
-    if use_providers_v2
+    if providers_v2_enabled
         && !matches!(policy_source, PolicySource::Global)
         && let Some(source_policy) = policy.as_ref()
     {
@@ -2828,7 +2829,7 @@ mod tests {
         let global_settings = StoredSettings {
             revision: 1,
             settings: std::iter::once((
-                settings::USE_PROVIDERS_V2_KEY.to_string(),
+                settings::PROVIDERS_V2_ENABLED_KEY.to_string(),
                 StoredSettingValue::Bool(true),
             ))
             .collect(),
@@ -2892,22 +2893,25 @@ mod tests {
     }
 
     #[test]
-    fn use_providers_v2_defaults_false_when_unset() {
+    fn providers_v2_enabled_defaults_false_when_unset() {
         assert!(
-            !bool_setting_enabled(&StoredSettings::default(), settings::USE_PROVIDERS_V2_KEY)
-                .unwrap()
+            !bool_setting_enabled(
+                &StoredSettings::default(),
+                settings::PROVIDERS_V2_ENABLED_KEY
+            )
+            .unwrap()
         );
     }
 
     #[test]
-    fn use_providers_v2_reads_global_bool_setting() {
+    fn providers_v2_enabled_reads_global_bool_setting() {
         let mut settings = StoredSettings::default();
         settings.settings.insert(
-            settings::USE_PROVIDERS_V2_KEY.to_string(),
+            settings::PROVIDERS_V2_ENABLED_KEY.to_string(),
             StoredSettingValue::Bool(true),
         );
 
-        assert!(bool_setting_enabled(&settings, settings::USE_PROVIDERS_V2_KEY).unwrap());
+        assert!(bool_setting_enabled(&settings, settings::PROVIDERS_V2_ENABLED_KEY).unwrap());
     }
 
     #[tokio::test]
@@ -3226,7 +3230,7 @@ mod tests {
             revision: 1,
             settings: [
                 (
-                    settings::USE_PROVIDERS_V2_KEY.to_string(),
+                    settings::PROVIDERS_V2_ENABLED_KEY.to_string(),
                     StoredSettingValue::Bool(true),
                 ),
                 (

docs/sandboxes/manage-providers.mdx

@@ -12,11 +12,11 @@ AI agents typically need credentials to access external services: an API key for
 
 Create and manage providers that supply credentials to sandboxes.
 
-Provider types include profile metadata for known endpoints and binaries. View
-the available provider types before creating a provider:
+Provider profiles include metadata for known endpoints and binaries. View
+the available profiles before creating a provider:
 
 ```shell
-openshell provider list-types
+openshell provider list-profiles
 ```
 
 ## Create a Provider
@@ -58,10 +58,10 @@ Provider profile metadata is available for known provider types. Provider profil
 network policy is gateway opt-in:
 
 ```shell
-openshell settings set --global --key use_providers_v2 --value true
+openshell settings set --global --key providers_v2_enabled --value true
 ```
 
-Without `use_providers_v2=true`, provider behavior remains credential-only.
+Without `providers_v2_enabled=true`, provider behavior remains credential-only.
 
 ## Manage Providers
 
@@ -102,7 +102,7 @@ openshell sandbox create --provider my-claude --provider my-github -- claude
 Each `--provider` flag attaches one provider. The sandbox receives all
 credentials from every attached provider at runtime. Profile-managed providers
 also contribute provider-generated network policy entries when
-`use_providers_v2` is enabled at the gateway. When the setting is disabled,
+`providers_v2_enabled` is enabled at the gateway. When the setting is disabled,
 providers keep the previous behavior and only provide credentials.
 
 <Warning>