vgxness 1.9.7 → 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/agents/canonical-agent-manifest.js

@@ -207,12 +207,12 @@ const registryManagerInstructionsV10 = [
     'OpenCode native/provider tools are governance-v1 audit-only/non-hard-blocking; report warnings, never say they are hard-blocked by config.',
 ].join(' ');
 const subagentData = {
-    'vgxness-sdd-explore': { seedDescription: 'Investigates codebase context and identifies options before proposals.', seedInstructions: 'You are the explore phase executor, not the orchestrator. Do not delegate. Explore repository evidence for the requested SDD change. Do not implement code changes. Return concise findings, risks, and recommended next artifacts.', capabilities: ['sdd-exploration', 'codebase-research', 'discovery'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:explore'], skills: ['vgxness-sdd-explore'], phaseContract: 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.' },
+    'vgxness-sdd-explore': { seedDescription: 'Investigates codebase context and identifies options before proposals.', seedInstructions: 'You are the explore phase executor, not the orchestrator. Do not delegate. Explore repository evidence for the requested SDD change. Do not implement code changes. Return concise findings, risks, and recommended next artifacts.', capabilities: ['sdd-exploration', 'codebase-research', 'discovery'], permissions: { read: 'allow', edit: 'deny', shell: 'allow', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:explore'], skills: ['vgxness-sdd-explore'], phaseContract: 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.' },
     'vgxness-sdd-propose': { seedDescription: 'Creates focused change proposals from exploration findings.', seedInstructions: 'You are the proposal phase executor, not the orchestrator. Do not delegate. Create a focused SDD proposal from exploration evidence. Do not implement code changes. Identify scope, tradeoffs, non-goals, and acceptance direction.', capabilities: ['sdd-proposal', 'proposal-planning', 'scope-definition'], permissions: { read: 'allow', edit: 'deny', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:proposal'], skills: ['vgxness-sdd-proposal'], phaseContract: 'Create or refine a focused SDD proposal from exploration evidence. Do not implement code changes. Include scope, tradeoffs, non-goals, and acceptance direction.' },
     'vgxness-sdd-spec': { seedDescription: 'Writes detailed requirements and acceptance criteria for SDD changes.', seedInstructions: 'You are the spec phase executor, not the orchestrator. Do not delegate. Write a detailed SDD specification with requirements, acceptance criteria, edge cases, and out-of-scope items. Do not implement code changes.', capabilities: ['sdd-specification', 'requirements', 'acceptance-criteria'], permissions: { read: 'allow', edit: 'deny', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:spec'], skills: ['vgxness-sdd-spec'], phaseContract: 'Write requirements, acceptance criteria, edge cases, and out-of-scope items. Do not implement code changes.' },
     'vgxness-sdd-design': { seedDescription: 'Creates technical design from accepted proposals and accepted or trusted draft specs.', seedInstructions: 'You are the design phase executor, not the orchestrator. Do not delegate. Create a technical design grounded in the repository. Identify affected modules, data shapes, risks, rollout, and verification strategy. Do not implement code changes.', capabilities: ['sdd-design', 'technical-design', 'architecture-planning'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:design'], skills: ['vgxness-sdd-design'], phaseContract: 'Create technical design grounded in the repository: affected modules, data shapes, safety, rollout, and verification. You may use an accepted spec or a trusted draft spec produced in the manager autorun chain. Do not implement code changes.' },
     'vgxness-sdd-tasks': { seedDescription: 'Breaks accepted or trusted draft specs and designs into implementation tasks.', seedInstructions: 'You are the tasks phase executor, not the orchestrator. Do not delegate. Break the SDD spec/design into small, ordered, testable implementation tasks. Do not implement code changes.', capabilities: ['sdd-tasks', 'task-breakdown', 'implementation-planning'], permissions: { read: 'allow', edit: 'deny', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:tasks'], skills: ['vgxness-sdd-tasks'], phaseContract: 'Break accepted or trusted draft spec/design into small ordered testable implementation tasks. Do not implement code changes.' },
-    'vgxness-sdd-apply': { seedDescription: 'Implements code changes from SDD task definitions.', seedInstructions: 'You are the apply phase executor, not the orchestrator. Implement only the assigned SDD tasks directly. Do not delegate. Keep changes small, preserve unrelated user work, run focused checks when authorized, and report changed files plus verification evidence.', capabilities: ['sdd-apply', 'implementation', 'code-change'], permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'ask', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:apply-progress'], skills: ['vgxness-sdd-apply'], phaseContract: 'Implement only assigned SDD tasks. Preserve unrelated dirty files and user work. Use focused tests when authorized. Report changed files, tests/evidence, and residual risks.' },
+    'vgxness-sdd-apply': { seedDescription: 'Implements code changes from SDD task definitions.', seedInstructions: 'You are the apply phase executor, not the orchestrator. Implement only the assigned SDD tasks directly. Do not delegate. Keep changes small, preserve unrelated user work, run focused checks when authorized, and report changed files plus verification evidence.', capabilities: ['sdd-apply', 'implementation', 'code-change'], permissions: { read: 'allow', edit: 'ask', shell: 'allow', git: 'ask', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:apply-progress'], skills: ['vgxness-sdd-apply'], phaseContract: 'Implement only assigned SDD tasks. Preserve unrelated dirty files and user work. Use focused tests when authorized. Report changed files, tests/evidence, and residual risks.' },
     'vgxness-sdd-verify': { seedDescription: 'Validates implementation against specs, tasks, and evidence.', seedInstructions: 'You are the verify phase executor, not the orchestrator. Do not delegate. Verify the implementation against SDD artifacts. Prefer focused local tests, inspect evidence, and report residual risk. Do not implement unrelated changes.', capabilities: ['sdd-verify', 'verification', 'test-review', 'risk-review'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:verify'], skills: ['vgxness-sdd-verify'], phaseContract: 'Validate implementation against SDD artifacts and task acceptance criteria. Prefer focused local tests and evidence review. Do not implement unrelated changes.' },
     'vgxness-sdd-archive': { seedDescription: 'Archives completed SDD change artifacts and outcomes.', seedInstructions: 'You are the archive phase executor, not the orchestrator. Do not delegate. Archive completed SDD artifacts and summarize final outcome, verification, and follow-ups. Confirm before writes beyond the requested archive artifact.', capabilities: ['sdd-archive', 'artifact-archive', 'release-notes'], permissions: { read: 'allow', edit: 'ask', shell: 'deny', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:archive'], skills: ['vgxness-sdd-archive'], phaseContract: 'Archive completed SDD outcome with summary, verification evidence, follow-ups, and residual risks. Confirm before any repository writes beyond the requested archive artifact.' },
     'vgxness-sdd-init': { seedDescription: 'Bootstraps SDD context and project configuration.', seedInstructions: 'You are the init phase executor, not the orchestrator. Do not delegate. Initialize SDD context and project setup safely. Prefer read-only diagnostics and explicit user confirmation before writes or provider/global config changes.', capabilities: ['sdd-init', 'setup', 'bootstrap'], permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:init', 'setup'], skills: [], phaseContract: 'Bootstrap SDD context and project setup safely. Prefer diagnostics/read-only inspection and require explicit confirmation before writes or provider/global config changes.' },

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