vgxness 1.9.8 → 1.10.1

package/README.md

@@ -6,7 +6,7 @@ VGXNESS is an installable CLI, MCP control plane, and native code runtime for gu
 
 This package is proprietary software. The npm package ships inspectable JavaScript (`dist/`) so Node can run it, but it is **not open-source licensed** and may not be redistributed unless you have written permission. See [LICENSE](./LICENSE).
 
-OpenCode is the primary supported provider. Other providers remain preview/manual only. Provider config writes require explicit CLI confirmation.
+OpenCode is the primary supported provider. Claude setup support is secondary. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
 
 VGXNESS v1.9.1 has a canonical project health audit with validated evidence: 38 MCP tools, 106 test files, and the official Bun validation path passing, including package evidence with `releaseReadiness: pass`. Current unreleased builds expose 41 MCP tools after adding read-only SDD/run recovery parity. See [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md) for the versioned matrix and safety taxonomy.
 
@@ -150,7 +150,7 @@ vgxness sdd continue --project <project> --change <change>
 vgxness code sdd <change> <phase> --project <project> --save-artifact
 ```
 
-Stable defaults are: package `vgxness`, provider `opencode`, global user data DB, user/global OpenCode scope (`$HOME/.config/opencode/opencode.json`), and `mcp-plus-agents` mode. Use `--scope project` only when you intentionally want `<workspace>/.opencode/opencode.json`. The generated MCP command for the global DB default is:
+Stable defaults are: package `vgxness`, provider `opencode`, global user data DB, user-global OpenCode config (`$HOME/.config/opencode/opencode.json`), and `mcp-plus-agents` mode. VGX-managed OpenCode and Claude provider configuration is user-global only; runtime VGXNESS state remains project-aware through `--project`, `--change`, workspace, and database context. Existing project-local provider files such as `.opencode/`, `opencode.json`, `.mcp.json`, `.claude/`, and `CLAUDE.md` remain untouched by VGXNESS setup. They may still affect OpenCode or Claude behavior externally, but VGXNESS treats them as external/manual diagnostics and will not repair, write, back up, or delete them. The generated MCP command for the global DB default is:
 
 ```bash
 vgxness mcp start
@@ -182,7 +182,8 @@ Edits, shell, network, git mutations, SDD persistence, and memory saves route th
 ## Safety model
 
 - Preview, status, and plan commands do not write provider config; local VGXNESS store initialization may occur where the command needs SQLite-backed state.
-- Provider config writes require explicit `--yes` confirmation.
+- VGX-managed OpenCode and Claude provider config writes are user-global only and require explicit `--yes` confirmation.
+- Runtime VGXNESS state remains project-aware; project-local provider files are read-only external/manual diagnostics and may still affect provider behavior outside VGXNESS.
 - Setup/status TUI surfaces are read-only setup, diagnostics, recovery, and fallback surfaces; daily SDD progression stays in OpenCode with VGXNESS MCP.
 - SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write `openspec/`.
 - `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
@@ -260,7 +261,7 @@ Do not publish from CI. Publication or registry dry-run checks require separate
 npm uninstall -g vgxness
 ```
 
-Remove any OpenCode config entries and local/global VGXNESS data manually if you no longer need them.
+Remove any user-global OpenCode/Claude config entries and local/global VGXNESS data manually if you no longer need them. Project-local provider files are external/manual and are not created, repaired, or deleted by VGXNESS setup.
 
 ## More docs
 

package/dist/cli/cli-flags.js

@@ -112,9 +112,22 @@ function optionalScopeFlag(flags, name) {
         return { ok: true, value: undefined };
     return value === 'project' || value === 'personal' ? { ok: true, value } : validationFailure(`--${name} must be project or personal`);
 }
+const providerUserGlobalOnlyMigrationMessage = 'VGX-managed provider configuration is user-global only for OpenCode and Claude. Project/local provider files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
 function opencodeInstallScopeFlag(flags, name) {
     const value = optionalStringFlag(flags, name) ?? vgxnessSetupDefaults.defaultOpenCodeScope;
-    return value === 'project' || value === 'user' ? { ok: true, value } : validationFailure(`--${name} must be project or user`);
+    if (value === 'user' || value === 'global' || value === 'personal')
+        return { ok: true, value: 'user' };
+    if (value === 'project' || value === 'local')
+        return validationFailure(providerUserGlobalOnlyMigrationMessage);
+    return validationFailure(`--${name} must be user, global, or personal`);
+}
+function opencodeDiagnosticScopeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name) ?? vgxnessSetupDefaults.defaultOpenCodeScope;
+    if (value === 'user' || value === 'global' || value === 'personal')
+        return { ok: true, value: 'user' };
+    if (value === 'project')
+        return { ok: true, value };
+    return validationFailure(`--${name} must be user, global, personal, or project`);
 }
 function optionalModeFlag(flags, name) {
     const value = optionalStringFlag(flags, name);
@@ -325,4 +338,4 @@ function setupInstallModeFlag(flags) {
         return { ok: true, value: 'mcp-only' };
     return { ok: true, value: vgxnessSetupDefaults.defaultInstallMode };
 }
-export { acceptedAtFlag, codeApprovalPolicyFlag, codeMemoryPolicyFlag, codeTranscriptModeFlag, codeVerificationModeFlag, csvFlag, databasePathFor, databasePathSelectionFor, finalRunStatusFlag, instructionKindFlag, isRunStatus, isSkillEvaluationResultStatus, isSkillTargetType, jsonFlag, opencodeInstallScopeFlag, optionalJsonFlag, optionalModeFlag, optionalNumberFlag, optionalRunStatusFlag, optionalScopeFlag, optionalSkillEvaluationResultStatusFlag, optionalSkillImprovementProposalStatusFlag, optionalSkillResolutionUsageFlag, optionalSkillTargetTypeFlag, optionalSkillVersionStatusFlag, optionalStringFlag, optionalTrimmedFlag, parseArgs, permissionCategoryFlag, requiredFlag, requiredTrimmedFlag, retryPolicyFlag, runOutcomeFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, skillEvaluationResultStatusFlag, skillSourceFromFlags, skillSourceKindFlag, skillTargetTypeFlag, skillUsageOutcomeFlag, };
+export { acceptedAtFlag, codeApprovalPolicyFlag, codeMemoryPolicyFlag, codeTranscriptModeFlag, codeVerificationModeFlag, csvFlag, databasePathFor, databasePathSelectionFor, finalRunStatusFlag, instructionKindFlag, isRunStatus, isSkillEvaluationResultStatus, isSkillTargetType, jsonFlag, providerUserGlobalOnlyMigrationMessage, opencodeDiagnosticScopeFlag, opencodeInstallScopeFlag, optionalJsonFlag, optionalModeFlag, optionalNumberFlag, optionalRunStatusFlag, optionalScopeFlag, optionalSkillEvaluationResultStatusFlag, optionalSkillImprovementProposalStatusFlag, optionalSkillResolutionUsageFlag, optionalSkillTargetTypeFlag, optionalSkillVersionStatusFlag, optionalStringFlag, optionalTrimmedFlag, parseArgs, permissionCategoryFlag, requiredFlag, requiredTrimmedFlag, retryPolicyFlag, runOutcomeFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, skillEvaluationResultStatusFlag, skillSourceFromFlags, skillSourceKindFlag, skillTargetTypeFlag, skillUsageOutcomeFlag, };

package/dist/cli/cli-help.js

@@ -9,9 +9,9 @@ Areas:
   status [--project <name>] [--change <id>] [--db <path>] [--json]
   next [--project <name>] [--change <id>] [--db <path>] [--json]
   resume [--project <name>] [--run-id <id>] [--db <path>] [--json]
-  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]
+  init [--project <name>] [--provider opencode|claude|none] [--scope user|global|personal] [--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|global|personal] [--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|global|personal] [--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]
@@ -23,7 +23,7 @@ Areas:
   Next answers "what should I do now?" with a shorter next-action view.
   Resume answers "how do I continue interrupted work?" with run inspection guidance.
   Without --change or --run-id they stay orientation-only and do not open local memory; with --change or --run-id they read SQLite read-only. Pass --json for automation.
-  Setup plan/init default to human-readable read-only output; pass --json for automation. Setup apply writes OpenCode config only with --yes and uses the global user DB plus mcp-plus-agents by default.
+  Setup plan/init default to human-readable read-only output; pass --json for automation. VGX-managed provider configuration is user-global only for OpenCode and Claude; setup apply writes provider config only with --yes and uses the global user DB plus mcp-plus-agents by default.
   Setup status defaults to human-readable read-only output; pass --json for automation. It never writes provider config or executes providers.
   Doctor defaults to human-readable output; pass --json for automation.
   Verification plans are read-only recommendations only; they never execute commands, write provider config, persist results, mutate SDD artifacts, or infer acceptance.
@@ -64,19 +64,19 @@ Areas:
   Approval commands resolve explicit run/preflight approval records; they do not change agent seed permissions or globally allow shell/provider access.
 
   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 [--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 install opencode --plan [--scope user|global|personal] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install opencode --yes [--scope user|global|personal] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install claude --plan [--scope user|global|personal] [--db <path>] [--overwrite-vgxness|--reinstall]
+  mcp install claude --yes --run-id <id> [--scope user|global|personal] [--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.
   Without --db, MCP install and setup commands use the vgxness global default database; pass --db .vgx/memory.sqlite for project-local compatibility.
-  OpenCode install defaults to user/global scope and installs mcp.vgxness plus top-level permission.bash=ask, vgxness-manager with bash=allow, and hidden vgxness-sdd-* agents with explicit permissions; use --mcp-only for legacy MCP-only config.
+  OpenCode install defaults to user-global scope and installs mcp.vgxness plus top-level permission.bash=ask, vgxness-manager with bash=allow, and hidden vgxness-sdd-* agents with explicit permissions; use --mcp-only for legacy MCP-only config.
   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 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.
+  It writes only after --yes. VGX-managed provider configuration is user-global only for OpenCode and Claude; the OpenCode target is $HOME/.config/opencode/opencode.json.
+  Project/local provider files are external/manual diagnostics and will not be written by VGXNESS. Plans are read-only; applies refuse unsafe existing user-global config and create backups before merge.
+  Claude support is first-class for guarded MCP setup. Claude user/global/personal scopes all target user-global managed config. Confirmed Claude writes narrowly merge 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]
@@ -105,7 +105,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 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 setup support: OpenCode first-class supported default guided install; Claude first-class supported guarded user-global install; project/local provider files are diagnostics only; 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/mcp-dispatcher.js

@@ -9,7 +9,7 @@ import { resolveClaudeCodeScope } from '../../mcp/claude-code-scope.js';
 import { computeEffectiveManagerInstructions } from '../../agents/manager-profile-overlay-service.js';
 import { RunService } from '../../runs/run-service.js';
 import { isTerminalRunStatus } from '../../runs/schema.js';
-import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalNumberFlag, optionalStringFlag } from '../cli-flags.js';
+import { databasePathFor, databasePathSelectionFor, opencodeDiagnosticScopeFlag, opencodeInstallScopeFlag, optionalNumberFlag, optionalStringFlag, providerUserGlobalOnlyMigrationMessage, } from '../cli-flags.js';
 import { usageFailure, validationFailure } from '../cli-help.js';
 import { jsonResult, openCliDatabase, resultFailure } from '../cli-helpers.js';
 import { renderDoctorReport } from '../doctor-renderer.js';
@@ -129,8 +129,12 @@ 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);
+    const resolved = resolveClaudeCodeScope(value, 'user');
+    if (!resolved.ok)
+        return validationFailure(resolved.error.message);
+    if (resolved.value.canonical === 'project' || resolved.value.canonical === 'local')
+        return validationFailure(providerUserGlobalOnlyMigrationMessage);
+    return { ok: true, value: resolved.value.canonical };
 }
 function createClaudeCodeInstallPreflight(parsed, database, environment) {
     return (request) => {
@@ -211,7 +215,7 @@ export function runMcpDoctorCommand(parsed, environment, output = 'json') {
     })();
 }
 export function runMcpDoctorOpenCodeCommand(parsed, environment) {
-    const scope = opencodeInstallScopeFlag(parsed.flags, 'scope');
+    const scope = opencodeDiagnosticScopeFlag(parsed.flags, 'scope');
     if (!scope.ok)
         return resultFailure(scope);
     const projectRoot = optionalStringFlag(parsed.flags, 'project-root');

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

@@ -9,7 +9,7 @@ import { applyRollbackConfigBackup, listProviderConfigBackups, previewRollbackCo
 import { vgxnessSetupDefaults } from '../../setup/setup-defaults.js';
 import { SetupLifecycleService } from '../../setup/setup-lifecycle-service.js';
 import { createSetupPlan } from '../../setup/setup-plan.js';
-import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalStringFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, } from '../cli-flags.js';
+import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalStringFlag, providerUserGlobalOnlyMigrationMessage, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, } from '../cli-flags.js';
 import { okText, usageFailure, validationFailure } from '../cli-help.js';
 import { jsonResult, openCliDatabase, resultFailure } from '../cli-helpers.js';
 import { renderSetupPlan } from '../setup-plan-renderer.js';
@@ -121,7 +121,7 @@ export function runSetupBackupCommand(parsed, environment) {
 }
 export async function runSetupApplyCommand(parsed, environment) {
     if (parsed.flags.yes !== true)
-        return usageFailure('setup apply writes provider config and requires --yes');
+        return usageFailure('setup apply writes provider config and requires explicit confirmation with --yes. No provider config was written.');
     const input = setupPlanInputFromFlags(parsed, environment);
     if (!input.ok)
         return resultFailure(input);
@@ -141,7 +141,7 @@ export async function applySetupPlanInput(input, environment) {
             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.',
+                message: `Claude setup apply is intentionally non-mutating here; use vgxness mcp install claude --yes --run-id <id> for guarded user-global Claude writes. ${providerUserGlobalOnlyMigrationMessage}`,
                 plan: plan.value,
             },
         };
@@ -365,7 +365,7 @@ export async function runInitCommandWithSetupTui(parsed, environment, setupTui)
 }
 export async function runSetupTuiCommand(environment, input) {
     if (!canRunInteractiveTui(environment.stdin, environment.stdout))
-        return okText('Setup TUI requires an interactive TTY; no provider config was written. Run `vgxness init --plan` or `vgxness setup plan` for read-only output.\n');
+        return okText('Setup TUI requires an interactive TTY. [read-only] No provider config was written. Run `vgxness init --plan` or `vgxness setup plan` for read-only preview output; apply later with `vgxness setup apply --yes` only after review.\n');
     const selectedDatabasePath = databasePathSelectionFor({}, environment);
     if (!selectedDatabasePath.ok)
         return resultFailure(selectedDatabasePath);

package/dist/cli/doctor-renderer.js

@@ -21,6 +21,6 @@ export function renderDoctorReport(input) {
         if (check.status !== 'pass' && check.remediation !== undefined)
             lines.push(`  Fix: ${check.remediation}`);
     }
-    lines.push('', 'Safety: read-only; provider config was not written.', `Next: ${next}`);
+    lines.push('', 'Safety: [read-only] No provider config was written. This diagnostic does not install or repair provider config.', `Next: ${next}`);
     return `${lines.join('\n')}\n`;
 }

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

@@ -1,6 +1,6 @@
 export function renderSetupPlan(plan) {
     return [
-        'Setup Plan',
+        'Setup Plan [read-only] [preview]',
         `Project: ${plan.project}`,
         `Workspace root: ${plan.workspaceRoot}`,
         `Database: ${plan.db.mode} — ${plan.db.path} (source: ${plan.db.source})`,
@@ -10,7 +10,7 @@ export function renderSetupPlan(plan) {
         ...renderBackups(plan),
         ...renderConflicts(plan),
         ...renderNextCommands(plan),
-        'Safety: read-only plan; provider config was not written. Apply requires --yes.',
+        'Safety: [read-only] preview only. No provider config was written. Explicit confirmation is required before writing provider config; apply with --yes only after review.',
     ].join('\n');
 }
 function renderOpenCode(plan) {

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

@@ -1,6 +1,6 @@
 export function renderSetupStatus(status) {
     return [
-        'Setup Status',
+        'Setup Status [read-only]',
         `- Environment: ${status.environment.status} — ${status.environment.summary}`,
         `- Project: ${status.projectState.status} — ${status.projectState.summary}`,
         `- Store: ${status.store.status}${status.store.path === '' ? '' : ` — ${status.store.path}`}${status.store.blocker === undefined ? '' : ` (${status.store.blocker})`}`,
@@ -10,7 +10,7 @@ export function renderSetupStatus(status) {
         `- Verification: ${status.verification.status} — ${status.verification.summary}`,
         `- Next setup action: ${status.nextAction.command} — ${status.nextAction.reason}`,
         `- Provider writes: ${status.safety.writesProviderConfig} · provider execution: ${status.safety.executesProvider}`,
-        'Safety: read-only status; provider config was not written; providers were not executed.',
+        'Safety: [read-only] status only. No provider config was written; providers were not executed. Mutating setup commands require explicit confirmation.',
     ].join('\n');
 }
 export function setupNeedsAction(status) {

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

@@ -8,7 +8,7 @@ const dashboardHero = {
     badges: [tuiBadges.readOnly, tuiBadges.noProviderWrites],
 };
 const statCards = [
-    { label: 'actions', value: '5', badge: '', description: 'safe routes' },
+    { label: 'routes', value: '5', badge: '', description: 'setup diagnostics preview manual exit' },
     { label: 'provider', value: '1', badge: '', description: 'OpenCode' },
     { label: 'writes', value: '0', badge: '', description: 'dashboard render' },
     { label: 'SDD', value: 'OpenCode', badge: '', description: 'daily surface' },
@@ -19,39 +19,39 @@ const statusSnapshotLines = [
 ];
 const optionCopy = {
     setup: {
-        label: 'Setup OpenCode',
-        description: 'guided install; confirm before writes',
-        badges: [tuiBadges.requiresConfirmation],
-        detailTitle: 'Setup OpenCode',
-        detailLines: ['Guided install opens in review mode; provider writes require final confirmation.'],
+        label: 'Setup / install OpenCode',
+        description: 'guided setup; writes only after final confirmation',
+        badges: ['[confirm required]'],
+        detailTitle: 'Setup / install OpenCode',
+        detailLines: ['Opens the guided setup flow. Provider config writes require final confirmation; review screens stay preview-only.'],
     },
     doctor: {
-        label: 'Doctor / recovery',
-        description: 'health and repair commands',
-        badges: [tuiBadges.previewOnly],
-        detailTitle: 'Doctor / recovery',
-        detailLines: ['Shows status and recovery guidance only; it does not call providers.'],
+        label: 'Diagnostics / doctor',
+        description: 'status and recovery guidance only',
+        badges: ['[read-only]'],
+        detailTitle: 'Diagnostics / doctor',
+        detailLines: ['Shows status and recovery guidance only. This route does not install, repair, or call providers.'],
     },
     sdd: {
-        label: 'SDD workflow',
-        description: 'diagnostics, recovery, fallback',
-        badges: [tuiBadges.previewOnly],
-        detailTitle: 'SDD workflow',
-        detailLines: ['Use OpenCode conversation plus VGXNESS MCP and hidden SDD subagents for daily progression; this TUI stays read-only for setup, diagnostics, recovery, and fallback commands.'],
+        label: 'Provider plan / preview',
+        description: 'read-only setup plan and SDD guidance',
+        badges: ['[preview]', '[read-only]'],
+        detailTitle: 'Provider plan / preview',
+        detailLines: ['Use preview/status commands to inspect provider setup. Daily SDD progression remains in OpenCode with VGXNESS MCP; this menu does not write provider config.'],
     },
     'advanced-cli': {
-        label: 'Advanced CLI',
-        description: 'fallback scripts, no automation',
-        badges: [tuiBadges.manual],
+        label: 'Advanced / manual CLI',
+        description: 'manual fallback commands and scripts',
+        badges: ['[manual]', '[read-only]'],
         detailTitle: 'Advanced CLI',
         detailLines: ['Prints explicit diagnostic, recovery, fallback, and scripting command references; no provider config is written.'],
     },
     exit: {
-        label: 'Quit',
-        description: 'leave cleanly',
-        badges: [tuiBadges.exit, tuiBadges.noProviderWrites],
-        detailTitle: 'Quit',
-        detailLines: ['Close the dashboard; no provider config was written.'],
+        label: 'Exit / cancel',
+        description: 'leave cleanly without writes',
+        badges: ['[manual]', tuiBadges.noProviderWrites],
+        detailTitle: 'Exit / cancel',
+        detailLines: ['Close the dashboard or cancel navigation; no provider config was written.'],
     },
 };
 export function buildMainMenuViewModel(state) {
@@ -62,14 +62,14 @@ export function buildMainMenuViewModel(state) {
         subtitle: dashboardHero.subtitle,
         hero: dashboardHero,
         statCards,
-        contextLines: ['Pick a route. Dashboard render stays passive/read-only; daily SDD continues in OpenCode.'],
+        contextLines: ['Pick a route: setup, diagnostics, provider preview, advanced/manual, or exit. Dashboard render stays passive/read-only.'],
         options,
         detail: { title: focused.detailTitle, lines: focused.detailLines, badges: focused.badges },
         statusSnapshot: { title: 'Signal', lines: statusSnapshotLines, badges: [tuiBadges.readOnly] },
-        safetyLines: ['read-only • no provider writes • explicit confirmation'],
+        safetyLines: ['[read-only] dashboard • [preview] plans • [confirm required] provider writes • [manual] advanced/exit'],
         helpLines: state.helpVisible
-            ? ['Keys: ↑/↓ or j/k move, Enter open, ?/h help, q/Esc quit.', 'Guidance entries print fallback/diagnostic commands only; setup writes still require confirmation.']
+            ? ['Keys: ↑/↓ or j/k move, Enter open, b/back cancel, ?/h help, q/Esc exit.', 'Diagnostics and previews are read-only; setup writes still require final confirmation.']
             : [],
-        footer: state.viewport.mode === 'narrow' ? 'no provider writes • explicit confirmation' : 'j/k • enter • q • no provider writes • explicit confirmation',
+        footer: state.viewport.mode === 'narrow' ? 'enter open • q/Esc exit • [confirm required]' : 'j/k move • enter open • b back • q/Esc exit • no provider writes without confirmation',
     };
 }

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

@@ -34,6 +34,10 @@ function clampLine(line, width) {
         'read-only',
         'quit without writes',
         'provider config writes',
+        '[confirm required]',
+        '[read-only]',
+        '[preview]',
+        '[manual]',
     ];
     const phrase = protectedPhrases.find((candidate) => line.includes(candidate));
     if (phrase !== undefined)
@@ -41,6 +45,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] : []);
+    const badges = formatBadges([...(choice.focused === true ? [tuiBadges.focused] : []), ...choice.badges]);
     return `${choice.focused === true ? '›' : ' '} ${choice.label}${badges.length === 0 ? '' : ` ${badges}`} — ${choice.description}`;
 }

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] : []);
+    const badges = formatBadges([...(option.focused ? [tuiBadges.focused] : []), ...option.badges]);
     return `${option.focused ? '›' : ' '} ${option.label}${badges.length === 0 ? '' : ` ${badges}`} — ${option.description}`;
 }

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

@@ -21,10 +21,10 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
     const warnings = plan?.conflicts.filter((conflict) => conflict.severity === 'warning').map((conflict) => conflict.message) ?? [];
     const backups = plan?.backupsPlanned.map((backup) => `${backup.targetPath} (${backup.reason})`) ?? [];
     const previewLabel = state?.previewRefresh === 'refreshing'
-        ? 'Preview: refreshing plan from current choices [read-only]'
+        ? `Preview: refreshing plan from current choices ${badgeLabels.preview} ${badgeLabels.readOnly} ${badgeLabels.noFilesWritten}`
         : state?.previewRefresh === 'failed'
-            ? 'Preview: refresh failed [warning]'
-            : 'Preview: current choices are reflected in the read-only plan';
+            ? `Preview: refresh failed ${badgeLabels.warning} ${badgeLabels.noFilesWritten}`
+            : `Preview: current choices are reflected in the read-only plan ${badgeLabels.preview} ${badgeLabels.readOnly} ${badgeLabels.noFilesWritten}`;
     return {
         title: 'VGXNESS Setup Assistant',
         projectLabel: project,
@@ -35,20 +35,20 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         databaseLabel: plan === undefined ? 'pending' : plan.db.mode,
         databasePathLabel: compactPath(databasePath, 72),
         databaseSourceLabel: String(databaseSource),
-        scopeLabel: isOpenCode ? (opencode?.scope ?? selections?.scope ?? 'user') : isClaude ? 'Project-local Claude config only; OpenCode controls disabled' : 'Manual / none (OpenCode controls disabled)',
+        scopeLabel: isOpenCode ? 'user-global provider config' : isClaude ? 'User-global Claude config only; project-local files are diagnostics' : 'Manual / none (OpenCode controls disabled)',
         installModeLabel: isOpenCode
             ? opencode?.installsAgents === false
                 ? 'mcp-only'
                 : (selections?.installMode ?? 'mcp-plus-agents')
             : isClaude
-                ? 'Claude guarded apply outside guided OpenCode install'
+                ? 'Claude guarded user-global 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.',
+        targetPathLabel: isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : isClaude ? 'Claude targets: user-global ~/.claude.json, ~/.claude/agents/*.md, ~/.claude/CLAUDE.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 user-global 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 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.',
+            ? 'OpenCode is the default guided install provider. VGXNESS will manage user-global provider configuration. Claude is first-class supported via guarded mcp install claude --yes --run-id <id>. Project-local provider files are external/manual diagnostics and will not be modified.'
+            : 'Manual / none is read-only guidance. Claude remains supported through explicit guarded user-global apply outside this guided OpenCode flow.',
         agentReadinessLabel: agentReadiness.label,
         agentReadinessDetail: agentReadiness.detail,
         plannedActions: plan?.actions.map((action) => ({
@@ -63,29 +63,28 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         nextCommands: plan?.nextCommands ?? ['vgxness setup plan'],
         canAutoApply: plan?.provider === 'opencode' && plan.status === 'ready' && state?.selections.provider !== 'none' && plan.opencode !== undefined,
         safetyWarning: isOpenCode && (selections?.overwriteVgxness === true || opencode?.overwriteVgxness === true)
-            ? 'Final confirmation is required. Reinstall is enabled: VGXNESS OpenCode entries will be overwritten after a managed backup when the target exists; unrelated config is preserved.'
-            : 'Final confirmation is required before any provider config write. OpenCode config may be modified and backed up.',
+            ? `${badgeLabels.confirmRequired} Final confirmation remains required. Explicit confirmation is required before writing provider config. Reinstall is enabled: user-global VGXNESS OpenCode entries will be overwritten after a managed backup when the target exists; unrelated config is preserved. Project-local provider files are external/manual diagnostics and will not be modified.`
+            : `${badgeLabels.confirmRequired} Final confirmation remains required. Explicit confirmation is required before writing provider config. VGXNESS will manage user-global provider configuration. Project-local provider files are external/manual diagnostics and will not be modified.`,
         frameLabel: 'VGXNESS Setup Assistant workspace',
         progressLabel: progressLabel(state?.screen),
         previewLabel,
         previewDetailLines: previewDetailLines({ plan, provider, databasePath, databaseSource, blockers, warnings, backups, isOpenCode }),
         helpVisible: state?.helpVisible ?? false,
         helpLines: helpLines(state?.screen),
-        footerSafetyLabel: 'Safety: plan review is read-only; final confirmation is the first write-capable screen.',
+        footerSafetyLabel: `Safety: plan review is ${badgeLabels.readOnly} ${badgeLabels.noFilesWritten}; final confirmation is ${badgeLabels.confirmRequired} and is the first write-capable screen.`,
         databaseChoices: [
             choice('database:global', 'Global database', 'Use the OS-level VGXNESS database. Recommended for normal local use.', selections?.databaseMode === 'global' || (selections === undefined && plan?.db.mode === 'global'), state?.focusedChoiceId, [badgeLabels.recommended]),
             choice('database:project-local', 'Project-local database', 'Preview a workspace-scoped database path. No file is created here.', selections?.databaseMode === 'project-local' || (selections === undefined && plan?.db.mode === 'project-local'), state?.focusedChoiceId, [badgeLabels.readOnly]),
             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', 'Default guided install provider; writes still require final confirmation.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
-            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:opencode', 'OpenCode', 'Default guided install provider. VGXNESS will manage user-global provider configuration.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
+            choice('provider:claude-supported', 'Claude (first-class supported)', 'Claude user-global CLI MCP registration and config apply only via guarded mcp install claude --yes --run-id <id>; project-local files are diagnostics only.', (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
             ? [
-                choice('scope:user', 'User/global scope', 'Preview the default user-level OpenCode config target; still requires final confirmation.', (selections?.scope ?? opencode?.scope ?? 'user') === 'user', state?.focusedChoiceId, [badgeLabels.recommended, badgeLabels.writeAfterConfirm]),
-                choice('scope:project', 'Project scope', 'Opt in to writing project OpenCode config only after final confirmation.', (selections?.scope ?? opencode?.scope) === 'project', state?.focusedChoiceId, [badgeLabels.writeAfterConfirm]),
+                choice('scope:user', 'User-global provider config', 'VGXNESS will manage user-global provider configuration. Project-local provider files are external/manual diagnostics and will not be modified.', true, state?.focusedChoiceId, [badgeLabels.recommended, badgeLabels.writeAfterConfirm]),
             ]
             : [],
         installModeChoices: isOpenCode
@@ -96,7 +95,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
             : [],
         overwriteChoices: isOpenCode
             ? [
-                choice('overwrite:vgxness', 'Reinstall VGXNESS entries', 'Default off. When enabled, final confirmation overwrites existing VGXNESS OpenCode entries and preserves unrelated OpenCode config.', selections?.overwriteVgxness ?? opencode?.overwriteVgxness ?? false, state?.focusedChoiceId, [badgeLabels.warning, badgeLabels.writeAfterConfirm]),
+                choice('overwrite:vgxness', 'Reinstall VGXNESS entries', 'Default off. When enabled, final confirmation overwrites existing user-global VGXNESS OpenCode entries and preserves unrelated OpenCode config.', selections?.overwriteVgxness ?? opencode?.overwriteVgxness ?? false, state?.focusedChoiceId, [badgeLabels.warning, badgeLabels.writeAfterConfirm]),
             ]
             : [],
     };
@@ -109,13 +108,13 @@ function previewDetailLines(input) {
         `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'}`,
+        `Scope: ${input.isOpenCode ? 'user-global provider config' : '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 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.'}`,
+        `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation. VGXNESS will manage user-global provider configuration. Claude first-class support requires guarded mcp install claude --yes --run-id <id>. Project-local provider files are external/manual diagnostics and will not be modified.' : 'No guided provider install from this selection; Claude uses guarded explicit user-global 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'}`,
+        `Safety: ${input.isOpenCode ? `${badgeLabels.confirmRequired} only on final confirmation; ${badgeLabels.noFilesWritten} during preview` : `${badgeLabels.readOnly} ${badgeLabels.noFilesWritten} manual/no-provider-write mode`}`,
         ...actions,
         input.backups.length === 0 ? 'Backups: none planned' : `Backups: ${input.backups.join('; ')}`,
         ...(input.warnings.length === 0 ? ['Warnings: none'] : input.warnings.map((warning) => `Warning: ${warning}`)),
@@ -132,7 +131,8 @@ 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 first-class supported 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 user-global apply via mcp install claude --yes --run-id <id>; Manual / none writes no provider config.',
+        'Provider config: VGXNESS will manage user-global provider configuration. Project-local provider files are external/manual diagnostics and will not be modified.',
         '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.',
     ];
@@ -177,7 +177,7 @@ function progressLabel(screen) {
     if (screen === 'provider')
         return 'Step 3/6 Provider: choose OpenCode or manual/none';
     if (screen === 'opencode-details')
-        return 'Step 4/6 OpenCode: scope and install mode';
+        return 'Step 4/6 OpenCode: user-global target and install mode';
     if (screen === 'plan-review')
         return 'Step 5/6 Review: read-only plan review';
     if (screen === 'final-confirmation')
@@ -201,7 +201,7 @@ function readinessBadge(status) {
     if (status === 'manual-required')
         return badgeLabels.warning;
     if (status === 'conflict' || status === 'blocked')
-        return badgeLabels.error;
+        return badgeLabels.blocked;
     return badgeLabels.warning;
 }
 function opencodeActionLabel(action) {