feat: wizard entry points — /setup command, claw setup subcommand (rebased)

rust/crates/commands/src/lib.rs

@@ -720,6 +720,13 @@ const SLASH_COMMAND_SPECS: &[SlashCommandSpec] = &[
         argument_hint: None,
         resume_supported: true,
     },
+    SlashCommandSpec {
+        name: "setup",
+        aliases: &[],
+        summary: "Run the interactive provider setup wizard",
+        argument_hint: None,
+        resume_supported: false,
+    },
     SlashCommandSpec {
         name: "notifications",
         aliases: &[],
@@ -1102,6 +1109,7 @@ pub enum SlashCommand {
         args: Option<String>,
     },
     Doctor,
+    Setup,
     Login,
     Logout,
     Vim,
@@ -1223,6 +1231,7 @@ impl SlashCommand {
             Self::Compact { .. } => "/compact",
             Self::Cost => "/cost",
             Self::Doctor => "/doctor",
+            Self::Setup => "/setup",
             Self::Config { .. } => "/config",
             Self::Memory { .. } => "/memory",
             Self::History { .. } => "/history",
@@ -1392,6 +1401,10 @@ pub fn validate_slash_command_input(
             validate_no_args(command, &args)?;
             SlashCommand::Doctor
         }
+        "setup" => {
+            validate_no_args(command, &args)?;
+            SlashCommand::Setup
+        }
         "login" | "logout" => {
             return Err(command_error(
                 "This auth flow was removed. Set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN instead.",
@@ -1914,7 +1927,7 @@ fn slash_command_category(name: &str) -> &'static str {
         | "stickers" | "language" | "profile" | "max-tokens" | "temperature" | "system-prompt"
         | "api-key" | "terminal-setup" | "notifications" | "telemetry" | "providers" | "env"
         | "project" | "reasoning" | "budget" | "rate-limit" | "workspace" | "reset" | "ide"
-        | "desktop" | "upgrade" => "Config",
+        | "desktop" | "upgrade" | "setup" => "Config",
         "debug-tool-call" | "doctor" | "sandbox" | "diagnostics" | "tool-details" | "changelog"
         | "metrics" => "Debug",
         _ => "Tools",
@@ -5381,6 +5394,7 @@ pub fn handle_slash_command(
         | SlashCommand::AddDir { .. }
         | SlashCommand::History { .. }
         | SlashCommand::Team { .. }
+        | SlashCommand::Setup
         | SlashCommand::Unknown(_) => None,
     }
 }
@@ -5997,7 +6011,8 @@ mod tests {
         assert!(help.contains("aliases: /skill"));
         assert!(!help.contains("/login"));
         assert!(!help.contains("/logout"));
-        assert_eq!(slash_command_specs().len(), 139);
+        assert!(help.contains("/setup"));
+        assert_eq!(slash_command_specs().len(), 140);
         assert!(resume_supported_slash_commands().len() >= 39);
     }
 

rust/crates/runtime/src/config.rs

@@ -162,6 +162,7 @@ pub struct RuntimeFeatureConfig {
     trusted_roots: Vec<String>,
     api_timeout: ApiTimeoutConfig,
     rules_import: RulesImportConfig,
+    provider: RuntimeProviderConfig,
 }
 
 /// Controls which external AI coding framework rules are imported into the system prompt.
@@ -189,6 +190,41 @@ impl RulesImportConfig {
     }
 }
 
+/// Stored provider configuration from the setup wizard.
+///
+/// Represents the `provider` section in `~/.claw/settings.json`, used as a
+/// fallback when environment variables are absent (3-tier resolution:
+/// env var > .env file > stored config).
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct RuntimeProviderConfig {
+    kind: Option<String>,
+    api_key: Option<String>,
+    base_url: Option<String>,
+    model: Option<String>,
+}
+
+impl RuntimeProviderConfig {
+    #[must_use]
+    pub fn kind(&self) -> Option<&str> {
+        self.kind.as_deref()
+    }
+
+    #[must_use]
+    pub fn api_key(&self) -> Option<&str> {
+        self.api_key.as_deref()
+    }
+
+    #[must_use]
+    pub fn base_url(&self) -> Option<&str> {
+        self.base_url.as_deref()
+    }
+
+    #[must_use]
+    pub fn model(&self) -> Option<&str> {
+        self.model.as_deref()
+    }
+}
+
 /// Ordered chain of fallback model identifiers used when the primary
 /// provider returns a retryable failure (429/500/503/etc.). The chain is
 /// strict: each entry is tried in order until one succeeds.
@@ -764,6 +800,7 @@ fn build_runtime_config(
         trusted_roots: parse_optional_trusted_roots(&merged_value)?,
         api_timeout: parse_optional_api_timeout_config(&merged_value)?,
         rules_import: parse_optional_rules_import(&merged_value)?,
+        provider: parse_optional_provider_config(&merged_value)?,
     };
 
     Ok(RuntimeConfig {
@@ -878,6 +915,11 @@ impl RuntimeConfig {
         &self.feature_config.rules_import
     }
 
+    #[must_use]
+    pub fn provider(&self) -> &RuntimeProviderConfig {
+        &self.feature_config.provider
+    }
+
     /// Merge config-level default trusted roots with per-call roots.
     ///
     /// Config roots are defaults and are kept first; per-call roots extend the
@@ -891,6 +933,13 @@ impl RuntimeConfig {
 }
 
 impl RuntimeFeatureConfig {
+    /// Parsed provider configuration (kind, apiKey, baseUrl, model) from
+    /// merged settings.
+    #[must_use]
+    pub fn provider(&self) -> &RuntimeProviderConfig {
+        &self.provider
+    }
+
     #[must_use]
     pub fn with_hooks(mut self, hooks: RuntimeHookConfig) -> Self {
         self.hooks = hooks;
@@ -2104,6 +2153,25 @@ fn parse_optional_rules_import(root: &JsonValue) -> Result<RulesImportConfig, Co
     }
 }
 
+fn parse_optional_provider_config(root: &JsonValue) -> Result<RuntimeProviderConfig, ConfigError> {
+    let Some(provider_value) = root.as_object().and_then(|object| object.get("provider")) else {
+        return Ok(RuntimeProviderConfig::default());
+    };
+    let Some(object) = provider_value.as_object() else {
+        return Ok(RuntimeProviderConfig::default());
+    };
+    let kind = optional_string(object, "kind", "provider")?.map(str::to_string);
+    let api_key = optional_string(object, "apiKey", "provider")?.map(str::to_string);
+    let base_url = optional_string(object, "baseUrl", "provider")?.map(str::to_string);
+    let model = optional_string(object, "model", "provider")?.map(str::to_string);
+    Ok(RuntimeProviderConfig {
+        kind,
+        api_key,
+        base_url,
+        model,
+    })
+}
+
 fn parse_filesystem_mode_label(value: &str) -> Result<FilesystemIsolationMode, ConfigError> {
     match value {
         "off" => Ok(FilesystemIsolationMode::Off),

rust/crates/runtime/src/config_validate.rs

@@ -216,6 +216,10 @@ const TOP_LEVEL_FIELDS: &[FieldSpec] = &[
         name: "rulesImport",
         expected: FieldType::RulesImport,
     },
+    FieldSpec {
+        name: "subagentModel",
+        expected: FieldType::String,
+    },
 ];
 
 const HOOKS_FIELDS: &[FieldSpec] = &[
@@ -421,8 +425,6 @@ fn validate_object_keys(
         } else if DEPRECATED_FIELDS.iter().any(|d| d.name == key) {
             // Deprecated key — handled separately, not an unknown-key error.
         } else {
-            // Unknown key — preserve compatibility by surfacing it as a warning
-            // instead of blocking otherwise valid config files.
             let suggestion = suggest_field(key, &known_names);
             result.warnings.push(ConfigDiagnostic {
                 path: path_display.to_string(),
@@ -436,56 +438,8 @@ fn validate_object_keys(
     result
 }
 
-/// Emit deprecation warnings for bare string hook entries in the hooks object.
-/// Legacy `["command-string"]` arrays still load but suggest migration to the
-/// structured `{matcher, hooks:[{type, command}]}` form.
-fn validate_hook_entry_format(
-    hooks: &BTreeMap<String, JsonValue>,
-    source: &str,
-    path_display: &str,
-) -> ValidationResult {
-    let mut result = ValidationResult {
-        errors: Vec::new(),
-        warnings: Vec::new(),
-    };
-    for spec in HOOKS_FIELDS {
-        let Some(value) = hooks.get(spec.name) else {
-            continue;
-        };
-        let Some(array) = value.as_array() else {
-            continue;
-        };
-        for item in array {
-            if item.as_str().is_some() {
-                result.warnings.push(ConfigDiagnostic {
-                    path: path_display.to_string(),
-                    field: format!("hooks.{}", spec.name),
-                    line: find_key_line(source, spec.name),
-                    kind: DiagnosticKind::Deprecated {
-                        replacement: "object-style hook entries with hooks:[{type:\"command\",command:\"...\"}]",
-                    },
-                });
-                // One deprecation warning per event is enough
-                break;
-            }
-        }
-    }
-    result
-}
-
 fn suggest_field(input: &str, candidates: &[&str]) -> Option<String> {
     let input_lower = input.to_ascii_lowercase();
-    // #461: prefix-aware matching — if input is a prefix of a candidate,
-    // treat it as distance 0 (perfect prefix match) to avoid edit-distance
-    // misranking (e.g., "mcp" → "env" instead of "mcpServers").
-    let prefix_match = candidates
-        .iter()
-        .filter(|c| c.to_ascii_lowercase().starts_with(&input_lower))
-        .min_by_key(|c| c.len())
-        .map(|name| name.to_string());
-    if prefix_match.is_some() {
-        return prefix_match;
-    }
     candidates
         .iter()
         .filter_map(|candidate| {
@@ -555,7 +509,6 @@ pub fn validate_config_file(
             source,
             &path_display,
         ));
-        result.merge(validate_hook_entry_format(hooks, source, &path_display));
     }
     if let Some(permissions) = object.get("permissions").and_then(JsonValue::as_object) {
         result.merge(validate_object_keys(

rust/crates/runtime/src/lib.rs

@@ -65,14 +65,15 @@ pub use compact::{
     get_compact_continuation_message, should_compact, CompactionConfig, CompactionResult,
 };
 pub use config::{
+    clear_user_provider_settings, default_config_home, save_user_provider_settings,
     suppress_config_warnings_for_json_mode, ApiTimeoutConfig, ConfigEntry, ConfigError,
     ConfigFileReport, ConfigFileStatus, ConfigInspection, ConfigLoader, ConfigSource,
     McpConfigCollection, McpInvalidServerConfig, McpManagedProxyServerConfig, McpOAuthConfig,
     McpRemoteServerConfig, McpSdkServerConfig, McpServerConfig, McpStdioServerConfig, McpTransport,
     McpWebSocketServerConfig, OAuthConfig, ProviderFallbackConfig, ResolvedPermissionMode,
     RulesImportConfig, RuntimeConfig, RuntimeFeatureConfig, RuntimeHookCommand, RuntimeHookConfig,
     RuntimeInvalidHookConfig, RuntimePermissionRuleConfig, RuntimePluginConfig,
-    ScopedMcpServerConfig, CLAW_SETTINGS_SCHEMA_NAME,
+    RuntimeProviderConfig, ScopedMcpServerConfig, CLAW_SETTINGS_SCHEMA_NAME,
 };
 pub use config_validate::{
     check_unsupported_format, format_diagnostics, validate_config_file, ConfigDiagnostic,