@pellux/goodvibes-agent 0.1.0

package/src/input/commands/local-setup-review.ts

@@ -0,0 +1,199 @@
+import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import type { CommandContext } from '../command-registry.ts';
+import { discoverSkills } from '../../panels/skills-panel.ts';
+import { buildSandboxReview, isRunningInWsl } from '@/runtime/index.ts';
+import { getPluginDirectories } from '../../plugins/loader';
+import { listBuiltinSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config';
+import type { SetupReviewSnapshot } from './local-setup-transfer.ts';
+import { requireProviderApi, requireReadModels, requireServiceRegistry, requireShellPaths, requireSubscriptionManager } from './runtime-services.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../../config/surface.ts';
+
+export async function buildSetupReviewSnapshot(ctx: CommandContext): Promise<SetupReviewSnapshot> {
+  const shellPaths = requireShellPaths(ctx);
+  const serviceRegistry = requireServiceRegistry(ctx);
+  const services = Object.keys(serviceRegistry.getAll()).sort((a, b) => a.localeCompare(b));
+  const serviceConfigs = serviceRegistry.getAll();
+  const serviceIssues: string[] = [];
+  for (const name of services) {
+    const inspection = await serviceRegistry.inspect(name);
+    if (!inspection?.hasPrimaryCredential) {
+      serviceIssues.push(`${name}: missing primary credential`);
+    }
+  }
+
+  const skills = await discoverSkills(shellPaths);
+  const security = requireReadModels(ctx).security.getSnapshot();
+  const plugins = security.plugins;
+  const mcpServers = security.mcpServers;
+  const pluginDirectories = getPluginDirectories({
+    cwd: shellPaths.workingDirectory,
+    homeDir: shellPaths.homeDirectory,
+  });
+  const providerCount = (await requireProviderApi(ctx).listModels()).length;
+  const remoteRunnerCount = ctx.ops.remoteRuntime?.listContracts().length ?? 0;
+  const oauthProviderCount = Object.values(serviceConfigs).filter((service) => service.authType === 'oauth' && service.oauth).length;
+  const builtinSubscriptionProviderCount = listBuiltinSubscriptionProviders().length;
+  const subscriptionManager = requireSubscriptionManager(ctx);
+  const activeSubscriptionCount = subscriptionManager.list().length;
+  const pendingSubscriptionCount = subscriptionManager.listPending().length;
+  const sandboxReplIsolation = String(ctx.platform.configManager.get('sandbox.replIsolation'));
+  const sandboxMcpIsolation = String(ctx.platform.configManager.get('sandbox.mcpIsolation'));
+  const sandboxReview = buildSandboxReview(ctx.platform.configManager);
+  const sandboxSecureModeReady = sandboxReview.host.secureSandboxReady;
+  const quarantinedPluginCount = plugins.filter((plugin) => plugin.quarantined).length;
+  const quarantinedMcpCount = mcpServers.filter((server) => server.schemaFreshness === 'quarantined').length;
+  const elevatedMcpCount = mcpServers.filter((server) => server.trustMode === 'allow-all').length;
+  const hooksPath = shellPaths.resolveProjectPath('hooks.managed.json');
+  let managedHookCount = 0;
+  let managedHookChainCount = 0;
+  if (existsSync(hooksPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(hooksPath, 'utf-8')) as { hooks?: unknown[]; chains?: unknown[] };
+      managedHookCount = parsed.hooks?.length ?? 0;
+      managedHookChainCount = parsed.chains?.length ?? 0;
+    } catch {
+      // Ignore malformed hook config during snapshot collection.
+    }
+  }
+
+  const issues: SetupReviewSnapshot['issues'] = [
+    {
+      severity: providerCount > 0 ? 'pass' : 'fail',
+      area: 'providers',
+      message: providerCount > 0 ? `${providerCount} model(s) available` : 'no models available',
+    },
+    {
+      severity: (services.length === 0 && oauthProviderCount === 0 && builtinSubscriptionProviderCount === 0) ? 'warn' : serviceIssues.length === 0 ? 'pass' : 'warn',
+      area: 'services',
+      message: (services.length === 0 && oauthProviderCount === 0 && builtinSubscriptionProviderCount === 0)
+        ? 'no services configured'
+        : serviceIssues.length === 0
+          ? `${services.length} service(s), ${oauthProviderCount + builtinSubscriptionProviderCount} oauth provider(s), ${activeSubscriptionCount} active subscription override(s)`
+          : `${serviceIssues.length} service configuration issue(s)`,
+    },
+    {
+      severity: quarantinedPluginCount === 0 ? 'pass' : 'warn',
+      area: 'plugins',
+      message: quarantinedPluginCount === 0
+        ? `${plugins.length} plugin(s) discovered`
+        : `${quarantinedPluginCount} plugin(s) quarantined`,
+    },
+    {
+      severity: quarantinedMcpCount === 0 && elevatedMcpCount === 0 ? 'pass' : 'warn',
+      area: 'mcp',
+      message: quarantinedMcpCount > 0 || elevatedMcpCount > 0
+        ? `${quarantinedMcpCount} quarantined, ${elevatedMcpCount} elevated`
+        : `${mcpServers.length} server(s) known`,
+    },
+    {
+      severity: managedHookCount > 0 || managedHookChainCount > 0 ? 'pass' : 'warn',
+      area: 'hooks',
+      message: `${managedHookCount} managed hook(s), ${managedHookChainCount} chain(s)`,
+    },
+    {
+      severity: remoteRunnerCount > 0 ? 'pass' : 'warn',
+      area: 'remote',
+      message: remoteRunnerCount > 0 ? `${remoteRunnerCount} remote runner contract(s)` : 'no remote runner contracts registered',
+    },
+    {
+      severity: sandboxSecureModeReady || `${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'local' ? 'pass' : 'warn',
+      area: 'sandbox',
+      message: `${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'local'
+        ? 'local mode (virtualization disabled by default)'
+        : sandboxSecureModeReady
+          ? `QEMU enabled: REPL=${sandboxReplIsolation}, MCP=${sandboxMcpIsolation}`
+          : 'QEMU sandboxing requires running GoodVibes inside WSL on Windows',
+    },
+  ];
+
+  return {
+    sessionId: ctx.session.runtime.sessionId,
+    providerCount,
+    serviceCount: services.length,
+    oauthProviderCount,
+    builtinSubscriptionProviderCount,
+    activeSubscriptionCount,
+    pendingSubscriptionCount,
+    serviceIssues,
+    skillCount: skills.length,
+    pluginCount: plugins.length,
+    quarantinedPluginCount,
+    pluginDirectories,
+    managedHookCount,
+    managedHookChainCount,
+    mcpServerCount: mcpServers.length,
+    quarantinedMcpCount,
+    elevatedMcpCount,
+    remoteRunnerCount,
+    sandboxReplIsolation,
+    sandboxMcpIsolation,
+    sandboxSecureModeReady,
+    issues,
+    services,
+  };
+}
+
+export function renderSetupSandboxReview(ctx: CommandContext, snapshot: SetupReviewSnapshot): string {
+  const backend = `${ctx.platform.configManager.get('sandbox.vmBackend')}`;
+  const image = String(ctx.platform.configManager.get('sandbox.qemuImagePath') ?? '').trim();
+  const wrapper = String(ctx.platform.configManager.get('sandbox.qemuExecWrapper') ?? '').trim();
+  const host = String(ctx.platform.configManager.get('sandbox.qemuGuestHost') ?? '').trim();
+  const workspace = String(ctx.platform.configManager.get('sandbox.qemuWorkspacePath') ?? '').trim();
+  const lines = [
+    'Setup Sandbox Review',
+    `  backend: ${backend}`,
+    `  repl isolation: ${snapshot.sandboxReplIsolation}`,
+    `  mcp isolation: ${snapshot.sandboxMcpIsolation}`,
+    `  secure mode ready: ${snapshot.sandboxSecureModeReady ? 'yes' : 'no'}`,
+    `  qemu image: ${image || '(not configured)'}`,
+    `  qemu wrapper: ${wrapper || '(not configured)'}`,
+    `  guest host: ${host || '(not configured)'}`,
+    `  guest workspace: ${workspace || '(not configured)'}`,
+    '',
+    '  next:',
+  ];
+  if (backend === 'local') {
+    lines.push('    sandbox/QEMU setup is externalized to GoodVibes TUI');
+    lines.push('    use GoodVibes TUI for coding/runtime isolation work');
+  } else if (!image || !wrapper) {
+    lines.push('    sandbox/QEMU setup is externalized to GoodVibes TUI');
+    lines.push('    use GoodVibes TUI for coding/runtime isolation work');
+  } else {
+    lines.push('    sandbox sessions are blocked in Agent');
+    lines.push('    delegate build/fix/review work to GoodVibes TUI');
+  }
+  if (process.platform === 'win32' && !isRunningInWsl()) {
+    lines.push('    Run GoodVibes inside WSL before enabling QEMU sandboxing.');
+  }
+  return lines.join('\n');
+}
+
+export function exportSetupSupportBundle(
+  targetDirArg: string,
+  snapshot: SetupReviewSnapshot,
+  ctx: CommandContext,
+): string {
+  const shellPaths = requireShellPaths(ctx);
+  const targetDir = shellPaths.resolveWorkspacePath(targetDirArg);
+  mkdirSync(targetDir, { recursive: true });
+  writeFileSync(join(targetDir, 'startup-review.json'), JSON.stringify(snapshot, null, 2) + '\n', 'utf-8');
+  const servicesPath = shellPaths.resolveProjectPath(GOODVIBES_AGENT_SURFACE_ROOT, 'services.json');
+  if (existsSync(servicesPath)) {
+    writeFileSync(join(targetDir, 'services.json'), readFileSync(servicesPath, 'utf-8'), 'utf-8');
+  }
+  const hooksPath = shellPaths.resolveProjectPath('hooks.managed.json');
+  if (existsSync(hooksPath)) {
+    writeFileSync(join(targetDir, 'hooks.managed.json'), readFileSync(hooksPath, 'utf-8'), 'utf-8');
+  }
+  writeFileSync(
+    join(targetDir, 'sandbox-externalized.txt'),
+    [
+      'GoodVibes Agent does not ship or manage QEMU sandbox wrappers.',
+      'Delegate build, fix, review, and runtime-isolation work to GoodVibes TUI.',
+      '',
+    ].join('\n'),
+    'utf-8',
+  );
+  return targetDir;
+}

package/src/input/commands/local-setup-transfer.ts

@@ -0,0 +1,135 @@
+import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import type { CommandContext } from '../command-registry.ts';
+import type { ConfigKey } from '../../config/index.ts';
+import { CONFIG_SCHEMA } from '../../config/index.ts';
+import { requireShellPaths } from './runtime-services.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../../config/surface.ts';
+
+export interface SetupReviewSnapshot {
+  readonly sessionId: string;
+  readonly providerCount: number;
+  readonly serviceCount: number;
+  readonly oauthProviderCount: number;
+  readonly builtinSubscriptionProviderCount: number;
+  readonly activeSubscriptionCount: number;
+  readonly pendingSubscriptionCount: number;
+  readonly serviceIssues: string[];
+  readonly skillCount: number;
+  readonly pluginCount: number;
+  readonly quarantinedPluginCount: number;
+  readonly pluginDirectories: string[];
+  readonly managedHookCount: number;
+  readonly managedHookChainCount: number;
+  readonly mcpServerCount: number;
+  readonly quarantinedMcpCount: number;
+  readonly elevatedMcpCount: number;
+  readonly remoteRunnerCount: number;
+  readonly sandboxReplIsolation: string;
+  readonly sandboxMcpIsolation: string;
+  readonly sandboxSecureModeReady: boolean;
+  readonly issues: Array<{ severity: 'pass' | 'warn' | 'fail'; area: string; message: string }>;
+  readonly services: string[];
+}
+
+export interface SetupTransferBundle {
+  readonly schemaVersion: 'v1';
+  readonly exportedAt: number;
+  readonly startupReview: SetupReviewSnapshot;
+  readonly config: Record<string, unknown>;
+  readonly services?: Record<string, unknown>;
+  readonly ecosystem?: {
+    readonly plugins?: Record<string, unknown>;
+    readonly skills?: Record<string, unknown>;
+  };
+}
+
+export function inspectSetupTransferBundle(bundle: SetupTransferBundle): string {
+  const ecosystemPluginCount = bundle.ecosystem?.plugins && Array.isArray((bundle.ecosystem.plugins as { entries?: unknown[] }).entries)
+    ? ((bundle.ecosystem.plugins as { entries: unknown[] }).entries.length)
+    : 0;
+  const ecosystemSkillCount = bundle.ecosystem?.skills && Array.isArray((bundle.ecosystem.skills as { entries?: unknown[] }).entries)
+    ? ((bundle.ecosystem.skills as { entries: unknown[] }).entries.length)
+    : 0;
+  return [
+    'Setup Transfer Review',
+    `  schemaVersion: ${bundle.schemaVersion}`,
+    `  exportedAt: ${new Date(bundle.exportedAt).toISOString()}`,
+    `  session: ${bundle.startupReview.sessionId}`,
+    `  services: ${bundle.startupReview.serviceCount}`,
+    `  plugins: ${bundle.startupReview.pluginCount}`,
+    `  skills: ${bundle.startupReview.skillCount}`,
+    `  remote runners: ${bundle.startupReview.remoteRunnerCount}`,
+    `  config keys: ${Object.keys(bundle.config ?? {}).length}`,
+    `  curated plugins: ${ecosystemPluginCount}`,
+    `  curated skills: ${ecosystemSkillCount}`,
+  ].join('\n');
+}
+
+export function buildSetupTransferBundle(ctx: CommandContext, snapshot: SetupReviewSnapshot): SetupTransferBundle {
+  const shellPaths = requireShellPaths(ctx);
+  const config: Record<string, unknown> = {};
+  for (const entry of CONFIG_SCHEMA) {
+    try {
+      config[entry.key] = structuredClone(ctx.platform.configManager.get(entry.key as ConfigKey));
+    } catch {
+      // Ignore unreadable config values in transfer bundles.
+    }
+  }
+  const servicesPath = shellPaths.resolveProjectPath(GOODVIBES_AGENT_SURFACE_ROOT, 'services.json');
+  const pluginsPath = shellPaths.resolveProjectPath(GOODVIBES_AGENT_SURFACE_ROOT, 'ecosystem', 'plugins.json');
+  const skillsPath = shellPaths.resolveProjectPath(GOODVIBES_AGENT_SURFACE_ROOT, 'ecosystem', 'skills.json');
+  const services = existsSync(servicesPath)
+    ? JSON.parse(readFileSync(servicesPath, 'utf-8')) as Record<string, unknown>
+    : undefined;
+  const plugins = existsSync(pluginsPath)
+    ? JSON.parse(readFileSync(pluginsPath, 'utf-8')) as Record<string, unknown>
+    : undefined;
+  const skills = existsSync(skillsPath)
+    ? JSON.parse(readFileSync(skillsPath, 'utf-8')) as Record<string, unknown>
+    : undefined;
+
+  return {
+    schemaVersion: 'v1',
+    exportedAt: Date.now(),
+    startupReview: snapshot,
+    config,
+    services,
+    ecosystem: {
+      plugins,
+      skills,
+    },
+  };
+}
+
+export function createSetupLink(surface: string, target?: string): string {
+  const encodedTarget = target ? `?target=${encodeURIComponent(target)}` : '';
+  return `goodvibes://open/${encodeURIComponent(surface)}${encodedTarget}`;
+}
+
+export function parseSetupLink(value: string): { surface: string; target?: string } | null {
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== 'goodvibes:') return null;
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    if (parsed.hostname !== 'open' || segments.length !== 1) return null;
+    return {
+      surface: decodeURIComponent(segments[0]!),
+      target: parsed.searchParams.get('target') ?? undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function exportSetupTransferBundle(
+  ctx: CommandContext,
+  pathArg: string,
+  bundle: SetupTransferBundle,
+): string {
+  const shellPaths = requireShellPaths(ctx);
+  const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, JSON.stringify(bundle, null, 2) + '\n', 'utf-8');
+  return targetPath;
+}

package/src/input/commands/local-setup.ts

@@ -0,0 +1,282 @@
+import { dirname, join } from 'path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import type { CommandRegistry } from '../command-registry.ts';
+import type { ConfigKey } from '../../config/index.ts';
+import { CONFIG_SCHEMA } from '../../config/index.ts';
+import { listHookPointContracts } from '@pellux/goodvibes-sdk/platform/hooks';
+import type { SetupTransferBundle } from './local-setup-transfer.ts';
+import {
+  buildSetupTransferBundle,
+  createSetupLink,
+  exportSetupTransferBundle,
+  inspectSetupTransferBundle,
+  parseSetupLink,
+} from './local-setup-transfer.ts';
+import { buildSetupReviewSnapshot, exportSetupSupportBundle } from './local-setup-review.ts';
+import { openOnboardingWizard, requirePanelManager, requireShellPaths } from './runtime-services.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../../config/surface.ts';
+
+type SetupSnapshot = Awaited<ReturnType<typeof buildSetupReviewSnapshot>>;
+
+export function registerLocalSetupCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'setup',
+    aliases: ['startup'],
+    description: 'Launch the onboarding wizard and review Agent startup readiness',
+    usage: '[review|doctor|services|hooks|remote|sandbox|onboarding|support-bundle <dir>|export <path>|transfer <export|inspect|import> <path>|link <surface> [target]|open-link <uri>]',
+    async handler(args, ctx) {
+      const sub = args[0] ?? 'review';
+      let shellPaths: ReturnType<typeof requireShellPaths> | null = null;
+      let snapshotPromise: Promise<SetupSnapshot> | null = null;
+      const getShellPaths = () => (shellPaths ??= requireShellPaths(ctx));
+      const getSnapshot = async (): Promise<SetupSnapshot> => {
+        snapshotPromise ??= buildSetupReviewSnapshot(ctx);
+        return snapshotPromise;
+      };
+
+      if (sub === 'review') {
+        const snapshot = await getSnapshot();
+        ctx.print([
+          'Startup Readiness Review',
+          `  session: ${snapshot.sessionId}`,
+          `  providers/models: ${snapshot.providerCount}`,
+          `  services configured: ${snapshot.serviceCount}`,
+          `  oauth providers: ${snapshot.oauthProviderCount + snapshot.builtinSubscriptionProviderCount}`,
+          `  active subscriptions: ${snapshot.activeSubscriptionCount}`,
+          `  pending subscriptions: ${snapshot.pendingSubscriptionCount}`,
+          `  skills discovered: ${snapshot.skillCount}`,
+          `  plugins discovered: ${snapshot.pluginCount}`,
+          `  quarantined plugins: ${snapshot.quarantinedPluginCount}`,
+          `  plugin search dirs: ${snapshot.pluginDirectories.length}`,
+          `  managed hooks: ${snapshot.managedHookCount}`,
+          `  managed hook chains: ${snapshot.managedHookChainCount}`,
+          `  mcp servers known: ${snapshot.mcpServerCount}`,
+          `  mcp quarantined: ${snapshot.quarantinedMcpCount}`,
+          `  mcp elevated: ${snapshot.elevatedMcpCount}`,
+          `  remote runners: ${snapshot.remoteRunnerCount}`,
+          '  sandbox/QEMU: externalized to GoodVibes TUI for delegated build/runtime isolation',
+          '',
+          `  service ids: ${snapshot.services.join(', ') || '(none)'}`,
+          `  plugin dirs: ${snapshot.pluginDirectories.join(', ') || '(none)'}`,
+        ].join('\n'));
+        return;
+      }
+
+      if (sub === 'doctor') {
+        const snapshot = await getSnapshot();
+        ctx.print([
+          'Startup Doctor',
+          ...snapshot.issues.map((issue) => `  [${issue.severity.toUpperCase()}] ${issue.area}: ${issue.message}`),
+          '  [INFO] sandbox: GoodVibes Agent does not own sandbox/QEMU setup; delegate build/runtime isolation to GoodVibes TUI.',
+          ...(snapshot.serviceIssues.length > 0
+            ? ['', '  Service issues:', ...snapshot.serviceIssues.map((issue) => `    - ${issue}`)]
+            : []),
+        ].join('\n'));
+        return;
+      }
+
+      if (sub === 'services') {
+        const snapshot = await getSnapshot();
+        ctx.print([
+          'Startup Services',
+          `  configured: ${snapshot.serviceCount}`,
+          `  oauth providers: ${snapshot.oauthProviderCount + snapshot.builtinSubscriptionProviderCount}`,
+          `  active subscriptions: ${snapshot.activeSubscriptionCount}`,
+          `  pending subscriptions: ${snapshot.pendingSubscriptionCount}`,
+          `  issues: ${snapshot.serviceIssues.length}`,
+          ...snapshot.services.map((name) => `  ${name}`),
+          ...(snapshot.serviceIssues.length > 0
+            ? ['', ...snapshot.serviceIssues.map((issue) => `  issue: ${issue}`)]
+            : []),
+        ].join('\n'));
+        return;
+      }
+
+      if (sub === 'hooks') {
+        const snapshot = await getSnapshot();
+        const contracts = listHookPointContracts();
+        ctx.print([
+          'Startup Hooks',
+          `  managed hooks: ${snapshot.managedHookCount}`,
+          `  managed chains: ${snapshot.managedHookChainCount}`,
+          `  hook contracts: ${contracts.length}`,
+        ].join('\n'));
+        return;
+      }
+
+      if (sub === 'remote') {
+        const snapshot = await getSnapshot();
+        const runners = ctx.ops.remoteRuntime?.listContracts() ?? [];
+        ctx.print([
+          'Startup Remote',
+          `  runner contracts: ${snapshot.remoteRunnerCount}`,
+          ...runners.map((runner) => `  ${runner.id}  [${runner.trustClass}]  ${runner.label}`),
+        ].join('\n'));
+        return;
+      }
+
+      if (sub === 'sandbox') {
+        ctx.print([
+          'Setup Sandbox',
+          '  status: externalized',
+          '  owner: GoodVibes TUI',
+          '  reason: sandbox/QEMU setup and runtime isolation are coding/build execution surfaces.',
+          '  result: no local Agent sandbox settings, files, or sessions were changed.',
+        ].join('\n'));
+        return;
+      }
+
+      if (sub === 'onboarding') {
+        openOnboardingWizard(ctx, { mode: 'edit', reset: true });
+        ctx.print('Opening onboarding wizard.');
+        return;
+      }
+
+      if (sub === 'support-bundle') {
+        const snapshot = await getSnapshot();
+        const dirArg = args[1];
+        if (!dirArg) {
+          ctx.print('Usage: /setup support-bundle <dir>');
+          return;
+        }
+        const targetDir = exportSetupSupportBundle(dirArg, snapshot, ctx);
+        writeFileSync(join(targetDir, 'remote-summary.json'), JSON.stringify({
+          runners: ctx.ops.remoteRuntime?.listContracts() ?? [],
+          artifacts: (ctx.ops.remoteRuntime?.listArtifacts() ?? []).map((artifact) => ({
+            id: artifact.id,
+            runnerId: artifact.runnerId,
+            status: artifact.task.status,
+            createdAt: artifact.createdAt,
+          })),
+        }, null, 2) + '\n', 'utf-8');
+        ctx.print(`Exported support bundle to ${targetDir}`);
+        return;
+      }
+
+      if (sub === 'export') {
+        const snapshot = await getSnapshot();
+        const pathArg = args[1];
+        if (!pathArg) {
+          ctx.print('Usage: /setup export <path>');
+          return;
+        }
+        const targetPath = getShellPaths().resolveWorkspacePath(pathArg);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, JSON.stringify(snapshot, null, 2) + '\n', 'utf-8');
+        ctx.print(`Exported startup review to ${targetPath}`);
+        return;
+      }
+
+      if (sub === 'transfer') {
+        const mode = args[1]?.toLowerCase();
+        const pathArg = args[2];
+        if (!mode || !pathArg) {
+          ctx.print('Usage: /setup transfer <export|inspect|import> <path>');
+          return;
+        }
+        const targetPath = getShellPaths().resolveWorkspacePath(pathArg);
+        if (mode === 'export') {
+          const snapshot = await getSnapshot();
+          const bundle = buildSetupTransferBundle(ctx, snapshot);
+          ctx.print(`Exported setup transfer bundle to ${exportSetupTransferBundle(ctx, pathArg, bundle)}`);
+          return;
+        }
+        if (mode === 'inspect') {
+          try {
+            const bundle = JSON.parse(readFileSync(targetPath, 'utf-8')) as SetupTransferBundle;
+            ctx.print(`${inspectSetupTransferBundle(bundle)}\n  path: ${targetPath}`);
+          } catch (error) {
+            ctx.print(`Failed to inspect setup transfer bundle: ${summarizeError(error)}`);
+          }
+          return;
+        }
+        if (mode === 'import') {
+          try {
+            const bundle = JSON.parse(readFileSync(targetPath, 'utf-8')) as SetupTransferBundle;
+            for (const entry of CONFIG_SCHEMA) {
+              if (Object.prototype.hasOwnProperty.call(bundle.config, entry.key)) {
+                ctx.platform.configManager.setDynamic(entry.key as ConfigKey, (bundle.config as Record<string, unknown>)[entry.key]);
+              }
+            }
+            if (bundle.services) {
+              const servicesPath = getShellPaths().resolveProjectPath(GOODVIBES_AGENT_SURFACE_ROOT, 'services.json');
+              mkdirSync(dirname(servicesPath), { recursive: true });
+              writeFileSync(servicesPath, JSON.stringify(bundle.services, null, 2) + '\n', 'utf-8');
+            }
+            if (bundle.ecosystem?.plugins) {
+              const pluginsPath = getShellPaths().resolveProjectPath(GOODVIBES_AGENT_SURFACE_ROOT, 'ecosystem', 'plugins.json');
+              mkdirSync(dirname(pluginsPath), { recursive: true });
+              writeFileSync(pluginsPath, JSON.stringify(bundle.ecosystem.plugins, null, 2) + '\n', 'utf-8');
+            }
+            if (bundle.ecosystem?.skills) {
+              const skillsPath = getShellPaths().resolveProjectPath(GOODVIBES_AGENT_SURFACE_ROOT, 'ecosystem', 'skills.json');
+              mkdirSync(dirname(skillsPath), { recursive: true });
+              writeFileSync(skillsPath, JSON.stringify(bundle.ecosystem.skills, null, 2) + '\n', 'utf-8');
+            }
+            ctx.print(`Imported setup transfer bundle from ${targetPath}`);
+          } catch (error) {
+            ctx.print(`Failed to import setup transfer bundle: ${summarizeError(error)}`);
+          }
+          return;
+        }
+        ctx.print('Usage: /setup transfer <export|inspect|import> <path>');
+        return;
+      }
+
+      if (sub === 'link') {
+        const surface = args[1];
+        const target = args[2];
+        if (!surface) {
+          ctx.print('Usage: /setup link <cockpit|security|remote|knowledge|incident|hooks|orchestration|tasks> [target]');
+          return;
+        }
+        ctx.print(createSetupLink(surface, target));
+        return;
+      }
+
+      if (sub === 'open-link') {
+        const link = args[1];
+        if (!link) {
+          ctx.print('Usage: /setup open-link <goodvibes://...>');
+          return;
+        }
+        const parsed = parseSetupLink(link);
+        if (!parsed) {
+          ctx.print(`Invalid setup link: ${link}`);
+          return;
+        }
+        const panelOpeners: Record<string, (() => void) | undefined> = {
+          cockpit: ctx.openCockpitPanel,
+          security: ctx.openSecurityPanel,
+          remote: ctx.openRemotePanel,
+          knowledge: ctx.openKnowledgePanel,
+          incident: ctx.openIncidentPanel,
+          hooks: ctx.openHooksPanel,
+          orchestration: ctx.openOrchestrationPanel,
+        };
+        if (parsed.surface === 'tasks') {
+          if (ctx.showPanel) ctx.showPanel('tasks');
+          else {
+            const panelManager = requirePanelManager(ctx);
+            panelManager.open('tasks');
+            panelManager.show();
+            ctx.renderRequest();
+          }
+          ctx.print(`Opened setup link for tasks${parsed.target ? ` (${parsed.target})` : ''}.`);
+          return;
+        }
+        const openPanel = panelOpeners[parsed.surface];
+        if (!openPanel) {
+          ctx.print(`Unsupported setup link surface: ${parsed.surface}`);
+          return;
+        }
+        openPanel();
+        ctx.print(`Opened setup link for ${parsed.surface}${parsed.target ? ` (${parsed.target})` : ''}.`);
+        return;
+      }
+
+      ctx.print('Usage: /setup [review|doctor|services|hooks|remote|sandbox|onboarding|support-bundle <dir>|export <path>|transfer <export|inspect|import> <path>|link <surface> [target]|open-link <uri>]');
+    },
+  });
+}