@functional-systems/lambdadb-cli 0.1.4 → 0.1.5-dev.20

package/src/agents.ts

@@ -0,0 +1,212 @@
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { jsonConfig, strictJsonConfig, tomlConfig, type McpLaunch } from './agent-config.js';
+import { InputError } from './errors.js';
+
+export type AgentScope = 'project' | 'user';
+export type AgentContext = { cwd: string; home: string; env: NodeJS.ProcessEnv; platform?: NodeJS.Platform };
+type AgentPaths = { mcp: string; skill?: string };
+export type AgentAdapter = {
+  id: string;
+  executable: string | readonly string[];
+  scopes?: readonly AgentScope[];
+  detectionDirectories(context: AgentContext): string[];
+  paths(scope: AgentScope, context: AgentContext): AgentPaths | Promise<AgentPaths>;
+  configure(path: string, text: string | undefined, launch: McpLaunch): string;
+  instructions: string;
+};
+
+const codexServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({ command, args, env_vars: [apiKeyEnv] });
+const claudeServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
+  type: 'stdio', command, args, env: { [apiKeyEnv]: `\${${apiKeyEnv}}` },
+});
+const cursorServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
+  type: 'stdio', command, args, env: { [apiKeyEnv]: `\${env:${apiKeyEnv}}` },
+});
+const geminiServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
+  command, args, env: { [apiKeyEnv]: `\${${apiKeyEnv}}` },
+});
+const opencodeServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
+  type: 'local', command: [command, ...args], environment: { [apiKeyEnv]: `{env:${apiKeyEnv}}` },
+});
+
+function vscodeUserDirectory({ cwd, home, env, platform = process.platform }: AgentContext): string {
+  if (env.VSCODE_PORTABLE) return resolve(cwd, env.VSCODE_PORTABLE, 'user-data', 'User');
+  const appData = env.VSCODE_APPDATA ?? (platform === 'darwin' ? join(home, 'Library', 'Application Support')
+    : platform === 'win32' ? env.APPDATA ?? join(home, 'AppData', 'Roaming')
+    : env.XDG_CONFIG_HOME ?? join(home, '.config'));
+  return resolve(cwd, appData, 'Code', 'User');
+}
+
+function geminiDirectory({ cwd, home, env }: AgentContext): string {
+  return resolve(cwd, env.GEMINI_CLI_HOME ?? home, '.gemini');
+}
+
+function opencodeDirectory({ cwd, home, env }: AgentContext): string {
+  return resolve(cwd, env.XDG_CONFIG_HOME ?? join(home, '.config'), 'opencode');
+}
+
+async function opencodePaths(scope: AgentScope, context: AgentContext): Promise<AgentPaths> {
+  const root = scope === 'user' ? opencodeDirectory(context) : context.cwd;
+  const json = join(root, 'opencode.json');
+  const jsonc = join(root, 'opencode.jsonc');
+  const [hasJson, hasJsonc] = await Promise.all([exists(json), exists(jsonc)]);
+  if (hasJson && hasJsonc) throw new InputError(`Both ${json} and ${jsonc} exist. Consolidate the active OpenCode configuration before running init so no LambdaDB entry is shadowed.`);
+  return { mcp: hasJsonc ? jsonc : json, skill: join(scope === 'user' ? root : join(root, '.opencode'), 'skills', 'lambdadb', 'SKILL.md') };
+}
+
+function opencodeMapPath(value: Record<string, unknown>): readonly string[] {
+  const mcp = value.mcp;
+  if (mcp && typeof mcp === 'object' && !Array.isArray(mcp) && 'servers' in mcp) {
+    const servers = mcp.servers;
+    // A V1 server may itself be named "servers". Preserve that server's shape.
+    const legacyServer = servers && typeof servers === 'object' && 'type' in servers && typeof servers.type === 'string';
+    if (!legacyServer) {
+      if ('lambdadb' in mcp) throw new InputError('OpenCode has both a V1 LambdaDB entry and a V2 MCP server map. Consolidate the LambdaDB entry before rerunning init.');
+      return ['mcp', 'servers'];
+    }
+  }
+  // V1 configuration remains supported by V2; never migrate unrelated settings.
+  return ['mcp'];
+}
+
+function copilotDirectory({ cwd, home, env }: AgentContext): string {
+  return resolve(cwd, env.COPILOT_HOME ?? join(home, '.copilot'));
+}
+
+async function copilotPaths(scope: AgentScope, context: AgentContext): Promise<AgentPaths> {
+  if (scope === 'user') return { mcp: join(copilotDirectory(context), 'mcp-config.json'),
+    skill: join(copilotDirectory(context), 'skills', 'lambdadb', 'SKILL.md') };
+  const rootConfig = join(context.cwd, '.mcp.json');
+  const sharedConfig = join(context.cwd, '.github', 'mcp.json');
+  return { mcp: await exists(rootConfig) || !await exists(sharedConfig) ? rootConfig : sharedConfig,
+    skill: join(context.cwd, '.github', 'skills', 'lambdadb', 'SKILL.md') };
+}
+
+function copilotMapPath(value: Record<string, unknown>): readonly string[] {
+  if ('mcpServers' in value || Object.keys(value).length === 0) return ['mcpServers'];
+  // Copilot also reads bare maps. Do not hide those entries behind a new wrapper.
+  const bare = Object.values(value).every(entry => entry && typeof entry === 'object' && !Array.isArray(entry)
+    && ('command' in entry || 'url' in entry || 'type' in entry));
+  if (!bare) throw new InputError('Copilot MCP configuration must contain mcpServers or a bare map of server definitions. Fix it before rerunning init.');
+  return [];
+}
+
+function clineSettingsDirectory(context: AgentContext): string {
+  return join(vscodeUserDirectory(context), 'globalStorage', 'saoudrizwan.claude-dev', 'settings');
+}
+
+// Register new agents here; init consumes this contract without agent-specific branches.
+export const agentAdapters = [
+  {
+    id: 'codex', executable: 'codex',
+    detectionDirectories: ({ cwd, home, env }) => [env.CODEX_HOME ?? join(home, '.codex'), join(cwd, '.codex')],
+    paths(scope, { cwd, home, env }) {
+      const root = scope === 'user' ? home : cwd;
+      const directory = scope === 'user' ? resolve(env.CODEX_HOME ?? join(root, '.codex')) : join(root, '.codex');
+      return { mcp: join(directory, 'config.toml'), skill: join(root, '.agents', 'skills', 'lambdadb', 'SKILL.md') };
+    },
+    configure: (path, text, launch) => tomlConfig(path, text, launch, codexServer),
+    instructions: 'Codex: trust the project if using project scope, start a new session, and check /mcp.',
+  },
+  {
+    id: 'claude', executable: 'claude',
+    detectionDirectories: ({ cwd, home, env }) => [env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), join(cwd, '.claude')],
+    paths(scope, { cwd, home, env }) {
+      const root = scope === 'user' ? home : cwd;
+      const directory = scope === 'user' ? resolve(env.CLAUDE_CONFIG_DIR ?? join(root, '.claude')) : join(root, '.claude');
+      return { mcp: scope === 'user' ? join(env.CLAUDE_CONFIG_DIR ? directory : root, '.claude.json') : join(root, '.mcp.json'),
+        skill: join(directory, 'skills', 'lambdadb', 'SKILL.md') };
+    },
+    configure: (path, text, launch) => jsonConfig(path, text, launch, claudeServer),
+    instructions: 'Claude Code: restart and approve the project MCP server if prompted; check /mcp.',
+  },
+  {
+    id: 'cursor', executable: ['cursor', 'cursor-agent'],
+    detectionDirectories: ({ cwd, home }) => [join(home, '.cursor'), join(cwd, '.cursor')],
+    paths(scope, { cwd, home }) {
+      const root = scope === 'user' ? home : cwd;
+      return { mcp: join(root, '.cursor', 'mcp.json'), skill: join(root, '.cursor', 'skills', 'lambdadb', 'SKILL.md') };
+    },
+    configure: (path, text, launch) => jsonConfig(path, text, launch, cursorServer),
+    instructions: 'Cursor: restart/reload and check MCP settings.',
+  },
+  {
+    id: 'vscode', executable: 'code',
+    detectionDirectories: context => [join(context.home, '.vscode'), join(context.cwd, '.vscode'), vscodeUserDirectory(context)],
+    paths(scope, context) {
+      return { mcp: scope === 'user' ? join(vscodeUserDirectory(context), 'mcp.json') : join(context.cwd, '.vscode', 'mcp.json'),
+        skill: join(scope === 'user' ? context.home : context.cwd, scope === 'user' ? '.copilot' : '.github', 'skills', 'lambdadb', 'SKILL.md') };
+    },
+    configure: (path, text, launch) => jsonConfig(path, text, launch, cursorServer, ['servers']),
+    instructions: 'VS Code: reload the window, trust the workspace, and use MCP: List Servers to start/check lambdadb. Init targets the Local harness and the default user profile, not portable Copilot or remote profiles.',
+  },
+  {
+    id: 'gemini', executable: 'gemini',
+    detectionDirectories: context => [geminiDirectory(context), join(context.cwd, '.gemini')],
+    paths(scope, context) {
+      const root = scope === 'user' ? geminiDirectory(context) : join(context.cwd, '.gemini');
+      return { mcp: join(root, 'settings.json'), skill: join(root, 'skills', 'lambdadb', 'SKILL.md') };
+    },
+    configure: (path, text, launch) => jsonConfig(path, text, launch, geminiServer),
+    instructions: 'Gemini CLI: restart or run /mcp refresh and /skills reload, trust the workspace if prompted, and check /mcp and /skills list.',
+  },
+  {
+    id: 'opencode', executable: 'opencode',
+    detectionDirectories: context => [opencodeDirectory(context), join(context.cwd, '.opencode'), join(context.cwd, 'opencode.json'), join(context.cwd, 'opencode.jsonc')],
+    paths: opencodePaths,
+    configure: (path, text, launch) => jsonConfig(path, text, launch, opencodeServer, opencodeMapPath),
+    instructions: 'OpenCode: restart and run opencode mcp list. Init preserves existing V2 mcp.servers maps; new files use V1 syntax supported by V1 and V2. Custom config files and organization policies may override these settings.',
+  },
+  {
+    id: 'copilot', executable: 'copilot',
+    detectionDirectories: context => [copilotDirectory(context), join(context.cwd, '.github', 'mcp.json')],
+    paths: copilotPaths,
+    configure: (path, text, launch) => strictJsonConfig(path, text, launch, claudeServer, copilotMapPath),
+    instructions: 'GitHub Copilot CLI: restart from the environment holding the selected key, trust the repository, then check /mcp and run /skills reload. Project MCP settings override user settings.',
+  },
+  {
+    id: 'kiro', executable: ['kiro', 'kiro-cli'],
+    detectionDirectories: ({ cwd, home }) => [join(home, '.kiro'), join(cwd, '.kiro')],
+    paths(scope, { cwd, home }) {
+      const directory = join(scope === 'user' ? home : cwd, '.kiro');
+      return { mcp: join(directory, 'settings', 'mcp.json'), skill: join(directory, 'skills', 'lambdadb', 'SKILL.md') };
+    },
+    configure: (path, text, launch) => jsonConfig(path, text, launch, geminiServer),
+    instructions: 'Kiro IDE/CLI: restart from the environment holding the selected key and check /mcp. Approve the selected variable in Mcp Approved Env Vars when prompted. Custom agents must include the MCP JSON and skill resources; init does not alter agent permissions or definitions.',
+  },
+  {
+    id: 'cline', executable: [], scopes: ['user'],
+    detectionDirectories: context => [clineSettingsDirectory(context)],
+    paths(_scope, context) {
+      return { mcp: join(clineSettingsDirectory(context), 'cline_mcp_settings.json'),
+        skill: join(context.home, '.cline', 'skills', 'lambdadb', 'SKILL.md') };
+    },
+    configure: (path, text, launch) => strictJsonConfig(path, text, launch, cursorServer),
+    instructions: 'Cline VS Code extension: reload VS Code from the environment holding the selected key and check MCP Servers and the Skills menu. Init targets the default stable VS Code profile, not Cline CLI or other editors/profiles. No tools are auto-approved.',
+  },
+] as const satisfies readonly AgentAdapter[];
+
+export type Agent = typeof agentAdapters[number]['id'];
+export const agentNames = agentAdapters.map(adapter => adapter.id).join(',');
+
+async function exists(path: string, executable = false) {
+  try { await access(path, executable ? constants.X_OK : constants.F_OK); return true; }
+  catch { return false; }
+}
+
+export async function detectAgents(context: AgentContext): Promise<Agent[]> {
+  const paths = (context.env.PATH ?? '').split(delimiter);
+  const found = await Promise.all(agentAdapters.map(async adapter => {
+    const executables = typeof adapter.executable === 'string' ? [adapter.executable] : adapter.executable;
+    const commands = executables.flatMap(executable => process.platform === 'win32'
+      ? [executable + '.exe', executable + '.cmd', executable] : [executable]);
+    const matches = await Promise.all([
+      ...adapter.detectionDirectories(context).map(path => exists(path)),
+      ...paths.flatMap(path => commands.map(command => exists(join(path, command), true))),
+    ]);
+    return matches.some(Boolean) ? adapter.id : undefined;
+  }));
+  return found.filter((agent): agent is Agent => agent !== undefined);
+}

package/src/cli.ts

@@ -6,7 +6,10 @@ import { createInput, parseRef, queryInput, readJson, readJsonl, updateInput } f
 import { importDocuments, planBatches } from './import-workflow.js';
 import { definitelyRejected, describeError, InputError, isInputError } from './errors.js';
 import { Output, type Envelope } from './output.js';
-import { runtime } from './runtime.js';
+import { checkConnection, runtime } from './runtime.js';
+import { initialize } from './init.js';
+import { serveMcp } from './mcp.js';
+import { agentNames } from './agents.js';
 
 const output = new Output();
 output.protect(process.env.LAMBDADB_API_KEY);
@@ -17,7 +20,7 @@ let mutationStarted = false;
 
 const program = new Command()
   .name('lambdadb')
-  .description('Project-scoped LambdaDB CLI. All commands are non-interactive.')
+  .description('Project-scoped LambdaDB CLI. Only init prompts; all other commands are non-interactive.')
   .version(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version)
   .option('--json', 'Emit one versioned JSON result on stdout; diagnostics stay on stderr')
   .option('--endpoint <url>', 'API origin (overrides LAMBDADB_ENDPOINT and saved configuration)')
@@ -51,6 +54,11 @@ function scoped(command: Command): string {
   return collection;
 }
 
+program.hook('preSubcommand', (_parent, command) => {
+  // Reserve MCP stdout even when subcommand option parsing fails before preAction.
+  if (command.name() === 'mcp') commandName = 'mcp';
+});
+
 program.hook('preAction', (_parent, command) => {
   output.json = !!command.optsWithGlobals().json;
   commandName = command.name();
@@ -64,14 +72,37 @@ program.command('configure')
     result(saved, 'Configuration saved. Supply the key in the selected environment variable, then run doctor.');
   });
 
+program.command('init')
+  .description('Connect an existing project and install agent MCP configuration and a usage skill')
+  .option('--non-interactive', 'Require explicit agent/scope choices; never prompt')
+  .option('--agents <names>', `Comma-separated ${agentNames} subset, or none`)
+  .option('--scope <scope>', 'Agent configuration scope: project (current directory) or user')
+  .option('--write-tools', 'Explicitly enable MCP write tools (default: read-only)')
+  .addHelpText('after', '\nObtain endpoint, project and a project API key manually from https://console.lambdadb.ai.\nExport the key securely before running init; no key value is saved.\nAutomation example:\n  lambdadb init --non-interactive --agents codex,claude,cursor --scope project --endpoint https://api.lambdadb.ai --project my-project --json')
+  .action(async (_opts, cmd: Command) => {
+    const data = await initialize(cmd.optsWithGlobals(), output);
+    target = { endpoint: data.settings.endpoint, project: data.settings.project };
+    result(data, 'Initialization complete. Authentication and collection-list access verified; search readiness is not verified.');
+  });
+
+program.command('mcp')
+  .description('Launch the existing stdio MCP package with runtime credential forwarding (used by init)')
+  .option('--write-tools', 'Explicitly enable MCP write tools (default: read-only)')
+  .action(async (_opts, cmd: Command) => {
+    const opts = cmd.optsWithGlobals();
+    if (opts.json) throw new InputError('The mcp command uses stdout exclusively for MCP; remove --json.');
+    const config = await resolveConfig(opts, true);
+    output.protect(config.apiKey);
+    if ([`\${${config.apiKeyEnv}}`, `\${env:${config.apiKeyEnv}}`, `{env:${config.apiKeyEnv}}`].includes(config.apiKey)) {
+      throw new InputError(`The agent did not expand ${config.apiKeyEnv}. Export it securely in the agent launch environment and restart the agent.`);
+    }
+    process.exitCode = await serveMcp(config, !!opts.writeTools);
+  });
+
 program.command('doctor')
   .description('Check configuration, authentication and project collection-list access')
   .action(async (_opts, cmd: Command) => connected(cmd, async ({ client, options }) => {
-    await client.listCollections({ size: 1 }, options);
-    result({ checks: [
-      { name: 'configuration', status: 'passed' },
-      { name: 'authentication_and_project_collection_list', status: 'passed' },
-    ], writesVerified: false, queryReadinessVerified: false }, 'Connection verified using the project collection-list API.');
+    result(await checkConnection({ client, options }), 'Connection verified using the project collection-list API.');
   }));
 
 const collections = program.command('collections').description('List, describe, create and update collections');
@@ -218,7 +249,10 @@ try {
       ? new InputError('Invalid or incomplete command. Run lambdadb --help or the command-specific --help.') : error;
     const unknownWrite = mutationStarted && !definitelyRejected(failure);
     const exitCode = isInputError(failure) ? 2 : unknownWrite ? 5 : 3;
-    output.emit({
+    if (commandName === 'mcp') {
+      const safe = describeError(failure);
+      output.diagnostic(`${safe.message} ${safe.hint}`);
+    } else output.emit({
       schemaVersion: 1, command: commandName, ok: false, target,
       ...(unknownWrite ? { data: { state: 'unknown', searchable: 'not_verified' } } : {}),
       error: describeError(failure),

package/src/config.ts

@@ -72,8 +72,8 @@ export async function settings(options: Options, creating = false): Promise<Requ
   };
 }
 
-export async function resolveConfig(options: Options): Promise<Config> {
-  const selected = await settings(options);
+export async function resolveConfig(options: Options, creating = false): Promise<Config> {
+  const selected = await settings(options, creating);
   const apiKey = process.env[selected.apiKeyEnv];
   if (!apiKey || !apiKey.trim() || /[\r\n]/.test(apiKey)) throw new InputError('The selected API-key environment variable is missing or invalid. Supply it through your shell or CI secret manager.');
   return {

package/src/init.ts

@@ -0,0 +1,185 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { configPath, loadSettings, resolveConfig, saveSettings, settings, type Options, type Settings } from './config.js';
+import { InputError } from './errors.js';
+import type { Output } from './output.js';
+import { checkConnection, runtime } from './runtime.js';
+import { mcpPackage } from './mcp.js';
+import { mcpLaunch } from './agent-config.js';
+import { agentAdapters, agentNames, detectAgents, type Agent, type AgentAdapter, type AgentContext, type AgentScope } from './agents.js';
+
+type InitOptions = Options & { nonInteractive?: boolean; agents?: string; scope?: string; writeTools?: boolean; json?: boolean };
+type Change = { path: string; before: string | undefined; after: string; kind: string };
+type PlannedChange = Change & { destination: string; aliases: string[] };
+const version = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version as string;
+
+function selectedAgents(value: string | undefined): Agent[] {
+  if (value === 'none') return [];
+  const values = value?.split(',').map(v => v.trim());
+  if (!values?.length || values.some(v => !agentAdapters.some(adapter => adapter.id === v))) {
+    throw new InputError(`Choose --agents ${agentNames} (comma-separated subset), or --agents none.`);
+  }
+  return [...new Set(values)] as Agent[];
+}
+
+function availableScopes(chosen: Agent[]): AgentScope[] {
+  return (['project', 'user'] as const).filter(scope => chosen.every(agent => {
+    const adapter: AgentAdapter = agentAdapters.find(adapter => adapter.id === agent)!;
+    return !adapter.scopes || adapter.scopes.includes(scope);
+  }));
+}
+
+async function readOptional(path: string): Promise<string | undefined> {
+  try { return await readFile(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw new InputError(`Cannot read ${path}. Check file permissions.`);
+  }
+}
+
+async function fileIdentity(path: string): Promise<string> {
+  try { return await realpath(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw new InputError(`Cannot resolve configuration path: ${path}.`);
+    const info = await lstat(path).catch(error => {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw new InputError(`Cannot resolve configuration path: ${path}.`);
+    });
+    if (info?.isSymbolicLink()) throw new InputError(`Configuration symbolic link has a missing target: ${path}. Restore its target before rerunning init.`);
+    return join(await fileIdentity(dirname(path)), basename(path));
+  }
+}
+
+async function plan(selected: Required<Settings>, chosen: Agent[], scope: AgentScope, options: InitOptions, context: AgentContext): Promise<PlannedChange[]> {
+  const changes: Change[] = [];
+  const path = configPath(options);
+  changes.push({ path, before: await readOptional(path), after: JSON.stringify(selected, null, 2) + '\n', kind: 'CLI settings (no key)' });
+  const skill = await readFile(new URL('../skills/lambdadb/SKILL.md', import.meta.url), 'utf8');
+  for (const agent of chosen) {
+    const adapter: AgentAdapter = agentAdapters.find(adapter => adapter.id === agent)!;
+    const paths = await adapter.paths(scope, context);
+    const before = await readOptional(paths.mcp);
+    const after = adapter.configure(paths.mcp, before, mcpLaunch(selected, !!options.writeTools, version));
+    changes.push({ path: paths.mcp, before, after, kind: `${agent} MCP (${scope})` });
+    const skillPath = paths.skill;
+    if (!skillPath) continue;
+    const previousSkill = await readOptional(skillPath);
+    // Preserve existing skills, including user edits, rather than taking ownership.
+    changes.push({ path: skillPath, before: previousSkill, after: previousSkill ?? skill, kind: `${agent} skill (${scope}${previousSkill && previousSkill !== skill ? ', existing skill preserved' : ''})` });
+  }
+  const unique = new Map<string, PlannedChange>();
+  for (const change of changes) {
+    const identity = await fileIdentity(change.path);
+    const previous = unique.get(identity);
+    if (!previous) { unique.set(identity, { ...change, destination: identity, aliases: [] }); continue; }
+    if (change.path === configPath(options) || previous.path === configPath(options)) {
+      throw new InputError('The CLI --config path overlaps an agent configuration or skill path. Choose a separate CLI configuration path and rerun init.');
+    }
+    if (previous.before !== change.before || previous.after !== change.after) {
+      throw new InputError(`Agents request conflicting changes to ${change.path}. Select them separately and inspect the shared file before retrying.`);
+    }
+    previous.kind += `; ${change.kind}`;
+    if (change.path !== previous.path && !previous.aliases.includes(change.path)) previous.aliases.push(change.path);
+  }
+  return [...unique.values()];
+}
+
+async function apply(changes: PlannedChange[], options: Options) {
+  // Detect concurrent edits before writing anything. Individual writes are atomic;
+  // a disk/permission failure can still leave a partial install, safe to rerun.
+  for (const change of changes) {
+    for (const path of [change.path, ...change.aliases]) {
+      if (await fileIdentity(path) !== change.destination) throw new InputError(`Configuration changed during init: ${path}. Rerun init to review the new plan.`);
+    }
+    if (await readOptional(change.destination) !== change.before) {
+      throw new InputError(`Configuration changed during init: ${change.path}. Rerun init to review the new plan.`);
+    }
+  }
+  for (const change of changes.filter(change => change.before !== change.after)) {
+    if (change.path === configPath(options)) { await saveSettings({ ...options, config: change.destination }); continue; }
+    const temp = `${change.destination}.${randomUUID()}.tmp`;
+    try {
+      await mkdir(dirname(change.destination), { recursive: true });
+      await writeFile(temp, change.after, { flag: 'wx', mode: 0o600 });
+      await rename(temp, change.destination);
+    } catch {
+      throw new InputError(`Cannot update ${change.path}. Check permissions and rerun init; earlier files may already have been updated.`);
+    } finally { await rm(temp, { force: true }).catch(() => {}); }
+  }
+}
+
+export async function initialize(options: InitOptions, output: Output) {
+  const interactive = !options.nonInteractive && !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+  if (!interactive && !options.nonInteractive) {
+    throw new InputError(`Init needs a terminal. For automation or --json, pass --non-interactive --agents ${agentNames} (or none) --scope project (or user).`);
+  }
+  const context = { cwd: process.cwd(), home: homedir(), env: process.env };
+  const detected = await detectAgents(context);
+  output.diagnostic('Manual Console step: open https://console.lambdadb.ai, select an existing project, and obtain its API endpoint, project name and API key. Export the key securely; init never accepts or saves a key value.');
+  const prompt = interactive ? createInterface({ input: process.stdin, output: process.stderr }) : undefined;
+  const ask = async (label: string, fallback?: string) => {
+    const cancellation = new AbortController();
+    const cancel = () => cancellation.abort();
+    prompt!.once('SIGINT', cancel);
+    prompt!.once('close', cancel);
+    try {
+      const answer = (await prompt!.question(`${label}${fallback ? ` [${fallback}]` : ''}: `, { signal: cancellation.signal })).trim();
+      return answer || fallback;
+    } catch (error) {
+      if (cancellation.signal.aborted) throw new InputError('Init canceled. No files were changed.');
+      throw error;
+    } finally {
+      prompt!.removeListener('SIGINT', cancel);
+      prompt!.removeListener('close', cancel);
+    }
+  };
+  try {
+    if (interactive) {
+      const saved = await loadSettings(configPath(options));
+      options.endpoint = await ask('API endpoint', options.endpoint ?? process.env.LAMBDADB_ENDPOINT ?? saved.endpoint);
+      options.project = await ask('Existing project name', options.project ?? process.env.LAMBDADB_PROJECT ?? saved.project);
+      options.apiKeyEnv = await ask('Environment variable holding your API key (not its value)', options.apiKeyEnv ?? process.env.LAMBDADB_API_KEY_ENV ?? saved.apiKeyEnv ?? 'LAMBDADB_API_KEY');
+      output.protect(options.apiKeyEnv ? process.env[options.apiKeyEnv] : undefined);
+      output.diagnostic(`Detected agents (heuristic): ${detected.join(', ') || 'none'}. You may also select an undetected agent.`);
+      options.agents ??= await ask(`Agents: ${agentNames} (comma-separated), or none`, detected.join(',') || 'none');
+      const scopes = availableScopes(selectedAgents(options.agents));
+      options.scope ??= await ask(`Agent configuration scope: ${scopes.join(' or ')}`, scopes[0]);
+      if (options.writeTools === undefined) options.writeTools = (await ask('Enable MCP write tools? Type yes to opt in', 'no')) === 'yes';
+    }
+    const chosen = selectedAgents(options.agents);
+    if (!['project', 'user'].includes(options.scope ?? '')) throw new InputError('Specify --scope project or --scope user. CLI settings still use --config or the normal user configuration path.');
+    if (!availableScopes(chosen).includes(options.scope as AgentScope)) {
+      throw new InputError(`The selected agents do not all support --scope ${options.scope}. Use --scope ${availableScopes(chosen).join(' or --scope ')} or remove agents that do not support the selected scope.`);
+    }
+    // Use the existing precedence and validation for both saved settings and auth.
+    const selected = await settings(options, true);
+    options = { ...options, ...selected };
+    output.protect(process.env[selected.apiKeyEnv]);
+    if (!process.env[selected.apiKeyEnv]?.trim()) throw new InputError(`Export ${selected.apiKeyEnv} securely in this shell, then rerun init. Obtain a project API key in the LambdaDB Console; never pass its value as a flag.`);
+    const config = await resolveConfig(options, true);
+    const changes = await plan(selected, chosen, options.scope as AgentScope, options, context);
+    const files = changes.map(change => ({ path: change.path, ...(change.aliases.length ? { aliases: change.aliases } : {}), ...(change.destination !== change.path ? { destination: change.destination } : {}), kind: change.kind,
+      action: change.before === change.after ? 'unchanged' : change.before === undefined ? 'create' : 'update' }));
+    for (const file of files) output.diagnostic(`${file.action}: ${[file.path, ...(file.aliases ?? [])].join(', ')}${file.destination ? ` -> ${file.destination}` : ''} — ${file.kind}`);
+    output.diagnostic(`MCP: ${mcpPackage}; write tools ${options.writeTools ? 'enabled (explicit opt-in)' : 'disabled'}. Agents must inherit ${selected.apiKeyEnv}; only its name is stored.`);
+    if (interactive && (await ask('Apply these changes after verifying collection-list access? Type yes', 'no')) !== 'yes') {
+      throw new InputError('Init canceled. No files were changed.');
+    }
+    const ctx = runtime(config);
+    let connection;
+    try { connection = await checkConnection(ctx); } finally { ctx.close(); }
+    await apply(changes, options);
+    const nextSteps = [
+      `Restart/reload selected agents from an environment containing ${selected.apiKeyEnv} and npx on PATH. GUI launches may not inherit shell exports.`,
+      agentAdapters.filter(adapter => chosen.includes(adapter.id)).map(adapter => adapter.instructions).join(' '),
+      'Agent prompt: Use LambdaDB MCP to list collections, inspect the collection I choose, then read up to five documents at branch:main with query omitted. Help me search an actual indexed field. Do not create or modify data.',
+      'CLI alternative: run lambdadb collections list --json and lambdadb collections describe --collection NAME --json. Save {"size":5} in first-query.json, then run lambdadb query --collection NAME --ref branch:main --file first-query.json --json. Replace NAME with the collection you chose.',
+      'If the project has no collections/data, populate it deliberately outside init. Connection success does not establish search readiness.',
+    ];
+    return { ...connection, settings: selected, detectedAgents: detected, agents: chosen, scope: options.scope,
+      writeTools: !!options.writeTools, files, nextSteps };
+  } finally { prompt?.close(); }
+}

package/src/mcp.ts

@@ -0,0 +1,45 @@
+import { spawn } from 'node:child_process';
+import type { Config } from './config.js';
+import { InputError } from './errors.js';
+
+// Stable stdio package; this CLI only adapts credentials and process lifecycle.
+export const mcpPackage = '@functional-systems/lambdadb-mcp@0.1.4';
+
+export function mcpEnvironment(config: Config, writeTools: boolean): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    LAMBDADB_BASE_URL: config.endpoint,
+    LAMBDADB_PROJECT_NAME: config.project,
+    LAMBDADB_PROJECT_API_KEY: config.apiKey,
+    LAMBDADB_MCP_ENABLE_WRITE_TOOLS: String(writeTools),
+    LAMBDADB_DEBUG: 'false',
+  };
+}
+
+export async function serveMcp(config: Config, writeTools: boolean): Promise<number> {
+  // Never emit CLI results on stdout: it belongs exclusively to the MCP transport.
+  const child = spawn('npx', ['-y', mcpPackage], {
+    env: mcpEnvironment(config, writeTools), stdio: 'inherit', detached: process.platform !== 'win32',
+    // Windows needs the npm-provided .cmd launcher. Arguments contain no secrets.
+    ...(process.platform === 'win32' ? { shell: true } : {}),
+  });
+  const forward = (signal: NodeJS.Signals) => {
+    try {
+      if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal);
+      else child.kill(signal);
+    } catch { /* The child may already have exited. */ }
+  };
+  const interrupt = () => forward('SIGINT');
+  const terminate = () => forward('SIGTERM');
+  process.once('SIGINT', interrupt);
+  process.once('SIGTERM', terminate);
+  try {
+    return await new Promise<number>((resolve, reject) => {
+      child.once('error', () => reject(new InputError('Cannot start npx. Install Node.js/npm and make npx available on the agent PATH.')));
+      child.once('exit', (code, signal) => resolve(code ?? (signal === 'SIGINT' ? 130 : 143)));
+    });
+  } finally {
+    process.removeListener('SIGINT', interrupt);
+    process.removeListener('SIGTERM', terminate);
+  }
+}

package/src/runtime.ts

@@ -38,3 +38,12 @@ export function runtime(config: Config) {
     },
   };
 }
+
+// Both doctor and init verify access without implying collection/query readiness.
+export async function checkConnection(ctx: Pick<ReturnType<typeof runtime>, 'client' | 'options'>) {
+  await ctx.client.listCollections({ size: 1 }, ctx.options);
+  return { checks: [
+    { name: 'configuration', status: 'passed' },
+    { name: 'authentication_and_project_collection_list', status: 'passed' },
+  ], writesVerified: false, queryReadinessVerified: false };
+}