heedvane 0.2.1 → 0.3.4

package/dist/mcp.d.ts

@@ -1,57 +1,47 @@
 /**
- * MCP registration entry builder per client.
+ * Heedvane's MCP connection: the one MCP entry the installer registers, named `heedvane`, pointing at
+ * the organization's remote server (`<server>/api/mcp/<org>`). Remote entries take the shapes the dashboard's
+ * setup writes (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`); Claude Desktop's mcp-remote bridge
+ * (`bridgeEntry`, with the installing Node's folder) is this CLI's own. The agent signs in in the browser on first use.
  *
- * The heedvane MCP server is the universal integration channel — and the only
- * policy channel for agents with no native hooks (Warp). Entries are stdio
- * commands (`npx heedvane mcp`); an `--http` mode may be added later
- * without changing the shape of these builders.
- *
- * Identity: uninstall and marker detection recognize our entries by the
- * identity markers below (today's `npx -y heedvane mcp` args, plus the
- * scoped and `heedvane-hooks` names development installs wrote), or by the
- * reserved entry name `heedvane`.
+ * Identity: uninstall and detection recognize an entry by its name and shape together, never by a name
+ * alone: today's connection, the local helper earlier versions registered (`npx -y heedvane mcp`, under any
+ * name) and the connection under its earlier name `heedvane-findings`. Connect replaces the earlier ones.
  */
-/** Reserved server entry name. Presence of this NAME alone marks the entry ours. */
+/** The entry's name in every agent's MCP config. */
 export declare const HEEDVANE_SERVER_NAME = "heedvane";
-/**
- * Identity markers: an entry whose command/args contain any of these strings
- * is a heedvane-managed entry, whatever name it is registered under. These are
- * the names development builds wrote; today's entry is recognized by its whole
- * argument list ({@link MCP_ENTRY_ARGS}), since the bare package name would
- * also match a path like `~/Projects/heedvane`.
- */
-export declare const IDENTITY_MARKERS: readonly ["@heedvane/hooks", "heedvane-hooks"];
+/** Why metrics only registers no MCP connection: its tools send questions and repository names to Heedvane. */
+export declare const MCP_OFF_METRICS_ONLY = "Heedvane's MCP connection: off under Metrics only, since its tools send your questions and repository names to Heedvane";
+/** What to do when no organization is known, so no MCP connection can be registered. */
+export declare const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx -y heedvane connect --org <id>";
+/** How to add the organization: `setup` cannot, since it compiles heed.yaml as it is. */
+export declare const ORG_REMEDIATION = "run the connect command from your dashboard's Settings, or npx -y heedvane connect --org <organization id>";
 /** Uninstall/detection marker for inline dispatcher snippets (hooks configs). */
 export declare const SNIPPET_MARKER = "heedvane-agent-hook-form";
-/** Args of the stdio MCP entry (command is always `npx`). */
-export declare const MCP_ENTRY_ARGS: string[];
-export interface McpServerEntry {
-    command: string;
-    args: string[];
-    [key: string]: unknown;
-}
-/** The stdio MCP entry, for JSON-family configs (`mcpServers` / `servers` / `mcp`). */
-export declare function mcpEntry(): McpServerEntry;
-/**
- * The stdio MCP entry for TOML configs. Codex reads `~/.codex/config.toml`
- * where servers are `mcp_servers.<name>` and a slow `npx` cold start needs an
- * explicit generous startup timeout.
- */
-export declare function mcpEntryForToml(): McpServerEntry;
-/** Per-client desired entry. Only Codex (TOML) carries the startup timeout. */
-export declare function desiredServer(clientId: string): McpServerEntry;
-/** Warp's MCP config is project-level and approval-gated. */
-export declare const WARP_MCP_RELATIVE_PATH = ".warp/.mcp.json";
-/**
- * Honest limitation surfaced by init/doctor for Warp. Warp has no native
- * hooks and its MCP support is project-scoped and import-gated: the user must
- * approve the import in Warp, per project, before the server activates.
- * Policies therefore arrive via MCP tools, not hooks.
- */
-export declare const WARP_MCP_LIMITATION: string;
+/** The connection's URL for an organization, as the dashboard builds it (`buildHeedvaneMcpUrl`). */
+export declare function connectorUrl(server: string, org: string): string;
 /**
- * Is this server entry a heedvane-managed one? True when the entry NAME is
- * the reserved `heedvane` name, or when the entry's command/args carry an
- * identity marker. Used by detectMarker and doctor.
+ * The entry as drift checks compare it: a bridge's installing-Node folder is left out, since the launcher finds a Node
+ * without it, and connect run from another Node is no change to the connection.
  */
+export declare function comparableEntry(entry: unknown): unknown;
+/** The variable a software factory holds its organization API key in; the dashboard's factory commands use it. */
+export declare const ORG_KEY_ENV = "HEEDVANE_ORG_KEY";
+/** The software-factory connection entry for this agent; undefined where it keeps the browser sign-in. */
+export declare function keyConnectorEntry(clientId: string, url: string): Record<string, unknown> | undefined;
+/** The connection entry for this agent, or undefined when the installer does not register it there. `nodeDir` (POSIX only) is the installing Node's folder, for an entry that runs a local bridge. */
+export declare function connectorEntry(clientId: string, url: string, nodeDir?: string): Record<string, unknown> | undefined;
+/** The organization an entry's Heedvane MCP URL names at `server`, if it points there. */
+export declare function connectorOrganization(entry: unknown, server: string): string | undefined;
+/** The strings an entry names a server URL with: any agent's URL field, or a bridge's arguments. */
+export declare function entryUrls(entry: unknown): string[];
+/** Is this today's connection entry? Its name and a Heedvane MCP URL both have to match. */
+export declare function isConnectorEntry(name: string, entry: unknown): boolean;
+/** Is this an entry an earlier version wrote: the local helper under any name, or the connection under its earlier name? */
+export declare function isLegacyEntry(name: string, entry: unknown): boolean;
+/** Does this entry run the local helper an earlier version registered, under any name? */
+export declare function isHelperEntry(_name: string, entry: unknown): boolean;
+/** Is this server entry Heedvane's, today's or an earlier version's? Used by uninstall, detection and doctor. */
 export declare function isHeedvaneEntry(name: string, entry: unknown): boolean;
+/** Names of the entries `match` accepts in a parsed config's MCP containers, as `container::name`. */
+export declare function mcpEntryNames(doc: Record<string, unknown>, containerKeys: string[], match: (name: string, entry: unknown) => boolean): string[];

package/dist/mcp.js

@@ -1,83 +1,216 @@
 /**
- * MCP registration entry builder per client.
+ * Heedvane's MCP connection: the one MCP entry the installer registers, named `heedvane`, pointing at
+ * the organization's remote server (`<server>/api/mcp/<org>`). Remote entries take the shapes the dashboard's
+ * setup writes (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`); Claude Desktop's mcp-remote bridge
+ * (`bridgeEntry`, with the installing Node's folder) is this CLI's own. The agent signs in in the browser on first use.
  *
- * The heedvane MCP server is the universal integration channel — and the only
- * policy channel for agents with no native hooks (Warp). Entries are stdio
- * commands (`npx heedvane mcp`); an `--http` mode may be added later
- * without changing the shape of these builders.
- *
- * Identity: uninstall and marker detection recognize our entries by the
- * identity markers below (today's `npx -y heedvane mcp` args, plus the
- * scoped and `heedvane-hooks` names development installs wrote), or by the
- * reserved entry name `heedvane`.
+ * Identity: uninstall and detection recognize an entry by its name and shape together, never by a name
+ * alone: today's connection, the local helper earlier versions registered (`npx -y heedvane mcp`, under any
+ * name) and the connection under its earlier name `heedvane-findings`. Connect replaces the earlier ones.
  */
-/** Reserved server entry name. Presence of this NAME alone marks the entry ours. */
+/** The entry's name in every agent's MCP config. */
 export const HEEDVANE_SERVER_NAME = "heedvane";
-/**
- * Identity markers: an entry whose command/args contain any of these strings
- * is a heedvane-managed entry, whatever name it is registered under. These are
- * the names development builds wrote; today's entry is recognized by its whole
- * argument list ({@link MCP_ENTRY_ARGS}), since the bare package name would
- * also match a path like `~/Projects/heedvane`.
- */
-export const IDENTITY_MARKERS = ["@heedvane/hooks", "heedvane-hooks"];
+/** Why metrics only registers no MCP connection: its tools send questions and repository names to Heedvane. */
+export const MCP_OFF_METRICS_ONLY = "Heedvane's MCP connection: off under Metrics only, since its tools send your questions and repository names to Heedvane";
+/** What to do when no organization is known, so no MCP connection can be registered. */
+export const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx -y heedvane connect --org <id>";
+/** How to add the organization: `setup` cannot, since it compiles heed.yaml as it is. */
+export const ORG_REMEDIATION = "run the connect command from your dashboard's Settings, or npx -y heedvane connect --org <organization id>";
+/** The connection's name before 0.3.0; connect and uninstall remove an entry under it. */
+const EARLIER_CONNECTOR_NAME = "heedvane-findings";
+/** The packages the local helper ran from: `heedvane` (0.1.0 to 0.2.1 on npm) and the development builds' names. */
+const HELPER_PACKAGES = ["heedvane", "heedvane-hooks", "@heedvane/hooks"];
 /** Uninstall/detection marker for inline dispatcher snippets (hooks configs). */
 export const SNIPPET_MARKER = "heedvane-agent-hook-form";
-/** The npm package name entries carry; marker + entry builder use it. */
-const MCP_ENTRY_COMMAND = "heedvane";
-/** Args of the stdio MCP entry (command is always `npx`). */
-export const MCP_ENTRY_ARGS = ["-y", MCP_ENTRY_COMMAND, "mcp"];
-/** The stdio MCP entry, for JSON-family configs (`mcpServers` / `servers` / `mcp`). */
-export function mcpEntry() {
-    return { command: "npx", args: [...MCP_ENTRY_ARGS] };
+/** The connection's URL for an organization, as the dashboard builds it (`buildHeedvaneMcpUrl`). */
+export function connectorUrl(server, org) {
+    return `${server.replace(/\/+$/, "")}/api/mcp/${encodeURIComponent(org)}`;
 }
 /**
- * The stdio MCP entry for TOML configs. Codex reads `~/.codex/config.toml`
- * where servers are `mcp_servers.<name>` and a slow `npx` cold start needs an
- * explicit generous startup timeout.
+ * The connection entry per agent, in each agent's documented remote-server (Streamable HTTP) shape. Claude Code
+ * and VS Code need `type: "http"` (a typeless entry is read as stdio and skipped); Codex (`codex mcp add --url`)
+ * and Cursor take `url` alone, as the dashboard's setup writes them. Each agent signs in in the browser itself.
  */
-export function mcpEntryForToml() {
-    return { command: "npx", args: [...MCP_ENTRY_ARGS], startup_timeout_sec: 30 };
+const CONNECTOR_ENTRY = {
+    claude: (url) => ({ type: "http", url }),
+    vscode: (url) => ({ type: "http", url }),
+    codex: (url) => ({ url }),
+    cursor: (url) => ({ url }),
+    // Gemini CLI: `httpUrl` is Streamable HTTP (`url` is SSE); OAuth is discovered on the first 401 (`/mcp auth heedvane`).
+    gemini: (url) => ({ httpUrl: url }),
+    // Qwen Code (a Gemini CLI fork) runs the OAuth flow only for a server whose `oauth` is enabled; endpoints and client are discovered.
+    "qwen-code": (url) => ({ httpUrl: url, oauth: { enabled: true } }),
+    opencode: (url) => ({ type: "remote", url, enabled: true }),
+    warp: (url) => ({ url }),
+    // Kimi Code: a `url` without `transport` is Streamable HTTP (`/mcp-config login heedvane` signs in).
+    kimi: (url) => ({ url }),
+    droid: (url) => ({ type: "http", url }),
+    // Antigravity and Windsurf read only `serverUrl` for a remote server.
+    antigravity: (url) => ({ serverUrl: url }),
+    windsurf: (url) => ({ serverUrl: url }),
+    // Copilot CLI lists the tools it may call; `*` is every tool.
+    copilot_cli: (url) => ({ type: "http", url, tools: ["*"] }),
+    // Pi signs in on the first 401 (`pi mcp login heedvane`) and offers the tools to the model only with `direct` exposure.
+    pi: (url) => ({ url, exposure: "direct" }),
+    // Claude Desktop's config file runs only local (stdio) servers, so the mcp-remote bridge carries the connection and
+    // its browser sign-in. `@latest` keeps npx off an older cached copy (0.1.15 and earlier had CVE-2025-6514).
+    claude_desktop: (url, nodeDir) => bridgeEntry(["-y", "mcp-remote@latest", url], nodeDir),
+};
+/**
+ * Finds npx when the agent starts the server: the installing Node's folder first, then the newest Node 22 or later
+ * from nvm, then Homebrew's and /usr/local's, so an upgrade that removes the installing folder does not break the entry.
+ * The folder found leads PATH, since npx finds `node` through PATH and Claude Desktop opened from Finder starts servers
+ * with launchd's PATH, which holds no Node from nvm or Homebrew.
+ */
+const BRIDGE_LAUNCHER = [
+    'installed="$1"; shift',
+    'newest=""; newest_rank=0',
+    'for bin in "$HOME"/.nvm/versions/node/v*/bin; do',
+    '  version="${bin%/bin}"; version="${version##*/v}"; major="${version%%.*}"; rest="${version#*.}"; minor="${rest%%.*}"; patch="${rest#*.}"',
+    '  case "$major$minor$patch" in ""|*[!0-9]*) continue ;; esac',
+    "  rank=$((major * 1000000 + minor * 1000 + patch))",
+    '  if [ "$major" -ge 22 ] && [ "$rank" -gt "$newest_rank" ] && [ -x "$bin/npx" ]; then newest="$bin"; newest_rank="$rank"; fi',
+    "done",
+    'for dir in "$installed" "$newest" /opt/homebrew/bin /usr/local/bin; do',
+    '  if [ -n "$dir" ] && [ -x "$dir/npx" ]; then PATH="$dir:/usr/bin:/bin:/usr/sbin:/sbin" exec "$dir/npx" "$@"; fi',
+    "done",
+    'echo "heedvane: no npx found for Heedvane\'s MCP connection; install Node.js 22 or later" >&2',
+    "exit 127",
+].join("\n");
+const BRIDGE_NAME = "heedvane-bridge";
+/** A local server run by npx: through {@link BRIDGE_LAUNCHER} given the installing Node's folder, else the bare npx (Windows). */
+function bridgeEntry(args, nodeDir) {
+    if (nodeDir === undefined)
+        return { command: "npx", args };
+    return { command: "/bin/sh", args: ["-c", BRIDGE_LAUNCHER, BRIDGE_NAME, nodeDir, ...args] };
 }
-/** Per-client desired entry. Only Codex (TOML) carries the startup timeout. */
-export function desiredServer(clientId) {
-    return clientId === "codex" ? mcpEntryForToml() : mcpEntry();
+/**
+ * The entry as drift checks compare it: a bridge's installing-Node folder is left out, since the launcher finds a Node
+ * without it, and connect run from another Node is no change to the connection.
+ */
+export function comparableEntry(entry) {
+    if (entry === null || typeof entry !== "object")
+        return entry;
+    const { command, args } = entry;
+    if (command !== "/bin/sh" || !Array.isArray(args) || args[0] !== "-c" || args[2] !== BRIDGE_NAME)
+        return entry;
+    return { ...entry, args: [...args.slice(0, 3), ...args.slice(4)] };
 }
-/** Warp's MCP config is project-level and approval-gated. */
-export const WARP_MCP_RELATIVE_PATH = ".warp/.mcp.json";
+/** The fields agents name a remote server's URL with. */
+const URL_FIELDS = ["url", "httpUrl", "serverUrl"];
+/** The variable a software factory holds its organization API key in; the dashboard's factory commands use it. */
+export const ORG_KEY_ENV = "HEEDVANE_ORG_KEY";
 /**
- * Honest limitation surfaced by init/doctor for Warp. Warp has no native
- * hooks and its MCP support is project-scoped and import-gated: the user must
- * approve the import in Warp, per project, before the server activates.
- * Policies therefore arrive via MCP tools, not hooks.
+ * A software factory's connection: the agent sends the organization key from HEEDVANE_ORG_KEY as `Authorization: Bearer`
+ * through its own documented way to read a variable, so the key is never written to a file and no browser sign-in is
+ * needed. VS Code, Warp, Antigravity and Claude Desktop document none, so they keep the browser sign-in.
  */
-export const WARP_MCP_LIMITATION = "Warp limitation: Warp has no native hooks support, and its MCP servers are project-scoped and " +
-    "approval-gated. Heedvane writes a project-level .warp/.mcp.json for the current project only; " +
-    "you must approve the heedvane MCP import inside Warp (Settings > MCP) before it activates, and " +
-    "repeat that approval in every project you use it in. Hooks are unsupported in Warp — policies " +
-    "arrive via MCP tools once the server import is approved.";
+const KEY_CONNECTOR_ENTRY = {
+    // Claude Code, Gemini CLI, Qwen Code, Droid, Copilot CLI and Pi expand ${VAR} in header values.
+    claude: (url) => ({ type: "http", url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    gemini: (url) => ({ httpUrl: url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    "qwen-code": (url) => ({ httpUrl: url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    droid: (url) => ({ type: "http", url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` } }),
+    copilot_cli: (url) => ({ type: "http", url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` }, tools: ["*"] }),
+    pi: (url) => ({ url, headers: { Authorization: `Bearer \${${ORG_KEY_ENV}}` }, exposure: "direct" }),
+    // Codex and Kimi Code name the variable that holds the bearer token.
+    codex: (url) => ({ url, bearer_token_env_var: ORG_KEY_ENV }),
+    kimi: (url) => ({ url, bearerTokenEnvVar: ORG_KEY_ENV }),
+    // Cursor and Windsurf (Devin Desktop) read ${env:VAR}; OpenCode reads {env:VAR} and needs its own OAuth off.
+    cursor: (url) => ({ url, headers: { Authorization: `Bearer \${env:${ORG_KEY_ENV}}` } }),
+    windsurf: (url) => ({ serverUrl: url, headers: { Authorization: `Bearer \${env:${ORG_KEY_ENV}}` } }),
+    opencode: (url) => ({ type: "remote", url, enabled: true, oauth: false, headers: { Authorization: `Bearer {env:${ORG_KEY_ENV}}` } }),
+};
+/** The software-factory connection entry for this agent; undefined where it keeps the browser sign-in. */
+export function keyConnectorEntry(clientId, url) {
+    return KEY_CONNECTOR_ENTRY[clientId]?.(url);
+}
+/** The connection entry for this agent, or undefined when the installer does not register it there. `nodeDir` (POSIX only) is the installing Node's folder, for an entry that runs a local bridge. */
+export function connectorEntry(clientId, url, nodeDir) {
+    return CONNECTOR_ENTRY[clientId]?.(url, nodeDir);
+}
 /**
- * Does this entry's command/args carry a heedvane identity marker? This is
- * the STRICT check used by uninstall: an entry is only removed when its
- * command/args prove it is ours. A name match without the marker is a
- * renamed/replaced entry and is left alone.
+ * The server and organization of a Heedvane MCP URL exactly as {@link connectorUrl} builds it: http(s)
+ * `<server>/api/mcp/<organization>`, where a server under a base path keeps that path, with no credentials, query or
+ * fragment. A user's own URL whose path merely contains `/api/mcp/` is none.
  */
-function hasHeedvaneMarker(entry) {
+function parsedConnectorUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        const path = url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+        const segments = path.split("/");
+        const encodedOrg = segments.pop();
+        if (!encodedOrg || segments.pop() !== "mcp" || segments.pop() !== "api")
+            return undefined;
+        const written = new URL(url);
+        written.pathname = path;
+        const server = `${url.origin}${segments.join("/")}`;
+        const org = decodeURIComponent(encodedOrg);
+        return new URL(connectorUrl(server, org)).href === written.href ? { server, org } : undefined;
+    }
+    catch {
+        return undefined; // not a URL, or an organization that does not decode: not one connectorUrl builds
+    }
+}
+/** The organization an entry's Heedvane MCP URL names at `server`, if it points there. */
+export function connectorOrganization(entry, server) {
+    for (const value of entryUrls(entry)) {
+        const parsed = parsedConnectorUrl(value);
+        if (parsed !== undefined && new URL(connectorUrl(parsed.server, parsed.org)).href === new URL(connectorUrl(server, parsed.org)).href)
+            return parsed.org;
+    }
+    return undefined;
+}
+/** The strings an entry names a server URL with: any agent's URL field, or a bridge's arguments. */
+export function entryUrls(entry) {
     if (entry === null || typeof entry !== "object")
-        return false;
+        return [];
     const e = entry;
-    const command = typeof e.command === "string" ? e.command : "";
-    const args = Array.isArray(e.args) ? e.args.filter((a) => typeof a === "string") : [];
-    const haystack = [command, ...args].join(" ");
-    return haystack.includes(MCP_ENTRY_ARGS.join(" ")) || IDENTITY_MARKERS.some((m) => haystack.includes(m));
+    const args = Array.isArray(e.args) ? e.args : [];
+    return [...URL_FIELDS.map((field) => e[field]), ...args].filter((value) => typeof value === "string");
 }
-/**
- * Is this server entry a heedvane-managed one? True when the entry NAME is
- * the reserved `heedvane` name, or when the entry's command/args carry an
- * identity marker. Used by detectMarker and doctor.
- */
+/** Does this entry point at a Heedvane MCP URL, under any agent's name for the field or as a bridge's argument? */
+function hasConnectorUrl(entry) {
+    return entryUrls(entry).some((url) => parsedConnectorUrl(url) !== undefined);
+}
+/** Is this today's connection entry? Its name and a Heedvane MCP URL both have to match. */
+export function isConnectorEntry(name, entry) {
+    return name === HEEDVANE_SERVER_NAME && hasConnectorUrl(entry);
+}
+/** Is this an entry an earlier version wrote: the local helper under any name, or the connection under its earlier name? */
+export function isLegacyEntry(name, entry) {
+    return hasHelperCommand(entry) || (name === EARLIER_CONNECTOR_NAME && hasConnectorUrl(entry));
+}
+/** Does this entry run the local helper an earlier version registered, under any name? */
+export function isHelperEntry(_name, entry) {
+    return hasHelperCommand(entry);
+}
+/** Is this server entry Heedvane's, today's or an earlier version's? Used by uninstall, detection and doctor. */
 export function isHeedvaneEntry(name, entry) {
-    if (name === HEEDVANE_SERVER_NAME)
-        return true;
-    return hasHeedvaneMarker(entry);
+    return isConnectorEntry(name, entry) || isLegacyEntry(name, entry);
+}
+/** Names of the entries `match` accepts in a parsed config's MCP containers, as `container::name`. */
+export function mcpEntryNames(doc, containerKeys, match) {
+    const names = [];
+    for (const key of new Set(containerKeys)) {
+        const container = doc[key];
+        if (container === null || typeof container !== "object" || Array.isArray(container))
+            continue;
+        for (const [name, entry] of Object.entries(container)) {
+            if (match(name, entry))
+                names.push(`${key}::${name}`);
+        }
+    }
+    return names;
+}
+/** Does this entry run the local helper, exactly as earlier versions wrote it: `npx -y <helper package> mcp`? */
+function hasHelperCommand(entry) {
+    if (entry === null || typeof entry !== "object")
+        return false;
+    const { command, args } = entry;
+    if (command !== "npx" || !Array.isArray(args) || args.length !== 3)
+        return false;
+    return args[0] === "-y" && HELPER_PACKAGES.includes(String(args[1])) && args[2] === "mcp";
 }

package/dist/plan.d.ts

@@ -2,7 +2,8 @@ import { type Capability, type Env, type ResolvedClient } from "./clients/defini
 import { type DocFormat } from "./config-doc.js";
 import type { HeedFile, HeedGatingConfig } from "./heed-file.js";
 export type ActionKind = "hooks" | "mcp" | "skill" | "skip";
-export type Operation = "create" | "update" | "unchanged" | "skip";
+/** `remove`: the action only removes entries ({@link mcpLeftovers}); the plan shows it as removed. */
+export type Operation = "create" | "update" | "unchanged" | "skip" | "remove";
 export interface PlannedAction {
     clientId: string;
     kind: ActionKind;
@@ -21,11 +22,6 @@ export interface PlanInput {
     /** Desired skill digest; defaults to the canonical bundled content. */
     skillDigest?: string;
 }
-/** Our MCP stdio registration entry (unscoped package per the plan's decision). */
-export declare function mcpEntry(): {
-    command: string;
-    args: string[];
-};
 interface Desired {
     path: string;
     format: DocFormat;
@@ -42,16 +38,51 @@ export declare function hooksTarget(client: ResolvedClient): {
 export interface ClientContext {
     home: string;
     env: Env;
+    /** Heedvane's MCP connection URL (`connect --org`), registered where the agent takes it. */
+    connector?: string;
+    /** The folder whose npx runs a local MCP bridge (`bridgeNodeDir`); without it, the bare `npx`. */
+    nodeDir?: string;
 }
 /**
  * Desired write targets per client × capability. This is the desired-state
  * compiler heed.yaml → concrete files; doctor reuses it via a callback so
- * it never needs apply.ts. `env` is accepted for API stability — the client's
- * config paths arrive already resolved against it.
+ * it never needs apply.ts. The client's config paths arrive already resolved
+ * against `env`; its HEEDVANE_ORG_KEY picks the software-factory MCP connection.
  */
 export declare function desiredEntriesFor(client: ResolvedClient, capability: Capability, context: ClientContext & {
     gating?: HeedGatingConfig["mode"];
 }): Desired[];
+/** The folder whose npx runs a local MCP bridge on `platform`; none on Windows, which keeps the bare `npx` its docs show (a `.cmd` path cannot be started without a shell). */
+export declare function bridgeNodeDir(platform: string): string | undefined;
+/**
+ * Why heed.yaml registers no MCP connection, the one owner of that decision: metrics only, whose promise the
+ * connection's tools would break (they send questions and repository names), or no organization. None when it does.
+ */
+export declare function connectionOff(heedFile: HeedFile): "metrics-only" | "no-organization" | undefined;
+/** Heedvane's MCP connection URL for the organization heed.yaml names, unless {@link connectionOff} says there is none. */
+export declare function heedvaneConnector(heedFile: HeedFile): string | undefined;
+/** What to tell a person who asked for the MCP connection but gets none, and why; nothing when it is registered. */
+export declare function connectionNote(heedFile: HeedFile): string | undefined;
+/** The organization an earlier version's connection (`heedvane-findings`) names at `server`, so connect can replace it without --org. */
+export declare function legacyOrganization(clients: readonly ResolvedClient[], server: string): string | undefined;
+/** The MCP containers a client's configs can hold our entries in (Codex's TOML and OpenCode's `mcp` beside the usual key). */
+export declare function mcpContainers(client: ResolvedClient): string[];
+/** The doc's parsed value, or null when the config is absent or unparseable — nothing marker-verified to remove. */
+export declare function parseClientDoc(path: string, format: DocFormat): Record<string, unknown> | null;
+/** True when the client's MCP config holds Heedvane's connection, not only a user's entry that shares its name. */
+export declare function hasOwnConnection(client: ResolvedClient): boolean;
+/** Whether Heedvane's connection in this client's MCP config is in the key form (mcp.ts `keyConnectorEntry`), for whatever server and organization it names. */
+export declare function sendsOrgKey(client: ResolvedClient): boolean;
+/** The first config of this client still holding an MCP entry an earlier version wrote, and those entries' names. */
+export declare function legacyMcpEntries(client: ResolvedClient): {
+    path: string;
+    names: string[];
+} | undefined;
+/** The first config of this client holding any Heedvane MCP entry, today's or an earlier version's, and their names. */
+export declare function heedvaneMcpEntries(client: ResolvedClient): {
+    path: string;
+    names: string[];
+} | undefined;
 /**
  * The client whose hooks this one already runs, when that client's hooks are installed too, by this run or
  * an earlier one: installing both would run every event twice, recorded under two agents. Plan and doctor
@@ -67,6 +98,14 @@ interface AgentScope {
 }
 /** Whether a client is detected on this machine via its primary marker or any altMarkerPaths (e.g. GUI ADEs). */
 export declare function isClientDetected(client: ResolvedClient): boolean;
+/** The client's native capability, or hooks written as whole files (definitions.ts `hookFiles`). */
+export declare function supportsCapability(client: ResolvedClient, capability: "hooks" | "mcp" | "skill"): boolean;
+/**
+ * The MCP entries connect removes: under metrics only every Heedvane entry, today's too; without an organization the
+ * local helper, which has no tools any more (a connection under its earlier name still works, and nothing would replace
+ * it); otherwise everything an earlier version registered.
+ */
+export declare function mcpLeftovers(heedFile: HeedFile): (name: string, entry: unknown) => boolean;
 /**
  * The planner. For each client a run installs (installsClient), emit one action per enabled
  * capability the client supports — or an honest skip with a reason it doesn't.