heedvane 0.2.0 → 0.3.3

package/README.md

@@ -7,8 +7,8 @@ checks and team memory for Claude Code, Codex, Cursor, Gemini CLI, Hermes, OpenC
 npx heedvane
 ```
 
-The installer shows the agents it found on your machine. Tick the ones you want, choose what Heedvane
-adds and does, confirm. It installs, starts Heedvane in the background and signs you in through the
+The installer shows the agents it found on your machine. Tick the ones you want, choose how much leaves
+your machine, choose what Heedvane adds and does, confirm. It installs, starts Heedvane in the background and signs you in through the
 browser. It needs Node.js 22 or newer.
 
 Your dashboard's Agents page has the same command with your server and organization filled in:
@@ -17,12 +17,27 @@ Your dashboard's Agents page has the same command with your server and organizat
 npx heedvane connect --server https://app.heedvane.com --org <organization id>
 ```
 
+## How much leaves your machine
+
+| Choice | What leaves your machine |
+| --- | --- |
+| **Look but don't keep** (default) | Heedvane's guardrail checks read the prompt or tool call, then keep only the verdict, never the text. |
+| **Metrics only** | Only counts and names. Your organization's fixed rules still run on your machine; Heedvane's own checks and team memory are off. |
+
+Scripts choose with `--mode look-but-dont-keep` or `--mode metrics-only`. The choice is saved in
+`heed.yaml` as `heedvane.dataMode`.
+
 ## What it changes
 
 - Writes `~/.heed/heed.yaml`, your control file, with your answers. Run `npx heedvane` again to change
   them.
-- Adds Heedvane's hooks, MCP server entry and skill to each agent you ticked. A config file it edits is
-  backed up first.
+- Adds Heedvane's hooks and skill to each agent you ticked. A config file it edits is backed up first.
+- With `--org` (the dashboard's command has it), also adds Heedvane's MCP connection, named `heedvane`, for
+  your organization (findings, reports and agent feedback) in every agent you ticked. Claude Desktop gets it
+  through the `mcp-remote` bridge, run with the Node.js that installed it (run `npx heedvane connect` again after
+  removing that Node version). The agent signs in
+  through the browser the first time it uses it. It replaces the `heedvane` and
+  `heedvane-findings` entries an earlier version added.
 - Starts Heedvane's local listener, which answers the hooks. After a restart the hooks start it again by
   themselves, at most once a minute. Set `HEED_LISTENER_AUTOSTART=0` to turn that off.
 
@@ -49,7 +64,7 @@ own lines go to stderr and `~/.heed/listener.log`.
 
 - Claude Code runs the hooks in print mode (`claude -p`), but not with `--bare`.
 - Codex runs hooks only after they are trusted.
-- Pi and Flue agents cannot be connected yet.
+- The installer does not set up Pi or Flue. Connect them with a hook of your own that sends each action to `POST /api/agent/steering` with the organization key; Heedvane answers whether to refuse it.
 
 ## Everyday commands
 

package/dist/cli.d.ts

@@ -25,5 +25,6 @@ declare function main(argv: string[], opts?: MainOptions): Promise<number>;
  * The command that opens `url` in the default browser. Windows goes through rundll32, not `cmd /c start`:
  * cmd would cut the sign-in URL at its first `&`.
  */
-export declare function browserOpener(platform: NodeJS.Platform, url: string): [string, string[]];
+/** The command that opens `url`: `$BROWSER` when set (a no-op such as `true` keeps captures and tests off a real browser), else the platform's opener. */
+export declare function browserOpener(platform: NodeJS.Platform, url: string, browser?: string): [string, string[]];
 export { main };

package/dist/cli.js

@@ -7,20 +7,21 @@
 import { createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { constants as osConstants, homedir, platform } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { supportedClients } from "./clients/definitions.js";
 import { installHermesPlugin } from "./clients/hermes-plugin.js";
 import { applyEntry } from "./apply.js";
-import { DEFAULT_HEED_YAML_TEMPLATE, heedvaneConfigAt, loadHeedFile, loadHeedFileAt, withInstallChoices, withServerUrl } from "./heed-file.js";
-import { planActions, desiredEntriesFor, isClientDetected } from "./plan.js";
+import { DATA_MODES, DEFAULT_HEED_YAML_TEMPLATE, heedvaneConfigAt, loadHeedFile, loadHeedFileAt, withInstallChoices, withSettings } from "./heed-file.js";
+import { planActions, desiredEntriesFor, heedvaneConnector, installingNodeDir, isClientDetected } from "./plan.js";
 import { appliedFailed, capabilitySummary, renderApplied, renderDetection, renderPlan, wouldInstallSummary } from "./render.js";
 import { runDoctor } from "./doctor.js";
 import { installSkill } from "./skill/bundle.js";
 import { canonicalSkillFiles, skillDigest } from "./skill/content.js";
 import { emptyState, readState, writeStateAtomic } from "./state.js";
 import { writeDispatcherScript } from "./dispatchers/posix.js";
-import { removeDeferredHookGroups, removeStaleHookGroups, uninstall } from "./uninstall.js";
-import { statusText, runMcpStdio } from "./mcp-server.js";
+import { removeDeferredHookGroups, removeLegacyMcpEntries, removeStaleHookGroups, uninstall } from "./uninstall.js";
+import { statusText } from "./status.js";
+import { MCP_NEEDS_ORG } from "./mcp.js";
 import { errorMessage } from "./guards.js";
 import { ensureEndpoint } from "./listener/endpoint.js";
 import { listenerLogPath, startListenerInBackground } from "./listener/background.js";
@@ -29,7 +30,7 @@ import { cmdAuth, cmdLogin, cmdSkills } from "./commands/heedvane.js";
 import { cmdMemory } from "./commands/memory.js";
 import { backendAt } from "./backend/credentials.js";
 import { readLogin } from "./backend/login.js";
-import { agentLines, askChoices, brandIntro, confirmInstall, installCancelled, installFinished, installWithSpinner, listenerStep, promptLine, showInstalled } from "./installer.js";
+import { agentLines, askChoices, brandIntro, confirmInstall, installCancelled, installDetails, installFinished, installWithSpinner, listenerStep, promptLine, showInstalled } from "./installer.js";
 const USAGE = `  heedvane-hook — cross-agent steering, guardrails & analysis
 
   Usage: npx heedvane [command] [flags]   (installed: heedvane <command>)
@@ -48,11 +49,11 @@ const USAGE = `  heedvane-hook — cross-agent steering, guardrails & analysis
     skills sync     install the organization's approved skills and cache the list hooks enforce
     memory list|show|search   browse this repository's team memory (a folder, one memory, or a question)
     status          quick state summary
-    mcp             run the MCP stdio server (what agents register)
 
   Flags: --dry-run --yes --json --agent <id> (repeatable) --client <id> --purge-config --project
          --server <url> (connect/init: the Heedvane app to use, saved as heedvane.url; --url also works)
-         --org <id> (connect/init: the organization the sign-in must belong to)`;
+         --org <id> (connect/init: the organization the sign-in must belong to; also registers Heedvane's MCP connection)
+         --mode <look-but-dont-keep|metrics-only> (connect/init: what leaves this machine, saved as heedvane.dataMode)`;
 function resolveHome(env) {
     return env.HEED_HOME ?? homedir();
 }
@@ -98,17 +99,64 @@ function parseInvocation(args) {
         clients: parseRepeatedFlag(args, "--client"),
         server: flagValue(args, "--server") ?? flagValue(args, "--url"),
         org: flagValue(args, "--org"),
-        positional: positionalArgs(args, ["--agent", "--client", "--folder", "--offset", "--url", "--server", "--org", "--token"]),
+        mode: flagValue(args, "--mode"),
+        positional: positionalArgs(args, VALUE_FLAGS),
     };
 }
+/** Flags without a value. */
+const SWITCH_FLAGS = ["--dry-run", "--yes", "--json", "--purge-config", "--project", "--help", "-h"];
+/** Flags followed by a value. */
+const VALUE_FLAGS = ["--agent", "--client", "--folder", "--offset", "--url", "--server", "--org", "--mode", "--token"];
+/** Heedvane's own arguments: everything before `--`, after which `run` passes the rest to the agent. */
+function ownArgs(args) {
+    const separator = args.indexOf("--");
+    return separator < 0 ? args : args.slice(0, separator);
+}
+/** The first argument that looks like a flag but is not one of ours (values of value flags skipped). */
+function unknownFlag(args) {
+    for (let i = 0; i < args.length; i++) {
+        if (VALUE_FLAGS.includes(args[i]))
+            i += 1;
+        else if (args[i].startsWith("-") && !SWITCH_FLAGS.includes(args[i]))
+            return args[i];
+    }
+    return undefined;
+}
+/** One command's usage line from USAGE plus the flags, or the whole USAGE for no or an unknown command. */
+function helpFor(command) {
+    const lines = USAGE.split("\n");
+    const own = command === undefined ? [] : lines.filter((line) => line.trim().startsWith(`${command} `));
+    if (own.length === 0)
+        return USAGE;
+    const flags = lines.slice(lines.findIndex((line) => line.trim().startsWith("Flags:")));
+    return [`  Usage: npx heedvane ${command} [flags]`, "", ...own, "", ...flags].join("\n");
+}
+/** The command help is asked about: `help <command>`, `<command> --help`, or none for `-h` alone. */
+function helpTopic([first, second]) {
+    if (first === "help")
+        return second;
+    return first === "-h" ? undefined : first;
+}
 async function main(argv, opts = {}) {
     const ctx = commandContext(argv, opts);
     const command = ctx.positional[0];
+    const own = ownArgs(ctx.args);
+    // Help never runs anything: `uninstall --help` must not uninstall.
+    if (command === "help" || own.includes("--help") || own.includes("-h")) {
+        ctx.out(helpFor(helpTopic(ctx.positional)));
+        return 0;
+    }
+    const unknown = unknownFlag(own);
+    if (unknown !== undefined) {
+        ctx.out(`  ✗ unknown flag: ${unknown} (nothing was changed)`);
+        ctx.out(helpFor(command));
+        return 2;
+    }
     if (command === undefined && takesInstaller(ctx))
         return cmdInstall(ctx);
-    if (!command || command === "help" || command === "--help") {
+    if (!command) {
         ctx.out(USAGE);
-        return command ? 0 : 2;
+        return 2;
     }
     return routeCommand(command, ctx);
 }
@@ -122,7 +170,7 @@ function commandContext(argv, opts) {
         out: opts.write ?? ((line) => console.log(line)),
         args,
         readStdin: opts.readStdin ?? readProcessStdin,
-        openBrowser: opts.openBrowser ?? openSystemBrowser,
+        openBrowser: opts.openBrowser ?? ((url) => openSystemBrowser(url, env.BROWSER)),
         interactive: opts.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
         cwd: opts.cwd ?? process.cwd(),
         prompts: opts.prompts ?? {},
@@ -151,10 +199,6 @@ async function routeServiceCommand(command, ctx) {
             ctx.out(await statusText());
             return 0;
         }
-        case "mcp": {
-            runMcpStdio({ write: (line) => ctx.out(line) });
-            return 0;
-        }
         case "listener": {
             return cmdListener({ home: ctx.home, out: ctx.out, rest: ctx.args.slice(ctx.args.indexOf("listener") + 1) });
         }
@@ -214,11 +258,11 @@ async function cmdInit(ctx) {
     }
     let serverEdit;
     try {
-        serverEdit = ctx.server === undefined ? null : withServer(home, loaded, ctx.server);
+        serverEdit = withFlags(home, loaded, ctx);
     }
     catch (err) {
         out("");
-        out(`  ✗ --server ${ctx.server} cannot be used: ${errorMessage(err)}`);
+        out(`  ✗ ${errorMessage(err)}`);
         return 1;
     }
     const { heedFile, existed } = serverEdit ?? loaded;
@@ -243,11 +287,27 @@ async function cmdInit(ctx) {
     // --yes: first non-dry run has approval; proceed to write.
     return applyAndReport(ctx, { heedFile, agents, existed, ...(serverEdit === null ? {} : { text: serverEdit.text }) });
 }
-/** heed.yaml (or the template) with `--server` as `heedvane.url`; null when it already names that server. Throws on an unusable URL. */
-function withServer(home, loaded, server) {
-    const text = withServerUrl(heedText(home, loaded.existed), server);
-    const heedFile = loadHeedFile(text);
-    if (loaded.existed && heedFile.heedvane.url === loaded.heedFile.heedvane.url)
+/** The heed.yaml settings `--server`, `--org` and `--mode` name; a refusal when a value cannot be used. */
+function flagSettings({ server, org, mode }) {
+    if (mode !== undefined && !DATA_MODES.some((known) => known === mode))
+        throw new Error(`--mode ${mode} is not one of ${DATA_MODES.join(", ")}; nothing was changed`);
+    const settings = [[["heedvane", "url"], server], [["heedvane", "org"], org], [["heedvane", "dataMode"], mode]];
+    return settings.filter((setting) => setting[1] !== undefined);
+}
+/** heed.yaml (or the template) with the flags' settings; null when they change nothing. Throws on a value it cannot use. */
+function withFlags(home, loaded, flags) {
+    const settings = flagSettings(flags);
+    if (settings.length === 0)
+        return null;
+    const text = withSettings(heedText(home, loaded.existed), settings);
+    let heedFile;
+    try {
+        heedFile = loadHeedFile(text);
+    }
+    catch (err) {
+        throw new Error(`${flags.server === undefined ? "a flag" : `--server ${flags.server}`} cannot be used: ${errorMessage(err)}`, { cause: err });
+    }
+    if (loaded.existed && JSON.stringify(heedFile.heedvane) === JSON.stringify(loaded.heedFile.heedvane))
         return null;
     return { heedFile, existed: loaded.existed, text };
 }
@@ -259,7 +319,9 @@ async function applyAndReport(ctx, spec) {
     if (!flags.dryRun)
         await signInIfNeeded(ctx, spec.heedFile.heedvane.url);
     out("");
-    out("  Next: open a new agent session and run /heedvane-status.");
+    out("  Next: open a new agent session; Heedvane joins it at session start.");
+    if (spec.heedFile.install.mcp && heedvaneConnector(spec.heedFile) === undefined)
+        out(`  ${MCP_NEEDS_ORG}`);
     out("  Re-run `npx heedvane doctor` after any heed.yaml edit.");
     const failed = applied.some(appliedFailed);
     if (flags.json)
@@ -272,7 +334,13 @@ function writeControlFile({ home, out }, { heedFile, existed, text }) {
         return;
     mkdirSync(join(home, ".heed"), { recursive: true, mode: 0o700 });
     writeFileSync(join(home, ".heed", "heed.yaml"), text ?? DEFAULT_HEED_YAML_TEMPLATE, { mode: 0o600 });
-    out(existed ? `  ✓ Set heedvane.url in ~/.heed/heed.yaml to ${heedFile.heedvane.url}` : `  ✓ Wrote ~/.heed/heed.yaml (your control file — edit any time)`);
+    if (!existed)
+        return out(`  ✓ Wrote ~/.heed/heed.yaml (your control file — edit any time)`);
+    const { url, org, dataMode } = heedFile.heedvane;
+    for (const [name, value] of [["url", url], ["org", org], ["dataMode", dataMode]]) {
+        if (value !== undefined)
+            out(`  ✓ Set heedvane.${name} in ~/.heed/heed.yaml to ${value}`);
+    }
 }
 /** Without a sign-in to `url` (and to `--org`, when named), sign in now when a person is at the terminal, else say how. Never fails setup. */
 /** Writes heed.yaml, applies the plan, issues the listener endpoint and records the machine state. Prints only what applying prints. */
@@ -285,9 +353,9 @@ async function installPlan(ctx, spec) {
     const dispatcher = {
         denySkillsWhenUnchecked: heedFile.heedvane.skills.enforce && heedFile.heedvane.skills.whenUnknown === "deny",
         gating: heedFile.gating.mode,
-        nodeDir: dirname(process.execPath),
+        nodeDir: installingNodeDir(),
     };
-    const applied = await applyPlan(actions, { home, env, out, dispatcher });
+    const applied = await applyPlan(actions, { home, env, out, dispatcher, connector: heedvaneConnector(heedFile) });
     // The listener port and token every dispatcher reads; kept once issued.
     await ensureEndpoint(join(home, ".heed"));
     // Machine state: CLI-owned; preserve an existing endpoint.
@@ -351,9 +419,9 @@ async function cmdSetup(ctx) {
     }
     return applyAndReport(ctx, { heedFile, agents: ctx.agents, existed: true });
 }
-/** A person at a terminal who did not ask for the one-shot path (`--yes`, `--dry-run`, `--json`) or for help. */
+/** A person at a terminal who did not ask for the one-shot path (`--yes`, `--dry-run`, `--json`). */
 function takesInstaller(ctx) {
-    return ctx.interactive && !ctx.flags.yes && !ctx.flags.dryRun && !ctx.flags.json && !ctx.args.includes("--help");
+    return ctx.interactive && !ctx.flags.yes && !ctx.flags.dryRun && !ctx.flags.json;
 }
 /** heed.yaml's text, or the template when there is none yet. */
 function heedText(home, existed) {
@@ -375,7 +443,7 @@ async function cmdInstall(ctx) {
     const spec = { heedFile: loadHeedFile(text), agents: choices.agents === "auto" ? [] : choices.agents, existed: base.existed, text };
     const names = new Map(detectionRows(ctx.home, ctx.env).map((row) => [row.client.id, row.client.displayName]));
     const planned = agentLines(planFor({ home: ctx.home, env: ctx.env, ...spec }), names);
-    if (!(await confirmInstall(planned, prompts)))
+    if (!(await confirmInstall(planned, installDetails(spec.heedFile, heedvaneConnector(spec.heedFile)), prompts)))
         return installCancelled(prompts);
     const notes = [];
     const { actions, applied } = await installWithSpinner(planned.length, () => installPlan({ ...ctx, out: (line) => notes.push(line) }, spec), prompts);
@@ -383,29 +451,29 @@ async function cmdInstall(ctx) {
     showInstalled(agentLines(actions, names, applied), prompts);
     const listening = await listenerStep(() => ctx.startListener(ctx.home), listenerLogPath(join(ctx.home, ".heed")), prompts);
     await signInIfNeeded({ ...ctx, out: promptLine(prompts) }, spec.heedFile.heedvane.url);
-    installFinished(nextSteps(listening, spec.heedFile.heedvane.url), prompts);
+    installFinished(nextSteps(listening, spec.heedFile), prompts);
     return applied.some(appliedFailed) ? 1 : 0;
 }
-/** heed.yaml's current text (or the template) with `--server` applied, parsed; a message when either cannot be used. */
-function installerBase({ home, server }) {
-    const loaded = loadOrTemplate(home);
+/** heed.yaml's current text (or the template) with `--server`, `--org` and `--mode` applied, parsed; a message when it cannot be used. */
+function installerBase(ctx) {
+    const loaded = loadOrTemplate(ctx.home);
     if (loaded.error)
         return `~/.heed/heed.yaml does not parse: ${loaded.error}`;
     try {
-        const current = heedText(home, loaded.existed);
-        const text = server === undefined ? current : withServerUrl(current, server);
-        return { heedFile: loadHeedFile(text), existed: loaded.existed, text };
+        return withFlags(ctx.home, loaded, ctx) ?? { heedFile: loaded.heedFile, existed: loaded.existed, text: heedText(ctx.home, loaded.existed) };
     }
     catch (err) {
-        return `--server ${server} cannot be used: ${errorMessage(err)}`;
+        return errorMessage(err);
     }
 }
 function agentOptions({ home, env }) {
     return detectionRows(home, env).map(({ client, detected }) => ({ id: client.id, name: client.displayName, detected, capability: capabilitySummary(client) }));
 }
-function nextSteps(listening, server) {
+function nextSteps(listening, heedFile) {
+    const server = heedFile.heedvane.url;
     return [
         "Open a new agent session: Heedvane joins it at session start.",
+        ...(heedFile.install.mcp && heedvaneConnector(heedFile) === undefined ? [MCP_NEEDS_ORG] : []),
         `Watch your sessions: ${server}`,
         ...(listening ? [] : ["Heedvane starts by itself with your next agent session. To see why it did not start now: npx heedvane listener start"]),
         "Check the install: npx heedvane doctor",
@@ -421,24 +489,38 @@ async function applyHermesPlugin(client, ctx) {
     }
     return { clientId: client.id, kind: "hooks", status: status === "installed" ? "create" : "unchanged", path };
 }
+/** Folds removals into an apply result: a failed removal becomes the result, any other makes an unchanged one an update. */
+function withRemovals(items, result) {
+    let worst = result;
+    for (const item of items) {
+        if (item.status === "failed")
+            return { status: "failed", path: item.path, reason: item.detail };
+        if (worst.status === "unchanged")
+            worst = { status: "update", path: item.path };
+    }
+    return worst;
+}
 /** Drop our groups under event keys this client no longer installs; a failed removal becomes the result. */
 async function withoutStaleHookGroups(client, writes, result) {
     let worst = result;
     for (const { target, containerKey } of writes) {
         if (containerKey !== "hooks")
             continue;
-        for (const item of await removeStaleHookGroups(client, target)) {
-            if (item.status === "failed")
-                return { status: "failed", path: item.path, reason: item.detail };
-            if (worst.status === "unchanged")
-                worst = { status: "update", path: item.path };
-        }
+        worst = withRemovals(await removeStaleHookGroups(client, target), worst);
+        if (worst.status === "failed")
+            return worst;
     }
     return worst;
 }
+/** After the writes: our hook groups under events no longer installed, and what an earlier version registered as MCP (the local helper, the connection's earlier name), with or without a connection to write. */
+async function withoutLeftovers(kind, client, done) {
+    if (kind === "hooks")
+        return withoutStaleHookGroups(client, done.writes, done.result);
+    return kind === "mcp" ? withRemovals(await removeLegacyMcpEntries(client), done.result) : done.result;
+}
 /** Patch every desired entry into the client's config files, then refresh the dispatcher script. */
 async function applyConfigEntries(action, client, ctx) {
-    const desireds = desiredEntriesFor(client, action.kind === "hooks" ? "hooks" : "mcp", { home: ctx.home, env: ctx.env });
+    const desireds = desiredEntriesFor(client, action.kind === "hooks" ? "hooks" : "mcp", { home: ctx.home, env: ctx.env, connector: ctx.connector });
     // One write per file and container: every hook event lands (and is backed up) together.
     const writes = new Map();
     for (const d of desireds) {
@@ -457,9 +539,8 @@ async function applyConfigEntries(action, client, ctx) {
         if (res.status !== "unchanged")
             worst = res;
     }
-    if (action.kind === "hooks" && worst.status !== "failed" && worst.status !== "invalid") {
-        worst = await withoutStaleHookGroups(client, writes.values(), worst);
-    }
+    if (worst.status !== "failed" && worst.status !== "invalid")
+        worst = await withoutLeftovers(action.kind, client, { writes: writes.values(), result: worst });
     // The dispatcher script the snippet delegates to.
     await writeDispatcherScript(ctx.home, client.id, ctx.dispatcher);
     return {
@@ -569,10 +650,10 @@ async function cmdListener(ctx) {
     }
     const started = await serveHooks(ctx.home, ctx.out);
     ctx.out(`  ✓ listener on 127.0.0.1:${started.port}, ${started.replayed} spooled event(s) replayed (Ctrl-C to stop)`);
+    // Ends on Ctrl-C, or when uninstall asks it to stop (POST /shutdown).
     await new Promise((resolve) => {
-        process.on("SIGINT", () => {
-            started.server.close(() => resolve());
-        });
+        started.server.on("close", resolve);
+        process.on("SIGINT", () => started.server.close());
     });
     return 0;
 }
@@ -630,12 +711,15 @@ function backendCommandContext(ctx) {
  * The command that opens `url` in the default browser. Windows goes through rundll32, not `cmd /c start`:
  * cmd would cut the sign-in URL at its first `&`.
  */
-export function browserOpener(platform, url) {
+/** The command that opens `url`: `$BROWSER` when set (a no-op such as `true` keeps captures and tests off a real browser), else the platform's opener. */
+export function browserOpener(platform, url, browser) {
+    if (browser)
+        return [browser, [url]];
     const openers = { darwin: ["open", [url]], win32: ["rundll32", ["url.dll,FileProtocolHandler", url]] };
     return openers[platform] ?? ["xdg-open", [url]];
 }
-function openSystemBrowser(url) {
-    const [command, args] = browserOpener(process.platform, url);
+function openSystemBrowser(url, browser) {
+    const [command, args] = browserOpener(process.platform, url, browser);
     const child = spawn(command, args, { detached: true, stdio: "ignore" });
     child.on("error", () => undefined); // no browser opener: the printed URL is the way in
     child.unref();

package/dist/clients/definitions.d.ts

@@ -34,7 +34,7 @@ export interface ResolveContext {
 /** Root a client's directory or detection marker is resolved against. */
 export type ClientPathBase = "home" | "xdg-config" | "platform-config";
 /** Base a writable config target is resolved against. */
-export type PathBase = "client" | "home" | "platform-config";
+export type PathBase = "client" | "home" | "platform-config" | "xdg-config";
 /** One writable config file for a client. */
 export interface ConfigTarget {
     /** Path segments relative to {@link PathBase}. */

package/dist/clients/definitions.js

@@ -155,13 +155,13 @@ const SUPPORTED_CLIENTS = [
                 base: "client",
                 format: "json",
                 purpose: "mcp",
-                limitation: "Warp has no native hook events (hooks unavailable); ~/.warp/.mcp.json is project-level, and user-level MCP requires explicit in-app approval of the import.",
+                limitation: "Warp has no native hook events (hooks unavailable); ~/.warp/.mcp.json is Warp's global MCP file, and a remote server signs in through the browser when it first starts.",
             },
         ],
         capabilities: ["mcp", "skill"],
         events: [],
         mcpServersKey: "mcpServers",
-        limitation: "Warp exposes no native hook events — policies ship via MCP only, and the MCP import needs explicit user approval in Warp.",
+        limitation: "Warp exposes no native hook events, so Heedvane adds only its MCP connection and the skill there.",
     },
     {
         id: "opencode",
@@ -227,11 +227,12 @@ const SUPPORTED_CLIENTS = [
         homeOverrideEnv: "KIMI_CODE_HOME",
         configs: [
             { segments: ["config.toml"], base: "client", format: "toml", purpose: "hooks" },
-            { segments: ["config.toml"], base: "client", format: "toml", purpose: "mcp" },
+            // MCP servers live in mcp.json (Kimi Code's MCP docs); config.toml is listed with hooks, so cleanup still finds the helper 0.3.0 and earlier wrote there.
+            { segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["hooks", "mcp", "skill"],
         events: KIMI_EVENTS,
-        mcpServersKey: "mcp_servers",
+        mcpServersKey: "mcpServers",
     },
     {
         id: "droid",
@@ -253,6 +254,8 @@ const SUPPORTED_CLIENTS = [
         base: "home",
         configs: [
             { segments: [".gemini", "config", "hooks.json"], base: "home", format: "json", purpose: "hooks" },
+            // Antigravity's documented global MCP file; the second is where 0.3.0 and earlier wrote, kept only so cleanup and uninstall reach it.
+            { segments: [".gemini", "config", "mcp_config.json"], base: "home", format: "json", purpose: "mcp" },
             { segments: ["mcp_config.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["hooks", "mcp", "skill"],
@@ -266,6 +269,8 @@ const SUPPORTED_CLIENTS = [
         base: "home",
         homeOverrideEnv: "COPILOT_HOME",
         configs: [
+            // Copilot CLI's documented MCP file; the second is where 0.3.0 and earlier wrote, kept only so cleanup and uninstall reach it.
+            { segments: ["mcp-config.json"], base: "client", format: "json", purpose: "mcp" },
             { segments: ["mcp.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["mcp", "skill"],
@@ -276,8 +281,12 @@ const SUPPORTED_CLIENTS = [
         id: "windsurf",
         displayName: "Windsurf",
         markerSegments: [".codeium", "windsurf"],
+        // Devin Desktop's folder: $XDG_CONFIG_HOME/devin, %APPDATA%\devin on Windows.
+        altMarkers: [{ segments: ["devin"], base: "xdg-config" }],
         base: "home",
         configs: [
+            // The file Windsurf's docs (now Devin Desktop's) name; the second is where 0.3.1 and earlier wrote, kept only so cleanup and uninstall reach it.
+            { segments: ["devin", "mcp_config.json"], base: "xdg-config", format: "json", purpose: "mcp" },
             { segments: ["mcp_config.json"], base: "client", format: "json", purpose: "mcp" },
         ],
         capabilities: ["mcp"],
@@ -324,14 +333,16 @@ function platformConfigDir(def, ctx, p) {
     switch (ctx.platform) {
         case "darwin":
             return p.join(ctx.home, "Library", "Application Support", appName);
-        case "win32": {
-            const appData = ctx.env["APPDATA"] ?? p.join(ctx.home, "AppData", "Roaming");
-            return p.join(absoluteOrHome(appData, ctx, p), appName);
-        }
+        case "win32":
+            return p.join(appDataRoot(ctx, p), appName);
         default:
             return p.join(xdgConfigRoot(ctx, p), appName);
     }
 }
+/** %APPDATA%, else the default roaming folder under the home. */
+function appDataRoot(ctx, p) {
+    return absoluteOrHome(ctx.env["APPDATA"] ?? p.join(ctx.home, "AppData", "Roaming"), ctx, p);
+}
 /** Treat a relative env override as home-relative so resolution never throws. */
 function absoluteOrHome(value, ctx, p) {
     return p.isAbsolute(value) ? value : p.join(ctx.home, value);
@@ -357,7 +368,8 @@ function resolveMarkerBase(target, ctx, p) {
         case "home":
             return p.join(ctx.home, ...segments);
         case "xdg-config":
-            return p.join(xdgConfigRoot(ctx, p), ...segments);
+            // As for config targets: %APPDATA% on Windows (Devin Desktop's folder for Windsurf).
+            return p.join(ctx.platform === "win32" ? appDataRoot(ctx, p) : xdgConfigRoot(ctx, p), ...segments);
         case "platform-config":
             return p.join(platformConfigDir(def, ctx, p), ...segments);
     }
@@ -388,6 +400,9 @@ function resolveConfigTarget(def, target, resolve) {
         case "platform-config":
             path = p.join(platformConfigDir(def, ctx, p), ...target.segments);
             break;
+        case "xdg-config":
+            path = p.join(ctx.platform === "win32" ? appDataRoot(ctx, p) : xdgConfigRoot(ctx, p), ...target.segments);
+            break;
     }
     return target.limitation === undefined
         ? { path, format: target.format, purpose: target.purpose }

package/dist/commands/memory.js

@@ -37,7 +37,12 @@ async function ask(ctx, request) {
         return 1;
     }
     const root = join(ctx.home, ".heed");
-    const backend = await backendAt(root, heedvaneConfigAt(root).url);
+    const config = heedvaneConfigAt(root);
+    if (config.dataMode === "metrics-only") {
+        ctx.out("  ✗ team memory is off on this machine: heed.yaml heedvane.dataMode is metrics-only, so no question or repository leaves it");
+        return 1;
+    }
+    const backend = await backendAt(root, config.url);
     if (backend === null) {
         ctx.out("  ✗ not signed in — run: npx heedvane login (or, headless: npx heedvane auth org < key-file)");
         return 1;

package/dist/doctor.js

@@ -8,7 +8,8 @@ import { join } from "node:path";
 import { supportedClients } from "./clients/definitions.js";
 import { entryValue, parseDoc, readEntry, valuesEqual } from "./config-doc.js";
 import { loadHeedFileAt } from "./heed-file.js";
-import { desiredEntriesFor, hooksDeferredTo, isClientDetected } from "./plan.js";
+import { desiredEntriesFor, heedvaneConnector, hooksDeferredTo, isClientDetected, legacyMcpEntries } from "./plan.js";
+import { MCP_NEEDS_ORG, connectorEntry } from "./mcp.js";
 import { readInstalledSkillDigest } from "./skill/bundle.js";
 import { HeedStateCorruptError, readState } from "./state.js";
 import { readApprovedSkills } from "./skills/approved.js";
@@ -109,13 +110,14 @@ void checkState;
 function scopeSet(clients) {
     return clients && clients.length > 0 ? new Set(clients) : null;
 }
-/** The pure-planner desired-entry lookup, resolving each client id against home/env. */
-function defaultDesiredLookup(home, env) {
+/** The pure-planner desired-entry lookup, resolving each client id against home/env and heed.yaml's organization. */
+function defaultDesiredLookup(home, env, heedFile) {
+    const connector = heedFile === undefined ? undefined : heedvaneConnector(heedFile);
     return (clientId, capability) => {
         const client = supportedClients({ home, platform: process.platform, env }).find((c) => c.id === clientId);
         if (!client)
             return undefined;
-        return desiredEntriesFor(client, capability, { home, env }).map((d) => ({
+        return desiredEntriesFor(client, capability, { home, env, connector }).map((d) => ({
             path: d.path,
             format: d.format,
             containerKey: d.containerKey,
@@ -160,13 +162,27 @@ function collectCapabilityStates(client, ctx) {
         const supported = client.capabilities.includes(capability) || (capability === "hooks" && client.id === "hermes" && client.capabilities.includes("plugin-install"));
         if (!supported || !heedFileWants(client, capability, ctx))
             continue;
-        const desireds = ctx.desired(client.id, capability);
-        if (!desireds || desireds.length === 0)
-            continue;
-        states.push({ capability, result: registrationState(desireds, ctx.home) });
+        const desireds = ctx.desired(client.id, capability) ?? [];
+        const result = capability === "mcp" ? mcpConnectionState(client, desireds, ctx.home) : hooksState(desireds, ctx.home);
+        if (result !== undefined)
+            states.push({ capability, result });
     }
     return states;
 }
+/** The hooks' registration verdict, when this client has hooks to register. */
+function hooksState(desireds, home) {
+    return desireds.length > 0 ? registrationState(desireds, home) : undefined;
+}
+/** Heedvane's MCP connection: stale while an earlier version's entry is left, missing without an organization, else the registration verdict. */
+function mcpConnectionState(client, desireds, home) {
+    const legacy = legacyMcpEntries(client);
+    if (legacy !== undefined)
+        return { state: "stale", detail: `${legacy.names.join(", ")} in ${legacy.path} is an earlier version's entry; npx heedvane connect replaces it` };
+    if (desireds.length > 0)
+        return registrationState(desireds, home);
+    // Agents the connection is not registered in have nothing to check.
+    return connectorEntry(client.id, "") === undefined ? undefined : { state: "missing", detail: MCP_NEEDS_ORG };
+}
 /** One detected client's registration check (aligned / stale / missing with per-entry detail). */
 function pushRegistrationChecks(checks, client, ctx) {
     const detected = isClientDetected(client);
@@ -233,7 +249,7 @@ export async function runDoctor(input) {
     const root = join(home, ".heed");
     const state = await readStateOrReport(root, checks);
     // 4. Desired-entry lookup: injected, falling back to the pure planner.
-    const desired = input.desired ?? defaultDesiredLookup(home, env);
+    const desired = input.desired ?? defaultDesiredLookup(home, env, heedFile);
     // 5. Per detected client: registration state aligned | stale | missing.
     const scope = scopeSet(input.clients);
     const allClients = supportedClients({ home, platform: process.platform, env });