zam-core 0.10.3 → 0.10.4

package/dist/cli/commands/mcp.js

@@ -5481,20 +5481,20 @@ import { homedir as homedir5 } from "os";
 import { join as join8 } from "path";
 import { fileURLToPath } from "url";
 function getPackageSkillPath(agent = "default") {
-  const packageRoot2 = [
+  const packageRoot4 = [
     fileURLToPath(new URL("../../..", import.meta.url)),
     fileURLToPath(new URL("../..", import.meta.url)),
     fileURLToPath(new URL("..", import.meta.url))
   ].find((candidate) => existsSync7(join8(candidate, "package.json"))) ?? "";
-  if (!packageRoot2) return "";
+  if (!packageRoot4) return "";
   if (agent === "codex") {
-    const codexPath = join8(packageRoot2, ".agents", "skills", "zam", "SKILL.md");
+    const codexPath = join8(packageRoot4, ".agents", "skills", "zam", "SKILL.md");
     if (existsSync7(codexPath)) return codexPath;
     return "";
   }
   if (agent === "claude") {
     const claudePath = join8(
-      packageRoot2,
+      packageRoot4,
       ".claude",
       "skills",
       "zam",
@@ -5503,9 +5503,9 @@ function getPackageSkillPath(agent = "default") {
     if (existsSync7(claudePath)) return claudePath;
     return "";
   }
-  let path = join8(packageRoot2, ".agent", "skills", "zam", "SKILL.md");
+  let path = join8(packageRoot4, ".agent", "skills", "zam", "SKILL.md");
   if (existsSync7(path)) return path;
-  path = join8(packageRoot2, ".claude", "skills", "zam", "SKILL.md");
+  path = join8(packageRoot4, ".claude", "skills", "zam", "SKILL.md");
   if (existsSync7(path)) return path;
   return "";
 }
@@ -5946,6 +5946,18 @@ function saveMachineAiConfig(ai, path = defaultConfigPath()) {
   config.ai = ai;
   saveInstallConfig(config, path);
 }
+function getAgentConnectAutoDone(path = defaultConfigPath()) {
+  return loadInstallConfig(path).agent?.connectAutoDone === true;
+}
+function setAgentConnectAutoDone(done, path = defaultConfigPath()) {
+  const config = loadInstallConfig(path);
+  if (done) {
+    config.agent = { ...config.agent ?? {}, connectAutoDone: true };
+  } else if (config.agent) {
+    delete config.agent.connectAutoDone;
+  }
+  saveInstallConfig(config, path);
+}
 function getConfiguredWorkspaces(path = defaultConfigPath()) {
   return loadInstallConfig(path).workspaces ?? [];
 }
@@ -6622,6 +6634,7 @@ __export(kernel_exports, {
   getActiveWorkspace: () => getActiveWorkspace,
   getActiveWorkspaceContext: () => getActiveWorkspaceContext,
   getActiveWorkspaceId: () => getActiveWorkspaceId,
+  getAgentConnectAutoDone: () => getAgentConnectAutoDone,
   getAgentSkill: () => getAgentSkill,
   getAllSettings: () => getAllSettings,
   getAllSettingsDetailed: () => getAllSettingsDetailed,
@@ -6731,6 +6744,7 @@ __export(kernel_exports, {
   setADOCredentials: () => setADOCredentials,
   setActiveWorkspaceContext: () => setActiveWorkspaceContext,
   setActiveWorkspaceId: () => setActiveWorkspaceId,
+  setAgentConnectAutoDone: () => setAgentConnectAutoDone,
   setInstallChannel: () => setInstallChannel,
   setInstallMode: () => setInstallMode,
   setProviderApiKey: () => setProviderApiKey,
@@ -6809,9 +6823,9 @@ var init_kernel = __esm({
 
 // src/cli/commands/mcp.ts
 init_kernel();
-import { existsSync as existsSync17, readFileSync as readFileSync15 } from "fs";
-import { dirname as dirname8, join as join21 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { existsSync as existsSync19, readFileSync as readFileSync17 } from "fs";
+import { dirname as dirname11, join as join23 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
 import {
   RESOURCE_MIME_TYPE,
   registerAppResource,
@@ -6854,6 +6868,7 @@ var DEFAULT_LLM_URL = "http://localhost:8000/v1";
 var DEFAULT_LLM_MAX_TOKENS = 1e4;
 var RECALL_QUESTION_MAX_OUTPUT_TOKENS = 400;
 var RECALL_EVALUATION_MAX_OUTPUT_TOKENS = 1200;
+var RECALL_DISCUSSION_MAX_OUTPUT_TOKENS = 1200;
 var RECALL_ENDPOINT_CACHE_MS = 6e4;
 var cachedRecallEndpoint = null;
 function recallEndpointSignature(cfg) {
@@ -7216,6 +7231,64 @@ Evaluation:`;
     providerName: endpoint.providerName
   };
 }
+async function discussReviewViaLLM(db, input) {
+  const cfg = await getProviderForRole(db, "recall");
+  const endpoint = await resolveUsableRecallEndpoint(db);
+  const langName = LANGUAGE_NAMES[cfg.locale] || "English";
+  const systemPrompt = `You are ZAM, a warm, precise, and encouraging skills trainer in a follow-up discussion about one flashcard.
+The learner has already answered, the reference answer is revealed, and your evaluation feedback was shown \u2014 nothing about this card is a spoiler anymore.
+
+Guidelines:
+1. Answer the learner's follow-up directly and concretely in ${langName}, grounded in the card's target concept, context, and source reference.
+2. Stay scoped to this card and its concept. If the learner drifts to unrelated territory, answer briefly and steer back to the concept.
+3. Keep replies conversational and short (a few sentences) unless the learner explicitly asks for depth. Plain text only \u2014 no markdown wrapper, headers, or bullet lists.
+4. The self-rating is the learner's own choice. If asked, explain the FSRS scale (1 forgot, 2 hard, 3 good, 4 easy) but never pressure them toward a specific rating.`;
+  const cardFrame = `The card under discussion:
+Domain: ${input.domain}
+Slug: ${input.slug}
+Recall Question: ${input.question}
+Learner's Answer: ${input.userAnswer}
+
+Target Concept (Correct Answer): ${input.concept}
+Target Context: ${input.context || "(none)"}
+${input.sourceLinkContent ? `Source Code Reference:
+${input.sourceLinkContent}` : ""}`;
+  const messages = [
+    { role: "system", content: systemPrompt },
+    { role: "user", content: cardFrame }
+  ];
+  const feedback = input.feedback?.trim();
+  if (feedback) {
+    messages.push({ role: "assistant", content: feedback });
+  }
+  for (const turn of input.thread) {
+    messages.push({ role: turn.role, content: turn.content });
+  }
+  messages.push({ role: "user", content: input.message });
+  const res = await fetchWithInteractiveTimeout(
+    `${endpoint.url}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${endpoint.apiKey}`
+      },
+      body: JSON.stringify({
+        model: endpoint.model,
+        messages,
+        temperature: 0.3,
+        max_tokens: RECALL_DISCUSSION_MAX_OUTPUT_TOKENS
+      }),
+      locale: cfg.locale
+    }
+  );
+  const text = await readChatContent(res, "LLM discussion");
+  return {
+    text,
+    model: endpoint.model,
+    providerName: endpoint.providerName
+  };
+}
 var MAX_IMPORT_TEXT_CHARS = 2e5;
 var VALID_GENERATED_MODES = /* @__PURE__ */ new Set(["shadowing", "copilot", "autonomy"]);
 function parseGeneratedCardArray(responseText, label, limits) {
@@ -7803,7 +7876,7 @@ async function prepareRecallChain(db, opts) {
       } else {
         spawnLocalRunner(endpoint.url, endpoint.model, endpoint.runner);
         while (Date.now() < deadline) {
-          await new Promise((resolve5) => setTimeout(resolve5, 1e3));
+          await new Promise((resolve6) => setTimeout(resolve6, 1e3));
           if (await isLlmOnline(endpoint.url)) {
             online = true;
             break;
@@ -8096,7 +8169,7 @@ async function startLocalRunner(url, model, locale, hint) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve5) => setTimeout(resolve5, 500));
+    await new Promise((resolve6) => setTimeout(resolve6, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -8156,8 +8229,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve5) => {
-      timeoutId = setTimeout(() => resolve5("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve6) => {
+      timeoutId = setTimeout(() => resolve6("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -9501,11 +9574,11 @@ async function publishUiIntent(app, input = {}, opts = {}) {
 
 // src/cli/commands/bridge.ts
 init_kernel();
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import { existsSync as existsSync16, readdirSync as readdirSync2, readFileSync as readFileSync14, rmSync as rmSync3 } from "fs";
-import { homedir as homedir11, tmpdir as tmpdir3 } from "os";
-import { join as join20, resolve as resolve4 } from "path";
+import { existsSync as existsSync18, readdirSync as readdirSync2, readFileSync as readFileSync16, rmSync as rmSync3 } from "fs";
+import { homedir as homedir14, tmpdir as tmpdir3 } from "os";
+import { join as join22, resolve as resolve5 } from "path";
 import { Command } from "commander";
 import { ulid as ulid10 } from "ulid";
 
@@ -9584,7 +9657,7 @@ async function readWebLink(url) {
         redirect: "manual",
         signal: controller.signal,
         headers: {
-          "User-Agent": "ZAM-Content-Studio/0.10.0"
+          "User-Agent": "ZAM-Content-Studio/0.10.4"
         }
       });
       if (res.status >= 300 && res.status < 400) {
@@ -9647,6 +9720,12 @@ async function readImageOCR(db, imagePath) {
   return extractTextFromScanViaLLM(db, imagePath);
 }
 
+// src/cli/agent-connect.ts
+init_kernel();
+import { mkdirSync as mkdirSync12, writeFileSync as writeFileSync10 } from "fs";
+import { homedir as homedir13 } from "os";
+import { dirname as dirname9 } from "path";
+
 // src/cli/agent-harness.ts
 import { spawn as spawn2 } from "child_process";
 import { existsSync as existsSync14, readFileSync as readFileSync11 } from "fs";
@@ -9967,6 +10046,710 @@ function launchHarness(harness, opts) {
     console.log(`Launched ${harness.label} in ${opts.workspace}`);
   }
 }
+function detectInstalledConnectHarnesses(options = {}) {
+  const home = options.home ?? homedir10();
+  const platform = options.platform ?? process.platform;
+  const find = options.find ?? findExecutable;
+  const exists = options.exists ?? existsSync14;
+  const detected = [];
+  const hasCommandOrPath = (command, paths = []) => Boolean(find(command)) || paths.some((path) => exists(path));
+  if (hasCommandOrPath("codex", [
+    join16(home, ".codex"),
+    ...platform === "darwin" ? ["/Applications/Codex.app"] : platform === "win32" ? [join16(home, "AppData", "Local", "Programs", "Codex")] : []
+  ])) {
+    detected.push("codex");
+  }
+  const vscodePaths = platform === "darwin" ? [
+    "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
+    join16(
+      home,
+      "Applications",
+      "Visual Studio Code.app",
+      "Contents",
+      "Resources",
+      "app",
+      "bin",
+      "code"
+    )
+  ] : platform === "win32" ? [
+    join16(
+      home,
+      "AppData",
+      "Local",
+      "Programs",
+      "Microsoft VS Code",
+      "bin",
+      "code.cmd"
+    )
+  ] : ["/usr/bin/code", "/usr/local/bin/code", "/snap/bin/code"];
+  if (hasCommandOrPath("code", vscodePaths)) detected.push("vscode");
+  const copilotHome = options.copilotHome ?? join16(home, ".copilot");
+  if (hasCommandOrPath("copilot", [
+    copilotHome,
+    ...platform === "darwin" ? ["/Applications/GitHub Copilot.app"] : []
+  ])) {
+    detected.push("copilot");
+  }
+  if (hasCommandOrPath("opencode", [join16(home, ".config", "opencode")])) {
+    detected.push("opencode");
+  }
+  if (hasCommandOrPath("goose", [join16(home, ".config", "goose")])) {
+    detected.push("goose");
+  }
+  if (hasCommandOrPath("antigravity", [
+    join16(home, ".gemini", "config"),
+    ...platform === "darwin" ? [
+      join16(
+        home,
+        ".antigravity-ide",
+        "antigravity-ide",
+        "bin",
+        "antigravity-ide"
+      ),
+      "/Applications/Antigravity.app",
+      "/Applications/Antigravity IDE.app"
+    ] : []
+  ]) || find("antigravity-ide")) {
+    detected.push("antigravity");
+  }
+  const claudeDesktopPath = platform === "darwin" ? "/Applications/Claude.app" : platform === "win32" ? join16(home, "AppData", "Local", "AnthropicClaude") : join16(home, ".config", "Claude");
+  if (exists(claudeDesktopPath)) detected.push("claude-desktop");
+  return detected;
+}
+function parseMcpJsonConfig(path, content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new Error(
+      `Cannot update ${path}: existing file is not valid JSON (${error instanceof Error ? error.message : String(error)})`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Cannot update ${path}: expected a JSON object`);
+  }
+  const config = parsed;
+  if (config.mcpServers !== void 0 && (typeof config.mcpServers !== "object" || config.mcpServers === null || Array.isArray(config.mcpServers))) {
+    throw new Error(`Cannot update ${path}: mcpServers must be a JSON object`);
+  }
+  return config;
+}
+function connectHarnessMcp(harnessId, opts) {
+  const exists = (p) => {
+    if (opts.readFile) {
+      try {
+        opts.readFile(p);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    return existsSync14(p);
+  };
+  const read = (p) => {
+    if (opts.readFile) return opts.readFile(p);
+    return readFileSync11(p, "utf-8");
+  };
+  let targetPath = "";
+  let content = "";
+  let alreadyConfigured = false;
+  let hint = "";
+  const mergeMcpServersJson = (path) => {
+    let existing = {};
+    if (exists(path)) {
+      existing = parseMcpJsonConfig(path, read(path));
+    }
+    if (!existing.mcpServers) {
+      existing.mcpServers = {};
+    }
+    existing.mcpServers.zam = {
+      command: opts.zamPath,
+      args: ["mcp"]
+    };
+    return JSON.stringify(existing, null, 2);
+  };
+  if (harnessId === "claude-code") {
+    targetPath = join16(opts.cwd, ".mcp.json");
+    hint = "Claude Code will prompt you to approve the 'zam' MCP server on next launch.";
+    content = mergeMcpServersJson(targetPath);
+  } else if (harnessId === "claude-desktop") {
+    const platform = opts.platform ?? process.platform;
+    targetPath = platform === "win32" ? join16(
+      opts.home,
+      "AppData",
+      "Roaming",
+      "Claude",
+      "claude_desktop_config.json"
+    ) : platform === "darwin" ? join16(
+      opts.home,
+      "Library",
+      "Application Support",
+      "Claude",
+      "claude_desktop_config.json"
+    ) : join16(opts.home, ".config", "Claude", "claude_desktop_config.json");
+    hint = "Restart Claude Desktop to load the 'zam' MCP server; MCP Apps panels render inline in the chat.";
+    content = mergeMcpServersJson(targetPath);
+  } else if (harnessId === "antigravity") {
+    targetPath = join16(opts.home, ".gemini", "config", "mcp_config.json");
+    hint = "Shared config read by Antigravity CLI and IDE (2.0+); older IDE builds read ~/.gemini/antigravity/mcp_config.json instead. Refresh Installed MCP Servers; the first tool call may still require approval.";
+    let existing = {};
+    if (exists(targetPath)) {
+      existing = parseMcpJsonConfig(targetPath, read(targetPath));
+    }
+    if (!existing.mcpServers) {
+      existing.mcpServers = {};
+    }
+    existing.mcpServers.zam = {
+      command: opts.zamPath,
+      args: ["mcp"]
+    };
+    content = JSON.stringify(existing, null, 2);
+  } else if (harnessId === "opencode") {
+    targetPath = join16(opts.home, ".config", "opencode", "opencode.json");
+    hint = "OpenCode will load the enabled 'zam' MCP server on next launch.";
+    let existing = {};
+    if (exists(targetPath)) {
+      existing = parseMcpJsonConfig(targetPath, read(targetPath));
+    }
+    const mcp = existing.mcp;
+    if (mcp !== void 0 && (typeof mcp !== "object" || mcp === null || Array.isArray(mcp))) {
+      throw new Error(`Cannot update ${targetPath}: mcp must be a JSON object`);
+    }
+    const servers = mcp ?? {};
+    servers.zam = {
+      type: "local",
+      command: [opts.zamPath, "mcp"],
+      enabled: true
+    };
+    existing.mcp = servers;
+    content = JSON.stringify(existing, null, 2);
+  } else if (harnessId === "codex") {
+    targetPath = join16(opts.home, ".codex", "config.toml");
+    hint = "Codex will prompt for tool execution approvals or respect the TOML approval modes.";
+    let existingStr = "";
+    if (exists(targetPath)) {
+      existingStr = read(targetPath);
+    }
+    if (existingStr.includes("[mcp_servers.zam]")) {
+      alreadyConfigured = true;
+      content = existingStr;
+    } else {
+      const block = `
+[mcp_servers.zam]
+command = ${JSON.stringify(opts.zamPath)}
+args = ["mcp"]
+default_tools_approval_mode = "approve"
+
+[mcp_servers.zam.tools.zam_review_action]
+approval_mode = "prompt"
+`;
+      content = existingStr ? `${existingStr.trimEnd()}
+${block}` : block;
+    }
+  } else if (harnessId === "vscode") {
+    const platform = opts.platform ?? process.platform;
+    targetPath = platform === "win32" ? join16(opts.home, "AppData", "Roaming", "Code", "User", "mcp.json") : platform === "darwin" ? join16(
+      opts.home,
+      "Library",
+      "Application Support",
+      "Code",
+      "User",
+      "mcp.json"
+    ) : join16(opts.home, ".config", "Code", "User", "mcp.json");
+    hint = "Reload VS Code after setup. ZAM Companion stays separate from the Codex chat and can be moved to any panel or sidebar.";
+    let existing = {};
+    if (exists(targetPath)) {
+      existing = parseMcpJsonConfig(targetPath, read(targetPath));
+    }
+    if (existing.servers !== void 0 && (typeof existing.servers !== "object" || existing.servers === null || Array.isArray(existing.servers))) {
+      throw new Error(
+        `Cannot update ${targetPath}: servers must be a JSON object`
+      );
+    }
+    if (existing.inputs !== void 0 && !Array.isArray(existing.inputs)) {
+      throw new Error(`Cannot update ${targetPath}: inputs must be an array`);
+    }
+    if (!existing.servers) existing.servers = {};
+    const expectedServer = { command: opts.zamPath, args: ["mcp"] };
+    const currentServer = existing.servers.zam;
+    alreadyConfigured = Array.isArray(existing.inputs) && typeof currentServer === "object" && currentServer !== null && !Array.isArray(currentServer) && JSON.stringify(currentServer) === JSON.stringify(expectedServer);
+    existing.servers.zam = expectedServer;
+    if (!existing.inputs) existing.inputs = [];
+    content = JSON.stringify(existing, null, 2);
+  } else if (harnessId === "goose") {
+    targetPath = join16(opts.home, ".config", "goose", "config.yaml");
+    hint = "goose will load the 'zam' extension on next session start. Run 'goose configure' to manage extensions.";
+    const zamExtension = [
+      "  zam:",
+      "    name: ZAM",
+      `    cmd: ${opts.zamPath}`,
+      "    args:",
+      "      - mcp",
+      "    enabled: true",
+      "    type: stdio",
+      "    timeout: 300",
+      "    description: Symbiotic learning agent with spaced repetition"
+    ].join("\n");
+    let existingStr = "";
+    if (exists(targetPath)) {
+      existingStr = read(targetPath);
+    }
+    if (/^\s+zam:\s*$/m.test(existingStr) && existingStr.includes("- mcp")) {
+      alreadyConfigured = true;
+      content = existingStr;
+    } else if (/^extensions:[ \t]*$/m.test(existingStr)) {
+      content = existingStr.replace(
+        /^extensions:[ \t]*$/m,
+        (line) => `${line}
+${zamExtension}`
+      );
+    } else if (existingStr.trim()) {
+      content = `${existingStr.trimEnd()}
+extensions:
+${zamExtension}
+`;
+    } else {
+      content = `extensions:
+${zamExtension}
+`;
+    }
+  } else if (harnessId === "copilot") {
+    targetPath = join16(
+      opts.copilotHome ?? join16(opts.home, ".copilot"),
+      "mcp-config.json"
+    );
+    hint = "Restart GitHub Copilot or start a new session to load the 'zam' MCP server and its focused Recall, Graph, and Settings canvases.";
+    let existing = {};
+    if (exists(targetPath)) {
+      existing = parseMcpJsonConfig(targetPath, read(targetPath));
+    }
+    if (!existing.mcpServers) {
+      existing.mcpServers = {};
+    }
+    existing.mcpServers.zam = {
+      type: "local",
+      command: opts.zamPath,
+      args: ["mcp"],
+      tools: ["*"]
+    };
+    content = JSON.stringify(existing, null, 2);
+  }
+  return {
+    path: targetPath,
+    content,
+    alreadyConfigured,
+    hint
+  };
+}
+
+// src/cli/copilot-extension.ts
+import {
+  existsSync as existsSync15,
+  lstatSync,
+  mkdirSync as mkdirSync10,
+  readFileSync as readFileSync12,
+  writeFileSync as writeFileSync8
+} from "fs";
+import { homedir as homedir11 } from "os";
+import { dirname as dirname7, join as join17, resolve as resolve4 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+var EXTENSION_NAME = "zam-mcp-apps";
+var EXTENSION_FILES = [
+  "extension.mjs",
+  "host.bundle.js",
+  "mcp-client.bundle.mjs",
+  "manifest.json"
+];
+var packageRoot = [
+  fileURLToPath3(new URL("../..", import.meta.url)),
+  fileURLToPath3(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync15(join17(candidate, "package.json"))) ?? fileURLToPath3(new URL("../..", import.meta.url));
+function defaultCliEntry() {
+  return join17(dirname7(fileURLToPath3(import.meta.url)), "index.js");
+}
+function resolveCopilotHome(home = homedir11(), configuredHome = process.env.COPILOT_HOME) {
+  return configuredHome?.trim() ? resolve4(configuredHome) : join17(home, ".copilot");
+}
+function resolveCopilotZamLaunch(zamPath, options = {}) {
+  const cliEntry = options.cliEntry ?? defaultCliEntry();
+  if (existsSync15(cliEntry)) {
+    return {
+      command: options.nodePath ?? process.execPath,
+      args: [cliEntry, "mcp"]
+    };
+  }
+  return {
+    command: zamPath,
+    args: ["mcp"]
+  };
+}
+function planCopilotExtensionInstall(options) {
+  const sourceDir = options.assetsDir ?? join17(packageRoot, "dist", "copilot-extension");
+  for (const file of EXTENSION_FILES) {
+    if (!existsSync15(join17(sourceDir, file))) {
+      throw new Error(
+        `Copilot MCP Apps asset is missing: ${join17(sourceDir, file)}. Run \`npm run build\` and retry.`
+      );
+    }
+  }
+  const manifest = JSON.parse(
+    readFileSync12(join17(sourceDir, "manifest.json"), "utf8")
+  );
+  if (manifest.name !== EXTENSION_NAME || typeof manifest.version !== "string" || !manifest.version) {
+    throw new Error(
+      `Invalid Copilot MCP Apps manifest: ${join17(sourceDir, "manifest.json")}`
+    );
+  }
+  const copilotHome = resolveCopilotHome(
+    options.home,
+    options.copilotHome ?? process.env.COPILOT_HOME
+  );
+  return {
+    sourceDir,
+    destinationDir: join17(copilotHome, "extensions", EXTENSION_NAME),
+    launch: resolveCopilotZamLaunch(options.zamPath, options),
+    files: EXTENSION_FILES
+  };
+}
+function writeIfChanged(path, content) {
+  const next = Buffer.isBuffer(content) ? content : Buffer.from(content);
+  if (existsSync15(path) && readFileSync12(path).equals(next)) return false;
+  writeFileSync8(path, next);
+  return true;
+}
+function installCopilotExtension(options) {
+  const plan = planCopilotExtensionInstall(options);
+  if (options.dryRun) {
+    return { ...plan, action: "planned", changedFiles: [] };
+  }
+  const destinationExisted = existsSync15(plan.destinationDir);
+  if (destinationExisted && lstatSync(plan.destinationDir).isSymbolicLink()) {
+    throw new Error(
+      `Refusing to replace symlinked Copilot extension directory: ${plan.destinationDir}`
+    );
+  }
+  mkdirSync10(plan.destinationDir, { recursive: true });
+  const changedFiles = [];
+  for (const file of plan.files) {
+    const source = join17(plan.sourceDir, file);
+    const destination = join17(plan.destinationDir, file);
+    if (writeIfChanged(destination, readFileSync12(source))) {
+      changedFiles.push(file);
+    }
+  }
+  const launchContent = `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      command: plan.launch.command,
+      args: plan.launch.args
+    },
+    null,
+    2
+  )}
+`;
+  if (writeIfChanged(join17(plan.destinationDir, "launch.json"), launchContent)) {
+    changedFiles.push("launch.json");
+  }
+  return {
+    ...plan,
+    action: !destinationExisted ? "installed" : changedFiles.length > 0 ? "updated" : "unchanged",
+    changedFiles
+  };
+}
+
+// src/cli/vscode-extension.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { existsSync as existsSync16, mkdirSync as mkdirSync11, readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "fs";
+import { homedir as homedir12 } from "os";
+import { dirname as dirname8, join as join18 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+var packageRoot2 = [
+  fileURLToPath4(new URL("../..", import.meta.url)),
+  fileURLToPath4(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync16(join18(candidate, "package.json"))) ?? fileURLToPath4(new URL("../..", import.meta.url));
+function resolveVscodeExecutable(options = {}) {
+  const home = options.home ?? homedir12();
+  const platform = options.platform ?? process.platform;
+  const find = options.find ?? findExecutable;
+  const exists = options.exists ?? existsSync16;
+  const found = find("code");
+  if (found) return found;
+  const candidates = platform === "darwin" ? [
+    "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
+    join18(
+      home,
+      "Applications",
+      "Visual Studio Code.app",
+      "Contents",
+      "Resources",
+      "app",
+      "bin",
+      "code"
+    )
+  ] : platform === "win32" ? [
+    join18(
+      home,
+      "AppData",
+      "Local",
+      "Programs",
+      "Microsoft VS Code",
+      "bin",
+      "code.cmd"
+    )
+  ] : ["/usr/bin/code", "/usr/local/bin/code", "/snap/bin/code"];
+  return candidates.find((candidate) => exists(candidate)) ?? null;
+}
+function packageVersion() {
+  const parsed = JSON.parse(
+    readFileSync13(join18(packageRoot2, "package.json"), "utf8")
+  );
+  if (typeof parsed.version !== "string" || !parsed.version) {
+    throw new Error("Cannot determine the ZAM package version");
+  }
+  return parsed.version;
+}
+function planVscodeExtensionInstall(options) {
+  const home = options.home ?? homedir12();
+  const version = options.version ?? packageVersion();
+  const assetsDir = options.assetsDir ?? join18(packageRoot2, "dist", "vscode-extension");
+  const vsixPath = join18(assetsDir, `ZAM_Companion_${version}.vsix`);
+  if (!existsSync16(vsixPath)) {
+    throw new Error(
+      `ZAM Companion VSIX asset is missing: ${vsixPath}. Run \`npm run build\` and retry.`
+    );
+  }
+  const codePath = options.codePath ?? resolveVscodeExecutable({
+    home,
+    platform: options.platform,
+    find: options.find,
+    exists: options.exists
+  });
+  if (!codePath) {
+    throw new Error(
+      "Visual Studio Code was not detected. Install VS Code or add its 'code' command to PATH."
+    );
+  }
+  return {
+    version,
+    vsixPath,
+    codePath,
+    launchConfigPath: join18(home, ".zam", "vscode-launch.json"),
+    launch: { command: options.zamPath, args: ["mcp"] }
+  };
+}
+function installVscodeExtension(options) {
+  const plan = planVscodeExtensionInstall(options);
+  if (options.dryRun) return { ...plan, action: "planned" };
+  const launchContent = `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      version: plan.version,
+      command: plan.launch.command,
+      args: plan.launch.args
+    },
+    null,
+    2
+  )}
+`;
+  const existed = existsSync16(plan.launchConfigPath);
+  const changed = !existed || readFileSync13(plan.launchConfigPath, "utf8") !== launchContent;
+  const run = options.run ?? ((command, args) => {
+    execFileSync3(command, args, { stdio: "pipe" });
+  });
+  run(plan.codePath, ["--install-extension", plan.vsixPath, "--force"]);
+  if (changed) {
+    mkdirSync11(dirname8(plan.launchConfigPath), { recursive: true });
+    writeFileSync9(plan.launchConfigPath, launchContent, "utf8");
+  }
+  return {
+    ...plan,
+    action: !existed ? "installed" : changed ? "updated" : "unchanged"
+  };
+}
+
+// src/cli/agent-connect.ts
+var CONNECT_HARNESSES = [
+  "claude-code",
+  "claude-desktop",
+  "antigravity",
+  "codex",
+  "vscode",
+  "opencode",
+  "goose",
+  "copilot"
+];
+var USER_SCOPED_CONNECT_HARNESSES = [
+  "claude-desktop",
+  "antigravity",
+  "codex",
+  "vscode",
+  "opencode",
+  "goose",
+  "copilot"
+];
+var CONNECT_HARNESS_LABELS = {
+  "claude-code": "Claude Code",
+  "claude-desktop": "Claude Desktop",
+  antigravity: "Antigravity",
+  codex: "Codex",
+  vscode: "VS Code",
+  opencode: "OpenCode",
+  goose: "Goose",
+  copilot: "GitHub Copilot"
+};
+function isConnectHarnessId(value) {
+  return CONNECT_HARNESSES.includes(value);
+}
+function resolveDeps(deps) {
+  const home = deps.home ?? homedir13();
+  const cwd = deps.cwd ?? process.cwd();
+  const copilotHome = deps.copilotHome ?? process.env.COPILOT_HOME;
+  return {
+    home,
+    cwd,
+    copilotHome,
+    findZam: deps.findZam ?? (() => findExecutable("zam")),
+    detect: deps.detect ?? (() => detectInstalledConnectHarnesses({ home, copilotHome })),
+    connectMcp: deps.connectMcp ?? connectHarnessMcp,
+    writeConfig: deps.writeConfig ?? ((path, content) => {
+      mkdirSync12(dirname9(path), { recursive: true });
+      writeFileSync10(path, content, "utf-8");
+    }),
+    installCopilot: deps.installCopilot ?? installCopilotExtension,
+    installVscode: deps.installVscode ?? installVscodeExtension,
+    resolveAntigravity: deps.resolveAntigravity ?? resolveAntigravityIdeExecutable,
+    refreshSkills: deps.refreshSkills ?? distributeGlobalSkills
+  };
+}
+function performAgentConnect(opts = {}, deps = {}) {
+  const d = resolveDeps(deps);
+  const dryRun = Boolean(opts.dryRun);
+  const detected = opts.harness ? [opts.harness] : d.detect();
+  const foundZam = d.findZam();
+  const zamPath = foundZam ?? "zam";
+  const results = [];
+  for (const harness of detected) {
+    const label = CONNECT_HARNESS_LABELS[harness];
+    try {
+      const prepared = d.connectMcp(harness, {
+        zamPath,
+        cwd: d.cwd,
+        home: d.home,
+        copilotHome: d.copilotHome
+      });
+      let extension = null;
+      if (harness === "copilot") {
+        const installed = d.installCopilot({
+          home: d.home,
+          zamPath,
+          dryRun
+        });
+        extension = {
+          kind: "copilot",
+          action: installed.action,
+          location: installed.destinationDir,
+          detail: `${installed.launch.command} ${installed.launch.args.join(" ")}`
+        };
+      } else if (harness === "vscode") {
+        const installed = d.installVscode({ home: d.home, zamPath, dryRun });
+        extension = {
+          kind: "vscode",
+          action: installed.action,
+          location: installed.vsixPath,
+          detail: installed.launchConfigPath
+        };
+      } else if (harness === "antigravity") {
+        const antigravityPath = d.resolveAntigravity();
+        if (antigravityPath) {
+          const installed = d.installVscode({
+            home: d.home,
+            zamPath,
+            codePath: antigravityPath,
+            dryRun
+          });
+          extension = {
+            kind: "vscode",
+            action: installed.action,
+            location: installed.vsixPath,
+            detail: installed.launchConfigPath
+          };
+        }
+      }
+      let wrote = false;
+      if (!prepared.alreadyConfigured && !dryRun) {
+        d.writeConfig(prepared.path, prepared.content);
+        wrote = true;
+      }
+      results.push({
+        harness,
+        label,
+        path: prepared.path,
+        content: prepared.content,
+        alreadyConfigured: prepared.alreadyConfigured,
+        wrote,
+        hint: prepared.hint,
+        extension
+      });
+    } catch (error) {
+      results.push({
+        harness,
+        label,
+        path: "",
+        content: "",
+        alreadyConfigured: false,
+        wrote: false,
+        hint: "",
+        extension: null,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  let skills = null;
+  if (!dryRun && detected.length > 0) {
+    const skillResults = d.refreshSkills(d.home);
+    skills = {
+      refreshed: skillResults.filter((result) => result.success).length,
+      total: skillResults.length
+    };
+  }
+  return {
+    success: results.every((result) => !result.error),
+    detected,
+    zamPath,
+    zamOnPath: Boolean(foundZam),
+    results,
+    skills
+  };
+}
+function inspectConnectHarnesses(deps = {}) {
+  const d = resolveDeps(deps);
+  const foundZam = d.findZam();
+  const zamPath = foundZam ?? "zam";
+  const installed = new Set(d.detect());
+  const harnesses = USER_SCOPED_CONNECT_HARNESSES.map((harness) => {
+    const status = {
+      harness,
+      label: CONNECT_HARNESS_LABELS[harness],
+      installed: installed.has(harness),
+      configured: false,
+      configPath: ""
+    };
+    try {
+      const probe = d.connectMcp(harness, {
+        zamPath,
+        cwd: d.cwd,
+        home: d.home,
+        copilotHome: d.copilotHome
+      });
+      status.configured = probe.alreadyConfigured;
+      status.configPath = probe.path;
+    } catch (error) {
+      status.note = error instanceof Error ? error.message : String(error);
+    }
+    return status;
+  });
+  return { zamOnPath: Boolean(foundZam), harnesses };
+}
 
 // src/cli/curriculum/breadcrumb.ts
 init_kernel();
@@ -12633,9 +13416,9 @@ function getCurriculumProvider(id) {
 // src/cli/llm/vision.ts
 init_kernel();
 import { randomBytes } from "crypto";
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync14 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename4, join as join17 } from "path";
+import { basename as basename4, join as join19 } from "path";
 var LANGUAGE_NAMES2 = {
   en: "English",
   de: "German",
@@ -12671,13 +13454,13 @@ async function observeUiSnapshotViaLLM(db, input) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync12, readdirSync: readdirSync3, rmSync: rmSync4 } = await import("fs");
+    const { mkdirSync: mkdirSync15, readdirSync: readdirSync3, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync5 } = await import("child_process");
-    const tempDir = join17(
+    const tempDir = join19(
       tmpdir2(),
       `zam-frames-${randomBytes(4).toString("hex")}`
     );
-    mkdirSync12(tempDir, { recursive: true });
+    mkdirSync15(tempDir, { recursive: true });
     try {
       execSync5(
         `ffmpeg -i "${input.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
@@ -12706,7 +13489,7 @@ async function observeUiSnapshotViaLLM(db, input) {
         }
       }
       for (const file of sampledFiles) {
-        const bytes = readFileSync12(join17(tempDir, file));
+        const bytes = readFileSync14(join19(tempDir, file));
         imageUrls.push(`data:image/png;base64,${bytes.toString("base64")}`);
       }
     } finally {
@@ -12716,7 +13499,7 @@ async function observeUiSnapshotViaLLM(db, input) {
       }
     }
   } else {
-    const imageBytes = readFileSync12(input.imagePath);
+    const imageBytes = readFileSync14(input.imagePath);
     const ext = input.imagePath.split(".").pop()?.toLowerCase();
     const mime = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
     imageUrls.push(`data:${mime};base64,${imageBytes.toString("base64")}`);
@@ -13182,36 +13965,36 @@ async function withProviderScope(machine, action) {
 
 // src/cli/provisioning/index.ts
 import {
-  existsSync as existsSync15,
-  lstatSync,
-  mkdirSync as mkdirSync10,
-  readFileSync as readFileSync13,
+  existsSync as existsSync17,
+  lstatSync as lstatSync2,
+  mkdirSync as mkdirSync13,
+  readFileSync as readFileSync15,
   realpathSync,
   rmSync as rmSync2,
   symlinkSync,
-  writeFileSync as writeFileSync8
+  writeFileSync as writeFileSync11
 } from "fs";
-import { basename as basename5, dirname as dirname7, join as join18 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
-var packageRoot = [
-  fileURLToPath3(new URL("../..", import.meta.url)),
-  fileURLToPath3(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync15(join18(candidate, "package.json"))) ?? fileURLToPath3(new URL("../..", import.meta.url));
+import { basename as basename5, dirname as dirname10, join as join20 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
+var packageRoot3 = [
+  fileURLToPath5(new URL("../..", import.meta.url)),
+  fileURLToPath5(new URL("../../..", import.meta.url))
+].find((candidate) => existsSync17(join20(candidate, "package.json"))) ?? fileURLToPath5(new URL("../..", import.meta.url));
 var ALL_SETUP_AGENTS = ["claude", "copilot", "codex", "agent"];
 var SKILL_PAIRS = [
   {
-    from: join18(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join18(".claude", "skills", "zam", "SKILL.md"),
+    from: join20(packageRoot3, ".claude", "skills", "zam", "SKILL.md"),
+    to: join20(".claude", "skills", "zam", "SKILL.md"),
     agents: ["claude", "copilot"]
   },
   {
-    from: join18(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join18(".agent", "skills", "zam", "SKILL.md"),
+    from: join20(packageRoot3, ".agent", "skills", "zam", "SKILL.md"),
+    to: join20(".agent", "skills", "zam", "SKILL.md"),
     agents: ["agent"]
   },
   {
-    from: join18(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join18(".agents", "skills", "zam", "SKILL.md"),
+    from: join20(packageRoot3, ".agents", "skills", "zam", "SKILL.md"),
+    to: join20(".agents", "skills", "zam", "SKILL.md"),
     agents: ["codex"]
   }
 ];
@@ -13241,7 +14024,7 @@ function parseSetupAgents(value) {
 }
 function pathExists(path) {
   try {
-    lstatSync(path);
+    lstatSync2(path);
     return true;
   } catch {
     return false;
@@ -13249,7 +14032,7 @@ function pathExists(path) {
 }
 function isSymbolicLink(path) {
   try {
-    return lstatSync(path).isSymbolicLink();
+    return lstatSync2(path).isSymbolicLink();
   } catch {
     return false;
   }
@@ -13270,16 +14053,16 @@ function linkPointsTo(sourceDir, destinationDir) {
 }
 function isZamSkillCopy(destinationDir) {
   try {
-    if (!lstatSync(destinationDir).isDirectory()) return false;
-    const skillFile = join18(destinationDir, "SKILL.md");
-    if (!existsSync15(skillFile)) return false;
-    return /^name:\s*zam\s*$/m.test(readFileSync13(skillFile, "utf8"));
+    if (!lstatSync2(destinationDir).isDirectory()) return false;
+    const skillFile = join20(destinationDir, "SKILL.md");
+    if (!existsSync17(skillFile)) return false;
+    return /^name:\s*zam\s*$/m.test(readFileSync15(skillFile, "utf8"));
   } catch {
     return false;
   }
 }
 function classifySkillDestination(sourceDir, destinationDir) {
-  if (!existsSync15(sourceDir)) return "source-missing";
+  if (!existsSync17(sourceDir)) return "source-missing";
   if (!isSymbolicLink(destinationDir) && pathsResolveToSameDirectory(sourceDir, destinationDir)) {
     return "source-directory";
   }
@@ -13296,9 +14079,9 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
   };
   for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
     if (!pairAgents.some((agent) => agents.has(agent))) continue;
-    const sourceDir = dirname7(from);
-    const destinationDir = dirname7(join18(cwd, to));
-    const label = dirname7(to);
+    const sourceDir = dirname10(from);
+    const destinationDir = dirname10(join20(cwd, to));
+    const label = dirname10(to);
     const state = classifySkillDestination(sourceDir, destinationDir);
     if (state === "source-missing") {
       if (!opts.quiet) {
@@ -13355,7 +14138,7 @@ function wireSkills(cwd = process.cwd(), agents = parseSetupAgents(), opts = {})
       if (destinationExists) {
         rmSync2(destinationDir, { recursive: true, force: true });
       }
-      mkdirSync10(dirname7(destinationDir), { recursive: true });
+      mkdirSync13(dirname10(destinationDir), { recursive: true });
       symlinkSync(
         sourceDir,
         destinationDir,
@@ -13371,8 +14154,8 @@ function inspectSkillLinks(cwd = process.cwd(), agents = parseSetupAgents()) {
   const results = [];
   for (const { from, to, agents: pairAgents } of SKILL_PAIRS) {
     if (!pairAgents.some((agent) => agents.has(agent))) continue;
-    const sourceDir = dirname7(from);
-    const destinationDir = dirname7(join18(cwd, to));
+    const sourceDir = dirname10(from);
+    const destinationDir = dirname10(join20(cwd, to));
     results.push({
       agents: pairAgents,
       source: sourceDir,
@@ -13416,13 +14199,13 @@ async function resolveUser(opts, db, resolveOpts) {
 }
 
 // src/cli/workspaces/backup.ts
-import { mkdirSync as mkdirSync11 } from "fs";
-import { join as join19 } from "path";
+import { mkdirSync as mkdirSync14 } from "fs";
+import { join as join21 } from "path";
 async function backupDatabaseTo(db, targetDir) {
-  const backupDir = join19(targetDir, "zam-backups");
-  mkdirSync11(backupDir, { recursive: true });
+  const backupDir = join21(targetDir, "zam-backups");
+  mkdirSync14(backupDir, { recursive: true });
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const dest = join19(backupDir, `zam-${stamp}.db`);
+  const dest = join21(backupDir, `zam-${stamp}.db`);
   await db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
   return dest;
 }
@@ -13553,20 +14336,20 @@ bridgeCommand.command("workspace-info").description("Report the workspace dir, i
       activeWorkspace,
       workspaceDir: activeWorkspace.path,
       defaultWorkspaceDir: defaultWorkspaceDir(),
-      dataDir: join20(homedir11(), ".zam")
+      dataDir: join22(homedir14(), ".zam")
     });
   });
 });
 function provisionConfiguredWorkspaces() {
   return getConfiguredWorkspaces().flatMap(
-    (workspace) => existsSync16(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
+    (workspace) => existsSync18(workspace.path) ? wireSkills(workspace.path, parseSetupAgents(), { quiet: true }) : []
   );
 }
 function buildWorkspaceLinkHealth(workspaces) {
   const agents = parseSetupAgents();
   const map = {};
   for (const workspace of workspaces) {
-    if (!existsSync16(workspace.path)) continue;
+    if (!existsSync18(workspace.path)) continue;
     const links = inspectSkillLinks(workspace.path, agents);
     map[workspace.id] = {
       health: summarizeSkillLinkHealth(links),
@@ -13596,7 +14379,7 @@ bridgeCommand.command("workspace-list").description("List configured ZAM workspa
       activeWorkspace,
       workspaceDir: activeWorkspace.path,
       defaultWorkspaceDir: defaultWorkspaceDir(),
-      dataDir: join20(homedir11(), ".zam"),
+      dataDir: join22(homedir14(), ".zam"),
       linkHealth: buildWorkspaceLinkHealth(workspaces)
     });
   });
@@ -13611,7 +14394,7 @@ bridgeCommand.command("workspace-repair-links").description(
   if (!id) jsonError("A non-empty --id is required");
   const workspace = getConfiguredWorkspaces().find((item) => item.id === id);
   if (!workspace) jsonError(`Workspace "${id}" is not configured`);
-  if (!existsSync16(workspace.path)) {
+  if (!existsSync18(workspace.path)) {
     jsonError(`Workspace path does not exist: ${workspace.path}`);
   }
   const agents = parseSetupAgents(opts.agents);
@@ -13642,8 +14425,8 @@ function parseBridgeWorkspaceKind(value) {
 bridgeCommand.command("workspace-add").description("Register an existing directory as a ZAM workspace (JSON)").requiredOption("--path <dir>", "Existing workspace/repository directory").option("--id <id>", "Workspace id").option("--label <label>", "Human-readable label").option("--kind <kind>", "Workspace kind", "custom").action(async (opts) => {
   const raw = String(opts.path ?? "").trim();
   if (!raw) jsonError("A non-empty --path is required");
-  const path = resolve4(raw);
-  if (!existsSync16(path)) jsonError(`Workspace path does not exist: ${path}`);
+  const path = resolve5(raw);
+  if (!existsSync18(path)) jsonError(`Workspace path does not exist: ${path}`);
   const id = opts.id ? String(opts.id).trim() : void 0;
   if (opts.id && !id) jsonError("A non-empty --id is required");
   const kind = parseBridgeWorkspaceKind(opts.kind);
@@ -13687,8 +14470,8 @@ bridgeCommand.command("workspace-remove").description("Unregister a ZAM workspac
 bridgeCommand.command("set-workspace-dir").description("Set the personal workspace directory (JSON)").requiredOption("--dir <path>", "Path to the workspace directory").action(async (opts) => {
   const raw = String(opts.dir ?? "").trim();
   if (!raw) jsonError("A non-empty --dir is required");
-  const dir = resolve4(raw);
-  if (!existsSync16(dir)) jsonError(`Workspace path does not exist: ${dir}`);
+  const dir = resolve5(raw);
+  if (!existsSync18(dir)) jsonError(`Workspace path does not exist: ${dir}`);
   const skillLinks = wireSkills(dir, parseSetupAgents(), { quiet: true });
   await withDb2(async (db) => {
     const workspace = await activateWorkspacePath(db, dir);
@@ -13751,7 +14534,7 @@ bridgeCommand.command("agent-open").description("Launch an agent harness in the
       jsonError(`Workspace is not configured: ${opts.workspace}`);
     }
     const activeWorkspace = await ensureActiveWorkspace(db);
-    const workspace = opts.dir ? existsSync16(opts.dir) ? opts.dir : homedir11() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
+    const workspace = opts.dir ? existsSync18(opts.dir) ? opts.dir : homedir14() : existingWorkspaceDirOrHome(configuredWorkspace ?? activeWorkspace);
     launchHarness(harness, {
       executable,
       workspace,
@@ -14123,7 +14906,7 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join20(homedir11(), ".zam", "monitor");
+    const monitorDir = join22(homedir14(), ".zam", "monitor");
     let files;
     try {
       files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
@@ -14136,7 +14919,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join20(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join22(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
     const sessionCommands = /* @__PURE__ */ new Map();
     for (const file of sorted) {
       const sessionId = file.name.replace(".jsonl", "");
@@ -14248,7 +15031,7 @@ bridgeCommand.command("observe-ui-snapshot").description(
 });
 function resolveWindowsPowerShell() {
   try {
-    execFileSync3("where.exe", ["pwsh.exe"], { stdio: "ignore" });
+    execFileSync4("where.exe", ["pwsh.exe"], { stdio: "ignore" });
     return "pwsh";
   } catch {
     return "powershell";
@@ -14263,7 +15046,7 @@ function captureScreenshot(outputPath, hwnd, processName) {
     throw new Error(`Invalid process name format: ${processName}`);
   }
   if (platform === "win32") {
-    const stdout = execFileSync3(
+    const stdout = execFileSync4(
       resolveWindowsPowerShell(),
       [
         "-NoProfile",
@@ -14576,13 +15359,13 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
   } else if (platform === "darwin") {
     if (hwnd) {
       const parsedHwnd = hwnd.startsWith("0x") ? parseInt(hwnd, 16) : parseInt(hwnd, 10);
-      execFileSync3("screencapture", ["-l", String(parsedHwnd), outputPath], {
+      execFileSync4("screencapture", ["-l", String(parsedHwnd), outputPath], {
         stdio: "pipe"
       });
       return { method: "screencapture-window", target: null };
     } else if (processName) {
       try {
-        const windowId = execFileSync3(
+        const windowId = execFileSync4(
           "osascript",
           [
             "-e",
@@ -14591,17 +15374,17 @@ Write-CaptureResult "fullscreen" $hwndVal $matchedBy
           { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
         ).trim();
         if (windowId && /^\d+$/.test(windowId)) {
-          execFileSync3("screencapture", ["-l", windowId, outputPath], {
+          execFileSync4("screencapture", ["-l", windowId, outputPath], {
             stdio: "pipe"
           });
           return { method: "screencapture-window", target: null };
         }
       } catch {
       }
-      execFileSync3("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     } else {
-      execFileSync3("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      execFileSync4("screencapture", ["-x", outputPath], { stdio: "pipe" });
       return { method: "screencapture-full", target: null };
     }
   } else {
@@ -14638,7 +15421,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const outputPath = opts.image ?? opts.output ?? join20(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
+    const outputPath = opts.image ?? opts.output ?? join22(tmpdir3(), `zam-capture-${randomBytes2(4).toString("hex")}.png`);
     const captureResult = isProvided ? { method: "provided", target: null } : captureScreenshot(outputPath, opts.hwnd, opts.processName);
     if (!isProvided) {
       const post = decidePostCapture(policy, {
@@ -14666,7 +15449,7 @@ bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-
         return;
       }
     }
-    const imageBytes = readFileSync14(outputPath);
+    const imageBytes = readFileSync16(outputPath);
     const base64 = imageBytes.toString("base64");
     jsonOut({
       sessionId: opts.session ?? null,
@@ -14693,11 +15476,11 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     return;
   }
   const sessionId = opts.session;
-  const statePath = join20(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
-  const outputPath = opts.output ?? join20(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
-  const { existsSync: existsSync18, writeFileSync: writeFileSync9, openSync, closeSync } = await import("fs");
-  if (existsSync18(statePath)) {
+  const outputPath = opts.output ?? join22(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
+  const { existsSync: existsSync20, writeFileSync: writeFileSync12, openSync, closeSync } = await import("fs");
+  if (existsSync20(statePath)) {
     jsonOut({
       sessionId,
       started: false,
@@ -14705,7 +15488,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
     });
     return;
   }
-  const logPath = join20(tmpdir3(), `zam-recording-${sessionId}.log`);
+  const logPath = join22(tmpdir3(), `zam-recording-${sessionId}.log`);
   let logFd;
   try {
     logFd = openSync(logPath, "w");
@@ -14751,7 +15534,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   }
   child.unref();
   if (child.pid) {
-    writeFileSync9(
+    writeFileSync12(
       statePath,
       JSON.stringify({
         pid: child.pid,
@@ -14787,9 +15570,9 @@ bridgeCommand.command("stop-recording").description(
     return;
   }
   const sessionId = opts.session;
-  const statePath = join20(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync18, readFileSync: readFileSync16, rmSync: rmSync4 } = await import("fs");
-  if (!existsSync18(statePath)) {
+  const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
+  const { existsSync: existsSync20, readFileSync: readFileSync18, rmSync: rmSync4 } = await import("fs");
+  if (!existsSync20(statePath)) {
     jsonOut({
       sessionId,
       stopped: false,
@@ -14797,7 +15580,7 @@ bridgeCommand.command("stop-recording").description(
     });
     return;
   }
-  const state = JSON.parse(readFileSync16(statePath, "utf8"));
+  const state = JSON.parse(readFileSync18(statePath, "utf8"));
   const { pid, outputPath } = state;
   try {
     process.kill(pid, "SIGINT");
@@ -14813,7 +15596,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve5) => setTimeout(resolve5, 250));
+    await new Promise((resolve6) => setTimeout(resolve6, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -14826,7 +15609,7 @@ bridgeCommand.command("stop-recording").description(
     rmSync4(statePath, { force: true });
   } catch {
   }
-  if (!existsSync18(outputPath)) {
+  if (!existsSync20(outputPath)) {
     jsonOut({
       sessionId,
       stopped: false,
@@ -15063,7 +15846,7 @@ bridgeCommand.command("cloud-model-hint").description("Suggest a cloud model for
 });
 bridgeCommand.command("local-llm-hints").description("Detect installed local LLM servers and suggest defaults (JSON)").action(() => {
   const profile = getSystemProfile();
-  const flmInstalled = hasCommand("flm") || existsSync16("C:\\Program Files\\flm\\flm.exe");
+  const flmInstalled = hasCommand("flm") || existsSync18("C:\\Program Files\\flm\\flm.exe");
   const ollamaInstalled = isOllamaInstalled();
   const runners = [
     { id: "flm", label: "FastFlowLM", installed: flmInstalled },
@@ -15203,6 +15986,93 @@ bridgeCommand.command("evaluate-answer").description(
     }
   });
 });
+function parseDiscussionThread(raw) {
+  if (!raw) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid --thread: not valid JSON");
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error("Invalid --thread: expected a JSON array of turns");
+  }
+  return parsed.map((turn, index) => {
+    const candidate = turn;
+    if (candidate?.role !== "user" && candidate?.role !== "assistant" || typeof candidate?.content !== "string") {
+      throw new Error(
+        `Invalid --thread: turn ${index} must be {"role": "user"|"assistant", "content": string}`
+      );
+    }
+    return { role: candidate.role, content: candidate.content };
+  });
+}
+bridgeCommand.command("discuss-review").description(
+  "Answer one turn of the post-reveal follow-up discussion about a card (JSON)"
+).requiredOption("--slug <slug>", "Token slug").requiredOption("--concept <concept>", "Target concept text").requiredOption("--domain <domain>", "Token domain").requiredOption("--bloom-level <level>", "Bloom taxonomy level").requiredOption("--question <question>", "Question prompt presented").requiredOption("--user-answer <answer>", "User's typed answer").requiredOption("--message <text>", "The learner's newest discussion turn").option("--feedback <text>", "AI feedback already shown for this answer").option(
+  "--thread <json>",
+  'Prior turns, oldest first, as JSON: [{"role":"user"|"assistant","content":"\u2026"},\u2026]'
+).option("--context <context>", "Optional token context details").option("--source-link <link>", "Optional source link").option(
+  "--source-content <content>",
+  "Pre-resolved source reference content (skips re-fetch when set)"
+).action(async (opts) => {
+  await withDb2(async (db) => {
+    const isEnabled = await getSetting(db, "llm.enabled") === "true";
+    if (!isEnabled) {
+      jsonOut({
+        success: false,
+        error: "LLM integration is disabled",
+        reply: ""
+      });
+      return;
+    }
+    let thread;
+    try {
+      thread = parseDiscussionThread(opts.thread);
+    } catch (err) {
+      jsonOut({
+        success: false,
+        error: err.message,
+        reply: ""
+      });
+      return;
+    }
+    let resolvedContextContent = opts.sourceContent ?? null;
+    if (resolvedContextContent == null && opts.sourceLink) {
+      try {
+        const resolved = await resolveReviewContext(opts.sourceLink);
+        resolvedContextContent = resolved?.content ?? null;
+      } catch {
+      }
+    }
+    try {
+      const result = await discussReviewViaLLM(db, {
+        slug: opts.slug,
+        concept: opts.concept,
+        domain: opts.domain,
+        bloomLevel: Number(opts.bloomLevel),
+        context: opts.context,
+        question: opts.question,
+        userAnswer: opts.userAnswer,
+        sourceLinkContent: resolvedContextContent,
+        feedback: opts.feedback ?? null,
+        thread,
+        message: opts.message
+      });
+      jsonOut({
+        success: true,
+        reply: result.text,
+        replyModel: result.model
+      });
+    } catch (err) {
+      jsonOut({
+        success: false,
+        error: err.message,
+        reply: ""
+      });
+    }
+  });
+});
 bridgeCommand.command("desktop-bootstrap").description("Initialize first-run desktop state (JSON)").option("--user <id>", "Preferred user ID when none is configured").action(async (opts) => {
   await withDb2(async (db) => {
     const userId = await ensureDefaultUser(db, opts.user);
@@ -15231,6 +16101,54 @@ bridgeCommand.command("get-settings").description("Get active ZAM settings (JSON
     });
   });
 });
+bridgeCommand.command("agent-harness-status").description(
+  "Detect installed agent harnesses and their ZAM MCP configuration state (JSON)"
+).action(() => {
+  const report = inspectConnectHarnesses();
+  jsonOut({
+    success: true,
+    zamOnPath: report.zamOnPath,
+    harnesses: report.harnesses
+  });
+});
+bridgeCommand.command("agent-connect").description(
+  "Run the idempotent agent-connect flow for one or all detected harnesses (JSON)"
+).option("--harness <id>", "Explicit harness id (default: all detected)").option(
+  "--auto-once",
+  "First-run mode: skip when the auto-connect marker is already set; set the marker after a run that detected at least one harness"
+).action(async (opts) => {
+  if (opts.harness && !isConnectHarnessId(opts.harness)) {
+    jsonOut({
+      success: false,
+      error: `Unsupported harness: ${opts.harness}`
+    });
+    return;
+  }
+  const harness = opts.harness;
+  const run = () => {
+    const report = performAgentConnect({ harness });
+    return {
+      success: report.success,
+      detected: report.detected,
+      zamOnPath: report.zamOnPath,
+      results: report.results.map(({ content: _content, ...rest }) => rest),
+      skills: report.skills
+    };
+  };
+  if (opts.autoOnce) {
+    if (getAgentConnectAutoDone()) {
+      jsonOut({ success: true, skipped: true });
+      return;
+    }
+    const payload = run();
+    if (payload.detected.length > 0) {
+      setAgentConnectAutoDone(true);
+    }
+    jsonOut(payload);
+    return;
+  }
+  jsonOut(run());
+});
 async function readDatabaseUserSummaries(db) {
   return await db.prepare(
     `SELECT user_id AS id, COUNT(*) AS cardCount
@@ -16336,12 +17254,12 @@ bridgeCommand.command("serve").description("Start the persistent JSON-RPC stdin/
 });
 
 // src/cli/commands/mcp.ts
-var __dirname = dirname8(fileURLToPath4(import.meta.url));
-var pkgPath = join21(__dirname, "..", "..", "package.json");
-if (!existsSync17(pkgPath)) {
-  pkgPath = join21(__dirname, "..", "..", "..", "package.json");
+var __dirname = dirname11(fileURLToPath6(import.meta.url));
+var pkgPath = join23(__dirname, "..", "..", "package.json");
+if (!existsSync19(pkgPath)) {
+  pkgPath = join23(__dirname, "..", "..", "..", "package.json");
 }
-var pkg = JSON.parse(readFileSync15(pkgPath, "utf-8"));
+var pkg = JSON.parse(readFileSync17(pkgPath, "utf-8"));
 var STUDIO_RESOURCE_URI = "ui://zam/studio";
 var RECALL_RESOURCE_URI = "ui://zam/recall";
 var GRAPH_RESOURCE_URI = "ui://zam/graph";
@@ -16366,13 +17284,13 @@ var STUDIO_BRIDGE_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
 function loadPanelHtml(fileName, placeholderTitle) {
   const candidates = [
     // dist/cli/commands/mcp.js → dist/ui/
-    join21(__dirname, "..", "..", "ui", fileName),
+    join23(__dirname, "..", "..", "ui", fileName),
     // src/cli/commands/mcp.ts via tsx → <repo>/dist/ui/
-    join21(__dirname, "..", "..", "..", "dist", "ui", fileName)
+    join23(__dirname, "..", "..", "..", "dist", "ui", fileName)
   ];
   for (const candidate of candidates) {
-    if (existsSync17(candidate)) {
-      return readFileSync15(candidate, "utf-8");
+    if (existsSync19(candidate)) {
+      return readFileSync17(candidate, "utf-8");
     }
   }
   return `<!doctype html>