Merge pull request #3227 from TheArchitectit/worktree-wizard-entry-points

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,6 +65,7 @@ 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,
@@ -72,7 +73,7 @@ pub use config::{
     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,

rust/crates/rusty-claude-cli/src/main.rs

@@ -17,6 +17,7 @@
 mod init;
 mod input;
 mod render;
+mod setup_wizard;
 
 use std::collections::BTreeSet;
 use std::env;
@@ -1095,6 +1096,7 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
         CliAction::SessionList { output_format } => run_session_list(output_format)?,
         CliAction::State { output_format } => run_worker_state(output_format)?,
         CliAction::Init { output_format } => run_init(output_format)?,
+        CliAction::Setup { output_format: _ } => run_setup()?,
         // #146: dispatch pure-local introspection. Text mode uses existing
         // render_config_report/render_diff_report; JSON mode uses the
         // corresponding _json helpers already exposed for resume sessions.
@@ -1238,6 +1240,9 @@ enum CliAction {
     Init {
         output_format: CliOutputFormat,
     },
+    Setup {
+        output_format: CliOutputFormat,
+    },
     // #146: `claw config` and `claw diff` are pure-local read-only
     // introspection commands; wire them as standalone CLI subcommands.
     Config {
@@ -1301,6 +1306,7 @@ enum LocalHelpTopic {
     Model,
     Settings,
     Diff,
+    Setup,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -1765,6 +1771,7 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
                 "doctor" => Some(LocalHelpTopic::Doctor),
                 "acp" => Some(LocalHelpTopic::Acp),
                 "init" => Some(LocalHelpTopic::Init),
+                "setup" => Some(LocalHelpTopic::Setup),
                 "state" => Some(LocalHelpTopic::State),
                 "resume" => Some(LocalHelpTopic::Resume),
                 "session" => Some(LocalHelpTopic::Session),
@@ -2144,6 +2151,15 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             }
             Ok(CliAction::Init { output_format })
         }
+        "setup" => {
+            if rest.len() > 1 {
+                let extra = rest[1..].join(" ");
+                return Err(format!(
+                    "unexpected extra arguments after `claw setup`: {extra}\nUsage: claw setup"
+                ));
+            }
+            Ok(CliAction::Setup { output_format })
+        }
         "export" => parse_export_args(&rest[1..], output_format),
         "prompt" => {
             let mut read_stdin = false;
@@ -2271,6 +2287,7 @@ fn parse_local_help_action(
         "doctor" => LocalHelpTopic::Doctor,
         "acp" => LocalHelpTopic::Acp,
         "init" => LocalHelpTopic::Init,
+        "setup" => LocalHelpTopic::Setup,
         "state" => LocalHelpTopic::State,
         "export" => LocalHelpTopic::Export,
         "version" => LocalHelpTopic::Version,
@@ -2316,7 +2333,7 @@ fn parse_single_word_command_alias(
     let verb = &rest[0];
     let is_diagnostic = matches!(
         verb.as_str(),
-        "help" | "version" | "status" | "sandbox" | "doctor" | "state"
+        "help" | "version" | "status" | "sandbox" | "doctor" | "setup" | "state"
     );
 
     if is_diagnostic && rest.len() > 1 {
@@ -2336,6 +2353,7 @@ fn parse_single_word_command_alias(
                 "doctor" => Some(LocalHelpTopic::Doctor),
                 "acp" => Some(LocalHelpTopic::Acp),
                 "init" => Some(LocalHelpTopic::Init),
+                "setup" => Some(LocalHelpTopic::Setup),
                 "state" => Some(LocalHelpTopic::State),
                 "export" => Some(LocalHelpTopic::Export),
                 "version" => Some(LocalHelpTopic::Version),
@@ -2390,6 +2408,7 @@ fn parse_single_word_command_alias(
             "doctor" => Some(LocalHelpTopic::Doctor),
             "acp" => Some(LocalHelpTopic::Acp),
             "init" => Some(LocalHelpTopic::Init),
+            "setup" => Some(LocalHelpTopic::Setup),
             "state" => Some(LocalHelpTopic::State),
             "export" => Some(LocalHelpTopic::Export),
             "version" => Some(LocalHelpTopic::Version),
@@ -2452,6 +2471,7 @@ fn parse_single_word_command_alias(
                 .map(PermissionModeProvenance::from_flag)
                 .unwrap_or_else(permission_mode_provenance_for_current_dir),
         })),
+        "setup" => Some(Ok(CliAction::Setup { output_format })),
         "state" => Some(Ok(CliAction::State { output_format })),
         // #146: let `config` and `diff` fall through to parse_subcommand
         // where they are wired as pure-local introspection, instead of
@@ -2744,6 +2764,7 @@ fn suggest_similar_subcommand(input: &str) -> Option<Vec<String>> {
         "status",
         "sandbox",
         "doctor",
+        "setup",
         "state",
         "dump-manifests",
         "bootstrap-plan",
@@ -3729,6 +3750,11 @@ fn run_doctor(
     Ok(())
 }
 
+/// Run the interactive setup wizard to configure provider, API key, and model.
+fn run_setup() -> Result<(), Box<dyn std::error::Error>> {
+    setup_wizard::run_setup_wizard()
+}
+
 /// Starts a minimal Model Context Protocol server that exposes claw's
 /// built-in tools over stdio.
 ///
@@ -6900,7 +6926,8 @@ fn run_resume_command(
         | SlashCommand::Tag { .. }
         | SlashCommand::OutputStyle { .. }
         | SlashCommand::AddDir { .. }
-        | SlashCommand::Team { .. } => Err("unsupported resumed slash command".into()),
+        | SlashCommand::Team { .. }
+        | SlashCommand::Setup => Err("unsupported resumed slash command".into()),
     }
 }
 
@@ -8161,6 +8188,12 @@ impl LiveCli {
                 );
                 false
             }
+            SlashCommand::Setup => {
+                if let Err(e) = setup_wizard::run_setup_wizard() {
+                    eprintln!("Setup wizard failed: {e}");
+                }
+                false
+            }
             SlashCommand::History { count } => {
                 self.print_prompt_history(count.as_deref());
                 false
@@ -10230,6 +10263,13 @@ fn render_help_topic(topic: LocalHelpTopic) -> String {
   Formats          text (default), json
   Related          /diff · ROADMAP #148"
             .to_string(),
+        LocalHelpTopic::Setup => "Setup
+  Usage            claw setup
+  Aliases          /setup (inside the REPL)
+  Purpose          run the interactive provider setup wizard to configure API key, model, and base URL
+  Output           writes provider settings to ~/.claw/settings.json (0600 permissions)
+  Related          /model · /config · claw doctor"
+            .to_string(),
     }
 }
 
@@ -10257,6 +10297,7 @@ fn local_help_topic_command(topic: LocalHelpTopic) -> &'static str {
         LocalHelpTopic::Model => "models",
         LocalHelpTopic::Settings => "settings",
         LocalHelpTopic::Diff => "diff",
+        LocalHelpTopic::Setup => "setup",
     }
 }
 

rust/crates/rusty-claude-cli/src/setup_wizard.rs

@@ -23,7 +23,10 @@ const DEFAULT_BASE_URLS: &[(&str, &str)] = &[
     ("anthropic", "https://api.anthropic.com"),
     ("xai", "https://api.x.ai/v1"),
     ("openai", "https://api.openai.com/v1"),
-    ("dashscope", "https://dashscope.aliyuncs.com/compatible-mode/v1"),
+    (
+        "dashscope",
+        "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    ),
 ];
 
 const API_KEY_ENV_VARS: &[(&str, &str)] = &[
@@ -51,12 +54,7 @@ pub fn run_setup_wizard() -> Result<(), Box<dyn std::error::Error>> {
     let model = prompt_model(&kind, &current)?;
     let fast_model = prompt_fast_model(&current, model.as_deref())?;
 
-    save_user_provider_settings(
-        &kind,
-        &api_key,
-        base_url.as_deref(),
-        model.as_deref(),
-    )?;
+    save_user_provider_settings(&kind, &api_key, base_url.as_deref(), model.as_deref())?;
 
     if let Some(fast) = &fast_model {
         save_settings_field("subagentModel", fast)?;
@@ -64,7 +62,10 @@ pub fn run_setup_wizard() -> Result<(), Box<dyn std::error::Error>> {
 
     println!();
     println!("  \x1b[32mProvider saved to ~/.claw/settings.json\x1b[0m");
-    println!("  Run \x1b[1m/model {}\x1b[0m or restart claw to activate.", model.as_deref().unwrap_or(&kind));
+    println!(
+        "  Run \x1b[1m/model {}\x1b[0m or restart claw to activate.",
+        model.as_deref().unwrap_or(&kind)
+    );
     println!();
 
     Ok(())
@@ -82,7 +83,11 @@ fn prompt_provider(current: &RuntimeProviderConfig) -> Result<String, Box<dyn st
     let current_kind = current.kind().unwrap_or("anthropic");
     println!("  \x1b[1mProvider\x1b[0m");
     for (num, label, kind) in PROVIDERS {
-        let marker = if *kind == current_kind { " (current)" } else { "" };
+        let marker = if *kind == current_kind {
+            " (current)"
+        } else {
+            ""
+        };
         println!("    [{num}] {label}{marker}");
     }
     let default = PROVIDERS
@@ -129,9 +134,7 @@ fn prompt_api_key(
     };
 
     // Check if env var is already set
-    let env_set = std::env::var(env_var)
-        .ok()
-        .is_some_and(|v| !v.is_empty());
+    let env_set = std::env::var(env_var).ok().is_some_and(|v| !v.is_empty());
     if env_set {
         println!("  {env_var} is set in environment (will take priority over stored key)");
     }
@@ -144,7 +147,9 @@ fn prompt_api_key(
     };
 
     if key.is_empty() && !env_set {
-        eprintln!("  \x1b[33mWarning: no API key configured. Set {env_var} or re-run setup.\x1b[0m");
+        eprintln!(
+            "  \x1b[33mWarning: no API key configured. Set {env_var} or re-run setup.\x1b[0m"
+        );
     }
 
     Ok(key)
@@ -174,9 +179,7 @@ fn prompt_base_url(
         "dashscope" => "DASHSCOPE_BASE_URL",
         _ => "BASE_URL",
     };
-    let env_set = std::env::var(env_var)
-        .ok()
-        .is_some_and(|v| !v.is_empty());
+    let env_set = std::env::var(env_var).ok().is_some_and(|v| !v.is_empty());
     if env_set {
         println!("  {env_var} is set in environment (will take priority over stored URL)");
     }
@@ -203,7 +206,9 @@ fn prompt_model(
         .find(|(k, _)| *k == kind)
         .map_or(empty, |(_, models)| *models);
 
-    let current_model = current.model().unwrap_or(aliases.first().copied().unwrap_or(""));
+    let current_model = current
+        .model()
+        .unwrap_or(aliases.first().copied().unwrap_or(""));
 
     println!("  \x1b[1mModel\x1b[0m");
     if !aliases.is_empty() {
@@ -235,12 +240,16 @@ fn prompt_fast_model(
     println!("    Press Enter to skip (agents will use your main model).");
 
     let current_fast = load_current_settings_field("subagentModel");
-    let default_hint = current_fast
-        .as_deref()
-        .or(main_model)
-        .unwrap_or("");
+    let default_hint = current_fast.as_deref().or(main_model).unwrap_or("");
 
-    let input = read_line(&format!("  Fast model [{}]: ", if default_hint.is_empty() { "same as main" } else { default_hint }))?;
+    let input = read_line(&format!(
+        "  Fast model [{}]: ",
+        if default_hint.is_empty() {
+            "same as main"
+        } else {
+            default_hint
+        }
+    ))?;
     if input.trim().is_empty() {
         Ok(current_fast)
     } else {
@@ -269,7 +278,10 @@ fn save_settings_field(field: &str, value: &str) -> Result<(), Box<dyn std::erro
     };
 
     if let Some(obj) = settings.as_object_mut() {
-        obj.insert(field.to_string(), serde_json::Value::String(value.to_string()));
+        obj.insert(
+            field.to_string(),
+            serde_json::Value::String(value.to_string()),
+        );
     }
 
     std::fs::create_dir_all(&settings_dir)?;