vgxness 1.5.2 → 1.6.0

package/dist/mcp/provider-doctor.js

@@ -1,9 +1,11 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 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 { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
+import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
 import { inspectOpenCodeConfigPaths } from './provider-status.js';
 export class ProviderDoctorService {
     deps;
@@ -83,24 +85,42 @@ export class ProviderDoctorService {
         };
     }
     getClaudeDoctor(normalized) {
+        const resolvedScope = resolveClaudeCodeScope(normalized.scope);
+        if (!resolvedScope.ok)
+            return resolvedScope;
+        if (isUserGlobalScope(normalized.scope) || resolvedScope.value.canonical === 'local')
+            return this.getClaudeUserGlobalDoctor(normalized, resolvedScope.value.canonical, resolvedScope.value.warnings);
         const mcp = inspectClaudeCodeMcpConfig(normalized.workspaceRoot);
         const agents = inspectClaudeCodeAgents(normalized.workspaceRoot);
+        const projectMemory = inspectClaudeProjectMemory(normalized.workspaceRoot);
         const advisoryPaths = claudeAdvisoryPaths(normalized.workspaceRoot);
-        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), ...advisoryPaths];
+        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), projectMemory.path, ...advisoryPaths];
         const before = snapshotPaths(checkedPathList, normalized.workspaceRoot);
         const missingAgents = agents.agents.filter((agent) => agent.status === 'missing');
-        const badFrontmatter = agents.agents.filter((agent) => agent.frontmatter === 'invalid' || agent.frontmatter === '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 memoryFiles = advisoryPaths.filter((path) => existsSync(path));
         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: 'pass', detail: 'Claude provider adapter selected for project-local .mcp.json and .claude/agents support.' },
+            { id: 'provider-supported', status: 'pass', detail: 'Claude provider adapter selected for CLI MCP registration diagnostics, project .mcp.json compatibility, and Claude agents support.' },
+            { id: 'claude-scope', status: 'pass', detail: 'Claude scope project resolved to canonical project.' },
+            { id: 'claude-cli-presence', status: 'warn', detail: 'Read-only doctor does not execute `claude --version`; CLI availability is diagnosed during explicit apply/preflight only.' },
             { id: 'claude-project-mcp-readable', status: mcp.status === 'invalid' ? 'fail' : mcp.status === 'missing' ? 'not-configured' : 'pass', detail: mcp.message, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed .mcp.json before installing VGXNESS Claude support.' } : {}) },
             { id: 'claude-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 before applying VGXNESS Claude support.' } : {}) },
             { id: 'claude-agents-directory', status: agents.directoryExists ? 'pass' : 'not-configured', detail: agents.directoryExists ? 'Claude project agents directory exists.' : 'Claude project agents directory is missing; confirmed apply may create it.' },
-            { id: 'claude-vgxness-agents', status: missingAgents.length === 0 && agents.agents.every((agent) => agent.status !== 'conflicting' && agent.status !== 'invalid') ? 'pass' : missingAgents.length > 0 ? 'not-configured' : 'fail', detail: missingAgents.length > 0 ? `Missing VGXNESS Claude agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.` : 'Expected VGXNESS Claude agent targets were inspected.' },
+            {
+                id: 'claude-vgxness-agents',
+                status: blockingAgents.length > 0 ? 'fail' : missingAgents.length > 0 ? 'not-configured' : 'pass',
+                detail: blockingAgents.length > 0
+                    ? `Conflicting or invalid VGXNESS Claude agents: ${blockingAgents.map((agent) => agent.agentName).join(', ')}.`
+                    : missingAgents.length > 0
+                        ? `Missing VGXNESS Claude agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.`
+                        : 'Expected VGXNESS Claude agent targets were inspected.',
+            },
             { id: 'claude-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'fail', detail: badFrontmatter.length === 0 ? 'Expected Claude agent frontmatter is valid.' : `Invalid or missing frontmatter for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
             { id: 'claude-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'fail', detail: badMarkers.length === 0 ? 'Existing VGXNESS Claude agent files include generated metadata markers.' : `Missing VGXNESS generated marker for: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
+            claudeProjectMemoryCheck(projectMemory),
             { id: 'claude-project-memory-advisory', status: memoryFiles.length === 0 ? 'pass' : 'warn', detail: memoryFiles.length === 0 ? 'No Claude project memory/settings advisory files were found.' : `Advisory only; VGXNESS will not modify: ${memoryFiles.join(', ')}.` },
             readonlySafetyCheck(before, snapshotPaths(checkedPathList, normalized.workspaceRoot)),
         ];
@@ -111,6 +131,23 @@ export class ProviderDoctorService {
         const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
         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 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: '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.` },
+        ];
+        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 } } };
+    }
 }
 function summarizeDoctor(status, failedCount, recommendationCount) {
     if (status === 'healthy')
@@ -223,6 +260,19 @@ function readonlySafetyCheck(before, after) {
         }
         : { id: 'provider-config-readonly-safety', status: 'fail', detail: 'Provider config path existence or mtimes changed during read-only doctor.' };
 }
+function claudeProjectMemoryCheck(state) {
+    const status = state.status === 'managed-current' ? 'pass' : state.status === 'managed-stale' ? 'warn' : state.status === 'blocked' ? 'fail' : 'not-configured';
+    return {
+        id: 'claude-project-memory-managed-block',
+        status,
+        detail: state.message,
+        ...(state.status === 'blocked'
+            ? { remediation: 'Manually reconcile VGXNESS Claude project-memory markers before installing.' }
+            : state.status === 'managed-current'
+                ? {}
+                : { remediation: 'Run confirmed Claude project install when ready.' }),
+    };
+}
 function snapshotPaths(paths, workspaceRoot) {
     const unique = [...paths, `${workspaceRoot}/.vgx`];
     return Object.fromEntries(unique.map((path) => [path, existsSync(path) ? statSync(path).mtimeMs : false]));

package/dist/mcp/provider-health-types.js

@@ -11,6 +11,10 @@ export const PROVIDER_HEALTH_SAFETY = {
     runsRepair: false,
     executesProvider: false,
 };
+export const CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES = ['status', 'doctor', 'change-plan'];
+export function isUserGlobalScope(scope) {
+    return scope === 'personal' || scope === 'user';
+}
 export const REQUIRED_PROVIDER_MCP_TOOLS = ['vgxness_provider_status', 'vgxness_provider_doctor', 'vgxness_provider_change_plan'];
 export const REQUIRED_PROVIDER_NATIVE_MCP_TOOLS = [
     'vgxness_provider_status',

package/dist/mcp/provider-status.js

@@ -1,11 +1,14 @@
 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 { 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';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
+import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
 const projectConfigTargets = ['.opencode/opencode.json', 'opencode.json', '.opencode/opencode.jsonc', 'opencode.jsonc'];
 export class ProviderStatusService {
     deps;
@@ -87,24 +90,30 @@ export class ProviderStatusService {
         return { change, ...(status.ok ? { status: status.value } : {}), ...(next.ok ? { next: next.value } : {}) };
     }
     getClaudeStatus(normalized) {
+        const resolvedScope = resolveClaudeCodeScope(normalized.scope);
+        if (!resolvedScope.ok)
+            return resolvedScope;
+        if (isUserGlobalScope(normalized.scope) || resolvedScope.value.canonical === 'local')
+            return this.getClaudeUserGlobalStatus(normalized, resolvedScope.value.canonical, resolvedScope.value.warnings);
         const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
         const mcpState = inspectClaudeCodeMcpConfig(normalized.workspaceRoot);
         const agents = inspectClaudeCodeAgents(normalized.workspaceRoot);
-        const paths = [claudeMcpConfigPathStatus(mcpState)];
+        const projectMemory = inspectClaudeProjectMemory(normalized.workspaceRoot);
+        const paths = [claudeMcpConfigPathStatus(mcpState), claudeProjectMemoryPathStatus(projectMemory)];
         const mcpEntry = claudeMcpEntryStatus(mcpState);
         const agentStatuses = agents.agents.map((agent) => (agent.status === 'managed' ? 'pass' : agent.status === 'missing' ? 'not-configured' : 'fail'));
         const advisory = claudeAdvisoryPaths(normalized.workspaceRoot).filter((path) => existsSync(path));
-        const configStatus = claudeConfigHealthStatus([paths[0]?.status ?? 'not-configured', ...agentStatuses]);
+        const configStatus = claudeConfigHealthStatus([...paths.map((path) => path.status), ...agentStatuses]);
         const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus]);
         const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
-        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), ...claudeAdvisoryPaths(normalized.workspaceRoot)] : [mcpState.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path), ...advisory];
-        const tools = requiredToolPresence();
-        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, advisory, sdd, mcpRequiredTools: tools };
-        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), advisory, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
+        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), projectMemory.path, ...claudeAdvisoryPaths(normalized.workspaceRoot)] : [mcpState.path, projectMemory.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path), ...advisory];
+        const tools = [...requiredToolPresence(), { tool: 'claude-cli', present: false, diagnostic: 'Read-only status does not execute `claude --version`; CLI presence is checked during explicit apply/preflight only.' }];
+        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, projectMemory, advisory, sdd, mcpRequiredTools: tools };
+        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), projectMemory: { status: projectMemory.status, action: projectMemory.action }, advisory, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
         const originalBytes = Buffer.byteLength(JSON.stringify(verboseShape), 'utf8');
         const compactBytes = Buffer.byteLength(JSON.stringify(compactShape), 'utf8');
         const issueCount = [canonicalAgentManifest.status, configStatus, ...agentStatuses].filter((item) => item === 'fail' || item === 'not-configured').length;
-        const warningCount = advisory.length;
+        const warningCount = advisory.length + resolvedScope.value.warnings.length + paths.filter((path) => path.status === 'warn').length;
         return {
             ok: true,
             value: {
@@ -136,6 +145,61 @@ 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 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 };
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'provider-status',
+                project: normalized.project,
+                providerAdapter: 'claude',
+                scope: normalized.scope,
+                workspaceRoot: normalized.workspaceRoot,
+                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: [],
+                canonicalAgentManifest,
+                config: { status: 'warn', 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'),
+                compactBytes: Buffer.byteLength(JSON.stringify(compactShape), 'utf8'),
+                verboseAvailable: normalized.payloadMode === 'compact',
+                fullContentRef: `provider-status:claude:user-global:${normalized.workspaceRoot}`,
+                generatedAt: 'read-only-snapshot',
+                safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES },
+            },
+        };
+    }
 }
 function summarizeClaudeAgents(agents) {
     return { expected: agents.agents.length, managed: agents.agents.filter((agent) => agent.status === 'managed').length, missing: agents.agents.filter((agent) => agent.status === 'missing').length, conflicting: agents.agents.filter((agent) => agent.status === 'conflicting' || agent.status === 'invalid').length };
@@ -149,6 +213,18 @@ function claudeConfigHealthStatus(statuses) {
         return 'warn';
     return 'pass';
 }
+function claudeProjectMemoryPathStatus(state) {
+    const status = state.status === 'managed-current' ? 'pass' : state.status === 'managed-stale' ? 'warn' : state.status === 'blocked' ? 'fail' : 'not-configured';
+    return {
+        label: 'project CLAUDE.md managed block',
+        path: state.path,
+        exists: state.exists,
+        readable: state.status !== 'blocked' || state.reason !== 'unreadable',
+        parsed: state.status === 'managed-current' || state.status === 'managed-stale',
+        status,
+        detail: state.message,
+    };
+}
 function compactPaths(paths, mode) {
     if (mode === 'verbose')
         return paths;

package/dist/mcp/schema.js

@@ -90,6 +90,7 @@ export function toInternalVgxMcpToolName(toolName) {
     return EXPOSED_TO_INTERNAL_TOOL_NAMES[toolName];
 }
 const scopes = ['project', 'personal'];
+const providerScopes = ['project', 'personal', 'local', 'user'];
 const agentModes = ['agent', 'subagent'];
 const memoryTypes = ['architecture', 'decision', 'bugfix', 'pattern', 'config', 'discovery', 'learning', 'preference', 'manual'];
 const activityKinds = ['prompt', 'tool_call', 'artifact', 'summary', 'error'];
@@ -429,7 +430,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_status: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
+        scope: z.enum(providerScopes).optional(),
         providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         change: z.string().min(1).optional(),
@@ -439,7 +440,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_doctor: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
+        scope: z.enum(providerScopes).optional(),
         providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         expectedPromptContractVersion: z.number().int().positive().optional(),
@@ -449,7 +450,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_change_plan: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
+        scope: z.enum(providerScopes).optional(),
         provider: z.enum(providerChangePlanProviders),
         changeType: z.enum(providerChangePlanTypes),
         workspaceRoot: z.string().min(1),

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

@@ -3,27 +3,29 @@ import { noWriteActionSafety } from './provider-setup-adapter.js';
 export const claudeSetupAdapter = {
     id: 'claude',
     displayName: 'Claude',
-    supportLevel: 'preview-only',
-    capabilities: ['mcp-preview', 'mcp-install-plan', 'agent-preview', 'doctor', 'manual-guidance'],
+    supportLevel: 'supported-secondary',
+    capabilities: ['mcp-preview', 'mcp-install-plan', 'cli-mcp-plan', 'agent-preview', 'doctor', 'manual-guidance'],
     targets: [
         { kind: 'project-config', label: 'Project .mcp.json', path: '.mcp.json', writableBySetup: false },
         { kind: 'project-config', label: 'Project Claude agents', path: '.claude/agents/*.md', writableBySetup: false },
+        { kind: 'project-config', label: 'Project Claude memory', path: 'CLAUDE.md', writableBySetup: false },
+        { kind: 'user-config', label: 'User Claude agents', path: '~/.claude/agents/*.md', writableBySetup: false },
     ],
     getStatus(context) {
         return {
             providerId: 'claude',
-            status: 'preview-only',
-            summary: 'Claude setup supports project-local read-only planning for .mcp.json and .claude/agents/*.md; confirmed writes are handled by guarded install flows.',
+            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.',
             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: ['Review the Claude plan before any write. VGXNESS never writes ~/.claude.json, CLAUDE.md, or .claude/CLAUDE.md and does not execute/install Claude Code.'],
+            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.'],
             actions: [
                 {
                     id: 'claude-manual-guidance',
-                    label: 'Review Claude MCP snippet',
+                    label: 'Review guarded Claude install guidance',
                     kind: 'manual-guidance',
-                    description: 'Manual preview guidance only; no install/apply action is available.',
+                    description: 'Supported secondary guidance only in setup status; writes are available only through the guarded mcp install claude flow with run preflight metadata.',
                     safety: noWriteActionSafety,
                 },
             ],

package/dist/setup/setup-plan.js

@@ -1,4 +1,5 @@
 import { join, resolve } from 'node:path';
+import { planClaudeCodeMcpInstall } from '../mcp/client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from '../mcp/client-install-opencode-contract.js';
 import { resolveMemoryDatabasePath } from '../memory/storage-paths.js';
 import { vgxnessSetupDefaults } from './setup-defaults.js';
@@ -45,8 +46,66 @@ export function createSetupPlan(input) {
             },
         };
     }
+    if (provider === 'claude') {
+        const claude = planClaudeCodeMcpInstall({
+            cwd: input.workspaceRoot,
+            databasePath: database.value.path,
+            databasePathSource: database.value.planSource,
+            ...(input.overwriteVgxness === undefined ? {} : { overwriteVgxness: input.overwriteVgxness }),
+        });
+        const targetPath = claude.targetPath;
+        if (claude.status === 'refused') {
+            return {
+                ok: true,
+                value: {
+                    ...common,
+                    provider: 'claude',
+                    db: { mode: database.value.mode, path: database.value.path, source: database.value.source },
+                    status: 'conflict',
+                    actions: [],
+                    conflicts: [
+                        {
+                            id: claude.reason,
+                            severity: 'blocking',
+                            message: claude.message,
+                            targetPath,
+                            recovery: claude.reason === 'malformed_claude_project_memory' || claude.reason === 'conflicting_claude_project_memory' ? 'Manually reconcile the VGXNESS markers in project-root CLAUDE.md, then rerun `vgxness setup plan --provider claude`.' : 'Inspect the Claude project config, resolve the conflict, then rerun `vgxness setup plan --provider claude`.',
+                        },
+                    ],
+                    backupsPlanned: [],
+                    nextCommands: ['vgxness mcp install claude --plan --scope project', 'Resolve the reported Claude project conflict before guarded apply.'],
+                },
+            };
+        }
+        return {
+            ok: true,
+            value: {
+                ...common,
+                provider: 'claude',
+                db: { mode: database.value.mode, path: database.value.path, source: database.value.source },
+                status: 'ready',
+                actions: [
+                    {
+                        id: 'claude-guarded-install',
+                        description: `Review supported secondary Claude plan for CLI MCP registration, .mcp.json compatibility, ${claude.agentNames.length} .claude/agents/*.md file(s), and guarded project-root CLAUDE.md managed block; apply only with vgxness mcp install claude --scope project --yes --run-id <id>.`,
+                        mutating: false,
+                        targetPath,
+                        backupRequired: claude.backupRequired,
+                    },
+                ],
+                conflicts: [],
+                backupsPlanned: claude.targets
+                    .filter((target) => target.kind !== 'cli-mcp-registration' && ((target.kind === 'project-memory' && target.backupRequired) || target.action === 'merge' || target.action === 'update-vgxness'))
+                    .map((target) => ({
+                    targetPath: target.path,
+                    reason: target.kind === 'project-memory' ? 'A future guarded Claude apply would create a managed VGXNESS backup before appending or updating the project-root CLAUDE.md managed block.' : 'A future guarded Claude apply would create a managed VGXNESS backup before merging or updating Claude project configuration.',
+                })),
+                nextCommands: ['vgxness mcp install claude --plan --scope project', 'vgxness mcp install claude --scope project --yes --run-id <id>', 'OpenCode remains the default/primary provider.'],
+            },
+        };
+    }
     if (provider !== 'opencode')
-        return { ok: false, error: { code: 'validation_failed', message: 'Provider must be opencode or none for the setup plan.' } };
+        return { ok: false, error: { code: 'validation_failed', message: 'Provider must be opencode, claude, or none for the setup plan.' } };
     const opencode = planOpenCodeMcpInstall({
         cwd: input.workspaceRoot,
         databasePath: database.value.path,

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 supported provider; Claude Code is preview/manual only and VGXNESS does not install Claude or write `.claude/` or `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 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`. |
 | 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 rendering remains follow-up work after its exact install-safe artifact shape is specified.
+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.
 
 ### 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** — preview-only guidance; no install/apply action is exposed.
+- **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.
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
@@ -445,7 +445,7 @@ bun run cli:bun -- mcp setup --preview --provider claude --db <path>
 bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke
 ```
 
-The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`.
+The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`. For Claude config, inspect `mcp install claude --plan --scope local|project|user`; confirmed writes or CLI execution require `mcp install claude --scope <scope> --yes --run-id <id>` so VGXNESS run preflight can authorize each target.
 
 The top-level `vgxness doctor` command prints human-readable readiness checks by default and accepts `--json` for scriptable output. Lower-level `mcp doctor` remains useful for MCP-specific checks and manual diagnostics; use `--json` where parseable output is needed. `ready:true` means required checks passed. `ready:false` means at least one required check failed; read the failed check `id`, `detail`, and optional `remediation` to fix the local setup, then run doctor again.
 
@@ -506,6 +506,41 @@ Manual OpenCode verification checklist:
 5. In OpenCode, confirm the `vgxness` MCP tools are available.
 6. Call `vgxness_sdd_status` against a known project/change, then run doctor again if anything fails.
 
+## 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.
+
+```bash
+bun run cli:bun -- mcp install claude --plan --scope project --db <path>
+bun run cli:bun -- mcp install claude --plan --scope user --db <path>
+bun run cli:bun -- mcp install claude --yes --scope project --run-id <id> --db <path>
+```
+
+Allowed project-scope writes after explicit confirmation and run preflight:
+
+- `.mcp.json`
+- `.claude/agents/*.md`
+- project-root `CLAUDE.md`, only the VGXNESS managed block; user-authored content outside the block is preserved and existing files are backed up before append/update
+
+User agent files target `~/.claude/agents/*.md` only when a future apply path explicitly preflights that external directory. Read-only plans/status/doctor/change-plan never write it.
+
+Forbidden writes:
+
+- `~/.claude.json`
+- `.claude/CLAUDE.md`
+
+Malformed or conflicting VGXNESS markers in project-root `CLAUDE.md` refuse the full Claude project install before any Claude target is mutated.
+
+Manual/opt-in runtime validation checklist (not normal CI):
+
+1. Apply Claude project-local config through the guarded VGXNESS flow.
+2. Open Claude Code in the project manually.
+3. Approve the project MCP server if prompted.
+4. Run `/mcp` and verify `vgxness` is connected.
+5. Run `/agents` and verify expected project subagents are visible.
+6. Ask Claude to call a safe read-only VGXNESS MCP tool.
+7. Confirm forbidden files were not written by VGXNESS.
+
 ## SDD workflow examples
 
 Use `sdd` commands to inspect local SDD artifact state and save, read, or list phase artifacts. These commands read and write only the selected `vgxness` local SQLite memory store: `--db <path>` when passed, `VGXNESS_DB_PATH` when set, or the global default database when neither override is present.

package/docs/glossary.md

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

package/docs/prd.md

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

package/docs/providers.md

@@ -1,13 +1,13 @@
 # Providers
 
-VGXNESS is provider-agnostic at the core: the registry stores provider-neutral definitions and adapters translate them into provider-specific config and runtime behavior. This document covers the two adapter layers: the **control-plane adapter** (OpenCode renderer today, with a Claude preview renderer in the tree) and the **code-runtime provider adapter** (OpenAI-compatible + fake).
+VGXNESS is provider-agnostic at the core: the registry stores provider-neutral definitions and adapters translate them into provider-specific config and runtime behavior. This document covers the two adapter layers: the **control-plane adapter** (OpenCode primary plus supported secondary Claude Code support) and the **code-runtime provider adapter** (OpenAI-compatible + fake).
 
-## Status (v1.5.1)
+## Status (v1.6.0)
 
 | 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 | `preview/manual` | n/a | The canonical agent manifest declares Claude support as `preview` with an explicit reason: VGXNESS does not install Claude or write `.claude/` or `CLAUDE.md`. Owners of Claude-only workflows must run setup themselves. |
+| 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`. |
 | 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. |
@@ -42,9 +42,36 @@ The output is previewable JSON; the renderer does not write to `.opencode/`, `.c
 vgxness agents render --provider json --project vgxness --name apply-agent
 ```
 
-### Claude renderer (preview)
+### Claude Code support
 
-`src/agents/renderers/claude-renderer.ts` exists in the tree as a preview renderer. The shape of an install-safe Claude artifact is not yet finalized, so the renderer is not enabled for end-to-end install flows.
+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.
+
+Allowed project-scope writes, only after explicit guarded apply with run preflight metadata (`vgxness mcp install claude --scope project --yes --run-id <id>`):
+
+- `.mcp.json`
+- `.claude/agents/*.md`
+- project-root `CLAUDE.md`, only the VGXNESS managed block; user content outside the block is preserved exactly and existing files are backed up before append/update
+
+User-scoped agent files target `~/.claude/agents/*.md` only as an explicit external-directory/preflighted operation. They are never written by read-only planning/status/doctor/change-plan.
+
+Forbidden writes:
+
+- `~/.claude.json`
+- `.claude/CLAUDE.md`
+
+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.
+
+Manual/opt-in runtime validation checklist (not normal CI):
+
+1. Apply Claude project-local config through the guarded VGXNESS flow.
+2. Open Claude Code in the project manually.
+3. Approve the project MCP server if prompted.
+4. Run `/mcp` and verify `vgxness` is connected.
+5. Run `/agents` and verify expected project subagents are visible.
+6. Ask Claude to call a safe read-only VGXNESS MCP tool.
+7. Confirm forbidden files were not written by VGXNESS.
 
 ### OpenCode injection preview
 
@@ -113,7 +140,7 @@ Writes happen only through `apply` with explicit consent. Plans, status, doctor,
 
 Adapters and renderers must not:
 
-- Write provider config (`.opencode/`, `.claude/`, `opencode.json`, `CLAUDE.md`).
+- 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.
 - Call providers (`opencode`, `claude`, etc.) during preview or status.
 - Install global memory.
 - Create `openspec/`.

package/docs/roadmap.md

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