vgxness 1.6.0 → 1.7.0

package/dist/cli/cli-help.js

@@ -69,7 +69,7 @@ Areas:
   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 secondary. Claude scopes are local|project|user; compatibility aliases personal/global map to user with warnings. Plans show Claude CLI argv, project .mcp.json compatibility, agents, and guarded project-root CLAUDE.md managed memory separately. Project scope confirmed applies write .mcp.json, .claude/agents/*.md, and the CLAUDE.md managed block as needed. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). VGXNESS does not manually read/write ~/.claude.json or private Claude config; status/doctor/change-plan are read-only and do not execute Claude Code.
+  Claude support is secondary. 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.
 
   skills register --project <name> --name <name> --description <text>
   skills list [--project <name>] [--scope project|personal]

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

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isManagedClaudeCodeMcpServer } from './claude-code-config.js';
+import { safeHomeDirectory } from './claude-code-agent-config.js';
+export function resolveClaudeCodeUserMcpJsonPath(env = process.env) {
+    return join(safeHomeDirectory(env), '.claude.json');
+}
+export function inspectClaudeCodeUserMcpConfig(env = process.env) {
+    const path = resolveClaudeCodeUserMcpJsonPath(env);
+    if (!existsSync(path))
+        return { status: 'missing', path, exists: false, parsed: false, message: 'Claude user ~/.claude.json does not exist.' };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!isRecord(parsed))
+            return { status: 'invalid', path, exists: true, parsed: false, message: 'Claude user ~/.claude.json must be a JSON object.' };
+        if (parsed.mcpServers !== undefined && !isRecord(parsed.mcpServers))
+            return { status: 'invalid', path, exists: true, parsed: false, message: 'Claude user ~/.claude.json mcpServers must be a JSON object.' };
+        const entry = isRecord(parsed.mcpServers) ? parsed.mcpServers.vgxness : undefined;
+        if (entry === undefined)
+            return { status: 'stale', path, exists: true, parsed: true, config: parsed, message: 'Claude user ~/.claude.json is readable but mcpServers.vgxness is missing.' };
+        if (isManagedClaudeCodeMcpServer(entry))
+            return { status: 'configured', path, exists: true, parsed: true, config: parsed, message: 'Claude user ~/.claude.json has a managed mcpServers.vgxness entry.' };
+        return { status: 'conflicting', path, exists: true, parsed: true, config: parsed, message: 'Claude user ~/.claude.json has a conflicting mcpServers.vgxness entry.' };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { status: 'invalid', path, exists: true, parsed: false, message: `Claude user ~/.claude.json could not be read or parsed: ${message}` };
+    }
+}
+export function mergeClaudeCodeUserMcpConfig(existing, server) {
+    return { ...existing, mcpServers: { ...(isRecord(existing.mcpServers) ? existing.mcpServers : {}), vgxness: server } };
+}
+export function claudeUserMcpConfigPathStatus(state) {
+    return {
+        label: 'user ~/.claude.json',
+        path: state.path,
+        exists: state.exists,
+        readable: state.status !== 'invalid',
+        parsed: state.parsed,
+        status: state.status === 'configured' ? 'pass' : state.status === 'invalid' || state.status === 'conflicting' ? 'fail' : 'not-configured',
+        detail: state.message,
+    };
+}
+export function claudeUserMcpEntryStatus(state) {
+    if (state.status === 'configured')
+        return { configured: true, status: 'pass', serverName: 'vgxness', enabled: true, detail: state.message };
+    if (state.status === 'conflicting')
+        return { configured: true, status: 'fail', serverName: 'vgxness', detail: state.message };
+    if (state.status === 'invalid')
+        return { configured: false, status: 'fail', serverName: 'vgxness', detail: state.message };
+    return { configured: false, status: 'not-configured', serverName: 'vgxness', detail: state.message };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../agents/canonical-agent-projection.js';
+import { safeHomeDirectory } from './claude-code-agent-config.js';
+export const claudeUserMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE USER MEMORY -->';
+export const claudeUserMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE USER MEMORY -->';
+export function resolveClaudeUserMemoryPath(env = process.env) {
+    return join(safeHomeDirectory(env), '.claude', 'CLAUDE.md');
+}
+export function renderClaudeUserMemoryBlock() {
+    const projection = projectCanonicalAgentManifestToClaudeProjectMemory();
+    return [
+        claudeUserMemoryBeginMarker,
+        `<!-- VGXNESS-GENERATED owner=vgxness provider=claude artifact=claude-user-memory safe-update=true defaultAgent=${projection.defaultAgent} promptContractVersion=${projection.promptContractVersion} canonicalSource=canonical-agent-manifest repositoryInstructions=${projection.repositoryInstructions} -->`,
+        '',
+        '# VGXNESS Claude User Memory',
+        '',
+        'Global/user Claude Code guidance installed by VGXNESS. Use the VGXNESS MCP server for SDD, runs, memory, provider status, and governance-aware workflow progress.',
+        '',
+        ...projection.guidance.slice(1).map((line) => `- ${line}`),
+        '',
+        claudeUserMemoryEndMarker,
+    ].join('\n');
+}
+export function inspectClaudeUserMemory(env = process.env) {
+    const path = resolveClaudeUserMemoryPath(env);
+    if (!existsSync(path))
+        return { status: 'missing', path, exists: false, action: 'create', backupRequired: false, message: 'Claude user memory ~/.claude/CLAUDE.md does not exist.' };
+    let contents;
+    try {
+        const bytes = readFileSync(path);
+        contents = bytes.toString('utf8');
+        if (!Buffer.from(contents, 'utf8').equals(bytes))
+            return blocked(path, true, 'non_utf8', 'Claude user memory is not valid UTF-8; refusing safe managed-block updates.');
+    }
+    catch (cause) {
+        return blocked(path, true, 'unreadable', `Claude user memory could not be read: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const beginCount = countOccurrences(contents, claudeUserMemoryBeginMarker);
+    const endCount = countOccurrences(contents, claudeUserMemoryEndMarker);
+    if (beginCount === 0 && endCount === 0)
+        return { status: 'unmanaged', path, exists: true, action: 'append-managed-block', backupRequired: true, message: 'Claude user memory exists without a VGXNESS managed block; apply would append one after backup.', contents };
+    if (beginCount === 0)
+        return blocked(path, true, 'missing_begin_marker', 'Claude user memory has an end marker without a begin marker.');
+    if (endCount === 0)
+        return blocked(path, true, 'missing_end_marker', 'Claude user memory has a begin marker without an end marker.');
+    if (beginCount > 1 || endCount > 1)
+        return blocked(path, true, 'duplicate_markers', 'Claude user memory has duplicate VGXNESS managed-block markers.');
+    const start = contents.indexOf(claudeUserMemoryBeginMarker);
+    const endMarkerStart = contents.indexOf(claudeUserMemoryEndMarker);
+    if (endMarkerStart < start)
+        return blocked(path, true, 'reordered_markers', 'Claude user memory end marker appears before begin marker.');
+    const end = endMarkerStart + claudeUserMemoryEndMarker.length;
+    const inner = contents.slice(start + claudeUserMemoryBeginMarker.length, endMarkerStart);
+    if (inner.includes(claudeUserMemoryBeginMarker) || inner.includes(claudeUserMemoryEndMarker))
+        return blocked(path, true, 'nested_markers', 'Claude user memory has nested VGXNESS managed-block markers.');
+    if (!inner.includes('owner=vgxness') || !inner.includes('provider=claude') || !inner.includes('artifact=claude-user-memory') || !inner.includes('safe-update=true'))
+        return blocked(path, true, 'conflicting_ownership', 'Claude user memory managed block is not a VGXNESS-owned user-memory block.');
+    const expected = renderClaudeUserMemoryBlock();
+    const actual = contents.slice(start, end);
+    if (actual === expected)
+        return { status: 'managed-current', path, exists: true, action: 'none', backupRequired: false, message: 'Claude user memory has the current VGXNESS managed block.', blockRange: { start, end }, contents };
+    return { status: 'managed-stale', path, exists: true, action: 'update-managed-block', backupRequired: true, message: 'Claude user memory has a stale VGXNESS managed block; apply would update only that block after backup.', blockRange: { start, end }, staleReasons: ['managed_block_differs_from_canonical_render'], contents };
+}
+export function mergeClaudeUserMemory(state) {
+    const block = renderClaudeUserMemoryBlock();
+    if (state.status === 'missing')
+        return { ok: true, value: { path: state.path, contents: `${block}\n` } };
+    if (state.status === 'unmanaged') {
+        const separator = state.contents.length === 0 ? '' : state.contents.endsWith('\n') ? '\n' : '\n\n';
+        return { ok: true, value: { path: state.path, contents: `${state.contents}${separator}${block}\n` } };
+    }
+    if (state.status === 'managed-stale')
+        return { ok: true, value: { path: state.path, contents: state.contents.slice(0, state.blockRange.start) + block + state.contents.slice(state.blockRange.end) } };
+    if (state.status === 'managed-current')
+        return { ok: true, value: { path: state.path, contents: state.contents } };
+    return { ok: false, error: { code: 'validation_failed', message: state.message } };
+}
+function blocked(path, exists, reason, message) {
+    return { status: 'blocked', path, exists, action: 'blocked', backupRequired: false, reason, message };
+}
+function countOccurrences(contents, needle) {
+    let count = 0;
+    let index = contents.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = contents.indexOf(needle, index + needle.length);
+    }
+    return count;
+}

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

@@ -3,6 +3,8 @@ 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 { 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);
@@ -14,8 +16,11 @@ export function planClaudeCodeMcpInstall(input) {
     if (!cliCommand.ok)
         return refused(input, server, 'unsupported_scope', cliCommand.error.message, [], [], overwriteVgxness);
     if (resolvedScope.value.canonical !== 'project') {
-        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' };
+        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 {
@@ -61,6 +66,40 @@ export function planClaudeCodeMcpInstall(input) {
 export function expectedClaudeCodeRenderedAgents(workspaceRoot) {
     return expectedClaudeCodeAgentFiles(workspaceRoot).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
 }
+export function expectedClaudeCodeRenderedUserAgents(workspaceRoot, env) {
+    return expectedClaudeCodeAgentFiles({ workspaceRoot, scope: 'user', ...(env === undefined ? {} : { env }) }).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
+}
+function planUserInstall(input, server, overwriteVgxness, cliCommand, scopeWarnings) {
+    const mcpState = inspectClaudeCodeUserMcpConfig(input.env);
+    const targets = [{ kind: 'cli-mcp-registration', scope: 'user', command: cliCommand, action: 'register' }];
+    const preservedTopLevelKeys = mcpState.parsed ? Object.keys(mcpState.config) : [];
+    if (mcpState.status === 'missing')
+        targets.push({ kind: 'user-mcp-json', path: mcpState.path, external: true, action: 'create' });
+    else if (mcpState.status === 'stale')
+        targets.push({ kind: 'user-mcp-json', path: mcpState.path, external: true, action: 'merge' });
+    else if (mcpState.status === 'configured')
+        targets.push({ kind: 'user-mcp-json', path: mcpState.path, external: true, action: 'update-vgxness' });
+    else
+        targets.push({ kind: 'user-mcp-json', path: mcpState.path, external: true, action: 'blocked', reason: mcpState.message });
+    const agentInspection = inspectClaudeCodeAgents({ workspaceRoot: input.cwd, scope: 'user', ...(input.env === undefined ? {} : { env: input.env }) });
+    for (const agent of agentInspection.agents) {
+        if (agent.status === 'missing')
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'user', external: true, action: 'create' });
+        else if (agent.status === 'managed')
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'user', external: true, action: 'update-vgxness' });
+        else
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'user', external: true, action: 'blocked', reason: agent.detail });
+    }
+    const userMemory = inspectClaudeUserMemory(input.env);
+    targets.push({ kind: 'user-memory', path: userMemory.path, external: true, action: userMemory.action, status: userMemory.status, backupRequired: userMemory.backupRequired, ...(userMemory.status === 'blocked' ? { reason: userMemory.message } : {}) });
+    const blocked = targets.find((target) => target.action === 'blocked');
+    if (blocked !== undefined) {
+        const reason = blocked.kind === 'user-mcp-json' ? userMcpRefusalReason(mcpState.status) : blocked.kind === 'user-memory' ? userMemoryRefusalReason(userMemory) : 'existing_vgxness_agent';
+        return refused(input, server, reason, blocked.reason ?? 'Claude user install plan is blocked by an existing conflicting target.', targets, preservedTopLevelKeys, overwriteVgxness);
+    }
+    const backupRequired = targets.some((target) => (target.kind === 'user-mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness') || (target.kind === 'user-memory' && target.backupRequired));
+    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';
@@ -69,7 +108,7 @@ function refused(input, server, reason, message, targets, preservedTopLevelKeys,
 }
 function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, canonicalClaudeScope, cliCommand, scopeWarnings) {
     const source = input.databasePathSource ?? 'flag';
-    const targetPath = canonicalClaudeScope === 'project' ? resolveClaudeCodeMcpJsonPath(input.cwd) : `claude-cli:${canonicalClaudeScope}:vgxness`;
+    const targetPath = canonicalClaudeScope === 'project' ? resolveClaudeCodeMcpJsonPath(input.cwd) : canonicalClaudeScope === 'user' ? resolveClaudeCodeUserMcpJsonPath(input.env) : `claude-cli:${canonicalClaudeScope}:vgxness`;
     return {
         version: 1,
         kind: 'mcp-client-install-claude-code',
@@ -83,9 +122,9 @@ function base(input, server, targets, preservedTopLevelKeys, backupRequired, ove
         safety: { operation: 'plan', mutating: false, writesProviderConfig: false, targetPath, backupRequired, mergePolicy: backupRequired ? 'merge-preserve-existing' : 'create' },
         warnings: [
             ...scopeWarnings,
-            'Claude Code MCP registration is modeled as Claude CLI argv, never shell strings or manual ~/.claude.json mutation.',
-            'Project compatibility may write .mcp.json, .claude/agents/*.md, and a guarded project-root CLAUDE.md managed block after explicit confirmation/preflight; user/local scopes do not inspect or write private Claude config.',
-            'VGXNESS never manually writes ~/.claude.json or .claude/CLAUDE.md; project-root CLAUDE.md is only touched through the guarded project install managed block.',
+            '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.',
+            '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.' },
@@ -107,8 +146,20 @@ function mcpRefusalReason(status) {
         return 'existing_vgxness_mcp';
     return 'invalid_mcp_shape';
 }
+function userMcpRefusalReason(status) {
+    if (status === 'invalid')
+        return 'malformed_json';
+    if (status === 'conflicting')
+        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';
+    return 'malformed_claude_project_memory';
+}

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

@@ -5,11 +5,13 @@ import { parseClaudeAgentFrontmatter } from './claude-code-agent-config.js';
 import { runClaudeCodeCliCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, mergeClaudeCodeMcpConfig } from './claude-code-config.js';
 import { inspectClaudeProjectMemory, mergeClaudeProjectMemory } from './claude-code-project-memory.js';
-import { expectedClaudeCodeRenderedAgents, planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
+import { expectedClaudeCodeRenderedAgents, expectedClaudeCodeRenderedUserAgents, planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
+import { inspectClaudeCodeUserMcpConfig, mergeClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory, mergeClaudeUserMemory } from './claude-code-user-memory.js';
 export async function installClaudeCodeMcpClient(input) {
     const source = input.databasePathSource ?? 'flag';
     const server = createClaudeCodeMcpServerConfig(input.databasePath, source);
-    const plan = planClaudeCodeMcpInstall({ cwd: input.cwd, databasePath: input.databasePath, databasePathSource: source, ...(input.overwriteVgxness !== undefined ? { overwriteVgxness: input.overwriteVgxness } : {}), ...(input.scope !== undefined ? { scope: input.scope } : {}) });
+    const plan = planClaudeCodeMcpInstall({ cwd: input.cwd, databasePath: input.databasePath, databasePathSource: source, ...(input.overwriteVgxness !== undefined ? { overwriteVgxness: input.overwriteVgxness } : {}), ...(input.scope !== undefined ? { scope: input.scope } : {}), ...(input.env !== undefined ? { env: input.env } : {}) });
     if (plan.status === 'refused')
         return refusal(plan.reason, plan.message, plan, server, [], []);
     if (!input.confirmed)
@@ -23,7 +25,7 @@ export async function installClaudeCodeMcpClient(input) {
     for (const targetPath of preflightPaths) {
         const preflight = await input.preflight({
             category: 'provider-tool',
-            operation: 'write claude project provider config',
+            operation: plan.canonicalClaudeScope === 'user' ? 'write claude user provider config' : 'write claude project provider config',
             targetPath,
             workspaceRoot: input.cwd,
             providerToolName: 'claude-code',
@@ -36,7 +38,7 @@ export async function installClaudeCodeMcpClient(input) {
     }
     const backups = [];
     const writtenPaths = [];
-    if (plan.canonicalClaudeScope !== 'project') {
+    if (plan.canonicalClaudeScope === 'local') {
         if (input.cliRunner === undefined)
             return refusal('preflight_failed', 'Claude CLI MCP registration apply requires an injected runner boundary; read-only plans never execute Claude Code.', plan, server, [], []);
         if (plan.cliCommand === undefined)
@@ -47,6 +49,8 @@ export async function installClaudeCodeMcpClient(input) {
             return refusal('preflight_failed', `Claude CLI MCP registration failed with exit code ${cli.exitCode ?? 'unknown'}.`, plan, server, [], [], cliResult);
         return { version: 1, kind: 'mcp-client-install-claude-code', status: 'installed', targetPath: plan.targetPath, writtenPaths: [], backups: [], safety: applySafety(plan), server, warnings: plan.warnings, verificationHints: plan.verificationHints, agentNames: plan.agentNames, overwriteVgxness: plan.overwriteVgxness, cliResult };
     }
+    if (plan.canonicalClaudeScope === 'user')
+        return applyUserInstall(input, plan, server, writtenPaths, backups);
     const existingTargets = plan.targets.filter((target) => target.kind !== 'cli-mcp-registration' && (target.action === 'merge' || target.action === 'update-vgxness' || target.action === 'append-managed-block'));
     for (const target of existingTargets) {
         const backup = createBackup(target.path, target.kind === 'project-memory' ? 'project-memory' : 'config');
@@ -88,6 +92,25 @@ function writeMcpJson(cwd, plan, server) {
     const after = inspectClaudeCodeMcpConfig(cwd);
     return after.status === 'configured' ? { ok: true, value: plan.targetPath } : { ok: false, error: { code: 'validation_failed', message: 'Claude .mcp.json did not validate after write.' } };
 }
+function writeUserMcpJson(env, plan, server) {
+    const target = plan.targets.find((item) => item.kind === 'user-mcp-json');
+    if (target === undefined)
+        return { ok: true, value: plan.targetPath };
+    if (target.action === 'blocked')
+        return { ok: false, error: { code: 'validation_failed', message: target.reason ?? 'Claude user config is blocked.' } };
+    const state = inspectClaudeCodeUserMcpConfig(env);
+    if (state.status === 'invalid' || state.status === 'conflicting')
+        return { ok: false, error: { code: 'validation_failed', message: state.message } };
+    if (target.action === 'create' && existsSync(target.path))
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude user ~/.claude.json appeared after planning; rerun apply to merge safely.' } };
+    if (state.path !== target.path)
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude user config path changed after planning; rerun apply.' } };
+    const merged = mergeClaudeCodeUserMcpConfig(state.parsed ? state.config : {}, server);
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeFileSync(target.path, `${JSON.stringify(merged, null, 2)}\n`);
+    const after = inspectClaudeCodeUserMcpConfig(env);
+    return after.status === 'configured' ? { ok: true, value: target.path } : { ok: false, error: { code: 'validation_failed', message: 'Claude user ~/.claude.json did not validate after write.' } };
+}
 function writeProjectMemory(plan) {
     const target = plan.targets.find((item) => item.kind === 'project-memory');
     if (target === undefined || target.action === 'none')
@@ -105,14 +128,61 @@ function writeProjectMemory(plan) {
     const after = inspectClaudeProjectMemory(dirname(target.path));
     return after.status === 'managed-current' ? { ok: true, value: target.path } : { ok: false, error: { code: 'validation_failed', message: 'Claude project memory did not validate as managed-current after write.' } };
 }
-function createBackup(path, kind) {
+async function applyUserInstall(input, plan, server, writtenPaths, backups) {
+    const existingTargets = plan.targets.filter((target) => target.kind !== 'cli-mcp-registration' && (target.action === 'merge' || target.action === 'update-vgxness' || target.action === 'append-managed-block' || target.action === 'update-managed-block'));
+    for (const target of existingTargets) {
+        const backup = createBackup(target.path, target.kind === 'user-memory' ? 'user-memory' : 'config', 'user');
+        if (!backup.ok)
+            return refusal('backup_failed', backup.error.message, plan, server, writtenPaths, backups);
+        backups.push(toBackupSummary(backup.value));
+    }
+    const mcpWrite = writeUserMcpJson(input.env, plan, server);
+    if (!mcpWrite.ok)
+        return refusal('post_write_validation_failed', mcpWrite.error.message, plan, server, writtenPaths, backups);
+    writtenPaths.push(mcpWrite.value);
+    for (const agent of expectedClaudeCodeRenderedUserAgents(input.cwd, input.env)) {
+        const target = plan.targets.find((item) => item.kind === 'agent-file' && item.path === agent.path);
+        if (target?.action !== 'create' && target?.action !== 'update-vgxness')
+            continue;
+        mkdirSync(dirname(agent.path), { recursive: true });
+        writeFileSync(agent.path, agent.contents);
+        const validation = parseClaudeAgentFrontmatter(readFileSync(agent.path, 'utf8'));
+        if (!validation.ok || validation.data.name !== agent.agentName)
+            return refusal('post_write_validation_failed', `Claude user agent ${agent.agentName} failed post-write validation.`, plan, server, writtenPaths, backups);
+        writtenPaths.push(agent.path);
+    }
+    const memoryWrite = writeUserMemory(input.env, plan);
+    if (!memoryWrite.ok)
+        return refusal('post_write_validation_failed', memoryWrite.error.message, plan, server, writtenPaths, backups);
+    if (memoryWrite.value !== undefined)
+        writtenPaths.push(memoryWrite.value);
+    return { version: 1, kind: 'mcp-client-install-claude-code', status: 'installed', targetPath: plan.targetPath, writtenPaths, backups, safety: applySafety(plan), server, warnings: plan.warnings, verificationHints: plan.verificationHints, agentNames: plan.agentNames, overwriteVgxness: plan.overwriteVgxness };
+}
+function writeUserMemory(env, plan) {
+    const target = plan.targets.find((item) => item.kind === 'user-memory');
+    if (target === undefined || target.action === 'none')
+        return { ok: true, value: undefined };
+    if (target.action === 'blocked')
+        return { ok: false, error: { code: 'validation_failed', message: target.reason ?? 'Claude user memory is blocked.' } };
+    const state = inspectClaudeUserMemory(env);
+    if (state.path !== target.path || state.action !== target.action)
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude user memory changed after planning; rerun apply.' } };
+    const merged = mergeClaudeUserMemory(state);
+    if (!merged.ok)
+        return merged;
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeFileSync(target.path, merged.value.contents);
+    const after = inspectClaudeUserMemory(env);
+    return after.status === 'managed-current' ? { ok: true, value: target.path } : { ok: false, error: { code: 'validation_failed', message: 'Claude user memory did not validate as managed-current after write.' } };
+}
+function createBackup(path, kind, scope = 'project') {
     return createManagedProviderConfigBackup({
         targetPath: path,
         provider: 'claude',
-        scope: 'project',
+        scope,
         createdByOperation: 'mcp-client-install-claude-code',
-        reason: kind === 'project-memory' ? 'pre-project-memory-update-safety' : 'pre-merge-safety',
-        description: kind === 'project-memory' ? 'Backup existing Claude Code project memory before appending or updating the VGXNESS managed block.' : 'Backup existing Claude Code project config before merging VGXNESS MCP or agent configuration.',
+        reason: kind === 'project-memory' ? 'pre-project-memory-update-safety' : kind === 'user-memory' ? 'pre-user-memory-update-safety' : 'pre-merge-safety',
+        description: kind === 'project-memory' ? 'Backup existing Claude Code project memory before appending or updating the VGXNESS managed block.' : kind === 'user-memory' ? 'Backup existing Claude Code user memory before appending or updating the VGXNESS managed block.' : 'Backup existing Claude Code config before merging VGXNESS MCP or agent configuration.',
     });
 }
 function refusal(reason, message, plan, server, writtenPaths, backups, cliResult) {

package/dist/mcp/control-plane.js

@@ -29,7 +29,7 @@ export function callVgxTool(call, services) {
         case 'vgxness_sdd_get_readiness':
             return auditedEnvelope(validated.tool, services.sdd.getReady(validated.input), services, sddReadinessAuditPayload(validated.input));
         case 'vgxness_sdd_save_artifact':
-            return toEnvelope(validated.tool, services.sdd.saveArtifact(validated.input));
+            return auditedEnvelope(validated.tool, services.sdd.saveArtifact(validated.input), services, sddSaveAuditPayload(validated.input));
         case 'vgxness_sdd_accept_artifact':
             return auditedEnvelope(validated.tool, services.sdd.acceptArtifact(toAcceptArtifactServiceInput(validated.input)), services, sddAcceptanceAuditPayload(validated.input));
         case 'vgxness_sdd_get_artifact':
@@ -170,6 +170,23 @@ function sddAcceptanceAuditPayload(input) {
         }),
     };
 }
+function sddSaveAuditPayload(input) {
+    return {
+        runId: input.runId,
+        title: 'Audit: sdd-artifact-saved',
+        relatedType: 'sdd-artifact',
+        relatedId: `${input.change}:${input.phase}`,
+        payload: (value) => ({
+            eventType: 'sdd-artifact-saved',
+            project: input.project,
+            change: input.change,
+            phase: input.phase,
+            topicKey: value.topicKey,
+            artifactId: value.id,
+            ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
+        }),
+    };
+}
 function governanceReportAuditPayload(input) {
     return {
         runId: input.runId,

package/dist/mcp/index.js

@@ -10,6 +10,8 @@ export * from './claude-code-cli.js';
 export * from './claude-code-config.js';
 export * from './claude-code-project-memory.js';
 export * from './claude-code-scope.js';
+export * from './claude-code-user-config.js';
+export * from './claude-code-user-memory.js';
 export * from './control-plane.js';
 export * from './doctor.js';
 export * from './opencode-visibility.js';

package/dist/mcp/provider-change-plan.js

@@ -2,9 +2,7 @@ import { resolveMemoryDatabasePath } from '../memory/storage-paths.js';
 import { planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from './client-install-opencode-contract.js';
 import { ProviderDoctorService } from './provider-doctor.js';
-import { CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, isUserGlobalScope } from './provider-health-types.js';
 import { ProviderStatusService } from './provider-status.js';
-import { createClaudeCodeCliRegistrationPreview } from './claude-code-cli.js';
 import { resolveClaudeCodeScope } from './claude-code-scope.js';
 export const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
 export const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
@@ -81,51 +79,13 @@ export class ProviderChangePlanService {
         const claudeScope = resolveClaudeCodeScope(normalized.scope);
         if (!claudeScope.ok)
             return claudeScope;
-        if (isUserGlobalScope(normalized.scope) || claudeScope.value.canonical === 'local')
-            return { ok: true, value: claudeUserGlobalEnvelope(normalized, status.value, doctor.value, claudeScope.value.canonical, claudeScope.value.warnings) };
         const databasePath = resolveMemoryDatabasePath({ cwd: normalized.workspaceRoot, env: this.deps.env ?? process.env });
         if (!databasePath.ok)
             return { ok: true, value: blockedPlanEnvelope(normalized, status.value, doctor.value, databasePath.error.message) };
-        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source });
+        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, scope: normalized.scope, env: this.deps.env ?? process.env });
         return { ok: true, value: claudeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source) };
     }
 }
-function claudeUserGlobalEnvelope(input, status, doctor, canonicalScope = 'user', scopeWarnings = []) {
-    const warnings = [
-        ...scopeWarnings,
-        ...statusWarnings(status),
-        ...doctor.recommendations,
-        'Claude private config mutation is intentionally unsupported by VGXNESS; future apply uses Claude CLI argv only after confirmation/preflight.',
-    ];
-    const envelope = {
-        ...baseEnvelope(input),
-        supported: true,
-        status: 'planned',
-        summary: `Read-only Claude ${canonicalScope} change planning completed. VGXNESS will not read or write private Claude config files from this plan. Future apply requires confirmation/preflight and uses Claude CLI argv only: claude mcp add --scope ${canonicalScope} vgxness -- vgxness mcp start.`,
-        providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
-        statusSummary: statusSummary(status),
-        statusFindings: status.config,
-        doctorSummary: doctorSummary(doctor),
-        doctorFindings: doctor.checks,
-        previewEffects: {
-            action: 'none',
-            backupRequired: false,
-            preservedTopLevelKeys: [],
-            cliCommandPreview: createClaudeCodeCliRegistrationPreview(canonicalScope),
-            installsAgents: false,
-            agentNames: [],
-            refusalMessage: 'Read-only plan only; future apply requires confirmation/preflight and does not mutate ~/.claude.json manually.',
-        },
-        backupRollback: descriptiveBackupPolicy(false),
-        confirmations: confirmationPolicy(),
-        risks: [
-            `VGXNESS cannot verify Claude ${canonicalScope} MCP registration from read-only planning because it intentionally avoids reading private Claude config and does not execute Claude Code.`,
-            `Supported Claude read-only capabilities are: ${CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES.join(', ')}.`,
-        ],
-        warnings,
-    };
-    return input.payloadMode === 'verbose' ? { ...envelope, rawSources: { status, doctor } } : envelope;
-}
 function normalizeInput(input) {
     return {
         project: input.project?.trim() || 'vgxness',
@@ -224,7 +184,7 @@ function claudeEnvelope(input, status, doctor, installPlan, source) {
         supported: true,
         status: installPlan.status === 'refused' ? 'blocked' : 'planned',
         ...(installPlan.status === 'refused' ? { code: 'PLAN_UNAVAILABLE' } : {}),
-        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update project .mcp.json, ${installPlan.agentNames.length} agent file(s), and project-root CLAUDE.md as needed.`,
+        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update ${installPlan.canonicalClaudeScope === 'user' ? '~/.claude.json, user agents, and ~/.claude/CLAUDE.md' : 'project .mcp.json, agent files, and project-root CLAUDE.md'} as needed.`,
         providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
@@ -309,11 +269,11 @@ function previewEffectsClaude(plan) {
     const projectMemory = projectMemoryPreview(plan.targets);
     if (plan.status === 'refused')
         return { action: 'refused', targetPath: plan.targetPath, backupRequired: false, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'refused', refusalReason: plan.reason, refusalMessage: plan.message, ...(projectMemory === undefined ? {} : { projectMemory }) };
-    const mcpTarget = plan.targets.find((target) => target.kind === 'mcp-json');
+    const mcpTarget = plan.targets.find((target) => target.kind === 'mcp-json' || target.kind === 'user-mcp-json');
     return { action: mcpTarget?.action === 'create' ? 'would-create' : 'would-merge', targetPath: plan.targetPath, backupRequired: plan.backupRequired, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'would_install', ...(projectMemory === undefined ? {} : { projectMemory }) };
 }
 function projectMemoryPreview(targets) {
-    const target = targets.find((item) => item.kind === 'project-memory');
+    const target = targets.find((item) => item.kind === 'project-memory' || item.kind === 'user-memory');
     if (target === undefined)
         return undefined;
     const action = target.action === 'create' ? 'would-create' : target.action === 'append-managed-block' ? 'would-append' : target.action === 'update-managed-block' ? 'would-update-managed-block' : target.action === 'none' ? 'up-to-date' : 'refused';
@@ -352,7 +312,7 @@ function risksForOpenCode(status, doctor, plan, source) {
     return risks;
 }
 function risksForClaude(status, doctor, plan, source) {
-    const risks = ['Claude project .mcp.json and project-root CLAUDE.md may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
+    const risks = [plan.canonicalClaudeScope === 'user' ? 'Claude user/global files affect this OS user; backups are required before merging existing files.' : 'Claude project .mcp.json and project-root CLAUDE.md may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
     if (status.status !== 'ready')
         risks.push(`Provider status is ${status.status}; future writes should review status findings first.`);
     if (doctor.status !== 'healthy')

package/dist/mcp/provider-doctor.js

@@ -3,6 +3,8 @@ import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
 import { claudeAdvisoryPaths, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
 import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
 import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { inspectClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
 import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
@@ -132,21 +134,35 @@ export class ProviderDoctorService {
         return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: PROVIDER_HEALTH_SAFETY } };
     }
     getClaudeUserGlobalDoctor(normalized, canonicalScope = 'user', scopeWarnings = []) {
+        const mcp = inspectClaudeCodeUserMcpConfig(normalized.env);
+        const agents = inspectClaudeCodeAgents({ workspaceRoot: normalized.workspaceRoot, scope: 'user', env: normalized.env });
+        const userMemory = inspectClaudeUserMemory(normalized.env);
+        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), userMemory.path];
+        const before = snapshotPaths(checkedPathList, normalized.workspaceRoot);
+        const missingAgents = agents.agents.filter((agent) => agent.status === 'missing');
+        const blockingAgents = agents.agents.filter((agent) => agent.status === 'conflicting' || agent.status === 'invalid');
+        const badFrontmatter = agents.agents.filter((agent) => agent.exists && agent.frontmatter === 'invalid');
+        const badMarkers = agents.agents.filter((agent) => agent.exists && !agent.generatedMarker);
         const checks = [
             { id: 'workspace-root', status: existsSync(normalized.workspaceRoot) ? 'pass' : 'fail', detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}` },
-            { id: 'provider-supported', status: 'warn', detail: `Claude ${canonicalScope} scope is supported as read-only advisory status/doctor/change-plan. Future install requires explicit confirmation/preflight and Claude CLI; private config mutation is unsupported.` },
+            { id: 'provider-supported', status: 'pass', detail: `Claude ${canonicalScope} scope supports guarded ~/.claude.json MCP merge, user agents, and ~/.claude/CLAUDE.md managed block after confirmation/preflight.` },
             { id: 'claude-scope', status: scopeWarnings.length === 0 ? 'pass' : 'warn', detail: scopeWarnings.join(' ') || `Claude scope resolved to canonical ${canonicalScope}.` },
             { id: 'claude-cli-presence', status: 'warn', detail: 'Read-only doctor does not execute `claude --version`; no provider process was launched.' },
-            { id: 'provider-config-readonly-safety', status: 'pass', detail: `No Claude ${canonicalScope} paths were inspected or mutated; no repair/install/write occurred.` },
+            { id: 'claude-user-mcp-readable', status: mcp.status === 'invalid' ? 'fail' : mcp.status === 'missing' ? 'not-configured' : 'pass', detail: mcp.message, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed ~/.claude.json before installing VGXNESS Claude user support.' } : {}) },
+            { id: 'claude-user-vgxness-mcp-entry', status: mcp.status === 'configured' ? 'pass' : mcp.status === 'conflicting' ? 'fail' : 'not-configured', detail: mcp.message, ...(mcp.status === 'conflicting' ? { remediation: 'Manually reconcile mcpServers.vgxness in ~/.claude.json before applying VGXNESS Claude user support.' } : {}) },
+            { id: 'claude-user-agents-directory', status: agents.directoryExists ? 'pass' : 'not-configured', detail: agents.directoryExists ? 'Claude user agents directory exists.' : 'Claude user agents directory is missing; confirmed apply may create it.' },
+            { id: 'claude-user-vgxness-agents', status: blockingAgents.length > 0 ? 'fail' : missingAgents.length > 0 ? 'not-configured' : 'pass', detail: blockingAgents.length > 0 ? `Conflicting or invalid VGXNESS Claude user agents: ${blockingAgents.map((agent) => agent.agentName).join(', ')}.` : missingAgents.length > 0 ? `Missing VGXNESS Claude user agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.` : 'Expected VGXNESS Claude user agent targets were inspected.' },
+            { id: 'claude-user-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'fail', detail: badFrontmatter.length === 0 ? 'Expected Claude user agent frontmatter is valid.' : `Invalid or missing frontmatter for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
+            { id: 'claude-user-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'fail', detail: badMarkers.length === 0 ? 'Existing VGXNESS Claude user agent files include generated metadata markers.' : `Missing VGXNESS generated marker for: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
+            { ...claudeProjectMemoryCheck(userMemory), id: 'claude-user-memory-managed-block' },
+            readonlySafetyCheck(before, snapshotPaths(checkedPathList, normalized.workspaceRoot)),
         ];
         const status = rollupProviderDoctor(checks.map((check) => check.status));
         const compactChecksValue = compactChecks(checks, normalized.payloadMode);
         const failedChecks = checks.filter((check) => check.status === 'fail').map((check) => check.id);
-        const recommendations = [
-            `If you choose to configure Claude ${canonicalScope} scope manually, run Claude Code yourself and use a command like: claude mcp add --scope ${canonicalScope} vgxness -- vgxness mcp start.`,
-            'VGXNESS will not read or write private Claude config files during status/doctor/change-plan, repair config, or execute Claude Code from read-only surfaces.',
-        ];
-        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: `Claude ${canonicalScope} doctor is advisory and read-only; no private Claude files were inspected, no config was changed, and Claude Code was not executed.`, recommendations, checks: compactChecksValue, checkedPaths: [], bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: [] }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths: [] }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${canonicalScope}:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES } } };
+        const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
+        const checkedPaths = normalized.payloadMode === 'verbose' ? checkedPathList : checkedPathList.filter((path) => existsSync(path) || path === mcp.path || path === userMemory.path);
+        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${canonicalScope}:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES } } };
     }
 }
 function summarizeDoctor(status, failedCount, recommendationCount) {

package/dist/mcp/provider-status.js

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
-import { createClaudeCodeCliRegistrationPreview } from './claude-code-cli.js';
 import { claudeAdvisoryPaths, claudeMcpConfigPathStatus, claudeMcpEntryStatus, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
 import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
 import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { claudeUserMcpConfigPathStatus, claudeUserMcpEntryStatus, inspectClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodePromptContractVersion, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
@@ -147,28 +148,20 @@ export class ProviderStatusService {
     }
     getClaudeUserGlobalStatus(normalized, canonicalScope = 'user', scopeWarnings = []) {
         const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
-        const paths = [
-            {
-                label: `Claude ${canonicalScope} scope`,
-                path: `${canonicalScope} Claude configuration (not inspected)`,
-                exists: false,
-                readable: false,
-                parsed: false,
-                status: 'warn',
-                detail: `Claude ${canonicalScope} scope is advisory only in read-only status: VGXNESS does not read private Claude files, write config, execute Claude Code, or install provider config.`,
-            },
-        ];
-        const mcpEntry = {
-            configured: false,
-            status: 'warn',
-            serverName: 'vgxness',
-            detail: `${canonicalScope} Claude MCP status is not inspected by VGXNESS; use this as planning guidance only. Future apply uses Claude CLI argv only: ${createClaudeCodeCliRegistrationPreview(canonicalScope).join(' ')}`,
-        };
-        const tools = requiredToolPresence();
-        const status = rollupProviderHealth([canonicalAgentManifest.status, 'warn']);
+        const mcpState = inspectClaudeCodeUserMcpConfig(normalized.env);
+        const agents = inspectClaudeCodeAgents({ workspaceRoot: normalized.workspaceRoot, scope: 'user', env: normalized.env });
+        const userMemory = inspectClaudeUserMemory(normalized.env);
+        const userMemoryPathStatus = { ...claudeProjectMemoryPathStatus(userMemory), label: 'user ~/.claude/CLAUDE.md managed block' };
+        const paths = [claudeUserMcpConfigPathStatus(mcpState), userMemoryPathStatus];
+        const mcpEntry = claudeUserMcpEntryStatus(mcpState);
+        const agentStatuses = agents.agents.map((agent) => (agent.status === 'managed' ? 'pass' : agent.status === 'missing' ? 'not-configured' : 'fail'));
+        const configStatus = claudeConfigHealthStatus([...paths.map((path) => path.status), ...agentStatuses]);
+        const tools = [...requiredToolPresence(), { tool: 'claude-cli', present: false, diagnostic: 'Read-only status does not execute `claude --version`; no Claude Code process was launched.' }];
+        const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus]);
         const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
-        const verboseShape = { config: { status: 'warn', paths, mcpEntry }, canonicalAgentManifest, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, scopeWarnings, sdd, mcpRequiredTools: tools };
-        const compactShape = { config: { status: 'warn', paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
+        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), userMemory.path] : [mcpState.path, userMemory.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path)];
+        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, userMemory: { status: userMemory.status, action: userMemory.action }, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, scopeWarnings, sdd, mcpRequiredTools: tools };
+        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), userMemory: { status: userMemory.status, action: userMemory.action }, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
         return {
             ok: true,
             value: {
@@ -181,14 +174,14 @@ export class ProviderStatusService {
                 status,
                 payloadMode: normalized.payloadMode,
                 overallStatus: status,
-                inspectedPaths: [],
-                issueCount: canonicalAgentManifest.status === 'fail' ? 1 : 0,
-                warningCount: 1 + scopeWarnings.length,
-                summary: `Claude ${canonicalScope} scope status is read-only/advisory; no private Claude files are inspected or written, and Claude Code is not executed.`,
-                nextAction: { kind: 'review', message: 'Review the planning-only guidance; future apply requires explicit confirmation/preflight and uses Claude CLI argv, not private config mutation.' },
-                checkedPaths: [],
+                inspectedPaths: checkedPaths,
+                issueCount: [canonicalAgentManifest.status, configStatus, ...agentStatuses].filter((item) => item === 'fail' || item === 'not-configured').length,
+                warningCount: scopeWarnings.length + paths.filter((path) => path.status === 'warn').length + 1,
+                summary: summarizeClaudeStatus(status, mcpEntry),
+                nextAction: nextActionFor(status, mcpEntry, sdd?.next),
+                checkedPaths,
                 canonicalAgentManifest,
-                config: { status: 'warn', paths: compactPaths(paths, normalized.payloadMode), mcpEntry: compactMcpEntry(mcpEntry, normalized.payloadMode) },
+                config: { status: configStatus, paths: compactPaths(paths, normalized.payloadMode), mcpEntry: compactMcpEntry(mcpEntry, normalized.payloadMode) },
                 ...(sdd === undefined ? {} : { sdd: compactSdd(sdd, normalized.payloadMode) }),
                 mcpRequiredTools: tools,
                 originalBytes: Buffer.byteLength(JSON.stringify(verboseShape), 'utf8'),

package/dist/sdd/schema.js

@@ -1,5 +1,20 @@
 import { z } from 'zod';
 export const sddPhases = ['explore', 'proposal', 'spec', 'design', 'tasks', 'apply-progress', 'verify', 'archive'];
+/**
+ * Governance status of an SDD artifact.
+ *
+ * - `draft`     — present in the DB; satisfies downstream readiness when the
+ *                 `VGXNESS_SDD_AUTO_ADVANCE` feature flag is on (or
+ *                 `SddWorkflowService` is constructed with `autoAdvance: true`).
+ *                 Does NOT count toward the change being `complete`.
+ * - `accepted`  — content has been frozen by an explicit human
+ *                 `vgxness_sdd_accept_artifact` call. Satisfies downstream
+ *                 readiness regardless of the auto-advance flag.
+ * - `rejected`  — explicit human rejection. Hard-blocker for downstream
+ *                 readiness; can only be cleared by re-opening the artifact.
+ * - `superseded`— replaced by a newer artifact under a different topic key.
+ *                 Hard-blocker; cannot be re-saved or accepted.
+ */
 export const sddArtifactStatuses = ['draft', 'accepted', 'rejected', 'superseded'];
 export const sddArtifactNormalizationWarnings = ['legacy-artifact-defaulted-to-draft', 'invalid-artifact-metadata-defaulted-to-draft'];
 export const SddArtifactStatusSchema = z.enum(sddArtifactStatuses);

package/dist/sdd/sdd-workflow-service.js

@@ -2,12 +2,32 @@ import { summarizePayloadContent } from '../payload/payload-summary.js';
 import { isSddPhase, normalizeSddArtifact, sddPhases, sddPrerequisites, sddTopicKey, } from './schema.js';
 const defaultContext = { actor: 'sdd-workflow-service' };
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function readAutoAdvanceFromEnv() {
+    const value = process.env.VGXNESS_SDD_AUTO_ADVANCE;
+    return value === 'true' || value === '1';
+}
+function isPrerequisiteSatisfied(status) {
+    if (status === undefined)
+        return false;
+    if (status.legacy === true)
+        return false;
+    if (status.accepted === true)
+        return true;
+    if (status.state === 'draft')
+        return true;
+    return false;
+}
 export class SddWorkflowService {
     memory;
     context;
-    constructor(memory, context = defaultContext) {
+    options;
+    constructor(memory, context = defaultContext, options = {}) {
         this.memory = memory;
         this.context = context;
+        this.options = {
+            ...options,
+            autoAdvance: options.autoAdvance ?? readAutoAdvanceFromEnv(),
+        };
     }
     getWorkflow(change) {
         return sddPhases.map((phase) => ({
@@ -23,7 +43,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value);
+        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value, this.options);
         return {
             ok: true,
             value: {
@@ -40,7 +60,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        return statusFromPhases(validated.value.change, phases.value);
+        return statusFromPhases(validated.value.change, phases.value, this.options);
     }
     getNext(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -49,7 +69,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        return ok(nextDecisionFromStatuses(validated.value.change, phases.value));
+        return ok(nextDecisionFromStatuses(validated.value.change, phases.value, this.options));
     }
     getCockpit(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -59,12 +79,12 @@ export class SddWorkflowService {
         if (!snapshot.ok)
             return snapshot;
         const phases = snapshot.value.phases;
-        const next = nextDecisionFromStatuses(validated.value.change, phases);
+        const next = nextDecisionFromStatuses(validated.value.change, phases, this.options);
         const cockpitPhases = phases.map((phaseStatus) => {
             const readiness = {
                 change: validated.value.change,
                 phase: phaseStatus.phase,
-                ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases),
+                ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases, this.options),
             };
             const artifact = phaseStatus.present ? cockpitArtifactSummaryFromSnapshotItem(phaseStatus) : undefined;
             const blockers = cockpitBlockersForPhase(phaseStatus, readiness);
@@ -115,7 +135,7 @@ export class SddWorkflowService {
         if (!snapshot.ok)
             return snapshot;
         const phases = snapshot.value.phases;
-        const status = statusFromPhases(validated.value.change, phases);
+        const status = statusFromPhases(validated.value.change, phases, this.options);
         if (!status.ok)
             return status;
         const warnings = [];
@@ -137,7 +157,7 @@ export class SddWorkflowService {
             }
             return [{ phase: phase.phase, topicKey: phase.topicKey, artifact: phase.artifact, envelope }];
         });
-        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases) };
+        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases, this.options) };
         return ok({ status: status.value, artifacts, ...(readiness === undefined ? {} : { readiness }), warnings });
     }
     saveArtifact(input) {
@@ -146,13 +166,20 @@ export class SddWorkflowService {
             return validated;
         if (input.content.trim().length === 0)
             return validationFailure('SDD artifact content must not be empty');
-        return this.memory.saveArtifact({
-            project: validated.value.project,
-            topicKey: sddTopicKey(validated.value.change, validated.value.phase),
-            phase: validated.value.phase,
-            content: input.content,
-            metadata: { status: 'draft' },
-        }, this.context);
+        const { project, change, phase } = validated.value;
+        const topicKey = sddTopicKey(change, phase);
+        const existing = this.memory.getArtifact(project, topicKey, this.context);
+        if (existing.ok) {
+            const envelope = normalizeSddArtifact(existing.value);
+            const status = envelope.metadata.status;
+            if (status === 'accepted')
+                return validationFailure('Cannot overwrite an accepted SDD artifact; supersede it under a new topic key.');
+            if (status === 'rejected')
+                return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before saving.');
+            if (status === 'superseded')
+                return validationFailure('Cannot overwrite a superseded SDD artifact.');
+        }
+        return this.memory.saveArtifact({ project, topicKey, phase, content: input.content, metadata: { status: 'draft' } }, this.context);
     }
     acceptArtifact(input) {
         const validated = this.validatePhaseInput(input);
@@ -169,6 +196,11 @@ export class SddWorkflowService {
         if (!existing.ok)
             return existing;
         const existingEnvelope = normalizeSddArtifact(existing.value);
+        const existingStatus = existingEnvelope.metadata.status;
+        if (existingStatus === 'rejected')
+            return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before accepting.');
+        if (existingStatus === 'superseded')
+            return validationFailure('Cannot accept a superseded SDD artifact; create a new artifact under a different topic key instead.');
         const acceptance = {
             actor: {
                 type: 'human',
@@ -203,7 +235,7 @@ export class SddWorkflowService {
         const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!statuses.ok)
             return statuses;
-        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value)));
+        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value, this.options)));
     }
     listArtifacts(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -219,7 +251,7 @@ export class SddWorkflowService {
                 artifacts: snapshot.value.phases.flatMap((phase) => {
                     if (phase.artifact === undefined)
                         return [];
-                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases))];
+                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases, this.options))];
                 }),
                 fullRetrieval: {
                     tool: 'vgxness_sdd_list_artifacts',
@@ -280,14 +312,14 @@ export class SddWorkflowService {
         return ok({ project, change, phases });
     }
 }
-export function nextDecisionFromStatuses(change, phases) {
+export function nextDecisionFromStatuses(change, phases, options = {}) {
     const blockedPresentPhase = phases.find((status) => {
         if (!status.present)
             return false;
-        return (getReadinessFromStatuses(change, status.phase, phases).blockedPrerequisites ?? []).length > 0;
+        return (getReadinessFromStatuses(change, status.phase, phases, options).blockedPrerequisites ?? []).length > 0;
     });
     if (blockedPresentPhase !== undefined) {
-        const readiness = getReadinessFromStatuses(change, blockedPresentPhase.phase, phases);
+        const readiness = getReadinessFromStatuses(change, blockedPresentPhase.phase, phases, options);
         const blockers = readiness.blockedPrerequisites ?? [];
         return {
             change,
@@ -329,7 +361,7 @@ export function nextDecisionFromStatuses(change, phases) {
             recommendedAction: 'No next SDD phase remains for this change.',
         };
     }
-    const readiness = getReadinessFromStatuses(change, nextMissingPhase, phases);
+    const readiness = getReadinessFromStatuses(change, nextMissingPhase, phases, options);
     if (!readiness.ready) {
         const blockers = readiness.blockedPrerequisites ?? [];
         return {
@@ -352,24 +384,26 @@ export function nextDecisionFromStatuses(change, phases) {
         recommendedAction: `Run the ${nextMissingPhase} SDD phase for ${change}.`,
     };
 }
-function statusFromPhases(change, phases) {
+function statusFromPhases(change, phases, options = {}) {
     const nextReadyPhase = sddPhases.find((phase) => {
         if (phases.find((status) => status.phase === phase)?.present)
             return false;
-        return getReadinessFromStatuses(change, phase, phases).ready;
+        return getReadinessFromStatuses(change, phase, phases, options).ready;
     });
     const status = { change, phases };
     if (nextReadyPhase !== undefined)
         status.nextReadyPhase = nextReadyPhase;
     return { ok: true, value: status };
 }
-function getReadinessFromStatuses(change, phase, phases) {
+function getReadinessFromStatuses(change, phase, phases, options = {}) {
     const satisfiedPrerequisites = [];
     const missingArtifactTopicKeys = [];
     const blockedPrerequisites = [];
+    const useAutoAdvance = options.autoAdvance === true;
     for (const prerequisite of sddPrerequisites[phase]) {
         const status = phases.find((candidate) => candidate.phase === prerequisite);
-        if (status?.accepted) {
+        const satisfied = useAutoAdvance ? isPrerequisiteSatisfied(status) : status?.accepted === true;
+        if (satisfied) {
             satisfiedPrerequisites.push(prerequisite);
             continue;
         }
@@ -508,10 +542,6 @@ function blockerReasonForStatus(status) {
     if (status.legacy === true)
         return 'legacy';
     const state = status.state ?? (status.present ? 'draft' : 'missing');
-    if (state === 'missing')
-        return 'missing';
-    if (state === 'accepted')
-        return 'draft';
     return state;
 }
 function formatBlockers(blockers) {

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

@@ -9,17 +9,19 @@ export const claudeSetupAdapter = {
         { 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 },
     ],
     getStatus(context) {
         return {
             providerId: 'claude',
             status: 'supported-secondary',
-            summary: 'Claude is supported as a secondary, non-default provider for CLI MCP registration planning/apply, project .mcp.json compatibility, and project/user agent planning; explicit guarded apply is required for writes or CLI execution.',
+            summary: 'Claude is supported as a secondary, non-default provider 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.',
             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. VGXNESS may write project-root CLAUDE.md only through confirmed, preflighted Claude project install; it never manually writes ~/.claude.json or .claude/CLAUDE.md. Read-only setup/status surfaces do not execute Claude Code.'],
+            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.'],
             actions: [
                 {
                     id: 'claude-manual-guidance',

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 project-root `CLAUDE.md` managed memory, and project/user agent planning. Claude scopes are `local`, `project`, and `user` (`personal`/`global` map to `user`). Read-only status/doctor/change-plan never execute Claude Code or inspect private Claude config, and VGXNESS never manually mutates `~/.claude.json` or `.claude/CLAUDE.md`. 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 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`. |
 | 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. |
@@ -439,7 +439,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. Local/user MCP registration is represented through Claude CLI argv after confirmation/preflight, not private config mutation.
+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`.
 
 ### OpenCode injection preview
 

package/docs/cli.md

@@ -232,7 +232,7 @@ bun run cli:bun -- sdd status --project vgxness --change my-change
 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, project-root `CLAUDE.md` managed memory, and project/user agent planning. 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 read private Claude config or execute Claude Code.
+- **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.
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
@@ -508,7 +508,7 @@ 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 Claude CLI argv (`claude mcp add --scope <scope> vgxness -- vgxness mcp start`), never shell strings or manual `~/.claude.json` mutation.
+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.
 
 ```bash
 bun run cli:bun -- mcp install claude --plan --scope project --db <path>
@@ -526,8 +526,8 @@ User agent files target `~/.claude/agents/*.md` only when a future apply path ex
 
 Forbidden writes:
 
-- `~/.claude.json`
-- `.claude/CLAUDE.md`
+- `~/.claude.json` except guarded user/global `mcpServers.vgxness` merge
+- `.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.
 

package/docs/providers.md

@@ -7,7 +7,7 @@ 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, project-root `CLAUDE.md` managed memory, and project/user agent planning. Scopes are `local`, `project`, and `user`; `personal`/`global` map to `user` for compatibility. Confirmed applies are explicit and guarded; read-only surfaces do not execute Claude Code and VGXNESS never manually mutates `~/.claude.json`. |
+| 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. |
 | 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,7 +46,7 @@ vgxness agents render --provider json --project vgxness --name apply-agent
 
 Claude Code is supported as a secondary, non-default control-plane target. Read-only status, doctor, setup plan, and change-plan surfaces can inspect or preview Claude targets without Claude Code installed and without writing files.
 
-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 argv only, for example `claude mcp add --scope user vgxness -- vgxness mcp start`; no shell strings or manual `~/.claude.json` edits are generated. Status/doctor/change-plan avoid private Claude config reads and do not execute Claude Code.
+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.
 
 Allowed project-scope writes, only after explicit guarded apply with run preflight metadata (`vgxness mcp install claude --scope project --yes --run-id <id>`):
 
@@ -58,8 +58,8 @@ User-scoped agent files target `~/.claude/agents/*.md` only as an explicit exter
 
 Forbidden writes:
 
-- `~/.claude.json`
-- `.claude/CLAUDE.md`
+- `~/.claude.json` except the guarded user/global merge of `mcpServers.vgxness`
+- `.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.
 
@@ -140,7 +140,7 @@ Writes happen only through `apply` with explicit consent. Plans, status, doctor,
 
 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 local/user MCP registration uses Claude CLI argv after confirmation/preflight and never manual private-config mutation.
+- 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.
 - Call providers (`opencode`, `claude`, etc.) during preview or status.
 - Install global memory.
 - Create `openspec/`.

package/package.json

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