vgxness 1.21.0 → 1.21.2

package/dist/adapters/opencode/install/client-install-opencode-contract.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, } from './opencode-default-agent-config.js';
+import { planVgxnessPathProfileUpdate, resolveVgxnessPathEnvironment, } from './vgxness-path-environment.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
 const opencodeUserGlobalOnlyMessage = 'VGX-managed OpenCode configuration is user-global only. Project/local OpenCode files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
 export function resolveOpenCodeMcpInstallTarget(input) {
@@ -40,7 +41,7 @@ export function planOpenCodeMcpInstall(input) {
     if (scope === 'user') {
         return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy);
     }
-    return refusal('unsupported_config_shape', opencodeUserGlobalOnlyMessage, input.databasePath, databasePathSource, scope, undefined, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+    return refusal('unsupported_config_shape', opencodeUserGlobalOnlyMessage, input.databasePath, databasePathSource, scope, undefined, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
 }
 function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy) {
     const target = resolveOpenCodeMcpInstallTarget({
@@ -49,15 +50,15 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
         env: input.env,
     });
     if (!target.ok) {
-        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user', undefined, [], undefined, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user', undefined, [], undefined, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     const jsoncPath = `${target.path}c`;
     if (existsSync(jsoncPath)) {
-        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (!existsSync(target.path)) {
         return {
-            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan, overwriteVgxness, bashPermissionPolicy),
+            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan, overwriteVgxness, bashPermissionPolicy, input.env),
             status: 'would_install',
             action: 'create',
             targetPath: target.path,
@@ -69,13 +70,13 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
     }
     const parsed = parseConfig(target.path);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     const config = parsed.value;
     if (config.mcp !== undefined && !isRecord(config.mcp)) {
-        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness') && !overwriteVgxness) {
-        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
     if (agentConflict.length > 0 && !overwriteVgxness) {
@@ -84,16 +85,16 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
                 kind: 'manual-check',
                 message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.`,
             },
-        ], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        ], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (agentPlan.installsAgents && config.agent !== undefined && !isRecord(config.agent)) {
-        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (config.permission !== undefined && !isRecord(config.permission)) {
-        return refusal('unsupported_config_shape', 'Existing top-level permission must be a JSON object before VGXNESS can set top-level permission.bash to ask.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_config_shape', 'Existing top-level permission must be a JSON object before VGXNESS can set top-level permission.bash to ask.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     return {
-        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan, overwriteVgxness, bashPermissionPolicy),
+        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan, overwriteVgxness, bashPermissionPolicy, input.env),
         status: 'would_install',
         action: 'merge',
         targetPath: target.path,
@@ -157,7 +158,9 @@ function deepEqual(left, right) {
     const rightKeys = Object.keys(right).sort();
     return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index] && deepEqual(left[key], right[key]));
 }
-function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan)) {
+function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan), env) {
+    const pathEnvironment = resolveVgxnessPathEnvironment({ env });
+    const pathProfileUpdate = planVgxnessPathProfileUpdate({ env });
     return {
         version: 1,
         kind: 'mcp-client-install-opencode',
@@ -172,18 +175,20 @@ function baseContract(databasePath, source, scope, targetPath, backupRequired, m
             mergePolicy,
         },
         scope,
-        warnings: warningsForScope(scope, overwriteVgxness, agentPlan, bashPermissionPolicy),
-        verificationHints: verificationHints(databasePath, source),
+        warnings: warningsForScope(scope, overwriteVgxness, agentPlan, bashPermissionPolicy, pathEnvironment),
+        verificationHints: verificationHints(databasePath, source, pathEnvironment),
         manualTest: manualTestForScope(scope, databasePath, source),
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
         overwriteVgxness,
         bashPermissionPolicy,
+        pathEnvironment,
+        ...(pathProfileUpdate.supported && pathProfileUpdate.changed ? { pathProfileUpdate } : {}),
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
-function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan)) {
-    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan, overwriteVgxness, bashPermissionPolicy);
+function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan), env) {
+    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan, overwriteVgxness, bashPermissionPolicy, env);
     return {
         ...contract,
         verificationHints: [...extraVerificationHints, ...contract.verificationHints],
@@ -193,7 +198,7 @@ function refusal(reason, message, databasePath, source, scope, targetPath, extra
         ...(targetPath !== undefined ? { targetPath } : {}),
     };
 }
-function warningsForScope(_scope, overwriteVgxness, agentPlan, bashPermissionPolicy) {
+function warningsForScope(_scope, overwriteVgxness, agentPlan, bashPermissionPolicy, pathEnvironment) {
     const overwriteWarnings = overwriteVgxness
         ? [
             `Reinstall/overwrite is enabled: existing VGXNESS-managed OpenCode entries will be replaced (${agentPlan.installsAgents ? 'mcp.vgxness, default_agent, instructions AGENTS.md, and known VGXNESS agents' : 'mcp.vgxness only'}); unrelated OpenCode config is preserved.`,
@@ -207,6 +212,7 @@ function warningsForScope(_scope, overwriteVgxness, agentPlan, bashPermissionPol
     return [
         'Restart OpenCode after installation so it reloads the user MCP config.',
         'OpenCode project config may override user config for a workspace; check project-level config if vgxness is not visible.',
+        ...pathEnvironment.warnings,
         ...overwriteWarnings,
         ...bashWarnings,
     ];
@@ -225,7 +231,7 @@ function manualTestForScope(_scope, databasePath, source) {
         doctorCommand: createVgxnessMcpDoctorCommand(databasePath, source),
     };
 }
-function verificationHints(databasePath, source) {
+function verificationHints(databasePath, source, pathEnvironment) {
     return [
         {
             kind: 'restart-client',
@@ -240,5 +246,6 @@ function verificationHints(databasePath, source) {
             message: 'Run the MCP doctor command after installation.',
             command: createVgxnessMcpDoctorCommand(databasePath, source),
         },
+        ...(pathEnvironment.vgxness.onPath ? [] : pathEnvironment.remediation.map((message) => ({ kind: 'manual-check', message }))),
     ];
 }

package/dist/adapters/opencode/install/client-install-opencode.js

@@ -1,9 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createManagedProviderConfigBackup } from '../../../setup/backup-rollback-service.js';
 import { findConflictingVgxnessAgents, planOpenCodeMcpInstall, } from './client-install-opencode-contract.js';
-import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, vgxnessOpenCodeInstructionsPath, } from './opencode-default-agent-config.js';
+import { applyVgxnessPathProfileUpdate } from './vgxness-path-environment.js';
+import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, createOpenCodeGlobalInstructionsContent, createOpenCodeGlobalInstructionsManagedBlock, vgxnessOpenCodeGlobalInstructionsBlockEnd, vgxnessOpenCodeGlobalInstructionsBlockStart, vgxnessOpenCodeInstructionsPath, } from './opencode-default-agent-config.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
 export { createInstalledVgxnessMcpServerCommand };
 function createInstalledVgxnessMcpServerCommand(databasePath, source = 'flag') {
@@ -45,8 +46,13 @@ export async function installOpenCodeMcpClient(input) {
                 return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.bashPermissionPolicy);
             return refusal('unsupported_config_shape', 'OpenCode config appeared after planning; rerun setup apply so it can be merged safely without overwriting user config.', input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
         }
+        const globalInstructions = prepareOpenCodeGlobalInstructionsWrite(plan.targetPath, plan.scope, input.env?.HOME, agentPlan);
+        if (!globalInstructions.ok)
+            return refusal('post_write_validation_failed', globalInstructions.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
         writeConfig(plan.targetPath, mergeVgxnessOpenCodeConfig({ $schema: opencodeConfigSchema }, plan.server, plan.installsAgents, input.effectiveManagerInstructions));
-        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
+        writeOpenCodeGlobalInstructions(globalInstructions.value);
+        const pathProfileUpdate = applyVgxnessPathProfileUpdate({ env: input.env });
+        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy, plan.pathEnvironment, pathProfileUpdate);
     }
     const parsed = parseConfig(plan.targetPath);
     if (!parsed.ok)
@@ -59,10 +65,15 @@ export async function installOpenCodeMcpClient(input) {
     const backup = createBackup(plan.targetPath, plan.scope, input.env?.HOME);
     if (!backup.ok)
         return refusal('post_write_validation_failed', backup.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
+    const globalInstructions = prepareOpenCodeGlobalInstructionsWrite(plan.targetPath, plan.scope, input.env?.HOME, agentPlan);
+    if (!globalInstructions.ok)
+        return refusal('post_write_validation_failed', globalInstructions.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
     const config = parsed.value;
     const mergedConfig = mergeVgxnessOpenCodeConfig({ ...config, $schema: plan.existingSchema ?? opencodeConfigSchema }, plan.server, plan.installsAgents, input.effectiveManagerInstructions);
     writeConfig(plan.targetPath, mergedConfig);
-    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
+    writeOpenCodeGlobalInstructions(globalInstructions.value);
+    const pathProfileUpdate = applyVgxnessPathProfileUpdate({ env: input.env });
+    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy, plan.pathEnvironment, pathProfileUpdate);
 }
 function mergeVgxnessOpenCodeConfig(config, server, installsAgents, effectiveManagerInstructions) {
     const merged = {
@@ -101,18 +112,72 @@ function writeConfig(path, config) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
 }
-function createBackup(path, scope, allowedManagedHome) {
+function prepareOpenCodeGlobalInstructionsWrite(opencodeConfigPath, scope, allowedManagedHome, agentPlan) {
+    const instructionsPath = join(dirname(opencodeConfigPath), vgxnessOpenCodeInstructionsPath);
+    if (!agentPlan.installsAgents)
+        return { ok: true, value: { path: instructionsPath, content: '', changed: false } };
+    const existing = existsSync(instructionsPath) ? readFileSync(instructionsPath, 'utf8') : undefined;
+    const nextContent = reconcileOpenCodeGlobalInstructions(existing);
+    if (existing === nextContent)
+        return { ok: true, value: { path: instructionsPath, content: nextContent, changed: false } };
+    if (existing !== undefined) {
+        const backup = createBackup(instructionsPath, scope, allowedManagedHome, {
+            reason: 'pre-global-instructions-merge',
+            description: 'Backup existing OpenCode global AGENTS.md before aligning VGXNESS global instructions.',
+        });
+        if (!backup.ok)
+            return backup;
+    }
+    return { ok: true, value: { path: instructionsPath, content: nextContent, changed: true } };
+}
+function writeOpenCodeGlobalInstructions(plan) {
+    if (!plan.changed)
+        return;
+    mkdirSync(dirname(plan.path), { recursive: true });
+    writeFileSync(plan.path, plan.content);
+}
+function reconcileOpenCodeGlobalInstructions(existing) {
+    const canonical = createOpenCodeGlobalInstructionsContent();
+    if (existing === undefined || existing.trim().length === 0)
+        return canonical;
+    if (looksLikeLegacyVgxnessGlobalInstructions(existing) || looksLikeUnmarkedVgxnessGlobalInstructions(existing))
+        return canonical;
+    if (existing.includes(vgxnessOpenCodeGlobalInstructionsBlockStart) || existing.includes(vgxnessOpenCodeGlobalInstructionsBlockEnd)) {
+        return replaceOpenCodeGlobalInstructionsManagedBlock(existing);
+    }
+    return `${existing.trimEnd()}\n\n${createOpenCodeGlobalInstructionsManagedBlock()}\n`;
+}
+function replaceOpenCodeGlobalInstructionsManagedBlock(existing) {
+    const start = existing.indexOf(vgxnessOpenCodeGlobalInstructionsBlockStart);
+    const end = existing.indexOf(vgxnessOpenCodeGlobalInstructionsBlockEnd);
+    const block = createOpenCodeGlobalInstructionsManagedBlock();
+    if (start < 0 || end < start)
+        return `${existing.trimEnd()}\n\n${block}\n`;
+    const afterEnd = end + vgxnessOpenCodeGlobalInstructionsBlockEnd.length;
+    return `${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(afterEnd).trimStart()}`;
+}
+function looksLikeLegacyVgxnessGlobalInstructions(content) {
+    return /^# VGXNESS Persona\b/m.test(content) || content.includes('gentle-ai:codegraph-guidance');
+}
+function looksLikeUnmarkedVgxnessGlobalInstructions(content) {
+    return (/^# Global OpenCode Instructions\b/m.test(content) &&
+        content.includes('## Instruction Layering') &&
+        content.includes('## Memory and Context Continuity') &&
+        content.includes('## VGXNESS Workflow Expectations') &&
+        content.includes('## Code Context Providers'));
+}
+function createBackup(path, scope, allowedManagedHome, override) {
     return createManagedProviderConfigBackup({
         targetPath: path,
         provider: 'opencode',
         scope,
         createdByOperation: 'mcp-client-install-opencode',
-        reason: 'pre-merge-safety',
-        description: 'Backup existing OpenCode config before merging VGXNESS MCP configuration.',
+        reason: override?.reason ?? 'pre-merge-safety',
+        description: override?.description ?? 'Backup existing OpenCode config before merging VGXNESS MCP configuration.',
         ...(allowedManagedHome !== undefined ? { allowedManagedHome } : {}),
     });
 }
-function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan)) {
+function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan), pathEnvironment, pathProfileUpdate) {
     const parsed = parseConfig(targetPath);
     if (!parsed.ok)
         return refusal('post_write_validation_failed', 'OpenCode config could not be re-read after write.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness, bashPermissionPolicy);
@@ -126,6 +191,10 @@ function validateInstalledResult(targetPath, backup, server, databasePath, sourc
         if (!isRecord(agent) || parsed.value.default_agent !== agentPlan.defaultAgent || agentPlan.agentNames.some((name) => !isRecord(agent[name]))) {
             return refusal('post_write_validation_failed', 'OpenCode config was written but VGXNESS agent entries did not validate.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness, bashPermissionPolicy);
         }
+        const instructionsPath = join(dirname(targetPath), vgxnessOpenCodeInstructionsPath);
+        if (!existsSync(instructionsPath) || !readFileSync(instructionsPath, 'utf8').includes('## Memory and Context Continuity')) {
+            return refusal('post_write_validation_failed', 'OpenCode config was written but global AGENTS.md instructions did not validate.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness, bashPermissionPolicy);
+        }
     }
     const permission = parsed.value.permission;
     if (!isRecord(permission) || permission.bash !== 'ask') {
@@ -146,6 +215,8 @@ function validateInstalledResult(targetPath, backup, server, databasePath, sourc
         agentNames: agentPlan.agentNames,
         overwriteVgxness,
         bashPermissionPolicy,
+        pathEnvironment,
+        ...(pathProfileUpdate.supported ? { pathProfileUpdate } : {}),
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }

package/dist/adapters/opencode/install/opencode-default-agent-config.js

@@ -3,6 +3,8 @@ import { projectCanonicalAgentManifestToOpenCode, withEffectiveOpenCodeManagerIn
 export const vgxnessOpenCodeDefaultAgent = canonicalDefaultAgentName;
 export const vgxnessOpenCodePromptContractVersion = canonicalPromptContractVersion;
 export const vgxnessOpenCodeInstructionsPath = 'AGENTS.md';
+export const vgxnessOpenCodeGlobalInstructionsBlockStart = '<!-- VGXNESS-GLOBAL-INSTRUCTIONS:START -->';
+export const vgxnessOpenCodeGlobalInstructionsBlockEnd = '<!-- VGXNESS-GLOBAL-INSTRUCTIONS:END -->';
 export const vgxnessOpenCodeSddSubagents = canonicalSddSubagentNames;
 export function createOpenCodeSddTaskPermissions() {
     return createCanonicalOpenCodeSddTaskPermissions();
@@ -18,3 +20,90 @@ export function createOpenCodeDefaultAgentInstallPlan(input = {}) {
 export function createOpenCodeDefaultAgentConfig(input = {}) {
     return withEffectiveOpenCodeManagerInstructions(projectCanonicalAgentManifestToOpenCode(), input.effectiveManagerInstructions);
 }
+export function createOpenCodeGlobalInstructionsContent() {
+    return `# Global OpenCode Instructions
+
+These are global instructions for OpenCode. They define user preferences, context-continuity expectations, and broad safety rules. They do not replace project \`AGENTS.md\` / \`CLAUDE.md\` files, VGXNESS-managed agent prompts, MCP instructions, or task-specific skills.
+
+## Instruction Layering
+
+- Treat this file as the user's global collaboration and safety layer.
+- Project instruction files define repository-specific commands, architecture, and conventions.
+- When the selected agent is \`vgxness-manager\`, treat its generated prompt as the operational routing/governance layer.
+- VGXNESS MCP and SQLite are the source of truth for VGXNESS state: SDD artifacts, memory, permissions, runs, setup evidence, and verification evidence.
+- OpenCode and Claude execute provider-native. VGXNESS coordinates and governs; it is not a provider runtime.
+- If layers conflict, preserve safety and user intent first, then project instructions, then VGXNESS-managed workflow rules, then this global preference layer. Report the conflict instead of guessing.
+
+## Rules
+
+- Never add \`Co-Authored-By\` or AI attribution to commits.
+- Use conventional commits unless the repository explicitly says otherwise.
+- Ask at most one focused question at a time. After asking, stop and wait.
+- Never agree with technical claims without verification. Check code, docs, config, live state, or evidence first.
+- If the user is wrong, explain why with evidence and show the correct path.
+- If you were wrong, acknowledge it clearly and explain the correction.
+- Prefer alternatives with tradeoffs when the decision has meaningful consequences.
+- Do not overwrite, revert, commit, push, publish, install, or mutate provider/global configuration unless the user explicitly requested that scope.
+- Protect user work and unrelated changes. Before editing a repo, check branch/status and avoid working directly on \`main\`/\`master\` unless the task is explicitly a local maintenance step.
+- For code changes, prefer small focused diffs and focused verification. Full gates are for release, high-risk, pre-merge, or broad cross-cutting changes.
+- For configuration changes, preserve unrelated settings, create/keep backups when available, and explain restart requirements.
+
+## Language and Tone
+
+- Respond in the same language the user uses.
+- Use a warm, professional, direct tone.
+- Act like a senior architect and teacher: practical, concept-first, and invested in the user's growth.
+- Push back when a request is risky, vague, or technically weak. Be precise, not rude.
+
+## Philosophy
+
+- CONCEPTS > CODE.
+- AI is a tool; the human leads.
+- Solid foundations before shortcuts.
+- Architecture and correctness matter more than immediacy.
+- Prefer safe, testable, reversible steps.
+
+## Memory and Context Continuity
+
+The agent must not start each interaction blind when durable context exists.
+
+- At session start, resume, or before non-trivial work, inspect relevant available context before acting: VGXNESS resume/context state, project memory, active SDD artifacts, recent runs, and relevant project instructions.
+- For VGXNESS-managed work, prefer VGXNESS MCP/SQLite context over guessing. Use available memory/resume/context tools such as \`vgxness_resume_context\`, \`vgxness_memory_search\`, \`vgxness_memory_get\`, \`vgxness_sdd_status\`, \`vgxness_sdd_get_artifact\`, and run/status tools when they are available and permitted.
+- Memory is advisory context, not proof. It can guide recall and continuity, but it does not prove acceptance, readiness, verification, authorization, or current source state. Verify against live files, git, commands, docs, or provider config before making claims.
+- Before architecture, workflow, configuration, release, or SDD decisions, search/retrieve relevant memory or SDD artifacts so the user does not need to repeat context.
+- At natural checkpoints and session end, save or update durable context when available: decisions, architecture choices, reusable conventions, environment/config gotchas, release/reinstall procedures, and active-work summaries.
+- Prefer updating an existing memory when an id/topic is known; otherwise save a compact new memory. Avoid duplicate memory spam.
+- Do not store secrets, credentials, hidden reasoning, raw transcripts, raw logs, sensitive personal data, or full SDD artifacts as ordinary memory. SDD artifacts belong in the SDD artifact store.
+- If memory conflicts with current evidence, trust current evidence and record/update the corrected durable context.
+
+## VGXNESS Workflow Expectations
+
+- Treat VGXNESS as a local-first governance OS / control plane for existing coding agents.
+- Daily implementation can happen in OpenCode or Claude provider-native; VGXNESS governs state, evidence, memory, permissions, and SDD flow.
+- Do not imply a \`vgxness code\` provider runtime unless the product explicitly adds one.
+- Human acceptance is explicit. Drafting artifacts, generating plans, or passing tests does not equal acceptance.
+- Capability subagents are optional tools for useful delegation, not mandatory for every request.
+- For small concrete requests, use direct-change routing: inspect minimal context, make the narrow change, run focused verification, and summarize evidence.
+- Use SDD for phase-shaped, large, architectural, unclear, governance-sensitive, or explicitly requested SDD work.
+- After VGXNESS/OpenCode setup changes, restart OpenCode so it reloads config.
+
+## Code Context Providers
+
+CodeGraph and Graphify are optional repository-intelligence providers. They provide advisory evidence; they are not required for every task.
+
+- Prefer VGXNESS \`code-context\` status/query surfaces when available.
+- Do not install packages, initialize indexes, write provider config, or register external MCP servers unless the user explicitly asks for that setup/mutation.
+- If a provider index is missing, report the missing index and recommended command instead of silently creating it.
+- Use code-context evidence to inform architecture, impact, debugging, tests, PR evidence, onboarding, and memory summaries, but verify conclusions against source files and tests.
+
+## Behavior
+
+- Explain the problem, then the solution, then the tradeoffs when useful.
+- Use examples when they clarify the concept.
+- Keep summaries concise but include concrete evidence: files changed, commands run, checks passed/failed, and remaining risk.
+- If blocked, say exactly what blocked progress and what decision or credential is needed next.
+`;
+}
+export function createOpenCodeGlobalInstructionsManagedBlock() {
+    return `${vgxnessOpenCodeGlobalInstructionsBlockStart}\n${createOpenCodeGlobalInstructionsContent().trimEnd()}\n${vgxnessOpenCodeGlobalInstructionsBlockEnd}`;
+}

package/dist/adapters/opencode/install/opencode-visibility.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { SUPPORTED_VGX_MCP_TOOL_NAMES } from '../../../mcp/schema.js';
 import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
+import { resolveVgxnessPathEnvironment } from './vgxness-path-environment.js';
 const serverName = 'vgxness';
 const expectedToolCount = SUPPORTED_VGX_MCP_TOOL_NAMES.length;
 export function createOpenCodeMcpVisibilityReport(options) {
@@ -17,6 +18,7 @@ export function createOpenCodeMcpVisibilityReport(options) {
     const userReport = userTarget.ok ? userVisibilityReport(userTarget.path, projectVisibleFromCurrentCwd) : undefined;
     const selectedTargetPath = userTarget.ok ? userTarget.path : '$HOME/.config/opencode/opencode.json';
     const selectedReady = targetScope === 'user' ? userReport?.configExists === true && userReport.hasVgxnessServer : projectVisibleFromCurrentCwd;
+    const pathEnvironment = resolveVgxnessPathEnvironment({ env: options.env });
     return {
         version: 1,
         kind: 'mcp-doctor-opencode-visibility',
@@ -36,6 +38,7 @@ export function createOpenCodeMcpVisibilityReport(options) {
         },
         visibility: { cwdInsideProject, configExists: projectConfigExists, hasVgxnessServer: projectHasVgxnessServer },
         expected: { serverName, toolCount: expectedToolCount, visibleFromCurrentCwd: selectedReady },
+        pathEnvironment,
         guidance: buildGuidance({
             cwdInsideProject,
             configExists: projectConfigExists,

package/dist/adapters/opencode/install/vgxness-path-environment.js

@@ -0,0 +1,186 @@
+import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { delimiter, dirname, extname, join, resolve } from 'node:path';
+export const vgxnessPathProfileBlockStart = '# >>> VGXNESS managed PATH >>>';
+export const vgxnessPathProfileBlockEnd = '# <<< VGXNESS managed PATH <<<';
+export function resolveVgxnessPathEnvironment(input) {
+    const env = input.env ?? process.env;
+    const home = homeFromEnv(env);
+    const pathEntries = splitPath(Object.hasOwn(env, 'PATH') ? env.PATH : process.env.PATH, home);
+    const bunGlobalBinPath = bunGlobalBin(env, home);
+    const vgxness = resolveCommandOnPath('vgxness', pathEntries);
+    const opencodeCli = resolveCommandOnPath('opencode', pathEntries);
+    const bunGlobalBinStatus = {
+        path: bunGlobalBinPath,
+        exists: existsSync(bunGlobalBinPath),
+        onPath: pathEntries.some((entry) => samePath(entry, bunGlobalBinPath)),
+        hasVgxnessExecutable: resolveCommandInDirectory('vgxness', bunGlobalBinPath).onPath,
+    };
+    const warnings = pathWarnings(vgxness, bunGlobalBinStatus);
+    return {
+        command: 'vgxness',
+        pathEntries,
+        vgxness,
+        opencodeCli,
+        bunGlobalBin: bunGlobalBinStatus,
+        warnings,
+        remediation: pathRemediation(vgxness, bunGlobalBinStatus, opencodeCli),
+    };
+}
+export function planVgxnessPathProfileUpdate(input) {
+    const env = input.env ?? process.env;
+    const home = homeFromEnv(env);
+    const targetBinDir = bunGlobalBin(env, home);
+    const managedBlock = createManagedPathBlock(targetBinDir, home);
+    if (home === undefined) {
+        return {
+            supported: false,
+            changed: false,
+            backupRequired: false,
+            managedBlock,
+            reason: 'HOME is not set; VGXNESS cannot safely update a shell profile PATH block.',
+            targetBinDir,
+        };
+    }
+    const profilePath = shellProfilePath(env, home);
+    const existing = existsSync(profilePath) ? readFileSync(profilePath, 'utf8') : undefined;
+    const nextContent = reconcileManagedPathBlock(existing, managedBlock);
+    const pathEnvironment = resolveVgxnessPathEnvironment({ env });
+    const blockExists = existing?.includes(vgxnessPathProfileBlockStart) === true || existing?.includes(vgxnessPathProfileBlockEnd) === true;
+    const shouldEnsureProfile = blockExists || (!pathEnvironment.vgxness.onPath && !pathEnvironment.bunGlobalBin.onPath);
+    const changed = shouldEnsureProfile && existing !== nextContent;
+    return {
+        supported: true,
+        changed,
+        backupRequired: changed && existing !== undefined,
+        managedBlock,
+        reason: changed
+            ? 'A VGXNESS-managed shell PATH block is planned so path-based OpenCode MCP command `vgxness mcp start` can resolve after restarting terminal/OpenCode.'
+            : 'No shell profile PATH update is needed for the current environment.',
+        profilePath,
+        targetBinDir,
+    };
+}
+export function applyVgxnessPathProfileUpdate(input) {
+    const plan = planVgxnessPathProfileUpdate(input);
+    if (!plan.supported || !plan.changed || plan.profilePath === undefined)
+        return plan;
+    const existing = existsSync(plan.profilePath) ? readFileSync(plan.profilePath, 'utf8') : undefined;
+    const backupPath = existing === undefined ? undefined : createProfileBackup(plan.profilePath);
+    if (backupPath !== undefined)
+        copyFileSync(plan.profilePath, backupPath);
+    mkdirSync(dirname(plan.profilePath), { recursive: true });
+    writeFileSync(plan.profilePath, reconcileManagedPathBlock(existing, plan.managedBlock));
+    return { ...plan, ...(backupPath === undefined ? {} : { backupPath }) };
+}
+function pathWarnings(vgxness, bunGlobalBinStatus) {
+    if (vgxness.onPath)
+        return [];
+    return [
+        `PATH-based OpenCode MCP command \`vgxness mcp start\` may fail because \`vgxness\` was not found on the current PATH. OpenCode may report "Executable not found in $PATH" until ${bunGlobalBinStatus.path} is on PATH.`,
+    ];
+}
+function pathRemediation(vgxness, bunGlobalBinStatus, opencodeCli) {
+    const steps = vgxness.onPath
+        ? ['`vgxness` resolves from the current PATH; keep OpenCode config path-based as `vgxness mcp start`.']
+        : [
+            'Keep OpenCode config portable as `mcp.vgxness.command: ["vgxness", "mcp", "start"]`; do not replace it with an absolute binary path by default.',
+            `Add Bun global binaries to your shell PATH, for example: export PATH="$HOME/.bun/bin:$PATH" (${bunGlobalBinStatus.path}).`,
+            'Restart terminal/OpenCode after PATH profile changes so the provider process inherits the updated PATH.',
+        ];
+    return opencodeCli.onPath
+        ? [...steps, 'After restarting, verify with `opencode mcp list` and confirm the `vgxness` server is listed.']
+        : [...steps, 'Skipped `opencode mcp list` verification because the OpenCode CLI was not found on the current PATH.'];
+}
+function createManagedPathBlock(targetBinDir, home) {
+    const pathExpression = home !== undefined && samePath(targetBinDir, join(home, '.bun', 'bin')) ? '$HOME/.bun/bin' : targetBinDir;
+    return [
+        vgxnessPathProfileBlockStart,
+        '# Ensures OpenCode can resolve the path-based VGXNESS MCP command.',
+        `export PATH="${pathExpression}:$PATH"`,
+        vgxnessPathProfileBlockEnd,
+    ].join('\n');
+}
+function reconcileManagedPathBlock(existing, managedBlock) {
+    if (existing === undefined || existing.length === 0)
+        return `${managedBlock}\n`;
+    const start = existing.indexOf(vgxnessPathProfileBlockStart);
+    const end = existing.indexOf(vgxnessPathProfileBlockEnd);
+    if (start >= 0 && end >= start) {
+        const afterEnd = end + vgxnessPathProfileBlockEnd.length;
+        return `${existing.slice(0, start).trimEnd()}\n\n${managedBlock}\n${existing.slice(afterEnd).trimStart()}`;
+    }
+    return `${existing.trimEnd()}\n\n${managedBlock}\n`;
+}
+function shellProfilePath(env, home) {
+    const explicit = env.VGXNESS_SHELL_PROFILE;
+    if (explicit !== undefined && explicit.trim().length > 0)
+        return resolve(home, explicit);
+    const shell = env.SHELL ?? '';
+    if (shell.endsWith('/zsh') || shell === 'zsh')
+        return join(home, '.zshrc');
+    if (shell.endsWith('/bash') || shell === 'bash')
+        return join(home, '.bashrc');
+    return join(home, '.profile');
+}
+function createProfileBackup(profilePath) {
+    const stamp = new Date().toISOString().replaceAll('-', '').replaceAll(':', '').replace(/\.\d{3}Z$/, 'Z');
+    return `${profilePath}.backup-${stamp}-vgxness-path`;
+}
+function bunGlobalBin(env, home) {
+    const bunInstall = env.BUN_INSTALL;
+    if (bunInstall !== undefined && bunInstall.trim().length > 0)
+        return resolve(expandHome(bunInstall, home), 'bin');
+    return home === undefined ? resolve('.bun', 'bin') : join(home, '.bun', 'bin');
+}
+function homeFromEnv(env) {
+    const home = env.HOME;
+    return home === undefined || home.trim().length === 0 ? undefined : home;
+}
+function splitPath(pathValue, home) {
+    if (pathValue === undefined || pathValue.length === 0)
+        return [];
+    return pathValue
+        .split(delimiter)
+        .filter((entry) => entry.length > 0)
+        .map((entry) => resolve(expandHome(entry, home)));
+}
+function expandHome(pathValue, home) {
+    if (home !== undefined && (pathValue === '~' || pathValue.startsWith('~/')))
+        return join(home, pathValue.slice(2));
+    return pathValue;
+}
+function resolveCommandOnPath(command, pathEntries) {
+    for (const pathEntry of pathEntries) {
+        const resolved = resolveCommandInDirectory(command, pathEntry);
+        if (resolved.onPath)
+            return resolved;
+    }
+    return { onPath: false };
+}
+function resolveCommandInDirectory(command, directory) {
+    for (const candidateName of commandCandidateNames(command)) {
+        const candidate = join(directory, candidateName);
+        if (isExecutable(candidate))
+            return { onPath: true, resolvedPath: candidate };
+    }
+    return { onPath: false };
+}
+function commandCandidateNames(command) {
+    if (process.platform !== 'win32' || extname(command).length > 0)
+        return [command];
+    return [command, `${command}.cmd`, `${command}.exe`, `${command}.bat`, `${command}.ps1`];
+}
+function isExecutable(path) {
+    try {
+        accessSync(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function samePath(left, right) {
+    const resolvedLeft = resolve(left);
+    const resolvedRight = resolve(right);
+    return process.platform === 'win32' ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase() : resolvedLeft === resolvedRight;
+}

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

@@ -22,6 +22,11 @@ function renderOpenCode(plan) {
         field('Installs agents', yesNo(plan.opencode.installsAgents)),
         field('Reinstall entries', yesNo(plan.opencode.overwriteVgxness === true)),
         field('Bash policy', formatBashPermissionPolicy(plan.opencode.bashPermissionPolicy)),
+        field('VGXNESS on PATH', yesNo(plan.opencode.pathEnvironment.vgxness.onPath)),
+        field('Bun bin on PATH', yesNo(plan.opencode.pathEnvironment.bunGlobalBin.onPath)),
+        ...(plan.opencode.pathProfileUpdate === undefined
+            ? []
+            : [field('PATH profile', `${plan.opencode.pathProfileUpdate.changed ? 'planned' : 'unchanged'} — ${plan.opencode.pathProfileUpdate.profilePath ?? 'not supported'}`)]),
         field('Agent names', plan.opencode.agentNames.length === 0 ? 'none' : plan.opencode.agentNames.join(', ')),
     ], { status });
 }

package/dist/setup/backup-rollback-service.js

@@ -263,6 +263,8 @@ function isManagedUserGlobalProviderTarget(targetPath, allowedManagedHome) {
     const home = resolveManagedHome(allowedManagedHome);
     if (targetPath === resolve(home, '.config', 'opencode', 'opencode.json'))
         return true;
+    if (targetPath === resolve(home, '.config', 'opencode', 'AGENTS.md'))
+        return true;
     if (targetPath === resolve(home, '.claude.json'))
         return true;
     if (targetPath === resolve(home, '.claude', 'CLAUDE.md'))

package/dist/setup/setup-plan.js

@@ -141,6 +141,8 @@ function setupPlanFromOpenCode(input) {
                 agentNames: input.opencode.agentNames,
                 ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
                 bashPermissionPolicy: input.opencode.bashPermissionPolicy,
+                pathEnvironment: input.opencode.pathEnvironment,
+                ...(input.opencode.pathProfileUpdate === undefined ? {} : { pathProfileUpdate: input.opencode.pathProfileUpdate }),
             },
             actions: [],
             conflicts: [
@@ -171,6 +173,8 @@ function setupPlanFromOpenCode(input) {
             agentNames: input.opencode.agentNames,
             ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
             bashPermissionPolicy: input.opencode.bashPermissionPolicy,
+            pathEnvironment: input.opencode.pathEnvironment,
+            ...(input.opencode.pathProfileUpdate === undefined ? {} : { pathProfileUpdate: input.opencode.pathProfileUpdate }),
         },
         actions: [
             {
@@ -180,18 +184,22 @@ function setupPlanFromOpenCode(input) {
                 targetPath: input.opencode.targetPath,
                 backupRequired: input.opencode.backupRequired,
             },
+            ...pathProfileUpdateActions(input.opencode.pathProfileUpdate),
         ],
         conflicts: [],
-        backupsPlanned: input.opencode.backupRequired
-            ? [
-                {
-                    targetPath: input.opencode.targetPath,
-                    reason: input.opencode.overwriteVgxness
-                        ? 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before VGXNESS entries are overwritten/reinstalled.'
-                        : 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
-                },
-            ]
-            : [],
+        backupsPlanned: [
+            ...(input.opencode.backupRequired
+                ? [
+                    {
+                        targetPath: input.opencode.targetPath,
+                        reason: input.opencode.overwriteVgxness
+                            ? 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before VGXNESS entries are overwritten/reinstalled.'
+                            : 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
+                    },
+                ]
+                : []),
+            ...pathProfileUpdateBackups(input.opencode.pathProfileUpdate),
+        ],
         nextCommands: [
             input.opencode.overwriteVgxness ? 'vgxness setup reinstall --yes' : 'vgxness setup apply --yes',
             'vgxness doctor',
@@ -202,6 +210,29 @@ function setupPlanFromOpenCode(input) {
 function bashPermissionDescription(policy) {
     return policy.manager === 'deny' ? '; sets top-level permission.bash to ask and manager bash to deny' : '; sets top-level permission.bash to ask';
 }
+function pathProfileUpdateActions(update) {
+    if (update === undefined || !update.supported || !update.changed || update.profilePath === undefined)
+        return [];
+    return [
+        {
+            id: 'opencode-path-profile-update',
+            description: `${update.reason} Target shell profile: ${update.profilePath}`,
+            mutating: false,
+            targetPath: update.profilePath,
+            backupRequired: update.backupRequired,
+        },
+    ];
+}
+function pathProfileUpdateBackups(update) {
+    if (update === undefined || !update.supported || !update.changed || !update.backupRequired || update.profilePath === undefined)
+        return [];
+    return [
+        {
+            targetPath: update.profilePath,
+            reason: 'Existing shell profile would receive a managed VGXNESS backup before updating the PATH block used by the path-based OpenCode MCP command.',
+        },
+    ];
+}
 function resolveSetupDatabase(input) {
     if (input.mode === 'global') {
         const resolved = resolveMemoryDatabasePath({ cwd: input.workspaceRoot, env: input.env });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.21.0",
+  "version": "1.21.2",
   "description": "Local-first governance OS, CLI and MCP control plane for existing coding agents, SDD, memory, runs, permissions, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {