iranti 0.2.3 → 0.2.5

package/dist/scripts/iranti-cli.js

@@ -722,7 +722,7 @@ async function chooseAvailablePort(session, promptText, preferredPort, allowOccu
     let suggested = preferredPort;
     if (!allowOccupiedCurrent && !(await isPortAvailable(preferredPort))) {
         suggested = await findNextAvailablePort(preferredPort + 1);
-        console.log(`${warnLabel()} Port ${preferredPort} is already in use. Suggested port: ${suggested}`);
+        console.log(`${warnLabel()} Port ${preferredPort} is already in use. A good next option is ${suggested}.`);
     }
     while (true) {
         const raw = await promptNonEmpty(session, promptText, String(suggested));
@@ -1015,6 +1015,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 +1186,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 +1292,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 +1311,12 @@ function detectUpgradeContext(args) {
         runtimeRoot,
         runtimeInstalled,
         repoCheckout,
+        repoDirty,
         globalNpmInstall,
         globalNpmRoot,
+        globalNpmVersion,
         python,
+        pythonVersion,
         availableTargets,
     };
 }
@@ -1256,6 +1335,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 +1482,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) {
@@ -1522,13 +1688,13 @@ async function setupCommand(args) {
     const explicitScope = getFlag(args, 'scope');
     const explicitRoot = getFlag(args, 'root');
     console.log(bold('Iranti setup'));
-    console.log('This wizard will install a runtime, create or update an instance, configure provider keys, create a usable Iranti API key, and optionally bind one or more project folders.');
+    console.log('This wizard will get Iranti set up: install a runtime, create or update an instance, connect provider keys, create a usable Iranti API key, and optionally bind one or more project folders.');
     console.log('');
     let result = null;
     await withPromptSession(async (prompt) => {
         let setupMode = 'shared';
         while (true) {
-            const chosen = (await prompt.line('Setup mode: shared runtime or isolated runtime folder', 'shared') ?? 'shared').trim().toLowerCase();
+            const chosen = (await prompt.line('How should Iranti install the runtime: shared or isolated folder', 'shared') ?? 'shared').trim().toLowerCase();
             if (chosen === 'shared' || chosen === 'isolated') {
                 setupMode = chosen;
                 break;
@@ -1538,43 +1704,43 @@ 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 {
             while (true) {
-                const chosenScope = (await prompt.line('Install scope', explicitScope ?? 'user') ?? 'user').trim().toLowerCase();
+                const chosenScope = (await prompt.line('Install scope: user or system', explicitScope ?? 'user') ?? 'user').trim().toLowerCase();
                 if (chosenScope === 'user' || chosenScope === 'system') {
                     finalScope = chosenScope;
                     break;
                 }
-                console.log(`${warnLabel()} Install scope must be user or system.`);
+                console.log(`${warnLabel()} Please choose either user or system.`);
             }
             finalRoot = explicitRoot ? path_1.default.resolve(explicitRoot) : resolveInstallRoot(args, finalScope);
         }
         await ensureRuntimeInstalled(finalRoot, finalScope);
         console.log(`${okLabel()} Runtime ready at ${finalRoot}`);
-        const instanceName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Instance name', setupMode === 'isolated' ? sanitizeIdentifier(path_1.default.basename(process.cwd()), 'local') : 'local'), 'local');
+        const instanceName = sanitizeIdentifier(await promptNonEmpty(prompt, 'What should this instance be called', setupMode === 'isolated' ? sanitizeIdentifier(path_1.default.basename(process.cwd()), 'local') : 'local'), 'local');
         const existingInstance = fs_1.default.existsSync(instancePaths(finalRoot, instanceName).envFile)
             ? await loadInstanceEnv(finalRoot, instanceName)
             : null;
         if (existingInstance) {
-            console.log(`${infoLabel()} Updating existing instance '${instanceName}'.`);
+            console.log(`${infoLabel()} Found existing instance '${instanceName}'. Updating it.`);
         }
         else {
             console.log(`${infoLabel()} Creating new instance '${instanceName}'.`);
         }
         const existingPort = Number.parseInt(existingInstance?.env.IRANTI_PORT ?? '3001', 10);
-        const port = await chooseAvailablePort(prompt, 'Iranti API port', existingPort, Boolean(existingInstance));
+        const port = await chooseAvailablePort(prompt, 'Which port should the Iranti API use', existingPort, Boolean(existingInstance));
         const dockerAvailable = hasDockerInstalled();
         let dbUrl = '';
         let bootstrapDatabase = false;
         while (true) {
             const defaultMode = dockerAvailable ? 'docker' : 'existing';
-            const dbMode = (await prompt.line('Database setup mode: existing, managed, or docker', defaultMode) ?? defaultMode).trim().toLowerCase();
+            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.`);
@@ -1587,9 +1753,9 @@ async function setupCommand(args) {
                     console.log(`${warnLabel()} Docker is not installed or not on PATH. Choose existing or managed instead.`);
                     continue;
                 }
-                const dbHostPort = await chooseAvailablePort(prompt, 'Docker PostgreSQL host port', 5432, false);
-                const dbName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Docker PostgreSQL database name', `iranti_${instanceName}`), `iranti_${instanceName}`);
-                const dbPassword = await promptRequiredSecret(prompt, 'Docker PostgreSQL password');
+                const dbHostPort = await chooseAvailablePort(prompt, 'Which host port should Docker PostgreSQL use', 5432, false);
+                const dbName = sanitizeIdentifier(await promptNonEmpty(prompt, 'What should the Docker PostgreSQL database be called', `iranti_${instanceName}`), `iranti_${instanceName}`);
+                const dbPassword = await promptRequiredSecret(prompt, 'Set a password for Docker PostgreSQL');
                 const containerName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Docker container name', `iranti_${instanceName}_db`), `iranti_${instanceName}_db`);
                 dbUrl = `postgresql://postgres:${dbPassword}@localhost:${dbHostPort}/${dbName}`;
                 console.log(`${infoLabel()} Docker will be used only for PostgreSQL. Iranti itself does not require Docker once a PostgreSQL database is available.`);
@@ -1613,7 +1779,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 +1802,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 +1837,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 +1892,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 +2041,7 @@ async function doctorCommand(args) {
         envFile,
         status: summarizeStatus(checks),
         checks,
+        remediations: collectDoctorRemediations(checks, envSource, envFile),
     };
     if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -1894,6 +2065,13 @@ async function doctorCommand(args) {
                 : failLabel('FAIL');
         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 +2143,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 +2222,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 +2248,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 +2479,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 +2544,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 +2558,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 +2610,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 +2678,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) {
@@ -2565,7 +2782,7 @@ 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>]
 

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.3',
+        version: '0.2.5',
     });
     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.3',
+            version: '0.2.5',
             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.3',
+            version: '0.2.5',
             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.3',
+            version: '0.2.5',
             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.3' },
+        valueRaw: { version: '0.2.5' },
         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.3',
+            seedVersion: '0.2.5',
         },
         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.3',
+            version: '0.2.5',
             states: ['candidate', 'provisional', 'canonical'],
             coreEntityTypes: [
                 'person',
@@ -156,7 +156,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'extension_registry',
         valueRaw: {
-            version: '0.2.3',
+            version: '0.2.5',
             namespaces: {
                 education: {
                     status: 'provisional',
@@ -187,7 +187,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'candidate_terms',
         valueRaw: {
-            version: '0.2.3',
+            version: '0.2.5',
             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.3',
+            version: '0.2.5',
             candidateToProvisional: {
                 minSeenCount: 3,
                 minDistinctAgents: 2,
@@ -237,7 +237,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'change_log',
         valueRaw: {
-            version: '0.2.3',
+            version: '0.2.5',
             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.3',
+        version: '0.2.5',
         provider: process.env.LLM_PROVIDER ?? 'mock',
     });
 });

package/package.json

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