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

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+### Added
+
+- First-use `init` for existing projects, with interactive guidance and an explicit
+  non-interactive path. Verify collection-list access and optionally configure
+  Codex, Claude Code, Cursor, VS Code, Gemini CLI, OpenCode, GitHub Copilot CLI,
+  Kiro IDE/CLI or the Cline VS Code extension (user scope) and a bundled LambdaDB
+  usage skill. Agent adapters preserve existing configuration and keep
+  environment forwarding specific to each tool.
+- Deduplicate identical shared MCP/skill file updates across selected agents;
+  reject conflicting plans and unsupported agent scopes before connection or writes.
+- Runtime-only credential forwarding to the existing read-only-by-default stdio
+  MCP package through `lambdadb mcp`; no key values are persisted. Existing CLI
+  commands remain non-interactive. Search readiness is not inferred from setup.
+
 ### Maintenance
 
 - Synchronize the 0.1.4 release history and start the 0.1.5 development line.

package/CONTRIBUTING.md

@@ -90,6 +90,26 @@ live-service readiness. See [README.md](README.md) for public behavior and the
 
 ## Compatibility and maintenance
 
+Agent integrations live in the `agentAdapters` registry in `src/agents.ts`.
+Each adapter owns detection directories and executable names, supported scopes, project/user
+paths, MCP configuration generation (including environment forwarding), optional
+skill path, and restart instructions. Add an adapter there to extend init's
+selection, detection and help; keep authentication, file planning and atomic
+writes in `src/init.ts`. `src/agent-config.ts` provides shared CLI launch
+arguments and JSONC/TOML editors that preserve unrelated settings. MCP
+configuration generation receives the key's variable name, never its value.
+An MCP-only adapter can omit the skill path.
+An adapter that cannot configure project MCP settings declares `scopes: ['user']`;
+init rejects unsupported flags and offers only shared supported scopes interactively.
+Identical changes to the same canonical path are combined; conflicting contents
+or CLI-settings overlaps fail before connection or writes. Copilot/Cline adapters
+use the strict JSON editor rather than silently removing comments.
+
+Before adding an agent, verify its documented formats and environment forwarding,
+then cover both scopes, unrelated configuration preservation, conflicts, reruns
+and secret handling through the CLI tests. Test real agent startup separately;
+configuration generation alone is not a successful connection.
+
 Treat documented flags, JSON schema, exit codes, explicit target selection and
 failure semantics as public contracts. Add regression coverage for changes to
 these behaviors; do not script against human summaries. Update the changelog
@@ -114,6 +134,13 @@ repository's runtime matrix or release tooling without checking this CLI's needs
   that artifact. To check an existing candidate, use
   `npm run test:package -- /path/to/package.tgz`. Building test sources alone is
   not evidence that tests executed.
+- Init contracts run in temporary home/project directories against loopback
+  collection-list responses. They cover configuration/comment preservation,
+  reruns, conflicts, scope, secret handling and non-interactive failures. An npx
+  stub verifies stdio launch, credential mapping and write opt-in without fetching
+  or running an agent. The packaged suite repeats these contracts and verifies
+  the bundled skill. These checks do not establish actual agent MCP connection,
+  live authentication or document search readiness.
 - [Homebrew validation](packaging/homebrew/README.md#local-and-ci-verification)
   checks the stable formula's installation and released CLI contracts on macOS
   and Linux. A new installation does not establish an existing-user upgrade;

package/README.md

@@ -88,6 +88,208 @@ printf '\n'
 export LAMBDADB_API_KEY
 ```
 
+### First-use setup with `init`
+
+After securely exporting the key, run either entry point. Both use this same
+package and executable:
+
+```sh
+lambdadb init
+npx @functional-systems/lambdadb-cli@latest init
+```
+
+`init` guides you through the existing project's endpoint, name and API-key
+environment-variable name. It detects Codex, Claude Code, Cursor, VS Code,
+Gemini CLI, OpenCode, GitHub Copilot CLI, Kiro IDE/CLI and the Cline VS Code
+extension using PATH and configuration directories, then lets you choose any subset (or `none`),
+project/user scope, and whether to enable MCP write tools. Detection is a hint,
+not proof that an agent is installed or connected. Project scope means the
+current working directory; run from your repository root.
+Cursor detection recognizes both the editor's `cursor` command and the
+`cursor-agent` CLI, which reads the same MCP configuration. With Cursor CLI,
+check the generated server with `cursor-agent mcp list-tools lambdadb`.
+
+The remaining manual step is in [LambdaDB Console](https://console.lambdadb.ai):
+select an existing project and obtain its API endpoint, project name and project
+API key. Inject the key into your shell or secret manager before running init.
+There is no browser login, account/project creation, key issuance, remote MCP,
+or backend/Console change in this flow. Init never asks for the key value and
+does not load or write `.env` files.
+
+For automation, explicitly select both agents and scope:
+
+```sh
+# Inject LAMBDADB_API_KEY securely before running this command.
+lambdadb init --non-interactive --agents codex,claude,cursor --scope project \
+  --endpoint https://api.lambdadb.ai --project YOUR_PROJECT --json
+# Configure only the CLI, without changing agent files:
+lambdadb init --non-interactive --agents none --scope project \
+  --endpoint https://api.lambdadb.ai --project YOUR_PROJECT --api-key-env MY_PROJECT_KEY
+```
+
+`--agents` accepts a comma-separated subset of
+`codex,claude,cursor,vscode,gemini,opencode,copilot,kiro,cline` or `none`. For example:
+
+```sh
+lambdadb init --non-interactive --agents vscode,gemini,opencode --scope project
+lambdadb init --non-interactive --agents copilot,kiro,cline --scope user
+```
+
+This example reuses your existing CLI settings and environment-held key.
+`--scope` accepts `project` or `user`. `--write-tools` explicitly enables MCP
+write tools; omission disables them, including on reruns and when the inherited
+`LAMBDADB_MCP_ENABLE_WRITE_TOOLS` environment variable is true. The normal global
+`--config`, `--endpoint`, `--project`, `--api-key-env`, and `--timeout-ms` flags
+apply. Existing settings/environment precedence is unchanged. Non-TTY and
+`--json` runs require `--non-interactive`; missing choices, target or key fail
+with exit 2 and instructions, without prompting. This mode authorizes applying
+the displayed file plan; it does not silently select detected agents.
+Cline's extension supports only user-scope MCP settings. Selecting `cline` with
+`--scope project` fails before any file writes or connection; interactive setup
+offers user scope when Cline is selected. It never silently broadens the scope.
+
+Before writing, init displays exact paths and create/update/unchanged actions,
+then uses the same SDK check as `doctor` to verify authentication and collection-list
+access. Failed validation/authentication leaves files untouched. The CLI's
+non-secret settings always use its usual configuration path (or `--config`),
+independently of agent scope:
+
+| Agent | Project MCP / skill | User MCP / skill |
+| --- | --- | --- |
+| Codex | `.codex/config.toml` / `.agents/skills/lambdadb/SKILL.md` | `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) / `~/.agents/skills/lambdadb/SKILL.md` |
+| Claude Code | `.mcp.json` / `.claude/skills/lambdadb/SKILL.md` | `~/.claude.json` / `~/.claude/skills/lambdadb/SKILL.md` |
+| Cursor | `.cursor/mcp.json` / `.cursor/skills/lambdadb/SKILL.md` | `~/.cursor/mcp.json` / `~/.cursor/skills/lambdadb/SKILL.md` |
+| VS Code | `.vscode/mcp.json` / `.github/skills/lambdadb/SKILL.md` | Default profile `mcp.json` (see below) / `~/.copilot/skills/lambdadb/SKILL.md` |
+| Gemini CLI | `.gemini/settings.json` / `.gemini/skills/lambdadb/SKILL.md` | `~/.gemini/settings.json` / `~/.gemini/skills/lambdadb/SKILL.md` |
+| OpenCode | `opencode.json` or existing `opencode.jsonc` / `.opencode/skills/lambdadb/SKILL.md` | `~/.config/opencode/opencode.json` or existing `.jsonc` / `~/.config/opencode/skills/lambdadb/SKILL.md` |
+| GitHub Copilot CLI | `.mcp.json` or existing `.github/mcp.json` / `.github/skills/lambdadb/SKILL.md` | `~/.copilot/mcp-config.json` / `~/.copilot/skills/lambdadb/SKILL.md` |
+| Kiro IDE/CLI | `.kiro/settings/mcp.json` / `.kiro/skills/lambdadb/SKILL.md` | `~/.kiro/settings/mcp.json` / `~/.kiro/skills/lambdadb/SKILL.md` |
+| Cline VS Code extension | Unsupported; choose user scope | VS Code user profile `globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` / `~/.cline/skills/lambdadb/SKILL.md` |
+
+When `CLAUDE_CONFIG_DIR` is set, Claude's user MCP file is
+`$CLAUDE_CONFIG_DIR/.claude.json` and its user skill is under
+`$CLAUDE_CONFIG_DIR/skills/lambdadb/SKILL.md`.
+
+Gemini's `GEMINI_CLI_HOME` replaces the home directory, with `.gemini` appended;
+both user settings and the skill follow it. OpenCode's user config and skill
+respect `XDG_CONFIG_HOME` (default `~/.config`). Existing OpenCode JSONC files
+are edited in place. If both `opencode.json` and `opencode.jsonc` exist in the
+chosen scope, init asks you to consolidate them before proceeding. It preserves
+existing V2 `mcp.servers` maps; new files use V1 `mcp` syntax, which V2 also
+supports. A mixed V1 LambdaDB entry and V2 server map is rejected for manual
+resolution. Custom `OPENCODE_CONFIG`, `OPENCODE_CONFIG_DIR`, inline or
+higher-priority project settings may override the selected root/user file.
+
+VS Code uses the documented `servers` format for its Local harness, with
+project scope at `.vscode/mcp.json`. User scope targets the default stable
+profile: `~/Library/Application Support/Code/User/mcp.json` on macOS,
+`${XDG_CONFIG_HOME:-$HOME/.config}/Code/User/mcp.json` on Linux, and
+`%APPDATA%/Code/User/mcp.json` on Windows (fallback `%USERPROFILE%/AppData/Roaming`).
+`VSCODE_PORTABLE` and `VSCODE_APPDATA` overrides are honored. Named profiles,
+Insiders, `--user-data-dir`, remote hosts and portable Copilot configuration are
+outside this adapter's scope. Reload the window and use **MCP: List Servers**.
+In Gemini, restart or use `/mcp refresh` and `/skills reload`; in OpenCode,
+restart and use `opencode mcp list`. Preserve normal trust/approval prompts.
+
+Copilot CLI is separate from the VS Code adapter. It reads `mcpServers`, not
+VS Code's `servers` map. Project setup reuses `.mcp.json` if present, otherwise
+an existing `.github/mcp.json`, otherwise creates `.mcp.json`. Both wrapped
+`mcpServers` and existing bare server maps are preserved. `COPILOT_HOME` overrides
+the user MCP and skill directory. Restart with the selected key in the launch
+environment, trust the repository, check `/mcp`, and run `/skills reload`.
+
+Kiro IDE and CLI share one `kiro` adapter; detection recognizes both `kiro` and
+`kiro-cli` executables. Approve the selected key variable in **Mcp Approved Env
+Vars** when prompted. For a custom Kiro agent, ensure it includes the MCP JSON
+and skill resources; init does not edit agent definitions or grant tool approvals.
+
+The `cline` adapter targets the Cline extension in the default stable VS Code
+user profile, using the same platform/portable user directory rules above.
+Reload VS Code from an environment containing the selected key and inspect
+Cline's MCP Servers and Skills menus. Cline CLI, other editors and named profiles
+use different configuration locations and are outside this adapter's scope.
+
+Unrelated configuration and comments are preserved where JSONC is accepted.
+Copilot and Cline settings must be strict JSON for init; comments/trailing
+commas cause an actionable failure and leave the file untouched. Shared files
+(such as Claude/Copilot project MCP and VS Code/Copilot skills) are written only
+once when both agents request identical contents; conflicting changes stop
+before connection or writes. Symbolic links are preserved: init displays the
+resolved write target and updates it once. Links with missing targets fail before
+connection or writes; restore their targets before rerunning init.
+Reruns update only recognizable init-generated `lambdadb` MCP entries;
+existing custom entries or additions inside a generated entry cause an actionable
+conflict. Existing skills are preserved, including user edits; remove the skill
+file deliberately if you want to reinstall the bundled version. Writes use
+atomic replacement per file, not a transaction across files: a disk/permission
+failure can leave a partial installation; inspect the displayed paths and rerun.
+
+Agent settings launch `npx -y @functional-systems/lambdadb-cli@<installed-version> mcp`,
+which runs the existing `@functional-systems/lambdadb-mcp@0.1.4` stdio package.
+No npx cache path is saved. The exact CLI version must be published before an
+agent can fetch it; a source checkout/unpublished tarball alone does not provide
+that registry version. Node/npm and `npx` must be on the agent's PATH; first launch
+may download both packages and requires npm registry access.
+
+The `mcp` bridge reads the selected key from the agent environment at startup and
+maps CLI endpoint/project/key to MCP's `LAMBDADB_BASE_URL`,
+`LAMBDADB_PROJECT_NAME`, and `LAMBDADB_PROJECT_API_KEY`. The bridge sets
+`LAMBDADB_MCP_ENABLE_WRITE_TOOLS` explicitly. No key value is placed in arguments
+or configuration. Codex uses `env_vars` to forward the selected variable;
+Claude, Gemini, Copilot and Kiro use `${VAR}`; Cursor, VS Code and Cline use `${env:VAR}`; and
+OpenCode uses `{env:VAR}` environment references. Gemini's explicit `env` entry
+also forwards the key through its inherited-environment sanitization. An unresolved
+reference fails before starting MCP. Keep the variable in the agent launch
+environment: GUI apps may not inherit a terminal export. Restart/reload agents
+after setup or credential changes, check `/mcp` in Codex/Claude or Cursor's MCP
+settings, and approve/trust project settings if prompted. Higher-priority agent
+settings or organization policies may override or block these files.
+
+The no-secret-persistence contract covers files written by this CLI. Agents
+manage their own runtime storage; for example, Codex shell snapshots can capture
+the launch environment. Review your agent's environment/snapshot settings and
+protect its runtime directory when forwarding a project key.
+
+Init does not query documents or create collections/data. Connection success does
+not establish search readiness. Its result includes a read-only agent prompt:
+list collections, inspect the selected collection's index configuration, then
+read up to five documents at `branch:main` with `query` omitted before searching
+an actual indexed field. Without an agent, run `lambdadb collections list --json`,
+choose an existing collection, save `{"size":5}` in `first-query.json`, and run:
+
+```sh
+lambdadb collections describe --collection YOUR_COLLECTION --json
+lambdadb query --collection YOUR_COLLECTION --ref branch:main --file first-query.json --json
+```
+
+An empty project needs deliberately supplied data outside init. Empty results
+are not evidence of indexing failure or readiness.
+
+Agent formats were checked against official documentation on 2026-10-24:
+[Codex MCP](https://developers.openai.com/codex/mcp),
+[Codex skills](https://developers.openai.com/codex/skills),
+[Claude Code MCP](https://code.claude.com/docs/en/mcp),
+[Claude Code skills](https://code.claude.com/docs/en/skills),
+[Cursor MCP](https://cursor.com/docs/mcp),
+[Cursor CLI MCP](https://cursor.com/docs/cli/mcp),
+[Cursor skills](https://cursor.com/docs/skills),
+[VS Code MCP](https://code.visualstudio.com/docs/agents/reference/mcp-configuration),
+[VS Code skills](https://code.visualstudio.com/docs/agent-customization/agent-skills),
+[Gemini MCP](https://geminicli.com/docs/tools/mcp-server/),
+[Gemini skills](https://geminicli.com/docs/cli/skills/),
+[OpenCode MCP](https://opencode.ai/docs/mcp-servers/),
+[OpenCode skills](https://opencode.ai/docs/skills/),
+[OpenCode V2 compatibility](https://opencode.ai/v2/docs/migrate-v1/),
+[Copilot MCP](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers),
+[Copilot skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills),
+[Kiro MCP](https://kiro.dev/docs/mcp/configuration/),
+[Kiro skills](https://kiro.dev/docs/skills/),
+[Cline MCP](https://docs.cline.bot/mcp/mcp-overview),
+[Cline skills](https://docs.cline.bot/customization/skills), and
+[Cline environment expansion source](https://github.com/cline/cline/blob/main/apps/vscode/src/utils/envExpansion.ts).
+Generated settings still require
+verification in the actual agent; local contract tests simulate that boundary.
+
 No command accepts a raw key argument. Configuration stores only `endpoint`,
 `project` and `apiKeyEnv`. Keys are read from the selected environment variable at
 runtime and are never persisted by this CLI. Environment variables are still
@@ -112,7 +314,10 @@ Use a CI secret manager instead of adding credentials to tracked files.
 
 There is no implicit endpoint, project, collection, branch or read ref. Explicit
 empty values fail validation instead of silently falling back. An explicitly
-selected missing config file fails except when `configure` creates it.
+selected missing config file fails for existing commands except `configure`,
+which can create it. `init` can also create it; the `mcp` bridge allows a missing
+file when endpoint/project settings are supplied through flags or environment.
+
 `configure` applies the same precedence and saves the selected non-secret values;
 it does not contact the service. To reference a different secret variable:
 
@@ -396,7 +601,9 @@ collection and explicit ref/branch. Errors use stable categories and safe hints.
 API-specific response data may grow as the upstream API evolves. Help/version
 remain plain text even with `--json`. Default output adds a readable summary and
 pretty-printed data. Progress and diagnostics go only to stderr. No ANSI styling
-or interactive prompts are used.
+is used. Only `init` prompts on a terminal; `init --non-interactive` and all
+existing commands never prompt. `mcp` reserves stdout for MCP JSON-RPC and sends
+startup failures to stderr rather than emitting the CLI JSON envelope.
 
 Credential redaction preserves fixed protocol field names and command, status,
 ref-kind and error-code tokens, even when a short credential coincides with one
@@ -453,7 +660,7 @@ methods and their limits.
 
 This MVP intentionally omits Branch/Tag/Alias management: default `main` supports
 first use, while reads can select existing refs. It also omits Console management,
-MCP, Git collection, chunking, embedding workflows, code-search logic, delete,
+remote MCP, Git collection, chunking, embedding workflows, code-search logic, delete,
 plugins and publication. There are no changes to the SDK or reference repositories.
 
 Live verification requires an explicitly designated development project, endpoint

package/dist/agent-config.d.ts

@@ -0,0 +1,21 @@
+import type { Settings } from './config.js';
+export type McpLaunch = {
+    command: string;
+    args: string[];
+    apiKeyEnv: string;
+};
+type Server = {
+    command: string | string[];
+    args?: string[];
+    env_vars?: string[];
+    env?: Record<string, string>;
+    environment?: Record<string, string>;
+    type?: string;
+};
+type ServerFactory = (launch: McpLaunch) => Server;
+type JsonMapPath = readonly string[] | ((value: Record<string, unknown>) => readonly string[]);
+export declare function mcpLaunch(selected: Required<Settings>, writeTools: boolean, cliVersion: string): McpLaunch;
+export declare function jsonConfig(path: string, text: string | undefined, launch: McpLaunch, createServer: ServerFactory, mapPath?: JsonMapPath): string;
+export declare function strictJsonConfig(path: string, text: string | undefined, launch: McpLaunch, createServer: ServerFactory, mapPath?: JsonMapPath): string;
+export declare function tomlConfig(path: string, text: string | undefined, launch: McpLaunch, createServer: ServerFactory): string;
+export {};

package/dist/agent-config.js

@@ -0,0 +1,124 @@
+import { applyEdits, modify, parse as parseJson } from 'jsonc-parser';
+import { parse as parseToml } from 'smol-toml';
+import { InputError } from './errors.js';
+const begin = '# BEGIN lambdadb init';
+const end = '# END lambdadb init';
+export function mcpLaunch(selected, writeTools, cliVersion) {
+    return { command: 'npx', apiKeyEnv: selected.apiKeyEnv,
+        args: ['-y', `@functional-systems/lambdadb-cli@${cliVersion}`, 'mcp',
+            '--endpoint', selected.endpoint, '--project', selected.project, '--api-key-env', selected.apiKeyEnv,
+            ...(writeTools ? ['--write-tools'] : [])] };
+}
+function object(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+// Only entries generated by init may be updated. User additions to our entry
+// cause a conflict instead of silently dropping their settings.
+function managedServer(value, createServer) {
+    if (!object(value))
+        return false;
+    const command = Array.isArray(value.command) ? value.command[0] : value.command;
+    const a = Array.isArray(value.command) ? value.command.slice(1) : value.args;
+    if (command !== 'npx' || !Array.isArray(a))
+        return false;
+    if (a.some(v => typeof v !== 'string') || !/^@functional-systems\/lambdadb-cli@[\w.+-]+$/.test(a[1] ?? '')
+        || a[0] !== '-y' || a[2] !== 'mcp' || a[3] !== '--endpoint' || a[5] !== '--project'
+        || a[7] !== '--api-key-env' || ![9, 10].includes(a.length) || (a.length === 10 && a[9] !== '--write-tools'))
+        return false;
+    const expected = createServer({ command: 'npx', args: a, apiKeyEnv: a[8] });
+    return Object.keys(value).length === Object.keys(expected).length
+        && Object.entries(expected).every(([key, item]) => JSON.stringify(value[key]) === JSON.stringify(item));
+}
+function conflict(path) {
+    throw new InputError(`Existing LambdaDB configuration in ${path} was not generated by init or has been edited. Preserve or rename that entry before rerunning init; no overwrite was performed.`);
+}
+export function jsonConfig(path, text, launch, createServer, mapPath = ['mcpServers']) {
+    const errors = [];
+    const value = parseJson(text ?? '{}', errors, { allowTrailingComma: true });
+    if (errors.length || !object(value)) {
+        throw new InputError(`Invalid agent JSON configuration: ${path}. Fix it before rerunning init.`);
+    }
+    const keys = typeof mapPath === 'function' ? mapPath(value) : mapPath;
+    let container = value;
+    for (const key of keys) {
+        const child = container[key];
+        if (child !== undefined && !object(child)) {
+            throw new InputError(`Invalid agent JSON configuration: ${path}. ${keys.join('.')} must contain objects.`);
+        }
+        container = (child ?? {});
+    }
+    const previous = container.lambdadb;
+    if (previous !== undefined && !managedServer(previous, createServer))
+        conflict(path);
+    const desired = createServer(launch);
+    if (JSON.stringify(previous) === JSON.stringify(desired))
+        return text;
+    const source = text ?? '{}\n';
+    return applyEdits(source, modify(source, [...keys, 'lambdadb'], desired, {
+        formattingOptions: { insertSpaces: true, tabSize: 2 },
+    }));
+}
+export function strictJsonConfig(path, text, launch, createServer, mapPath = ['mcpServers']) {
+    try {
+        JSON.parse(text ?? '{}');
+    }
+    catch {
+        throw new InputError(`Init requires strict JSON for ${path}. Remove comments or trailing commas before rerunning init.`);
+    }
+    return jsonConfig(path, text, launch, createServer, mapPath);
+}
+function tomlBlock(value) {
+    return `${begin}\n[mcp_servers.lambdadb]\ncommand = "npx"\nargs = ${JSON.stringify(value.args)}\nenv_vars = ${JSON.stringify(value.env_vars)}\n${end}\n`;
+}
+export function tomlConfig(path, text, launch, createServer) {
+    const source = text ?? '';
+    let parsed;
+    try {
+        parsed = parseToml(source);
+    }
+    catch {
+        throw new InputError(`Invalid agent TOML configuration: ${path}. Fix it before rerunning init.`);
+    }
+    const servers = parsed.mcp_servers;
+    if (servers !== undefined && !object(servers))
+        conflict(path);
+    const previous = object(servers) ? servers.lambdadb : undefined;
+    const block = tomlBlock(createServer(launch));
+    const start = source.indexOf(begin);
+    let after;
+    if (start < 0) {
+        if (previous !== undefined || source.includes(end))
+            conflict(path);
+        after = source + (source.endsWith('\n') || !source ? '' : '\n') + '\n' + block;
+    }
+    else {
+        const finish = source.indexOf(end, start);
+        if (finish < 0 || source.indexOf(begin, start + begin.length) >= 0 || source.indexOf(end, finish + end.length) >= 0
+            || !managedServer(previous, createServer))
+            conflict(path);
+        const stop = finish + end.length + (source[finish + end.length] === '\n' ? 1 : 0);
+        // Refuse to remove any unrelated sections/settings hidden inside markers.
+        let managed;
+        try {
+            managed = parseToml(source.slice(start, stop));
+        }
+        catch {
+            conflict(path);
+        }
+        if (Object.keys(managed).length !== 1 || !object(managed.mcp_servers)
+            || Object.keys(managed.mcp_servers).length !== 1 || !managedServer(managed.mcp_servers.lambdadb, createServer))
+            conflict(path);
+        if (source.slice(start, stop) !== tomlBlock(previous))
+            conflict(path);
+        after = source.slice(0, start) + block + source.slice(stop);
+    }
+    // Appending a table is unsafe when an existing inline table seals mcp_servers.
+    try {
+        parseToml(after);
+    }
+    catch {
+        throw new InputError(`Cannot safely add LambdaDB to ${path}. Expand inline MCP tables before rerunning init.`);
+    }
+    return after;
+}
+//# sourceMappingURL=agent-config.js.map

package/dist/agent-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config.js","sourceRoot":"","sources":["../src/agent-config.ts"],"names":[],"mappings":"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"}

package/dist/agents.d.ts

@@ -0,0 +1,113 @@
+import { type McpLaunch } from './agent-config.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;
+};
+declare function opencodePaths(scope: AgentScope, context: AgentContext): Promise<AgentPaths>;
+declare function copilotPaths(scope: AgentScope, context: AgentContext): Promise<AgentPaths>;
+export declare const agentAdapters: readonly [{
+    readonly id: "codex";
+    readonly executable: "codex";
+    readonly detectionDirectories: ({ cwd, home, env }: AgentContext) => string[];
+    readonly paths: (scope: AgentScope, { cwd, home, env }: AgentContext) => {
+        mcp: string;
+        skill: string;
+    };
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly instructions: "Codex: trust the project if using project scope, start a new session, and check /mcp.";
+}, {
+    readonly id: "claude";
+    readonly executable: "claude";
+    readonly detectionDirectories: ({ cwd, home, env }: AgentContext) => string[];
+    readonly paths: (scope: AgentScope, { cwd, home, env }: AgentContext) => {
+        mcp: string;
+        skill: string;
+    };
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly instructions: "Claude Code: restart and approve the project MCP server if prompted; check /mcp.";
+}, {
+    readonly id: "cursor";
+    readonly executable: readonly ["cursor", "cursor-agent"];
+    readonly detectionDirectories: ({ cwd, home }: AgentContext) => string[];
+    readonly paths: (scope: AgentScope, { cwd, home }: AgentContext) => {
+        mcp: string;
+        skill: string;
+    };
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly instructions: "Cursor: restart/reload and check MCP settings.";
+}, {
+    readonly id: "vscode";
+    readonly executable: "code";
+    readonly detectionDirectories: (context: AgentContext) => string[];
+    readonly paths: (scope: AgentScope, context: AgentContext) => {
+        mcp: string;
+        skill: string;
+    };
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly 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.";
+}, {
+    readonly id: "gemini";
+    readonly executable: "gemini";
+    readonly detectionDirectories: (context: AgentContext) => string[];
+    readonly paths: (scope: AgentScope, context: AgentContext) => {
+        mcp: string;
+        skill: string;
+    };
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly instructions: "Gemini CLI: restart or run /mcp refresh and /skills reload, trust the workspace if prompted, and check /mcp and /skills list.";
+}, {
+    readonly id: "opencode";
+    readonly executable: "opencode";
+    readonly detectionDirectories: (context: AgentContext) => string[];
+    readonly paths: typeof opencodePaths;
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly 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.";
+}, {
+    readonly id: "copilot";
+    readonly executable: "copilot";
+    readonly detectionDirectories: (context: AgentContext) => string[];
+    readonly paths: typeof copilotPaths;
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly 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.";
+}, {
+    readonly id: "kiro";
+    readonly executable: readonly ["kiro", "kiro-cli"];
+    readonly detectionDirectories: ({ cwd, home }: AgentContext) => string[];
+    readonly paths: (scope: AgentScope, { cwd, home }: AgentContext) => {
+        mcp: string;
+        skill: string;
+    };
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly 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.";
+}, {
+    readonly id: "cline";
+    readonly executable: readonly [];
+    readonly scopes: readonly ["user"];
+    readonly detectionDirectories: (context: AgentContext) => string[];
+    readonly paths: (_scope: AgentScope, context: AgentContext) => {
+        mcp: string;
+        skill: string;
+    };
+    readonly configure: (path: string, text: string | undefined, launch: McpLaunch) => string;
+    readonly 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.";
+}];
+export type Agent = typeof agentAdapters[number]['id'];
+export declare const agentNames: string;
+export declare function detectAgents(context: AgentContext): Promise<Agent[]>;
+export {};