vgxness 1.6.0 → 1.8.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 first-class for guarded MCP setup. Claude scopes are local|project|user; compatibility aliases personal/global map to user with warnings. Plans show Claude CLI argv, project .mcp.json compatibility, user ~/.claude.json MCP merge, agents, and guarded CLAUDE.md managed memory separately. Project scope confirmed applies write .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block as needed. User/global confirmed applies narrowly merge only mcpServers.vgxness in ~/.claude.json, write ~/.claude/agents/*.md, and manage only the VGXNESS block in ~/.claude/CLAUDE.md. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). Status/doctor/change-plan are read-only and do not execute Claude Code.
 
   skills register --project <name> --name <name> --description <text>
   skills list [--project <name>] [--scope project|personal]
@@ -98,7 +98,7 @@ Areas:
   No args in an interactive TTY opens the OpenTUI main menu.
   No args without a TTY prints static safe setup guidance and exits 0 without opening project state.
   Setup TUI may launch without --project; Installation remains available and project-scoped checks are deferred while project screens render project-required recovery states.
-  Provider setup support: OpenCode supported primary/default; Claude supported secondary for CLI MCP registration, project compatibility, and project/user agent planning; Antigravity placeholder; Custom/future extension point.
+  Provider setup support: OpenCode first-class supported default guided install; Claude first-class supported guarded install for CLI MCP registration, project compatibility, and project/user agent planning; Antigravity placeholder; Custom/future extension point.
   Provider config writes/install/apply are external-only and require explicit confirmation.
 
   sdd status --project <name> --change <id> [--json]

package/dist/cli/setup-status-renderer.js

@@ -41,5 +41,10 @@ function renderDefaults(status) {
 }
 function renderProvider(provider) {
     const safety = provider.actions.some((action) => action.safety.writesProviderConfig) ? 'external write action flagged' : 'no provider writes';
-    return `${provider.displayName} ${provider.status}/${provider.supportLevel} (${safety})`;
+    return `${provider.displayName} ${provider.status}/${renderSupportLevel(provider.supportLevel)} (${safety})`;
+}
+function renderSupportLevel(supportLevel) {
+    if (supportLevel === 'supported-primary' || supportLevel === 'supported-secondary')
+        return 'supported';
+    return supportLevel;
 }

package/dist/cli/tui/main-menu/main-menu-read-model.js

@@ -14,7 +14,7 @@ const statCards = [
     { label: 'SDD', value: 'guided', badge: '', description: 'MCP flow' },
 ];
 const statusSnapshotLines = [
-    'OpenCode primary; dashboard does not call providers.',
+    'OpenCode supported; dashboard does not call providers.',
     'Advanced checks stay explicit: setup status, mcp doctor opencode.',
 ];
 const optionCopy = {

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

@@ -31,7 +31,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         workspaceRootLabel: compactPath(workspaceRoot, 72),
         readinessLabel: label(readiness),
         readinessBadge: readinessBadge(readiness),
-        providerLabel: isOpenCode ? 'OpenCode' : isClaude ? 'Claude (supported secondary)' : 'Manual / none',
+        providerLabel: isOpenCode ? 'OpenCode' : isClaude ? 'Claude (first-class supported)' : 'Manual / none',
         databaseLabel: plan === undefined ? 'pending' : plan.db.mode,
         databasePathLabel: compactPath(databasePath, 72),
         databaseSourceLabel: String(databaseSource),
@@ -47,8 +47,8 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         opencodeActionLabel: isOpenCode ? opencodeActionLabel(opencode?.action) : isClaude ? 'No guided setup write; use guarded Claude install with run preflight.' : 'No automatic provider write; use manual setup guidance.',
         memoryPathExplanation: memoryExplanation,
         providerInstallabilityLabel: isOpenCode
-            ? 'OpenCode is the default guided install provider. Claude is supported secondary via guarded mcp install claude --scope project --yes --run-id <id>.'
-            : 'Manual / none is read-only guidance. Claude remains supported secondary through explicit guarded apply outside this guided OpenCode flow.',
+            ? 'OpenCode is the default guided install provider. Claude is first-class supported via guarded mcp install claude --scope project --yes --run-id <id>.'
+            : 'Manual / none is read-only guidance. Claude remains supported through explicit guarded apply outside this guided OpenCode flow.',
         agentReadinessLabel: agentReadiness.label,
         agentReadinessDetail: agentReadiness.detail,
         plannedActions: plan?.actions.map((action) => ({
@@ -79,7 +79,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         ],
         providerChoices: [
             choice('provider:opencode', 'OpenCode', 'Default guided install provider; writes still require final confirmation.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
-            choice('provider:claude-supported-secondary', 'Claude (supported secondary)', 'Claude CLI MCP registration and project compatibility apply only via guarded mcp install claude --scope project --yes --run-id <id>; not default.', (selections?.provider ?? plan?.provider) === 'claude', state?.focusedChoiceId, ['[supported secondary]', badgeLabels.readOnly]),
+            choice('provider:claude-supported', 'Claude (first-class supported)', 'Claude CLI MCP registration and project compatibility apply only via guarded mcp install claude --scope project --yes --run-id <id>; explicit install path.', (selections?.provider ?? plan?.provider) === 'claude', state?.focusedChoiceId, ['[supported]', badgeLabels.readOnly]),
             choice('provider:none', 'Manual / none', 'No automatic provider config write; follow manual setup guidance.', (selections?.provider ?? plan?.provider) === 'none', state?.focusedChoiceId, [badgeLabels.manual, badgeLabels.readOnly]),
         ],
         scopeChoices: isOpenCode
@@ -106,13 +106,13 @@ function previewDetailLines(input) {
     const opencode = plan?.opencode;
     const actions = plan?.actions.map((action) => `Planned action: ${action.description}${action.targetPath === undefined ? '' : ` Target: ${compactPath(action.targetPath, 72)}`}${action.backupRequired ? ' Backup required.' : ''}`) ?? ['Planned action: create read-only preview plan.'];
     return [
-        `Provider: ${input.provider === 'opencode' ? 'OpenCode [recommended default]' : input.provider === 'claude' ? 'Claude [supported secondary] [guarded explicit apply]' : 'Manual / none [manual] [read-only]'}`,
+        `Provider: ${input.provider === 'opencode' ? 'OpenCode [recommended default]' : input.provider === 'claude' ? 'Claude [first-class supported] [guarded explicit apply]' : 'Manual / none [manual] [read-only]'}`,
         `Memory path: ${plan?.db.mode ?? 'pending'} at ${compactPath(input.databasePath, 72)} (source: ${String(input.databaseSource)})`,
         `Memory guidance: ${memoryPathExplanation(plan, input.databasePath, input.databaseSource)}`,
         `Scope: ${input.isOpenCode ? (opencode?.scope ?? 'user') : 'disabled for manual/none provider'}`,
         `Install mode: ${input.isOpenCode ? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents') : 'disabled for manual/none provider'}`,
         `Reinstall VGXNESS entries: ${input.isOpenCode ? String(opencode?.overwriteVgxness ?? false) : 'disabled for manual/none provider'}`,
-        `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation; Claude supported secondary requires guarded mcp install claude --scope project --yes --run-id <id>.' : 'No guided provider install from this selection; Claude supported secondary uses guarded explicit apply.'}`,
+        `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation; Claude first-class support requires guarded mcp install claude --scope project --yes --run-id <id>.' : 'No guided provider install from this selection; Claude uses guarded explicit apply.'}`,
         `Agent readiness: ${agentReadinessFromPlan(plan)}`,
         `Target config: ${input.isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : 'none; no provider config will be written'}`,
         `Safety: ${input.isOpenCode ? '[will write after confirm] only on final confirmation' : '[read-only] manual/no-provider-write mode'}`,
@@ -132,7 +132,7 @@ function helpLines(screen) {
         'Next/back: Tab continues; Shift+Tab goes back. Enter continues on review and confirms only on final confirmation.',
         'Cancel/close: q or Esc cancels setup; when help is open, ?/h toggles it closed.',
         reviewLine,
-        'Provider support: OpenCode is the default guided install provider; Claude is supported secondary for guarded explicit apply via mcp install claude --scope project --yes --run-id <id>; Manual / none writes no provider config.',
+        'Provider support: OpenCode is the default guided install provider; Claude is first-class supported for guarded explicit apply via mcp install claude --scope project --yes --run-id <id>; Manual / none writes no provider config.',
         'Agent readiness: the preview checks vgxness-manager/SDD readiness guidance; preview screens never seed agents.',
         'No-write guarantee: no provider config is written before explicit final confirmation.',
     ];

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