feat: implement XDG Base Directory layout for all paths #18

Migrate from monolithic ~/.localgpt/ to XDG-compliant directory structure:
- Config:  ~/.config/localgpt/
- Data:    ~/.local/share/localgpt/ (workspace, device key, skills)
- State:   ~/.local/state/localgpt/ (sessions, audit log, logs)
- Cache:   ~/.cache/localgpt/ (search index, embeddings)
- Runtime: $TMPDIR/localgpt-$UID/ (PID file, workspace lock)

Adds Paths struct (src/paths.rs) with three-level env var fallback:
LOCALGPT_* -> XDG_* -> platform defaults (via etcetera crate).
Existing configs with memory.workspace set are honored via deprecated
compat logic. New `localgpt paths` subcommand for debugging.

Author: yiwang

Cargo.lock

@@ -75,6 +75,8 @@ mime_guess = "2.0"
 # Utilities
 chrono = { version = "0.4", features = ["serde"] }
 directories = "6.0"
+etcetera = "0.8"
+libc = "0.2"
 thiserror = "2.0"
 anyhow = "1.0"
 uuid = { version = "1.20", features = ["v4"] }

Cargo.toml

@@ -98,15 +98,14 @@ impl Agent {
 
         // Load and verify security policy
         let workspace = app_config.workspace_path();
-        let state_dir = workspace
-            .parent()
-            .unwrap_or_else(|| std::path::Path::new("~/.localgpt"));
+        let data_dir = &app_config.paths.data_dir;
+        let state_dir = &app_config.paths.state_dir;
 
         let verified_security_policy = if app_config.security.disable_policy {
             debug!("Security policy loading disabled by config");
             None
         } else {
-            match crate::security::load_and_verify_policy(&workspace, state_dir) {
+            match crate::security::load_and_verify_policy(&workspace, data_dir) {
                 crate::security::PolicyVerification::Valid(content) => {
                     let sha = crate::security::content_sha256(&content);
                     let _ = crate::security::append_audit_entry(
@@ -220,13 +219,11 @@ impl Agent {
 
         // Load security policy
         let workspace = app_config.workspace_path();
-        let state_dir = workspace
-            .parent()
-            .unwrap_or_else(|| std::path::Path::new("~/.localgpt"));
+        let data_dir = &app_config.paths.data_dir;
         let verified_security_policy = if app_config.security.disable_policy {
             None
         } else {
-            match crate::security::load_and_verify_policy(&workspace, state_dir) {
+            match crate::security::load_and_verify_policy(&workspace, data_dir) {
                 crate::security::PolicyVerification::Valid(content) => Some(content),
                 _ => None,
             }

src/agent/mod.rs

@@ -596,22 +596,13 @@ fn get_sessions_dir() -> Result<PathBuf> {
 }
 
 pub fn get_sessions_dir_for_agent(agent_id: &str) -> Result<PathBuf> {
-    let base = directories::BaseDirs::new()
-        .ok_or_else(|| anyhow::anyhow!("Could not determine home directory"))?;
-
-    Ok(base
-        .home_dir()
-        .join(".localgpt")
-        .join("agents")
-        .join(agent_id)
-        .join("sessions"))
+    let paths = crate::paths::Paths::resolve()?;
+    Ok(paths.sessions_dir(agent_id))
 }
 
 pub fn get_state_dir() -> Result<PathBuf> {
-    let base = directories::BaseDirs::new()
-        .ok_or_else(|| anyhow::anyhow!("Could not determine home directory"))?;
-
-    Ok(base.home_dir().join(".localgpt"))
+    let paths = crate::paths::Paths::resolve()?;
+    Ok(paths.state_dir)
 }
 
 fn estimate_tokens(text: &str) -> usize {

src/agent/session.rs

@@ -211,9 +211,11 @@ pub fn load_skills(workspace: &Path) -> Result<Vec<Skill>> {
     Ok(skills)
 }
 
-/// Get the managed skills directory (~/.localgpt/skills/)
+/// Get the managed skills directory (data_dir/skills)
 fn get_managed_skills_dir() -> Option<PathBuf> {
-    directories::BaseDirs::new().map(|dirs| dirs.home_dir().join(".localgpt").join("skills"))
+    crate::paths::Paths::resolve()
+        .ok()
+        .map(|paths| paths.managed_skills_dir())
 }
 
 /// Load skills from a single directory

src/agent/skills.rs

@@ -29,10 +29,7 @@ pub fn create_default_tools(
     memory: Option<Arc<MemoryManager>>,
 ) -> Result<Vec<Box<dyn Tool>>> {
     let workspace = config.workspace_path();
-    let state_dir = workspace
-        .parent()
-        .unwrap_or_else(|| std::path::Path::new("~/.localgpt"))
-        .to_path_buf();
+    let state_dir = config.paths.state_dir.clone();
 
     // Build sandbox policy if enabled
     let sandbox_policy = if config.sandbox.enabled {

src/agent/tools.rs

@@ -144,7 +144,10 @@ interval = "30m"
 # end = "22:00"
 
 [memory]
-workspace = "~/.localgpt/workspace"
+# Workspace directory for memory files (MEMORY.md, HEARTBEAT.md, etc.)
+# Default: XDG data dir (~/.local/share/localgpt/workspace)
+# Override with: LOCALGPT_WORKSPACE=/path or LOCALGPT_PROFILE=work
+# workspace = "~/.local/share/localgpt/workspace"
 
 [server]
 enabled = true

src/cli/config.rs

@@ -451,14 +451,13 @@ async fn run_heartbeat_once(agent_id: &str) -> Result<()> {
 }
 
 fn get_pid_file() -> Result<PathBuf> {
-    // Put PID file in state dir (~/.localgpt/), not workspace
-    let state_dir = crate::agent::get_state_dir()?;
-    Ok(state_dir.join("daemon.pid"))
+    let paths = crate::paths::Paths::resolve()?;
+    Ok(paths.pid_file())
 }
 
 fn get_log_file(retention_days: u32) -> Result<PathBuf> {
-    let state_dir = crate::agent::get_state_dir()?;
-    let logs_dir = state_dir.join("logs");
+    let paths = crate::paths::Paths::resolve()?;
+    let logs_dir = paths.logs_dir();
     fs::create_dir_all(&logs_dir)?;
 
     // Prune old logs only if retention_days > 0

src/cli/daemon.rs

@@ -50,12 +50,11 @@ pub async fn run(args: MdArgs) -> Result<()> {
 async fn sign_policy() -> Result<()> {
     let config = Config::load()?;
     let workspace = config.workspace_path();
-    let state_dir = workspace
-        .parent()
-        .ok_or_else(|| anyhow::anyhow!("Workspace has no parent directory"))?;
+    let data_dir = &config.paths.data_dir;
+    let state_dir = &config.paths.state_dir;
 
     // Ensure device key exists
-    security::ensure_device_key(state_dir)?;
+    security::ensure_device_key(data_dir)?;
 
     // Check policy file exists
     let policy_path = workspace.join(security::POLICY_FILENAME);
@@ -68,7 +67,7 @@ async fn sign_policy() -> Result<()> {
     }
 
     // Sign
-    let manifest = security::sign_policy(state_dir, &workspace, "cli")?;
+    let manifest = security::sign_policy(data_dir, &workspace, "cli")?;
 
     // Write audit entry
     security::append_audit_entry(
@@ -91,11 +90,10 @@ async fn sign_policy() -> Result<()> {
 async fn verify_policy() -> Result<()> {
     let config = Config::load()?;
     let workspace = config.workspace_path();
-    let state_dir = workspace
-        .parent()
-        .ok_or_else(|| anyhow::anyhow!("Workspace has no parent directory"))?;
+    let data_dir = &config.paths.data_dir;
+    let state_dir = &config.paths.state_dir;
 
-    let result = security::load_and_verify_policy(&workspace, state_dir);
+    let result = security::load_and_verify_policy(&workspace, data_dir);
 
     match result {
         security::PolicyVerification::Valid(content) => {
@@ -145,10 +143,7 @@ async fn verify_policy() -> Result<()> {
 
 async fn show_audit(json_output: bool, filter: Option<String>) -> Result<()> {
     let config = Config::load()?;
-    let workspace = config.workspace_path();
-    let state_dir = workspace
-        .parent()
-        .ok_or_else(|| anyhow::anyhow!("Workspace has no parent directory"))?;
+    let state_dir = &config.paths.state_dir;
 
     let mut entries = security::read_audit_log(state_dir)?;
 
@@ -230,16 +225,15 @@ async fn show_audit(json_output: bool, filter: Option<String>) -> Result<()> {
 async fn show_status() -> Result<()> {
     let config = Config::load()?;
     let workspace = config.workspace_path();
-    let state_dir = workspace
-        .parent()
-        .ok_or_else(|| anyhow::anyhow!("Workspace has no parent directory"))?;
+    let data_dir = &config.paths.data_dir;
+    let state_dir = &config.paths.state_dir;
 
     println!("Security Status:");
 
     // Policy file
     let policy_path = workspace.join(security::POLICY_FILENAME);
     if policy_path.exists() {
-        let result = security::load_and_verify_policy(&workspace, state_dir);
+        let result = security::load_and_verify_policy(&workspace, data_dir);
         let status = match result {
             security::PolicyVerification::Valid(_) => "Valid (signed and verified)",
             security::PolicyVerification::Unsigned => "Unsigned (run `localgpt md sign`)",
@@ -262,7 +256,7 @@ async fn show_status() -> Result<()> {
     }
 
     // Device key
-    let key_path = state_dir.join(".device_key");
+    let key_path = config.paths.device_key();
     if key_path.exists() {
         println!("  Device Key: Present");
     } else {

src/cli/md.rs

@@ -8,6 +8,7 @@ pub mod desktop;
 pub mod gen3d;
 pub mod md;
 pub mod memory;
+pub mod paths;
 pub mod sandbox;
 
 use clap::{Parser, Subcommand};
@@ -67,6 +68,9 @@ pub enum Commands {
     /// LocalGPT.md policy management
     Md(md::MdArgs),
 
+    /// Show resolved XDG directory paths
+    Paths,
+
     /// Shell sandbox management
     Sandbox(sandbox::SandboxArgs),
 }