vgxness 1.9.8 → 1.10.1

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

@@ -7,23 +7,21 @@ export const claudeSetupAdapter = {
     supportLevel: 'supported',
     capabilities: ['mcp-preview', 'mcp-install-plan', 'cli-mcp-plan', 'agent-preview', 'doctor', 'manual-guidance'],
     targets: [
-        { kind: 'project-config', label: 'Project .mcp.json', path: '.mcp.json', writableBySetup: false },
-        { kind: 'project-config', label: 'Project Claude agents', path: '.claude/agents/*.md', writableBySetup: false },
-        { kind: 'project-config', label: 'Project Claude memory', path: 'CLAUDE.md', writableBySetup: false },
-        { kind: 'user-config', label: 'User Claude MCP config', path: '~/.claude.json', writableBySetup: false },
-        { kind: 'user-config', label: 'User Claude agents', path: '~/.claude/agents/*.md', writableBySetup: false },
-        { kind: 'user-config', label: 'User Claude memory', path: '~/.claude/CLAUDE.md', writableBySetup: false },
+        { kind: 'user-config', label: 'Managed user-global Claude MCP config', path: '~/.claude.json', writableBySetup: false },
+        { kind: 'user-config', label: 'Managed user-global Claude agents', path: '~/.claude/agents/*.md', writableBySetup: false },
+        { kind: 'user-config', label: 'Managed user-global Claude memory', path: '~/.claude/CLAUDE.md', writableBySetup: false },
+        { kind: 'project-config', label: 'Project Claude files (external/manual diagnostic only)', path: '.mcp.json, .claude/agents/*.md, CLAUDE.md', writableBySetup: false },
     ],
     getStatus(context) {
         const plan = this.getInstallPlan?.(context);
         return {
             providerId: 'claude',
             status: plan?.status === 'blocked' ? 'blocked' : 'available',
-            summary: 'Claude provider setup is available for CLI MCP registration planning/apply, project .mcp.json compatibility, guarded CLAUDE.md memory, user ~/.claude.json MCP merge, and project/user agents; explicit guarded apply is required for writes or CLI execution.',
+            summary: 'Claude provider setup is available for user-global CLI MCP registration planning/apply, ~/.claude.json MCP merge, ~/.claude/agents/*.md, and guarded ~/.claude/CLAUDE.md memory; explicit guarded apply is required for writes or CLI execution. Project-local provider files are external/manual diagnostics and will not be modified.',
             evidence: context.databasePath !== undefined
                 ? ['Claude MCP preview can be generated from the selected database path.']
                 : ['Claude MCP preview uses a placeholder until a database path is selected.'],
-            guidance: ['Use `vgxness mcp install claude --scope local|project|user --yes --run-id <id>` for explicit guarded apply. Project scope may write .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block. User/global scope narrowly merges only mcpServers.vgxness in ~/.claude.json, writes ~/.claude/agents/*.md, and manages only the VGXNESS block in ~/.claude/CLAUDE.md. Read-only setup/status surfaces do not execute Claude Code.'],
+            guidance: ['VGXNESS will manage user-global provider configuration. Use `vgxness mcp install claude --yes --run-id <id>` for explicit guarded apply. Project-local provider files are external/manual diagnostics and will not be modified. Read-only setup/status surfaces do not execute Claude Code.'],
             actions: [
                 {
                     id: 'claude-manual-guidance',
@@ -56,7 +54,7 @@ export const claudeSetupAdapter = {
             cwd: context.workspaceRoot,
             databasePath: context.databasePath ?? '<database-path>',
             ...(context.databasePathSource !== undefined ? { databasePathSource: context.databasePathSource } : {}),
-            scope: 'project',
+            scope: 'user',
             ...(context.env !== undefined ? { env: context.env } : {}),
             ...(context.overwriteVgxness !== undefined ? { overwriteVgxness: context.overwriteVgxness } : {}),
         });
@@ -72,7 +70,7 @@ function claudeInstallPlan(_context, contract) {
         mutating: false,
         writesProviderConfig: false,
         summary: contract.status === 'would_install'
-            ? 'Claude project install plan is available for external guarded application; the read-only setup status does not write provider config.'
+            ? 'Claude user-global install plan is available for external guarded application; the read-only setup status does not write provider config. Project-local provider files are external/manual diagnostics and will not be modified.'
             : contract.message,
         targetPath: contract.targetPath,
         warnings: contract.warnings,
@@ -82,13 +80,13 @@ function claudeInstallPlan(_context, contract) {
 }
 function externalInstallAction(targetPath, overwriteVgxness = false) {
     return {
-        id: 'claude-mcp-install-project',
-        label: 'Copy external Claude project install command',
+        id: 'claude-mcp-install-user-global',
+        label: 'Copy external Claude user-global install command',
         kind: 'copy-command',
-        command: ['vgxness', 'mcp', 'install', 'claude', '--scope', 'project', '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
+        command: ['vgxness', 'mcp', 'install', 'claude', '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
         description: overwriteVgxness
-            ? 'Copy and run this outside setup status only after reviewing that VGXNESS entries will be overwritten and unrelated config preserved.'
-            : 'Copy and run this outside setup status only after reviewing the read-only plan.',
+            ? 'Copy and run this outside setup status only after reviewing that user-global VGXNESS entries will be overwritten and unrelated config preserved.'
+            : 'Copy and run this outside setup status only after reviewing the read-only user-global plan.',
         safety: externalProviderWriteSafety(targetPath),
     };
 }

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

@@ -8,8 +8,8 @@ export const openCodeSetupAdapter = {
     supportLevel: 'supported',
     capabilities: ['mcp-preview', 'mcp-install-plan', 'mcp-install-apply-external', 'agent-preview', 'doctor', 'visibility-check'],
     targets: [
-        { kind: 'user-config', label: 'User/global OpenCode config (default)', path: '$HOME/.config/opencode/opencode.json', writableBySetup: false },
-        { kind: 'project-config', label: 'Project OpenCode config (explicit opt-in)', path: '.opencode/opencode.json', writableBySetup: false },
+        { kind: 'user-config', label: 'Managed user-global OpenCode config', path: '$HOME/.config/opencode/opencode.json', writableBySetup: false },
+        { kind: 'project-config', label: 'Project OpenCode config (external/manual diagnostic only)', path: '.opencode/opencode.json', writableBySetup: false },
     ],
     getStatus(context) {
         const visibility = this.getVisibility?.(context);
@@ -21,7 +21,7 @@ export const openCodeSetupAdapter = {
                 ? 'OpenCode MCP visibility is ready.'
                 : 'OpenCode provider setup is available; install/apply remains external and explicit.',
             evidence: visibility?.evidence ?? ['OpenCode setup preview and install planning are available.'],
-            guidance: visibility?.guidance ?? ['Preview setup first, then copy and run external install commands only after review.'],
+            guidance: visibility?.guidance ?? ['VGXNESS will manage user-global provider configuration. Project-local provider files are external/manual diagnostics and will not be modified.'],
             actions: plan?.actions ?? [],
             ...previewField(openCodePlanPreview(visibility, plan)),
         };
@@ -52,7 +52,7 @@ export const openCodeSetupAdapter = {
             ...(context.overwriteVgxness !== undefined ? { overwriteVgxness: context.overwriteVgxness } : {}),
         });
         const targetPath = 'targetPath' in contract ? contract.targetPath : undefined;
-        const actions = contract.status === 'would_install' ? [externalInstallAction(contract.scope, targetPath, contract.overwriteVgxness)] : [];
+        const actions = contract.status === 'would_install' ? [externalInstallAction(targetPath, contract.overwriteVgxness)] : [];
         return {
             providerId: 'opencode',
             status: contract.status === 'would_install' ? 'available' : 'blocked',
@@ -61,8 +61,8 @@ export const openCodeSetupAdapter = {
             writesProviderConfig: false,
             summary: contract.status === 'would_install'
                 ? contract.overwriteVgxness
-                    ? `OpenCode ${contract.action} reinstall plan is available; confirmed apply overwrites VGXNESS entries only, preserves unrelated config, sets top-level permission.bash=ask and manager bash=allow, and creates managed backups for existing targets.`
-                    : `OpenCode ${contract.action} plan is available for external application; confirmed applies mcp.vgxness, top-level permission.bash=ask, and manager bash=allow, and creates managed VGXNESS backups when merging.`
+                    ? `OpenCode ${contract.action} reinstall plan is available for user-global provider configuration; confirmed apply overwrites VGXNESS entries only, preserves unrelated config, sets top-level permission.bash=ask and manager bash=allow, and creates managed backups for existing user-global targets.`
+                    : `OpenCode ${contract.action} plan is available for user-global provider configuration; confirmed applies mcp.vgxness, top-level permission.bash=ask, and manager bash=allow, and creates managed VGXNESS backups when merging. Project-local provider files are external/manual diagnostics and will not be modified.`
                 : contract.message,
             ...(targetPath !== undefined ? { targetPath } : {}),
             warnings: contract.warnings,
@@ -174,15 +174,15 @@ function isOpenCodeInstallContract(value) {
 function databasePathOrPlaceholder(context) {
     return context.databasePath ?? '<database-path>';
 }
-function externalInstallAction(scope, targetPath, overwriteVgxness = false) {
+function externalInstallAction(targetPath, overwriteVgxness = false) {
     return {
-        id: `opencode-mcp-install-${scope}`,
-        label: `Copy external OpenCode ${scope === 'user' ? 'user/global' : 'project'} install command`,
+        id: 'opencode-mcp-install-user-global',
+        label: 'Copy external OpenCode user-global install command',
         kind: 'copy-command',
-        command: ['vgxness', 'mcp', 'install', 'opencode', '--scope', scope, '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
+        command: ['vgxness', 'mcp', 'install', 'opencode', '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
         description: overwriteVgxness
-            ? 'Copy and run this outside the TUI only after reviewing that VGXNESS entries will be overwritten, unrelated config preserved, top-level bash prompts, and manager bash is allowed.'
-            : 'Copy and run this outside the TUI only after reviewing the read-only plan and scoped bash permission behavior.',
+            ? 'Copy and run this outside the TUI only after reviewing that user-global VGXNESS entries will be overwritten, unrelated config preserved, top-level bash prompts, and manager bash is allowed.'
+            : 'Copy and run this outside the TUI only after reviewing the read-only user-global plan and scoped bash permission behavior.',
         safety: externalProviderWriteSafety(targetPath),
     };
 }

package/dist/setup/setup-defaults.js

@@ -3,6 +3,7 @@ export const vgxnessSetupDefaults = {
     minimumNodeMajor: 22,
     defaultProvider: 'opencode',
     primaryProvider: 'opencode',
+    defaultProviderInstallTarget: 'user-global',
     defaultDatabaseMode: 'global',
     defaultOpenCodeScope: 'user',
     defaultInstallMode: 'mcp-plus-agents',

package/dist/setup/setup-plan.js

@@ -69,11 +69,11 @@ export function createSetupPlan(input) {
                             severity: 'blocking',
                             message: claude.message,
                             targetPath,
-                            recovery: claude.reason === 'malformed_claude_project_memory' || claude.reason === 'conflicting_claude_project_memory' ? 'Manually reconcile the VGXNESS markers in project-root CLAUDE.md, then rerun `vgxness setup plan --provider claude`.' : 'Inspect the Claude project config, resolve the conflict, then rerun `vgxness setup plan --provider claude`.',
+                            recovery: claude.reason === 'malformed_claude_project_memory' || claude.reason === 'conflicting_claude_project_memory' ? 'Manually reconcile the VGXNESS markers in user-global ~/.claude/CLAUDE.md, then rerun `vgxness setup plan --provider claude`.' : 'Inspect the Claude user-global config, resolve the conflict, then rerun `vgxness setup plan --provider claude`.',
                         },
                     ],
                     backupsPlanned: [],
-                    nextCommands: ['vgxness mcp install claude --plan --scope project', 'Resolve the reported Claude project conflict before guarded apply.'],
+                    nextCommands: ['vgxness mcp install claude --plan', 'Resolve the reported Claude user-global config conflict before guarded apply.'],
                 },
             };
         }
@@ -87,7 +87,7 @@ export function createSetupPlan(input) {
                 actions: [
                     {
                         id: 'claude-guarded-install',
-                        description: `Review first-class supported Claude plan for CLI MCP registration, .mcp.json compatibility, ${claude.agentNames.length} .claude/agents/*.md file(s), and guarded project-root CLAUDE.md managed block; apply only with vgxness mcp install claude --scope project --yes --run-id <id>.`,
+                        description: `Review first-class supported Claude user-global plan for CLI MCP registration, ~/.claude.json, ${claude.agentNames.length} ~/.claude/agents/*.md file(s), and guarded ~/.claude/CLAUDE.md managed block; project-local provider files are diagnostics only and will not be modified; apply only with vgxness mcp install claude --yes --run-id <id>.`,
                         mutating: false,
                         targetPath,
                         backupRequired: claude.backupRequired,
@@ -95,12 +95,12 @@ export function createSetupPlan(input) {
                 ],
                 conflicts: [],
                 backupsPlanned: claude.targets
-                    .filter((target) => target.kind !== 'cli-mcp-registration' && ((target.kind === 'project-memory' && target.backupRequired) || target.action === 'merge' || target.action === 'update-vgxness'))
+                    .filter((target) => target.kind !== 'cli-mcp-registration' && ((target.kind === 'user-memory' && target.backupRequired) || target.action === 'merge' || target.action === 'update-vgxness'))
                     .map((target) => ({
                     targetPath: target.path,
-                    reason: target.kind === 'project-memory' ? 'A future guarded Claude apply would create a managed VGXNESS backup before appending or updating the project-root CLAUDE.md managed block.' : 'A future guarded Claude apply would create a managed VGXNESS backup before merging or updating Claude project configuration.',
+                    reason: target.kind === 'user-memory' ? 'A future guarded Claude apply would create a managed VGXNESS backup before appending or updating the user-global ~/.claude/CLAUDE.md managed block.' : 'A future guarded Claude apply would create a managed VGXNESS backup before merging or updating Claude user-global configuration.',
                 })),
-                nextCommands: ['vgxness mcp install claude --plan --scope project', 'vgxness mcp install claude --scope project --yes --run-id <id>', 'OpenCode remains the default guided setup provider.'],
+                nextCommands: ['vgxness mcp install claude --plan', 'vgxness mcp install claude --yes --run-id <id>', 'OpenCode remains the default guided setup provider.'],
             },
         };
     }

package/docs/architecture.md

@@ -18,7 +18,7 @@ The user-facing shape is deliberately four-surface: **MCP for agents**, **CLI fo
 | Core workflow | SDD-first canonical state: explore → proposal → spec → design → tasks → apply-progress → verify → archive. |
 | Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows, and `vgxness code` runtime for bounded workspace work. |
 | Installation UX | Step-based guided setup with doctor checks, dry-run support, and no manual provider JSON editing on the happy path. |
-| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for CLI MCP registration, project `.mcp.json` compatibility, guarded `CLAUDE.md` managed memory, direct user `~/.claude.json` MCP merge, and project/user agent files. Claude scopes are `local`, `project`, and `user` (`personal`/`global` map to `user`). Read-only status/doctor/change-plan never execute Claude Code; user/global apply mutates only `mcpServers.vgxness`, VGXNESS-owned `~/.claude/agents/*.md`, and the VGXNESS block in `~/.claude/CLAUDE.md` after confirmation/preflight. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
+| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for user-global CLI MCP registration, direct user `~/.claude.json` MCP merge, and VGXNESS-owned user agent/memory files. VGX-managed OpenCode and Claude provider configuration is user-global only. Project-local provider files are external/manual diagnostics that may still affect providers externally, but VGXNESS does not repair, write, back up, or delete them. Read-only status/doctor/change-plan never execute providers. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
 | Memory | Project memory plus personal/global memory, backed locally. |
 | Agents | Agents/subagents are registered in a neutral schema, then rendered into provider-specific config. |
 | Skills | Skills are first-class, versioned, attachable to agents/workflows/adapters, and improved through reviewable proposals. |
@@ -97,7 +97,7 @@ The canonical agent manifest in `src/agents/canonical-agent-manifest.ts` is the
 
 ### Manager overlay parity across providers
 
-A user-saved `manager_profile_overlay` flows to both providers symmetrically. OpenCode consults the overlay inside `OpenCodeManagerPayloadService.applyManagerOverlayWhenAvailable` (`src/providers/opencode/manager-payload.ts:152-156`), which calls `ManagerProfileOverlayService.resolveEffectiveManager` before producing the OpenCode manager payload. Claude Code was previously canonical-only; the fix routes the overlay through `withEffectiveManagerInstructions` (`src/agents/canonical-agent-projection.ts`) into the render path (`expectedClaudeCodeRenderedAgents` / `expectedClaudeCodeRenderedUserAgents`), with the caller (`mcp install claude` in `src/cli/commands/mcp-dispatcher.ts`) computing the effective instructions via `computeEffectiveManagerInstructions(database)` and passing them into `installClaudeCodeMcpClient`. As a result, `vgxness mcp install claude` writes the user's customized instructions into `.claude/agents/vgxness-manager.md` instead of silently falling back to canonical.
+A user-saved `manager_profile_overlay` flows to both providers symmetrically. OpenCode consults the overlay inside `OpenCodeManagerPayloadService.applyManagerOverlayWhenAvailable` (`src/providers/opencode/manager-payload.ts:152-156`), which calls `ManagerProfileOverlayService.resolveEffectiveManager` before producing the OpenCode manager payload. Claude Code was previously canonical-only; the fix routes the overlay through `withEffectiveManagerInstructions` (`src/agents/canonical-agent-projection.ts`) into the render path (`expectedClaudeCodeRenderedAgents` / `expectedClaudeCodeRenderedUserAgents`), with the caller (`mcp install claude` in `src/cli/commands/mcp-dispatcher.ts`) computing the effective instructions via `computeEffectiveManagerInstructions(database)` and passing them into `installClaudeCodeMcpClient`. As a result, `vgxness mcp install claude` writes the user's customized instructions into the user-global `~/.claude/agents/vgxness-manager.md` instead of silently falling back to canonical; project-local Claude agent files remain external/manual diagnostics.
 
 ## Storage model
 
@@ -447,7 +447,7 @@ vgxness agents render --provider opencode --project vgxness --name apply-agent
 Rendering is intentionally read-only: it returns generated content in the CLI response. It does **not** write `.opencode/`, `.claude/`, or any user/global provider config.
 OpenCode agent keys are sanitized deterministically from registry names, and rendering rejects key collisions instead of overwriting generated config.
 
-Claude Code install planning/apply is supported through the guarded MCP install path. Rendering remains read-only; confirmed project compatibility writes are limited to `.mcp.json`, `.claude/agents/*.md`, and the project-root `CLAUDE.md` managed block with run preflight metadata. User/global install is a guarded direct path that backs up existing files, merges only `mcpServers.vgxness` in `~/.claude.json`, writes VGXNESS-owned `~/.claude/agents/*.md`, and manages only the VGXNESS block in `~/.claude/CLAUDE.md`.
+Claude Code install planning/apply is supported through the guarded MCP install path. Rendering remains read-only. VGX-managed Claude writes are user-global only: the guarded path backs up existing user-global files, merges only `mcpServers.vgxness` in `~/.claude.json`, writes VGXNESS-owned `~/.claude/agents/*.md`, and manages only the VGXNESS block in `~/.claude/CLAUDE.md`. Project-local `.mcp.json`, `.claude/agents/*.md`, and project-root `CLAUDE.md` are external/manual diagnostics and are not repaired, written, backed up, or deleted by VGXNESS setup.
 
 ### OpenCode injection preview
 

package/docs/cli.md

@@ -26,7 +26,7 @@ vgxness mcp start --db <temp-memory.sqlite> # then call verification_plan with {
 
 `vgxness setup plan` and `vgxness setup status` are human-readable and do not write provider config by default; local VGXNESS store initialization may occur when the selected SQLite store is needed. Pass `--json` when you need parseable automation output. The MCP plan does not write provider config. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
 
-Only apply the OpenCode user/global config after reviewing the plan (use `--scope project` only when you intentionally want project config):
+Only apply the OpenCode user-global config after reviewing the plan. VGXNESS does not manage project/local OpenCode or Claude provider files:
 
 ```bash
 vgxness mcp install opencode --yes --db "$VGXNESS_SMOKE_DB"
@@ -45,7 +45,7 @@ Release defaults used by the guided setup are:
 - Bun package evidence as the release artifact and isolated install-smoke path.
 - Provider: OpenCode.
 - Database: global user data location by default.
-- OpenCode scope: user/global config by default (`$HOME/.config/opencode/opencode.json`).
+- OpenCode/Claude provider config: user-global only for VGX-managed writes (`$HOME/.config/opencode/opencode.json`, `~/.claude.json`, `~/.claude/agents/*.md`, `~/.claude/CLAUDE.md`).
 - Install mode: MCP plus manager/SDD agents (`mcp-plus-agents`).
 - Public CLI language: English.
 
@@ -68,9 +68,9 @@ vgxness setup rollback --backup <path>
 
 Daily SDD phase progression is OpenCode-first: talk to OpenCode with the VGXNESS MCP server installed, and let the hidden SDD subagents use MCP tools for phase work. The CLI and TUI remain supported for bootstrap/setup, diagnostics, recovery, manual fallback, and scripting; they are not the primary daily surface.
 
-`setup plan`, `setup status`, and non-TTY `init` planning do not write provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
+`setup plan`, `setup status`, and non-TTY `init` planning do not write provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default and only VGX-managed OpenCode target is `$HOME/.config/opencode/opencode.json`; Claude managed targets are user-global (`~/.claude.json`, `~/.claude/agents/*.md`, and `~/.claude/CLAUDE.md`). `setup apply --yes` is the explicit provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current user-global target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
 
-`vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd cockpit`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
+`vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, user-global provider target, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd cockpit`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
 
 `vgxness sdd cockpit --json` returns the same additive compatibility shape as the MCP cockpit: all existing raw `SddCockpit` top-level fields remain present, with an additional top-level `readModel`. The cockpit is read-only and metadata-only: it does not include artifact bodies, infer acceptance from artifact presence, advance phases, execute acceptance, call providers, or write provider config. Text output renders from read-model concepts such as next action, phase metadata, blockers, guidance, and `Content included: no`.
 
@@ -256,7 +256,7 @@ bun run cli:bun -- resume --project vgxness --run-id <id>
 Provider support shown in the Installation surface is:
 
 - **OpenCode** — supported primary provider with preview/status/doctor and read-only install planning.
-- **Claude** — supported secondary provider for Claude CLI MCP registration, project `.mcp.json` compatibility, guarded `CLAUDE.md` managed memory, user `~/.claude.json` MCP merge, and project/user agents. Scopes are `local|project|user`; `personal`/`global` map to `user`. Explicit guarded apply is outside the guided OpenCode flow and requires `mcp install claude --scope <scope> --yes --run-id <id>`. Read-only status/doctor/change-plan do not execute Claude Code.
+- **Claude** — supported secondary provider for user-global Claude CLI MCP registration, user `~/.claude.json` MCP merge, and VGXNESS-owned user agents/memory. Project-local Claude files are external/manual diagnostics only. Explicit guarded apply is outside the guided OpenCode flow and requires `mcp install claude --scope user --yes --run-id <id>`. Read-only status/doctor/change-plan do not execute Claude Code.
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
@@ -469,55 +469,53 @@ bun run cli:bun -- mcp setup --preview --provider claude --db <path>
 bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke
 ```
 
-The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`. For Claude config, inspect `mcp install claude --plan --scope local|project|user`; confirmed writes or CLI execution require `mcp install claude --scope <scope> --yes --run-id <id>` so VGXNESS run preflight can authorize each target.
+The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the only VGX-managed target is `$HOME/.config/opencode/opencode.json`. For Claude config, inspect `mcp install claude --plan --scope user`; confirmed writes require `mcp install claude --scope user --yes --run-id <id>` so VGXNESS run preflight can authorize user-global targets.
 
 The top-level `vgxness doctor` command prints human-readable readiness checks by default and accepts `--json` for scriptable output. Lower-level `mcp doctor` remains useful for MCP-specific checks and manual diagnostics; use `--json` where parseable output is needed. `ready:true` means required checks passed. `ready:false` means at least one required check failed; read the failed check `id`, `detail`, and optional `remediation` to fix the local setup, then run doctor again.
 
 ## OpenCode MCP visibility
 
-Use this read-only diagnostic when you need to confirm why OpenCode sees the project-local `vgxness` server from the repo but not from outside the worktree:
+Use this read-only diagnostic when you need to understand OpenCode visibility for the current workspace and any external/manual project-local provider files:
 
 ```bash
 bun run cli:bun -- mcp doctor opencode
 opencode mcp list
 ```
 
-Run both commands from the `vgxness` repo or a directory inside its worktree. The diagnostic reports the current cwd, detected project root, expected project target `.opencode/opencode.json`, optional user target `$HOME/.config/opencode/opencode.json`, whether each target contains `mcp.vgxness`, and whether the project config is inside OpenCode's project-local discovery boundary for the current cwd.
+Run both commands from the `vgxness` repo or a directory inside its worktree. The diagnostic reports the current cwd, detected project root, managed user-global target `$HOME/.config/opencode/opencode.json`, external/manual project-local paths such as `.opencode/opencode.json`, whether each contains `mcp.vgxness`, and whether project-local config is inside OpenCode's discovery boundary for the current cwd.
 
-Expected happy path: after OpenCode starts inside `vgxness`, `opencode mcp list` should show `vgxness` with the registered VGXNESS MCP tools exposed by the current build. Treat `SUPPORTED_VGX_MCP_TOOL_NAMES` and `client.listTools()` as the source of truth rather than a fixed count. Restart OpenCode if the server is not listed after project-local config changes.
+Expected happy path: after OpenCode starts inside `vgxness`, `opencode mcp list` should show `vgxness` with the registered VGXNESS MCP tools exposed by the current build. Treat `SUPPORTED_VGX_MCP_TOOL_NAMES` and `client.listTools()` as the source of truth rather than a fixed count. Restart OpenCode if the server is not listed after user-global config changes.
 
-From a parent directory or another path outside the worktree, the project-local `vgxness` server is not expected to appear. Use `mcp install opencode --scope user --plan` to inspect the user/global target without writing it. OpenCode may load project config with higher precedence than user config for a workspace, so check project config first when both define `mcp.vgxness`.
+From a parent directory or another path outside the worktree, project-local provider files may not affect OpenCode. Use `mcp install opencode --scope user --plan` to inspect the user-global target without writing it. OpenCode may load project config with higher precedence than user config for a workspace, so status/doctor reports project-local files as external/manual diagnostics. VGXNESS will not repair, write, back up, or delete them.
 
 ## OpenCode MCP install
 
-Use the installer when you want `vgxness` registered in OpenCode instead of copying the setup preview by hand. User/global scope is the default; project scope is opt-in:
+Use the installer when you want `vgxness` registered in OpenCode instead of copying the setup preview by hand. User-global scope is the default and only VGX-managed target:
 
 ```bash
 bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke
 bun run cli:bun -- mcp install opencode --plan
 bun run cli:bun -- mcp install opencode --yes
-bun run cli:bun -- mcp install opencode --plan --scope project --db <path>
-bun run cli:bun -- mcp install opencode --yes --scope project --db <path>
 ```
 
-Use `--plan` first when you want concrete target analysis without mutation. It prints the same OpenCode install contract the apply path uses, including `scope`, `targetPath`, `safety`, backup requirement, merge policy, verification hints, and any refusal reason. It does not create `.opencode/`, write user config, touch `$HOME/.config/opencode`, or create backups. User/global scope plans target `$HOME/.config/opencode/opencode.json` by default; project scope requires explicit `--scope project` and targets only the project config path.
+Use `--plan` first when you want concrete target analysis without mutation. It prints the same OpenCode install contract the apply path uses, including `scope`, `targetPath`, `safety`, backup requirement, merge policy, verification hints, and any refusal reason. It does not create `.opencode/`, write user config, touch `$HOME/.config/opencode`, or create backups. User/global scope plans target `$HOME/.config/opencode/opencode.json`; project/local install scopes are rejected with migration guidance.
 
 The `--yes` flag is required for apply because this path writes OpenCode config. If `--db` and `VGXNESS_DB_PATH` are omitted, the installed server and manual doctor commands omit `--db` and resolve the global default database at runtime. Pass `--db .vgx/memory.sqlite` when you intentionally want the old project-local database, or another explicit path when you need an isolated store preserved in the installed command.
 
-On success, the installer creates or updates exactly one target: project scope writes `<workspace>/.opencode/opencode.json`; user scope writes `$HOME/.config/opencode/opencode.json`. It writes top-level `mcp.vgxness` as an OpenCode local server, preserves unrelated fields and `$schema`, and reports the installed `targetPath`, optional `backupPath`, server command, restart warning, and manual doctor command.
+On success, the installer creates or updates exactly one user-global target: `$HOME/.config/opencode/opencode.json`. It writes top-level `mcp.vgxness` as an OpenCode local server, preserves unrelated fields and `$schema`, and reports the installed `targetPath`, optional `backupPath`, server command, restart warning, and manual doctor command.
 
 Safety boundaries:
 
-- User/global scope is the default. `--scope user` is an explicit alias for the default; `--scope project` is required for `<workspace>/.opencode/opencode.json`.
+- User/global scope is the default. `--scope user`, `--scope global`, and `--scope personal` are user-global aliases; `--scope project` and `--scope local` are rejected for managed provider writes.
 - `--plan` is read-only and `--yes` is the explicit mutating apply path.
 - It refuses to proceed without `--yes`.
 - It refuses ambiguous project targets, missing `HOME` for user scope, malformed JSON, JSONC config, unsupported `mcp` shapes, and existing `mcp.vgxness` by default.
-- Before modifying an existing JSON config, it writes a sibling backup such as `.opencode/opencode.json.backup-20260515T052852123Z` or `$HOME/.config/opencode/opencode.json.backup-20260515T052852123Z`.
-- OpenCode project config may override user config for a workspace; if user-scope install succeeds but `vgxness` is not visible, inspect project `.opencode/opencode.json` first.
+- Before modifying an existing JSON config, it writes a sibling backup such as `$HOME/.config/opencode/opencode.json.backup-20260515T052852123Z`.
+- OpenCode project config may override user config for a workspace; if user-scope install succeeds but `vgxness` is not visible, inspect project `.opencode/opencode.json` as external/manual config. VGXNESS will not repair, write, back up, or delete it.
 
 Rollback is file-based:
 
-- If install created a new config, delete the reported `targetPath` (`.opencode/opencode.json` for project scope or `$HOME/.config/opencode/opencode.json` for user scope).
+- If install created a new config, delete the reported user-global `targetPath` (`$HOME/.config/opencode/opencode.json`).
 - If install modified an existing config, restore the reported backup over `targetPath`.
 - Run `bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke` again after rollback.
 
@@ -532,38 +530,36 @@ Manual OpenCode verification checklist:
 
 ## Claude Code MCP install
 
-Claude Code is supported as a secondary, non-default provider for VGXNESS MCP/subagent configuration. Planning/status/doctor/change-plan are read-only and do not require Claude Code, network, or credentials. Scopes are `local`, `project`, and `user`; compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as structured config/argv (`claude mcp add --scope <scope> vgxness -- vgxness mcp start`), never shell strings. User/global apply narrowly merges only `mcpServers.vgxness` in `~/.claude.json` and preserves unknown keys/auth/session data.
+Claude Code is supported as a secondary, non-default provider for VGXNESS MCP/subagent configuration. Planning/status/doctor/change-plan are read-only and do not require Claude Code, network, or credentials. VGX-managed Claude writes are user-global only; compatibility aliases `personal` and legacy `global` map to `user`. MCP registration is represented as structured config/argv (`claude mcp add --scope user vgxness -- vgxness mcp start`), never shell strings. User/global apply narrowly merges only `mcpServers.vgxness` in `~/.claude.json`, writes VGXNESS-owned user agent/memory files, and preserves unknown keys/auth/session data.
 
 ```bash
-bun run cli:bun -- mcp install claude --plan --scope project --db <path>
 bun run cli:bun -- mcp install claude --plan --scope user --db <path>
-bun run cli:bun -- mcp install claude --yes --scope project --run-id <id> --db <path>
+bun run cli:bun -- mcp install claude --yes --scope user --run-id <id> --db <path>
 ```
 
-Allowed project-scope writes after explicit confirmation and run preflight:
+Project-local provider files are external/manual diagnostics only:
 
 - `.mcp.json`
 - `.claude/agents/*.md`
-- project-root `CLAUDE.md`, only the VGXNESS managed block; user-authored content outside the block is preserved and existing files are backed up before append/update
+- project-root `CLAUDE.md`
 
-User agent files target `~/.claude/agents/*.md` only when a future apply path explicitly preflights that external directory. Read-only plans/status/doctor/change-plan never write it.
+Existing files remain untouched by VGXNESS setup. They may still affect Claude Code behavior externally, but VGXNESS will not repair, write, back up, or delete them.
 
 Forbidden writes:
 
-- `~/.claude.json` except guarded user/global `mcpServers.vgxness` merge
+- project-local `.mcp.json`, `.claude/agents/*.md`, and project-root `CLAUDE.md`
 - `.claude/CLAUDE.md`; user/global uses `~/.claude/CLAUDE.md` and manages only the VGXNESS block
 
-Malformed or conflicting VGXNESS markers in project-root `CLAUDE.md` refuse the full Claude project install before any Claude target is mutated.
+Malformed or conflicting VGXNESS markers in project-root `CLAUDE.md` are reported as advisory diagnostics only; they do not cause VGXNESS to mutate project-local Claude files.
 
 Manual/opt-in runtime validation checklist (not normal CI):
 
-1. Apply Claude project-local config through the guarded VGXNESS flow.
+1. Apply Claude user-global config through the guarded VGXNESS flow.
 2. Open Claude Code in the project manually.
-3. Approve the project MCP server if prompted.
-4. Run `/mcp` and verify `vgxness` is connected.
-5. Run `/agents` and verify expected project subagents are visible.
-6. Ask Claude to call a safe read-only VGXNESS MCP tool.
-7. Confirm forbidden files were not written by VGXNESS.
+3. Run `/mcp` and verify `vgxness` is connected.
+4. Run `/agents` and verify expected user-global subagents are visible.
+5. Ask Claude to call a safe read-only VGXNESS MCP tool with a project context.
+6. Confirm project-local provider files were not written, backed up, repaired, or deleted by VGXNESS.
 
 ## SDD workflow examples
 

package/docs/glossary.md

@@ -8,7 +8,7 @@ A human-only action that records explicit approval of a SDD phase artifact. `vgx
 
 ## Adapter
 
-A translator between VGXNESS's provider-neutral domain and a specific provider. The control plane uses renderers/install planners (OpenCode, JSON, Claude project-local support). The code runtime uses `CodeProviderAdapter` implementations (`openai-compatible`, `fake`).
+A translator between VGXNESS's provider-neutral domain and a specific provider. The control plane uses renderers/install planners for OpenCode, JSON previews, and user-global Claude support. The code runtime uses `CodeProviderAdapter` implementations (`openai-compatible`, `fake`).
 
 ## Agent
 
@@ -92,7 +92,7 @@ The provider-agnostic front-door classifier for operator text. Maps an intent to
 
 ## OpenCode
 
-The primary/default supported provider for the control plane. The configurator renders OpenCode MCP config and manager/SDD agent definitions. Claude Code is supported secondary for project-local VGXNESS MCP/subagent configuration through explicit guarded apply.
+The primary/default supported provider for the control plane. The configurator renders OpenCode MCP config and manager/SDD agent definitions. VGX-managed OpenCode and Claude provider configuration is user-global only; project-local provider files are external/manual diagnostics and remain outside VGXNESS repair/write/delete flows.
 
 ## Operation attempt
 

package/docs/mcp.md

@@ -148,7 +148,7 @@ vgxness_run_resume_gate       { approvalId, policy }
 
 MCP tools do not:
 
-- Write provider config (`.opencode/`, `.claude/`, `opencode.json`, `CLAUDE.md`).
+- Write project-local provider config (`.opencode/`, `.mcp.json`, `.claude/`, project-root `CLAUDE.md`). VGX-managed OpenCode and Claude writes are user-global only and must stay behind explicit install/apply confirmation outside read-only status/preview tools.
 - Execute providers (`opencode`, `claude`, etc.).
 - Install global memory.
 - Create `openspec/`.

package/docs/prd.md

@@ -202,8 +202,8 @@ The same flow must be available through CLI flags for automation and CI-friendly
 
 Initial integration targets:
 
-- OpenCode — primary supported provider. The configurator plane renders OpenCode MCP config and manager/SDD agent definitions; the code runtime speaks to any OpenAI-compatible endpoint, including OpenCode's local bridge.
-- Claude Code — supported secondary for project-local VGXNESS MCP/subagent configuration and guarded project-root `CLAUDE.md` managed memory. Confirmed writes are explicit and guarded (`.mcp.json`, `.claude/agents/*.md`, and the `CLAUDE.md` managed block only); VGXNESS does not install/execute Claude Code and never manually writes `~/.claude.json` or `.claude/CLAUDE.md`.
+- OpenCode — primary supported provider. VGX-managed configuration is user-global only; the code runtime speaks to any OpenAI-compatible endpoint, including OpenCode's local bridge.
+- Claude Code — supported secondary for user-global VGXNESS MCP/subagent configuration. VGX-managed configuration is user-global only (`~/.claude.json`, `~/.claude/agents/*.md`, and `~/.claude/CLAUDE.md` after confirmation/preflight). Project-local provider files remain external/manual diagnostics and may still affect Claude Code externally, but VGXNESS does not repair, write, back up, or delete them.
 
 Pi/`gentle-pi` is a design reference and future adapter target, not part of the first integration target list unless the MVP scope is explicitly expanded.
 
@@ -351,7 +351,7 @@ Many of the early PRD questions are resolved in v1.5.1. Tracking them here keeps
 
 | Question | Resolved as of v1.5.1 |
 |---|---|
-| First integration adapter | OpenCode primary/default; Claude is supported secondary for project-local explicit apply. |
+| First integration adapter | OpenCode primary/default; Claude is supported secondary for user-global explicit apply. Project-local provider files are external/manual diagnostics only. |
 | Memory storage scopes | Project memory and personal/global memory live in separate SQLite stores; `--db` flag and `VGXNESS_DB_PATH` env var override. |
 | Agent config format | Provider-neutral schema in `src/agents/schema.ts`; canonical manifest with validation in `src/agents/canonical-agent-manifest.ts`. |
 | Skill config format | Versioned skills with source metadata (`path`/`url`/`inline`); active version gating in `src/skills/skill-registry-service.ts`. |

package/docs/providers.md

@@ -6,8 +6,8 @@ VGXNESS is provider-agnostic at the core: the registry stores provider-neutral d
 
 | Provider | Control plane | Code runtime | Notes |
 |---|---|---|---|
-| OpenCode | `managed` | n/a (target) | Primary supported provider. The configurator renders OpenCode MCP config and manager/SDD agent definitions into the chosen scope. |
-| Claude Code | `supported-secondary` | n/a | Supported for Claude CLI MCP registration planning/apply, project `.mcp.json` compatibility, guarded `CLAUDE.md` managed memory, user `~/.claude.json` MCP merge, and project/user agent files. Scopes are `local`, `project`, and `user`; `personal`/`global` map to `user` for compatibility. Confirmed applies are explicit and guarded; read-only surfaces inspect files without executing Claude Code. |
+| OpenCode | `managed` | n/a (target) | Primary supported provider. VGX-managed provider configuration is user-global only; project-local OpenCode files are external/manual diagnostics. |
+| Claude Code | `supported-secondary` | n/a | Supported for user-global Claude CLI MCP registration planning/apply, `~/.claude.json` MCP merge, and VGXNESS-owned user agent/memory files. Project `.mcp.json`, `.claude/agents/*.md`, and `CLAUDE.md` are external/manual diagnostics only. |
 | Antigravity | `placeholder` | n/a | Listed in the TUI Installation surface as coming-soon. |
 | Custom / future | `extension` | extension point | Per the [Architecture](./architecture.md) decision, anything not OpenCode or Claude is a custom extension. |
 | OpenAI-compatible | n/a | `openai-compatible-provider-adapter.ts` | Real adapter used by `vgxness code`. Speaks to any OpenAI-compatible endpoint. |
@@ -46,32 +46,31 @@ vgxness agents render --provider json --project vgxness --name apply-agent
 
 Claude Code is supported as a secondary, non-default control-plane target. Status, doctor, setup plan, and change-plan surfaces can inspect or preview Claude targets without Claude Code installed and without writing provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed.
 
-Claude scopes are canonicalized to `local`, `project`, and `user`; VGXNESS compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as structured config/argv, for example `claude mcp add --scope user vgxness -- vgxness mcp start`; no shell strings are generated. For user/global apply, VGXNESS narrowly merges only `mcpServers.vgxness` in `~/.claude.json`, preserves unknown keys, backs up existing files, and does not manage auth/session data. Status/doctor/change-plan are read-only and do not execute Claude Code.
+VGX-managed Claude provider configuration is user-global only. Compatibility aliases `personal` and legacy `global` map to Claude `user`; project/local install scopes are rejected for managed writes. MCP registration is represented as structured config/argv, for example `claude mcp add --scope user vgxness -- vgxness mcp start`; no shell strings are generated. For user/global apply, VGXNESS narrowly merges only `mcpServers.vgxness` in `~/.claude.json`, preserves unknown keys, backs up existing user-global files, writes VGXNESS-owned `~/.claude/agents/*.md` and `~/.claude/CLAUDE.md`, and does not manage auth/session data. Status/doctor/change-plan are read-only and do not execute Claude Code.
 
-Allowed project-scope writes, only after explicit guarded apply with run preflight metadata (`vgxness mcp install claude --scope project --yes --run-id <id>`):
+Project-local provider files are external/manual diagnostics only:
 
 - `.mcp.json`
 - `.claude/agents/*.md`
-- project-root `CLAUDE.md`, only the VGXNESS managed block; user content outside the block is preserved exactly and existing files are backed up before append/update
+- project-root `CLAUDE.md`
 
-User-scoped agent files target `~/.claude/agents/*.md` only as an explicit external-directory/preflighted operation. They are never written by read-only planning/status/doctor/change-plan.
+These files remain untouched by VGXNESS setup. They may still affect Claude Code behavior externally, but VGXNESS will not repair, write, back up, or delete them. Runtime VGXNESS state remains project-aware through the selected project, workspace root, change, and database context.
 
 Forbidden writes:
 
-- `~/.claude.json` except the guarded user/global merge of `mcpServers.vgxness`
+- project-local `.mcp.json`, `.claude/agents/*.md`, and project-root `CLAUDE.md`
 - `.claude/CLAUDE.md`; user/global memory is `~/.claude/CLAUDE.md` and only the VGXNESS managed block is touched
 
-Malformed, duplicate, partial, or conflicting VGXNESS markers in `CLAUDE.md` cause the full Claude project install to be refused before `.mcp.json`, `.claude/agents/*.md`, or `CLAUDE.md` are mutated.
+Malformed, duplicate, partial, or conflicting VGXNESS markers in project-root `CLAUDE.md` are reported as advisory diagnostics only and do not cause VGXNESS to mutate project-local Claude files.
 
 Manual/opt-in runtime validation checklist (not normal CI):
 
-1. Apply Claude project-local config through the guarded VGXNESS flow.
+1. Apply Claude user-global config through the guarded VGXNESS flow.
 2. Open Claude Code in the project manually.
-3. Approve the project MCP server if prompted.
-4. Run `/mcp` and verify `vgxness` is connected.
-5. Run `/agents` and verify expected project subagents are visible.
-6. Ask Claude to call a safe read-only VGXNESS MCP tool.
-7. Confirm forbidden files were not written by VGXNESS.
+3. Run `/mcp` and verify `vgxness` is connected.
+4. Run `/agents` and verify expected user-global subagents are visible.
+5. Ask Claude to call a safe read-only VGXNESS MCP tool with project context.
+6. Confirm project-local provider files were not written, backed up, repaired, or deleted by VGXNESS.
 
 ### OpenCode injection preview
 
@@ -140,7 +139,7 @@ Provider config writes happen only through `apply` with explicit consent. Plans,
 
 Adapters and renderers must not:
 
-- Write provider config outside explicit guarded apply. OpenCode install writes only its selected target; Claude project compatibility apply writes only `.mcp.json`, `.claude/agents/*.md`, and the guarded project-root `CLAUDE.md` managed block. Claude user/global apply narrowly merges `mcpServers.vgxness` in `~/.claude.json`, writes VGXNESS-owned `~/.claude/agents/*.md`, and manages only the VGXNESS block in `~/.claude/CLAUDE.md` after confirmation/preflight.
+- Write provider config outside explicit guarded apply. VGX-managed OpenCode and Claude writes are user-global only. Project-local provider files such as `.opencode/`, `opencode.json`, `.mcp.json`, `.claude/agents/*.md`, and project-root `CLAUDE.md` are external/manual diagnostics and must not be repaired, written, backed up, or deleted by VGXNESS setup.
 - Call providers (`opencode`, `claude`, etc.) during preview or status.
 - Install global memory.
 - Create `openspec/`.

package/docs/roadmap.md

@@ -63,7 +63,7 @@ The main menu and setup screens are in via OpenTUI. The dashboard directory is e
 
 ## Provider coverage
 
-- **Claude Code runtime validation.** Project-local install planning/apply is supported behind explicit run preflight. Remaining work is optional manual runtime smoke guidance or future live smoke tooling; it must stay out of normal CI.
+- **Claude Code runtime validation.** User-global install planning/apply is supported behind explicit run preflight. Project-local Claude files are external/manual diagnostics only. Remaining work is optional manual runtime smoke guidance or future live smoke tooling; it must stay out of normal CI.
 - **Antigravity and other custom adapters.** Listed as placeholders; a real adapter would unblock those workflows.
 - **Provider doctor upgrades.** Doctor checks could surface real config drift, not just existence of expected files.
 

package/docs/safety.md

@@ -133,7 +133,7 @@ Retry policy evaluation is separate from execution. `vgxness_run_resume_gate` ev
 ## Safety boundaries (enforced everywhere)
 
 - Read-only/preview commands must not mutate provider config or external tool state: setup plans, MCP setup previews, OpenCode previews, workflow previews, status views, and the natural-language orchestrator preview never write provider config, call providers, or install global memory. Local VGXNESS store initialization may occur when a command needs the selected SQLite store.
-- Provider config writes (`opencode.json`, `.opencode/`, `.claude/`, `CLAUDE.md`) require explicit consent (`--yes` or an equivalent confirmed flow) plus backup/rollback behavior.
+- VGX-managed OpenCode and Claude provider config writes are user-global only and require explicit consent (`--yes` or an equivalent confirmed flow) plus backup/rollback behavior. Project-local provider files such as `.opencode/`, `.mcp.json`, `.claude/`, and project-root `CLAUDE.md` are external/manual diagnostics: VGXNESS may report that they exist and may affect provider behavior externally, but it must not repair, write, back up, or delete them.
 - The control plane and the code runtime do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys.
 - Human acceptance is distinct from artifact presence: `vgxness_sdd_accept_artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
 - Unrelated user work is preserved. Workspace boundary denials cannot be relaxed by agent or subagent overrides.

package/docs/storage.md

@@ -80,7 +80,7 @@ The schema follows a small set of conventions:
 
 There is no automatic backup of the SQLite database in v1.5.1. The recommended pattern is to treat the database file as a normal file in the user's data directory and use OS-level snapshots if needed.
 
-Provider config (OpenCode) has its own backup/rollback path through `vgxness setup rollback --backup <path>`. That is separate from the database and is documented in the [CLI reference](./cli.md).
+VGX-managed provider config backups/rollback apply to user-global OpenCode/Claude targets only. Project-local provider files remain untouched external/manual diagnostics: they may still affect provider behavior externally, but VGXNESS will not repair, write, back up, or delete them. Provider config recovery is separate from the database and is documented in the [CLI reference](./cli.md).
 
 ## Wiping and migrating
 

package/package.json

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