fix(cli): honor XDG_CONFIG_HOME on Linux and clarify TOKSCALE_CONFIG_DIR docs

- Linux config resolution now flows through dirs::config_dir() instead
  of hardcoding $HOME/.config, so users with a custom XDG_CONFIG_HOME
  pointing the user config root elsewhere are no longer silently sent
  to the wrong directory. macOS still overrides dirs::config_dir() to
  reach $HOME/.config/tokscale, since dirs returns Application Support
  there and the docs already promised .config.
- README env-var rows for TOKSCALE_CONFIG_DIR now mention star-cache.json
  alongside settings.json (the override controls every file under the
  config root, not just settings), soften 'absolute path' to 'absolute
  path recommended; relative paths resolve against the process CWD'
  matching what get_config_dir() actually accepts, and explicitly note
  the legacy macOS fallback is suppressed when the override is set.
- New regression test linux_honors_xdg_config_home_when_set proves the
  XDG_CONFIG_HOME case. The existing Unix default test now also unsets
  XDG_CONFIG_HOME so it stays hermetic regardless of the host shell.

Author: junhoyeo

README.ja.md

@@ -499,7 +499,7 @@ Tokscaleは設定を`~/.config/tokscale/settings.json`に保存します：
 | 変数 | デフォルト | 説明 |
 |----------|---------|-------------|
 | `TOKSCALE_NATIVE_TIMEOUT_MS` | `300000`（5分） | `nativeTimeoutMs` 設定をオーバーライド |
-| `TOKSCALE_CONFIG_DIR` | unset | 設定ディレクトリ（`settings.json` の保存場所）をオーバーライドします。絶対パス。CI サンドボックスや非デフォルトの場所を固定したい場合に便利です。 |
+| `TOKSCALE_CONFIG_DIR` | unset | 設定ディレクトリ（`settings.json` と `star-cache.json` の保存場所）をオーバーライドします。絶対パス推奨；相対パスはプロセス CWD を基準に解決されます。CI サンドボックスや非デフォルトの場所を固定したい場合に便利です。設定されている場合、tokscale は macOS のレガシーパス（`~/Library/Application Support/tokscale/`）にフォールバックしません。 |
 
 ```bash
 # 例：非常に大きなデータセット用にタイムアウトを増加

README.ko.md

@@ -498,7 +498,7 @@ Tokscale은 설정을 `~/.config/tokscale/settings.json`에 저장합니다:
 | 변수 | 기본값 | 설명 |
 |----------|---------|-------------|
 | `TOKSCALE_NATIVE_TIMEOUT_MS` | `300000` (5분) | `nativeTimeoutMs` 설정 오버라이드 |
-| `TOKSCALE_CONFIG_DIR` | unset | 설정 디렉토리(`settings.json` 위치)를 오버라이드합니다. 절대 경로. CI 샌드박스나 비기본 위치를 고정할 때 유용합니다. |
+| `TOKSCALE_CONFIG_DIR` | unset | 설정 디렉토리(`settings.json` 및 `star-cache.json` 위치)를 오버라이드합니다. 절대 경로 권장; 상대 경로는 프로세스 CWD 기준으로 해석됩니다. CI 샌드박스나 비기본 위치를 고정할 때 유용합니다. 설정되면 tokscale은 macOS 레거시 경로(`~/Library/Application Support/tokscale/`)로 폴백하지 않습니다. |
 
 ```bash
 # 예시: 매우 큰 데이터셋에 대한 타임아웃 증가

README.md

@@ -515,7 +515,7 @@ Environment variables override config file values. For CI/CD or one-off use:
 |----------|---------|-------------|
 | `TOKSCALE_NATIVE_TIMEOUT_MS` | `300000` (5 min) | Overrides `nativeTimeoutMs` config |
 | `TOKSCALE_EXTRA_DIRS` | unset | One-off extra session roots as `client:/abs/path,client:/abs/path` |
-| `TOKSCALE_CONFIG_DIR` | unset | Overrides the config directory (where `settings.json` lives). Absolute path. Useful for CI sandboxes or pinning a non-default location. |
+| `TOKSCALE_CONFIG_DIR` | unset | Overrides the config directory (where `settings.json` and `star-cache.json` live). Absolute path recommended; relative paths resolve against the process CWD. Useful for CI sandboxes or pinning a non-default location. When set, tokscale will not fall back to the legacy macOS `~/Library/Application Support/tokscale/` path. |
 
 ```bash
 # Example: Increase timeout for very large datasets

README.zh-cn.md

@@ -499,7 +499,7 @@ Tokscale 将设置存储在 `~/.config/tokscale/settings.json`：
 | 变量 | 默认值 | 描述 |
 |----------|---------|-------------|
 | `TOKSCALE_NATIVE_TIMEOUT_MS` | `300000`（5 分钟） | 覆盖 `nativeTimeoutMs` 配置 |
-| `TOKSCALE_CONFIG_DIR` | unset | 覆盖配置目录（`settings.json` 所在位置）。绝对路径。适用于 CI 沙箱或固定到非默认位置。 |
+| `TOKSCALE_CONFIG_DIR` | unset | 覆盖配置目录（`settings.json` 和 `star-cache.json` 所在位置）。建议使用绝对路径；相对路径将基于进程 CWD 解析。适用于 CI 沙箱或固定到非默认位置。设置后，tokscale 不会回退到 macOS 旧路径（`~/Library/Application Support/tokscale/`）。 |
 
 ```bash
 # 示例：为非常大的数据集增加超时时间

crates/tokscale-cli/src/paths.rs

@@ -13,16 +13,22 @@ use std::path::PathBuf;
 /// Resolve the tokscale config dir, honoring `TOKSCALE_CONFIG_DIR` first.
 ///
 /// Resolution order:
-/// 1. `TOKSCALE_CONFIG_DIR` (absolute path, taken verbatim).
-/// 2. macOS / Linux: `$HOME/.config/tokscale`.
-/// 3. Windows (and any other platform): `dirs::config_dir().join("tokscale")`.
-/// 4. Last-ditch fallback: `./.tokscale` so a missing HOME never panics.
+/// 1. `TOKSCALE_CONFIG_DIR` taken verbatim. Absolute paths are recommended;
+///    relative paths are accepted and resolved against the process CWD.
+/// 2. macOS: `$HOME/.config/tokscale` (overrides `dirs::config_dir()`,
+///    which would return `~/Library/Application Support/` and split state
+///    across two roots — see module docs).
+/// 3. Linux: `dirs::config_dir().join("tokscale")` so XDG_CONFIG_HOME is
+///    honored. Falls through to `$HOME/.config/tokscale` when neither
+///    `XDG_CONFIG_HOME` nor `HOME` resolve.
+/// 4. Windows (and any other platform): `dirs::config_dir().join("tokscale")`.
+/// 5. Last-ditch fallback: `./.tokscale` so a missing HOME never panics.
 pub fn get_config_dir() -> PathBuf {
     if let Ok(custom) = std::env::var("TOKSCALE_CONFIG_DIR") {
         return PathBuf::from(custom);
     }
 
-    #[cfg(any(target_os = "macos", target_os = "linux"))]
+    #[cfg(target_os = "macos")]
     {
         if let Some(home) = dirs::home_dir() {
             return home.join(".config").join("tokscale");
@@ -93,8 +99,10 @@ mod tests {
     fn unix_default_is_dot_config_tokscale_under_home() {
         let prev_override = env::var_os("TOKSCALE_CONFIG_DIR");
         let prev_home = env::var_os("HOME");
+        let prev_xdg = env::var_os("XDG_CONFIG_HOME");
         unsafe {
             env::remove_var("TOKSCALE_CONFIG_DIR");
+            env::remove_var("XDG_CONFIG_HOME");
             env::set_var("HOME", "/tmp/tokscale-home-test");
         }
         assert_eq!(
@@ -110,6 +118,39 @@ mod tests {
                 Some(v) => env::set_var("HOME", v),
                 None => env::remove_var("HOME"),
             }
+            match prev_xdg {
+                Some(v) => env::set_var("XDG_CONFIG_HOME", v),
+                None => env::remove_var("XDG_CONFIG_HOME"),
+            }
+        }
+    }
+
+    #[test]
+    #[serial]
+    #[cfg(target_os = "linux")]
+    fn linux_honors_xdg_config_home_when_set() {
+        // XDG_CONFIG_HOME is the documented way to relocate the user
+        // config directory on Linux. Hardcoding `$HOME/.config` would
+        // silently break setups that point this elsewhere.
+        let prev_override = env::var_os("TOKSCALE_CONFIG_DIR");
+        let prev_xdg = env::var_os("XDG_CONFIG_HOME");
+        unsafe {
+            env::remove_var("TOKSCALE_CONFIG_DIR");
+            env::set_var("XDG_CONFIG_HOME", "/tmp/tokscale-xdg-config");
+        }
+        assert_eq!(
+            get_config_dir(),
+            PathBuf::from("/tmp/tokscale-xdg-config/tokscale"),
+        );
+        unsafe {
+            match prev_override {
+                Some(v) => env::set_var("TOKSCALE_CONFIG_DIR", v),
+                None => env::remove_var("TOKSCALE_CONFIG_DIR"),
+            }
+            match prev_xdg {
+                Some(v) => env::set_var("XDG_CONFIG_HOME", v),
+                None => env::remove_var("XDG_CONFIG_HOME"),
+            }
         }
     }