@nemus-cli/nemus 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-02
+
+### Added
+
+- **`nemus version` subcommand** — a companion to the `-V/--version` flag for
+  people who type `nemus version`. `--json` additionally reports the Node.js
+  version, platform, and arch (handy for bug reports), as a single JSON document
+  to stdout. (#74)
+- **`NEMUS_NO_UPDATE_CHECK`** — opt out of the background "update available"
+  check entirely (no cache read, no network). Also honors the de-facto
+  `NO_UPDATE_NOTIFIER`. An explicit falsey value (`0`/`false`/empty) does not
+  disable it. Documented in the README env-var table. (#76)
+
+## [0.11.0] - 2026-09-02
+
+### Added
+
+- **`nemus prune`** — bulk-delete workspaces with no recent activity, **safe by
+  default.** It selects workspaces whose most recent agent session (or, absent
+  any session, whose `createdAt`) is older than `--days` (default 30), and
+  **holds back any workspace with uncommitted or unpushed changes** — listing
+  each protected one and why. Preview with `--dry-run` or `--json` (both never
+  delete); otherwise it deletes after a confirmation (`-y/--yes` to skip).
+  `--include-dirty` overrides the safety guard. Deletions go through the same
+  validated `safeWorkspacePath()` choke point as `nemus delete`. The
+  stale/protected decision logic is pure and unit-tested.
+
 ## [0.10.0] - 2026-09-01
 
 ### Changed

package/README.md

@@ -202,9 +202,22 @@ nemus create           # (c) interactive create
 nemus list             # (l) list workspaces
 nemus update           # (u) add repos to a workspace
 nemus delete           # (del) delete a workspace
+nemus prune            # delete workspaces with no recent activity (safe by default)
 nemus go [name]        # jump to a workspace directory
 ```
 
+> **`prune`** clears out workspaces you've finished with. It selects those with
+> no agent session (or, failing that, no `createdAt`) in the last **N days**
+> (`--days`, default 30) and — crucially — **protects any workspace with
+> uncommitted or unpushed work**, listing why it was skipped. Preview with
+> `--dry-run` (or `--json`), then delete after a confirmation (`--yes` to skip).
+> `--include-dirty` overrides the safety guard. Example:
+>
+> ```bash
+> nemus prune --days 30 --dry-run   # see what would go, nothing deleted
+> nemus prune --days 30             # prune stale + clean workspaces, with a prompt
+> ```
+
 ### Operate across all repos
 
 ```bash
@@ -275,6 +288,7 @@ Everything Nemus reads from the environment (all optional):
 | `NEMUS_JUDGE_TIMEOUT_MS` | Timeout for the `reflect` judge call. |
 | `NEMUS_BUG_REPORT_REPO` | Repo that `report-bug` files issues against. |
 | `NEMUS_SKIP_CONFIGURE` | Skip the one-time post-install `configure` prompt. |
+| `NEMUS_NO_UPDATE_CHECK` | Disable the background "update available" check (also honors `NO_UPDATE_NOTIFIER`). |
 | `WORKSPACE_CLONE_TIMEOUT_MS` | Git clone timeout (default 15 min). |
 | `NO_COLOR` / `FORCE_COLOR` | Disable / force ANSI color (see [Global flags](#global-flags)). |
 | `VISUAL` / `EDITOR` | Editor launched by `nemus config edit`. |

package/dist/commands/prune.js

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPruneCommand = registerPruneCommand;
+exports.handlePrune = handlePrune;
+const fs = __importStar(require("fs/promises"));
+const validation_1 = require("../utils/validation");
+const workspace_meta_1 = require("../utils/workspace-meta");
+const claude_sessions_1 = require("../utils/claude-sessions");
+const git_status_1 = require("../utils/git-status");
+const logger_1 = require("../utils/logger");
+const colors_1 = require("../utils/colors");
+const prompt_1 = require("../utils/prompt");
+const command_helpers_1 = require("../utils/command-helpers");
+const output_1 = require("../utils/output");
+const prune_1 = require("../utils/prune");
+const DEFAULT_DAYS = 30;
+function registerPruneCommand(parent) {
+    parent
+        .command('prune')
+        .description('Delete workspaces with no recent activity (safe by default)')
+        .option('-d, --days <n>', `Consider a workspace stale after N days of inactivity (default ${DEFAULT_DAYS})`)
+        .option('--include-dirty', 'Also prune workspaces with uncommitted/unpushed changes (default: protected)')
+        .option('--dry-run', 'Show what would be pruned without deleting anything')
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .option('--json', 'Output the prune plan as JSON (never deletes)')
+        .action(async (opts, cmd) => {
+        const globalOpts = (0, command_helpers_1.getGlobalOpts)(cmd);
+        await handlePrune({ ...opts, ...globalOpts });
+    });
+}
+function parseDays(raw) {
+    if (raw === undefined)
+        return DEFAULT_DAYS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    return Math.floor(n);
+}
+async function handlePrune(opts) {
+    const json = !!opts.json;
+    const days = parseDays(opts.days);
+    if (days === null) {
+        if (json)
+            (0, output_1.outputJsonError)('--days must be a non-negative number');
+        else
+            (0, logger_1.logError)('--days must be a non-negative number');
+        process.exit(1);
+    }
+    try {
+        const [workspaces, sessions] = await Promise.all([(0, workspace_meta_1.listWorkspaces)(), (0, claude_sessions_1.getWorkspaceSessions)()]);
+        const sessionMap = new Map(sessions.map((s) => [s.workspaceName, s]));
+        const now = Date.now();
+        const candidates = workspaces.map((ws) => {
+            const session = sessionMap.get(ws.name);
+            const createdRaw = ws.metadata?.createdAt ? Date.parse(ws.metadata.createdAt) : NaN;
+            const forPrune = {
+                name: ws.name,
+                path: ws.path,
+                repoDirNames: (ws.metadata?.repositories ?? []).map((r) => r.directoryName),
+                lastActiveAt: session ? session.lastActiveAt.getTime() : 0,
+                createdAt: Number.isFinite(createdRaw) ? createdRaw : 0,
+            };
+            return (0, prune_1.toCandidate)(forPrune, now);
+        });
+        const stale = candidates.filter((c) => (0, prune_1.isStale)(c, days));
+        if (stale.length === 0) {
+            if (json) {
+                (0, output_1.outputJson)({ ok: true, days, prunable: [], protected: [], scanned: workspaces.length });
+            }
+            else {
+                (0, logger_1.logInfo)(`No workspaces inactive for ${days}+ days (scanned ${workspaces.length}).`);
+            }
+            return;
+        }
+        // Compute the plan. The git safety check only runs for stale workspaces.
+        const plan = await (0, prune_1.planPrune)(stale, (c) => (0, git_status_1.getAllReposStatus)(c.path, c.repoDirNames, 3), !!opts.includeDirty);
+        if (json) {
+            (0, output_1.outputJson)({
+                ok: true,
+                days,
+                scanned: workspaces.length,
+                prunable: plan.prunable.map((c) => ({ name: c.name, path: c.path, ageDays: c.ageDays, repos: c.repoDirNames.length })),
+                protected: plan.protected.map((p) => ({ name: p.candidate.name, ageDays: p.candidate.ageDays, reason: p.reason })),
+            });
+            return;
+        }
+        // Human report.
+        console.log('\n' + '='.repeat(60));
+        console.log((0, colors_1.colorize)(`Prune — workspaces inactive for ${days}+ days`, 'bright'));
+        console.log('='.repeat(60) + '\n');
+        if (plan.protected.length > 0) {
+            (0, logger_1.logWarning)(`Protected (${plan.protected.length}) — skipped due to unsaved work:`);
+            for (const p of plan.protected) {
+                console.log(`  ${(0, colors_1.colorize)('•', 'yellow')} ${(0, colors_1.colorize)(p.candidate.name, 'cyan')} — ${p.reason} ${(0, colors_1.colorize)(`(${ageLabel(p.candidate)})`, 'gray')}`);
+            }
+            console.log('');
+        }
+        if (plan.prunable.length === 0) {
+            (0, logger_1.logInfo)('Nothing safe to prune.');
+            if (plan.protected.length > 0)
+                (0, logger_1.logInfo)('Re-run with --include-dirty to include the protected ones (careful).');
+            return;
+        }
+        console.log(`${(0, colors_1.colorize)('Prunable', 'bright')} (${plan.prunable.length}):`);
+        for (const c of plan.prunable) {
+            const repoLabel = c.repoDirNames.length === 1 ? '1 repo' : `${c.repoDirNames.length} repos`;
+            console.log(`  ${(0, colors_1.colorize)('✗', 'red')} ${(0, colors_1.colorize)(c.name, 'cyan')} ${(0, colors_1.colorize)(`(${ageLabel(c)}, ${repoLabel})`, 'gray')}`);
+        }
+        console.log('');
+        if (opts.dryRun) {
+            (0, logger_1.logInfo)(`Dry run — nothing deleted. ${plan.prunable.length} workspace(s) would be pruned.`);
+            return;
+        }
+        (0, logger_1.logWarning)('This permanently deletes the selected workspaces and every cloned repo inside them!');
+        if (!opts.yes) {
+            const confirmed = await (0, prompt_1.confirm)({
+                message: plan.prunable.length === 1
+                    ? `Prune workspace ${plan.prunable[0].name}?`
+                    : `Prune these ${plan.prunable.length} workspaces?`,
+                default: false,
+            });
+            if (!confirmed) {
+                (0, logger_1.logInfo)('Prune cancelled');
+                return;
+            }
+        }
+        let deleted = 0;
+        for (const c of plan.prunable) {
+            let target;
+            try {
+                // Re-validate through the same choke point delete uses: enforces the
+                // name allowlist and pins the path inside WORKSPACES_DIR.
+                target = (0, validation_1.safeWorkspacePath)(c.name);
+            }
+            catch (error) {
+                (0, logger_1.logError)(error instanceof Error ? error.message : `Invalid workspace name "${c.name}"`);
+                continue;
+            }
+            try {
+                await fs.rm(target, { recursive: true, force: true });
+                (0, logger_1.logSuccess)(`Pruned "${(0, colors_1.colorize)(c.name, 'cyan')}"`);
+                deleted++;
+            }
+            catch (error) {
+                (0, logger_1.logError)(`Failed to prune "${c.name}"`);
+                if (error instanceof Error)
+                    (0, logger_1.logError)(error.message);
+            }
+        }
+        (0, logger_1.logStep)(`Pruned ${deleted} of ${plan.prunable.length} workspace(s).`);
+    }
+    catch (error) {
+        if (json)
+            (0, output_1.outputJsonError)(error instanceof Error ? error.message : 'prune failed');
+        else
+            (0, logger_1.logError)(error instanceof Error ? error.message : 'prune failed');
+        process.exit(1);
+    }
+}
+function ageLabel(c) {
+    const base = c.ageDays === 1 ? '1 day' : `${c.ageDays} days`;
+    return c.fromSession ? `${base} since last session` : `${base} since created, no sessions`;
+}

package/dist/commands/version.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVersionInfo = buildVersionInfo;
+exports.registerVersionCommand = registerVersionCommand;
+const output_1 = require("../utils/output");
+/**
+ * Build the version payload. Pure and process-injectable so the JSON shape is
+ * unit-testable without reading the real runtime.
+ */
+function buildVersionInfo(version, proc = process) {
+    return {
+        version,
+        node: proc.versions.node,
+        platform: proc.platform,
+        arch: proc.arch,
+    };
+}
+/**
+ * `nemus version` — a subcommand companion to the `-V/--version` flag, for
+ * people who type `nemus version`. `--json` also reports the Node/OS runtime
+ * (handy for bug reports), emitting a single JSON document to stdout.
+ */
+function registerVersionCommand(program, version) {
+    program
+        .command('version')
+        .description('Print the Nemus version (with --json for version + runtime info)')
+        .option('--json', 'Output version + runtime info as JSON')
+        .action((opts) => {
+        const info = buildVersionInfo(version);
+        if (opts.json) {
+            (0, output_1.outputJson)(info);
+        }
+        else {
+            process.stdout.write(`nemus ${info.version}\n`);
+        }
+    });
+}

package/dist/program.js

@@ -40,6 +40,7 @@ const fs = __importStar(require("fs"));
 const colors_1 = require("./utils/colors");
 const banner_1 = require("./utils/banner");
 const global_flags_1 = require("./utils/global-flags");
+const version_1 = require("./commands/version");
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 // --no-color must be applied BEFORE commander parses so it reaches the help
@@ -66,10 +67,12 @@ exports.program
 // also pre-scanned above.
 exports.program.hook('preAction', () => (0, global_flags_1.applyGlobalFlags)(exports.program.opts()));
 // Register top-level commands
+(0, version_1.registerVersionCommand)(exports.program, pkg.version);
 const create_1 = require("./commands/create");
 const list_1 = require("./commands/list");
 const update_1 = require("./commands/update");
 const delete_1 = require("./commands/delete");
+const prune_1 = require("./commands/prune");
 const sync_1 = require("./commands/sync");
 const status_1 = require("./commands/status");
 const diff_1 = require("./commands/diff");
@@ -96,6 +99,7 @@ const reflect_1 = require("./commands/reflect");
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
 (0, delete_1.registerDeleteCommand)(exports.program);
+(0, prune_1.registerPruneCommand)(exports.program);
 (0, sync_1.registerSyncCommand)(exports.program);
 (0, status_1.registerStatusCommand)(exports.program);
 (0, diff_1.registerDiffCommand)(exports.program);

package/dist/utils/prune.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCandidate = toCandidate;
+exports.isStale = isStale;
+exports.protectionReason = protectionReason;
+exports.planPrune = planPrune;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Build a dated candidate for a workspace. `now` is injected for testability. */
+function toCandidate(ws, now) {
+    const referenceAt = ws.lastActiveAt > 0 ? ws.lastActiveAt : ws.createdAt;
+    const undatable = !(referenceAt > 0);
+    const ageDays = undatable ? 0 : Math.floor((now - referenceAt) / MS_PER_DAY);
+    return {
+        name: ws.name,
+        path: ws.path,
+        repoDirNames: ws.repoDirNames,
+        referenceAt,
+        fromSession: ws.lastActiveAt > 0,
+        ageDays,
+        undatable,
+    };
+}
+/**
+ * A workspace is a prune candidate when it is datable and its age meets the
+ * threshold. Undatable workspaces are never auto-selected — we won't delete
+ * something we can't put a date on. A future `referenceAt` (clock skew) yields
+ * a negative age and is therefore not stale.
+ */
+function isStale(c, days) {
+    return !c.undatable && c.ageDays >= days;
+}
+/**
+ * Why a stale workspace should be held back from deletion, or null if it's safe.
+ * Unsafe = any repo has uncommitted changes (`!clean`) or unpushed commits
+ * (`ahead > 0`). With `includeDirty`, nothing is held back. An empty workspace
+ * (no repos) is always safe.
+ */
+function protectionReason(statuses, includeDirty) {
+    if (includeDirty)
+        return null;
+    const dirty = statuses.filter((s) => !s.clean).length;
+    const unpushed = statuses.filter((s) => s.ahead > 0).length;
+    if (dirty === 0 && unpushed === 0)
+        return null;
+    const parts = [];
+    if (dirty > 0)
+        parts.push(`${dirty} repo${dirty === 1 ? '' : 's'} with uncommitted changes`);
+    if (unpushed > 0)
+        parts.push(`${unpushed} repo${unpushed === 1 ? '' : 's'} with unpushed commits`);
+    return parts.join(', ');
+}
+/**
+ * Partition stale candidates into prunable vs. protected, given a resolver that
+ * returns each workspace's per-repo git status. The resolver is only invoked
+ * for workspaces that actually have repos, so empty stale workspaces cost no git
+ * calls. Injecting the resolver keeps this function pure and unit-testable.
+ */
+async function planPrune(staleCandidates, getStatuses, includeDirty) {
+    const prunable = [];
+    const protectedList = [];
+    for (const c of staleCandidates) {
+        const statuses = c.repoDirNames.length > 0 ? await getStatuses(c) : [];
+        const reason = protectionReason(statuses, includeDirty);
+        if (reason)
+            protectedList.push({ candidate: c, reason });
+        else
+            prunable.push(c);
+    }
+    return { prunable, protected: protectedList };
+}

package/dist/utils/version-check.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkForUpdate = checkForUpdate;
+exports.updateCheckDisabled = updateCheckDisabled;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -89,6 +90,11 @@ async function fetchLatestVersion() {
  * This is designed to be non-blocking and best-effort — failures are silent.
  */
 async function checkForUpdate() {
+    // Opt-out: skip the check entirely (no cache read, no network) when the user
+    // asks for it. NEMUS_NO_UPDATE_CHECK is ours; NO_UPDATE_NOTIFIER is the
+    // de-facto convention several Node CLIs honor.
+    if (updateCheckDisabled(process.env))
+        return null;
     try {
         const currentVersion = (0, config_1.getPackageVersion)();
         const cache = await loadCache();
@@ -116,6 +122,15 @@ async function checkForUpdate() {
         return null;
     }
 }
+/**
+ * Whether the update check is opted out via env. A value is "set" unless it is
+ * empty or an explicit falsey token (`0`/`false`), so `NEMUS_NO_UPDATE_CHECK=0`
+ * does NOT disable the check. Pure + exported for testing.
+ */
+function updateCheckDisabled(env) {
+    const isSet = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+    return isSet(env.NEMUS_NO_UPDATE_CHECK) || isSet(env.NO_UPDATE_NOTIFIER);
+}
 function formatUpdateMessage(current, latest) {
     return `\x1b[33m[nemus] Update available: ${current} -> ${latest}. Run: npm install -g @nemus-cli/nemus@latest\x1b[0m`;
 }

package/package.json

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

package/scripts/release-notes.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Emit GitHub Release notes for a given version by extracting that version's
+// section from CHANGELOG.md (newest-first "Keep a Changelog" format), prepended
+// with an install snippet and followed by a compare link to the previous tag.
+//
+// Usage: node scripts/release-notes.mjs <version> [repo]
+//   repo defaults to $GITHUB_REPOSITORY or "me-public/nemus".
+//
+// If the version has no CHANGELOG section, prints a minimal fallback (so a
+// release is never blocked on a missing entry). Dependency-free; prints to
+// stdout so the workflow can redirect it into `gh release --notes-file`.
+import { readFileSync } from 'node:fs';
+
+const version = (process.argv[2] || '').trim();
+const repo = (process.argv[3] || process.env.GITHUB_REPOSITORY || 'me-public/nemus').trim();
+if (!version) {
+  process.stderr.write('usage: release-notes.mjs <version> [repo]\n');
+  process.exit(2);
+}
+
+const install = `\`\`\`bash\nnpm install -g @nemus-cli/nemus@${version}\n\`\`\``;
+
+let body = '';
+let prev = null;
+try {
+  const changelog = readFileSync(new URL('../CHANGELOG.md', import.meta.url), 'utf8');
+  const lines = changelog.split('\n');
+  // Collect version headers in file order (newest first) with their line index.
+  const heads = [];
+  lines.forEach((line, i) => {
+    const m = line.match(/^## \[(\d+\.\d+\.\d+)\]/);
+    if (m) heads.push({ version: m[1], line: i });
+  });
+  const idx = heads.findIndex((h) => h.version === version);
+  if (idx !== -1) {
+    const start = heads[idx].line + 1;
+    const end = idx + 1 < heads.length ? heads[idx + 1].line : lines.length;
+    body = lines.slice(start, end).join('\n').trim();
+    // Newest-first: the NEXT header in the file is the previous release.
+    prev = idx + 1 < heads.length ? heads[idx + 1].version : null;
+  }
+} catch {
+  // fall through to fallback
+}
+
+const compare = prev
+  ? `[\`v${prev}...v${version}\`](https://github.com/${repo}/compare/v${prev}...v${version})`
+  : `[\`v${version}\`](https://github.com/${repo}/releases/tag/v${version})`;
+
+const parts = [`## Nemus v${version}`, '', install];
+if (body) parts.push('', body);
+parts.push('', '---', '', `**Full diff:** ${compare} · [Full changelog](https://github.com/${repo}/blob/main/CHANGELOG.md)`);
+
+process.stdout.write(parts.join('\n') + '\n');

package/skills/config.md

@@ -0,0 +1,17 @@
+---
+name: config
+description: Read and write Nemus configuration non-interactively (get/set/unset/list/path/edit)
+---
+
+Non-interactive configuration in `~/.nemus/config.json` (no wizard):
+```bash
+nemus config list                 # all keys + resolved values (alias: ls; --json)
+nemus config get <key>            # print one value (--json)
+nemus config set <key> <value>    # set + validate + persist
+nemus config unset <key>          # revert a key to its default
+nemus config path                 # print the config file path
+```
+
+- Values are validated/coerced per key: booleans accept `true/false/yes/no/on/off/1/0`; enums (e.g. `cloneProtocol=ssh|https`) are checked. Invalid key/value exits non-zero.
+- Common keys: `workspacesDir`, `githubOrg`, `cloneProtocol`, `aiAgent`, `primaryAgent`. Run `nemus config list` to see all.
+- For a guided first-time setup, use `nemus configure` instead.

package/skills/nemus/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: nemus
 description: Manage multi-repo development workspaces — create, sync, branch, diff, clone, archive, analyze dependencies, run commands across repos, check status, clean up, delete, list org repos, search repos, list suites, remove repo, cache, suite management, sessions, history, generate docs, configure, MCP server, AI prompt. Use when working with workspaces, repos, branches, git operations across multiple repos, or the `nemus` CLI tool. NEVER use `git clone` directly — always use `nemus update` to add repos and `nemus create` to create workspaces.
-bashPattern: "\\bnemus\\s+(create|list|update|delete|sync|status|diff|run|go|doctor|analyze-deps|history|cleanup|remove-repo|archive|sessions|generate-docs|configure|configure-claude|ghq-status|tui|dashboard|dash|branch|suite|cache|mcp|--)\\b"
+bashPattern: "\\bnemus\\s+(create|list|update|delete|prune|sync|status|diff|run|go|doctor|analyze-deps|reflect|retro|history|cleanup|remove-repo|archive|sessions|save-context|ctx|generate-docs|configure|config|configure-claude|ghq-status|completion|tui|dashboard|dash|branch|suite|cache|mcp|--)\\b"
 ---
 
 # Nemus
@@ -33,6 +33,7 @@ Global flags: `-f/--force-refresh` (skip repo cache), `-y/--yes` (skip prompts),
 | Create new workspace | [create-workspace](references/create-workspace.md) | `nemus create` | `c` |
 | Add repos to workspace | [update-workspace](references/update-workspace.md) | `nemus update` | `u` |
 | Delete workspace permanently | [delete-workspace](references/delete-workspace.md) | `nemus delete` | `d` |
+| Prune inactive workspaces (safe) | [prune](references/prune.md) | `nemus prune` | — |
 | Archive / unarchive workspace | [archive-workspace](references/archive-workspace.md) | `nemus archive` | `a` |
 | List all workspaces | [list-workspaces](references/list-workspaces.md) | `nemus list` | `l` |
 | Navigate to workspace | [go](references/go.md) | `nemus go [name]` | — |
@@ -88,14 +89,18 @@ Global flags: `-f/--force-refresh` (skip repo cache), `-y/--yes` (skip prompts),
 | Resume Claude session | [sessions](references/sessions.md) | `nemus sessions` | `ses` |
 | Agent management dashboard | [dashboard](references/dashboard.md) | `nemus dashboard` | `dash` |
 | View operation history | [history](references/history.md) | `nemus history` | `h` |
+| Save progress/context to a workspace | [save-context](references/save-context.md) | `nemus save-context` | `ctx` |
+| Retrospective on recent sessions | [reflect](references/reflect.md) | `nemus reflect` | `retro` |
 
 ### Configuration & MCP
 
 | Intent | Reference | CLI |
 |---|---|---|
-| Configure Nemus | [configure](references/configure.md) | `nemus configure` |
+| Configure Nemus (interactive wizard) | [configure](references/configure.md) | `nemus configure` |
+| Get/set config non-interactively | [config](references/config.md) | `nemus config get\|set\|list\|edit` |
 | Configure Claude integration | [configure-claude](references/configure-claude.md) | `nemus configure-claude` |
 | Check ghq status | [ghq-status](references/ghq-status.md) | `nemus ghq-status` |
+| Shell completions (bash/zsh/fish) | [completion](references/completion.md) | `nemus completion <shell>` |
 | Install / manage MCP server | [mcp](references/mcp.md) | `nemus mcp install\|status\|upgrade\|uninstall` |
 
 ### AI Assistant & TUI

package/skills/nemus/references/completion.md

@@ -0,0 +1,22 @@
+# Shell Completions
+
+`nemus completion <shell>` prints a completion script for `bash`, `zsh`, or
+`fish`. It completes subcommands and, for workspace-scoped commands, live
+workspace names (the script calls back into `nemus completion --workspaces`, so
+completions stay fresh without regenerating). Registered for both `nemus` and
+`nem`.
+
+Install (pick your shell):
+```bash
+# bash
+nemus completion bash > /etc/bash_completion.d/nemus     # or: >> ~/.bashrc
+
+# zsh — save on your $fpath as _nemus
+nemus completion zsh > "${fpath[1]}/_nemus"
+
+# fish
+nemus completion fish > ~/.config/fish/completions/nemus.fish
+```
+
+Then restart the shell (or `source` the file). Requires a shell argument —
+one of `bash|zsh|fish`.

package/skills/nemus/references/config.md

@@ -0,0 +1,32 @@
+# Config — non-interactive configuration
+
+`nemus config` reads and writes `~/.nemus/config.json` without the interactive
+`nemus configure` wizard. Ideal for scripting and for setting one value.
+
+```bash
+nemus config list                 # show all keys + resolved values (alias: ls)
+nemus config list --json          # machine-readable
+nemus config get <key>            # print one value (--json for structured)
+nemus config set <key> <value>    # set + validate + persist
+nemus config unset <key>          # remove a key (revert to default)
+nemus config path                 # print the config file path
+nemus config edit                 # open the file in $VISUAL/$EDITOR (needs a TTY)
+```
+
+Values are validated and coerced per key: booleans accept
+`true/false/yes/no/on/off/1/0`; enums (e.g. `cloneProtocol` = `ssh|https`) are
+checked. An unknown key or invalid value exits non-zero with a clear message.
+
+Common keys: `workspacesDir`, `githubOrg`, `cloneProtocol`, `aiAgent`,
+`primaryAgent`, `autoLaunchClaude`, `generateClaudeContext`, `installMcp`.
+Run `nemus config list` to see them all.
+
+```bash
+# examples
+nemus config set githubOrg acme
+nemus config set cloneProtocol https
+nemus config get workspacesDir --json
+```
+
+Pairs well with `--quiet` for scripts. For a guided first-time setup, use
+`nemus configure` instead.

package/skills/nemus/references/prune.md

@@ -0,0 +1,44 @@
+# Prune Inactive Workspaces
+
+Bulk-delete workspaces with no recent activity. **Safe by default** — it holds
+back any workspace with uncommitted or unpushed work.
+
+1. **Always preview first.** Show the user exactly what would be deleted (and
+   what is protected) before removing anything:
+   ```bash
+   nemus prune --days <n> --dry-run
+   ```
+   A workspace is *stale* when its most recent agent session — or, if it has no
+   session, its `createdAt` — is older than `--days` (default 30). Workspaces
+   with no date at all are never selected.
+
+2. **Review the two lists.** `prune` prints:
+   - **Protected** — stale workspaces skipped because a repo has uncommitted
+     changes or unpushed commits (with the reason). These are NOT deleted.
+   - **Prunable** — stale workspaces that are safe to remove.
+
+3. **Confirm with the user, then prune.** This permanently deletes the
+   workspace directories and every cloned repo inside them:
+   ```bash
+   nemus prune --days <n>          # prompts for confirmation (default: No)
+   nemus prune --days <n> --yes    # non-interactive (only when the user is sure)
+   ```
+
+4. **`--json`** gives a machine-readable plan (`{ prunable, protected }`) and,
+   like `--dry-run`, never deletes.
+
+Deletions go through the same validated path as `nemus delete` (name allowlist +
+path pinned inside the workspaces directory).
+
+## Flags
+
+| Flag | Short | Description |
+|---|---|---|
+| `--days <n>` | `-d` | Stale after N days of inactivity (default 30) |
+| `--dry-run` | | Show the plan without deleting anything |
+| `--json` | | Output the plan as JSON (never deletes) |
+| `--yes` | `-y` | Skip the confirmation prompt |
+| `--include-dirty` | | Also prune workspaces with uncommitted/unpushed work (overrides the safety guard — use with care) |
+
+> **Only** pass `--include-dirty` when the user has explicitly accepted losing
+> uncommitted/unpushed work in the protected workspaces.