iranti 0.2.10 → 0.2.11

package/dist/scripts/iranti-cli.js

@@ -707,7 +707,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 +730,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 +1466,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 +1480,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.');
         }
     }
@@ -2341,7 +2349,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 +2359,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 +2375,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 +2386,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 +2394,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 +2423,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 +2449,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 +2472,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 +2507,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 +2582,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 +2676,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 +2697,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 +2709,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 +2748,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,
@@ -3173,13 +3215,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 +3298,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;
@@ -3675,24 +3717,26 @@ 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('');
     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.'],
     ]);
@@ -3738,22 +3782,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,6 +3814,15 @@ 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));
     if (!args.command || args.command === 'help' || args.command === '--help') {
@@ -3772,6 +3834,10 @@ async function main() {
         return;
     }
     if (args.command === 'setup') {
+        if (hasFlag(args, 'help')) {
+            printSetupHelp();
+            return;
+        }
         await setupCommand(args);
         return;
     }
@@ -3833,18 +3899,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;
     }

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.11',
     });
     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.11',
             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.11',
             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.11',
             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.11' },
         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.11',
         },
         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.11',
             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.11',
             namespaces: {
                 education: {
                     status: 'provisional',
@@ -187,7 +187,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'candidate_terms',
         valueRaw: {
-            version: '0.2.10',
+            version: '0.2.11',
             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.11',
             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.11',
             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.11',
         provider: process.env.LLM_PROVIDER ?? 'mock',
     });
 });

package/package.json

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