@pellux/goodvibes-tui 0.19.25 → 0.19.27

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.19.27] — 2026-04-24
+
+### Changes
+- ac02372 chore: update goodvibes sdk to 0.25.1
+
+## [0.19.26] — 2026-04-24
+
+### Changes
+- f1e0ac3 feat: harden CLI operations and support bundles
+- 0c94095 feat: enforce readiness command exit codes
+- 566bc34 feat: improve CLI help and listener readiness
+- d620637 feat: harden CLI diagnostics and provider posture
+
 ## [0.19.25] — 2026-04-24
 
 ### Changes

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.19.25-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.19.27-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
 A terminal-native AI coding, operations, automation, knowledge, and integration console with a typed runtime, omnichannel surfaces, structured memory/knowledge, and a raw ANSI renderer.
 

package/bin/goodvibes

@@ -39,9 +39,14 @@ function run(command, args) {
 }
 
 const artifactName = resolveArtifactName(process.platform, process.arch);
+const localPlatformBuild = artifactName ? join(packageRoot, 'dist', artifactName) : null;
 const localBuild = join(packageRoot, 'dist', 'goodvibes');
 const vendoredBinary = artifactName ? join(packageRoot, 'vendor', artifactName) : null;
 
+if (localPlatformBuild && isExecutable(localPlatformBuild)) {
+  run(localPlatformBuild, process.argv.slice(2));
+}
+
 if (isExecutable(localBuild)) {
   run(localBuild, process.argv.slice(2));
 }

package/bin/goodvibes-daemon

@@ -39,9 +39,14 @@ function run(command, args) {
 }
 
 const artifactName = resolveArtifactName(process.platform, process.arch);
+const localPlatformBuild = artifactName ? join(packageRoot, 'dist', artifactName) : null;
 const localBuild = join(packageRoot, 'dist', 'goodvibes-daemon');
 const vendoredBinary = artifactName ? join(packageRoot, 'vendor', artifactName) : null;
 
+if (localPlatformBuild && isExecutable(localPlatformBuild)) {
+  run(localPlatformBuild, process.argv.slice(2));
+}
+
 if (isExecutable(localBuild)) {
   run(localBuild, process.argv.slice(2));
 }

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "0.25.0"
+    "version": "0.25.1"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.19.25",
+  "version": "0.19.27",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -49,6 +49,7 @@
     "publish:dry-run": "bun run scripts/publish-package.ts --dry-run",
     "publish:dry-run:github": "GOODVIBES_PUBLIC_PACKAGE_NAME=@mgd34msu/goodvibes-tui GOODVIBES_PUBLISH_REGISTRY=https://npm.pkg.github.com bun run scripts/publish-package.ts --dry-run",
     "publish:check": "bun run scripts/publish-check.ts",
+    "package:install-check": "bun run scripts/package-install-check.ts",
     "build:prod": "bun run scripts/build.ts",
     "build:all": "bun run scripts/build.ts --all",
     "perf:check": "bun run scripts/perf-check.ts",
@@ -90,7 +91,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "^0.25.0",
+    "@pellux/goodvibes-sdk": "^0.25.1",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/cli/bundle-command.ts

@@ -0,0 +1,225 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { RuntimeEventBus } from '@pellux/goodvibes-sdk/platform/runtime/events/index';
+import { createShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
+import { listProviderRuntimeSnapshots } from '@pellux/goodvibes-sdk/platform/providers/runtime-snapshot';
+import { createRuntimeServices } from '../runtime/services.ts';
+import { createRuntimeStore } from '../runtime/store/index.ts';
+import { CONFIG_SCHEMA } from '../config/index.ts';
+import { SecretsManager } from '../config/secrets.ts';
+import type { ConfigKey } from '../config/index.ts';
+import type { CliCommandRuntime } from './management.ts';
+import type { CliCommandOutput } from './types.ts';
+import { getPackageVersion } from './help.ts';
+import { classifyProviderSetup } from './provider-classification.ts';
+import { buildCliServicePosture } from './service-posture.ts';
+import { REDACTED_VALUE, collectSensitiveConfigValues, isRedactedValue, redactConfig, redactSerializedSecrets } from './redaction.ts';
+
+interface BundleInspectSummary {
+  readonly type: string;
+  readonly version: string;
+  readonly path: string;
+  readonly capturedAt: number | null;
+  readonly configKeys: number;
+  readonly redactedConfigPaths: readonly string[];
+  readonly hasDiagnostics: boolean;
+}
+
+function formatJsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+function getNestedValue(source: unknown, key: string): unknown {
+  let cursor = source;
+  for (const part of key.split('.')) {
+    if (cursor == null || typeof cursor !== 'object') return undefined;
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return cursor;
+}
+
+function readJsonFile(path: string): { readonly ok: true; readonly value: Record<string, unknown> } | { readonly ok: false; readonly error: string } {
+  try {
+    return { ok: true, value: JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown> };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function inspectBundle(path: string, parsed: Record<string, unknown>): BundleInspectSummary {
+  return {
+    type: String(parsed['type'] ?? 'unknown'),
+    version: String(parsed['version'] ?? 'unknown'),
+    path,
+    capturedAt: typeof parsed['capturedAt'] === 'number' ? parsed['capturedAt'] : null,
+    configKeys: parsed['config'] && typeof parsed['config'] === 'object'
+      ? CONFIG_SCHEMA.filter((setting) => getNestedValue(parsed['config'], setting.key) !== undefined).length
+      : 0,
+    redactedConfigPaths: Array.isArray((parsed['redaction'] as { redactedConfigPaths?: unknown } | undefined)?.redactedConfigPaths)
+      ? (parsed['redaction'] as { redactedConfigPaths: string[] }).redactedConfigPaths
+      : [],
+    hasDiagnostics: Boolean(parsed['diagnostics'] && typeof parsed['diagnostics'] === 'object'),
+  };
+}
+
+function readAuthPosture(runtime: CliCommandRuntime) {
+  const shellPaths = createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+  const userStorePath = shellPaths.resolveUserPath('tui', 'auth-users.json');
+  const bootstrapCredentialPath = shellPaths.resolveUserPath('tui', 'auth-bootstrap.txt');
+  const operatorTokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
+  return {
+    userStorePath,
+    userStorePresent: existsSync(userStorePath),
+    bootstrapCredentialPath,
+    bootstrapCredentialPresent: existsSync(bootstrapCredentialPath),
+    operatorTokenPath,
+    operatorTokenPresent: existsSync(operatorTokenPath),
+  };
+}
+
+async function buildProviderReadiness(runtime: CliCommandRuntime) {
+  const runtimeBus = new RuntimeEventBus();
+  const runtimeStore = createRuntimeStore();
+  const services = createRuntimeServices({
+    configManager: runtime.configManager,
+    runtimeBus,
+    runtimeStore,
+    workingDir: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+  services.providerRegistry.initModelLimits();
+  services.benchmarkStore.initBenchmarks();
+  services.providerRegistry.initCatalog();
+  try {
+    await services.providerRegistry.ready();
+    const snapshots = await listProviderRuntimeSnapshots(services.providerRegistry);
+    return snapshots.map((snapshot) => ({
+      provider: snapshot.providerId,
+      active: snapshot.active,
+      configured: snapshot.runtime.auth?.configured ?? true,
+      configuredVia: snapshot.runtime.auth?.mode ?? 'unknown',
+      models: snapshot.modelCount,
+      setup: classifyProviderSetup({
+        providerId: snapshot.providerId,
+        authMode: snapshot.runtime.auth?.mode,
+        configured: snapshot.runtime.auth?.configured ?? true,
+        modelCount: snapshot.modelCount,
+      }),
+    }));
+  } finally {
+    services.providerRegistry.stopWatching();
+  }
+}
+
+export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const [sub = 'inspect', ...rest] = runtime.cli.commandArgs;
+  const shellPaths = createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+
+  if (sub === 'inspect') {
+    const path = rest[0];
+    if (!path) return { output: 'Usage: goodvibes bundle inspect <path>', exitCode: 2 };
+    const sourcePath = shellPaths.resolveWorkspacePath(path);
+    const parsed = readJsonFile(sourcePath);
+    if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
+    const summary = inspectBundle(sourcePath, parsed.value);
+    return {
+      output: formatJsonOrText(runtime, summary, [
+        'GoodVibes bundle',
+        `  type: ${summary.type}`,
+        `  version: ${summary.version}`,
+        `  path: ${summary.path}`,
+        `  capturedAt: ${summary.capturedAt === null ? 'n/a' : new Date(summary.capturedAt).toISOString()}`,
+        `  configKeys: ${summary.configKeys}`,
+        `  redactedConfigKeys: ${summary.redactedConfigPaths.length}`,
+        `  diagnostics: ${summary.hasDiagnostics ? 'present' : 'missing'}`,
+      ].join('\n')),
+      exitCode: 0,
+    };
+  }
+
+  if (sub === 'export') {
+    const outputPath = rest[0] ?? 'goodvibes-bundle.json';
+    const secrets = new SecretsManager({
+      projectRoot: runtime.workingDirectory,
+      globalHome: runtime.homeDirectory,
+      configManager: runtime.configManager,
+    });
+    const rawConfig = runtime.configManager.getRaw();
+    const sensitiveValues = collectSensitiveConfigValues(rawConfig);
+    const redactedConfig = redactConfig(rawConfig);
+    const service = await buildCliServicePosture(runtime, { logTailBytes: 8192 });
+    const bundle = {
+      version: 2,
+      type: 'goodvibes.support',
+      capturedAt: Date.now(),
+      package: {
+        name: '@pellux/goodvibes-tui',
+        version: getPackageVersion(),
+      },
+      roots: {
+        workingDirectory: runtime.workingDirectory,
+        homeDirectory: runtime.homeDirectory,
+      },
+      config: redactedConfig.value,
+      redaction: {
+        sentinel: REDACTED_VALUE,
+        redactedConfigPaths: redactedConfig.redactedPaths,
+      },
+      diagnostics: {
+        service,
+        auth: readAuthPosture(runtime),
+        providers: await buildProviderReadiness(runtime),
+      },
+      secrets: await secrets.inspect(),
+      onboarding: {
+        projectMarker: existsSync(shellPaths.resolveProjectPath('tui', 'onboarding.json')),
+        userMarker: existsSync(shellPaths.resolveUserPath('tui', 'onboarding.json')),
+      },
+    };
+    const targetPath = shellPaths.resolveWorkspacePath(outputPath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, redactSerializedSecrets(JSON.stringify(bundle, null, 2), sensitiveValues) + '\n', 'utf-8');
+    return {
+      output: formatJsonOrText(runtime, {
+        path: targetPath,
+        redactedConfigPaths: redactedConfig.redactedPaths,
+        serviceIssues: service.issues,
+      }, `Bundle exported: ${targetPath}\n  redactedConfigKeys: ${redactedConfig.redactedPaths.length}\n  serviceIssues: ${service.issues.length}`),
+      exitCode: 0,
+    };
+  }
+
+  if (sub === 'import') {
+    const path = rest[0];
+    if (!path) return { output: 'Usage: goodvibes bundle import <path>', exitCode: 2 };
+    const sourcePath = shellPaths.resolveWorkspacePath(path);
+    const parsed = readJsonFile(sourcePath);
+    if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
+    const config = parsed.value['config'];
+    if (!config || typeof config !== 'object') return { output: 'Bundle has no config object to import.', exitCode: 1 };
+    let count = 0;
+    let skippedRedacted = 0;
+    for (const setting of CONFIG_SCHEMA) {
+      const value = getNestedValue(config, setting.key);
+      if (value === undefined) continue;
+      if (isRedactedValue(value)) {
+        skippedRedacted++;
+        continue;
+      }
+      runtime.configManager.setDynamic(setting.key as ConfigKey, value as never);
+      count++;
+    }
+    return {
+      output: `Bundle imported: ${count} config value${count === 1 ? '' : 's'} applied.${skippedRedacted ? ` ${skippedRedacted} redacted value${skippedRedacted === 1 ? '' : 's'} skipped.` : ''}`,
+      exitCode: 0,
+    };
+  }
+
+  return { output: 'Usage: goodvibes bundle export [path]|inspect <path>|import <path>', exitCode: 2 };
+}

package/src/cli/completion.ts

@@ -4,6 +4,7 @@ const COMMANDS = [
   'exec',
   'serve',
   'web',
+  'service',
   'onboarding',
   'setup',
   'doctor',

package/src/cli/entrypoint.ts

@@ -10,14 +10,17 @@ import {
   applyRuntimeConfigOverrides,
   applyRuntimeConfigValue,
   applyRuntimeFeatureFlagOverrides,
+  buildCliStatusSnapshot,
   handleGoodVibesCliCommand,
   parseGoodVibesCli,
   renderCliStatus,
   renderCompletion,
+  renderGoodVibesCommandHelp,
   renderGoodVibesHelp,
   renderGoodVibesVersion,
   renderOnboardingCliStatus,
 } from './index.ts';
+import { buildCliServicePosture } from './service-posture.ts';
 
 type ShellEntrypointOwnership = {
   readonly workingDirectory: string;
@@ -58,7 +61,10 @@ export async function prepareShellCliRuntime(
   }
 
   if (cli.flags.help || cli.command === 'help') {
-    console.log(renderGoodVibesHelp(binary));
+    const helpTopic = cli.command === 'help'
+      ? cli.commandArgs[0]
+      : cli.rawCommand ?? undefined;
+    console.log(helpTopic ? renderGoodVibesCommandHelp(helpTopic, binary) : renderGoodVibesHelp(binary));
     process.exit(0);
   }
 
@@ -120,6 +126,11 @@ export async function prepareShellCliRuntime(
     const bootstrapCredentialPath = shellPaths.resolveUserPath('tui', 'auth-bootstrap.txt');
     const operatorTokenPath = join(bootstrapHomeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
     const onboardingMarkers = readOnboardingCompletionMarkers(shellPaths);
+    const service = await buildCliServicePosture({
+      configManager,
+      workingDirectory: bootstrapWorkingDir,
+      homeDirectory: bootstrapHomeDirectory,
+    });
     const statusOptions = {
       configManager,
       workingDirectory: bootstrapWorkingDir,
@@ -133,12 +144,15 @@ export async function prepareShellCliRuntime(
         operatorTokenPath,
         operatorTokenPresent: existsSync(operatorTokenPath),
       },
+      service,
       doctor: cli.command === 'doctor',
+      outputFormat: cli.flags.outputFormat,
     };
+    const snapshot = buildCliStatusSnapshot(statusOptions);
     console.log(cli.command === 'onboarding'
       ? renderOnboardingCliStatus(statusOptions)
       : renderCliStatus(statusOptions));
-    process.exit(0);
+    process.exit(cli.command === 'doctor' && snapshot.findings.length > 0 ? 1 : 0);
   }
 
   const cliCommandResult = await handleGoodVibesCliCommand({

package/src/cli/help.ts

@@ -35,6 +35,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes'): string {
     '  run|exec [prompt]          Run non-interactively with text/json/stream-json output',
     '  serve|daemon               Start the daemon/API host',
     '  web                        Show browser surface bind URL and enablement',
+    '  service                    Inspect/manage daemon service lifecycle',
     '  status                     Print config, provider, service, and onboarding posture',
     '  doctor                     Print status plus setup warnings',
     '  onboarding [status]        Open onboarding in the TUI, or print onboarding status',
@@ -53,7 +54,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes'): string {
     '                             Move setup/profile/trust/support bundles',
     '  remote|bridge              Inspect remote runner/node posture',
     '  completion <shell>         Generate shell completion script',
-    '  help                       Print this help',
+    '  help [command]             Print this help or command-specific help',
     '  version                    Print version',
     '',
     'Options:',
@@ -94,6 +95,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes'): string {
     `  ${binary} surfaces`,
     `  ${binary} surfaces check`,
     `  ${binary} surfaces enable web`,
+    `  ${binary} service check`,
     `  ${binary} listener test`,
     `  ${binary} control-plane status`,
     `  ${binary} subscription providers`,
@@ -102,6 +104,183 @@ export function renderGoodVibesHelp(binary = 'goodvibes'): string {
   ].join('\n');
 }
 
+type CommandHelp = {
+  readonly usage: readonly string[];
+  readonly summary: string;
+  readonly subcommands?: readonly string[];
+  readonly examples?: readonly string[];
+};
+
+const COMMAND_HELP: Record<string, CommandHelp> = {
+  tui: {
+    usage: ['tui [path]', '[prompt]'],
+    summary: 'Start the interactive terminal UI. A prompt starts the TUI with that prompt seeded.',
+    examples: ['', 'tui ~/work/project', '"review this repo"'],
+  },
+  run: {
+    usage: ['run [prompt] [--output text|json|stream-json]', 'exec [prompt]'],
+    summary: 'Run a single non-interactive agent turn and write the result to stdout.',
+    examples: ['run "summarize the current project"', 'run --output json "list risks"', 'exec --output stream-json "fix lint"'],
+  },
+  onboarding: {
+    usage: ['onboarding', 'setup', 'onboarding status'],
+    summary: 'Open the setup wizard on the next TUI startup, or inspect onboarding marker status from the CLI.',
+    examples: ['onboarding', 'onboarding status'],
+  },
+  status: {
+    usage: ['status', 'status --json'],
+    summary: 'Print config, provider, auth, service, surface, and onboarding posture.',
+    examples: ['status', 'status --json'],
+  },
+  doctor: {
+    usage: ['doctor', 'doctor --json'],
+    summary: 'Print status plus actionable setup warnings with cause, impact, and next action.',
+    examples: ['doctor', 'doctor --json'],
+  },
+  providers: {
+    usage: ['providers [list]', 'providers current', 'providers inspect <provider>', 'providers use <provider> [modelRegistryKey]'],
+    summary: 'Inspect and change provider setup, auth posture, model counts, and setup class.',
+    examples: ['providers', 'providers inspect openai-subscriber', 'providers use openai openai:gpt-5.4'],
+  },
+  models: {
+    usage: ['models [provider]', 'models current', 'models use <registryKey>', 'models pin <registryKey>', 'models recent'],
+    summary: 'List, inspect, select, pin, and review model choices.',
+    examples: ['models current', 'models openai', 'models use openai:gpt-5.4'],
+  },
+  auth: {
+    usage: ['auth status', 'auth users', 'auth sessions', 'auth add-user <username>', 'auth clear-bootstrap'],
+    summary: 'Inspect and manage local admin users, bootstrap auth, and local sessions.',
+    examples: ['auth', 'auth add-user admin --password-stdin', 'auth clear-bootstrap'],
+  },
+  subscription: {
+    usage: ['subscription list', 'subscription providers', 'subscription inspect <provider>', 'subscription login <provider> start|finish', 'subscription logout <provider>'],
+    summary: 'Manage OAuth/subscription-backed provider sessions such as OpenAI subscription access.',
+    examples: ['subscription providers', 'subscription login openai start --open', 'subscription inspect openai'],
+  },
+  secrets: {
+    usage: ['secrets list', 'secrets providers', 'secrets test goodvibes://secrets/<source>/...', 'secrets set <KEY> <value>', 'secrets link <KEY> <ref>'],
+    summary: 'Manage GoodVibes secret records and secret references. Secret refs never embed secret values.',
+    examples: ['secrets providers', 'secrets test goodvibes://secrets/env/OPENAI_API_KEY', 'secrets link OPENAI_API_KEY goodvibes://secrets/env/OPENAI_API_KEY'],
+  },
+  sessions: {
+    usage: ['sessions list', 'sessions show <id|name>', 'sessions export <id|name> [path]', 'sessions resume <id|name>'],
+    summary: 'List, inspect, export, or resume saved TUI sessions.',
+    examples: ['sessions list', 'sessions show latest-session', 'sessions export abc123 session.json'],
+  },
+  tasks: {
+    usage: ['tasks list', 'tasks show <taskId>', 'tasks submit <prompt>'],
+    summary: 'Inspect runtime tasks or submit a non-interactive task.',
+    examples: ['tasks list', 'tasks submit "check provider readiness"'],
+  },
+  surfaces: {
+    usage: ['surfaces [list]', 'surfaces check', 'surfaces show <surfaceId>', 'surfaces enable <web|listener|control-plane|surfaceId>', 'surfaces disable <surfaceId>'],
+    summary: 'Inspect and configure browser, control-plane, HTTP listener, and external integration surfaces.',
+    examples: ['surfaces check', 'surfaces enable web', 'surfaces enable slack'],
+  },
+  listener: {
+    usage: ['listener test'],
+    summary: 'Check HTTP listener/webhook readiness, network posture, service posture, auth, and enabled surface requirements.',
+    examples: ['listener test', 'listener test --json'],
+  },
+  'control-plane': {
+    usage: ['control-plane status'],
+    summary: 'Inspect daemon control-plane bind posture, reachability, local auth, bootstrap credentials, and operator tokens.',
+    examples: ['control-plane status', 'control-plane status --json'],
+  },
+  bundle: {
+    usage: ['bundle export [path]', 'bundle inspect <path>', 'bundle import <path>'],
+    summary: 'Export, inspect, or import setup/profile/trust/support bundle data.',
+    examples: ['bundle export goodvibes-bundle.json', 'bundle inspect goodvibes-bundle.json'],
+  },
+  pair: {
+    usage: ['pair', 'qrcode'],
+    summary: 'Print companion pairing connection details and a QR code.',
+    examples: ['pair', 'qrcode'],
+  },
+  web: {
+    usage: ['web [--open]'],
+    summary: 'Show the configured browser surface URL, bind address, and enablement state.',
+    examples: ['web', 'web --open', 'web --hostname 0.0.0.0 --port 3423'],
+  },
+  service: {
+    usage: ['service status', 'service check', 'service install|start|stop|restart|uninstall'],
+    summary: 'Inspect and manage the daemon service lifecycle, autostart, restart policy, PID, logs, and endpoint readiness.',
+    examples: ['service status', 'service check --json', 'service install'],
+  },
+  completion: {
+    usage: ['completion <bash|zsh|fish>'],
+    summary: 'Generate shell completion scripts.',
+    examples: ['completion bash', 'completion zsh'],
+  },
+  serve: {
+    usage: ['serve [--hostname <host>] [--port <port>]', 'daemon [--hostname <host>] [--port <port>]'],
+    summary: 'Start the headless GoodVibes daemon/API host.',
+    examples: ['serve', 'serve --hostname 0.0.0.0 --port 3421'],
+  },
+  remote: {
+    usage: ['remote', 'bridge'],
+    summary: 'Inspect remote runner/node posture and bridge readiness.',
+    examples: ['remote', 'bridge'],
+  },
+};
+
+const HELP_ALIASES: Record<string, string> = {
+  app: 'tui',
+  exec: 'run',
+  setup: 'onboarding',
+  provider: 'providers',
+  model: 'models',
+  subscriptions: 'subscription',
+  secret: 'secrets',
+  session: 'sessions',
+  task: 'tasks',
+  surface: 'surfaces',
+  webhook: 'listener',
+  controlplane: 'control-plane',
+  cp: 'control-plane',
+  qrcode: 'pair',
+  qr: 'pair',
+  daemon: 'serve',
+  server: 'serve',
+  services: 'service',
+  bridge: 'remote',
+};
+
+function normalizeHelpTopic(topic: string): string {
+  const normalized = topic.trim().toLowerCase();
+  return HELP_ALIASES[normalized] ?? normalized;
+}
+
+export function renderGoodVibesCommandHelp(topic: string, binary = 'goodvibes'): string {
+  const normalized = normalizeHelpTopic(topic);
+  const help = COMMAND_HELP[normalized];
+  if (!help) {
+    return [
+      `No detailed help is available for "${topic}".`,
+      '',
+      renderGoodVibesHelp(binary),
+    ].join('\n');
+  }
+  return [
+    `GoodVibes ${normalized}`,
+    '',
+    help.summary,
+    '',
+    'Usage:',
+    ...help.usage.map((usage) => `  ${binary} ${usage}`),
+    ...(help.subcommands && help.subcommands.length > 0 ? [
+      '',
+      'Subcommands:',
+      ...help.subcommands.map((subcommand) => `  ${subcommand}`),
+    ] : []),
+    ...(help.examples && help.examples.length > 0 ? [
+      '',
+      'Examples:',
+      ...help.examples.map((example) => `  ${binary}${example ? ` ${example}` : ''}`),
+    ] : []),
+  ].join('\n');
+}
+
 export function renderGoodVibesDaemonHelp(binary = 'goodvibes-daemon'): string {
   return [
     `Usage: ${binary} [OPTIONS]`,

package/src/cli/index.ts

@@ -5,4 +5,7 @@ export * from './status.ts';
 export * from './completion.ts';
 export * from './config-overrides.ts';
 export * from './endpoints.ts';
+export * from './surface-command.ts';
+export * from './service-command.ts';
+export * from './bundle-command.ts';
 export * from './management.ts';