@nemus-cli/nemus 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-02
+
+### Added
+
+- **Shell completions now cover second-level subcommands and value arguments.**
+  `nemus config <TAB>` completes `get/set/unset/list/path/edit`, `nemus config
+  set <TAB>` completes the config **keys**, and `nemus reflect <TAB>` completes
+  `history/show` — across bash, zsh, and fish. Subcommands are auto-derived from
+  the command tree (so `suite`/`branch`/`cache`/`mcp` are covered too). (#73)
+- **`nemus completion` infers the shell from `$SHELL`** when no argument is
+  given (`nemus completion` → emits your shell's script). An explicit
+  `bash|zsh|fish` still wins; an unknown/invalid value errors as before. (#75)
+
 ## [0.12.0] - 2026-09-02
 
 ### Added

package/dist/commands/completion.js

@@ -1,13 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMPLETION_BINS = void 0;
+exports.SHELLS = exports.COMPLETION_BINS = void 0;
+exports.detectShell = detectShell;
 exports.generateCompletion = generateCompletion;
 exports.specsFromProgram = specsFromProgram;
 exports.registerCompletionCommand = registerCompletionCommand;
 const workspace_meta_1 = require("../utils/workspace-meta");
 const logger_1 = require("../utils/logger");
+const config_schema_1 = require("../utils/config-schema");
 /** Binaries that get completion registered (the CLI's bins). */
 exports.COMPLETION_BINS = ['nemus', 'nem'];
+exports.SHELLS = ['bash', 'zsh', 'fish'];
+/** Commands whose subcommands are positional args (not nested commander commands). */
+const POSITIONAL_SUBCOMMANDS = { reflect: ['history', 'show'] };
+/**
+ * Infer a shell from a `$SHELL`-style path (e.g. `/bin/zsh` -> `zsh`). Returns
+ * null for an unknown/empty value. Pure + exported for testing.
+ */
+function detectShell(shellPath) {
+    if (!shellPath)
+        return null;
+    const base = shellPath.trim().split('/').pop()?.toLowerCase() ?? '';
+    return exports.SHELLS.find((s) => s === base) ?? null;
+}
 /** Every token (name + aliases) that should complete as a subcommand. */
 function allTokens(cmds) {
     return cmds.flatMap((c) => [c.name, ...c.aliases]);
@@ -16,23 +31,46 @@ function allTokens(cmds) {
 function workspaceTokens(cmds) {
     return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
 }
+/** All tokens (name + aliases) that route to a given command spec. */
+function cmdTokens(c) {
+    return [c.name, ...c.aliases];
+}
 /** Escape a description for a fish single-quoted string. */
 function fishDesc(s) {
     return s.replace(/\n/g, ' ').replace(/'/g, "'\\''");
 }
 /**
  * Generate a shell completion script. Pure (no I/O) so it's unit-tested. The
- * generated script completes subcommands at position 1, and for a subcommand
- * that takes a workspace it completes workspace names by calling back into the
- * CLI: `<bin> completion --workspaces`. Dynamic values stay fresh without
- * regenerating the script.
+ * generated script completes, in order: top-level commands (position 1); then
+ * either workspace names (for workspace-scoped commands) or a command's own
+ * subcommands (position 2); then value completions like `config` keys
+ * (position 3). Workspace names stay dynamic via a callback into
+ * `<bin> completion --workspaces`.
  */
 function generateCompletion(shell, cmds, bins = exports.COMPLETION_BINS) {
     const commands = allTokens(cmds).join(' ');
     const wsCommands = workspaceTokens(cmds).join(' ');
+    const withSubs = cmds.filter((c) => c.subcommands && c.subcommands.length);
+    const withArgVals = cmds.filter((c) => c.argValues && c.argValues.values.length);
     if (shell === 'bash') {
+        const subArms = withSubs
+            .map((c) => `    ${cmdTokens(c).join('|')}) echo "${c.subcommands.join(' ')}" ;;`)
+            .join('\n');
+        const argArms = withArgVals
+            .map((c) => `    ${cmdTokens(c).join('|')}) case "$2" in ${c.argValues.after.join('|')}) echo "${c.argValues.values.join(' ')}" ;; esac ;;`)
+            .join('\n');
         return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
 #   (or: nemus completion bash >> ~/.bashrc)
+_nemus_subcmds() {
+  case "$1" in
+${subArms}
+  esac
+}
+_nemus_argvals() {
+  case "$1" in
+${argArms}
+  esac
+}
 _nemus_complete() {
   local cur bin sub
   # bash does not clear COMPREPLY between completions; reset so a stale result
@@ -54,6 +92,20 @@ _nemus_complete() {
       COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
       return 0
     fi
+    local subs
+    subs="\$(_nemus_subcmds "\$sub")"
+    if [ -n "\$subs" ]; then
+      COMPREPLY=( \$(compgen -W "\$subs" -- "\$cur") )
+    fi
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 3 ]; then
+    local vals
+    vals="\$(_nemus_argvals "\${COMP_WORDS[1]}" "\${COMP_WORDS[2]}")"
+    if [ -n "\$vals" ]; then
+      COMPREPLY=( \$(compgen -W "\$vals" -- "\$cur") )
+    fi
+    return 0
   fi
   return 0
 }
@@ -61,6 +113,12 @@ ${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
 `;
     }
     if (shell === 'zsh') {
+        const subArms = withSubs
+            .map((c) => `      ${cmdTokens(c).join('|')}) compadd -- ${c.subcommands.join(' ')} ;;`)
+            .join('\n');
+        const argArms = withArgVals
+            .map((c) => `      ${cmdTokens(c).join('|')}) case \${words[3]} in ${c.argValues.after.join('|')}) compadd -- ${c.argValues.values.join(' ')} ;; esac ;;`)
+            .join('\n');
         // Autoloaded form: save as a file named `_nemus` on your $fpath.
         return `#compdef ${bins.join(' ')}
 # nemus zsh completion. Install: nemus completion zsh > "\${fpath[1]}/_nemus"
@@ -77,7 +135,17 @@ if (( CURRENT == 3 )); then
     local -a _nemus_names
     _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
     compadd -- $_nemus_names
+    return
   fi
+  case $sub in
+${subArms}
+  esac
+  return
+fi
+if (( CURRENT == 4 )); then
+  case \${words[2]} in
+${argArms}
+  esac
 fi
 `;
     }
@@ -86,7 +154,7 @@ fi
     for (const bin of bins) {
         lines.push(`complete -c ${bin} -f`);
         for (const c of cmds) {
-            for (const tok of [c.name, ...c.aliases]) {
+            for (const tok of cmdTokens(c)) {
                 lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
             }
         }
@@ -94,6 +162,14 @@ fi
         if (wsToks) {
             lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`);
         }
+        // Second-level subcommands.
+        for (const c of withSubs) {
+            lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}' -a '${c.subcommands.join(' ')}'`);
+        }
+        // Third-level value completions (e.g. config keys after get/set/unset).
+        for (const c of withArgVals) {
+            lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}; and __fish_seen_subcommand_from ${c.argValues.after.join(' ')}' -a '${c.argValues.values.join(' ')}'`);
+        }
     }
     return lines.join('\n') + '\n';
 }
@@ -103,11 +179,19 @@ function specsFromProgram(program) {
         .map((c) => {
         const args = c.registeredArguments ?? [];
         const firstArg = args[0]?.name?.();
+        const name = c.name();
+        // Nested commander subcommands (config/suite/branch/cache/mcp), else a
+        // manual override for commands whose subcommands are positional (reflect).
+        const nested = c.commands.flatMap((s) => [s.name(), ...s.aliases()]).filter(Boolean);
+        const subcommands = nested.length ? nested : POSITIONAL_SUBCOMMANDS[name];
+        const argValues = name === 'config' ? { after: ['get', 'set', 'unset'], values: [...config_schema_1.CONFIG_KEYS] } : undefined;
         return {
-            name: c.name(),
+            name,
             aliases: c.aliases(),
             takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
             description: c.description() ?? '',
+            ...(subcommands ? { subcommands } : {}),
+            ...(argValues ? { argValues } : {}),
         };
     })
         // The completion command itself and any hidden helper needn't clutter, but
@@ -117,7 +201,7 @@ function specsFromProgram(program) {
 function registerCompletionCommand(program) {
     program
         .command('completion [shell]')
-        .description('Output a shell completion script (bash|zsh|fish)')
+        .description('Output a shell completion script (bash|zsh|fish; inferred from $SHELL if omitted)')
         .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
         .action(async (shell, opts) => {
         // Data helper the generated scripts call back into.
@@ -132,12 +216,22 @@ function registerCompletionCommand(program) {
             }
             return;
         }
-        const shells = ['bash', 'zsh', 'fish'];
-        if (!shell || !shells.includes(shell)) {
-            (0, logger_1.logError)(`completion: specify a shell — one of ${shells.join(', ')}`);
+        // An explicit argument wins; only fall back to $SHELL when none is given
+        // (an invalid explicit arg is an error, not a reason to guess).
+        let target = null;
+        if (shell) {
+            target = exports.SHELLS.includes(shell) ? shell : null;
+        }
+        else {
+            target = detectShell(process.env.SHELL);
+            if (target)
+                (0, logger_1.logInfo)(`completion: no shell given — using ${target} (from $SHELL)`);
+        }
+        if (!target) {
+            (0, logger_1.logError)(`completion: specify a shell — one of ${exports.SHELLS.join(', ')}`);
             (0, logger_1.logError)('e.g. nemus completion bash');
             process.exit(1);
         }
-        process.stdout.write(generateCompletion(shell, specsFromProgram(program)));
+        process.stdout.write(generateCompletion(target, specsFromProgram(program)));
     });
 }

package/package.json

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

package/skills/nemus/references/completion.md

@@ -18,5 +18,10 @@ nemus completion zsh > "${fpath[1]}/_nemus"
 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`.
+Then restart the shell (or `source` the file). The shell argument is inferred
+from `$SHELL` when omitted (`nemus completion`), so you usually don't need to
+pass it; an explicit `bash|zsh|fish` always wins.
+
+Completions cover second-level subcommands too — e.g. `nemus config <TAB>`
+(get/set/…), `nemus config set <TAB>` (config keys), and `nemus reflect <TAB>`
+(history/show).

package/src/commands/completion.test.ts

@@ -1,6 +1,6 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { Command } from 'commander';
-import { generateCompletion, specsFromProgram, CommandSpec } from './completion';
+import { generateCompletion, specsFromProgram, detectShell, registerCompletionCommand, CommandSpec } from './completion';
 
 const specs: CommandSpec[] = [
   { name: 'list', aliases: ['l'], takesWorkspace: false, description: 'List workspaces' },
@@ -8,6 +8,49 @@ const specs: CommandSpec[] = [
   { name: 'doctor', aliases: ['doc'], takesWorkspace: true, description: 'Health checks' },
 ];
 
+// A spec set exercising second-level subcommands and third-level value completion.
+const subSpecs: CommandSpec[] = [
+  {
+    name: 'config', aliases: [], takesWorkspace: false, description: 'Configure',
+    subcommands: ['get', 'set', 'list', 'ls'],
+    argValues: { after: ['get', 'set'], values: ['githubOrg', 'cloneProtocol'] },
+  },
+  { name: 'reflect', aliases: ['retro'], takesWorkspace: false, description: 'Retrospective', subcommands: ['history', 'show'] },
+];
+
+describe('detectShell', () => {
+  it('infers the shell from a $SHELL-style path', () => {
+    expect(detectShell('/bin/zsh')).toBe('zsh');
+    expect(detectShell('/usr/bin/fish')).toBe('fish');
+    expect(detectShell('/bin/bash')).toBe('bash');
+  });
+  it('returns null for unknown/empty values', () => {
+    expect(detectShell('/bin/tcsh')).toBeNull();
+    expect(detectShell('')).toBeNull();
+    expect(detectShell(undefined)).toBeNull();
+  });
+});
+
+describe('generateCompletion — second/third level', () => {
+  it('bash completes subcommands and config-key values, and stays valid', () => {
+    const s = generateCompletion('bash', subSpecs);
+    expect(s).toContain('config) echo "get set list ls" ;;');
+    expect(s).toContain('reflect|retro) echo "history show" ;;');
+    expect(s).toContain('case "$2" in get|set) echo "githubOrg cloneProtocol"');
+  });
+  it('zsh completes subcommands and values at CURRENT 3/4', () => {
+    const s = generateCompletion('zsh', subSpecs);
+    expect(s).toContain('config) compadd -- get set list ls ;;');
+    expect(s).toContain('reflect|retro) compadd -- history show ;;');
+    expect(s).toContain('case ${words[3]} in get|set) compadd -- githubOrg cloneProtocol');
+  });
+  it('fish emits seen-subcommand conditions for subcommands and values', () => {
+    const s = generateCompletion('fish', subSpecs);
+    expect(s).toContain("-n '__fish_seen_subcommand_from config' -a 'get set list ls'");
+    expect(s).toContain("__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get set");
+  });
+});
+
 describe('generateCompletion — bash', () => {
   const s = generateCompletion('bash', specs);
   it('resets COMPREPLY, lists tokens, and registers both bins', () => {
@@ -43,6 +86,42 @@ describe('generateCompletion — fish', () => {
   });
 });
 
+describe('registerCompletionCommand — stdout hygiene on inferred shell', () => {
+  it('writes ONLY the script to stdout; the $SHELL inference note goes to stderr', async () => {
+    // The documented install path is `nemus completion zsh > _nemus`, so if the
+    // inference note leaked to stdout it would corrupt the generated script.
+    const program = new Command();
+    program.exitOverride();
+    program.command('list').description('list');
+    registerCompletionCommand(program);
+
+    const stdoutChunks: string[] = [];
+    const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(((c: unknown) => {
+      stdoutChunks.push(String(c));
+      return true;
+    }) as typeof process.stdout.write);
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const prevShell = process.env.SHELL;
+    process.env.SHELL = '/bin/zsh';
+
+    let errCalls: string[] = [];
+    try {
+      await program.parseAsync(['node', 'nemus', 'completion']);
+      errCalls = errSpy.mock.calls.map((c) => c.map(String).join(' '));
+    } finally {
+      if (prevShell === undefined) delete process.env.SHELL;
+      else process.env.SHELL = prevShell;
+      stdoutSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+
+    const stdout = stdoutChunks.join('');
+    expect(stdout.startsWith('#compdef')).toBe(true); // the zsh script, nothing prepended
+    expect(stdout).not.toContain('no shell given'); // the note never reached stdout
+    expect(errCalls.some((l) => l.includes('no shell given'))).toBe(true); // it went to stderr
+  });
+});
+
 describe('specsFromProgram', () => {
   it('detects workspace args + aliases from a commander program', () => {
     const program = new Command();
@@ -57,4 +136,26 @@ describe('specsFromProgram', () => {
     expect(byName.list.takesWorkspace).toBe(false);
     expect(byName.create.takesWorkspace).toBe(false);
   });
+
+  it('derives nested subcommands, the reflect override, and config keys', () => {
+    const program = new Command();
+    const cfg = program.command('config').description('config');
+    cfg.command('get').description('get');
+    cfg.command('set').description('set');
+    program.command('reflect').description('reflect'); // positional subcommands
+    program.command('list').description('list');
+
+    const byName = Object.fromEntries(specsFromProgram(program).map((s) => [s.name, s]));
+    // nested commander subcommands are auto-derived
+    expect(byName.config.subcommands).toContain('get');
+    expect(byName.config.subcommands).toContain('set');
+    // reflect's positional subcommands come from the override
+    expect(byName.reflect.subcommands).toEqual(['history', 'show']);
+    // config gets key-value completion from the authoritative CONFIG_KEYS
+    expect(byName.config.argValues?.after).toEqual(['get', 'set', 'unset']);
+    expect(byName.config.argValues?.values).toContain('githubOrg');
+    // a plain command has neither
+    expect(byName.list.subcommands).toBeUndefined();
+    expect(byName.list.argValues).toBeUndefined();
+  });
 });

package/src/commands/completion.ts

@@ -1,11 +1,16 @@
 import { Command } from 'commander';
 import { listWorkspaces } from '../utils/workspace-meta';
-import { logError } from '../utils/logger';
+import { logError, logInfo } from '../utils/logger';
+import { CONFIG_KEYS } from '../utils/config-schema';
 
 /** Binaries that get completion registered (the CLI's bins). */
 export const COMPLETION_BINS = ['nemus', 'nem'];
 
 export type Shell = 'bash' | 'zsh' | 'fish';
+export const SHELLS: Shell[] = ['bash', 'zsh', 'fish'];
+
+/** Commands whose subcommands are positional args (not nested commander commands). */
+const POSITIONAL_SUBCOMMANDS: Record<string, string[]> = { reflect: ['history', 'show'] };
 
 /** One top-level command, distilled to what a completion script needs. */
 export interface CommandSpec {
@@ -14,6 +19,20 @@ export interface CommandSpec {
   /** True if its first positional argument is a workspace name. */
   takesWorkspace: boolean;
   description: string;
+  /** Second-level tokens (e.g. `config get`, `reflect history`), if any. */
+  subcommands?: string[];
+  /** Third-level value completion: for these subcommands, complete `values`. */
+  argValues?: { after: string[]; values: string[] };
+}
+
+/**
+ * Infer a shell from a `$SHELL`-style path (e.g. `/bin/zsh` -> `zsh`). Returns
+ * null for an unknown/empty value. Pure + exported for testing.
+ */
+export function detectShell(shellPath: string | undefined): Shell | null {
+  if (!shellPath) return null;
+  const base = shellPath.trim().split('/').pop()?.toLowerCase() ?? '';
+  return SHELLS.find((s) => s === base) ?? null;
 }
 
 /** Every token (name + aliases) that should complete as a subcommand. */
@@ -26,6 +45,11 @@ function workspaceTokens(cmds: CommandSpec[]): string[] {
   return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
 }
 
+/** All tokens (name + aliases) that route to a given command spec. */
+function cmdTokens(c: CommandSpec): string[] {
+  return [c.name, ...c.aliases];
+}
+
 /** Escape a description for a fish single-quoted string. */
 function fishDesc(s: string): string {
   return s.replace(/\n/g, ' ').replace(/'/g, "'\\''");
@@ -33,18 +57,40 @@ function fishDesc(s: string): string {
 
 /**
  * Generate a shell completion script. Pure (no I/O) so it's unit-tested. The
- * generated script completes subcommands at position 1, and for a subcommand
- * that takes a workspace it completes workspace names by calling back into the
- * CLI: `<bin> completion --workspaces`. Dynamic values stay fresh without
- * regenerating the script.
+ * generated script completes, in order: top-level commands (position 1); then
+ * either workspace names (for workspace-scoped commands) or a command's own
+ * subcommands (position 2); then value completions like `config` keys
+ * (position 3). Workspace names stay dynamic via a callback into
+ * `<bin> completion --workspaces`.
  */
 export function generateCompletion(shell: Shell, cmds: CommandSpec[], bins: string[] = COMPLETION_BINS): string {
   const commands = allTokens(cmds).join(' ');
   const wsCommands = workspaceTokens(cmds).join(' ');
+  const withSubs = cmds.filter((c) => c.subcommands && c.subcommands.length);
+  const withArgVals = cmds.filter((c) => c.argValues && c.argValues.values.length);
 
   if (shell === 'bash') {
+    const subArms = withSubs
+      .map((c) => `    ${cmdTokens(c).join('|')}) echo "${c.subcommands!.join(' ')}" ;;`)
+      .join('\n');
+    const argArms = withArgVals
+      .map(
+        (c) =>
+          `    ${cmdTokens(c).join('|')}) case "$2" in ${c.argValues!.after.join('|')}) echo "${c.argValues!.values.join(' ')}" ;; esac ;;`,
+      )
+      .join('\n');
     return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
 #   (or: nemus completion bash >> ~/.bashrc)
+_nemus_subcmds() {
+  case "$1" in
+${subArms}
+  esac
+}
+_nemus_argvals() {
+  case "$1" in
+${argArms}
+  esac
+}
 _nemus_complete() {
   local cur bin sub
   # bash does not clear COMPREPLY between completions; reset so a stale result
@@ -66,6 +112,20 @@ _nemus_complete() {
       COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
       return 0
     fi
+    local subs
+    subs="\$(_nemus_subcmds "\$sub")"
+    if [ -n "\$subs" ]; then
+      COMPREPLY=( \$(compgen -W "\$subs" -- "\$cur") )
+    fi
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 3 ]; then
+    local vals
+    vals="\$(_nemus_argvals "\${COMP_WORDS[1]}" "\${COMP_WORDS[2]}")"
+    if [ -n "\$vals" ]; then
+      COMPREPLY=( \$(compgen -W "\$vals" -- "\$cur") )
+    fi
+    return 0
   fi
   return 0
 }
@@ -74,6 +134,15 @@ ${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
   }
 
   if (shell === 'zsh') {
+    const subArms = withSubs
+      .map((c) => `      ${cmdTokens(c).join('|')}) compadd -- ${c.subcommands!.join(' ')} ;;`)
+      .join('\n');
+    const argArms = withArgVals
+      .map(
+        (c) =>
+          `      ${cmdTokens(c).join('|')}) case \${words[3]} in ${c.argValues!.after.join('|')}) compadd -- ${c.argValues!.values.join(' ')} ;; esac ;;`,
+      )
+      .join('\n');
     // Autoloaded form: save as a file named `_nemus` on your $fpath.
     return `#compdef ${bins.join(' ')}
 # nemus zsh completion. Install: nemus completion zsh > "\${fpath[1]}/_nemus"
@@ -90,7 +159,17 @@ if (( CURRENT == 3 )); then
     local -a _nemus_names
     _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
     compadd -- $_nemus_names
+    return
   fi
+  case $sub in
+${subArms}
+  esac
+  return
+fi
+if (( CURRENT == 4 )); then
+  case \${words[2]} in
+${argArms}
+  esac
 fi
 `;
   }
@@ -100,7 +179,7 @@ fi
   for (const bin of bins) {
     lines.push(`complete -c ${bin} -f`);
     for (const c of cmds) {
-      for (const tok of [c.name, ...c.aliases]) {
+      for (const tok of cmdTokens(c)) {
         lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
       }
     }
@@ -110,6 +189,18 @@ fi
         `complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`,
       );
     }
+    // Second-level subcommands.
+    for (const c of withSubs) {
+      lines.push(
+        `complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}' -a '${c.subcommands!.join(' ')}'`,
+      );
+    }
+    // Third-level value completions (e.g. config keys after get/set/unset).
+    for (const c of withArgVals) {
+      lines.push(
+        `complete -c ${bin} -n '__fish_seen_subcommand_from ${cmdTokens(c).join(' ')}; and __fish_seen_subcommand_from ${c.argValues!.after.join(' ')}' -a '${c.argValues!.values.join(' ')}'`,
+      );
+    }
   }
   return lines.join('\n') + '\n';
 }
@@ -120,11 +211,20 @@ export function specsFromProgram(program: Command): CommandSpec[] {
     .map((c) => {
       const args = (c as any).registeredArguments ?? [];
       const firstArg: string | undefined = args[0]?.name?.();
+      const name = c.name();
+      // Nested commander subcommands (config/suite/branch/cache/mcp), else a
+      // manual override for commands whose subcommands are positional (reflect).
+      const nested = c.commands.flatMap((s) => [s.name(), ...s.aliases()]).filter(Boolean);
+      const subcommands = nested.length ? nested : POSITIONAL_SUBCOMMANDS[name];
+      const argValues =
+        name === 'config' ? { after: ['get', 'set', 'unset'], values: [...CONFIG_KEYS] } : undefined;
       return {
-        name: c.name(),
+        name,
         aliases: c.aliases(),
         takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
         description: c.description() ?? '',
+        ...(subcommands ? { subcommands } : {}),
+        ...(argValues ? { argValues } : {}),
       };
     })
     // The completion command itself and any hidden helper needn't clutter, but
@@ -135,7 +235,7 @@ export function specsFromProgram(program: Command): CommandSpec[] {
 export function registerCompletionCommand(program: Command) {
   program
     .command('completion [shell]')
-    .description('Output a shell completion script (bash|zsh|fish)')
+    .description('Output a shell completion script (bash|zsh|fish; inferred from $SHELL if omitted)')
     .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
     .action(async (shell: string | undefined, opts: { workspaces?: boolean }) => {
       // Data helper the generated scripts call back into.
@@ -149,12 +249,21 @@ export function registerCompletionCommand(program: Command) {
         return;
       }
 
-      const shells: Shell[] = ['bash', 'zsh', 'fish'];
-      if (!shell || !shells.includes(shell as Shell)) {
-        logError(`completion: specify a shell — one of ${shells.join(', ')}`);
+      // An explicit argument wins; only fall back to $SHELL when none is given
+      // (an invalid explicit arg is an error, not a reason to guess).
+      let target: Shell | null = null;
+      if (shell) {
+        target = SHELLS.includes(shell as Shell) ? (shell as Shell) : null;
+      } else {
+        target = detectShell(process.env.SHELL);
+        if (target) logInfo(`completion: no shell given — using ${target} (from $SHELL)`);
+      }
+
+      if (!target) {
+        logError(`completion: specify a shell — one of ${SHELLS.join(', ')}`);
         logError('e.g. nemus completion bash');
         process.exit(1);
       }
-      process.stdout.write(generateCompletion(shell as Shell, specsFromProgram(program)));
+      process.stdout.write(generateCompletion(target, specsFromProgram(program)));
     });
 }