@nemus-cli/nemus 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-09-02
+
+### Added
+
+- **XDG base-directory support for config/state (Linux).** A fresh install now
+  stores its config/state under `$XDG_CONFIG_HOME/nemus` (default
+  `~/.config/nemus`) on Linux, making Nemus a better Linux citizen. Precedence
+  (first match wins): `NEMUS_CACHE_DIR`/`WORKSPACE_MANAGER_CACHE_DIR` override →
+  an existing `~/.nemus` with state (kept on every platform, never moved) →
+  an absolute `XDG_CONFIG_HOME` → Linux default `~/.config/nemus` → `~/.nemus`
+  (macOS/Windows). Existing `~/.nemus` installs are untouched. (#77)
+
+## [0.14.0] - 2026-09-02
+
+### Changed
+
+- **Shell integration now keeps its generated functions out of your shell RC
+  files.** Nemus writes them to `~/.nemus/shell-integration.sh` and adds only a
+  single guarded `source` line to `.zshrc`/`.bashrc`, so upgrades no longer
+  churn hundreds of lines in your personal shell config. Existing inline
+  installations migrate automatically without disturbing surrounding user
+  content, and reinstalls stay idempotent. Uninstall removes the generated file
+  too. Thanks to @uzikilon for the idea and original implementation (#50).
+
 ## [0.13.0] - 2026-09-02
 
 ### Added

package/README.md

@@ -138,7 +138,9 @@ npm install -g @nemus-cli/nemus
 ```
 
 The postinstall step sets up optional shell integration (auto-cd into new
-workspaces + a quick-navigate helper).
+workspaces + a quick-navigate helper). It keeps the generated functions in
+`~/.nemus/shell-integration.sh` and adds only a guarded source line to your
+shell RC file, so upgrades don't churn your `.zshrc`/`.bashrc`.
 
 ### From source
 
@@ -282,7 +284,8 @@ Everything Nemus reads from the environment (all optional):
 | Variable | Effect |
 | --- | --- |
 | `NEMUS_DIR` | Override where workspaces are created (also `WORKSPACE_MANAGER_DIR`). |
-| `NEMUS_CACHE_DIR` | Override the cache/config/state dir, default `~/.nemus` (also `WORKSPACE_MANAGER_CACHE_DIR`). |
+| `NEMUS_CACHE_DIR` | Override the config/state dir. Default: `~/.nemus`, or `$XDG_CONFIG_HOME/nemus` (→ `~/.config/nemus`) on Linux. Also `WORKSPACE_MANAGER_CACHE_DIR`. |
+| `XDG_CONFIG_HOME` | On Linux (or when set explicitly), a fresh install stores config/state under `$XDG_CONFIG_HOME/nemus`. An existing `~/.nemus` is always kept as-is. |
 | `NEMUS_JUDGE_MODEL` | Model for the `reflect` judge (overrides `--model`'s default). |
 | `NEMUS_JUDGE_THINKING` | Thinking level for the `reflect` judge on pi (`off`…`max`). |
 | `NEMUS_JUDGE_TIMEOUT_MS` | Timeout for the `reflect` judge call. |
@@ -424,7 +427,19 @@ export NEMUS_CACHE_DIR="$HOME/.cache/nemus"   # default: ~/.nemus
 
 (The legacy `WORKSPACE_MANAGER_DIR` / `WORKSPACE_MANAGER_CACHE_DIR` names still
 work as fallbacks. On first run, state from the old `~/.workspace-manager-cache`
-location is migrated to `~/.nemus` automatically.)
+location is migrated to the resolved config dir automatically.)
+
+**Config/state location (XDG-aware).** Resolution order, first match wins —
+designed so existing installs are never silently moved:
+
+1. `NEMUS_CACHE_DIR` / `WORKSPACE_MANAGER_CACHE_DIR` (explicit override).
+2. An existing `~/.nemus` that holds durable state (anything beyond regenerable
+   caches like `repos-cache.json` / `last-version-check.json` and the
+   `shell-integration.sh` file — e.g. `config.json`, `suites.json`, the
+   `reflect/` reports) — kept on every platform, never moved.
+3. `XDG_CONFIG_HOME/nemus`, when `XDG_CONFIG_HOME` is set to an absolute path.
+4. Linux with no prior install → `~/.config/nemus` (the XDG default).
+5. Otherwise (macOS/Windows, fresh install) → `~/.nemus`.
 
 Key settings: `githubOrg` (which org's repos to list — leave empty to list your
 own), `cloneProtocol` (`ssh`|`https`), `aiAgent`, `primaryAgent`, `installMcp`.

package/dist/utils/config.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.config = exports.CLONE_MAX_BUFFER = exports.CLONE_TIMEOUT_MS = exports.CONFIG_PATH = exports.META_FILENAME = exports.SUITES_FILE = exports.HISTORY_FILE = exports.CACHE_DIR = exports.WORKSPACES_DIR = exports.CONFIG_DEFAULTS = void 0;
+exports.resolveNemusHome = resolveNemusHome;
 exports.getUserConfig = getUserConfig;
 exports.getPackageVersion = getPackageVersion;
 exports.getCloneUrl = getCloneUrl;
@@ -42,11 +43,62 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const HOME_DIR = os.homedir();
-// Cache/config/state directory. Prefer the branded NEMUS_* env vars; fall back
-// to the legacy WORKSPACE_MANAGER_* names for backward compatibility; else the
-// default ~/.nemus home.
-const DEFAULT_CACHE_DIR = path.join(HOME_DIR, '.nemus');
 const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
+// Entries in ~/.nemus that do NOT make it a "real install": regenerable caches
+// and the shell-integration artifact. Anything else (config.json, suites.json,
+// history.jsonl, the reflect/ report dir, or any future state) marks the dir as
+// an existing install to keep in place. Denylisting the throwaways — a small,
+// stable set — is exhaustive for durable state by construction, which is safer
+// than allowlisting state files (that could miss e.g. reflect/ and wrongly
+// relocate a real install to XDG on upgrade).
+const REGENERABLE_ENTRIES = new Set([
+    'last-version-check.json', // update-check cache
+    'repos-cache.json', // GitHub repo-list cache
+    'last-error.json', // last error, for report-bug
+    'shell-integration.sh', // shell installer artifact — not Nemus state
+    '.DS_Store',
+]);
+/** True if ~/.nemus holds anything beyond regenerable caches / the shell artifact. */
+function hasDurableState(dir, readDir) {
+    let entries;
+    try {
+        entries = readDir(dir);
+    }
+    catch {
+        return false; // dir doesn't exist
+    }
+    return entries.some((e) => !REGENERABLE_ENTRIES.has(e));
+}
+/**
+ * Resolve the directory that holds Nemus config + state. Precedence (first
+ * match wins), designed so existing users are never silently moved:
+ *
+ *   1. Explicit override — NEMUS_CACHE_DIR (or legacy WORKSPACE_MANAGER_CACHE_DIR).
+ *   2. An existing ~/.nemus that holds durable state (anything beyond
+ *      regenerable caches / the shell-integration file) — kept on every platform.
+ *   3. XDG_CONFIG_HOME, when set to an absolute path — $XDG_CONFIG_HOME/nemus.
+ *   4. Linux with no prior install — the XDG default ~/.config/nemus.
+ *   5. Otherwise (macOS/Windows, fresh install) — ~/.nemus.
+ *
+ * Config + state are kept together in one dir (a later change may split cache
+ * out under XDG_CACHE_HOME). The dir is chosen under XDG_CONFIG_HOME, not
+ * XDG_CACHE_HOME, because it holds real config (config.json) — not disposable
+ * cache a cleaner may wipe. A relative XDG_CONFIG_HOME is ignored per the spec.
+ */
+function resolveNemusHome({ env, home, platform, readDir }) {
+    const explicit = env.NEMUS_CACHE_DIR || env.WORKSPACE_MANAGER_CACHE_DIR;
+    if (explicit)
+        return explicit;
+    const branded = path.join(home, '.nemus');
+    if (hasDurableState(branded, readDir))
+        return branded;
+    const xdg = env.XDG_CONFIG_HOME;
+    if (xdg && path.isAbsolute(xdg))
+        return path.join(xdg, 'nemus');
+    if (platform === 'linux')
+        return path.join(home, '.config', 'nemus');
+    return branded;
+}
 /**
  * One-time, best-effort migration of state from the pre-0.2.2 cache location
  * (~/.workspace-manager-cache) to ~/.nemus. Runs only when using the default
@@ -58,11 +110,15 @@ const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
  * shared by another tool whose "latest version" is unrelated to nemus, and
  * copying it would make the update check report a wrong version until the entry
  * expires. Skipping it just forces one fresh lookup.
+ *
+ * Skipped when an explicit env override is in effect (don't copy into a path the
+ * user deliberately chose). Runs into whatever default location was resolved,
+ * including a new XDG dir on Linux.
  */
 const MIGRATION_SKIP = new Set(['last-version-check.json']);
-function migrateLegacyCacheDir(targetDir) {
+function migrateLegacyCacheDir(targetDir, isExplicitOverride) {
     try {
-        if (targetDir === DEFAULT_CACHE_DIR && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
+        if (!isExplicitOverride && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
             fs.cpSync(LEGACY_CACHE_DIR, targetDir, {
                 recursive: true,
                 filter: (src) => !MIGRATION_SKIP.has(path.basename(src)),
@@ -73,8 +129,14 @@ function migrateLegacyCacheDir(targetDir) {
         // best-effort — ignore and let the dir be created lazily
     }
 }
-const CACHE_DIR_RESOLVED = process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR || DEFAULT_CACHE_DIR;
-migrateLegacyCacheDir(CACHE_DIR_RESOLVED);
+const EXPLICIT_OVERRIDE = !!(process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR);
+const CACHE_DIR_RESOLVED = resolveNemusHome({
+    env: process.env,
+    home: HOME_DIR,
+    platform: process.platform,
+    readDir: (p) => fs.readdirSync(p),
+});
+migrateLegacyCacheDir(CACHE_DIR_RESOLVED, EXPLICIT_OVERRIDE);
 // Config file lives inside the cache dir.
 const CONFIG_FILE = path.join(CACHE_DIR_RESOLVED, 'config.json');
 exports.CONFIG_DEFAULTS = {

package/install-shell-integration.sh

@@ -491,17 +491,30 @@ else
   exit 1
 fi
 
-# Check if already installed (version marker is in the grep below)
-if grep -q "Shell Integration (v50)" "$RC_FILE" 2>/dev/null; then
+# Keep the generated functions out of the user's shell config. The same file
+# works in both bash and zsh; the RC file only needs this guarded source line.
+SHELL_INTEGRATION_DIR="$HOME/.nemus"
+SHELL_INTEGRATION_FILE="$SHELL_INTEGRATION_DIR/shell-integration.sh"
+SOURCE_LINE='[ -f "$HOME/.nemus/shell-integration.sh" ] && source "$HOME/.nemus/shell-integration.sh"'
+
+mkdir -p "$SHELL_INTEGRATION_DIR"
+SHELL_TMPFILE=$(mktemp "$SHELL_INTEGRATION_DIR/.shell-integration.XXXXXX")
+printf '%s\n' "$SHELL_FUNCTION" > "$SHELL_TMPFILE"
+mv "$SHELL_TMPFILE" "$SHELL_INTEGRATION_FILE"
+
+append_source_line() {
+  printf '\n# Nemus - Shell Integration\n%s\n' "$SOURCE_LINE" >> "$1"
+}
+
+# Check if already installed
+if grep -Fq "$SOURCE_LINE" "$RC_FILE" 2>/dev/null; then
   echo "✅ Shell integration already up to date in $RC_FILE"
 elif grep -q "# Nemus - Shell Integration" "$RC_FILE" 2>/dev/null; then
-  # Old version installed — remove it and install new version
+  # Old inline version installed — remove it and leave only the source line
   echo "🔄 Upgrading shell integration in $RC_FILE..."
   TMPFILE=$(mktemp)
   awk -f "$SCRIPT_DIR/remove-shell-block.awk" "$RC_FILE" > "$TMPFILE"
-  # Append new shell integration to temp file so mv is atomic
-  echo "" >> "$TMPFILE"
-  echo "$SHELL_FUNCTION" >> "$TMPFILE"
+  append_source_line "$TMPFILE"
   cp "$RC_FILE" "${RC_FILE}.backup.$(date +%Y%m%d_%H%M%S)"
   chmod --reference="$RC_FILE" "$TMPFILE" 2>/dev/null || chmod "$(stat -f '%Lp' "$RC_FILE")" "$TMPFILE" 2>/dev/null || true
   mv "$TMPFILE" "$RC_FILE"
@@ -514,9 +527,8 @@ else
     echo "📦 Backup created: ${RC_FILE}.backup.*"
   fi
 
-  # Append shell function (creates the file if it doesn't exist)
-  echo "" >> "$RC_FILE"
-  echo "$SHELL_FUNCTION" >> "$RC_FILE"
+  # Append the source line (creates the file if it doesn't exist)
+  append_source_line "$RC_FILE"
 
   echo "✅ Shell integration installed in $RC_FILE"
   echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "workspaces": [
     "packages/*"
   ],

package/remove-shell-block.awk

@@ -33,6 +33,14 @@ skip {
     saw_func = 1
     next
   }
+  if (/\.nemus\/shell-integration\.sh/ && /source/) {
+    # Current installs keep the functions in a generated file and leave only
+    # this source line in the RC file.
+    skip = 0
+    saw_func = 0
+    buf = ""
+    next
+  }
   # Non-function line: block is over — emit any buffered lines
   skip = 0
   if (buf != "") printf "%s", buf

package/src/utils/config.test.ts

@@ -202,12 +202,21 @@ describe('config', () => {
   });
 
   describe('cache dir location + legacy migration', () => {
-    it('defaults CACHE_DIR to ~/.nemus when no env override is set', async () => {
+    // With XDG support a fresh install resolves to ~/.config/nemus on Linux and
+    // ~/.nemus elsewhere. Delete XDG_CONFIG_HOME so resolution is homedir-based
+    // (and stays inside the tempDir sandbox on any CI host).
+    const defaultHome = () =>
+      process.platform === 'linux'
+        ? path.join(tempDir, '.config', 'nemus')
+        : path.join(tempDir, '.nemus');
+
+    it('defaults CACHE_DIR to the platform default when no env override is set', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
       vi.resetModules();
       const { CACHE_DIR } = await loadModule();
-      expect(CACHE_DIR).toBe(path.join(tempDir, '.nemus'));
+      expect(CACHE_DIR).toBe(defaultHome());
     });
 
     it('prefers NEMUS_CACHE_DIR, then legacy WORKSPACE_MANAGER_CACHE_DIR', async () => {
@@ -222,41 +231,122 @@ describe('config', () => {
       expect((await loadModule()).CACHE_DIR).toBe(path.join(tempDir, '.workspace-manager-cache'));
     });
 
-    it('migrates state from ~/.workspace-manager-cache to ~/.nemus on first run', async () => {
+    it('migrates state from ~/.workspace-manager-cache to the default dir on first run', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
       // legacy dir (created by beforeEach) holds prior state; new dir absent
       fs.writeFileSync(path.join(tempDir, '.workspace-manager-cache', 'suites.json'), '{"x":1}');
-      expect(fs.existsSync(path.join(tempDir, '.nemus'))).toBe(false);
+      expect(fs.existsSync(defaultHome())).toBe(false);
       vi.resetModules();
       const { CACHE_DIR } = await loadModule();
-      expect(CACHE_DIR).toBe(path.join(tempDir, '.nemus'));
+      expect(CACHE_DIR).toBe(defaultHome());
       // copied, not moved: file exists in the new dir AND the legacy dir survives
-      expect(fs.readFileSync(path.join(tempDir, '.nemus', 'suites.json'), 'utf-8')).toBe('{"x":1}');
+      expect(fs.readFileSync(path.join(defaultHome(), 'suites.json'), 'utf-8')).toBe('{"x":1}');
       expect(fs.existsSync(path.join(tempDir, '.workspace-manager-cache', 'suites.json'))).toBe(true);
     });
 
     it('does not migrate last-version-check.json (avoids inheriting a foreign latest)', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
       const legacy = path.join(tempDir, '.workspace-manager-cache');
       fs.writeFileSync(path.join(legacy, 'suites.json'), '{"x":1}');
       fs.writeFileSync(path.join(legacy, 'last-version-check.json'), '{"latestVersion":"99.0.0"}');
       vi.resetModules();
       await loadModule();
       // other state migrates, but the version-check cache is left behind
-      expect(fs.existsSync(path.join(tempDir, '.nemus', 'suites.json'))).toBe(true);
-      expect(fs.existsSync(path.join(tempDir, '.nemus', 'last-version-check.json'))).toBe(false);
+      expect(fs.existsSync(path.join(defaultHome(), 'suites.json'))).toBe(true);
+      expect(fs.existsSync(path.join(defaultHome(), 'last-version-check.json'))).toBe(false);
     });
 
     it('does not migrate when the new dir already exists', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
-      fs.mkdirSync(path.join(tempDir, '.nemus'), { recursive: true });
+      delete process.env.XDG_CONFIG_HOME;
+      fs.mkdirSync(defaultHome(), { recursive: true });
       fs.writeFileSync(path.join(tempDir, '.workspace-manager-cache', 'suites.json'), '{"x":1}');
       vi.resetModules();
       await loadModule();
-      expect(fs.existsSync(path.join(tempDir, '.nemus', 'suites.json'))).toBe(false);
+      expect(fs.existsSync(path.join(defaultHome(), 'suites.json'))).toBe(false);
+    });
+
+    it('keeps an existing ~/.nemus install even on Linux (no surprise XDG move)', async () => {
+      delete process.env.NEMUS_CACHE_DIR;
+      delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
+      const branded = path.join(tempDir, '.nemus');
+      fs.mkdirSync(branded, { recursive: true });
+      fs.writeFileSync(path.join(branded, 'config.json'), '{}'); // real prior state
+      vi.resetModules();
+      const { CACHE_DIR } = await loadModule();
+      expect(CACHE_DIR).toBe(branded);
+    });
+  });
+
+  describe('resolveNemusHome precedence', () => {
+    const home = '/home/u';
+    const branded = path.join(home, '.nemus');
+    // A readDir that reports the given entries for ~/.nemus and "absent" elsewhere.
+    const brandedHas = (...entries: string[]) => (p: string): string[] => {
+      if (p === branded) return entries;
+      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    };
+    const empty = (): string[] => {
+      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    };
+
+    it('explicit NEMUS_CACHE_DIR / legacy override wins over everything', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(
+        resolveNemusHome({ env: { NEMUS_CACHE_DIR: '/x', XDG_CONFIG_HOME: '/c' }, home, platform: 'linux', readDir: brandedHas('config.json') }),
+      ).toBe('/x');
+      expect(
+        resolveNemusHome({ env: { WORKSPACE_MANAGER_CACHE_DIR: '/y' }, home, platform: 'linux', readDir: brandedHas('config.json') }),
+      ).toBe('/y');
+    });
+
+    it('an existing ~/.nemus with durable state wins over XDG, on any platform', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: '/c' }, home, platform: 'linux', readDir: brandedHas('config.json') })).toBe(branded);
+    });
+
+    it('counts reflect/ (and any non-cache entry) as durable state — not just the classic 3', async () => {
+      const { resolveNemusHome } = await loadModule();
+      // a reflect-only user has no config.json/suites.json/history.jsonl
+      expect(resolveNemusHome({ env: {}, home, platform: 'linux', readDir: brandedHas('reflect') })).toBe(branded);
+    });
+
+    it('a ~/.nemus holding only regenerable caches / the shell artifact does NOT count', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(
+        resolveNemusHome({
+          env: {},
+          home,
+          platform: 'linux',
+          readDir: brandedHas('shell-integration.sh', 'last-version-check.json', 'repos-cache.json', 'last-error.json', '.DS_Store'),
+        }),
+      ).toBe(path.join(home, '.config', 'nemus'));
+    });
+
+    it('honors an absolute XDG_CONFIG_HOME on a fresh install (any platform)', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: '/cfg' }, home, platform: 'linux', readDir: empty })).toBe('/cfg/nemus');
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: '/cfg' }, home, platform: 'darwin', readDir: empty })).toBe('/cfg/nemus');
+    });
+
+    it('ignores a relative XDG_CONFIG_HOME (per spec)', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: 'rel/path' }, home, platform: 'linux', readDir: empty })).toBe(
+        path.join(home, '.config', 'nemus'),
+      );
+    });
+
+    it('fresh-install default: Linux -> ~/.config/nemus, macOS/Windows -> ~/.nemus', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: {}, home, platform: 'linux', readDir: empty })).toBe(path.join(home, '.config', 'nemus'));
+      expect(resolveNemusHome({ env: {}, home, platform: 'darwin', readDir: empty })).toBe(branded);
+      expect(resolveNemusHome({ env: {}, home, platform: 'win32', readDir: empty })).toBe(branded);
     });
   });
 });

package/src/utils/config.ts

@@ -4,12 +4,73 @@ import * as fs from 'fs';
 
 const HOME_DIR = os.homedir();
 
-// Cache/config/state directory. Prefer the branded NEMUS_* env vars; fall back
-// to the legacy WORKSPACE_MANAGER_* names for backward compatibility; else the
-// default ~/.nemus home.
-const DEFAULT_CACHE_DIR = path.join(HOME_DIR, '.nemus');
 const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
 
+// Entries in ~/.nemus that do NOT make it a "real install": regenerable caches
+// and the shell-integration artifact. Anything else (config.json, suites.json,
+// history.jsonl, the reflect/ report dir, or any future state) marks the dir as
+// an existing install to keep in place. Denylisting the throwaways — a small,
+// stable set — is exhaustive for durable state by construction, which is safer
+// than allowlisting state files (that could miss e.g. reflect/ and wrongly
+// relocate a real install to XDG on upgrade).
+const REGENERABLE_ENTRIES = new Set([
+  'last-version-check.json', // update-check cache
+  'repos-cache.json', // GitHub repo-list cache
+  'last-error.json', // last error, for report-bug
+  'shell-integration.sh', // shell installer artifact — not Nemus state
+  '.DS_Store',
+]);
+
+export interface NemusHomeEnv {
+  env: NodeJS.ProcessEnv;
+  home: string;
+  platform: NodeJS.Platform;
+  /** List a directory's entries; throw (or return []) when it doesn't exist. */
+  readDir: (p: string) => string[];
+}
+
+/** True if ~/.nemus holds anything beyond regenerable caches / the shell artifact. */
+function hasDurableState(dir: string, readDir: (p: string) => string[]): boolean {
+  let entries: string[];
+  try {
+    entries = readDir(dir);
+  } catch {
+    return false; // dir doesn't exist
+  }
+  return entries.some((e) => !REGENERABLE_ENTRIES.has(e));
+}
+
+/**
+ * Resolve the directory that holds Nemus config + state. Precedence (first
+ * match wins), designed so existing users are never silently moved:
+ *
+ *   1. Explicit override — NEMUS_CACHE_DIR (or legacy WORKSPACE_MANAGER_CACHE_DIR).
+ *   2. An existing ~/.nemus that holds durable state (anything beyond
+ *      regenerable caches / the shell-integration file) — kept on every platform.
+ *   3. XDG_CONFIG_HOME, when set to an absolute path — $XDG_CONFIG_HOME/nemus.
+ *   4. Linux with no prior install — the XDG default ~/.config/nemus.
+ *   5. Otherwise (macOS/Windows, fresh install) — ~/.nemus.
+ *
+ * Config + state are kept together in one dir (a later change may split cache
+ * out under XDG_CACHE_HOME). The dir is chosen under XDG_CONFIG_HOME, not
+ * XDG_CACHE_HOME, because it holds real config (config.json) — not disposable
+ * cache a cleaner may wipe. A relative XDG_CONFIG_HOME is ignored per the spec.
+ */
+export function resolveNemusHome({ env, home, platform, readDir }: NemusHomeEnv): string {
+  const explicit = env.NEMUS_CACHE_DIR || env.WORKSPACE_MANAGER_CACHE_DIR;
+  if (explicit) return explicit;
+
+  const branded = path.join(home, '.nemus');
+  if (hasDurableState(branded, readDir)) return branded;
+
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg && path.isAbsolute(xdg)) return path.join(xdg, 'nemus');
+
+  if (platform === 'linux') return path.join(home, '.config', 'nemus');
+
+  return branded;
+}
+
 /**
  * One-time, best-effort migration of state from the pre-0.2.2 cache location
  * (~/.workspace-manager-cache) to ~/.nemus. Runs only when using the default
@@ -21,11 +82,15 @@ const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
  * shared by another tool whose "latest version" is unrelated to nemus, and
  * copying it would make the update check report a wrong version until the entry
  * expires. Skipping it just forces one fresh lookup.
+ *
+ * Skipped when an explicit env override is in effect (don't copy into a path the
+ * user deliberately chose). Runs into whatever default location was resolved,
+ * including a new XDG dir on Linux.
  */
 const MIGRATION_SKIP = new Set(['last-version-check.json']);
-function migrateLegacyCacheDir(targetDir: string): void {
+function migrateLegacyCacheDir(targetDir: string, isExplicitOverride: boolean): void {
   try {
-    if (targetDir === DEFAULT_CACHE_DIR && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
+    if (!isExplicitOverride && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
       fs.cpSync(LEGACY_CACHE_DIR, targetDir, {
         recursive: true,
         filter: (src) => !MIGRATION_SKIP.has(path.basename(src)),
@@ -36,9 +101,14 @@ function migrateLegacyCacheDir(targetDir: string): void {
   }
 }
 
-const CACHE_DIR_RESOLVED =
-  process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR || DEFAULT_CACHE_DIR;
-migrateLegacyCacheDir(CACHE_DIR_RESOLVED);
+const EXPLICIT_OVERRIDE = !!(process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR);
+const CACHE_DIR_RESOLVED = resolveNemusHome({
+  env: process.env,
+  home: HOME_DIR,
+  platform: process.platform,
+  readDir: (p) => fs.readdirSync(p),
+});
+migrateLegacyCacheDir(CACHE_DIR_RESOLVED, EXPLICIT_OVERRIDE);
 
 // Config file lives inside the cache dir.
 const CONFIG_FILE = path.join(CACHE_DIR_RESOLVED, 'config.json');

package/uninstall.sh

@@ -38,7 +38,7 @@ echo -e "${YELLOW}This will NOT remove:${NC}"
 echo "  • Your workspaces ($HOME/workspaces/)"
 echo "  • Cache files (~/.workspace-manager-cache/)"
 echo "  • Configuration files (~/.workspace-manager-claude-config.json)"
-echo "  • Shell integration (from .zshrc or .bashrc)"
+echo "  • Shell integration (from .zshrc or .bashrc and ~/.nemus/)"
 echo "  • ghq (if installed)"
 echo ""
 
@@ -85,8 +85,11 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
         if grep -q "# Nemus - Shell Integration" "$HOME/.zshrc"; then
             # Create backup
             cp "$HOME/.zshrc" "$HOME/.zshrc.backup.$(date +%Y%m%d_%H%M%S)"
-            # Remove the function
-            sed -i.bak '/# Nemus - Shell Integration/,/^}$/d' "$HOME/.zshrc"
+            # Remove the block/source line (awk handles both formats safely)
+            TMPFILE=$(mktemp)
+            awk -f "$SCRIPT_DIR/remove-shell-block.awk" "$HOME/.zshrc" > "$TMPFILE"
+            chmod --reference="$HOME/.zshrc" "$TMPFILE" 2>/dev/null || chmod "$(stat -f '%Lp' "$HOME/.zshrc")" "$TMPFILE" 2>/dev/null || true
+            mv "$TMPFILE" "$HOME/.zshrc"
             print_success "Removed from .zshrc (backup created)"
         fi
     fi
@@ -96,11 +99,19 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
         if grep -q "# Nemus - Shell Integration" "$HOME/.bashrc"; then
             # Create backup
             cp "$HOME/.bashrc" "$HOME/.bashrc.backup.$(date +%Y%m%d_%H%M%S)"
-            # Remove the function
-            sed -i.bak '/# Nemus - Shell Integration/,/^}$/d' "$HOME/.bashrc"
+            # Remove the block/source line (awk handles both formats safely)
+            TMPFILE=$(mktemp)
+            awk -f "$SCRIPT_DIR/remove-shell-block.awk" "$HOME/.bashrc" > "$TMPFILE"
+            chmod --reference="$HOME/.bashrc" "$TMPFILE" 2>/dev/null || chmod "$(stat -f '%Lp' "$HOME/.bashrc")" "$TMPFILE" 2>/dev/null || true
+            mv "$TMPFILE" "$HOME/.bashrc"
             print_success "Removed from .bashrc (backup created)"
         fi
     fi
+
+    if [ -f "$HOME/.nemus/shell-integration.sh" ]; then
+        rm -f "$HOME/.nemus/shell-integration.sh"
+        print_success "Removed ~/.nemus/shell-integration.sh"
+    fi
 fi
 
 # Optionally remove cache