feat(config): implement project-level config discovery for .terraphim/

- Add project.rs with discover() function that walks up from cwd to find .terraphim/
- Change global_shortcut from String to Option<String> in Config
- Add merge_with() and with_project() methods to ConfigBuilder
- Update TuiService::new to accept no_project_config parameter
- Add merge_project_config() helper that discovers and merges project config
- Update all call sites and tests to use new signatures

Refs #1674

Author: Alex

crates/terraphim_agent/src/main.rs

@@ -2049,7 +2049,7 @@ async fn run_offline_command(
         return run_learn_command(sub).await;
     }
 
-    let service = TuiService::new(config_path).await?;
+    let service = TuiService::new(config_path, false).await?;
 
     match command {
         Command::Search {
@@ -5087,7 +5087,7 @@ fn ui_loop(
 
     #[cfg(not(feature = "server"))]
     let backend = {
-        let service = rt.block_on(async { TuiService::new(None).await })?;
+        let service = rt.block_on(async { TuiService::new(None, false).await })?;
         crate::tui_backend::TuiBackend::Local(service)
     };
 

crates/terraphim_agent/src/service.rs

@@ -1,4 +1,5 @@
 use anyhow::Result;
+use std::path::PathBuf;
 use std::sync::Arc;
 use terraphim_config::{Config, ConfigBuilder, ConfigId, ConfigState};
 use terraphim_persistence::Persistable;
@@ -24,7 +25,10 @@ impl TuiService {
     ///    JSON and saves to persistence; subsequent runs use persistence so CLI changes stick)
     /// 3. Persistence layer (SQLite)
     /// 4. Embedded defaults (hardcoded roles)
-    pub async fn new(config_path: Option<String>) -> Result<Self> {
+    ///
+    /// If `no_project_config` is false, project-level `.terraphim/config.json` is discovered
+    /// and merged on top of the loaded configuration.
+    pub async fn new(config_path: Option<String>, no_project_config: bool) -> Result<Self> {
         // Initialize logging
         terraphim_service::logging::init_logging(
             terraphim_service::logging::detect_logging_config(),
@@ -36,7 +40,10 @@ impl TuiService {
         if let Some(ref path) = config_path {
             log::info!("Loading config from --config flag: '{}'", path);
             match Config::load_from_json_file(path) {
-                Ok(config) => {
+                Ok(mut config) => {
+                    if !no_project_config {
+                        Self::merge_project_config(&mut config);
+                    }
                     return Self::from_config(config).await;
                 }
                 Err(e) => {
@@ -71,7 +78,12 @@ impl TuiService {
         // Priority 2: role_config in settings.toml (bootstrap-then-persistence)
         if let Some(ref role_config_path) = device_settings.role_config {
             log::info!("Found role_config in settings.toml: '{}'", role_config_path);
-            return Self::load_with_role_config(role_config_path, &device_settings).await;
+            return Self::load_with_role_config(
+                role_config_path,
+                &device_settings,
+                no_project_config,
+            )
+            .await;
         }
 
         // Priority 3 & 4: Persistence -> embedded defaults (existing behavior)
@@ -84,15 +96,19 @@ impl TuiService {
                 }
                 Err(_) => {
                     log::debug!("No saved config found, using default embedded");
-                    return Self::new_with_embedded_defaults().await;
+                    return Self::new_with_embedded_defaults(no_project_config).await;
                 }
             },
             Err(e) => {
                 log::warn!("Failed to build config: {:?}, using default", e);
-                return Self::new_with_embedded_defaults().await;
+                return Self::new_with_embedded_defaults(no_project_config).await;
             }
         };
 
+        let mut config = config;
+        if !no_project_config {
+            Self::merge_project_config(&mut config);
+        }
         Self::from_config(config).await
     }
 
@@ -104,6 +120,7 @@ impl TuiService {
     async fn load_with_role_config(
         role_config_path: &str,
         device_settings: &DeviceSettings,
+        no_project_config: bool,
     ) -> Result<Self> {
         // Try persistence first (preserves runtime changes like `config set`)
         if let Ok(mut empty_config) = ConfigBuilder::new_with_id(ConfigId::Embedded).build() {
@@ -113,7 +130,11 @@ impl TuiService {
                         "Loaded {} role(s) from persistence (role_config bootstrap already done)",
                         persisted.roles.len()
                     );
-                    return Self::from_config(persisted).await;
+                    let mut config = persisted;
+                    if !no_project_config {
+                        Self::merge_project_config(&mut config);
+                    }
+                    return Self::from_config(config).await;
                 }
             }
         }
@@ -153,6 +174,9 @@ impl TuiService {
                     log::warn!("Failed to save bootstrapped config to persistence: {:?}", e);
                 }
 
+                if !no_project_config {
+                    Self::merge_project_config(&mut config);
+                }
                 Self::from_config(config).await
             }
             Err(e) => {
@@ -161,18 +185,21 @@ impl TuiService {
                     role_config_path,
                     e
                 );
-                Self::new_with_embedded_defaults().await
+                Self::new_with_embedded_defaults(no_project_config).await
             }
         }
     }
 
     /// Initialize service strictly from the embedded default configuration.
     ///
     /// This constructor avoids touching host-specific config/state and is used by tests.
-    pub async fn new_with_embedded_defaults() -> Result<Self> {
-        let config = ConfigBuilder::new_with_id(ConfigId::Embedded)
+    pub async fn new_with_embedded_defaults(no_project_config: bool) -> Result<Self> {
+        let mut config = ConfigBuilder::new_with_id(ConfigId::Embedded)
             .build_default_embedded()
             .build()?;
+        if !no_project_config {
+            Self::merge_project_config(&mut config);
+        }
         Self::from_config(config).await
     }
 
@@ -186,6 +213,28 @@ impl TuiService {
         })
     }
 
+    fn merge_project_config(config: &mut Config) {
+        if let Ok(Some(path)) = terraphim_config::project::discover(None) {
+            let config_path = path.join("config.json");
+            if config_path.is_file() {
+                if let Ok(project_config) =
+                    terraphim_config::project::ProjectConfig::from_file(&config_path)
+                {
+                    log::info!("Merging project config from '{}'", config_path.display());
+                    let builder = ConfigBuilder::from_config(
+                        config.clone(),
+                        DeviceSettings::new(),
+                        PathBuf::new(),
+                    );
+                    *config = builder
+                        .merge_with(&project_config)
+                        .build()
+                        .unwrap_or_else(|_| config.clone());
+                }
+            }
+        }
+    }
+
     /// Get the current configuration
     pub async fn get_config(&self) -> terraphim_config::Config {
         let config = self.config_state.config.lock().await;

crates/terraphim_agent/tests/tui_service_tests.rs

@@ -12,7 +12,7 @@ use terraphim_types::RoleName;
 /// Test that TuiService can be created and basic methods work
 #[tokio::test]
 async fn test_tui_service_creation() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
 
     // Get the current config
     let config = service.get_config().await;
@@ -63,7 +63,7 @@ async fn test_tui_service_new_uses_host_settings_path() -> Result<()> {
 /// Test the search method with default role
 #[tokio::test]
 async fn test_tui_service_search() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
 
     // Search with the selected role
     let selected_role = service.get_selected_role().await;
@@ -88,7 +88,7 @@ async fn test_tui_service_search() -> Result<()> {
 /// Test autocomplete method
 #[tokio::test]
 async fn test_tui_service_autocomplete() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
     let role_name = service.get_selected_role().await;
 
     // Autocomplete may fail if no thesaurus is loaded, which is expected
@@ -113,7 +113,7 @@ async fn test_tui_service_autocomplete() -> Result<()> {
 /// Test replace_matches method
 #[tokio::test]
 async fn test_tui_service_replace_matches() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
     let role_name = service.get_selected_role().await;
 
     let text = "This is a test with some terms to replace.";
@@ -141,7 +141,7 @@ async fn test_tui_service_replace_matches() -> Result<()> {
 /// Test summarize method
 #[tokio::test]
 async fn test_tui_service_summarize() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
     let role_name = service.get_selected_role().await;
 
     let content = "This is a test paragraph that needs to be summarized. It contains multiple sentences with various topics and information that should be condensed.";
@@ -171,7 +171,7 @@ async fn test_tui_service_summarize() -> Result<()> {
 /// Test list roles with info
 #[tokio::test]
 async fn test_tui_service_list_roles_with_info() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
 
     let roles = service.list_roles_with_info().await;
 
@@ -186,7 +186,7 @@ async fn test_tui_service_list_roles_with_info() -> Result<()> {
 /// Test find_matches method
 #[tokio::test]
 async fn test_tui_service_find_matches() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
     let role_name = service.get_selected_role().await;
 
     let text = "This is a test paragraph with some terms to match.";
@@ -212,7 +212,7 @@ async fn test_tui_service_find_matches() -> Result<()> {
 /// Test that role discovery works with shortnames and case-insensitive lookups
 #[tokio::test]
 async fn test_tui_service_find_role_by_shortname() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
     let roles = service.list_roles_with_info().await;
 
     let (role_name, shortname) = roles
@@ -241,7 +241,7 @@ async fn test_tui_service_find_role_by_shortname() -> Result<()> {
 /// Test that updating the selected role persists across service queries
 #[tokio::test]
 async fn test_tui_service_update_selected_role() -> Result<()> {
-    let service = TuiService::new_with_embedded_defaults().await?;
+    let service = TuiService::new_with_embedded_defaults(true).await?;
     let current_role = service.get_selected_role().await;
 
     let new_role = service

crates/terraphim_agent/tests/unit_test.rs

@@ -121,7 +121,10 @@ fn test_config_response_deserialization() {
     let config_response = response.unwrap();
     assert_eq!(config_response.status, "success");
     assert_eq!(config_response.config.selected_role.to_string(), "Default");
-    assert_eq!(config_response.config.global_shortcut, "Ctrl+Space");
+    assert_eq!(
+        config_response.config.global_shortcut,
+        Some("Ctrl+Space".to_string())
+    );
     assert!(
         config_response
             .config

crates/terraphim_config/src/lib.rs

@@ -46,6 +46,9 @@ use crate::llm_router::LlmRouterConfig;
 // LLM Router configuration
 pub mod llm_router;
 
+// Project-level configuration discovery
+pub mod project;
+
 /// Convenience alias for `Result<T, TerraphimConfigError>` used throughout this crate.
 pub type Result<T> = std::result::Result<T, TerraphimConfigError>;
 
@@ -846,7 +849,37 @@ impl ConfigBuilder {
 
     /// Set the global shortcut for the config
     pub fn global_shortcut(mut self, global_shortcut: &str) -> Self {
-        self.config.global_shortcut = global_shortcut.to_string();
+        self.config.global_shortcut = Some(global_shortcut.to_string());
+        self
+    }
+
+    /// Merge with a project config.
+    ///
+    /// Project roles fully replace global roles (by RoleName), not deep-merge.
+    /// Project global_shortcut, if present, overrides the global one.
+    pub fn merge_with(mut self, project_config: &crate::project::ProjectConfig) -> Self {
+        if let Some(ref shortcut) = project_config.global_shortcut {
+            self.config.global_shortcut = Some(shortcut.clone());
+        }
+        for (name, role) in &project_config.roles {
+            let role_name = RoleName::new(name);
+            self.config.roles.insert(role_name, role.clone());
+        }
+        self
+    }
+
+    /// Apply project config discovery and merge if found.
+    ///
+    /// Returns self unchanged if no project config is found.
+    pub fn with_project(self) -> Self {
+        if let Ok(Some(path)) = crate::project::discover(None) {
+            let config_path = path.join("config.json");
+            if config_path.is_file() {
+                if let Ok(project_config) = crate::project::ProjectConfig::from_file(&config_path) {
+                    return self.merge_with(&project_config);
+                }
+            }
+        }
         self
     }
 
@@ -915,7 +948,8 @@ pub struct Config {
     /// Identifier for the config
     pub id: ConfigId,
     /// Global shortcut for activating terraphim desktop
-    pub global_shortcut: String,
+    #[schemars(default)]
+    pub global_shortcut: Option<String>,
     /// User roles with their respective settings
     #[schemars(skip)]
     pub roles: AHashMap<RoleName, Role>,
@@ -928,7 +962,7 @@ impl Config {
     fn empty() -> Self {
         Self {
             id: ConfigId::Server, // Default to Server
-            global_shortcut: "Ctrl+X".to_string(),
+            global_shortcut: None,
             roles: AHashMap::new(),
             default_role: RoleName::new("Default"),
             selected_role: RoleName::new("Default"),
@@ -1516,15 +1550,15 @@ mod tests {
             .add_role("dummy", dummy_role())
             .build()
             .unwrap();
-        assert_eq!(config.global_shortcut, "Ctrl+X");
+        assert_eq!(config.global_shortcut, None);
         let device_settings = DeviceSettings::new();
         let settings_path = PathBuf::from(".");
         let new_config = ConfigBuilder::from_config(config, device_settings, settings_path)
             .global_shortcut("Ctrl+/")
             .build()
             .unwrap();
 
-        assert_eq!(new_config.global_shortcut, "Ctrl+/");
+        assert_eq!(new_config.global_shortcut, Some("Ctrl+/".to_string()));
     }
 
     fn dummy_role() -> Role {