vgxness 1.5.2 → 1.6.0

package/dist/agents/canonical-agent-projection.js

@@ -73,6 +73,24 @@ export function projectCanonicalAgentManifestToClaudeCode(manifest = canonicalAg
     }
     return { defaultAgent: canonicalDefaultAgentName, agents };
 }
+export function projectCanonicalAgentManifestToClaudeProjectMemory(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    return {
+        defaultAgent: canonicalDefaultAgentName,
+        promptContractVersion: canonicalPromptContractVersion,
+        repositoryInstructions: 'AGENTS.md',
+        guidance: [
+            `Use \`${canonicalDefaultAgentName}\` as the VGXNESS project manager/personality for this project.`,
+            'Follow project-root `AGENTS.md` when present.',
+            'Use VGXNESS MCP as durable state for SDD artifacts, runs, memory, agents, permissions, and provider diagnostics.',
+            'SDD artifact acceptance is human-only; never infer acceptance from generated output or file presence.',
+            'Before phase advancement, check VGXNESS SDD readiness/status.',
+            'Preserve confirmation and preflight requirements for risky side effects.',
+            'Do not tell users to run terminal SDD phase commands for normal daily SDD flow.',
+            'Be concise, evidence-grounded, user-controlled, practical, and willing to challenge unsafe assumptions.',
+        ],
+    };
+}
 export function canonicalProviderProjection(provider, manifest = canonicalAgentManifest) {
     assertValidCanonicalManifest(manifest);
     const normalized = provider.trim().toLowerCase();

package/dist/agents/renderers/claude-renderer.js

@@ -1,8 +1,8 @@
 import { ok, validationFailure } from './provider-adapter.js';
 const previewWarnings = [
-    'Claude rendering returns installable preview artifacts only; it does not install or write provider configuration.',
+    'Claude rendering returns installable preview artifacts only; it does not install and does not write provider configuration.',
     'VGX does not execute Claude or run Claude Code from this preview.',
-    'VGXNESS does not install Claude Code, does not write CLAUDE.md, and does not write provider configuration from renderer previews.',
+    'VGXNESS does not install Claude Code or write provider configuration from renderer previews; project-root CLAUDE.md is only managed by confirmed/preflighted Claude project install.',
     'VGX does not guarantee exact Claude Code configuration compatibility; this output is a neutral preview only.',
 ];
 const previewSafety = {
@@ -23,7 +23,7 @@ const claudeCapabilities = {
         'Preview artifacts only; does not execute Claude or Claude Code.',
         'Does not install Claude Code or provider tooling.',
         'Renderer preview does not write .claude/, CLAUDE.md, or provider configuration.',
-        'Confirmed apply writes only project .mcp.json and .claude/agents/*.md.',
+        'Confirmed apply writes only project .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block.',
         'Claude Code compatibility can drift; validate with provider doctor after confirmed install.',
     ],
     render: {

package/dist/cli/cli-flags.js

@@ -315,7 +315,7 @@ function setupDatabaseFlags(flags) {
 }
 function setupProviderFlag(flags) {
     const value = optionalStringFlag(flags, 'provider') ?? vgxnessSetupDefaults.defaultProvider;
-    return value === 'opencode' || value === 'none' ? { ok: true, value } : validationFailure('--provider must be opencode or none');
+    return value === 'opencode' || value === 'claude' || value === 'none' ? { ok: true, value } : validationFailure('--provider must be opencode, claude, or none');
 }
 function setupInstallModeFlag(flags) {
     const value = optionalStringFlag(flags, 'mode');

package/dist/cli/cli-help.js

@@ -6,9 +6,9 @@ Global flags:
   --version, -v    Print the installed package version.
 
 Areas:
-  init [--project <name>] [--provider opencode|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
-  setup plan [--project <name>] [--provider opencode|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
-  setup apply --yes [--project <name>] [--provider opencode|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
+  init [--project <name>] [--provider opencode|claude|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
+  setup plan [--project <name>] [--provider opencode|claude|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
+  setup apply --yes [--project <name>] [--provider opencode|claude|none] [--scope user|project] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
   setup backup list --provider opencode [--scope project|user|global] [--target <path>] [--json]
   setup rollback --backup <path> [--preview|--yes] [--json]
   setup status [--project <name>] [--scope project|personal] [--db <path>] [--json]
@@ -59,8 +59,8 @@ Areas:
   mcp setup --preview --provider opencode|claude [--db <path>]
   mcp install opencode --plan [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
   mcp install opencode --yes [--scope user|project] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
-  mcp install claude --plan [--db <path>] [--overwrite-vgxness|--reinstall]
-  mcp install claude --yes [--db <path>] [--overwrite-vgxness|--reinstall]
+  mcp install claude --plan [--scope local|project|user] [--db <path>] [--overwrite-vgxness|--reinstall]
+  mcp install claude --yes --run-id <id> [--scope local|project|user] [--db <path>] [--phase <phase>] [--agent-id <id>] [--overwrite-vgxness|--reinstall]
   mcp doctor opencode [--scope user|project] [--project-root <path>]
   mcp doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>]
   MCP setup preview is read-only; it does not install or write .opencode/, .claude/, or provider config.
@@ -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 install support is project-local only: confirmed applies write .mcp.json and .claude/agents/*.md. VGXNESS never writes ~/.claude.json, CLAUDE.md, or .claude/CLAUDE.md and does not execute/install Claude Code.
+  Claude support is secondary. Claude scopes are local|project|user; compatibility aliases personal/global map to user with warnings. Plans show Claude CLI argv, project .mcp.json compatibility, agents, and guarded project-root CLAUDE.md managed memory separately. Project scope confirmed applies write .mcp.json, .claude/agents/*.md, and the CLAUDE.md managed block as needed. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). VGXNESS does not manually read/write ~/.claude.json or private Claude config; status/doctor/change-plan are read-only and do not execute Claude Code.
 
   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; Claude preview-only; Antigravity placeholder; Custom/future extension point.
+  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 config writes/install/apply are external-only and require explicit confirmation.
 
   sdd status --project <name> --change <id> [--json]

package/dist/cli/commands/interactive-entrypoint-dispatcher.js

@@ -13,7 +13,7 @@ import { canRunInteractiveTui } from '../tui/terminal-capabilities.js';
 import { runSetupTuiCommand } from './setup-dispatcher.js';
 function defaultNoTtyGuidance() {
     return ([
-        'VGXNESS main menu requires a TTY; no provider config was written.',
+        'VGXNESS Dashboard requires a TTY; no provider config was written.',
         'Next: rerun `vgxness` in an interactive terminal, run `vgxness init --plan`, or run `vgxness setup plan` for read-only installation guidance.',
     ].join('\n') + '\n');
 }
@@ -25,7 +25,7 @@ function guidanceForMainMenuResult(result) {
     if (result.type === 'show-advanced-cli')
         return ['Advanced CLI guidance:', '- Installation preview: `vgxness init --plan` or `vgxness setup plan`', '- Setup status: `vgxness setup status --project <name>`', '- SDD status: `vgxness sdd status --project <name> --change <change>`', '- No provider config was written.'].join('\n') + '\n';
     if (result.type === 'exit')
-        return 'Exited main menu; no provider config was written.\n';
+        return 'Exited dashboard; no provider config was written.\n';
     return undefined;
 }
 async function renderDefaultMainMenu(environment, onResult) {

package/dist/cli/commands/mcp-dispatcher.js

@@ -5,6 +5,7 @@ import { planOpenCodeMcpInstall } from '../../mcp/client-install-opencode-contra
 import { createMcpClientSetupPreview, isMcpClientSetupProvider } from '../../mcp/client-setup-preview.js';
 import { createMcpDoctorReport } from '../../mcp/doctor.js';
 import { createOpenCodeMcpVisibilityReport } from '../../mcp/opencode-visibility.js';
+import { resolveClaudeCodeScope } from '../../mcp/claude-code-scope.js';
 import { RunService } from '../../runs/run-service.js';
 import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalNumberFlag, optionalStringFlag } from '../cli-flags.js';
 import { usageFailure, validationFailure } from '../cli-help.js';
@@ -24,8 +25,11 @@ export function runMcpInstallCommand(parsed, environment) {
         const mcpOnly = parsed.flags['mcp-only'] === true || parsed.flags['no-agents'] === true;
         const overwriteVgxness = parsed.flags['overwrite-vgxness'] === true || parsed.flags.reinstall === true;
         if (client === 'claude') {
+            const claudeScope = claudeInstallScopeFlag(parsed.flags);
+            if (!claudeScope.ok)
+                return resultFailure(claudeScope);
             if (parsed.flags.plan === true) {
-                return jsonResult({ ok: true, value: planClaudeCodeMcpInstall({ cwd: environment.cwd, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, overwriteVgxness }) });
+                return jsonResult({ ok: true, value: planClaudeCodeMcpInstall({ cwd: environment.cwd, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, overwriteVgxness, scope: claudeScope.value }) });
             }
             if (parsed.flags.yes !== true) {
                 return resultFailure({ ok: false, error: { code: 'validation_failed', message: 'confirmation_required: `mcp install claude` requires explicit --yes before any project config write.' } });
@@ -44,6 +48,7 @@ export function runMcpInstallCommand(parsed, environment) {
                     databasePathSource: databasePath.value.source,
                     confirmed: true,
                     overwriteVgxness,
+                    scope: claudeScope.value,
                     preflight,
                 });
                 return result.status === 'installed' ? jsonResult({ ok: true, value: result }) : resultFailure({ ok: false, error: { code: 'validation_failed', message: `${result.reason}: ${result.message}` } });
@@ -87,6 +92,11 @@ export function runMcpInstallCommand(parsed, environment) {
             });
     })();
 }
+function claudeInstallScopeFlag(flags) {
+    const value = optionalStringFlag(flags, 'scope');
+    const resolved = resolveClaudeCodeScope(value);
+    return resolved.ok ? { ok: true, value: resolved.value.canonical } : validationFailure(resolved.error.message);
+}
 function createClaudeCodeInstallPreflight(parsed, database, environment) {
     return (request) => {
         const runId = optionalStringFlag(parsed.flags, 'run-id');

package/dist/cli/commands/setup-dispatcher.js

@@ -135,6 +135,15 @@ export async function applySetupPlanInput(input, environment) {
         return validationFailure(`Setup plan is ${plan.value.status}; resolve conflicts before applying.`);
     if (input.provider === 'none')
         return { ok: true, value: { status: 'manual-required', message: 'Provider is none; there is no config to apply.', plan: plan.value } };
+    if (input.provider === 'claude')
+        return {
+            ok: true,
+            value: {
+                status: 'manual-required',
+                message: 'Claude setup apply is intentionally non-mutating here; use vgxness mcp install claude --scope project --yes --run-id <id> for guarded Claude writes.',
+                plan: plan.value,
+            },
+        };
     const result = await installOpenCodeMcpClient({
         cwd: environment.cwd,
         databasePath: plan.value.db.path,

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

@@ -1,78 +1,75 @@
 import { tuiBadges } from '../visual/badges.js';
-import { formatTuiFooter } from '../visual/footer.js';
 import { mainMenuOptionIds } from './main-menu-state.js';
+const dashboardHero = {
+    title: 'VGXNESS ONLINE',
+    subtitle: 'vgxness — local-first SDD control',
+    compactTitle: 'VGXNESS Dashboard',
+    asciiLines: ['██╗   ██╗ ██████╗ ██╗  ██╗███╗   ██╗███████╗███████╗███████╗', '██║   ██║██╔════╝ ╚██╗██╔╝████╗  ██║██╔════╝██╔════╝██╔════╝', '██║   ██║██║  ███╗ ╚███╔╝ ██╔██╗ ██║█████╗  ███████╗███████╗', '╚██╗ ██╔╝██║   ██║ ██╔██╗ ██║╚██╗██║██╔══╝  ╚════██║╚════██║', ' ╚████╔╝ ╚██████╔╝██╔╝ ██╗██║ ╚████║███████╗███████║███████║'],
+    badges: [tuiBadges.readOnly, tuiBadges.noProviderWrites],
+};
+const statCards = [
+    { label: 'actions', value: '5', badge: '', description: 'safe routes' },
+    { label: 'provider', value: '1', badge: '', description: 'OpenCode' },
+    { label: 'writes', value: '0', badge: '', description: 'dashboard render' },
+    { label: 'SDD', value: 'guided', badge: '', description: 'MCP flow' },
+];
 const statusSnapshotLines = [
-    'Primary provider: OpenCode.',
-    'Manual checks: vgxness setup status; vgxness mcp doctor opencode.',
-    'SDD cue: vgxness sdd next --project <project> --change <change>.',
-    'No checks run here; copy and run commands explicitly when needed.',
+    'OpenCode primary; dashboard does not call providers.',
+    'Advanced checks stay explicit: setup status, mcp doctor opencode.',
 ];
 const optionCopy = {
     setup: {
-        label: 'Installation',
-        description: 'Start guided installation for memory and OpenCode integration safely.',
+        label: 'Setup OpenCode',
+        description: 'guided install; confirm before writes',
         badges: [tuiBadges.requiresConfirmation],
-        detailTitle: 'Installation',
-        detailLines: [
-            'Opens the guided Installation TUI.',
-            'Plan/review screens are read-only.',
-            'Provider writes require final confirmation; OpenCode is the only automatic provider with explicit consent.',
-        ],
+        detailTitle: 'Setup OpenCode',
+        detailLines: ['Guided install opens in review mode; provider writes require final confirmation.'],
     },
     doctor: {
         label: 'Doctor / recovery',
-        description: 'See health-check and recovery commands.',
+        description: 'health and repair commands',
         badges: [tuiBadges.previewOnly],
-        detailTitle: 'Doctor guidance',
-        detailLines: ['Shows commands for status and recovery.', 'This menu only prints guidance for doctor/recovery; it does not call providers.'],
+        detailTitle: 'Doctor / recovery',
+        detailLines: ['Shows status and recovery guidance only; it does not call providers.'],
     },
     sdd: {
-        label: 'SDD / workflow guidance',
-        description: 'Review safe workflow entry points and artifact guidance.',
+        label: 'SDD workflow',
+        description: 'artifacts, phases, next step',
         badges: [tuiBadges.previewOnly],
-        detailTitle: 'SDD guidance',
-        detailLines: ['Use OpenCode conversation plus VGXNESS MCP for daily SDD progression.', 'Terminal commands are shown only as advanced/manual references.'],
+        detailTitle: 'SDD workflow',
+        detailLines: ['Use OpenCode conversation plus VGXNESS MCP for daily progression.'],
     },
     'advanced-cli': {
         label: 'Advanced CLI',
-        description: 'Show common explicit commands for experienced users.',
+        description: 'manual commands, no automation',
         badges: [tuiBadges.manual],
         detailTitle: 'Advanced CLI',
-        detailLines: ['Commands remain explicit and user-triggered.', 'No new public product commands are introduced by this menu.'],
+        detailLines: ['Prints explicit command references; no provider config is written.'],
     },
     exit: {
-        label: 'Exit',
-        description: 'Close without changing files.',
+        label: 'Quit',
+        description: 'leave cleanly',
         badges: [tuiBadges.exit, tuiBadges.noProviderWrites],
-        detailTitle: 'Exit',
-        detailLines: ['Close the main menu.', 'No provider config was written.'],
+        detailTitle: 'Quit',
+        detailLines: ['Close the dashboard; no provider config was written.'],
     },
 };
 export function buildMainMenuViewModel(state) {
     const options = mainMenuOptionIds.map((id) => ({ id, ...optionCopy[id], focused: id === state.focusedOptionId }));
     const focused = optionCopy[state.focusedOptionId];
-    const footerHints = [
-        { key: '↑/↓ j/k', label: 'move' },
-        { key: 'Enter', label: 'open focused item' },
-        { key: '?/h', label: 'help' },
-        { key: 'q/Esc', label: 'quit without writes', priority: 'critical' },
-    ];
     return {
-        title: 'VGXNESS Main Menu',
-        subtitle: 'Keyboard-first local control plane',
-        contextLines: ['Choose where to go next. Installation is first; the menu itself is read-only and does not write provider config.'],
+        title: dashboardHero.title,
+        subtitle: dashboardHero.subtitle,
+        hero: dashboardHero,
+        statCards,
+        contextLines: ['Pick a route. Dashboard render stays passive/read-only.'],
         options,
         detail: { title: focused.detailTitle, lines: focused.detailLines, badges: focused.badges },
-        statusSnapshot: { title: 'Status snapshot', lines: statusSnapshotLines, badges: [tuiBadges.readOnly, tuiBadges.noProviderWrites] },
-        safetyLines: [
-            'Previews are read-only.',
-            'Status snapshot is static guidance; no SQLite, doctor/status checks, provider calls, or provider config writes run from the main menu.',
-            'Installation/provider writes require final confirmation.',
-            'OpenCode is the only automatic provider path and still requires explicit consent.',
-        ],
+        statusSnapshot: { title: 'Signal', lines: statusSnapshotLines, badges: [tuiBadges.readOnly] },
+        safetyLines: ['read-only • no provider writes • explicit confirmation'],
         helpLines: state.helpVisible
-            ? ['Keys: ↑/↓ or j/k move, Enter open, ?/h toggle help, q/Esc quit.', 'Doctor, SDD, and Advanced CLI entries print guidance only.']
+            ? ['Keys: ↑/↓ or j/k move, Enter open, ?/h help, q/Esc quit.', 'Guidance entries print commands only; setup writes still require confirmation.']
             : [],
-        footer: formatTuiFooter(footerHints, state.viewport.width, state.viewport.mode),
+        footer: state.viewport.mode === 'narrow' ? 'no provider writes • explicit confirmation' : 'j/k • enter • q • no provider writes • explicit confirmation',
     };
 }

package/dist/cli/tui/main-menu/main-menu-render-shape.js

@@ -3,20 +3,22 @@ import { buildMainMenuViewModel } from './main-menu-read-model.js';
 export function renderMainMenuShape(input) {
     const state = input.width === undefined ? input.state : { ...input.state, viewport: { ...input.state.viewport, width: input.width } };
     const vm = buildMainMenuViewModel(state);
+    const showAscii = state.viewport.mode === 'wide';
+    const stats = vm.statCards.map((card) => `${card.value} ${card.label}`).join('      ');
     const lines = [
-        vm.title,
-        vm.subtitle,
+        `Hero: ${state.viewport.mode === 'narrow' ? vm.hero.compactTitle : vm.hero.title} ${vm.hero.badges.join(' ')}`,
+        ...(showAscii ? vm.hero.asciiLines : []),
+        vm.hero.subtitle,
         ...vm.contextLines,
-        'Menu',
+        `Stats: ${stats}`,
+        'Actions',
         ...vm.options.map(choiceLine),
-        `Detail: ${vm.detail.title}${vm.detail.badges.length === 0 ? '' : ` ${vm.detail.badges.join(' ')}`}`,
+        `Focused detail: ${vm.detail.title}${vm.detail.badges.length === 0 ? '' : ` ${vm.detail.badges.join(' ')}`}`,
         ...vm.detail.lines,
-        `${vm.statusSnapshot.title}${vm.statusSnapshot.badges.length === 0 ? '' : ` ${vm.statusSnapshot.badges.join(' ')}`}`,
+        `${vm.statusSnapshot.title}: ${vm.statusSnapshot.badges.join(' ')}`,
         ...vm.statusSnapshot.lines,
-        'Safety',
-        ...vm.safetyLines,
-        ...vm.helpLines.map((line) => `Help: ${line}`),
         `Footer: ${vm.footer}`,
+        ...vm.helpLines.map((line) => `Help: ${line}`),
     ];
     return lines.map((line) => clampLine(line, state.viewport.width)).join('\n');
 }
@@ -25,14 +27,12 @@ function clampLine(line, width) {
         return line;
     const protectedPhrases = [
         'final confirmation',
-        'read-only',
-        'Requires confirmation',
-        'explicit consent',
         'No provider writes',
+        'no provider writes',
+        'explicit confirmation',
+        'Requires confirmation',
+        'read-only',
         'quit without writes',
-        'vgxness setup status',
-        'vgxness mcp doctor opencode',
-        'no SQLite',
         'provider config writes',
     ];
     const phrase = protectedPhrases.find((candidate) => line.includes(candidate));
@@ -41,6 +41,6 @@ function clampLine(line, width) {
     return `${line.slice(0, Math.max(0, width - 1)).trim()}…`;
 }
 function choiceLine(choice) {
-    const badges = formatBadges([...(choice.focused === true ? [tuiBadges.focused] : []), ...choice.badges]);
+    const badges = formatBadges(choice.focused === true ? [tuiBadges.focused] : []);
     return `${choice.focused === true ? '›' : ' '} ${choice.label}${badges.length === 0 ? '' : ` ${badges}`} — ${choice.description}`;
 }

package/dist/cli/tui/opentui/main-menu/screen.js

@@ -12,43 +12,7 @@ export function createOpenTuiMainMenuScreen(state) {
         padding: 1,
         gap: 1,
         backgroundColor: '#080B12',
-    }, Box({
-        border: true,
-        borderStyle: 'rounded',
-        borderColor: '#7DD3FC',
-        paddingX: 1,
-        title: ' VGXNESS ',
-    }, Text({ content: `${vm.title}\n${vm.subtitle} ${tuiBadges.readOnly}\n${vm.contextLines.join('\n')}`, fg: '#E0F2FE', wrapMode: 'word' })), Box({
-        border: true,
-        borderStyle: 'rounded',
-        borderColor: '#14B8A6',
-        paddingX: 1,
-        title: ` ${vm.statusSnapshot.title} ${vm.statusSnapshot.badges.join(' ')} `,
-    }, Text({ content: vm.statusSnapshot.lines.join('\n'), fg: '#CCFBF1', wrapMode: 'word' })), Box({
-        flexDirection: state.viewport.mode === 'narrow' ? 'column' : 'row',
-        flexGrow: 1,
-        gap: 1,
-    }, Box({
-        border: true,
-        borderStyle: 'rounded',
-        borderColor: '#A78BFA',
-        flexGrow: 1,
-        padding: 1,
-        title: ' Menu ',
-    }, Text({ content: formatMainMenuOptions(vm.options), fg: '#F8FAFC', wrapMode: 'word' })), Box({
-        border: true,
-        borderStyle: 'rounded',
-        borderColor: '#22C55E',
-        flexGrow: 1,
-        padding: 1,
-        title: ` ${vm.detail.title}${vm.detail.badges.length === 0 ? '' : ` ${vm.detail.badges.join(' ')}`} `,
-    }, Text({ content: vm.detail.lines.join('\n'), fg: '#DCFCE7', wrapMode: 'word' }))), Box({
-        border: true,
-        borderStyle: 'rounded',
-        borderColor: '#F59E0B',
-        paddingX: 1,
-        title: ` Safety ${tuiBadges.noProviderWrites} `,
-    }, Text({ content: vm.safetyLines.join('\n'), fg: '#FEF3C7', wrapMode: 'word' })), ...(vm.helpLines.length === 0
+    }, renderHeroPanel(vm, state), renderStatsStrip(vm), renderActionDetailPanel(vm, state), ...(vm.helpLines.length === 0
         ? []
         : [
             Box({
@@ -58,11 +22,45 @@ export function createOpenTuiMainMenuScreen(state) {
                 paddingX: 1,
                 title: ` Help ${tuiBadges.readOnly} `,
             }, Text({ content: vm.helpLines.join('\n'), fg: '#E0F2FE', wrapMode: 'word' })),
-        ]), Box({
+        ]), renderFooterStrip(vm));
+}
+function renderHeroPanel(vm, state) {
+    const title = state.viewport.mode === 'narrow' ? vm.hero.compactTitle : vm.hero.title;
+    const ascii = state.viewport.mode === 'wide' ? `${vm.hero.asciiLines.join('\n')}\n` : '';
+    return Box({
         border: true,
         borderStyle: 'rounded',
-        borderColor: '#475569',
+        borderColor: '#7DD3FC',
         paddingX: 1,
-        title: ' Shortcuts ',
-    }, Text({ content: vm.footer, fg: '#CBD5E1', wrapMode: 'word' })));
+        title: ` ${title}                         READ-ONLY `,
+    }, Text({ content: `${ascii}${vm.hero.subtitle}\n${vm.contextLines.join('\n')}`, fg: '#E0F2FE', wrapMode: 'word' }));
+}
+function renderStatsStrip(vm) {
+    const content = vm.statCards.map((card) => `${card.value} ${card.label}`).join('      ');
+    return Text({ content, fg: '#99F6E4', wrapMode: 'word' });
+}
+function renderActionDetailPanel(vm, state) {
+    return Box({
+        border: true,
+        borderStyle: 'rounded',
+        borderColor: '#A78BFA',
+        flexDirection: state.viewport.mode === 'narrow' ? 'column' : 'row',
+        flexGrow: 1,
+        gap: 1,
+        padding: 1,
+        title: ' Actions ',
+    }, renderActionsList(vm), renderFocusedDetail(vm));
+}
+function renderActionsList(vm) {
+    return Box({
+        flexGrow: 1,
+    }, Text({ content: formatMainMenuOptions(vm.options), fg: '#F8FAFC', wrapMode: 'word' }));
+}
+function renderFocusedDetail(vm) {
+    return Box({
+        flexGrow: 1,
+    }, Text({ content: `Detail: ${vm.detail.title}${vm.detail.badges.length === 0 ? '' : ` ${vm.detail.badges.join(' ')}`}\n${vm.detail.lines.join('\n')}`, fg: '#DCFCE7', wrapMode: 'word' }));
+}
+function renderFooterStrip(vm) {
+    return Text({ content: vm.footer, fg: '#CBD5E1', wrapMode: 'word' });
 }

package/dist/cli/tui/opentui/main-menu/smoke.js

@@ -6,7 +6,7 @@ try {
     setup.renderer.root.add(createOpenTuiMainMenuScreen(createMainMenuState({ focusedOptionId: 'setup', helpVisible: true, width: 120 })));
     await setup.renderOnce();
     const frame = setup.captureCharFrame();
-    const requiredText = ['VGXNESS Main Menu', 'Installation', 'Requires confirmation', 'No provider writes', 'final confirmation', 'q/Esc'];
+    const requiredText = ['VGXNESS ONLINE', 'Setup OpenCode', 'Requires confirmation', 'no provider writes', 'final confirmation', 'q quit'];
     const missing = requiredText.filter((text) => !frame.includes(text));
     if (missing.length > 0)
         throw new Error(`Main menu smoke frame is missing expected text: ${missing.join(', ')}`);

package/dist/cli/tui/opentui/main-menu/view.js

@@ -3,6 +3,6 @@ export function formatMainMenuOptions(options) {
     return options.map(formatMainMenuOption).join('\n');
 }
 function formatMainMenuOption(option) {
-    const badges = formatBadges([...(option.focused ? [tuiBadges.focused] : []), ...option.badges]);
+    const badges = formatBadges(option.focused ? [tuiBadges.focused] : []);
     return `${option.focused ? '›' : ' '} ${option.label}${badges.length === 0 ? '' : ` ${badges}`} — ${option.description}`;
 }

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

@@ -8,6 +8,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
     const provider = selections?.provider ?? plan?.provider ?? 'opencode';
     const opencode = plan?.opencode;
     const isOpenCode = provider === 'opencode';
+    const isClaude = provider === 'claude';
     const project = plan?.project ?? status?.project ?? status?.projectState.project ?? 'pending project';
     const workspaceRoot = plan?.workspaceRoot ?? status?.environment.workspaceRoot ?? 'pending workspace';
     const databasePath = plan?.db.path ?? status?.store.path ?? 'pending database path';
@@ -30,22 +31,24 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         workspaceRootLabel: compactPath(workspaceRoot, 72),
         readinessLabel: label(readiness),
         readinessBadge: readinessBadge(readiness),
-        providerLabel: isOpenCode ? 'OpenCode' : 'Manual / none',
+        providerLabel: isOpenCode ? 'OpenCode' : isClaude ? 'Claude (supported secondary)' : 'Manual / none',
         databaseLabel: plan === undefined ? 'pending' : plan.db.mode,
         databasePathLabel: compactPath(databasePath, 72),
         databaseSourceLabel: String(databaseSource),
-        scopeLabel: isOpenCode ? (opencode?.scope ?? selections?.scope ?? 'user') : 'Manual / none (OpenCode controls disabled)',
+        scopeLabel: isOpenCode ? (opencode?.scope ?? selections?.scope ?? 'user') : isClaude ? 'Project-local Claude config only; OpenCode controls disabled' : 'Manual / none (OpenCode controls disabled)',
         installModeLabel: isOpenCode
             ? opencode?.installsAgents === false
                 ? 'mcp-only'
                 : (selections?.installMode ?? 'mcp-plus-agents')
-            : 'Manual / none (no OpenCode install)',
-        targetPathLabel: isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : 'No provider config target; manual/no-provider-write mode',
-        opencodeActionLabel: isOpenCode ? opencodeActionLabel(opencode?.action) : 'No automatic provider write; use manual setup guidance.',
+            : isClaude
+                ? 'Claude guarded apply outside guided OpenCode install'
+                : 'Manual / none (no OpenCode install)',
+        targetPathLabel: isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : isClaude ? 'Claude targets: .mcp.json and .claude/agents/*.md via guarded apply' : 'No provider config target; manual/no-provider-write mode',
+        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 only installable provider in this guided setup. Claude is deferred guidance only.'
-            : 'Manual / none is read-only guidance; no provider is installable from this selection. Claude is deferred guidance only.',
+            ? '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.',
         agentReadinessLabel: agentReadiness.label,
         agentReadinessDetail: agentReadiness.detail,
         plannedActions: plan?.actions.map((action) => ({
@@ -75,8 +78,8 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
             choice('database:custom', 'Custom database path', 'Deferred/read-only in the TUI unless already supplied by flags or environment.', selections?.databaseMode === 'custom' || (selections === undefined && plan?.db.mode === 'custom'), state?.focusedChoiceId, [badgeLabels.deferred, badgeLabels.readOnly]),
         ],
         providerChoices: [
-            choice('provider:opencode', 'OpenCode', 'Only installable provider in this guided setup; writes still require final confirmation.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
-            choice('provider:claude-deferred', 'Claude (deferred)', 'Guidance only for now; not selectable and not installable in this setup flow.', false, state?.focusedChoiceId, [badgeLabels.deferred, badgeLabels.readOnly]),
+            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: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
@@ -103,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]' : 'Manual / none [manual] [read-only]'}`,
+        `Provider: ${input.provider === 'opencode' ? 'OpenCode [recommended default]' : input.provider === 'claude' ? 'Claude [supported secondary] [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 deferred/not installable.' : 'No provider installable; OpenCode controls disabled and Claude deferred.'}`,
+        `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.'}`,
         `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'}`,
@@ -129,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 only installable provider; Claude is [deferred] [read-only] guidance and Manual / none writes no provider config.',
+        '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.',
         'Agent readiness: the preview checks vgxness-manager/SDD readiness guidance; preview screens never seed agents.',
         'No-write guarantee: no provider config is written before explicit final confirmation.',
     ];

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

@@ -1,22 +1,38 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { projectCanonicalAgentManifestToClaudeCode } from '../agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeCodeGeneratedMarker = 'VGXNESS-GENERATED';
-export function expectedClaudeCodeAgentFiles(workspaceRoot) {
+export function expectedClaudeCodeAgentFiles(input) {
+    const target = typeof input === 'string' ? resolveClaudeAgentTarget({ workspaceRoot: input, scope: 'project' }) : resolveClaudeAgentTarget(input);
     return projectCanonicalAgentManifestToClaudeCode().agents.map((agent) => {
-        const path = resolve(workspaceRoot, '.claude', 'agents', agent.fileName);
-        assertInsideWorkspace(workspaceRoot, path);
+        const path = resolve(target.directoryPath, agent.fileName);
+        if (target.scope === 'project')
+            assertInsideWorkspace(target.workspaceRoot, path);
         return { ...agent, path };
     });
 }
 export function renderClaudeCodeAgentMarkdown(agent) {
     return `---\nname: ${yamlScalar(agent.name)}\ndescription: ${yamlScalar(agent.description)}\n---\n\n<!-- ${claudeCodeGeneratedMarker} claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=${agent.promptContractVersion} safe-update=true -->\n\n${agent.instructions.trim()}\n`;
 }
-export function inspectClaudeCodeAgents(workspaceRoot) {
-    const directoryPath = join(workspaceRoot, '.claude', 'agents');
-    const expected = expectedClaudeCodeAgentFiles(workspaceRoot);
-    return { directoryPath, directoryExists: existsSync(directoryPath), agents: expected.map(inspectAgent) };
+export function inspectClaudeCodeAgents(input) {
+    const target = typeof input === 'string' ? resolveClaudeAgentTarget({ workspaceRoot: input, scope: 'project' }) : resolveClaudeAgentTarget(input);
+    const expected = expectedClaudeCodeAgentFiles({ workspaceRoot: target.workspaceRoot, scope: target.scope, ...(target.env === undefined ? {} : { env: target.env }) });
+    return { scope: target.scope, directoryPath: target.directoryPath, directoryExists: existsSync(target.directoryPath), external: target.scope === 'user', agents: expected.map(inspectAgent) };
+}
+export function resolveClaudeAgentTarget(input) {
+    const scope = input.scope ?? 'project';
+    if (scope === 'project')
+        return { workspaceRoot: input.workspaceRoot, scope, directoryPath: join(input.workspaceRoot, '.claude', 'agents'), ...(input.env === undefined ? {} : { env: input.env }) };
+    const home = safeHomeDirectory(input.env);
+    return { workspaceRoot: input.workspaceRoot, scope, directoryPath: join(home, '.claude', 'agents'), ...(input.env === undefined ? {} : { env: input.env }) };
+}
+export function safeHomeDirectory(env = process.env) {
+    const candidate = env.HOME?.trim() || homedir();
+    if (!candidate || candidate === '/' || candidate.includes('\0') || candidate.includes('~'))
+        throw new Error('Unable to resolve a safe home directory for Claude user agents.');
+    return resolve(candidate);
 }
 export function isVgxnessOwnedClaudeAgentMarkdown(contents) {
     return contents.includes(claudeCodeGeneratedMarker) && contents.includes('provider=claude') && contents.includes('artifact=claude-code-subagent');