iranti 0.2.10 → 0.2.12

package/README.md

@@ -245,6 +245,14 @@ iranti run --instance local
 
 If local PostgreSQL is available, setup can bootstrap a localhost database for you. If local PostgreSQL is not available, setup recommends Docker when Docker is installed, and otherwise steers you to managed PostgreSQL with concrete install guidance.
 
+If something still fails and you need more detail, use:
+
+```bash
+iranti doctor --debug
+iranti run --instance local --debug
+iranti upgrade --verbose
+```
+
 Advanced/manual path:
 
 ```bash

package/dist/scripts/iranti-cli.js

@@ -21,6 +21,15 @@ const resolutionist_1 = require("../src/resolutionist");
 const chat_1 = require("../src/chat");
 const backends_1 = require("../src/library/backends");
 const sdk_1 = require("../src/sdk");
+class CliError extends Error {
+    constructor(code, message, hints = [], details) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.hints = hints;
+        this.details = details;
+    }
+}
 const PROVIDER_ENV_KEYS = {
     mock: null,
     ollama: null,
@@ -43,6 +52,8 @@ const ANSI = {
     cyan: '\x1b[36m',
     gray: '\x1b[90m',
 };
+let CLI_DEBUG = process.argv.includes('--debug') || process.env.IRANTI_DEBUG === '1';
+let CLI_VERBOSE = CLI_DEBUG || process.argv.includes('--verbose') || process.env.IRANTI_VERBOSE === '1';
 function useColor() {
     return Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
 }
@@ -81,6 +92,25 @@ function printNextSteps(steps) {
         console.log(`  ${index + 1}. ${step}`);
     }
 }
+function setCliDebugFlags(args) {
+    CLI_DEBUG = CLI_DEBUG || hasFlag(args, 'debug');
+    CLI_VERBOSE = CLI_VERBOSE || CLI_DEBUG || hasFlag(args, 'verbose');
+}
+function debugLog(message, details) {
+    if (!CLI_DEBUG)
+        return;
+    const suffix = details && Object.keys(details).length > 0 ? ` ${JSON.stringify(details)}` : '';
+    console.log(`${paint('[DEBUG]', 'gray')} ${message}${suffix}`);
+}
+function verboseLog(message, details) {
+    if (!CLI_VERBOSE)
+        return;
+    const suffix = details && Object.keys(details).length > 0 ? ` ${JSON.stringify(details)}` : '';
+    console.log(`${paint('[TRACE]', 'gray')} ${message}${suffix}`);
+}
+function cliError(code, message, hints = [], details) {
+    return new CliError(code, message, hints, details);
+}
 function parseArgs(argv) {
     const flags = new Map();
     const positionals = [];
@@ -197,6 +227,7 @@ function formatSetupBootstrapFailure(error) {
 }
 async function handoffToScript(scriptName, rawArgs) {
     const builtPath = builtScriptPath(scriptName);
+    debugLog('Handing off to companion script.', { scriptName, builtPath, rawArgs: rawArgs.join(' ') });
     if (fs_1.default.existsSync(builtPath)) {
         await new Promise((resolve, reject) => {
             const child = (0, child_process_1.spawn)(process.execPath, [builtPath, ...rawArgs], {
@@ -219,7 +250,7 @@ async function handoffToScript(scriptName, rawArgs) {
     }
     const sourcePath = path_1.default.resolve(process.cwd(), 'scripts', `${scriptName}.ts`);
     if (!fs_1.default.existsSync(sourcePath)) {
-        throw new Error(`Unable to locate ${scriptName} implementation.`);
+        throw cliError('IRANTI_SCRIPT_NOT_FOUND', `Unable to locate ${scriptName} implementation.`, ['Run from an installed Iranti package or from the Iranti repo root where scripts/ exists.'], { scriptName, sourcePath, builtPath });
     }
     await new Promise((resolve, reject) => {
         const child = (0, child_process_1.spawn)('npx', ['ts-node', sourcePath, ...rawArgs], {
@@ -428,8 +459,12 @@ function instancePaths(root, name) {
 async function loadInstanceEnv(root, name) {
     const paths = instancePaths(root, name);
     if (!fs_1.default.existsSync(paths.envFile)) {
-        throw new Error(`Instance '${name}' not found at ${paths.instanceDir}`);
+        throw cliError('IRANTI_INSTANCE_NOT_FOUND', `Instance '${name}' not found at ${paths.instanceDir}`, [
+            'Run `iranti instance list` to see known instances.',
+            `Run \`iranti setup\` or \`iranti instance create ${name}\` if this instance does not exist yet.`,
+        ], { instance: name, root, instanceDir: paths.instanceDir });
     }
+    debugLog('Loaded instance env target.', { instance: name, envFile: paths.envFile });
     return {
         ...paths,
         env: await readEnvFile(paths.envFile),
@@ -451,15 +486,15 @@ async function resolveProviderKeyTarget(args) {
     const projectPath = path_1.default.resolve(getFlag(args, 'project') ?? process.cwd());
     const bindingFile = path_1.default.join(projectPath, '.env.iranti');
     if (!fs_1.default.existsSync(bindingFile)) {
-        throw new Error('No --instance provided and no .env.iranti found in the current project. Run from a bound project or pass --instance <name>.');
+        throw cliError('IRANTI_PROJECT_BINDING_MISSING', 'No --instance provided and no .env.iranti found in the current project.', ['Run `iranti project init . --instance <name>` or pass `--instance <name>`.'], { projectPath, bindingFile });
     }
     const binding = await readEnvFile(bindingFile);
     const envFile = binding.IRANTI_INSTANCE_ENV?.trim();
     if (!envFile) {
-        throw new Error(`Project binding is missing IRANTI_INSTANCE_ENV: ${bindingFile}`);
+        throw cliError('IRANTI_BINDING_INSTANCE_ENV_MISSING', `Project binding is missing IRANTI_INSTANCE_ENV: ${bindingFile}`, ['Run `iranti configure project` to refresh the binding.'], { bindingFile });
     }
     if (!fs_1.default.existsSync(envFile)) {
-        throw new Error(`Instance env referenced by project binding was not found: ${envFile}`);
+        throw cliError('IRANTI_BINDING_INSTANCE_ENV_NOT_FOUND', `Instance env referenced by project binding was not found: ${envFile}`, ['Run `iranti configure project` to refresh the binding or recreate the target instance.'], { bindingFile, envFile });
     }
     return {
         instanceName: binding.IRANTI_INSTANCE?.trim() || undefined,
@@ -707,7 +742,7 @@ function isSupportedProvider(provider) {
 async function promptYesNo(session, prompt, defaultValue) {
     const defaultToken = defaultValue ? 'Y/n' : 'y/N';
     while (true) {
-        const answer = (await session.line(`${prompt} (${defaultToken})`, '') ?? '').trim().toLowerCase();
+        const answer = (await session.line(`${prompt} (${defaultToken})`) ?? '').trim().toLowerCase();
         if (!answer)
             return defaultValue;
         if (['y', 'yes'].includes(answer))
@@ -730,7 +765,7 @@ async function promptRequiredSecret(session, prompt, currentValue) {
         const value = (await session.secretRequired(prompt, currentValue) ?? '').trim();
         if (value.length > 0 && !detectPlaceholder(value))
             return value;
-        console.log(`${warnLabel()} A real secret is required.`);
+        console.log(`${warnLabel()} ${prompt} is required.`);
     }
 }
 function makeLegacyInstanceApiKey(instanceName) {
@@ -1466,8 +1501,13 @@ function collectDoctorRemediations(checks, envSource, envFile) {
                 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 === 'database configuration' || check.name === 'bound instance database configuration') && check.status === 'fail') {
+            if (check.name === 'bound instance database configuration') {
+                add('Fix the linked instance env, or rerun `iranti setup` / `iranti configure instance` for the bound instance.');
+            }
+            else {
+                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`.');
@@ -1475,15 +1515,18 @@ function collectDoctorRemediations(checks, envSource, envFile) {
         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 === '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 === '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') {
+        if ((check.name === 'provider credentials' || check.name === 'bound instance 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') {
+        if ((check.name === 'vector backend' || check.name === 'bound instance 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.');
         }
     }
@@ -1498,6 +1541,7 @@ function resolveDoctorEnvTarget(args) {
     const explicitEnv = getFlag(args, 'env');
     const cwd = process.cwd();
     if (explicitEnv) {
+        debugLog('Doctor target resolved from explicit env.', { envFile: path_1.default.resolve(explicitEnv) });
         return {
             envFile: path_1.default.resolve(explicitEnv),
             envSource: 'explicit-env',
@@ -1505,6 +1549,7 @@ function resolveDoctorEnvTarget(args) {
     }
     if (instanceName) {
         const root = resolveInstallRoot(args, scope);
+        debugLog('Doctor target resolved from instance.', { instance: instanceName, root });
         return {
             envFile: path_1.default.join(root, 'instances', instanceName, '.env'),
             envSource: `instance:${instanceName}`,
@@ -1513,11 +1558,14 @@ function resolveDoctorEnvTarget(args) {
     const repoEnv = path_1.default.join(cwd, '.env');
     const projectEnv = path_1.default.join(cwd, '.env.iranti');
     if (fs_1.default.existsSync(repoEnv)) {
+        debugLog('Doctor target resolved from repo env.', { envFile: repoEnv });
         return { envFile: repoEnv, envSource: 'repo' };
     }
     if (fs_1.default.existsSync(projectEnv)) {
+        debugLog('Doctor target resolved from project binding.', { envFile: projectEnv });
         return { envFile: projectEnv, envSource: 'project-binding' };
     }
+    debugLog('Doctor target resolution found no env file.', { cwd });
     return { envFile: null, envSource: 'repo' };
 }
 function resolveUpgradeTarget(raw) {
@@ -1638,6 +1686,11 @@ function quoteForCmd(arg) {
     return `"${arg.replace(/"/g, '\\"')}"`;
 }
 function runCommandCapture(executable, args, cwd, extraEnv) {
+    verboseLog('Running subprocess (capture).', {
+        executable,
+        args: args.join(' '),
+        cwd: cwd ?? process.cwd(),
+    });
     const proc = process.platform === 'win32'
         ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', [
             '/d',
@@ -1661,13 +1714,24 @@ function runCommandCapture(executable, args, cwd, extraEnv) {
                 ...extraEnv,
             },
         });
-    return {
+    const result = {
         status: proc.status,
         stdout: proc.stdout ?? '',
         stderr: proc.stderr ?? '',
     };
+    verboseLog('Subprocess finished (capture).', {
+        executable,
+        status: result.status ?? -1,
+        stderr: result.stderr.trim() || null,
+    });
+    return result;
 }
 function runCommandInteractive(step) {
+    verboseLog('Running subprocess (interactive).', {
+        label: step.label,
+        command: step.display,
+        cwd: step.cwd ?? process.cwd(),
+    });
     const proc = process.platform === 'win32'
         ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', [
             '/d',
@@ -1681,6 +1745,10 @@ function runCommandInteractive(step) {
             cwd: step.cwd,
             stdio: 'inherit',
         });
+    verboseLog('Subprocess finished (interactive).', {
+        label: step.label,
+        status: proc.status ?? -1,
+    });
     return proc.status;
 }
 function deriveDatabaseUrlForMode(mode, instanceName, explicitDatabaseUrl) {
@@ -2341,7 +2409,7 @@ async function setupCommand(args) {
     await withPromptSession(async (prompt) => {
         let setupMode = 'isolated';
         while (true) {
-            const chosen = (await prompt.line('How should Iranti install the runtime: isolated per-project or shared machine runtime', 'isolated') ?? 'isolated').trim().toLowerCase();
+            const chosen = (await prompt.line('Runtime mode (isolated or shared)', 'isolated') ?? 'isolated').trim().toLowerCase();
             if (chosen === 'shared' || chosen === 'isolated') {
                 setupMode = chosen;
                 break;
@@ -2351,12 +2419,12 @@ async function setupCommand(args) {
         let finalScope = 'user';
         let finalRoot = '';
         if (setupMode === 'isolated') {
-            finalRoot = path_1.default.resolve(await promptNonEmpty(prompt, 'Where should the isolated runtime live', explicitRoot ?? path_1.default.join(process.cwd(), '.iranti-runtime')));
+            finalRoot = path_1.default.resolve(await promptNonEmpty(prompt, 'Isolated runtime path', explicitRoot ?? path_1.default.join(process.cwd(), '.iranti-runtime')));
             finalScope = 'user';
         }
         else {
             while (true) {
-                const chosenScope = (await prompt.line('Install scope: user or system', 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;
@@ -2367,7 +2435,7 @@ async function setupCommand(args) {
         }
         await ensureRuntimeInstalled(finalRoot, finalScope);
         console.log(`${okLabel()} Runtime ready at ${finalRoot}`);
-        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 instanceName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Instance name', 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;
@@ -2378,7 +2446,7 @@ async function setupCommand(args) {
             console.log(`${infoLabel()} Creating new instance '${instanceName}'.`);
         }
         const existingPort = Number.parseInt(existingInstance?.env.IRANTI_PORT ?? '3001', 10);
-        const port = await chooseAvailablePort(prompt, 'Which port should the Iranti API use', existingPort, Boolean(existingInstance));
+        const port = await chooseAvailablePort(prompt, 'API port', existingPort, Boolean(existingInstance));
         const dockerAvailable = hasDockerInstalled();
         const psqlAvailable = hasCommandInstalled('psql');
         let dbUrl = '';
@@ -2386,14 +2454,14 @@ async function setupCommand(args) {
         let databaseMode = recommendedDatabaseMode;
         while (true) {
             const defaultMode = recommendedDatabaseMode;
-            const dbMode = (await prompt.line('How should we set up the database: local, managed, or docker', defaultMode) ?? defaultMode).trim().toLowerCase();
+            const dbMode = (await prompt.line('Database mode (local, managed, or docker)', defaultMode) ?? defaultMode).trim().toLowerCase();
             if (dbMode === 'existing' || dbMode === 'local' || dbMode === 'managed') {
                 databaseMode = dbMode === 'existing' ? 'local' : dbMode;
                 const defaultDatabaseUrl = databaseMode === 'local'
                     ? existingInstance?.env.DATABASE_URL ?? deriveDatabaseUrlForMode('local', instanceName)
                     : existingInstance?.env.DATABASE_URL ?? '';
                 while (true) {
-                    dbUrl = await promptNonEmpty(prompt, 'Database connection string (DATABASE_URL)', defaultDatabaseUrl);
+                    dbUrl = await promptNonEmpty(prompt, 'DATABASE_URL', defaultDatabaseUrl);
                     if (!detectPlaceholder(dbUrl))
                         break;
                     console.log(`${warnLabel()} DATABASE_URL still looks like a placeholder. Enter a real connection string before finishing setup.`);
@@ -2415,9 +2483,9 @@ async function setupCommand(args) {
                     console.log(`${warnLabel()} Docker is not installed or not on PATH. Choose local or managed instead.`);
                     continue;
                 }
-                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 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 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.`);
@@ -2441,7 +2509,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, 'Which LLM provider should Iranti use by default', provider));
+            const chosen = normalizeProvider(await promptNonEmpty(prompt, 'Default LLM provider', provider));
             if (chosen && isSupportedProvider(chosen)) {
                 provider = chosen;
                 break;
@@ -2464,7 +2532,7 @@ async function setupCommand(args) {
             let extraProvider = provider;
             while (true) {
                 listProviderChoices(provider, { ...seedEnv, ...providerKeys });
-                const chosen = normalizeProvider(await promptNonEmpty(prompt, 'Which extra provider would you like to add', 'claude'));
+                const chosen = normalizeProvider(await promptNonEmpty(prompt, 'Additional provider', 'claude'));
                 if (!chosen) {
                     console.log(`${warnLabel()} Provider is required.`);
                     continue;
@@ -2499,9 +2567,9 @@ 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, '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 projectPath = path_1.default.resolve(await promptNonEmpty(prompt, 'Project path to bind', projects.length === 0 ? defaultProjectPath : process.cwd()));
+            const agentId = sanitizeIdentifier(await promptNonEmpty(prompt, 'Project agent ID', projectAgentDefault(projectPath)), 'project_main');
+            const memoryEntity = await promptNonEmpty(prompt, 'Project memory entity', 'user/main');
             const claudeCode = await promptYesNo(prompt, 'Create Claude Code project files here now?', true);
             projects.push({
                 path: projectPath,
@@ -2574,6 +2642,71 @@ async function doctorCommand(args) {
     const { envFile, envSource } = resolveDoctorEnvTarget(args);
     const checks = [];
     const version = getPackageVersion();
+    const pushEnvironmentChecks = async (env, prefix = '') => {
+        const databaseUrl = env.DATABASE_URL;
+        checks.push(detectPlaceholder(databaseUrl)
+            ? {
+                name: `${prefix}database configuration`,
+                status: 'fail',
+                detail: 'DATABASE_URL is missing or still uses a placeholder value.',
+            }
+            : {
+                name: `${prefix}database configuration`,
+                status: 'pass',
+                detail: 'DATABASE_URL is present and non-placeholder.',
+            });
+        const provider = env.LLM_PROVIDER ?? 'mock';
+        checks.push({
+            name: `${prefix}llm provider`,
+            status: 'pass',
+            detail: `LLM_PROVIDER=${provider}`,
+        });
+        const providerKeyCheck = detectProviderKey(provider, env);
+        checks.push({
+            ...providerKeyCheck,
+            name: `${prefix}${providerKeyCheck.name}`,
+        });
+        try {
+            const backendName = (0, backends_1.resolveVectorBackendName)({
+                vectorBackend: env.IRANTI_VECTOR_BACKEND,
+                qdrantUrl: env.IRANTI_QDRANT_URL,
+                qdrantApiKey: env.IRANTI_QDRANT_API_KEY,
+                qdrantCollection: env.IRANTI_QDRANT_COLLECTION,
+                chromaUrl: env.IRANTI_CHROMA_URL,
+                chromaCollection: env.IRANTI_CHROMA_COLLECTION,
+                chromaTenant: env.IRANTI_CHROMA_TENANT,
+                chromaDatabase: env.IRANTI_CHROMA_DATABASE,
+                chromaToken: env.IRANTI_CHROMA_TOKEN,
+            });
+            const backend = (0, backends_1.createVectorBackend)({
+                vectorBackend: backendName,
+                qdrantUrl: env.IRANTI_QDRANT_URL,
+                qdrantApiKey: env.IRANTI_QDRANT_API_KEY,
+                qdrantCollection: env.IRANTI_QDRANT_COLLECTION,
+                chromaUrl: env.IRANTI_CHROMA_URL,
+                chromaCollection: env.IRANTI_CHROMA_COLLECTION,
+                chromaTenant: env.IRANTI_CHROMA_TENANT,
+                chromaDatabase: env.IRANTI_CHROMA_DATABASE,
+                chromaToken: env.IRANTI_CHROMA_TOKEN,
+            });
+            const reachable = await backend.ping();
+            const url = vectorBackendUrl(backendName, env);
+            checks.push({
+                name: `${prefix}vector backend`,
+                status: reachable ? 'pass' : 'warn',
+                detail: url
+                    ? `${backendName} (${url}) is ${reachable ? 'reachable' : 'unreachable'}`
+                    : `${backendName} is ${reachable ? 'reachable' : 'unreachable'}`,
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: `${prefix}vector backend`,
+                status: 'fail',
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
     checks.push({
         name: 'node version',
         status: Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10) >= 18 ? 'pass' : 'fail',
@@ -2603,24 +2736,15 @@ async function doctorCommand(args) {
     }
     else {
         const env = await readEnvFile(envFile);
+        const treatAsProjectBinding = envSource === 'project-binding'
+            || path_1.default.basename(envFile).toLowerCase() === '.env.iranti'
+            || (Boolean(env.IRANTI_URL?.trim()) && detectPlaceholder(env.DATABASE_URL));
         checks.push({
             name: 'environment file',
             status: 'pass',
             detail: `${envSource} env loaded from ${envFile}`,
         });
-        const databaseUrl = env.DATABASE_URL;
-        checks.push(detectPlaceholder(databaseUrl)
-            ? {
-                name: 'database configuration',
-                status: 'fail',
-                detail: 'DATABASE_URL is missing or still uses a placeholder value.',
-            }
-            : {
-                name: 'database configuration',
-                status: 'pass',
-                detail: 'DATABASE_URL is present and non-placeholder.',
-            });
-        if (envSource === 'project-binding') {
+        if (treatAsProjectBinding) {
             checks.push(detectPlaceholder(env.IRANTI_URL)
                 ? {
                     name: 'project binding url',
@@ -2633,7 +2757,7 @@ async function doctorCommand(args) {
                     detail: `IRANTI_URL=${env.IRANTI_URL}`,
                 });
         }
-        if (envSource === 'project-binding') {
+        if (treatAsProjectBinding) {
             checks.push(detectPlaceholder(env.IRANTI_API_KEY)
                 ? {
                     name: 'project api key',
@@ -2645,8 +2769,33 @@ async function doctorCommand(args) {
                     status: 'pass',
                     detail: 'IRANTI_API_KEY is present in .env.iranti.',
                 });
+            const linkedInstanceEnv = env.IRANTI_INSTANCE_ENV?.trim();
+            if (!linkedInstanceEnv) {
+                checks.push({
+                    name: 'bound instance env',
+                    status: 'warn',
+                    detail: 'IRANTI_INSTANCE_ENV is not set in .env.iranti. Skipping database and provider checks for the bound instance.',
+                });
+            }
+            else if (!fs_1.default.existsSync(linkedInstanceEnv)) {
+                checks.push({
+                    name: 'bound instance env',
+                    status: 'warn',
+                    detail: `Linked instance env not found: ${linkedInstanceEnv}. Skipping database and provider checks for the bound instance.`,
+                });
+            }
+            else {
+                checks.push({
+                    name: 'bound instance env',
+                    status: 'pass',
+                    detail: `Using ${linkedInstanceEnv} for bound instance diagnostics.`,
+                });
+                const linkedEnv = await readEnvFile(linkedInstanceEnv);
+                await pushEnvironmentChecks(linkedEnv, 'bound instance ');
+            }
         }
         else {
+            await pushEnvironmentChecks(env);
             checks.push(detectPlaceholder(env.IRANTI_API_KEY)
                 ? {
                     name: 'api key',
@@ -2659,53 +2808,6 @@ async function doctorCommand(args) {
                     detail: 'IRANTI_API_KEY is present.',
                 });
         }
-        const provider = env.LLM_PROVIDER ?? 'mock';
-        checks.push({
-            name: 'llm provider',
-            status: 'pass',
-            detail: `LLM_PROVIDER=${provider}`,
-        });
-        checks.push(detectProviderKey(provider, env));
-        try {
-            const backendName = (0, backends_1.resolveVectorBackendName)({
-                vectorBackend: env.IRANTI_VECTOR_BACKEND,
-                qdrantUrl: env.IRANTI_QDRANT_URL,
-                qdrantApiKey: env.IRANTI_QDRANT_API_KEY,
-                qdrantCollection: env.IRANTI_QDRANT_COLLECTION,
-                chromaUrl: env.IRANTI_CHROMA_URL,
-                chromaCollection: env.IRANTI_CHROMA_COLLECTION,
-                chromaTenant: env.IRANTI_CHROMA_TENANT,
-                chromaDatabase: env.IRANTI_CHROMA_DATABASE,
-                chromaToken: env.IRANTI_CHROMA_TOKEN,
-            });
-            const backend = (0, backends_1.createVectorBackend)({
-                vectorBackend: backendName,
-                qdrantUrl: env.IRANTI_QDRANT_URL,
-                qdrantApiKey: env.IRANTI_QDRANT_API_KEY,
-                qdrantCollection: env.IRANTI_QDRANT_COLLECTION,
-                chromaUrl: env.IRANTI_CHROMA_URL,
-                chromaCollection: env.IRANTI_CHROMA_COLLECTION,
-                chromaTenant: env.IRANTI_CHROMA_TENANT,
-                chromaDatabase: env.IRANTI_CHROMA_DATABASE,
-                chromaToken: env.IRANTI_CHROMA_TOKEN,
-            });
-            const reachable = await backend.ping();
-            const url = vectorBackendUrl(backendName, env);
-            checks.push({
-                name: 'vector backend',
-                status: reachable ? 'pass' : 'warn',
-                detail: url
-                    ? `${backendName} (${url}) is ${reachable ? 'reachable' : 'unreachable'}`
-                    : `${backendName} is ${reachable ? 'reachable' : 'unreachable'}`,
-            });
-        }
-        catch (error) {
-            checks.push({
-                name: 'vector backend',
-                status: 'fail',
-                detail: error instanceof Error ? error.message : String(error),
-            });
-        }
     }
     const result = {
         version,
@@ -3102,19 +3204,21 @@ async function showInstanceCommand(args) {
 }
 async function runInstanceCommand(args) {
     const name = getFlag(args, 'instance') ?? args.positionals[0] ?? args.subcommand;
-    if (!name)
-        throw new Error('Missing instance name. Usage: iranti run --instance <name>');
+    if (!name) {
+        throw cliError('IRANTI_INSTANCE_NAME_REQUIRED', 'Missing instance name. Usage: iranti run --instance <name>', ['Run `iranti instance list` to see configured instances.']);
+    }
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
     const envFile = path_1.default.join(root, 'instances', name, '.env');
-    if (!fs_1.default.existsSync(envFile))
-        throw new Error(`Instance '${name}' not found. Create it first.`);
+    if (!fs_1.default.existsSync(envFile)) {
+        throw cliError('IRANTI_INSTANCE_NOT_FOUND', `Instance '${name}' not found. Create it first.`, [`Run \`iranti setup\` or \`iranti instance create ${name}\` first.`], { instance: name, envFile });
+    }
     const env = await readEnvFile(envFile);
     for (const [k, v] of Object.entries(env)) {
         process.env[k] = v;
     }
     if (!process.env.DATABASE_URL || process.env.DATABASE_URL.includes('yourpassword')) {
-        throw new Error(`Instance '${name}' has placeholder DATABASE_URL. Edit ${envFile} first.`);
+        throw cliError('IRANTI_INSTANCE_DATABASE_PLACEHOLDER', `Instance '${name}' has placeholder DATABASE_URL. Edit ${envFile} first.`, ['Run `iranti configure instance <name> --interactive` or rerun `iranti setup`.'], { instance: name, envFile });
     }
     console.log(`${infoLabel()} Starting Iranti instance '${name}' on port ${process.env.IRANTI_PORT ?? '3001'}...`);
     const serverEntry = path_1.default.resolve(__dirname, '..', 'src', 'api', 'server');
@@ -3125,7 +3229,7 @@ async function projectInitCommand(args) {
     const projectPath = path_1.default.resolve(args.positionals[0] ?? process.cwd());
     const instanceName = getFlag(args, 'instance');
     if (!instanceName) {
-        throw new Error('Missing --instance <name>. Usage: iranti project init [path] --instance <name>');
+        throw cliError('IRANTI_INSTANCE_NAME_REQUIRED', 'Missing --instance <name>. Usage: iranti project init [path] --instance <name>', ['Run `iranti instance list` to see available instances.']);
     }
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
@@ -3136,7 +3240,7 @@ async function projectInitCommand(args) {
     const projectMode = normalizeProjectMode(getFlag(args, 'mode'), 'isolated');
     const outFile = path_1.default.join(projectPath, '.env.iranti');
     if (fs_1.default.existsSync(outFile) && !hasFlag(args, 'force')) {
-        throw new Error(`${outFile} already exists. Use --force to overwrite.`);
+        throw cliError('IRANTI_PROJECT_BINDING_EXISTS', `${outFile} already exists. Use --force to overwrite.`, ['Use `iranti configure project` if you want to refresh the existing binding instead.'], { outFile });
     }
     await writeProjectBinding(projectPath, {
         IRANTI_URL: `http://localhost:${port}`,
@@ -3173,13 +3277,13 @@ async function configureInstanceCommand(args) {
     let clearProviderKey = hasFlag(args, 'clear-provider-key');
     if (hasFlag(args, 'interactive')) {
         await withPromptSession(async (prompt) => {
-            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');
+            portRaw = await prompt.line('API 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');
             const interactiveProvider = normalizeProvider(providerInput ?? env.LLM_PROVIDER ?? 'mock');
             const interactiveProviderEnvKey = providerKeyEnv(interactiveProvider);
             if (interactiveProvider && interactiveProviderEnvKey) {
-                providerKey = await prompt.secret(`Enter the ${providerDisplayName(interactiveProvider)} API key`, providerKey ?? env[interactiveProviderEnvKey]);
+                providerKey = await prompt.secret(`${providerDisplayName(interactiveProvider)} API key`, providerKey ?? env[interactiveProviderEnvKey]);
             }
             apiKey = await prompt.secret('Iranti API key', apiKey ?? env.IRANTI_API_KEY);
         });
@@ -3256,12 +3360,12 @@ async function configureProjectCommand(args) {
     let explicitProjectMode = getFlag(args, 'mode');
     if (hasFlag(args, 'interactive')) {
         await withPromptSession(async (prompt) => {
-            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 ?? projectAgentDefault(projectPath));
-            explicitMemoryEntity = await prompt.line('What memory entity should this project use', explicitMemoryEntity ?? existing.IRANTI_MEMORY_ENTITY ?? 'user/main');
-            explicitProjectMode = await prompt.line('Should this project be isolated or shared', explicitProjectMode ?? existing.IRANTI_PROJECT_MODE ?? inferProjectMode(projectPath, existing.IRANTI_INSTANCE_ENV));
+            instanceName = await prompt.line('Instance name', instanceName);
+            explicitUrl = await prompt.line('Iranti URL', explicitUrl ?? existing.IRANTI_URL);
+            explicitApiKey = await prompt.secret('Project API key', explicitApiKey ?? existing.IRANTI_API_KEY);
+            explicitAgentId = await prompt.line('Project agent ID', explicitAgentId ?? existing.IRANTI_AGENT_ID ?? projectAgentDefault(projectPath));
+            explicitMemoryEntity = await prompt.line('Project memory entity', explicitMemoryEntity ?? existing.IRANTI_MEMORY_ENTITY ?? 'user/main');
+            explicitProjectMode = await prompt.line('Project mode (isolated or shared)', explicitProjectMode ?? existing.IRANTI_PROJECT_MODE ?? inferProjectMode(projectPath, existing.IRANTI_INSTANCE_ENV));
         });
     }
     let instanceEnvFile = existing.IRANTI_INSTANCE_ENV;
@@ -3591,7 +3695,7 @@ async function claudeSetupCommand(args) {
             ?? (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}`);
+            throw cliError('IRANTI_SCAN_PATH_NOT_FOUND', `Scan directory not found: ${scanDir}`);
         }
         const candidates = findClaudeProjects(scanDir, recursive);
         if (candidates.length === 0) {
@@ -3638,10 +3742,10 @@ async function claudeSetupCommand(args) {
         ? 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}`);
+        throw cliError('IRANTI_PROJECT_PATH_NOT_FOUND', `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.`);
+        throw cliError('IRANTI_PROJECT_BINDING_MISSING', `Project binding not found at ${projectEnvPath}. Run \`iranti project init\` or \`iranti configure project\` first.`, ['Run `iranti project init . --instance <name>` before `iranti claude-setup`.'], { projectEnvPath });
     }
     const result = await writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force);
     console.log(`${okLabel()} Claude Code integration scaffolded`);
@@ -3675,24 +3779,27 @@ function printHelp() {
     const printRows = (title, entries) => {
         console.log(sectionTitle(title));
         for (const [command, description] of entries) {
-            console.log(`  ${commandText(command.padEnd(72))} ${description}`);
+            console.log(`  ${commandText(command)}`);
+            console.log(`    ${description}`);
         }
         console.log('');
     };
     console.log(sectionTitle('Iranti CLI'));
     console.log('Memory infrastructure for multi-agent systems.');
+    console.log('Most instance-aware commands also accept --root <path> in addition to --scope.');
+    console.log('Global debugging flags: --debug for extra diagnostics, --verbose for subprocess trace output.');
     console.log('');
     printRows('Start Here', rows);
     printRows('Setup And Runtime', [
         ['iranti install [--scope user|system] [--root <path>]', 'Initialize the machine-level runtime folders.'],
-        ['iranti setup [--scope user|system] [--root <path>] [--mode isolated|shared] [--config <file> | --defaults] [--db-mode local|managed|docker] [--db-url <url>] [--bootstrap-db]', 'Guided setup for runtime, database, instance, keys, and project binding.'],
+        ['iranti setup [--scope user|system] [--root <path>] [--mode isolated|shared] [--instance <name>] [--port <n>] [--config <file> | --defaults] [--db-mode local|managed|docker] [--db-url <url>] [--provider <name>] [--api-key <token>] [--projects <path1,path2>] [--claude-code] [--bootstrap-db]', 'Guided setup for runtime, database, instance, keys, and project binding. Run iranti setup --help for the non-interactive flow.'],
         ['iranti instance create <name> [--port 3001] [--db-url <url>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--scope user|system]', 'Create an instance directly if you want low-level control.'],
         ['iranti instance list [--scope user|system]', 'List configured instances.'],
         ['iranti instance show <name> [--scope user|system]', 'Show one instance env, port, and database target.'],
         ['iranti run --instance <name> [--scope user|system]', 'Start an instance.'],
     ]);
     printRows('Configuration', [
-        ['iranti configure instance <name> [--interactive] [--db-url <url>] [--port <n>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--clear-provider-key]', 'Update an instance without editing env files manually.'],
+        ['iranti configure instance <name> [--interactive] [--db-url <url>] [--port <n>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--clear-provider-key] [--json]', 'Update an instance without editing env files manually.'],
         ['iranti project init [path] --instance <name> [--api-key <token>] [--agent-id <id>] [--mode isolated|shared] [--force]', 'Create a new .env.iranti binding for one project.'],
         ['iranti configure project [path] [--interactive] [--instance <name>] [--url <http://host:port>] [--api-key <token>] [--agent-id <id>] [--memory-entity <entity>] [--mode isolated|shared] [--json]', 'Refresh or retarget an existing project binding.'],
     ]);
@@ -3706,7 +3813,7 @@ function printHelp() {
         ['iranti remove api-key [provider] [--instance <name>] [--project <path>] [--json]', 'Remove a stored provider key.'],
     ]);
     printRows('Diagnostics And Operator Tools', [
-        ['iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json]', 'Run environment and runtime diagnostics.'],
+        ['iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json] [--debug]', 'Run environment and runtime diagnostics.'],
         ['iranti status [--scope user|system] [--json]', 'Show runtime roots, bindings, and known instances.'],
         ['iranti upgrade [--check] [--dry-run] [--yes] [--all] [--target auto|npm-global|npm-repo|python[,python]] [--json]', 'Check or run CLI/runtime/package upgrades.'],
         ['iranti handshake [--instance <name> | --project-env <file>] [--agent <id>] [--task <text>] [--recent <msg1||msg2>] [--recent-file <path>] [--json]', 'Manually inspect Attendant handshake output.'],
@@ -3738,22 +3845,31 @@ function printHelp() {
     console.log(`    ${commandText('iranti auth create-key --instance local --key-id app_main --owner \"App Main\" --scopes \"kb:read,kb:write,memory:read,memory:write\"')}`);
     console.log(`    ${commandText('iranti add api-key openai --instance local --set-default')}`);
 }
+function printSetupHelp() {
+    console.log(sectionTitle('Setup Command'));
+    console.log(`  ${commandText('iranti setup [--scope user|system] [--root <path>] [--mode isolated|shared] [--instance <name>] [--port <n>] [--config <file> | --defaults] [--db-mode local|managed|docker] [--db-url <url>] [--provider <name>] [--api-key <token>] [--projects <path1,path2>] [--claude-code] [--bootstrap-db]')}`);
+    console.log('');
+    console.log('  Interactive mode walks through runtime, database, provider keys, API keys, and project binding.');
+    console.log('  Use `--defaults` to build a plan from flags and environment variables without prompts.');
+    console.log('  Use `--config <file>` to execute a saved setup plan.');
+    console.log('  `--projects` and `--claude-code` apply to the non-interactive defaults flow.');
+}
 function printInstanceHelp() {
     console.log(sectionTitle('Instance Commands'));
-    console.log(`  ${commandText('iranti instance create <name> [--port 3001] [--db-url <url>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--scope user|system]')}`);
-    console.log(`  ${commandText('iranti instance list [--scope user|system]')}`);
-    console.log(`  ${commandText('iranti instance show <name> [--scope user|system]')}`);
+    console.log(`  ${commandText('iranti instance create <name> [--port 3001] [--db-url <url>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--scope user|system] [--root <path>]')}`);
+    console.log(`  ${commandText('iranti instance list [--scope user|system] [--root <path>]')}`);
+    console.log(`  ${commandText('iranti instance show <name> [--scope user|system] [--root <path>]')}`);
 }
 function printConfigureHelp() {
     console.log(sectionTitle('Configure Commands'));
-    console.log(`  ${commandText('iranti configure instance <name> [--interactive] [--db-url <url>] [--port <n>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--clear-provider-key]')}`);
-    console.log(`  ${commandText('iranti configure project [path] [--interactive] [--instance <name>] [--url <http://host:port>] [--api-key <token>] [--agent-id <id>] [--memory-entity <entity>] [--mode isolated|shared] [--json]')}`);
+    console.log(`  ${commandText('iranti configure instance <name> [--interactive] [--db-url <url>] [--port <n>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--clear-provider-key] [--scope user|system] [--root <path>] [--json]')}`);
+    console.log(`  ${commandText('iranti configure project [path] [--interactive] [--instance <name>] [--url <http://host:port>] [--api-key <token>] [--agent-id <id>] [--memory-entity <entity>] [--mode isolated|shared] [--scope user|system] [--root <path>] [--json]')}`);
 }
 function printAuthHelp() {
     console.log(sectionTitle('Auth Commands'));
-    console.log(`  ${commandText('iranti auth create-key --instance <name> --key-id <id> --owner <owner> [--scopes ...] [--description <text>] [--write-instance] [--project <path>] [--agent-id <id>] [--json]')}`);
-    console.log(`  ${commandText('iranti auth list-keys --instance <name> [--json]')}`);
-    console.log(`  ${commandText('iranti auth revoke-key --instance <name> --key-id <id> [--json]')}`);
+    console.log(`  ${commandText('iranti auth create-key --instance <name> --key-id <id> --owner <owner> [--scopes ...] [--description <text>] [--write-instance] [--project <path>] [--agent-id <id>] [--scope user|system] [--root <path>] [--json]')}`);
+    console.log(`  ${commandText('iranti auth list-keys --instance <name> [--scope user|system] [--root <path>] [--json]')}`);
+    console.log(`  ${commandText('iranti auth revoke-key --instance <name> --key-id <id> [--scope user|system] [--root <path>] [--json]')}`);
 }
 function printIntegrateHelp() {
     console.log(sectionTitle('Integrations'));
@@ -3761,8 +3877,23 @@ function printIntegrateHelp() {
     console.log(`  ${commandText('iranti integrate claude --scan <dir> [--recursive] [--force]')}`);
     console.log(`  ${commandText('iranti integrate codex [--name iranti] [--agent codex_code] [--source Codex] [--provider openai] [--project-env <path>] [--local-script]')}`);
 }
+function printProviderKeyHelp() {
+    console.log(sectionTitle('Provider Key Commands'));
+    console.log(`  ${commandText('iranti list api-keys [--instance <name>] [--project <path>] [--json]')}`);
+    console.log(`  ${commandText('iranti add api-key [provider] [--instance <name>] [--project <path>] [--key <token>] [--set-default] [--json]')}`);
+    console.log(`  ${commandText('iranti update api-key [provider] [--instance <name>] [--project <path>] [--key <token>] [--set-default] [--json]')}`);
+    console.log(`  ${commandText('iranti remove api-key [provider] [--instance <name>] [--project <path>] [--json]')}`);
+    console.log('');
+    console.log('  Target either an instance env or a project binding. If neither is supplied, the CLI will try the current project first.');
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    setCliDebugFlags(args);
+    debugLog('CLI invocation started.', {
+        command: args.command,
+        subcommand: args.subcommand,
+        cwd: process.cwd(),
+    });
     if (!args.command || args.command === 'help' || args.command === '--help') {
         printHelp();
         return;
@@ -3772,6 +3903,10 @@ async function main() {
         return;
     }
     if (args.command === 'setup') {
+        if (hasFlag(args, 'help')) {
+            printSetupHelp();
+            return;
+        }
         await setupCommand(args);
         return;
     }
@@ -3833,18 +3968,34 @@ async function main() {
         throw new Error(`Unknown auth subcommand '${args.subcommand ?? ''}'.`);
     }
     if (args.command === 'list' && args.subcommand === 'api-keys') {
+        if (hasFlag(args, 'help')) {
+            printProviderKeyHelp();
+            return;
+        }
         await listProviderKeysCommand(args);
         return;
     }
     if (args.command === 'add' && args.subcommand === 'api-key') {
+        if (hasFlag(args, 'help')) {
+            printProviderKeyHelp();
+            return;
+        }
         await upsertProviderKeyCommand(args, 'add');
         return;
     }
     if (args.command === 'update' && args.subcommand === 'api-key') {
+        if (hasFlag(args, 'help')) {
+            printProviderKeyHelp();
+            return;
+        }
         await upsertProviderKeyCommand(args, 'update');
         return;
     }
     if (args.command === 'remove' && args.subcommand === 'api-key') {
+        if (hasFlag(args, 'help')) {
+            printProviderKeyHelp();
+            return;
+        }
         await removeProviderKeyCommand(args);
         return;
     }
@@ -3911,11 +4062,27 @@ async function main() {
         }
         throw new Error(`Unknown integrate target '${args.subcommand ?? ''}'. Use 'claude' or 'codex'.`);
     }
-    throw new Error(`Unknown command '${args.command}'. Run: iranti help`);
+    throw cliError('IRANTI_UNKNOWN_COMMAND', `Unknown command '${args.command}'. Run: iranti help`, ['Use `iranti help` to see the current command surface.'], { command: args.command });
 }
 main().catch((err) => {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`${failLabel('ERROR')} ${message}`);
+    const code = err instanceof CliError ? err.code : null;
+    console.error(`${failLabel('ERROR')}${code ? ` [${code}]` : ''} ${message}`);
+    if (err instanceof CliError && err.hints.length > 0) {
+        console.error('');
+        console.error('Possible fixes:');
+        for (const hint of err.hints) {
+            console.error(`  - ${hint}`);
+        }
+    }
+    if (CLI_DEBUG && err instanceof CliError && err.details && Object.keys(err.details).length > 0) {
+        console.error('');
+        console.error(`${paint('[DEBUG]', 'gray')} ${JSON.stringify(err.details, null, 2)}`);
+    }
+    if (CLI_DEBUG && err instanceof Error && err.stack) {
+        console.error('');
+        console.error(err.stack);
+    }
     process.exit(1);
 });
 //# sourceMappingURL=iranti-cli.js.map

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

package/package.json

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