iranti 0.2.4 → 0.2.6

package/README.md

@@ -305,6 +305,12 @@ iranti mcp
 
 Use it with a project-local `.mcp.json`, and optionally add `iranti claude-hook` for `SessionStart` and `UserPromptSubmit`.
 
+Fast path:
+
+```bash
+iranti claude-setup
+```
+
 Guide: [`docs/guides/claude-code.md`](docs/guides/claude-code.md)
 
 ### Codex via MCP
@@ -318,6 +324,12 @@ codex -C /path/to/your/project
 
 When `iranti codex-setup` is run from a project directory, it automatically captures that project's `.env.iranti` as `IRANTI_PROJECT_ENV` so Codex resolves the correct Iranti instance consistently.
 
+Alias:
+
+```bash
+iranti integrate codex
+```
+
 Guide: [`docs/guides/codex.md`](docs/guides/codex.md)
 
 ### Resolve Pending Escalations

package/dist/scripts/codex-setup.js

@@ -153,11 +153,19 @@ function canUseInstalledIranti(repoRoot) {
         return false;
     }
 }
+function ensureCodexInstalled(repoRoot) {
+    try {
+        run('codex', ['--version'], repoRoot);
+    }
+    catch {
+        throw new Error('Codex CLI is not installed or not on PATH. Install Codex first, confirm `codex --version` works, then rerun `iranti codex-setup`.');
+    }
+}
 function main() {
     const options = parseArgs(process.argv.slice(2));
     const repoRoot = findPackageRoot(__dirname);
     const mcpScript = node_path_1.default.join(repoRoot, 'dist', 'scripts', 'iranti-mcp.js');
-    run('codex', ['--version'], repoRoot);
+    ensureCodexInstalled(repoRoot);
     const useInstalled = !options.useLocalScript && canUseInstalledIranti(repoRoot);
     if (!useInstalled && !node_fs_1.default.existsSync(mcpScript)) {
         throw new Error(`Missing build artifact: ${mcpScript}. Run "npm run build" first, or install iranti globally and rerun without --local-script.`);

package/dist/scripts/iranti-cli.js

@@ -644,39 +644,95 @@ async function ensureInstanceConfigured(root, name, config) {
     });
     return { envFile, instanceDir, created };
 }
-async function writeClaudeCodeProjectFiles(projectPath) {
+function makeIrantiMcpServerConfig() {
+    return {
+        command: 'iranti',
+        args: ['mcp'],
+    };
+}
+function makeClaudeHookSettings(projectEnvPath) {
+    const hookArgs = (event) => {
+        const args = ['claude-hook', '--event', event];
+        if (projectEnvPath) {
+            args.push('--project-env', projectEnvPath);
+        }
+        return args;
+    };
+    return {
+        hooks: {
+            SessionStart: [
+                {
+                    command: 'iranti',
+                    args: hookArgs('SessionStart'),
+                },
+            ],
+            UserPromptSubmit: [
+                {
+                    command: 'iranti',
+                    args: hookArgs('UserPromptSubmit'),
+                },
+            ],
+        },
+    };
+}
+async function writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force = false) {
     const mcpFile = path_1.default.join(projectPath, '.mcp.json');
+    let mcpStatus = 'unchanged';
+    const irantiMcpServer = makeIrantiMcpServerConfig();
     if (!fs_1.default.existsSync(mcpFile)) {
         await writeText(mcpFile, `${JSON.stringify({
             mcpServers: {
-                iranti: {
-                    command: 'iranti',
-                    args: ['mcp'],
-                },
+                iranti: irantiMcpServer,
             },
         }, null, 2)}\n`);
+        mcpStatus = 'created';
+    }
+    else {
+        const existing = readJsonFile(mcpFile);
+        if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+            if (!force) {
+                throw new Error(`Existing .mcp.json is not valid JSON. Re-run with --force to overwrite it: ${mcpFile}`);
+            }
+            await writeText(mcpFile, `${JSON.stringify({
+                mcpServers: {
+                    iranti: irantiMcpServer,
+                },
+            }, null, 2)}\n`);
+            mcpStatus = 'updated';
+        }
+        else {
+            const existingServers = existing.mcpServers && typeof existing.mcpServers === 'object' && !Array.isArray(existing.mcpServers)
+                ? existing.mcpServers
+                : {};
+            const hasIranti = Object.prototype.hasOwnProperty.call(existingServers, 'iranti');
+            if (!hasIranti || force) {
+                await writeText(mcpFile, `${JSON.stringify({
+                    ...existing,
+                    mcpServers: {
+                        ...existingServers,
+                        iranti: irantiMcpServer,
+                    },
+                }, null, 2)}\n`);
+                mcpStatus = 'updated';
+            }
+        }
     }
     const claudeDir = path_1.default.join(projectPath, '.claude');
     await ensureDir(claudeDir);
     const settingsFile = path_1.default.join(claudeDir, 'settings.local.json');
+    let settingsStatus = 'unchanged';
     if (!fs_1.default.existsSync(settingsFile)) {
-        await writeText(settingsFile, `${JSON.stringify({
-            hooks: {
-                SessionStart: [
-                    {
-                        command: 'iranti',
-                        args: ['claude-hook', '--event', 'SessionStart'],
-                    },
-                ],
-                UserPromptSubmit: [
-                    {
-                        command: 'iranti',
-                        args: ['claude-hook', '--event', 'UserPromptSubmit'],
-                    },
-                ],
-            },
-        }, null, 2)}\n`);
+        await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath), null, 2)}\n`);
+        settingsStatus = 'created';
     }
+    else if (force) {
+        await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath), null, 2)}\n`);
+        settingsStatus = 'updated';
+    }
+    return {
+        mcp: mcpStatus,
+        settings: settingsStatus,
+    };
 }
 function hasCodexInstalled() {
     try {
@@ -1015,6 +1071,53 @@ function summarizeStatus(checks) {
         return 'warn';
     return 'pass';
 }
+function collectDoctorRemediations(checks, envSource, envFile) {
+    const hints = [];
+    const add = (hint) => {
+        if (!hints.includes(hint))
+            hints.push(hint);
+    };
+    for (const check of checks) {
+        if (check.name === 'node version' && check.status === 'fail') {
+            add('Upgrade Node.js to version 18 or newer, then rerun `iranti doctor`.');
+        }
+        if (check.name === 'cli build artifact' && check.status !== 'pass') {
+            add('If this is a repo checkout, run `npm run build`. If this is an installed CLI, reinstall it with `npm install -g iranti@latest`.');
+        }
+        if (check.name === 'environment file' && check.status === 'fail') {
+            if (envFile) {
+                add(`Fix or recreate the target env file at ${envFile}, or rerun \`iranti setup\`.`);
+            }
+            else {
+                add('Run `iranti setup`, or rerun `iranti doctor` with `--instance <name>` or `--env <file>`.');
+            }
+        }
+        if (check.name === 'database configuration' && check.status === 'fail') {
+            add(`Set a real DATABASE_URL in ${envFile ?? 'the target env file'}, or rerun \`iranti setup\` to configure the database again.`);
+        }
+        if (check.name === 'project binding url' && check.status === 'fail') {
+            add('Run `iranti configure project` to refresh the project binding, or set IRANTI_URL in `.env.iranti`.');
+        }
+        if (check.name === 'project api key' && check.status === 'fail') {
+            add('Run `iranti configure project` or set IRANTI_API_KEY in `.env.iranti`.');
+        }
+        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`.'
+                : 'Create or rotate an Iranti key with `iranti auth create-key`, then store it in the target env.');
+        }
+        if (check.name === 'provider credentials' && check.status === 'fail') {
+            add('Store or refresh the upstream provider key with `iranti add api-key` or `iranti update api-key`.');
+        }
+        if (check.name === 'vector backend' && check.status === 'fail') {
+            add('Check the vector backend env vars, or switch back to `IRANTI_VECTOR_BACKEND=pgvector` if the external backend is not ready.');
+        }
+    }
+    if (checks.some((check) => check.status !== 'pass')) {
+        add('Use `iranti upgrade --all --dry-run` to see whether this machine has stale CLI or Python installs.');
+    }
+    return hints;
+}
 function resolveDoctorEnvTarget(args) {
     const scope = normalizeScope(getFlag(args, 'scope'));
     const instanceName = getFlag(args, 'instance');
@@ -1139,6 +1242,32 @@ function detectGlobalNpmRoot() {
     const value = proc.stdout.trim();
     return value ? path_1.default.resolve(value) : null;
 }
+function detectGlobalNpmInstalledVersion() {
+    const proc = runCommandCapture('npm', ['list', '-g', 'iranti', '--depth=0', '--json']);
+    if (proc.status !== 0)
+        return null;
+    try {
+        const payload = JSON.parse(proc.stdout);
+        return typeof payload?.dependencies?.iranti?.version === 'string'
+            ? payload.dependencies.iranti.version
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function detectPythonInstalledVersion(command) {
+    if (!command)
+        return null;
+    const args = command.executable === 'py' ? ['-3', '-m', 'pip', 'show', 'iranti'] : ['-m', 'pip', 'show', 'iranti'];
+    const proc = runCommandCapture(command.executable, args);
+    if (proc.status !== 0)
+        return null;
+    const versionLine = proc.stdout.split(/\r?\n/).find((line) => line.toLowerCase().startsWith('version:'));
+    if (!versionLine)
+        return null;
+    return versionLine.split(':').slice(1).join(':').trim() || null;
+}
 function readJsonFile(filePath) {
     if (!fs_1.default.existsSync(filePath))
         return null;
@@ -1219,9 +1348,12 @@ function detectUpgradeContext(args) {
     const runtimeRoot = resolveInstallRoot(args, scope);
     const runtimeInstalled = fs_1.default.existsSync(path_1.default.join(runtimeRoot, 'install.json'));
     const repoCheckout = fs_1.default.existsSync(path_1.default.join(packageRootPath, '.git'));
+    const repoDirty = repoCheckout ? repoIsDirty(packageRootPath) : false;
     const globalNpmRoot = detectGlobalNpmRoot();
     const globalNpmInstall = globalNpmRoot !== null && isPathInside(globalNpmRoot, packageRootPath);
+    const globalNpmVersion = globalNpmInstall ? detectGlobalNpmInstalledVersion() : null;
     const python = detectPythonLauncher();
+    const pythonVersion = detectPythonInstalledVersion(python);
     const availableTargets = [];
     if (globalNpmInstall)
         availableTargets.push('npm-global');
@@ -1235,9 +1367,12 @@ function detectUpgradeContext(args) {
         runtimeRoot,
         runtimeInstalled,
         repoCheckout,
+        repoDirty,
         globalNpmInstall,
         globalNpmRoot,
+        globalNpmVersion,
         python,
+        pythonVersion,
         availableTargets,
     };
 }
@@ -1256,6 +1391,101 @@ function chooseUpgradeTarget(requested, context) {
         return 'python';
     return null;
 }
+function resolveRequestedUpgradeTargets(raw, all) {
+    if (all) {
+        return ['npm-global', 'npm-repo', 'python'];
+    }
+    if (!raw) {
+        return ['auto'];
+    }
+    return raw
+        .split(',')
+        .map((value) => resolveUpgradeTarget(value))
+        .filter((value, index, array) => array.indexOf(value) === index);
+}
+function buildUpgradeTargetStatuses(context, latestNpm, latestPython) {
+    return [
+        {
+            target: 'npm-global',
+            available: context.globalNpmInstall,
+            currentVersion: context.globalNpmVersion,
+            latestVersion: latestNpm,
+            upToDate: context.globalNpmVersion && latestNpm ? compareVersions(context.globalNpmVersion, latestNpm) >= 0 : null,
+            blockedReason: context.globalNpmInstall ? undefined : 'No global npm install detected on PATH.',
+        },
+        {
+            target: 'npm-repo',
+            available: context.repoCheckout,
+            currentVersion: context.currentVersion,
+            latestVersion: latestNpm,
+            upToDate: null,
+            blockedReason: !context.repoCheckout
+                ? 'Current package root is not a git checkout.'
+                : context.repoDirty
+                    ? 'Repository worktree is dirty.'
+                    : undefined,
+        },
+        {
+            target: 'python',
+            available: context.python !== null,
+            currentVersion: context.pythonVersion,
+            latestVersion: latestPython,
+            upToDate: context.pythonVersion && latestPython ? compareVersions(context.pythonVersion, latestPython) >= 0 : null,
+            blockedReason: context.python ? undefined : 'Python launcher not found.',
+        },
+    ];
+}
+function describeUpgradeTarget(target) {
+    const current = target.currentVersion ?? 'not installed';
+    const latest = target.latestVersion ?? 'unknown';
+    if (target.target === 'npm-repo') {
+        return target.blockedReason
+            ? `repo checkout (${current}) — ${target.blockedReason}`
+            : `repo checkout (${current}) — refresh local checkout and rebuild`;
+    }
+    if (target.upToDate === true) {
+        return `${target.target} (${current}) — already at latest ${latest}`;
+    }
+    if (target.blockedReason) {
+        return `${target.target} (${current}) — ${target.blockedReason}`;
+    }
+    return `${target.target} (${current}) — latest ${latest}`;
+}
+async function chooseInteractiveUpgradeTargets(statuses) {
+    const selected = [];
+    await withPromptSession(async (prompt) => {
+        for (const status of statuses) {
+            if (!status.available) {
+                console.log(`${warnLabel()} ${describeUpgradeTarget(status)}`);
+                continue;
+            }
+            if (status.target === 'npm-repo' && status.blockedReason) {
+                console.log(`${warnLabel()} ${describeUpgradeTarget(status)}`);
+                continue;
+            }
+            const defaultChoice = status.target === 'npm-repo'
+                ? false
+                : status.upToDate === false;
+            const question = status.target === 'npm-global'
+                ? `Upgrade global npm install now? (${describeUpgradeTarget(status)})`
+                : status.target === 'python'
+                    ? `Upgrade Python client now? (${describeUpgradeTarget(status)})`
+                    : `Refresh local repo checkout now? (${describeUpgradeTarget(status)})`;
+            if (await promptYesNo(prompt, question, defaultChoice)) {
+                selected.push(status.target);
+            }
+        }
+    });
+    return selected;
+}
+async function executeUpgradeTargets(targets, context) {
+    const results = [];
+    for (const target of targets) {
+        const result = await executeUpgradeTarget(target, context);
+        results.push(result);
+    }
+    return results;
+}
 function commandListForTarget(target, context) {
     if (target === 'npm-repo') {
         return repoUpgradeCommands(context.packageRootPath);
@@ -1308,17 +1538,9 @@ function verifyGlobalNpmInstall() {
     }
 }
 function verifyPythonInstall(command) {
-    const args = command.executable === 'py' ? ['-3', '-m', 'pip', 'show', 'iranti'] : ['-m', 'pip', 'show', 'iranti'];
-    const proc = runCommandCapture(command.executable, args);
-    if (proc.status !== 0) {
-        return {
-            status: 'warn',
-            detail: 'Python upgrade finished, but `pip show iranti` did not confirm the installed version.',
-        };
-    }
-    const versionLine = proc.stdout.split(/\r?\n/).find((line) => line.toLowerCase().startsWith('version:'));
-    return versionLine
-        ? { status: 'pass', detail: `Python client ${versionLine.trim()}.` }
+    const version = detectPythonInstalledVersion(command);
+    return version
+        ? { status: 'pass', detail: `Python client Version: ${version}.` }
         : { status: 'warn', detail: 'Python upgrade finished, but installed version could not be confirmed.' };
 }
 async function executeUpgradeTarget(target, context) {
@@ -1538,7 +1760,7 @@ async function setupCommand(args) {
         let finalScope = 'user';
         let finalRoot = '';
         if (setupMode === 'isolated') {
-            finalRoot = path_1.default.resolve(await promptNonEmpty(prompt, 'Runtime root folder', explicitRoot ?? path_1.default.join(process.cwd(), '.iranti-runtime')));
+            finalRoot = path_1.default.resolve(await promptNonEmpty(prompt, 'Where should the isolated runtime live', explicitRoot ?? path_1.default.join(process.cwd(), '.iranti-runtime')));
             finalScope = 'user';
         }
         else {
@@ -1574,7 +1796,7 @@ async function setupCommand(args) {
             const dbMode = (await prompt.line('How should we set up the database: existing, managed, or docker', defaultMode) ?? defaultMode).trim().toLowerCase();
             if (dbMode === 'existing' || dbMode === 'managed') {
                 while (true) {
-                    dbUrl = await promptNonEmpty(prompt, 'DATABASE_URL', existingInstance?.env.DATABASE_URL ?? `postgresql://postgres:yourpassword@localhost:5432/iranti_${instanceName}`);
+                    dbUrl = await promptNonEmpty(prompt, 'Database connection string (DATABASE_URL)', existingInstance?.env.DATABASE_URL ?? `postgresql://postgres:yourpassword@localhost:5432/iranti_${instanceName}`);
                     if (!detectPlaceholder(dbUrl))
                         break;
                     console.log(`${warnLabel()} DATABASE_URL still looks like a placeholder. Enter a real connection string before finishing setup.`);
@@ -1613,7 +1835,7 @@ async function setupCommand(args) {
         let provider = normalizeProvider(existingInstance?.env.LLM_PROVIDER ?? 'openai') ?? 'openai';
         while (true) {
             listProviderChoices(provider, existingInstance?.env ?? {});
-            const chosen = normalizeProvider(await promptNonEmpty(prompt, 'Default LLM provider', provider));
+            const chosen = normalizeProvider(await promptNonEmpty(prompt, 'Which LLM provider should Iranti use by default', provider));
             if (chosen && isSupportedProvider(chosen)) {
                 provider = chosen;
                 break;
@@ -1636,7 +1858,7 @@ async function setupCommand(args) {
             let extraProvider = provider;
             while (true) {
                 listProviderChoices(provider, { ...seedEnv, ...providerKeys });
-                const chosen = normalizeProvider(await promptNonEmpty(prompt, 'Provider to add', 'claude'));
+                const chosen = normalizeProvider(await promptNonEmpty(prompt, 'Which extra provider would you like to add', 'claude'));
                 if (!chosen) {
                     console.log(`${warnLabel()} Provider is required.`);
                     continue;
@@ -1671,10 +1893,10 @@ async function setupCommand(args) {
         const defaultProjectPath = process.cwd();
         let shouldBindProject = await promptYesNo(prompt, 'Bind a project folder to this instance now?', true);
         while (shouldBindProject) {
-            const projectPath = path_1.default.resolve(await promptNonEmpty(prompt, 'Project path', projects.length === 0 ? defaultProjectPath : process.cwd()));
-            const agentId = sanitizeIdentifier(await promptNonEmpty(prompt, 'Agent id for this project', projectAgentDefault(projectPath)), 'project_main');
-            const memoryEntity = await promptNonEmpty(prompt, 'Memory entity for this project', 'user/main');
-            const claudeCode = await promptYesNo(prompt, 'Create Claude Code project files here?', true);
+            const projectPath = path_1.default.resolve(await promptNonEmpty(prompt, 'Which project folder should we bind', projects.length === 0 ? defaultProjectPath : process.cwd()));
+            const agentId = sanitizeIdentifier(await promptNonEmpty(prompt, 'What agent id should this project use', projectAgentDefault(projectPath)), 'project_main');
+            const memoryEntity = await promptNonEmpty(prompt, 'What memory entity should this project use', 'user/main');
+            const claudeCode = await promptYesNo(prompt, 'Create Claude Code project files here now?', true);
             projects.push({
                 path: projectPath,
                 agentId,
@@ -1726,6 +1948,10 @@ async function setupCommand(args) {
     console.log(`${infoLabel()} Next steps:`);
     console.log(`  1. iranti run --instance ${finalResult.instanceName} --root "${finalResult.root}"`);
     console.log(`  2. iranti doctor --instance ${finalResult.instanceName} --root "${finalResult.root}"`);
+    if (finalResult.bindings.length > 0) {
+        console.log(`  3. cd "${finalResult.bindings[0].projectPath}"`);
+        console.log('  4. iranti chat');
+    }
 }
 async function doctorCommand(args) {
     const json = hasFlag(args, 'json');
@@ -1871,6 +2097,7 @@ async function doctorCommand(args) {
         envFile,
         status: summarizeStatus(checks),
         checks,
+        remediations: collectDoctorRemediations(checks, envSource, envFile),
     };
     if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -1892,7 +2119,14 @@ async function doctorCommand(args) {
             : check.status === 'warn'
                 ? warnLabel('WARN')
                 : failLabel('FAIL');
-        console.log(`${marker} ${check.name} — ${check.detail}`);
+        console.log(`${marker} ${check.name} — ${check.detail}`);
+    }
+    if (result.remediations.length > 0) {
+        console.log('');
+        console.log('Suggested fixes:');
+        for (const remediation of result.remediations) {
+            console.log(`  - ${remediation}`);
+        }
     }
     if (result.status !== 'pass') {
         process.exitCode = 1;
@@ -1965,46 +2199,72 @@ async function statusCommand(args) {
     }
 }
 async function upgradeCommand(args) {
+    const runAll = hasFlag(args, 'all');
     const checkOnly = hasFlag(args, 'check');
     const dryRun = hasFlag(args, 'dry-run');
     const execute = hasFlag(args, 'yes');
     const json = hasFlag(args, 'json');
-    const requestedTarget = resolveUpgradeTarget(getFlag(args, 'target'));
+    const requestedTargets = resolveRequestedUpgradeTargets(getFlag(args, 'target'), runAll);
     const context = detectUpgradeContext(args);
     const latestNpm = await fetchLatestNpmVersion();
     const latestPython = await fetchLatestPypiVersion();
-    const chosenTarget = chooseUpgradeTarget(requestedTarget, context);
+    const statuses = buildUpgradeTargetStatuses(context, latestNpm, latestPython);
+    const statusByTarget = new Map(statuses.map((status) => [status.target, status]));
+    const autoSelected = requestedTargets.includes('auto')
+        ? chooseUpgradeTarget('auto', context)
+        : null;
+    const explicitTargets = requestedTargets
+        .filter((target) => target !== 'auto');
+    for (const target of explicitTargets) {
+        const status = statusByTarget.get(target);
+        if (!runAll && !status?.available) {
+            throw new Error(`Requested target '${target}' is not available in this environment.`);
+        }
+    }
+    const selectedTargets = requestedTargets.includes('auto')
+        ? (autoSelected ? [autoSelected] : [])
+        : explicitTargets.filter((target) => {
+            const status = statusByTarget.get(target);
+            if (!status?.available)
+                return false;
+            if (runAll && status.blockedReason)
+                return false;
+            return true;
+        });
     const commands = {
         npmGlobal: 'npm install -g iranti@latest',
         npmRepo: 'git pull --ff-only && npm install && npm run build',
         python: context.python?.display ?? 'python -m pip install --upgrade iranti',
     };
     const updateAvailable = {
-        npm: latestNpm ? compareVersions(latestNpm, context.currentVersion) > 0 : null,
-        python: latestPython ? compareVersions(latestPython, context.currentVersion) > 0 : null,
+        npm: context.globalNpmVersion && latestNpm ? compareVersions(latestNpm, context.globalNpmVersion) > 0 : null,
+        python: context.pythonVersion && latestPython ? compareVersions(latestPython, context.pythonVersion) > 0 : null,
     };
-    const plan = chosenTarget ? commandListForTarget(chosenTarget, context) : [];
-    let execution = null;
+    const plan = selectedTargets.flatMap((target) => commandListForTarget(target, context).map((step) => step.display));
+    let execution = [];
     let note = null;
     if (execute) {
-        if (!chosenTarget) {
-            throw new Error('No executable upgrade path was detected. Use --target npm-global, --target npm-repo, or --target python.');
+        if (selectedTargets.length === 0) {
+            throw new Error('No executable upgrade path was detected. Use --target npm-global, --target npm-repo, --target python, or --all.');
         }
         if (dryRun || checkOnly) {
             note = 'Execution skipped because --dry-run or --check was provided.';
         }
-        else if (chosenTarget === 'npm-global' && updateAvailable.npm === false) {
-            note = 'npm global install is already at the latest published version.';
+        else {
+            execution = await executeUpgradeTargets(selectedTargets, context);
         }
-        else if (chosenTarget === 'python' && updateAvailable.python === false) {
-            note = 'Python client is already at the latest published version.';
+    }
+    else if (!checkOnly && !dryRun && !json && process.stdin.isTTY && process.stdout.isTTY) {
+        const interactiveTargets = await chooseInteractiveUpgradeTargets(statuses);
+        if (interactiveTargets.length === 0) {
+            note = 'No upgrade targets selected.';
         }
         else {
-            execution = await executeUpgradeTarget(chosenTarget, context);
+            execution = await executeUpgradeTargets(interactiveTargets, context);
         }
     }
     else if (!checkOnly && !dryRun) {
-        note = 'Run with --yes to execute the selected upgrade path. Use --check to inspect and --dry-run to print exact commands.';
+        note = 'Run with --yes to execute the selected upgrade path, or run plain `iranti upgrade` in a TTY to choose interactively.';
     }
     if (json) {
         console.log(JSON.stringify({
@@ -2018,17 +2278,21 @@ async function upgradeCommand(args) {
                 runtimeRoot: context.runtimeRoot,
                 runtimeInstalled: context.runtimeInstalled,
                 repoCheckout: context.repoCheckout,
+                repoDirty: context.repoDirty,
                 globalNpmInstall: context.globalNpmInstall,
                 globalNpmRoot: context.globalNpmRoot,
+                globalNpmVersion: context.globalNpmVersion,
                 pythonLauncher: context.python?.executable ?? null,
+                pythonVersion: context.pythonVersion,
             },
-            requestedTarget,
-            selectedTarget: chosenTarget,
+            requestedTargets,
+            selectedTargets,
             availableTargets: context.availableTargets,
+            targets: statuses,
             updateAvailable,
             commands,
-            plan: plan.map((step) => step.display),
-            action: execute && !dryRun && !checkOnly ? 'upgrade' : checkOnly ? 'check' : dryRun ? 'dry-run' : 'inspect',
+            plan,
+            action: execution.length > 0 ? 'upgrade' : checkOnly ? 'check' : dryRun ? 'dry-run' : 'inspect',
             execution,
             note,
         }, null, 2));
@@ -2040,38 +2304,43 @@ async function upgradeCommand(args) {
     console.log(`  latest_python    ${latestPython ?? '(unavailable)'}`);
     console.log(`  package_root     ${context.packageRootPath}`);
     console.log(`  runtime_root     ${context.runtimeRoot}`);
-    console.log(`  repo_checkout    ${context.repoCheckout ? paint('yes', 'green') : paint('no', 'gray')}`);
-    console.log(`  npm_global       ${context.globalNpmInstall ? paint('yes', 'green') : paint('no', 'gray')}`);
-    console.log(`  python           ${context.python?.executable ?? paint('not found', 'yellow')}`);
+    console.log(`  repo_checkout    ${context.repoCheckout ? paint('yes', 'green') : paint('no', 'gray')}${context.repoDirty ? paint(' (dirty)', 'yellow') : ''}`);
+    console.log(`  npm_global       ${context.globalNpmInstall ? paint('yes', 'green') : paint('no', 'gray')}${context.globalNpmVersion ? ` (${context.globalNpmVersion})` : ''}`);
+    console.log(`  python           ${context.python?.executable ?? paint('not found', 'yellow')}${context.pythonVersion ? ` (${context.pythonVersion})` : ''}`);
     console.log('');
-    if (chosenTarget) {
-        console.log(`  selected_target  ${paint(chosenTarget, 'cyan')}${requestedTarget === 'auto' ? paint(' (auto)', 'gray') : ''}`);
+    if (selectedTargets.length > 0) {
+        console.log(`  selected_target${selectedTargets.length > 1 ? 's' : ''} ${paint(selectedTargets.join(', '), 'cyan')}${requestedTargets.includes('auto') ? paint(' (auto)', 'gray') : ''}`);
         console.log('  plan');
         for (const step of plan) {
-            console.log(`    - ${step.display}`);
+            console.log(`    - ${step}`);
         }
     }
     else {
-        console.log(`  selected_target  ${paint('none', 'yellow')}`);
+        console.log(`  selected_targets ${paint('none', 'yellow')}`);
         console.log('  plan             No executable upgrade path detected automatically.');
     }
     console.log('');
     console.log(`  npm global       ${commands.npmGlobal}`);
     console.log(`  npm repo         ${commands.npmRepo}`);
     console.log(`  python client    ${commands.python}`);
-    if (execution) {
-        const marker = execution.verification.status === 'pass'
-            ? okLabel('PASS')
-            : execution.verification.status === 'warn'
-                ? warnLabel('WARN')
-                : failLabel('FAIL');
+    if (execution.length > 0) {
         console.log('');
-        console.log(`${okLabel()} Upgrade completed for ${execution.target}.`);
-        console.log(`${marker} ${execution.verification.detail}`);
+        for (const result of execution) {
+            const marker = result.verification.status === 'pass'
+                ? okLabel('PASS')
+                : result.verification.status === 'warn'
+                    ? warnLabel('WARN')
+                    : failLabel('FAIL');
+            console.log(`${okLabel()} Upgrade completed for ${result.target}.`);
+            console.log(`${marker} ${result.verification.detail}`);
+        }
         const { envFile } = resolveDoctorEnvTarget(args);
         if (envFile) {
             console.log(`${infoLabel()} Run \`iranti doctor\` to verify the active environment after the package upgrade.`);
         }
+        if (execution.some((result) => result.target === 'npm-global')) {
+            console.log(`${infoLabel()} If this shell started on an older global CLI, open a new terminal or rerun \`iranti upgrade --check\` to confirm the new binary is active.`);
+        }
         return;
     }
     if (note) {
@@ -2266,14 +2535,15 @@ async function configureInstanceCommand(args) {
     let clearProviderKey = hasFlag(args, 'clear-provider-key');
     if (hasFlag(args, 'interactive')) {
         await withPromptSession(async (prompt) => {
-            portRaw = await prompt.line('IRANTI_PORT', portRaw ?? env.IRANTI_PORT);
-            dbUrl = await prompt.line('DATABASE_URL', dbUrl ?? env.DATABASE_URL);
-            providerInput = await prompt.line('LLM_PROVIDER', providerInput ?? env.LLM_PROVIDER ?? 'mock');
+            portRaw = await prompt.line('Which API port should this instance use', portRaw ?? env.IRANTI_PORT);
+            dbUrl = await prompt.line('Database connection string (DATABASE_URL)', dbUrl ?? env.DATABASE_URL);
+            providerInput = await prompt.line('Which LLM provider should this instance use', providerInput ?? env.LLM_PROVIDER ?? 'mock');
             const interactiveProvider = normalizeProvider(providerInput ?? env.LLM_PROVIDER ?? 'mock');
-            if (providerKeyEnv(interactiveProvider)) {
-                providerKey = await prompt.secret(`${providerKeyEnv(interactiveProvider)}`, providerKey ?? env[providerKeyEnv(interactiveProvider)]);
+            const interactiveProviderEnvKey = providerKeyEnv(interactiveProvider);
+            if (interactiveProvider && interactiveProviderEnvKey) {
+                providerKey = await prompt.secret(`Enter the ${providerDisplayName(interactiveProvider)} API key`, providerKey ?? env[interactiveProviderEnvKey]);
             }
-            apiKey = await prompt.secret('IRANTI_API_KEY', apiKey ?? env.IRANTI_API_KEY);
+            apiKey = await prompt.secret('Iranti API key', apiKey ?? env.IRANTI_API_KEY);
         });
         clearProviderKey = false;
     }
@@ -2330,6 +2600,7 @@ async function configureInstanceCommand(args) {
     if (providerKey) {
         console.log(`  provider ${result.provider}`);
     }
+    console.log(`${infoLabel()} Next: iranti doctor --instance ${name}${scope ? ` --scope ${scope}` : ''}`);
 }
 async function configureProjectCommand(args) {
     const projectPath = path_1.default.resolve(args.positionals[0] ?? process.cwd());
@@ -2343,11 +2614,11 @@ async function configureProjectCommand(args) {
     let explicitMemoryEntity = getFlag(args, 'memory-entity');
     if (hasFlag(args, 'interactive')) {
         await withPromptSession(async (prompt) => {
-            instanceName = await prompt.line('IRANTI_INSTANCE', instanceName);
-            explicitUrl = await prompt.line('IRANTI_URL', explicitUrl ?? existing.IRANTI_URL);
-            explicitApiKey = await prompt.secret('IRANTI_API_KEY', explicitApiKey ?? existing.IRANTI_API_KEY);
-            explicitAgentId = await prompt.line('IRANTI_AGENT_ID', explicitAgentId ?? existing.IRANTI_AGENT_ID ?? 'my_agent');
-            explicitMemoryEntity = await prompt.line('IRANTI_MEMORY_ENTITY', explicitMemoryEntity ?? existing.IRANTI_MEMORY_ENTITY ?? 'user/main');
+            instanceName = await prompt.line('Which instance should this project use', instanceName);
+            explicitUrl = await prompt.line('What Iranti URL should this project talk to', explicitUrl ?? existing.IRANTI_URL);
+            explicitApiKey = await prompt.secret('What API key should this project use', explicitApiKey ?? existing.IRANTI_API_KEY);
+            explicitAgentId = await prompt.line('What agent id should this project use', explicitAgentId ?? existing.IRANTI_AGENT_ID ?? 'my_agent');
+            explicitMemoryEntity = await prompt.line('What memory entity should this project use', explicitMemoryEntity ?? existing.IRANTI_MEMORY_ENTITY ?? 'user/main');
         });
     }
     let instanceEnvFile = existing.IRANTI_INSTANCE_ENV;
@@ -2395,6 +2666,7 @@ async function configureProjectCommand(args) {
     if (updates.IRANTI_INSTANCE) {
         console.log(`  instance ${updates.IRANTI_INSTANCE}`);
     }
+    console.log(`${infoLabel()} Next: iranti doctor${updates.IRANTI_INSTANCE ? ` --instance ${updates.IRANTI_INSTANCE}` : ''}`);
 }
 async function authCreateKeyCommand(args) {
     const instanceName = getFlag(args, 'instance');
@@ -2462,6 +2734,7 @@ async function authCreateKeyCommand(args) {
     if (projectPath) {
         console.log(`  project ${path_1.default.resolve(projectPath)}`);
     }
+    console.log(`${infoLabel()} Next: iranti doctor --instance ${instanceName}`);
     process.exit(0);
 }
 async function authListKeysCommand(args) {
@@ -2519,6 +2792,151 @@ async function resolveCommand(args) {
     const escalationDir = explicitDir ? path_1.default.resolve(explicitDir) : (0, escalationPaths_1.getEscalationPaths)().root;
     await (0, resolutionist_1.resolveInteractive)(escalationDir);
 }
+function printClaudeSetupHelp() {
+    console.log([
+        'Scaffold Claude Code MCP and hook files for the current project.',
+        '',
+        'Usage:',
+        '  iranti claude-setup [path] [--project-env <path>] [--force]',
+        '  iranti claude-setup --scan <dir> [--recursive] [--force]',
+        '  iranti integrate claude [path] [--project-env <path>] [--force]',
+        '  iranti integrate claude --scan <dir> [--recursive] [--force]',
+        '',
+        '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.',
+        '  - Leaves existing Claude hook files untouched unless --force is supplied.',
+        '',
+        'Scan mode (--scan):',
+        '  - Scans immediate subdirectories of the given dir by default.',
+        '  - Add --recursive to scan nested project trees too.',
+        '  - Only scaffolds projects that already have a .claude subfolder.',
+        '  - No .env.iranti required - skips the per-project binding check.',
+        '  - Scan mode adds or merges .mcp.json and only creates hook settings when missing.',
+    ].join('\n'));
+}
+function shouldSkipRecursiveClaudeScanDir(name) {
+    if (name.startsWith('.'))
+        return true;
+    return [
+        'node_modules',
+        'dist',
+        'build',
+        'out',
+        'coverage',
+        '.next',
+        '.turbo',
+        '.cache',
+    ].includes(name);
+}
+function findClaudeProjects(scanDir, recursive) {
+    if (!recursive) {
+        return fs_1.default.readdirSync(scanDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path_1.default.join(scanDir, entry.name))
+            .filter((candidate) => fs_1.default.existsSync(path_1.default.join(candidate, '.claude')));
+    }
+    const found = new Set();
+    const queue = [scanDir];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        let entries = [];
+        try {
+            entries = fs_1.default.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (fs_1.default.existsSync(path_1.default.join(current, '.claude'))) {
+            found.add(current);
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (shouldSkipRecursiveClaudeScanDir(entry.name))
+                continue;
+            queue.push(path_1.default.join(current, entry.name));
+        }
+    }
+    found.delete(scanDir);
+    return Array.from(found).sort((a, b) => a.localeCompare(b));
+}
+async function claudeSetupCommand(args) {
+    if (hasFlag(args, 'help')) {
+        printClaudeSetupHelp();
+        return;
+    }
+    const force = hasFlag(args, 'force');
+    if (args.flags.has('scan')) {
+        const recursive = hasFlag(args, 'recursive');
+        const dirArg = getFlag(args, 'scan')
+            ?? args.positionals[0]
+            ?? (args.command === 'claude-setup' ? args.subcommand ?? undefined : undefined);
+        const scanDir = path_1.default.resolve(dirArg ?? process.cwd());
+        if (!fs_1.default.existsSync(scanDir)) {
+            throw new Error(`Scan directory not found: ${scanDir}`);
+        }
+        const candidates = findClaudeProjects(scanDir, recursive);
+        if (candidates.length === 0) {
+            console.log(`${infoLabel()} No ${recursive ? 'nested project directories' : 'subdirectories'} with a .claude folder found in ${scanDir}`);
+            return;
+        }
+        console.log(`${okLabel()} Scanning ${scanDir} - found ${candidates.length} project(s) with .claude${recursive ? ' (recursive)' : ''}`);
+        let createdMcp = 0;
+        let updatedMcp = 0;
+        let createdSettings = 0;
+        let updatedSettings = 0;
+        let unchanged = 0;
+        for (const projectPath of candidates) {
+            const result = await writeClaudeCodeProjectFiles(projectPath, undefined, force);
+            if (result.mcp === 'created')
+                createdMcp += 1;
+            if (result.mcp === 'updated')
+                updatedMcp += 1;
+            if (result.settings === 'created')
+                createdSettings += 1;
+            if (result.settings === 'updated')
+                updatedSettings += 1;
+            if (result.mcp === 'unchanged' && result.settings === 'unchanged')
+                unchanged += 1;
+            console.log(`  ${projectPath}`);
+            console.log(`    mcp       ${result.mcp}`);
+            console.log(`    settings  ${result.settings}`);
+        }
+        console.log('');
+        console.log('Summary:');
+        console.log(`  projects          ${candidates.length}`);
+        console.log(`  mcp created       ${createdMcp}`);
+        console.log(`  mcp updated       ${updatedMcp}`);
+        console.log(`  settings created  ${createdSettings}`);
+        console.log(`  settings updated  ${updatedSettings}`);
+        console.log(`  unchanged         ${unchanged}`);
+        console.log(`${infoLabel()} Done. Open each project in Claude Code to verify Iranti tools are available.`);
+        return;
+    }
+    const projectArg = args.positionals[0] ?? (args.command === 'claude-setup' ? args.subcommand ?? undefined : undefined);
+    const projectPath = path_1.default.resolve(projectArg ?? process.cwd());
+    const explicitProjectEnv = getFlag(args, 'project-env');
+    const projectEnvPath = explicitProjectEnv
+        ? path_1.default.resolve(explicitProjectEnv)
+        : path_1.default.join(projectPath, '.env.iranti');
+    if (!fs_1.default.existsSync(projectPath)) {
+        throw new Error(`Project path not found: ${projectPath}`);
+    }
+    if (!fs_1.default.existsSync(projectEnvPath)) {
+        throw new Error(`Project binding not found at ${projectEnvPath}. Run \`iranti project init\` or \`iranti configure project\` first.`);
+    }
+    const result = await writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force);
+    console.log(`${okLabel()} Claude Code integration scaffolded`);
+    console.log(`  project   ${projectPath}`);
+    console.log(`  binding   ${projectEnvPath}`);
+    console.log(`  mcp       ${path_1.default.join(projectPath, '.mcp.json')}`);
+    console.log(`  settings  ${path_1.default.join(projectPath, '.claude', 'settings.local.json')}`);
+    console.log(`  mcp status      ${result.mcp}`);
+    console.log(`  settings status ${result.settings}`);
+    console.log(`${infoLabel()} Next: open Claude Code in this project and verify Iranti tools are available.`);
+}
 async function chatCommand(args) {
     const provider = normalizeProvider(getFlag(args, 'provider'));
     if (provider && !isSupportedProvider(provider)) {
@@ -2565,14 +2983,19 @@ Project-level:
   Diagnostics:
     iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json]
     iranti status [--scope user|system] [--json]
-    iranti upgrade [--check] [--dry-run] [--yes] [--target auto|npm-global|npm-repo|python] [--json]
+    iranti upgrade [--check] [--dry-run] [--yes] [--all] [--target auto|npm-global|npm-repo|python[,python]] [--json]
     iranti chat [--agent <agent-id>] [--provider <provider>] [--model <model>]
     iranti resolve [--dir <escalation-dir>]
 
 Integrations:
   iranti mcp [--help]
+  iranti claude-setup [path] [--project-env <path>] [--force]
+  iranti claude-setup --scan <dir> [--force]
   iranti claude-hook --event SessionStart|UserPromptSubmit [--project-env <path>] [--instance-env <path>] [--env-file <path>]
   iranti codex-setup [--name iranti] [--agent codex_code] [--source Codex] [--provider openai] [--project-env <path>] [--local-script]
+  iranti integrate claude [path] [--project-env <path>] [--force]
+  iranti integrate claude --scan <dir> [--force]
+  iranti integrate codex [--name iranti] [--agent codex_code] [--source Codex] [--provider openai] [--project-env <path>] [--local-script]
   `);
 }
 async function main() {
@@ -2678,6 +3101,10 @@ async function main() {
         await handoffToScript('iranti-mcp', process.argv.slice(3));
         return;
     }
+    if (args.command === 'claude-setup') {
+        await claudeSetupCommand(args);
+        return;
+    }
     if (args.command === 'claude-hook') {
         await handoffToScript('claude-code-memory-hook', process.argv.slice(3));
         return;
@@ -2686,6 +3113,17 @@ async function main() {
         await handoffToScript('codex-setup', process.argv.slice(3));
         return;
     }
+    if (args.command === 'integrate') {
+        if (args.subcommand === 'claude') {
+            await claudeSetupCommand(args);
+            return;
+        }
+        if (args.subcommand === 'codex') {
+            await handoffToScript('codex-setup', process.argv.slice(4));
+            return;
+        }
+        throw new Error(`Unknown integrate target '${args.subcommand ?? ''}'. Use 'claude' or 'codex'.`);
+    }
     throw new Error(`Unknown command '${args.command}'. Run: iranti help`);
 }
 main().catch((err) => {

package/dist/scripts/iranti-mcp.js

@@ -144,7 +144,7 @@ async function main() {
     await ensureDefaultAgent(iranti);
     const server = new mcp_js_1.McpServer({
         name: 'iranti-mcp',
-        version: '0.2.4',
+        version: '0.2.6',
     });
     server.registerTool('iranti_handshake', {
         description: `Initialize or refresh an agent's working-memory brief for the current task.

package/dist/scripts/seed.js

@@ -15,7 +15,7 @@ const STAFF_ENTRIES = [
         entityId: 'librarian',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             rules: [
                 'All writes from external agents go through the Librarian — never directly to the database',
                 'Check for existing entries before every write',
@@ -39,7 +39,7 @@ const STAFF_ENTRIES = [
         entityId: 'attendant',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             rules: [
                 'Assigned one-per-external-agent — serve the agent, not the user',
                 'On handshake: read AGENTS.md and MCP config, query Librarian for relevant rules and task context',
@@ -61,7 +61,7 @@ const STAFF_ENTRIES = [
         entityId: 'archivist',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             rules: [
                 'Run on schedule or when conflict flags exceed threshold — not on every write',
                 'Scan for expired, low-confidence, flagged, and duplicate entries',
@@ -82,7 +82,7 @@ const STAFF_ENTRIES = [
         entityType: 'system',
         entityId: 'library',
         key: 'schema_version',
-        valueRaw: { version: '0.2.4' },
+        valueRaw: { version: '0.2.6' },
         valueSummary: 'Current Library schema version.',
         confidence: 100,
         source: 'seed',
@@ -95,7 +95,7 @@ const STAFF_ENTRIES = [
         key: 'initialization_log',
         valueRaw: {
             initializedAt: new Date().toISOString(),
-            seedVersion: '0.2.4',
+            seedVersion: '0.2.6',
         },
         valueSummary: 'Record of when and how this Library was initialized.',
         confidence: 100,
@@ -108,7 +108,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'core_schema',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             states: ['candidate', 'provisional', 'canonical'],
             coreEntityTypes: [
                 'person',
@@ -156,7 +156,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'extension_registry',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             namespaces: {
                 education: {
                     status: 'provisional',
@@ -187,7 +187,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'candidate_terms',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             terms: [],
         },
         valueSummary: 'Staging area for ontology terms detected repeatedly but not yet promoted.',
@@ -201,7 +201,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'promotion_policy',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             candidateToProvisional: {
                 minSeenCount: 3,
                 minDistinctAgents: 2,
@@ -237,7 +237,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'change_log',
         valueRaw: {
-            version: '0.2.4',
+            version: '0.2.6',
             events: [
                 {
                     at: new Date().toISOString(),

package/dist/src/api/server.js

@@ -69,7 +69,7 @@ app.use(express_1.default.json({ limit: process.env.IRANTI_MAX_BODY_BYTES ?? '25
 app.get(ROUTES.health, (_req, res) => {
     res.json({
         status: 'ok',
-        version: '0.2.4',
+        version: '0.2.6',
         provider: process.env.LLM_PROVIDER ?? 'mock',
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iranti",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Memory infrastructure for multi-agent AI systems",
   "main": "dist/src/sdk/index.js",
   "files": [