heedvane 0.2.1 → 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.
 

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,13 +99,14 @@ function parseInvocation(args) {
         clients: parseRepeatedFlag(args, "--client"),
         server: flagValue(args, "--server") ?? flagValue(args, "--url"),
         org: flagValue(args, "--org"),
+        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", "--token"];
+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("--");
@@ -168,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 ?? {},
@@ -197,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) });
         }
@@ -260,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;
@@ -289,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 };
 }
@@ -305,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)
@@ -318,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. */
@@ -331,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.
@@ -421,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);
@@ -429,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",
@@ -467,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) {
@@ -503,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 {
@@ -676,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 });

package/dist/heed-file.d.ts

@@ -27,9 +27,19 @@ export interface HeedSkillsConfig {
     /** No synced approved list, or no listener to check it: let the skill run with a warning, or deny it. */
     whenUnknown: "allow" | "deny";
 }
+/**
+ * What leaves this machine (the installer and data modes proposal, "Proposed data modes"). `look-but-dont-keep`:
+ * Heedvane's guardrail checks read the prompt or tool call and keep only the verdict. `metrics-only`: only counts and
+ * names leave; the organization's fixed rules still run here, Heedvane's own checks and team memory do not.
+ */
+export declare const DATA_MODES: readonly ["look-but-dont-keep", "metrics-only"];
+export type DataMode = (typeof DATA_MODES)[number];
 /** The Heedvane backend the listener asks for steering, approved skills and memory. */
 export interface HeedvaneConfig {
     url: string;
+    /** The organization `connect --org` named: Heedvane's MCP connection URL carries it. */
+    org?: string;
+    dataMode: DataMode;
     steering: boolean;
     memory: boolean;
     skills: HeedSkillsConfig;
@@ -47,7 +57,7 @@ export interface HeedFile {
  * The commented control file written by `npx heedvane init`.
  * Kept loadable: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE) yields every default.
  */
-export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 Heedvane agent hooks control file (v1)\nschemaVersion: v1\n\n# Where managed scripts and spool live. Default below; one install per machine.\nroot: ~/.heed\n\n# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.\nlistener:\n  port: 0            # 0 = pick a free port at first start, persist to endpoint.env\n  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)\n\n# Which agents to manage. `auto` = every detected agent on the machine.\nagents: auto        # or an explicit list: [claude, codex, warp]\n\n# Which integrations to install per agent where supported.\ninstall:\n  hooks: true       # native hook config injection (skipped where the agent has none)\n  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/\n  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)\n\n# Session gating (Orca's env-gated dispatcher pattern).\ngating:\n  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env\n\n# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).\nheedvane:\n  url: https://app.heedvane.com\n  steering: true      # ask the organization's steering rules before tool calls, prompts and stops\n  memory: true        # add your private memories (~/.heed/memory, local only) at session start\n  skills:\n    enforce: true     # deny skills that are not on the organization's approved list\n    strict: false     # also require the local SKILL.md to match the approved revision\n    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny\n";
+export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 Heedvane agent hooks control file (v1)\nschemaVersion: v1\n\n# Where managed scripts and spool live. Default below; one install per machine.\nroot: ~/.heed\n\n# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.\nlistener:\n  port: 0            # 0 = pick a free port at first start, persist to endpoint.env\n  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)\n\n# Which agents to manage. `auto` = every detected agent on the machine.\nagents: auto        # or an explicit list: [claude, codex, warp]\n\n# Which integrations to install per agent where supported.\ninstall:\n  hooks: true       # native hook config injection (skipped where the agent has none)\n  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/\n  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)\n\n# Session gating (Orca's env-gated dispatcher pattern).\ngating:\n  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env\n\n# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).\nheedvane:\n  url: https://app.heedvane.com\n  dataMode: look-but-dont-keep  # what leaves this machine: look-but-dont-keep (checks read prompts and tool calls, keep only verdicts) or metrics-only (only counts and names)\n  steering: true      # ask the organization's steering rules before tool calls, prompts and stops\n  memory: true        # add your private memories (~/.heed/memory, local only) at session start\n  skills:\n    enforce: true     # deny skills that are not on the organization's approved list\n    strict: false     # also require the local SKILL.md to match the approved revision\n    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny\n";
 /**
  * Parse and validate a heed.yaml document, returning the fully normalized file.
  * Throws {@link HeedFileError} (message prefixed "invalid heed.yaml:") on any problem:
@@ -55,6 +65,8 @@ export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 He
  * (top-level or nested), or wrong-typed values.
  */
 export declare function loadHeedFile(text: string): HeedFile;
+/** `text` with each `[path, value]` written in place; the file's comments stay. Validate with {@link loadHeedFile}. */
+export declare function withSettings(text: string, settings: ReadonlyArray<readonly [string[], unknown]>): string;
 /** `text` with `heedvane.url` set to `url` (`connect --server`); the file's comments stay. Validate with {@link loadHeedFile}. */
 export declare function withServerUrl(text: string, url: string): string;
 /** What the interactive installer asks: which agents, which integrations, and which Heedvane features. */
@@ -62,6 +74,7 @@ export interface InstallChoices {
     /** Chosen agent ids, or "auto" for every detected agent. */
     agents: "auto" | string[];
     install: HeedInstallConfig;
+    dataMode: DataMode;
     steering: boolean;
     memory: boolean;
     skillChecks: boolean;