vgxness 1.9.8 → 1.10.1

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

@@ -12,8 +12,8 @@ function screenLines(input, width) {
                 '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.',
+                `Configure local storage and OpenCode integration with read-only previews first ${badgeLabels.readOnly} ${badgeLabels.preview}.`,
+                `No provider config is written until the final confirmation ${badgeLabels.noFilesWritten}.`,
             ], width, [setupFooterHints.continue, setupFooterHints.help, setupFooterHints.cancel]);
         case 'project-database':
             return workspaceLines(vm, [
@@ -32,12 +32,12 @@ function screenLines(input, width) {
                 '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.',
+                `OpenCode setup remains gated by final confirmation ${badgeLabels.confirmRequired}. Manual / none has no automatic install and no provider config will be written.`,
             ], width, choiceFooter());
         case 'opencode-details':
             return workspaceLines(vm, vm.providerLabel === 'OpenCode'
                 ? [
-                    'OpenCode plan ' + badgeLabels.writeAfterConfirm,
+                    'OpenCode plan ' + badgeLabels.confirmRequired,
                     ...choiceLines(vm.scopeChoices),
                     ...choiceLines(vm.installModeChoices),
                     ...choiceLines(vm.overwriteChoices),
@@ -47,7 +47,7 @@ function screenLines(input, width) {
                     `Action: ${vm.opencodeActionLabel}`,
                     `Agent readiness: ${vm.agentReadinessLabel}`,
                     vm.agentReadinessDetail,
-                    'Details are preview-only here; writes require final confirmation.',
+                    `Details are preview-only here ${badgeLabels.preview} ${badgeLabels.noFilesWritten}; writes require final confirmation.`,
                 ]
                 : [
                     'Manual / no-provider-write mode ' + badgeLabels.manual,
@@ -57,19 +57,22 @@ function screenLines(input, width) {
                 ], width, vm.providerLabel === 'OpenCode' ? choiceFooter() : [setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel]);
         case 'plan-review':
             return workspaceLines(vm, [
-                'Read-only plan review',
-                'Plan summary ' + badgeLabels.readOnly,
+                `Read-only plan review ${badgeLabels.preview}`,
+                `Plan summary ${badgeLabels.readOnly} ${badgeLabels.noFilesWritten}`,
+                'Plan generated. No files were written.',
                 ...planLines(vm, width),
                 ...nextCommandLines(vm),
-                'Review only: this screen does not write provider config.',
+                `Review only: this screen does not write provider config ${badgeLabels.noFilesWritten}.`,
                 vm.canAutoApply ? 'Press Enter to continue to final confirmation.' : 'Press Enter to show manual next steps; no automatic apply is available.',
             ], width, vm.canAutoApply ? [setupFooterHints.finalConfirmation, setupFooterHints.back, setupFooterHints.cancel] : [setupFooterHints.continue, setupFooterHints.back, setupFooterHints.cancel]);
         case 'final-confirmation':
             return workspaceLines(vm, [
                 'Final confirmation',
-                badgeLabels.warning,
+                `${badgeLabels.warning} ${badgeLabels.confirmRequired}`,
                 'Confirm OpenCode setup',
                 ...planLines(vm, width),
+                'Explicit confirmation is required before writing provider config.',
+                'This is the first write-capable screen; earlier wizard steps were preview/read-only only.',
                 '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.',
@@ -84,12 +87,12 @@ function screenLines(input, width) {
                 'Setup recovery',
                 badgeLabels.error,
                 `Error: ${input.error ?? 'Unknown setup error'}`,
-                'No unconfirmed provider config write was performed.',
+                `No unconfirmed provider config write was performed ${badgeLabels.noFilesWritten}.`,
                 'Next: inspect `vgxness setup plan`, resolve blockers, then retry.',
                 footer([setupFooterHints.close], width),
             ];
         case 'cancelled':
-            return ['Setup cancelled', badgeLabels.cancelled, 'Setup was not completed.', 'No provider config was written.', 'No agent seeding was performed.', footer([setupFooterHints.close], width)];
+            return ['Setup cancelled', `${badgeLabels.cancelled} ${badgeLabels.noFilesWritten}`, 'Cancelled. No changes were applied.', 'No provider config was written.', 'No agent seeding was performed.', footer([setupFooterHints.close], width)];
     }
 }
 function planLines(vm, width) {
@@ -153,7 +156,7 @@ function resultLines(result, vm, width) {
             ...vm.nextCommands.map((command) => `Next: ${command}`),
             footer([setupFooterHints.close], width),
         ];
-    return ['Setup result', 'No provider config write occurred.', footer([setupFooterHints.close], width)];
+    return ['Setup result', `${badgeLabels.noFilesWritten} 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));

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', 'overwrite:vgxness'],
+    'opencode-details': ['scope:user', 'install:mcp-plus-agents', 'install:mcp-only', 'overwrite:vgxness'],
     'plan-review': [],
     'final-confirmation': [],
     applying: [],
@@ -126,8 +126,6 @@ function selectFocusedChoice(state) {
             return reduceSetupTuiState(state, { type: 'select-provider', provider: 'opencode' });
         case 'provider:none':
             return reduceSetupTuiState(state, { type: 'select-provider', provider: 'none' });
-        case 'scope:project':
-            return reduceSetupTuiState(state, { type: 'select-scope', scope: 'project' });
         case 'scope:user':
             return reduceSetupTuiState(state, { type: 'select-scope', scope: 'user' });
         case 'install:mcp-plus-agents':

package/dist/cli/tui/setup/setup-tui-view-helpers.js

@@ -3,10 +3,14 @@ export const badgeLabels = {
     recommended: '[recommended]',
     selected: '[selected]',
     focused: '[focused]',
+    preview: '[preview]',
     warning: '[warning]',
     error: '[error]',
-    writeAfterConfirm: '[will write after confirm]',
+    confirmRequired: '[confirm required]',
+    writeAfterConfirm: '[confirm required]',
+    blocked: '[blocked]',
     readOnly: '[read-only]',
+    noFilesWritten: '[no files written]',
     manual: '[manual]',
     deferred: '[deferred]',
     cancelled: '[cancelled]',
@@ -35,7 +39,19 @@ 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', 'not installable', 'read-only', 'requires confirmation', 'will write after confirm', 'error', 'cancelled'];
+    const protectedPhrases = [
+        'final confirmation',
+        'confirm and apply',
+        'not installable',
+        'unrelated config is preserved',
+        'read-only',
+        'confirm required',
+        'no files written',
+        '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/mcp/claude-code-config.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
+import { providerConfigPathDiagnostics } from './provider-health-types.js';
 export function resolveClaudeCodeMcpJsonPath(workspaceRoot) {
     const target = resolve(workspaceRoot, '.mcp.json');
     assertInsideWorkspace(workspaceRoot, target);
@@ -55,6 +56,7 @@ export function claudeMcpConfigPathStatus(state) {
         parsed: state.parsed,
         status: state.status === 'configured' ? 'pass' : state.status === 'invalid' || state.status === 'conflicting' ? 'fail' : 'not-configured',
         detail: state.message,
+        diagnostics: providerConfigPathDiagnostics('external-project', state.exists),
     };
 }
 export function claudeMcpEntryStatus(state) {

package/dist/mcp/claude-code-scope.js

@@ -16,3 +16,4 @@ export function resolveClaudeCodeScope(input, fallback = 'project') {
 export function isClaudeCodeUserScope(scope) {
     return scope === 'user';
 }
+export const CLAUDE_CODE_USER_GLOBAL_ONLY_MESSAGE = 'VGX-managed Claude provider configuration is user-global only. Project/local Claude files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';

package/dist/mcp/claude-code-user-config.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { providerConfigPathDiagnostics } from './provider-health-types.js';
 import { isManagedClaudeCodeMcpServer } from './claude-code-config.js';
 import { safeHomeDirectory } from './claude-code-agent-config.js';
 export function resolveClaudeCodeUserMcpJsonPath(env = process.env) {
@@ -39,6 +40,7 @@ export function claudeUserMcpConfigPathStatus(state) {
         parsed: state.parsed,
         status: state.status === 'configured' ? 'pass' : state.status === 'invalid' || state.status === 'conflicting' ? 'fail' : 'not-configured',
         detail: state.message,
+        diagnostics: providerConfigPathDiagnostics('managed-user-global', state.exists),
     };
 }
 export function claudeUserMcpEntryStatus(state) {

package/dist/mcp/client-install-claude-code-contract.js

@@ -1,68 +1,23 @@
 import { withEffectiveManagerInstructions } from '../agents/canonical-agent-projection.js';
 import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
 import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
-import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, resolveClaudeCodeMcpJsonPath } from './claude-code-config.js';
-import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
-import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig } from './claude-code-config.js';
+import { CLAUDE_CODE_USER_GLOBAL_ONLY_MESSAGE, resolveClaudeCodeScope } from './claude-code-scope.js';
 import { inspectClaudeCodeUserMcpConfig, resolveClaudeCodeUserMcpJsonPath } from './claude-code-user-config.js';
 import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 export function planClaudeCodeMcpInstall(input) {
     const source = input.databasePathSource ?? 'flag';
     const server = createClaudeCodeMcpServerConfig(input.databasePath, source);
     const overwriteVgxness = input.overwriteVgxness === true;
-    const resolvedScope = resolveClaudeCodeScope(input.scope);
+    const resolvedScope = resolveClaudeCodeScope(input.scope, 'user');
     if (!resolvedScope.ok)
         return refused(input, server, 'unsupported_scope', resolvedScope.error.message, [], [], overwriteVgxness);
+    if (resolvedScope.value.canonical !== 'user')
+        return refused(input, server, 'unsupported_scope', CLAUDE_CODE_USER_GLOBAL_ONLY_MESSAGE, [], [], overwriteVgxness);
     const cliCommand = buildClaudeCodeMcpAddCommand({ scope: resolvedScope.value.canonical });
     if (!cliCommand.ok)
         return refused(input, server, 'unsupported_scope', cliCommand.error.message, [], [], overwriteVgxness);
-    if (resolvedScope.value.canonical !== 'project') {
-        if (resolvedScope.value.canonical === 'local') {
-            const targets = [{ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' }];
-            return { ...base(input, server, targets, [], false, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings), status: 'would_install' };
-        }
-        return planUserInstall(input, server, overwriteVgxness, cliCommand.value, resolvedScope.value.warnings);
-    }
-    let mcpPath;
-    try {
-        mcpPath = resolveClaudeCodeMcpJsonPath(input.cwd);
-    }
-    catch (cause) {
-        return refused(input, server, 'outside_workspace', cause instanceof Error ? cause.message : String(cause), [], [], overwriteVgxness);
-    }
-    const mcpState = inspectClaudeCodeMcpConfig(input.cwd);
-    const targets = [];
-    targets.push({ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' });
-    const preservedTopLevelKeys = mcpState.parsed ? Object.keys(mcpState.config) : [];
-    if (mcpState.status === 'missing')
-        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'create' });
-    else if (mcpState.status === 'stale')
-        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'merge' });
-    else if (mcpState.status === 'configured')
-        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'update-vgxness' });
-    else
-        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'blocked', reason: mcpState.message });
-    const agentInspection = inspectClaudeCodeAgents(input.cwd);
-    for (const agent of agentInspection.agents) {
-        if (agent.status === 'missing')
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'create' });
-        else if (agent.status === 'managed')
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'update-vgxness' });
-        else
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'blocked', reason: agent.detail });
-    }
-    const projectMemory = inspectClaudeProjectMemory(input.cwd);
-    targets.push({ kind: 'project-memory', path: projectMemory.path, action: projectMemory.action, status: projectMemory.status, backupRequired: projectMemory.backupRequired, ...(projectMemory.status === 'blocked' ? { reason: projectMemory.message } : {}) });
-    const blocked = targets.find((target) => target.action === 'blocked');
-    if (blocked !== undefined) {
-        const reason = blocked.kind === 'mcp-json' ? mcpRefusalReason(mcpState.status) : blocked.kind === 'project-memory' ? projectMemoryRefusalReason(projectMemory) : 'existing_vgxness_agent';
-        return refused(input, server, reason, blocked.reason ?? 'Claude Code install plan is blocked by an existing conflicting target.', targets, preservedTopLevelKeys, overwriteVgxness);
-    }
-    const backupRequired = targets.some((target) => (target.kind === 'mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness') || (target.kind === 'project-memory' && target.backupRequired));
-    return {
-        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings),
-        status: 'would_install',
-    };
+    return planUserInstall(input, server, overwriteVgxness, cliCommand.value, resolvedScope.value.warnings);
 }
 export function expectedClaudeCodeRenderedAgents(workspaceRoot, options) {
     const files = expectedClaudeCodeAgentFiles(workspaceRoot);
@@ -116,21 +71,21 @@ function planUserInstall(input, server, overwriteVgxness, cliCommand, scopeWarni
     return { ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, 'user', cliCommand, scopeWarnings), status: 'would_install' };
 }
 function refused(input, server, reason, message, targets, preservedTopLevelKeys, overwriteVgxness) {
-    const resolved = resolveClaudeCodeScope(input.scope);
-    const canonical = resolved.ok ? resolved.value.canonical : 'project';
-    const cli = buildClaudeCodeMcpAddCommand({ scope: canonical });
-    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness, canonical, cli.ok ? cli.value : undefined, resolved.ok ? resolved.value.warnings : []), status: 'refused', reason, message };
+    const resolved = resolveClaudeCodeScope(input.scope, 'user');
+    const canonical = resolved.ok ? resolved.value.canonical : 'user';
+    const cli = canonical === 'user' ? buildClaudeCodeMcpAddCommand({ scope: canonical }) : undefined;
+    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness, canonical, cli?.ok ? cli.value : undefined, resolved.ok ? resolved.value.warnings : []), status: 'refused', reason, message };
 }
 function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, canonicalClaudeScope, cliCommand, scopeWarnings) {
     const source = input.databasePathSource ?? 'flag';
-    const targetPath = canonicalClaudeScope === 'project' ? resolveClaudeCodeMcpJsonPath(input.cwd) : canonicalClaudeScope === 'user' ? resolveClaudeCodeUserMcpJsonPath(input.env) : `claude-cli:${canonicalClaudeScope}:vgxness`;
+    const targetPath = resolveClaudeCodeUserMcpJsonPath(input.env);
     return {
         version: 1,
         kind: 'mcp-client-install-claude-code',
         installable: true,
         mutating: false,
         provider: 'claude',
-        scope: input.scope ?? 'project',
+        scope: input.scope ?? 'user',
         targetPath,
         targets,
         backupRequired,
@@ -138,12 +93,12 @@ function base(input, server, targets, preservedTopLevelKeys, backupRequired, ove
         warnings: [
             ...scopeWarnings,
             'Claude Code MCP registration is modeled as structured config/argv, never shell strings.',
-            'Project compatibility may write .mcp.json, .claude/agents/*.md, and a guarded project-root CLAUDE.md managed block after explicit confirmation/preflight.',
+            'VGX-managed Claude provider configuration is user-global only; project/local Claude files are treated as external/manual diagnostics and are not written by VGXNESS.',
             'Claude user/global support narrowly merges only mcpServers.vgxness in ~/.claude.json and writes VGXNESS-owned ~/.claude/agents/*.md plus a managed block in ~/.claude/CLAUDE.md after confirmation/preflight; unknown config keys and non-managed memory content are preserved.',
         ],
         verificationHints: [
-            { kind: 'restart-client', message: 'Restart or reload Claude Code after confirmed project config installation.' },
-            { kind: 'manual-check', message: 'Open the project in Claude Code and verify the vgxness MCP server and project agents are visible.' },
+            { kind: 'restart-client', message: 'Restart or reload Claude Code after confirmed user-global config installation.' },
+            { kind: 'manual-check', message: 'Open Claude Code and verify the vgxness MCP server and user agents are visible.' },
             { kind: 'command', message: 'Run the MCP doctor command after installation.', command: createClaudeCodeMcpDoctorCommand(input.databasePath, source) },
         ],
         server,
@@ -154,13 +109,6 @@ function base(input, server, targets, preservedTopLevelKeys, backupRequired, ove
         overwriteVgxness,
     };
 }
-function mcpRefusalReason(status) {
-    if (status === 'invalid')
-        return 'malformed_json';
-    if (status === 'conflicting')
-        return 'existing_vgxness_mcp';
-    return 'invalid_mcp_shape';
-}
 function userMcpRefusalReason(status) {
     if (status === 'invalid')
         return 'malformed_json';
@@ -168,11 +116,6 @@ function userMcpRefusalReason(status) {
         return 'existing_vgxness_mcp';
     return 'invalid_mcp_shape';
 }
-function projectMemoryRefusalReason(state) {
-    if (state.status === 'blocked' && state.reason === 'conflicting_ownership')
-        return 'conflicting_claude_project_memory';
-    return 'malformed_claude_project_memory';
-}
 function userMemoryRefusalReason(state) {
     if (state.status === 'blocked' && state.reason === 'conflicting_ownership')
         return 'conflicting_claude_project_memory';

package/dist/mcp/client-install-claude-code.js

@@ -15,17 +15,15 @@ export async function installClaudeCodeMcpClient(input) {
     if (plan.status === 'refused')
         return refusal(plan.reason, plan.message, plan, server, [], []);
     if (!input.confirmed)
-        return refusal('confirmation_required', '`mcp install claude` requires explicit --yes before any project config write.', plan, server, [], []);
+        return refusal('confirmation_required', '`mcp install claude` requires explicit --yes before any user-global provider config write.', plan, server, [], []);
     if (input.preflight === undefined) {
-        return refusal('preflight_failed', 'Claude Code provider config writes require VGXNESS preflight before any project config write.', plan, server, [], []);
+        return refusal('preflight_failed', 'Claude Code provider config writes require VGXNESS preflight before any user-global provider config write.', plan, server, [], []);
     }
-    const preflightPaths = unique(plan.targets.flatMap((target) => (isMutatingTarget(target) ? [target.path] : [])));
-    if (plan.canonicalClaudeScope !== 'project')
-        preflightPaths.unshift(plan.targetPath);
+    const preflightPaths = unique([plan.targetPath, ...plan.targets.flatMap((target) => (isMutatingTarget(target) ? [target.path] : []))]);
     for (const targetPath of preflightPaths) {
         const preflight = await input.preflight({
             category: 'provider-tool',
-            operation: plan.canonicalClaudeScope === 'user' ? 'write claude user provider config' : 'write claude project provider config',
+            operation: 'write claude user-global provider config',
             targetPath,
             workspaceRoot: input.cwd,
             providerToolName: 'claude-code',

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

@@ -2,14 +2,15 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, } from './opencode-default-agent-config.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
-const supportedConfigTargets = ['.opencode/opencode.json', 'opencode.json', '.opencode/opencode.jsonc', 'opencode.jsonc'];
+const opencodeUserGlobalOnlyMessage = 'VGX-managed OpenCode configuration is user-global only. Project/local OpenCode files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
 export function resolveOpenCodeMcpInstallTarget(input) {
     const scope = input.scope ?? 'user';
     if (scope === 'project')
         return {
-            ok: true,
+            ok: false,
             scope,
-            path: join(input.cwd, '.opencode', 'opencode.json'),
+            reason: 'legacy_project_scope',
+            message: opencodeUserGlobalOnlyMessage,
         };
     const home = input.env?.HOME;
     if (typeof home !== 'string' || home.trim().length === 0) {
@@ -38,73 +39,7 @@ export function planOpenCodeMcpInstall(input) {
     if (scope === 'user') {
         return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy);
     }
-    const existingTargets = supportedConfigTargets
-        .map((relativePath) => ({
-        relativePath,
-        absolutePath: join(input.cwd, relativePath),
-    }))
-        .filter((target) => existsSync(target.absolutePath));
-    if (existingTargets.length > 1) {
-        return refusal('ambiguous_target', `Multiple OpenCode project config targets exist: ${existingTargets.map((target) => target.relativePath).join(', ')}. Remove ambiguity before installing.`, input.databasePath, databasePathSource, scope, undefined, [
-            {
-                kind: 'manual-check',
-                message: 'Remove ambiguity by keeping exactly one OpenCode project config target before installing.',
-            },
-        ], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    if (existingTargets.length === 0) {
-        return {
-            ...baseContract(input.databasePath, databasePathSource, scope, join(input.cwd, '.opencode', 'opencode.json'), false, 'create', agentPlan, overwriteVgxness, bashPermissionPolicy),
-            status: 'would_install',
-            action: 'create',
-            targetPath: join(input.cwd, '.opencode', 'opencode.json'),
-            backupRequired: false,
-            server,
-            preservedTopLevelKeys: createdConfigKeys(agentPlan),
-            existingSchema: null,
-        };
-    }
-    const [target] = existingTargets;
-    if (target === undefined)
-        return refusal('ambiguous_target', 'Unable to resolve OpenCode project config target.', input.databasePath, databasePathSource, scope, undefined, [], undefined, overwriteVgxness, bashPermissionPolicy);
-    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, overwriteVgxness, bashPermissionPolicy);
-    }
-    const parsed = parseConfig(target.absolutePath);
-    if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    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, overwriteVgxness, bashPermissionPolicy);
-    }
-    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, bashPermissionPolicy);
-    }
-    const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
-    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, overwriteVgxness, bashPermissionPolicy);
-    }
-    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, bashPermissionPolicy);
-    }
-    if (config.permission !== undefined && !isRecord(config.permission)) {
-        return refusal('unsupported_config_shape', 'Existing top-level permission must be a JSON object before VGXNESS can set top-level permission.bash to ask.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
-    }
-    return {
-        ...baseContract(input.databasePath, databasePathSource, scope, target.absolutePath, true, 'merge-preserve-existing', agentPlan, overwriteVgxness, bashPermissionPolicy),
-        status: 'would_install',
-        action: 'merge',
-        targetPath: target.absolutePath,
-        backupRequired: true,
-        server,
-        preservedTopLevelKeys: Object.keys(config),
-        existingSchema: typeof config.$schema === 'string' ? config.$schema : opencodeConfigSchema,
-    };
+    return refusal('unsupported_config_shape', opencodeUserGlobalOnlyMessage, input.databasePath, databasePathSource, scope, undefined, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
 }
 function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy) {
     const target = resolveOpenCodeMcpInstallTarget({
@@ -263,8 +198,6 @@ function warningsForScope(scope, overwriteVgxness, agentPlan, bashPermissionPoli
         ]
         : [];
     const bashWarnings = bashPermissionPolicy.manager === 'allow' ? ['OpenCode top-level permission.bash is set to ask; the VGXNESS manager agent allows bash while SDD subagents keep explicit permissions.'] : ['OpenCode top-level permission.bash is set to ask.'];
-    if (scope === 'project')
-        return ['Restart OpenCode after installation so it reloads the project MCP config.', ...overwriteWarnings, ...bashWarnings];
     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.',
@@ -280,13 +213,6 @@ function createdConfigKeys(agentPlan) {
     return [...keys, 'permission'];
 }
 function manualTestForScope(scope, databasePath, source) {
-    if (scope === 'project') {
-        return {
-            restart: 'Restart OpenCode after the config is installed.',
-            verify: 'Open the project in OpenCode and verify the vgxness MCP server is available.',
-            doctorCommand: createVgxnessMcpDoctorCommand(databasePath, source),
-        };
-    }
     return {
         restart: 'Restart OpenCode after the user config is installed.',
         verify: 'Open OpenCode and verify the vgxness MCP server is available from the user OpenCode config; project config may override it.',

package/dist/mcp/opencode-visibility.js

@@ -15,7 +15,7 @@ export function createOpenCodeMcpVisibilityReport(options) {
     const projectVisibleFromCurrentCwd = cwdInsideProject && projectConfigExists && projectHasVgxnessServer;
     const userTarget = resolveOpenCodeMcpInstallTarget({ cwd: projectRoot, scope: 'user', env: options.env });
     const userReport = userTarget.ok ? userVisibilityReport(userTarget.path, projectVisibleFromCurrentCwd) : undefined;
-    const selectedTargetPath = targetScope === 'user' && userTarget.ok ? userTarget.path : projectTargetPath;
+    const selectedTargetPath = userTarget.ok ? userTarget.path : '$HOME/.config/opencode/opencode.json';
     const selectedReady = targetScope === 'user' ? userReport?.configExists === true && userReport.hasVgxnessServer : projectVisibleFromCurrentCwd;
     return {
         version: 1,
@@ -57,6 +57,9 @@ function buildGuidance(state) {
         guidance.push('User scope targets `$HOME/.config/opencode/opencode.json` and this diagnostic reads it without writing provider config.');
         guidance.push('Project OpenCode config can override user config for a workspace; inspect project config first when both define `mcp.vgxness`.');
     }
+    if (state.targetScope === 'project') {
+        guidance.push('VGX-managed OpenCode installs are user-global only; project OpenCode config is read as external/manual diagnostics and will not be written by VGXNESS.');
+    }
     if (state.userTargetMessage !== undefined)
         guidance.push(state.userTargetMessage);
     if (state.userOverridden)
@@ -65,8 +68,6 @@ function buildGuidance(state) {
         guidance.push('The project-local `vgxness` server is not expected to appear from outside the worktree.');
         guidance.push('Use `mcp install opencode --scope user --plan` to inspect the user config target without writing it.');
     }
-    if (!state.configExists && state.targetScope === 'project')
-        guidance.push('Expected project-local config `.opencode/opencode.json` was not found.');
     if (state.configExists && !state.hasVgxnessServer)
         guidance.push('Project-local config exists, but it does not define `mcp.vgxness`.');
     return guidance;