numux 2.10.4 → 2.11.0

package/dist/numux.js

@@ -31,13 +31,514 @@ var __toESM = (mod, isNodeMode, target) => {
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
+// src/generated/help-topics.ts
+var TOPIC_ALIASES, HELP_TOPICS;
+var init_help_topics = __esm(() => {
+  TOPIC_ALIASES = {
+    keys: "keybindings",
+    icons: "tab-icons",
+    deps: "dependency-orchestration",
+    "env-interpolation": "environment-variable-interpolation"
+  };
+  HELP_TOPICS = {
+    install: { title: "Install", body: `Requires [Bun](https://bun.sh) >= 1.0.
+
+\`\`\`sh
+bun install -g numux
+\`\`\`` },
+    "quick-start": { title: "Quick start", body: `\`\`\`sh
+numux init
+\`\`\`
+
+This creates a starter \`numux.config.ts\` with commented-out examples. Edit it, then run \`numux\`.` },
+    "config-file": { title: "Config file", body: `Create \`numux.config.ts\` (or \`.js\`):
+
+\`\`\`ts
+import { defineConfig } from 'numux'
+
+export default defineConfig({
+  processes: {
+    db: {
+      command: 'docker compose up postgres',
+      readyPattern: 'ready to accept connections',
+    },
+    migrate: {
+      command: 'bun run migrate',
+      dependsOn: ['db'],
+    },
+    api: {
+      command: 'bun run dev:api',
+      dependsOn: ['migrate'],
+      readyPattern: 'listening on port 3000',
+    },
+    // String shorthand for simple processes
+    web: 'bun run dev:web',
+    // Interactive process \u2014 keyboard input is forwarded
+    confirm: {
+      command: 'sh -c "printf \\'Deploy to staging? [y/n] \\' && read answer && echo $answer"',
+      interactive: true,
+    },
+  },
+})
+\`\`\`
+
+The \`defineConfig()\` helper is optional \u2014 it provides type checking for your config.
+
+Processes can be a string (shorthand for \`{ command: "..." }\`), \`true\` or \`{}\` (auto-resolves to a matching \`package.json\` script), or a full config object.
+
+Then run:
+
+\`\`\`sh
+numux
+\`\`\`` },
+    subcommands: { title: "Subcommands", body: `<!-- generated:subcommands -->
+\`\`\`sh
+numux init                         # Create a starter config file
+numux validate                     # Validate config and show process graph
+numux exec <name> [--] <cmd>       # Run a command in a process's environment
+numux logs [name]                  # Open the log directory or a specific process log
+numux completions <shell>          # Generate shell completions (bash, zsh, fish)
+numux help [topic]                 # Show help for a topic
+\`\`\`
+<!-- /generated:subcommands -->
+
+\`validate\` respects \`--only\`/\`--exclude\` filters and shows processes grouped by dependency tiers.
+
+\`exec\` runs a one-off command using a process's configured \`cwd\`, \`env\`, and \`envFile\` \u2014 useful for migrations, scripts, or any command that needs the same environment:
+
+\`\`\`sh
+numux exec api -- npx prisma migrate
+numux exec web npm run build
+\`\`\`
+
+\`logs\` prints the log directory path, or a specific process's log contents:
+
+\`\`\`sh
+numux logs           # Print log directory path
+numux logs api       # Print the api process log
+\`\`\`
+
+Set up completions for your shell:
+
+\`\`\`sh
+# Bash (add to ~/.bashrc)
+eval "$(numux completions bash)"
+
+# Zsh (add to ~/.zshrc)
+eval "$(numux completions zsh)"
+
+# Fish
+numux completions fish | source
+# Or save permanently:
+numux completions fish > ~/.config/fish/completions/numux.fish
+\`\`\`` },
+    workspaces: { title: "Workspaces", body: `Run a \`package.json\` script across all workspaces in a monorepo:
+
+\`\`\`sh
+numux -w dev
+\`\`\`
+
+Reads the \`workspaces\` field from your root \`package.json\`, finds which workspaces have the given script, and spawns \`<pm> run <script>\` in each. The package manager is auto-detected from \`packageManager\` field or lockfiles.
+
+Composes with other flags:
+
+\`\`\`sh
+numux -w dev -n redis="redis-server" --colors
+\`\`\`` },
+    "ad-hoc-commands": { title: "Ad-hoc commands", body: `\`\`\`sh
+# Unnamed (name derived from command)
+numux "bun dev:api" "bun dev:web"
+
+# Named process
+numux -n api="bun dev:api" -n web="bun dev:web"
+\`\`\`` },
+    "script-patterns": { title: "Script patterns", body: `Run package.json scripts by name \u2014 any colon-containing name is automatically recognized as a script reference:
+
+\`\`\`sh
+numux 'lint:eslint --fix'  # runs: yarn run lint:eslint --fix
+numux 'dev:*'              # all scripts matching dev:*
+numux 'npm:*:dev'          # explicit npm: prefix (same behavior)
+\`\`\`
+
+<!-- generated:script-pattern-rules -->` },
+    "script-pattern-rules": { title: "Script pattern rules", body: `**Recognition:** A process name is treated as a script reference when it:
+- starts with \`npm:\` (e.g. \`npm:dev:*\`)
+- contains glob metacharacters (\`*\`, \`?\`, \`[\`)
+- contains a colon AND has no explicit \`command\` (e.g. \`lint:eslint: {}\`)
+
+**Glob matching:** Patterns are matched against \`package.json\` scripts using
+\`Bun.Glob\`. The \`*\` wildcard does NOT match across \`:\` separators \u2014 \`dev:*\`
+matches \`dev:web\` but not \`dev:web:hmr\`. Use \`dev:*:*\` for two levels deep.
+
+**Leaf-only (\`^\`):** Append \`^\` to skip scripts that are group runners \u2014
+scripts that have sub-scripts beneath them. E.g. if \`format:check\` has
+\`format:check:store\` and \`format:check:odoo\` below it, \`format:*^\` excludes
+\`format:check\` but keeps the leaf scripts.
+
+**Extra args:** Anything after the first space in the pattern is forwarded
+as extra arguments to each matched command: \`lint:* --fix\` \u2192 \`bun run lint:js -- --fix\`.
+
+**Template inheritance:** Config properties on a pattern entry (color, env,
+dependsOn, etc.) are inherited by all expanded processes. Color arrays are
+distributed round-robin across matches.
+
+**Display names:** The glob's literal prefix and suffix are stripped from
+matched script names: \`dev:*\` + \`dev:web\` \u2192 display name \`web\`.` },
+    "auto-resolution": { title: "Auto-resolution", body: `When a process has no \`command\` and its name matches a \`package.json\` script,
+the command is auto-resolved to \`<pm> run <name>\`. This works for:
+- \`true\` or \`{}\` shorthand: \`lint: true\` \u2192 \`bun run lint\`
+- Objects without \`command\`: \`typecheck: { dependsOn: ['db'] }\` \u2192 \`bun run typecheck\`` },
+    "npm-prefix": { title: "npm: prefix", body: `Commands starting with \`npm:\` are rewritten to use the detected package
+manager: \`npm:dev\` \u2192 \`bun run dev\` (if bun is detected).
+<!-- /generated:script-pattern-rules -->
+
+\`\`\`sh
+numux 'lint:* --fix'      # \u2192 bun run lint:js --fix, bun run lint:ts --fix
+\`\`\`
+
+In a config file, use the pattern as the process name:
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    'dev:*': { color: ['green', 'cyan'] },
+    'lint:* --fix': {},
+  },
+})
+\`\`\`
+
+Auto-resolution example:
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    lint: true,                       // \u2192 bun run lint
+    typecheck: { dependsOn: ['db'] }, // \u2192 bun run typecheck (with dependency)
+    db: 'docker compose up postgres', // explicit command, not resolved
+  },
+})
+\`\`\`` },
+    options: { title: "Options", body: `<!-- generated:options -->
+| Flag | Description |
+|------|-------------|
+| \`-s,\` \`--sort\` \`<config|alphabetical|topological>\` | Tab display order |
+| \`-w,\` \`--workspace\` \`<script>\` | Run a package.json script across all workspaces |
+| \`-n,\` \`--name\` \`<name=command>\` | Add a named process |
+| \`-c,\` \`--color\` \`<colors>\` | Comma-separated colors (hex or names: black, red, green, yellow, blue, magenta, cyan, white, gray, orange, purple) |
+| \`--colors\` | Auto-assign colors to processes based on their name |
+| \`-e,\` \`--env-file\` \`<path|false>\` | Env file path, or "false" to disable env file loading |
+| \`--config\` \`<path>\` | Config file path (default: auto-detect) |
+| \`-p,\` \`--prefix\` | Prefixed output mode (no TUI, for CI/scripts) |
+| \`--only\` \`<a,b,...>\` | Only run these processes (+ their dependencies) |
+| \`--exclude\` \`<a,b,...>\` | Exclude these processes |
+| \`--kill-others\` | Kill all processes when any exits (regardless of exit code) |
+| \`--kill-others-on-fail\` | Kill all processes when any exits with non-zero code |
+| \`--max-restarts\` \`<n>\` | Max auto-restarts for crashed processes |
+| \`--no-watch\` | Disable file watching even if config has watch patterns |
+| \`-t,\` \`--timestamps\` \`[<format>]\` | Add timestamps to output (default HH:mm:ss, or pass a format string) |
+| \`--log-dir\` \`<path>\` | Write per-process logs to directory |
+| \`--debug\` | Enable debug logging to .numux/debug.log |
+| \`-h,\` \`--help\` | Show this help |
+| \`-v,\` \`--version\` | Show version |
+<!-- /generated:options -->` },
+    "prefix-mode": { title: "Prefix mode", body: `Use \`--prefix\` (\`-p\`) for CI or headless environments. Output is printed with colored \`[name]\` prefixes instead of the TUI:
+
+\`\`\`sh
+numux --prefix
+\`\`\`
+
+Auto-exits when all processes finish. Exit code 1 if any process failed.` },
+    "global-options": { title: "Global options", body: `Top-level options apply to all processes (process-level settings override):
+
+<!-- generated:config-global -->
+| Field | Type | Description |
+|-------|------|-------------|
+| \`cwd\` | \`string\` | Global working directory, inherited by all processes |
+| \`env\` | \`Record<string, string>\` | Global env vars, merged into each process (process-level overrides) |
+| \`envFile\` | \`string \\| string[] \\| false\` | Global .env file(s), inherited by processes without their own envFile; \`false\` disables |
+| \`showCommand\` | \`boolean\` | Global showCommand flag, inherited by all processes |
+| \`maxRestarts\` | \`number\` | Global restart limit, inherited by all processes (only restarts on non-zero exit) |
+| \`readyTimeout\` | \`number\` | Global ready timeout (ms), inherited by all processes |
+| \`stopSignal\` | \`'SIGTERM' \\| 'SIGINT' \\| 'SIGHUP'\` | Global stop signal, inherited by all processes |
+| \`errorMatcher\` | \`boolean \\| string\` | Global error matcher, inherited by all processes. \`true\` = detect ANSI red output, string = regex |
+| \`watch\` | \`string \\| string[]\` | Global watch patterns, inherited by processes without their own watch |
+| \`sort\` | \`'config' \\| 'alphabetical' \\| 'topological'\` | Tab display order. \`'config'\` preserves definition order (package.json script order for wildcards), \`'alphabetical'\` sorts by process name, \`'topological'\` sorts by dependency tiers. |
+| \`prefix\` | \`boolean\` | Use prefixed output mode instead of TUI (for CI/scripts) |
+| \`timestamps\` | \`boolean \\| string\` | Add timestamps to output lines. \`true\` uses default \`HH:mm:ss\` format, or pass a format string (e.g. \`"HH:mm:ss.SSS"\`) |
+| \`killOthers\` | \`boolean\` | Kill all processes when any one exits (regardless of exit code) |
+| \`killOthersOnFail\` | \`boolean\` | Kill all processes when any one exits with a non-zero exit code |
+| \`noWatch\` | \`boolean\` | Disable file watching even if processes have watch patterns |
+| \`logDir\` | \`string\` | Directory to write per-process log files |
+<!-- /generated:config-global -->
+
+\`\`\`ts
+export default defineConfig({
+  cwd: './packages/backend',
+  env: { NODE_ENV: 'development' },
+  envFile: '.env',
+  processes: {
+    api: { command: 'node server.js' },           // inherits cwd, env, envFile
+    web: { command: 'vite', cwd: './packages/web' }, // overrides cwd
+  },
+})
+\`\`\`` },
+    "process-options": { title: "Process options", body: `Each process accepts:
+
+<!-- generated:config-process -->
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| \`command\` | \`string\` | *required* | Shell command to run. Supports \`$dep.group\` references from dependency capture groups |
+| \`cwd\` | \`string\` | \u2014 | Working directory for the process |
+| \`env\` | \`Record<string, string>\` | \u2014 | Extra environment variables. Values support \`$dep.group\` references from dependency capture groups. |
+| \`envFile\` | \`string \\| string[] \\| false\` | \u2014 | .env file path(s) to load, or \`false\` to disable |
+| \`dependsOn\` | \`string \\| string[]\` | \u2014 | Processes that must be ready before this one starts |
+| \`readyPattern\` | \`string \\| RegExp\` | \u2014 | Regex matched against stdout to signal readiness. Use \`RegExp\` to capture groups for \`$dep.group\` expansion |
+| \`maxRestarts\` | \`number\` | \`0\` | Limit auto-restart attempts (only restarts on non-zero exit) |
+| \`readyTimeout\` | \`number\` | \u2014 | Milliseconds to wait for readyPattern before failing |
+| \`delay\` | \`number\` | \u2014 | Milliseconds to wait before starting the process |
+| \`condition\` | \`string\` | \u2014 | Env var name (prefix with \`!\` to negate); process skipped if condition is falsy |
+| \`platform\` | \`string \\| string[]\` | \u2014 | OS(es) this process runs on (e.g. \`'darwin'\`, \`'linux'\`). Non-matching processes are removed, their dependents still start |
+| \`stopSignal\` | \`'SIGTERM' \\| 'SIGINT' \\| 'SIGHUP'\` | \`'SIGTERM'\` | Signal for graceful stop |
+| \`color\` | \`string \\| string[]\` | \u2014 | Hex color (e.g. \`"#ff6600"\`) or color name. Array for round-robin in script patterns |
+| \`watch\` | \`string \\| string[]\` | \u2014 | Glob patterns \u2014 restart process when matching files change |
+| \`interactive\` | \`boolean\` | \`false\` | When true, keyboard input is forwarded to the process |
+| \`optional\` | \`boolean\` | \u2014 | Process is visible but not started automatically. Use Alt+S to start manually |
+| \`errorMatcher\` | \`boolean \\| string\` | \u2014 | \`true\` = detect ANSI red output, string = regex pattern |
+| \`workspaces\` | \`boolean \\| string \\| string[]\` | \u2014 | Run command in monorepo workspaces. \`true\` = all workspaces, string = specific workspace by name/path, string[] = multiple workspaces |
+| \`showCommand\` | \`boolean\` | \`true\` | Print the command being run as the first line of output |
+<!-- /generated:config-process -->` },
+    "workspace-expansion": { title: "Workspace expansion", body: `Use \`workspaces\` on a process to expand it into per-workspace processes. Reads the \`workspaces\` field from your root \`package.json\`.
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    // All workspaces \u2014 filters by script availability for PM run commands
+    lint: { command: 'npm run lint', workspaces: true },
+
+    // Specific workspace by package name
+    validate: { command: 'npm run validate', workspaces: '@repo/image-worker' },
+
+    // Multiple specific workspaces
+    dev: { command: 'npm run dev', workspaces: ['@repo/api', '@repo/web'] },
+  },
+})
+\`\`\`
+
+Each entry expands into \`{name}:{wsName}\` processes (e.g. \`lint:api\`, \`lint:web\`) with \`cwd\` set to the workspace directory. All other config (env, dependsOn, color, etc.) is inherited from the template.
+
+When \`workspaces: true\` is used with a PM run command (\`npm run lint\`), only workspaces that have the matching script are included. Raw commands (\`eslint .\`) run in all workspaces.
+
+String values resolve by package name first (with or without scope), then fall back to relative path. Cannot be combined with \`cwd\`.` },
+    "file-watching": { title: "File watching", body: `Use \`watch\` to automatically restart a process when source files change:
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    api: {
+      command: 'node server.js',
+      watch: 'src/**/*.ts',
+    },
+    styles: {
+      command: 'sass --watch src:dist',
+      watch: ['src/**/*.scss', 'src/**/*.css'],
+    },
+  },
+})
+\`\`\`
+
+Patterns are matched relative to the process's \`cwd\` (or the project root). Changes in \`node_modules\` and \`.git\` are always ignored. Rapid file changes are debounced (300ms) to avoid restart storms.
+
+A watched process is only restarted if it's currently running, ready, or failed \u2014 manually stopped processes are not affected.` },
+    "environment-variable-interpolation": { title: "Environment variable interpolation", body: `Config values support \`\${VAR}\` syntax for environment variable substitution:
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    api: {
+      command: 'node server.js --port \${PORT:-3000}',
+      env: {
+        DATABASE_URL: '\${DATABASE_URL:?DATABASE_URL must be set}',
+      },
+    },
+  },
+})
+\`\`\`
+
+| Syntax | Behavior |
+|--------|----------|
+| \`\${VAR}\` | Value of \`VAR\`, or empty string if unset |
+| \`\${VAR:-default}\` | Value of \`VAR\`, or \`default\` if unset |
+| \`\${VAR:?error}\` | Value of \`VAR\`, or error with message if unset |
+
+Interpolation applies to all string values in the config (command, cwd, env, envFile, readyPattern, etc.).` },
+    "conditional-processes": { title: "Conditional processes", body: `Use \`condition\` to run a process only when an environment variable is set:
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    seed: {
+      command: 'bun run seed',
+      condition: 'SEED_DB',    // only runs when SEED_DB is set and truthy
+    },
+    storybook: {
+      command: 'bun run storybook',
+      condition: '!CI',         // skipped in CI environments
+    },
+  },
+})
+\`\`\`
+
+Falsy values: unset, empty string, \`"0"\`, \`"false"\`, \`"no"\`, \`"off"\` (case-insensitive). If a conditional process is skipped, its dependents are also skipped.` },
+    "optional-processes": { title: "Optional processes", body: `Use \`optional\` for tools you want visible in tabs but not auto-started (e.g. Prisma Studio, debug servers):
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    app: { command: 'bun run dev' },
+    studio: {
+      command: 'bunx prisma studio',
+      optional: true,  // shows as stopped tab, start with Alt+S
+    },
+  },
+})
+\`\`\`
+
+Unlike \`condition\`, optional processes don't cascade \u2014 their dependents still start normally.` },
+    "dependency-orchestration": { title: "Dependency orchestration", body: `Each process starts as soon as its declared \`dependsOn\` dependencies are ready \u2014 it does not wait for unrelated processes. If a process fails, its dependents are skipped.
+
+A process becomes **ready** when:
+- **Has \`readyPattern\`** \u2014 the pattern matches in stdout (long-running server)
+- **No \`readyPattern\`** \u2014 exits with code 0 (one-shot task)
+
+Processes that crash (non-zero exit) can be auto-restarted by setting \`maxRestarts\` (default: \`0\`). Restarts use exponential backoff (1s\u201330s), which resets after 10s of uptime.` },
+    "dependency-output-capture": { title: "Dependency output capture", body: `When \`readyPattern\` is a \`RegExp\` (not a string), capture groups are extracted on match and expanded into dependent process \`command\` and \`env\` values using \`$process.group\` syntax:
+
+\`\`\`ts
+export default defineConfig({
+  processes: {
+    db: {
+      command: 'docker compose up postgres',
+      readyPattern: /ready to accept connections on port (?<port>\\d+)/,
+    },
+    api: {
+      command: 'node server.js --db-port $db.port',
+      dependsOn: ['db'],
+      env: { DB_PORT: '$db.port' },
+    },
+  },
+})
+\`\`\`
+
+Both named (\`$db.port\`) and positional (\`$db.1\`) references work. Named groups also populate positional slots, so \`$db.port\` and \`$db.1\` both resolve to the same value above.
+
+Unmatched references are left as-is (the shell will expand \`$db\` as empty + \`.port\` literal, making the issue visible). String \`readyPattern\` values work as before \u2014 readiness detection only, no capture extraction.` },
+    keybindings: { title: "Keybindings", body: `Keybindings are shown in the status bar at the bottom of the app. Panes are readonly by default \u2014 keyboard input is not forwarded to processes. Set \`interactive: true\` on processes that need stdin (REPLs, shells, etc.).
+
+<!-- generated:keybindings -->
+| Key | Action |
+|-----|--------|
+| \`\u2190\`/\`\u2192\` or \`1\`-\`9\` | Tabs |
+| \`G/Shift+G\` | Top/bottom |
+| \`R\` | Restart |
+| \`S\` | Stop/start |
+| \`F\` | Search |
+| \`Y\` | Copy all |
+| \`L\` | Clear |
+| \`T\` | Timestamps |
+| \`O\` | Open logs |
+| \`Ctrl+Click\` | Open link |
+| \`Ctrl+C\` | Quit |
+<!-- /generated:keybindings -->
+
+Search mode (after pressing \`F\`):
+
+| Key | Action |
+|-----|--------|
+| \`Tab\` | Toggle between single-pane and all-process search |
+| \`Enter\`/\`Shift+Enter\` | Next/previous match |
+| \`Esc\` | Exit search |
+| \`PageUp\`/\`PageDown\` | Scroll by page |` },
+    "tab-icons": { title: "Tab icons", body: `<!-- generated:tab-icons -->
+| Icon | Status |
+|------|--------|
+| \u25CB | Pending |
+| \u25D0 | Starting |
+| \u25C9 | Running |
+| \u25CF | Ready |
+| \u25D1 | Stopping |
+| \u25A0 | Stopped |
+| \u2713 | Finished |
+| \u2716 | Failed |
+| \u2298 | Skipped |
+<!-- /generated:tab-icons -->` },
+    "ghostty-opentui": { title: "ghostty-opentui", body: `Despite the name, [\`ghostty-opentui\`](https://github.com/remorses/ghostty-opentui) is **not** a compatibility layer for the [Ghostty](https://ghostty.org) terminal. It uses Ghostty's Zig-based VT parser as the ANSI terminal emulation engine for OpenTUI's terminal renderable. It works in any terminal emulator (iTerm, Kitty, Alacritty, WezTerm, etc.) and adds ~8MB to install size due to native binaries.` },
+    license: { title: "License", body: `MIT` }
+  };
+});
+
+// src/help.ts
+var exports_help = {};
+__export(exports_help, {
+  showHelp: () => showHelp
+});
+function stripMarkdown(md) {
+  return md.replace(/<!--[\s\S]*?-->/g, "").replace(/\*\*(.+?)\*\*/g, "$1").replace(/\*(.+?)\*/g, "$1").replace(/`([^`]+)`/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\n{3,}/g, `
+
+`).trim();
+}
+function showHelp(topic) {
+  if (!topic) {
+    const entries = Object.entries(HELP_TOPICS).map(([slug, t]) => `  ${slug.padEnd(40)}${t.title}`).join(`
+`);
+    const aliases = Object.entries(TOPIC_ALIASES).map(([alias, target]) => `  ${alias} \u2192 ${target}`).join(`
+`);
+    return `Available help topics:
+
+${entries}
+
+Aliases:
+${aliases}
+
+Usage: numux help <topic>`;
+  }
+  const resolved = TOPIC_ALIASES[topic] ?? topic;
+  const entry = HELP_TOPICS[resolved];
+  if (!entry) {
+    const available = Object.keys(HELP_TOPICS).join(", ");
+    return `Unknown topic: "${topic}"
+
+Available topics: ${available}`;
+  }
+  return `${entry.title}
+${"=".repeat(entry.title.length)}
+
+${stripMarkdown(entry.body)}`;
+}
+var init_help = __esm(() => {
+  init_help_topics();
+});
+
 // package.json
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "numux",
-    version: "2.10.4",
+    version: "2.11.0",
     description: "Terminal multiplexer with dependency orchestration",
     type: "module",
     license: "MIT",
@@ -60,6 +561,7 @@ var require_package = __commonJS((exports, module) => {
     bin: {
       numux: "dist/bin.js"
     },
+    man: "dist/man/numux.1",
     exports: {
       ".": {
         types: "./dist/config.d.ts",
@@ -67,8 +569,9 @@ var require_package = __commonJS((exports, module) => {
       }
     },
     scripts: {
+      docs: "bun scripts/generate-docs.ts",
       build: "bun run build.ts",
-      prepublishOnly: "bun run build",
+      prepublishOnly: "bun run docs && bun run build",
       dev: "cd example && bun run dev --debug",
       test: "bun test",
       typecheck: "bunx tsc --noEmit",
@@ -87,7 +590,8 @@ var require_package = __commonJS((exports, module) => {
       "@biomejs/biome": "^2.4.4",
       "@commitlint/cli": "^20.4.2",
       "@commitlint/config-conventional": "^20.4.2",
-      "@types/bun": "^1.3.9"
+      "@types/bun": "^1.3.9",
+      "marked-man": "^2.1.0"
     },
     patchedDependencies: {
       "ghostty-opentui@1.4.7": "patches/ghostty-opentui@1.4.7.patch"
@@ -99,6 +603,122 @@ var require_package = __commonJS((exports, module) => {
 import { existsSync as existsSync6, writeFileSync } from "fs";
 import { resolve as resolve8 } from "path";
 
+// src/config/loader.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// src/utils/logger.ts
+import { appendFileSync, existsSync, mkdirSync } from "fs";
+import { resolve } from "path";
+var enabled = false;
+var logFile = "";
+var debugCallback = null;
+function enableDebugLog(dir) {
+  const logDir = dir ?? resolve(process.cwd(), ".numux");
+  logFile = resolve(logDir, "debug.log");
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+  }
+  enabled = true;
+}
+function log(...args) {
+  if (!enabled)
+    return;
+  try {
+    const timestamp = new Date().toISOString();
+    const formatted = args.length > 0 ? `${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}` : "";
+    const line = `[${timestamp}] ${formatted}`;
+    appendFileSync(logFile, `${line}
+`);
+    debugCallback?.(line);
+  } catch {
+    enabled = false;
+  }
+}
+
+// src/config/interpolate.ts
+var VAR_RE = /\$\{([^}:]+)(?::([-?])([^}]*))?\}/g;
+function interpolateConfig(config) {
+  return interpolateValue(config);
+}
+function interpolateValue(value) {
+  if (typeof value === "string") {
+    return interpolateString(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(interpolateValue);
+  }
+  if (value instanceof RegExp) {
+    return value;
+  }
+  if (value && typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = interpolateValue(v);
+    }
+    return result;
+  }
+  return value;
+}
+function interpolateString(str) {
+  return str.replace(VAR_RE, (_match, name, operator, operand) => {
+    const value = process.env[name];
+    if (value !== undefined && value !== "") {
+      return value;
+    }
+    if (operator === "-") {
+      return operand ?? "";
+    }
+    if (operator === "?") {
+      throw new Error(operand || `Required variable ${name} is not set`);
+    }
+    return "";
+  });
+}
+
+// src/config/loader.ts
+var CONFIG_FILES = ["numux.config.ts", "numux.config.js"];
+async function loadConfig(configPath, cwd) {
+  if (configPath) {
+    return loadExplicitConfig(configPath);
+  }
+  return autoDetectConfig(cwd ?? process.cwd());
+}
+async function loadFile(path) {
+  try {
+    const mod = await import(path);
+    return interpolateConfig(mod.default ?? mod);
+  } catch (err) {
+    throw new Error(`Failed to load ${path}: ${err instanceof Error ? err.message : err}`, { cause: err });
+  }
+}
+async function loadExplicitConfig(configPath) {
+  const path = resolve2(configPath);
+  if (!existsSync2(path)) {
+    throw new Error(`Config file not found: ${path}`);
+  }
+  log(`Loading explicit config: ${path}`);
+  return loadFile(path);
+}
+async function autoDetectConfig(cwd) {
+  for (const file of CONFIG_FILES) {
+    const path = resolve2(cwd, file);
+    if (existsSync2(path)) {
+      log(`Found config file: ${path}`);
+      return loadFile(path);
+    }
+  }
+  const pkgPath = resolve2(cwd, "package.json");
+  if (existsSync2(pkgPath)) {
+    const pkgJson = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    if (pkgJson.numux && typeof pkgJson.numux === "object") {
+      log(`Found numux config in package.json`);
+      return interpolateConfig(pkgJson.numux);
+    }
+  }
+  throw new Error(`No numux config found. Create one of: ${CONFIG_FILES.join(", ")}, or add a "numux" key to package.json`);
+}
+
 // src/cli-flags.ts
 var commaSplit = (raw) => raw.split(",").map((s) => s.trim()).filter(Boolean);
 var FLAGS = [
@@ -326,6 +946,20 @@ var SUBCOMMANDS = [
       result.completions = next;
       return i;
     }
+  },
+  {
+    name: "help",
+    description: "Show help for a topic",
+    usage: "help [topic]",
+    parse: (args, i, result) => {
+      result.help = true;
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        result.helpTopic = next;
+        i++;
+      }
+      return i;
+    }
   }
 ];
 function generateHelp() {
@@ -355,7 +989,7 @@ function generateHelp() {
     const left = `  ${parts.join(" ")}`;
     lines.push(`${left.padEnd(29)}${f.description}`);
   }
-  lines.push("", "Config files (auto-detected):", "  numux.config.ts, numux.config.js");
+  lines.push("", "Config files (auto-detected):", `  ${CONFIG_FILES.join(", ")}, or "numux" key in package.json`);
   return lines.join(`
 `);
 }
@@ -514,7 +1148,9 @@ function filterConfig(config, only, exclude) {
 }
 
 // src/completions.ts
+init_help_topics();
 var SUPPORTED_SHELLS = ["bash", "zsh", "fish"];
+var HELP_TOPIC_NAMES = [...Object.keys(HELP_TOPICS), ...Object.keys(TOPIC_ALIASES)];
 function generateCompletions(shell) {
   switch (shell) {
     case "bash":
@@ -555,6 +1191,9 @@ function bashCompletions() {
   caseEntries.push(`    completions)
       COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
       return ;;`);
+  caseEntries.push(`    help)
+      COMPREPLY=( $(compgen -W "${HELP_TOPIC_NAMES.join(" ")}" -- "$cur") )
+      return ;;`);
   const allFlags = FLAGS.flatMap((f) => f.short ? [f.short, f.long] : [f.long]);
   const subcmds = SUBCOMMANDS.map((s) => s.name);
   return `# numux bash completions
@@ -634,6 +1273,17 @@ ${argsBlock}
       _describe 'subcommand' subcmds
       ;;
   esac
+
+  case "\${words[2]}" in
+    help)
+      local -a topics
+      topics=(${HELP_TOPIC_NAMES.map((t) => `'${t}'`).join(" ")})
+      _describe 'topic' topics
+      ;;
+    completions)
+      _values 'shell' bash zsh fish
+      ;;
+  esac
 }
 _numux`;
 }
@@ -649,7 +1299,7 @@ function fishCompletions() {
   for (const s of SUBCOMMANDS) {
     lines.push(`complete -c numux -n __fish_use_subcommand -a ${s.name} -d '${sq(s.description)}'`);
   }
-  lines.push("", "# Completions subcommand", "complete -c numux -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'", "", "# Options");
+  lines.push("", "# Completions subcommand", "complete -c numux -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'", "", "# Help subcommand", `complete -c numux -n '__fish_seen_subcommand_from help' -a '${HELP_TOPIC_NAMES.join(" ")}'`, "", "# Options");
   for (const f of FLAGS) {
     const parts = ["complete -c numux"];
     if (f.short)
@@ -672,8 +1322,8 @@ function fishCompletions() {
 }
 
 // src/config/expand-scripts.ts
-import { existsSync, readFileSync } from "fs";
-import { resolve } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve3 } from "path";
 var LOCKFILE_PM = [
   ["bun.lockb", "bun"],
   ["bun.lock", "bun"],
@@ -689,7 +1339,7 @@ function detectPackageManager(pkgJson, cwd) {
       return name;
   }
   for (const [file, pm] of LOCKFILE_PM) {
-    if (existsSync(resolve(cwd, file)))
+    if (existsSync3(resolve3(cwd, file)))
       return pm;
   }
   return "npm";
@@ -757,11 +1407,11 @@ function expandScriptPatterns(config, cwd) {
   if (!(hasScriptRef || hasNpmCommand || hasCommandlessEntry))
     return config;
   const dir = config.cwd ?? cwd ?? process.cwd();
-  const pkgPath = resolve(dir, "package.json");
-  if (!existsSync(pkgPath) && hasScriptRef) {
+  const pkgPath = resolve3(dir, "package.json");
+  if (!existsSync3(pkgPath) && hasScriptRef) {
     throw new Error(`Wildcard patterns require a package.json (looked in ${dir})`);
   }
-  const pkgJson = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, "utf-8")) : {};
+  const pkgJson = existsSync3(pkgPath) ? JSON.parse(readFileSync2(pkgPath, "utf-8")) : {};
   const scripts = pkgJson.scripts;
   const scriptNames = scripts && typeof scripts === "object" ? Object.keys(scripts) : [];
   const pm = detectPackageManager(pkgJson, dir);
@@ -820,122 +1470,6 @@ function expandScriptPatterns(config, cwd) {
   return { ...config, processes: expanded };
 }
 
-// src/config/loader.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
-import { resolve as resolve3 } from "path";
-
-// src/utils/logger.ts
-import { appendFileSync, existsSync as existsSync2, mkdirSync } from "fs";
-import { resolve as resolve2 } from "path";
-var enabled = false;
-var logFile = "";
-var debugCallback = null;
-function enableDebugLog(dir) {
-  const logDir = dir ?? resolve2(process.cwd(), ".numux");
-  logFile = resolve2(logDir, "debug.log");
-  if (!existsSync2(logDir)) {
-    mkdirSync(logDir, { recursive: true });
-  }
-  enabled = true;
-}
-function log(...args) {
-  if (!enabled)
-    return;
-  try {
-    const timestamp = new Date().toISOString();
-    const formatted = args.length > 0 ? `${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}` : "";
-    const line = `[${timestamp}] ${formatted}`;
-    appendFileSync(logFile, `${line}
-`);
-    debugCallback?.(line);
-  } catch {
-    enabled = false;
-  }
-}
-
-// src/config/interpolate.ts
-var VAR_RE = /\$\{([^}:]+)(?::([-?])([^}]*))?\}/g;
-function interpolateConfig(config) {
-  return interpolateValue(config);
-}
-function interpolateValue(value) {
-  if (typeof value === "string") {
-    return interpolateString(value);
-  }
-  if (Array.isArray(value)) {
-    return value.map(interpolateValue);
-  }
-  if (value instanceof RegExp) {
-    return value;
-  }
-  if (value && typeof value === "object") {
-    const result = {};
-    for (const [k, v] of Object.entries(value)) {
-      result[k] = interpolateValue(v);
-    }
-    return result;
-  }
-  return value;
-}
-function interpolateString(str) {
-  return str.replace(VAR_RE, (_match, name, operator, operand) => {
-    const value = process.env[name];
-    if (value !== undefined && value !== "") {
-      return value;
-    }
-    if (operator === "-") {
-      return operand ?? "";
-    }
-    if (operator === "?") {
-      throw new Error(operand || `Required variable ${name} is not set`);
-    }
-    return "";
-  });
-}
-
-// src/config/loader.ts
-var CONFIG_FILES = ["numux.config.ts", "numux.config.js"];
-async function loadConfig(configPath, cwd) {
-  if (configPath) {
-    return loadExplicitConfig(configPath);
-  }
-  return autoDetectConfig(cwd ?? process.cwd());
-}
-async function loadFile(path) {
-  try {
-    const mod = await import(path);
-    return interpolateConfig(mod.default ?? mod);
-  } catch (err) {
-    throw new Error(`Failed to load ${path}: ${err instanceof Error ? err.message : err}`, { cause: err });
-  }
-}
-async function loadExplicitConfig(configPath) {
-  const path = resolve3(configPath);
-  if (!existsSync3(path)) {
-    throw new Error(`Config file not found: ${path}`);
-  }
-  log(`Loading explicit config: ${path}`);
-  return loadFile(path);
-}
-async function autoDetectConfig(cwd) {
-  for (const file of CONFIG_FILES) {
-    const path = resolve3(cwd, file);
-    if (existsSync3(path)) {
-      log(`Found config file: ${path}`);
-      return loadFile(path);
-    }
-  }
-  const pkgPath = resolve3(cwd, "package.json");
-  if (existsSync3(pkgPath)) {
-    const pkgJson = JSON.parse(readFileSync2(pkgPath, "utf-8"));
-    if (pkgJson.numux && typeof pkgJson.numux === "object") {
-      log(`Found numux config in package.json`);
-      return interpolateConfig(pkgJson.numux);
-    }
-  }
-  throw new Error(`No numux config found. Create one of: ${CONFIG_FILES.join(", ")}, or add a "numux" key to package.json`);
-}
-
 // src/config/platform.ts
 function filterByPlatform(config, currentPlatform = process.platform) {
   const excluded = new Set;
@@ -4392,7 +4926,12 @@ export default defineConfig({
 async function main() {
   const parsed = parseArgs(process.argv);
   if (parsed.help) {
-    console.info(HELP);
+    if (parsed.helpTopic) {
+      const { showHelp: showHelp2 } = await Promise.resolve().then(() => (init_help(), exports_help));
+      console.info(showHelp2(parsed.helpTopic));
+    } else {
+      console.info(HELP);
+    }
     process.exit(0);
   }
   if (parsed.version) {