vgxness 1.1.0 → 1.2.0

package/README.md

@@ -58,7 +58,7 @@ npm run probe:bun
 npm run probe:bun -- --yes   # mutates dependencies only after explicit consent
 ```
 
-Runtime SQLite readiness is proven with `bun:sqlite`. `bun run verify:bun-sqlite` copies the source migrations into a temporary directory, applies them against a temporary database, checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup. `bun run verify:node-sqlite` remains optional Node native-binding tooling coverage only.
+Runtime SQLite readiness is proven only with `bun:sqlite`. `bun run verify:bun-sqlite` copies the source migrations into a temporary directory, applies them against a temporary database, checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup. Node.js remains development/build/test tooling, but real local SQLite storage is supported through the Bun runtime path.
 
 #### Bun package evidence
 

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/dist/mcp/doctor.js

@@ -66,7 +66,7 @@ async function runRealMcpSmoke(options) {
     const client = new Client({ name: 'vgxness-doctor', version: '0.1.0' }, { capabilities: {} });
     const invocation = resolveDoctorCliInvocation(options.databasePath);
     const transport = new StdioClientTransport({
-        command: process.execPath,
+        command: invocation.command,
         args: invocation.args,
         cwd: options.cwd,
         stderr: 'pipe',
@@ -173,11 +173,17 @@ function parseMcpToolResult(result) {
         return { ok: false, error: { code: 'validation_failed', message: 'MCP response did not contain text JSON' } };
     return JSON.parse(text);
 }
-export function resolveDoctorCliInvocation(databasePath, moduleUrl = import.meta.url) {
+export function resolveDoctorCliInvocation(databasePath, moduleUrl = import.meta.url, options = {}) {
+    const runtime = options.runtime ?? currentRuntime();
     const builtCliPath = fileURLToPath(new URL('../cli/index.js', moduleUrl));
     if (existsSync(builtCliPath))
-        return { args: [builtCliPath, 'mcp', 'start', '--db', databasePath] };
-    return { args: ['--import', import.meta.resolve('tsx'), cliSourcePath(moduleUrl), 'mcp', 'start', '--db', databasePath] };
+        return { command: process.execPath, args: [builtCliPath, 'mcp', 'start', '--db', databasePath] };
+    if (runtime === 'bun')
+        return { command: process.execPath, args: [cliSourcePath(moduleUrl), 'mcp', 'start', '--db', databasePath] };
+    return { command: process.execPath, args: ['--import', import.meta.resolve('tsx'), cliSourcePath(moduleUrl), 'mcp', 'start', '--db', databasePath] };
+}
+function currentRuntime() {
+    return typeof globalThis.Bun === 'undefined' ? 'node' : 'bun';
 }
 function cliSourcePath(moduleUrl) {
     return fileURLToPath(new URL('../cli/index.ts', moduleUrl));

package/dist/memory/sqlite/database.js

@@ -1,17 +1,10 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const migrationsDirectory = join(dirname(fileURLToPath(import.meta.url)), 'migrations');
 export const sqliteBusyTimeoutMs = 5000;
-const nativeBindingDiagnosticGuidance = 'Detected a likely better-sqlite3 native binding problem. Ensure npm install scripts are enabled, then rebuild or reinstall dependencies for the active Node.js version (for example: npm rebuild better-sqlite3 --ignore-scripts=false).';
-const nativeBindingFailurePatterns = [
-    /better_sqlite3\.node/i,
-    /better-sqlite3/i,
-    /NODE_MODULE_VERSION/i,
-    /ERR_DLOPEN_FAILED/i,
-    /Could not locate the bindings file/i,
-    /compiled against a different Node\.js version/i,
-];
+const bunRequiredGuidance = 'Real local SQLite storage requires Bun. Use the installed Bun-backed vgxness/vgx runtime, or run Bun storage verification with bun run verify:bun-sqlite.';
 export class MemoryDatabase {
     connection;
     constructor(connection) {
@@ -99,39 +92,37 @@ export function openMemoryDatabase(options) {
 }
 export function buildMemoryStoreUnavailableMessage(path, cause) {
     const message = `Unable to open local memory store at ${path}`;
-    if (!isLikelyBetterSqlite3NativeBindingFailure(cause))
+    if (!isUnsupportedSqliteRuntimeError(cause))
         return message;
-    return `${message}. ${nativeBindingDiagnosticGuidance}`;
+    return `${message}. ${bunRequiredGuidance}`;
 }
-export function isLikelyBetterSqlite3NativeBindingFailure(cause) {
-    const values = collectDiagnosticValues(cause);
-    return values.some((value) => nativeBindingFailurePatterns.some((pattern) => pattern.test(value)));
-}
-const sqliteDriver = await resolveSqliteDriver();
 function openSqliteConnection(options) {
-    return sqliteDriver(options);
+    return resolveSqliteDriver()(options);
 }
-async function resolveSqliteDriver() {
+function resolveSqliteDriver() {
     if (isBunRuntime())
         return resolveBunSqliteDriver();
-    return resolveBetterSqlite3Driver();
+    throw createUnsupportedSqliteRuntimeError();
 }
 function isBunRuntime() {
     return typeof globalThis.Bun !== 'undefined';
 }
-async function resolveBetterSqlite3Driver() {
-    const module = await import('better-sqlite3');
-    const BetterSqlite3Database = module.default;
-    return (options) => new BetterSqlite3Database(options.path, { readonly: options.readonly ?? false });
-}
-async function resolveBunSqliteDriver() {
-    const bunSqliteSpecifier = 'bun:sqlite';
-    const module = (await import(bunSqliteSpecifier));
+function resolveBunSqliteDriver() {
+    const require = createRequire(import.meta.url);
+    const module = require('bun:sqlite');
     const BunDatabase = module.Database;
     if (typeof BunDatabase !== 'function')
         throw new Error('bun:sqlite Database constructor is unavailable');
     return (options) => createBunSqliteConnection(new BunDatabase(options.path, { readonly: options.readonly ?? false, strict: true }));
 }
+function createUnsupportedSqliteRuntimeError() {
+    const error = new Error(bunRequiredGuidance);
+    error.name = 'UnsupportedSqliteRuntimeError';
+    return error;
+}
+function isUnsupportedSqliteRuntimeError(cause) {
+    return cause instanceof Error && cause.name === 'UnsupportedSqliteRuntimeError';
+}
 function createBunSqliteConnection(database) {
     const record = database;
     return {
@@ -139,7 +130,7 @@ function createBunSqliteConnection(database) {
             const prepare = record.prepare;
             if (typeof prepare !== 'function')
                 throw new Error('bun:sqlite prepare() is unavailable');
-            return prepare.call(database, sql);
+            return createBunSqliteStatement(prepare.call(database, sql));
         },
         exec(sql) {
             const exec = record.exec;
@@ -174,6 +165,30 @@ function createBunSqliteConnection(database) {
         },
     };
 }
+function createBunSqliteStatement(statement) {
+    const record = statement;
+    return {
+        get(...params) {
+            const get = record.get;
+            if (typeof get !== 'function')
+                throw new Error('bun:sqlite statement.get() is unavailable');
+            const row = get.call(statement, ...params);
+            return row === null ? undefined : row;
+        },
+        all(...params) {
+            const all = record.all;
+            if (typeof all !== 'function')
+                throw new Error('bun:sqlite statement.all() is unavailable');
+            return all.call(statement, ...params);
+        },
+        run(...params) {
+            const run = record.run;
+            if (typeof run !== 'function')
+                throw new Error('bun:sqlite statement.run() is unavailable');
+            return run.call(statement, ...params);
+        },
+    };
+}
 function runBunPragma(database, statement) {
     const normalizedStatement = statement.trim();
     if (isPragmaSetter(normalizedStatement)) {
@@ -211,26 +226,3 @@ function migrationFailure(message, cause) {
         error.cause = cause;
     return { ok: false, error };
 }
-function collectDiagnosticValues(value, seen = new Set()) {
-    if (value === undefined || value === null)
-        return [];
-    if (typeof value === 'string')
-        return [value];
-    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol')
-        return [String(value)];
-    if (typeof value !== 'object')
-        return [];
-    if (seen.has(value))
-        return [];
-    seen.add(value);
-    const diagnosticValues = [];
-    const record = value;
-    for (const key of ['code', 'message', 'stack', 'name']) {
-        const property = record[key];
-        if (property !== undefined)
-            diagnosticValues.push(...collectDiagnosticValues(property, seen));
-    }
-    if (record.cause !== undefined)
-        diagnosticValues.push(...collectDiagnosticValues(record.cause, seen));
-    return diagnosticValues;
-}

package/docs/cli.md

@@ -77,12 +77,13 @@ bun install --frozen-lockfile
 bun run check:bun-lock
 bun run verify:typecheck
 bun run verify:test
+bun run verify:test:bun-storage
 bun run verify:bun-sqlite
 bun run verify:package
 bun run package:bun:evidence -- --require-pass
 ```
 
-`bun run verify:bun-sqlite` is the SQLite runtime release gate. It uses `bun:sqlite` against a temporary database, copies/applies the source migrations, and checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup. `bun run verify:node-sqlite` is optional Node native-binding tooling coverage only.
+`bun run verify:bun-sqlite` is the SQLite runtime release gate. It uses `bun:sqlite` against a temporary database, copies/applies the source migrations, and checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup. `bun run verify:test:bun-storage` covers storage-backed tests under Bun. Node.js remains development/build/test tooling, but real local SQLite storage is supported through the Bun runtime path.
 
 Keep lockfile changes intentional: when `package.json` dependency specifiers change, refresh and review the root `bun.lock` diff. The read-only drift check does not run `bun install` and does not mutate `node_modules`:
 

package/docs/funcionamiento-del-sistema.md

@@ -43,13 +43,12 @@ Esa capa no reemplaza a OpenCode, Claude Code o futuros adapters. Los coordina.
 
 ## Como esta construido
 
-El proyecto esta escrito en TypeScript y corre sobre Node.js 22 o superior.
+El proyecto esta escrito en TypeScript. Node.js 22 o superior sigue siendo tooling de desarrollo/build/tests; la persistencia local real en SQLite corre por el runtime Bun soportado.
 
 Dependencias principales:
 
 | Dependencia | Uso |
 |---|---|
-| `better-sqlite3` | Persistencia local en SQLite. |
 | `@modelcontextprotocol/sdk` | Servidor MCP por stdio. |
 | `zod` | Validacion de schemas de entrada. |
 | `tsx` | Ejecucion TypeScript en desarrollo. |
@@ -135,9 +134,9 @@ Archivo clave:
 src/memory/sqlite/database.ts
 ```
 
-Al abrir la base, el sistema:
+Al abrir la base con el runtime Bun, el sistema:
 
-1. Crea una conexion con `better-sqlite3`.
+1. Crea una conexion SQLite usando `bun:sqlite`.
 2. Activa `foreign_keys`.
 3. Configura `busy_timeout`.
 4. Aplica migraciones SQL si la base no esta en modo readonly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.1.0",
+  "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": {
@@ -22,12 +22,12 @@
   "scripts": {
     "cli": "tsx src/cli/index.ts",
     "build": "tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
-    "verify": "bun run verify:typecheck && bun run verify:test && bun run verify:bun-sqlite && bun run verify:package",
+    "verify": "bun run verify:typecheck && bun run verify:test && bun run verify:test:bun-storage && bun run verify:bun-sqlite && bun run verify:package",
     "verify:typecheck": "tsc --noEmit",
-    "verify:test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "verify:test": "node scripts/run-node-tests.mjs",
+    "verify:test:bun-storage": "node scripts/run-bun-storage-tests.mjs",
     "verify:package": "bun run package:bun:evidence",
     "verify:bun-sqlite": "bun scripts/probe-bun-sqlite.mjs",
-    "verify:node-sqlite": "node scripts/probe-native-sqlite.mjs",
     "ci:bun": "bun run check:bun-lock && bun run verify",
     "check:bun-lock": "node scripts/check-bun-lock.mjs",
     "check:vgxcode:bun-lock": "node scripts/check-bun-lock.mjs --package-json packages/vgxcode/package.json --bun-lock packages/vgxcode/bun.lock",
@@ -36,7 +36,7 @@
     "probe:bun-runtime": "node scripts/probe-bun-runtime-cli-mcp.mjs",
     "verify:bun-runtime": "node scripts/probe-bun-runtime-cli-mcp.mjs --require-pass",
     "package:bun:evidence": "node scripts/probe-bun-package-evidence.mjs",
-    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "test": "node scripts/run-node-tests.mjs",
     "typecheck": "tsc --noEmit"
   },
   "bin": {
@@ -58,10 +58,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.18",
     "@types/react": "^19.2.15",
-    "better-sqlite3": "^12.10.0",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3"
   },