feat: Centralize configuration in ~/.codegraph directory

Changed configuration system to use a centralized user-level directory:

## Primary Changes
- Updated ConfigManager to prioritize ~/.codegraph/ as primary config directory
- Added fallback to ./config/ for backward compatibility
- Added fallback to current directory as last resort

## New Features
- `ConfigManager::init_user_config_dir()` - Initialize ~/.codegraph with defaults
- `ConfigManager::get_config_dir()` - Get config dir with custom override
- Automatic directory priority: ~/.codegraph → ./config → current dir
- Creates README.txt in ~/.codegraph explaining the directory structure

## Benefits
- **Centralized**: All CodeGraph configs in one uniform location
- **User-level**: Config follows user across projects
- **Standard practice**: Follows Unix/Linux convention (~/.config pattern)
- **Backward compatible**: Existing ./config setups continue to work
- **Cleaner projects**: Keeps project directories focused on code

## Documentation
- Created comprehensive CONFIGURATION_GUIDE.md
- Updated README.md to reflect new config directory
- Added config/README.md explaining migration
- Updated SURREALDB_GUIDE.md with new paths

## Configuration Loading Order
1. ~/.codegraph/default.toml (base)
2. ~/.codegraph/{environment}.toml (dev/staging/prod)
3. ~/.codegraph/local.toml (machine-specific overrides)
4. ./config/ (backward compatibility)
5. Environment variables (CODEGRAPH__* prefix)

Users can initialize ~/.codegraph by:
- Calling ConfigManager::init_user_config_dir(true)
- Manually: mkdir -p ~/.codegraph && cp config/*.toml ~/.codegraph/

Existing projects using ./config will continue to work seamlessly.

Author: claude

README.md

@@ -323,10 +323,18 @@ cargo build --release --bin codegraph-setup --features all-cloud-providers
 
 ### Manual Configuration
 
+**Configuration directory: `~/.codegraph/`**
+
+All configuration files are stored in `~/.codegraph/` in TOML format.
+
 Configuration is loaded from (in order):
-1. `./.codegraph.toml` (project-specific)
-2. `~/.codegraph/config.toml` (global)
-3. Environment variables
+1. `~/.codegraph/default.toml` (base configuration)
+2. `~/.codegraph/{environment}.toml` (e.g., development.toml, production.toml)
+3. `~/.codegraph/local.toml` (local overrides, machine-specific)
+4. `./config/` (fallback for backward compatibility)
+5. Environment variables (CODEGRAPH__* prefix)
+
+**See [Configuration Guide](docs/CONFIGURATION_GUIDE.md) for complete documentation.**
 
 **Full configuration example:**
 ```toml

config/README.md

@@ -0,0 +1,128 @@
+# CodeGraph Configuration Files
+
+## Important: Configuration Directory Migration
+
+**As of the latest version, CodeGraph uses `~/.codegraph` as the primary configuration directory.**
+
+### New Location: `~/.codegraph`
+
+All user-level configuration files should now be placed in:
+
+```
+~/.codegraph/
+```
+
+This provides a centralized, uniform location for all CodeGraph configuration across your system.
+
+### Why the Change?
+
+- **Centralized**: All CodeGraph configs in one place, regardless of project
+- **User-level**: Configurations follow you across different projects
+- **Standard practice**: Follows Unix/Linux convention for user configuration
+- **Cleaner projects**: Keeps project directories focused on code
+
+### Migration
+
+To migrate your existing configurations:
+
+```bash
+# Create the directory
+mkdir -p ~/.codegraph
+
+# Copy existing configs
+cp config/*.toml ~/.codegraph/
+
+# Or symlink for development (keeps backward compatibility)
+ln -s $(pwd)/config ~/.codegraph
+```
+
+### Backward Compatibility
+
+CodeGraph maintains backward compatibility by checking directories in this order:
+
+1. **`~/.codegraph/`** (Primary)
+2. **`./config/`** (This directory - fallback)
+3. **Current directory** (last resort)
+
+If `~/.codegraph` exists, it will be used. Otherwise, CodeGraph falls back to `./config/`.
+
+## Configuration Files in This Directory
+
+This directory contains **example configuration files** that can be copied to `~/.codegraph/`:
+
+- `default.toml` - Base configuration example
+- `surrealdb_example.toml` - SurrealDB configuration
+- `example_embedding.toml` - Embedding provider configuration
+- `example_performance.toml` - Performance tuning
+- `production.toml` - Production settings example
+
+## Quick Start
+
+### 1. Initialize User Config
+
+```bash
+# Create ~/.codegraph with default configs
+mkdir -p ~/.codegraph
+cp config/default.toml ~/.codegraph/
+```
+
+### 2. Customize Your Configuration
+
+```bash
+# Edit your user config
+nano ~/.codegraph/default.toml
+
+# Or create environment-specific configs
+cp ~/.codegraph/default.toml ~/.codegraph/development.toml
+cp ~/.codegraph/default.toml ~/.codegraph/production.toml
+```
+
+### 3. Set Environment
+
+```bash
+export APP_ENV=development  # Loads ~/.codegraph/development.toml
+# or
+export APP_ENV=production   # Loads ~/.codegraph/production.toml
+```
+
+## Environment Variables
+
+Override any config value using environment variables:
+
+```bash
+# Database backend
+export CODEGRAPH__DATABASE__BACKEND=surrealdb
+
+# SurrealDB connection
+export CODEGRAPH__DATABASE__SURREALDB__CONNECTION=ws://localhost:8000
+
+# Server port
+export CODEGRAPH__SERVER__PORT=8080
+```
+
+## Further Documentation
+
+- **[Full Configuration Guide](../docs/CONFIGURATION_GUIDE.md)** - Complete configuration documentation
+- **[SurrealDB Guide](../docs/SURREALDB_GUIDE.md)** - SurrealDB-specific configuration
+- **[Environment Variables](../docs/CONFIGURATION_GUIDE.md#environment-variables)** - Full list of env vars
+
+## Development
+
+For development, you can continue using this `./config` directory, but we recommend migrating to `~/.codegraph` for consistency:
+
+```bash
+# Option 1: Copy to ~/.codegraph
+mkdir -p ~/.codegraph && cp config/*.toml ~/.codegraph/
+
+# Option 2: Symlink (for active development)
+ln -s $(pwd)/config ~/.codegraph
+
+# Option 3: Keep using ./config (backward compatible)
+# CodeGraph will use ./config if ~/.codegraph doesn't exist
+```
+
+## Need Help?
+
+- Check the [Configuration Guide](../docs/CONFIGURATION_GUIDE.md)
+- See example configs in this directory
+- Use `CODEGRAPH__LOGGING__LEVEL=debug` to see which config directory is being used

crates/codegraph-core/src/config.rs

@@ -324,15 +324,97 @@ impl ConfigManager {
         Ok(manager)
     }
 
+    /// Get the default configuration directory.
+    ///
+    /// Priority order:
+    /// 1. ~/.codegraph/ (primary, user-level config)
+    /// 2. ./config/ (backward compatibility, project-level config)
+    /// 3. Current directory (fallback)
     pub fn default_config_dir() -> PathBuf {
-        // Prefer ./config/, fallback to current dir
+        // First, try ~/.codegraph
+        if let Some(home_dir) = dirs::home_dir() {
+            let codegraph_dir = home_dir.join(".codegraph");
+            if codegraph_dir.exists() {
+                info!("Using config directory: {:?}", codegraph_dir);
+                return codegraph_dir;
+            }
+        }
+
+        // Fall back to ./config/ for backward compatibility
         let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
-        let dir = cwd.join("config");
-        if dir.exists() {
-            dir
-        } else {
-            cwd
+        let project_config = cwd.join("config");
+        if project_config.exists() {
+            info!("Using config directory: {:?}", project_config);
+            return project_config;
+        }
+
+        // Final fallback to current directory
+        info!("Using config directory: {:?}", cwd);
+        cwd
+    }
+
+    /// Initialize the ~/.codegraph configuration directory with default config files.
+    ///
+    /// This creates the directory if it doesn't exist and optionally copies
+    /// default configuration files.
+    pub fn init_user_config_dir(copy_defaults: bool) -> Result<PathBuf> {
+        let home_dir = dirs::home_dir()
+            .ok_or_else(|| anyhow::anyhow!("Could not determine home directory"))?;
+
+        let codegraph_dir = home_dir.join(".codegraph");
+
+        // Create directory if it doesn't exist
+        if !codegraph_dir.exists() {
+            fs::create_dir_all(&codegraph_dir)
+                .context("Failed to create ~/.codegraph directory")?;
+            info!("Created config directory: {:?}", codegraph_dir);
         }
+
+        if copy_defaults {
+            // Create default.toml if it doesn't exist
+            let default_config = codegraph_dir.join("default.toml");
+            if !default_config.exists() {
+                let default_content = include_str!("../../../config/default.toml");
+                fs::write(&default_config, default_content)
+                    .context("Failed to write default config")?;
+                info!("Created default config: {:?}", default_config);
+            }
+
+            // Create README
+            let readme = codegraph_dir.join("README.txt");
+            if !readme.exists() {
+                let readme_content = r#"CodeGraph Configuration Directory
+==================================
+
+This directory contains configuration files for CodeGraph.
+
+Configuration files are loaded in the following order:
+1. default.toml (base configuration)
+2. {environment}.toml (e.g., development.toml, production.toml)
+3. local.toml (local overrides, not tracked in git)
+4. Environment variables (CODEGRAPH__* prefix)
+
+Example configuration files:
+- default.toml         - Base configuration
+- development.toml     - Development environment
+- production.toml      - Production environment
+- surrealdb.toml       - SurrealDB-specific config
+- embedding.toml       - Embedding model config
+
+For documentation, see: https://github.com/your-repo/codegraph-rust
+"#;
+                fs::write(&readme, readme_content)
+                    .context("Failed to write README")?;
+                info!("Created README: {:?}", readme);
+            }
+        }
+
+        Ok(codegraph_dir)
+    }
+
+    /// Get the config directory path, with an option to specify a custom location
+    pub fn get_config_dir(custom_path: Option<PathBuf>) -> PathBuf {
+        custom_path.unwrap_or_else(Self::default_config_dir)
     }
 
     pub fn load_from_sources(config_dir: &Path, env_name: &str) -> Result<Settings> {