vgxness 1.6.0 → 1.8.0

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

@@ -1,33 +1,38 @@
+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 },
         { kind: 'project-config', label: 'Project Claude agents', path: '.claude/agents/*.md', writableBySetup: false },
         { kind: 'project-config', label: 'Project Claude memory', path: 'CLAUDE.md', writableBySetup: false },
+        { kind: 'user-config', label: 'User Claude MCP config', path: '~/.claude.json', writableBySetup: false },
         { kind: 'user-config', label: 'User Claude agents', path: '~/.claude/agents/*.md', writableBySetup: false },
+        { 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, and project/user agent planning; 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.'],
-            guidance: ['Use `vgxness mcp install claude --scope local|project|user --yes --run-id <id>` for explicit guarded apply. VGXNESS may write project-root CLAUDE.md only through confirmed, preflighted Claude project install; it never manually writes ~/.claude.json or .claude/CLAUDE.md. Read-only setup/status surfaces do not execute Claude Code.'],
+            guidance: ['Use `vgxness mcp install claude --scope local|project|user --yes --run-id <id>` for explicit guarded apply. Project scope may write .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block. User/global scope narrowly merges only mcpServers.vgxness in ~/.claude.json, writes ~/.claude/agents/*.md, and manages only the VGXNESS block in ~/.claude/CLAUDE.md. Read-only setup/status surfaces do not execute Claude Code.'],
             actions: [
                 {
                     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 ?? []),
             ],
         };
     },
@@ -46,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/docs/architecture.md

@@ -18,7 +18,7 @@ The user-facing shape is deliberately four-surface: **MCP for agents**, **CLI fo
 | Core workflow | SDD-first canonical state: explore → proposal → spec → design → tasks → apply-progress → verify → archive. |
 | Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows, and `vgxness code` runtime for bounded workspace work. |
 | Installation UX | Step-based guided setup with doctor checks, dry-run support, and no manual provider JSON editing on the happy path. |
-| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for CLI MCP registration, project `.mcp.json` compatibility, guarded project-root `CLAUDE.md` managed memory, and project/user agent planning. Claude scopes are `local`, `project`, and `user` (`personal`/`global` map to `user`). Read-only status/doctor/change-plan never execute Claude Code or inspect private Claude config, and VGXNESS never manually mutates `~/.claude.json` or `.claude/CLAUDE.md`. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
+| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for CLI MCP registration, project `.mcp.json` compatibility, guarded `CLAUDE.md` managed memory, direct user `~/.claude.json` MCP merge, and project/user agent files. Claude scopes are `local`, `project`, and `user` (`personal`/`global` map to `user`). Read-only status/doctor/change-plan never execute Claude Code; user/global apply mutates only `mcpServers.vgxness`, VGXNESS-owned `~/.claude/agents/*.md`, and the VGXNESS block in `~/.claude/CLAUDE.md` after confirmation/preflight. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
 | Memory | Project memory plus personal/global memory, backed locally. |
 | Agents | Agents/subagents are registered in a neutral schema, then rendered into provider-specific config. |
 | Skills | Skills are first-class, versioned, attachable to agents/workflows/adapters, and improved through reviewable proposals. |
@@ -439,7 +439,7 @@ vgxness agents render --provider opencode --project vgxness --name apply-agent
 Rendering is intentionally read-only: it returns generated content in the CLI response. It does **not** write `.opencode/`, `.claude/`, or any user/global provider config.
 OpenCode agent keys are sanitized deterministically from registry names, and rendering rejects key collisions instead of overwriting generated config.
 
-Claude Code install planning/apply is supported through the guarded MCP install path. Rendering remains read-only; confirmed project compatibility writes are limited to `.mcp.json`, `.claude/agents/*.md`, and the project-root `CLAUDE.md` managed block with run preflight metadata. Local/user MCP registration is represented through Claude CLI argv after confirmation/preflight, not private config mutation.
+Claude Code install planning/apply is supported through the guarded MCP install path. Rendering remains read-only; confirmed project compatibility writes are limited to `.mcp.json`, `.claude/agents/*.md`, and the project-root `CLAUDE.md` managed block with run preflight metadata. User/global install is a guarded direct path that backs up existing files, merges only `mcpServers.vgxness` in `~/.claude.json`, writes VGXNESS-owned `~/.claude/agents/*.md`, and manages only the VGXNESS block in `~/.claude/CLAUDE.md`.
 
 ### OpenCode injection preview
 

package/docs/cli.md

@@ -232,7 +232,7 @@ bun run cli:bun -- sdd status --project vgxness --change my-change
 Provider support shown in the Installation surface is:
 
 - **OpenCode** — supported primary provider with preview/status/doctor and read-only install planning.
-- **Claude** — supported secondary provider for Claude CLI MCP registration, project `.mcp.json` compatibility, project-root `CLAUDE.md` managed memory, and project/user agent planning. Scopes are `local|project|user`; `personal`/`global` map to `user`. Explicit guarded apply is outside the guided OpenCode flow and requires `mcp install claude --scope <scope> --yes --run-id <id>`. Read-only status/doctor/change-plan do not read private Claude config or execute Claude Code.
+- **Claude** — supported secondary provider for Claude CLI MCP registration, project `.mcp.json` compatibility, guarded `CLAUDE.md` managed memory, user `~/.claude.json` MCP merge, and project/user agents. Scopes are `local|project|user`; `personal`/`global` map to `user`. Explicit guarded apply is outside the guided OpenCode flow and requires `mcp install claude --scope <scope> --yes --run-id <id>`. Read-only status/doctor/change-plan do not execute Claude Code.
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
@@ -508,7 +508,7 @@ Manual OpenCode verification checklist:
 
 ## Claude Code MCP install
 
-Claude Code is supported as a secondary, non-default provider for VGXNESS MCP/subagent configuration. Planning/status/doctor/change-plan are read-only and do not require Claude Code, network, or credentials. Scopes are `local`, `project`, and `user`; compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as Claude CLI argv (`claude mcp add --scope <scope> vgxness -- vgxness mcp start`), never shell strings or manual `~/.claude.json` mutation.
+Claude Code is supported as a secondary, non-default provider for VGXNESS MCP/subagent configuration. Planning/status/doctor/change-plan are read-only and do not require Claude Code, network, or credentials. Scopes are `local`, `project`, and `user`; compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as structured config/argv (`claude mcp add --scope <scope> vgxness -- vgxness mcp start`), never shell strings. User/global apply narrowly merges only `mcpServers.vgxness` in `~/.claude.json` and preserves unknown keys/auth/session data.
 
 ```bash
 bun run cli:bun -- mcp install claude --plan --scope project --db <path>
@@ -526,8 +526,8 @@ User agent files target `~/.claude/agents/*.md` only when a future apply path ex
 
 Forbidden writes:
 
-- `~/.claude.json`
-- `.claude/CLAUDE.md`
+- `~/.claude.json` except guarded user/global `mcpServers.vgxness` merge
+- `.claude/CLAUDE.md`; user/global uses `~/.claude/CLAUDE.md` and manages only the VGXNESS block
 
 Malformed or conflicting VGXNESS markers in project-root `CLAUDE.md` refuse the full Claude project install before any Claude target is mutated.
 

package/docs/providers.md

@@ -7,7 +7,7 @@ VGXNESS is provider-agnostic at the core: the registry stores provider-neutral d
 | Provider | Control plane | Code runtime | Notes |
 |---|---|---|---|
 | OpenCode | `managed` | n/a (target) | Primary supported provider. The configurator renders OpenCode MCP config and manager/SDD agent definitions into the chosen scope. |
-| Claude Code | `supported-secondary` | n/a | Supported for Claude CLI MCP registration planning/apply, project `.mcp.json` compatibility, project-root `CLAUDE.md` managed memory, and project/user agent planning. Scopes are `local`, `project`, and `user`; `personal`/`global` map to `user` for compatibility. Confirmed applies are explicit and guarded; read-only surfaces do not execute Claude Code and VGXNESS never manually mutates `~/.claude.json`. |
+| Claude Code | `supported-secondary` | n/a | Supported for Claude CLI MCP registration planning/apply, project `.mcp.json` compatibility, guarded `CLAUDE.md` managed memory, user `~/.claude.json` MCP merge, and project/user agent files. Scopes are `local`, `project`, and `user`; `personal`/`global` map to `user` for compatibility. Confirmed applies are explicit and guarded; read-only surfaces inspect files without executing Claude Code. |
 | Antigravity | `placeholder` | n/a | Listed in the TUI Installation surface as coming-soon. |
 | Custom / future | `extension` | extension point | Per the [Architecture](./architecture.md) decision, anything not OpenCode or Claude is a custom extension. |
 | OpenAI-compatible | n/a | `openai-compatible-provider-adapter.ts` | Real adapter used by `vgxness code`. Speaks to any OpenAI-compatible endpoint. |
@@ -46,7 +46,7 @@ vgxness agents render --provider json --project vgxness --name apply-agent
 
 Claude Code is supported as a secondary, non-default control-plane target. Read-only status, doctor, setup plan, and change-plan surfaces can inspect or preview Claude targets without Claude Code installed and without writing files.
 
-Claude scopes are canonicalized to `local`, `project`, and `user`; VGXNESS compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as argv only, for example `claude mcp add --scope user vgxness -- vgxness mcp start`; no shell strings or manual `~/.claude.json` edits are generated. Status/doctor/change-plan avoid private Claude config reads and do not execute Claude Code.
+Claude scopes are canonicalized to `local`, `project`, and `user`; VGXNESS compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as structured config/argv, for example `claude mcp add --scope user vgxness -- vgxness mcp start`; no shell strings are generated. For user/global apply, VGXNESS narrowly merges only `mcpServers.vgxness` in `~/.claude.json`, preserves unknown keys, backs up existing files, and does not manage auth/session data. Status/doctor/change-plan are read-only and do not execute Claude Code.
 
 Allowed project-scope writes, only after explicit guarded apply with run preflight metadata (`vgxness mcp install claude --scope project --yes --run-id <id>`):
 
@@ -58,8 +58,8 @@ User-scoped agent files target `~/.claude/agents/*.md` only as an explicit exter
 
 Forbidden writes:
 
-- `~/.claude.json`
-- `.claude/CLAUDE.md`
+- `~/.claude.json` except the guarded user/global merge of `mcpServers.vgxness`
+- `.claude/CLAUDE.md`; user/global memory is `~/.claude/CLAUDE.md` and only the VGXNESS managed block is touched
 
 Malformed, duplicate, partial, or conflicting VGXNESS markers in `CLAUDE.md` cause the full Claude project install to be refused before `.mcp.json`, `.claude/agents/*.md`, or `CLAUDE.md` are mutated.
 
@@ -140,7 +140,7 @@ Writes happen only through `apply` with explicit consent. Plans, status, doctor,
 
 Adapters and renderers must not:
 
-- Write provider config outside explicit guarded apply. OpenCode install writes only its selected target; Claude project compatibility apply writes only `.mcp.json`, `.claude/agents/*.md`, and the guarded project-root `CLAUDE.md` managed block; Claude local/user MCP registration uses Claude CLI argv after confirmation/preflight and never manual private-config mutation.
+- Write provider config outside explicit guarded apply. OpenCode install writes only its selected target; Claude project compatibility apply writes only `.mcp.json`, `.claude/agents/*.md`, and the guarded project-root `CLAUDE.md` managed block. Claude user/global apply narrowly merges `mcpServers.vgxness` in `~/.claude.json`, writes VGXNESS-owned `~/.claude/agents/*.md`, and manages only the VGXNESS block in `~/.claude/CLAUDE.md` after confirmation/preflight.
 - Call providers (`opencode`, `claude`, etc.) during preview or status.
 - Install global memory.
 - Create `openspec/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.6.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": {