vgxness 1.7.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, 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.
+  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/provider-change-plan.js

@@ -5,7 +5,7 @@ import { ProviderDoctorService } from './provider-doctor.js';
 import { ProviderStatusService } from './provider-status.js';
 import { resolveClaudeCodeScope } from './claude-code-scope.js';
 export const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-export const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+export const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const safety = {
     readOnly: true,
     willWrite: false,
@@ -102,7 +102,7 @@ function unsupportedProviderEnvelope(input) {
         supported: false,
         status: 'unsupported',
         code: 'UNSUPPORTED_PROVIDER',
-        summary: `${input.provider} is a recognized provider value, but provider change planning is currently implemented only for OpenCode.`,
+        summary: `${input.provider} is a recognized provider value, but read-only provider change planning currently supports OpenCode and Claude.`,
         providerIdentity: {
             provider: input.provider,
             adapter: input.provider,
@@ -120,15 +120,16 @@ function unsupportedProviderEnvelope(input) {
     };
 }
 function blockedPlanEnvelope(input, status, doctor, message) {
+    const providerName = input.provider === 'claude' ? 'Claude' : 'OpenCode';
     return {
         ...baseEnvelope(input),
         supported: true,
         status: 'blocked',
         code: 'PLAN_UNAVAILABLE',
-        summary: `OpenCode change planning could not resolve the future MCP server command: ${message}`,
+        summary: `${providerName} change planning could not resolve the future MCP server command: ${message}`,
         providerIdentity: {
-            provider: 'opencode',
-            adapter: 'opencode',
+            provider: input.provider,
+            adapter: input.provider,
             support: 'supported',
         },
         statusSummary: statusSummary(status),
@@ -206,14 +207,24 @@ function baseEnvelope(input) {
         scope: input.scope,
         provider: input.provider,
         requestedChangeType: input.changeType,
-        normalizedChangeType: normalizeChangeType(input.changeType),
+        normalizedChangeType: normalizeChangeType(input.provider, input.changeType),
         payloadMode: input.payloadMode,
         workspaceRoot: input.workspaceRoot,
         safety,
     };
 }
-function normalizeChangeType(changeType) {
-    return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' ? 'opencode-mcp-install' : changeType;
+function normalizeChangeType(provider, changeType) {
+    if (provider === 'opencode') {
+        return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' || changeType === 'claude-mcp-install'
+            ? 'opencode-mcp-install'
+            : changeType;
+    }
+    if (provider === 'claude') {
+        return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' || changeType === 'opencode-mcp-install'
+            ? 'claude-mcp-install'
+            : changeType;
+    }
+    return changeType;
 }
 function statusSummary(status) {
     return {

package/dist/mcp/schema.js

@@ -99,7 +99,7 @@ const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
 const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const payloadModes = ['compact', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const jsonValueSchema = z.lazy(() => z.union([z.string(), z.number().finite(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)]));
 export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_sdd_status: z

package/dist/mcp/validation.js

@@ -13,7 +13,7 @@ const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const permissionDecisions = ['allow', 'ask', 'deny'];
 const payloadModes = ['compact', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const validMemoryTopicKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 const maxMemoryTitleLength = 200;

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

@@ -1,9 +1,10 @@
+import { planClaudeCodeMcpInstall } from '../../mcp/client-install-claude-code-contract.js';
 import { createMcpClientSetupPreview } from '../../mcp/client-setup-preview.js';
-import { noWriteActionSafety } from './provider-setup-adapter.js';
+import { externalProviderWriteSafety, noWriteActionSafety } from './provider-setup-adapter.js';
 export const claudeSetupAdapter = {
     id: 'claude',
     displayName: 'Claude',
-    supportLevel: 'supported-secondary',
+    supportLevel: 'supported',
     capabilities: ['mcp-preview', 'mcp-install-plan', 'cli-mcp-plan', 'agent-preview', 'doctor', 'manual-guidance'],
     targets: [
         { kind: 'project-config', label: 'Project .mcp.json', path: '.mcp.json', writableBySetup: false },
@@ -14,10 +15,11 @@ export const claudeSetupAdapter = {
         { kind: 'user-config', label: 'User Claude memory', path: '~/.claude/CLAUDE.md', writableBySetup: false },
     ],
     getStatus(context) {
+        const plan = this.getInstallPlan?.(context);
         return {
             providerId: 'claude',
-            status: 'supported-secondary',
-            summary: 'Claude is supported as a secondary, non-default provider for CLI MCP registration planning/apply, project .mcp.json compatibility, guarded CLAUDE.md memory, user ~/.claude.json MCP merge, and project/user agents; explicit guarded apply is required for writes or CLI execution.',
+            status: plan?.status === 'blocked' ? 'blocked' : 'available',
+            summary: 'Claude provider setup is available for CLI MCP registration planning/apply, project .mcp.json compatibility, guarded CLAUDE.md memory, user ~/.claude.json MCP merge, and project/user agents; explicit guarded apply is required for writes or CLI execution.',
             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.'],
@@ -27,9 +29,10 @@ export const claudeSetupAdapter = {
                     id: 'claude-manual-guidance',
                     label: 'Review guarded Claude install guidance',
                     kind: 'manual-guidance',
-                    description: 'Supported secondary guidance only in setup status; writes are available only through the guarded mcp install claude flow with run preflight metadata.',
+                    description: 'Claude install guidance only in setup status; writes are available only through the guarded mcp install claude flow with run preflight metadata.',
                     safety: noWriteActionSafety,
                 },
+                ...(plan?.actions ?? []),
             ],
         };
     },
@@ -48,4 +51,44 @@ export const claudeSetupAdapter = {
             warnings: preview.warnings,
         };
     },
+    getInstallPlan(context) {
+        const contract = planClaudeCodeMcpInstall({
+            cwd: context.workspaceRoot,
+            databasePath: context.databasePath ?? '<database-path>',
+            ...(context.databasePathSource !== undefined ? { databasePathSource: context.databasePathSource } : {}),
+            scope: 'project',
+            ...(context.env !== undefined ? { env: context.env } : {}),
+            ...(context.overwriteVgxness !== undefined ? { overwriteVgxness: context.overwriteVgxness } : {}),
+        });
+        return claudeInstallPlan(context, contract);
+    },
 };
+function claudeInstallPlan(_context, contract) {
+    const actions = contract.status === 'would_install' ? [externalInstallAction(contract.targetPath, contract.overwriteVgxness)] : [];
+    return {
+        providerId: 'claude',
+        status: contract.status === 'would_install' ? 'available' : 'blocked',
+        readOnly: true,
+        mutating: false,
+        writesProviderConfig: false,
+        summary: contract.status === 'would_install'
+            ? 'Claude project install plan is available for external guarded application; the read-only setup status does not write provider config.'
+            : contract.message,
+        targetPath: contract.targetPath,
+        warnings: contract.warnings,
+        actions,
+        source: contract,
+    };
+}
+function externalInstallAction(targetPath, overwriteVgxness = false) {
+    return {
+        id: 'claude-mcp-install-project',
+        label: 'Copy external Claude project install command',
+        kind: 'copy-command',
+        command: ['vgxness', 'mcp', 'install', 'claude', '--scope', 'project', '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
+        description: overwriteVgxness
+            ? 'Copy and run this outside setup status only after reviewing that VGXNESS entries will be overwritten and unrelated config preserved.'
+            : 'Copy and run this outside setup status only after reviewing the read-only plan.',
+        safety: externalProviderWriteSafety(targetPath),
+    };
+}

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

@@ -5,7 +5,7 @@ import { externalProviderWriteSafety, noWriteActionSafety, } from './provider-se
 export const openCodeSetupAdapter = {
     id: 'opencode',
     displayName: 'OpenCode',
-    supportLevel: 'supported-primary',
+    supportLevel: 'supported',
     capabilities: ['mcp-preview', 'mcp-install-plan', 'mcp-install-apply-external', 'agent-preview', 'doctor', 'visibility-check'],
     targets: [
         { kind: 'user-config', label: 'User/global OpenCode config (default)', path: '$HOME/.config/opencode/opencode.json', writableBySetup: false },
@@ -19,7 +19,7 @@ export const openCodeSetupAdapter = {
             status: visibility?.ready === true ? 'ready' : 'available',
             summary: visibility?.ready === true
                 ? 'OpenCode MCP visibility is ready.'
-                : 'OpenCode is the supported primary provider; install/apply remains external and explicit.',
+                : 'OpenCode provider setup is available; install/apply remains external and explicit.',
             evidence: visibility?.evidence ?? ['OpenCode setup preview and install planning are available.'],
             guidance: visibility?.guidance ?? ['Preview setup first, then copy and run external install commands only after review.'],
             actions: plan?.actions ?? [],

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

@@ -1,3 +1,6 @@
+export function isSupportedProviderLevel(level) {
+    return level === 'supported' || level === 'supported-primary' || level === 'supported-secondary';
+}
 export const noWriteActionSafety = {
     mutating: false,
     writesProviderConfig: false,

package/dist/setup/setup-lifecycle-service.js

@@ -1,3 +1,4 @@
+import { isSupportedProviderLevel } from './providers/provider-setup-adapter.js';
 import { listProviderSetupAdapters } from './providers/provider-setup-registry.js';
 const agentName = 'vgxness-manager';
 export class SetupLifecycleService {
@@ -151,7 +152,7 @@ function verificationSummary(environment, project, providers, agents, mcp) {
         {
             id: 'providers',
             label: 'Providers',
-            status: providers.some((provider) => provider.supportLevel === 'supported-primary') ? 'ready' : 'unknown',
+            status: providers.some((provider) => isSupportedProviderLevel(provider.supportLevel)) ? 'ready' : 'unknown',
             detail: `${providers.length} provider targets are available for read-only setup status.`,
         },
         {

package/dist/setup/setup-plan.js

@@ -87,7 +87,7 @@ export function createSetupPlan(input) {
                 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>.`,
+                        description: `Review first-class supported Claude plan for CLI MCP registration, .mcp.json compatibility, ${claude.agentNames.length} .claude/agents/*.md file(s), and guarded project-root CLAUDE.md managed block; apply only with vgxness mcp install claude --scope project --yes --run-id <id>.`,
                         mutating: false,
                         targetPath,
                         backupRequired: claude.backupRequired,
@@ -100,7 +100,7 @@ export function createSetupPlan(input) {
                     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.'],
+                nextCommands: ['vgxness mcp install claude --plan --scope project', 'vgxness mcp install claude --scope project --yes --run-id <id>', 'OpenCode remains the default guided setup provider.'],
             },
         };
     }

package/package.json

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