vgxness 1.1.1 → 1.2.0

package/dist/cli/commands/dashboard-dispatcher.js

@@ -6,6 +6,7 @@ import { InMemoryRunGateway } from '../../code/runtime/gateways.js';
 import { MemoryServiceCodeGateway } from '../../code/runtime/memory-service-gateway.js';
 import { RunsCodeRunGateway } from '../../code/runtime/runs-code-run-gateway.js';
 import { SddWorkflowGateway } from '../../code/runtime/sdd-workflow-gateway.js';
+import React from 'react';
 import { ProviderChangePlanService } from '../../mcp/provider-change-plan.js';
 import { ProviderDoctorService } from '../../mcp/provider-doctor.js';
 import { ProviderStatusService } from '../../mcp/provider-status.js';
@@ -20,14 +21,47 @@ import { buildDashboardApprovalsReadModel, buildDashboardInstallationReadModel,
 import { renderDashboard as renderStatusDashboard } from '../dashboard-renderer.js';
 import { sanitizeDashboardError, } from '../dashboard-tui-read-model.js';
 import { dashboardKeyFromInput, loadInitialDashboardState, reduceDashboardKey, refreshDashboard, renderDashboard as renderInteractiveDashboard, resolveDashboardRenderStyle, } from '../interactive-dashboard.js';
+import { MainMenuApp } from '../tui/main-menu/index.js';
+import { renderInkApp } from '../tui/render-ink-app.js';
 import { canRunInteractiveTui } from '../tui/terminal-capabilities.js';
-import { collectRunDetails, collectRunInsights, createSetupLifecycleService, readSetupStatus } from './setup-dispatcher.js';
+import { collectRunDetails, collectRunInsights, createSetupLifecycleService, readSetupStatus, runSetupTuiCommand } from './setup-dispatcher.js';
 function defaultNoTtyGuidance() {
     return ([
-        'VGXNESS interactive dashboard requires a TTY; no provider config was written.',
-        'Next: rerun `vgx` in an interactive terminal, use `vgx dashboard interactive` for the same dashboard, or run `vgx dashboard status --project <name>` for scriptable read-only output.',
+        'VGXNESS main menu requires a TTY; no provider config was written.',
+        'Next: rerun `vgx` in an interactive terminal, run `vgx init --plan` or `vgx setup plan` for read-only installation guidance, use `vgx dashboard interactive` for the dashboard, or run `vgx dashboard status --project <name>` for scriptable read-only output.',
     ].join('\n') + '\n');
 }
+function guidanceForMainMenuResult(result) {
+    if (result.type === 'show-doctor-guidance')
+        return ['Doctor / recovery guidance:', '- Read-only status: `vgx setup status`', '- Provider doctor: `vgx mcp doctor opencode`', '- No provider config was written.'].join('\n') + '\n';
+    if (result.type === 'show-sdd-guidance')
+        return ['SDD / workflow guidance:', '- Use VGXNESS MCP tools from OpenCode for normal SDD progression.', '- Manual status: `vgx sdd status --project <name> --change <change>`', '- No provider config was written.'].join('\n') + '\n';
+    if (result.type === 'show-advanced-cli')
+        return ['Advanced CLI guidance:', '- Installation preview: `vgx init --plan` or `vgx setup plan`', '- Dashboard: `vgx dashboard interactive`', '- Scriptable status: `vgx dashboard status --project <name>`', '- No provider config was written.'].join('\n') + '\n';
+    if (result.type === 'exit')
+        return 'Exited main menu; no provider config was written.\n';
+    return undefined;
+}
+async function renderDefaultMainMenu(environment, onResult) {
+    await renderInkApp(React.createElement(MainMenuApp, { onResult }), {
+        stdin: environment.stdin,
+        stdout: environment.stdout,
+    });
+}
+export async function runDefaultInteractiveEntrypointWithMainMenu(environment, input = {}) {
+    if (!canRunInteractiveTui(environment.stdin, environment.stdout))
+        return okText(defaultNoTtyGuidance());
+    let selected;
+    await (input.renderMainMenu ?? ((onResult) => renderDefaultMainMenu(environment, onResult)))((result) => {
+        selected = result;
+    });
+    const result = selected ?? { type: 'exit' };
+    if (result.type === 'open-setup')
+        return (input.setupTui ?? runSetupTuiCommand)(environment);
+    if (result.type === 'open-dashboard')
+        return (input.dashboardInteractive ?? runDashboardInteractiveCommand)({ positionals: ['dashboard', 'interactive'], flags: {} }, environment);
+    return okText(guidanceForMainMenuResult(result) ?? 'No provider config was written.\n');
+}
 function buildDashboardProfiles(managerProfiles, project, setupStatus, sectionErrors) {
     const resolved = managerProfiles.resolveEffectiveManager({ project, scope: 'project', managerName: 'vgxness-manager' });
     if (!resolved.ok) {
@@ -431,9 +465,7 @@ export async function runDashboardInteractiveCommand(parsed, environment) {
     }
 }
 export async function runDefaultInteractiveEntrypoint(environment) {
-    if (!canRunInteractiveTui(environment.stdin, environment.stdout))
-        return okText(defaultNoTtyGuidance());
-    return runDashboardInteractiveCommand({ positionals: ['dashboard', 'interactive'], flags: {} }, environment);
+    return runDefaultInteractiveEntrypointWithMainMenu(environment);
 }
 export async function runCodeCliCommand(parsed, environment) {
     const [, command] = parsed.positionals;

package/dist/cli/tui/main-menu/main-menu-read-model.js

@@ -2,12 +2,12 @@ import { formatTuiFooter, tuiBadges } from '../visual/index.js';
 import { mainMenuOptionIds } from './main-menu-state.js';
 const optionCopy = {
     setup: {
-        label: 'Setup / Guided installation',
-        description: 'Review local storage and OpenCode integration safely.',
+        label: 'Installation',
+        description: 'Start guided installation for memory and OpenCode integration safely.',
         badges: [tuiBadges.requiresConfirmation],
-        detailTitle: 'Setup assistant',
+        detailTitle: 'Installation',
         detailLines: [
-            'Opens the existing Setup TUI.',
+            'Opens the guided Installation TUI.',
             'Plan/review screens are read-only.',
             'Provider writes require final confirmation; OpenCode is the only automatic provider with explicit consent.',
         ],
@@ -60,12 +60,12 @@ export function buildMainMenuViewModel(state) {
     return {
         title: 'VGXNESS Main Menu',
         subtitle: 'Keyboard-first local control plane',
-        contextLines: ['Choose where to go next. The menu itself is read-only and does not write provider config.'],
+        contextLines: ['Choose where to go next. Installation is first; the menu itself is read-only and does not write provider config.'],
         options,
         detail: { title: focused.detailTitle, lines: focused.detailLines, badges: focused.badges },
         safetyLines: [
             'Previews are read-only.',
-            'Setup/provider writes require final confirmation.',
+            'Installation/provider writes require final confirmation.',
             'OpenCode is the only automatic provider path and still requires explicit consent.',
         ],
         helpLines: state.helpVisible

package/dist/cli/tui/setup/screens/cancellation-screen.js

@@ -2,5 +2,5 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from 'ink';
 import { badgeLabels, Panel, SetupScreenFrame, setupFooterHints } from './screen-components.js';
 export function CancellationScreen() {
-    return (_jsx(SetupScreenFrame, { title: "Setup cancelled", tone: "cancelled", footer: [setupFooterHints.close], children: _jsxs(Panel, { title: "Cancelled", badge: { label: badgeLabels.cancelled }, children: [_jsx(Text, { children: "Setup was not completed." }), _jsx(Text, { children: "No provider config was written." })] }) }));
+    return (_jsx(SetupScreenFrame, { title: "Setup cancelled", tone: "cancelled", footer: [setupFooterHints.close], children: _jsxs(Panel, { title: "Cancelled", badge: { label: badgeLabels.cancelled }, children: [_jsx(Text, { children: "Setup was not completed." }), _jsx(Text, { children: "No provider config was written." }), _jsx(Text, { children: "No agent seeding was performed." })] }) }));
 }

package/dist/cli/tui/setup/screens/final-confirmation-screen.js

@@ -2,5 +2,5 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from 'ink';
 import { Panel, PlanSummary, SetupWorkspace, setupFooterHints } from './screen-components.js';
 export function FinalConfirmationScreen(props) {
-    return (_jsx(SetupWorkspace, { title: "Final confirmation", viewModel: props.viewModel, footer: [setupFooterHints.confirmApply, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Confirm OpenCode setup", children: [_jsx(PlanSummary, { viewModel: props.viewModel }), _jsx(Text, { children: "[warning]" }), _jsx(Text, { color: "yellow", children: "WARNING: OpenCode provider config may be modified at the target path above. Existing config is backed up when planned." }), _jsx(Text, { children: "Press Enter to confirm and apply OpenCode setup, or Esc/q to cancel without writing." })] }) }));
+    return (_jsx(SetupWorkspace, { title: "Final confirmation", viewModel: props.viewModel, footer: [setupFooterHints.confirmApply, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Confirm OpenCode setup", children: [_jsx(PlanSummary, { viewModel: props.viewModel }), _jsx(Text, { children: "[warning]" }), _jsx(Text, { color: "yellow", children: "WARNING: OpenCode provider config may be modified at the target path above. Existing config is backed up when planned." }), _jsx(Text, { children: "After confirmation: run doctor, then restart OpenCode to reload MCP configuration." }), _jsx(Text, { children: "Press Enter to confirm and apply OpenCode setup, or Esc/q to cancel without writing." })] }) }));
 }

package/dist/cli/tui/setup/screens/opencode-details-screen.js

@@ -6,5 +6,5 @@ export function OpenCodeDetailsScreen(props) {
     if (vm.providerLabel !== 'OpenCode') {
         return (_jsx(SetupWorkspace, { title: "OpenCode details", viewModel: vm, footer: [setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel], children: _jsx(ManualNoProviderNotice, {}) }));
     }
-    return (_jsx(SetupWorkspace, { title: "OpenCode details", viewModel: vm, footer: [setupFooterHints.select, setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "OpenCode plan", badge: { label: badgeLabels.writeAfterConfirm }, children: [_jsx(ChoiceList, { choices: vm.scopeChoices }), _jsx(ChoiceList, { choices: vm.installModeChoices }), _jsx(KeyValue, { label: "Scope", value: vm.scopeLabel }), _jsx(KeyValue, { label: "Install mode", value: vm.installModeLabel }), _jsx(KeyValue, { label: "Target config", value: vm.targetPathLabel }), _jsx(KeyValue, { label: "Action", value: vm.opencodeActionLabel }), _jsx(Text, { children: "Details are preview-only here; writes require final confirmation." })] }) }));
+    return (_jsx(SetupWorkspace, { title: "OpenCode details", viewModel: vm, footer: [setupFooterHints.select, setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "OpenCode plan", badge: { label: badgeLabels.writeAfterConfirm }, children: [_jsx(ChoiceList, { choices: vm.scopeChoices }), _jsx(ChoiceList, { choices: vm.installModeChoices }), _jsx(KeyValue, { label: "Scope", value: vm.scopeLabel }), _jsx(KeyValue, { label: "Install mode", value: vm.installModeLabel }), _jsx(KeyValue, { label: "Target config", value: vm.targetPathLabel }), _jsx(KeyValue, { label: "Action", value: vm.opencodeActionLabel }), _jsx(KeyValue, { label: "Agent readiness", value: vm.agentReadinessLabel }), _jsx(Text, { children: vm.agentReadinessDetail }), _jsx(Text, { children: "Details are preview-only here; writes require final confirmation." })] }) }));
 }

package/dist/cli/tui/setup/screens/plan-review-screen.js

@@ -2,5 +2,5 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from 'ink';
 import { badgeLabels, Panel, PlanSummary, SetupWorkspace, setupFooterHints } from './screen-components.js';
 export function PlanReviewScreen(props) {
-    return (_jsx(SetupWorkspace, { title: "Read-only plan review", viewModel: props.viewModel, footer: [setupFooterHints.finalConfirmation, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Plan summary", badge: { label: badgeLabels.readOnly }, children: [_jsx(PlanSummary, { viewModel: props.viewModel }), _jsx(Text, { children: "Review only: this screen does not write provider config." }), _jsx(Text, { children: props.viewModel.canAutoApply ? 'Press Enter to continue to final confirmation.' : 'Manual setup required; no automatic apply is available.' })] }) }));
+    return (_jsx(SetupWorkspace, { title: "Read-only plan review", viewModel: props.viewModel, footer: [setupFooterHints.finalConfirmation, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Plan summary", badge: { label: badgeLabels.readOnly }, children: [_jsx(PlanSummary, { viewModel: props.viewModel }), _jsxs(Text, { children: ["Doctor next step: ", props.viewModel.nextCommands.find((command) => /\bdoctor\b/.test(command)) ?? 'vgx doctor'] }), _jsx(Text, { children: "Restart next step: Restart OpenCode after confirmed setup so it reloads MCP configuration." }), _jsx(Text, { children: "Review only: this screen does not write provider config." }), _jsx(Text, { children: props.viewModel.canAutoApply ? 'Press Enter to continue to final confirmation.' : 'Manual setup required; no automatic apply is available.' })] }) }));
 }

package/dist/cli/tui/setup/screens/project-database-screen.js

@@ -2,5 +2,5 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChoiceList, KeyValue, Panel, SetupWorkspace, setupFooterHints } from './screen-components.js';
 export function ProjectDatabaseScreen(props) {
     const vm = props.viewModel;
-    return (_jsxs(SetupWorkspace, { title: "Project and database", viewModel: vm, footer: [setupFooterHints.select, setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel], children: [_jsxs(Panel, { title: "Project", children: [_jsx(KeyValue, { label: "Project", value: vm.projectLabel }), _jsx(KeyValue, { label: "Workspace", value: vm.workspaceRootLabel })] }), _jsxs(Panel, { title: "Database", children: [_jsx(ChoiceList, { choices: vm.databaseChoices }), _jsx(KeyValue, { label: "Mode", value: vm.databaseLabel }), _jsx(KeyValue, { label: "Path", value: vm.databasePathLabel }), _jsx(KeyValue, { label: "Source", value: vm.databaseSourceLabel })] })] }));
+    return (_jsxs(SetupWorkspace, { title: "Project and database", viewModel: vm, footer: [setupFooterHints.select, setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel], children: [_jsxs(Panel, { title: "Project", children: [_jsx(KeyValue, { label: "Project", value: vm.projectLabel }), _jsx(KeyValue, { label: "Workspace", value: vm.workspaceRootLabel })] }), _jsxs(Panel, { title: "Database", children: [_jsx(ChoiceList, { choices: vm.databaseChoices }), _jsx(KeyValue, { label: "Mode", value: vm.databaseLabel }), _jsx(KeyValue, { label: "Path", value: vm.databasePathLabel }), _jsx(KeyValue, { label: "Source", value: vm.databaseSourceLabel }), _jsx(KeyValue, { label: "Memory path explanation", value: vm.memoryPathExplanation })] })] }));
 }

package/dist/cli/tui/setup/screens/provider-screen.js

@@ -3,5 +3,5 @@ import { Text } from 'ink';
 import { ChoiceList, Panel, SetupWorkspace, setupFooterHints } from './screen-components.js';
 export function ProviderScreen(props) {
     const vm = props.viewModel;
-    return (_jsx(SetupWorkspace, { title: "Provider", viewModel: vm, footer: [setupFooterHints.select, setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Provider selection", children: [_jsx(ChoiceList, { choices: vm.providerChoices }), _jsx(Text, { children: "OpenCode setup remains gated by final confirmation. Non-OpenCode/manual has no auto-apply." })] }) }));
+    return (_jsx(SetupWorkspace, { title: "Provider", viewModel: vm, footer: [setupFooterHints.select, setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Provider selection", children: [_jsx(ChoiceList, { choices: vm.providerChoices }), _jsx(Text, { children: vm.providerInstallabilityLabel }), _jsx(Text, { children: "OpenCode setup remains gated by final confirmation. Non-OpenCode/manual has no auto-apply." })] }) }));
 }

package/dist/cli/tui/setup/screens/result-screen.js

@@ -4,8 +4,13 @@ import { badgeLabels, KeyValue, Panel, SetupScreenFrame, setupFooterHints } from
 export function ResultScreen(props) {
     const result = props.result;
     if (result?.status === 'installed')
-        return (_jsx(SetupScreenFrame, { title: "Setup complete", tone: "success", footer: [setupFooterHints.close], children: _jsxs(Panel, { title: "Installed", badge: { label: badgeLabels.success }, children: [_jsx(KeyValue, { label: "Target config", value: result.targetPath }), result.backupPath === undefined ? _jsx(Text, { children: "Backup: none created" }) : _jsx(KeyValue, { label: "Backup", value: result.backupPath }), result.warnings.map((warning) => (_jsxs(Text, { children: ["Warning: ", warning] }, warning)))] }) }));
+        return (_jsx(SetupScreenFrame, { title: "Setup complete", tone: "success", footer: [setupFooterHints.close], children: _jsxs(Panel, { title: "Installed", badge: { label: badgeLabels.success }, children: [_jsx(KeyValue, { label: "Target config", value: result.targetPath }), result.backupPath === undefined ? _jsx(Text, { children: "Backup: none created" }) : _jsx(KeyValue, { label: "Backup", value: result.backupPath }), result.warnings.map((warning) => (_jsxs(Text, { children: ["Warning: ", warning] }, warning))), resultNextCommands(props.viewModel).map((command) => (_jsxs(Text, { children: ["Next: ", command] }, command)))] }) }));
     if (result?.status === 'manual-required')
         return (_jsx(SetupScreenFrame, { title: "Manual setup", tone: "warning", footer: [setupFooterHints.close], children: _jsxs(Panel, { title: "Manual follow-up", badge: { label: badgeLabels.warning }, children: [_jsx(Text, { children: result.message }), props.viewModel.nextCommands.map((command) => (_jsxs(Text, { children: ["Next: ", command] }, command)))] }) }));
     return (_jsx(SetupScreenFrame, { title: "Setup result", footer: [setupFooterHints.close], children: _jsx(Panel, { title: "No write", children: _jsx(Text, { children: "No provider config write occurred." }) }) }));
 }
+function resultNextCommands(viewModel) {
+    const filtered = viewModel.nextCommands.filter((command) => !/^vgx(?:ness)? setup apply\b/.test(command));
+    const withDoctor = filtered.some((command) => /\bdoctor\b/.test(command)) ? filtered : [...filtered, 'vgx doctor'];
+    return withDoctor.some((command) => /Restart OpenCode/i.test(command)) ? withDoctor : [...withDoctor, 'Restart OpenCode and verify the vgxness MCP server is visible.'];
+}

package/dist/cli/tui/setup/screens/screen-components.js

@@ -64,10 +64,10 @@ export function KeyValue(props) {
 }
 export function PlanSummary(props) {
     const vm = props.viewModel;
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(KeyValue, { label: "Readiness", value: `${vm.readinessBadge} ${vm.readinessLabel}` }), _jsx(KeyValue, { label: "Provider", value: vm.providerLabel }), _jsx(KeyValue, { label: "Database", value: vm.databaseLabel }), _jsx(KeyValue, { label: "Database path", value: vm.databasePathLabel }), _jsx(KeyValue, { label: "OpenCode scope", value: vm.scopeLabel }), _jsx(KeyValue, { label: "Install mode", value: vm.installModeLabel }), _jsx(KeyValue, { label: "Target config", value: vm.targetPathLabel }), _jsx(Text, { children: vm.backupLabel }), vm.plannedActions.map((action) => (_jsxs(Text, { children: ["Action: ", action.safetyBadge, " ", action.label, action.targetPathLabel === undefined ? '' : ` (${action.targetPathLabel})`] }, `action:${action.id}`))), vm.warnings.map((warning) => (_jsxs(Text, { children: ["Warning: ", warning] }, `warning:${warning}`))), vm.blockers.map((blocker) => (_jsxs(Text, { children: ["Blocked: ", blocker] }, `blocker:${blocker}`)))] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(KeyValue, { label: "Readiness", value: `${vm.readinessBadge} ${vm.readinessLabel}` }), _jsx(KeyValue, { label: "Provider", value: vm.providerLabel }), _jsx(KeyValue, { label: "Database", value: vm.databaseLabel }), _jsx(KeyValue, { label: "Database path", value: vm.databasePathLabel }), _jsx(KeyValue, { label: "OpenCode scope", value: vm.scopeLabel }), _jsx(KeyValue, { label: "Install mode", value: vm.installModeLabel }), _jsx(KeyValue, { label: "Provider installability", value: vm.providerInstallabilityLabel }), _jsx(KeyValue, { label: "Agent readiness", value: vm.agentReadinessLabel }), _jsx(KeyValue, { label: "Agent detail", value: vm.agentReadinessDetail }), _jsx(KeyValue, { label: "Target config", value: vm.targetPathLabel }), _jsx(Text, { children: vm.backupLabel }), vm.plannedActions.map((action) => (_jsxs(Text, { children: ["Action: ", action.safetyBadge, " ", action.label, action.targetPathLabel === undefined ? '' : ` (${action.targetPathLabel})`] }, `action:${action.id}`))), vm.warnings.map((warning) => (_jsxs(Text, { children: ["Warning: ", warning] }, `warning:${warning}`))), vm.blockers.map((blocker) => (_jsxs(Text, { children: ["Blocked: ", blocker] }, `blocker:${blocker}`)))] }));
 }
 export function ManualNoProviderNotice() {
-    return (_jsxs(Panel, { title: "Manual / no-provider-write mode", badge: { label: badgeLabels.manual }, children: [_jsx(Text, { children: "OpenCode-only scope and install controls are disabled because provider is Manual / none." }), _jsx(Text, { children: "No provider config will be written; use the manual next commands from the plan." })] }));
+    return (_jsxs(Panel, { title: "Manual / no-provider-write mode", badge: { label: badgeLabels.manual }, children: [_jsx(Text, { children: "OpenCode-only scope and install controls are disabled because provider is Manual / none." }), _jsx(Text, { children: "Claude remains deferred/not installable in guided setup." }), _jsx(Text, { children: "No provider config will be written; use the manual next commands from the plan." })] }));
 }
 export function compactPath(path, width) {
     if (width <= 0 || path.length <= width)
@@ -81,7 +81,7 @@ export function compactPath(path, width) {
 export function wrapLabel(value, width) {
     if (width <= 0 || value.length <= width)
         return value;
-    const protectedPhrases = ['final confirmation', 'confirm and apply', 'read-only', 'requires confirmation', 'will write after confirm', 'error', 'cancelled'];
+    const protectedPhrases = ['final confirmation', 'confirm and apply', 'not installable', 'read-only', 'requires confirmation', 'will write after confirm', 'error', 'cancelled'];
     const phrase = protectedPhrases.find((candidate) => value.includes(candidate));
     if (phrase !== undefined)
         return `${value.slice(0, Math.max(0, width - phrase.length - 5)).trim()} ... ${phrase}`.trim();

package/dist/cli/tui/setup/screens/welcome-screen.js

@@ -2,5 +2,5 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from 'ink';
 import { Panel, SetupWorkspace, setupFooterHints } from './screen-components.js';
 export function WelcomeScreen(props) {
-    return (_jsx(SetupWorkspace, { title: "Detect", viewModel: props.viewModel, footer: [setupFooterHints.continue, setupFooterHints.help, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Safe local setup", children: [_jsx(Text, { children: "Setup welcome" }), _jsx(Text, { children: "VGXNESS Setup Assistant" }), _jsx(Text, { children: "Configure local storage and OpenCode integration with read-only previews first." }), _jsx(Text, { children: "No provider config is written until the final confirmation." })] }) }));
+    return (_jsx(SetupWorkspace, { title: "Detect", viewModel: props.viewModel, footer: [setupFooterHints.continue, setupFooterHints.help, setupFooterHints.cancel], children: _jsxs(Panel, { title: "Guided installation sequence", children: [_jsx(Text, { children: "Setup welcome: global memory \u2192 provider \u2192 OpenCode details \u2192 agent readiness \u2192 preview \u2192 final confirmation \u2192 doctor/restart." }), _jsx(Text, { children: "VGXNESS Setup Assistant" }), _jsx(Text, { children: "Configure local storage and OpenCode integration with read-only previews first." }), _jsx(Text, { children: "No provider config is written until the final confirmation." })] }) }));
 }

package/dist/cli/tui/setup/setup-tui-read-model.js

@@ -12,6 +12,8 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
     const workspaceRoot = plan?.workspaceRoot ?? status?.environment.workspaceRoot ?? 'pending workspace';
     const databasePath = plan?.db.path ?? status?.store.path ?? 'pending database path';
     const databaseSource = plan?.db.source ?? 'pending';
+    const memoryExplanation = memoryPathExplanation(plan, databasePath, databaseSource);
+    const agentReadiness = agentReadinessLabels(plan, status);
     const blockers = plan?.conflicts
         .filter((conflict) => conflict.severity === 'blocking')
         .map((conflict) => `${conflict.message}${conflict.recovery === undefined ? '' : ` Recovery: ${conflict.recovery}`}`) ?? [];
@@ -40,6 +42,12 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
             : 'Manual / none (no OpenCode install)',
         targetPathLabel: isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : 'No provider config target; manual/no-provider-write mode',
         opencodeActionLabel: isOpenCode ? opencodeActionLabel(opencode?.action) : 'No automatic provider write; use manual setup guidance.',
+        memoryPathExplanation: memoryExplanation,
+        providerInstallabilityLabel: isOpenCode
+            ? 'OpenCode is the only installable provider in this guided setup. Claude is deferred guidance only.'
+            : 'Manual / none is read-only guidance; no provider is installable from this selection. Claude is deferred guidance only.',
+        agentReadinessLabel: agentReadiness.label,
+        agentReadinessDetail: agentReadiness.detail,
         plannedActions: plan?.actions.map((action) => ({
             id: action.id,
             label: action.description,
@@ -65,7 +73,8 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
             choice('database:custom', 'Custom database path', 'Deferred/read-only in the TUI unless already supplied by flags or environment.', selections?.databaseMode === 'custom' || (selections === undefined && plan?.db.mode === 'custom'), state?.focusedChoiceId, [badgeLabels.deferred, badgeLabels.readOnly]),
         ],
         providerChoices: [
-            choice('provider:opencode', 'OpenCode', 'Primary supported provider for managed MCP setup.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
+            choice('provider:opencode', 'OpenCode', 'Only installable provider in this guided setup; writes still require final confirmation.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
+            choice('provider:claude-deferred', 'Claude (deferred)', 'Guidance only for now; not selectable and not installable in this setup flow.', false, state?.focusedChoiceId, [badgeLabels.deferred, badgeLabels.readOnly]),
             choice('provider:none', 'Manual / none', 'No automatic provider config write; follow manual setup guidance.', (selections?.provider ?? plan?.provider) === 'none', state?.focusedChoiceId, [badgeLabels.manual, badgeLabels.readOnly]),
         ],
         scopeChoices: isOpenCode
@@ -76,7 +85,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
             : [],
         installModeChoices: isOpenCode
             ? [
-                choice('install:mcp-plus-agents', 'MCP plus agents', 'Install VGXNESS MCP and bundled agent metadata after confirmation.', (selections?.installMode ?? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents')) === 'mcp-plus-agents', state?.focusedChoiceId, [badgeLabels.recommended, badgeLabels.writeAfterConfirm]),
+                choice('install:mcp-plus-agents', 'MCP plus agents', 'Install OpenCode MCP/agent entries after confirmation; local VGXNESS agent seeding is not done by preview screens.', (selections?.installMode ?? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents')) === 'mcp-plus-agents', state?.focusedChoiceId, [badgeLabels.recommended, badgeLabels.writeAfterConfirm]),
                 choice('install:mcp-only', 'MCP only', 'Install only the MCP server entry after confirmation.', (selections?.installMode ?? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents')) === 'mcp-only', state?.focusedChoiceId, [badgeLabels.writeAfterConfirm]),
             ]
             : [],
@@ -88,9 +97,12 @@ function previewDetailLines(input) {
     const actions = plan?.actions.map((action) => `Planned action: ${action.description}${action.targetPath === undefined ? '' : ` Target: ${compactPath(action.targetPath, 72)}`}${action.backupRequired ? ' Backup required.' : ''}`) ?? ['Planned action: create read-only preview plan.'];
     return [
         `Provider: ${input.provider === 'opencode' ? 'OpenCode [recommended]' : 'Manual / none [manual] [read-only]'}`,
-        `Database: ${plan?.db.mode ?? 'pending'} at ${compactPath(input.databasePath, 72)} (source: ${String(input.databaseSource)})`,
+        `Memory path: ${plan?.db.mode ?? 'pending'} at ${compactPath(input.databasePath, 72)} (source: ${String(input.databaseSource)})`,
+        `Memory guidance: ${memoryPathExplanation(plan, input.databasePath, input.databaseSource)}`,
         `Scope: ${input.isOpenCode ? (opencode?.scope ?? 'user') : 'disabled for manual/none provider'}`,
         `Install mode: ${input.isOpenCode ? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents') : 'disabled for manual/none provider'}`,
+        `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation; Claude deferred/not installable.' : 'No provider installable; OpenCode controls disabled and Claude deferred.'}`,
+        `Agent readiness: ${agentReadinessFromPlan(plan)}`,
         `Target config: ${input.isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : 'none; no provider config will be written'}`,
         `Safety: ${input.isOpenCode ? '[will write after confirm] only on final confirmation' : '[read-only] manual/no-provider-write mode'}`,
         ...actions,
@@ -109,10 +121,38 @@ function helpLines(screen) {
         'Next/back: Tab continues; Shift+Tab goes back. Enter continues on review and confirms only on final confirmation.',
         'Cancel/close: q or Esc cancels setup; when help is open, ?/h toggles it closed.',
         reviewLine,
-        'Provider support: OpenCode is [recommended]; Manual / none is [manual] [read-only] and writes no provider config.',
+        'Provider support: OpenCode is the only installable provider; Claude is [deferred] [read-only] guidance and Manual / none writes no provider config.',
+        'Agent readiness: the preview checks vgxness-manager/SDD readiness guidance; preview screens never seed agents.',
         'No-write guarantee: no provider config is written before explicit final confirmation.',
     ];
 }
+function memoryPathExplanation(plan, path, source) {
+    if (plan?.db.mode === 'project-local')
+        return `Project-local memory would use ${compactPath(path, 72)} for this workspace only; this preview creates no file.`;
+    if (plan?.db.mode === 'custom')
+        return `Custom memory path ${compactPath(path, 72)} is used only when supplied by flags or environment; this preview is read-only.`;
+    return `Global memory is the default local store at ${compactPath(path, 72)} (source: ${String(source)}), shared across VGXNESS projects unless a project/custom path is chosen.`;
+}
+function agentReadinessLabels(plan, status) {
+    const names = plan?.opencode?.agentNames.length === 0 ? ['vgxness-manager', 'SDD agents'] : (plan?.opencode?.agentNames ?? ['vgxness-manager', 'SDD agents']);
+    if (status?.agents.deferred === true)
+        return {
+            label: 'Agent readiness deferred',
+            detail: status.agents.nextAction ?? 'Select a project to check vgxness-manager and SDD agent readiness. No agent seeding occurs in preview.',
+        };
+    if (status?.agents.status === 'ready')
+        return { label: 'Agents ready', detail: `Required local agent context is ready for ${status.agents.agentName}; preview target agents: ${names.join(', ')}.` };
+    if (status?.agents.status === 'blocked')
+        return {
+            label: 'Agents need attention',
+            detail: `${status.agents.blocker ?? 'Required agents are not ready.'} Next: ${status.agents.nextAction ?? 'vgx agents seed --scope project'}`,
+        };
+    return { label: 'Agent readiness preview', detail: `Required agents: ${names.join(', ')}. Preview/status screens do not seed agents.` };
+}
+function agentReadinessFromPlan(plan) {
+    const names = plan?.opencode?.agentNames.length === 0 ? ['vgxness-manager', 'SDD agents'] : (plan?.opencode?.agentNames ?? ['vgxness-manager', 'SDD agents']);
+    return `preview required agents (${names.join(', ')}); no agent seeding on read-only screens`;
+}
 function choice(id, label, description, selected, focusedChoiceId, badges) {
     return { id, label, description, selected, focused: focusedChoiceId === undefined ? selected : focusedChoiceId === id, badges };
 }

package/dist/cli/tui/setup/setup-tui-render-shape.js

@@ -9,8 +9,8 @@ function screenLines(input, width) {
     switch (input.screen) {
         case 'welcome':
             return workspaceLines(vm, [
-                'Safe local setup',
-                'Setup welcome',
+                'Guided installation sequence',
+                'Setup welcome: global memory → provider → OpenCode details → agent readiness → preview → final confirmation → doctor/restart.',
                 'VGXNESS Setup Assistant',
                 'Configure local storage and OpenCode integration with read-only previews first.',
                 'No provider config is written until the final confirmation.',
@@ -25,11 +25,13 @@ function screenLines(input, width) {
                 `Mode: ${vm.databaseLabel}`,
                 `Path: ${compactPath(vm.databasePathLabel, width - 7)}`,
                 `Source: ${vm.databaseSourceLabel}`,
+                `Memory path explanation: ${vm.memoryPathExplanation}`,
             ], width, choiceFooter());
         case 'provider':
             return workspaceLines(vm, [
                 'Provider selection',
                 ...choiceLines(vm.providerChoices),
+                vm.providerInstallabilityLabel,
                 'OpenCode setup remains gated by final confirmation. Manual / none has no automatic install and no provider config will be written.',
             ], width, choiceFooter());
         case 'opencode-details':
@@ -42,11 +44,14 @@ function screenLines(input, width) {
                     `Install mode: ${vm.installModeLabel}`,
                     `Target config: ${compactPath(vm.targetPathLabel, width - 15)}`,
                     `Action: ${vm.opencodeActionLabel}`,
+                    `Agent readiness: ${vm.agentReadinessLabel}`,
+                    vm.agentReadinessDetail,
                     'Details are preview-only here; writes require final confirmation.',
                 ]
                 : [
                     'Manual / no-provider-write mode ' + badgeLabels.manual,
                     'OpenCode-only scope and install controls are disabled.',
+                    'Claude remains deferred/not installable; no provider config will be written.',
                     'No provider config will be written; use manual setup guidance.',
                 ], width, vm.providerLabel === 'OpenCode' ? choiceFooter() : [setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel]);
         case 'plan-review':
@@ -54,6 +59,8 @@ function screenLines(input, width) {
                 'Read-only plan review',
                 'Plan summary ' + badgeLabels.readOnly,
                 ...planLines(vm, width),
+                `Doctor next step: ${doctorCommand(vm)}`,
+                'Restart next step: Restart OpenCode after confirmed setup so it reloads MCP configuration.',
                 'Review only: this screen does not write provider config.',
                 vm.canAutoApply ? 'Press Enter to continue to final confirmation.' : 'Manual setup required; no automatic apply is available.',
             ], width, [setupFooterHints.finalConfirmation, setupFooterHints.back, setupFooterHints.cancel]);
@@ -64,6 +71,7 @@ function screenLines(input, width) {
                 'Confirm OpenCode setup',
                 ...planLines(vm, width),
                 'WARNING: OpenCode provider config may be modified at the target path above. Existing config is backed up when planned.',
+                'After confirmation: run doctor, then restart OpenCode to reload MCP configuration.',
                 'Press Enter to confirm and apply OpenCode setup, or Esc/q to cancel without writing.',
             ], width, [setupFooterHints.confirmApply, setupFooterHints.back, setupFooterHints.cancel]);
         case 'applying':
@@ -80,7 +88,7 @@ function screenLines(input, width) {
                 footer([setupFooterHints.close], width),
             ];
         case 'cancelled':
-            return ['Setup cancelled', badgeLabels.cancelled, 'Setup was not completed.', 'No provider config was written.', footer([setupFooterHints.close], width)];
+            return ['Setup cancelled', badgeLabels.cancelled, 'Setup was not completed.', 'No provider config was written.', 'No agent seeding was performed.', footer([setupFooterHints.close], width)];
     }
 }
 function planLines(vm, width) {
@@ -91,6 +99,9 @@ function planLines(vm, width) {
         `Database path: ${compactPath(vm.databasePathLabel, width - 15)}`,
         `OpenCode scope: ${vm.scopeLabel}`,
         `Install mode: ${vm.installModeLabel}`,
+        `Provider installability: ${vm.providerInstallabilityLabel}`,
+        `Agent readiness: ${vm.agentReadinessLabel}`,
+        `Agent detail: ${vm.agentReadinessDetail}`,
         `Target config: ${compactPath(vm.targetPathLabel, width - 15)}`,
         vm.backupLabel,
         ...vm.plannedActions.map((action) => `Action: ${action.safetyBadge} ${action.label}${action.targetPathLabel === undefined ? '' : ` (${compactPath(action.targetPathLabel, width - 12)})`}`),
@@ -129,6 +140,7 @@ function resultLines(result, vm, width) {
             `Target config: ${compactPath(result.targetPath, width - 15)}`,
             result.backupPath === undefined ? 'Backup: none created' : `Backup: ${compactPath(result.backupPath, width - 8)}`,
             ...result.warnings.map((warning) => `Warning: ${warning}`),
+            ...resultNextCommands(vm).map((command) => `Next: ${command}`),
             footer([setupFooterHints.close], width),
         ];
     if (result?.status === 'manual-required')
@@ -141,6 +153,14 @@ function resultLines(result, vm, width) {
         ];
     return ['Setup result', 'No provider config write occurred.', footer([setupFooterHints.close], width)];
 }
+function resultNextCommands(vm) {
+    const filtered = vm.nextCommands.filter((command) => !/^vgx(?:ness)? setup apply\b/.test(command));
+    const withDoctor = filtered.some((command) => /\bdoctor\b/.test(command)) ? filtered : [...filtered, 'vgx doctor'];
+    return withDoctor.some((command) => /Restart OpenCode/i.test(command)) ? withDoctor : [...withDoctor, 'Restart OpenCode and verify the vgxness MCP server is visible.'];
+}
+function doctorCommand(vm) {
+    return vm.nextCommands.find((command) => /\bdoctor\b/.test(command)) ?? 'vgx doctor';
+}
 function footer(hints, width) {
     return formatFooter(hints, width);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {