diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc634c5..573f4a5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Configuration file support via `rb.toml` for global settings
+- Project script management with `rbproject.toml` and `rb run` command
+- Project bootstrap script with `rb init`
+
 ## [0.1.0] - 2025-09-26
 
 ### Added
@@ -24,4 +29,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-*Distinguished releases crafted with appropriate ceremony by RubyElders.com*
\ No newline at end of file
+*Distinguished releases crafted with appropriate ceremony by RubyElders.com*
diff --git a/Cargo.lock b/Cargo.lock
index e685aa8..cd47444 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -158,6 +158,12 @@ dependencies = [
  "log",
 ]
 
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
 [[package]]
 name = "errno"
 version = "0.3.13"
@@ -186,6 +192,12 @@ dependencies = [
  "wasi",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5419bdc4f6a9207fbeba6d11b604d481addf78ecd10c11ad51e76c2f6482748d"
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -201,6 +213,16 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "indexmap"
+version = "2.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b0f83760fb341a774ed326568e19f5a863af4a952def8c39f9ab92fd95b88e5"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.1"
@@ -320,7 +342,7 @@ checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 
 [[package]]
 name = "rb-cli"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "clap",
  "colored",
@@ -330,12 +352,14 @@ dependencies = [
  "rb-core",
  "rb-tests",
  "semver",
+ "serde",
+ "toml",
  "which",
 ]
 
 [[package]]
 name = "rb-core"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "colored",
  "home",
@@ -343,13 +367,15 @@ dependencies = [
  "rb-tests",
  "regex",
  "semver",
+ "serde",
  "tempfile",
+ "toml",
  "which",
 ]
 
 [[package]]
 name = "rb-tests"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "tempfile",
 ]
@@ -435,6 +461,15 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_spanned"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -465,6 +500,47 @@ dependencies = [
  "windows-sys 0.60.2",
 ]
 
+[[package]]
+name = "toml"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
+dependencies = [
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_edit",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.22.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
+dependencies = [
+ "indexmap",
+ "serde",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_write",
+ "winnow",
+]
+
+[[package]]
+name = "toml_write"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.18"
@@ -651,6 +727,15 @@ version = "0.53.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "271414315aff87387382ec3d271b52d7ae78726f5d44ac98b4f4030c91880486"
 
+[[package]]
+name = "winnow"
+version = "0.7.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21a0236b59786fed61e2a80582dd500fe61f18b5dca67a4a067d0bc9039339cf"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "winsafe"
 version = "0.0.19"
diff --git a/Cargo.toml b/Cargo.toml
index c4b13cc..e749edd 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/*"]
 
 [workspace.package]
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 authors = ["RubyElders.com"]
 description = "A sophisticated Ruby environment manager that orchestrates installations and gem collections with distinguished precision"
diff --git a/README.md b/README.md
index bf7bb7f..e6bed47 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,12 @@ Ruby Butler expects Ruby installations in `~/.rubies/` (the standard location fo
 - `rb exec` / `rb x` - Execute commands within meticulously prepared environments
 - `rb environment` / `rb env` - Display current environment composition
 - `rb sync` - Manually synchronize bundler environments (auto-triggered when needed)
+- `rb run` / `rb r` - Execute project scripts defined in `gem.toml` or `rbproject.toml`
+
+## Configuration
+
+- **`rb.toml`** - Global configuration file (in `%APPDATA%/rb/` or `~/.rb.toml`)
+- **`gem.toml`** or **`rbproject.toml`** - Project-level script definitions and metadata
 
 ## Development
 
diff --git a/crates/rb-cli/Cargo.toml b/crates/rb-cli/Cargo.toml
index 21c93ab..f285554 100644
--- a/crates/rb-cli/Cargo.toml
+++ b/crates/rb-cli/Cargo.toml
@@ -27,6 +27,8 @@ log = "0.4"
 env_logger = "0.11"
 semver = "1.0.26"
 which = "6.0"
+toml = "0.8"
+serde = { version = "1.0", features = ["derive"] }
 
 [dev-dependencies]
 rb-tests = { path = "../rb-tests" }
diff --git a/crates/rb-cli/src/bin/rb.rs b/crates/rb-cli/src/bin/rb.rs
index e5fedb0..26a32ad 100644
--- a/crates/rb-cli/src/bin/rb.rs
+++ b/crates/rb-cli/src/bin/rb.rs
@@ -1,7 +1,7 @@
 use clap::Parser;
 use rb_cli::{
-    Cli, Commands, environment_command, exec_command, init_logger, resolve_search_dir,
-    runtime_command, sync_command,
+    Cli, Commands, environment_command, exec_command, init_command, init_logger,
+    resolve_search_dir, run_command, runtime_command, sync_command,
 };
 use rb_core::butler::{ButlerError, ButlerRuntime};
 
@@ -53,15 +53,35 @@ fn main() {
 
     let cli = Cli::parse();
 
-    // Initialize logger with the effective log level (considering -v/-vv flags)
+    // Initialize logger early with the effective log level (considering -v/-vv flags)
+    // This allows us to see config file loading and merging logs
     init_logger(cli.effective_log_level());
 
+    // Merge config file defaults with CLI arguments
+    let cli = match cli.with_config_defaults() {
+        Ok(cli) => cli,
+        Err(e) => {
+            eprintln!("Configuration error: {}", e);
+            std::process::exit(1);
+        }
+    };
+
+    // Handle init command early - doesn't require Ruby environment
+    if let Commands::Init = cli.command {
+        let current_dir = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."));
+        if let Err(e) = init_command(&current_dir) {
+            eprintln!("{}", e);
+            std::process::exit(1);
+        }
+        return;
+    }
+
     // Handle sync command differently since it doesn't use ButlerRuntime in the same way
     if let Commands::Sync = cli.command {
         if let Err(e) = sync_command(
-            cli.rubies_dir.clone(),
-            cli.ruby_version.clone(),
-            cli.gem_home.clone(),
+            cli.config.rubies_dir.clone(),
+            cli.config.ruby_version.clone(),
+            cli.config.gem_home.clone(),
         ) {
             eprintln!("Sync failed: {}", e);
             std::process::exit(1);
@@ -70,13 +90,13 @@ fn main() {
     }
 
     // Resolve search directory for Ruby installations
-    let rubies_dir = resolve_search_dir(cli.rubies_dir);
+    let rubies_dir = resolve_search_dir(cli.config.rubies_dir);
 
     // Perform comprehensive environment discovery once
     let butler_runtime = match ButlerRuntime::discover_and_compose_with_gem_base(
         rubies_dir,
-        cli.ruby_version,
-        cli.gem_home,
+        cli.config.ruby_version,
+        cli.config.gem_home,
     ) {
         Ok(runtime) => runtime,
         Err(e) => match e {
@@ -109,11 +129,18 @@ fn main() {
             runtime_command(&butler_runtime);
         }
         Commands::Environment => {
-            environment_command(&butler_runtime);
+            environment_command(&butler_runtime, cli.project_file);
         }
         Commands::Exec { args } => {
             exec_command(butler_runtime, args);
         }
+        Commands::Run { script, args } => {
+            run_command(butler_runtime, script, args, cli.project_file);
+        }
+        Commands::Init => {
+            // Already handled above
+            unreachable!()
+        }
         Commands::Sync => {
             // Already handled above
             unreachable!()
diff --git a/crates/rb-cli/src/commands/environment.rs b/crates/rb-cli/src/commands/environment.rs
index f954558..967ccc5 100644
--- a/crates/rb-cli/src/commands/environment.rs
+++ b/crates/rb-cli/src/commands/environment.rs
@@ -1,15 +1,17 @@
 use colored::*;
-use log::{debug, info};
+use log::{debug, info, warn};
 use rb_core::bundler::BundlerRuntime;
 use rb_core::butler::ButlerRuntime;
+use rb_core::project::{ProjectRuntime, RbprojectDetector};
 use rb_core::ruby::RubyType;
+use std::path::PathBuf;
 
-pub fn environment_command(butler_runtime: &ButlerRuntime) {
+pub fn environment_command(butler_runtime: &ButlerRuntime, project_file: Option<PathBuf>) {
     info!("Presenting current Ruby environment from the working directory");
-    present_current_environment(butler_runtime);
+    present_current_environment(butler_runtime, project_file);
 }
 
-fn present_current_environment(butler_runtime: &ButlerRuntime) {
+fn present_current_environment(butler_runtime: &ButlerRuntime, project_file: Option<PathBuf>) {
     println!("{}", "🌍 Your Current Ruby Environment".to_string().bold());
     println!();
 
@@ -26,14 +28,60 @@ fn present_current_environment(butler_runtime: &ButlerRuntime) {
     // Get gem runtime from butler runtime
     let gem_runtime = butler_runtime.gem_runtime();
 
+    // Detect or load project runtime
+    let project_runtime = if let Some(path) = project_file {
+        // Use specified project file
+        debug!(
+            "Loading project config from specified path: {}",
+            path.display()
+        );
+        match ProjectRuntime::from_file(&path) {
+            Ok(project) => {
+                debug!(
+                    "Loaded {} with {} scripts",
+                    project.config_filename,
+                    project.scripts.len()
+                );
+                Some(project)
+            }
+            Err(e) => {
+                warn!(
+                    "Failed to load specified project config at {}: {}",
+                    path.display(),
+                    e
+                );
+                None
+            }
+        }
+    } else {
+        // Auto-detect project file
+        RbprojectDetector::discover(current_dir)
+            .ok()
+            .flatten()
+            .inspect(|project| {
+                debug!(
+                    "Discovered {} with {} scripts",
+                    project.config_filename,
+                    project.scripts.len()
+                );
+            })
+    };
+
     // Present the environment
-    present_environment_details(ruby, gem_runtime, bundler_runtime, butler_runtime);
+    present_environment_details(
+        ruby,
+        gem_runtime,
+        bundler_runtime,
+        project_runtime.as_ref(),
+        butler_runtime,
+    );
 }
 
 fn present_environment_details(
     ruby: &rb_core::ruby::RubyRuntime,
     gem_runtime: Option<&rb_core::gems::GemRuntime>,
     bundler_runtime: Option<&BundlerRuntime>,
+    project_runtime: Option<&ProjectRuntime>,
     butler: &ButlerRuntime,
 ) {
     let label_width = [
@@ -189,6 +237,79 @@ fn present_environment_details(
         println!("    {}", "Bundler environment not detected".bright_black());
     }
 
+    // Present Project Environment (if detected)
+    if let Some(project) = project_runtime {
+        println!();
+        println!("{}", "📋 Project".green().bold());
+
+        // Display project name if available
+        if let Some(name) = &project.metadata.name {
+            println!(
+                "    {:<width$}: {}",
+                "Name".bright_blue().bold(),
+                name.bright_black(),
+                width = label_width
+            );
+        }
+
+        // Display project description if available
+        if let Some(description) = &project.metadata.description {
+            println!(
+                "    {:<width$}: {}",
+                "Description".bright_blue().bold(),
+                description.bright_black(),
+                width = label_width
+            );
+        }
+
+        println!(
+            "    {:<width$}: {}",
+            "Project file".bright_blue().bold(),
+            project
+                .rbproject_path()
+                .display()
+                .to_string()
+                .bright_black(),
+            width = label_width
+        );
+
+        println!(
+            "    {:<width$}: {}",
+            "Scripts loaded".bright_blue().bold(),
+            format!("{}", project.scripts.len()).bright_black(),
+            width = label_width
+        );
+
+        if !project.scripts.is_empty() {
+            println!();
+            println!("    {}", "Available Scripts:".bright_blue().bold());
+
+            // Get sorted script names for consistent display
+            let script_names = project.script_names();
+            for name in script_names {
+                let script = project.get_script(name).unwrap();
+                let command = script.command();
+
+                // Always show: name → command
+                println!(
+                    "      {} {} {}",
+                    name.cyan().bold(),
+                    "→".bright_black(),
+                    command.to_string().bright_black()
+                );
+
+                // Optionally show description on next line with more indent
+                if let Some(description) = script.description() {
+                    println!("        {}", description.bright_black().italic());
+                }
+            }
+        }
+    } else {
+        println!();
+        println!("{}", "📋 Project Scripts".bright_black());
+        println!("    {}", "No project config detected".bright_black());
+    }
+
     // Present environment summary
     println!();
     println!("{}", "🎯 Environment Summary".green().bold());
@@ -262,7 +383,7 @@ mod tests {
                 .expect("Failed to create butler runtime with test Ruby");
 
         // This will handle the environment presentation gracefully
-        environment_command(&butler_runtime);
+        environment_command(&butler_runtime, None);
     }
 
     #[test]
@@ -283,7 +404,7 @@ mod tests {
         let butler = ButlerRuntime::new(ruby.clone(), Some(gem_runtime.clone()));
 
         // Test with no bundler environment
-        present_environment_details(&ruby, Some(&gem_runtime), None, &butler);
+        present_environment_details(&ruby, Some(&gem_runtime), None, None, &butler);
 
         Ok(())
     }
@@ -310,7 +431,62 @@ mod tests {
         let butler = ButlerRuntime::new(ruby.clone(), Some(gem_runtime.clone()));
 
         // Test with bundler environment
-        present_environment_details(&ruby, Some(&gem_runtime), Some(&bundler_runtime), &butler);
+        present_environment_details(
+            &ruby,
+            Some(&gem_runtime),
+            Some(&bundler_runtime),
+            None,
+            &butler,
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn present_environment_details_with_project() -> std::io::Result<()> {
+        use rb_core::gems::GemRuntime;
+        use rb_core::project::{ProjectMetadata, ScriptDefinition};
+        use rb_tests::RubySandbox;
+        use std::collections::HashMap;
+
+        let ruby_sandbox = RubySandbox::new()?;
+        let ruby_dir = ruby_sandbox.add_ruby_dir("3.2.5")?;
+        let ruby = rb_core::ruby::RubyRuntime::new(
+            rb_core::ruby::RubyType::CRuby,
+            semver::Version::parse("3.2.5").unwrap(),
+            &ruby_dir,
+        );
+
+        // Create a project runtime with some scripts
+        let mut scripts = HashMap::new();
+        scripts.insert(
+            "test".to_string(),
+            ScriptDefinition::Detailed {
+                command: "rspec".to_string(),
+                description: Some("Run the test suite".to_string()),
+            },
+        );
+        scripts.insert(
+            "lint:fix".to_string(),
+            ScriptDefinition::Simple("rubocop -a".to_string()),
+        );
+
+        let metadata = ProjectMetadata::default();
+        let project_runtime =
+            ProjectRuntime::new(ruby_sandbox.root(), "rbproject.toml", metadata, scripts);
+
+        // Use sandboxed gem directory
+        let gem_runtime = GemRuntime::for_base_dir(&ruby_sandbox.gem_base_dir(), &ruby.version);
+        let butler = ButlerRuntime::new(ruby.clone(), Some(gem_runtime.clone()));
+
+        // Test with project environment
+        present_environment_details(
+            &ruby,
+            Some(&gem_runtime),
+            None,
+            Some(&project_runtime),
+            &butler,
+        );
 
         Ok(())
     }
diff --git a/crates/rb-cli/src/commands/init.rs b/crates/rb-cli/src/commands/init.rs
new file mode 100644
index 0000000..d1e296c
--- /dev/null
+++ b/crates/rb-cli/src/commands/init.rs
@@ -0,0 +1,114 @@
+use std::fs;
+use std::path::Path;
+
+const DEFAULT_RBPROJECT_TOML: &str = r#"[project]
+name = "Butler project template"
+description = "Please fill in"
+
+[scripts]
+ruby-version = "ruby -v"
+"#;
+
+/// Initialize a new rbproject.toml in the current directory
+pub fn init_command(current_dir: &Path) -> Result<(), String> {
+    let project_file = current_dir.join("rbproject.toml");
+
+    // Check if file already exists
+    if project_file.exists() {
+        return Err(
+            "🎩 My sincerest apologies, but an rbproject.toml file already graces\n\
+             this directory with its presence.\n\n\
+             This humble Butler cannot overwrite existing project configurations\n\
+             without explicit instruction, as such an action would be most improper.\n\n\
+             If you wish to recreate the file, kindly delete the existing one first."
+                .to_string(),
+        );
+    }
+
+    // Write the default template
+    fs::write(&project_file, DEFAULT_RBPROJECT_TOML)
+        .map_err(|e| format!("Failed to create rbproject.toml: {}", e))?;
+
+    println!("✨ Splendid! A new rbproject.toml has been created with appropriate ceremony.");
+    println!();
+    println!("📝 This template includes:");
+    println!("   • Project metadata (name and description)");
+    println!("   • A sample script (ruby-version) to demonstrate usage");
+    println!();
+    println!("🎯 You may now:");
+    println!("   • Edit rbproject.toml to add your own scripts");
+    println!("   • Run 'rb run' to list available scripts");
+    println!("   • Execute scripts with: rb run <script-name>");
+    println!();
+    println!("For comprehensive examples, please consult:");
+    println!("   https://github.com/RubyElders/ruby-butler/blob/main/examples/rbproject.toml");
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    #[test]
+    fn test_init_creates_rbproject_toml() {
+        let temp_dir = std::env::temp_dir().join(format!("rb-init-test-{}", std::process::id()));
+        fs::create_dir_all(&temp_dir).unwrap();
+
+        let result = init_command(&temp_dir);
+
+        assert!(result.is_ok());
+        let project_file = temp_dir.join("rbproject.toml");
+        assert!(project_file.exists());
+
+        let content = fs::read_to_string(&project_file).unwrap();
+        assert!(content.contains("[project]"));
+        assert!(content.contains("name = \"Butler project template\""));
+        assert!(content.contains("[scripts]"));
+        assert!(content.contains("ruby-version = \"ruby -v\""));
+
+        // Cleanup
+        fs::remove_dir_all(&temp_dir).ok();
+    }
+
+    #[test]
+    fn test_init_fails_if_file_exists() {
+        let temp_dir =
+            std::env::temp_dir().join(format!("rb-init-test-exists-{}", std::process::id()));
+        fs::create_dir_all(&temp_dir).unwrap();
+        let project_file = temp_dir.join("rbproject.toml");
+
+        // Create existing file
+        fs::write(&project_file, "existing content").unwrap();
+
+        let result = init_command(&temp_dir);
+        assert!(result.is_err());
+        let error = result.unwrap_err();
+        assert!(error.contains("already graces"));
+        assert!(error.contains("this directory"));
+
+        // Cleanup
+        fs::remove_dir_all(&temp_dir).ok();
+    }
+
+    #[test]
+    fn test_init_creates_valid_toml() {
+        let temp_dir =
+            std::env::temp_dir().join(format!("rb-init-test-valid-{}", std::process::id()));
+        fs::create_dir_all(&temp_dir).unwrap();
+
+        let result = init_command(&temp_dir);
+
+        assert!(result.is_ok());
+        let project_file = temp_dir.join("rbproject.toml");
+        let content = fs::read_to_string(&project_file).unwrap();
+
+        // Verify it's valid TOML
+        let parsed: Result<toml::Value, _> = toml::from_str(&content);
+        assert!(parsed.is_ok(), "Generated TOML should be valid");
+
+        // Cleanup
+        fs::remove_dir_all(&temp_dir).ok();
+    }
+}
diff --git a/crates/rb-cli/src/commands/mod.rs b/crates/rb-cli/src/commands/mod.rs
index 17bcba3..215b1e1 100644
--- a/crates/rb-cli/src/commands/mod.rs
+++ b/crates/rb-cli/src/commands/mod.rs
@@ -1,9 +1,13 @@
 pub mod environment;
 pub mod exec;
+pub mod init;
+pub mod run;
 pub mod runtime;
 pub mod sync;
 
 pub use environment::environment_command;
 pub use exec::exec_command;
+pub use init::init_command;
+pub use run::run_command;
 pub use runtime::runtime_command;
 pub use sync::sync_command;
diff --git a/crates/rb-cli/src/commands/run.rs b/crates/rb-cli/src/commands/run.rs
new file mode 100644
index 0000000..531175a
--- /dev/null
+++ b/crates/rb-cli/src/commands/run.rs
@@ -0,0 +1,434 @@
+use colored::*;
+use log::{debug, info, warn};
+use rb_core::butler::ButlerRuntime;
+use rb_core::project::{ProjectRuntime, RbprojectDetector};
+use std::path::PathBuf;
+
+use super::exec::exec_command;
+
+fn list_available_scripts(butler_runtime: ButlerRuntime, project_file: Option<PathBuf>) {
+    info!("Listing available project scripts");
+
+    // Detect or load project runtime
+    let current_dir = butler_runtime.current_dir();
+    let project_runtime = if let Some(path) = project_file {
+        // Use specified project file
+        debug!(
+            "Loading project config from specified path: {}",
+            path.display()
+        );
+        match ProjectRuntime::from_file(&path) {
+            Ok(project) => Some(project),
+            Err(e) => {
+                eprintln!("{}", "❌ Selection Failed".red().bold());
+                eprintln!();
+                eprintln!("The specified project configuration could not be loaded:");
+                eprintln!("  File: {}", path.display().to_string().bright_black());
+                eprintln!("  Error: {}", e.to_string().bright_black());
+                eprintln!();
+                eprintln!("Please verify the file exists and contains valid TOML configuration.");
+                std::process::exit(1);
+            }
+        }
+    } else {
+        // Auto-detect project file
+        match RbprojectDetector::discover(current_dir) {
+            Ok(Some(project)) => {
+                debug!(
+                    "Discovered {} with {} scripts",
+                    project.config_filename,
+                    project.scripts.len()
+                );
+                Some(project)
+            }
+            Ok(None) => None,
+            Err(e) => {
+                warn!("Error detecting project config: {}", e);
+                None
+            }
+        }
+    };
+
+    // Ensure we have a project configuration
+    let project = match project_runtime {
+        Some(p) => p,
+        None => {
+            eprintln!("{}", "❌ No Project Configuration".red().bold());
+            eprintln!();
+            eprintln!("No project configuration detected in the current directory hierarchy.");
+            eprintln!();
+            eprintln!(
+                "To define project scripts, create an {} or {} file:",
+                "rbproject.toml".cyan(),
+                "gem.toml".cyan()
+            );
+            eprintln!();
+            eprintln!("  {}", "[scripts]".bright_black());
+            eprintln!("  {} = {}", "test".cyan(), "\"rspec\"".bright_black());
+            eprintln!(
+                "  {} = {{ command = {}, description = {} }}",
+                "lint".cyan(),
+                "\"rubocop\"".bright_black(),
+                "\"Check code quality\"".bright_black()
+            );
+            eprintln!();
+            eprintln!(
+                "Or specify a custom location: {} -P path/to/rbproject.toml run",
+                "rb".green().bold()
+            );
+            std::process::exit(1);
+        }
+    };
+
+    // Display help-style output
+    println!("{}", "🎯 Run Project Scripts".green().bold());
+    println!();
+
+    // Show project metadata if available
+    if let Some(name) = &project.metadata.name {
+        println!("{}", name);
+    }
+
+    if let Some(description) = &project.metadata.description {
+        println!("{}", description.bright_black());
+    }
+
+    if project.metadata.name.is_some() || project.metadata.description.is_some() {
+        println!();
+    }
+
+    // Usage section
+    println!("{}", "Usage:".green().bold());
+    println!("  rb run <SCRIPT> [ARGS]...");
+    println!();
+
+    let available_scripts = project.script_names();
+    let script_count = available_scripts.len();
+
+    if available_scripts.is_empty() {
+        println!("{}", "Scripts:".green().bold());
+        println!("  {}", "No scripts defined.".bright_black());
+        println!();
+        println!(
+            "To define scripts, add them to {}:",
+            project.config_filename.cyan()
+        );
+        println!();
+        println!("  {}", "[scripts]".bright_black());
+        println!("  {} = {}", "test".cyan(), "\"rspec\"".bright_black());
+        println!(
+            "  {} = {{ command = {}, description = {} }}",
+            "lint".cyan(),
+            "\"rubocop\"".bright_black(),
+            "\"Check code quality\"".bright_black()
+        );
+    } else {
+        // Scripts section - formatted like Clap's Commands section
+        println!("{}", "Scripts:".green().bold());
+
+        // Calculate max width for alignment
+        let max_name_width = available_scripts.iter().map(|s| s.len()).max().unwrap_or(0);
+
+        for name in available_scripts {
+            let script = project.get_script(name).unwrap();
+            let command = script.command();
+
+            if let Some(description) = script.description() {
+                // Show: name  description
+                println!(
+                    "  {:<width$}  {}",
+                    name.cyan().bold(),
+                    description.bright_black(),
+                    width = max_name_width
+                );
+            } else {
+                // Show: name  command
+                println!(
+                    "  {:<width$}  {}",
+                    name.cyan().bold(),
+                    command.bright_black(),
+                    width = max_name_width
+                );
+            }
+        }
+
+        println!();
+        println!("{}", "Details:".green().bold());
+        println!(
+            "  {}: {}",
+            "Project".bright_black(),
+            project
+                .rbproject_path()
+                .display()
+                .to_string()
+                .bright_black()
+        );
+        println!(
+            "  {}: {}",
+            "Scripts".bright_black(),
+            script_count.to_string().bright_black()
+        );
+    }
+}
+
+pub fn run_command(
+    butler_runtime: ButlerRuntime,
+    script_name: Option<String>,
+    args: Vec<String>,
+    project_file: Option<PathBuf>,
+) {
+    // If no script name provided, list available scripts
+    if script_name.is_none() {
+        list_available_scripts(butler_runtime, project_file);
+        return;
+    }
+
+    let script_name = script_name.unwrap();
+    info!(
+        "Executing project script '{}' with distinguished precision",
+        script_name
+    );
+
+    // Detect or load project runtime
+    let current_dir = butler_runtime.current_dir();
+    let project_runtime = if let Some(path) = project_file {
+        // Use specified project file
+        debug!(
+            "Loading project config from specified path: {}",
+            path.display()
+        );
+        match ProjectRuntime::from_file(&path) {
+            Ok(project) => Some(project),
+            Err(e) => {
+                eprintln!("{}", "❌ Selection Failed".red().bold());
+                eprintln!();
+                eprintln!("The specified project configuration could not be loaded:");
+                eprintln!("  File: {}", path.display().to_string().bright_black());
+                eprintln!("  Error: {}", e.to_string().bright_black());
+                eprintln!();
+                eprintln!("Please verify the file exists and contains valid TOML configuration.");
+                std::process::exit(1);
+            }
+        }
+    } else {
+        // Auto-detect project file
+        match RbprojectDetector::discover(current_dir) {
+            Ok(Some(project)) => {
+                debug!(
+                    "Discovered {} with {} scripts",
+                    project.config_filename,
+                    project.scripts.len()
+                );
+                Some(project)
+            }
+            Ok(None) => None,
+            Err(e) => {
+                warn!("Error detecting project config: {}", e);
+                None
+            }
+        }
+    };
+
+    // Ensure we have a project configuration
+    let project = match project_runtime {
+        Some(p) => p,
+        None => {
+            eprintln!("{}", "❌ Selection Failed".red().bold());
+            eprintln!();
+            eprintln!("No project configuration detected in the current directory hierarchy.");
+            eprintln!();
+            eprintln!(
+                "To use project scripts, please create an {} or {} file with script definitions:",
+                "rbproject.toml".cyan(),
+                "gem.toml".cyan()
+            );
+            eprintln!();
+            eprintln!("  {}", "[scripts]".bright_black());
+            eprintln!("  {} = {}", "test".cyan(), "\"rspec\"".bright_black());
+            eprintln!(
+                "  {} = {{ command = {}, description = {} }}",
+                "lint".cyan(),
+                "\"rubocop\"".bright_black(),
+                "\"Check code quality\"".bright_black()
+            );
+            eprintln!();
+            eprintln!(
+                "Or specify a custom location with: {} -P path/to/rbproject.toml run {}",
+                "rb".green().bold(),
+                script_name.cyan()
+            );
+            std::process::exit(1);
+        }
+    };
+
+    // Look up the script
+    if !project.has_script(&script_name) {
+        eprintln!("{}", "❌ Script Not Found".red().bold());
+        eprintln!();
+        eprintln!(
+            "The script '{}' is not defined in your project configuration.",
+            script_name.cyan().bold()
+        );
+        eprintln!();
+
+        let available_scripts = project.script_names();
+        if available_scripts.is_empty() {
+            eprintln!(
+                "No scripts are currently defined in {}.",
+                project
+                    .rbproject_path()
+                    .display()
+                    .to_string()
+                    .bright_black()
+            );
+        } else {
+            eprintln!(
+                "Available scripts from {}:",
+                project
+                    .rbproject_path()
+                    .display()
+                    .to_string()
+                    .bright_black()
+            );
+            eprintln!();
+            for name in available_scripts {
+                let script = project.get_script(name).unwrap();
+                let command = script.command();
+                eprintln!(
+                    "  {} {} {}",
+                    name.cyan().bold(),
+                    "→".bright_black(),
+                    command.bright_black()
+                );
+                if let Some(description) = script.description() {
+                    eprintln!("    {}", description.bright_black().italic());
+                }
+            }
+        }
+        eprintln!();
+        eprintln!(
+            "Run {} to see all available scripts.",
+            "rb env".green().bold()
+        );
+        std::process::exit(1);
+    }
+
+    // Get the script command
+    let command_str = project.get_script_command(&script_name).unwrap();
+
+    info!("Executing script: {} → {}", script_name, command_str);
+
+    // Parse the command string into program and arguments using shell word splitting
+    let command_parts = parse_command(command_str);
+
+    if command_parts.is_empty() {
+        eprintln!("{}", "❌ Invalid Script".red().bold());
+        eprintln!();
+        eprintln!(
+            "The script '{}' has an empty command.",
+            script_name.cyan().bold()
+        );
+        std::process::exit(1);
+    }
+
+    // Build the full argument list: parsed command parts + user-provided args
+    let mut full_args = command_parts;
+    full_args.extend(args);
+
+    info!("Delegating to exec command with args: {:?}", full_args);
+
+    // Delegate to exec_command - this ensures consistent behavior including:
+    // - Automatic bundle exec detection
+    // - Bundler environment synchronization
+    // - Proper environment composition
+    // - Command validation and error handling
+    exec_command(butler_runtime, full_args);
+}
+
+/// Parse a command string into program and arguments
+/// This is a simple whitespace-based parser that respects quotes
+fn parse_command(command: &str) -> Vec<String> {
+    let mut parts = Vec::new();
+    let mut current = String::new();
+    let mut in_quotes = false;
+
+    for ch in command.chars() {
+        match ch {
+            '"' => {
+                in_quotes = !in_quotes;
+            }
+            ' ' if !in_quotes => {
+                if !current.is_empty() {
+                    parts.push(current.clone());
+                    current.clear();
+                }
+            }
+            _ => {
+                current.push(ch);
+            }
+        }
+    }
+
+    if !current.is_empty() {
+        parts.push(current);
+    }
+
+    parts
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_command_simple() {
+        assert_eq!(
+            parse_command("ruby -v"),
+            vec!["ruby".to_string(), "-v".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_parse_command_with_multiple_args() {
+        assert_eq!(
+            parse_command("gem install bundler --version 2.4.0"),
+            vec![
+                "gem".to_string(),
+                "install".to_string(),
+                "bundler".to_string(),
+                "--version".to_string(),
+                "2.4.0".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn test_parse_command_with_quotes() {
+        assert_eq!(
+            parse_command("rails new \"my app\""),
+            vec!["rails".to_string(), "new".to_string(), "my app".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_parse_command_with_extra_spaces() {
+        assert_eq!(
+            parse_command("ruby  -e   \"puts 'hello'\""),
+            vec![
+                "ruby".to_string(),
+                "-e".to_string(),
+                "puts 'hello'".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn test_parse_command_empty() {
+        assert_eq!(parse_command(""), Vec::<String>::new());
+    }
+
+    #[test]
+    fn test_parse_command_only_spaces() {
+        assert_eq!(parse_command("   "), Vec::<String>::new());
+    }
+}
diff --git a/crates/rb-cli/src/config/loader.rs b/crates/rb-cli/src/config/loader.rs
new file mode 100644
index 0000000..deaa503
--- /dev/null
+++ b/crates/rb-cli/src/config/loader.rs
@@ -0,0 +1,81 @@
+use super::locator::locate_config_file;
+use super::{ConfigError, RbConfig};
+use log::{debug, info};
+use std::fs;
+use std::path::PathBuf;
+
+/// Load configuration from file
+/// Returns default config if no file is found
+///
+/// # Arguments
+/// * `override_path` - Optional path to explicitly load config from (for testing)
+pub fn load_config(override_path: Option<PathBuf>) -> Result<RbConfig, ConfigError> {
+    if let Some(config_path) = locate_config_file(override_path.clone()) {
+        info!("Loading configuration from: {}", config_path.display());
+
+        let contents = fs::read_to_string(&config_path)?;
+        let config: RbConfig = toml::from_str(&contents)?;
+
+        // Log what was loaded
+        debug!("Configuration file contents parsed successfully");
+        if let Some(ref dir) = config.rubies_dir {
+            debug!("  rubies-dir: {}", dir.display());
+        }
+        if let Some(ref version) = config.ruby_version {
+            debug!("  ruby-version: {}", version);
+        }
+        if let Some(ref home) = config.gem_home {
+            debug!("  gem-home: {}", home.display());
+        }
+
+        Ok(config)
+    } else {
+        if override_path.is_some() {
+            debug!("Specified configuration file not found, using defaults");
+        } else {
+            debug!("No configuration file found in default locations, using defaults");
+        }
+        Ok(RbConfig::default())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_load_config_returns_default_when_no_file() {
+        // Should return default config when no file exists
+        let result = load_config(None);
+        assert!(result.is_ok());
+
+        let config = result.unwrap();
+        assert!(config.rubies_dir.is_none());
+        assert!(config.ruby_version.is_none());
+        assert!(config.gem_home.is_none());
+    }
+
+    #[test]
+    fn test_load_config_with_custom_path() {
+        use std::fs;
+        use std::io::Write;
+
+        let temp_dir = std::env::temp_dir();
+        let config_path = temp_dir.join("test_rb_custom.toml");
+
+        // Create a test config file
+        let mut file = fs::File::create(&config_path).expect("Failed to create test config");
+        writeln!(file, r#"ruby-version = "3.2.0""#).expect("Failed to write config");
+        drop(file);
+
+        // Load config from custom path
+        let result = load_config(Some(config_path.clone()));
+        assert!(result.is_ok());
+
+        let config = result.unwrap();
+        assert_eq!(config.ruby_version, Some("3.2.0".to_string()));
+
+        // Cleanup
+        let _ = fs::remove_file(&config_path);
+    }
+}
diff --git a/crates/rb-cli/src/config/locator.rs b/crates/rb-cli/src/config/locator.rs
new file mode 100644
index 0000000..70cddd5
--- /dev/null
+++ b/crates/rb-cli/src/config/locator.rs
@@ -0,0 +1,139 @@
+use log::debug;
+use std::path::PathBuf;
+
+/// Locate the configuration file following XDG Base Directory specification
+///
+/// Priority order:
+/// 1. Explicit override path (if provided)
+/// 2. $RB_CONFIG environment variable
+/// 3. $XDG_CONFIG_HOME/rb/rb.toml (Unix/Linux)
+/// 4. ~/.config/rb/rb.toml (Unix/Linux fallback)
+/// 5. %APPDATA%/rb/rb.toml (Windows)
+/// 6. ~/.rb.toml (cross-platform fallback)
+pub fn locate_config_file(override_path: Option<PathBuf>) -> Option<PathBuf> {
+    debug!("Searching for configuration file...");
+
+    // 1. Check for explicit override first
+    if let Some(path) = override_path {
+        debug!("  Checking --config override: {}", path.display());
+        if path.exists() {
+            debug!("  Found configuration file via --config flag");
+            return Some(path);
+        }
+    }
+
+    // 2. Check RB_CONFIG environment variable
+    if let Ok(rb_config) = std::env::var("RB_CONFIG") {
+        let config_path = PathBuf::from(rb_config);
+        debug!("  Checking RB_CONFIG env var: {}", config_path.display());
+        if config_path.exists() {
+            debug!("  Found configuration file via RB_CONFIG");
+            return Some(config_path);
+        }
+    }
+
+    // 3. Try XDG_CONFIG_HOME (Unix/Linux)
+    if let Ok(xdg_config) = std::env::var("XDG_CONFIG_HOME") {
+        let config_path = PathBuf::from(xdg_config).join("rb").join("rb.toml");
+        debug!("  Checking XDG_CONFIG_HOME: {}", config_path.display());
+        if config_path.exists() {
+            debug!("  Found configuration file in XDG_CONFIG_HOME");
+            return Some(config_path);
+        }
+    }
+
+    // Try home directory based paths
+    if let Some(home_dir) = home::home_dir() {
+        // Unix/Linux: ~/.config/rb/rb.toml
+        #[cfg(not(target_os = "windows"))]
+        {
+            let config_path = home_dir.join(".config").join("rb").join("rb.toml");
+            debug!("  Checking ~/.config/rb/rb.toml: {}", config_path.display());
+            if config_path.exists() {
+                debug!("  Found configuration file in ~/.config/rb/");
+                return Some(config_path);
+            }
+        }
+
+        // Windows: %APPDATA%/rb/rb.toml
+        #[cfg(target_os = "windows")]
+        {
+            if let Ok(appdata) = std::env::var("APPDATA") {
+                let config_path = PathBuf::from(appdata).join("rb").join("rb.toml");
+                debug!("  Checking %APPDATA%/rb/rb.toml: {}", config_path.display());
+                if config_path.exists() {
+                    debug!("  Found configuration file in %APPDATA%/rb/");
+                    return Some(config_path);
+                }
+            }
+        }
+
+        // Cross-platform fallback: ~/.rb.toml
+        let fallback_path = home_dir.join(".rb.toml");
+        debug!(
+            "  Checking fallback ~/.rb.toml: {}",
+            fallback_path.display()
+        );
+        if fallback_path.exists() {
+            debug!("  Found configuration file at ~/.rb.toml");
+            return Some(fallback_path);
+        }
+    }
+
+    debug!("  No configuration file found in any location");
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_locate_config_file_returns_option() {
+        // Should not panic even if no config exists
+        let result = locate_config_file(None);
+        assert!(result.is_none() || result.is_some());
+    }
+
+    #[test]
+    fn test_locate_config_file_with_override() {
+        use std::fs;
+        let temp_dir = std::env::temp_dir();
+        let config_path = temp_dir.join("test_rb_override.toml");
+
+        // Create a temporary config file
+        fs::write(&config_path, "# test config").expect("Failed to write test config");
+
+        // Should return the override path
+        let result = locate_config_file(Some(config_path.clone()));
+        assert_eq!(result, Some(config_path.clone()));
+
+        // Cleanup
+        let _ = fs::remove_file(&config_path);
+    }
+
+    #[test]
+    fn test_locate_config_file_with_env_var() {
+        use std::fs;
+        let temp_dir = std::env::temp_dir();
+        let config_path = temp_dir.join("test_rb_env.toml");
+
+        // Create a temporary config file
+        fs::write(&config_path, "# test config").expect("Failed to write test config");
+
+        // Set environment variable (unsafe but required for testing)
+        unsafe {
+            std::env::set_var("RB_CONFIG", &config_path);
+        }
+
+        // Should return the env var path
+        let result = locate_config_file(None);
+        assert_eq!(result, Some(config_path.clone()));
+
+        // Cleanup
+        unsafe {
+            std::env::remove_var("RB_CONFIG");
+        }
+        let _ = fs::remove_file(&config_path);
+    }
+}
diff --git a/crates/rb-cli/src/config/mod.rs b/crates/rb-cli/src/config/mod.rs
new file mode 100644
index 0000000..4cf20d7
--- /dev/null
+++ b/crates/rb-cli/src/config/mod.rs
@@ -0,0 +1,214 @@
+pub mod loader;
+pub mod locator;
+
+use clap::Args;
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+/// Shared configuration for both CLI and TOML
+/// This struct serves both purposes:
+/// - CLI argument parsing via clap::Args
+/// - TOML deserialization via serde::Deserialize
+#[derive(Debug, Clone, Args, Deserialize, Serialize, Default)]
+pub struct RbConfig {
+    /// Designate the directory containing your Ruby installations
+    #[arg(
+        short = 'R',
+        long = "rubies-dir",
+        global = true,
+        help = "Designate the directory containing your Ruby installations (default: ~/.rubies)"
+    )]
+    #[serde(rename = "rubies-dir", skip_serializing_if = "Option::is_none")]
+    pub rubies_dir: Option<PathBuf>,
+
+    /// Request a particular Ruby version for your environment
+    #[arg(
+        short = 'r',
+        long = "ruby",
+        global = true,
+        help = "Request a particular Ruby version for your environment (defaults to latest available)"
+    )]
+    #[serde(rename = "ruby-version", skip_serializing_if = "Option::is_none")]
+    pub ruby_version: Option<String>,
+
+    /// Specify custom gem base directory
+    #[arg(
+        short = 'G',
+        long = "gem-home",
+        global = true,
+        help = "Specify custom gem base directory for gem installations (default: ~/.gem)"
+    )]
+    #[serde(rename = "gem-home", skip_serializing_if = "Option::is_none")]
+    pub gem_home: Option<PathBuf>,
+}
+
+impl RbConfig {
+    /// Merge two configs, preferring values from self
+    /// Used to merge CLI args (self) with file config (other)
+    pub fn merge_with(&mut self, other: RbConfig) {
+        use log::debug;
+
+        debug!("Merging configuration (CLI arguments take precedence over config file)");
+
+        if self.rubies_dir.is_none() {
+            if let Some(ref dir) = other.rubies_dir {
+                debug!("  Using rubies-dir from config file: {}", dir.display());
+                self.rubies_dir = other.rubies_dir;
+            }
+        } else {
+            debug!(
+                "  Using rubies-dir from CLI arguments: {}",
+                self.rubies_dir.as_ref().unwrap().display()
+            );
+        }
+
+        if self.ruby_version.is_none() {
+            if let Some(ref version) = other.ruby_version {
+                debug!("  Using ruby-version from config file: {}", version);
+                self.ruby_version = other.ruby_version;
+            }
+        } else {
+            debug!(
+                "  Using ruby-version from CLI arguments: {}",
+                self.ruby_version.as_ref().unwrap()
+            );
+        }
+
+        if self.gem_home.is_none() {
+            if let Some(ref home) = other.gem_home {
+                debug!("  Using gem-home from config file: {}", home.display());
+                self.gem_home = other.gem_home;
+            }
+        } else {
+            debug!(
+                "  Using gem-home from CLI arguments: {}",
+                self.gem_home.as_ref().unwrap().display()
+            );
+        }
+    }
+}
+
+#[derive(Debug)]
+pub enum ConfigError {
+    IoError(std::io::Error),
+    ParseError(toml::de::Error),
+}
+
+impl std::fmt::Display for ConfigError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ConfigError::IoError(e) => write!(f, "Failed to read configuration file: {}", e),
+            ConfigError::ParseError(e) => write!(f, "Failed to parse configuration file: {}", e),
+        }
+    }
+}
+
+impl std::error::Error for ConfigError {}
+
+impl From<std::io::Error> for ConfigError {
+    fn from(err: std::io::Error) -> Self {
+        ConfigError::IoError(err)
+    }
+}
+
+impl From<toml::de::Error> for ConfigError {
+    fn from(err: toml::de::Error) -> Self {
+        ConfigError::ParseError(err)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_merge_with_empty_cli_config() {
+        let mut cli_config = RbConfig::default();
+        let file_config = RbConfig {
+            rubies_dir: Some(PathBuf::from("/test/rubies")),
+            ruby_version: Some("3.3.0".to_string()),
+            gem_home: Some(PathBuf::from("/test/gems")),
+        };
+
+        cli_config.merge_with(file_config);
+
+        assert_eq!(cli_config.rubies_dir, Some(PathBuf::from("/test/rubies")));
+        assert_eq!(cli_config.ruby_version, Some("3.3.0".to_string()));
+        assert_eq!(cli_config.gem_home, Some(PathBuf::from("/test/gems")));
+    }
+
+    #[test]
+    fn test_merge_with_cli_takes_precedence() {
+        let mut cli_config = RbConfig {
+            rubies_dir: Some(PathBuf::from("/cli/rubies")),
+            ruby_version: Some("3.2.0".to_string()),
+            gem_home: None,
+        };
+        let file_config = RbConfig {
+            rubies_dir: Some(PathBuf::from("/file/rubies")),
+            ruby_version: Some("3.3.0".to_string()),
+            gem_home: Some(PathBuf::from("/file/gems")),
+        };
+
+        cli_config.merge_with(file_config);
+
+        // CLI values should be preserved
+        assert_eq!(cli_config.rubies_dir, Some(PathBuf::from("/cli/rubies")));
+        assert_eq!(cli_config.ruby_version, Some("3.2.0".to_string()));
+        // File value should fill in missing CLI value
+        assert_eq!(cli_config.gem_home, Some(PathBuf::from("/file/gems")));
+    }
+
+    #[test]
+    fn test_merge_with_partial_file_config() {
+        let mut cli_config = RbConfig {
+            rubies_dir: None,
+            ruby_version: Some("3.2.0".to_string()),
+            gem_home: None,
+        };
+        let file_config = RbConfig {
+            rubies_dir: Some(PathBuf::from("/file/rubies")),
+            ruby_version: None,
+            gem_home: Some(PathBuf::from("/file/gems")),
+        };
+
+        cli_config.merge_with(file_config);
+
+        assert_eq!(cli_config.rubies_dir, Some(PathBuf::from("/file/rubies")));
+        assert_eq!(cli_config.ruby_version, Some("3.2.0".to_string()));
+        assert_eq!(cli_config.gem_home, Some(PathBuf::from("/file/gems")));
+    }
+
+    #[test]
+    fn test_toml_deserialization() {
+        let toml_str = r#"
+            rubies-dir = "/opt/rubies"
+            ruby-version = "3.3.0"
+            gem-home = "/opt/gems"
+        "#;
+
+        let config: RbConfig = toml::from_str(toml_str).expect("Failed to parse TOML");
+
+        assert_eq!(config.rubies_dir, Some(PathBuf::from("/opt/rubies")));
+        assert_eq!(config.ruby_version, Some("3.3.0".to_string()));
+        assert_eq!(config.gem_home, Some(PathBuf::from("/opt/gems")));
+    }
+
+    #[test]
+    fn test_toml_serialization() {
+        let config = RbConfig {
+            rubies_dir: Some(PathBuf::from("/opt/rubies")),
+            ruby_version: Some("3.3.0".to_string()),
+            gem_home: Some(PathBuf::from("/opt/gems")),
+        };
+
+        let toml_str = toml::to_string(&config).expect("Failed to serialize to TOML");
+
+        assert!(toml_str.contains("rubies-dir"));
+        assert!(toml_str.contains("/opt/rubies"));
+        assert!(toml_str.contains("ruby-version"));
+        assert!(toml_str.contains("3.3.0"));
+        assert!(toml_str.contains("gem-home"));
+        assert!(toml_str.contains("/opt/gems"));
+    }
+}
diff --git a/crates/rb-cli/src/lib.rs b/crates/rb-cli/src/lib.rs
index 019e873..1e74c17 100644
--- a/crates/rb-cli/src/lib.rs
+++ b/crates/rb-cli/src/lib.rs
@@ -1,8 +1,10 @@
 pub mod commands;
+pub mod config;
 pub mod discovery;
 
 use clap::builder::styling::{AnsiColor, Effects, Styles};
 use clap::{Parser, Subcommand, ValueEnum};
+use config::{ConfigError, RbConfig};
 
 // Configures Clap v4-style help menu colors (same as cargo and uv)
 const STYLES: Styles = Styles::styled()
@@ -56,32 +58,27 @@ pub struct Cli {
     #[arg(short = 'v', long = "verbose", action = clap::ArgAction::Count, global = true, help = "Enhance verbosity gradually (-v for details, -vv for comprehensive diagnostics)")]
     pub verbose: u8,
 
-    /// Designate the directory containing your Ruby installations
+    /// Specify custom configuration file location
     #[arg(
-        short = 'R',
-        long = "rubies-dir",
+        short = 'c',
+        long = "config",
         global = true,
-        help = "Designate the directory containing your Ruby installations (default: ~/.rubies)"
+        help = "Specify custom configuration file location (overrides RB_CONFIG env var and default locations)"
     )]
-    pub rubies_dir: Option<std::path::PathBuf>,
+    pub config_file: Option<std::path::PathBuf>,
 
-    /// Request a particular Ruby version for your environment
+    /// Specify custom project file location
     #[arg(
-        short = 'r',
-        long = "ruby",
+        short = 'P',
+        long = "project",
         global = true,
-        help = "Request a particular Ruby version for your environment (defaults to latest available)"
+        help = "Specify custom rbproject.toml location (skips autodetection)"
     )]
-    pub ruby_version: Option<String>,
+    pub project_file: Option<std::path::PathBuf>,
 
-    /// Specify custom gem base directory (default: ~/.gem)
-    #[arg(
-        short = 'G',
-        long = "gem-home",
-        global = true,
-        help = "Specify custom gem base directory for gem installations (default: ~/.gem)"
-    )]
-    pub gem_home: Option<std::path::PathBuf>,
+    /// Flattened configuration options (works for both CLI and config file)
+    #[command(flatten)]
+    pub config: RbConfig,
 
     #[command(subcommand)]
     pub command: Commands,
@@ -120,10 +117,36 @@ pub enum Commands {
     /// 🔄 Synchronize your bundler environment with distinguished precision
     #[command(visible_alias = "s")]
     Sync,
+
+    /// 🎯 Execute project scripts defined in rbproject.toml
+    #[command(
+        visible_alias = "r",
+        about = "🎯 Execute project scripts defined in rbproject.toml",
+        long_about = "🎯 Run Project Scripts\n\nExecute scripts defined in your project's rbproject.toml file with the\nmeticulously prepared Ruby environment appropriate to your distinguished project.\n\nProject scripts provide convenient shortcuts for common development tasks,\nconfigured with the same refined precision befitting a proper Ruby development workflow.\n\nRun without a script name to list all available scripts."
+    )]
+    Run {
+        /// Name of the script to execute (from rbproject.toml), or omit to list available scripts
+        #[arg(help = "Name of the script to execute (omit to list available scripts)")]
+        script: Option<String>,
+
+        /// Additional arguments to pass to the script
+        #[arg(
+            trailing_var_arg = true,
+            allow_hyphen_values = true,
+            help = "Additional arguments to pass to the script"
+        )]
+        args: Vec<String>,
+    },
+
+    /// 📝 Initialize a new rbproject.toml in the current directory
+    #[command(about = "📝 Initialize a new rbproject.toml in the current directory")]
+    Init,
 }
 
 // Re-export for convenience
-pub use commands::{environment_command, exec_command, runtime_command, sync_command};
+pub use commands::{
+    environment_command, exec_command, init_command, run_command, runtime_command, sync_command,
+};
 
 use log::debug;
 use rb_core::butler::ButlerRuntime;
@@ -161,6 +184,16 @@ pub fn resolve_search_dir(rubies_dir: Option<PathBuf>) -> PathBuf {
     })
 }
 
+impl Cli {
+    /// Merge CLI arguments with config file defaults
+    /// CLI arguments always take precedence over config file values
+    pub fn with_config_defaults(mut self) -> Result<Self, ConfigError> {
+        let file_config = config::loader::load_config(self.config_file.clone())?;
+        self.config.merge_with(file_config);
+        Ok(self)
+    }
+}
+
 /// Initialize the logger with the specified log level
 pub fn init_logger(log_level: LogLevel) {
     env_logger::Builder::from_default_env()
@@ -214,9 +247,9 @@ mod tests {
         let cli = Cli {
             log_level: LogLevel::Info,
             verbose: 0,
-            rubies_dir: None,
-            ruby_version: None,
-            gem_home: None,
+            config_file: None,
+            project_file: None,
+            config: RbConfig::default(),
             command: Commands::Runtime,
         };
         assert!(matches!(cli.effective_log_level(), LogLevel::Info));
@@ -225,9 +258,9 @@ mod tests {
         let cli = Cli {
             log_level: LogLevel::None,
             verbose: 1,
-            rubies_dir: None,
-            ruby_version: None,
-            gem_home: None,
+            config_file: None,
+            project_file: None,
+            config: RbConfig::default(),
             command: Commands::Runtime,
         };
         assert!(matches!(cli.effective_log_level(), LogLevel::Info));
@@ -236,9 +269,9 @@ mod tests {
         let cli = Cli {
             log_level: LogLevel::None,
             verbose: 2,
-            rubies_dir: None,
-            ruby_version: None,
-            gem_home: None,
+            config_file: None,
+            project_file: None,
+            config: RbConfig::default(),
             command: Commands::Runtime,
         };
         assert!(matches!(cli.effective_log_level(), LogLevel::Debug));
diff --git a/crates/rb-core/Cargo.toml b/crates/rb-core/Cargo.toml
index 19f0100..5e647f2 100644
--- a/crates/rb-core/Cargo.toml
+++ b/crates/rb-core/Cargo.toml
@@ -17,6 +17,8 @@ home = "0.5"
 log = "0.4"
 colored = "2.1.0"
 which = "6.0"
+toml = "0.8"
+serde = { version = "1.0", features = ["derive"] }
 
 [dev-dependencies]
 tempfile = "3.21.0"
diff --git a/crates/rb-core/src/lib.rs b/crates/rb-core/src/lib.rs
index 8922cf2..e3fbbe1 100644
--- a/crates/rb-core/src/lib.rs
+++ b/crates/rb-core/src/lib.rs
@@ -1,9 +1,11 @@
 pub mod bundler;
 pub mod butler;
 pub mod gems;
+pub mod project;
 pub mod ruby;
 
 pub use bundler::{BundlerRuntime, BundlerRuntimeDetector};
 pub use butler::{ButlerRuntime, Command as ButlerCommand};
 pub use gems::GemRuntime;
+pub use project::{ProjectRuntime, RbprojectDetector};
 pub use ruby::{RubyRuntime, RubyRuntimeDetector};
diff --git a/crates/rb-core/src/project/detector.rs b/crates/rb-core/src/project/detector.rs
new file mode 100644
index 0000000..f461827
--- /dev/null
+++ b/crates/rb-core/src/project/detector.rs
@@ -0,0 +1,320 @@
+use log::{debug, info};
+use std::path::Path;
+
+use super::ProjectRuntime;
+
+pub struct RbprojectDetector;
+
+impl RbprojectDetector {
+    /// Supported project file names in order of preference
+    const PROJECT_FILENAMES: &'static [&'static str] = &["rbproject.toml", "gem.toml"];
+
+    /// Discover a ProjectRuntime by searching for project config files (rbproject.toml or gem.toml)
+    /// in the current directory and walking up the directory tree until one is found or we reach the root.
+    pub fn discover(start_dir: &Path) -> std::io::Result<Option<ProjectRuntime>> {
+        debug!(
+            "Searching for project config file starting from directory: {}",
+            start_dir.display()
+        );
+
+        let mut current_dir = start_dir.to_path_buf();
+
+        loop {
+            debug!(
+                "Checking directory for project config: {}",
+                current_dir.display()
+            );
+
+            // Try each supported filename in order
+            for filename in Self::PROJECT_FILENAMES {
+                let project_path = current_dir.join(filename);
+
+                if project_path.exists() && project_path.is_file() {
+                    info!("Discovered {} at: {}", filename, project_path.display());
+
+                    // Parse the file and create ProjectRuntime
+                    match ProjectRuntime::from_file(&project_path) {
+                        Ok(project_runtime) => {
+                            debug!("Created ProjectRuntime for root: {}", current_dir.display());
+                            return Ok(Some(project_runtime));
+                        }
+                        Err(e) => {
+                            debug!(
+                                "Failed to parse {} at {}: {}",
+                                filename,
+                                project_path.display(),
+                                e
+                            );
+                            return Err(e);
+                        }
+                    }
+                }
+            }
+
+            debug!("No project config found in: {}", current_dir.display());
+
+            // Move up one directory
+            match current_dir.parent() {
+                Some(parent) => {
+                    current_dir = parent.to_path_buf();
+                    debug!("Moving up to parent directory: {}", current_dir.display());
+                }
+                None => {
+                    debug!("Reached filesystem root, no project config found");
+                    break;
+                }
+            }
+        }
+
+        info!(
+            "No project config found starting from: {}",
+            start_dir.display()
+        );
+        Ok(None)
+    }
+
+    /// Convenience method to discover from current working directory
+    pub fn discover_from_cwd() -> std::io::Result<Option<ProjectRuntime>> {
+        let cwd = std::env::current_dir()?;
+        debug!(
+            "Discovering project runtime from current working directory: {}",
+            cwd.display()
+        );
+        Self::discover(&cwd)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::io;
+    use tempfile::TempDir;
+
+    fn create_rbproject_toml(dir: &Path, content: &str) -> io::Result<()> {
+        let rbproject_path = dir.join("rbproject.toml");
+        fs::write(rbproject_path, content)?;
+        Ok(())
+    }
+
+    #[test]
+    fn discover_finds_rbproject_in_current_directory() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        let toml_content = r#"
+[scripts]
+test = "rspec"
+lint = "rubocop"
+"#;
+        create_rbproject_toml(project_dir, toml_content)?;
+
+        let result = RbprojectDetector::discover(project_dir)?;
+
+        assert!(result.is_some());
+        let project_runtime = result.unwrap();
+        assert_eq!(project_runtime.root, project_dir);
+        assert_eq!(project_runtime.scripts.len(), 2);
+        assert_eq!(project_runtime.get_script_command("test"), Some("rspec"));
+        assert_eq!(project_runtime.get_script_command("lint"), Some("rubocop"));
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_finds_rbproject_in_parent_directory() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        let toml_content = r#"
+[scripts]
+server = "rails server"
+"#;
+        create_rbproject_toml(project_dir, toml_content)?;
+
+        // Create nested directory structure
+        let nested_dir = project_dir.join("app").join("controllers");
+        fs::create_dir_all(&nested_dir)?;
+
+        let result = RbprojectDetector::discover(&nested_dir)?;
+
+        assert!(result.is_some());
+        let project_runtime = result.unwrap();
+        assert_eq!(project_runtime.root, project_dir);
+        assert_eq!(project_runtime.scripts.len(), 1);
+        assert_eq!(
+            project_runtime.get_script_command("server"),
+            Some("rails server")
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_returns_none_when_no_rbproject_found() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        let result = RbprojectDetector::discover(project_dir)?;
+
+        assert!(result.is_none());
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_stops_at_first_rbproject_found() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let root_dir = temp_dir.path();
+
+        // Create root rbproject.toml
+        let root_toml = r#"
+[scripts]
+root = "root command"
+"#;
+        create_rbproject_toml(root_dir, root_toml)?;
+
+        // Create nested project with its own rbproject.toml
+        let nested_dir = root_dir.join("subproject");
+        fs::create_dir_all(&nested_dir)?;
+        let nested_toml = r#"
+[scripts]
+nested = "nested command"
+"#;
+        create_rbproject_toml(&nested_dir, nested_toml)?;
+
+        // Create deep directory in nested project
+        let deep_dir = nested_dir.join("lib").join("deep");
+        fs::create_dir_all(&deep_dir)?;
+
+        // Search from deep directory - should find subproject rbproject.toml, not root
+        let result = RbprojectDetector::discover(&deep_dir)?;
+
+        assert!(result.is_some());
+        let project_runtime = result.unwrap();
+        assert_eq!(project_runtime.root, nested_dir);
+        assert_eq!(project_runtime.scripts.len(), 1);
+        assert_eq!(
+            project_runtime.get_script_command("nested"),
+            Some("nested command")
+        );
+        assert_eq!(project_runtime.get_script_command("root"), None);
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_handles_empty_scripts_section() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        let toml_content = r#"
+[scripts]
+"#;
+        create_rbproject_toml(project_dir, toml_content)?;
+
+        let result = RbprojectDetector::discover(project_dir)?;
+
+        assert!(result.is_some());
+        let project_runtime = result.unwrap();
+        assert_eq!(project_runtime.scripts.len(), 0);
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_handles_missing_scripts_section() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        let toml_content = r#"
+[other_section]
+key = "value"
+"#;
+        create_rbproject_toml(project_dir, toml_content)?;
+
+        let result = RbprojectDetector::discover(project_dir)?;
+
+        assert!(result.is_some());
+        let project_runtime = result.unwrap();
+        assert_eq!(project_runtime.scripts.len(), 0);
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_returns_error_for_invalid_toml() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        let invalid_toml = r#"
+[scripts
+this is not valid toml
+"#;
+        create_rbproject_toml(project_dir, invalid_toml)?;
+
+        let result = RbprojectDetector::discover(project_dir);
+
+        assert!(result.is_err());
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_finds_gem_toml_in_current_directory() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        let toml_content = r#"
+[scripts]
+test = "rspec"
+"#;
+        // Create gem.toml instead of rbproject.toml
+        let gem_toml_path = project_dir.join("gem.toml");
+        fs::write(&gem_toml_path, toml_content)?;
+
+        let result = RbprojectDetector::discover(project_dir)?;
+
+        assert!(result.is_some());
+        let project_runtime = result.unwrap();
+        assert_eq!(project_runtime.root, project_dir);
+        assert_eq!(project_runtime.config_filename, "gem.toml");
+        assert_eq!(project_runtime.scripts.len(), 1);
+        assert_eq!(project_runtime.get_script_command("test"), Some("rspec"));
+
+        Ok(())
+    }
+
+    #[test]
+    fn discover_prefers_rbproject_toml_over_gem_toml() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let project_dir = temp_dir.path();
+
+        // Create both files with different content
+        let rbproject_content = r#"
+[scripts]
+test = "rspec from rbproject.toml"
+"#;
+        create_rbproject_toml(project_dir, rbproject_content)?;
+
+        let gem_content = r#"
+[scripts]
+test = "rspec from gem.toml"
+"#;
+        let gem_toml_path = project_dir.join("gem.toml");
+        fs::write(&gem_toml_path, gem_content)?;
+
+        let result = RbprojectDetector::discover(project_dir)?;
+
+        assert!(result.is_some());
+        let project_runtime = result.unwrap();
+        assert_eq!(project_runtime.root, project_dir);
+        assert_eq!(project_runtime.config_filename, "rbproject.toml");
+        assert_eq!(
+            project_runtime.get_script_command("test"),
+            Some("rspec from rbproject.toml")
+        );
+
+        Ok(())
+    }
+}
diff --git a/crates/rb-core/src/project/mod.rs b/crates/rb-core/src/project/mod.rs
new file mode 100644
index 0000000..2efa291
--- /dev/null
+++ b/crates/rb-core/src/project/mod.rs
@@ -0,0 +1,646 @@
+use crate::butler::runtime_provider::RuntimeProvider;
+use log::{debug, info};
+use serde::Deserialize;
+use std::collections::HashMap;
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+pub mod detector;
+
+pub use detector::RbprojectDetector;
+
+/// Represents a script definition in rbproject.toml
+/// Supports both simple string format and detailed object format
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(untagged)]
+pub enum ScriptDefinition {
+    /// Simple format: script = "command"
+    Simple(String),
+    /// Detailed format: script = { command = "...", description = "..." }
+    Detailed {
+        command: String,
+        #[serde(default)]
+        description: Option<String>,
+    },
+}
+
+impl ScriptDefinition {
+    /// Get the command string
+    pub fn command(&self) -> &str {
+        match self {
+            ScriptDefinition::Simple(cmd) => cmd,
+            ScriptDefinition::Detailed { command, .. } => command,
+        }
+    }
+
+    /// Get the optional description
+    pub fn description(&self) -> Option<&str> {
+        match self {
+            ScriptDefinition::Simple(_) => None,
+            ScriptDefinition::Detailed { description, .. } => description.as_deref(),
+        }
+    }
+}
+
+/// Project metadata from [project] section
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Default)]
+pub struct ProjectMetadata {
+    #[serde(default)]
+    pub name: Option<String>,
+    #[serde(default)]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+struct RbprojectConfig {
+    #[serde(default)]
+    project: ProjectMetadata,
+    #[serde(default)]
+    scripts: HashMap<String, ScriptDefinition>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProjectRuntime {
+    /// Root directory containing the project config file
+    pub root: PathBuf,
+    /// Name of the config file (rbproject.toml or gem.toml)
+    pub config_filename: String,
+    /// Project metadata
+    pub metadata: ProjectMetadata,
+    /// Scripts defined in the [scripts] section
+    pub scripts: HashMap<String, ScriptDefinition>,
+}
+
+impl ProjectRuntime {
+    /// Create a new ProjectRuntime from a directory containing a project config file
+    pub fn new(
+        root: impl AsRef<Path>,
+        config_filename: impl Into<String>,
+        metadata: ProjectMetadata,
+        scripts: HashMap<String, ScriptDefinition>,
+    ) -> Self {
+        let root = root.as_ref().to_path_buf();
+        let config_filename = config_filename.into();
+
+        debug!("Creating ProjectRuntime for root: {}", root.display());
+        debug!("Config file: {}", config_filename);
+        if let Some(ref name) = metadata.name {
+            debug!("Project name: {}", name);
+        }
+        debug!("Scripts defined: {:?}", scripts.keys().collect::<Vec<_>>());
+
+        Self {
+            root,
+            config_filename,
+            metadata,
+            scripts,
+        }
+    }
+
+    /// Load ProjectRuntime from a project config file
+    pub fn from_file(config_path: impl AsRef<Path>) -> io::Result<Self> {
+        let config_path = config_path.as_ref();
+
+        // Extract the filename from the path
+        let config_filename = config_path
+            .file_name()
+            .and_then(|n| n.to_str())
+            .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput, "Invalid config file path"))?
+            .to_string();
+
+        debug!("Loading project config from: {}", config_path.display());
+
+        let content = fs::read_to_string(config_path)?;
+        debug!("Read {} bytes from {}", content.len(), config_filename);
+
+        let config: RbprojectConfig = toml::from_str(&content).map_err(|e| {
+            debug!("Failed to parse TOML: {}", e);
+            io::Error::new(
+                io::ErrorKind::InvalidData,
+                format!("Failed to parse {}: {}", config_filename, e),
+            )
+        })?;
+
+        let root = config_path
+            .parent()
+            .ok_or_else(|| {
+                io::Error::new(
+                    io::ErrorKind::NotFound,
+                    "Could not determine parent directory",
+                )
+            })?
+            .to_path_buf();
+
+        if let Some(ref name) = config.project.name {
+            info!("Loaded project '{}' from {}", name, config_filename);
+        } else {
+            info!("Loaded {}", config_filename);
+        }
+
+        let script_names: Vec<&str> = config.scripts.keys().map(|s| s.as_str()).collect();
+        info!(
+            "Found {} script(s): {}",
+            config.scripts.len(),
+            if script_names.is_empty() {
+                "none".to_string()
+            } else {
+                script_names.join(", ")
+            }
+        );
+
+        for (name, script_def) in &config.scripts {
+            if let Some(desc) = script_def.description() {
+                debug!("Script '{}': {} ({})", name, script_def.command(), desc);
+            } else {
+                debug!("Script '{}': {}", name, script_def.command());
+            }
+        }
+
+        Ok(Self::new(
+            root,
+            config_filename,
+            config.project,
+            config.scripts,
+        ))
+    }
+
+    /// Returns the full path to the project config file
+    pub fn rbproject_path(&self) -> PathBuf {
+        self.root.join(&self.config_filename)
+    }
+
+    /// Check if a script with the given name exists
+    pub fn has_script(&self, name: &str) -> bool {
+        self.scripts.contains_key(name)
+    }
+
+    /// Get the script definition by name
+    pub fn get_script(&self, name: &str) -> Option<&ScriptDefinition> {
+        self.scripts.get(name)
+    }
+
+    /// Get the command string for a script by name
+    pub fn get_script_command(&self, name: &str) -> Option<&str> {
+        self.scripts.get(name).map(|s| s.command())
+    }
+
+    /// Get the description for a script by name
+    pub fn get_script_description(&self, name: &str) -> Option<&str> {
+        self.scripts.get(name).and_then(|s| s.description())
+    }
+
+    /// Get all script names
+    pub fn script_names(&self) -> Vec<&str> {
+        let mut names: Vec<&str> = self.scripts.keys().map(|s| s.as_str()).collect();
+        names.sort();
+        names
+    }
+}
+
+impl RuntimeProvider for ProjectRuntime {
+    fn bin_dir(&self) -> Option<PathBuf> {
+        // Project runtime doesn't add a bin directory to PATH
+        None
+    }
+
+    fn gem_dir(&self) -> Option<PathBuf> {
+        // Project runtime doesn't add a gem directory
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io;
+    use tempfile::TempDir;
+
+    fn create_rbproject_file(dir: &Path, content: &str) -> io::Result<PathBuf> {
+        let rbproject_path = dir.join("rbproject.toml");
+        fs::write(&rbproject_path, content)?;
+        Ok(rbproject_path)
+    }
+
+    #[test]
+    fn new_creates_project_runtime() {
+        let temp_dir = TempDir::new().unwrap();
+        let mut scripts = HashMap::new();
+        scripts.insert(
+            "test".to_string(),
+            ScriptDefinition::Simple("rspec".to_string()),
+        );
+        scripts.insert(
+            "lint".to_string(),
+            ScriptDefinition::Simple("rubocop".to_string()),
+        );
+
+        let metadata = ProjectMetadata::default();
+        let project =
+            ProjectRuntime::new(temp_dir.path(), "rbproject.toml", metadata, scripts.clone());
+
+        assert_eq!(project.root, temp_dir.path());
+        assert_eq!(project.scripts, scripts);
+    }
+
+    #[test]
+    fn from_file_parses_simple_scripts() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[scripts]
+test = "rspec"
+lint = "rubocop"
+server = "rails server -p 3000"
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.root, temp_dir.path());
+        assert_eq!(project.scripts.len(), 3);
+        assert_eq!(project.get_script_command("test"), Some("rspec"));
+        assert_eq!(project.get_script_command("lint"), Some("rubocop"));
+        assert_eq!(
+            project.get_script_command("server"),
+            Some("rails server -p 3000")
+        );
+        assert_eq!(project.get_script_description("test"), None);
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_handles_empty_scripts_section() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[scripts]
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.scripts.len(), 0);
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_handles_missing_scripts_section() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[other_section]
+key = "value"
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.scripts.len(), 0);
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_returns_error_for_invalid_toml() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let invalid_toml = r#"
+[scripts
+this is not valid toml
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), invalid_toml)?;
+
+        let result = ProjectRuntime::from_file(&rbproject_path);
+
+        assert!(result.is_err());
+        let err = result.unwrap_err();
+        assert_eq!(err.kind(), io::ErrorKind::InvalidData);
+
+        Ok(())
+    }
+
+    #[test]
+    fn rbproject_path_returns_correct_path() {
+        let temp_dir = TempDir::new().unwrap();
+        let project = ProjectRuntime::new(
+            temp_dir.path(),
+            "rbproject.toml",
+            ProjectMetadata::default(),
+            HashMap::new(),
+        );
+
+        let expected_path = temp_dir.path().join("rbproject.toml");
+        assert_eq!(project.rbproject_path(), expected_path);
+    }
+
+    #[test]
+    fn has_script_returns_true_for_existing_script() {
+        let temp_dir = TempDir::new().unwrap();
+        let mut scripts = HashMap::new();
+        scripts.insert(
+            "test".to_string(),
+            ScriptDefinition::Simple("rspec".to_string()),
+        );
+        let project = ProjectRuntime::new(
+            temp_dir.path(),
+            "rbproject.toml",
+            ProjectMetadata::default(),
+            scripts,
+        );
+
+        assert!(project.has_script("test"));
+        assert!(!project.has_script("nonexistent"));
+    }
+
+    #[test]
+    fn get_script_command_returns_command_string() {
+        let temp_dir = TempDir::new().unwrap();
+        let mut scripts = HashMap::new();
+        scripts.insert(
+            "test".to_string(),
+            ScriptDefinition::Simple("rspec".to_string()),
+        );
+        scripts.insert(
+            "lint".to_string(),
+            ScriptDefinition::Simple("rubocop -a".to_string()),
+        );
+        let project = ProjectRuntime::new(
+            temp_dir.path(),
+            "rbproject.toml",
+            ProjectMetadata::default(),
+            scripts,
+        );
+
+        assert_eq!(project.get_script_command("test"), Some("rspec"));
+        assert_eq!(project.get_script_command("lint"), Some("rubocop -a"));
+        assert_eq!(project.get_script_command("nonexistent"), None);
+    }
+
+    #[test]
+    fn script_names_returns_sorted_list() {
+        let temp_dir = TempDir::new().unwrap();
+        let mut scripts = HashMap::new();
+        scripts.insert(
+            "server".to_string(),
+            ScriptDefinition::Simple("rails server".to_string()),
+        );
+        scripts.insert(
+            "test".to_string(),
+            ScriptDefinition::Simple("rspec".to_string()),
+        );
+        scripts.insert(
+            "lint".to_string(),
+            ScriptDefinition::Simple("rubocop".to_string()),
+        );
+        let project = ProjectRuntime::new(
+            temp_dir.path(),
+            "rbproject.toml",
+            ProjectMetadata::default(),
+            scripts,
+        );
+
+        let names = project.script_names();
+
+        assert_eq!(names, vec!["lint", "server", "test"]);
+    }
+
+    #[test]
+    fn runtime_provider_returns_none() {
+        let temp_dir = TempDir::new().unwrap();
+        let project = ProjectRuntime::new(
+            temp_dir.path(),
+            "rbproject.toml",
+            ProjectMetadata::default(),
+            HashMap::new(),
+        );
+
+        assert_eq!(project.bin_dir(), None);
+        assert_eq!(project.gem_dir(), None);
+    }
+
+    #[test]
+    fn from_file_with_complex_commands() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[scripts]
+test = "rspec --format documentation"
+server = "rails server -b 0.0.0.0 -p 3000"
+console = "rails console"
+deploy = "cap production deploy"
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.scripts.len(), 4);
+        assert_eq!(
+            project.get_script_command("test"),
+            Some("rspec --format documentation")
+        );
+        assert_eq!(
+            project.get_script_command("server"),
+            Some("rails server -b 0.0.0.0 -p 3000")
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_parses_detailed_scripts() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[scripts]
+test = { command = "rspec", description = "Run test suite" }
+lint = { command = "rubocop", description = "Run linter" }
+server = { command = "rails server -p 3000" }
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.scripts.len(), 3);
+        assert_eq!(project.get_script_command("test"), Some("rspec"));
+        assert_eq!(
+            project.get_script_description("test"),
+            Some("Run test suite")
+        );
+        assert_eq!(project.get_script_command("lint"), Some("rubocop"));
+        assert_eq!(project.get_script_description("lint"), Some("Run linter"));
+        assert_eq!(
+            project.get_script_command("server"),
+            Some("rails server -p 3000")
+        );
+        assert_eq!(project.get_script_description("server"), None);
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_parses_mixed_scripts() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[scripts]
+test = "rspec"
+lint = { command = "rubocop", description = "Check code quality" }
+server = "rails server"
+deploy = { command = "cap production deploy", description = "Deploy to production" }
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.scripts.len(), 4);
+        // Simple format
+        assert_eq!(project.get_script_command("test"), Some("rspec"));
+        assert_eq!(project.get_script_description("test"), None);
+        // Detailed format
+        assert_eq!(project.get_script_command("lint"), Some("rubocop"));
+        assert_eq!(
+            project.get_script_description("lint"),
+            Some("Check code quality")
+        );
+        // Simple format
+        assert_eq!(project.get_script_command("server"), Some("rails server"));
+        assert_eq!(project.get_script_description("server"), None);
+        // Detailed format
+        assert_eq!(
+            project.get_script_command("deploy"),
+            Some("cap production deploy")
+        );
+        assert_eq!(
+            project.get_script_description("deploy"),
+            Some("Deploy to production")
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn script_definition_simple_variant() {
+        let def = ScriptDefinition::Simple("test command".to_string());
+        assert_eq!(def.command(), "test command");
+        assert_eq!(def.description(), None);
+    }
+
+    #[test]
+    fn script_definition_detailed_variant_with_description() {
+        let def = ScriptDefinition::Detailed {
+            command: "test command".to_string(),
+            description: Some("Test description".to_string()),
+        };
+        assert_eq!(def.command(), "test command");
+        assert_eq!(def.description(), Some("Test description"));
+    }
+
+    #[test]
+    fn script_definition_detailed_variant_without_description() {
+        let def = ScriptDefinition::Detailed {
+            command: "test command".to_string(),
+            description: None,
+        };
+        assert_eq!(def.command(), "test command");
+        assert_eq!(def.description(), None);
+    }
+
+    #[test]
+    fn from_file_parses_scripts_with_colons() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[scripts]
+test = "rspec"
+"test:watch" = "guard"
+"lint:fix" = { command = "rubocop -a", description = "Auto-fix linting issues" }
+"db:migrate" = "rails db:migrate"
+"deploy:production" = { command = "cap production deploy" }
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.scripts.len(), 5);
+        assert_eq!(project.get_script_command("test"), Some("rspec"));
+        assert_eq!(project.get_script_command("test:watch"), Some("guard"));
+        assert_eq!(project.get_script_command("lint:fix"), Some("rubocop -a"));
+        assert_eq!(
+            project.get_script_description("lint:fix"),
+            Some("Auto-fix linting issues")
+        );
+        assert_eq!(
+            project.get_script_command("db:migrate"),
+            Some("rails db:migrate")
+        );
+        assert_eq!(
+            project.get_script_command("deploy:production"),
+            Some("cap production deploy")
+        );
+        assert_eq!(project.get_script_description("deploy:production"), None);
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_parses_project_metadata() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[project]
+name = "My Elegant Project"
+description = "A sophisticated Ruby application managed with distinction"
+
+[scripts]
+test = "rspec"
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(
+            project.metadata.name,
+            Some("My Elegant Project".to_string())
+        );
+        assert_eq!(
+            project.metadata.description,
+            Some("A sophisticated Ruby application managed with distinction".to_string())
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_handles_missing_project_metadata() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[scripts]
+test = "rspec"
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(project.metadata.name, None);
+        assert_eq!(project.metadata.description, None);
+
+        Ok(())
+    }
+
+    #[test]
+    fn from_file_handles_partial_project_metadata() -> io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let toml_content = r#"
+[project]
+name = "Project Without Description"
+
+[scripts]
+test = "rspec"
+"#;
+        let rbproject_path = create_rbproject_file(temp_dir.path(), toml_content)?;
+
+        let project = ProjectRuntime::from_file(&rbproject_path)?;
+
+        assert_eq!(
+            project.metadata.name,
+            Some("Project Without Description".to_string())
+        );
+        assert_eq!(project.metadata.description, None);
+
+        Ok(())
+    }
+}
diff --git a/examples/rb.toml b/examples/rb.toml
new file mode 100644
index 0000000..548ca3a
--- /dev/null
+++ b/examples/rb.toml
@@ -0,0 +1,48 @@
+# Ruby Butler Configuration File
+# 
+# This configuration file allows you to set default values for Ruby Butler's
+# global options. These defaults will be used when the corresponding CLI flags
+# are not provided.
+#
+# Location:
+#   Unix/Linux/macOS: ~/.config/rb/rb.toml (primary) or ~/.rb.toml (fallback)
+#   Windows:          %APPDATA%\rb\rb.toml (primary) or ~\.rb.toml (fallback)
+#
+# Note: CLI arguments always take precedence over configuration file values.
+
+# Designate the directory containing your Ruby installations
+# Default: ~/.rubies
+#
+# This is where Ruby Butler will look for Ruby installations, typically
+# directories named ruby-X.Y.Z (e.g., ruby-3.3.0, ruby-3.2.5)
+#
+# rubies-dir = "~/.rubies"
+# rubies-dir = "/opt/rubies"
+
+# Request a particular Ruby version for your environment
+# Default: latest available version
+#
+# Specify which Ruby version to use by default. You can use:
+# - Exact version: "3.3.0"
+# - Major.minor: "3.3"
+# - Just major: "3"
+#
+# ruby-version = "3.3"
+# ruby-version = "3.3.0"
+
+# Specify custom gem base directory
+# Default: ~/.gem
+#
+# This is the base directory where gems will be installed. Ruby Butler
+# will create version-specific subdirectories within this location
+# (e.g., ~/.gem/ruby/3.3.0)
+#
+# gem-home = "~/.gem"
+# gem-home = "/opt/gems"
+
+# Example: Complete configuration
+# Uncomment and adjust these values to suit your needs:
+#
+# rubies-dir = "~/.rubies"
+# ruby-version = "3.3"
+# gem-home = "~/.gem"
diff --git a/examples/rbproject.toml b/examples/rbproject.toml
new file mode 100644
index 0000000..d9d4f99
--- /dev/null
+++ b/examples/rbproject.toml
@@ -0,0 +1,55 @@
+# rbproject.toml - Project-specific configuration for Ruby Butler
+#
+# This file provides project-specific scripts, similar to package.json scripts
+# in Node.js projects. Place this file in your project root, and Ruby Butler
+# will discover it by recursively searching upward from your current directory.
+#
+# Scripts defined here will appear as custom commands in `rb --help` when
+# running within the project directory.
+#
+# Scripts support two notations:
+# 1. Simple: script-name = "command"
+# 2. Detailed: script-name = { command = "command", description = "helpful description" }
+#
+# You can mix both notations in the same file.
+
+[project]
+name = "Ruby Butler Example Project"
+description = "A sophisticated Rails application demonstrating Ruby Butler's project management capabilities"
+
+[scripts]
+# Test suite execution - showing both simple and detailed notation
+test = { command = "rspec", description = "Run the test suite" }
+"test:watch" = "guard"
+coverage = { command = "rspec --format documentation", description = "Run tests with detailed output" }
+
+# Code quality and linting - detailed notation with descriptions
+lint = { command = "rubocop", description = "Run linter for code quality" }
+"lint:fix" = { command = "rubocop -a", description = "Run linter and auto-fix issues" }
+"lint:strict" = { command = "rubocop --parallel", description = "Run linter in strict parallel mode" }
+
+# Development server - simple notation
+server = "rails server -b 0.0.0.0 -p 3000"
+console = "rails console"
+
+# Database operations - mixed notation
+"db:setup" = { command = "rails db:setup", description = "Initialize database" }
+"db:migrate" = "rails db:migrate"
+"db:seed" = { command = "rails db:seed", description = "Seed database with sample data" }
+"db:reset" = "rails db:reset"
+
+# Asset management
+"assets:precompile" = "rails assets:precompile"
+"assets:clean" = "rails assets:clean"
+
+# Documentation generation - detailed notation
+docs = { command = "yard doc", description = "Generate API documentation" }
+"docs:server" = { command = "yard server --reload", description = "Start documentation server with live reload" }
+
+# Deployment - detailed notation with clear descriptions
+"deploy:staging" = { command = "cap staging deploy", description = "Deploy to staging environment" }
+"deploy:production" = { command = "cap production deploy", description = "Deploy to production environment" }
+
+# Custom tasks - simple notation for brevity
+setup = "bin/setup"
+update = "bin/update"
diff --git a/spec/commands/config_spec.sh b/spec/commands/config_spec.sh
new file mode 100644
index 0000000..feaa6d0
--- /dev/null
+++ b/spec/commands/config_spec.sh
@@ -0,0 +1,123 @@
+#!/bin/bash
+# ShellSpec tests for Ruby Butler configuration file support
+# Distinguished validation of rb.toml loading and precedence
+
+Describe "Ruby Butler Configuration System"
+  Include spec/support/helpers.sh
+  
+  setup() {
+    TEST_CONFIG_DIR="${SHELLSPEC_TMPBASE}/config-test-$$-${RANDOM}"
+    mkdir -p "$TEST_CONFIG_DIR"
+  }
+  
+  cleanup() {
+    if [ -d "$TEST_CONFIG_DIR" ]; then
+      rm -rf "$TEST_CONFIG_DIR"
+    fi
+    unset RB_CONFIG
+  }
+  
+  BeforeEach 'setup'
+  AfterEach 'cleanup'
+  
+  Describe "--config flag"
+    Context "when loading custom configuration file"
+      It "accepts --config flag with valid TOML file"
+        cd "$TEST_CONFIG_DIR"
+        cat > test-config.toml << 'EOF'
+ruby-version = "3.2.0"
+rubies-dir = "/custom/rubies"
+EOF
+        When run rb --config test-config.toml --version
+        The status should equal 0
+        The output should include "rb"
+      End
+      
+      It "applies rubies-dir from config file"
+        cd "$TEST_CONFIG_DIR"
+        cat > test-config.toml << 'EOF'
+rubies-dir = "/nonexistent/custom/rubies"
+EOF
+        When run rb --config test-config.toml runtime
+        The status should not equal 0
+        The stderr should include "/nonexistent/custom/rubies"
+      End
+      
+      It "shows --config option in help"
+        When run rb --help
+        The status should equal 0
+        The output should include "--config"
+        The output should include "configuration file"
+      End
+    End
+    
+    Context "with short form -c flag"
+      It "accepts -c flag as alias for --config"
+        cd "$TEST_CONFIG_DIR"
+        cat > test-config.toml << 'EOF'
+ruby-version = "3.2.0"
+EOF
+        When run rb -c test-config.toml --version
+        The status should equal 0
+        The output should include "rb"
+      End
+    End
+  End
+  
+  Describe "RB_CONFIG environment variable"
+    Context "when RB_CONFIG is set"
+      It "loads configuration from RB_CONFIG path"
+        cd "$TEST_CONFIG_DIR"
+        cat > rb-env-config.toml << 'EOF'
+rubies-dir = "/env/var/rubies"
+EOF
+        export RB_CONFIG="${TEST_CONFIG_DIR}/rb-env-config.toml"
+        When run rb runtime
+        The status should not equal 0
+        The stderr should include "/env/var/rubies"
+      End
+      
+      It "shows config loading with verbose flag"
+        cd "$TEST_CONFIG_DIR"
+        cat > rb-env-config.toml << 'EOF'
+rubies-dir = "/env/var/rubies"
+EOF
+        export RB_CONFIG="${TEST_CONFIG_DIR}/rb-env-config.toml"
+        When run rb -R $RUBIES_DIR -v runtime
+        The status should equal 0
+        The output should include "Ruby Environment Survey"
+        The stderr should include "Loading configuration"
+      End
+    End
+  End
+  
+  Describe "Configuration precedence"
+    Context "when both --config and RB_CONFIG are set"
+      It "prefers --config flag over RB_CONFIG"
+        cd "$TEST_CONFIG_DIR"
+        cat > cli-config.toml << 'EOF'
+rubies-dir = "/cli/rubies"
+EOF
+        cat > env-config.toml << 'EOF'
+rubies-dir = "/env/rubies"
+EOF
+        export RB_CONFIG="${TEST_CONFIG_DIR}/env-config.toml"
+        When run rb --config cli-config.toml runtime
+        The status should not equal 0
+        The stderr should include "/cli/rubies"
+      End
+    End
+    
+    Context "CLI flags override config file values"
+      It "uses -R flag over config file rubies-dir"
+        cd "$TEST_CONFIG_DIR"
+        cat > config.toml << 'EOF'
+rubies-dir = "/config/rubies"
+EOF
+        When run rb --config config.toml -R "/override/rubies" runtime
+        The status should not equal 0
+        The stderr should include "/override/rubies"
+      End
+    End
+  End
+End
diff --git a/spec/commands/init_spec.sh b/spec/commands/init_spec.sh
new file mode 100644
index 0000000..753ad4d
--- /dev/null
+++ b/spec/commands/init_spec.sh
@@ -0,0 +1,130 @@
+#!/bin/bash
+# ShellSpec tests for Ruby Butler init command
+# Distinguished validation of project initialization capabilities
+
+Describe "Ruby Butler Init Command"
+  Include spec/support/helpers.sh
+  
+  # Use a temporary directory for each test
+  setup() {
+    TEST_INIT_DIR="${SHELLSPEC_TMPBASE}/init-test-$$-${RANDOM}"
+    mkdir -p "$TEST_INIT_DIR"
+  }
+  
+  cleanup() {
+    if [ -d "$TEST_INIT_DIR" ]; then
+      rm -rf "$TEST_INIT_DIR"
+    fi
+  }
+  
+  BeforeEach 'setup'
+  AfterEach 'cleanup'
+  
+  Describe "rb init command"
+    Context "when creating a new rbproject.toml"
+      It "creates rbproject.toml in current directory"
+        cd "$TEST_INIT_DIR"
+        When run rb init
+        The status should equal 0
+        The output should include "Splendid"
+        The file "rbproject.toml" should be exist
+      End
+      
+      It "displays success message with ceremony"
+        cd "$TEST_INIT_DIR"
+        When run rb init
+        The status should equal 0
+        The output should include "Splendid!"
+        The output should include "rbproject.toml has been created"
+      End
+      
+      It "creates valid TOML file"
+        cd "$TEST_INIT_DIR"
+        When run rb init
+        The status should equal 0
+        The output should include "Splendid"
+        The contents of file "rbproject.toml" should include "[project]"
+        The contents of file "rbproject.toml" should include "[scripts]"
+      End
+      
+      It "includes project metadata section"
+        cd "$TEST_INIT_DIR"
+        When run rb init
+        The status should equal 0
+        The output should include "Splendid"
+        The contents of file "rbproject.toml" should include 'name = "Butler project template"'
+        The contents of file "rbproject.toml" should include 'description = "Please fill in"'
+      End
+      
+      It "includes sample ruby-version script"
+        cd "$TEST_INIT_DIR"
+        When run rb init
+        The status should equal 0
+        The output should include "Splendid"
+        The contents of file "rbproject.toml" should include 'ruby-version = "ruby -v"'
+      End
+      
+      It "provides helpful next steps"
+        cd "$TEST_INIT_DIR"
+        When run rb init
+        The status should equal 0
+        The output should include "You may now"
+        The output should include "rb run"
+      End
+      
+      It "references example documentation"
+        cd "$TEST_INIT_DIR"
+        When run rb init
+        The status should equal 0
+        The output should include "examples/rbproject.toml"
+      End
+    End
+    
+    Context "when rbproject.toml already exists"
+      It "gracefully refuses to overwrite existing file"
+        cd "$TEST_INIT_DIR"
+        echo "existing content" > rbproject.toml
+        When run rb init
+        The status should not equal 0
+        The stderr should include "already graces"
+        The stderr should include "this directory"
+      End
+      
+      It "provides proper guidance for resolution"
+        cd "$TEST_INIT_DIR"
+        echo "existing content" > rbproject.toml
+        When run rb init
+        The status should not equal 0
+        The stderr should include "delete the existing one first"
+      End
+      
+      It "preserves existing file content"
+        cd "$TEST_INIT_DIR"
+        echo "my precious content" > rbproject.toml
+        When run rb init
+        The status should not equal 0
+        The stderr should include "already graces"
+        The contents of file "rbproject.toml" should equal "my precious content"
+      End
+    End
+    
+    Context "working with generated rbproject.toml"
+      It "can list scripts from generated file"
+        cd "$TEST_INIT_DIR"
+        rb init >/dev/null 2>&1
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "ruby-version"
+      End
+      
+      It "can execute generated script"
+        Skip if "Ruby not available" is_ruby_available
+        cd "$TEST_INIT_DIR"
+        rb init >/dev/null 2>&1
+        When run rb -R $RUBIES_DIR run ruby-version
+        The status should equal 0
+        The output should include "ruby"
+      End
+    End
+  End
+End
diff --git a/spec/commands/project_spec.sh b/spec/commands/project_spec.sh
new file mode 100644
index 0000000..b63f3ce
--- /dev/null
+++ b/spec/commands/project_spec.sh
@@ -0,0 +1,181 @@
+#!/bin/bash
+# ShellSpec tests for Ruby Butler project file support
+# Distinguished validation of rbproject.toml and --project/-P flag
+
+Describe "Ruby Butler Project System"
+  Include spec/support/helpers.sh
+  
+  setup() {
+    TEST_PROJECT_DIR="${SHELLSPEC_TMPBASE}/project-test-$$-${RANDOM}"
+    mkdir -p "$TEST_PROJECT_DIR"
+  }
+  
+  cleanup() {
+    if [ -d "$TEST_PROJECT_DIR" ]; then
+      rm -rf "$TEST_PROJECT_DIR"
+    fi
+  }
+  
+  BeforeEach 'setup'
+  AfterEach 'cleanup'
+  
+  Describe "--project flag (-P)"
+    Context "with valid project file"
+      It "accepts --project flag with rbproject.toml"
+        cd "$TEST_PROJECT_DIR"
+        cat > custom-project.toml << 'EOF'
+[project]
+name = "Test Project"
+description = "A test project"
+
+[scripts]
+test = "echo 'test script'"
+EOF
+        When run rb -R $RUBIES_DIR --project custom-project.toml env
+        The status should equal 0
+        The output should include "Project"
+      End
+      
+      It "accepts -P short form flag"
+        cd "$TEST_PROJECT_DIR"
+        cat > custom-project.toml << 'EOF'
+[project]
+name = "Test Project"
+
+[scripts]
+test = "echo 'test'"
+EOF
+        When run rb -R $RUBIES_DIR -P custom-project.toml env
+        The status should equal 0
+        The output should include "Project"
+      End
+      
+      It "displays project name from specified file"
+        cd "$TEST_PROJECT_DIR"
+        cat > custom-project.toml << 'EOF'
+[project]
+name = "Distinguished Project"
+description = "A refined test project"
+
+[scripts]
+version = "ruby -v"
+EOF
+        When run rb -R $RUBIES_DIR -P custom-project.toml env
+        The status should equal 0
+        The output should include "Distinguished Project"
+      End
+      
+      It "displays project description when specified"
+        cd "$TEST_PROJECT_DIR"
+        cat > custom-project.toml << 'EOF'
+[project]
+name = "Test"
+description = "Sophisticated description text"
+
+[scripts]
+test = "echo test"
+EOF
+        When run rb -R $RUBIES_DIR -P custom-project.toml env
+        The status should equal 0
+        The output should include "Sophisticated description text"
+      End
+      
+      It "shows --project option in help"
+        When run rb --help
+        The status should equal 0
+        The output should include "--project"
+        The output should include "rbproject.toml"
+      End
+    End
+    
+    Context "with rb run command"
+      It "loads scripts from specified project file"
+        cd "$TEST_PROJECT_DIR"
+        cat > custom.toml << 'EOF'
+[scripts]
+custom-script = "echo 'custom script executed'"
+EOF
+        When run rb -R $RUBIES_DIR -P custom.toml run
+        The status should equal 0
+        The output should include "custom-script"
+      End
+      
+      It "executes scripts from specified project file"
+        Skip if "Ruby not available" is_ruby_available
+        cd "$TEST_PROJECT_DIR"
+        cat > custom.toml << 'EOF'
+[scripts]
+version = "ruby -v"
+EOF
+        When run rb -R $RUBIES_DIR -P custom.toml run version
+        The status should equal 0
+        The output should include "ruby"
+      End
+    End
+    
+    Context "with non-existent project file"
+      It "handles missing project file gracefully"
+        cd "$TEST_PROJECT_DIR"
+        When run rb -R $RUBIES_DIR -P nonexistent.toml run
+        The status should not equal 0
+        The stderr should include "Selection Failed"
+        The stderr should include "nonexistent.toml"
+      End
+    End
+    
+    Context "with invalid TOML"
+      It "reports TOML parsing errors clearly"
+        cd "$TEST_PROJECT_DIR"
+        cat > invalid.toml << 'EOF'
+[project
+name = "Missing bracket"
+EOF
+        When run rb -R $RUBIES_DIR -P invalid.toml run
+        The status should not equal 0
+        The stderr should include "Selection Failed"
+      End
+    End
+  End
+  
+  Describe "project file auto-detection"
+    Context "when rbproject.toml exists in current directory"
+      It "automatically discovers rbproject.toml"
+        Skip if "Ruby not available" is_ruby_available
+        cd "$TEST_PROJECT_DIR"
+        cat > rbproject.toml << 'EOF'
+[project]
+name = "Auto-detected Project"
+
+[scripts]
+version = "ruby -v"
+EOF
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "Auto-detected Project"
+      End
+      
+      It "lists scripts from auto-detected file"
+        cd "$TEST_PROJECT_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+test = "echo test"
+build = "echo build"
+EOF
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "test"
+        The output should include "build"
+      End
+    End
+    
+    Context "when no rbproject.toml exists"
+      It "provides helpful guidance when run command used"
+        cd "$TEST_PROJECT_DIR"
+        When run rb -R $RUBIES_DIR run
+        The status should not equal 0
+        The stderr should include "No project configuration"
+        The stderr should include "rbproject.toml"
+      End
+    End
+  End
+End
diff --git a/spec/commands/run_spec.sh b/spec/commands/run_spec.sh
new file mode 100644
index 0000000..8dbe449
--- /dev/null
+++ b/spec/commands/run_spec.sh
@@ -0,0 +1,230 @@
+#!/bin/bash
+# ShellSpec tests for Ruby Butler run command
+# Distinguished validation of rb run / rb r script execution
+
+Describe "Ruby Butler Run Command"
+  Include spec/support/helpers.sh
+  
+  setup() {
+    TEST_RUN_DIR="${SHELLSPEC_TMPBASE}/run-test-$$-${RANDOM}"
+    mkdir -p "$TEST_RUN_DIR"
+  }
+  
+  cleanup() {
+    if [ -d "$TEST_RUN_DIR" ]; then
+      rm -rf "$TEST_RUN_DIR"
+    fi
+  }
+  
+  BeforeEach 'setup'
+  AfterEach 'cleanup'
+  
+  Describe "rb run command"
+    Context "listing available scripts"
+      It "lists all scripts when no script name provided"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[project]
+name = "Test Project"
+
+[scripts]
+test = "echo test"
+build = "echo build"
+deploy = "echo deploy"
+EOF
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "test"
+        The output should include "build"
+        The output should include "deploy"
+      End
+      
+      It "shows project name in script list"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[project]
+name = "Sophisticated Project"
+
+[scripts]
+version = "ruby -v"
+EOF
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "Sophisticated Project"
+      End
+      
+      It "displays script descriptions when available"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+test = { command = "echo test", description = "Run test suite" }
+build = "echo build"
+EOF
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "Run test suite"
+      End
+      
+      It "handles scripts with colon notation"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+"test:unit" = "echo unit"
+"test:integration" = "echo integration"
+EOF
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "test:unit"
+        The output should include "test:integration"
+      End
+    End
+    
+    Context "executing scripts"
+      It "executes simple script command"
+        Skip if "Ruby not available" is_ruby_available
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+version = "ruby -v"
+EOF
+        When run rb -R $RUBIES_DIR run version
+        The status should equal 0
+        The output should include "ruby"
+      End
+      
+      It "executes script with detailed notation"
+        Skip if "Ruby not available" is_ruby_available
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+info = { command = "ruby -v", description = "Show version" }
+EOF
+        When run rb -R $RUBIES_DIR run info
+        The status should equal 0
+        The output should include "ruby"
+      End
+      
+      It "passes additional arguments to script"
+        Skip if "Ruby not available" is_ruby_available
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+echo-args = "ruby -e 'puts ARGV.join(\", \")'"
+EOF
+        When run rb -R $RUBIES_DIR run echo-args arg1 arg2 arg3
+        The status should equal 0
+        The output should include "arg1"
+        The output should include "arg2"
+      End
+      
+      It "handles scripts with colons in execution"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+"test:version" = "echo 'test version script'"
+EOF
+        When run rb -R $RUBIES_DIR run test:version
+        The status should equal 0
+        The output should include "test version"
+      End
+    End
+    
+    Context "rb r alias"
+      It "responds to 'r' alias for run"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+test = "echo test"
+EOF
+        When run rb -R $RUBIES_DIR r
+        The status should equal 0
+        The output should include "test"
+      End
+      
+      It "executes scripts via 'r' alias"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+hello = "echo 'Hello from rb r'"
+EOF
+        When run rb -R $RUBIES_DIR r hello
+        The status should equal 0
+        The output should include "Hello from rb r"
+      End
+    End
+    
+    Context "error handling"
+      It "reports when script name not found"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+test = "echo test"
+EOF
+        When run rb -R $RUBIES_DIR run nonexistent
+        The status should not equal 0
+        The stderr should include "Script Not Found"
+        The stderr should include "nonexistent"
+      End
+      
+      It "provides helpful suggestions for similar script names"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+test = "echo test"
+tests = "echo tests"
+EOF
+        When run rb -R $RUBIES_DIR run tset
+        The status should not equal 0
+        The stderr should include "test"
+      End
+      
+      It "handles empty scripts section gracefully"
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[project]
+name = "Empty Scripts"
+
+[scripts]
+EOF
+        When run rb -R $RUBIES_DIR run
+        The status should equal 0
+        The output should include "No scripts"
+      End
+      
+      It "reports missing rbproject.toml clearly"
+        cd "$TEST_RUN_DIR"
+        When run rb -R $RUBIES_DIR run test
+        The status should not equal 0
+        The stderr should include "No project configuration"
+        The stderr should include "rbproject.toml"
+      End
+    End
+    
+    Context "with Ruby environment"
+      It "executes gem commands within Ruby environment"
+        Skip if "Ruby not available" is_ruby_available
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+gem-version = "gem -v"
+EOF
+        When run rb -R $RUBIES_DIR run gem-version
+        The status should equal 0
+        The output should include "."
+      End
+      
+      It "provides access to bundler if available"
+        Skip if "Ruby not available" is_ruby_available
+        Skip if "Bundler not available" is_bundler_available
+        cd "$TEST_RUN_DIR"
+        cat > rbproject.toml << 'EOF'
+[scripts]
+bundle-version = "bundle -v"
+EOF
+        When run rb -R $RUBIES_DIR run bundle-version
+        The status should equal 0
+        The output should include "Bundler"
+      End
+    End
+  End
+End
diff --git a/spec/support/helpers.sh b/spec/support/helpers.sh
index 63c487f..424419e 100644
--- a/spec/support/helpers.sh
+++ b/spec/support/helpers.sh
@@ -70,6 +70,25 @@ cleanup_test_project() {
 
 # Distinguished rb command function with complete isolation
 rb() {
-    local cmd="/app/rb"
-    "$cmd" "$@"
+    # Use local build if available (for development), otherwise Docker path
+    if [ -n "$RB_TEST_BINARY" ] && [ -f "$RB_TEST_BINARY" ]; then
+        "$RB_TEST_BINARY" "$@"
+    elif [ -f "/app/rb" ]; then
+        "/app/rb" "$@"
+    elif [ -f "./target/debug/rb" ]; then
+        "./target/debug/rb" "$@"
+    else
+        # Fallback to PATH
+        command rb "$@"
+    fi
+}
+
+# Check if Ruby is available for testing
+is_ruby_available() {
+    command -v ruby >/dev/null 2>&1
+}
+
+# Check if Bundler is available for testing
+is_bundler_available() {
+    command -v bundle >/dev/null 2>&1
 }
diff --git a/tests/commands/Config.Integration.Tests.ps1 b/tests/commands/Config.Integration.Tests.ps1
new file mode 100644
index 0000000..26340ab
--- /dev/null
+++ b/tests/commands/Config.Integration.Tests.ps1
@@ -0,0 +1,206 @@
+# Integration Tests for Ruby Butler Configuration File Support
+# Tests configuration file loading, precedence, and override mechanisms
+
+BeforeAll {
+    $Script:RbPath = $env:RB_TEST_PATH
+    if (-not $Script:RbPath) {
+        throw "RB_TEST_PATH environment variable not set. Run Setup.ps1 first."
+    }
+}
+
+Describe "Configuration File Tests" {
+    Context "RB_CONFIG Environment Variable" {
+        BeforeEach {
+            # Create a temporary config file
+            $script:TempConfigPath = Join-Path $env:TEMP "test-rb-config-$([guid]::NewGuid().ToString()).toml"
+            $configContent = @"
+ruby-version = "3.2.0"
+rubies-dir = "C:/test/rubies"
+gem-home = "C:/test/gems"
+"@
+            Set-Content -Path $script:TempConfigPath -Value $configContent -Force
+            
+            # Set the environment variable
+            $env:RB_CONFIG = $script:TempConfigPath
+        }
+        
+        AfterEach {
+            # Clean up
+            Remove-Item -Path $script:TempConfigPath -ErrorAction SilentlyContinue -Force
+            Remove-Item env:RB_CONFIG -ErrorAction SilentlyContinue
+        }
+        
+        It "Should load configuration from RB_CONFIG environment variable" {
+            # Run rb --help to verify it loads without error
+            $Output = & $Script:RbPath --help 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join " ") | Should -Match "Ruby Butler"
+        }
+        
+        It "Should use config file values when RB_CONFIG is set" {
+            # Note: We can't easily test the actual values being used without
+            # running a command that shows them, but we can verify it doesn't error
+            $Output = & $Script:RbPath --version 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join " ") | Should -Match "Ruby Butler"
+        }
+        
+        It "Should apply rubies-dir from RB_CONFIG to runtime command" {
+            # Use rb runtime to check that the config value is actually used
+            $Output = & $Script:RbPath runtime 2>&1
+            # The error message should reference the configured directory
+            ($Output -join " ") | Should -Match "C:/test/rubies"
+        }
+        
+        It "Should show configured values with verbose logging" {
+            # Use -v flag to see which config was loaded
+            $Output = & $Script:RbPath -v runtime 2>&1
+            # Should show that config was loaded
+            ($Output -join " ") | Should -Match "Loading configuration from.*test-rb-config.*\.toml"
+        }
+    }
+    
+    Context "--config CLI Flag" {
+        BeforeEach {
+            # Create a temporary config file
+            $script:TempConfigPath = Join-Path $env:TEMP "test-rb-cli-config-$([guid]::NewGuid().ToString()).toml"
+            $configContent = @"
+ruby-version = "3.3.0"
+rubies-dir = "D:/custom/rubies"
+"@
+            Set-Content -Path $script:TempConfigPath -Value $configContent -Force
+        }
+        
+        AfterEach {
+            # Clean up
+            Remove-Item -Path $script:TempConfigPath -ErrorAction SilentlyContinue -Force
+        }
+        
+        It "Should load configuration from --config flag" {
+            # Run with --config flag
+            $Output = & $Script:RbPath --config $script:TempConfigPath --help 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join " ") | Should -Match "Ruby Butler"
+        }
+        
+        It "Should show --config option in help" {
+            $Output = & $Script:RbPath --help 2>&1
+            ($Output -join " ") | Should -Match "--config"
+            ($Output -join " ") | Should -Match "configuration file"
+        }
+        
+        It "Should apply rubies-dir from --config flag to runtime command" {
+            # Verify the config value is actually used
+            $Output = & $Script:RbPath --config $script:TempConfigPath runtime 2>&1
+            # The error message should reference the configured directory
+            ($Output -join " ") | Should -Match "D:/custom/rubies"
+        }
+    }
+    
+    Context "Config Precedence" {
+        BeforeEach {
+            # Create two different config files
+            $script:EnvConfigPath = Join-Path $env:TEMP "test-rb-env-config-$([guid]::NewGuid().ToString()).toml"
+            $script:CliConfigPath = Join-Path $env:TEMP "test-rb-cli-config-$([guid]::NewGuid().ToString()).toml"
+            
+            Set-Content -Path $script:EnvConfigPath -Value "ruby-version = `"3.1.0`"" -Force
+            Set-Content -Path $script:CliConfigPath -Value "ruby-version = `"3.2.0`"" -Force
+            
+            # Set environment variable
+            $env:RB_CONFIG = $script:EnvConfigPath
+        }
+        
+        AfterEach {
+            # Clean up
+            Remove-Item -Path $script:EnvConfigPath -ErrorAction SilentlyContinue -Force
+            Remove-Item -Path $script:CliConfigPath -ErrorAction SilentlyContinue -Force
+            Remove-Item env:RB_CONFIG -ErrorAction SilentlyContinue
+        }
+        
+        It "Should prioritize --config flag over RB_CONFIG environment variable" {
+            # Both config sources exist, --config should win
+            # We verify this by ensuring the command doesn't fail
+            $Output = & $Script:RbPath --config $script:CliConfigPath --help 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join " ") | Should -Match "Ruby Butler"
+        }
+        
+        It "Should prioritize CLI argument over config file" {
+            # CLI flag should override config file value
+            # Using -r flag should take precedence over any config
+            $Output = & $Script:RbPath --config $script:CliConfigPath -r 3.4.0 --help 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join " ") | Should -Match "Ruby Butler"
+        }
+        
+        It "Should verify CLI argument precedence with runtime command" {
+            # Create a config with a rubies-dir, then override it with CLI
+            $TestConfigPath = Join-Path $env:TEMP "test-precedence-$([guid]::NewGuid().ToString()).toml"
+            Set-Content -Path $TestConfigPath -Value "rubies-dir = `"C:/config/rubies`"" -Force
+            
+            # Override with CLI argument
+            $Output = & $Script:RbPath --config $TestConfigPath -R "C:/cli/rubies" runtime 2>&1
+            
+            # Should use CLI value, not config value
+            ($Output -join " ") | Should -Match "C:/cli/rubies"
+            ($Output -join " ") | Should -Not -Match "C:/config/rubies"
+            
+            Remove-Item -Path $TestConfigPath -Force
+        }
+        
+        It "Should show precedence in debug logs" {
+            # Create a config file with rubies-dir
+            $TestConfigPath = Join-Path $env:TEMP "test-debug-$([guid]::NewGuid().ToString()).toml"
+            Set-Content -Path $TestConfigPath -Value "rubies-dir = `"C:/config/rubies`"" -Force
+            
+            # Override with CLI and use -vv for debug logging
+            $Output = & $Script:RbPath --config $TestConfigPath -R "C:/cli/rubies" -vv runtime 2>&1
+            
+            # Should show merge strategy in debug logs
+            ($Output -join " ") | Should -Match "Using rubies-dir from CLI arguments"
+            
+            Remove-Item -Path $TestConfigPath -Force
+        }
+    }
+    
+    Context "Invalid Config File" {
+        BeforeEach {
+            # Create an invalid config file
+            $script:InvalidConfigPath = Join-Path $env:TEMP "test-rb-invalid-$([guid]::NewGuid().ToString()).toml"
+            Set-Content -Path $script:InvalidConfigPath -Value "this is not valid toml { [ ]" -Force
+        }
+        
+        AfterEach {
+            # Clean up
+            Remove-Item -Path $script:InvalidConfigPath -ErrorAction SilentlyContinue -Force
+        }
+        
+        It "Should handle invalid TOML file gracefully" {
+            # Invalid TOML files cause errors during parsing
+            $Output = & $Script:RbPath --config $script:InvalidConfigPath --help 2>&1
+            # If the file exists but has invalid TOML, we should get an error
+            # For now, verify the command ran (implementation may vary)
+            $Output | Should -Not -BeNullOrEmpty
+        }
+    }
+    
+    Context "Non-existent Config File" {
+        It "Should work fine with non-existent --config path" {
+            $NonExistentPath = "C:/does/not/exist/rb.toml"
+            # Should use defaults when file doesn't exist
+            $Output = & $Script:RbPath --config $NonExistentPath --help 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join " ") | Should -Match "Ruby Butler"
+        }
+        
+        It "Should work fine with non-existent RB_CONFIG" {
+            $env:RB_CONFIG = "C:/does/not/exist/rb.toml"
+            # Should use defaults when file doesn't exist
+            $Output = & $Script:RbPath --help 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join " ") | Should -Match "Ruby Butler"
+            
+            Remove-Item env:RB_CONFIG -ErrorAction SilentlyContinue
+        }
+    }
+}
diff --git a/tests/commands/Project.Integration.Tests.ps1 b/tests/commands/Project.Integration.Tests.ps1
new file mode 100644
index 0000000..58314fd
--- /dev/null
+++ b/tests/commands/Project.Integration.Tests.ps1
@@ -0,0 +1,491 @@
+# Integration Tests for Ruby Butler Project Commands
+# Tests --project/-P flag functionality with rbproject.toml files
+
+BeforeAll {
+    $Script:RbPath = $env:RB_TEST_PATH
+    if (-not $Script:RbPath) {
+        throw "RB_TEST_PATH environment variable not set. Run Setup.ps1 first."
+    }
+    
+    # Create temporary directory for test files
+    $Script:TestDir = Join-Path $env:TEMP "rb-project-tests-$(Get-Random)"
+    New-Item -ItemType Directory -Path $Script:TestDir -Force | Out-Null
+    
+    # Create a valid test rbproject.toml
+    $Script:ValidProjectFile = Join-Path $Script:TestDir "valid-project.toml"
+    @'
+[project]
+name = "Test Project"
+description = "A test project for Pester testing"
+
+[scripts]
+test = "rspec"
+"test:watch" = { command = "guard", description = "Watch and run tests" }
+lint = { command = "rubocop", description = "Run linter" }
+"lint:fix" = "rubocop -a"
+'@ | Set-Content -Path $Script:ValidProjectFile -Encoding UTF8
+    
+    # Create a project file without metadata
+    $Script:NoMetadataProjectFile = Join-Path $Script:TestDir "no-metadata.toml"
+    @'
+[scripts]
+test = "rspec"
+build = "rake build"
+'@ | Set-Content -Path $Script:NoMetadataProjectFile -Encoding UTF8
+    
+    # Create a project file with only name
+    $Script:PartialMetadataProjectFile = Join-Path $Script:TestDir "partial-metadata.toml"
+    @'
+[project]
+name = "Partial Metadata Project"
+
+[scripts]
+server = "rails server"
+'@ | Set-Content -Path $Script:PartialMetadataProjectFile -Encoding UTF8
+    
+    # Create an invalid TOML file
+    $Script:InvalidTomlFile = Join-Path $Script:TestDir "invalid.toml"
+    @'
+[project
+name = "Invalid TOML - missing closing bracket"
+
+[scripts]
+test = "rspec"
+'@ | Set-Content -Path $Script:InvalidTomlFile -Encoding UTF8
+    
+    # Create an empty file
+    $Script:EmptyFile = Join-Path $Script:TestDir "empty.toml"
+    "" | Set-Content -Path $Script:EmptyFile -Encoding UTF8
+    
+    # Path for non-existent file
+    $Script:NonExistentFile = Join-Path $Script:TestDir "does-not-exist.toml"
+}
+
+AfterAll {
+    # Clean up test directory
+    if (Test-Path $Script:TestDir) {
+        Remove-Item -Path $Script:TestDir -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}
+
+Describe "Ruby Butler - Project Flag (-P/--project)" {
+    
+    Context "Valid Project File with Full Metadata" {
+        It "Loads project file specified with -P flag" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Project"
+        }
+        
+        It "Loads project file specified with --project flag" {
+            $Output = & $Script:RbPath --project $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Project"
+        }
+        
+        It "Displays project name when specified" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Name\s*:\s*Test Project"
+        }
+        
+        It "Displays project description when specified" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Description\s*:\s*A test project for Pester testing"
+        }
+        
+        It "Displays project file path" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Project file"
+            ($Output -join "`n") | Should -Match "valid-project\.toml"
+        }
+        
+        It "Shows correct script count" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Scripts loaded\s*:\s*4"
+        }
+        
+        It "Lists all available scripts" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "test"
+            $OutputText | Should -Match "rspec"
+            $OutputText | Should -Match "test:watch"
+            $OutputText | Should -Match "guard"
+            $OutputText | Should -Match "lint"
+            $OutputText | Should -Match "rubocop"
+        }
+        
+        It "Shows script descriptions when available" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "Watch and run tests"
+            $OutputText | Should -Match "Run linter"
+        }
+    }
+    
+    Context "Project File without Metadata" {
+        It "Loads project file without [project] section" {
+            $Output = & $Script:RbPath -P $Script:NoMetadataProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Project"
+        }
+        
+        It "Does not show Name field when not specified" {
+            $Output = & $Script:RbPath -P $Script:NoMetadataProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Not -Match "Name\s*:"
+        }
+        
+        It "Does not show Description field when not specified" {
+            $Output = & $Script:RbPath -P $Script:NoMetadataProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Not -Match "Description\s*:"
+        }
+        
+        It "Still shows scripts from file without metadata" {
+            $Output = & $Script:RbPath -P $Script:NoMetadataProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Scripts loaded\s*:\s*2"
+        }
+    }
+    
+    Context "Project File with Partial Metadata" {
+        It "Shows only name when description is missing" {
+            $Output = & $Script:RbPath -P $Script:PartialMetadataProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "Name\s*:\s*Partial Metadata Project"
+            $OutputText | Should -Not -Match "Description\s*:"
+        }
+    }
+    
+    Context "Empty Project File" {
+        It "Handles empty file gracefully" {
+            $Output = & $Script:RbPath -P $Script:EmptyFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Project"
+        }
+        
+        It "Shows zero scripts for empty file" {
+            $Output = & $Script:RbPath -P $Script:EmptyFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Scripts loaded\s*:\s*0"
+        }
+    }
+    
+    Context "Invalid TOML File - Error Handling" {
+        It "Does not crash with invalid TOML syntax" {
+            $Output = & $Script:RbPath -P $Script:InvalidTomlFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+        }
+        
+        It "Shows no project detected message for invalid TOML" {
+            $Output = & $Script:RbPath -P $Script:InvalidTomlFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "No project config detected"
+        }
+        
+        It "Logs warning with verbose flag for invalid TOML" {
+            $Output = & $Script:RbPath -v -P $Script:InvalidTomlFile env 2>&1
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "WARN.*Failed to load"
+            $OutputText | Should -Match "TOML parse error|invalid"
+        }
+        
+        It "Still shows Ruby environment despite invalid project file" {
+            $Output = & $Script:RbPath -P $Script:InvalidTomlFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Ruby"
+            ($Output -join "`n") | Should -Match "Environment Summary"
+        }
+    }
+    
+    Context "Non-existent File - Error Handling" {
+        It "Does not crash when file does not exist" {
+            $Output = & $Script:RbPath -P $Script:NonExistentFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+        }
+        
+        It "Shows no project detected message for missing file" {
+            $Output = & $Script:RbPath -P $Script:NonExistentFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "No project config detected"
+        }
+        
+        It "Logs warning with verbose flag for missing file" {
+            $Output = & $Script:RbPath -v -P $Script:NonExistentFile env 2>&1
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "WARN.*Failed to load"
+            $OutputText | Should -Match "does-not-exist\.toml"
+        }
+        
+        It "Still shows Ruby environment despite missing project file" {
+            $Output = & $Script:RbPath -P $Script:NonExistentFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Ruby"
+            ($Output -join "`n") | Should -Match "Environment Summary"
+        }
+        
+        It "Shows environment ready message despite project file error" {
+            $Output = & $Script:RbPath -P $Script:NonExistentFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Environment ready"
+        }
+    }
+    
+    Context "Project Flag with Examples Directory" {
+        It "Can load example rbproject.toml from repository" {
+            $ExampleFile = Join-Path (Split-Path $Script:RbPath -Parent | Split-Path -Parent) "examples" "rbproject.toml"
+            if (Test-Path $ExampleFile) {
+                $Output = & $Script:RbPath -P $ExampleFile env 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "📋 Project"
+                ($Output -join "`n") | Should -Match "Ruby Butler Example Project"
+            }
+        }
+        
+        It "Shows all scripts from example file" {
+            $ExampleFile = Join-Path (Split-Path $Script:RbPath -Parent | Split-Path -Parent) "examples" "rbproject.toml"
+            if (Test-Path $ExampleFile) {
+                $Output = & $Script:RbPath -P $ExampleFile env 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "test.*rspec"
+                $OutputText | Should -Match "lint:fix"
+                $OutputText | Should -Match "Scripts loaded\s*:\s*20"
+            }
+        }
+    }
+    
+    Context "Relative and Absolute Paths" {
+        It "Handles relative path with .\ notation" {
+            Push-Location $Script:TestDir
+            try {
+                $Output = & $Script:RbPath -P ".\valid-project.toml" env 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Project"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Handles absolute path" {
+            $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Project"
+        }
+    }
+    
+    Context "Project Flag Overrides Auto-detection" {
+        It "Uses specified file even if rbproject.toml exists in current directory" {
+            # Create a different rbproject.toml in temp dir
+            $LocalProjectFile = Join-Path $Script:TestDir "rbproject.toml"
+            @'
+[project]
+name = "Local Project"
+
+[scripts]
+local = "echo local"
+'@ | Set-Content -Path $LocalProjectFile -Encoding UTF8
+            
+            Push-Location $Script:TestDir
+            try {
+                # Specify the valid project file (not the local one)
+                $Output = & $Script:RbPath -P $Script:ValidProjectFile env 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                # Should show the specified file, not the local one
+                $OutputText | Should -Match "Test Project"
+                $OutputText | Should -Not -Match "Local Project"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Integration with Other Flags" {
+        It "Works with -v verbose flag" {
+            $Output = & $Script:RbPath -v -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "INFO"
+            ($Output -join "`n") | Should -Match "Project"
+        }
+        
+        It "Works with -vv very verbose flag" {
+            $Output = & $Script:RbPath -vv -P $Script:ValidProjectFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "DEBUG|INFO"
+            ($Output -join "`n") | Should -Match "Project"
+        }
+    }
+}
+
+Describe "Ruby Butler - Project Flag Error Messages" {
+    Context "User-Friendly Error Messages" {
+        It "Provides helpful message when file is not found" {
+            $Output = & $Script:RbPath -v -P "completely-missing-file.toml" env 2>&1
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "Failed to load|cannot|not found|Systém nemůže nalézt"
+        }
+        
+        It "Provides helpful message for parse errors" {
+            $Output = & $Script:RbPath -v -P $Script:InvalidTomlFile env 2>&1
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "parse error|invalid"
+        }
+    }
+}
+
+Describe "Ruby Butler - gem.toml Support" {
+    BeforeAll {
+        # Create a gem.toml test file
+        $Script:GemTomlDir = Join-Path $Script:TestDir "gem-toml-test"
+        New-Item -ItemType Directory -Path $Script:GemTomlDir -Force | Out-Null
+        
+        $GemTomlFile = Join-Path $Script:GemTomlDir "gem.toml"
+        @'
+[project]
+name = "Gem TOML Project"
+description = "Testing gem.toml as alternative filename"
+
+[scripts]
+test = "rspec spec"
+build = { command = "rake build", description = "Build the gem" }
+publish = "gem push *.gem"
+'@ | Set-Content -Path $GemTomlFile -Encoding UTF8
+        
+        # Create a directory with both rbproject.toml and gem.toml
+        $Script:BothFilesDir = Join-Path $Script:TestDir "both-files-test"
+        New-Item -ItemType Directory -Path $Script:BothFilesDir -Force | Out-Null
+        
+        $RbprojectFile = Join-Path $Script:BothFilesDir "rbproject.toml"
+        @'
+[project]
+name = "RBProject File"
+
+[scripts]
+from-rbproject = "echo from rbproject.toml"
+'@ | Set-Content -Path $RbprojectFile -Encoding UTF8
+        
+        $GemFile = Join-Path $Script:BothFilesDir "gem.toml"
+        @'
+[project]
+name = "Gem File"
+
+[scripts]
+from-gem = "echo from gem.toml"
+'@ | Set-Content -Path $GemFile -Encoding UTF8
+    }
+    
+    Context "gem.toml Discovery" {
+        It "Detects gem.toml in current directory" {
+            Push-Location $Script:GemTomlDir
+            try {
+                $Output = & $Script:RbPath env 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "gem\.toml"
+                $OutputText | Should -Match "Gem TOML Project"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Lists scripts from gem.toml with rb run" {
+            Push-Location $Script:GemTomlDir
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "test.*rspec spec"
+                $OutputText | Should -Match "build.*Build the gem"
+                $OutputText | Should -Match "publish"
+                $OutputText | Should -Match "gem\.toml"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows gem.toml scripts in rb env" {
+            Push-Location $Script:GemTomlDir
+            try {
+                $Output = & $Script:RbPath env 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "Project file.*gem\.toml"
+                $OutputText | Should -Match "Scripts loaded.*3"
+                $OutputText | Should -Match "test.*rspec spec"
+                $OutputText | Should -Match "build.*rake build"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Can specify gem.toml with -P flag" {
+            $GemTomlFile = Join-Path $Script:GemTomlDir "gem.toml"
+            $Output = & $Script:RbPath -P $GemTomlFile env 2>&1
+            $LASTEXITCODE | Should -Be 0
+            $OutputText = $Output -join "`n"
+            $OutputText | Should -Match "gem\.toml"
+            $OutputText | Should -Match "Gem TOML Project"
+        }
+    }
+    
+    Context "File Priority" {
+        It "Prefers rbproject.toml over gem.toml when both exist" {
+            Push-Location $Script:BothFilesDir
+            try {
+                $Output = & $Script:RbPath env 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                # Should find rbproject.toml, not gem.toml
+                # Check for the full path ending with rbproject.toml
+                $OutputText | Should -Match "rbproject\.toml"
+                $OutputText | Should -Match "RBProject File"
+                $OutputText | Should -Not -Match "Gem File"
+                $OutputText | Should -Match "from-rbproject"
+                $OutputText | Should -Not -Match "from-gem"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Uses rbproject.toml for rb run when both files exist" {
+            Push-Location $Script:BothFilesDir
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "rbproject\.toml"
+                $OutputText | Should -Match "from-rbproject"
+                $OutputText | Should -Not -Match "from-gem"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Error Messages Mention Both Filenames" {
+        It "Mentions both rbproject.toml and gem.toml when no config found" {
+            # Create a truly isolated temp directory (not under TestDir which might have project files)
+            $IsolatedDir = Join-Path $env:TEMP "rb-isolated-test-$(Get-Random)"
+            New-Item -ItemType Directory -Path $IsolatedDir -Force | Out-Null
+            
+            Push-Location $IsolatedDir
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "rbproject\.toml.*gem\.toml|gem\.toml.*rbproject\.toml"
+            } finally {
+                Pop-Location
+                Remove-Item -Path $IsolatedDir -Recurse -Force -ErrorAction SilentlyContinue
+            }
+        }
+    }
+}
diff --git a/tests/commands/Run.Integration.Tests.ps1 b/tests/commands/Run.Integration.Tests.ps1
new file mode 100644
index 0000000..6cdbeed
--- /dev/null
+++ b/tests/commands/Run.Integration.Tests.ps1
@@ -0,0 +1,787 @@
+# Integration Tests for Ruby Butler Run Command
+# Tests rb run / rb r command functionality with rbproject.toml scripts
+
+BeforeAll {
+    $Script:RbPath = $env:RB_TEST_PATH
+    if (-not $Script:RbPath) {
+        throw "RB_TEST_PATH environment variable not set. Run Setup.ps1 first."
+    }
+    
+    # Create temporary directory for test files
+    $Script:TestDir = Join-Path $env:TEMP "rb-run-tests-$(Get-Random)"
+    New-Item -ItemType Directory -Path $Script:TestDir -Force | Out-Null
+    
+    # Create a project with various script types
+    $Script:ProjectWithScripts = Join-Path $Script:TestDir "with-scripts"
+    New-Item -ItemType Directory -Path $Script:ProjectWithScripts -Force | Out-Null
+    
+    $ProjectFile = Join-Path $Script:ProjectWithScripts "rbproject.toml"
+    @'
+[project]
+name = "Test Runner Project"
+description = "Project for testing rb run command"
+
+[scripts]
+# Simple scripts (platform-independent commands)
+version = "ruby -v"
+gem-version = "gem -v"
+help = "ruby --help"
+
+# Scripts with descriptions
+info = { command = "ruby -v", description = "Show Ruby version information" }
+check = { command = "gem -v", description = "Verify gem installation" }
+
+# Scripts with colons (namespace-style)
+"test:version" = "ruby -v"
+"test:env" = { command = "gem env", description = "Show gem environment" }
+
+# Multi-word commands
+list-gems = "gem list --local"
+'@ | Set-Content -Path $ProjectFile -Encoding UTF8
+    
+    # Create empty project (no scripts)
+    $Script:ProjectNoScripts = Join-Path $Script:TestDir "no-scripts"
+    New-Item -ItemType Directory -Path $Script:ProjectNoScripts -Force | Out-Null
+    
+    $EmptyProjectFile = Join-Path $Script:ProjectNoScripts "rbproject.toml"
+    @'
+[project]
+name = "Empty Project"
+
+[scripts]
+'@ | Set-Content -Path $EmptyProjectFile -Encoding UTF8
+    
+    # Create project without rbproject.toml
+    $Script:ProjectNoConfig = Join-Path $Script:TestDir "no-config"
+    New-Item -ItemType Directory -Path $Script:ProjectNoConfig -Force | Out-Null
+    
+    # Create project with only simple scripts (no descriptions)
+    $Script:ProjectSimple = Join-Path $Script:TestDir "simple"
+    New-Item -ItemType Directory -Path $Script:ProjectSimple -Force | Out-Null
+    
+    $SimpleProjectFile = Join-Path $Script:ProjectSimple "rbproject.toml"
+    @'
+[scripts]
+version = "ruby -v"
+help = "ruby --help"
+'@ | Set-Content -Path $SimpleProjectFile -Encoding UTF8
+}
+
+AfterAll {
+    # Clean up test directory
+    if (Test-Path $Script:TestDir) {
+        Remove-Item -Path $Script:TestDir -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}
+
+Describe "Ruby Butler - Run Command (rb run)" {
+    
+    Context "Listing Available Scripts - Basic Functionality" {
+        It "Lists scripts when no script name provided" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Run Project Scripts"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows project name in list output" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Test Runner Project"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows project description in list output" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Project for testing rb run command"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows Usage section" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "Usage:"
+                $OutputText | Should -Match "rb run <SCRIPT>"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Lists all available scripts" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "version"
+                $OutputText | Should -Match "gem-version"
+                $OutputText | Should -Match "info"
+                $OutputText | Should -Match "check"
+                $OutputText | Should -Match "test:version"
+                $OutputText | Should -Match "test:env"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows script descriptions when available" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "Show Ruby version information"
+                $OutputText | Should -Match "Verify gem installation"
+                $OutputText | Should -Match "Show gem environment"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows Details section with project path and script count" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "Details:"
+                $OutputText | Should -Match "Project.*rbproject\.toml"
+                $OutputText | Should -Match "Scripts.*8"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Listing Scripts - Short Alias (rb r)" {
+        It "Works with 'r' alias" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath r 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Run Project Scripts"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Lists scripts with 'r' alias just like 'run'" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath r 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "version"
+                $OutputText | Should -Match "gem-version"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Listing Scripts - Empty Project" {
+        It "Handles project with no scripts gracefully" {
+            Push-Location $Script:ProjectNoScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "No scripts defined"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows helpful message about adding scripts" {
+            Push-Location $Script:ProjectNoScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "To define scripts, add them to"
+                $OutputText | Should -Match "rbproject\.toml"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows example syntax for adding scripts" {
+            Push-Location $Script:ProjectNoScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "\[scripts\]"
+                $OutputText | Should -Match 'test.*=.*"rspec"'
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Listing Scripts - No Project File" {
+        It "Shows error when no rbproject.toml exists" {
+            Push-Location $Script:ProjectNoConfig
+            try {
+                $Output = & $Script:RbPath run 2>&1 | Out-String
+                $Output | Should -Match "No Project Configuration|not found"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Returns non-zero exit code when no project file exists" {
+            Push-Location $Script:ProjectNoConfig
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Not -Be 0
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Executing Scripts - Simple Commands" {
+        It "Executes simple script successfully" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run version 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Executes gem command successfully" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run gem-version 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "\d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Executes script with description" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run info 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Executes script with colon in name" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run test:version 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Executing Scripts - Short Alias" {
+        It "Executes script with 'r' alias" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath r version 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Executes colon-named script with 'r' alias" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath r test:version 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Executing Scripts - Error Handling" {
+        It "Shows error for non-existent script" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run nonexistent 2>&1 | Out-String
+                $Output | Should -Match "not found|Script .* not found"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Returns non-zero exit code for non-existent script" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run nonexistent 2>&1
+                $LASTEXITCODE | Should -Not -Be 0
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows available scripts when script not found" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run nonexistent 2>&1 | Out-String
+                $Output | Should -Match "Available scripts"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Integration with --project Flag" {
+        It "Lists scripts from specified project file" {
+            $ProjectFile = Join-Path $Script:ProjectWithScripts "rbproject.toml"
+            $Output = & $Script:RbPath -P $ProjectFile run 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Run Project Scripts"
+            ($Output -join "`n") | Should -Match "version"
+        }
+        
+        It "Executes script from specified project file" {
+            $ProjectFile = Join-Path $Script:ProjectWithScripts "rbproject.toml"
+            Push-Location $Script:TestDir  # Different directory
+            try {
+                $Output = & $Script:RbPath -P $ProjectFile run version 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Uses specified project file even from different directory" {
+            $ProjectFile = Join-Path $Script:ProjectWithScripts "rbproject.toml"
+            Push-Location $Script:TestDir
+            try {
+                $Output = & $Script:RbPath -P $ProjectFile run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Test Runner Project"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Output Format - Professional Styling" {
+        It "Uses emoji in title" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                # Emoji rendering varies by terminal, just check for the text
+                ($Output -join "`n") | Should -Match "Run Project Scripts"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows Scripts section with colon" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                ($Output -join "`n") | Should -Match "Scripts:"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Shows aligned script list" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                # Should have some output with scripts
+                ($Output -join "`n").Length | Should -BeGreaterThan 100
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Simple Project without Metadata" {
+        It "Lists scripts even without [project] section" {
+            Push-Location $Script:ProjectSimple
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "version"
+                $OutputText | Should -Match "help"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Executes scripts without [project] section" {
+            Push-Location $Script:ProjectSimple
+            try {
+                $Output = & $Script:RbPath run version 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Does not show project name when not specified" {
+            Push-Location $Script:ProjectSimple
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                # Should go straight from title to Usage section
+                $OutputText = $Output -join "`n"
+                $OutputText | Should -Match "Run Project Scripts[\s\r\n]+Usage:"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Cross-Command Consistency" {
+        It "Works with verbose flag" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath -v run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Run Project Scripts"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Works with very verbose flag" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath -vv run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Run Project Scripts"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Combines with --project flag correctly" {
+            $ProjectFile = Join-Path $Script:ProjectWithScripts "rbproject.toml"
+            $Output = & $Script:RbPath -v -P $ProjectFile run 2>&1
+            $LASTEXITCODE | Should -Be 0
+            ($Output -join "`n") | Should -Match "Run Project Scripts"
+        }
+    }
+}
+
+Describe "Ruby Butler - Run Command Edge Cases" {
+    
+    Context "Script Name Variations" {
+        It "Handles script names with hyphens" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath run gem-version 2>&1
+                $LASTEXITCODE | Should -Be 0
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Handles script names with multiple colons" {
+            # Create temporary project with multi-colon script
+            $TempProject = Join-Path $Script:TestDir "multi-colon"
+            New-Item -ItemType Directory -Path $TempProject -Force | Out-Null
+            @'
+[scripts]
+"db:migrate:up" = "ruby -v"
+'@ | Set-Content (Join-Path $TempProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $TempProject
+            try {
+                $Output = & $Script:RbPath run 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "db:migrate:up"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Case Sensitivity" {
+        It "Script names are case-sensitive on all platforms" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                # 'version' exists but 'Version' doesn't
+                $Output = & $Script:RbPath run Version 2>&1 | Out-String
+                # Should fail to find 'Version'
+                $Output | Should -Match "not found|Script .* not found"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Performance with Many Scripts" {
+        It "Handles projects with many scripts efficiently" {
+            # Create project with 50 scripts
+            $LargeProject = Join-Path $Script:TestDir "large"
+            New-Item -ItemType Directory -Path $LargeProject -Force | Out-Null
+            
+            $Scripts = "[scripts]`n"
+            for ($i = 1; $i -le 50; $i++) {
+                $Scripts += "script$i = `"ruby -v`"`n"
+            }
+            $Scripts | Set-Content (Join-Path $LargeProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $LargeProject
+            try {
+                $Stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
+                $Output = & $Script:RbPath run 2>&1
+                $Stopwatch.Stop()
+                
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Scripts.*50"
+                # Should complete in reasonable time (< 5 seconds)
+                $Stopwatch.ElapsedMilliseconds | Should -BeLessThan 5000
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+}
+
+Describe "Ruby Butler - Run Command Delegation to Exec" {
+    
+    Context "Exec Command Delegation" {
+        It "Delegates to exec command for script execution" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath -v run version 2>&1 | Out-String
+                # Should show exec-related log messages
+                $Output | Should -Match "Delegating to exec command"
+                $Output | Should -Match "Preparing to execute"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Parses script command correctly" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath -vv run version 2>&1 | Out-String
+                # Should parse "ruby -v" into program and args (debug level logging)
+                $Output | Should -Match "Program: ruby"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Passes additional arguments to executed command" {
+            # Create project with ruby -e script
+            $EchoProject = Join-Path $Script:TestDir "echo-args"
+            New-Item -ItemType Directory -Path $EchoProject -Force | Out-Null
+            @'
+[scripts]
+echo = "ruby -e"
+'@ | Set-Content (Join-Path $EchoProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $EchoProject
+            try {
+                # Pass additional arguments after the script name
+                $Output = & $Script:RbPath run echo "puts ARGV.inspect" arg1 arg2 2>&1 | Out-String
+                # Should show the arguments were passed
+                $Output | Should -Match 'arg1.*arg2'
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Uses same environment composition as exec" {
+            Push-Location $Script:ProjectWithScripts
+            try {
+                $Output = & $Script:RbPath -v run version 2>&1 | Out-String
+                # Should show environment composition messages (same as exec)
+                $Output | Should -Match "Environment composition complete"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Command Parsing" {
+        It "Handles commands with multiple arguments" {
+            # Create project with multi-arg command
+            $MultiArgProject = Join-Path $Script:TestDir "multi-arg"
+            New-Item -ItemType Directory -Path $MultiArgProject -Force | Out-Null
+            @'
+[scripts]
+multi = "ruby -e \"puts 'test'\""
+'@ | Set-Content (Join-Path $MultiArgProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $MultiArgProject
+            try {
+                $Output = & $Script:RbPath run multi 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "test"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Preserves quoted arguments in command" {
+            # Create project with quoted command
+            $QuotedProject = Join-Path $Script:TestDir "quoted"
+            New-Item -ItemType Directory -Path $QuotedProject -Force | Out-Null
+            @'
+[scripts]
+hello = "ruby -e \"puts 'Hello World'\""
+'@ | Set-Content (Join-Path $QuotedProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $QuotedProject
+            try {
+                $Output = & $Script:RbPath run hello 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "Hello World"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Handles commands with extra whitespace" {
+            # Create project with extra spaces
+            $SpaceProject = Join-Path $Script:TestDir "spaces"
+            New-Item -ItemType Directory -Path $SpaceProject -Force | Out-Null
+            @'
+[scripts]
+spaced = "ruby   -v"
+'@ | Set-Content (Join-Path $SpaceProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $SpaceProject
+            try {
+                $Output = & $Script:RbPath run spaced 2>&1
+                $LASTEXITCODE | Should -Be 0
+                ($Output -join "`n") | Should -Match "ruby \d+\.\d+\.\d+"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Bundler Integration via Exec" {
+        It "Detects bundler environment when Gemfile exists" {
+            # Create project with Gemfile
+            $BundlerProject = Join-Path $Script:TestDir "bundler-detect"
+            New-Item -ItemType Directory -Path $BundlerProject -Force | Out-Null
+            
+            # Create minimal Gemfile
+            @'
+source 'https://rubygems.org'
+gem 'rake'
+'@ | Set-Content (Join-Path $BundlerProject "Gemfile") -Encoding UTF8
+            
+            @'
+[scripts]
+version = "ruby -v"
+'@ | Set-Content (Join-Path $BundlerProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $BundlerProject
+            try {
+                $Output = & $Script:RbPath -v run version 2>&1 | Out-String
+                # Should detect bundler environment
+                $Output | Should -Match "Bundler.*detected|Found Gemfile"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Triggers bundle sync when needed" {
+            # Create project with Gemfile but no bundle install
+            $BundlerSyncProject = Join-Path $Script:TestDir "bundler-sync"
+            New-Item -ItemType Directory -Path $BundlerSyncProject -Force | Out-Null
+            
+            # Create minimal Gemfile
+            @'
+source 'https://rubygems.org'
+gem 'rake'
+'@ | Set-Content (Join-Path $BundlerSyncProject "Gemfile") -Encoding UTF8
+            
+            @'
+[scripts]
+test = "ruby -v"
+'@ | Set-Content (Join-Path $BundlerSyncProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $BundlerSyncProject
+            try {
+                $Output = & $Script:RbPath run test 2>&1 | Out-String
+                # Should trigger bundle sync if needed
+                $Output | Should -Match "ruby \d+\.\d+\.\d+|Butler Notice|Bundle complete"
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+    
+    Context "Error Handling via Exec" {
+        It "Provides helpful error for non-existent commands" {
+            # Create project with non-existent command
+            $BadCommandProject = Join-Path $Script:TestDir "bad-command"
+            New-Item -ItemType Directory -Path $BadCommandProject -Force | Out-Null
+            @'
+[scripts]
+missing = "nonexistent-command-xyz"
+'@ | Set-Content (Join-Path $BadCommandProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $BadCommandProject
+            try {
+                $Output = & $Script:RbPath run missing 2>&1 | Out-String
+                # Should get exec's helpful error message
+                $Output | Should -Match "My sincerest apologies|command.*appears to be.*absent|not found"
+            } finally {
+                Pop-Location
+            }
+        }
+        
+        It "Handles command exit codes correctly" {
+            # Create project with failing command
+            $FailProject = Join-Path $Script:TestDir "fail"
+            New-Item -ItemType Directory -Path $FailProject -Force | Out-Null
+            @'
+[scripts]
+fail = "ruby -e \"exit 42\""
+'@ | Set-Content (Join-Path $FailProject "rbproject.toml") -Encoding UTF8
+            
+            Push-Location $FailProject
+            try {
+                $Output = & $Script:RbPath run fail 2>&1
+                # Should exit with the command's exit code
+                $LASTEXITCODE | Should -Be 42
+            } finally {
+                Pop-Location
+            }
+        }
+    }
+}