vgxness 1.9.8 → 1.10.0

package/README.md

@@ -6,7 +6,7 @@ VGXNESS is an installable CLI, MCP control plane, and native code runtime for gu
 
 This package is proprietary software. The npm package ships inspectable JavaScript (`dist/`) so Node can run it, but it is **not open-source licensed** and may not be redistributed unless you have written permission. See [LICENSE](./LICENSE).
 
-OpenCode is the primary supported provider. Other providers remain preview/manual only. Provider config writes require explicit CLI confirmation.
+OpenCode is the primary supported provider. Claude setup support is secondary. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
 
 VGXNESS v1.9.1 has a canonical project health audit with validated evidence: 38 MCP tools, 106 test files, and the official Bun validation path passing, including package evidence with `releaseReadiness: pass`. Current unreleased builds expose 41 MCP tools after adding read-only SDD/run recovery parity. See [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md) for the versioned matrix and safety taxonomy.
 
@@ -150,7 +150,7 @@ vgxness sdd continue --project <project> --change <change>
 vgxness code sdd <change> <phase> --project <project> --save-artifact
 ```
 
-Stable defaults are: package `vgxness`, provider `opencode`, global user data DB, user/global OpenCode scope (`$HOME/.config/opencode/opencode.json`), and `mcp-plus-agents` mode. Use `--scope project` only when you intentionally want `<workspace>/.opencode/opencode.json`. The generated MCP command for the global DB default is:
+Stable defaults are: package `vgxness`, provider `opencode`, global user data DB, user-global OpenCode config (`$HOME/.config/opencode/opencode.json`), and `mcp-plus-agents` mode. VGX-managed OpenCode and Claude provider configuration is user-global only; runtime VGXNESS state remains project-aware through `--project`, `--change`, workspace, and database context. Existing project-local provider files such as `.opencode/`, `opencode.json`, `.mcp.json`, `.claude/`, and `CLAUDE.md` remain untouched by VGXNESS setup. They may still affect OpenCode or Claude behavior externally, but VGXNESS treats them as external/manual diagnostics and will not repair, write, back up, or delete them. The generated MCP command for the global DB default is:
 
 ```bash
 vgxness mcp start
@@ -182,7 +182,8 @@ Edits, shell, network, git mutations, SDD persistence, and memory saves route th
 ## Safety model
 
 - Preview, status, and plan commands do not write provider config; local VGXNESS store initialization may occur where the command needs SQLite-backed state.
-- Provider config writes require explicit `--yes` confirmation.
+- VGX-managed OpenCode and Claude provider config writes are user-global only and require explicit `--yes` confirmation.
+- Runtime VGXNESS state remains project-aware; project-local provider files are read-only external/manual diagnostics and may still affect provider behavior outside VGXNESS.
 - Setup/status TUI surfaces are read-only setup, diagnostics, recovery, and fallback surfaces; daily SDD progression stays in OpenCode with VGXNESS MCP.
 - SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write `openspec/`.
 - `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
@@ -260,7 +261,7 @@ Do not publish from CI. Publication or registry dry-run checks require separate
 npm uninstall -g vgxness
 ```
 
-Remove any OpenCode config entries and local/global VGXNESS data manually if you no longer need them.
+Remove any user-global OpenCode/Claude config entries and local/global VGXNESS data manually if you no longer need them. Project-local provider files are external/manual and are not created, repaired, or deleted by VGXNESS setup.
 
 ## More docs
 

package/dist/cli/cli-flags.js

@@ -112,9 +112,22 @@ function optionalScopeFlag(flags, name) {
         return { ok: true, value: undefined };
     return value === 'project' || value === 'personal' ? { ok: true, value } : validationFailure(`--${name} must be project or personal`);
 }
+const providerUserGlobalOnlyMigrationMessage = 'VGX-managed provider configuration is user-global only for OpenCode and Claude. Project/local provider files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
 function opencodeInstallScopeFlag(flags, name) {
     const value = optionalStringFlag(flags, name) ?? vgxnessSetupDefaults.defaultOpenCodeScope;
-    return value === 'project' || value === 'user' ? { ok: true, value } : validationFailure(`--${name} must be project or user`);
+    if (value === 'user' || value === 'global' || value === 'personal')
+        return { ok: true, value: 'user' };
+    if (value === 'project' || value === 'local')
+        return validationFailure(providerUserGlobalOnlyMigrationMessage);
+    return validationFailure(`--${name} must be user, global, or personal`);
+}
+function opencodeDiagnosticScopeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name) ?? vgxnessSetupDefaults.defaultOpenCodeScope;
+    if (value === 'user' || value === 'global' || value === 'personal')
+        return { ok: true, value: 'user' };
+    if (value === 'project')
+        return { ok: true, value };
+    return validationFailure(`--${name} must be user, global, personal, or project`);
 }
 function optionalModeFlag(flags, name) {
     const value = optionalStringFlag(flags, name);
@@ -325,4 +338,4 @@ function setupInstallModeFlag(flags) {
         return { ok: true, value: 'mcp-only' };
     return { ok: true, value: vgxnessSetupDefaults.defaultInstallMode };
 }
-export { acceptedAtFlag, codeApprovalPolicyFlag, codeMemoryPolicyFlag, codeTranscriptModeFlag, codeVerificationModeFlag, csvFlag, databasePathFor, databasePathSelectionFor, finalRunStatusFlag, instructionKindFlag, isRunStatus, isSkillEvaluationResultStatus, isSkillTargetType, jsonFlag, opencodeInstallScopeFlag, optionalJsonFlag, optionalModeFlag, optionalNumberFlag, optionalRunStatusFlag, optionalScopeFlag, optionalSkillEvaluationResultStatusFlag, optionalSkillImprovementProposalStatusFlag, optionalSkillResolutionUsageFlag, optionalSkillTargetTypeFlag, optionalSkillVersionStatusFlag, optionalStringFlag, optionalTrimmedFlag, parseArgs, permissionCategoryFlag, requiredFlag, requiredTrimmedFlag, retryPolicyFlag, runOutcomeFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, skillEvaluationResultStatusFlag, skillSourceFromFlags, skillSourceKindFlag, skillTargetTypeFlag, skillUsageOutcomeFlag, };
+export { acceptedAtFlag, codeApprovalPolicyFlag, codeMemoryPolicyFlag, codeTranscriptModeFlag, codeVerificationModeFlag, csvFlag, databasePathFor, databasePathSelectionFor, finalRunStatusFlag, instructionKindFlag, isRunStatus, isSkillEvaluationResultStatus, isSkillTargetType, jsonFlag, providerUserGlobalOnlyMigrationMessage, opencodeDiagnosticScopeFlag, opencodeInstallScopeFlag, optionalJsonFlag, optionalModeFlag, optionalNumberFlag, optionalRunStatusFlag, optionalScopeFlag, optionalSkillEvaluationResultStatusFlag, optionalSkillImprovementProposalStatusFlag, optionalSkillResolutionUsageFlag, optionalSkillTargetTypeFlag, optionalSkillVersionStatusFlag, optionalStringFlag, optionalTrimmedFlag, parseArgs, permissionCategoryFlag, requiredFlag, requiredTrimmedFlag, retryPolicyFlag, runOutcomeFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, skillEvaluationResultStatusFlag, skillSourceFromFlags, skillSourceKindFlag, skillTargetTypeFlag, skillUsageOutcomeFlag, };

package/dist/cli/cli-help.js

@@ -9,9 +9,9 @@ Areas:
   status [--project <name>] [--change <id>] [--db <path>] [--json]
   next [--project <name>] [--change <id>] [--db <path>] [--json]
   resume [--project <name>] [--run-id <id>] [--db <path>] [--json]
-  init [--project <name>] [--provider opencode|claude|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
-  setup plan [--project <name>] [--provider opencode|claude|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
-  setup apply --yes [--project <name>] [--provider opencode|claude|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
+  init [--project <name>] [--provider opencode|claude|none] [--scope user|global|personal] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
+  setup plan [--project <name>] [--provider opencode|claude|none] [--scope user|global|personal] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
+  setup apply --yes [--project <name>] [--provider opencode|claude|none] [--scope user|global|personal] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
   setup backup list --provider opencode [--scope project|user|global] [--target <path>] [--json]
   setup rollback --backup <path> [--preview|--yes] [--json]
   setup status [--project <name>] [--scope project|personal] [--db <path>] [--json]
@@ -23,7 +23,7 @@ Areas:
   Next answers "what should I do now?" with a shorter next-action view.
   Resume answers "how do I continue interrupted work?" with run inspection guidance.
   Without --change or --run-id they stay orientation-only and do not open local memory; with --change or --run-id they read SQLite read-only. Pass --json for automation.
-  Setup plan/init default to human-readable read-only output; pass --json for automation. Setup apply writes OpenCode config only with --yes and uses the global user DB plus mcp-plus-agents by default.
+  Setup plan/init default to human-readable read-only output; pass --json for automation. VGX-managed provider configuration is user-global only for OpenCode and Claude; setup apply writes provider config only with --yes and uses the global user DB plus mcp-plus-agents by default.
   Setup status defaults to human-readable read-only output; pass --json for automation. It never writes provider config or executes providers.
   Doctor defaults to human-readable output; pass --json for automation.
   Verification plans are read-only recommendations only; they never execute commands, write provider config, persist results, mutate SDD artifacts, or infer acceptance.
@@ -64,19 +64,19 @@ 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] [--overwrite-vgxness|--reinstall]
-  mcp install opencode --yes [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
-  mcp install claude --plan [--scope local|project|user] [--db <path>] [--overwrite-vgxness|--reinstall]
-  mcp install claude --yes --run-id <id> [--scope local|project|user] [--db <path>] [--phase <phase>] [--agent-id <id>] [--overwrite-vgxness|--reinstall]
+  mcp install opencode --plan [--scope user|global|personal] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install opencode --yes [--scope user|global|personal] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install claude --plan [--scope user|global|personal] [--db <path>] [--overwrite-vgxness|--reinstall]
+  mcp install claude --yes --run-id <id> [--scope user|global|personal] [--db <path>] [--phase <phase>] [--agent-id <id>] [--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 top-level permission.bash=ask, vgxness-manager with bash=allow, and hidden vgxness-sdd-* agents with explicit permissions; use --mcp-only for legacy MCP-only config.
+  OpenCode install defaults to user-global scope and installs mcp.vgxness plus top-level permission.bash=ask, vgxness-manager with bash=allow, and hidden vgxness-sdd-* agents with explicit permissions; 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.
-  Claude support is first-class for guarded MCP setup. Claude scopes are local|project|user; compatibility aliases personal/global map to user with warnings. Plans show Claude CLI argv, project .mcp.json compatibility, user ~/.claude.json MCP merge, agents, and guarded CLAUDE.md managed memory separately. Project scope confirmed applies write .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block as needed. User/global confirmed applies narrowly merge only mcpServers.vgxness in ~/.claude.json, write ~/.claude/agents/*.md, and manage only the VGXNESS block in ~/.claude/CLAUDE.md. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). Status/doctor/change-plan are read-only and do not execute Claude Code.
+  It writes only after --yes. VGX-managed provider configuration is user-global only for OpenCode and Claude; the OpenCode target is $HOME/.config/opencode/opencode.json.
+  Project/local provider files are external/manual diagnostics and will not be written by VGXNESS. Plans are read-only; applies refuse unsafe existing user-global config and create backups before merge.
+  Claude support is first-class for guarded MCP setup. Claude user/global/personal scopes all target user-global managed config. Confirmed Claude writes narrowly merge mcpServers.vgxness in ~/.claude.json, write ~/.claude/agents/*.md, and manage only the VGXNESS block in ~/.claude/CLAUDE.md. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). Status/doctor/change-plan are read-only and do not execute Claude Code.
 
   skills register --project <name> --name <name> --description <text>
   skills list [--project <name>] [--scope project|personal]
@@ -105,7 +105,7 @@ Areas:
   No args in an interactive TTY opens the OpenTUI main menu.
   No args without a TTY prints static safe setup guidance and exits 0 without opening project state.
   Setup TUI may launch without --project; Installation remains available and project-scoped checks are deferred while project screens render project-required recovery states.
-  Provider setup support: OpenCode first-class supported default guided install; Claude first-class supported guarded install for CLI MCP registration, project compatibility, and project/user agent planning; Antigravity placeholder; Custom/future extension point.
+  Provider setup support: OpenCode first-class supported default guided install; Claude first-class supported guarded user-global install; project/local provider files are diagnostics only; Antigravity placeholder; Custom/future extension point.
   Provider config writes/install/apply are external-only and require explicit confirmation.
 
   sdd status --project <name> --change <id> [--json]

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

@@ -9,7 +9,7 @@ import { resolveClaudeCodeScope } from '../../mcp/claude-code-scope.js';
 import { computeEffectiveManagerInstructions } from '../../agents/manager-profile-overlay-service.js';
 import { RunService } from '../../runs/run-service.js';
 import { isTerminalRunStatus } from '../../runs/schema.js';
-import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalNumberFlag, optionalStringFlag } from '../cli-flags.js';
+import { databasePathFor, databasePathSelectionFor, opencodeDiagnosticScopeFlag, opencodeInstallScopeFlag, optionalNumberFlag, optionalStringFlag, providerUserGlobalOnlyMigrationMessage, } from '../cli-flags.js';
 import { usageFailure, validationFailure } from '../cli-help.js';
 import { jsonResult, openCliDatabase, resultFailure } from '../cli-helpers.js';
 import { renderDoctorReport } from '../doctor-renderer.js';
@@ -129,8 +129,12 @@ export function runMcpInstallCommand(parsed, environment) {
 }
 function claudeInstallScopeFlag(flags) {
     const value = optionalStringFlag(flags, 'scope');
-    const resolved = resolveClaudeCodeScope(value);
-    return resolved.ok ? { ok: true, value: resolved.value.canonical } : validationFailure(resolved.error.message);
+    const resolved = resolveClaudeCodeScope(value, 'user');
+    if (!resolved.ok)
+        return validationFailure(resolved.error.message);
+    if (resolved.value.canonical === 'project' || resolved.value.canonical === 'local')
+        return validationFailure(providerUserGlobalOnlyMigrationMessage);
+    return { ok: true, value: resolved.value.canonical };
 }
 function createClaudeCodeInstallPreflight(parsed, database, environment) {
     return (request) => {
@@ -211,7 +215,7 @@ export function runMcpDoctorCommand(parsed, environment, output = 'json') {
     })();
 }
 export function runMcpDoctorOpenCodeCommand(parsed, environment) {
-    const scope = opencodeInstallScopeFlag(parsed.flags, 'scope');
+    const scope = opencodeDiagnosticScopeFlag(parsed.flags, 'scope');
     if (!scope.ok)
         return resultFailure(scope);
     const projectRoot = optionalStringFlag(parsed.flags, 'project-root');

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

@@ -9,7 +9,7 @@ import { applyRollbackConfigBackup, listProviderConfigBackups, previewRollbackCo
 import { vgxnessSetupDefaults } from '../../setup/setup-defaults.js';
 import { SetupLifecycleService } from '../../setup/setup-lifecycle-service.js';
 import { createSetupPlan } from '../../setup/setup-plan.js';
-import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalStringFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, } from '../cli-flags.js';
+import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalStringFlag, providerUserGlobalOnlyMigrationMessage, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, } from '../cli-flags.js';
 import { okText, usageFailure, validationFailure } from '../cli-help.js';
 import { jsonResult, openCliDatabase, resultFailure } from '../cli-helpers.js';
 import { renderSetupPlan } from '../setup-plan-renderer.js';
@@ -141,7 +141,7 @@ export async function applySetupPlanInput(input, environment) {
             ok: true,
             value: {
                 status: 'manual-required',
-                message: 'Claude setup apply is intentionally non-mutating here; use vgxness mcp install claude --scope project --yes --run-id <id> for guarded Claude writes.',
+                message: `Claude setup apply is intentionally non-mutating here; use vgxness mcp install claude --yes --run-id <id> for guarded user-global Claude writes. ${providerUserGlobalOnlyMigrationMessage}`,
                 plan: plan.value,
             },
         };

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

@@ -35,20 +35,20 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         databaseLabel: plan === undefined ? 'pending' : plan.db.mode,
         databasePathLabel: compactPath(databasePath, 72),
         databaseSourceLabel: String(databaseSource),
-        scopeLabel: isOpenCode ? (opencode?.scope ?? selections?.scope ?? 'user') : isClaude ? 'Project-local Claude config only; OpenCode controls disabled' : 'Manual / none (OpenCode controls disabled)',
+        scopeLabel: isOpenCode ? 'user-global provider config' : isClaude ? 'User-global Claude config only; project-local files are diagnostics' : 'Manual / none (OpenCode controls disabled)',
         installModeLabel: isOpenCode
             ? opencode?.installsAgents === false
                 ? 'mcp-only'
                 : (selections?.installMode ?? 'mcp-plus-agents')
             : isClaude
-                ? 'Claude guarded apply outside guided OpenCode install'
+                ? 'Claude guarded user-global apply outside guided OpenCode install'
                 : 'Manual / none (no OpenCode install)',
-        targetPathLabel: isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : isClaude ? 'Claude targets: .mcp.json and .claude/agents/*.md via guarded apply' : 'No provider config target; manual/no-provider-write mode',
-        opencodeActionLabel: isOpenCode ? opencodeActionLabel(opencode?.action) : isClaude ? 'No guided setup write; use guarded Claude install with run preflight.' : 'No automatic provider write; use manual setup guidance.',
+        targetPathLabel: isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : isClaude ? 'Claude targets: user-global ~/.claude.json, ~/.claude/agents/*.md, ~/.claude/CLAUDE.md via guarded apply' : 'No provider config target; manual/no-provider-write mode',
+        opencodeActionLabel: isOpenCode ? opencodeActionLabel(opencode?.action) : isClaude ? 'No guided setup write; use guarded user-global Claude install with run preflight.' : 'No automatic provider write; use manual setup guidance.',
         memoryPathExplanation: memoryExplanation,
         providerInstallabilityLabel: isOpenCode
-            ? 'OpenCode is the default guided install provider. Claude is first-class supported via guarded mcp install claude --scope project --yes --run-id <id>.'
-            : 'Manual / none is read-only guidance. Claude remains supported through explicit guarded apply outside this guided OpenCode flow.',
+            ? 'OpenCode is the default guided install provider. VGXNESS will manage user-global provider configuration. Claude is first-class supported via guarded mcp install claude --yes --run-id <id>. Project-local provider files are external/manual diagnostics and will not be modified.'
+            : 'Manual / none is read-only guidance. Claude remains supported through explicit guarded user-global apply outside this guided OpenCode flow.',
         agentReadinessLabel: agentReadiness.label,
         agentReadinessDetail: agentReadiness.detail,
         plannedActions: plan?.actions.map((action) => ({
@@ -63,8 +63,8 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         nextCommands: plan?.nextCommands ?? ['vgxness setup plan'],
         canAutoApply: plan?.provider === 'opencode' && plan.status === 'ready' && state?.selections.provider !== 'none' && plan.opencode !== undefined,
         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.',
+            ? 'Final confirmation is required. Reinstall is enabled: user-global VGXNESS OpenCode entries will be overwritten after a managed backup when the target exists; unrelated config is preserved. Project-local provider files are external/manual diagnostics and will not be modified.'
+            : 'Final confirmation is required before any provider config write. VGXNESS will manage user-global provider configuration. Project-local provider files are external/manual diagnostics and will not be modified.',
         frameLabel: 'VGXNESS Setup Assistant workspace',
         progressLabel: progressLabel(state?.screen),
         previewLabel,
@@ -78,14 +78,13 @@ 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', 'Default guided install provider; writes still require final confirmation.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
-            choice('provider:claude-supported', 'Claude (first-class supported)', 'Claude CLI MCP registration and project compatibility apply only via guarded mcp install claude --scope project --yes --run-id <id>; explicit install path.', (selections?.provider ?? plan?.provider) === 'claude', state?.focusedChoiceId, ['[supported]', badgeLabels.readOnly]),
+            choice('provider:opencode', 'OpenCode', 'Default guided install provider. VGXNESS will manage user-global provider configuration.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
+            choice('provider:claude-supported', 'Claude (first-class supported)', 'Claude user-global CLI MCP registration and config apply only via guarded mcp install claude --yes --run-id <id>; project-local files are diagnostics only.', (selections?.provider ?? plan?.provider) === 'claude', state?.focusedChoiceId, ['[supported]', 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
             ? [
-                choice('scope:user', 'User/global scope', 'Preview the default user-level OpenCode config target; still requires final confirmation.', (selections?.scope ?? opencode?.scope ?? 'user') === 'user', state?.focusedChoiceId, [badgeLabels.recommended, badgeLabels.writeAfterConfirm]),
-                choice('scope:project', 'Project scope', 'Opt in to writing project OpenCode config only after final confirmation.', (selections?.scope ?? opencode?.scope) === 'project', state?.focusedChoiceId, [badgeLabels.writeAfterConfirm]),
+                choice('scope:user', 'User-global provider config', 'VGXNESS will manage user-global provider configuration. Project-local provider files are external/manual diagnostics and will not be modified.', true, state?.focusedChoiceId, [badgeLabels.recommended, badgeLabels.writeAfterConfirm]),
             ]
             : [],
         installModeChoices: isOpenCode
@@ -96,7 +95,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
             : [],
         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]),
+                choice('overwrite:vgxness', 'Reinstall VGXNESS entries', 'Default off. When enabled, final confirmation overwrites existing user-global VGXNESS OpenCode entries and preserves unrelated OpenCode config.', selections?.overwriteVgxness ?? opencode?.overwriteVgxness ?? false, state?.focusedChoiceId, [badgeLabels.warning, badgeLabels.writeAfterConfirm]),
             ]
             : [],
     };
@@ -109,10 +108,10 @@ function previewDetailLines(input) {
         `Provider: ${input.provider === 'opencode' ? 'OpenCode [recommended default]' : input.provider === 'claude' ? 'Claude [first-class supported] [guarded explicit apply]' : 'Manual / none [manual] [read-only]'}`,
         `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'}`,
+        `Scope: ${input.isOpenCode ? 'user-global provider config' : '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 first-class support requires guarded mcp install claude --scope project --yes --run-id <id>.' : 'No guided provider install from this selection; Claude uses guarded explicit apply.'}`,
+        `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation. VGXNESS will manage user-global provider configuration. Claude first-class support requires guarded mcp install claude --yes --run-id <id>. Project-local provider files are external/manual diagnostics and will not be modified.' : 'No guided provider install from this selection; Claude uses guarded explicit user-global apply.'}`,
         `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'}`,
@@ -132,7 +131,8 @@ 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 the default guided install provider; Claude is first-class supported for guarded explicit apply via mcp install claude --scope project --yes --run-id <id>; Manual / none writes no provider config.',
+        'Provider support: OpenCode is the default guided install provider; Claude is first-class supported for guarded explicit user-global apply via mcp install claude --yes --run-id <id>; Manual / none writes no provider config.',
+        'Provider config: VGXNESS will manage user-global provider configuration. Project-local provider files are external/manual diagnostics and will not be modified.',
         '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.',
     ];
@@ -177,7 +177,7 @@ function progressLabel(screen) {
     if (screen === 'provider')
         return 'Step 3/6 Provider: choose OpenCode or manual/none';
     if (screen === 'opencode-details')
-        return 'Step 4/6 OpenCode: scope and install mode';
+        return 'Step 4/6 OpenCode: user-global target and install mode';
     if (screen === 'plan-review')
         return 'Step 5/6 Review: read-only plan review';
     if (screen === 'final-confirmation')

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/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',