@geravant/sinain 1.22.9 → 1.23.1

package/launcher.js

@@ -56,6 +56,26 @@ const children = [];    // { name, proc, pid }
 await main();
 
 async function main() {
+  // ── Platform guard (ENG-05, CONTEXT.md D-03) ─────────────────────────────
+  // Friendly blocker for non-macOS platforms. SINAIN_FAKE_PLATFORM enables
+  // env-var spoof testing without an actual Windows/Linux host.
+  const platform = process.env.SINAIN_FAKE_PLATFORM || os.platform();
+  if (platform !== "darwin") {
+    const isWindows = platform === "win32";
+    console.log("");
+    console.log("  ┌─────────────────────────────────────────────────────────┐");
+    console.log("  │  Sinain is macOS-only for this launch                   │");
+    console.log("  │                                                         │");
+    console.log("  │  " + (isWindows
+      ? "Windows support is in progress — star the repo for updates."
+      : "Linux support is planned — star the repo for updates.        ") + "  │");
+    console.log("  │  https://github.com/geravant/sinain-hud                 │");
+    console.log("  └─────────────────────────────────────────────────────────┘");
+    console.log("");
+    process.exit(0);
+  }
+  // ── End platform guard ────────────────────────────────────────────────────
+
   setupSignalHandlers();
 
   log("Preflight checks...");

package/mcp-register.js

@@ -0,0 +1,572 @@
+/**
+ * sinain mcp-register — detect and register the sinain MCP server
+ * into MCP-aware agents (Claude Code, Claude Desktop, Cursor, Codex, Goose, Junie).
+ *
+ * Designed to be called from two surfaces:
+ *   - the wizard (`stepMcpInstall` from onboard.js)
+ *   - a standalone CLI (`runMcpCli` from cli.js)
+ *
+ * Idempotency is the design contract for every backend: read existing config,
+ * upsert the `sinain` entry only, never duplicate. Re-running this module
+ * after upgrading the npm package is the canonical "re-point my paths" flow.
+ */
+
+import * as p from "@clack/prompts";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execFileSync, execSync } from "child_process";
+import { c, guard, cmdExists, PKG_DIR, HOME, SINAIN_DIR, ENV_PATH, IS_WINDOWS, IS_MAC } from "./config-shared.js";
+
+// ── Paths to the bundled MCP server ─────────────────────────────────────────
+
+const MCP_SERVER_DIR = path.join(PKG_DIR, "sinain-mcp-server");
+const MCP_ENTRY = path.join(MCP_SERVER_DIR, "index.ts");
+const TSX_BIN = path.join(MCP_SERVER_DIR, "node_modules", ".bin", IS_WINDOWS ? "tsx.cmd" : "tsx");
+
+const DEFAULT_ENV = {
+  SINAIN_CORE_URL: "http://localhost:9500",
+  SINAIN_WORKSPACE: path.join(HOME, ".openclaw", "workspace"),
+};
+
+function mcpServerReady() {
+  return fs.existsSync(MCP_ENTRY) && fs.existsSync(TSX_BIN);
+}
+
+function ensureMcpServerDeps() {
+  if (mcpServerReady()) return true;
+  if (!fs.existsSync(MCP_ENTRY)) return false;
+  try {
+    execSync("npm install --silent", { cwd: MCP_SERVER_DIR, stdio: "pipe" });
+    return mcpServerReady();
+  } catch {
+    return false;
+  }
+}
+
+function mcpServerPayload() {
+  return {
+    command: TSX_BIN,
+    args: [MCP_ENTRY],
+    env: { ...DEFAULT_ENV },
+  };
+}
+
+// ── Backend: Claude Code (CLI-managed via `claude mcp`) ─────────────────────
+
+function claudeListJson() {
+  try {
+    const out = execFileSync("claude", ["mcp", "list", "--json"], { stdio: "pipe", encoding: "utf-8" });
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}
+
+function claudeAlreadyRegistered() {
+  const list = claudeListJson();
+  if (list && typeof list === "object") {
+    if (list.sinain) return true;
+    if (Array.isArray(list)) return list.some((e) => e?.name === "sinain");
+  }
+  try {
+    const out = execFileSync("claude", ["mcp", "list"], { stdio: "pipe", encoding: "utf-8" });
+    return /\bsinain\b/.test(out);
+  } catch {
+    return false;
+  }
+}
+
+function claudeRegister({ extraEnv = {} } = {}) {
+  if (!ensureMcpServerDeps()) {
+    throw new Error(`MCP server not built. Run: cd ${MCP_SERVER_DIR} && npm install`);
+  }
+  // Idempotent: remove first (no-op if absent), then add.
+  try { execFileSync("claude", ["mcp", "remove", "sinain"], { stdio: "pipe" }); } catch { /* not registered */ }
+  const env = { ...DEFAULT_ENV, ...extraEnv };
+  const args = ["mcp", "add", "sinain", "--scope", "user"];
+  for (const [k, v] of Object.entries(env)) args.push("--env", `${k}=${v}`);
+  args.push("--", TSX_BIN, MCP_ENTRY);
+  execFileSync("claude", args, { stdio: "pipe", env: { ...process.env, ...env } });
+}
+
+function claudeUnregister() {
+  try { execFileSync("claude", ["mcp", "remove", "sinain"], { stdio: "pipe" }); } catch { /* idempotent */ }
+}
+
+// ── Backend: Codex (CLI-managed via `codex mcp`) ────────────────────────────
+
+function codexAlreadyRegistered() {
+  try {
+    const out = execFileSync("codex", ["mcp", "list"], { stdio: "pipe", encoding: "utf-8" });
+    return /\bsinain\b/.test(out);
+  } catch {
+    return false;
+  }
+}
+
+function codexRegister() {
+  if (!ensureMcpServerDeps()) {
+    throw new Error(`MCP server not built. Run: cd ${MCP_SERVER_DIR} && npm install`);
+  }
+  try { execFileSync("codex", ["mcp", "remove", "sinain"], { stdio: "pipe" }); } catch { /* not registered */ }
+  const args = ["mcp", "add", "sinain"];
+  for (const [k, v] of Object.entries(DEFAULT_ENV)) args.push("--env", `${k}=${v}`);
+  args.push("--", TSX_BIN, MCP_ENTRY);
+  execFileSync("codex", args, { stdio: "pipe" });
+}
+
+function codexUnregister() {
+  try { execFileSync("codex", ["mcp", "remove", "sinain"], { stdio: "pipe" }); } catch { /* idempotent */ }
+}
+
+// ── Backend: JSON-config agents (Claude Desktop, Cursor, Junie) ─────────────
+//
+// All three use the same `mcpServers` object shape. The only thing that
+// varies is the file path. Read-merge-write keeps untouched entries intact.
+
+function jsonConfigPath(agentId) {
+  switch (agentId) {
+    case "claude-desktop":
+      if (IS_MAC) return path.join(HOME, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      if (IS_WINDOWS) return path.join(process.env.APPDATA || path.join(HOME, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+      return path.join(HOME, ".config", "Claude", "claude_desktop_config.json");
+    case "cursor":
+      return path.join(HOME, ".cursor", "mcp.json");
+    case "junie":
+      return path.join(HOME, ".junie", "mcp", "mcp.json");
+    default:
+      throw new Error(`Unknown JSON-config agent: ${agentId}`);
+  }
+}
+
+function jsonAlreadyRegistered(agentId) {
+  const file = jsonConfigPath(agentId);
+  if (!fs.existsSync(file)) return false;
+  try {
+    const json = JSON.parse(fs.readFileSync(file, "utf-8"));
+    return !!json?.mcpServers?.sinain;
+  } catch {
+    return false;
+  }
+}
+
+function jsonRegister(agentId) {
+  if (!ensureMcpServerDeps()) {
+    throw new Error(`MCP server not built. Run: cd ${MCP_SERVER_DIR} && npm install`);
+  }
+  const file = jsonConfigPath(agentId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let config = {};
+  if (fs.existsSync(file)) {
+    try {
+      config = JSON.parse(fs.readFileSync(file, "utf-8")) || {};
+    } catch (err) {
+      throw new Error(`Existing config at ${file} is not valid JSON: ${err.message}`);
+    }
+  }
+  config.mcpServers = config.mcpServers || {};
+  config.mcpServers.sinain = mcpServerPayload();
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+}
+
+function jsonUnregister(agentId) {
+  const file = jsonConfigPath(agentId);
+  if (!fs.existsSync(file)) return;
+  let config;
+  try { config = JSON.parse(fs.readFileSync(file, "utf-8")); } catch { return; }
+  if (config?.mcpServers?.sinain) {
+    delete config.mcpServers.sinain;
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+  }
+}
+
+// ── Backend: Goose (YAML, hand-rolled splice with snippet fallback) ─────────
+//
+// Goose's config is YAML and we don't want a YAML dep just for this site.
+// Strategy: detect a `sinain:` block under `extensions:` via line scanning;
+// if present, splice replace; if absent, append. On any structural surprise,
+// abort the write and return a printable snippet for the user to paste.
+
+const GOOSE_CONFIG = path.join(HOME, ".config", "goose", "config.yaml");
+
+function gooseSnippet() {
+  return [
+    "extensions:",
+    "  sinain:",
+    "    enabled: true",
+    `    cmd: "${TSX_BIN}"`,
+    `    args: ["${MCP_ENTRY}"]`,
+    "    envs:",
+    `      SINAIN_CORE_URL: "${DEFAULT_ENV.SINAIN_CORE_URL}"`,
+    `      SINAIN_WORKSPACE: "${DEFAULT_ENV.SINAIN_WORKSPACE}"`,
+  ].join("\n");
+}
+
+function gooseAlreadyRegistered() {
+  if (!fs.existsSync(GOOSE_CONFIG)) return false;
+  const content = fs.readFileSync(GOOSE_CONFIG, "utf-8");
+  return /^\s+sinain:/m.test(content);
+}
+
+function gooseRegister() {
+  if (!ensureMcpServerDeps()) {
+    throw new Error(`MCP server not built. Run: cd ${MCP_SERVER_DIR} && npm install`);
+  }
+  fs.mkdirSync(path.dirname(GOOSE_CONFIG), { recursive: true });
+  const exists = fs.existsSync(GOOSE_CONFIG);
+  const content = exists ? fs.readFileSync(GOOSE_CONFIG, "utf-8") : "";
+
+  // If the file is empty or only has top-level keys we recognise as safe to
+  // append to, we add the extensions block fresh.
+  if (!exists || !content.trim()) {
+    fs.writeFileSync(GOOSE_CONFIG, gooseSnippet() + "\n");
+    return { ok: true };
+  }
+
+  const hasExtensions = /^extensions:/m.test(content);
+  const hasSinain = /^\s+sinain:/m.test(content);
+
+  if (!hasExtensions) {
+    const sep = content.endsWith("\n") ? "" : "\n";
+    fs.writeFileSync(GOOSE_CONFIG, content + sep + "\n" + gooseSnippet() + "\n");
+    return { ok: true };
+  }
+
+  if (!hasSinain) {
+    // Insert `sinain:` block right after the `extensions:` line.
+    const lines = content.split("\n");
+    const idx = lines.findIndex((l) => /^extensions:/.test(l));
+    const block = gooseSnippet().split("\n").slice(1); // drop the `extensions:` header
+    lines.splice(idx + 1, 0, ...block);
+    fs.writeFileSync(GOOSE_CONFIG, lines.join("\n"));
+    return { ok: true };
+  }
+
+  // Sinain entry already exists — replace it. We replace the `sinain:` block
+  // and every immediately-following line that's deeper-indented, stopping at
+  // the next sibling key or end of file.
+  const lines = content.split("\n");
+  const start = lines.findIndex((l) => /^\s+sinain:/.test(l));
+  if (start === -1) return { ok: false, reason: "structural-mismatch", snippet: gooseSnippet() };
+  const indentMatch = lines[start].match(/^(\s+)/);
+  const baseIndent = indentMatch ? indentMatch[1].length : 2;
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end];
+    if (line.trim() === "") { end++; continue; }
+    const m = line.match(/^(\s*)/);
+    if ((m ? m[1].length : 0) <= baseIndent) break;
+    end++;
+  }
+  const replacement = gooseSnippet().split("\n").slice(1); // drop `extensions:` header
+  // re-indent replacement to baseIndent
+  const reindented = replacement.map((l) => l.replace(/^ {2}/, " ".repeat(baseIndent)));
+  lines.splice(start, end - start, ...reindented);
+  fs.writeFileSync(GOOSE_CONFIG, lines.join("\n"));
+  return { ok: true };
+}
+
+function gooseUnregister() {
+  if (!fs.existsSync(GOOSE_CONFIG)) return;
+  const content = fs.readFileSync(GOOSE_CONFIG, "utf-8");
+  if (!/^\s+sinain:/m.test(content)) return;
+  const lines = content.split("\n");
+  const start = lines.findIndex((l) => /^\s+sinain:/.test(l));
+  if (start === -1) return;
+  const baseIndent = (lines[start].match(/^(\s+)/)?.[1].length) || 2;
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end];
+    if (line.trim() === "") { end++; continue; }
+    if ((line.match(/^(\s*)/)?.[1].length || 0) <= baseIndent) break;
+    end++;
+  }
+  lines.splice(start, end - start);
+  fs.writeFileSync(GOOSE_CONFIG, lines.join("\n"));
+}
+
+// ── Agent registry ──────────────────────────────────────────────────────────
+
+const AGENTS = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    detect: () => cmdExists("claude"),
+    isRegistered: claudeAlreadyRegistered,
+    register: (opts) => claudeRegister(opts),
+    unregister: claudeUnregister,
+  },
+  {
+    id: "claude-desktop",
+    label: "Claude Desktop",
+    detect: () => fs.existsSync(path.dirname(jsonConfigPath("claude-desktop"))),
+    isRegistered: () => jsonAlreadyRegistered("claude-desktop"),
+    register: () => jsonRegister("claude-desktop"),
+    unregister: () => jsonUnregister("claude-desktop"),
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    detect: () => cmdExists("cursor") || fs.existsSync(path.join(HOME, ".cursor")),
+    isRegistered: () => jsonAlreadyRegistered("cursor"),
+    register: () => jsonRegister("cursor"),
+    unregister: () => jsonUnregister("cursor"),
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    detect: () => cmdExists("codex"),
+    isRegistered: codexAlreadyRegistered,
+    register: codexRegister,
+    unregister: codexUnregister,
+  },
+  {
+    id: "goose",
+    label: "Goose",
+    detect: () => cmdExists("goose") || fs.existsSync(GOOSE_CONFIG),
+    isRegistered: gooseAlreadyRegistered,
+    register: gooseRegister,
+    unregister: gooseUnregister,
+  },
+  {
+    id: "junie",
+    label: "Junie",
+    detect: () => cmdExists("junie") || fs.existsSync(path.join(HOME, ".junie")),
+    isRegistered: () => jsonAlreadyRegistered("junie"),
+    register: () => jsonRegister("junie"),
+    unregister: () => jsonUnregister("junie"),
+  },
+];
+
+function findAgent(id) {
+  return AGENTS.find((a) => a.id === id);
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export async function detectMcpAgents() {
+  return AGENTS.map((a) => {
+    const present = !!a.detect();
+    let alreadyRegistered = false;
+    if (present) {
+      try { alreadyRegistered = !!a.isRegistered(); } catch { /* ignore */ }
+    }
+    return { id: a.id, label: a.label, present, alreadyRegistered };
+  });
+}
+
+export async function registerSinainMcp(agentId, opts = {}) {
+  const a = findAgent(agentId);
+  if (!a) throw new Error(`Unknown agent: ${agentId}`);
+  await a.register(opts);
+}
+
+export async function unregisterSinainMcp(agentId) {
+  const a = findAgent(agentId);
+  if (!a) throw new Error(`Unknown agent: ${agentId}`);
+  await a.unregister();
+}
+
+// ── Wizard step ─────────────────────────────────────────────────────────────
+
+export async function stepMcpInstall(_existing, label = "MCP agents") {
+  p.log.step(label);
+
+  if (!mcpServerReady()) {
+    const s = p.spinner();
+    s.start("Preparing sinain MCP server...");
+    const ok = ensureMcpServerDeps();
+    s.stop(ok ? c.green("MCP server ready.") : c.yellow("MCP server deps not installed."));
+    if (!ok) {
+      p.note(
+        `Could not install dependencies for the bundled MCP server.\nRun manually: cd ${MCP_SERVER_DIR} && npm install`,
+        "MCP server",
+      );
+      return;
+    }
+  }
+
+  const detectSpinner = p.spinner();
+  detectSpinner.start("Detecting MCP-aware agents...");
+  const agents = await detectMcpAgents();
+  detectSpinner.stop(c.green("Detection done."));
+
+  const detected = agents.filter((a) => a.present);
+  if (detected.length === 0) {
+    p.note(
+      "No MCP-aware agents detected on this machine.\nInstall Claude Code, Cursor, Codex, Goose, or Junie first.\nThen re-run: npx @geravant/sinain mcp install",
+      "Skipped",
+    );
+    return;
+  }
+
+  // Status summary
+  const summary = detected
+    .map((a) => `${a.label}: ${a.alreadyRegistered ? c.dim("registered") : c.green("detected")}`)
+    .join("\n");
+  p.note(summary, "Agents found");
+
+  // Multi-select: pre-check unregistered detected agents
+  const choice = guard(await p.multiselect({
+    message: "Register sinain MCP for:",
+    options: detected.map((a) => ({
+      value: a.id,
+      label: a.label,
+      hint: a.alreadyRegistered ? "already registered (re-register to refresh paths)" : undefined,
+    })),
+    initialValues: detected.filter((a) => !a.alreadyRegistered).map((a) => a.id),
+    required: false,
+  }));
+
+  if (!choice || choice.length === 0) {
+    p.log.info("No agents selected — skipping MCP registration.");
+    return;
+  }
+
+  for (const id of choice) {
+    const a = findAgent(id);
+    const s = p.spinner();
+    s.start(`Registering for ${a.label}...`);
+    try {
+      await a.register();
+      s.stop(c.green(`${a.label}: registered.`));
+    } catch (err) {
+      s.stop(c.yellow(`${a.label}: failed — ${err.message}`));
+      if (id === "goose") {
+        p.note(`Paste this into ${GOOSE_CONFIG}:\n\n${gooseSnippet()}`, "Goose snippet");
+      }
+    }
+  }
+
+  // Bonus: alternate Claude config dir (pclaude / CLAUDE_CONFIG_DIR)
+  if (process.env.CLAUDE_CONFIG_DIR && choice.includes("claude")) {
+    const altDir = process.env.CLAUDE_CONFIG_DIR;
+    const alsoRegister = guard(await p.confirm({
+      message: `Also register sinain for CLAUDE_CONFIG_DIR=${altDir}?`,
+      initialValue: true,
+    }));
+    if (alsoRegister) {
+      const s = p.spinner();
+      s.start(`Registering for Claude (${altDir})...`);
+      try {
+        const env = { ...process.env, CLAUDE_CONFIG_DIR: altDir };
+        const args = ["mcp", "remove", "sinain"];
+        try { execFileSync("claude", args, { stdio: "pipe", env }); } catch { /* not registered */ }
+        const addArgs = ["mcp", "add", "sinain", "--scope", "user"];
+        for (const [k, v] of Object.entries(DEFAULT_ENV)) addArgs.push("--env", `${k}=${v}`);
+        addArgs.push("--", TSX_BIN, MCP_ENTRY);
+        execFileSync("claude", addArgs, { stdio: "pipe", env });
+        s.stop(c.green(`Claude (${altDir}): registered.`));
+      } catch (err) {
+        s.stop(c.yellow(`Alt config dir: failed — ${err.message}`));
+      }
+    }
+  }
+}
+
+// ── Standalone CLI ──────────────────────────────────────────────────────────
+
+export async function runMcpCli(sub, args = []) {
+  switch (sub) {
+    case "install":
+      return cliInstall(args);
+    case "list":
+      return cliList();
+    case "remove":
+      return cliRemove(args);
+    default:
+      printMcpUsage();
+      process.exit(sub ? 1 : 0);
+  }
+}
+
+async function cliInstall(args) {
+  const all = args.includes("--all");
+  const agentArg = args.find((a) => a.startsWith("--agent="));
+  const agentId = agentArg ? agentArg.slice("--agent=".length) : null;
+
+  if (agentId) {
+    const a = findAgent(agentId);
+    if (!a) { console.error(c.red(`Unknown agent: ${agentId}`)); process.exit(1); }
+    if (!a.detect()) { console.error(c.yellow(`${a.label} not detected on this machine.`)); process.exit(1); }
+    try {
+      await a.register();
+      console.log(c.green(`✓ ${a.label}: registered.`));
+    } catch (err) {
+      console.error(c.red(`✗ ${a.label}: ${err.message}`));
+      if (agentId === "goose") console.log(`\nPaste this into ${GOOSE_CONFIG}:\n\n${gooseSnippet()}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (all) {
+    if (!mcpServerReady() && !ensureMcpServerDeps()) {
+      console.error(c.red(`MCP server deps not installed. Run: cd ${MCP_SERVER_DIR} && npm install`));
+      process.exit(1);
+    }
+    const agents = await detectMcpAgents();
+    const detected = agents.filter((a) => a.present);
+    if (detected.length === 0) {
+      console.log(c.yellow("No MCP-aware agents detected."));
+      return;
+    }
+    for (const a of detected) {
+      const backend = findAgent(a.id);
+      try {
+        await backend.register();
+        console.log(c.green(`✓ ${a.label}: registered.`));
+      } catch (err) {
+        console.error(c.yellow(`! ${a.label}: ${err.message}`));
+      }
+    }
+    return;
+  }
+
+  // Interactive
+  await stepMcpInstall({}, "MCP agents");
+}
+
+async function cliList() {
+  const agents = await detectMcpAgents();
+  console.log();
+  console.log(c.bold("  Sinain MCP — agent status"));
+  console.log();
+  for (const a of agents) {
+    const present = a.present ? c.green("present") : c.dim("absent ");
+    const reg = a.alreadyRegistered ? c.green("✓ registered") : (a.present ? c.dim("· not registered") : c.dim("·"));
+    console.log(`    ${present}  ${a.label.padEnd(18)}  ${reg}`);
+  }
+  console.log();
+}
+
+async function cliRemove(args) {
+  const id = args[0];
+  if (!id) { console.error(c.red("Usage: sinain mcp remove <agent>")); process.exit(1); }
+  const a = findAgent(id);
+  if (!a) { console.error(c.red(`Unknown agent: ${id}`)); process.exit(1); }
+  try {
+    await a.unregister();
+    console.log(c.green(`✓ ${a.label}: removed.`));
+  } catch (err) {
+    console.error(c.red(`✗ ${a.label}: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+function printMcpUsage() {
+  console.log(`
+sinain mcp — register the sinain MCP server with your agents
+
+Usage:
+  sinain mcp install                Interactive install (multi-select)
+  sinain mcp install --all          Register for every detected agent
+  sinain mcp install --agent=<id>   Register for one agent
+  sinain mcp list                   Show agent status
+  sinain mcp remove <agent>         Unregister sinain from <agent>
+
+Supported agent IDs:
+  claude, claude-desktop, cursor, codex, goose, junie
+`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geravant/sinain",
-  "version": "1.22.9",
+  "version": "1.23.1",
   "description": "Ambient intelligence that sees what you see, hears what you hear, and acts on your behalf",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "config-shared.js",
     "onboard.js",
     "launcher.js",
+    "mcp-register.js",
     "setup-overlay.js",
     "setup-sck-capture.js",
     "pack-prepare.js",

package/sinain-core/src/server.ts

@@ -942,14 +942,16 @@ function setupSearch() {
     const q = input.value.trim();
     if (!q) { dropdown.classList.remove("open"); dropdown.innerHTML = ""; return; }
     const result = await api("/knowledge/search?q=" + encodeURIComponent(q) + "&limit=15");
+    // Always show "Search: query" as first option → topic page with combined recall
+    const topicLink = \`
+      <div class="search-result" onclick="navigate('/knowledge/ui/topic/' + encodeURIComponent('\${esc(q)}'))" style="border-bottom:1px solid rgba(255,255,255,0.1)">
+        <div class="entity">🔍 Search: \${esc(q)}</div>
+        <div class="snippet">Combined query — find facts across multiple entities</div>
+      </div>\`;
     if (!result.results || result.results.length === 0) {
-      dropdown.innerHTML = \`
-        <div class="search-result" onclick="navigate('/knowledge/ui/topic/' + encodeURIComponent('\${esc(q)}'))">
-          <div class="entity">View as topic page</div>
-          <div class="snippet">No matching entities — synthesize from search hits.</div>
-        </div>\`;
+      dropdown.innerHTML = topicLink;
     } else {
-      dropdown.innerHTML = result.results.map(r => \`
+      dropdown.innerHTML = topicLink + result.results.map(r => \`
         <div class="search-result" onclick="navigate('/knowledge/ui/entity/' + encodeURIComponent('\${esc(r.entity)}'))">
           <div class="entity">\${esc(r.entity)}</div>
           <div class="meta">\${esc(r.type)} · \${r.fact_count} fact\${r.fact_count === 1 ? "" : "s"}</div>
@@ -960,6 +962,12 @@ function setupSearch() {
   }, 220);
   input.addEventListener("input", handleQuery);
   input.addEventListener("focus", () => { if (input.value) handleQuery(); });
+  input.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && input.value.trim()) {
+      dropdown.classList.remove("open");
+      navigate("/knowledge/ui/topic/" + encodeURIComponent(input.value.trim()));
+    }
+  });
   document.addEventListener("click", (e) => {
     if (!e.target.closest(".search-wrap")) dropdown.classList.remove("open");
   });
@@ -1339,25 +1347,109 @@ function renderMissingConcept(entity, root) {
 
 // ── Topic page (simple, v1) ───────────────────────────────────────────────
 async function renderTopicPage(q) {
-  document.title = "Topic: " + q;
+  document.title = "Topic: " + q + " · Sinain";
   const root = $("#root");
-  root.innerHTML = \`
-    <h1>Topic: \${esc(q)}</h1>
-    <div class="loading-block"><span class="spinner"></span> Searching…</div>\`;
-  const r = await api("/knowledge/search?q=" + encodeURIComponent(q) + "&limit=50");
-  if (!r.results || r.results.length === 0) {
-    root.innerHTML = \`<h1>Topic: \${esc(q)}</h1>
+  root.innerHTML = \`<div class="loading-block"><span class="spinner"></span> Searching…</div>\`;
+
+  // Parallel: get combined facts + matching entities
+  const [qr, sr] = await Promise.all([
+    api("/knowledge/query?q=" + encodeURIComponent(q) + "&max=30"),
+    api("/knowledge/search?q=" + encodeURIComponent(q) + "&limit=10"),
+  ]);
+  const factsText = qr.facts_text || "";
+  const entities = sr.results || [];
+
+  if (!factsText && entities.length === 0) {
+    root.innerHTML = \`
+      <div class="page-header"><div class="title">Topic: \${esc(q)}</div></div>
       <div class="error-block">No matching facts.</div>\`;
     return;
   }
+
+  // Parse compact facts into structured items, group by entity
+  const factItems = factsText ? factsText.split("; ").filter(Boolean) : [];
+  const grouped = {};
+  const ungrouped = [];
+  for (const f of factItems) {
+    const m = f.match(/^([^:]*?):\\s*(.+?)\\s*\\(([^)]+)\\)$/);
+    if (m) {
+      const ent = m[1].trim() || "general";
+      (grouped[ent] = grouped[ent] || []).push({text: m[2], meta: m[3], raw: f});
+    } else {
+      ungrouped.push({text: f, meta: "", raw: f});
+    }
+  }
+
+  // Build summary from top entities
+  const topEnts = Object.keys(grouped).slice(0, 5).join(", ");
+  const summary = factItems.length > 0
+    ? \`\${factItems.length} facts retrieved across \${Object.keys(grouped).length} entities\${topEnts ? ": " + topEnts : ""}\`
+    : "No facts found for this query.";
+
   root.innerHTML = \`
-    <h1>Topic: \${esc(q)}</h1>
-    <div class="summary">Top \${r.results.length} matches across the knowledge graph.</div>
-    \${r.results.map(rr => \`
-      <div class="bullet" onclick="navigate('/knowledge/ui/entity/' + encodeURIComponent('\${esc(rr.entity)}'))" style="cursor:pointer">
-        <span class="text"><strong>\${esc(rr.entity)}</strong> — \${esc(rr.snippet || "")}</span>
-        <span class="conf">\${rr.fact_count} fact\${rr.fact_count === 1 ? "" : "s"}</span>
-      </div>\`).join("")}\`;
+    <div class="page-header">
+      <div class="title">Topic: \${esc(q)}</div>
+      <div class="badges">
+        <span class="badge">\${factItems.length} fact\${factItems.length === 1 ? "" : "s"}</span>
+        <span class="badge">\${Object.keys(grouped).length} entit\${Object.keys(grouped).length === 1 ? "y" : "ies"}</span>
+      </div>
+      <div class="page-actions">
+        <button id="topicCopyLink" class="icon" title="Copy topic URL">🔗</button>
+        <button id="topicShare" class="icon" title="Share topic (auto-imports for recipient)">📤</button>
+      </div>
+    </div>
+    <div class="summary">\${esc(summary)}</div>
+    <div id="topicSections">
+      \${Object.entries(grouped).map(([ent, facts], i) => \`
+        <div class="section" id="sec-\${i}">
+          <div class="section-heading" onclick="this.parentElement.classList.toggle('collapsed')">
+            \${esc(ent)}
+            <span style="opacity:0.5;font-size:0.85em;margin-left:8px">\${facts.length} fact\${facts.length === 1 ? "" : "s"}</span>
+          </div>
+          <ul class="bullets">\${facts.map(f => \`
+            <li class="bullet">
+              <span class="text">\${esc(f.text)}</span>
+              <span class="conf">\${esc(f.meta)}</span>
+            </li>\`).join("")}</ul>
+        </div>\`).join("")}
+      \${ungrouped.length > 0 ? \`
+        <div class="section">
+          <div class="section-heading">Other</div>
+          <ul class="bullets">\${ungrouped.map(f => \`
+            <li class="bullet"><span class="text">\${esc(f.text)}</span></li>\`).join("")}</ul>
+        </div>\` : ""}
+    </div>
+    \${entities.length > 0 ? \`
+      <div class="section" style="margin-top:16px">
+        <div class="section-heading" onclick="this.parentElement.classList.toggle('collapsed')">
+          Related Entities
+        </div>
+        <ul class="bullets">\${entities.map(rr => \`
+          <li class="bullet" onclick="navigate('/knowledge/ui/entity/' + encodeURIComponent('\${esc(rr.entity)}'))" style="cursor:pointer">
+            <span class="text"><strong>\${esc(rr.entity)}</strong> — \${esc(rr.snippet || "")}</span>
+            <span class="conf">\${rr.fact_count} fact\${rr.fact_count === 1 ? "" : "s"}</span>
+          </li>\`).join("")}</ul>
+      </div>\` : ""}\`;
+
+  // Wire actions
+  $("#topicCopyLink").onclick = () => {
+    const url = location.origin + "/knowledge/ui/topic/" + encodeURIComponent(q);
+    navigator.clipboard.writeText(url);
+    showToast("✓ Link copied");
+  };
+  $("#topicShare").onclick = async () => {
+    // Share all entities mentioned in the query
+    const ents = (qr.entities || q.split(/[\\s,+]+/)).filter(Boolean);
+    if (ents.length === 0) { showToast("No entities to share"); return; }
+    showToast('<span class="spinner"></span> Preparing share…', 30_000);
+    try {
+      for (const ent of ents.slice(0, 3)) {
+        await ShareManager.createShare(ent);
+      }
+    } catch (e) {
+      showToast("Share failed: " + (e && e.message ? e.message : String(e)));
+    }
+  };
 }
 
 // ── Dropzone wiring (shared) ──────────────────────────────────────────────
@@ -1816,6 +1908,30 @@ export function createAppServer(deps: ServerDeps) {
         return;
       }
 
+      // ── /knowledge/query ── (combined entity recall — used by topic page) ──
+      if (req.method === "GET" && url.pathname === "/knowledge/query") {
+        const q = url.searchParams.get("q") || "";
+        const maxFacts = Math.min(parseInt(url.searchParams.get("max") || "20"), 50);
+        if (!q.trim()) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ ok: false, error: "q parameter required" }));
+          return;
+        }
+        // Split query into entity keywords for queryKnowledgeFacts
+        const entities = q.trim().split(/[\s,+]+/).filter(Boolean);
+        if (deps.queryKnowledgeFacts) {
+          try {
+            const factsText = await deps.queryKnowledgeFacts(entities, maxFacts);
+            res.end(JSON.stringify({ ok: true, query: q, facts_text: factsText, entities }));
+          } catch (err) {
+            res.end(JSON.stringify({ ok: false, error: String(err) }));
+          }
+        } else {
+          res.end(JSON.stringify({ ok: true, query: q, facts_text: "", entities }));
+        }
+        return;
+      }
+
       // ── /knowledge/search ── (entity-prioritized) ──
       if (req.method === "GET" && url.pathname === "/knowledge/search") {
         const q = url.searchParams.get("q") || "";

package/sinain-memory/graph_query.py

@@ -328,6 +328,70 @@ def _cooccurring_entities(
     return ranked[:max_entities]
 
 
+_SEMANTIC_CACHE: dict = {}  # {"db_path": {"names": [...], "embs": ndarray, "ts": float}}
+
+
+def _expand_keywords_semantic(
+    keywords: list[str],
+    db_path: str,
+    threshold: float = 0.50,
+    max_expansions: int = 3,
+) -> list[str]:
+    """Expand keywords with semantically similar entity names from the graph.
+
+    "AI" → ["ai", "machine-learning", "ai-agents", ...]. Caches model + entity
+    embeddings for fast repeated calls (<50ms after first load).
+    """
+    import time as _t
+    try:
+        from sentence_transformers import SentenceTransformer
+        import numpy as np
+        from triplestore import TripleStore
+
+        if not hasattr(_expand_keywords_semantic, "_model"):
+            _expand_keywords_semantic._model = SentenceTransformer("all-MiniLM-L6-v2")
+        model = _expand_keywords_semantic._model
+
+        # Cache entity names + embeddings (refresh every 5 min)
+        cache = _SEMANTIC_CACHE.get(db_path)
+        if not cache or _t.time() - cache["ts"] > 300:
+            store = TripleStore(db_path)
+            entity_names = [n for eid, n in store.entities_with_attr("name")
+                            if eid.startswith("entity:") and len(n) >= 4]
+            store.close()
+            if not entity_names:
+                return keywords
+            entity_embs = model.encode(entity_names, show_progress_bar=False)
+            _SEMANTIC_CACHE[db_path] = {"names": entity_names, "embs": entity_embs, "ts": _t.time()}
+            cache = _SEMANTIC_CACHE[db_path]
+
+        entity_names = cache["names"]
+        entity_embs = cache["embs"]
+
+        kw_embs = model.encode(keywords, show_progress_bar=False)
+
+        expanded = list(keywords)
+        for i, kw in enumerate(keywords):
+            # Skip expansion for very short keywords — embeddings are unreliable
+            # for abbreviations like "ml", "ai" (use community detection instead)
+            if len(kw) < 4:
+                continue
+            sims = []
+            for j, name in enumerate(entity_names):
+                if name == kw or name in expanded:
+                    continue
+                sim = float(np.dot(kw_embs[i], entity_embs[j]) /
+                            (np.linalg.norm(kw_embs[i]) * np.linalg.norm(entity_embs[j]) + 1e-9))
+                if sim >= threshold:
+                    sims.append((name, sim))
+            sims.sort(key=lambda x: -x[1])
+            expanded.extend(name for name, _ in sims[:max_expansions])
+
+        return expanded
+    except (ImportError, Exception):
+        return keywords
+
+
 def query_facts_hybrid(
     db_path: str,
     query: str,
@@ -342,15 +406,32 @@ def query_facts_hybrid(
     import time
     keywords = [w.lower() for w in re.findall(r"[a-zA-Z][a-zA-Z0-9-]+", query) if len(w) > 2]
 
-    # Entity graph pre-filter: find facts linked to mentioned entities via backrefs.
-    # Used to BOOST relevant facts in RRF, not as a separate tier (avoids dilution).
+    # Change 0: Semantic entity expansion — "ML" → ["ml", "machine-learning", "ai", ...]
+    expanded_keywords = keywords
+    if len(keywords) >= 1:
+        expanded_keywords = _expand_keywords_semantic(keywords, db_path)
+
+    # Entity graph pre-filter with per-entity tracking for intersection (Change A)
     graph_fact_ids: set[str] = set()
+    graph_intersection: set[str] = set()
     community_fact_ids: set[str] = set()
-    for kw in keywords:
+    per_entity_facts: dict[str, set[str]] = {}
+    for kw in expanded_keywords:
+        kw_facts: set[str] = set()
         for f in query_facts_by_entity_graph(db_path, kw, max_facts=50):
             eid = f.get("entity_id", "")
             if eid:
+                kw_facts.add(eid)
                 graph_fact_ids.add(eid)
+        if kw_facts:
+            per_entity_facts[kw] = kw_facts
+
+    # Compute intersection: facts linked to ALL original query keywords
+    if len(per_entity_facts) >= 2:
+        try:
+            graph_intersection = set.intersection(*per_entity_facts.values())
+        except TypeError:
+            pass
 
     # Community expansion: follow mentions edges to find related entities
     t0 = time.monotonic()
@@ -359,14 +440,14 @@ def query_facts_hybrid(
         store = TripleStore(db_path)
 
         matched_entities = set()
-        for kw in keywords:
+        for kw in expanded_keywords:
             node_id = f"entity:{kw}"
             if store.entity(node_id):
                 matched_entities.add(kw)
 
         for ent in matched_entities:
             if time.monotonic() - t0 > 0.5:
-                break  # timing guard
+                break
             community = expand_entity_community(store, ent, max_related=3)
             for related_name, _count in community:
                 for f in query_facts_by_entity_graph(db_path, related_name, max_facts=20):
@@ -378,12 +459,50 @@ def query_facts_hybrid(
     except Exception:
         pass
 
-    # Run three retrieval methods independently
+    # Run retrieval methods independently
     candidate_limit = max_facts * 3
-    fts_results = query_facts_fts(db_path, query, max_facts=candidate_limit)
-    tag_results = query_facts_by_entities(db_path, keywords, max_facts=candidate_limit) if keywords else []
+
+    # Change C: FTS5 AND mode for multi-keyword queries
+    if len(keywords) > 1:
+        fts_and_query = " AND ".join(keywords)
+        fts_results = query_facts_fts(db_path, fts_and_query, max_facts=candidate_limit)
+        if len(fts_results) < candidate_limit:
+            fts_or = query_facts_fts(db_path, " OR ".join(keywords), max_facts=candidate_limit)
+            fts_results.extend(fts_or)
+    else:
+        fts_results = query_facts_fts(db_path, query, max_facts=candidate_limit)
+
+    tag_results = query_facts_by_entities(db_path, expanded_keywords, max_facts=candidate_limit) if expanded_keywords else []
     top_results = query_top_facts(db_path, limit=candidate_limit)
 
+    # Change B: Tag intersection tier (facts tagged with ALL keywords)
+    intersection_results: list[dict] = []
+    if len(keywords) >= 2:
+        try:
+            from triplestore import TripleStore
+            _istore = TripleStore(db_path)
+            placeholders = ",".join("?" for _ in keywords)
+            rows = _istore._conn.execute(
+                f"""SELECT entity_id, COUNT(DISTINCT value) as matches
+                    FROM triples WHERE attribute = 'tag' AND NOT retracted
+                    AND value IN ({placeholders})
+                    GROUP BY entity_id HAVING COUNT(DISTINCT value) >= ?
+                    ORDER BY matches DESC LIMIT ?""",
+                (*keywords, len(keywords), candidate_limit),
+            ).fetchall()
+            for r in rows:
+                fid = r["entity_id"]
+                attrs = _istore.entity(fid)
+                if attrs and "value" in attrs:
+                    fact = {"entity_id": fid}
+                    for attr_name, values in attrs.items():
+                        if attr_name != "tag":
+                            fact[attr_name] = values[0] if len(values) == 1 else values
+                    intersection_results.append(fact)
+            _istore.close()
+        except Exception:
+            pass
+
     # Build ranked lists by entity_id
     def _ranked_ids(facts: list[dict]) -> list[str]:
         seen = set()
@@ -398,41 +517,58 @@ def query_facts_hybrid(
     fts_ranked = _ranked_ids(fts_results)
     tag_ranked = _ranked_ids(tag_results)
     top_ranked = _ranked_ids(top_results)
+    intersection_ranked = _ranked_ids(intersection_results)
 
     # Reciprocal Rank Fusion: RRF(d) = Σ 1/(k + rank_i(d))
-    K = 60  # standard RRF constant
+    K = 60
     rrf_scores: dict[str, float] = {}
-    for ranked_list in [fts_ranked, tag_ranked, top_ranked]:
+    tiers = [fts_ranked, tag_ranked, top_ranked]
+    if intersection_ranked:
+        tiers.append(intersection_ranked)
+    for ranked_list in tiers:
         for rank, eid in enumerate(ranked_list):
             rrf_scores[eid] = rrf_scores.get(eid, 0.0) + 1.0 / (K + rank)
 
-    # Co-occurrence boost: use FTS/tag results to find temporally related entities
-    import time as _time
-    _t_cooccur = _time.monotonic()
-    query_matched_ids = {f.get("entity_id", "") for f in fts_results + tag_results if f.get("entity_id")}
-    if query_matched_ids and _time.monotonic() - _t_cooccur < 0.3:
+    # Change D: Session co-occurrence for multi-entity queries
+    if len(keywords) >= 2 and time.monotonic() - t0 < 1.0:
         try:
             from triplestore import TripleStore
-            _store = TripleStore(db_path)
-            cooccur = _cooccurring_entities(_store, query_matched_ids, max_entities=5)
-            for ent_name in cooccur:
-                for f in query_facts_by_entity_graph(db_path, ent_name, max_facts=10):
-                    eid = f.get("entity_id", "")
-                    if eid and eid not in graph_fact_ids:
+            _sstore = TripleStore(db_path)
+            # Find sessions where facts about BOTH keywords exist
+            kw_a, kw_b = keywords[0], keywords[1]
+            sess_rows = _sstore._conn.execute(
+                """SELECT DISTINCT t1.value as ts FROM triples t1
+                   JOIN triples t2 ON t2.attribute='first_seen' AND t2.value=t1.value AND t2.retracted=0
+                   WHERE t1.attribute='first_seen' AND t1.retracted=0
+                   AND t1.entity_id IN (SELECT entity_id FROM triples WHERE attribute='tag' AND value=? AND NOT retracted)
+                   AND t2.entity_id IN (SELECT entity_id FROM triples WHERE attribute='tag' AND value=? AND NOT retracted)
+                   LIMIT 10""",
+                (kw_a, kw_b),
+            ).fetchall()
+            if sess_rows:
+                ts_values = [r[0] for r in sess_rows]
+                ph = ",".join("?" for _ in ts_values)
+                fact_rows = _sstore._conn.execute(
+                    f"SELECT DISTINCT entity_id FROM triples WHERE attribute='first_seen' AND value IN ({ph}) AND NOT retracted AND entity_id LIKE 'fact:%' LIMIT 30",
+                    ts_values,
+                ).fetchall()
+                for r in fact_rows:
+                    eid = r[0]
+                    if eid not in graph_fact_ids:
                         community_fact_ids.add(eid)
-            _store.close()
+            _sstore.close()
         except Exception:
             pass
 
-    # Graph boost: facts linked to mentioned entities via backrefs get priority
-    # +0.05 is significant vs RRF scores of ~0.015-0.033 — ensures entity-linked facts
-    # rank above FTS noise in large graphs (100K+ triples)
-    if graph_fact_ids or community_fact_ids:
+    # Graph boost with intersection bonus (Change A continued)
+    if graph_fact_ids or community_fact_ids or graph_intersection:
         for eid in rrf_scores:
-            if eid in graph_fact_ids:
+            if eid in graph_intersection:
+                rrf_scores[eid] += 0.10  # intersection: linked to ALL queried entities
+            elif eid in graph_fact_ids:
                 rrf_scores[eid] += 0.05  # direct graph-linked facts
             elif eid in community_fact_ids:
-                rrf_scores[eid] += 0.025  # community-expanded facts (half weight)
+                rrf_scores[eid] += 0.025  # community-expanded facts
 
     # Apply confidence decay as secondary signal (fresh facts rank above stale ones)
     from triplestore import decayed_confidence
@@ -462,11 +598,30 @@ def query_facts_hybrid(
             if eid and eid not in fact_map:
                 fact_map[eid] = f
 
-    # Return top RRF candidates. Embedding re-ranking is done by the caller
-    # (sinain-core Node.js) to avoid deadlock — the Python subprocess can't call
-    # back to sinain-core's /embed endpoint while sinain-core is blocked waiting
-    # for the subprocess.
-    results = [fact_map[eid] for eid in sorted_ids[:max_facts] if eid in fact_map]
+    # Return top RRF candidates, optionally re-ranked by embedding similarity.
+    # When called from sinain-core subprocess, embedding re-ranking happens in
+    # Node.js (to avoid deadlock). When called standalone (benchmark, CLI),
+    # we re-rank in-process if sentence-transformers is available.
+    rrf_candidates = [fact_map[eid] for eid in sorted_ids[:max_facts * 2] if eid in fact_map]
+
+    results = rrf_candidates[:max_facts]
+    try:
+        from sentence_transformers import SentenceTransformer
+        import numpy as np
+        if not hasattr(query_facts_hybrid, "_embed_model"):
+            query_facts_hybrid._embed_model = SentenceTransformer("all-MiniLM-L6-v2")
+        model = query_facts_hybrid._embed_model
+        texts = [query] + [f.get("value", "") for f in rrf_candidates]
+        embs = model.encode(texts, show_progress_bar=False)
+        q_emb = embs[0]
+        scored = []
+        for i, f in enumerate(rrf_candidates):
+            sim = float(np.dot(q_emb, embs[i + 1]) / (np.linalg.norm(q_emb) * np.linalg.norm(embs[i + 1]) + 1e-9))
+            scored.append((sim, f))
+        scored.sort(key=lambda x: -x[0])
+        results = [f for _, f in scored[:max_facts]]
+    except ImportError:
+        pass  # sentence-transformers not installed — use RRF order
 
     # Expand top results with 1-hop graph neighbors
     if results and len(results) < max_facts: