vgxness 1.4.0 → 1.5.0

package/dist/cli/cli-help.js

@@ -57,13 +57,14 @@ Areas:
   Approval commands resolve explicit run/preflight approval records; they do not change agent seed permissions or globally allow shell/provider access.
 
   mcp setup --preview --provider opencode|claude [--db <path>]
-  mcp install opencode --plan [--scope user|project] [--db <path>] [--mcp-only|--no-agents]
-  mcp install opencode --yes [--scope user|project] [--db <path>] [--mcp-only|--no-agents]
+  mcp install opencode --plan [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install opencode --yes [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
   mcp doctor opencode [--scope user|project] [--project-root <path>]
   mcp doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>]
   MCP setup preview is read-only; it does not install or write .opencode/, .claude/, or provider config.
   Without --db, MCP install and setup commands use the vgxness global default database; pass --db .vgx/memory.sqlite for project-local compatibility.
   OpenCode install defaults to user/global scope and installs mcp.vgxness plus vgxness-manager and hidden vgxness-sdd-* agents; use --mcp-only for legacy MCP-only config.
+  Use --overwrite-vgxness (alias --reinstall) to reinstall only VGXNESS-managed OpenCode entries while preserving unrelated config; --yes is still required to write.
   It writes only after --yes. The default target is $HOME/.config/opencode/opencode.json; use --scope project to target .opencode/opencode.json explicitly.
   Project OpenCode config can override user config. Plans are read-only; applies refuse unsafe existing config and create backups before merge.
 

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

@@ -19,6 +19,7 @@ export function runMcpInstallCommand(parsed, environment) {
         if (!scope.ok)
             return resultFailure(scope);
         const mcpOnly = parsed.flags['mcp-only'] === true || parsed.flags['no-agents'] === true;
+        const overwriteVgxness = parsed.flags['overwrite-vgxness'] === true || parsed.flags.reinstall === true;
         if (parsed.flags.plan === true) {
             return jsonResult({
                 ok: true,
@@ -29,6 +30,7 @@ export function runMcpInstallCommand(parsed, environment) {
                     scope: scope.value,
                     env: environment.env,
                     mcpOnly,
+                    overwriteVgxness,
                 }),
             });
         }
@@ -40,6 +42,7 @@ export function runMcpInstallCommand(parsed, environment) {
             env: environment.env,
             confirmed: parsed.flags.yes === true,
             mcpOnly,
+            overwriteVgxness,
         });
         return result.status === 'installed'
             ? jsonResult({ ok: true, value: result })

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

@@ -143,6 +143,7 @@ export async function applySetupPlanInput(input, environment) {
         env: environment.env,
         confirmed: true,
         mcpOnly: input.installMode === 'mcp-only',
+        ...(input.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.overwriteVgxness }),
     });
     return result.status === 'installed'
         ? {
@@ -172,6 +173,7 @@ export function setupPlanInputFromFlags(parsed, environment) {
     const installMode = setupInstallModeFlag(parsed.flags);
     if (!installMode.ok)
         return installMode;
+    const overwriteVgxness = parsed.flags['overwrite-vgxness'] === true || parsed.flags.reinstall === true;
     return {
         ok: true,
         value: {
@@ -183,6 +185,7 @@ export function setupPlanInputFromFlags(parsed, environment) {
             provider: provider.value,
             scope: scope.value,
             installMode: installMode.value,
+            overwriteVgxness,
         },
     };
 }
@@ -196,6 +199,7 @@ function defaultWizardInput(environment) {
         provider: vgxnessSetupDefaults.defaultProvider,
         scope: vgxnessSetupDefaults.defaultOpenCodeScope,
         installMode: vgxnessSetupDefaults.defaultInstallMode,
+        overwriteVgxness: false,
     };
 }
 function defaulted(value, fallback) {
@@ -281,6 +285,8 @@ export function promptSetupWizard(environment, defaults) {
                 : undefined;
         if (installMode === undefined)
             return validationFailure('Install mode must be MCP + manager/SDD agents or MCP only.');
+        const overwriteText = defaulted(await promptLine(environment, 'Reinstall VGXNESS entries: overwrite existing mcp.vgxness and VGXNESS agents after final confirmation; preserve unrelated OpenCode config [no]: '), 'no');
+        const overwriteVgxness = overwriteText.toLowerCase() === 'yes' || overwriteText.toLowerCase() === 'y' || overwriteText.toLowerCase() === 'true';
         const input = {
             project,
             workspaceRoot: environment.cwd,
@@ -290,6 +296,7 @@ export function promptSetupWizard(environment, defaults) {
             provider,
             scope,
             installMode,
+            overwriteVgxness,
         };
         const flags = {
             project,
@@ -298,6 +305,7 @@ export function promptSetupWizard(environment, defaults) {
             scope,
             mode: installMode,
             yes: true,
+            ...(overwriteVgxness ? { 'overwrite-vgxness': true } : {}),
             ...(databasePath === undefined ? {} : { 'db-path': databasePath }),
         };
         return { ok: true, value: { input, flags } };
@@ -355,6 +363,7 @@ export async function runSetupTuiCommand(environment, input) {
             provider: vgxnessSetupDefaults.defaultProvider,
             scope: vgxnessSetupDefaults.defaultOpenCodeScope,
             installMode: vgxnessSetupDefaults.defaultInstallMode,
+            overwriteVgxness: false,
         },
     };
     try {

package/dist/cli/setup-plan-renderer.js

@@ -23,6 +23,7 @@ function renderOpenCode(plan) {
         `- Action: ${plan.opencode.action}`,
         `- Target path: ${target}`,
         `- Installs agents: ${String(plan.opencode.installsAgents)}`,
+        `- Reinstall VGXNESS entries: ${String(plan.opencode.overwriteVgxness)}`,
         `- Agent names: ${plan.opencode.agentNames.length === 0 ? 'none' : plan.opencode.agentNames.join(', ')}`,
     ];
 }

package/dist/cli/tui/setup/setup-tui-controller.js

@@ -59,20 +59,24 @@ function canApplyCurrentState(previous, reduced) {
     if (plan?.provider !== 'opencode' || plan.status !== 'ready' || plan.opencode === undefined)
         return false;
     const installMode = plan.opencode.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents';
-    return plan.opencode.scope === reduced.selections.scope && installMode === reduced.selections.installMode;
+    return (plan.opencode.scope === reduced.selections.scope &&
+        installMode === reduced.selections.installMode &&
+        (plan.opencode.overwriteVgxness === true) === (reduced.selections.overwriteVgxness === true));
 }
 function shouldRefreshPlan(previous, next, action) {
     if (action.type !== 'select-focused-choice' &&
         action.type !== 'select-database-mode' &&
         action.type !== 'select-provider' &&
         action.type !== 'select-scope' &&
-        action.type !== 'select-install-mode')
+        action.type !== 'select-install-mode' &&
+        action.type !== 'toggle-overwrite-vgxness')
         return false;
     return (previous.selections.databaseMode !== next.selections.databaseMode ||
         previous.selections.databasePath !== next.selections.databasePath ||
         previous.selections.provider !== next.selections.provider ||
         previous.selections.scope !== next.selections.scope ||
-        previous.selections.installMode !== next.selections.installMode);
+        previous.selections.installMode !== next.selections.installMode ||
+        (previous.selections.overwriteVgxness === true) !== (next.selections.overwriteVgxness === true));
 }
 function refreshPlan(state, services, runtime) {
     const plan = services.createPlan(setupPlanInputFromTui(runtime));

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

@@ -59,7 +59,9 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         backupLabel: backups.length === 0 ? 'Backup: none planned' : `Backup planned: ${backups.join('; ')}`,
         nextCommands: plan?.nextCommands ?? ['vgxness setup plan'],
         canAutoApply: plan?.provider === 'opencode' && plan.status === 'ready' && state?.selections.provider !== 'none' && plan.opencode !== undefined,
-        safetyWarning: 'Final confirmation is required before any provider config write. OpenCode config may be modified and backed up.',
+        safetyWarning: isOpenCode && (selections?.overwriteVgxness === true || opencode?.overwriteVgxness === true)
+            ? 'Final confirmation is required. Reinstall is enabled: VGXNESS OpenCode entries will be overwritten after a managed backup when the target exists; unrelated config is preserved.'
+            : 'Final confirmation is required before any provider config write. OpenCode config may be modified and backed up.',
         frameLabel: 'VGXNESS Setup Assistant workspace',
         progressLabel: progressLabel(state?.screen),
         previewLabel,
@@ -89,6 +91,11 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
                 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]),
             ]
             : [],
+        overwriteChoices: isOpenCode
+            ? [
+                choice('overwrite:vgxness', 'Reinstall VGXNESS entries', 'Default off. When enabled, final confirmation overwrites existing VGXNESS OpenCode entries and preserves unrelated OpenCode config.', selections?.overwriteVgxness ?? opencode?.overwriteVgxness ?? false, state?.focusedChoiceId, [badgeLabels.warning, badgeLabels.writeAfterConfirm]),
+            ]
+            : [],
     };
 }
 function previewDetailLines(input) {
@@ -101,6 +108,7 @@ function previewDetailLines(input) {
         `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'}`,
+        `Reinstall VGXNESS entries: ${input.isOpenCode ? String(opencode?.overwriteVgxness ?? false) : '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'}`,

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

@@ -40,6 +40,7 @@ function screenLines(input, width) {
                     'OpenCode plan ' + badgeLabels.writeAfterConfirm,
                     ...choiceLines(vm.scopeChoices),
                     ...choiceLines(vm.installModeChoices),
+                    ...choiceLines(vm.overwriteChoices),
                     `Scope: ${vm.scopeLabel}`,
                     `Install mode: ${vm.installModeLabel}`,
                     `Target config: ${compactPath(vm.targetPathLabel, width - 15)}`,
@@ -70,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.',
+                vm.safetyWarning,
                 '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]);
@@ -98,6 +100,7 @@ function planLines(vm, width) {
         `Database path: ${compactPath(vm.databasePathLabel, width - 15)}`,
         `OpenCode scope: ${vm.scopeLabel}`,
         `Install mode: ${vm.installModeLabel}`,
+        vm.safetyWarning,
         `Provider installability: ${vm.providerInstallabilityLabel}`,
         `Agent readiness: ${vm.agentReadinessLabel}`,
         `Agent detail: ${vm.agentReadinessDetail}`,

package/dist/cli/tui/setup/setup-tui-services.js

@@ -11,6 +11,7 @@ export function setupPlanInputFromTui(input) {
         provider: input.selections.provider,
         scope: input.selections.scope,
         installMode: input.selections.installMode,
+        ...(input.selections.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.selections.overwriteVgxness }),
     };
 }
 export function createDefaultSetupTuiServices(input) {
@@ -44,6 +45,7 @@ export async function applySetupTuiPlan(planInput, runtime) {
         env: runtime.env,
         confirmed: true,
         mcpOnly: planInput.installMode === 'mcp-only',
+        ...(planInput.overwriteVgxness === undefined ? {} : { overwriteVgxness: planInput.overwriteVgxness }),
     });
     if (installed.status !== 'installed')
         return { ok: false, error: { code: 'validation_failed', message: `${installed.reason}: ${installed.message}` } };

package/dist/cli/tui/setup/setup-tui-state.js

@@ -4,7 +4,7 @@ const screenChoiceIds = {
     welcome: [],
     'project-database': ['database:global', 'database:project-local', 'database:custom'],
     provider: ['provider:opencode', 'provider:none'],
-    'opencode-details': ['scope:project', 'scope:user', 'install:mcp-plus-agents', 'install:mcp-only'],
+    'opencode-details': ['scope:project', 'scope:user', 'install:mcp-plus-agents', 'install:mcp-only', 'overwrite:vgxness'],
     'plan-review': [],
     'final-confirmation': [],
     applying: [],
@@ -20,6 +20,7 @@ export function createSetupTuiState(input = {}) {
             provider: vgxnessSetupDefaults.defaultProvider,
             scope: vgxnessSetupDefaults.defaultOpenCodeScope,
             installMode: vgxnessSetupDefaults.defaultInstallMode,
+            overwriteVgxness: false,
         },
         ...(input.focusedChoiceId === undefined ? {} : { focusedChoiceId: input.focusedChoiceId }),
         helpVisible: input.helpVisible ?? false,
@@ -55,6 +56,8 @@ export function reduceSetupTuiState(state, action) {
             return { ...state, selections: { ...state.selections, scope: action.scope } };
         case 'select-install-mode':
             return { ...state, selections: { ...state.selections, installMode: action.installMode } };
+        case 'toggle-overwrite-vgxness':
+            return { ...state, selections: { ...state.selections, overwriteVgxness: state.selections.overwriteVgxness !== true } };
         case 'refresh-plan-start':
             return { ...state, previewRefresh: 'refreshing' };
         case 'refresh-plan-success':
@@ -131,6 +134,8 @@ function selectFocusedChoice(state) {
             return reduceSetupTuiState(state, { type: 'select-install-mode', installMode: 'mcp-plus-agents' });
         case 'install:mcp-only':
             return reduceSetupTuiState(state, { type: 'select-install-mode', installMode: 'mcp-only' });
+        case 'overwrite:vgxness':
+            return reduceSetupTuiState(state, { type: 'toggle-overwrite-vgxness' });
         default:
             return state;
     }
@@ -154,7 +159,9 @@ function canAutoApplyFromState(state) {
     if (state.plan?.provider !== 'opencode' || state.plan.status !== 'ready' || state.plan.opencode === undefined)
         return false;
     const installMode = state.plan.opencode.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents';
-    return state.plan.opencode.scope === state.selections.scope && installMode === state.selections.installMode;
+    return (state.plan.opencode.scope === state.selections.scope &&
+        installMode === state.selections.installMode &&
+        (state.plan.opencode.overwriteVgxness === true) === (state.selections.overwriteVgxness === true));
 }
 function advance(state) {
     const index = setupTuiScreenOrder.indexOf(state.screen);

package/dist/mcp/client-install-opencode-contract.js

@@ -33,8 +33,9 @@ export function planOpenCodeMcpInstall(input) {
     const agentPlan = createOpenCodeDefaultAgentInstallPlan({
         mcpOnly: input.mcpOnly,
     });
+    const overwriteVgxness = input.overwriteVgxness === true;
     if (scope === 'user') {
-        return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan);
+        return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness);
     }
     const existingTargets = supportedConfigTargets
         .map((relativePath) => ({
@@ -48,11 +49,11 @@ export function planOpenCodeMcpInstall(input) {
                 kind: 'manual-check',
                 message: 'Remove ambiguity by keeping exactly one OpenCode project config target before installing.',
             },
-        ], agentPlan);
+        ], agentPlan, overwriteVgxness);
     }
     if (existingTargets.length === 0) {
         return {
-            ...baseContract(input.databasePath, databasePathSource, scope, join(input.cwd, '.opencode', 'opencode.json'), false, 'create', agentPlan),
+            ...baseContract(input.databasePath, databasePathSource, scope, join(input.cwd, '.opencode', 'opencode.json'), false, 'create', agentPlan, overwriteVgxness),
             status: 'would_install',
             action: 'create',
             targetPath: join(input.cwd, '.opencode', 'opencode.json'),
@@ -64,31 +65,34 @@ export function planOpenCodeMcpInstall(input) {
     }
     const [target] = existingTargets;
     if (target === undefined)
-        return refusal('ambiguous_target', 'Unable to resolve OpenCode project config target.', input.databasePath, databasePathSource, scope);
+        return refusal('ambiguous_target', 'Unable to resolve OpenCode project config target.', input.databasePath, databasePathSource, scope, undefined, [], undefined, overwriteVgxness);
     if (target.relativePath.endsWith('.jsonc')) {
-        return refusal('unsupported_jsonc', `OpenCode JSONC config ${target.relativePath} is not supported yet; use JSON or remove comments first.`, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+        return refusal('unsupported_jsonc', `OpenCode JSONC config ${target.relativePath} is not supported yet; use JSON or remove comments first.`, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
     const parsed = parseConfig(target.absolutePath);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     const config = parsed.value;
     if (config.mcp !== undefined && !isRecord(config.mcp)) {
-        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
-    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness')) {
-        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness') && !overwriteVgxness) {
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
     const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
-    if (agentConflict.length > 0) {
+    if (agentConflict.length > 0 && !overwriteVgxness) {
         return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${agentConflict.join(', ')}. Remove, rename, or manually reconcile them before installing.`, input.databasePath, databasePathSource, scope, target.absolutePath, [
             {
                 kind: 'manual-check',
                 message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.`,
             },
-        ], agentPlan);
+        ], agentPlan, overwriteVgxness);
+    }
+    if (agentPlan.installsAgents && config.agent !== undefined && !isRecord(config.agent)) {
+        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness);
     }
     return {
-        ...baseContract(input.databasePath, databasePathSource, scope, target.absolutePath, true, 'merge-preserve-existing', agentPlan),
+        ...baseContract(input.databasePath, databasePathSource, scope, target.absolutePath, true, 'merge-preserve-existing', agentPlan, overwriteVgxness),
         status: 'would_install',
         action: 'merge',
         targetPath: target.absolutePath,
@@ -98,22 +102,22 @@ export function planOpenCodeMcpInstall(input) {
         existingSchema: typeof config.$schema === 'string' ? config.$schema : opencodeConfigSchema,
     };
 }
-function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan) {
+function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness) {
     const target = resolveOpenCodeMcpInstallTarget({
         cwd: input.cwd,
         scope: 'user',
         env: input.env,
     });
     if (!target.ok) {
-        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user');
+        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user', undefined, [], undefined, overwriteVgxness);
     }
     const jsoncPath = `${target.path}c`;
     if (existsSync(jsoncPath)) {
-        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan);
+        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan, overwriteVgxness);
     }
     if (!existsSync(target.path)) {
         return {
-            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan),
+            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan, overwriteVgxness),
             status: 'would_install',
             action: 'create',
             targetPath: target.path,
@@ -125,25 +129,28 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
     }
     const parsed = parseConfig(target.path);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     const config = parsed.value;
     if (config.mcp !== undefined && !isRecord(config.mcp)) {
-        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     }
-    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness')) {
-        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness') && !overwriteVgxness) {
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     }
     const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
-    if (agentConflict.length > 0) {
+    if (agentConflict.length > 0 && !overwriteVgxness) {
         return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${agentConflict.join(', ')}. Remove, rename, or manually reconcile them before installing.`, input.databasePath, databasePathSource, 'user', target.path, [
             {
                 kind: 'manual-check',
                 message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.`,
             },
-        ], agentPlan);
+        ], agentPlan, overwriteVgxness);
+    }
+    if (agentPlan.installsAgents && config.agent !== undefined && !isRecord(config.agent)) {
+        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness);
     }
     return {
-        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan),
+        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan, overwriteVgxness),
         status: 'would_install',
         action: 'merge',
         targetPath: target.path,
@@ -206,7 +213,7 @@ function deepEqual(left, right) {
     const rightKeys = Object.keys(right).sort();
     return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index] && deepEqual(left[key], right[key]));
 }
-function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
+function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false) {
     return {
         version: 1,
         kind: 'mcp-client-install-opencode',
@@ -221,16 +228,17 @@ function baseContract(databasePath, source, scope, targetPath, backupRequired, m
             mergePolicy,
         },
         scope,
-        warnings: warningsForScope(scope),
+        warnings: warningsForScope(scope, overwriteVgxness, agentPlan),
         verificationHints: verificationHints(databasePath, source),
         manualTest: manualTestForScope(scope, databasePath, source),
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
+        overwriteVgxness,
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
-function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
-    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan);
+function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false) {
+    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan, overwriteVgxness);
     return {
         ...contract,
         verificationHints: [...extraVerificationHints, ...contract.verificationHints],
@@ -240,12 +248,18 @@ function refusal(reason, message, databasePath, source, scope, targetPath, extra
         ...(targetPath !== undefined ? { targetPath } : {}),
     };
 }
-function warningsForScope(scope) {
+function warningsForScope(scope, overwriteVgxness, agentPlan) {
+    const overwriteWarnings = overwriteVgxness
+        ? [
+            `Reinstall/overwrite is enabled: existing VGXNESS-managed OpenCode entries will be replaced (${agentPlan.installsAgents ? 'mcp.vgxness, default_agent, instructions AGENTS.md, and known VGXNESS agents' : 'mcp.vgxness only'}); unrelated OpenCode config is preserved.`,
+        ]
+        : [];
     if (scope === 'project')
-        return ['Restart OpenCode after installation so it reloads the project MCP config.'];
+        return ['Restart OpenCode after installation so it reloads the project MCP config.', ...overwriteWarnings];
     return [
         'Restart OpenCode after installation so it reloads the user MCP config.',
         'OpenCode project config may override user config for a workspace; check project-level config if vgxness is not visible.',
+        ...overwriteWarnings,
     ];
 }
 function manualTestForScope(scope, databasePath, source) {

package/dist/mcp/client-install-opencode.js

@@ -25,9 +25,10 @@ export async function installOpenCodeMcpClient(input) {
         ...(input.scope !== undefined ? { scope: input.scope } : {}),
         ...(input.env !== undefined ? { env: input.env } : {}),
         ...(input.mcpOnly !== undefined ? { mcpOnly: input.mcpOnly } : {}),
+        ...(input.overwriteVgxness !== undefined ? { overwriteVgxness: input.overwriteVgxness } : {}),
     });
     if (!input.confirmed) {
-        return refusal('confirmation_required', confirmationRequiredMessage(plan.scope), input.databasePath, databasePathSource, server, confirmationRequiredSafety(plan), 'targetPath' in plan ? plan.targetPath : undefined, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return refusal('confirmation_required', confirmationRequiredMessage(plan.scope), input.databasePath, databasePathSource, server, confirmationRequiredSafety(plan), 'targetPath' in plan ? plan.targetPath : undefined, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     }
     if (plan.status === 'refused')
         return refusalFromPlan(plan, input.databasePath, databasePathSource, server);
@@ -35,28 +36,28 @@ export async function installOpenCodeMcpClient(input) {
         if (existsSync(plan.targetPath)) {
             const reparsed = parseConfig(plan.targetPath);
             if (!reparsed.ok)
-                return refusal(reparsed.reason, reparsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+                return refusal(reparsed.reason, reparsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
             const conflictingAgents = findConflictingVgxnessAgents(reparsed.value, agentPlan);
-            if (conflictingAgents.length > 0)
+            if (conflictingAgents.length > 0 && input.overwriteVgxness !== true)
                 return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
-            return refusal('unsupported_config_shape', 'OpenCode config appeared after planning; rerun setup apply so it can be merged safely without overwriting user config.', input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+            return refusal('unsupported_config_shape', 'OpenCode config appeared after planning; rerun setup apply so it can be merged safely without overwriting user config.', input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
         }
         writeConfig(plan.targetPath, mergeVgxnessOpenCodeConfig({ $schema: opencodeConfigSchema }, plan.server, plan.installsAgents));
-        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     }
     const parsed = parseConfig(plan.targetPath);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     const conflictingAgents = findConflictingVgxnessAgents(parsed.value, agentPlan);
-    if (conflictingAgents.length > 0)
+    if (conflictingAgents.length > 0 && input.overwriteVgxness !== true)
         return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
     const backup = createBackup(plan.targetPath, plan.scope);
     if (!backup.ok)
-        return refusal('post_write_validation_failed', backup.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        return refusal('post_write_validation_failed', backup.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
     const config = parsed.value;
     const mergedConfig = mergeVgxnessOpenCodeConfig({ ...config, $schema: plan.existingSchema ?? opencodeConfigSchema }, plan.server, plan.installsAgents);
     writeConfig(plan.targetPath, mergedConfig);
-    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness);
 }
 function mergeVgxnessOpenCodeConfig(config, server, installsAgents) {
     const merged = {
@@ -101,7 +102,7 @@ function createBackup(path, scope) {
         description: 'Backup existing OpenCode config before merging VGXNESS MCP configuration.',
     });
 }
-function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan) {
+function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness = false) {
     const parsed = parseConfig(targetPath);
     if (!parsed.ok)
         return refusal('post_write_validation_failed', 'OpenCode config could not be re-read after write.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);
@@ -129,6 +130,7 @@ function validateInstalledResult(targetPath, backup, server, databasePath, sourc
         manualTest: manualTestGuidance,
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
+        overwriteVgxness,
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
@@ -153,7 +155,7 @@ function isOpenCodeLocalMcpServerConfig(value) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function refusal(reason, message, databasePath, source, server, safety, targetPath, verificationHints = defaultVerificationHints(databasePath, source), warningMessages = warnings(), manualTestGuidance = manualTest(databasePath, source), agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
+function refusal(reason, message, databasePath, source, server, safety, targetPath, verificationHints = defaultVerificationHints(databasePath, source), warningMessages = warnings(), manualTestGuidance = manualTest(databasePath, source), agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false) {
     return {
         version: 1,
         kind: 'mcp-client-install-opencode',
@@ -168,11 +170,12 @@ function refusal(reason, message, databasePath, source, server, safety, targetPa
         manualTest: manualTestGuidance,
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
+        overwriteVgxness,
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
 function refusalFromPlan(plan, databasePath, source, server) {
-    return refusal(plan.reason, plan.message, databasePath, source, server, plan.safety, plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, plan);
+    return refusal(plan.reason, plan.message, databasePath, source, server, plan.safety, plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, plan, plan.overwriteVgxness);
 }
 function agentConflictRefusal(conflictingAgents, databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan) {
     return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${conflictingAgents.join(', ')}. Remove, rename, or manually reconcile them before installing.`, databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);

package/dist/setup/providers/opencode-setup-adapter.js

@@ -49,9 +49,10 @@ export const openCodeSetupAdapter = {
             databasePath,
             ...(context.databasePathSource !== undefined ? { databasePathSource: context.databasePathSource } : {}),
             ...(context.env !== undefined ? { env: context.env } : {}),
+            ...(context.overwriteVgxness !== undefined ? { overwriteVgxness: context.overwriteVgxness } : {}),
         });
         const targetPath = 'targetPath' in contract ? contract.targetPath : undefined;
-        const actions = contract.status === 'would_install' ? [externalInstallAction(contract.scope, targetPath)] : [];
+        const actions = contract.status === 'would_install' ? [externalInstallAction(contract.scope, targetPath, contract.overwriteVgxness)] : [];
         return {
             providerId: 'opencode',
             status: contract.status === 'would_install' ? 'available' : 'blocked',
@@ -59,7 +60,9 @@ export const openCodeSetupAdapter = {
             mutating: false,
             writesProviderConfig: false,
             summary: contract.status === 'would_install'
-                ? `OpenCode ${contract.action} plan is available for external application; confirmed merges create managed VGXNESS backups.`
+                ? contract.overwriteVgxness
+                    ? `OpenCode ${contract.action} reinstall plan is available; confirmed apply overwrites VGXNESS entries only, preserves unrelated config, and creates managed backups for existing targets.`
+                    : `OpenCode ${contract.action} plan is available for external application; confirmed merges create managed VGXNESS backups.`
                 : contract.message,
             ...(targetPath !== undefined ? { targetPath } : {}),
             warnings: contract.warnings,
@@ -105,7 +108,11 @@ function openCodePlanPreview(visibility, plan) {
     if (!isOpenCodeInstallContract(source))
         return undefined;
     if (source.status === 'would_install') {
-        const action = source.action === 'create' ? 'Install OpenCode MCP config' : 'Update OpenCode MCP config';
+        const action = source.overwriteVgxness
+            ? 'Reinstall VGXNESS OpenCode entries'
+            : source.action === 'create'
+                ? 'Install OpenCode MCP config'
+                : 'Update OpenCode MCP config';
         return {
             kind: source.action === 'create' ? 'install' : 'update',
             action,
@@ -115,7 +122,7 @@ function openCodePlanPreview(visibility, plan) {
             targetPath: source.targetPath,
             backupRequired: source.backupRequired,
             confirmationRequired: Boolean(plan?.actions.some((candidate) => candidate.safety.requiresExplicitConfirmation)),
-            risks: source.action === 'create' ? createInstallRisks() : mergeInstallRisks(),
+            risks: source.overwriteVgxness ? overwriteInstallRisks(source.installsAgents) : source.action === 'create' ? createInstallRisks() : mergeInstallRisks(),
             warnings: source.warnings,
         };
     }
@@ -140,6 +147,13 @@ function mergeInstallRisks() {
         'OpenCode config discovery may still be affected by target precedence or malformed local config.',
     ];
 }
+function overwriteInstallRisks(installsAgents) {
+    return [
+        `Existing VGXNESS-managed OpenCode entries will be replaced (${installsAgents ? 'mcp.vgxness, default_agent, instructions AGENTS.md, and known VGXNESS agents' : 'mcp.vgxness only'}).`,
+        'Unrelated OpenCode config, unrelated agents, and unrelated MCP servers are preserved; existing targets still receive managed backups before writes.',
+        'OpenCode must be restarted after external installation before it discovers the updated vgxness MCP server.',
+    ];
+}
 function refusedRepairRisks(message) {
     return [
         `Install planner refused automatic repair: ${message}`,
@@ -155,13 +169,15 @@ function isOpenCodeInstallContract(value) {
 function databasePathOrPlaceholder(context) {
     return context.databasePath ?? '<database-path>';
 }
-function externalInstallAction(scope, targetPath) {
+function externalInstallAction(scope, targetPath, overwriteVgxness = false) {
     return {
         id: `opencode-mcp-install-${scope}`,
         label: `Copy external OpenCode ${scope === 'user' ? 'user/global' : 'project'} install command`,
         kind: 'copy-command',
-        command: ['vgxness', 'mcp', 'install', 'opencode', '--scope', scope, '--yes'],
-        description: 'Copy and run this outside the TUI only after reviewing the read-only plan.',
+        command: ['vgxness', 'mcp', 'install', 'opencode', '--scope', scope, '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
+        description: overwriteVgxness
+            ? 'Copy and run this outside the TUI only after reviewing that VGXNESS entries will be overwritten and unrelated config preserved.'
+            : 'Copy and run this outside the TUI only after reviewing the read-only plan.',
         safety: externalProviderWriteSafety(targetPath),
     };
 }

package/dist/setup/setup-plan.js

@@ -54,6 +54,7 @@ export function createSetupPlan(input) {
         scope,
         env: input.env,
         mcpOnly: installMode === 'mcp-only',
+        ...(input.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.overwriteVgxness }),
     });
     return { ok: true, value: setupPlanFromOpenCode({ ...common, provider: 'opencode', installMode, scope, opencode }) };
 }
@@ -70,6 +71,7 @@ function setupPlanFromOpenCode(input) {
                 ...(input.opencode.targetPath === undefined ? {} : { targetPath: input.opencode.targetPath }),
                 installsAgents: input.opencode.installsAgents,
                 agentNames: input.opencode.agentNames,
+                ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
             },
             actions: [],
             conflicts: [
@@ -96,11 +98,12 @@ function setupPlanFromOpenCode(input) {
             mcpServer: input.opencode.server,
             installsAgents: input.opencode.installsAgents,
             agentNames: input.opencode.agentNames,
+            ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
         },
         actions: [
             {
                 id: `opencode-${input.opencode.action}`,
-                description: `${input.opencode.action === 'create' ? 'Create' : 'Merge'} OpenCode config with mcp.vgxness using vgxness mcp start${input.installMode === 'mcp-plus-agents' ? ' and manager/SDD agents' : ''}.`,
+                description: `${input.opencode.overwriteVgxness ? 'Reinstall/overwrite VGXNESS entries in' : input.opencode.action === 'create' ? 'Create' : 'Merge'} OpenCode config with mcp.vgxness using vgxness mcp start${input.installMode === 'mcp-plus-agents' ? ' and manager/SDD agents' : ''}${input.opencode.overwriteVgxness ? '; unrelated OpenCode config is preserved' : ''}.`,
                 mutating: false,
                 targetPath: input.opencode.targetPath,
                 backupRequired: input.opencode.backupRequired,
@@ -111,7 +114,9 @@ function setupPlanFromOpenCode(input) {
             ? [
                 {
                     targetPath: input.opencode.targetPath,
-                    reason: 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
+                    reason: input.opencode.overwriteVgxness
+                        ? 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before VGXNESS entries are overwritten/reinstalled.'
+                        : 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
                 },
             ]
             : [],

package/package.json

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