vgxness 1.5.2 → 1.7.0

package/dist/sdd/schema.js

@@ -1,5 +1,20 @@
 import { z } from 'zod';
 export const sddPhases = ['explore', 'proposal', 'spec', 'design', 'tasks', 'apply-progress', 'verify', 'archive'];
+/**
+ * Governance status of an SDD artifact.
+ *
+ * - `draft`     — present in the DB; satisfies downstream readiness when the
+ *                 `VGXNESS_SDD_AUTO_ADVANCE` feature flag is on (or
+ *                 `SddWorkflowService` is constructed with `autoAdvance: true`).
+ *                 Does NOT count toward the change being `complete`.
+ * - `accepted`  — content has been frozen by an explicit human
+ *                 `vgxness_sdd_accept_artifact` call. Satisfies downstream
+ *                 readiness regardless of the auto-advance flag.
+ * - `rejected`  — explicit human rejection. Hard-blocker for downstream
+ *                 readiness; can only be cleared by re-opening the artifact.
+ * - `superseded`— replaced by a newer artifact under a different topic key.
+ *                 Hard-blocker; cannot be re-saved or accepted.
+ */
 export const sddArtifactStatuses = ['draft', 'accepted', 'rejected', 'superseded'];
 export const sddArtifactNormalizationWarnings = ['legacy-artifact-defaulted-to-draft', 'invalid-artifact-metadata-defaulted-to-draft'];
 export const SddArtifactStatusSchema = z.enum(sddArtifactStatuses);

package/dist/sdd/sdd-workflow-service.js

@@ -2,12 +2,32 @@ import { summarizePayloadContent } from '../payload/payload-summary.js';
 import { isSddPhase, normalizeSddArtifact, sddPhases, sddPrerequisites, sddTopicKey, } from './schema.js';
 const defaultContext = { actor: 'sdd-workflow-service' };
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function readAutoAdvanceFromEnv() {
+    const value = process.env.VGXNESS_SDD_AUTO_ADVANCE;
+    return value === 'true' || value === '1';
+}
+function isPrerequisiteSatisfied(status) {
+    if (status === undefined)
+        return false;
+    if (status.legacy === true)
+        return false;
+    if (status.accepted === true)
+        return true;
+    if (status.state === 'draft')
+        return true;
+    return false;
+}
 export class SddWorkflowService {
     memory;
     context;
-    constructor(memory, context = defaultContext) {
+    options;
+    constructor(memory, context = defaultContext, options = {}) {
         this.memory = memory;
         this.context = context;
+        this.options = {
+            ...options,
+            autoAdvance: options.autoAdvance ?? readAutoAdvanceFromEnv(),
+        };
     }
     getWorkflow(change) {
         return sddPhases.map((phase) => ({
@@ -23,7 +43,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value);
+        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value, this.options);
         return {
             ok: true,
             value: {
@@ -40,7 +60,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        return statusFromPhases(validated.value.change, phases.value);
+        return statusFromPhases(validated.value.change, phases.value, this.options);
     }
     getNext(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -49,7 +69,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        return ok(nextDecisionFromStatuses(validated.value.change, phases.value));
+        return ok(nextDecisionFromStatuses(validated.value.change, phases.value, this.options));
     }
     getCockpit(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -59,12 +79,12 @@ export class SddWorkflowService {
         if (!snapshot.ok)
             return snapshot;
         const phases = snapshot.value.phases;
-        const next = nextDecisionFromStatuses(validated.value.change, phases);
+        const next = nextDecisionFromStatuses(validated.value.change, phases, this.options);
         const cockpitPhases = phases.map((phaseStatus) => {
             const readiness = {
                 change: validated.value.change,
                 phase: phaseStatus.phase,
-                ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases),
+                ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases, this.options),
             };
             const artifact = phaseStatus.present ? cockpitArtifactSummaryFromSnapshotItem(phaseStatus) : undefined;
             const blockers = cockpitBlockersForPhase(phaseStatus, readiness);
@@ -115,7 +135,7 @@ export class SddWorkflowService {
         if (!snapshot.ok)
             return snapshot;
         const phases = snapshot.value.phases;
-        const status = statusFromPhases(validated.value.change, phases);
+        const status = statusFromPhases(validated.value.change, phases, this.options);
         if (!status.ok)
             return status;
         const warnings = [];
@@ -137,7 +157,7 @@ export class SddWorkflowService {
             }
             return [{ phase: phase.phase, topicKey: phase.topicKey, artifact: phase.artifact, envelope }];
         });
-        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases) };
+        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases, this.options) };
         return ok({ status: status.value, artifacts, ...(readiness === undefined ? {} : { readiness }), warnings });
     }
     saveArtifact(input) {
@@ -146,13 +166,20 @@ export class SddWorkflowService {
             return validated;
         if (input.content.trim().length === 0)
             return validationFailure('SDD artifact content must not be empty');
-        return this.memory.saveArtifact({
-            project: validated.value.project,
-            topicKey: sddTopicKey(validated.value.change, validated.value.phase),
-            phase: validated.value.phase,
-            content: input.content,
-            metadata: { status: 'draft' },
-        }, this.context);
+        const { project, change, phase } = validated.value;
+        const topicKey = sddTopicKey(change, phase);
+        const existing = this.memory.getArtifact(project, topicKey, this.context);
+        if (existing.ok) {
+            const envelope = normalizeSddArtifact(existing.value);
+            const status = envelope.metadata.status;
+            if (status === 'accepted')
+                return validationFailure('Cannot overwrite an accepted SDD artifact; supersede it under a new topic key.');
+            if (status === 'rejected')
+                return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before saving.');
+            if (status === 'superseded')
+                return validationFailure('Cannot overwrite a superseded SDD artifact.');
+        }
+        return this.memory.saveArtifact({ project, topicKey, phase, content: input.content, metadata: { status: 'draft' } }, this.context);
     }
     acceptArtifact(input) {
         const validated = this.validatePhaseInput(input);
@@ -169,6 +196,11 @@ export class SddWorkflowService {
         if (!existing.ok)
             return existing;
         const existingEnvelope = normalizeSddArtifact(existing.value);
+        const existingStatus = existingEnvelope.metadata.status;
+        if (existingStatus === 'rejected')
+            return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before accepting.');
+        if (existingStatus === 'superseded')
+            return validationFailure('Cannot accept a superseded SDD artifact; create a new artifact under a different topic key instead.');
         const acceptance = {
             actor: {
                 type: 'human',
@@ -203,7 +235,7 @@ export class SddWorkflowService {
         const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!statuses.ok)
             return statuses;
-        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value)));
+        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value, this.options)));
     }
     listArtifacts(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -219,7 +251,7 @@ export class SddWorkflowService {
                 artifacts: snapshot.value.phases.flatMap((phase) => {
                     if (phase.artifact === undefined)
                         return [];
-                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases))];
+                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases, this.options))];
                 }),
                 fullRetrieval: {
                     tool: 'vgxness_sdd_list_artifacts',
@@ -280,14 +312,14 @@ export class SddWorkflowService {
         return ok({ project, change, phases });
     }
 }
-export function nextDecisionFromStatuses(change, phases) {
+export function nextDecisionFromStatuses(change, phases, options = {}) {
     const blockedPresentPhase = phases.find((status) => {
         if (!status.present)
             return false;
-        return (getReadinessFromStatuses(change, status.phase, phases).blockedPrerequisites ?? []).length > 0;
+        return (getReadinessFromStatuses(change, status.phase, phases, options).blockedPrerequisites ?? []).length > 0;
     });
     if (blockedPresentPhase !== undefined) {
-        const readiness = getReadinessFromStatuses(change, blockedPresentPhase.phase, phases);
+        const readiness = getReadinessFromStatuses(change, blockedPresentPhase.phase, phases, options);
         const blockers = readiness.blockedPrerequisites ?? [];
         return {
             change,
@@ -329,7 +361,7 @@ export function nextDecisionFromStatuses(change, phases) {
             recommendedAction: 'No next SDD phase remains for this change.',
         };
     }
-    const readiness = getReadinessFromStatuses(change, nextMissingPhase, phases);
+    const readiness = getReadinessFromStatuses(change, nextMissingPhase, phases, options);
     if (!readiness.ready) {
         const blockers = readiness.blockedPrerequisites ?? [];
         return {
@@ -352,24 +384,26 @@ export function nextDecisionFromStatuses(change, phases) {
         recommendedAction: `Run the ${nextMissingPhase} SDD phase for ${change}.`,
     };
 }
-function statusFromPhases(change, phases) {
+function statusFromPhases(change, phases, options = {}) {
     const nextReadyPhase = sddPhases.find((phase) => {
         if (phases.find((status) => status.phase === phase)?.present)
             return false;
-        return getReadinessFromStatuses(change, phase, phases).ready;
+        return getReadinessFromStatuses(change, phase, phases, options).ready;
     });
     const status = { change, phases };
     if (nextReadyPhase !== undefined)
         status.nextReadyPhase = nextReadyPhase;
     return { ok: true, value: status };
 }
-function getReadinessFromStatuses(change, phase, phases) {
+function getReadinessFromStatuses(change, phase, phases, options = {}) {
     const satisfiedPrerequisites = [];
     const missingArtifactTopicKeys = [];
     const blockedPrerequisites = [];
+    const useAutoAdvance = options.autoAdvance === true;
     for (const prerequisite of sddPrerequisites[phase]) {
         const status = phases.find((candidate) => candidate.phase === prerequisite);
-        if (status?.accepted) {
+        const satisfied = useAutoAdvance ? isPrerequisiteSatisfied(status) : status?.accepted === true;
+        if (satisfied) {
             satisfiedPrerequisites.push(prerequisite);
             continue;
         }
@@ -508,10 +542,6 @@ function blockerReasonForStatus(status) {
     if (status.legacy === true)
         return 'legacy';
     const state = status.state ?? (status.present ? 'draft' : 'missing');
-    if (state === 'missing')
-        return 'missing';
-    if (state === 'accepted')
-        return 'draft';
     return state;
 }
 function formatBlockers(blockers) {

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

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

package/dist/setup/setup-plan.js

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

package/docs/architecture.md

@@ -18,7 +18,7 @@ The user-facing shape is deliberately four-surface: **MCP for agents**, **CLI fo
 | Core workflow | SDD-first canonical state: explore → proposal → spec → design → tasks → apply-progress → verify → archive. |
 | Interfaces | MCP server for AI tools, CLI for automation/power users, TUI for guided install/status/profile/SDD workflows, and `vgxness code` runtime for bounded workspace work. |
 | Installation UX | Step-based guided setup with doctor checks, dry-run support, and no manual provider JSON editing on the happy path. |
-| Provider strategy | Provider-agnostic domain model with OpenCode as the primary supported provider; Claude Code is preview/manual only and VGXNESS does not install Claude or write `.claude/` or `CLAUDE.md`. Pi/`gentle-pi` compatibility is a future adapter/reference target. The code runtime speaks to any OpenAI-compatible endpoint through `src/code/providers/openai-compatible-provider-adapter.ts`. |
+| Provider strategy | Provider-agnostic domain model with OpenCode as the primary/default supported provider; Claude Code is supported secondary for CLI MCP registration, project `.mcp.json` compatibility, guarded `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 rendering remains follow-up work after its exact install-safe artifact shape is specified.
+Claude Code install planning/apply is supported through the guarded MCP install path. Rendering remains read-only; confirmed project compatibility writes are limited to `.mcp.json`, `.claude/agents/*.md`, and the project-root `CLAUDE.md` managed block with run preflight metadata. 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** — preview-only guidance; no install/apply action is exposed.
+- **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.
 
@@ -445,7 +445,7 @@ bun run cli:bun -- mcp setup --preview --provider claude --db <path>
 bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke
 ```
 
-The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`.
+The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`. For Claude config, inspect `mcp install claude --plan --scope local|project|user`; confirmed writes or CLI execution require `mcp install claude --scope <scope> --yes --run-id <id>` so VGXNESS run preflight can authorize each target.
 
 The top-level `vgxness doctor` command prints human-readable readiness checks by default and accepts `--json` for scriptable output. Lower-level `mcp doctor` remains useful for MCP-specific checks and manual diagnostics; use `--json` where parseable output is needed. `ready:true` means required checks passed. `ready:false` means at least one required check failed; read the failed check `id`, `detail`, and optional `remediation` to fix the local setup, then run doctor again.
 
@@ -506,6 +506,41 @@ Manual OpenCode verification checklist:
 5. In OpenCode, confirm the `vgxness` MCP tools are available.
 6. Call `vgxness_sdd_status` against a known project/change, then run doctor again if anything fails.
 
+## Claude Code MCP install
+
+Claude Code is supported as a secondary, non-default provider for VGXNESS MCP/subagent configuration. Planning/status/doctor/change-plan are read-only and do not require Claude Code, network, or credentials. Scopes are `local`, `project`, and `user`; compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as 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>
+bun run cli:bun -- mcp install claude --plan --scope user --db <path>
+bun run cli:bun -- mcp install claude --yes --scope project --run-id <id> --db <path>
+```
+
+Allowed project-scope writes after explicit confirmation and run preflight:
+
+- `.mcp.json`
+- `.claude/agents/*.md`
+- project-root `CLAUDE.md`, only the VGXNESS managed block; user-authored content outside the block is preserved and existing files are backed up before append/update
+
+User agent files target `~/.claude/agents/*.md` only when a future apply path explicitly preflights that external directory. Read-only plans/status/doctor/change-plan never write it.
+
+Forbidden writes:
+
+- `~/.claude.json` 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.
+
+Manual/opt-in runtime validation checklist (not normal CI):
+
+1. Apply Claude project-local config through the guarded VGXNESS flow.
+2. Open Claude Code in the project manually.
+3. Approve the project MCP server if prompted.
+4. Run `/mcp` and verify `vgxness` is connected.
+5. Run `/agents` and verify expected project subagents are visible.
+6. Ask Claude to call a safe read-only VGXNESS MCP tool.
+7. Confirm forbidden files were not written by VGXNESS.
+
 ## SDD workflow examples
 
 Use `sdd` commands to inspect local SDD artifact state and save, read, or list phase artifacts. These commands read and write only the selected `vgxness` local SQLite memory store: `--db <path>` when passed, `VGXNESS_DB_PATH` when set, or the global default database when neither override is present.

package/docs/glossary.md

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

package/docs/prd.md

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

package/docs/providers.md

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

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

package/package.json

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