vgxness 1.5.2 → 1.7.0

package/dist/mcp/claude-code-cli.js

@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
+export function buildClaudeCodeMcpAddCommand(input = {}) {
+    const scope = resolveClaudeCodeScope(input.scope);
+    if (!scope.ok)
+        return scope;
+    const serverName = input.serverName ?? 'vgxness';
+    const command = input.command ?? 'vgxness';
+    const args = input.args ?? ['mcp', 'start'];
+    return commandEnvelope(['mcp', 'add', '--scope', scope.value.canonical, serverName, '--', command, ...args]);
+}
+export function buildClaudeCodeMcpAddJsonCommand(input) {
+    const scope = resolveClaudeCodeScope(input.scope);
+    if (!scope.ok)
+        return scope;
+    return commandEnvelope(['mcp', 'add-json', '--scope', scope.value.canonical, input.serverName ?? 'vgxness', sanitizeJsonArgument(input.json)]);
+}
+export async function runClaudeCodeCliCommand(command, runner = defaultClaudeCodeCliRunner) {
+    return runner(command);
+}
+export function createClaudeCodeCliRegistrationPreview(scope) {
+    const command = buildClaudeCodeMcpAddCommand({ scope });
+    return command.ok ? command.value.preview : ['claude', 'mcp', 'add', '--scope', scope, 'vgxness', '--', 'vgxness', 'mcp', 'start'];
+}
+function commandEnvelope(argv) {
+    return { ok: true, value: { executable: 'claude', argv, preview: ['claude', ...argv].map(redactArg), redacted: true } };
+}
+function sanitizeJsonArgument(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return JSON.stringify(redactUnknown(parsed));
+    }
+    catch {
+        return '<redacted-json>';
+    }
+}
+function redactUnknown(value) {
+    if (Array.isArray(value))
+        return value.map(redactUnknown);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const redacted = {};
+    for (const [key, nested] of Object.entries(value))
+        redacted[key] = /token|secret|password|key/i.test(key) ? '<redacted>' : redactUnknown(nested);
+    return redacted;
+}
+function redactArg(value) {
+    return /token|secret|password/i.test(value) ? '<redacted>' : value;
+}
+function defaultClaudeCodeCliRunner(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command.executable, command.argv, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (cause) => {
+            resolve({ command, exitCode: null, stdout: '', stderr: cause.message });
+        });
+        child.on('close', (exitCode) => {
+            resolve({ command, exitCode, stdout: redactOutput(stdout), stderr: redactOutput(stderr) });
+        });
+    });
+}
+function redactOutput(value) {
+    return value.replace(/(token|secret|password)=\S+/gi, '$1=<redacted>');
+}

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

@@ -74,7 +74,7 @@ export function assertInsideWorkspace(workspaceRoot, targetPath) {
         throw new Error(`Target path is outside workspace root: ${targetPath}`);
 }
 export function claudeAdvisoryPaths(workspaceRoot) {
-    return [join(workspaceRoot, '.claude', 'settings.json'), join(workspaceRoot, '.claude', 'settings.local.json'), join(workspaceRoot, 'CLAUDE.md'), join(workspaceRoot, '.claude', 'CLAUDE.md')];
+    return [join(workspaceRoot, '.claude', 'settings.json'), join(workspaceRoot, '.claude', 'settings.local.json'), join(workspaceRoot, '.claude', 'CLAUDE.md')];
 }
 function arraysEqual(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);

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

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../agents/canonical-agent-projection.js';
+import { assertInsideWorkspace } from './claude-code-config.js';
+export const claudeProjectMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
+export const claudeProjectMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
+export function resolveClaudeProjectMemoryPath(workspaceRoot) {
+    const target = resolve(workspaceRoot, 'CLAUDE.md');
+    assertInsideWorkspace(workspaceRoot, target);
+    return target;
+}
+export function renderClaudeProjectMemoryBlock() {
+    const projection = projectCanonicalAgentManifestToClaudeProjectMemory();
+    return [
+        claudeProjectMemoryBeginMarker,
+        `<!-- VGXNESS-GENERATED owner=vgxness provider=claude artifact=claude-project-memory safe-update=true defaultAgent=${projection.defaultAgent} promptContractVersion=${projection.promptContractVersion} canonicalSource=canonical-agent-manifest repositoryInstructions=${projection.repositoryInstructions} -->`,
+        '',
+        '# VGXNESS Claude Project Memory',
+        '',
+        projection.guidance[0] ?? '',
+        '',
+        ...projection.guidance.slice(1).map((line) => `- ${line}`),
+        '',
+        claudeProjectMemoryEndMarker,
+    ].join('\n');
+}
+export function inspectClaudeProjectMemory(workspaceRoot) {
+    let path;
+    try {
+        path = resolveClaudeProjectMemoryPath(workspaceRoot);
+    }
+    catch (cause) {
+        return blocked(resolve(workspaceRoot, 'CLAUDE.md'), false, 'outside_workspace', cause instanceof Error ? cause.message : String(cause));
+    }
+    if (!existsSync(path))
+        return { status: 'missing', path, exists: false, action: 'create', backupRequired: false, message: 'Claude project memory 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 project memory is not valid UTF-8; refusing safe managed-block updates.');
+    }
+    catch (cause) {
+        return blocked(path, true, 'unreadable', `Claude project memory could not be read: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const beginCount = countOccurrences(contents, claudeProjectMemoryBeginMarker);
+    const endCount = countOccurrences(contents, claudeProjectMemoryEndMarker);
+    if (beginCount === 0 && endCount === 0)
+        return { status: 'unmanaged', path, exists: true, action: 'append-managed-block', backupRequired: true, message: 'Claude project memory exists without a VGXNESS managed block; future apply would append one after backup.', contents };
+    if (beginCount === 0)
+        return blocked(path, true, 'missing_begin_marker', 'Claude project memory has an end marker without a begin marker.');
+    if (endCount === 0)
+        return blocked(path, true, 'missing_end_marker', 'Claude project memory has a begin marker without an end marker.');
+    if (beginCount > 1 || endCount > 1)
+        return blocked(path, true, 'duplicate_markers', 'Claude project memory has duplicate VGXNESS managed-block markers.');
+    const start = contents.indexOf(claudeProjectMemoryBeginMarker);
+    const endMarkerStart = contents.indexOf(claudeProjectMemoryEndMarker);
+    if (endMarkerStart < start)
+        return blocked(path, true, 'reordered_markers', 'Claude project memory end marker appears before begin marker.');
+    const end = endMarkerStart + claudeProjectMemoryEndMarker.length;
+    const inner = contents.slice(start + claudeProjectMemoryBeginMarker.length, endMarkerStart);
+    if (inner.includes(claudeProjectMemoryBeginMarker) || inner.includes(claudeProjectMemoryEndMarker))
+        return blocked(path, true, 'nested_markers', 'Claude project memory has nested VGXNESS managed-block markers.');
+    const metadata = parseMetadata(inner);
+    if (metadata === undefined)
+        return blocked(path, true, 'invalid_metadata', 'Claude project memory managed block is missing VGXNESS metadata.');
+    const ownership = validateMetadataOwnership(metadata);
+    if (!ownership.ok)
+        return blocked(path, true, ownership.reason, ownership.message);
+    const expected = renderClaudeProjectMemoryBlock();
+    const actual = contents.slice(start, end);
+    if (actual === expected)
+        return { status: 'managed-current', path, exists: true, action: 'none', backupRequired: false, message: 'Claude project 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 project memory has a stale VGXNESS managed block; future apply would update only that block after backup.', blockRange: { start, end }, staleReasons: ['managed_block_differs_from_canonical_render'], contents };
+}
+export function mergeClaudeProjectMemory(state) {
+    const block = renderClaudeProjectMemoryBlock();
+    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;
+}
+function parseMetadata(inner) {
+    const line = inner.split(/\r?\n/).find((item) => item.includes('VGXNESS-GENERATED'));
+    if (line === undefined)
+        return undefined;
+    const metadata = {};
+    for (const part of line.replace('<!--', '').replace('-->', '').trim().split(/\s+/)) {
+        const [key, value] = part.split('=');
+        if (key !== undefined && value !== undefined)
+            metadata[key] = value;
+    }
+    return metadata;
+}
+function validateMetadataOwnership(metadata) {
+    if (metadata['VGXNESS-GENERATED'] !== undefined)
+        return { ok: false, reason: 'invalid_metadata', message: 'Claude project memory metadata is malformed.' };
+    if (metadata.owner !== 'vgxness')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not owned by VGXNESS.' };
+    if (metadata.provider !== 'claude')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not for the Claude provider.' };
+    if (metadata.artifact !== 'claude-project-memory')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block has a conflicting artifact type.' };
+    if (metadata['safe-update'] !== 'true')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not marked safe for update.' };
+    return { ok: true };
+}

package/dist/mcp/claude-code-scope.js

@@ -0,0 +1,18 @@
+export const claudeCodeCanonicalScopes = ['local', 'project', 'user'];
+export function resolveClaudeCodeScope(input, fallback = 'project') {
+    if (input !== undefined && input.trim().length === 0)
+        return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+    const raw = input?.trim() || fallback;
+    if (raw === 'local' || raw === 'project' || raw === 'user')
+        return { ok: true, value: { canonical: raw, input: raw, warnings: [] } };
+    if (raw === 'personal') {
+        return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code scope `personal` is accepted for VGXNESS compatibility and maps to Claude `user`.'] } };
+    }
+    if (raw === 'global') {
+        return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code legacy scope `global` is deprecated and maps to Claude `user`.'] } };
+    }
+    return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+}
+export function isClaudeCodeUserScope(scope) {
+    return scope === 'user';
+}

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

@@ -1,9 +1,27 @@
 import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
+import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, resolveClaudeCodeMcpJsonPath } from './claude-code-config.js';
+import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { inspectClaudeCodeUserMcpConfig, resolveClaudeCodeUserMcpJsonPath } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 export function planClaudeCodeMcpInstall(input) {
     const source = input.databasePathSource ?? 'flag';
     const server = createClaudeCodeMcpServerConfig(input.databasePath, source);
     const overwriteVgxness = input.overwriteVgxness === true;
+    const resolvedScope = resolveClaudeCodeScope(input.scope);
+    if (!resolvedScope.ok)
+        return refused(input, server, 'unsupported_scope', resolvedScope.error.message, [], [], overwriteVgxness);
+    const cliCommand = buildClaudeCodeMcpAddCommand({ scope: resolvedScope.value.canonical });
+    if (!cliCommand.ok)
+        return refused(input, server, 'unsupported_scope', cliCommand.error.message, [], [], overwriteVgxness);
+    if (resolvedScope.value.canonical !== 'project') {
+        if (resolvedScope.value.canonical === 'local') {
+            const targets = [{ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' }];
+            return { ...base(input, server, targets, [], false, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings), status: 'would_install' };
+        }
+        return planUserInstall(input, server, overwriteVgxness, cliCommand.value, resolvedScope.value.warnings);
+    }
     let mcpPath;
     try {
         mcpPath = resolveClaudeCodeMcpJsonPath(input.cwd);
@@ -13,6 +31,7 @@ export function planClaudeCodeMcpInstall(input) {
     }
     const mcpState = inspectClaudeCodeMcpConfig(input.cwd);
     const targets = [];
+    targets.push({ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' });
     const preservedTopLevelKeys = mcpState.parsed ? Object.keys(mcpState.config) : [];
     if (mcpState.status === 'missing')
         targets.push({ kind: 'mcp-json', path: mcpPath, action: 'create' });
@@ -25,46 +44,87 @@ export function planClaudeCodeMcpInstall(input) {
     const agentInspection = inspectClaudeCodeAgents(input.cwd);
     for (const agent of agentInspection.agents) {
         if (agent.status === 'missing')
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'create' });
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'create' });
         else if (agent.status === 'managed')
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'update-vgxness' });
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'update-vgxness' });
         else
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'blocked', reason: agent.detail });
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'blocked', reason: agent.detail });
     }
+    const projectMemory = inspectClaudeProjectMemory(input.cwd);
+    targets.push({ kind: 'project-memory', path: projectMemory.path, action: projectMemory.action, status: projectMemory.status, backupRequired: projectMemory.backupRequired, ...(projectMemory.status === 'blocked' ? { reason: projectMemory.message } : {}) });
     const blocked = targets.find((target) => target.action === 'blocked');
     if (blocked !== undefined) {
-        const reason = blocked.kind === 'mcp-json' ? mcpRefusalReason(mcpState.status) : 'existing_vgxness_agent';
+        const reason = blocked.kind === 'mcp-json' ? mcpRefusalReason(mcpState.status) : blocked.kind === 'project-memory' ? projectMemoryRefusalReason(projectMemory) : 'existing_vgxness_agent';
         return refused(input, server, reason, blocked.reason ?? 'Claude Code install plan is blocked by an existing conflicting target.', targets, preservedTopLevelKeys, overwriteVgxness);
     }
-    const backupRequired = targets.some((target) => (target.kind === 'mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness'));
+    const backupRequired = targets.some((target) => (target.kind === 'mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness') || (target.kind === 'project-memory' && target.backupRequired));
     return {
-        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness),
+        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings),
         status: 'would_install',
     };
 }
 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) {
-    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness), status: 'refused', reason, message };
+    const resolved = resolveClaudeCodeScope(input.scope);
+    const canonical = resolved.ok ? resolved.value.canonical : 'project';
+    const cli = buildClaudeCodeMcpAddCommand({ scope: canonical });
+    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness, canonical, cli.ok ? cli.value : undefined, resolved.ok ? resolved.value.warnings : []), status: 'refused', reason, message };
 }
-function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness) {
+function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, canonicalClaudeScope, cliCommand, scopeWarnings) {
     const source = input.databasePathSource ?? 'flag';
-    const targetPath = resolveClaudeCodeMcpJsonPath(input.cwd);
+    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',
         installable: true,
         mutating: false,
         provider: 'claude',
-        scope: 'project',
+        scope: input.scope ?? 'project',
         targetPath,
         targets,
         backupRequired,
         safety: { operation: 'plan', mutating: false, writesProviderConfig: false, targetPath, backupRequired, mergePolicy: backupRequired ? 'merge-preserve-existing' : 'create' },
         warnings: [
-            'Claude Code support is project-local only and writes only .mcp.json plus .claude/agents/*.md after explicit confirmation.',
-            'VGXNESS never writes ~/.claude.json, CLAUDE.md, or .claude/CLAUDE.md and does not execute or install Claude Code.',
+            ...scopeWarnings,
+            'Claude Code MCP registration is modeled as structured config/argv, never shell strings.',
+            'Project compatibility may write .mcp.json, .claude/agents/*.md, and a guarded project-root CLAUDE.md managed block after explicit confirmation/preflight.',
+            '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.' },
@@ -72,6 +132,8 @@ function base(input, server, targets, preservedTopLevelKeys, backupRequired, ove
             { kind: 'command', message: 'Run the MCP doctor command after installation.', command: createClaudeCodeMcpDoctorCommand(input.databasePath, source) },
         ],
         server,
+        ...(cliCommand === undefined ? {} : { cliCommand }),
+        canonicalClaudeScope,
         preservedTopLevelKeys,
         agentNames: targets.filter((target) => target.kind === 'agent-file').map((target) => target.agentName),
         overwriteVgxness,
@@ -84,3 +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';
+}