iranti 0.2.41 → 0.2.44

package/dist/scripts/codex-setup.js

@@ -75,11 +75,11 @@ function printHelp() {
         'Notes:',
         '  - Registers a global Codex MCP entry using `codex mcp add`.',
         '  - Prefers the installed CLI path: `iranti mcp`.',
-        '  - When a project binding is available, also writes or merges a project-local `.mcp.json` entry pinned to that binding.',
+        '  - When a project binding is available, also writes or merges project-local `.mcp.json` and `.vscode/mcp.json` entries pinned to that binding.',
         '  - By default does not pin IRANTI_PROJECT_ENV, so Codex can resolve .env.iranti from the active project/workspace at runtime.',
         '  - Use --project-env only when you deliberately want to pin Codex globally to one project binding.',
         '  - Use --local-script only if you need to point Codex at this repo build directly.',
-        '  - Use --no-workspace-file only if you explicitly want global registration without a project-local `.mcp.json` update.',
+        '  - Use --no-workspace-file only if you explicitly want global registration without project-local MCP file updates.',
         '  - Does not store DATABASE_URL in Codex config; iranti-mcp loads project/instance env at runtime.',
         '  - Replaces any existing MCP entry with the same name.',
     ].join('\n'));
@@ -173,6 +173,29 @@ function makeWorkspaceMcpServer(options, projectEnv) {
         env,
     };
 }
+function makeVsCodeWorkspaceMcpServer(options, projectEnv) {
+    const projectPath = node_path_1.default.dirname(projectEnv);
+    const env = {
+        IRANTI_MCP_DEFAULT_AGENT: options.agent,
+        IRANTI_MCP_DEFAULT_SOURCE: options.source,
+    };
+    if (options.provider) {
+        env.LLM_PROVIDER = options.provider;
+    }
+    const localBinding = node_path_1.default.join(projectPath, '.env.iranti');
+    if (node_path_1.default.resolve(projectEnv) !== node_path_1.default.resolve(localBinding)) {
+        env.IRANTI_PROJECT_ENV = projectEnv;
+    }
+    return {
+        type: 'stdio',
+        command: 'iranti',
+        args: ['mcp'],
+        ...(node_path_1.default.resolve(projectEnv) === node_path_1.default.resolve(localBinding)
+            ? { envFile: '${workspaceFolder}/.env.iranti' }
+            : {}),
+        env,
+    };
+}
 function writeWorkspaceMcpFile(projectEnv, options) {
     const projectPath = node_path_1.default.dirname(projectEnv);
     const mcpFile = node_path_1.default.join(projectPath, '.mcp.json');
@@ -211,6 +234,46 @@ function writeWorkspaceMcpFile(projectEnv, options) {
     }, null, 2)}\n`, 'utf8');
     return { filePath: mcpFile, status: 'updated' };
 }
+function writeWorkspaceVsCodeMcpFile(projectEnv, options) {
+    const projectPath = node_path_1.default.dirname(projectEnv);
+    const vscodeDir = node_path_1.default.join(projectPath, '.vscode');
+    const mcpFile = node_path_1.default.join(vscodeDir, 'mcp.json');
+    const nextServer = makeVsCodeWorkspaceMcpServer(options, projectEnv);
+    node_fs_1.default.mkdirSync(vscodeDir, { recursive: true });
+    if (!node_fs_1.default.existsSync(mcpFile)) {
+        node_fs_1.default.writeFileSync(mcpFile, `${JSON.stringify({
+            servers: {
+                iranti: nextServer,
+            },
+        }, null, 2)}\n`, 'utf8');
+        return { filePath: mcpFile, status: 'created' };
+    }
+    let existing;
+    try {
+        existing = JSON.parse(node_fs_1.default.readFileSync(mcpFile, 'utf8'));
+    }
+    catch {
+        throw new Error(`Existing .vscode/mcp.json is not valid JSON: ${mcpFile}`);
+    }
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+        throw new Error(`Existing .vscode/mcp.json must contain a JSON object: ${mcpFile}`);
+    }
+    const existingServers = existing.servers && typeof existing.servers === 'object' && !Array.isArray(existing.servers)
+        ? existing.servers
+        : {};
+    const currentIranti = existingServers.iranti;
+    if (JSON.stringify(currentIranti) === JSON.stringify(nextServer)) {
+        return { filePath: mcpFile, status: 'unchanged' };
+    }
+    node_fs_1.default.writeFileSync(mcpFile, `${JSON.stringify({
+        ...existing,
+        servers: {
+            ...existingServers,
+            iranti: nextServer,
+        },
+    }, null, 2)}\n`, 'utf8');
+    return { filePath: mcpFile, status: 'updated' };
+}
 function canUseInstalledIranti(repoRoot) {
     try {
         run('iranti', ['mcp', '--help'], repoRoot);
@@ -267,8 +330,11 @@ function main() {
     const workspaceProjectEnv = options.writeWorkspaceFile
         ? resolveWorkspaceProjectEnv(options)
         : undefined;
-    const workspaceMcpResult = workspaceProjectEnv
-        ? writeWorkspaceMcpFile(workspaceProjectEnv, options)
+    const workspaceFilesResult = workspaceProjectEnv
+        ? {
+            mcp: writeWorkspaceMcpFile(workspaceProjectEnv, options),
+            vscode: writeWorkspaceVsCodeMcpFile(workspaceProjectEnv, options),
+        }
         : null;
     const registered = run('codex', ['mcp', 'get', options.name], repoRoot);
     console.log(registered);
@@ -296,11 +362,12 @@ function main() {
         console.log(`Launch with: codex -C "${repoRoot}"`);
     }
     if (options.writeWorkspaceFile) {
-        if (workspaceMcpResult) {
-            console.log(`Workspace .mcp.json: ${workspaceMcpResult.status} (${workspaceMcpResult.filePath})`);
+        if (workspaceFilesResult) {
+            console.log(`Workspace .mcp.json: ${workspaceFilesResult.mcp.status} (${workspaceFilesResult.mcp.filePath})`);
+            console.log(`Workspace .vscode/mcp.json: ${workspaceFilesResult.vscode.status} (${workspaceFilesResult.vscode.filePath})`);
         }
         else {
-            console.log('Workspace .mcp.json: unchanged (no project binding found from the current working directory)');
+            console.log('Workspace MCP files: unchanged (no project binding found from the current working directory)');
         }
     }
 }

package/dist/scripts/iranti-cli.js

@@ -22,6 +22,7 @@ const commandErrors_1 = require("../src/lib/commandErrors");
 const commandInvocation_1 = require("../src/lib/commandInvocation");
 const runtimeEnv_1 = require("../src/lib/runtimeEnv");
 const fileMutation_1 = require("../src/lib/fileMutation");
+const runtimeDependencies_1 = require("../src/lib/runtimeDependencies");
 const resolutionist_1 = require("../src/resolutionist");
 const chat_1 = require("../src/chat");
 const backends_1 = require("../src/library/backends");
@@ -606,6 +607,17 @@ async function readEnvFile(filePath) {
     }
     return out;
 }
+async function readInstanceMetaFile(metaFile) {
+    if (!fs_1.default.existsSync(metaFile))
+        return null;
+    try {
+        const raw = await promises_1.default.readFile(metaFile, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
 function makeInstanceEnv(name, port, dbUrl, apiKey, instanceDir) {
     const lines = [
         '# Iranti instance env',
@@ -769,6 +781,10 @@ async function inspectInstanceConfig(root, name) {
                 if (typeof parsed.envFile === 'string' && path_1.default.resolve(parsed.envFile) !== path_1.default.resolve(envFile)) {
                     ownershipIssues.push(`instance.json envFile points to ${parsed.envFile}`);
                 }
+                const dependencyValidation = (0, runtimeDependencies_1.parseInstanceDependencies)(parsed.dependencies);
+                if (dependencyValidation.errors.length > 0) {
+                    ownershipIssues.push(`instance.json dependencies invalid: ${dependencyValidation.errors.join(', ')}`);
+                }
             }
         }
         catch {
@@ -1133,6 +1149,10 @@ function sanitizeIdentifier(input, fallback) {
     }
     return value || fallback;
 }
+function normalizeDockerContainerName(input, fallback) {
+    const trimmed = input?.trim() ?? '';
+    return trimmed || fallback;
+}
 function projectAgentDefault(projectPath) {
     return `${sanitizeIdentifier(path_1.default.basename(projectPath), 'project')}_main`;
 }
@@ -1266,6 +1286,7 @@ async function ensureInstanceConfigured(root, name, config) {
             port: config.port,
             envFile,
             instanceDir,
+            ...(config.dependencies && config.dependencies.length > 0 ? { dependencies: config.dependencies } : {}),
         };
         await writeJson(metaFile, meta);
     }
@@ -1276,7 +1297,9 @@ async function ensureInstanceConfigured(root, name, config) {
         LLM_PROVIDER: config.provider,
         ...config.providerKeys,
     });
-    await syncInstanceMeta(root, name, config.port);
+    await syncInstanceMeta(root, name, config.port, {
+        ...(config.dependencies !== undefined ? { dependencies: config.dependencies } : {}),
+    });
     return { envFile, instanceDir, created };
 }
 function makeIrantiMcpServerConfig(projectEnvPath) {
@@ -1292,6 +1315,23 @@ function makeIrantiMcpServerConfig(projectEnvPath) {
             : {}),
     };
 }
+function makeVsCodeIrantiMcpServerConfig(projectPath, projectEnvPath) {
+    const resolvedProjectEnvPath = projectEnvPath ? path_1.default.resolve(projectEnvPath) : undefined;
+    const localProjectEnvPath = path_1.default.join(projectPath, '.env.iranti');
+    const env = {};
+    if (resolvedProjectEnvPath && path_1.default.resolve(localProjectEnvPath) !== resolvedProjectEnvPath) {
+        env.IRANTI_PROJECT_ENV = resolvedProjectEnvPath;
+    }
+    return {
+        type: 'stdio',
+        command: 'iranti',
+        args: ['mcp'],
+        ...(resolvedProjectEnvPath && path_1.default.resolve(localProjectEnvPath) === resolvedProjectEnvPath
+            ? { envFile: '${workspaceFolder}/.env.iranti' }
+            : {}),
+        ...(Object.keys(env).length > 0 ? { env } : {}),
+    };
+}
 function applyEnvMap(vars) {
     for (const [key, value] of Object.entries(vars)) {
         process.env[key] = value;
@@ -1638,6 +1678,49 @@ async function writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force =
             }
         }
     }
+    const vscodeDir = path_1.default.join(projectPath, '.vscode');
+    const vscodeMcpFile = path_1.default.join(vscodeDir, 'mcp.json');
+    let vscodeMcpStatus = 'unchanged';
+    const vscodeMcpServer = makeVsCodeIrantiMcpServerConfig(projectPath, resolvedProjectEnvPath);
+    await ensureDir(vscodeDir);
+    if (!fs_1.default.existsSync(vscodeMcpFile)) {
+        await writeText(vscodeMcpFile, `${JSON.stringify({
+            servers: {
+                iranti: vscodeMcpServer,
+            },
+        }, null, 2)}\n`);
+        vscodeMcpStatus = 'created';
+    }
+    else {
+        const existing = readJsonFile(vscodeMcpFile);
+        if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+            if (!force) {
+                throw new Error(`Existing .vscode/mcp.json is not valid JSON. Re-run with --force to overwrite it: ${vscodeMcpFile}`);
+            }
+            await writeText(vscodeMcpFile, `${JSON.stringify({
+                servers: {
+                    iranti: vscodeMcpServer,
+                },
+            }, null, 2)}\n`);
+            vscodeMcpStatus = 'updated';
+        }
+        else {
+            const existingServers = existing.servers && typeof existing.servers === 'object' && !Array.isArray(existing.servers)
+                ? existing.servers
+                : {};
+            const hasIranti = Object.prototype.hasOwnProperty.call(existingServers, 'iranti');
+            if (!hasIranti || force) {
+                await writeText(vscodeMcpFile, `${JSON.stringify({
+                    ...existing,
+                    servers: {
+                        ...existingServers,
+                        iranti: vscodeMcpServer,
+                    },
+                }, null, 2)}\n`);
+                vscodeMcpStatus = 'updated';
+            }
+        }
+    }
     const claudeDir = path_1.default.join(projectPath, '.claude');
     await ensureDir(claudeDir);
     const settingsFile = path_1.default.join(claudeDir, 'settings.local.json');
@@ -1661,6 +1744,7 @@ async function writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force =
     }
     return {
         mcp: mcpStatus,
+        vscodeMcp: vscodeMcpStatus,
         settings: settingsStatus,
     };
 }
@@ -1790,26 +1874,22 @@ async function chooseAvailablePort(session, promptText, preferredPort, allowOccu
         suggested = next;
     }
 }
-async function syncInstanceMeta(root, name, port) {
+async function syncInstanceMeta(root, name, port, options = {}) {
     const { instanceDir, envFile, metaFile } = instancePaths(root, name);
-    const existingCreatedAt = fs_1.default.existsSync(metaFile)
-        ? await promises_1.default.readFile(metaFile, 'utf-8')
-            .then((raw) => {
-            try {
-                const parsed = JSON.parse(raw);
-                return typeof parsed.createdAt === 'string' ? parsed.createdAt : undefined;
-            }
-            catch {
-                return undefined;
-            }
-        })
-        : undefined;
+    const existing = await readInstanceMetaFile(metaFile);
+    const existingCreatedAt = typeof existing?.createdAt === 'string' ? existing.createdAt : undefined;
+    const existingDependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(existing?.dependencies).dependencies;
     const meta = {
         name,
         createdAt: existingCreatedAt ?? new Date().toISOString(),
         port,
         envFile,
         instanceDir,
+        ...(options.dependencies !== undefined
+            ? { dependencies: options.dependencies }
+            : existingDependencies.length > 0
+                ? { dependencies: existingDependencies }
+                : {}),
     };
     await writeJson(metaFile, meta);
 }
@@ -1915,6 +1995,7 @@ async function executeSetupPlan(plan) {
         provider: plan.provider,
         providerKeys: plan.providerKeys,
         apiKey: plan.apiKey,
+        dependencies: plan.dependencies,
     });
     if (plan.bootstrapDatabase) {
         try {
@@ -2060,6 +2141,12 @@ function parseSetupConfig(filePath) {
         codex: Boolean(raw?.codex),
         codexAgent: raw?.codexAgent ? sanitizeIdentifier(String(raw.codexAgent), 'codex_code') : undefined,
         bootstrapDatabase: Boolean(raw?.bootstrapDatabase),
+        dependencies: inferSetupDependencies({
+            databaseMode,
+            databaseUrl,
+            dockerContainerName: typeof raw?.dockerContainerName === 'string' ? raw.dockerContainerName : undefined,
+            instanceName,
+        }),
     };
 }
 function defaultsSetupPlan(args) {
@@ -2135,6 +2222,12 @@ function defaultsSetupPlan(args) {
         codex: hasFlag(args, 'codex'),
         codexAgent: sanitizeIdentifier(getFlag(args, 'codex-agent') ?? 'codex_code', 'codex_code'),
         bootstrapDatabase: hasFlag(args, 'bootstrap-db'),
+        dependencies: inferSetupDependencies({
+            databaseMode,
+            databaseUrl,
+            dockerContainerName: getFlag(args, 'docker-container-name'),
+            instanceName,
+        }),
     };
 }
 function detectProviderKey(provider, env) {
@@ -2231,6 +2324,39 @@ function summarizeStatus(checks) {
         return 'warn';
     return 'pass';
 }
+function detectVsCodeMcpWorkspaceCheck(projectEnvPath) {
+    const vscodeMcpPath = path_1.default.join(path_1.default.dirname(projectEnvPath), '.vscode', 'mcp.json');
+    if (!fs_1.default.existsSync(vscodeMcpPath)) {
+        return {
+            name: 'vscode mcp workspace',
+            status: 'warn',
+            detail: `VS Code MCP workspace file is missing: ${vscodeMcpPath}. Codex VS Code sessions may not expose Iranti tools even when Codex CLI works.`,
+        };
+    }
+    const parsed = readJsonFile(vscodeMcpPath);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            name: 'vscode mcp workspace',
+            status: 'warn',
+            detail: `.vscode/mcp.json is not valid JSON: ${vscodeMcpPath}`,
+        };
+    }
+    const servers = parsed.servers && typeof parsed.servers === 'object' && !Array.isArray(parsed.servers)
+        ? parsed.servers
+        : {};
+    if (!Object.prototype.hasOwnProperty.call(servers, 'iranti')) {
+        return {
+            name: 'vscode mcp workspace',
+            status: 'warn',
+            detail: `.vscode/mcp.json exists but does not expose an \`iranti\` server: ${vscodeMcpPath}`,
+        };
+    }
+    return {
+        name: 'vscode mcp workspace',
+        status: 'pass',
+        detail: `VS Code MCP workspace file is present and exposes \`iranti\`: ${vscodeMcpPath}`,
+    };
+}
 function collectDoctorRemediations(checks, envSource, envFile) {
     const hints = [];
     const add = (hint) => {
@@ -2269,6 +2395,9 @@ function collectDoctorRemediations(checks, envSource, envFile) {
         if (check.name === 'bound instance env' && check.status !== 'pass') {
             add('Run `iranti configure project` to refresh the project binding, or set IRANTI_INSTANCE_ENV in `.env.iranti` so doctor can inspect the bound local instance.');
         }
+        if (check.name === 'vscode mcp workspace' && check.status !== 'pass') {
+            add('Run `iranti codex-setup` from the project root to scaffold `.vscode/mcp.json`, or add an `iranti` server entry there manually for VS Code MCP clients.');
+        }
         if (check.name === 'api key' && check.status !== 'pass') {
             add(envSource === 'project-binding'
                 ? 'Set IRANTI_API_KEY in the project binding, or rerun `iranti configure project`.'
@@ -2590,6 +2719,19 @@ function deriveDatabaseUrlForMode(mode, instanceName, explicitDatabaseUrl) {
     }
     return `postgresql://${user}:${password}@localhost:5432/iranti_${instanceName}`;
 }
+function inferSetupDependencies(plan) {
+    if (plan.databaseMode !== 'docker') {
+        return [];
+    }
+    const parsed = parsePostgresConnectionString(plan.databaseUrl);
+    const hostPort = Number.parseInt(parsed.port || '5432', 10);
+    const containerName = normalizeDockerContainerName(plan.dockerContainerName, `iranti_${plan.instanceName}_db`);
+    return [{
+            kind: 'docker-container',
+            name: containerName,
+            ...(Number.isFinite(hostPort) && hostPort > 0 ? { healthTcpPort: hostPort } : {}),
+        }];
+}
 async function ensurePostgresDatabaseExists(databaseUrl) {
     const parsed = parsePostgresConnectionString(databaseUrl);
     if (!isLocalPostgresHost(parsed.hostname)) {
@@ -4292,6 +4434,12 @@ async function setupCommand(args) {
             bootstrapDatabase,
             dockerContainerName,
             databaseProvisioned,
+            dependencies: inferSetupDependencies({
+                databaseMode,
+                databaseUrl: dbUrl,
+                dockerContainerName,
+                instanceName,
+            }),
         });
     });
     if (!result) {
@@ -4469,6 +4617,7 @@ async function doctorCommand(args) {
                     status: 'pass',
                     detail: `IRANTI_URL=${env.IRANTI_URL}`,
                 });
+            checks.push(detectVsCodeMcpWorkspaceCheck(envFile));
         }
         if (treatAsProjectBinding) {
             checks.push(detectPlaceholder(env.IRANTI_API_KEY)
@@ -5068,6 +5217,8 @@ async function showInstanceCommand(args) {
     const env = config.state.envPresent && config.state.envReadable
         ? await readEnvFile(envFile)
         : {};
+    const meta = await readInstanceMetaFile(instancePaths(root, name).metaFile);
+    const dependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(meta?.dependencies).dependencies;
     const runtime = await readInstanceRuntimeSummary(root, name);
     console.log(bold(`Instance: ${name}`));
     console.log(`  dir : ${instanceDir}`);
@@ -5076,6 +5227,9 @@ async function showInstanceCommand(args) {
     console.log(`  port: ${env.IRANTI_PORT ?? '3001'}`);
     console.log(`  db  : ${env.DATABASE_URL ?? '(missing)'}`);
     console.log(`  esc : ${env.IRANTI_ESCALATION_DIR ?? '(missing)'}`);
+    if (dependencies.length > 0) {
+        console.log(`  deps: ${dependencies.map((dependency) => (0, runtimeDependencies_1.describeInstanceDependency)(dependency)).join(', ')}`);
+    }
     console.log(`  runtime: ${describeInstanceRuntime(runtime)}`);
     if (runtime.state?.healthUrl) {
         console.log(`  health: ${runtime.state.healthUrl}`);
@@ -5090,6 +5244,8 @@ async function runInstanceCommand(args) {
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
     const { instanceDir, envFile, runtimeFile, env } = await loadInstanceEnv(root, name);
+    const meta = await readInstanceMetaFile(instancePaths(root, name).metaFile);
+    const dependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(meta?.dependencies).dependencies;
     const runtime = await readInstanceRuntimeSummary(root, name);
     if (runtime.running) {
         throw cliError('IRANTI_INSTANCE_ALREADY_RUNNING', `Instance '${name}' is already running on pid ${runtime.state?.pid ?? '(unknown)'}.`, [`Run \`iranti instance restart ${name}\` to restart the live process, or stop the existing process first.`], { instance: name, pid: runtime.state?.pid ?? null, runtimeFile });
@@ -5114,6 +5270,16 @@ async function runInstanceCommand(args) {
     if (!(await isPortUsable(port, '0.0.0.0', listPublishedDockerHostPorts()))) {
         throw cliError('IRANTI_INSTANCE_PORT_IN_USE', `Cannot start instance '${name}' because port ${port} is already in use.`, ['Run `iranti configure instance <name> --port <n>` or free the port before retrying.'], { instance: name, envFile, port });
     }
+    if (dependencies.length > 0) {
+        console.log(`${infoLabel()} Ensuring instance dependencies are ready...`);
+        const ensured = await (0, runtimeDependencies_1.ensureInstanceDependenciesHealthy)(dependencies, { cwd: instanceDir });
+        if (ensured.started.length > 0) {
+            console.log(`${okLabel()} Started dependency containers: ${ensured.started.join(', ')}`);
+        }
+        if (ensured.alreadyRunning.length > 0) {
+            console.log(`${infoLabel()} Dependency containers already running: ${ensured.alreadyRunning.join(', ')}`);
+        }
+    }
     await startInstanceRuntime(name, instanceDir, envFile, runtimeFile);
 }
 async function restartInstanceCommand(args) {
@@ -5186,6 +5352,8 @@ async function configureInstanceCommand(args) {
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
     const { instanceDir, envFile, env, config } = await loadInstanceEnv(root, name, { allowRepair: true });
+    const currentMeta = await readInstanceMetaFile(instancePaths(root, name).metaFile);
+    const currentDependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(currentMeta?.dependencies).dependencies;
     const updates = {};
     let portRaw = getFlag(args, 'port');
     let dbUrl = getFlag(args, 'db-url');
@@ -5193,6 +5361,9 @@ async function configureInstanceCommand(args) {
     let providerInput = getFlag(args, 'provider');
     let providerKey = getFlag(args, 'provider-key');
     let clearProviderKey = hasFlag(args, 'clear-provider-key');
+    let dockerContainerName = getFlag(args, 'docker-container');
+    let dockerHealthPortRaw = getFlag(args, 'docker-health-port');
+    const clearDockerContainer = hasFlag(args, 'clear-docker-container');
     if (hasFlag(args, 'interactive')) {
         await withPromptSession(async (prompt) => {
             printWizardNotes('Interactive Instance Configuration', [
@@ -5201,6 +5372,7 @@ async function configureInstanceCommand(args) {
                 'DATABASE_URL points at the PostgreSQL database for this instance.',
                 'LLM provider and provider key control which model backend Iranti uses.',
                 'Iranti API key is the client credential other tools and project bindings use to authenticate.',
+                'Optional Docker dependency settings let `iranti run --instance` start a recorded backing container before the API boots.',
             ]);
             portRaw = await prompt.line('API port', portRaw ?? env.IRANTI_PORT);
             dbUrl = await prompt.line('DATABASE_URL', dbUrl ?? env.DATABASE_URL);
@@ -5211,6 +5383,9 @@ async function configureInstanceCommand(args) {
                 providerKey = await prompt.secret(`${providerDisplayName(interactiveProvider)} API key`, providerKey ?? env[interactiveProviderEnvKey]);
             }
             apiKey = await prompt.secret('Iranti API key', apiKey ?? env.IRANTI_API_KEY);
+            const currentDockerDependency = currentDependencies.find((dependency) => dependency.kind === 'docker-container');
+            dockerContainerName = await prompt.line('Docker dependency container (optional)', dockerContainerName ?? currentDockerDependency?.name);
+            dockerHealthPortRaw = await prompt.line('Docker dependency health TCP port (optional)', dockerHealthPortRaw ?? (currentDockerDependency?.healthTcpPort ? String(currentDockerDependency.healthTcpPort) : ''));
         });
         clearProviderKey = false;
     }
@@ -5242,8 +5417,42 @@ async function configureInstanceCommand(args) {
         }
         updates[envKey] = undefined;
     }
+    let nextDependencies = currentDependencies;
+    if (clearDockerContainer) {
+        nextDependencies = currentDependencies.filter((dependency) => dependency.kind !== 'docker-container');
+    }
+    if (dockerHealthPortRaw && !dockerContainerName) {
+        throw new Error('--docker-health-port requires --docker-container <name>.');
+    }
+    if (dockerContainerName) {
+        const normalizedName = normalizeDockerContainerName(dockerContainerName, 'iranti_db');
+        const dockerHealthPortCandidate = dockerHealthPortRaw
+            ? Number.parseInt(dockerHealthPortRaw, 10)
+            : undefined;
+        if (dockerHealthPortRaw
+            && (dockerHealthPortCandidate === undefined
+                || !Number.isFinite(dockerHealthPortCandidate)
+                || dockerHealthPortCandidate <= 0)) {
+            throw new Error(`Invalid --docker-health-port '${dockerHealthPortRaw}'.`);
+        }
+        const dockerHealthPort = typeof dockerHealthPortCandidate === 'number' && dockerHealthPortCandidate > 0
+            ? dockerHealthPortCandidate
+            : undefined;
+        const withoutDocker = currentDependencies.filter((dependency) => dependency.kind !== 'docker-container');
+        nextDependencies = [
+            ...withoutDocker,
+            {
+                kind: 'docker-container',
+                name: normalizedName,
+                ...(dockerHealthPort ? { healthTcpPort: dockerHealthPort } : {}),
+            },
+        ];
+    }
     if (Object.keys(updates).length === 0) {
-        throw new Error('No changes provided. Use flags like --provider, --provider-key, --api-key, --db-url, or --port.');
+        const dependenciesUnchanged = JSON.stringify(nextDependencies) === JSON.stringify(currentDependencies);
+        if (dependenciesUnchanged) {
+            throw new Error('No changes provided. Use flags like --provider, --provider-key, --api-key, --db-url, --port, or the Docker dependency flags.');
+        }
     }
     const nextEnv = { ...env };
     for (const [key, value] of Object.entries(updates)) {
@@ -5264,7 +5473,7 @@ async function configureInstanceCommand(args) {
     }
     await ensureDir(instanceDir);
     await upsertEnvFile(envFile, updates);
-    await syncInstanceMeta(root, name, nextPort);
+    await syncInstanceMeta(root, name, nextPort, { dependencies: nextDependencies });
     const json = hasFlag(args, 'json');
     const result = {
         instance: name,
@@ -5273,6 +5482,7 @@ async function configureInstanceCommand(args) {
         provider: updates.LLM_PROVIDER ?? env.LLM_PROVIDER ?? 'mock',
         apiKeyChanged: Boolean(apiKey),
         providerKeyChanged: Boolean(providerKey) || hasFlag(args, 'clear-provider-key'),
+        dependencies: nextDependencies.map((dependency) => (0, runtimeDependencies_1.describeInstanceDependency)(dependency)),
     };
     if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -5282,6 +5492,9 @@ async function configureInstanceCommand(args) {
     console.log(`  status   ${okLabel()}`);
     console.log(`  env      ${envFile}`);
     console.log(`  keys     ${result.updatedKeys.join(', ')}`);
+    if (result.dependencies.length > 0) {
+        console.log(`  deps     ${result.dependencies.join(', ')}`);
+    }
     if (apiKey) {
         console.log(`  api key  ${redactSecret(apiKey)}`);
     }
@@ -5685,7 +5898,7 @@ async function handoffCommand(args) {
 function printClaudeSetupHelp() {
     console.log([
         'Scaffold Claude Code MCP and hook files for the current project.',
-        'Use this when a bound repo should be ready for Claude Code without hand-editing `.mcp.json` or `.claude/settings.local.json`.',
+        'Use this when a bound repo should be ready for Claude Code without hand-editing `.mcp.json`, `.vscode/mcp.json`, or `.claude/settings.local.json`.',
         '',
         'Usage:',
         '  iranti claude-setup [path] [--project-env <path>] [--force]',
@@ -5699,8 +5912,8 @@ function printClaudeSetupHelp() {
         '',
         'Notes:',
         '  - Expects a project binding at .env.iranti unless --project-env is supplied.',
-        '  - Writes .mcp.json and .claude/settings.local.json.',
-        '  - Adds the Iranti MCP server to existing .mcp.json files without removing other servers.',
+        '  - Writes .mcp.json, .vscode/mcp.json, and .claude/settings.local.json.',
+        '  - Adds the Iranti MCP server to existing .mcp.json / .vscode/mcp.json files without removing other servers.',
         '  - Leaves existing Claude hook files untouched unless --force is supplied.',
         '',
         'Scan mode (--scan):',
@@ -5870,6 +6083,8 @@ async function claudeSetupCommand(args) {
         console.log(`${okLabel()} Scanning ${scanDir} - found ${candidates.length} project(s) with .claude${recursive ? ' (recursive)' : ''}`);
         let createdMcp = 0;
         let updatedMcp = 0;
+        let createdVsCodeMcp = 0;
+        let updatedVsCodeMcp = 0;
         let createdSettings = 0;
         let updatedSettings = 0;
         let unchanged = 0;
@@ -5879,14 +6094,19 @@ async function claudeSetupCommand(args) {
                 createdMcp += 1;
             if (result.mcp === 'updated')
                 updatedMcp += 1;
+            if (result.vscodeMcp === 'created')
+                createdVsCodeMcp += 1;
+            if (result.vscodeMcp === 'updated')
+                updatedVsCodeMcp += 1;
             if (result.settings === 'created')
                 createdSettings += 1;
             if (result.settings === 'updated')
                 updatedSettings += 1;
-            if (result.mcp === 'unchanged' && result.settings === 'unchanged')
+            if (result.mcp === 'unchanged' && result.vscodeMcp === 'unchanged' && result.settings === 'unchanged')
                 unchanged += 1;
             console.log(`  ${projectPath}`);
             console.log(`    mcp       ${result.mcp}`);
+            console.log(`    vscode    ${result.vscodeMcp}`);
             console.log(`    settings  ${result.settings}`);
         }
         console.log('');
@@ -5894,6 +6114,8 @@ async function claudeSetupCommand(args) {
         console.log(`  projects          ${candidates.length}`);
         console.log(`  mcp created       ${createdMcp}`);
         console.log(`  mcp updated       ${updatedMcp}`);
+        console.log(`  vscode created    ${createdVsCodeMcp}`);
+        console.log(`  vscode updated    ${updatedVsCodeMcp}`);
         console.log(`  settings created  ${createdSettings}`);
         console.log(`  settings updated  ${updatedSettings}`);
         console.log(`  unchanged         ${unchanged}`);
@@ -5917,8 +6139,10 @@ async function claudeSetupCommand(args) {
     console.log(`  project   ${projectPath}`);
     console.log(`  binding   ${projectEnvPath}`);
     console.log(`  mcp       ${path_1.default.join(projectPath, '.mcp.json')}`);
+    console.log(`  vscode    ${path_1.default.join(projectPath, '.vscode', 'mcp.json')}`);
     console.log(`  settings  ${path_1.default.join(projectPath, '.claude', 'settings.local.json')}`);
     console.log(`  mcp status      ${result.mcp}`);
+    console.log(`  vscode status   ${result.vscodeMcp}`);
     console.log(`  settings status ${result.settings}`);
     console.log(`${infoLabel()} Next: open Claude Code in this project and verify Iranti tools are available.`);
 }